Files

T

asepharyana bb36af62e2 feat: add codegraph tool for querying pre-computed codebase dependency graph

- Implemented `tools-codegraph.ts` to provide various queries on the codebase dependency graph, including impact analysis, dead code detection, module boundaries, and more.
- Created a schema for validating query inputs using Zod.
- Developed helper functions for resolving file paths, formatting output, and handling different query types.
- Added tests for the codegraph queries in `codegraph-queries.test.ts` to ensure functionality and correctness.
- Introduced tests for the codegraph scanning and loading functionalities in `codegraph.test.ts`, verifying the detection of source files, imports, exports, circular dependencies, and entry points.

2026-09-04 22:37:38 +07:00

2.6 KiB

Raw Blame History

Codebase Graph

A pre-computed dependency graph built via static analysis (TypeScript compiler API). It gives the agent an immediate map of the codebase at session start — no exploration turns needed.

How it works

When a session starts, shiro-neko scans all .ts/.tsx files using the TypeScript compiler API. It resolves imports, exports, types, classes, and functions, and builds a directed dependency graph. The result is cached to .shiro/codegraph.json.

On subsequent sessions, if no source files have changed (mtime check), the cached graph is reused. This means the system prompt includes the architecture overview from the very first turn.

What it contains

Entry points: files the graph identifies as starting points (few imports, main() export, CLI-like)
Module map: directory → file count → key file names
Key types: the most frequently defined exported types/interfaces
Circular dependencies: any cycles detected in the import graph
Total LOC: total lines across all source files

System prompt integration

The graph summary appears in the system prompt as a "Codebase Architecture" section, right after the Environment block and before Tools. This means the agent knows the project structure before making a single tool call.

Querying the graph

Use the codegraph tool for detailed queries:

codegraph query: 'summary' — the same overview in the system prompt
codegraph query: 'list' — all files with kind and LOC
codegraph query: 'file', path: 'src/session.ts' — detailed info for one file
codegraph query: 'deps', path: 'session' — what it imports and what imports it
codegraph query: 'types' — all exported types across the codebase
codegraph query: 'circular' — circular dependency chains
codegraph query: 'entry' — detected entry points

Commands

/graph — force-regenerate the graph and show the summary.

Architecture decisions

TypeScript compiler API over regex parsing: handles re-exports, type-only imports, and module resolution correctly. Falls back to manual file walk if no tsconfig.json exists.
Mtime-based freshness: recompute only when a source file has been modified since the graph was generated. The check walks all source files (same as the scan) — for huge codebases, add a --no-graph flag to skip.
Lazy computation: the graph is computed once per session, not per step. The Session caches it in a field and the prompt is built from it.
Graceful fallback: non-TypeScript projects, unreadable directories, or scan failures silently omit the section from the prompt rather than breaking the session.

2.6 KiB Raw Blame History