carto-md 2.0.8 → 2.1.0

package/docs/anci/v0.1-DRAFT.md

@@ -0,0 +1,420 @@
+# ANCI v0.1 DRAFT — Architecturally Normalized Code Index
+
+> **Status:** DRAFT (unstable). Do not depend on this format in production
+> consumers without pinning to a specific carto-md version. The wire
+> format may change in any direction up to v1.0.
+>
+> **Spec:** v0.1.0-DRAFT
+> **Reference implementation:** carto-md ≥ 2.0.9
+> **Editor:** [@theanshsonkar](https://github.com/theanshsonkar)
+> **License:** MIT (the spec itself)
+> **Repository:** https://github.com/theanshsonkar/carto
+
+---
+
+## 1. Motivation
+
+Every AI coding tool today re-discovers a codebase's architecture from
+scratch on every session. Cursor builds its own embedding index. Cline
+builds its own. Continue builds its own. The work duplicates across
+tools and is lost across sessions.
+
+ANCI fills the hole. It is a **static file format** — two files,
+`anci.yaml` and `anci.bin`, sitting at a known location in a repository
+— that describes that codebase's architecture in a form any AI tool can
+read without indexing it itself.
+
+ANCI is to codebases what OpenAPI is to REST APIs: a standardized way for
+something to describe itself to consumers it doesn't know about.
+
+## 2. Goals & non-goals
+
+### Goals
+
+* **Tool-neutral.** No assumption about which AI tool consumes ANCI.
+* **Local-first.** ANCI files live next to the code, in `.carto/` by
+  convention. Never sent over a network unless the user chooses to.
+* **Hybrid representation.** Human-readable header for grep / inspection;
+  binary body for fast queries on million-file repos.
+* **Bounded size.** Target ≤ 20 MB total for a 100K-file repo.
+* **Lossless round-trip.** Producer → file → consumer reproduces the
+  exact graph, domains, and metadata.
+* **Forward-compatible.** New optional sections may be added in v0.x
+  releases. Consumers ignore unknown sections.
+
+### Non-goals
+
+* **Not a query language.** Consumers traverse the data structures with
+  their own code. ANCI is just the data.
+* **Not a network protocol.** No RPC. No streaming. Static files only.
+* **Not a replacement for source code.** ANCI describes structure
+  (graph, domains, routes), not source.
+* **Not yet stable.** v0.1 DRAFT may break in v0.2, v0.3, etc. Stability
+  begins at v1.0.
+
+## 3. File layout
+
+A repository that ships ANCI places two files in `.carto/`:
+
+```
+.carto/
+├── anci.yaml    # Header. UTF-8 YAML. Required. Human-readable.
+├── anci.bin     # Body.   Binary.    Required. Machine-readable.
+```
+
+Producers write both. Consumers read either independently:
+
+* If a consumer only needs domain names and route counts, parse
+  `anci.yaml` and ignore the body.
+* If a consumer needs blast radius or graph traversal, parse the body.
+
+The header MUST point to the body's filename and byte length. If they
+disagree, the body is authoritative for graph data and the header is
+authoritative for human metadata.
+
+## 4. Header format (`anci.yaml`)
+
+UTF-8, YAML 1.2, **strict subset**:
+
+* 2-space indentation
+* `key: value` pairs only (no flow style `{}`/`[]`)
+* All string values double-quoted (no implicit typing)
+* Lists use `- ` prefix
+* No multi-line strings, no anchors, no aliases, no tags
+
+A v0.1.0-DRAFT producer MUST emit a header that conforms to this
+schema. A consumer MAY accept other YAML inputs but reference
+implementations only emit/parse the strict subset.
+
+### 4.1 Schema
+
+```yaml
+anci:
+  version: "0.1.0-DRAFT"            # required, string
+  generator: "carto-md@2.0.9"       # required, string
+  generated_at: "2026-06-07T..."    # required, ISO-8601 UTC
+  body:
+    file: "anci.bin"                # required, relative to header
+    bytes: 12345                    # required, body length on disk
+
+project:
+  total_files: 7567                 # required
+  total_routes: 86                  # required
+  total_models: 12                  # required
+  total_import_edges: 13420         # required
+
+domains:                            # required, possibly empty
+  - name: "AUTH"
+    file_count: 42
+    route_count: 7
+    model_count: 1
+
+high_impact:                        # optional, top N by transitive dep count
+  - file: "src/auth/session.ts"
+    transitive_dependents: 47
+
+routes:                             # optional
+  - method: "POST"
+    path: "/auth/login"
+    file: "src/auth/login.ts"
+    framework: "express"
+    handler: "login"
+
+models:                             # optional
+  - name: "User"
+    kind: "prisma"
+    file: "prisma/schema.prisma"
+```
+
+Field names are stable for the v0.x line. Adding new optional fields is
+not a breaking change. Removing or renaming a field IS breaking and
+requires a version bump.
+
+### 4.2 Versioning
+
+| Field           | Meaning                                                   |
+|-----------------|-----------------------------------------------------------|
+| `anci.version`  | Spec version. v0.x is unstable. v1.0+ follows semver.     |
+| `anci.generator`| Producer identity. Free-form string, conventionally `name@version`. |
+
+Consumers MUST refuse to parse a header whose `anci.version` is not in
+their compatibility set. Reference consumer behavior (carto-md):
+
+* Accepts: `0.1.x-DRAFT`
+* Rejects: anything else
+
+## 5. Body format (`anci.bin`)
+
+Binary, little-endian, length-prefixed sections. Designed so a single
+streaming pass can fully reconstruct all bitmaps, paths, and domain
+mappings.
+
+### 5.1 Header
+
+| Offset | Size  | Field        | Value                                         |
+|-------:|------:|--------------|-----------------------------------------------|
+|      0 |  4 B  | magic        | `0x49434E41` (`'A','N','C','I'` little-endian)|
+|      4 |  1 B  | version      | `0x01`                                        |
+|      5 |  3 B  | reserved     | zero                                          |
+|      8 |  4 B  | size_bits    | u32 — bit dimension of every bitmap (= max file id + 1) |
+
+Total fixed-header length: **12 bytes.**
+
+### 5.2 Sections
+
+After the fixed header, sections appear **in this order**. Each section
+begins with a u32 count.
+
+#### 5.2.1 `forward` — file → its imports
+
+```
+count_u32
+count × {
+  from_file_id_u32
+  words_len_u32
+  words_u32 × words_len      // raw Uint32Array bytes, LE
+}
+```
+
+Bit `j` of the bitmap of `from_file_id` is 1 iff the file with id
+`from_file_id` directly imports the file with id `j`.
+
+#### 5.2.2 `reverse` — file → its direct dependents
+
+Same record shape as `forward`. Bit `j` set iff file `to_file_id` is
+directly imported by file `j`.
+
+#### 5.2.3 `popcount` — pre-computed transitive dependent counts
+
+```
+count_u32
+count × {
+  file_id_u32
+  count_u32       // # of distinct dependents reachable in ≤ 5 hops
+}
+```
+
+Sorted DESC by count. Lets `getHighImpactFiles(n)` answer in O(1).
+Producers MUST clamp BFS to 5 hops to match the carto-md reference.
+
+#### 5.2.4 `paths` — file id → path string
+
+```
+count_u32
+count × {
+  file_id_u32
+  path_len_u32
+  path_bytes (UTF-8, no NUL terminator)
+}
+```
+
+Paths are project-relative POSIX paths (forward slashes, no leading `./`).
+
+#### 5.2.5 `file_domain` — file id → domain id
+
+```
+count_u32
+count × {
+  file_id_u32
+  domain_id_u32
+}
+```
+
+Files absent from this section have no domain assignment. A file MAY
+have at most one domain.
+
+#### 5.2.6 `domain_names` — domain id → human name
+
+```
+count_u32
+count × {
+  domain_id_u32
+  name_len_u32
+  name_bytes (UTF-8)
+}
+```
+
+Domain names are uppercase by convention (`AUTH`, `PAYMENTS`,
+`DATABASE`) but the spec does not constrain their contents.
+
+### 5.3 Total layout (concrete byte map)
+
+```
+[ 12 B fixed header ]
+[ forward section     ]
+[ reverse section     ]
+[ popcount section    ]
+[ paths section       ]
+[ file_domain section ]
+[ domain_names section]
+EOF
+```
+
+A consumer that knows the spec version can stream-parse top to bottom.
+There is no out-of-line index — the format is designed for one
+sequential read.
+
+## 6. Generation algorithm (reference)
+
+Producers SHOULD compute the body as follows:
+
+1. Assign each file a stable, dense integer id.
+2. For each file, build a bitmap of its forward imports (resolved
+   imports only; unresolved imports are excluded).
+3. Reverse the forward bitmaps into `reverse`.
+4. For each file with ≥ 1 dependent, run a 5-hop BFS over `reverse`
+   using the same self-loop guard as `bitmap/sidecar.js`:
+   a. Seed `visited` with direct dependents.
+   b. Expand frontier by one hop, mask `visited`, add result to
+      `visited`. Repeat to depth 5 or until frontier is empty.
+   c. Clear the seed bit (cycles must not count the file itself).
+   d. Record `popcount(visited)` if > 0.
+5. Sort `popcount` records DESC.
+6. Write sections in the order specified in §5.2.
+
+The carto-md reference implementation lives in `src/anci/serialize.js`.
+
+## 7. Consumer responsibilities
+
+A consumer MUST:
+
+* Validate magic bytes and version before reading any section.
+* Refuse to parse if `size_bits` differs from the bitmap dimension
+  derived from any section's `words_len`.
+* Treat unknown sections (in future v0.x releases) as opaque and skip
+  them. The reference implementation enforces strict order today, but
+  consumers SHOULD be permissive on order to ease forward compatibility.
+
+A consumer SHOULD:
+
+* Cache the parsed body in memory rather than re-parsing on every
+  query. The format is designed for fast load, not fast random seek.
+* Cross-validate the header's `body.bytes` against the actual file
+  size and warn (not fail) on mismatch.
+
+## 8. Versioning & deprecation policy
+
+### v0.1.0-DRAFT (this spec)
+
+* Format may change in any direction up to v1.0.
+* Consumers pin to specific producer versions.
+* Reference implementation is carto-md ≥ 2.0.9.
+* No backward compatibility guarantees.
+
+### Future v0.x (e.g. v0.2)
+
+* MAY add optional header fields.
+* MAY add optional body sections (appended after `domain_names`).
+* MUST NOT remove or rename existing fields.
+* MUST bump `anci.version` to a new minor.
+* Reference consumer accepts the latest v0.x and the version it shipped
+  against.
+
+### v1.0 stability
+
+When the format is judged ready (reference partner integrations exist,
+plus 6 months of v0.x stability), `anci.version` graduates to `1.0.0`
+and standard semver applies thereafter:
+
+* MAJOR: incompatible breaking change.
+* MINOR: backward-compatible addition.
+* PATCH: clarification only.
+
+A v1.x consumer MUST accept all v1.x bodies. v0.x compatibility at v1.0
+is not guaranteed — producers re-emit at the v1.0 schema.
+
+## 9. Security considerations
+
+ANCI is a passive description of code structure. It contains:
+
+* File paths (project-relative).
+* Domain names.
+* Route paths and HTTP methods.
+* Model names and kinds.
+* Import graph as integer bitmaps.
+
+ANCI does **not** contain source code, secrets, env values, or
+user-identifying information. Producers MUST NOT include source content
+in any field.
+
+A repository that publishes its `.carto/anci.{yaml,bin}` to a remote
+location is exposing its architecture. This is the same disclosure
+level as making the directory tree public. Producers SHOULD respect
+`.cartoignore` and SHOULD NOT include paths matching its patterns.
+
+## 10. Why YAML + binary (and not just YAML, or just binary)
+
+| Property               | YAML alone | Binary alone | Hybrid |
+|------------------------|:----------:|:------------:|:------:|
+| Human-readable         | ✅          | ❌            | ✅      |
+| Grep-able from CI      | ✅          | ❌            | ✅      |
+| Compact at 100K files  | ❌ (50–500 MB) | ✅       | ✅ (5–20 MB) |
+| Fast graph queries     | ❌          | ✅            | ✅      |
+| Easy partial parse     | ✅          | ⚠️           | ✅      |
+
+The split mirrors the structure of the data: metadata is small and
+varied (good for YAML); the graph is large and uniform (good for
+binary).
+
+## 11. Why these specific bitmap sections
+
+The body ships exactly the data needed to answer the four MCP tools
+that drive most AI-tool queries:
+
+* `getBlastRadius(file)` → walk `reverse` BFS-style.
+* `simulateChangeImpact(files)` → OR-aggregate `reverse` bitmaps.
+* `getHighImpactFiles(n)` → take first N from `popcount`.
+* `getDomainsList()` / domain membership → header + `file_domain` +
+  `domain_names`.
+
+Everything else (cross-domain detection, similarity, change-plan
+ranking) can be derived from these primitives. The format keeps the
+ship surface small.
+
+## 12. Compatibility with carto-md `bitmap.bin`
+
+ANCI v0.1 and carto-md's internal `bitmap.bin` (magic `0x54524243`
+"CBRT") share record-level encoding but are **distinct file formats
+with distinct magics**. Reasons:
+
+* `bitmap.bin` is private cache; `anci.bin` is public export.
+* `bitmap.bin` includes `crossForward` and `domainBitmaps` (internal
+  query optimizations); ANCI omits them. Consumers can re-derive both
+  in O(N) on load.
+* `bitmap.bin` may evolve at carto-md's pace; ANCI evolves only at
+  spec-revision pace.
+
+A consumer MUST NOT attempt to load `bitmap.bin` as ANCI or vice versa.
+
+## 13. Reference vs. interoperability tests
+
+The carto-md reference implementation includes a roundtrip test suite
+(`test/test.js` → `ANCI roundtrip`). Other implementations are
+encouraged to:
+
+* Run carto-md's reference suite against their own
+  serialize/deserialize code.
+* Publish their own conformance tests for the spec to consume.
+
+The DRAFT spec deliberately ships **without** an independent
+conformance harness. v1.0 will require one before formalization.
+
+## 14. Open questions (RFC-stage feedback welcome)
+
+* **Should the body be Roaring-compressed instead of dense
+  Uint32Array?** Roaring is smaller on sparse repos but adds a
+  dependency. v0.1 ships dense; v1.0 may add an opt-in compressed
+  encoding.
+* **Should env vars be in the header?** Currently no — they leak
+  configuration surface. Open question for partners.
+* **Should source language be part of `paths`?** Currently no — language
+  is derivable from extension. Open if consumers ask.
+* **Cross-repo references?** Out of scope for v0.1. Tier 3 work.
+
+## 15. Acknowledgements
+
+Inspired by OpenAPI's standardization play (2010-2015), Git's pack
+reachability bitmaps (2013), and Lucene's Roaring posting lists (2014).
+
+The spec is iterated alongside carto-md. File issues at
+https://github.com/theanshsonkar/carto for proposed changes.

