# ADR-0003: Code Intelligence — Tree-sitter Outlines & Function Extraction

**Status:** Superseded (v2.0 — merged with search-helpers)
**Date:** 2026-05-16 (originally 2026-05-13)
**Extension:** `extensions/code-intel/` (11 files)

## Problem

Reading full files wastes 80-95% of tokens on implementation logic when only signatures matter. The original regex-based skeleton approach (v1.0) worked but had edge cases with multi-line TS generics, complex Python decorators, and required 6 hand-rolled regex sets.

Meanwhile, search-helpers (ADR-0018) duplicated noise-dir lists, exec helpers, and language mappings. Having 7 separate tools (`file_skeleton`, `get_function`, `find_definition`, `find_imports`, `search_config`, `project_overview`) created decision fatigue.

## Decision (v2.0)

Merge code-intel + search-helpers into 3 tools powered by tree-sitter (WASM, no native deps):

| Tool            | Replaces                           | Key Behavior                                                                                                                                          |
| --------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inspect_code`  | `file_skeleton` + `get_function`   | Small files (<200L) return full content. Large files get tree-sitter outline with line ranges. `functions` arg extracts bodies with hash-based dedup. |
| `find_symbol`   | `find_definition` + `find_imports` | `definition` mode: ripgrep + tree-sitter confirmation. `usage` mode: import/require patterns. Definitions ranked above usages. Session dedup.         |
| `search_config` | `search_config`                    | Unchanged — pure ripgrep for JSON/YAML/TOML/.env.                                                                                                     |

Dropped: `project_overview` (AGENTS.md/CLAUDE.md era — every repo has one now).

### Tree-sitter infrastructure

- **web-tree-sitter** (WASM) — loaded from pi-lens's installed grammars, zero additional deps
- **Lazy loading** — grammars loaded per file extension on first use
- **Outline extraction** — walks top-level AST nodes (function_declaration, class_declaration, etc.) inspired by tilth's outline.rs
- **Definition detection** — walks DEFINITION_KINDS array to find named definitions, same approach as tilth's symbol.rs

### Shared modules extracted to `extensions/shared/`

- `noise-dirs.ts` — SKIP_DIRS, noiseGlobs(), fdExcludes()
- `lang-registry.ts` — ext→lang mapping, GRAMMAR_FILES, rgTypeFlags()
- `exec.ts` — run(), getRg(), rgCountAndSearch(), formatSearchOutput()

## Alternatives Revisited

| Approach              | Decision                                                                                                        |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| Native tree-sitter    | Still rejected — WASM via pi-lens's grammars is zero-dep                                                        |
| Regex patterns (v1.0) | Replaced — tree-sitter handles multi-line signatures, decorators, generics                                      |
| tilth MCP server      | Considered — but internalizing the key insights (outline, def-first ranking) is simpler than an external binary |
| Keep 7 separate tools | Rejected — 3 tools with clear intent is less cognitive load                                                     |

## Trade-offs

- Tree-sitter WASM is ~10ms slower per file than regex, but far more accurate
- Depends on pi-lens's installed grammars — graceful fallback to first-50-lines if unavailable
- Session dedup state is in-memory per process — clears on restart (by design)

## References

- [tilth](https://github.com/jahala/tilth) — tree-sitter + ripgrep hybrid for AI agents (key design inspiration)
- [SigMap benchmarks](https://github.com/manojmallick/sigmap) — 59% vs 10% task success with skeleton context
- ADR-0018 (search-helpers) — now superseded, merged into this
