carto-md 2.0.1 → 2.0.3

package/BENCHMARK_RESULTS.md

@@ -0,0 +1,34 @@
+# Carto V2 Benchmark Results
+
+Generated: 2026-05-28T17:58:28.019Z
+Platform: Node v20.20.1 · 8 CPUs · 8192.0 MB RAM · darwin arm64
+
+| Repo | Source Files | Indexed | First Run | Second Run | DB Size | Routes | Import Edges |
+|------|-------------|---------|-----------|------------|---------|--------|--------------|
+| prisma | 3303 | 3303 | 1.6s | 178ms | 2.2 MB | 10 | 3590 |
+| supabase | 6818 | 6746 | 4.9s | 725ms | 4.3 MB | 90 | 5754 |
+| vscode | 10565 | 10565 | 9.7s | 1.2s | 10.6 MB | 11 | 19769 |
+| zed | 1837 | 1837 | 2.7s | 83ms | 4.7 MB | 12 | 2176 |
+
+## Domains Detected
+
+**prisma:** DATABASE(1044) · CORE(752) · EVENTS(36) · AUTH(8)
+**supabase:** CORE(4243) · AUTH(412) · DATABASE(387) · PAYMENTS(51) · EVENTS(17) · NOTIFICATIONS(12) · TRPC(3)
+**vscode:** CORE(5330) · AUTH(850) · EVENTS(446) · DATABASE(419) · NOTIFICATIONS(5)
+**zed:** CORE(1424) · DATABASE(110) · AUTH(75) · EVENTS(55) · PAYMENTS(53) · NOTIFICATIONS(10) · TRPC(2)
+
+## MCP Query Latency
+
+| Repo | get_structure | get_routes | get_domains_list |
+|------|--------------|------------|-----------------|
+| prisma | 0ms | 0ms | 1ms |
+| supabase | 1ms | 0ms | 3ms |
+| vscode | 1ms | 0ms | 3ms |
+| zed | 0ms | 0ms | 1ms |
+
+## Target Assessment
+
+- **prisma**: ✅ All targets met
+- **supabase**: ✅ All targets met
+- **vscode**: ✅ All targets met
+- **zed**: ✅ All targets met

package/CONTRIBUTING.md

@@ -215,13 +215,39 @@ cd carto
 npm install
 node src/cli/index.js init   # test in any project
 node src/cli/index.js serve  # test MCP server
