pi-code-review-graph

Graph-aware local code review package for Pi. This extension builds a repo-local code graph, maps changed files to impacted symbols, scores review risk, and queues compact review prompts with related callers, callees, tests, and package boundaries.

The package is local-first, telemetry-free, and designed for production publish through GitHub, Pi packages, and npm.

Table of Contents

• Overview
• Acknowledgements
• Package Boundary
• Core Capabilities
• Command Surface
• LLM Tools
• Documentation Map
• Tech Stack
• Getting Started
• Configuration
• Language Support
• Privacy And Security
• Development Workflow
• Testing And Verification
• Project Structure
• Publishing Notes
• Contribution Guide

Overview

pi-code-review-graph helps Pi review code without reading an entire repository. It indexes source structure into SQLite, tracks imports and calls, calculates blast radius for local changes, and prepares bounded context for the assistant.

This repository is responsible for:

• Pi extension entrypoint and package manifest.
• Repo-local enable/disable and graph storage lifecycle.
• Source file collection with secret and size guards.
• Parser adapters for supported languages.
• Graph schema, migrations, repository layer, impact traversal, and risk scoring.
• Review prompt generation with strict no-edit instruction and JSON marker contract.
• Pi commands, LLM tools, status UI, review panels, and automatic context injection.
• Local-only metrics, benchmark harness, release workflow, and npm publish safety docs.

Acknowledgements

This project is inspired by tirth8205/code-review-graph and adapts the graph-aware code review concept into a Pi extension package.

Package Boundary

The package owns local graph indexing and review context generation. It does not own model selection, external hosting, CI policy outside this repository, or automatic source-code fixes.

Area	Responsibility
Pi extension	Commands, tools, events, UI status, review panels
Graph core	SQLite schema, migrations, store, impact radius, risk scoring
Repo integration	Git root detection, changed files, safe file filtering, freshness checks
Parser layer	AST-backed or best-effort source facts normalized into graph records
Review workflow	Compact context, prompt contract, latest output replay, local feedback
Release workflow	Build output, npm pack dry-run, CI checks, trusted publishing

Core Capabilities

Capability	Status
Repo enable/disable	Implemented through /crg-enable and /crg-disable
Full graph build	Implemented through /crg-build
Incremental update	Implemented through /crg-update and edit/write hooks
Impact radius	Implemented through /crg-impact <paths>
Graph-aware review	Implemented through /crg-review [focus]
Review panel/actions	Implemented through /crg-review-panel and /crg-review-actions
Search index repair	Implemented through /crg-search-rebuild
Settings UI	Implemented through /crg-settings
Local metrics	Implemented through /crg-status --metrics
npm publish safety	Documented and covered by CI/publish workflows

Command Surface

/crg-enable
/crg-disable
/crg-status
/crg-build
/crg-update
/crg-impact <paths>
/crg-review [focus]
/crg-review-panel
/crg-review-actions
/crg-review-feedback
/crg-settings
/crg-search-rebuild

Example build output:

crg build complete: files=42 parsed=42 skipped=0 nodes=310 edges=528 duration=1.4s

Example impact output:

changed: src/repo/config.ts#loadCodeReviewGraphConfig
impacted files: src/commands/status.ts, src/tools/register.ts, test/config.test.ts
risk: medium (fan-in + config path)
tests: test/config.test.ts

Example review behavior:

Queues graph-aware review prompt with changed nodes, callers/callees, related tests,
affected packages, cross-package fan-in/out, risk score, token-savings estimate,
exact review scope, and strict no-edit instruction.

Scope resolution order is deterministic: explicit `/crg-review path` arguments,
then unstaged diff plus eligible untracked source files, then staged-only diff,
then branch/base diff. Branch diff uses `@{upstream}` when available, otherwise
`origin/main`, `origin/master`, `main`, or `master`. User-provided base refs are
validated before being passed to git. Rename/delete records preserve old and new
paths in context warnings for graph cleanup and reviewer visibility.

LLM Tools

crg_build_or_update_graph
crg_get_minimal_context
crg_detect_changes
crg_get_impact_radius
crg_query_graph
crg_search_symbols
crg_get_review_context
crg_stats

Tool outputs are bounded and truncated to Pi-style limits before reaching the model.

Documentation Map

Use this reading order for review or release handoff:

1. docs/PRIVACY_SECURITY.md for local-first behavior, secrets handling, and telemetry stance.
2. docs/LANGUAGE_SUPPORT.md for parser support, non-TS limitations, and confidence tiers.
3. docs/RELEASE_NOTES_0_1_0.md for first public release scope, guardrails, and accepted limitations.

Additional package docs should be added only when they are intended for public users.

Tech Stack

Area	Choice
Runtime target	Pi extension runtime through TypeScript loader
Development runtime	Bun
Language	TypeScript
Formatter/linter	Biome
Graph storage	SQLite through Bun or Node runtime adapter
Node SQLite path	node:sqlite when available
Bun SQLite path	bun:sqlite
Parser default	TypeScript Compiler API for TS/JS
Python parser	Local Python stdlib ast, default with missing-runtime skip
Go parser	Local Go stdlib go/parser, default with missing-runtime skip
Rust parser	web-tree-sitter with bundled Rust WASM grammar, default
Test runner	bun test
Publish target	npm package with Pi manifest

