codebase-context 1.7.0 → 1.8.1

package/docs/capabilities.md

@@ -4,14 +4,15 @@ Technical reference for what `codebase-context` ships today. For the user-facing
 
 ## CLI Reference
 
-All 10 MCP tools are exposed as CLI subcommands. Set `CODEBASE_ROOT` or run from the project directory.
+All shipped capabilities are available locally via the CLI (human-readable by default, `--json` for automation).
+For a “gallery” of commands and examples, see `docs/cli.md`.
 
 | 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` |
+| `reindex` | `--incremental`, `--reason <r>` | equivalent to `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` |
@@ -41,7 +42,7 @@ npx codebase-context reindex --incremental
 | ----------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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`. |
+| `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). When Tree-sitter + file content are available, comments and string literals are excluded from the scan — the count reflects real identifier nodes only. 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                                                                                                                                               |
 
@@ -75,7 +76,7 @@ Ordered by execution:
 
 - **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
+- **Embedding model**: `Xenova/bge-small-en-v1.5` (512 token context, fast, local-first) via `@huggingface/transformers`. Override: `EMBEDDING_MODEL=onnx-community/granite-embedding-small-english-r2-ONNX` for Granite (8192 ctx, slower).
 - **Vector DB**: LanceDB with cosine distance
 
 ## Decision Card (Edit Intent)
@@ -95,13 +96,16 @@ Returned as `preflight` when search `intent` is `edit`, `refactor`, or `migrate`
   };
   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)
+    coverage?: string;        // "X/Y callers in results"
+    files?: string[];         // Back-compat: top impact candidates (paths only)
+    details?: Array<{ file: string; line?: number; hop: 1 | 2 }>; // When available
   };
   whatWouldHelp?: string[];   // Concrete next steps (max 4) when ready=false
 }
 ```
 
+Impact is 2-hop transitive: direct importers (hop 1) and their importers (hop 2), each labeled with distance. Capped at 20 files to avoid noise.
+
 **Fields explained:**
 
 - `ready`: boolean, whether evidence is sufficient to proceed
@@ -111,7 +115,8 @@ Returned as `preflight` when search `intent` is `edit`, `refactor`, or `migrate`
 - `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)
+- `impact.details`: richer impact candidates with optional `line` and hop distance (1 = direct, 2 = transitive)
+- `impact.files`: back-compat list of impact candidate paths (when details aren’t available)
 - `whatWouldHelp`: specific next searches, tool calls, or files to check that would close evidence gaps
 
 ### How `ready` is determined
@@ -141,10 +146,11 @@ Returned as `preflight` when search `intent` is `edit`, `refactor`, or `migrate`
 
 - 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-refresh (MCP server mode only): chokidar file watcher triggers incremental reindex after a debounce on any source file change — `node_modules/`, `.git/`, `dist/`, and `.codebase-context/` are excluded. One-shot CLI runs skip the watcher entirely.
 - 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
+- Relationships sidecar: `relationships.json` contains file import graph, symbol export index, and per-edge import details (`importDetails`: line number + imported symbol names where available)
 - Storage: `.codebase-context/` directory (memory.json + generated files)
 
 ## Analyzers
@@ -167,3 +173,11 @@ Reproducible evaluation is shipped as a CLI entrypoint backed by shared scoring/
   - `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
+
+## Limitations
+
+- **Symbol refs are not a call-graph.** `get_symbol_references` counts identifier-node occurrences in the AST (comments/strings excluded via Tree-sitter). It does not distinguish call sites from type annotations, variable assignments, or imports. Full call-site-specific analysis (`call_expression` nodes only) is a roadmap item.
+- **Impact is 2-hop max.** `computeImpactCandidates` walks direct importers then their importers. Full BFS reachability is on the roadmap.
+- **Angular is the only framework with a rich dedicated analyzer.** All other languages go through the Generic analyzer (30+ languages, chunking + import graph, no framework-specific signal extraction).
+- **Default embedding model is `bge-small-en-v1.5` (512-token context).** Granite (8192 context) is opt-in via `EMBEDDING_MODEL`. OpenAI is opt-in via `EMBEDDING_PROVIDER=openai` — sends code externally.
+- **Patterns are file-level frequency counts.** Not semantic clustering. Rising/Declining trend is derived from git commit recency for files using each pattern, not from usage semantics.

package/docs/cli.md

