Skip to content

CLAUDE.md

Latest commit

 

History

History
203 lines (164 loc) · 9.82 KB

CLAUDE.md

File metadata and controls

203 lines (164 loc) · 9.82 KB

CLAUDE.md - Project Context for Claude Code

Project Overview

code-review-graph is a persistent, incrementally updated, local-first knowledge graph for token-efficient code review through MCP and the CLI. It parses codebases using Tree-sitter and targeted fallbacks, builds a structural graph in SQLite, and exposes compact context to AI coding tools including Claude Code, Codex, Cursor, Windsurf, Zed, Continue, OpenCode, Gemini CLI, Qwen, Kiro, Qoder, and GitHub Copilot.

Graph Tool Usage (Token-Efficient)

When using code-review-graph MCP tools, follow these rules:

  1. First call: get_minimal_context(task="<description>") — costs ~100 tokens, gives you the full picture.
  2. All subsequent calls: use detail_level="minimal" unless you need more.
  3. Prefer query_graph with a specific target over broad list_* calls.
  4. The next_tool_suggestions field in every response tells you the optimal next step.
  5. Target: ≤5 tool calls per task, ≤800 total tokens of graph context.

Architecture

  • Core Package: code_review_graph/ (Python 3.10+)

    • parser.py — Tree-sitter multi-language AST parser plus targeted fallbacks for broad source-language and notebook support
    • graph.py — SQLite-backed graph store (nodes, edges, BFS impact analysis)
    • tools/ — 30 MCP tool implementations split by domain
    • main.py — FastMCP server entry point, registers 30 tools + 5 prompts
    • incremental.py — Git-based change detection, file watching
    • embeddings.py — Optional vector embeddings (local sentence-transformers, OpenAI-compatible endpoints, Google Gemini, MiniMax)
    • visualization.py — D3.js interactive HTML graph generator
    • cli.py — CLI entry point (install, build, update, postprocess, watch, status, visualize, serve/mcp, wiki, detect-changes, register, unregister, repos, eval, daemon)
    • flows.py — Execution flow detection and criticality scoring
    • communities.py — Community detection (Leiden algorithm or file-based grouping) and architecture overview
    • search.py — FTS5 hybrid search (keyword + vector)
    • changes.py — Risk-scored change impact analysis (detect-changes)
    • refactor.py — Rename preview, dead code detection, refactoring suggestions
    • hints.py — Review hint generation
    • prompts.py — 5 MCP prompt templates (review_changes, architecture_map, debug_issue, onboard_developer, pre_merge_check)
    • wiki.py — Markdown wiki generation from community structure
    • skills.py — Multi-platform install/config generation and shipped skill metadata
    • registry.py — Multi-repo registry helpers
    • migrations.py — Database schema migrations (v1-v9)
    • tsconfig_resolver.py — TypeScript path alias resolution

  • VS Code Extension: code-review-graph-vscode/ (TypeScript)

    • Separate subproject with its own package.json, tsconfig.json
    • Reads from .code-review-graph/graph.db via SQLite

  • Database: .code-review-graph/graph.db (SQLite, WAL mode)

Key Commands

# Development
uv run pytest tests/ --tb=short -q          # Run tests
uv run ruff check code_review_graph/        # Lint
uv run mypy code_review_graph/ --ignore-missing-imports --no-strict-optional

# Build & test
uv run code-review-graph build              # Full graph build
uv run code-review-graph update             # Incremental update
uv run code-review-graph status             # Show stats
uv run code-review-graph serve              # Start MCP server
uv run code-review-graph wiki               # Generate markdown wiki
uv run code-review-graph detect-changes     # Risk-scored change analysis
uv run code-review-graph register <path>    # Register repo in multi-repo registry
uv run code-review-graph repos              # List registered repos
uv run code-review-graph eval               # Run evaluation benchmarks

Code Conventions

  • Line length: 100 chars (ruff)
  • Python target: 3.10+
  • SQL: Always use parameterized queries (? placeholders), never f-string values
  • Error handling: Catch specific exceptions, log with logger.warning/error
  • Thread safety: threading.Lock for shared caches, check_same_thread=False for SQLite
  • Node names: Always sanitize via _sanitize_name() before returning to MCP clients
  • File reads: Read bytes once, hash, then parse (TOCTOU-safe pattern)

