carto-md 1.1.1 → 1.1.2

package/README.md

@@ -27,6 +27,16 @@ AI coding tools are blind to your actual project. Every session starts from zero
 
 **Carto makes it live. And queryable.**
 
+| | Without Carto | With Carto |
+|---|---|---|
+| Knows blast radius before editing | Never | Always, instantly |
+| Knows which routes break | Never | Exact list |
+| Plans multi-file changes | Guesses | Fully informed |
+| Hallucinates field names | Often | Never |
+| Understands codebase on session start | 10–20 min | 0 |
+| Works across Kiro, Cursor, Claude, Copilot | Separately | One shared graph |
+| Stays current as code changes | Goes stale | Live on every save |
+
 ---
 
 ## Proof — cal.com (800k lines)

package/index.js

@@ -0,0 +1,20 @@
+'use strict';
+
+/**
+ * carto-md — public module API
+ *
+ * Usage:
+ *   const { Carto } = require('carto-md');
+ *   const carto = new Carto();
+ *   await carto.index('/path/to/project');
+ *
+ *   // Get everything Kepler needs for a file
+ *   const ctx = carto.getContextForFile('src/auth/auth.service.ts');
+ *
+ *   // Listen for live updates
+ *   carto.on('updated', ({ file, blastRadius }) => { ... });
+ */
+
+const { Carto } = require('./src/engine/carto');
+
+module.exports = { Carto };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "carto-md",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "The context layer for AI-native development.",
   "bin": {
     "carto": "src/cli/index.js"
   },
-  "main": "./src/sync.js",
+  "main": "./index.js",
   "scripts": {
     "test": "node test/test.js"
   },

package/src/cache/file-hash.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+function getHashPath(projectRoot) {
+  return path.join(projectRoot, '.carto', 'hashes.json');
+}
+
+function loadHashes(projectRoot) {
+  try {
+    const raw = fs.readFileSync(getHashPath(projectRoot), 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function saveHashes(projectRoot, hashes) {
+  const hashPath = getHashPath(projectRoot);
+  const tmp = hashPath + '.tmp';
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(hashes, null, 2), 'utf-8');
+    fs.renameSync(tmp, hashPath);
+  } catch {}
+}
+
+function hashContent(content) {
+  return crypto.createHash('sha1').update(content).digest('hex');
+}
+
+/**
+ * computeChangedFiles(filePaths, storedHashes, projectRoot)
+ * Returns { changed: string[], unchanged: string[], hashes: object }
+ * changed = files whose content hash differs from stored
+ * unchanged = files whose hash matches — can skip re-parsing
+ */
+function computeChangedFiles(filePaths, storedHashes, projectRoot) {
+  const changed = [];
+  const unchanged = [];
+  const newHashes = { ...storedHashes };
+
+  for (const filePath of filePaths) {
+    const relPath = path.relative(projectRoot, filePath);
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf-8');
+    } catch {
+      continue;
+    }
+    const hash = hashContent(content);
+    if (storedHashes[relPath] === hash) {
+      unchanged.push(filePath);
+    } else {
+      changed.push(filePath);
+      newHashes[relPath] = hash;
+    }
+  }
+
+  return { changed, unchanged, hashes: newHashes };
+}
+
+/**
+ * updateFileHash(projectRoot, relPath, content)
+ * Updates the hash for a single file after incremental re-index.
+ */
+function updateFileHash(projectRoot, relPath, content) {
+  const hashes = loadHashes(projectRoot);
+  hashes[relPath] = hashContent(content);
+  saveHashes(projectRoot, hashes);
+}
+
+/**
+ * removeFileHash(projectRoot, relPath)
+ * Removes hash entry when a file is deleted.
+ */
+function removeFileHash(projectRoot, relPath) {
+  const hashes = loadHashes(projectRoot);
+  delete hashes[relPath];
+  saveHashes(projectRoot, hashes);
+}
+
+module.exports = { loadHashes, saveHashes, hashContent, computeChangedFiles, updateFileHash, removeFileHash };

