Phase 108: graph traversal primitives (callers/callees/neighbors/path)

.changeset/phase-108-graph-traversal.md

@@ -0,0 +1,5 @@
+---
+"gitsema": minor
+---
+
+Add graph traversal primitives over the Phase 107 structural graph: `gitsema graph callers <symbol>` / `gitsema graph callees <symbol>` (transitive `calls` traversal, default and max depth 3), `gitsema graph neighbors <node>` (typed neighborhood, any edge kinds, configurable direction/depth), and `gitsema graph path <a> <b>` (shortest typed path between two nodes). New MCP tools `call_graph` and `graph_neighbors` expose the same traversals.

.changeset/phase-109-lens-toggle.md

@@ -0,0 +1,5 @@
+---
+"gitsema": minor
+---
+
+Add a cross-cutting `--lens semantic|structural|hybrid` toggle (plus `--weight-structural <n>`) and four new structural/semantic fusion commands: `gitsema blast-radius <symbol>` ("what changes if I touch this" — structural dependents and/or semantically similar blobs), `gitsema relate <symbol>` (callers/callees plus semantically similar blobs, both lenses), `gitsema similar <symbol>` (same call/import shape and/or semantic similarity), and `gitsema unused` (symbols/files with no inbound calls/imports edges). `gitsema impact <path> --lens structural|hybrid` now reuses `blast-radius` for true structural impact analysis.

CLAUDE.md

@@ -101,6 +101,12 @@ pnpm test -- --watch        # watch mode during development
 - Mock modules with `vi.mock()`, spy with `vi.fn()`, clean up with `vi.restoreAllMocks()` in `afterEach`
 - Integration tests use `mkdtempSync()` + `rmSync()` for isolated temp Git repos
 - `withDbSession()` helper creates isolated temp SQLite DBs per test
+- **Always close `session.rawDb` (`better-sqlite3`) before `rmSync()`-ing its temp
+  directory.** On Windows, `rmSync` on a directory containing an open SQLite handle
+  fails with `EBUSY: resource busy or locked, unlink '...\test.db'` — this passes on
+  Linux/macOS (CI runs `ubuntu-latest` by default) but fails the Windows CI job. Call
+  `session.rawDb.close()` (e.g. in a `try`/`finally` around `withDbSession()`) before
+  the test's temp dir is removed in `afterEach`.
 
 ---
 
@@ -468,7 +474,7 @@ node dist/cli/index.js tools mcp
 
 The MCP server reads the same environment variables as the CLI. It runs against the `.gitsema/index.db` in the current working directory when the server is started.
 
-**Exposed tools (34 total, registered across `src/mcp/tools/{search,analysis,clustering,infrastructure,workflow,narrator}.ts`):**
+**Exposed tools (36 total, registered across `src/mcp/tools/{search,analysis,clustering,infrastructure,workflow,narrator,graph}.ts`):**
 
 | Tool | Description |
 |---|---|
@@ -506,6 +512,8 @@ The MCP server reads the same environment variables as the CLI. It runs against
 | `workflow_run` | Run a named workflow template (`pr-review` \| `incident` \| `release-audit`) |
 | `narrate_repo` | Generate evidence (default) or an LLM narrative of repository development history |
 | `explain_issue_or_error` | Generate evidence (default) or an LLM explanation/timeline for a bug, error, or topic |
+| `call_graph` | Structural call-graph traversal — callers/callees of a symbol (Phase 108) |
+| `graph_neighbors` | Typed neighborhood of a graph node — any edge kinds, direction, depth (Phase 108) |
 
 ---
 

README.md

@@ -358,7 +358,7 @@ CI policy gate over drift, debt, and security thresholds.
 | `gitsema file-evolution <path> [options]` | Track semantic drift of a file over its Git history (see also: `file-diff`, `evolution`) |
 | `gitsema file-diff <ref1> <ref2> <path>` | Compute semantic diff between two versions of a file |
 | `gitsema blame <file>` (alias: `semantic-blame`) | Show semantic origin of each logical block in a file — nearest-neighbor blame |
-| `gitsema impact <path>` | Compute semantically similar blobs across the codebase to highlight refactor impact |
+| `gitsema impact <path> [--lens <lens>] [--weight-structural <n>]` | Compute semantically similar blobs across the codebase to highlight refactor impact. `--lens structural\|hybrid` makes this a thin alias over `blast-radius` (default lens: semantic, pre-Phase-109 behavior) |
 
 #### `gitsema file-evolution <path> [options]`
 
@@ -435,6 +435,14 @@ Track semantic drift of a single file across its Git history.
 | `gitsema co-change <path> [-k/--top <n>]` | Files that historically change together with `<path>` |
 | `gitsema deps <identifier> [--reverse] [--depth <n>] [--edge-types <types>]` | Import/dependency closure of a file or symbol (default edge types: `imports,calls,extends,implements`) |
 | `gitsema graph cycles [--edge-types <types>]` / `gitsema cycles [--edge-types <types>]` | Detect cycles in the structural graph (default: `imports`) |
+| `gitsema graph callers <symbol> [--depth <n>]` | Reverse `calls` traversal — who (transitively) calls `<symbol>` (default depth 3, max 3) |
+| `gitsema graph callees <symbol> [--depth <n>]` | Forward `calls` traversal — what `<symbol>` (transitively) calls (default depth 3, max 3) |
+| `gitsema graph neighbors <node> [--edge-types <types>] [--direction <dir>] [--depth <n>]` | Typed neighborhood of `<node>` — any edge kinds by default (default depth 1, max 3) |
+| `gitsema graph path <a> <b>` | Shortest typed path from `<a>` to `<b>` (max depth 3) |
+| `gitsema blast-radius <symbol> [--lens <lens>] [--depth <n>] [-k/--top <n>] [--weight-structural <n>]` | What changes if I touch this — structural dependents (`calls`/`imports`/`extends`/`implements`/`references`, reverse traversal) and/or semantically similar blobs (default lens: hybrid) |
+| `gitsema relate <symbol> [-k/--top <n>]` | Callers/callees (structural, depth 1) and semantically similar blobs, labeled — both lenses, lose neither |
+| `gitsema similar <symbol> [--lens <lens>] [-k/--top <n>] [--weight-structural <n>]` | Symbols/files with a similar call/import shape (structural, Jaccard overlap) and/or semantically similar (vector) (default lens: hybrid) |
+| `gitsema unused [--edge-types <types>]` | Symbols/files with no inbound `calls`/`imports` edges — structural complement to `dead-concepts` |
 
 ### Workflow & CI