carto-md 2.0.4 → 2.0.6

package/CONTRIBUTING.md

@@ -44,9 +44,9 @@ Framework-specific route and model extraction lives inside the language plugins.
 
 ---
 
-## How to add a language (V2 pattern — tree-sitter based)
+## How to add a language (tree-sitter based)
 
-V2 uses tree-sitter for import and symbol extraction. Babel is only used for deep JS/TS route/model extraction on API handler files.
+Carto uses tree-sitter for import and symbol extraction. Babel is only used for deep JS/TS route/model extraction on API handler files.
 
 ### Step 1: Install the grammar
 
@@ -177,7 +177,7 @@ Test on at least 2 real open-source projects using the framework.
 
 ---
 
-## How domain clustering works (V2)
+## How domain clustering works
 
 Domain detection uses **Leiden+CPM graph clustering** (`src/agents/leiden.js`). Files that import each other heavily cluster together. Domain names are inferred from path tokens, with keyword hints for well-known patterns.
 
@@ -215,7 +215,7 @@ 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 (35 tests)
+npm test                     # run test suite (62 tests)
 node test/correctness.js     # run correctness tests (31 tests)
 node test/benchmark.js       # run benchmarks against real repos
 ```
@@ -258,7 +258,7 @@ npm run test:bench-ci        # self-bench (matches what bench.yml runs)
 - [ ] 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 (35/35)
+- [ ] `npm test` passes (62/62)
 - [ ] `node test/correctness.js` passes (31/31)
 
 ---

package/README.md

@@ -138,7 +138,7 @@ Reads `tsconfig.json` / `jsconfig.json` for `paths` config. `@/components/Button
 
 ## Domain detection
 
-V2 uses **Leiden+CPM graph clustering** — files that import each other heavily cluster together. Domain names are inferred from path tokens, with keyword hints for well-known patterns (AUTH, PAYMENTS, DATABASE, etc.).
+Carto uses **Leiden+CPM graph clustering** — files that import each other heavily cluster together. Domain names are inferred from path tokens, with keyword hints for well-known patterns (AUTH, PAYMENTS, DATABASE, etc.).
 
 Works on any repo — not just SaaS apps. vscode gets AUTH/EVENTS/DATABASE. zed (Rust) gets DATABASE/AUTH/EVENTS. A game engine would get RENDERER/PHYSICS/AUDIO.
 
@@ -227,27 +227,10 @@ Other agents are smart but blind. Carto sees the architecture:
 
 ---
 
-## V1 → V2 migration
-
-Run `carto sync` — it auto-migrates your existing `graph-cache.json` and `map.json` into SQLite and renames them to `.bak`. No manual steps.
-
-What changed under the hood:
-
-| | V1 | V2 |
-|---|---|---|
-| Storage | JSON blobs | SQLite (WAL mode, indexed queries) |
-| Parsing | Babel-only | tree-sitter for all languages, Babel only for deep route/model extraction |
-| File limit | 300 cap | Unlimited |
-| Languages | JS/TS/Python/Go/R | + Rust/Java/C++/C#/Ruby |
-| Domain detection | Hardcoded keywords | Leiden+CPM graph clustering |
-| Watcher | Per-file chokidar | Single recursive directory watch (<20 file descriptors) |
-| MCP startup | Re-indexes on start | Opens SQLite instantly (<10ms) |
-| Path aliases | Not resolved | `@/`, `~/` resolved via tsconfig |
-
----
-
 ## MCP config (if auto-wire missed your IDE)
 
+`carto init` auto-wires into Kiro, Cursor, and Claude Desktop. If it missed yours, add manually:
+
 **Kiro** — `~/.kiro/settings/mcp.json`
 ```json
 { "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
@@ -263,6 +246,16 @@ What changed under the hood:
 { "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
 ```
 
+**VS Code Copilot** — `.vscode/mcp.json` in your project root, or Command Palette → `MCP: Add Server`
+```json
+{ "servers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
+```
+
+**Windsurf** — `~/.windsurf/mcp.json`
+```json
+{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
+```
+
 ---
 
 ## What Carto never does