package/src/cache/graph-cache.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function getCachePath(projectRoot) {
+  return path.join(projectRoot, '.carto', 'graph-cache.json');
+}
+
+/**
+ * loadGraphCache(projectRoot)
+ * Returns the full persisted graph or null if not found / corrupt.
+ *
+ * Cache shape:
+ * {
+ *   version: '2',
+ *   generated: ISO string,
+ *   fileData: {
+ *     [relPath]: { routes, models, functions, envVars, dbTables, fetches, storageKeys, imports }
+ *   },
+ *   importGraph: { [relPath]: [relPath, ...] },
+ *   routesByFile: { [relPath]: ['METHOD /path', ...] },
+ *   domains: { [domain]: { files, routes, models, functions, envVars, dbTables } },
+ *   highImpact: [{ file, dependents }],
+ *   entryPoints: [relPath, ...],
+ *   stack: [...],
+ *   meta: { totalFiles, totalRoutes, totalImportEdges, lastIndexed, indexDuration }
+ * }
+ */
+function loadGraphCache(projectRoot) {
+  try {
+    const raw = fs.readFileSync(getCachePath(projectRoot), 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== '2') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function saveGraphCache(projectRoot, cache) {
+  const cachePath = getCachePath(projectRoot);
+  const tmp = cachePath + '.tmp';
+  try {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    fs.writeFileSync(tmp, JSON.stringify(cache, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, cachePath);
+  } catch (err) {
+    console.warn(`[CARTO] Warning: Could not save graph cache — ${err.message}`);
+  }
+}
+
+/**
+ * buildEmptyCache() — starting point for a fresh index
+ */
+function buildEmptyCache() {
+  return {
+    version: '2',
+    generated: new Date().toISOString(),
+    fileData: {},
+    importGraph: {},
+    routesByFile: {},
+    domains: {},
+    highImpact: [],
+    entryPoints: [],
+    stack: [],
+    meta: {
+      totalFiles: 0,
+      totalRoutes: 0,
+      totalImportEdges: 0,
+      lastIndexed: null,
+      indexDuration: 0
+    }
+  };
+}
+
+module.exports = { loadGraphCache, saveGraphCache, buildEmptyCache, getCachePath };

package/src/cli/check.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const path = require('path');
+const { Carto } = require('../../index.js');
+
+async function run(projectRoot) {
+  const carto = new Carto();
+
+  try {
+    await carto.index(projectRoot, { useWorkers: false });
+  } catch (err) {
+    console.error(`[CARTO] Error loading index: ${err.message}`);
+    process.exit(1);
+  }
+
+  const meta = carto.getMeta();
+  const domains = carto.getDomainsList();
+  const crossDomain = carto.getCrossDomainDeps();
+  const highImpact = carto.getHighImpactFiles(20);
+
+  let hasIssues = false;
+
+  console.log('\n── Carto Check ─────────────────────────────────────────\n');
+
+  // ── Summary ──────────────────────────────────────────────────────────────
+  console.log(`  Files indexed : ${meta.totalFiles}`);
+  console.log(`  Routes found  : ${meta.totalRoutes}`);
+  console.log(`  Import edges  : ${meta.totalImportEdges}`);
+  console.log(`  Domains       : ${domains.map(d => d.name).join(', ') || 'none'}`);
+  if (meta.lastIndexed) {
+    const age = Math.round((Date.now() - new Date(meta.lastIndexed).getTime()) / 1000);
+    const ageStr = age < 60 ? `${age}s ago` : age < 3600 ? `${Math.round(age / 60)}m ago` : `${Math.round(age / 3600)}h ago`;
+    console.log(`  Last indexed  : ${ageStr}`);
+  }
+  console.log('');
+
+  // ── Uncommitted changes that touch high-blast-radius files ───────────────
+  const modifiedFiles = getModifiedFiles(projectRoot);
+  if (modifiedFiles.length > 0) {
+    const highImpactSet = new Set(highImpact.map(f => f.file));
+    const riskyChanges = modifiedFiles.filter(f => highImpactSet.has(f));
+
+    if (riskyChanges.length > 0) {
+      hasIssues = true;
+      console.log(`  ⚠️  High-risk uncommitted changes (${riskyChanges.length}):`);
+      for (const f of riskyChanges) {
+        const hi = highImpact.find(h => h.file === f);
+        const br = carto.getBlastRadius(f);
+        console.log(`     🔴 ${f}`);
+        console.log(`        ${hi.dependents} files depend on this — blast risk: ${br ? br.risk : 'UNKNOWN'}`);
+      }
+      console.log('');
+    } else {
+      console.log(`  ✅ ${modifiedFiles.length} modified file(s) — none are high-impact\n`);
+    }
+  }
+
+  // ── Cross-domain dependency violations ───────────────────────────────────
+  if (crossDomain.length > 0) {
+    hasIssues = true;
+    console.log(`  ⚠️  Cross-domain dependencies (${crossDomain.length}):`);
+    console.log('     These files import across domain boundaries.\n');
+
+    // Group by fromDomain → toDomain pair
+    const grouped = {};
+    for (const d of crossDomain) {
+      const key = `${d.fromDomain} → ${d.toDomain}`;
+      if (!grouped[key]) grouped[key] = [];
+      grouped[key].push(d);
+    }
+
+    for (const [pair, deps] of Object.entries(grouped)) {
+      console.log(`     ${pair} (${deps.length})`);
+      for (const d of deps.slice(0, 3)) {
+        console.log(`       ${path.basename(d.from)} imports ${path.basename(d.to)}`);
+      }
+      if (deps.length > 3) console.log(`       ...and ${deps.length - 3} more`);
+    }
+    console.log('');
+  } else if (domains.length > 1) {
+    console.log('  ✅ No cross-domain dependency violations\n');
+  }
+
+  // ── Top high-impact files ────────────────────────────────────────────────
+  if (highImpact.length > 0) {
+    console.log(`  🔥 Top high-impact files (changing these = highest blast radius):`);
+    for (const f of highImpact.slice(0, 5)) {
+      console.log(`     ${f.dependents.toString().padStart(3)} dependents — ${f.file}`);
+    }
+    console.log('');
+  }
+
+  // ── Domain breakdown ─────────────────────────────────────────────────────
+  if (domains.length > 0) {
+    console.log('  Domains:');
+    for (const d of domains) {
+      console.log(`     ${d.name.padEnd(16)} ${d.fileCount} files  ${d.routeCount} routes  ${d.modelCount} models`);
+    }
+    console.log('');
+  }
+
+  console.log('─────────────────────────────────────────────────────────\n');
+  console.log(hasIssues ? '  ⚠️  Issues found above.' : '  ✅ All clear.');
+  console.log('');
+
+  carto.terminate();
+}
+
+function getModifiedFiles(projectRoot) {
+  try {
+    const output = execSync('git diff --name-only HEAD 2>/dev/null && git diff --name-only 2>/dev/null', {
+      cwd: projectRoot,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    const files = [...new Set(output.trim().split('\n').filter(Boolean))];
+    return files;
+  } catch {
+    return [];
+  }
+}
+
+module.exports = { run };

package/src/cli/impact.js

@@ -1,167 +1,59 @@
-const fs = require('fs');
+'use strict';
+
 const path = require('path');
+const { Carto } = require('../../index.js');
 
-function run(projectRoot, fileArg) {
+async function run(projectRoot, fileArg) {
   if (!fileArg) {
     console.error('[CARTO] Usage: carto impact <file>');
     process.exit(1);
   }
 
-  const mapPath = path.join(projectRoot, '.carto', 'map.json');
-  if (!fs.existsSync(mapPath)) {
-    console.error('[CARTO] Run "carto init" first.');
-    process.exit(1);
-  }
-
-  let map;
+  const carto = new Carto();
   try {
-    map = JSON.parse(fs.readFileSync(mapPath, 'utf-8'));
+    await carto.index(projectRoot, { useWorkers: false });
   } catch (err) {
-    console.error(`[CARTO] Error reading .carto/map.json: ${err.message}`);
+    console.error(`[CARTO] Error loading index: ${err.message}`);
     process.exit(1);
   }
 
-  const imports = map.imports || {};
-  const routes = map.routes || [];
-
-  // Resolve file argument — match by basename or partial path
-  const matchedFile = resolveFile(fileArg, imports);
-  if (!matchedFile) {
+  const br = carto.getBlastRadius(fileArg);
+  if (!br) {
     console.error(`[CARTO] File not found in project graph: ${fileArg}`);
     process.exit(1);
   }
 
-  // Reverse lookup: which files import this file
-  const importedBy = [];
-  for (const [file, deps] of Object.entries(imports)) {
-    if (deps.includes(matchedFile)) {
-      importedBy.push(file);
-    }
-  }
-  importedBy.sort();
+  console.log(`\nImpact analysis: ${br.file}\n`);
 
-  // Collect all files that depend on matchedFile (up to 3 hops)
-  const dependentFiles = collectDependents(matchedFile, imports, 3);
-  // Also include the file itself — routes in the target file are affected
-  dependentFiles.add(matchedFile);
+  const riskBadge = { HIGH: '🔴 HIGH', MEDIUM: '🟡 MEDIUM', LOW: '🟢 LOW', SAFE: '✅ SAFE' };
+  console.log(`Risk: ${riskBadge[br.risk] || br.risk}`);
+  console.log(`Directly affected: ${br.directlyAffected.files} files across ${br.directlyAffected.domains} domain(s)`);
+  console.log(`Potentially affected: ${br.potentiallyAffected.files} files total\n`);
 
-  // Print output
-  console.log(`\nImpact analysis: ${matchedFile}\n`);
-
-  console.log('Imported by:');
-  if (importedBy.length > 0) {
-    for (const f of importedBy) {
-      console.log(`  → ${f}`);
-    }
-  } else {
-    console.log('  (none — this file is not imported by any other file)');
-  }
-
-  console.log('\nRoutes affected:');
-  // Use routesByFile for precise file→route mapping
-  const affectedRoutes = new Set();
-  for (const affectedFile of dependentFiles) {
-    const fileRoutes = map.routesByFile && map.routesByFile[affectedFile];
-    if (fileRoutes) {
-      for (const r of fileRoutes) affectedRoutes.add(r);
-    }
-  }
-  // Also check the target file itself
-  if (map.routesByFile && map.routesByFile[matchedFile]) {
-    for (const r of map.routesByFile[matchedFile]) affectedRoutes.add(r);
-  }
-
-  // Fall back to all routes only if no file-specific routes found and an entry point is hit
-  if (affectedRoutes.size === 0) {
-    const entryPointsInChain = map.entryPoints
-      ? map.entryPoints.filter(ep => dependentFiles.has(ep))
-      : [];
-    if (entryPointsInChain.length > 0) {
-      for (const route of routes) {
-        affectedRoutes.add(`${route.method} ${route.path}`);
-      }
-    }
+  if (br.domainsImpacted.length > 0) {
+    console.log(`Domains impacted: ${br.domainsImpacted.join(', ')}\n`);
   }
 
-  if (affectedRoutes.size > 0) {
-    for (const r of [...affectedRoutes].sort()) {
-      console.log(`  → ${r}`);
-    }
+  if (br.dependentFiles.length > 0) {
+    console.log(`Files that depend on this (${br.dependentFiles.length}):`);
+    for (const f of br.dependentFiles) console.log(`  → ${f}`);
+    console.log('');
   } else {
-    console.log('  (none — no route-serving files in the dependency chain)');
-  }
-
-  // Risk level
-  const depCount = importedBy.length;
-  let risk;
-  if (depCount >= 3) risk = 'HIGH';
-  else if (depCount === 2) risk = 'MEDIUM';
-  else if (depCount === 1) risk = 'LOW';
-  else risk = 'SAFE';
-
-  console.log(`\nRisk: ${risk} — ${depCount} file${depCount !== 1 ? 's' : ''} depend on this\n`);
-}
-
-/**
- * Resolve a file argument to a full relative path in the import graph.
- * Matches by basename or partial path suffix.
- */
-function resolveFile(fileArg, imports) {
-  const allFiles = new Set();
-  for (const [file, deps] of Object.entries(imports)) {
-    allFiles.add(file);
-    for (const dep of deps) allFiles.add(dep);
-  }
-
-  const normalized = fileArg.replace(/\\/g, '/');
-  const hasPathSeparator = normalized.includes('/');
-
-  // Exact match
-  if (allFiles.has(normalized)) return normalized;
-
-  // Match by suffix (partial path)
-  const matches = [...allFiles].filter(f => f.endsWith('/' + normalized) || f === normalized);
-  if (matches.length === 1) return matches[0];
-
-  // If input was a path (contains /), don't fall back to basename — it's ambiguous
-  if (hasPathSeparator) {
-    if (matches.length > 1) return null;
-    return null;
+    console.log('No files depend on this.\n');
   }
 
-  // Input is just a filename — fall back to basename matching
-  const byBasename = [...allFiles].filter(f => path.basename(f) === path.basename(normalized));
-  if (byBasename.length === 1) return byBasename[0];
-
-  // Multiple basename matches — ambiguous, don't guess
-  return null;
-}
-
-/**
- * Collect all files that transitively depend on the target file (reverse BFS).
- * maxHops limits the depth of the search.
- */
-function collectDependents(targetFile, imports, maxHops) {
-  const dependents = new Set();
-  let frontier = new Set([targetFile]);
-
-  for (let hop = 0; hop < maxHops; hop++) {
-    const nextFrontier = new Set();
-    for (const [file, deps] of Object.entries(imports)) {
-      if (dependents.has(file)) continue;
-      for (const dep of deps) {
-        if (frontier.has(dep)) {
-          dependents.add(file);
-          nextFrontier.add(file);
-          break;
-        }
-      }
+  if (br.routesImpacted.length > 0) {
+    console.log(`Routes at risk (${br.routesImpacted.length}):`);
+    for (const r of br.routesImpacted) {
+      const badge = r.risk === 'HIGH' ? '🔴' : r.risk === 'MEDIUM' ? '🟡' : '🟢';
+      console.log(`  ${badge} ${r.method} ${r.path}`);
     }
-    if (nextFrontier.size === 0) break;
-    frontier = nextFrontier;
+  } else {
+    console.log('No routes directly traceable.');
   }
 
-  return dependents;
+  console.log('');
+  carto.terminate();
 }
 
 module.exports = { run };

package/src/cli/index.js

@@ -12,6 +12,7 @@ Commands:
   watch         Read .carto/config.json, start file watcher
   sync          Read .carto/config.json, run one sync, exit
   impact <file> Show which files and routes are affected by changing a file
+  check         Report cross-domain deps, high-risk uncommitted changes, domain health
   remove        Remove AGENTS.md and .carto/ from this project
   serve         Start MCP server for AI tool integration
 
@@ -48,6 +49,11 @@ if (command === 'init') {
 } else if (command === 'impact') {
   const fileArg = process.argv[3];
   require('./impact').run(process.cwd(), fileArg);
+} else if (command === 'check') {
+  require('./check').run(process.cwd()).catch(err => {
+    console.error(`[CARTO] Fatal error: ${err.message}`);
+    process.exit(1);
+  });
 } else if (command === 'remove') {
   require('./remove').run(process.cwd());
 } else if (command === 'serve') {