diff --git a/docs/roadmap/BACKLOG.md b/docs/roadmap/BACKLOG.md index 5b7a80e53..a8bf8d25e 100644 --- a/docs/roadmap/BACKLOG.md +++ b/docs/roadmap/BACKLOG.md @@ -158,6 +158,7 @@ Six commands already produce Mermaid/DOT output: `export`, `diff-impact -f merma | 69 | Node annotations in `diff-impact` / `branch-compare` / `communities` | Use 61's annotation formatter to show top exports on file nodes in `diff-impact -f mermaid`, `branch-compare --format mermaid`, and `communities` output. | Visualization | All visual tools show file API surfaces inline, not just in `export` | ✓ | ✓ | 3 | No | 61 | | 70 | Drift/risk subgraph labels in `communities` and `triage` | Use 62's semantic label system to annotate `communities` subgraphs with drift status (`**(drifted)**` / `**(cohesive)**`) and add a new `--format mermaid` to `triage` with risk-severity group labels. | Intelligence | Community and triage diagrams communicate structural health directly in the layout | ✓ | ✓ | 3 | No | 62 | | 84 | Call-count annotations on `sequence` diagram arrows | `sequence` currently deduplicates caller→callee pairs with `SELECT DISTINCT`, silently hiding multi-site calls. Instead, count how many times each caller→callee pair appears in the edges table and annotate the Mermaid arrow with the count when > 1 (e.g., `CallerFile ->> CalleeFile: fnName (×3)`). Requires grouping by `(source_id, target_id)` and emitting the count alongside the edge. | Visualization | Sequence diagrams reveal call intensity — a file calling another 8 times is architecturally different from one that calls it once; agents and reviewers can immediately spot hot paths and coupling strength | ✓ | ✓ | 3 | No | — | +| 103 | Recursively foldable graph viewer | Add directory-level collapsing to the interactive HTML viewer (`codegraph plot`). Any directory group collapses into a single node showing only its external edges (imports in/out); click to expand into constituent symbols. Recursive: collapsed groups contain collapsed sub-groups. Inspired by Weft's "recursively foldable" design — a 100-node system still looks like 5 blocks at the top level. Implementation: extend `graph-enrichment.ts` to compute directory-level aggregate edges, extend `viewer.ts` to support expand/collapse toggling on `subgraph` cluster nodes (vis-network supports compound nodes via `clustering`). Add `--collapsed` flag to start fully collapsed, `--expand-depth N` to control initial expansion level. | Visualization | Large codebase graphs are currently unusable — hundreds of nodes render as spaghetti. Directory-level collapsing makes `codegraph plot` viable for real projects by letting users zoom from architecture overview to file-level detail interactively. Directly improves the "orientation" problem — agents and humans see module boundaries at a glance | ✓ | ✓ | 4 | No | — | | 86 | Mermaid `classDiagram` export | New `codegraph export -f class-diagram` (and `exportClassDiagram` programmatic API) that emits a Mermaid `classDiagram` for classes, interfaces, structs, traits, and enums in the graph. **What we already have:** class/interface/struct/trait/enum nodes in the `nodes` table, method nodes with `parent_id` linking them to their class (migration v11), property/parameter/constant child nodes via `symbol_children`, `extends` and `implements` edges stored by `builder.js`. **What's needed:** **(a)** New rendering function in `export.js` that queries classes → groups their child methods and properties → emits Mermaid `classDiagram` syntax with `<>`/`<>` stereotypes, inheritance (`<\|--`) and implementation (`..\|>`) arrows; **(b)** visibility markers (`+`/`-`/`#`) — infer from JS `#private` fields (already detected as `private_property_identifier` in `extractClassProperties`) and language-specific access modifiers; **(c)** optional `--scope ` to restrict diagram to a class and its hierarchy (uses `getClassHierarchy` BFS); **(d)** dependency arrows (`..>`) derived from cross-class call edges. **Nice-to-have (not blocking):** type annotations on methods/fields (requires extractor changes to persist TS/Java type info). Add corresponding `class_diagram` MCP tool. | Visualization | Agents and PR reviewers get UML-style class hierarchy diagrams generated directly from the graph — useful for understanding inheritance structures, spotting god classes, and reviewing OOP designs without manual diagramming. Particularly valuable for Java, C#, TypeScript, and Rust codebases with deep type hierarchies | ✓ | ✓ | 3 | No | — | ### Tier 1h — Core accuracy improvements (resolve known analysis gaps) @@ -200,6 +201,7 @@ Items identified by the architectural audit (v3.1.4) that don't fit existing tie | 92 | Auto-generate MCP tool schemas from types | The `tool-registry.js` (801 LOC) contains hand-maintained JSON schemas for 40+ tools. With TypeScript (Phase 5), these can be derived from types via `zod` or `typebox`. Schema drift between the implementation and MCP schema is inevitable with hand-maintenance. | Embeddability | Eliminates an entire class of MCP bugs (schema says one thing, implementation does another). Reduces maintenance burden for adding new MCP tools | ✗ | ✓ | 3 | No | Phase 5 (TypeScript) | | 93 | ~~Shell completion for CLI~~ | ~~Commander supports shell completion but it's not implemented. `codegraph completion bash\|zsh\|fish` outputs the appropriate script. Basic UX gap for a CLI tool with 40+ commands.~~ | Developer Experience | ~~Tab completion makes the CLI discoverable — users find commands without reading docs. Reduces friction for new users and agents exploring available commands~~ | ✓ | ✓ | 2 | No | — | **PROMOTED** — Moved to ROADMAP Phase 7.11 | | 94 | VS Code extension | Replace the planned Web UI (removed from roadmap Phase 12) with a VS Code extension providing: webview-based graph visualization (reusing the existing `viewer.js` HTML), go-to-definition via graph edges, inline impact annotations on hover, integration with the MCP server for queries, and a sidebar panel for triage/audit results. VS Code is the right UI target for developer tools in 2026. | Visualization | Developers get graph intelligence directly in their editor — no context switching to a browser or terminal. Impact annotations on hover surface blast radius without running commands | ✗ | ✓ | 3 | No | — | +| 104 | Architecture-as-code validation gate | Elevate `codegraph check` + `manifesto` + `boundaries` into a unified "architecture-as-code" validation system. Define architectural invariants in `.codegraphrc.json` under a new `architecture{}` block: layer rules (existing `boundaries`), dependency direction rules ("domain must not import infrastructure"), module cohesion thresholds ("community drift score < 0.3"), fan-in caps per layer ("adapters must have fan-in < 5"), and cross-cutting constraints ("no file may import from more than 3 top-level directories"). `codegraph check --architecture` validates all rules in one pass, exit code 1 on any violation. Framing inspired by Weft's design principle "if it compiles, the architecture is sound" — the goal is that passing `codegraph check` in CI means the architecture is structurally valid, not just that individual metrics are below thresholds. Builds entirely on existing `boundaries`, `manifesto`, `communities`, and `check` infrastructure — the work is unification and config surface, not new analysis. | Architecture | Current architecture validation is scattered across three features (`boundaries`, `manifesto`, `check`) with separate configs and no unified mental model. A single `architecture{}` config block with a single `check --architecture` command makes it practical for teams to adopt architectural CI gates — the barrier today is config complexity, not capability. Directly prevents architectural decay by making violations as visible as test failures | ✓ | ✓ | 4 | No | — | | 95 | SARIF output for cycle detection | Add SARIF output format so cycle detection integrates with GitHub Code Scanning, showing issues inline in PRs. Currently planned for Phase 11 but could be delivered as early as Phase 7 since it's a pure output format addition. | CI | GitHub Code Scanning integration surfaces cycle violations directly in PR review — no separate CI step or comment bot needed | ✓ | ✓ | 3 | No | — | | 96 | Fix README runtime dependency count | README claims "Only 3 runtime dependencies" but there are 5 — it omits `graphology` and `graphology-communities-louvain` which are in `package.json` `dependencies` (not optional). Correct to 5. | Documentation | Accuracy — users and contributors should be able to trust the README | ✓ | ✓ | 1 | No | #545 | **SUPERSEDED** — PR #545 removes `graphology` and `graphology-communities-louvain`, making the README's "3 runtime dependencies" claim correct again. No further action needed once #545 merges. |