carto-md 2.0.6 → 2.0.8

package/src/cli/inspect.js

@@ -0,0 +1,295 @@
+'use strict';
+
+/**
+ * `carto inspect` — read-only diagnostic command.
+ *
+ * Prints a snapshot of the on-disk index state — paths, sizes,
+ * freshness, sidecar shape, top-N popcount entries, schema version, sync
+ * timestamps, extraction error count, unavailable language grammars.
+ *
+ * Use cases:
+ *   - "Why is bitmap.bin stale?" — shows mtime gap vs carto.db.
+ *   - "Are my popcounts well-formed?" — top-10 entries match what
+ *     `get_high_impact_files` would return.
+ *   - "Did extractors fail silently?" — surfaces the breadcrumb count.
+ *   - "Are tree-sitter grammars healthy?" — surfaces the unavailable list.
+ *
+ * Two output modes:
+ *   carto inspect          — human-readable (sectioned text)
+ *   carto inspect --json   — single JSON object suitable for `| jq`
+ *
+ * **Strict invariant — never triggers a rebuild.** Uses the readonly
+ * SQLite path and `loadFromDisk` (not `ensureBitmapFresh`),
+ * so a missing or stale `bitmap.bin` shows up as `null` / `stale: true`
+ * in the output rather than mutating disk state. This is the diagnostic
+ * tool — its job is to report, not to fix.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { SQLiteStore } = require('../store/sqlite-store');
+const { loadFromDisk, BITMAP_FILENAME } = require('../bitmap/sidecar');
+
+function fileSize(p) {
+  try { return fs.statSync(p).size; } catch { return null; }
+}
+
+function fileMtime(p) {
+  try { return fs.statSync(p).mtimeMs; } catch { return null; }
+}
+
+function formatBytes(n) {
+  if (n === null || n === undefined) return 'n/a';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+function formatAge(ts) {
+  if (!ts) return 'never';
+  const ageSec = Math.max(0, Math.round((Date.now() - ts) / 1000));
+  if (ageSec < 60) return `${ageSec}s ago`;
+  if (ageSec < 3600) return `${Math.round(ageSec / 60)}m ago`;
+  if (ageSec < 86400) return `${Math.round(ageSec / 3600)}h ago`;
+  return `${Math.round(ageSec / 86400)}d ago`;
+}
+
+/**
+ * Collect everything the inspect command reports, as a plain object.
+ * Pure data extraction — no rendering. Both human and JSON modes
+ * consume this. Exposed for tests (asserts on the JSON shape are
+ * cheaper and more stable than parsing terminal output).
+ */
+function collect(projectRoot) {
+  const cartoDir = path.join(projectRoot, '.carto');
+  const dbPath = path.join(cartoDir, 'carto.db');
+  const bitmapPath = path.join(cartoDir, BITMAP_FILENAME);
+
+  const dbSize = fileSize(dbPath);
+  const dbMtime = fileMtime(dbPath);
+  const bitmapSize = fileSize(bitmapPath);
+  const bitmapMtime = fileMtime(bitmapPath);
+
+  // Bitmap freshness: stale if it's older than the DB (or missing).
+  let stale = null;
+  if (bitmapMtime === null) stale = true;
+  else if (dbMtime !== null) stale = bitmapMtime < dbMtime;
+
+  const out = {
+    paths: {
+      projectRoot,
+      cartoDir,
+      dbPath,
+      bitmapPath,
+    },
+    files: {
+      dbExists: dbSize !== null,
+      dbSize,
+      dbMtime,
+      bitmapExists: bitmapSize !== null,
+      bitmapSize,
+      bitmapMtime,
+      bitmapStale: stale,
+    },
+    meta: null,
+    bitmap: null,
+    topImpact: [],
+    domains: [],
+  };
+
+  // SQLite read — readonly path so this can never mutate the index.
+  // If the DB is missing, return what we have and let the caller render
+  // the "run carto init first" message.
+  if (!out.files.dbExists) return out;
+
+  const store = new SQLiteStore(projectRoot);
+  try {
+    store.open({ readonly: true });
+  } catch (err) {
+    out.error = `Failed to open ${dbPath}: ${err.message}`;
+    return out;
+  }
+
+  try {
+    const structure = store.getStructure();
+    const domainsList = store.getDomainsList();
+    // Defensive: getExtractionErrorCount throws on pre-Spec-11 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;
+    try { errCount = store.getExtractionErrorCount(); } catch { errCount = 0; }
+    const unavailRaw = store.getMeta('unavailable_languages_json');
+    let unavail = [];
+    if (unavailRaw) {
+      try { unavail = JSON.parse(unavailRaw); } catch { unavail = []; }
+    }
+
+    out.meta = {
+      schemaVersion: store.getMeta('schema_version'),
+      lastFullSync: store.getMeta('last_full_sync'),
+      lastPartialSync: store.getMeta('last_partial_sync'),
+      lastIndexed: structure.meta.lastIndexed,
+      indexDurationMs: structure.meta.indexDuration,
+      totalFiles: structure.meta.totalFiles,
+      totalRoutes: structure.meta.totalRoutes,
+      totalImportEdges: structure.meta.totalImportEdges,
+      extractionErrorCount: errCount,
+      unavailableLanguages: unavail,
+    };
+    out.domains = domainsList.map(d => ({
+      name: d.name,
+      files: d.fileCount,
+      routes: d.routeCount,
+      models: d.modelCount,
+    }));
+
+    // Bitmap shape — load from disk only. Returns null if missing or
+    // corrupt; we report that rather than rebuilding (see invariant
+    // in the file header).
+    if (out.files.bitmapExists) {
+      const sidecar = loadFromDisk(cartoDir);
+      if (sidecar) {
+        out.bitmap = {
+          loaded: true,
+          size: sidecar.size,
+          forwardCount: sidecar.forward.size,
+          reverseCount: sidecar.reverse.size,
+          crossForwardCount: sidecar.crossForward ? sidecar.crossForward.size : 0,
+          domainBitmapCount: sidecar.domainBitmaps.size,
+          popcountIndexLength: sidecar.popcountIndex.length,
+          fileIdMapped: sidecar.fileIdToPath.size,
+        };
+        // Top-N from popcountIndex, with hydrated paths so caller can
+        // sanity-check that get_high_impact_files would return these.
+        const topN = Math.min(10, sidecar.popcountIndex.length);
+        for (let i = 0; i < topN; i++) {
+          const e = sidecar.popcountIndex[i];
+          out.topImpact.push({
+            file: sidecar.fileIdToPath.get(e.fileId) || `<id ${e.fileId}>`,
+            dependents: e.count,
+          });
+        }
+      } else {
+        out.bitmap = { loaded: false, reason: 'corrupt or version mismatch' };
+      }
+    } else {
+      out.bitmap = { loaded: false, reason: 'bitmap.bin not present' };
+    }
+  } finally {
+    try { store.close(); } catch {}
+  }
+
+  return out;
+}
+
+function renderHuman(data) {
+  const lines = [];
+  lines.push('');
+  lines.push('── Carto Inspect ───────────────────────────────────────');
+  lines.push('');
+
+  // ── Paths
+  lines.push('Paths');
+  lines.push(`  project       : ${data.paths.projectRoot}`);
+  lines.push(`  .carto/       : ${data.paths.cartoDir}`);
+  lines.push(`  carto.db      : ${formatBytes(data.files.dbSize)}` +
+    (data.files.dbExists ? ` (${formatAge(data.files.dbMtime)})` : ' (missing)'));
+  lines.push(`  bitmap.bin    : ${formatBytes(data.files.bitmapSize)}` +
+    (data.files.bitmapExists
+      ? ` (${formatAge(data.files.bitmapMtime)}${data.files.bitmapStale ? ', ⚠️ stale vs DB' : ''})`
+      : ' (missing)'));
+  lines.push('');
+
+  if (!data.files.dbExists) {
+    lines.push('  ⚠️  No .carto/carto.db found. Run `carto init` first.');
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  if (data.error) {
+    lines.push(`  ⚠️  ${data.error}`);
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  // ── Meta
+  const m = data.meta;
+  lines.push('Meta');
+  lines.push(`  schema version       : ${m.schemaVersion || '?'}`);
+  lines.push(`  last full sync       : ${m.lastFullSync || 'never'}`);
+  lines.push(`  last partial sync    : ${m.lastPartialSync || 'never'}`);
+  lines.push(`  index duration       : ${m.indexDurationMs}ms`);
+  lines.push(`  files indexed        : ${m.totalFiles}`);
+  lines.push(`  routes               : ${m.totalRoutes}`);
+  lines.push(`  import edges         : ${m.totalImportEdges}`);
+  lines.push(`  extraction errors    : ${m.extractionErrorCount}` +
+    (m.extractionErrorCount > 0 ? ' ⚠️  (run `carto check`)' : ''));
+  if (m.unavailableLanguages && m.unavailableLanguages.length > 0) {
+    lines.push(`  grammars unavailable : ⚠️  ${m.unavailableLanguages.join(', ')}`);
+  }
+  lines.push('');
+
+  // ── Bitmap
+  lines.push('Bitmap');
+  if (!data.bitmap || !data.bitmap.loaded) {
+    lines.push(`  ⚠️  not loaded — ${data.bitmap ? data.bitmap.reason : 'unknown'}`);
+  } else {
+    const b = data.bitmap;
+    lines.push(`  size (bits)          : ${b.size}`);
+    lines.push(`  forward bitmaps      : ${b.forwardCount}`);
+    lines.push(`  reverse bitmaps      : ${b.reverseCount}`);
+    lines.push(`  crossForward bitmaps : ${b.crossForwardCount}`);
+    lines.push(`  domain bitmaps       : ${b.domainBitmapCount}`);
+    lines.push(`  popcount index       : ${b.popcountIndexLength} entries`);
+    lines.push(`  file paths mapped    : ${b.fileIdMapped}`);
+  }
+  lines.push('');
+
+  // ── Top impact (popcount-index head)
+  if (data.topImpact.length > 0) {
+    lines.push('Top impact (from popcount index)');
+    for (const e of data.topImpact) {
+      lines.push(`  ${String(e.dependents).padStart(4)}  ${e.file}`);
+    }
+    lines.push('');
+  }
+
+  // ── Domains
+  if (data.domains.length > 0) {
+    lines.push('Domains');
+    for (const d of data.domains) {
+      lines.push(`  ${d.name.padEnd(16)} ${String(d.files).padStart(5)} files  ` +
+        `${String(d.routes).padStart(4)} routes  ` +
+        `${String(d.models).padStart(4)} models`);
+    }
+    lines.push('');
+  }
+
+  lines.push('────────────────────────────────────────────────────────');
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * run(projectRoot, options)
+ *   options.json — emit machine-readable JSON instead of human text.
+ *
+ * Exit code:
+ *   0 — DB present, output rendered.
+ *   1 — DB missing (caller should run `carto init`).
+ */
+function run(projectRoot, options = {}) {
+  const data = collect(projectRoot);
+
+  if (options.json) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+  } else {
+    process.stdout.write(renderHuman(data));
+  }
+
+  if (!data.files.dbExists) return 1;
+  if (data.error) return 1;
+  return 0;
+}
+
+module.exports = { run, collect, renderHuman };

package/src/cli/serve.js

@@ -7,7 +7,7 @@ function run(projectRoot) {
   const dbPath = path.join(projectRoot, '.carto', 'carto.db');
 
   if (!fs.existsSync(dbPath)) {
-    // Could be pre-2.0.4 install with only map.json, or never initialized.
+    // Could be an old 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.');

package/src/cli/watch.js

@@ -169,6 +169,12 @@ async function run(projectRoot) {
     process.exit(1);
   }
 
+  // `carto watch` is opt-in. Git hooks + lazy MCP re-parse
+  // handle the 90% case automatically with no background process. Surface
+  // that to anyone who runs this command so they know it's not required.
+  console.log('[CARTO] Note: `carto watch` is opt-in. Git hooks + lazy MCP re-parse (installed by `carto init`) keep the index fresh without a background process.');
+  console.log('[CARTO] Use `carto watch` for AI-heavy workflows where many files are edited between commits and you want sub-second freshness.');
+
   // Initial full sync using V2
   console.log('[CARTO] Starting initial sync...');
   await runSyncV2({

package/src/engine/worker.js

@@ -15,6 +15,9 @@ parentPort.on('message', (task) => {
   try {
     content = fs.readFileSync(filePath, 'utf-8');
   } catch (err) {
+    // Real I/O failure (file deleted between discovery and extraction,
+    // permission denied, etc.) — no point trying to extract. Caller
+    // turns this into a skip; nothing reaches the index.
     parentPort.postMessage({ id, error: err.message, result: null });
     return;
   }
@@ -27,17 +30,33 @@ parentPort.on('message', (task) => {
     return;
   }
 
-  let extracted;
+  // Capture extractor failures as breadcrumbs instead of
+  // dropping the file. The file still gets indexed (with empty
+  // extraction arrays) so its existence and imports are visible — and
+  // the failure shows up in `carto check` instead of vanishing.
+  const errors = [];
+
+  let extracted = { routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [] };
   try {
     extracted = plugin.extract(content, relPath);
+    // Plugin-internal failure breadcrumbs — see extractFile().
+    if (Array.isArray(extracted._errors) && extracted._errors.length > 0) {
+      for (const e of extracted._errors) {
+        if (e && e.phase && e.message) errors.push({ phase: e.phase, message: e.message });
+      }
+    }
   } catch (err) {
-    parentPort.postMessage({ id, error: err.message, result: null });
-    return;
+    errors.push({ phase: 'extract', message: err.message || String(err) });
   }
 
   // Use tree-sitter imports if the plugin produced them (faster, no file I/O)
   // Fall back to the regex-based extractImports for resolution
-  const imports = extractImports(content, filePath, projectRoot);
+  let imports = [];
+  try {
+    imports = extractImports(content, filePath, projectRoot);
+  } catch (err) {
+    errors.push({ phase: 'imports', message: err.message || String(err) });
+  }
 
   // Attach tree-sitter symbols if available (richer than legacy functions array)
   const tsSymbols = extracted._tsSymbols || null;
@@ -56,6 +75,7 @@ parentPort.on('message', (task) => {
       storageKeys: extracted.storageKeys || [],
       imports,
       tsSymbols,
+      errors,
     }
   });
 });

package/src/extractors/imports.js

@@ -36,7 +36,11 @@ function extractImports(content, filePath, projectRoot) {
   if (['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'].includes(ext)) {
     rawImports = extractJSImports(content);
   } else if (ext === '.py') {
-    rawImports = extractPythonImports(content, filePath, projectRoot);
+    // Python returns absolute paths from resolvePythonRelativeImport / tryResolvePythonModule.
+    // Relativize to project root and return early — the JS-style dedup loop below only handles
+    // `./` and `@/~/#` prefixed strings, so falling through silently drops every Python edge.
+    const abs = extractPythonImports(content, filePath, projectRoot);
+    return [...new Set(abs.map(p => path.relative(projectRoot, p)))].sort();
   } else if (ext === '.r') {
     return extractRImports(content, filePath, projectRoot);
   } else if (ext === '.go') {
@@ -47,6 +51,10 @@ function extractImports(content, filePath, projectRoot) {
     return extractJavaImports(content, filePath, projectRoot);
   } else if (ext === '.rb') {
     return extractRubyImports(content, filePath, projectRoot);
+  } else if (['.cpp', '.cc', '.cxx', '.c', '.h', '.hpp', '.hh', '.hxx'].includes(ext)) {
+    return extractCppImports(content, filePath, projectRoot);
+  } else if (ext === '.cs') {
+    return extractCsharpImports(content, filePath, projectRoot);
   }
 
   // Resolve and deduplicate
@@ -646,3 +654,175 @@ function _resolveRubyPath(reqPath, baseDir, projectRoot) {
   }
   return null;
 }
+
+
+// ─── C / C++ imports ──────────────────────────────────────────────────────────
+
+/**
+ * extractCppImports(content, filePath, projectRoot) → Array<string>
+ *
+ * Resolves #include directives to actual files in the project.
+ *
+ *   #include "foo.h"      → resolved relative to current file's dir,
+ *                           then common include search dirs.
+ *   #include <foo>        → skipped (system header, external).
+ *
+ * Uses tree-sitter-cpp when available, otherwise falls back to a
+ * simple regex over the source.
+ */
+function extractCppImports(content, filePath, projectRoot) {
+  const results = new Set();
+  const fileDir = path.dirname(filePath);
+  const ext = path.extname(filePath);
+
+  // Pull raw includes via tree-sitter when available; fall back to regex.
+  let rawImports = [];
+  try {
+    const tsParser = require('./tree-sitter-parser');
+    if (tsParser.isAvailable()) {
+      rawImports = tsParser.extractImports(content, ext);
+    }
+  } catch { /* tree-sitter unavailable */ }
+
+  if (rawImports.length === 0) {
+    const re = /^\s*#\s*include\s+(?:"([^"]+)"|<([^>]+)>)/gm;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      // m[1] is quoted form, m[2] is angle-bracket form. Keep both shapes
+      // so the system-header filter below can drop the angle ones.
+      if (m[1]) rawImports.push(m[1]);
+      else if (m[2]) rawImports.push('<' + m[2] + '>');
+    }
+  }
+
+  for (const raw of rawImports) {
+    // Drop system headers (angle brackets). Tree-sitter returns these as
+    // "<string>" wrappers; the regex form we just constructed does too.
+    if (raw.startsWith('<') && raw.endsWith('>')) continue;
+    // Defensive: a tree-sitter grammar quirk could leak the wrappers in.
+    if (raw.startsWith('"') && raw.endsWith('"')) {
+      const inner = raw.slice(1, -1);
+      _tryResolveCppInclude(inner, fileDir, projectRoot, results);
+      continue;
+    }
+    _tryResolveCppInclude(raw, fileDir, projectRoot, results);
+  }
+
+  return [...results].sort();
+}
+
+function _tryResolveCppInclude(includePath, fileDir, projectRoot, results) {
+  // Search order: relative to current file, then common include roots.
+  const candidates = [
+    path.resolve(fileDir, includePath),
+    path.join(projectRoot, 'include', includePath),
+    path.join(projectRoot, 'src', 'include', includePath),
+    path.join(projectRoot, 'src', includePath),
+    path.join(projectRoot, includePath),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c) && fs.statSync(c).isFile()) {
+      results.add(path.relative(projectRoot, c));
+      return;
+    }
+  }
+}
+
+// ─── C# imports ───────────────────────────────────────────────────────────────
+
+// Cache: projectRoot → Map<namespace, Array<relativeFilePath>>
+const _csNamespaceCache = new Map();
+
+/**
+ * Build a namespace → files map by scanning every .cs file in the project
+ * once. Cached per projectRoot. This is the only reliable way to resolve
+ * `using A.B.C;` in C# because (unlike Java) namespace and folder structure
+ * are decoupled — a namespace can span many files in many directories.
+ */
+function _getCsharpNamespaceMap(projectRoot) {
+  if (_csNamespaceCache.has(projectRoot)) return _csNamespaceCache.get(projectRoot);
+  const map = new Map();
+
+  const SKIP_DIRS = new Set(['node_modules', 'bin', 'obj', 'packages', '.git', 'dist', 'build']);
+  const walk = (dir) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) walk(path.join(dir, e.name));
+        continue;
+      }
+      if (!e.isFile() || !e.name.endsWith('.cs')) continue;
+      const full = path.join(dir, e.name);
+      let c;
+      try { c = fs.readFileSync(full, 'utf-8'); } catch { continue; }
+      // Match both file-scoped (`namespace Foo;`) and block-scoped (`namespace Foo {`).
+      const m = c.match(/^\s*namespace\s+([\w.]+)\s*[;{]/m);
+      if (!m) continue;
+      const ns = m[1];
+      const rel = path.relative(projectRoot, full);
+      if (!map.has(ns)) map.set(ns, []);
+      map.get(ns).push(rel);
+    }
+  };
+
+  walk(projectRoot);
+  _csNamespaceCache.set(projectRoot, map);
+  return map;
+}
+
+/**
+ * extractCsharpImports(content, filePath, projectRoot) → Array<string>
+ *
+ * Resolves `using Foo.Bar.Baz;` to project files that declare the
+ * matching namespace. Skips standard library namespaces (System.*,
+ * Microsoft.*, etc.) — those produce only noise.
+ */
+function extractCsharpImports(content, filePath, projectRoot) {
+  const results = new Set();
+  const nsMap = _getCsharpNamespaceMap(projectRoot);
+
+  // System namespaces and well-known third-party prefixes that almost never
+  // resolve to project files. We still check the map (a project could ship a
+  // Microsoft.* namespace), but skip the FS fallback for these.
+  const EXTERNAL_PREFIXES = ['System', 'Microsoft', 'Windows', 'Newtonsoft', 'Xunit', 'NUnit', 'Mono'];
+
+  const re = /^\s*using\s+(?:static\s+)?([\w.]+)\s*;/gm;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const ns = m[1];
+    const isExternal = EXTERNAL_PREFIXES.includes(ns.split('.')[0]);
+
+    // Primary path: namespace map lookup. Works regardless of folder layout.
+    const matched = nsMap.get(ns);
+    if (matched) {
+      for (const f of matched) results.add(f);
+      continue;
+    }
+
+    if (isExternal) continue;
+
+    // Fallback: filename convention (Foo.Bar.Baz → Foo/Bar/Baz.cs).
+    const parts = ns.split('.');
+    const asFile = parts.join(path.sep) + '.cs';
+    const candidates = [
+      path.join(projectRoot, 'src', asFile),
+      path.join(projectRoot, asFile),
+    ];
+    for (const c of candidates) {
+      if (fs.existsSync(c)) {
+        results.add(path.relative(projectRoot, c));
+        break;
+      }
+    }
+  }
+
+  // Drop self-import — a file's `namespace X;` can match itself when the
+  // file imports its own namespace via `using X;`.
+  const selfRel = path.relative(projectRoot, filePath);
+  results.delete(selfRel);
+
+  return [...results].sort();
+}

