Skip to content

Roadmap

Jump to bottom
Stas edited this page Mar 15, 2026 · 1 revision

Roadmap

Cartograph is organized around a layered world model. v0.1.0 ships Layers 1 and 2. Layers 3 and 4 are planned.

Current: Layers 1 & 2

Layer 1 — Structure (shipped)

Static dependency graph from source parsing.

  • Rust parser (tree-sitter-rust): mod declarations, use imports
  • Directed graph: Imports and DependsOn edges
  • SQLite + petgraph store
  • Blast radius traversal (BFS to configurable depth)
  • Dependency query (upstream/downstream, one hop)
  • Hotspots ranking

Layer 2 — Dynamics (shipped)

Behavioral patterns from git history.

  • Git history mining via git log --name-status (up to 10,000 commits)
  • Co-change frequency analysis with normalized confidence
  • Blame-based ownership attribution
  • CoChangesWith and OwnedBy edges

Planned

Language parsers

The parser layer is designed for multiple languages. After Rust, planned in rough priority order:

  • TypeScript / JavaScript — import and require relationships
  • Python — import and from ... import relationships
  • Go — import paths

Each new parser registers entities and edges in the same store schema — cross-language dependency edges are possible once multiple parsers run on the same repo.

Layer 1 depth — finer-grained structure

Currently tracks file and module relationships. Planned finer-grained entities:

  • Functions, structs, traits, impl blocks (Rust)
  • Calls edges (function → function)
  • Implements edges (type → trait)
  • Test file detection and Test entity kind

Layer 3 — Institutional knowledge

Context that lives in text, not code.

  • Commit message indexing — mine commit messages for architectural decisions, incident references, and change rationale; store as DecidedBecause edges
  • PR description indexing — extract intent and context from PR bodies
  • Design document linking — associate ADRs and design docs with the code entities they describe; DocumentedIn edges
  • Incident / revert correlation — detect reverts and post-incident commits; store as RevertedBecause and BrokeAfter edges

Use cases: "Why was this module structured this way?" "What decision led to this dependency?"

Layer 4 — Change simulator

Predict the probable impact of a proposed change before it is made.

  • Impact scoring — given a set of files to change, predict blast radius weighted by historical co-change confidence and ownership
  • Risk heatmap — surface files with high connectivity + active co-change patterns as higher-risk targets
  • Reviewer suggestion — based on ownership and co-change data, suggest reviewers for a proposed diff
  • Pre-commit hook integration — run impact analysis automatically before git commit

Use cases: "If I refactor src/store/graph.rs, what is the predicted impact and who should review?"

MCP + agent integration improvements

  • Streaming results — for large blast radius traversals
  • Batch queries — query multiple entities in one call
  • Change-set input — accept a list of files (e.g. from a diff) and return aggregate impact
  • doctor command — validate that the database is current and the git history was fully mined

Out of scope (intentionally)

  • UI / TUI — Cartograph is a headless tool; visualization is a consumer's concern
  • Cloud sync — the database stays local in the indexed repo
  • LLM summarization — raw graph and text data only; interpretation is left to the calling agent or human

Clone this wiki locally