57 lines
2.6 KiB
Markdown
57 lines
2.6 KiB
Markdown
|
# 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.
|