package/docs/api/README.md

@@ -0,0 +1,99 @@
+# Carto MCP Tools — API Reference
+
+Auto-generated from `src/mcp/server.js`. Re-run `node scripts/gen-api-docs.js` after adding tools.
+
+**76 tools** across 8 categories.
+
+## Categories
+
+### Core graph (16)
+- [`get_routes`](./get_routes.md)
+- [`get_blast_radius`](./get_blast_radius.md)
+- [`get_structure`](./get_structure.md)
+- [`get_domain`](./get_domain.md)
+- [`get_neighbors`](./get_neighbors.md)
+- [`get_cross_domain`](./get_cross_domain.md)
+- [`get_context`](./get_context.md)
+- [`search_routes`](./search_routes.md)
+- [`get_models`](./get_models.md)
+- [`get_high_impact_files`](./get_high_impact_files.md)
+- [`get_env_vars`](./get_env_vars.md)
+- [`get_domains_list`](./get_domains_list.md)
+- [`get_file_summary`](./get_file_summary.md)
+- [`get_change_plan`](./get_change_plan.md)
+- [`get_similar_patterns`](./get_similar_patterns.md)
+- [`simulate_change_impact`](./simulate_change_impact.md)
+
+### Episodic Memory (5)
+- [`validate_diff`](./validate_diff.md)
+- [`get_recent_decisions`](./get_recent_decisions.md)
+- [`get_session_context`](./get_session_context.md)
+- [`did_we_discuss_this`](./did_we_discuss_this.md)
+- [`get_intervention_history`](./get_intervention_history.md)
+
+### Temporal (9)
+- [`get_architecture`](./get_architecture.md)
+- [`get_architectural_drift`](./get_architectural_drift.md)
+- [`get_domain_evolution`](./get_domain_evolution.md)
+- [`get_hotspot_files`](./get_hotspot_files.md)
+- [`get_complexity_trend`](./get_complexity_trend.md)
+- [`get_churn_vs_blast_radius`](./get_churn_vs_blast_radius.md)
+- [`get_arch_events`](./get_arch_events.md)
+- [`get_domain_health`](./get_domain_health.md)
+- [`get_temporal_context`](./get_temporal_context.md)
+
+### Brain (10)
+- [`get_invariants`](./get_invariants.md)
+- [`get_canonical_pattern`](./get_canonical_pattern.md)
+- [`get_conventions`](./get_conventions.md)
+- [`get_action_patterns`](./get_action_patterns.md)
+- [`scaffold_for_intent`](./scaffold_for_intent.md)
+- [`get_working_memory`](./get_working_memory.md)
+- [`get_pending_decisions`](./get_pending_decisions.md)
+- [`get_active_drift`](./get_active_drift.md)
+- [`get_active_suggestions`](./get_active_suggestions.md)
+- [`dismiss_suggestion`](./dismiss_suggestion.md)
+
+### AI-native (14)
+- [`get_minimal_context_for_intent`](./get_minimal_context_for_intent.md)
+- [`get_progressive_disclosure_tree`](./get_progressive_disclosure_tree.md)
+- [`get_token_budget_report`](./get_token_budget_report.md)
+- [`get_decision_log`](./get_decision_log.md)
+- [`get_evolution_delta`](./get_evolution_delta.md)
+- [`get_change_velocity`](./get_change_velocity.md)
+- [`get_test_coverage_map`](./get_test_coverage_map.md)
+- [`get_safety_checklist`](./get_safety_checklist.md)
+- [`get_data_flow`](./get_data_flow.md)
+- [`get_interface_contract`](./get_interface_contract.md)
+- [`explain_change_in_natural_language`](./explain_change_in_natural_language.md)
+- [`get_stale_docs`](./get_stale_docs.md)
+- [`get_dependency_surface`](./get_dependency_surface.md)
+- [`get_upgrade_risk`](./get_upgrade_risk.md)
+
+### Adjacent (8)
+- [`get_cross_language_call_graph`](./get_cross_language_call_graph.md)
+- [`get_iac_resources`](./get_iac_resources.md)
+- [`ingest_otlp_traces`](./ingest_otlp_traces.md)
+- [`get_risk_weighted_blast_radius`](./get_risk_weighted_blast_radius.md)
+- [`get_dead_code_with_confidence`](./get_dead_code_with_confidence.md)
+- [`get_hot_in_prod_no_tests`](./get_hot_in_prod_no_tests.md)
+- [`get_semantic_diff`](./get_semantic_diff.md)
+- [`get_llm_enrichment`](./get_llm_enrichment.md)
+
+### Predictive (7)
+- [`get_predictive_risk`](./get_predictive_risk.md)
+- [`get_microservice_cut_points`](./get_microservice_cut_points.md)
+- [`validate_change`](./validate_change.md)
+- [`get_file_ownership`](./get_file_ownership.md)
+- [`get_cross_team_coupling`](./get_cross_team_coupling.md)
+- [`get_drift_digest`](./get_drift_digest.md)
+- [`get_ai_cost_attribution`](./get_ai_cost_attribution.md)
+
+### Org-wide (7)
+- [`get_org_architecture`](./get_org_architecture.md)
+- [`get_service_dependency_graph`](./get_service_dependency_graph.md)
+- [`get_cross_repo_blast_radius`](./get_cross_repo_blast_radius.md)
+- [`find_consumers_of_api`](./find_consumers_of_api.md)
+- [`get_org_domain_mapping`](./get_org_domain_mapping.md)
+- [`get_service_boundary_violations`](./get_service_boundary_violations.md)
+- [`get_microservices_migration_cut_points`](./get_microservices_migration_cut_points.md)

