codebase-context 1.6.2 → 1.7.0

package/dist/utils/tree-sitter.js

@@ -0,0 +1,311 @@
+import { createRequire } from 'module';
+import { Language, Parser } from 'web-tree-sitter';
+import { CURATED_LANGUAGE_TO_WASM, supportsCuratedTreeSitter, resolveGrammarPath } from '../grammars/manifest.js';
+const require = createRequire(import.meta.url);
+const CORE_WASM_PATH = require.resolve('web-tree-sitter/tree-sitter.wasm');
+const SYMBOL_CANDIDATE_NODE_TYPES = [
+    'class_declaration',
+    'class_definition',
+    'class_specifier',
+    'constructor_declaration',
+    'enum_declaration',
+    'enum_item',
+    'function_declaration',
+    'function_definition',
+    'function_item',
+    'generator_function_declaration',
+    'interface_declaration',
+    'lexical_declaration',
+    'method',
+    'method_declaration',
+    'method_definition',
+    'struct_item',
+    'struct_specifier',
+    'trait_item',
+    'type_alias_declaration',
+    'type_declaration',
+    'type_spec',
+    'variable_declarator'
+];
+const NAME_FIELD_CANDIDATES = ['name', 'declarator', 'property', 'path'];
+const NAME_NODE_TYPE_HINTS = [
+    'identifier',
+    'type_identifier',
+    'property_identifier',
+    'scoped_identifier',
+    'constant',
+    'name'
+];
+const MAX_TREE_SITTER_PARSE_BYTES = 1024 * 1024;
+const TREE_SITTER_PARSE_TIMEOUT_MICROS = 30000000n;
+let initPromise = null;
+const languageCache = new Map();
+const parserCache = new Map();
+function maybeResetParser(parser) {
+    const maybeReset = parser.reset;
+    if (typeof maybeReset === 'function') {
+        maybeReset.call(parser);
+    }
+}
+function evictParser(language, parser) {
+    if (parser) {
+        maybeResetParser(parser);
+    }
+    parserCache.delete(language);
+}
+function setParseTimeout(parser) {
+    const maybeSetTimeout = parser.setTimeoutMicros;
+    if (typeof maybeSetTimeout === 'function') {
+        try {
+            maybeSetTimeout.call(parser, TREE_SITTER_PARSE_TIMEOUT_MICROS);
+        }
+        catch {
+            try {
+                maybeSetTimeout.call(parser, Number(TREE_SITTER_PARSE_TIMEOUT_MICROS));
+            }
+            catch {
+                // Ignore timeout wiring failures; parser execution still proceeds.
+            }
+        }
+    }
+}
+function sliceUtf8(content, startIndex, endIndex) {
+    const utf8 = Buffer.from(content, 'utf8');
+    return utf8.subarray(startIndex, endIndex).toString('utf8');
+}
+function extractNodeContent(node, content) {
+    const byteSlice = sliceUtf8(content, node.startIndex, node.endIndex);
+    const codeUnitSlice = content.slice(node.startIndex, node.endIndex);
+    if (node.text === codeUnitSlice && node.text !== byteSlice) {
+        return codeUnitSlice;
+    }
+    return byteSlice;
+}
+function isTreeSitterDebugEnabled() {
+    return Boolean(process.env.CODEBASE_CONTEXT_DEBUG);
+}
+export function supportsTreeSitter(language) {
+    return supportsCuratedTreeSitter(language);
+}
+async function ensureParserInitialized() {
+    if (!initPromise) {
+        initPromise = Parser.init({
+            locateFile(scriptName) {
+                if (scriptName === 'tree-sitter.wasm') {
+                    return CORE_WASM_PATH;
+                }
+                return scriptName;
+            }
+        });
+    }
+    await initPromise;
+}
+async function loadLanguage(language) {
+    const wasmFile = CURATED_LANGUAGE_TO_WASM[language];
+    if (!wasmFile) {
+        throw new Error(`Tree-sitter grammar is not configured for '${language}'.`);
+    }
+    let cachedLanguage = languageCache.get(language);
+    if (!cachedLanguage) {
+        const { wasmPath } = resolveGrammarPath(language, import.meta.url);
+        cachedLanguage = Language.load(wasmPath).catch((err) => {
+            // Evict failed entry so later calls can retry after fixes
+            languageCache.delete(language);
+            throw err;
+        });
+        languageCache.set(language, cachedLanguage);
+    }
+    return cachedLanguage;
+}
+async function getParserForLanguage(language) {
+    let cachedParser = parserCache.get(language);
+    if (!cachedParser) {
+        cachedParser = (async () => {
+            await ensureParserInitialized();
+            const parser = new Parser();
+            try {
+                parser.setLanguage(await loadLanguage(language));
+            }
+            catch (err) {
+                // setLanguage failed — evict both caches so retry is possible
+                parserCache.delete(language);
+                languageCache.delete(language);
+                throw err;
+            }
+            return parser;
+        })();
+        parserCache.set(language, cachedParser);
+    }
+    return cachedParser;
+}
+function getNodeKind(nodeType) {
+    if (nodeType.includes('class'))
+        return 'class';
+    if (nodeType.includes('interface'))
+        return 'interface';
+    if (nodeType.includes('enum'))
+        return 'enum';
+    if (nodeType.includes('struct'))
+        return 'struct';
+    if (nodeType.includes('trait'))
+        return 'trait';
+    if (nodeType.includes('constructor'))
+        return 'method';
+    if (nodeType.includes('method'))
+        return 'method';
+    if (nodeType.includes('type_alias') || nodeType === 'type_spec')
+        return 'type';
+    return 'function';
+}
+function normalizeSymbolName(rawName) {
+    return rawName
+        .replace(/[\s\n\t]+/g, ' ')
+        .trim()
+        .replace(/^[:@#]+/, '');
+}
+function maybeGetNameNode(node) {
+    for (const fieldName of NAME_FIELD_CANDIDATES) {
+        const field = node.childForFieldName(fieldName);
+        if (field) {
+            return field;
+        }
+    }
+    for (const child of node.namedChildren) {
+        if (!child)
+            continue;
+        if (NAME_NODE_TYPE_HINTS.some((hint) => child.type.includes(hint))) {
+            return child;
+        }
+    }
+    return null;
+}
+function extractNodeName(node) {
+    const nameNode = maybeGetNameNode(node);
+    if (nameNode?.text) {
+        const normalized = normalizeSymbolName(nameNode.text);
+        if (normalized) {
+            return normalized;
+        }
+    }
+    const compact = node.text.slice(0, 120).replace(/\s+/g, ' ').trim();
+    const match = compact.match(/(?:class|interface|enum|struct|trait|function|def|fn)\s+([A-Za-z_][\w$]*)/);
+    if (match?.[1]) {
+        return match[1];
+    }
+    return 'anonymous';
+}
+function isFunctionVariableDeclarator(node) {
+    if (node.type !== 'variable_declarator') {
+        return false;
+    }
+    const valueNode = node.childForFieldName('value');
+    if (!valueNode) {
+        return false;
+    }
+    return valueNode.type === 'arrow_function' || valueNode.type === 'function_expression';
+}
+function shouldSkipNode(language, node) {
+    if (node.type === 'variable_declarator') {
+        return (!['javascript', 'javascriptreact', 'typescript', 'typescriptreact'].includes(language) ||
+            !isFunctionVariableDeclarator(node));
+    }
+    if (node.type === 'lexical_declaration') {
+        return true;
+    }
+    if (node.type === 'type_declaration') {
+        return true;
+    }
+    return false;
+}
+function getSymbolRangeNode(node) {
+    const parent = node.parent;
+    if (parent?.type === 'export_statement') {
+        return parent;
+    }
+    return node;
+}
+function buildSymbol(node, content) {
+    const rangeNode = getSymbolRangeNode(node);
+    return {
+        name: extractNodeName(node),
+        kind: getNodeKind(node.type),
+        startLine: rangeNode.startPosition.row + 1,
+        endLine: rangeNode.endPosition.row + 1,
+        startIndex: rangeNode.startIndex,
+        endIndex: rangeNode.endIndex,
+        content: extractNodeContent(rangeNode, content),
+        nodeType: node.type
+    };
+}
+export async function extractTreeSitterSymbols(content, language) {
+    if (!supportsTreeSitter(language) || !content.trim()) {
+        return null;
+    }
+    if (Buffer.byteLength(content, 'utf8') > MAX_TREE_SITTER_PARSE_BYTES) {
+        return null;
+    }
+    try {
+        const parser = await getParserForLanguage(language);
+        setParseTimeout(parser);
+        let tree;
+        try {
+            tree = parser.parse(content);
+        }
+        catch (error) {
+            evictParser(language, parser);
+            throw error;
+        }
+        if (!tree) {
+            evictParser(language, parser);
+            return null;
+        }
+        try {
+            const hasErrorValue = tree.rootNode.hasError;
+            const rootHasError = typeof hasErrorValue === 'function'
+                ? Boolean(hasErrorValue())
+                : Boolean(hasErrorValue);
+            if (rootHasError) {
+                return null;
+            }
+            const nodes = tree.rootNode.descendantsOfType([...SYMBOL_CANDIDATE_NODE_TYPES]);
+            const seen = new Set();
+            const symbols = [];
+            for (const node of nodes) {
+                if (!node || !node.isNamed || shouldSkipNode(language, node)) {
+                    continue;
+                }
+                const symbol = buildSymbol(node, content);
+                if (symbol.name === 'anonymous') {
+                    continue;
+                }
+                const key = `${symbol.kind}:${symbol.name}:${symbol.startLine}:${symbol.endLine}`;
+                if (seen.has(key)) {
+                    continue;
+                }
+                seen.add(key);
+                symbols.push(symbol);
+            }
+            symbols.sort((a, b) => {
+                if (a.startLine !== b.startLine) {
+                    return a.startLine - b.startLine;
+                }
+                return a.endLine - b.endLine;
+            });
+            return {
+                grammarFile: CURATED_LANGUAGE_TO_WASM[language] ?? language,
+                symbols
+            };
+        }
+        finally {
+            tree.delete();
+        }
+    }
+    catch (error) {
+        evictParser(language);
+        if (isTreeSitterDebugEnabled()) {
+            console.error(`[DEBUG] Tree-sitter symbol extraction failed for '${language}':`, error instanceof Error ? error.message : String(error));
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=tree-sitter.js.map

package/dist/utils/tree-sitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-sitter.js","sourceRoot":"","sources":["../../src/utils/tree-sitter.ts"],"names":[],"mappings":"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"}

package/docs/capabilities.md

@@ -1,92 +1,169 @@
-# Capabilities Reference
-
-Technical reference for what `codebase-context` ships today. For the user-facing overview, see [README.md](../README.md).
-
-## Tool Surface
-
-10 MCP tools + 1 optional resource (`codebase://context`).
-
-### Core Tools
-
-| Tool | Input | Output |
-| --- | --- | --- |
-| `search_codebase` | `query`, optional `intent`, `limit`, `filters`, `includeSnippets` | Ranked results (`file`, `summary`, `score`, `type`, `trend`, `patternWarning`) + `searchQuality` (with `hint` when low confidence) + `preflight` ({ready, reason}). Snippets opt-in. |
-| `get_team_patterns` | optional `category` | Pattern frequencies, trends, golden files, conflicts |
-| `get_component_usage` | `name` (import source) | Files importing the given package/module |
-| `remember` | `type`, `category`, `memory`, `reason` | Persists to `.codebase-context/memory.json` |
-| `get_memory` | optional `category`, `type`, `query`, `limit` | Memories with confidence decay scoring |
-
-### Utility Tools
-
-| Tool | Purpose |
-| --- | --- |
-| `get_codebase_metadata` | Framework, dependencies, project stats |
-| `get_style_guide` | Style rules from project documentation |
-| `detect_circular_dependencies` | Import cycles in the file graph |
-| `refresh_index` | Full or incremental re-index + git memory extraction |
-| `get_indexing_status` | Index state, progress, last stats |
-
-## Retrieval Pipeline
-
-Ordered by execution:
-
-1. **Intent classification** — EXACT_NAME (for symbols), CONCEPTUAL, FLOW, CONFIG, WIRING. Sets keyword/semantic weight ratio.
-2. **Query expansion** — bounded domain term expansion for conceptual queries.
-3. **Dual retrieval** — keyword (Fuse.js) + semantic (local embeddings or OpenAI).
-4. **RRF fusion** — Reciprocal Rank Fusion (k=60) across all retrieval channels.
-5. **Structure-aware boosting** — import centrality, composition root boost, path overlap, definition demotion for action queries.
-6. **Contamination control** — test file filtering for non-test queries.
-7. **File deduplication** — best chunk per file.
-8. **Stage-2 reranking** — cross-encoder (`Xenova/ms-marco-MiniLM-L-6-v2`) triggers when the score between the top files are very close. CPU-only, top-10 bounded.
-9. **Result enrichment** — compact type (`componentType:layer`), pattern momentum (`trend` Rising/Declining only, Stable omitted), `patternWarning`, condensed relationships (`importedByCount`/`hasTests`), related memories (capped to 3), search quality assessment with `hint` when low confidence.
-
-### Defaults
-
-- **Chunk size**: 50 lines, 0 overlap
-- **Reranker trigger**: activates when top-3 results are within 0.08 score of each other
-- **Embedding model**: Granite (`ibm-granite/granite-embedding-30m-english`, 8192 token context) via `@huggingface/transformers` v3
-- **Vector DB**: LanceDB with cosine distance
-
-## Preflight (Edit Intent)
-
-Returned as `preflight` when search `intent` is `edit`, `refactor`, or `migrate`. Also returned for default searches when intelligence is available.
-
-Output: `{ ready: boolean, reason?: string }`
-
-- `ready`: whether evidence is sufficient to proceed with edits
-- `reason`: when `ready` is false, explains why (e.g., "Search quality is low", "Insufficient pattern evidence")
-
-### How `ready` is determined
-
-1. **Evidence triangulation** — scores code match (45%), pattern alignment (30%), and memory support (25%). Needs combined score ≥ 40 to pass.
-2. **Epistemic stress check** — if pattern conflicts, stale memories, or thin evidence are detected, `ready` is set to false with an abstain signal.
-3. **Search quality gate** — if `searchQuality.status` is `low_confidence`, `ready` is forced to false regardless of evidence scores. This prevents the "confidently wrong" problem where evidence counts look good but retrieval quality is poor.
-
-### Internal analysis (not in output, used to compute `ready`)
-
-- Risk level from circular deps + impact breadth + failure memories
-- Preferred/avoid patterns from team pattern analysis
-- Golden files by pattern density
-- Impact candidates from import graph
-- Failure warnings from related memories
-- Pattern conflicts when two patterns in the same category are both > 20% adoption
-
-## Memory System
-
-- 4 types: `convention`, `decision`, `gotcha`, `failure`
-- Confidence decay: conventions never decay, decisions 180-day half-life, gotchas/failures 90-day half-life
-- Stale threshold: memories below 30% confidence are flagged
-- Git auto-extraction: conventional commits from last 90 days
-- Surface locations: `search_codebase` results (as `relatedMemories`), `get_team_patterns` responses, preflight analysis
-
-## Indexing
-
-- Initial: full scan → chunking (50 lines, 0 overlap) → embedding → vector DB (LanceDB) + keyword index (Fuse.js)
-- Incremental: SHA-256 manifest diffing, selective embed/delete, full intelligence regeneration
-- Auto-heal: corrupted index triggers automatic full re-index on next search
-- Storage: `.codebase-context/` directory (memory.json + generated files)
-
-## Analyzers
-
-- **Angular**: signals, standalone components, control flow syntax, lifecycle hooks, DI patterns, component metadata
-- **Generic**: 30+ languages — TypeScript, JavaScript, Python, Java, Kotlin, C/C++, C#, Go, Rust, PHP, Ruby, Swift, Scala, Shell, config/markup formats
+# Capabilities Reference
+
+Technical reference for what `codebase-context` ships today. For the user-facing overview, see [README.md](../README.md).
+
+## CLI Reference
+
+All 10 MCP tools are exposed as CLI subcommands. Set `CODEBASE_ROOT` or run from the project directory.
+
+| Command | Flags | Maps to |
+|---|---|---|
+| `search --query <q>` | `--intent explore\|edit\|refactor\|migrate`, `--limit <n>`, `--lang <l>`, `--framework <f>`, `--layer <l>` | `search_codebase` |
+| `metadata` | — | `get_codebase_metadata` |
+| `status` | — | `get_indexing_status` |
+| `reindex` | `--incremental`, `--reason <r>` | `refresh_index` |
+| `style-guide` | `--query <q>`, `--category <c>` | `get_style_guide` |
+| `patterns` | `--category all\|di\|state\|testing\|libraries` | `get_team_patterns` |
+| `refs --symbol <name>` | `--limit <n>` | `get_symbol_references` |
+| `cycles` | `--scope <path>` | `detect_circular_dependencies` |
+| `memory list` | `--category`, `--type`, `--query`, `--json` | — |
+| `memory add` | `--type`, `--category`, `--memory`, `--reason` | `remember` |
+| `memory remove <id>` | — | — |
+
+All commands accept `--json` for raw JSON output. Errors go to stderr with exit code 1.
+
+```bash
+# Quick examples
+npx codebase-context status
+npx codebase-context search --query "auth middleware" --intent edit
+npx codebase-context refs --symbol "UserService" --limit 10
+npx codebase-context cycles --scope src/features
+npx codebase-context reindex --incremental
+```
+
+## Tool Surface
+
+10 MCP tools + 1 optional resource (`codebase://context`). **Migration:** `get_component_usage` was removed; use `get_symbol_references` for symbol usage evidence.
+
+### Core Tools
+
+| Tool                    | Input                                                             | Output                                                                                                                                                                                                                  |
+| ----------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `search_codebase`       | `query`, optional `intent`, `limit`, `filters`, `includeSnippets` | Ranked results (`file`, `summary`, `score`, `type`, `trend`, `patternWarning`, `relationships`, `hints`) + `searchQuality` + decision card (`ready`, `nextAction`, `patterns`, `bestExample`, `impact`, `whatWouldHelp`) when `intent="edit"`. Hints capped at 3 per category. |
+| `get_team_patterns`     | optional `category`                                               | Pattern frequencies, trends, golden files, conflicts                                                                                                                                 |
+| `get_symbol_references` | `symbol`, optional `limit`                                        | Concrete symbol usage evidence: `usageCount` + top usage snippets + `confidence` + `isComplete`. `confidence: "syntactic"` means static/source-based only (no runtime or dynamic dispatch). Replaces the removed `get_component_usage`. |
+| `remember`              | `type`, `category`, `memory`, `reason`                            | Persists to `.codebase-context/memory.json`                                                                                                                                          |
+| `get_memory`            | optional `category`, `type`, `query`, `limit`                     | Memories with confidence decay scoring                                                                                                                                               |
+
+### Utility Tools
+
+| Tool                           | Purpose                                              |
+| ------------------------------ | ---------------------------------------------------- |
+| `get_codebase_metadata`        | Framework, dependencies, project stats               |
+| `get_style_guide`              | Style rules from project documentation               |
+| `detect_circular_dependencies` | Import cycles in the file graph                      |
+| `refresh_index`                | Full or incremental re-index + git memory extraction |
+| `get_indexing_status`          | Index state, progress, last stats                    |
+
+## Retrieval Pipeline
+
+Ordered by execution:
+
+1. **Intent classification** — EXACT_NAME (for symbols), CONCEPTUAL, FLOW, CONFIG, WIRING. Sets keyword/semantic weight ratio.
+2. **Query expansion** — bounded domain term expansion for conceptual queries.
+3. **Dual retrieval** — keyword (Fuse.js) + semantic (local embeddings or OpenAI).
+4. **RRF fusion** — Reciprocal Rank Fusion (k=60) across all retrieval channels.
+5. **Definition-first boost** — for EXACT_NAME intent, results matching the symbol name get +15% score boost (e.g., defining file ranks above using files).
+6. **Structure-aware boosting** — import centrality, composition root boost, path overlap, definition demotion for action queries.
+7. **Contamination control** — test file filtering for non-test queries.
+8. **File deduplication** — best chunk per file.
+9. **Symbol-level deduplication** — within each `symbolPath` group, keep only the highest-scoring chunk (prevents duplicate methods from same class clogging results).
+10. **Stage-2 reranking** — cross-encoder (`Xenova/ms-marco-MiniLM-L-6-v2`) triggers when the score between the top files are very close. CPU-only, top-10 bounded.
+11. **Result enrichment** — compact type (`componentType:layer`), pattern momentum (`trend` Rising/Declining only, Stable omitted), `patternWarning`, condensed relationships (`importedByCount`/`hasTests`), structured hints (capped callers/consumers/tests ranked by frequency), scope header for symbol-aware snippets (`// ClassName.methodName`), related memories (capped to 3), search quality assessment with `hint` when low confidence.
+
+### Defaults
+
+- **Chunk size**: 50 lines, 0 overlap
+- **Reranker trigger**: activates when top-3 results are within 0.08 score of each other
+- **Embedding model**: Granite (`ibm-granite/granite-embedding-30m-english`, 8192 token context) via `@huggingface/transformers` v3
+- **Vector DB**: LanceDB with cosine distance
+
+## Decision Card (Edit Intent)
+
+Returned as `preflight` when search `intent` is `edit`, `refactor`, or `migrate`.
+
+**Output shape:**
+
+```typescript
+{
+  ready: boolean;
+  nextAction?: string;        // Only when ready=false; what to search for next
+  warnings?: string[];        // Failure memories (capped at 3)
+  patterns?: {
+    do: string[];             // Top 3 preferred patterns with adoption %
+    avoid: string[];          // Top 3 declining patterns
+  };
+  bestExample?: string;       // Top 1 golden file (path format)
+  impact?: {
+    coverage: string;         // "X/Y callers in results"
+    files: string[];          // Top 3 impact candidates (files importing results)
+  };
+  whatWouldHelp?: string[];   // Concrete next steps (max 4) when ready=false
+}
+```
+
+**Fields explained:**
+
+- `ready`: boolean, whether evidence is sufficient to proceed
+- `nextAction`: actionable reason why `ready=false` (e.g., "2 of 5 callers missing")
+- `warnings`: failure memories from team (auto-surfaces past mistakes)
+- `patterns.do`: patterns the team is adopting, ranked by adoption %
+- `patterns.avoid`: declining patterns, ranked by % (useful for migrations)
+- `bestExample`: exemplar file for the area under edit
+- `impact.coverage`: shows caller visibility ("3/5 callers in results" means 2 callers weren't searched yet)
+- `impact.files`: which files import the results (helps find blind spots)
+- `whatWouldHelp`: specific next searches, tool calls, or files to check that would close evidence gaps
+
+### How `ready` is determined
+
+1. **Evidence triangulation** — scores code match (45%), pattern alignment (30%), and memory support (25%). Needs combined score ≥ 40 to pass.
+2. **Epistemic stress check** — if pattern conflicts, stale memories, thin evidence, or low caller coverage are detected, `ready` is set to false.
+3. **Search quality gate** — if `searchQuality.status` is `low_confidence`, `ready` is forced to false regardless of evidence scores. This prevents the "confidently wrong" problem.
+
+### Internal signals (not in output, feed `ready` computation)
+
+- Risk level from circular deps, impact breadth, and failure memories
+- Preferred/avoid patterns from team pattern analysis
+- Golden files ranked by pattern density
+- Caller coverage from import graph (X of Y callers appearing in results)
+- Pattern conflicts when two patterns in the same category are both > 20% adoption
+- Confidence decay of related memories
+
+## Memory System
+
+- 4 types: `convention`, `decision`, `gotcha`, `failure`
+- Confidence decay: conventions never decay, decisions 180-day half-life, gotchas/failures 90-day half-life
+- Stale threshold: memories below 30% confidence are flagged
+- Git auto-extraction: conventional commits from last 90 days
+- Surface locations: `search_codebase` results (as `relatedMemories`), `get_team_patterns` responses, preflight analysis
+
+## Indexing
+
+- Initial: full scan → chunking (50 lines, 0 overlap) → embedding → vector DB (LanceDB) + keyword index (Fuse.js)
+- Incremental: SHA-256 manifest diffing, selective embed/delete, full intelligence regeneration
+- Version gating: `index-meta.json` tracks format version; mismatches trigger automatic rebuild
+- Crash-safe rebuilds: full rebuilds write to `.staging/` and swap atomically only on success
+- Auto-heal: corrupted index triggers automatic full re-index on next search
+- Relationships sidecar: `relationships.json` contains file import graph and symbol export index
+- Storage: `.codebase-context/` directory (memory.json + generated files)
+
+## Analyzers
+
+- **Angular**: signals, standalone components, control flow syntax, lifecycle hooks, DI patterns, component metadata
+- **Generic**: 30+ have indexing/retrieval coverage including PHP, Ruby, Swift, Scala, Shell, config/markup., 10 languages have full symbol extraction (Tree-sitter: TypeScript, JavaScript, Python, Java, Kotlin, C, C++, C#, Go, Rust). 
+
+Notes:
+
+- Language detection covers common extensions including `.pyi`, `.kt`/`.kts`, `.cc`/`.cxx`, and config formats like `.toml`/`.xml`.
+- When Tree-sitter grammars are present, the Generic analyzer uses AST-aligned chunking and scope-aware prefixes for symbol-aware snippets (with fallbacks).
+
+## Evaluation Harness
+
+Reproducible evaluation is shipped as a CLI entrypoint backed by shared scoring/reporting code.
+
+- **Command:** `npm run eval -- <codebaseA> <codebaseB>` (builds first, then runs `scripts/run-eval.mjs`)
+- **Shared implementation:** `src/eval/harness.ts` + `src/eval/types.ts` (tests and CLI use the same scoring)
+- **Frozen fixtures:**
+  - `tests/fixtures/eval-angular-spotify.json` (real-world)
+  - `tests/fixtures/eval-controlled.json` + `tests/fixtures/codebases/eval-controlled/` (offline controlled)
+- **Reported metrics:** Top-1 accuracy, Top-3 recall, spec contamination rate, and a gate pass/fail