Getting Started

Install published package:

pi install npm:pi-code-review-graph
/reload
/crg-enable
/crg-build

Run first review:

/crg-status
/crg-impact src/extension.ts
/crg-review auth flow
/crg-review-panel

Local package smoke:

bun install
bun run build
pi install .
/reload
/crg-enable
/crg-build

Direct extension smoke, when testing built output without package install:

pi install ./dist/index.ts
/reload

Repo-local files created by /crg-enable:

.pi/code-review-graph.json
.pi/code-review-graph/graph.db
.pi/code-review-graph/metrics.jsonl

Configuration

Default config path:

.pi/code-review-graph.json

Key options:

Option	Purpose
enabled	Enables or disables graph features for repo
include / exclude	Controls eligible files
enabledLanguages	Selects indexed languages; defaults to TS/JS/Python/Go/Rust
experimentalLanguages	Legacy alias for Python, Go, and Rust parser enablement
maxFileBytes	Skips oversized files
maxImpactDepth	Bounds impact traversal depth
maxImpactNodes	Bounds impact node count
maxContextChars	Bounds injected/review context size
autoInjectContext	Injects compact graph context before likely coding tasks
autoUpdateAfterEdit	Runs debounced graph updates after edit/write tools

Example language config:

{
  "enabledLanguages": ["typescript", "javascript", "python", "go", "rust"]
}

Language Support

Language	Default	Parser path	Notes
TypeScript	Yes	TypeScript Compiler API	Source, declarations, imports, exports, calls, tests
JavaScript	Yes	TypeScript Compiler API	Source, declarations, imports, exports, calls, tests
Python	Yes	Local Python stdlib ast	Skipped with warning when python3/python missing
Go	Yes	Local Go stdlib go/parser	Skipped with warning when go missing
Rust	Yes	web-tree-sitter + bundled Rust WASM grammar	No local Rust toolchain required

Python, Go, and Rust are default-enabled for next release. Python/Go missing local runtimes do not fail /crg-build; unavailable parsers warn and matching files are skipped. Non-TS accuracy remains best-effort for unresolved cross-file calls and test links.

Unsupported files are ignored by graph build. They can still appear in git diff output, but symbol-level context is limited to indexed graph data.

Privacy And Security

pi-code-review-graph is local-first.

• No telemetry.
• No network calls from runtime by default.
• No cloud embeddings.
• Review commands are read-only and include no-edit instructions.
• File collection excludes common secrets such as .env, private keys, certificates, and generated/vendor directories.
• Graph DB stores source metadata, not full large source dumps.
• Local metrics stay in .pi/code-review-graph/metrics.jsonl.
• Release workflow uses npm trusted publishing/OIDC instead of long-lived npm publish tokens.

See docs/PRIVACY_SECURITY.md for details.

Development Workflow

Install dependencies:

bun install

Run local checks:

bun run check

Build package output:

bun run build

Run npm package dry-run:

bun run pack:dry-run

Run Node SQLite smoke:

bun run smoke:node-sqlite

Run benchmark harness:

bun run benchmark

Testing And Verification

Fast verification before handoff:

bun run typecheck
bun run lint
bun test ./test
bun run smoke:node-sqlite
bun run pack:dry-run

Release verification should also include:

bun run benchmark
pi install .
/reload
/crg-enable
/crg-build
/crg-status

Recent local verification:

• bun run check passed.
• bun run pack:dry-run passed and produced npm tarball dry-run output.

Project Structure

.
|-- .github/workflows/
|   |-- ci.yml
|   `-- publish.yml
|-- docs/
|   |-- LANGUAGE_SUPPORT.md
|   |-- PRIVACY_SECURITY.md
|   `-- RELEASE_NOTES_0_1_0.md
|-- scripts/
|   |-- benchmark.ts
|   |-- build-package.ts
|   `-- smoke-node-sqlite.mjs
|-- src/
|   |-- benchmark/
|   |-- commands/
|   |-- context/
|   |-- graph/
|   |-- observability/
|   |-- parser/
|   |-- repo/
|   |-- review/
|   |-- sqlite/
|   |-- tools/
|   `-- ui/
|-- test/
|-- index.ts
|-- package.json
`-- README.md

Publishing Notes

Publish path:

1. Complete maintainer release checklist.
2. Run bun run check.
3. Run bun run smoke:node-sqlite.
4. Run bun run pack:dry-run.
5. Create and push release tag.
6. Let .github/workflows/publish.yml publish through npm trusted publishing/OIDC.

The Pi manifest is declared in package.json:

{
  "pi": {
    "extensions": ["./dist/index.ts"]
  }
}

The npm package file whitelist includes runtime dist, selected public docs, README, license, and package metadata.

Contribution Guide

Before changing behavior:

• Keep changes small and tied to one readiness item.
• Add or update tests for behavior changes.
• Keep public docs aligned with runtime behavior.
• Describe Python, Go, and Rust as default-enabled but best-effort for unresolved cross-file calls and non-TS test links.
• Run relevant verification commands before handoff.
• Document skipped checks and why they were skipped.