@@ -0,0 +1,196 @@
+# CLI Gallery (Human-readable)
+
+`codebase-context` exposes its MCP tools as a local CLI so humans can:
+
+- Onboard themselves onto an unfamiliar repo
+- Debug what the MCP server is doing
+- Use outputs in CI/scripts (via `--json`)
+
+> Output depends on the repo you run it against. The examples below are illustrative (paths, counts, and detected frameworks will vary).
+
+## How to run
+
+```bash
+# Run from a repo root, or set CODEBASE_ROOT explicitly:
+CODEBASE_ROOT=/path/to/repo npx -y codebase-context status
+
+# Every command supports --json (machine output). Human mode is default.
+npx -y codebase-context patterns --json
+```
+
+### ASCII fallback
+
+If your terminal doesn’t render Unicode box-drawing cleanly:
+
+```bash
+CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context patterns
+```
+
+## Commands
+
+- `metadata` — tech stack overview
+- `patterns` — team conventions + adoption/trends
+- `search --query <q>` — ranked results; add `--intent edit` for a preflight card
+- `refs --symbol <name>` — concrete reference evidence
+- `cycles` — circular dependency detection
+- `status` — index status/progress
+- `reindex` — rebuild index (full or incremental)
+- `style-guide` — find style guide sections in docs
+- `memory list|add|remove` — manage team memory (stored in `.codebase-context/memory.json`)
+
+---
+
+## `metadata`
+
+```bash
+npx -y codebase-context metadata
+```
+
+Example output:
+
+```text
+┌─ codebase-context [monorepo] ────────────────────────────────────────┐
+│                                                                      │
+│ Framework: Angular unknown   Architecture: mixed                     │
+│ 130 files · 24,211 lines · 1077 components                           │
+│                                                                      │
+│ Dependencies: @huggingface/transformers · @lancedb/lancedb ·         │
+│ @modelcontextprotocol/sdk · @typescript-eslint/typescript-estree ·   │
+│ chokidar · fuse.js (+14 more)                                        │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## `patterns`
+
+```bash
+npx -y codebase-context patterns
+```
+
+Example output (truncated):
+
+```text
+┌─ Team Patterns ──────────────────────────────────────────────────────┐
+│                                                                      │
+│ UNIT TEST FRAMEWORK                                                  │
+│      USE: Vitest – 96% adoption                                      │
+│ alt  CAUTION: Jest – 4% minority pattern                             │
+│                                                                      │
+│ STATE MANAGEMENT                                                     │
+│      PREFER: RxJS – 63% adoption                                     │
+│ alt  Redux-style store – 25%                                         │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## `search`
+
+```bash
+npx -y codebase-context search --query "file watcher" --intent edit --limit 3
+```
+
+Example output (truncated):
+
+```text
+┌─ Search: "file watcher" ─── intent: edit ────────────────────────────┐
+│ Quality: ok (1.00)                                                   │
+│ Ready to edit: YES                                                   │
+│                                                                      │
+│ Best example: index.ts                                               │
+└──────────────────────────────────────────────────────────────────────┘
+
+1.  src/core/file-watcher.ts:44-74
+    confidence: ██████████ 1.18
+    typescript module in file-watcher.ts: startFileWatcher :: (...)
+```
+
+## `refs`
+
+```bash
+npx -y codebase-context refs --symbol "startFileWatcher" --limit 10
+```
+
+Example output (truncated):
+
+```text
+┌─ startFileWatcher ─── 11 references ─── static analysis ─────────────┐
+│                                                                      │
+│ startFileWatcher                                                     │
+│ │                                                                    │
+│ ├─ file-watcher.test.ts:5                                            │
+│ │   import { startFileWatcher } from '../src/core/file-watcher....   │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## `cycles`
+
+```bash
+npx -y codebase-context cycles --scope src
+```
+
+Example output:
+
+```text
+┌─ Circular Dependencies ──────────────────────────────────────────────┐
+│                                                                      │
+│ No cycles found  ·  98 files  ·  260 edges  ·  2.7 avg deps          │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## `status`
+
+```bash
+npx -y codebase-context status
+```
+
+Example output:
+
+```text
+┌─ Index Status ───────────────────────────────────────────────────────┐
+│                                                                      │
+│ State: ready                                                         │
+│ Root:  /path/to/repo                                                 │
+│                                                                      │
+│ → Run `reindex` to re-index (`--incremental` skips unchanged).       │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## `reindex`
+
+```bash
+npx -y codebase-context reindex
+npx -y codebase-context reindex --incremental --reason "changed watcher logic"
+```
+
+> **MCP server mode**: if you're running codebase-context as an MCP server (long-running process), the index auto-refreshes via a file watcher — you don't need to call `reindex` between edits. Use `reindex` for one-shot CLI runs or to force a full rebuild.
+
+## `style-guide`
+
+```bash
+npx -y codebase-context style-guide --query "naming"
+```
+
+Example output:
+
+```text
+No style guides found.
+  Hint: Try broader terms like 'naming', 'patterns', 'testing', 'components'
+```
+
+## `memory`
+
+```bash
+npx -y codebase-context memory list
+npx -y codebase-context memory list --query "watcher"
+
+npx -y codebase-context memory add \
+  --type gotcha \
+  --category tooling \
+  --memory "Use pnpm, not npm" \
+  --reason "Workspace support and speed"
+
+npx -y codebase-context memory remove <id>
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codebase-context",
-  "version": "1.7.0",
-  "description": "Second brain for AI agents working on your codebase - team coding patterns detection, persistent memory, preflight checks, and hybrid search with evidence scoring. Local-first MCP server",
+  "version": "1.8.1",
+  "description": "Second brain for AI agents working on your codebase - team coding patterns detection, persistent memory, edit readiness checks, and hybrid search with evidence scoring. Local-first MCP server",
   "type": "module",
   "main": "./dist/lib.js",
   "types": "./dist/lib.d.ts",
