diff --git a/README.md b/README.md index c57046d88..9de7834f7 100644 --- a/README.md +++ b/README.md @@ -350,10 +350,10 @@ codegraph batch --json targets.json # Batch from a JSON file 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 -codegraph check --no-boundary-violations # Fail on architecture boundary violations +codegraph check --staged --cycles # Fail if staged changes introduce cycles +codegraph check --staged --blast-radius 50 # Fail if blast radius exceeds limit +codegraph check --staged --boundaries # Fail on architecture boundary violations +codegraph check --staged --signatures # Fail if an exported declaration's line was modified codegraph check main # Check current branch vs main ``` diff --git a/docs/contributing/harness-engineering.md b/docs/contributing/harness-engineering.md index 486c33ba8..890b1fc1d 100644 --- a/docs/contributing/harness-engineering.md +++ b/docs/contributing/harness-engineering.md @@ -41,7 +41,7 @@ Zero-tolerance enforcement: the agent cannot proceed until all checks pass. No w ```bash # Example: codegraph pre-commit gate codegraph build -codegraph check --staged --no-new-cycles --max-blast-radius 50 -T +codegraph check --staged --cycles --blast-radius 50 -T ``` ### Layer 2: AI Review @@ -119,7 +119,7 @@ With codegraph, this is built-in: ```bash # codegraph check provides actionable output -codegraph check --staged --no-new-cycles --max-blast-radius 50 -T +codegraph check --staged --cycles --blast-radius 50 -T # Output: "Cycle detected: A -> B -> C -> A. Break the cycle by..." # Output: "Blast radius 67 exceeds threshold 50. Function X affects..." ``` @@ -154,7 +154,7 @@ Types -> Config -> Repo -> Service -> Runtime -> UI ``` **Enforcement tools:** -- `codegraph check --no-boundary-violations` — blocks imports that violate layer direction +- `codegraph check --staged --boundaries` — blocks imports that violate layer direction - `codegraph cycles` — detects circular dependencies - Custom ESLint rules or `dependency-cruiser` for additional constraints - CI gates that fail the build on violations @@ -259,7 +259,7 @@ Codegraph already implements most of these practices. Here's how they map: |---|---| | Deterministic guardrails | `codegraph check` pre-commit gates, cycle detection, blast radius thresholds | | Remediation-focused errors | `codegraph check` output includes what violated and where | -| Mechanical architecture | `codegraph check --no-boundary-violations`, `codegraph cycles` | +| Mechanical architecture | `codegraph check --staged --boundaries`, `codegraph cycles` | | Silent success / loud failure | Claude Code hooks exit silently on success | | AGENTS.md | `CLAUDE.md` with codegraph workflow commands | | Progress tracking | Titan Paradigm skills with state files | @@ -274,7 +274,7 @@ To add harness engineering to an existing codegraph project: 1. **Create `CLAUDE.md`** with build commands and your top 5 failure-driven rules 2. **Add pre-commit hooks** using codegraph check: ```bash - codegraph check --staged --no-new-cycles --max-blast-radius 50 -T + codegraph check --staged --cycles --blast-radius 50 -T ``` 3. **Configure CI gates** with `codegraph check -T` in your pipeline 4. **Set up Claude Code hooks** — see [Claude Code Hooks Guide](../examples/claude-code-hooks/README.md) for ready-to-use scripts diff --git a/docs/examples/CLI.md b/docs/examples/CLI.md index a03a51051..f2538ed48 100644 --- a/docs/examples/CLI.md +++ b/docs/examples/CLI.md @@ -498,7 +498,7 @@ Cycles whose only closing edge is a low-confidence dynamic call (resolved via a resolver heuristic rather than confirmed statically) are marked `[speculative]` rather than reported as confirmed structural cycles. Pass `--exclude-speculative` to drop them from the output entirely, or `--json` to -get a `speculative: boolean` field per cycle. `codegraph check --cycles` and +get a `speculative: boolean` field per cycle. `codegraph check --staged --cycles` and the manifesto `noCycles` rule ignore speculative-only cycles by default (see `check.excludeSpeculativeCycles` in [configuration](../guides/configuration.md)). @@ -1172,43 +1172,46 @@ Configurable pass/fail gates. Exit code 0 = pass, 1 = fail. - `check --staged --rules` — runs both diff predicates AND manifesto rules ```bash -codegraph check --staged --no-new-cycles --max-complexity 30 +codegraph check --staged --cycles ``` ``` # Check Results - ✓ no-new-cycles — no new cycles introduced - ✗ max-complexity (30) — 3 functions exceed threshold: - buildGraph (cognitive=495) src/builder.js:335 - extractJavaSymbols (cognitive=208) src/extractors/java.js - extractSymbolsWalk (cognitive=197) src/extractors/javascript.js + Changed files: 4 New files: 1 Deleted files: 0 - Result: FAIL (exit code 1) + [PASS] cycles + + 1 predicates | 1 passed | 0 failed ``` ```bash -codegraph check --staged --max-blast-radius 50 +codegraph check --staged --blast-radius 50 ``` ``` # Check Results - ✓ max-blast-radius (50) — max blast radius is 1 + Changed files: 4 New files: 1 Deleted files: 0 - Result: PASS (exit code 0) + [FAIL] blast-radius + buildGraph (function) at src/builder.js:335 — 67 callers (max: 50) + + 1 predicates | 0 passed | 1 failed ``` ```bash -codegraph check --no-boundary-violations -T +codegraph check --staged --boundaries -T ``` ``` # Check Results - ✓ no-boundary-violations — no architecture boundary violations + Changed files: 4 New files: 1 Deleted files: 0 + + [PASS] boundaries - Result: PASS (exit code 0) + 1 predicates | 1 passed | 0 failed ``` --- diff --git a/docs/examples/MCP.md b/docs/examples/MCP.md index 5d3974453..019c1fa32 100644 --- a/docs/examples/MCP.md +++ b/docs/examples/MCP.md @@ -946,19 +946,19 @@ Configurable pass/fail gates. Returns structured results with exit status. ```json { "tool": "check", - "arguments": { "staged": true, "no_new_cycles": true, "max_complexity": 30 } + "arguments": { "staged": true, "cycles": true, "blast_radius": 50 } } ``` ```json { - "checks": [ - { "name": "no-new-cycles", "passed": true, "detail": "no new cycles introduced" }, - { "name": "max-complexity", "passed": false, "threshold": 30, "violations": [ - { "name": "buildGraph", "file": "src/builder.js", "line": 335, "cognitive": 495 }, - { "name": "extractJavaSymbols", "file": "src/extractors/java.js", "cognitive": 208 } + "predicates": [ + { "name": "cycles", "passed": true }, + { "name": "blast-radius", "passed": false, "threshold": 50, "violations": [ + { "name": "buildGraph", "kind": "function", "file": "src/builder.js", "line": 335, "transitiveCallers": 67 } ]} ], + "summary": { "changedFiles": 4, "newFiles": 1, "deletedFiles": 0, "total": 2, "passed": 1, "failed": 1 }, "passed": false } ``` @@ -966,16 +966,17 @@ Configurable pass/fail gates. Returns structured results with exit status. ```json { "tool": "check", - "arguments": { "staged": true, "max_blast_radius": 50, "no_boundary_violations": true } + "arguments": { "staged": true, "boundaries": true, "signatures": true } } ``` ```json { - "checks": [ - { "name": "max-blast-radius", "passed": true, "detail": "max blast radius is 1" }, - { "name": "no-boundary-violations", "passed": true, "detail": "no violations" } + "predicates": [ + { "name": "boundaries", "passed": true }, + { "name": "signatures", "passed": true } ], + "summary": { "changedFiles": 4, "newFiles": 1, "deletedFiles": 0, "total": 2, "passed": 2, "failed": 0 }, "passed": true } ``` diff --git a/docs/guides/ai-agent-guide.md b/docs/guides/ai-agent-guide.md index 4afb80bee..f91f17f0a 100644 --- a/docs/guides/ai-agent-guide.md +++ b/docs/guides/ai-agent-guide.md @@ -441,14 +441,14 @@ codegraph batch target1 target2 target3 -T --json Configurable pass/fail gates with exit code 0 (pass) or 1 (fail). ```bash -codegraph check --staged --no-new-cycles --max-complexity 30 -codegraph check --staged --max-blast-radius 50 --no-boundary-violations +codegraph check --staged --cycles +codegraph check --staged --blast-radius 50 --boundaries --signatures ``` | | | |---|---| | **MCP tool** | `check` | -| **Key flags** | `--staged`, `--no-new-cycles`, `--max-complexity `, `--max-blast-radius `, `--no-boundary-violations`, `-T` (no tests) | +| **Key flags** | `--staged`, `--cycles`, `--blast-radius `, `--boundaries`, `--signatures`, `-T` (no tests) | | **When to use** | CI gates, state machines, rollback triggers — anywhere you need a pass/fail signal | | **Output** | Per-predicate pass/fail results; exit code 0 or 1 | @@ -894,7 +894,7 @@ This project uses codegraph for dependency analysis. The graph is at `.codegraph - `codegraph diff-impact main -T` — impact of branch vs main - `codegraph audit -T` — structural summary + impact + health in one report - `codegraph triage -T` — ranked audit priority queue -- `codegraph check --staged --no-new-cycles` — CI validation predicates (exit 0/1) +- `codegraph check --staged --cycles` — CI validation predicates (exit 0/1) - `codegraph batch t1 t2 t3 -T --json` — batch query multiple targets ### Overview @@ -1087,7 +1087,7 @@ fi | Get a full risk report for a function | `codegraph audit -T` | | Get a ranked list of riskiest functions | `codegraph triage -T --limit 20` | | Batch query multiple targets at once | `codegraph batch t1 t2 t3 -T --json` | -| Validate staged changes pass CI rules | `codegraph check --staged --no-new-cycles` | +| Validate staged changes pass CI rules | `codegraph check --staged --cycles` | | Find who owns a piece of code | `codegraph owners ` | | Checkpoint the graph before refactoring | `codegraph snapshot save ` | | Restore graph after failed refactoring | `codegraph snapshot restore ` | diff --git a/docs/roadmap/BACKLOG.md b/docs/roadmap/BACKLOG.md index ee613ed52..1604bc3e8 100644 --- a/docs/roadmap/BACKLOG.md +++ b/docs/roadmap/BACKLOG.md @@ -55,7 +55,7 @@ Non-breaking, ordered by problem-fit: | 18 | ~~CODEOWNERS integration~~ | ~~Map graph nodes to CODEOWNERS entries. Show who owns each function, surface ownership boundaries in `diff-impact`. Inspired by CKB.~~ | Developer Experience | ~~`diff-impact` tells agents which teams to notify; ownership-aware impact analysis reduces missed reviews~~ | ✓ | ✓ | 3 | No | — | **DONE** — `src/owners.js` module with CODEOWNERS parser, matcher, and data functions. `codegraph owners [target]` CLI command with `--owner`, `--boundary`, `-f`, `-k`, `-T`, `-j` options. `code_owners` MCP tool. Integrated into `diff-impact` (affected owners + suggested reviewers). No new deps — glob patterns via ~30-line `patternToRegex`. PR #195. | | 22 | ~~Manifesto-driven pass/fail~~ | ~~User-defined rule engine with custom thresholds (e.g. "cognitive > 15 = fail", "cyclomatic > 10 = fail", "imports > 10 = decompose"). Outputs pass/fail per function/file. Generalizes ID 13 (boundary rules) into a generic rule system.~~ | Analysis | ~~Enables autonomous multi-agent audit workflows (GAUNTLET pattern); CI integration for code health gates with configurable thresholds~~ | ✓ | ✓ | 3 | No | — | **DONE** — `codegraph manifesto` with 9 configurable rules (cognitive, cyclomatic, nesting, MI, Halstead volume/effort/bugs, fan-in, fan-out). Warn/fail thresholds via `.codegraphrc.json`. Exit code 1 on any fail-level breach — CI gate ready. PR #138. | | 31 | ~~Graph snapshots~~ | ~~`codegraph snapshot save ` / `codegraph snapshot restore ` for lightweight SQLite DB backup and restore. Enables orchestrators to checkpoint before refactoring passes and instantly rollback without rebuilding. After Phase 4, also preserves embeddings and semantic metadata. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) STATE MACHINE phase.~~ | Orchestration | ~~Multi-agent workflows get instant rollback without re-running expensive builds or LLM calls — orchestrator checkpoints before each pass and restores on failure~~ | ✓ | ✓ | 3 | No | — | **DONE** — `codegraph snapshot` subcommand group with `save`, `restore`, `list`, `delete`. Uses SQLite `VACUUM INTO` for atomic, WAL-free snapshots in `.codegraph/snapshots/`. All 6 functions exported via programmatic API. PR #192. | -| 30 | ~~Change validation predicates~~ | ~~`codegraph check --staged` with configurable predicates: `--no-new-cycles`, `--max-blast-radius N`, `--no-signature-changes`, `--no-boundary-violations`. Returns exit code 0/1 for CI gates and state machines. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) STATE MACHINE phase.~~ | CI | ~~Automated rollback triggers without parsing JSON — orchestrators and CI pipelines get first-class pass/fail signals for blast radius, cycles, and contract changes~~ | ✓ | ✓ | 3 | No | — | **DONE** — `codegraph check` with `--no-new-cycles`, `--max-complexity N`, `--max-blast-radius N`, `--no-boundary-violations`, and `--staged`/ref support. Exit code 0/1 for CI gates. `check` MCP tool. PR #225 + #230. | +| 30 | ~~Change validation predicates~~ | ~~`codegraph check --staged` with configurable predicates: `--no-new-cycles`, `--max-blast-radius N`, `--no-signature-changes`, `--no-boundary-violations`. Returns exit code 0/1 for CI gates and state machines. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) STATE MACHINE phase.~~ | CI | ~~Automated rollback triggers without parsing JSON — orchestrators and CI pipelines get first-class pass/fail signals for blast radius, cycles, and contract changes~~ | ✓ | ✓ | 3 | No | — | **DONE** — `codegraph check` with `--cycles`, `--blast-radius N`, `--boundaries`, `--signatures`, and `--staged`/ref support. Exit code 0/1 for CI gates. `check` MCP tool. PR #225 + #230. | | 6 | ~~Formal code health metrics~~ | ~~Cyclomatic complexity, Maintainability Index, and Halstead metrics per function — we already parse the AST, the data is there. Inspired by code-health-meter (published in ACM TOSEM 2025).~~ | Analysis | ~~Agents can prioritize refactoring targets; `hotspots` becomes richer with quantitative health scores per function~~ | ✓ | ✓ | 2 | No | — | **DONE** — `codegraph complexity` provides cognitive, cyclomatic, nesting depth, Halstead (volume, difficulty, effort, bugs), and Maintainability Index per function. `--health` for full Halstead view, `--sort mi` to rank by MI, `--above-threshold` for flagged functions. `function_complexity` DB table. `complexity` MCP tool. PR #130 + #139. | | 11 | ~~Community detection~~ | ~~Leiden/Louvain algorithm to discover natural module boundaries vs actual file organization. Reveals which symbols are tightly coupled and whether the directory structure matches. Inspired by axon, GitNexus, CodeGraphMCPServer.~~ | Intelligence | ~~Surfaces architectural drift — when directory structure no longer matches actual dependency clusters; guides refactoring~~ | ✓ | ✓ | 2 | No | — | **DONE** — `codegraph communities` with Louvain algorithm. File-level and `--functions` function-level detection. `--drift` for drift analysis (split/merge candidates). `--resolution` tunable. `communities` MCP tool. PR #133/#134. | | 21 | ~~Cognitive + cyclomatic complexity~~ | ~~Cognitive Complexity (SonarSource) as the primary readability metric — penalizes nesting, so it subsumes nesting depth analysis. Cyclomatic complexity (McCabe) as secondary testability metric. Both computed from existing tree-sitter AST in a single traversal. Cognitive > 15 or cyclomatic > 10 = flag for refactoring. Extends ID 6 with the two most actionable metrics.~~ | Analysis | ~~Agents can flag hard-to-understand and hard-to-test functions in one pass; cognitive complexity captures both decision complexity and nesting depth in a single score~~ | ✓ | ✓ | 2 | No | — | **DONE** — Subsumed by ID 6. `codegraph complexity` provides both cognitive and cyclomatic metrics (plus nesting depth, Halstead, MI) in a single command. PR #130. | diff --git a/docs/use-cases/harness-engineering.md b/docs/use-cases/harness-engineering.md index 8ef237a9d..fc008ac8a 100644 --- a/docs/use-cases/harness-engineering.md +++ b/docs/use-cases/harness-engineering.md @@ -46,7 +46,7 @@ The most impactful harness component. The agent cannot commit until all checks p ```bash # One-call pre-commit gate: cycles + blast radius + boundaries -codegraph check --staged --no-new-cycles --max-blast-radius 50 --no-boundary-violations -T +codegraph check --staged --cycles --blast-radius 50 --boundaries -T ``` Exit code 0 = pass, 1 = fail. Perfect for hooks and CI gates. The agent doesn't need to know your architectural rules — the harness enforces them mechanically. @@ -55,13 +55,13 @@ Individual checks for targeted enforcement: ```bash # Did this change introduce a circular dependency? -codegraph check --staged --no-new-cycles +codegraph check --staged --cycles # Is the blast radius acceptable? (N = max callers affected) -codegraph check --staged --max-blast-radius 30 +codegraph check --staged --blast-radius 30 # Does this change violate module boundary rules? -codegraph check --staged --no-boundary-violations +codegraph check --staged --boundaries # Full code health gate — 9 configurable rules with warn/fail thresholds codegraph check -T @@ -76,7 +76,7 @@ OpenAI's key finding: linter error messages become part of the agent's context. Codegraph's output is designed for this: ```bash -codegraph check --staged --no-new-cycles --max-blast-radius 50 -T +codegraph check --staged --cycles --blast-radius 50 -T ``` ``` @@ -113,10 +113,12 @@ Then enforce it: ```bash # The agent literally cannot create an import that violates layer direction -codegraph check --staged --no-boundary-violations -T +codegraph check --staged --boundaries -T -# Detect all existing boundary violations for cleanup -codegraph check --no-boundary-violations -T +# Detect all existing boundary violations for cleanup (manifesto mode — +# reads manifesto.boundaries from .codegraphrc.json, checks the whole +# codebase rather than just a diff) +codegraph check -T ``` The agent doesn't need to "know" the rule. It tries an import, the check fails with a clear message, and it restructures. The harness teaches through failure. @@ -194,7 +196,7 @@ All of the above works in CI pipelines, not just locally: run: npx codegraph check -T - name: Change validation - run: npx codegraph check --staged --no-new-cycles --max-blast-radius 50 --no-boundary-violations -T + run: npx codegraph check --staged --cycles --blast-radius 50 --boundaries -T - name: Impact comment on PR run: | @@ -212,7 +214,7 @@ Here's how codegraph maps to each harness engineering practice: |---|---|---| | **Deterministic guardrails** | Agent introduces cycles, boundary violations, high blast radius | `codegraph check --staged` with configurable predicates | | **Remediation-focused errors** | Agent can't self-correct from opaque error messages | `check` output includes what violated, where, and how to fix | -| **Mechanical architecture** | Bad patterns compound exponentially without enforcement | `check --no-boundary-violations` + `.codegraphrc.json` boundary rules | +| **Mechanical architecture** | Bad patterns compound exponentially without enforcement | `check --staged --boundaries` + `.codegraphrc.json` boundary rules | | **Silent success / loud failure** | Large output floods context, causes hallucinations | Compact default output; `--json` only when needed | | **Blast radius awareness** | Agent edits functions without knowing who depends on them | `fn-impact`, `diff-impact --staged`, `audit --quick` | | **Continuous garbage collection** | Technical debt accumulates between cleanup sprints | `triage`, `roles --role dead`, `check`, `cycles` on cadence | @@ -257,7 +259,7 @@ Building harness systems for AI agents revealed gaps where codegraph could provi | ID | Title | Description | Category | Benefit | Backlog candidate | |----|-------|-------------|----------|---------|-------------------| | — | **Harness health dashboard** | Single command showing the state of all harness layers: which rules are active, which are passing, what's unguarded. Like `codegraph stats` but for the harness itself | Orchestration | Agents and humans see at a glance which guardrails are in place and which areas are unprotected | `codegraph harness-status` | -| — | **Rule suggestion from failures** | When `check` fails, suggest a `.codegraphrc.json` rule that would have caught it earlier. "This blast radius of 67 would have been caught by `max-blast-radius: 50`" | Intelligence | Accelerates the harness growth loop — every failure produces a concrete rule suggestion | Enhancement to `check` output | +| — | **Rule suggestion from failures** | When `check` fails, suggest a `.codegraphrc.json` rule that would have caught it earlier. "This blast radius of 67 would have been caught by `check.blastRadius: 50`" | Intelligence | Accelerates the harness growth loop — every failure produces a concrete rule suggestion | Enhancement to `check` output | | — | **Remediation templates** | Configurable fix-suggestion templates attached to `check` rules. When boundary violation fires, the message includes a project-specific remediation: "Extract to `src/shared/` per our architecture guide" | Developer Experience | Makes error messages maximally actionable for agents in a specific codebase, not just generic advice | `manifesto.remediationTemplates` config | | — | **Duplicate code detection** | Identify semantically similar functions — near-duplicates that agents create when they can't find existing utilities | Analysis | Agents frequently reinvent existing functions. Catching duplicates in `check` prevents code bloat | `codegraph check --no-duplicates` or `codegraph duplicates` | | — | **Mutation tracking** | Detect functions that mutate their arguments or external state | Analysis | Agents produce side-effect-heavy code by default. Making mutations visible in `audit` helps both agents and reviewers | Enhancement to `dataflow` | @@ -280,10 +282,10 @@ Start with cycle detection — it catches the most common structural mistake: ```bash # Test it manually first -codegraph check --no-new-cycles -T +codegraph check --staged --cycles -T # Then add to pre-commit hook -echo 'codegraph build && codegraph check --staged --no-new-cycles -T' > .husky/pre-commit +echo 'codegraph build && codegraph check --staged --cycles -T' > .husky/pre-commit ``` ### 3. Add blast radius limits @@ -291,7 +293,7 @@ echo 'codegraph build && codegraph check --staged --no-new-cycles -T' > .husky/p Pick a threshold that matches your codebase. Start generous and tighten over time: ```bash -codegraph check --staged --max-blast-radius 100 -T +codegraph check --staged --blast-radius 100 -T ``` ### 4. Define architecture boundaries @@ -311,8 +313,8 @@ codegraph check --staged --max-blast-radius 100 -T Every time the agent makes a mistake, add a rule: -- Agent introduced a cycle? → `--no-new-cycles` (already there) -- Agent broke 50 callers? → `--max-blast-radius 30` +- Agent introduced a cycle? → `--cycles` (already there) +- Agent broke 50 callers? → `--blast-radius 30` - Agent imported db from ui? → Add a boundary rule - Agent exceeded complexity? → Set `manifesto.rules.cognitive.fail: 15` diff --git a/docs/use-cases/titan-paradigm.md b/docs/use-cases/titan-paradigm.md index 05e2dc95a..07c1968f4 100644 --- a/docs/use-cases/titan-paradigm.md +++ b/docs/use-cases/titan-paradigm.md @@ -162,13 +162,13 @@ The State Machine phase needs yes/no answers: "Did this change introduce a cycle ```bash # Exit code 0 = pass, 1 = fail — perfect for CI gates and rollback triggers -codegraph check --staged --no-new-cycles --max-blast-radius 20 --max-complexity 30 +codegraph check --staged --cycles --blast-radius 20 # Also enforce architecture boundary rules -codegraph check --staged --no-boundary-violations +codegraph check --staged --boundaries # Or combine all predicates in one call -codegraph check --staged --no-new-cycles --max-blast-radius 20 --no-boundary-violations -T +codegraph check --staged --cycles --blast-radius 20 --boundaries -T ``` For detailed impact analysis, `diff-impact` provides the full picture: @@ -242,7 +242,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 `check` 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` (manifesto mode) and enforceable against staged changes via `check --staged --boundaries`. 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 | @@ -251,7 +251,7 @@ Several planned features would make codegraph even more powerful for the Titan P | Feature | Status | How it helps | |---------|--------|-------------| -| **Change validation predicates** ([Backlog #30](../../roadmap/BACKLOG.md)) | **Done** | `codegraph check --staged --no-new-cycles --max-blast-radius N --no-boundary-violations` with exit code 0/1. The STATE MACHINE gets first-class pass/fail signals without parsing JSON. PR #225 + #230 | +| **Change validation predicates** ([Backlog #30](../../roadmap/BACKLOG.md)) | **Done** | `codegraph check --staged --cycles --blast-radius N --boundaries` with exit code 0/1. The STATE MACHINE gets first-class pass/fail signals without parsing JSON. PR #225 + #230 | | **Graph snapshots** ([Backlog #31](../../roadmap/BACKLOG.md)) | **Done** | `codegraph snapshot save/restore` for instant DB backup and rollback. Orchestrators checkpoint before each refactoring pass and restore on failure without rebuilding. PR #192 | | **Branch structural diff** ([Backlog #16](../../roadmap/BACKLOG.md)) | **Done** | `codegraph branch-compare main feature-branch` compares code structure between two refs — added/removed/changed symbols with transitive caller impact. PR in v2.5.1 | | **Streaming / chunked results** ([Backlog #20](../../roadmap/BACKLOG.md)) | **Done** | Universal pagination on all 30 MCP tools, NDJSON streaming on CLI commands, generator APIs for memory-efficient iteration. PR #207 | diff --git a/tests/unit/docs-check-flags.test.ts b/tests/unit/docs-check-flags.test.ts index 94590ab85..0ef1963ab 100644 --- a/tests/unit/docs-check-flags.test.ts +++ b/tests/unit/docs-check-flags.test.ts @@ -1,21 +1,62 @@ /** - * Regression test for issue #1842: docs/guides/recommended-practices.md - * referenced `codegraph check` predicate flags (`--no-new-cycles`, - * `--max-blast-radius`, `--no-boundary-violations`) that were renamed to + * Regression test for issue #1842 (recommended-practices.md) and #1984 + * (README.md and several docs/ guides): these referenced `codegraph check` + * predicate flags (`--no-new-cycles`, `--max-blast-radius`, + * `--no-boundary-violations`, and the fully fabricated `--max-complexity`, + * which never existed as a check predicate at all) that were renamed to * `--cycles`, `--blast-radius`, `--boundaries` (plus `--signatures`, which * was never documented at all) and never updated. * - * Rather than pin the doc to today's flag names, this derives the valid + * Rather than pin each doc to today's flag names, this derives the valid * flag set from `command.options` in src/cli/commands/check.ts — the single - * source of truth — so a future rename that isn't reflected in the doc - * fails here instead of silently drifting again. + * source of truth — so a future rename that isn't reflected in a doc fails + * here instead of silently drifting again. */ import { readFileSync } from 'node:fs'; import path from 'node:path'; import { describe, expect, it } from 'vitest'; import { command as checkCommand } from '../../src/cli/commands/check.js'; -const DOC_PATH = path.join(__dirname, '../../docs/guides/recommended-practices.md'); +const REPO_ROOT = path.join(__dirname, '../..'); + +/** Every doc that references `codegraph check` predicate flags, checked for known-stale names. */ +const ALL_DOC_PATHS = [ + 'docs/guides/recommended-practices.md', + 'README.md', + 'docs/contributing/harness-engineering.md', + 'docs/use-cases/harness-engineering.md', + 'docs/use-cases/titan-paradigm.md', + 'docs/guides/ai-agent-guide.md', + 'docs/examples/CLI.md', + 'docs/examples/MCP.md', +].map((p) => path.join(REPO_ROOT, p)); + +/** + * Docs whose only `codegraph check`-flag content is real, current examples — + * safe for the stricter "every flag used must currently exist" check. + * + * Excluded: `docs/use-cases/harness-engineering.md`, `docs/use-cases/titan-paradigm.md`, + * and `docs/guides/ai-agent-guide.md` legitimately illustrate *proposed*, + * not-yet-built predicates (e.g. `--floating-promises`, `--no-duplicates`) in + * feature-wishlist tables, and reference other commands' own "Key flags" + * rows — a strict scan of those would false-positive on intentional, + * clearly-labeled hypothetical/unrelated syntax. `docs/examples/MCP.md`'s + * check examples are MCP tool JSON (snake_case `arguments` fields), not + * `--flag`-shaped CLI tokens, so the CLI flag extractor doesn't apply. + */ +const STRICT_DOC_PATHS = [ + 'docs/guides/recommended-practices.md', + 'README.md', + 'docs/contributing/harness-engineering.md', + 'docs/examples/CLI.md', +].map((p) => path.join(REPO_ROOT, p)); + +const STALE_FLAGS = [ + '--no-new-cycles', + '--max-blast-radius', + '--no-boundary-violations', + '--max-complexity', +]; /** Extract long-form flag names (e.g. "--blast-radius") from a commander option tuple's flags string. */ function longFlagNames(flags: string): string[] { @@ -54,27 +95,30 @@ function flagsUsedInCheckExamples(doc: string): string[] { return flags; } -describe('docs/guides/recommended-practices.md check flag references (#1842)', () => { - const doc = readFileSync(DOC_PATH, 'utf-8'); +describe('codegraph check flag references in docs (#1842, #1984)', () => { const valid = validCheckFlags(); - it('does not reference known-stale codegraph check flag names', () => { - const stale = [ - '--no-new-cycles', - '--max-blast-radius', - '--no-boundary-violations', - '--max-complexity', - ]; - for (const flag of stale) { - expect(doc).not.toContain(flag); - } - }); + for (const docPath of ALL_DOC_PATHS) { + const relPath = path.relative(REPO_ROOT, docPath); + const doc = readFileSync(docPath, 'utf-8'); - it('only references check flags that exist on the check command', () => { - const used = flagsUsedInCheckExamples(doc); - expect(used.length).toBeGreaterThan(0); - for (const flag of used) { - expect(valid.has(flag)).toBe(true); - } - }); + it(`${relPath} does not reference known-stale codegraph check flag names`, () => { + for (const flag of STALE_FLAGS) { + expect(doc).not.toContain(flag); + } + }); + } + + for (const docPath of STRICT_DOC_PATHS) { + const relPath = path.relative(REPO_ROOT, docPath); + const doc = readFileSync(docPath, 'utf-8'); + + it(`${relPath} only references check flags that exist on the check command`, () => { + const used = flagsUsedInCheckExamples(doc); + expect(used.length).toBeGreaterThan(0); + for (const flag of used) { + expect(valid.has(flag)).toBe(true); + } + }); + } });