From 4e733fe2eac5b9eabae982bac20d737187a43d68 Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Mon, 2 Mar 2026 22:47:48 -0700 Subject: [PATCH 1/2] docs: update all docs to reflect CLI consolidation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update command references across all documentation: - `codegraph explain` → `codegraph audit --quick` - `codegraph hotspots` → `codegraph triage --level` - `codegraph manifesto` → `codegraph check` - Add `codegraph path` references - Update remind-codegraph.sh hook example MCP tool references are left unchanged (backward compat). --- README.md | 46 +++++++++-------- docs/examples/CLI.md | 28 +++++++---- .../claude-code-hooks/remind-codegraph.sh | 2 +- docs/guides/ai-agent-guide.md | 50 +++++++++---------- docs/guides/recommended-practices.md | 14 +++--- docs/use-cases/titan-paradigm.md | 20 ++++---- 6 files changed, 86 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index aba7ae02..97ec8c50 100644 --- a/README.md +++ b/README.md @@ -169,7 +169,7 @@ Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) · [CLAU | 📁 | **File dependencies** | See what a file imports and what imports it | | 💥 | **Impact analysis** | Trace every file affected by a change (transitive) | | 🧬 | **Function-level tracing** | Call chains, caller trees, function-level impact, and A→B pathfinding with qualified call resolution | -| 🎯 | **Deep context** | `context` gives AI agents source, deps, callers, signature, and tests for a function in one call; `explain` gives structural summaries of files or functions | +| 🎯 | **Deep context** | `context` gives AI agents source, deps, callers, signature, and tests for a function in one call; `audit --quick` gives structural summaries of files or functions | | 📍 | **Fast lookup** | `where` shows exactly where a symbol is defined and used — minimal, fast | | 📊 | **Diff impact** | Parse `git diff`, find overlapping functions, trace their callers | | 🔗 | **Co-change analysis** | Analyze git history for files that always change together — surfaces hidden coupling the static graph can't see; enriches `diff-impact` with historically coupled files | @@ -184,7 +184,7 @@ Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) · [CLAU | ⚡ | **Always fresh** | Three-tier incremental detection — sub-second rebuilds even on large codebases | | 🧮 | **Complexity metrics** | Cognitive, cyclomatic, nesting depth, Halstead, and Maintainability Index per function | | 🏘️ | **Community detection** | Louvain clustering to discover natural module boundaries and architectural drift | -| 📜 | **Manifesto rule engine** | Configurable pass/fail rules with warn/fail thresholds for CI gates (exit code 1 on fail) | +| 📜 | **Manifesto rule engine** | Configurable pass/fail rules with warn/fail thresholds for CI gates via `check` (exit code 1 on fail) | | 👥 | **CODEOWNERS integration** | Map graph nodes to CODEOWNERS entries — see who owns each function, ownership boundaries in `diff-impact` | | 💾 | **Graph snapshots** | `snapshot save`/`restore` for instant DB backup and rollback — checkpoint before refactoring, restore without rebuilding | | 🔎 | **Hybrid BM25 + semantic search** | FTS5 keyword search + embedding-based semantic search fused via Reciprocal Rank Fusion — `hybrid`, `semantic`, or `keyword` modes | @@ -229,8 +229,8 @@ codegraph roles --role core --file src/ # Core symbols in src/ ```bash codegraph context # Full context: source, deps, callers, signature, tests codegraph context --depth 2 --no-tests # Include callee source 2 levels deep -codegraph explain # Structural summary: public API, internals, data flow -codegraph explain # Function summary: signature, calls, callers, tests +codegraph audit --quick # Structural summary: public API, internals, data flow +codegraph audit --quick # Function summary: signature, calls, callers, tests ``` ### Impact Analysis @@ -240,9 +240,9 @@ codegraph impact # Transitive reverse dependency trace codegraph query # Function-level: callers, callees, call chain codegraph query --no-tests --depth 5 codegraph fn-impact # What functions break if this one changes -codegraph query --path # Shortest path between two symbols (A calls...calls B) -codegraph query --path --reverse # Follow edges backward -codegraph query --path --depth 5 --kinds calls,imports +codegraph path # Shortest path between two symbols (A calls...calls B) +codegraph path --reverse # Follow edges backward +codegraph path --depth 5 --kinds calls,imports codegraph diff-impact # Impact of unstaged git changes codegraph diff-impact --staged # Impact of staged changes codegraph diff-impact HEAD~3 # Impact vs a specific ref @@ -273,8 +273,8 @@ Co-change data also enriches `diff-impact` — historically coupled files appear ```bash codegraph structure # Directory overview with cohesion scores -codegraph hotspots # Files with extreme fan-in, fan-out, or density -codegraph hotspots --metric coupling --level directory --no-tests +codegraph triage --level file # Files with extreme fan-in, fan-out, or density +codegraph triage --level directory --sort coupling --no-tests ``` ### Code Health & Architecture @@ -287,8 +287,8 @@ codegraph complexity --above-threshold -T # Only functions exceeding warn thres codegraph communities # Louvain community detection — natural module boundaries codegraph communities --drift -T # Drift analysis only — split/merge candidates codegraph communities --functions # Function-level community detection -codegraph manifesto # Pass/fail rule engine (exit code 1 on fail) -codegraph manifesto -T # Exclude test files from rule evaluation +codegraph check # Pass/fail rule engine (exit code 1 on fail) +codegraph check -T # Exclude test files from rule evaluation ``` ### Audit, Triage & Batch @@ -296,10 +296,13 @@ codegraph manifesto -T # Exclude test files from rule evaluation Composite commands for risk-driven workflows and multi-agent dispatch. ```bash -codegraph audit # Combined explain + impact + health in one report +codegraph audit # Combined structural summary + impact + health in one report +codegraph audit --quick # Structural summary only (skip impact and health) codegraph audit src/queries.js -T # Audit all functions in a file codegraph triage # Ranked audit priority queue (connectivity + hotspots + roles) codegraph triage -T --limit 20 # Top 20 riskiest functions, excluding tests +codegraph triage --level file -T # File-level hotspot analysis +codegraph triage --level directory -T # Directory-level hotspot analysis codegraph batch target1 target2 ... # Batch query multiple targets in one call codegraph batch --json targets.json # Batch from a JSON file ``` @@ -309,7 +312,9 @@ codegraph batch --json targets.json # Batch from a JSON file `codegraph check` provides configurable pass/fail predicates for CI gates and state machines. Exit code 0 = pass, 1 = fail. ```bash -codegraph check --staged # Check staged changes +codegraph check # Run manifesto rules on whole codebase +codegraph check --staged # Check staged changes (diff predicates) +codegraph check --staged --rules # Run both diff predicates AND manifesto rules codegraph check --no-new-cycles # Fail if staged changes introduce cycles codegraph check --max-complexity 30 # Fail if any function exceeds complexity threshold codegraph check --max-blast-radius 50 # Fail if blast radius exceeds limit @@ -413,7 +418,7 @@ codegraph registry remove # Unregister | Flag | Description | |---|---| | `-d, --db ` | Custom path to `graph.db` | -| `-T, --no-tests` | Exclude `.test.`, `.spec.`, `__test__` files (available on `fn`, `fn-impact`, `path`, `context`, `explain`, `where`, `diff-impact`, `search`, `map`, `hotspots`, `roles`, `co-change`, `deps`, `impact`, `complexity`, `communities`, `manifesto`, `branch-compare`, `audit`, `triage`, `check`) | +| `-T, --no-tests` | Exclude `.test.`, `.spec.`, `__test__` files (available on `fn`, `fn-impact`, `path`, `context`, `where`, `diff-impact`, `search`, `map`, `roles`, `co-change`, `deps`, `impact`, `complexity`, `communities`, `branch-compare`, `audit`, `triage`, `check`) | | `--depth ` | Transitive trace depth (default varies by command) | | `-j, --json` | Output as JSON | | `-v, --verbose` | Enable debug output | @@ -556,7 +561,7 @@ This project uses codegraph. The database is at `.codegraph/graph.db`. ### Before modifying code, always: 1. `codegraph where ` — find where the symbol lives -2. `codegraph explain ` — understand the structure +2. `codegraph audit --quick` — understand the structure 3. `codegraph context -T` — get full context (source, deps, callers) 4. `codegraph fn-impact -T` — check blast radius before editing @@ -567,16 +572,17 @@ This project uses codegraph. The database is at `.codegraph/graph.db`. - `codegraph build .` — rebuild the graph (incremental by default) - `codegraph map` — module overview - `codegraph query -T` — function call chain (callers + callees) -- `codegraph query --path -T` — shortest call path between two symbols +- `codegraph path -T` — shortest call path between two symbols - `codegraph deps ` — file-level dependencies - `codegraph roles --role dead -T` — find dead code (unreferenced symbols) - `codegraph roles --role core -T` — find core symbols (high fan-in) - `codegraph co-change ` — files that historically change together - `codegraph complexity -T` — per-function complexity metrics (cognitive, cyclomatic, MI) - `codegraph communities --drift -T` — module boundary drift analysis -- `codegraph manifesto -T` — pass/fail rule check (CI gate, exit code 1 on fail) -- `codegraph audit -T` — combined explain + impact + health in one report +- `codegraph check -T` — pass/fail rule check (CI gate, exit code 1 on fail) +- `codegraph audit -T` — combined structural summary + impact + health in one report - `codegraph triage -T` — ranked audit priority queue +- `codegraph triage --level file -T` — file-level hotspot analysis - `codegraph check --staged` — CI validation predicates (exit code 0/1) - `codegraph batch target1 target2` — batch query multiple targets at once - `codegraph owners [target]` — CODEOWNERS mapping for symbols @@ -665,7 +671,7 @@ Create a `.codegraphrc.json` in your project root to customize behavior: ### Manifesto rules -Configure pass/fail thresholds for `codegraph manifesto`: +Configure pass/fail thresholds for `codegraph check` (manifesto mode): ```json { @@ -681,7 +687,7 @@ Configure pass/fail thresholds for `codegraph manifesto`: } ``` -When any function exceeds a `fail` threshold, `codegraph manifesto` exits with code 1 — perfect for CI gates. +When any function exceeds a `fail` threshold, `codegraph check` exits with code 1 — perfect for CI gates. ### LLM credentials diff --git a/docs/examples/CLI.md b/docs/examples/CLI.md index b3ff00a9..703bf325 100644 --- a/docs/examples/CLI.md +++ b/docs/examples/CLI.md @@ -95,12 +95,12 @@ codegraph where -f src/db.js -T --- -## explain — Structural summary (file or function) +## audit --quick — Structural summary (file or function) ### On a file ```bash -codegraph explain src/builder.js -T +codegraph audit src/builder.js --quick -T ``` ``` @@ -132,7 +132,7 @@ codegraph explain src/builder.js -T ### On a function ```bash -codegraph explain buildGraph -T +codegraph audit buildGraph --quick -T ``` ``` @@ -450,10 +450,10 @@ tests/ (0 files, 32 symbols, <-0 ->6 cohesion=0.00) --- -## hotspots — Find structural hotspots +## triage --level — Find structural hotspots ```bash -codegraph hotspots --metric fan-in -T +codegraph triage --level file --sort fan-in -T ``` ``` @@ -469,7 +469,7 @@ Hotspots by fan-in (file-level, top 10): 8. src/cli.js <-0 ->10 (570L, 1 symbols) ``` -Other metrics: `fan-out`, `density`, `coupling`. +Other metrics: `fan-out`, `density`, `coupling`. Use `--level directory` for directory-level hotspots. --- @@ -903,14 +903,16 @@ codegraph communities --drift -T --- -## manifesto — Rule engine pass/fail +## check — Rule engine pass/fail (manifesto mode) + +Running `check` with no ref or `--staged` runs manifesto rules on the whole codebase: ```bash -codegraph manifesto -T +codegraph check -T ``` ``` -# Manifesto Results +# Manifesto Rules Rule Status Threshold Violations ────────────────────────── ──────── ──────────────── ────────── @@ -927,7 +929,7 @@ codegraph manifesto -T ## audit — Composite risk report -Combines explain + fn-impact + complexity metrics into one structured report per function. One call instead of 3-4. +Combines structural summary + fn-impact + complexity metrics into one structured report per function. Use `--quick` for structural summary only (skip impact and health metrics). ```bash codegraph audit src/builder.js -T @@ -962,7 +964,7 @@ codegraph audit buildGraph -T ## triage — Risk-ranked audit queue -Merges connectivity, hotspots, node roles, and complexity into a prioritized audit queue. +Merges connectivity, hotspots, node roles, and complexity into a prioritized audit queue. Use `--level file` or `--level directory` for file/directory-level hotspot analysis. ```bash codegraph triage -T --limit 5 @@ -1008,6 +1010,10 @@ codegraph batch buildGraph openDb parseFile -T --json Configurable pass/fail gates. Exit code 0 = pass, 1 = fail. +- `check` (no args) — runs manifesto rules on whole codebase (see above) +- `check --staged` / `check ` — runs diff predicates against changes +- `check --staged --rules` — runs both diff predicates AND manifesto rules + ```bash codegraph check --staged --no-new-cycles --max-complexity 30 ``` diff --git a/docs/examples/claude-code-hooks/remind-codegraph.sh b/docs/examples/claude-code-hooks/remind-codegraph.sh index d0a5d630..710afe35 100644 --- a/docs/examples/claude-code-hooks/remind-codegraph.sh +++ b/docs/examples/claude-code-hooks/remind-codegraph.sh @@ -61,7 +61,7 @@ cat <' to locate the symbol, (2) 'codegraph explain ${REL_PATH}' to understand the file, (3) 'codegraph context -T' for full context, (4) 'codegraph fn-impact -T' to check blast radius. If you already did this, proceed." + "additionalContext": "[codegraph reminder] You are about to edit ${REL_PATH}. Did you run codegraph first? Before editing, always: (1) 'codegraph where ' to locate the symbol, (2) 'codegraph audit --quick ${REL_PATH}' to understand the file, (3) 'codegraph context -T' for full context, (4) 'codegraph fn-impact -T' to check blast radius. If you already did this, proceed." } } HOOK_OUTPUT diff --git a/docs/guides/ai-agent-guide.md b/docs/guides/ai-agent-guide.md index a378278a..b9ef0712 100644 --- a/docs/guides/ai-agent-guide.md +++ b/docs/guides/ai-agent-guide.md @@ -18,7 +18,7 @@ Codegraph solves these problems by providing a pre-built dependency graph that a | Task | Without codegraph | With codegraph | Savings | |------|------------------|----------------|---------| | Understand a function | Read 3–5 full files (~10K tokens) | `context ` (~400 tokens) | ~96% | -| Find what a file does | Read the file + imports (~4K tokens) | `explain ` (~300 tokens) | ~92% | +| Find what a file does | Read the file + imports (~4K tokens) | `audit --quick ` (~300 tokens) | ~92% | | Locate a symbol | Grep + read matches (~3K tokens) | `where ` (~60 tokens) | ~98% | | Assess change impact | Read callers manually (~5K tokens) | `fn-impact ` (~200 tokens) | ~96% | | Pre-commit check | Manual review (~8K tokens) | `diff-impact --staged` (~300 tokens) | ~96% | @@ -58,8 +58,8 @@ codegraph search "error handling" # Semantic search (requires prior `embed`) Get a structural summary without reading raw source. ```bash -codegraph explain # File summary: public API, internal API, data flow -codegraph explain # Function summary: signature, calls, callers, tests +codegraph audit --quick # File summary: public API, internal API, data flow +codegraph audit --quick # Function summary: signature, calls, callers, tests ``` **When to use:** Before modifying anything. Understand the shape of the code first. @@ -124,19 +124,19 @@ codegraph where --file # File overview: symbols, imports, exports | **When to use** | First step when you know a name but not where it lives | | **Output** | Definition location (file:line), usage sites, export status | -#### `explain` — Structural summary +#### `audit --quick` — Structural summary -Get a human-readable summary of a file or function without reading raw source. +Get a human-readable summary of a file or function without reading raw source. (`audit --quick` replaces the former `explain` CLI command.) ```bash -codegraph explain src/parser.js # File: public API, internal functions, data flow -codegraph explain buildGraph # Function: signature, what it calls, who calls it +codegraph audit --quick src/parser.js # File: public API, internal functions, data flow +codegraph audit --quick buildGraph # Function: signature, what it calls, who calls it ``` | | | |---|---| | **MCP tool** | `explain` | -| **Key flags** | `-T` (no tests), `-j` (JSON) | +| **Key flags** | `--quick`, `-T` (no tests), `-j` (JSON) | | **When to use** | Before modifying code — understand structure first | | **Output** | For files: public/internal API, imports, dependents. For functions: signature, callees, callers, tests | @@ -326,19 +326,19 @@ codegraph structure --depth 2 --sort cohesion | **When to use** | Understanding project layout and identifying well/poorly-cohesive modules | | **Output** | Tree with per-directory metrics | -#### `hotspots` — Structural hotspots +#### `triage --level` — Structural hotspots -Find files or directories with extreme fan-in, fan-out, or symbol density. +Find files or directories with extreme fan-in, fan-out, or symbol density. (`triage --level file|directory` replaces the former `hotspots` CLI command.) ```bash -codegraph hotspots --metric coupling --limit 5 -codegraph hotspots --level directory --metric fan-out +codegraph triage --level file --sort coupling --limit 5 +codegraph triage --level directory --sort fan-out ``` | | | |---|---| | **MCP tool** | `hotspots` | -| **Key flags** | `--metric` (fan-in, fan-out, density, coupling; default: fan-in), `--level` (file, directory), `-n, --limit` (default: 10), `-T` (no tests), `-j` (JSON) | +| **Key flags** | `--level` (file, directory), `--sort` (fan-in, fan-out, density, coupling; default: fan-in), `-n, --limit` (default: 10), `-T` (no tests), `-j` (JSON) | | **When to use** | Finding the most critical or problematic parts of the codebase | | **Output** | Ranked list of files/directories by the chosen metric | @@ -362,7 +362,7 @@ codegraph cycles --functions #### `audit` — Composite risk report -Combines explain + impact + complexity metrics in one call per function or file. +Combines structural summary + impact + complexity metrics in one call per function or file. Use `--quick` for just the structural summary (no impact or health metrics). ```bash codegraph audit src/parser.js -T # Audit all functions in a file @@ -586,20 +586,20 @@ codegraph mcp --repos "myapp,lib" # Restricted repo list | `fn_impact` | `fn-impact ` | Function-level blast radius | | `context` | `context ` | Full function context | | `symbol_children` | `children ` | Sub-declaration children (parameters, properties, constants) | -| `explain` | `explain ` | Structural summary | +| `explain` | `audit --quick ` | Structural summary | | `where` | `where ` | Symbol definition and usage | | `diff_impact` | `diff-impact [ref]` | Git diff impact analysis | | `semantic_search` | `search ` | Natural language code search | | `export_graph` | `export` | Graph export (DOT/Mermaid/JSON) | | `list_functions` | *(MCP only)* | List/filter symbols | | `structure` | `structure [dir]` | Directory tree with metrics | -| `hotspots` | `hotspots` | Structural hotspot detection | +| `hotspots` | `triage --level file` | Structural hotspot detection | | `node_roles` | `roles` | Node role classification | | `co_changes` | `co-change` | Git co-change analysis | | `execution_flow` | `flow` | Execution flow tracing and entry point detection | | `complexity` | `complexity` | Per-function complexity metrics | | `communities` | `communities` | Community detection & drift | -| `manifesto` | `manifesto` | Rule engine pass/fail | +| `manifesto` | `check` (no args) | Rule engine pass/fail | | `code_owners` | `owners` | CODEOWNERS integration | | `audit` | `audit ` | Composite risk report | | `batch_query` | `batch ` | Multi-target batch querying | @@ -685,13 +685,13 @@ Hooks automate codegraph integration so the agent gets structural context withou **Trigger:** Before any Edit or Write operation (PreToolUse). -**What it does:** The first time the agent edits a source file, the hook injects a reminder via `additionalContext` to run `where`, `explain`, `context`, and `fn-impact` before proceeding. Subsequent edits to the same file in the same session are silently allowed (tracked in `.claude/codegraph-checked.log`). +**What it does:** The first time the agent edits a source file, the hook injects a reminder via `additionalContext` to run `where`, `audit --quick`, `context`, and `fn-impact` before proceeding. Subsequent edits to the same file in the same session are silently allowed (tracked in `.claude/codegraph-checked.log`). **Example output the agent sees:** ``` [codegraph reminder] You are about to edit src/parser.js. Did you run codegraph first? -Before editing, always: (1) where , (2) explain src/parser.js, +Before editing, always: (1) where , (2) audit --quick src/parser.js, (3) context -T, (4) fn-impact -T. If you already did this, proceed. ``` @@ -802,7 +802,7 @@ This project uses codegraph for dependency analysis. The graph is at `.codegraph ### Before modifying code, always: 1. `codegraph where ` — find where the symbol lives -2. `codegraph explain ` — understand the structure +2. `codegraph audit --quick ` — understand the structure 3. `codegraph context -T` — get full context (source, deps, callers) 4. `codegraph fn-impact -T` — check blast radius before editing @@ -813,7 +813,7 @@ This project uses codegraph for dependency analysis. The graph is at `.codegraph - `codegraph build .` — rebuild the graph (incremental by default) - `codegraph map` — module overview - `codegraph stats` — graph health and quality score -- `codegraph audit -T` — combined explain + impact + health in one report +- `codegraph audit -T` — combined structural summary + impact + health in one report - `codegraph triage -T` — ranked audit priority queue - `codegraph check --staged` — CI validation predicates (exit code 0/1) - `codegraph batch target1 target2` — batch query multiple targets at once @@ -955,7 +955,7 @@ fi | I want to... | Command | |---------------|---------| | Find where a function is defined | `codegraph where ` | -| See what a file does | `codegraph explain ` | +| See what a file does | `codegraph audit --quick ` | | Understand a function fully | `codegraph context -T` | | See what calls a function | `codegraph fn -T` | | See what a function calls | `codegraph fn -T` | @@ -966,7 +966,7 @@ fi | Get a codebase overview | `codegraph map` | | Check graph health | `codegraph stats` | | Find circular dependencies | `codegraph cycles` | -| Find hotspots | `codegraph hotspots --metric coupling` | +| Find hotspots | `codegraph triage --level file --sort coupling` | | See project structure | `codegraph structure --depth 2` | | List symbols in a file | `codegraph where --file ` | | Get a full risk report for a function | `codegraph audit -T` | @@ -987,7 +987,7 @@ fi | Flag | Short | Description | Available on | |------|-------|-------------|-------------| -| `--no-tests` | `-T` | Exclude test/spec files | All query commands (fn, fn-impact, context, explain, where, diff-impact, search, map, deps, impact, query, stats, hotspots, cycles, export, structure, audit, triage, check, batch, owners, branch-compare) | +| `--no-tests` | `-T` | Exclude test/spec files | All query commands (fn, fn-impact, context, where, diff-impact, search, map, deps, impact, query, path, stats, cycles, export, structure, audit, triage, check, batch, owners, branch-compare) | | `--json` | `-j` | JSON output | Most commands | | `--file ` | `-f` | Scope to a file | fn, fn-impact, context, where | | `--kind ` | `-k` | Filter by symbol kind | fn, fn-impact, context | @@ -1010,7 +1010,7 @@ fi 4. **Check impact before and after.** Run `fn-impact` before editing to know the blast radius. Run `diff-impact --staged` after to verify your changes. -5. **Use `explain` for orientation, `context` for implementation.** `explain` gives you the shape of the code. `context` gives you the actual source you need to write changes. +5. **Use `audit --quick` for orientation, `context` for implementation.** `audit --quick` gives you the shape of the code. `context` gives you the actual source you need to write changes. 6. **Multi-query semantic search.** When searching, phrase the same intent multiple ways: `codegraph search "parse imports, resolve require, extract dependencies"`. RRF ranking combines the results. diff --git a/docs/guides/recommended-practices.md b/docs/guides/recommended-practices.md index c349191f..a8694c2d 100644 --- a/docs/guides/recommended-practices.md +++ b/docs/guides/recommended-practices.md @@ -112,13 +112,13 @@ Add a threshold check to your CI pipeline: ### Code health gate -Use `manifesto` to enforce code health rules in CI — it exits with code 1 when any function exceeds a fail-level threshold: +Use `check` to enforce code health rules in CI — it exits with code 1 when any function exceeds a fail-level threshold: ```yaml - name: Code health gate run: | npx codegraph build - npx codegraph manifesto -T # exits 1 on fail-level breach + npx codegraph check -T # exits 1 on fail-level breach (manifesto mode) ``` ### Change validation gate @@ -206,7 +206,7 @@ This project uses codegraph. The database is at `.codegraph/graph.db`. ### Before modifying code, always: 1. `codegraph where ` — find where the symbol lives -2. `codegraph explain ` — understand the structure +2. `codegraph audit --quick ` — understand the structure 3. `codegraph context -T` — get full context (source, deps, callers) 4. `codegraph fn-impact -T` — check blast radius before editing @@ -224,8 +224,8 @@ This project uses codegraph. The database is at `.codegraph/graph.db`. - `codegraph co-change ` — files that historically change together - `codegraph complexity -T` — per-function complexity metrics (cognitive, cyclomatic, MI) - `codegraph communities --drift -T` — module boundary drift analysis -- `codegraph manifesto -T` — pass/fail rule check (CI gate, exit code 1 on fail) -- `codegraph audit -T` — combined explain + impact + health in one report +- `codegraph check -T` — pass/fail rule check (CI gate, exit code 1 on fail) +- `codegraph audit -T` — combined structural summary + impact + health in one report - `codegraph triage -T` — ranked audit priority queue - `codegraph check --staged` — CI validation predicates (exit code 0/1) - `codegraph batch target1 target2` — batch query multiple targets at once @@ -326,7 +326,7 @@ You can configure [Claude Code hooks](https://docs.anthropic.com/en/docs/claude- **Doc check hook** (PreToolUse on Bash): when Claude runs `git commit` with source files staged (anything under `src/`, `cli.js`, `constants.js`, `parser.js`, `package.json`, or `grammars/`), the hook checks whether `README.md`, `CLAUDE.md`, and `ROADMAP.md` are also staged. If any are missing, it blocks the commit with a `deny` decision listing which docs weren't staged and what to review in each (language support tables, architecture docs, roadmap phases, etc.). Non-source-only commits (tests, docs, config) pass through without checks. -**Edit reminder hook** (PreToolUse on Edit/Write): before the agent writes code, a reminder is injected via `additionalContext` prompting it to check `where`, `explain`, `context`, and `fn-impact` first. Only fires once per file per session (tracks in `.claude/codegraph-checked.log`, gitignored). Non-blocking — it nudges but never prevents the edit. Skips non-source files like `.md`, `.json`, `.yml`. +**Edit reminder hook** (PreToolUse on Edit/Write): before the agent writes code, a reminder is injected via `additionalContext` prompting it to check `where`, `audit --quick`, `context`, and `fn-impact` first. Only fires once per file per session (tracks in `.claude/codegraph-checked.log`, gitignored). Non-blocking — it nudges but never prevents the edit. Skips non-source files like `.md`, `.json`, `.yml`. **Graph update hook** (PostToolUse on Edit/Write): keeps the graph incrementally updated after each file edit. Only changed files are re-parsed. @@ -659,7 +659,7 @@ cp node_modules/@optave/codegraph/.github/workflows/codegraph-impact.yml .github codegraph co-change --analyze # 7. (Optional) Verify code health rules pass -codegraph manifesto -T +codegraph check -T # 8. (Optional) Set up CI validation gate # codegraph check --staged --no-new-cycles --max-blast-radius 50 -T diff --git a/docs/use-cases/titan-paradigm.md b/docs/use-cases/titan-paradigm.md index 3b9402e8..73cb1fbb 100644 --- a/docs/use-cases/titan-paradigm.md +++ b/docs/use-cases/titan-paradigm.md @@ -41,7 +41,7 @@ codegraph build . codegraph map --limit 30 --no-tests # Find structural hotspots — extreme fan-in, fan-out, coupling -codegraph hotspots --no-tests +codegraph triage --level file --no-tests # Graph health overview — node/edge counts, quality score codegraph stats @@ -70,7 +70,7 @@ For deeper structural understanding before touching anything: ```bash # Structural summary of a high-traffic file — public API, internals, data flow -codegraph explain src/builder.js +codegraph audit --quick src/builder.js # Understand a specific function before auditing it codegraph context buildGraph -T @@ -108,10 +108,10 @@ codegraph complexity --file src/parser.js -T codegraph complexity --file src/parser.js --health -T # Pass/fail rule check — does this file meet the manifesto? -codegraph manifesto -T +codegraph check -T # Architecture boundary violations — are cross-module dependencies allowed? -codegraph manifesto -T # boundaries are enforced as manifesto rules +codegraph check -T # boundaries are enforced as manifesto rules ``` When a sub-agent decides a function needs decomposition (complexity > 7, nesting > 3, 10+ mocks), it needs to know what breaks. `fn-impact` gives the complete blast radius **before** the agent writes a single line of code. @@ -191,14 +191,14 @@ codegraph snapshot save pre-gauntlet codegraph snapshot restore pre-gauntlet ``` -Use `manifesto` as an additional CI gate — it exits with code 1 when any function exceeds a fail-level threshold: +Use `check` as an additional CI gate — it exits with code 1 when any function exceeds a fail-level threshold: ```bash # Pass/fail rule check — exit code 1 = fail → rollback trigger -codegraph manifesto -T +codegraph check -T ``` -The orchestrator can gate every commit: run `check --staged` for pass/fail validation, `diff-impact --staged --json` for detailed blast radius, and `manifesto -T` to verify code health rules. Auto-rollback if any exceeds thresholds. Combined with `codegraph watch` for real-time graph updates, the state machine always has a current picture of the codebase. +The orchestrator can gate every commit: run `check --staged` for pass/fail validation, `diff-impact --staged --json` for detailed blast radius, and `check -T` to verify code health rules (or `check --staged --rules` for both at once). Auto-rollback if any exceeds thresholds. Combined with `codegraph watch` for real-time graph updates, the state machine always has a current picture of the codebase. ```bash # Watch mode — graph updates automatically as agents edit files @@ -218,7 +218,7 @@ Several planned features would make codegraph even more powerful for the Titan P | Feature | Status | How it helps | |---------|--------|-------------| -| **Node classification** ([Backlog #4](../../roadmap/BACKLOG.md)) | **Done** | Auto-tags every symbol as Entry Point, Core, Utility, or Adapter based on fan-in/fan-out. Available via `codegraph roles`, `where`, `explain`, `context`, and the `node_roles` MCP tool | +| **Node classification** ([Backlog #4](../../roadmap/BACKLOG.md)) | **Done** | Auto-tags every symbol as Entry Point, Core, Utility, or Adapter based on fan-in/fan-out. Available via `codegraph roles`, `where`, `audit --quick`, `context`, and the `node_roles` MCP tool | | **Git change coupling** ([Backlog #9](../../roadmap/BACKLOG.md)) | **Done** | `codegraph co-change` analyzes git history for files that always change together. Integrated into `diff-impact` output via `historicallyCoupled` section. MCP tool `co_changes` | ### For THE GAUNTLET @@ -226,7 +226,7 @@ Several planned features would make codegraph even more powerful for the Titan P | Feature | Status | How it helps | |---------|--------|-------------| | **Formal code health metrics** ([Backlog #6](../../roadmap/BACKLOG.md)) | **Done** | `codegraph complexity` provides cognitive, cyclomatic, nesting depth, Halstead (volume, effort, bugs), and Maintainability Index per function. `--health` for full view, `--sort mi` to rank by MI, `--above-threshold` for flagged functions. Maps directly to the Gauntlet's "complexity > 7 is a failure" rule. PR #130 + #139 | -| **Manifesto-driven pass/fail** ([Backlog #22](../../roadmap/BACKLOG.md)) | **Done** | `codegraph manifesto` with 9 configurable rules and warn/fail thresholds. Exit code 1 on fail — the Gauntlet gets first-class pass/fail signals without parsing JSON. PR #138 | +| **Manifesto-driven pass/fail** ([Backlog #22](../../roadmap/BACKLOG.md)) | **Done** | `codegraph check` (manifesto mode) with 9 configurable rules and warn/fail thresholds. Exit code 1 on fail — the Gauntlet gets first-class pass/fail signals without parsing JSON. PR #138 | | **Community detection** ([Backlog #11](../../roadmap/BACKLOG.md)) | **Done** | `codegraph communities` with Louvain algorithm discovers natural module boundaries vs actual file organization. `--drift` reveals which directories should be split or merged. `--functions` for function-level clustering. PR #133/#134 | | **Build-time semantic metadata** ([Roadmap Phase 4.4](../../roadmap/ROADMAP.md#44--build-time-semantic-metadata)) | Planned | LLM-generated `complexity_notes`, `risk_score`, and `side_effects` per function. A sub-agent could query `codegraph assess ` and get "3 responsibilities, low cohesion — consider splitting" without analyzing the code itself | @@ -234,7 +234,7 @@ Several planned features would make codegraph even more powerful for the Titan P | Feature | Status | How it helps | |---------|--------|-------------| -| **Architecture boundary rules** ([Backlog #13](../../roadmap/BACKLOG.md)) | **Done** | `manifesto.boundaries` config defines allowed/forbidden dependencies between modules. Onion architecture preset available via `manifesto.boundaryPreset: "onion"`. Violations flagged in `manifesto` and enforceable via `check --no-boundary-violations`. PR #228 + #229 | +| **Architecture boundary rules** ([Backlog #13](../../roadmap/BACKLOG.md)) | **Done** | `manifesto.boundaries` config defines allowed/forbidden dependencies between modules. Onion architecture preset available via `manifesto.boundaryPreset: "onion"`. Violations flagged in `check` and enforceable via `check --no-boundary-violations`. PR #228 + #229 | | **CODEOWNERS integration** ([Backlog #18](../../roadmap/BACKLOG.md)) | **Done** | `codegraph owners` maps graph nodes to CODEOWNERS entries. Shows who owns each function, surfaces ownership boundaries in `diff-impact`. The GLOBAL SYNC agent can identify which teams need to coordinate. PR #195 | | **Refactoring analysis** ([Roadmap Phase 8.5](../../roadmap/ROADMAP.md#85--refactoring-analysis)) | Planned | `split_analysis`, `extraction_candidates`, `boundary_analysis` — LLM-powered structural analysis that identifies exactly where shared abstractions should be created | | **Dead code detection** ([Backlog #1](../../roadmap/BACKLOG.md)) | **Done** | `codegraph roles --role dead -T` lists all symbols with zero fan-in that aren't exported. Delivered as part of node classification | From 20af81df00ee4dc17179d998b4b4f2c1b62a4fc5 Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Mon, 2 Mar 2026 23:01:07 -0700 Subject: [PATCH 2/2] docs: update CLAUDE.md stale CLI references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - explain → audit --quick - query --path → path - manifesto → check - "Combined explain + impact" → "Combined structural summary + impact" --- CLAUDE.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 77b42284..5ceeefdc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -> **Use codegraph before editing code.** This project has a pre-built dependency graph at `.codegraph/graph.db`. Before modifying any function or file, run `node src/cli.js where ` to locate it, `node src/cli.js explain ` to understand the structure, `node src/cli.js context -T` to gather full context, and `node src/cli.js fn-impact -T` to check blast radius. After staging changes, run `node src/cli.js diff-impact --staged -T` to verify impact. This saves tokens, prevents blind edits, and catches breakage before it happens. See the [Dogfooding](#dogfooding--codegraph-on-itself) section for the full command reference. +> **Use codegraph before editing code.** This project has a pre-built dependency graph at `.codegraph/graph.db`. Before modifying any function or file, run `node src/cli.js where ` to locate it, `node src/cli.js audit --quick` to understand the structure, `node src/cli.js context -T` to gather full context, and `node src/cli.js fn-impact -T` to check blast radius. After staging changes, run `node src/cli.js diff-impact --staged -T` to verify impact. This saves tokens, prevents blind edits, and catches breakage before it happens. See the [Dogfooding](#dogfooding--codegraph-on-itself) section for the full command reference. ## Project Overview @@ -114,7 +114,7 @@ Codegraph is **our own tool**. Use it to analyze this repository before making c ### Before modifying code, always: 1. `node src/cli.js where ` — find where the symbol lives -2. `node src/cli.js explain ` — understand the structure +2. `node src/cli.js audit --quick` — understand the structure 3. `node src/cli.js context -T` — get full context (source, deps, callers) 4. `node src/cli.js fn-impact -T` — check blast radius before editing @@ -127,13 +127,13 @@ node src/cli.js build . # Build/update the graph (incremental) node src/cli.js map --limit 20 # Module overview & most-connected nodes node src/cli.js stats # Graph health and quality score node src/cli.js query -T # Function call chain (callers + callees) -node src/cli.js query --path -T # Shortest path between two symbols +node src/cli.js path -T # Shortest path between two symbols node src/cli.js deps src/.js # File-level imports and importers node src/cli.js diff-impact main # Impact of current branch vs main node src/cli.js complexity -T # Per-function complexity metrics node src/cli.js communities -T # Community detection & drift analysis -node src/cli.js manifesto -T # Rule engine pass/fail check -node src/cli.js audit -T # Combined explain + impact + health report +node src/cli.js check -T # Rule engine pass/fail check +node src/cli.js audit -T # Combined structural summary + impact + health report node src/cli.js triage -T # Ranked audit priority queue node src/cli.js check --staged # CI validation predicates (exit code 0/1) node src/cli.js batch t1 t2 -T # Batch query multiple targets