Security Invariants

  • No eval(), exec(), pickle, or yaml.unsafe_load()
  • No shell=True in subprocess calls
  • _validate_repo_root() prevents path traversal via repo_root parameter
  • _sanitize_name() strips control characters, caps at 256 chars (prompt injection defense)
  • escH() in visualization escapes HTML entities including quotes and backticks
  • SRI hash on D3.js CDN script tag
  • API keys only from environment variables, never hardcoded

Test Structure

  • tests/test_parser.py — Parser correctness, cross-file resolution
  • tests/test_graph.py — Graph CRUD, stats, impact radius
  • tests/test_tools.py — MCP tool integration tests
  • tests/test_visualization.py — Export, HTML generation, C++ resolution
  • tests/test_incremental.py — Build, update, migration, git ops
  • tests/test_multilang.py — Broad language parsing tests, including SFCs, notebooks, SQL, Perl XS, and modern systems/web languages
  • tests/test_embeddings.py — Vector encode/decode, similarity, store
  • tests/test_flows.py — Execution flow detection and criticality
  • tests/test_communities.py — Community detection, architecture overview
  • tests/test_changes.py — Risk-scored change analysis
  • tests/test_refactor.py — Rename preview, dead code, suggestions
  • tests/test_search.py — FTS5 hybrid search
  • tests/test_hints.py — Review hint generation
  • tests/test_prompts.py — MCP prompt template tests
  • tests/test_wiki.py — Wiki generation
  • tests/test_context_savings.py — Estimated context-savings metadata
  • tests/test_skills.py — Install/config generation and shipped skill metadata
  • tests/test_registry.py — Multi-repo registry
  • tests/test_migrations.py — Database migrations
  • tests/test_eval.py — Evaluation framework
  • tests/test_tsconfig_resolver.py — TypeScript path resolution
  • tests/test_integration_v2.py — v2 pipeline integration test
  • tests/fixtures/ — Sample files for each supported language

CI Pipeline

  • lint: ruff on Python 3.10
  • type-check: mypy
  • security: bandit scan
  • test: pytest matrix (3.10, 3.11, 3.12, 3.13) with 65% coverage minimum

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

  • Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
  • Run bd prime for detailed command reference and session close protocol
  • Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Session Completion

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

  1. File issues for remaining work - Create issues for anything that needs follow-up
  2. Run quality gates (if code changed) - Tests, linters, builds
  3. Update issue status - Close finished work, update in-progress items
  4. PUSH TO REMOTE - This is MANDATORY: 
    git pull --rebase
bd dolt push
git push
git status  # MUST show "up to date with origin"
  5. Clean up - Clear stashes, prune remote branches
  6. Verify - All changes committed AND pushed
  7. Hand off - Provide context for next session

CRITICAL RULES:

  • Work is NOT complete until git push succeeds
  • NEVER stop before pushing - that leaves work stranded locally
  • NEVER say "ready to push when you are" - YOU must push
  • If push fails, resolve and retry until it succeeds

MCP Tools: code-review-graph

IMPORTANT: This project has a knowledge graph. ALWAYS use the code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore the codebase. The graph is faster, cheaper (fewer tokens), and gives you structural context (callers, dependents, test coverage) that file scanning cannot.

When to use graph tools FIRST

  • Exploring code: semantic_search_nodes_tool or query_graph_tool instead of Grep
  • Understanding impact: get_impact_radius_tool instead of manually tracing imports
  • Code review: detect_changes_tool + get_review_context_tool instead of reading entire files
  • Finding relationships: query_graph_tool with callers_of/callees_of/imports_of/tests_for
  • Architecture questions: get_architecture_overview_tool + list_communities_tool

Fall back to Grep/Glob/Read only when the graph doesn't cover what you need.

Key Tools

Tool Use when
detect_changes_tool Reviewing code changes — gives risk-scored analysis
get_review_context_tool Need source snippets for review — token-efficient
get_impact_radius_tool Understanding blast radius of a change
get_affected_flows_tool Finding which execution paths are impacted
query_graph_tool Tracing callers, callees, imports, tests, dependencies
semantic_search_nodes_tool Finding functions/classes by name or keyword
get_architecture_overview_tool Understanding high-level codebase structure
refactor_tool Planning renames, finding dead code

Workflow

  1. The graph auto-updates on file changes (via hooks).
  2. Use detect_changes_tool for code review.
  3. Use get_affected_flows_tool to understand impact.
  4. Use query_graph_tool pattern="tests_for" to check coverage.