carto-md 2.0.8 → 2.1.0

package/src/cli/init.js

@@ -2,18 +2,151 @@ const fs = require('fs');
 const path = require('path');
 const { detectFramework } = require('../detector/framework');
 const { parseCartoIgnore } = require('../security/ignore');
-const { runSyncV2, discoverFiles: discoverFilesV2 } = require('../store/sync-v2');
+const { runSync, discoverFiles: discoverFilesV2 } = require('../store/sync');
 const { checkForUpdate } = require('./update-check');
 
+const REQUIRED_NODE_MAJOR = 18;
+const LARGE_REPO_THRESHOLD = 100_000;
+
+/**
+ * Pre-flight checks that block or warn before we touch the filesystem.
+ * Returns true if init should proceed, false if it should bail.
+ */
+function preflightChecks(projectRoot) {
+  // Node version — postinstall blocks too, but a defensive double-check
+  // costs nothing and gives the user a clearer message than a crash 30
+  // lines later.
+  const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+  if (nodeMajor < REQUIRED_NODE_MAJOR) {
+    console.error(
+      `[CARTO] Node ${process.versions.node} is too old. ` +
+      `carto-md requires Node ≥ v${REQUIRED_NODE_MAJOR}. ` +
+      `Upgrade at https://nodejs.org/ and re-run.`,
+    );
+    return false;
+  }
+
+  // Already-initialized notice — we don't refuse to re-init, just call
+  // it out so the user knows what's happening.
+  const cartoDir = path.join(projectRoot, '.carto');
+  const dbPath = path.join(cartoDir, 'carto.db');
+  if (fs.existsSync(dbPath)) {
+    console.log('[CARTO] Re-indexing existing project (run `carto remove` first to start fresh).');
+  }
+
+  // Submodules warning — `discoverFiles` may or may not descend into
+  // them depending on .cartoignore. We surface so the user can choose.
+  const gitmodules = path.join(projectRoot, '.gitmodules');
+  if (fs.existsSync(gitmodules)) {
+    try {
+      const text = fs.readFileSync(gitmodules, 'utf8');
+      const count = (text.match(/\[submodule /g) || []).length;
+      if (count > 0) {
+        console.log(`[CARTO] Detected ${count} git submodule${count === 1 ? '' : 's'}. ` +
+          `Add their paths to .cartoignore if you don't want them indexed.`);
+      }
+    } catch { /* ignore */ }
+  }
+
+  // No .git? Hooks won't fire — git-based freshness mechanism is gone.
+  // Lazy MCP re-parse still handles staleness, but operators should know.
+  if (!fs.existsSync(path.join(projectRoot, '.git'))) {
+    console.log('[CARTO] No .git directory — skipping git-hooks install. The index will refresh on `carto sync` and on MCP queries.');
+  }
+
+  return true;
+}
+
+/**
+ * Render a small box with the headline numbers + one surprising fact
+ * after the first sync completes. The "mirror moment" — Carto reflects
+ * something the developer didn't already know.
+ */
+function printSummaryBox(projectRoot) {
+  try {
+    const { SQLiteStore } = require('../store/sqlite-store');
+    const store = new SQLiteStore(projectRoot);
+    store.open({ readonly: true });
+    const structure = store.getStructure();
+    const domains = store.getDomainsList() || [];
+    const highImpact = store.getHighImpactFiles(1) || [];
+    const crossDomain = store.getCrossDomainDeps() || [];
+    store.close();
+
+    const totalFiles = (structure.meta && structure.meta.totalFiles) || 0;
+    const totalRoutes = (structure.meta && structure.meta.totalRoutes) || 0;
+    const totalImports = (structure.meta && structure.meta.totalImportEdges) || 0;
+    if (totalFiles === 0) return; // empty repo — skip the box
+
+    const topDomains = domains.slice().sort((a, b) => b.fileCount - a.fileCount).slice(0, 4);
+    const lines = [];
+    lines.push('');
+    lines.push('┌─ Carto · indexed ─────────────────────────────────────────');
+    lines.push(`│  ${totalFiles} file${totalFiles === 1 ? '' : 's'} · ${domains.length} domain${domains.length === 1 ? '' : 's'} · ${totalRoutes} route${totalRoutes === 1 ? '' : 's'} · ${totalImports} import edge${totalImports === 1 ? '' : 's'}`);
+    if (topDomains.length > 0) {
+      lines.push('│');
+      lines.push('│  Top domains:');
+      for (const d of topDomains) {
+        lines.push(`│    ${d.name.padEnd(12)} (${d.fileCount} file${d.fileCount === 1 ? '' : 's'})`);
+      }
+    }
+    // The "mirror moment" — facts the user couldn't have known.
+    if (highImpact.length > 0) {
+      const top = highImpact[0];
+      const filePath = top.path || top.file || top;
+      const deps = top.centrality || top.dependents || top.dependentCount;
+      if (deps && deps > 0) {
+        lines.push('│');
+        lines.push(`│  💡 Highest-risk file: ${filePath}`);
+        const verb = deps === 1 ? 'file depends' : 'files depend';
+        lines.push(`│     (${deps} ${verb} on it — try \`carto why ${filePath}\`)`);
+      }
+    }
+    if (crossDomain.length > 0) {
+      lines.push('│');
+      lines.push(`│  ⚠️  ${crossDomain.length} cross-domain edge${crossDomain.length === 1 ? '' : 's'} — run \`carto check\` for details.`);
+    }
+    lines.push('└───────────────────────────────────────────────────────────');
+    lines.push('');
+    console.log(lines.join('\n'));
+  } catch (err) {
+    // Box is decorative — never let it fail the init flow.
+    if (process.env.CARTO_DEBUG) console.error(`[CARTO] (debug) summary box failed: ${err.message}`);
+  }
+}
+
 async function run(projectRoot) {
   checkForUpdate(); // fire and forget
+  if (!preflightChecks(projectRoot)) return;
   console.log('[CARTO] Detecting project...');
 
   const detection = detectFramework(projectRoot);
   console.log(`[CARTO] Detected: ${detection.framework} (${detection.language})`);
 
-  // V2: discover all files without cap
-  const relFiles = discoverFilesV2(projectRoot);
+  // Discover every file with no cap. The single-line counter refreshes
+  // every 500 files so users on big repos don't stare at a frozen
+  // "Detecting..." prompt for seconds.
+  const isTty = !!(process.stdout.isTTY && process.stdout.clearLine);
+  let lastTickAt = 0;
+  const onProgress = (count) => {
+    if (!isTty) return;
+    const now = Date.now();
+    if (now - lastTickAt < 50) return;  // throttle to ~20 Hz
+    lastTickAt = now;
+    process.stdout.write(`\r[CARTO] Discovering files: ${count.toLocaleString()}`);
+  };
+  const relFiles = discoverFilesV2(projectRoot, { onProgress });
+  if (isTty) process.stdout.write(`\r[CARTO] Discovered ${relFiles.length.toLocaleString()} source files.\n`);
+
+  // Large-repo ETA — at >100K files, indexing takes minutes, not
+  // seconds. Surface that so the user doesn't ctrl-C thinking we hung.
+  if (relFiles.length > LARGE_REPO_THRESHOLD) {
+    // Empirical: ~1ms / file for first-run on a recent laptop. Round
+    // up generously — better to over-estimate than have the user wait
+    // longer than promised.
+    const etaSec = Math.ceil(relFiles.length / 1000);
+    console.log(`[CARTO] Large repo (${relFiles.length.toLocaleString()} files). Estimated index time: ~${etaSec}s. Sit tight.`);
+  }
 
   const pyCount = relFiles.filter(f => f.endsWith('.py')).length;
   const jsCount = relFiles.filter(f => /\.(js|ts|jsx|tsx|mjs|cjs)$/.test(f)).length;
@@ -53,8 +186,8 @@ async function run(projectRoot) {
   // Install git hooks (silent freshness on git events)
   installGitHooks(projectRoot);
 
-  // Run first sync — V2 SQLite-backed indexer.
-  await runSyncV2({
+  // Run the first sync against the SQLite-backed indexer.
+  await runSync({
     projectRoot,
     output: path.resolve(projectRoot, config.output || 'AGENTS.md')
   });
@@ -63,6 +196,11 @@ async function run(projectRoot) {
   wireIDEs(projectRoot);
 
   console.log('[CARTO] AGENTS.md generated. Index stays fresh via git hooks + lazy MCP re-parse.');
+
+  // The "mirror moment" — print the headline numbers + a surprising
+  // fact (highest-risk file, cross-domain count). Decorative, never
+  // throws, gated on a valid index.
+  printSummaryBox(projectRoot);
 }
 
 /**
@@ -357,7 +495,7 @@ function wireIDEs(projectRoot) {
   // ─── VS Code Copilot ───────────────────────────────────────────────
   // Detection: `code` binary on PATH (most reliable; user-profile path
   // varies too much across macOS/Linux/Windows + Insiders/stable to be
-  // a good detection signal). Schema is different from MCP-spec default:
+  // a good detection signal). Schema differs from the standard MCP shape:
   // VS Code uses `servers` (not `mcpServers`) and requires `type: stdio`.
   if (binaryExists('code')) {
     try {

package/src/cli/inspect.js

@@ -113,7 +113,7 @@ function collect(projectRoot) {
   try {
     const structure = store.getStructure();
     const domainsList = store.getDomainsList();
-    // Defensive: getExtractionErrorCount throws on pre-Spec-11 schemas
+    // Defensive: getExtractionErrorCount throws on older schemas
     // (no `extraction_errors` table). Inspect must work on every DB
     // we've ever shipped — fall back to 0 on schema mismatch.
     let errCount = 0;

package/src/cli/org.js

@@ -0,0 +1,172 @@
+'use strict';
+
+/**
+ * `carto org` CLI commands.
+ *
+ * Subcommands:
+ *   carto org init [--name NAME]              — register the current cwd
+ *   carto org add <name> <root-path>          — register a repo
+ *   carto org remove <name>                   — drop a repo
+ *   carto org list                            — list registered repos
+ *   carto org sync [--npm scope...] [--pypi prefix...] [--go prefix...] [--maven prefix...]
+ *                                              — scan all repos, detect edges
+ *   carto org overview                        — print summary
+ *   carto org consumers <target>              — who imports this target
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { OrgStore, defaultOrgDbDir } = require('../org/store');
+const { orgSync } = require('../org/sync');
+const queries = require('../org/queries');
+
+function parseFlags(args) {
+  const out = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      // Multi-value flags collect into arrays.
+      if (next && !next.startsWith('--')) {
+        if (!out[key]) out[key] = next;
+        else if (Array.isArray(out[key])) out[key].push(next);
+        else out[key] = [out[key], next];
+        i++;
+      } else {
+        out[key] = true;
+      }
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+function help() {
+  console.log(`carto org <subcommand>
+
+Subcommands:
+  init [--name NAME]                   Register cwd as a repo (name = basename if omitted)
+  add <name> <root-path>               Register a repo
+  remove <name>                        Drop a repo
+  list                                 List registered repos
+  sync [--npm @scope] [--pypi prefix] [--go prefix] [--maven prefix]
+                                       Scan + detect cross-repo edges
+  overview                             Summary: repos + edge counts
+  consumers <target>                   Who depends on this target (npm name, etc.)
+`);
+}
+
+async function main(args) {
+  const sub = args[0];
+  if (!sub || sub === '--help' || sub === '-h') { help(); return; }
+  const flags = parseFlags(args.slice(1));
+  const orgDir = flags['org-dir'] || defaultOrgDbDir();
+
+  if (sub === 'init') {
+    const root = process.cwd();
+    const name = flags.name || path.basename(root);
+    const cartoDb = path.join(root, '.carto', 'carto.db');
+    const store = new OrgStore(orgDir).open();
+    try {
+      store.addRepo({ name, rootPath: root, cartoDbPath: fs.existsSync(cartoDb) ? cartoDb : null });
+      console.log(`[CARTO] org init: registered "${name}" at ${root}`);
+    } finally { store.close(); }
+    return;
+  }
+
+  if (sub === 'add') {
+    const name = flags._[0];
+    const rootPath = flags._[1] ? path.resolve(flags._[1]) : null;
+    if (!name || !rootPath) { console.error('Usage: carto org add <name> <root-path>'); process.exit(2); }
+    if (!fs.existsSync(rootPath)) { console.error(`[CARTO] root path not found: ${rootPath}`); process.exit(2); }
+    const store = new OrgStore(orgDir).open();
+    try {
+      const cartoDb = path.join(rootPath, '.carto', 'carto.db');
+      store.addRepo({ name, rootPath, cartoDbPath: fs.existsSync(cartoDb) ? cartoDb : null });
+      console.log(`[CARTO] org add: "${name}" → ${rootPath}`);
+    } finally { store.close(); }
+    return;
+  }
+
+  if (sub === 'remove') {
+    const name = flags._[0];
+    if (!name) { console.error('Usage: carto org remove <name>'); process.exit(2); }
+    const store = new OrgStore(orgDir).open();
+    try { store.removeRepo(name); console.log(`[CARTO] org remove: "${name}"`); }
+    finally { store.close(); }
+    return;
+  }
+
+  if (sub === 'list') {
+    const store = OrgStore.openIfExists(orgDir);
+    if (!store) { console.log('[CARTO] no org store yet. Run `carto org init`.'); return; }
+    try {
+      const repos = store.listRepos();
+      if (repos.length === 0) { console.log('[CARTO] no repos registered.'); return; }
+      console.log('| Name | Root | Last sync |');
+      console.log('|------|------|-----------|');
+      for (const r of repos) {
+        const ls = r.last_sync_at ? new Date(r.last_sync_at).toISOString() : '—';
+        console.log(`| ${r.name} | ${r.root_path} | ${ls} |`);
+      }
+    } finally { store.close(); }
+    return;
+  }
+
+  if (sub === 'sync') {
+    const scopes = {
+      npm: toArr(flags.npm),
+      pypi: toArr(flags.pypi),
+      go: toArr(flags.go),
+      maven: toArr(flags.maven),
+    };
+    const r = orgSync({ orgDir, scopes });
+    console.log(`[CARTO] org sync: ${r.repos} repo(s), ${r.edges_inserted} edge(s) inserted.`);
+    for (const [name, n] of Object.entries(r.edges_by_repo || {})) console.log(`  - ${name}: ${n} edges`);
+    return;
+  }
+
+  if (sub === 'overview') {
+    const store = OrgStore.openIfExists(orgDir);
+    if (!store) { console.log('[CARTO] no org store yet.'); return; }
+    try {
+      const o = queries.orgArchitectureOverview(store);
+      console.log(`# Org Architecture Overview\n`);
+      console.log(`Repos: ${o.summary.total_repos}`);
+      console.log(`Edges: ${o.summary.total_edges}`);
+      console.log(`\nBy kind:`);
+      for (const e of o.summary.edges_by_kind) console.log(`  ${e.edge_kind}: ${e.c}`);
+    } finally { store.close(); }
+    return;
+  }
+
+  if (sub === 'consumers') {
+    const target = flags._[0];
+    if (!target) { console.error('Usage: carto org consumers <target>'); process.exit(2); }
+    const store = OrgStore.openIfExists(orgDir);
+    if (!store) { console.log('[CARTO] no org store yet.'); return; }
+    try {
+      const rows = queries.findConsumersOfApi(store, target);
+      console.log(`# Consumers of ${target}\n`);
+      if (rows.length === 0) { console.log('_No consumers found._'); return; }
+      console.log('| From repo | Kind | File |');
+      console.log('|-----------|------|------|');
+      for (const r of rows.slice(0, 50)) console.log(`| ${r.from_repo} | ${r.edge_kind} | ${r.from_file || '—'} |`);
+    } finally { store.close(); }
+    return;
+  }
+
+  console.error(`Unknown subcommand: ${sub}`);
+  help();
+  process.exit(2);
+}
+
+function toArr(v) {
+  if (!v) return [];
+  if (Array.isArray(v)) return v;
+  return [v];
+}
+
+module.exports = { main };