package/src/extractors/languages/html.js

@@ -9,7 +9,10 @@ module.exports = {
       return { routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches, storageKeys };
     } catch (err) {
       console.warn(`[CARTO] html plugin error on ${filename}: ${err.message}`);
-      return { routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [] };
+      return {
+        routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [],
+        _errors: [{ phase: 'extract', message: err.message || String(err) }],
+      };
     }
   }
 };

package/src/extractors/languages/javascript.js

@@ -94,6 +94,11 @@ module.exports = {
         storageKeys: [],
         _tsImports:  tsImports,
         _tsSymbols:  tsSymbols,
+        // Surface the parse failure as a breadcrumb so the
+        // caller can record it in extraction_errors. Pre-Spec-11 this
+        // warning only hit stderr and the file lost all of its routes
+        // and models silently.
+        _errors:     [{ phase: 'parse', message: `Babel parse: ${err.message}` }],
       };
     }
 

package/src/extractors/languages/prisma.js

@@ -20,7 +20,10 @@ module.exports = {
       };
     } catch (err) {
       console.warn(`[CARTO] prisma plugin error on ${filename}: ${err.message}`);
-      return { routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [] };
+      return {
+        routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [],
+        _errors: [{ phase: 'extract', message: err.message || String(err) }],
+      };
     }
   }
 };