package/docs/api/did_we_discuss_this.md

@@ -0,0 +1,34 @@
+# `did_we_discuss_this`
+
+Substring search over the episodic memory log (decisions + interventions) for prior discussions of a topic. Use to avoid re-deciding settled questions.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "topic": {
+      "type": "string",
+      "description": "Topic to search for, e.g. \"auth\", \"snake_case\", \"blast radius\"."
+    }
+  },
+  "required": [
+    "topic"
+  ]
+}
+```
+
+## Required arguments
+
+- `topic`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `topic` | string | Topic to search for, e.g. "auth", "snake_case", "blast radius". |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/dismiss_suggestion.md

@@ -0,0 +1,34 @@
+# `dismiss_suggestion`
+
+Mark a suggestion ID as dismissed for the current session. Acknowledgment-only; the underlying signal still exists.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Suggestion id from get_active_suggestions."
+    }
+  },
+  "required": [
+    "id"
+  ]
+}
+```
+
+## Required arguments
+
+- `id`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `id` | string | Suggestion id from get_active_suggestions. |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/explain_change_in_natural_language.md

@@ -0,0 +1,33 @@
+# `explain_change_in_natural_language`
+
+Given a unified diff, returns a plain-language summary + risk + violation list + suggestions. Powered by validate_diff.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "diff": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "diff"
+  ]
+}
+```
+
+## Required arguments
+
+- `diff`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `diff` | string |  |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/find_consumers_of_api.md

@@ -0,0 +1,34 @@
+# `find_consumers_of_api`
+
+Across all org repos, find every file importing a given npm/pypi/go/maven target.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "target": {
+      "type": "string",
+      "description": "Target package or module name"
+    }
+  },
+  "required": [
+    "target"
+  ]
+}
+```
+
+## Required arguments
+
+- `target`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `target` | string | Target package or module name |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_action_patterns.md

@@ -0,0 +1,32 @@
+# `get_action_patterns`
+
+Procedural patterns mined from git history: "when developers add X, they also touch Y". Filter by natural-language intent.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "intent": {
+      "type": "string",
+      "description": "Optional intent filter (e.g. \"add route\")."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `intent` | string | Optional intent filter (e.g. "add route"). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)