package/index.js

@@ -4,17 +4,27 @@
  * carto-md — public module API
  *
  * Usage:
- *   const { Carto } = require('carto-md');
- *   const carto = new Carto();
+ *   const { StoreAdapter } = require('carto-md');
+ *   const carto = new StoreAdapter();
  *   await carto.index('/path/to/project');
  *
- *   // Get everything Kepler needs for a file
+ *   // Get everything an editor agent needs for a file
  *   const ctx = carto.getContextForFile('src/auth/auth.service.ts');
  *
- *   // Listen for live updates
- *   carto.on('updated', ({ file, blastRadius }) => { ... });
+ *   // Read structural facts
+ *   const routes = carto.getRoutes();
+ *   const radius = carto.getBlastRadius('src/auth/auth.service.ts');
+ *   carto.close();
+ *
+ * Back-compat: `Carto` is exported as an alias for `StoreAdapter`.
+ * Existing programs that did `const { Carto } = require('carto-md')`
+ * continue to work without changes. The alias (and the `terminate()`
+ * method on StoreAdapter) will be removed in 3.0.0.
  */
 
-const { Carto } = require('./src/engine/carto');
+const { StoreAdapter } = require('./src/store/store-adapter');
 
-module.exports = { Carto };
+module.exports = {
+  StoreAdapter,
+  Carto: StoreAdapter, // deprecated alias, removed in 3.0.0
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carto-md",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "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"

package/src/acp/session.js

@@ -3,7 +3,7 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
-const { Carto } = require('../engine/carto');
+const { StoreAdapter } = require('../store/store-adapter');
 
 class Session {
   constructor(id, workingDir) {
@@ -23,20 +23,16 @@ class Session {
     if (this._indexed) return null;
 
     const dbPath = path.join(this.workingDir, '.carto', 'carto.db');
-    this.carto = new Carto();
+    const wasIndexed = fs.existsSync(dbPath);
 
-    if (fs.existsSync(dbPath)) {
-      // DB exists — just load the index (fast path, <10ms)
-      await this.carto.index(this.workingDir);
-      this._indexed = true;
-      return null;
-    }
-
-    // No DB — run full indexing
+    this.carto = new StoreAdapter();
     const start = Date.now();
-    await this.carto.index(this.workingDir, { useWorkers: true });
+    await this.carto.index(this.workingDir, { writeOutputs: false });
     this._indexed = true;
 
+    if (wasIndexed) return null;
+
+    // Fresh index — surface status message
     const meta = this.carto.getMeta();
     const duration = ((Date.now() - start) / 1000).toFixed(1);
     const domains = this.carto.getDomainsList();
@@ -64,6 +60,8 @@ class SessionManager {
   }
 
   delete(id) {
+    const s = this._sessions.get(id);
+    if (s && s.carto) s.carto.close();
     this._sessions.delete(id);
   }
 }

package/src/cli/check.js

@@ -4,8 +4,10 @@ const { execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const { SQLiteStore } = require('../store/sqlite-store');
+const { checkForUpdate } = require('./update-check');
 
 async function run(projectRoot) {
+  checkForUpdate(); // fire and forget
   const dbPath = path.join(projectRoot, '.carto', 'carto.db');
 
   if (!fs.existsSync(dbPath)) {

package/src/cli/impact.js

@@ -1,17 +1,18 @@
 'use strict';
 
-const path = require('path');
-const { Carto } = require('../../index.js');
+const { StoreAdapter } = require('../store/store-adapter');
+const { checkForUpdate } = require('./update-check');
 
 async function run(projectRoot, fileArg) {
+  checkForUpdate(); // fire and forget
   if (!fileArg) {
     console.error('[CARTO] Usage: carto impact <file>');
     process.exit(1);
   }
 
-  const carto = new Carto();
+  const carto = new StoreAdapter();
   try {
-    await carto.index(projectRoot, { useWorkers: false });
+    await carto.index(projectRoot);
   } catch (err) {
     console.error(`[CARTO] Error loading index: ${err.message}`);
     process.exit(1);
@@ -20,6 +21,7 @@ async function run(projectRoot, fileArg) {
   const br = carto.getBlastRadius(fileArg);
   if (!br) {
     console.error(`[CARTO] File not found in project graph: ${fileArg}`);
+    carto.close();
     process.exit(1);
   }
 
@@ -53,7 +55,7 @@ async function run(projectRoot, fileArg) {
   }
 
   console.log('');
-  carto.terminate();
+  carto.close();
 }
 
 module.exports = { run };

package/src/cli/init.js

@@ -3,8 +3,10 @@ const path = require('path');
 const { detectFramework } = require('../detector/framework');
 const { parseCartoIgnore } = require('../security/ignore');
 const { runSyncV2, discoverFiles: discoverFilesV2 } = require('../store/sync-v2');
+const { checkForUpdate } = require('./update-check');
 
 async function run(projectRoot) {
+  checkForUpdate(); // fire and forget
   console.log('[CARTO] Detecting project...');
 
   const detection = detectFramework(projectRoot);
@@ -52,8 +54,6 @@ async function run(projectRoot) {
   installGitHook(projectRoot);
 
   // Run first sync — V2 SQLite-backed indexer.
-  // (Previously: V1 runFullSync with empty file lists from resolveConfig — produced
-  // a 23ms no-op that left .carto/carto.db missing and AGENTS.md unpopulated.)
   await runSyncV2({
     projectRoot,
     output: path.resolve(projectRoot, config.output || 'AGENTS.md')
@@ -65,22 +65,6 @@ async function run(projectRoot) {
   console.log('[CARTO] AGENTS.md generated. Carto will sync on every git commit.');
 }
 
-/**
- * Resolves config paths to absolute paths.
- * V2: no watch file lists — sync-v2 discovers files itself.
- */
-function resolveConfig(projectRoot, config) {
-  return {
-    watch: {
-      routeFiles: (config.watch && config.watch.routeFiles || []).map(f => path.resolve(projectRoot, f)),
-      modelFiles: (config.watch && config.watch.modelFiles || []).map(f => path.resolve(projectRoot, f)),
-      frontendFiles: (config.watch && config.watch.frontendFiles || []).map(f => path.resolve(projectRoot, f))
-    },
-    output: path.resolve(projectRoot, config.output || 'AGENTS.md'),
-    projectRoot
-  };
-}
-
 function installGitHook(projectRoot) {
   const gitDir = path.join(projectRoot, '.git');
   if (!fs.existsSync(gitDir)) return;
@@ -161,4 +145,4 @@ function wireIDEs(projectRoot) {
   }
 }
 
-module.exports = { run, resolveConfig };
+module.exports = { run };

package/src/cli/serve.js

@@ -1,23 +1,24 @@
 const path = require('path');
 const fs = require('fs');
+const { checkForUpdate } = require('./update-check');
 
 function run(projectRoot) {
-  // Prefer V2 SQLite-backed server
+  checkForUpdate(); // fire and forget
   const dbPath = path.join(projectRoot, '.carto', 'carto.db');
-  if (fs.existsSync(dbPath)) {
-    console.error('[CARTO] MCP server starting (V2 SQLite)...');
-    require('../mcp/server-v2');
-    return;
-  }
 
-  // Fallback to V1 if no SQLite DB exists
-  const mapPath = path.join(projectRoot, '.carto', 'map.json');
-  if (!fs.existsSync(mapPath)) {
-    console.error('[CARTO] No index found. Run `carto sync` first.');
+  if (!fs.existsSync(dbPath)) {
+    // Could be pre-2.0.4 install with only map.json, or never initialized.
+    const mapPath = path.join(projectRoot, '.carto', 'map.json');
+    if (fs.existsSync(mapPath)) {
+      console.error('[CARTO] Legacy index found (map.json) but no SQLite DB. Run `carto init` to upgrade your index.');
+    } else {
+      console.error('[CARTO] No index found. Run `carto init` first.');
+    }
     process.exit(1);
   }
-  console.error('[CARTO] MCP server starting (V1 compat)...');
-  require('../mcp/server');
+
+  console.error('[CARTO] MCP server starting...');
+  require('../mcp/server-v2');
 }
 
 module.exports = { run };

package/src/cli/sync.js

@@ -1,8 +1,6 @@
 const fs = require('fs');
 const path = require('path');
 const { runSyncV2 } = require('../store/sync-v2');
-const { runFullSync } = require('../sync');
-const { resolveConfig } = require('./init');
 const { checkForUpdate } = require('./update-check');
 
 async function run(projectRoot) {
@@ -22,20 +20,10 @@ async function run(projectRoot) {
     process.exit(1);
   }
 
-  // Use V2 SQLite-backed sync
-  const v2Config = {
+  await runSyncV2({
     projectRoot,
     output: path.resolve(projectRoot, config.output || 'AGENTS.md')
-  };
-
-  try {
-    await runSyncV2(v2Config);
-  } catch (err) {
-    // Fallback to V1 if V2 fails (e.g., better-sqlite3 not available)
-    console.warn(`[CARTO] V2 sync failed (${err.message}), falling back to V1`);
-    const resolved = resolveConfig(projectRoot, config);
-    await runFullSync(resolved);
-  }
+  });
 
   console.log('[CARTO] Sync complete.');
 }

package/src/cli/update-check.js

@@ -1,12 +1,21 @@
+'use strict';
+
 const https = require('https');
 const pkg = require('../../package.json');
 
 /**
  * Fire-and-forget version check against the npm registry.
- * Prints a one-liner to stderr if a newer version exists.
- * Never throws, never blocks — safe to call without await.
+ *
+ * Prints a visually distinct notice to stderr if a newer version is on npm.
+ * Never throws, never blocks (3s socket timeout, ignores all errors) —
+ * safe to call without await from any CLI command's entry point.
+ *
+ * Set `CARTO_NO_UPDATE_CHECK=1` to disable entirely (used in test runs and
+ * by users who don't want the egress).
  */
 function checkForUpdate() {
+  if (process.env.CARTO_NO_UPDATE_CHECK) return;
+
   const req = https.get('https://registry.npmjs.org/carto-md/latest', {
     timeout: 3000,
   }, (res) => {
@@ -16,10 +25,8 @@ function checkForUpdate() {
       try {
         const data = JSON.parse(body);
         const latest = data.version;
-        if (latest && latest !== pkg.version && isNewer(latest, pkg.version)) {
-          process.stderr.write(
-            `[CARTO] Update available: ${pkg.version} → ${latest}  |  npm install -g carto-md\n`
-          );
+        if (latest && isNewer(latest, pkg.version)) {
+          process.stderr.write(formatNotice(pkg.version, latest));
         }
       } catch (_) {
         // malformed JSON — ignore
@@ -27,6 +34,10 @@ function checkForUpdate() {
     });
   });
 
+  // unref so the pending request never delays process exit on its own —
+  // if the main command finishes first, the check is silently dropped.
+  if (typeof req.unref === 'function') req.unref();
+
   req.on('timeout', () => { req.destroy(); });
   req.on('error', () => { /* offline / DNS failure — ignore */ });
 }
@@ -45,4 +56,36 @@ function isNewer(a, b) {
   return false;
 }
 
-module.exports = { checkForUpdate };
+/**
+ * formatNotice(current, latest) → multi-line stderr string.
+ *
+ * TTY-aware: emits ANSI yellow + bold when stderr is a TTY, plain text
+ * otherwise (so piped output and CI logs stay clean).
+ *
+ * Format (TTY example, ★ in yellow, version + command in bold):
+ *
+ *     <blank line>
+ *     [CARTO] ★ Update available: 2.0.1 → 2.0.5
+ *     [CARTO]   Run: npm install -g carto-md
+ *     <blank line>
+ *
+ * Two blank lines (one before, one after) separate the notice from
+ * regular [CARTO] log output so the upgrade prompt stands out even when
+ * it lands mid-progress (the check is fire-and-forget, so the response
+ * arrives whenever the network resolves).
+ */
+function formatNotice(current, latest) {
+  const useColor = !!process.stderr.isTTY && !process.env.NO_COLOR;
+  const yellow = (s) => useColor ? `\x1b[33m${s}\x1b[0m` : s;
+  const bold   = (s) => useColor ? `\x1b[1m${s}\x1b[0m`  : s;
+
+  return [
+    '',
+    `${yellow('[CARTO] ★ Update available:')} ${bold(`${current} → ${latest}`)}`,
+    `${yellow('[CARTO]   Run:')} ${bold('npm install -g carto-md')}`,
+    '',
+    ''
+  ].join('\n');
+}
+
+module.exports = { checkForUpdate, isNewer, formatNotice };

package/src/store/sqlite-store.js

@@ -6,6 +6,34 @@ const fs = require('fs');
 
 const SCHEMA_VERSION = '1';
 
+/**
+ * normalizePath(p) — Canonicalize a relative path for storage and query.
+ *
+ * Converts backslashes to forward slashes (Windows → POSIX), strips leading
+ * './', and rejects absolute paths (callers must `path.relative(projectRoot, p)`
+ * before passing in).
+ *
+ * Single-source-of-truth for "what does a row in `files.path` look like?".
+ * Apply this at every boundary that writes or queries the column, and every
+ * downstream join (imports.from_file_id → files.path) stays consistent.
+ *
+ * Cross-platform invariant: same code, same DB, same query results on macOS,
+ * Linux, and Windows. Closes Bug 2 (carto impact path normalization) and the
+ * Windows-only "0 dependents" failures in the Store adapter test suite.
+ */
+function normalizePath(p) {
+  if (typeof p !== 'string' || p.length === 0) return p;
+  let out = p;
+  // Backslash → forward slash (Windows → POSIX). path.sep is '\\' on Windows.
+  if (path.sep !== '/') out = out.split(path.sep).join('/');
+  // Some inputs may already use mixed separators (e.g., `src\utils/foo.js`).
+  // Normalize aggressively.
+  out = out.replace(/\\/g, '/');
+  // Strip leading './'
+  if (out.startsWith('./')) out = out.slice(2);
+  return out;
+}
+
 class SQLiteStore {
   constructor(projectRoot) {
     this._projectRoot = projectRoot;
@@ -213,7 +241,7 @@ class SQLiteStore {
   // ─── File operations ───────────────────────────────────────────────────
 
   getFileByPath(relPath) {
-    return this._db.prepare('SELECT * FROM files WHERE path = ?').get(relPath);
+    return this._db.prepare('SELECT * FROM files WHERE path = ?').get(normalizePath(relPath));
   }
 
   getFileById(id) {
@@ -230,7 +258,8 @@ class SQLiteStore {
   }
 
   upsertFile(relPath, { language, hash, mtime, size }) {
-    const existing = this.getFileByPath(relPath);
+    const norm = normalizePath(relPath);
+    const existing = this.getFileByPath(norm);
     if (existing) {
       this._db.prepare(
         'UPDATE files SET language=?, hash=?, mtime=?, size=?, last_indexed_at=? WHERE id=?'
@@ -239,18 +268,18 @@ class SQLiteStore {
     }
     const info = this._db.prepare(
       'INSERT INTO files (path, language, hash, mtime, size, last_indexed_at) VALUES (?,?,?,?,?,?)'
-    ).run(relPath, language, hash, mtime, size, Date.now());
+    ).run(norm, language, hash, mtime, size, Date.now());
     return info.lastInsertRowid;
   }
 
   updateFileMtime(relPath, mtime, size) {
     this._db.prepare(
       'UPDATE files SET mtime=?, size=? WHERE path=?'
-    ).run(mtime, size, relPath);
+    ).run(mtime, size, normalizePath(relPath));
   }
 
   removeFile(relPath) {
-    this._db.prepare('DELETE FROM files WHERE path = ?').run(relPath);
+    this._db.prepare('DELETE FROM files WHERE path = ?').run(normalizePath(relPath));
   }
 
   removeStaleFiles(currentPaths) {
@@ -744,4 +773,4 @@ class SQLiteStore {
   }
 }
 
-module.exports = { SQLiteStore };
+module.exports = { SQLiteStore, normalizePath };