package/src/extractors/languages/python.js

@@ -34,7 +34,11 @@ module.exports = {
       };
     } catch (err) {
       console.warn(`[CARTO] python plugin error on ${filename}: ${err.message}`);
-      return { routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [] };
+      return {
+        routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [],
+        // Record the failure so it's visible in `carto check`.
+        _errors: [{ phase: 'extract', message: err.message || String(err) }],
+      };
     }
   }
 };

package/src/extractors/languages/r.js

@@ -249,7 +249,10 @@ module.exports = {
       };
     } catch (err) {
       console.warn(`[CARTO] r plugin error on ${filename}: ${err.message}`);
-      return { routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [] };
+      return {
+        routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [],
+        _errors: [{ phase: 'extract', message: err.message || String(err) }],
+      };
     }
   }
 };

package/src/extractors/languages/typescript.js

@@ -63,6 +63,8 @@ module.exports = {
         jobs:        extractQueueAndCron(content),
         _tsImports:  tsImports,
         _tsSymbols:  tsSymbols,
+        // Promote silent Babel failure to a breadcrumb.
+        _errors:     [{ phase: 'parse', message: `Babel parse: ${err.message}` }],
       };
     }
 

package/src/extractors/tree-sitter-parser.js

@@ -395,11 +395,26 @@ function _inferKind(nameNode, langName) {
   return 'variable';
 }
 
+/**
+ * getUnavailableLanguages() → string[]
+ * Returns language names whose grammars failed to load (or tree-sitter itself unavailable).
+ */
+function getUnavailableLanguages() {
+  if (!treeSitterAvailable) return GRAMMAR_DEFS.map(d => d.name);
+  const unavailable = [];
+  for (const def of GRAMMAR_DEFS) {
+    const ext = def.extensions[0];
+    if (!_getCompiledGrammar(ext)) unavailable.push(def.name);
+  }
+  return unavailable;
+}
+
 module.exports = {
   isAvailable,
   supportsExtension,
   extractImports,
   extractSymbols,
   extractAll,
+  getUnavailableLanguages,
   GRAMMAR_DEFS,
 };