wehub-resource-sync
207 lines
10 KiB
Markdown
207 lines
10 KiB
Markdown
# 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_tool` 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
|
|
- `custom_languages.py` — Config-driven custom language support (`.code-review-graph/languages.toml`, see docs/CUSTOM_LANGUAGES.md)
|
|
- `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/init, build, update, postprocess, embed, 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
|
|
|
|
```bash
|
|
# 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_custom_languages.py` — Config-driven custom languages (languages.toml loader + end-to-end Erlang parse)
|
|
- `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/test_action_render.py` — GitHub Action PR comment renderer (`scripts/render_pr_comment.py`)
|
|
- `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
|
|
|
|
|
|
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
|
|
## Beads Issue Tracker
|
|
|
|
This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
|
|
|
|
### Quick Reference
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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
|
|
<!-- END BEADS INTEGRATION -->
|
|
|
|
<!-- code-review-graph MCP tools -->
|
|
## 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.
|