Stage 01
Scan
File discovery with noise filtering and security blocking. `.cartographerignore` respected. Sub-100 ms over a full repo.
Architecture mapping · Preview
Cartographer
Know what your codebase is, before you change it..
Architecture maps built from the AST up. Dependency graph, bridge detection, layer enforcement, hotspots, co-change coupling. Rust core with a Python harness, MCP server, C FFI into CKB. One hundred and sixty-one open action points — preview status, preview-access only.
Status
Preview
Open action points
161
Languages (Tier 1)
10+
Tree-sitter tier
5
MCP tools
28
FFI functions
19
Live in preview
- — Dependency graph, bridge detection, cycle detection
- — Layer enforcement via `layers.toml`, CI gate
- — Git churn, co-change, hotspot scoring, semidiff
- — Mermaid / DOT / ASCII / HTML diagrams
- — MCP server (JSON-RPC 2.0 stdio, 28 tools)
- — C FFI into CKB (libcartographer.a)
- — Function-level call graphs for Rust & Python
On the roadmap — not yet
- — Public binary release (Homebrew / PyPI / crates.io)
- — Hosted control plane & update channel
- — Browser-side graph explorer beyond the single-file HTML
- — Tier-2 tree-sitter coverage for Java, C#, Ruby
- — First-class VS Code extension (currently MCP only)
- — Auto-fix hints beyond layer-violation reporting
Metis says: the list on the right is honest, not aspirational. Anything on it is unshipped today.
From AST to architecture
Parse, graph, coupling, exports.
Cartographer is not a compiler. It is a structural intelligence engine: fast, approximate, honest about its tier. Four stages, each with a named module in the Rust core, each replaceable without disturbing its neighbours.
Stage 02
Extract
Two-tier skeletons: regex for ten-plus languages (Tier 1, confidence 30), tree-sitter for Rust / Go / Python / TS / JS (Tier 2, confidence 60). Signatures only, no bodies.
Stage 03
Graph
Import resolution into petgraph edges. Tarjan SCC for cycles. Brandes centrality for bridges. Role classification: entry / core / utility / leaf / dead / bridge / standard.
Stage 04
Enrich
Git churn per file, co-change pairs for temporal coupling, hotspot scores. Bot and formatting-commit filtering so noise does not inflate the signal.
Cycles
Tarjan SCC
Bridges
Brandes centrality
Ranking
Personalized PageRank
Coupling
Git co-change
What you get out
The graph is data. Pipe it somewhere useful.
Cartographer ships graph-style data. Every export is documented, every seam is an integration point for code-review, auto-fix, or refactor pipelines. Pick the format, pick the seam.
project_graph.json
Nodes (files + public signatures), edges (imports), metadata (language, complexity, role, bridgeness). The canonical machine-readable output.
Mermaid · Graphviz DOT
`cartographer diagram --format mermaid` or `--format dot`. Focus node, depth cap, colour-by-owner, violation overlays.
ASCII tree · HTML explorer
`--format ascii` for terminal review. Writing to `.html` emits a self-contained single-file explorer — vanilla JS, no CDN, no build step.
SCIP index
`index.scip` emitted for compiler-adjacent tools. Compatible with the SCIP ecosystem for symbol lookup and cross-reference handoff to CKB.
MCP server (stdio)
`cartographer serve` speaks JSON-RPC 2.0 over stdio. Twenty-eight tools exposed; any MCP-aware assistant can query the graph live.
CKB handoff
C FFI (`libcartographer.a`, nineteen `#[no_mangle]` functions). CKB uses Cartographer to pre-filter blast radius before deep SCIP traversal.
CI gate
`cartographer check` exits non-zero on cycles or `layers.toml` violations. Drop-in for GitHub Actions, GitLab CI, any pipeline that reads exit codes.
Context injection
`cartographer context --focus <FILE> --budget 8000` — personalized PageRank pruned to a token budget. Ninety-plus-percent compression vs. full source.
Cartographer in thirty seconds
Map, check, simulate, hand off to CKB.
The CLI is `cartographer`. The Python harness (`compressor.py`) wraps it for context-injection pipelines. Commands below are the README's canonical set — copy-paste verbatim.
# Build the core (preview: no binary release yet) cd mapper-core/cargo && cargo build --release # Generate the architectural map cartographer map # Health score: cycles, bridges, god modules, layer violations cartographer health # Predict the blast radius of a change BEFORE you write it cartographer simulate \ --module src/auth/user.rs \ --new-signature "fn login(u: User)" # CI gate — exits non-zero on cycles or layer violations cartographer check # Ranked skeleton pruned to a token budget (personalized PageRank) cartographer context --focus src/api/mod.rs --budget 8000 # Diagram: mermaid / dot / ascii / html cartographer diagram --format mermaid > graph.mmd cartographer diagram --format html > graph.html # MCP server (JSON-RPC 2.0 over stdio — 28 tools) cartographer serve
Aristaeus says: read the graph before you touch the code. Half of "unexpected regressions" are expected coupling the author never saw.
Coupling is a security surface
Bridges, backdoors, and who imports whom.
Nemesis's cut: architecture is a security artefact. A utility module that everybody imports is a secrets-leak candidate, a privilege-escalation vector, and a blast-radius amplifier. Cartographer flags the structural shape; a human still makes the call.
Bridge audit
Bridgeness centrality pinpoints the files that connect disparate subsystems. Review those first for authZ boundaries and secret access.
Layer violation trails
`layers.toml` violations surface BackCalls (db → ui) and SkipCalls (ui → db without the business layer). Good architectural hygiene; also a standing audit log.
Unreferenced public exports
`cartographer symbols --unreferenced` lists public surface nothing inside the repo calls — candidates for attack-surface reduction or quiet deprecation.
What this is not
The adversary’s disclosure. Read before you install.
Ipcha Mistabra wrote this section. Cartographer is preview — genuinely preview. These are the seams and fragile edges you should know about before you build anything on top of it.
Disclosure
Extraction is approximate, by design.
Tier-1 regex runs at thirty milliseconds across a whole repo; it is not a compiler. Expect mis-extractions on unusual macro expansions, generated code, or deeply nested template metaprogramming. Tier-2 tree-sitter covers five languages for higher fidelity.
Disclosure
No public binary release yet.
Preview status means build-from-source via `cargo build --release` in `mapper-core/cargo`. No Homebrew tap, no PyPI wheel, no pre-built binaries. Preview access is gated while the ingress story and update channel stabilise.
Disclosure
Bridge detection will flag false positives.
Brandes centrality is noisy on small repos and on codebases with heavy re-export barrels. We filter utility hubs, but a senior engineer still has to read the list before acting. Cartographer points at suspects; it does not convict.
If any of those disclosures are dealbreakers for your use case — good. Better to learn it here than after you wired Cartographer into a merge gate.
How to get in
No public install yet. Request preview access.
Cartographer is not on Homebrew, PyPI, or crates.io yet. While the 161 open action points burn down and the ingress story stabilises, access is preview-only. One request, one reply, source access.
What preview access gets you
- — Read access to the private GitHub repo (`nyxCore-Systems/Cartographer`)
- — The Rust source, Python harness, MCP server, FFI headers
- — Direct Slack / email line to the Cartographer team for feedback
- — Early-mover influence on which roadmap items land first
Request preview access Ask a scoping question
Both buttons land on the main-site contact form — one inbox, one reply queue.
Before you wire it into a merge gate
Run `cartographer check` in advisory mode for a week. Calibrate the layer config, prune the bridge list, confirm the hotspot signal matches where your team actually feels pain. Only then turn on the non-zero exit code. A preview tool wired to block merges on day one is a self-inflicted wound; a preview tool observed for a week is a genuinely useful signal.
Metis says: measure it first, then let it block you.