@@ -39,7 +39,8 @@
     "grammars",
     "README.md",
     "LICENSE",
-    "docs"
+    "docs/cli.md",
+    "docs/capabilities.md"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -103,11 +104,12 @@
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",
     "@lancedb/lancedb": "^0.4.0",
-    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "@typescript-eslint/typescript-estree": "^7.0.0",
+    "chokidar": "^3.6.0",
     "fuse.js": "^7.0.0",
     "glob": "^10.3.10",
-    "hono": "^4.11.10",
+    "hono": "^4.12.5",
     "ignore": "^5.3.1",
     "typescript": "^5.3.3",
     "uuid": "^9.0.1",
@@ -125,11 +127,12 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "globals": "^17.0.0",
+    "husky": "^9.1.7",
     "prettier": "^3.7.4",
     "tree-sitter-wasms": "^0.1.13",
     "tsx": "^4.21.0",
     "typescript-eslint": "^8.51.0",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.18"
   },
   "scripts": {
     "preinstall": "npx only-allow pnpm",

package/dist/tools/get-component-usage.d.ts

@@ -1,5 +0,0 @@
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { ToolContext, ToolResponse } from './types.js';
-export declare const definition: Tool;
-export declare function handle(args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResponse>;
-//# sourceMappingURL=get-component-usage.d.ts.map

package/dist/tools/get-component-usage.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"get-component-usage.d.ts","sourceRoot":"","sources":["../../src/tools/get-component-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAE/D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5D,eAAO,MAAM,UAAU,EAAE,IAiBxB,CAAC;AAEF,wBAAsB,MAAM,CAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,YAAY,CAAC,CAiFvB"}

package/dist/tools/get-component-usage.js

@@ -1,83 +0,0 @@
-import { promises as fs } from 'fs';
-export const definition = {
-    name: 'get_component_usage',
-    description: 'Find WHERE a library or component is used in the codebase. ' +
-        "This is 'Find Usages' - returns all files that import a given package/module. " +
-        "Example: get_component_usage('@mycompany/utils') -> shows all files using it.",
-    inputSchema: {
-        type: 'object',
-        properties: {
-            name: {
-                type: 'string',
-                description: "Import source to find usages for (e.g., 'primeng/table', '@mycompany/ui/button', 'lodash')"
-            }
-        },
-        required: ['name']
-    }
-};
-export async function handle(args, ctx) {
-    const { name: componentName } = args;
-    try {
-        const intelligencePath = ctx.paths.intelligence;
-        const content = await fs.readFile(intelligencePath, 'utf-8');
-        const intelligence = JSON.parse(content);
-        const importGraph = intelligence.importGraph || {};
-        const usages = importGraph.usages || {};
-        // Find matching usages (exact match or partial match)
-        let matchedUsage = usages[componentName];
-        // Try partial match if exact match not found
-        if (!matchedUsage) {
-            const matchingKeys = Object.keys(usages).filter((key) => key.includes(componentName) || componentName.includes(key));
-            if (matchingKeys.length > 0) {
-                matchedUsage = usages[matchingKeys[0]];
-            }
-        }
-        if (matchedUsage) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            status: 'success',
-                            component: componentName,
-                            usageCount: matchedUsage.usageCount,
-                            usedIn: matchedUsage.usedIn
-                        }, null, 2)
-                    }
-                ]
-            };
-        }
-        else {
-            // Show top used as alternatives
-            const topUsed = importGraph.topUsed || [];
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            status: 'not_found',
-                            component: componentName,
-                            message: `No usages found for '${componentName}'.`,
-                            suggestions: topUsed.slice(0, 10)
-                        }, null, 2)
-                    }
-                ]
-            };
-        }
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({
-                        status: 'error',
-                        message: 'Failed to get component usage. Run indexing first.',
-                        error: error instanceof Error ? error.message : String(error)
-                    }, null, 2)
-                }
-            ]
-        };
-    }
-}
-//# sourceMappingURL=get-component-usage.js.map

package/dist/tools/get-component-usage.js.map

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