-npm test                     # run test suite (30 tests)
+npm test                     # run test suite (35 tests)
 node test/correctness.js     # run correctness tests (31 tests)
 node test/benchmark.js       # run benchmarks against real repos
 ```
 
 ---
 
+## CI
+
+Every push and PR runs the test suite on a 3 OS × 3 Node matrix (macOS, Linux, Windows × Node 18, 20, 22) via `.github/workflows/test.yml`. A red cell blocks merge; one cell failing does not cancel the others, so you see the full picture.
+
+There are three workflows:
+
+| Workflow | Trigger | What it does |
+|----------|---------|-------------|
+| `test.yml` | push to `main`, PRs to `main` | `npm ci` + `npm test` on 9 cells |
+| `bench.yml` | Sundays 04:00 UTC + manual | Self-bench (`test/bench-ci.js`) on `ubuntu-22.04`, compared against `test/bench-baseline.json` |
+| `release-smoke.yml` | tags `v*`, PRs touching `package.json` / `package-lock.json` / `.npmignore` | `npm pack` + install tarball into a fresh dir + `carto --help` smoke on 3 OS × 2 Node |
+
+**Local equivalents** before pushing:
+
+```bash
+npm test                     # main suite (matches what test.yml runs)
+npm run test:correctness     # correctness suite — needs tmp-bench/<name> clones, NOT run in CI
+npm run test:bench-ci        # self-bench (matches what bench.yml runs)
+```
+
+**If a cell goes red:** click the failing job's "Details" link in the PR check section. Test failures show test names; install failures usually mean `package-lock.json` drifted from `package.json` — re-run `npm install` locally and commit the lockfile change.
+
+**If `bench.yml` reports a regression:** the failure includes which metric exceeded its tolerance and by how much. The artifact `bench-output-<run-id>` keeps the raw output for 90 days. If the regression is intentional (e.g., you traded perf for correctness), update the baseline value in `test/bench-baseline.json` in the same PR and link the bench run id in the PR description.
+
+---
+
 ## PR checklist
 
 - [ ] Tested on at least 2-3 real open-source projects
@@ -232,7 +258,7 @@ node test/benchmark.js       # run benchmarks against real repos
 - [ ] Extension added to `CODE_EXTS` and `detectLanguage()` in `sync-v2.js`
 - [ ] No changes to merger logic (unless explicitly fixing a merger bug)
 - [ ] No network calls added
-- [ ] `npm test` passes (30/30)
+- [ ] `npm test` passes (35/35)
 - [ ] `node test/correctness.js` passes (31/31)
 
 ---

package/README.md

@@ -1,5 +1,6 @@
 # carto
 
+[![CI](https://github.com/theanshsonkar/carto/actions/workflows/test.yml/badge.svg)](https://github.com/theanshsonkar/carto/actions/workflows/test.yml)
 [![npm version](https://img.shields.io/npm/v/carto-md)](https://www.npmjs.com/package/carto-md)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 [![npm downloads](https://img.shields.io/npm/dm/carto-md)](https://www.npmjs.com/package/carto-md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carto-md",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Structural intelligence layer for AI coding tools. Indexes your codebase into SQLite — routes, models, import graph, blast radius, domains — and exposes 16 MCP tools for Kiro, Cursor, and Claude.",
   "bin": {
     "carto": "src/cli/index.js"
@@ -9,7 +9,8 @@
   "scripts": {
     "test": "node test/test.js",
     "test:correctness": "node test/correctness.js",
-    "test:benchmark": "node test/benchmark.js"
+    "test:benchmark": "node test/benchmark.js",
+    "test:bench-ci": "node test/bench-ci.js"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.22.1",

package/src/agents/formatter.js

@@ -16,6 +16,9 @@ function formatSections({ routes, models, frontend, structure, warnings, fileMap
       sections.push(`- ${icon} ${entry.name}${suffix}`);
     }
   } else {
+    if (process.env.CARTO_DEBUG) {
+      console.warn('[CARTO] Warning: structure data was empty when formatting AGENTS.md');
+    }
     sections.push('_No structure data available._');
   }
 

package/src/agents/scan-structure.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * IGNORE_DIRS — names skipped at the top level when listing project structure.
+ *
+ * This is intentionally a *small* set tuned for the "Project Structure (auto)"
+ * block in AGENTS.md. It is NOT the same as the recursive file-discovery
+ * ignore lists (e.g. JS_IGNORE / PYTHON_IGNORE in src/detector/files.js or
+ * IGNORE_DIRS in src/store/sync-v2.js) — those filter what gets indexed.
+ *
+ * Top-level structure should still surface things like `dist/`, `build/`,
+ * `coverage/` (so users see what their project actually contains), but it
+ * should hide noise (`node_modules`, `.git`, `.carto`, etc.) and the file
+ * the structure block is about to be merged into (`AGENTS.md`).
+ *
+ * Anchored on the original V1 set in src/sync.js so existing AGENTS.md
+ * outputs do not drift after the V1 → V2 cleanup.
+ */
+const IGNORE_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '__pycache__',
+  '.venv',
+  'venv',
+  '.idea',
+  '.vscode',
+  '.carto',
+  'AGENTS.md'
+]);
+
+/**
+ * scanStructure(basePath) → Array<{ name: string, type: 'dir' | 'file' }>
+ *
+ * Lists the immediate children of `basePath` (one level deep, no recursion).
+ * Filters out IGNORE_DIRS. Sorts: directories before files; alphabetical
+ * within each group.
+ *
+ * Symlinks are reported by Dirent as neither dir nor file → treated as 'file'.
+ * Failures (missing dir, EACCES, etc.) return an empty array silently — the
+ * formatter handles the empty case.
+ */
+async function scanStructure(basePath) {
+  const entries = [];
+  let items;
+  try {
+    items = await fs.promises.readdir(basePath, { withFileTypes: true });
+  } catch {
+    return entries;
+  }
+
+  for (const item of items) {
+    if (IGNORE_DIRS.has(item.name)) continue;
+    entries.push({
+      name: item.name,
+      type: item.isDirectory() ? 'dir' : 'file'
+    });
+  }
+
+  entries.sort((a, b) => {
+    if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+
+  return entries;
+}
+
+module.exports = { scanStructure, IGNORE_DIRS };