diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..655c47b --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,28 @@ +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Edit|Write|Bash", + "hooks": [ + { + "type": "command", + "command": "code-review-graph update --skip-flows", + "timeout": 30 + } + ] + } + ], + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "code-review-graph status", + "timeout": 10 + } + ] + } + ] + } +} diff --git a/.claude/skills/debug-issue.md b/.claude/skills/debug-issue.md new file mode 100644 index 0000000..ef1b38a --- /dev/null +++ b/.claude/skills/debug-issue.md @@ -0,0 +1,27 @@ +--- +name: Debug Issue +description: Systematically debug issues using graph-powered code navigation +--- + +## Debug Issue + +Use the knowledge graph to systematically trace and debug issues. + +### Steps + +1. Use `semantic_search_nodes` to find code related to the issue. +2. Use `query_graph` with `callers_of` and `callees_of` to trace call chains. +3. Use `get_flow` to see full execution paths through suspected areas. +4. Run `detect_changes` to check if recent changes caused the issue. +5. Use `get_impact_radius` on suspected files to see what else is affected. + +### Tips + +- Check both callers and callees to understand the full context. +- Look at affected flows to find the entry point that triggers the bug. +- Recent changes are the most common source of new issues. + +## Token Efficiency Rules +- ALWAYS start with `get_minimal_context(task="")` before any other graph tool. +- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient. +- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens. diff --git a/.claude/skills/explore-codebase.md b/.claude/skills/explore-codebase.md new file mode 100644 index 0000000..dc7ad10 --- /dev/null +++ b/.claude/skills/explore-codebase.md @@ -0,0 +1,28 @@ +--- +name: Explore Codebase +description: Navigate and understand codebase structure using the knowledge graph +--- + +## Explore Codebase + +Use the code-review-graph MCP tools to explore and understand the codebase. + +### Steps + +1. Run `list_graph_stats` to see overall codebase metrics. +2. Run `get_architecture_overview` for high-level community structure. +3. Use `list_communities` to find major modules, then `get_community` for details. +4. Use `semantic_search_nodes` to find specific functions or classes. +5. Use `query_graph` with patterns like `callers_of`, `callees_of`, `imports_of` to trace relationships. +6. Use `list_flows` and `get_flow` to understand execution paths. + +### Tips + +- Start broad (stats, architecture) then narrow down to specific areas. +- Use `children_of` on a file to see all its functions and classes. +- Use `find_large_functions` to identify complex code. + +## Token Efficiency Rules +- ALWAYS start with `get_minimal_context(task="")` before any other graph tool. +- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient. +- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens. diff --git a/.claude/skills/refactor-safely.md b/.claude/skills/refactor-safely.md new file mode 100644 index 0000000..cf84420 --- /dev/null +++ b/.claude/skills/refactor-safely.md @@ -0,0 +1,28 @@ +--- +name: Refactor Safely +description: Plan and execute safe refactoring using dependency analysis +--- + +## Refactor Safely + +Use the knowledge graph to plan and execute refactoring with confidence. + +### Steps + +1. Use `refactor_tool` with mode="suggest" for community-driven refactoring suggestions. +2. Use `refactor_tool` with mode="dead_code" to find unreferenced code. +3. For renames, use `refactor_tool` with mode="rename" to preview all affected locations. +4. Use `apply_refactor_tool` with the refactor_id to apply renames. +5. After changes, run `detect_changes` to verify the refactoring impact. + +### Safety Checks + +- Always preview before applying (rename mode gives you an edit list). +- Check `get_impact_radius` before major refactors. +- Use `get_affected_flows` to ensure no critical paths are broken. +- Run `find_large_functions` to identify decomposition targets. + +## Token Efficiency Rules +- ALWAYS start with `get_minimal_context(task="")` before any other graph tool. +- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient. +- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens. diff --git a/.claude/skills/review-changes.md b/.claude/skills/review-changes.md new file mode 100644 index 0000000..6bb3558 --- /dev/null +++ b/.claude/skills/review-changes.md @@ -0,0 +1,29 @@ +--- +name: Review Changes +description: Perform a structured code review using change detection and impact +--- + +## Review Changes + +Perform a thorough, risk-aware code review using the knowledge graph. + +### Steps + +1. Run `detect_changes` to get risk-scored change analysis. +2. Run `get_affected_flows` to find impacted execution paths. +3. For each high-risk function, run `query_graph` with pattern="tests_for" to check test coverage. +4. Run `get_impact_radius` to understand the blast radius. +5. For any untested changes, suggest specific test cases. + +### Output Format + +Provide findings grouped by risk level (high/medium/low) with: +- What changed and why it matters +- Test coverage status +- Suggested improvements +- Overall merge recommendation + +## Token Efficiency Rules +- ALWAYS start with `get_minimal_context(task="")` before any other graph tool. +- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient. +- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens. diff --git a/.codex/config.toml b/.codex/config.toml index 5e84d2e..b8982e6 100644 --- a/.codex/config.toml +++ b/.codex/config.toml @@ -1,3 +1,7 @@ [mcp_servers.chrome-devtools] command = "npx" args = ["chrome-devtools-mcp@latest", "--browserUrl", "http://localhost:9222"] + +[mcp_servers.code-review-graph] +command = "uvx" +args = ["code-review-graph", "serve"] diff --git a/.gitignore b/.gitignore index e3d2b54..9839f04 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,5 @@ output/playwright/ /blob-report/ /playwright/.cache/ /playwright/.auth/ +# Added by code-review-graph +.code-review-graph/ diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..c942808 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "code-review-graph": { + "command": "uvx", + "args": [ + "code-review-graph", + "serve" + ], + "type": "stdio" + } + } +} diff --git a/.opencode.json b/.opencode.json new file mode 100644 index 0000000..81d79fa --- /dev/null +++ b/.opencode.json @@ -0,0 +1,13 @@ +{ + "mcpServers": { + "code-review-graph": { + "command": "uvx", + "args": [ + "code-review-graph", + "serve" + ], + "type": "stdio", + "env": [] + } + } +} diff --git a/AGENTS.md b/AGENTS.md index 4e17d6c..ab83456 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,3 +25,42 @@ import { mdiAccount } from '@mdi/js' ``` + + +## 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` or `query_graph` instead of Grep +- **Understanding impact**: `get_impact_radius` instead of manually tracing imports +- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files +- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for +- **Architecture questions**: `get_architecture_overview` + `list_communities` + +Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need. + +### Key Tools + +| Tool | Use when | +|------|----------| +| `detect_changes` | Reviewing code changes — gives risk-scored analysis | +| `get_review_context` | Need source snippets for review — token-efficient | +| `get_impact_radius` | Understanding blast radius of a change | +| `get_affected_flows` | Finding which execution paths are impacted | +| `query_graph` | Tracing callers, callees, imports, tests, dependencies | +| `semantic_search_nodes` | Finding functions/classes by name or keyword | +| `get_architecture_overview` | 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` for code review. +3. Use `get_affected_flows` to understand impact. +4. Use `query_graph` pattern="tests_for" to check coverage. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0a3e5c8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,38 @@ + +## 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` or `query_graph` instead of Grep +- **Understanding impact**: `get_impact_radius` instead of manually tracing imports +- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files +- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for +- **Architecture questions**: `get_architecture_overview` + `list_communities` + +Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need. + +### Key Tools + +| Tool | Use when | +|------|----------| +| `detect_changes` | Reviewing code changes — gives risk-scored analysis | +| `get_review_context` | Need source snippets for review — token-efficient | +| `get_impact_radius` | Understanding blast radius of a change | +| `get_affected_flows` | Finding which execution paths are impacted | +| `query_graph` | Tracing callers, callees, imports, tests, dependencies | +| `semantic_search_nodes` | Finding functions/classes by name or keyword | +| `get_architecture_overview` | 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` for code review. +3. Use `get_affected_flows` to understand impact. +4. Use `query_graph` pattern="tests_for" to check coverage.