@clear-capabilities/agentic-security-scanner 0.128.1 → 0.130.0

package/src/ir/callgraph.js

@@ -8,6 +8,26 @@
 //   4. Anything else → unresolved; the dataflow engine treats the callee as
 //      an opaque sink for taint.
 
+// Resolve whatever a caller has — a qid string or an already-resolved record —
+// into the function record.
+//
+// `resolve()` returns a qid STRING (edges[].callee holds qids, and the C/C++
+// qualified-name path depends on that), but several dataflow call sites want the
+// record so they can bind parameters and compute a summary on demand. Those
+// sites previously tested `resolved && resolved.qid`, which is never true for a
+// string, so the record was always null: parameters never bound, summaries were
+// never computed, and the callback path never ran. This helper is the bridge.
+//
+// Tolerant of a record so a future caller that already has one still works.
+export function functionRecord(callGraph, resolved) {
+  if (!resolved || !callGraph) return null;
+  if (typeof resolved === 'object') return resolved.qid ? resolved : null;
+  if (typeof resolved !== 'string') return null;
+  const fns = callGraph.functions;
+  if (!fns || typeof fns.get !== 'function') return null;
+  return fns.get(resolved) || null;
+}
+
 export function buildCallGraph(perFileIR, fileContents) {
   const functions = new Map();
   const byNameInFile = new Map();
@@ -40,6 +60,86 @@ export function buildCallGraph(perFileIR, fileContents) {
     }
   }
 
+  // Project-wide qualified-name index. C++ splits declaration from definition
+  // (`Foo::bar` declared in a header, defined in a .cpp), so a file-local
+  // lookup resolves almost nothing. Definitions take precedence over
+  // declarations, which are indexed only as a fallback. Two DISTINCT
+  // definitions sharing one qname (unqualified `static`/internal-linkage
+  // helpers with the same name in different .cpp files are common in C) must
+  // refuse to resolve rather than pick whichever was indexed first — a wrong
+  // edge invents a data-flow path that doesn't exist, which is worse than a
+  // missing one.
+  //
+  // Also tracks which files actually emit `qname` (C/C++ today) so resolution
+  // below can require the CALLING function to be from a qname-bearing file —
+  // otherwise a JS/Python/etc. call site whose bare name happens to collide
+  // with a C++ method (`f.read(...)` vs `File::read`) would fabricate a
+  // cross-language edge that has no relationship to the real callee.
+  const byQname = new Map();
+  const qnameFiles = new Set();
+  for (const [file, ir] of Object.entries(perFileIR || {})) {
+    for (const fn of (ir && ir.functions) || []) {
+      if (!fn.qname) continue;
+      qnameFiles.add(file);
+      const existing = byQname.get(fn.qname);
+      if (existing === undefined) {
+        byQname.set(fn.qname, fn);
+      } else if (existing === null) {
+        // Already flagged ambiguous by an earlier collision — stays refused.
+      } else if (existing.isDeclaration && !fn.isDeclaration) {
+        // Declaration seen first, this is its definition — the normal
+        // header/source pairing, not ambiguity.
+        byQname.set(fn.qname, fn);
+      } else if (!existing.isDeclaration && fn.isDeclaration) {
+        // Definition already indexed; a later declaration changes nothing.
+      } else if (!existing.isDeclaration && !fn.isDeclaration && existing.qid !== fn.qid) {
+        // Two distinct definitions under the same qname — refuse to guess.
+        byQname.set(fn.qname, null);
+      }
+      // (Two declarations with no definition yet: leave the first: neither
+      // resolves anyway since `isDeclaration` blocks the direct-key return.)
+
+      // Also index the bare method name so `b->fill(p)` — which carries no
+      // class qualification at the call site — can still find `Buffer::fill`,
+      // but only when that bare name is unambiguous project-wide.
+      const bare = fn.qname.includes('::') ? fn.qname.split('::').pop() : null;
+      if (bare) {
+        const key = `~bare~${bare}`;
+        if (byQname.has(key)) {
+          const cur = byQname.get(key);
+          if (cur !== null && cur.qname !== fn.qname) {
+            byQname.set(key, null); // ambiguous — refuse to guess
+          } else if (cur && cur.isDeclaration && !fn.isDeclaration) {
+            // Same method, declaration seen first — a later definition must
+            // still win, exactly as the direct qname index above.
+            byQname.set(key, fn);
+          }
+        } else {
+          byQname.set(key, fn);
+        }
+      }
+    }
+  }
+
+  // Qualified-name resolution (C++ header/source pairing). Try the name as
+  // written, then its dotted form re-expressed with `::`, then the
+  // unambiguous bare name. Returns a qid or null — never a bodiless
+  // declaration's qid, and never a guess when a bare name is ambiguous.
+  function resolveQname(name) {
+    if (!name) return null;
+    const direct = byQname.get(name);
+    if (direct && !direct.isDeclaration) return direct.qid;
+    const colonised = name.replace(/\./g, '::');
+    const viaColon = byQname.get(colonised);
+    if (viaColon && !viaColon.isDeclaration) return viaColon.qid;
+    const bare = name.includes('.') || name.includes('::')
+      ? name.split(/[.:]+/).pop()
+      : name;
+    const viaBare = byQname.get(`~bare~${bare}`);
+    if (viaBare && !viaBare.isDeclaration) return viaBare.qid;
+    return null;
+  }
+
   // Resolve each call site.
   const edges = []; // { caller, site, callee, ambiguous? }
   for (const fn of functions.values()) {
@@ -51,6 +151,11 @@ export function buildCallGraph(perFileIR, fileContents) {
                        classMethods.get(c.callee) ||
                        // 2. ClassName.method form
                        (c.callee.includes('.') ? classMethods.get(c.callee) : null) ||
+                       // 3. Cross-TU qualified-name index (C++ header/source
+                       // pairing) — gated on the CALLER carrying a `qname`
+                       // (only parser-cpp.js emits one) so a same-named call
+                       // in another language's file can never bind here.
+                       (fn.qname ? resolveQname(c.callee) : null) ||
                        null;
       edges.push({ caller: fn.qid, site: c.site, callee: resolved, calleeName: c.callee, line: c.line });
     }
@@ -63,11 +168,44 @@ export function buildCallGraph(perFileIR, fileContents) {
     if (!callersOf.has(e.callee)) callersOf.set(e.callee, []);
     callersOf.get(e.callee).push(e);
   }
+  // A candidate qid is cross-language-unsafe for a given caller when it
+  // carries a `qname` (only parser-cpp.js emits one) and the caller cannot
+  // itself be established as a qname-bearing (C/C++) file. Without this, the
+  // GENERIC fallbacks below — which predate the qname index and were built
+  // for same-language bare-name collisions (Roadmap #3) — would let a
+  // same-named call from any other language bind to a C++ definition just
+  // because both happen to share a bare identifier (`f.read()` in JS vs.
+  // `File::read` in C++): a fabricated cross-language edge, reached through
+  // these older, coarser lookups BEFORE the qname-specific gate further down
+  // is ever consulted.
+  function isCrossLanguageUnsafe(qid, callerFile) {
+    const cand = qid && functions.get(qid);
+    if (!cand || !cand.qname) return false;
+    return !(callerFile && qnameFiles.has(callerFile));
+  }
+
   // Premortem #7: expose a name→qid resolver so the taint engine can ask
   // the call graph for the callee's qid at the assign-from-call site.
   // Same precedence as the edge resolution above (same-file ident wins,
   // ClassName.method falls back).
-  function resolve(name, callerFile) {
+  //
+  // `allowTailGuess` gates the ONE step in this precedence chain that is a
+  // genuine guess rather than an exact or qualified match: given a dotted
+  // name with no other match, strip it to its last segment and match ANY
+  // same-named function project-wide (`loader.read()` -> `read`). That
+  // invents a call edge with no real relationship to the call site — a
+  // false positive, which is worse than the false negative of skipping it.
+  // Every OTHER branch here (same-file, ClassName.method, re-export,
+  // cross-TU qualified name) is an exact or intentionally-qualified match,
+  // never a bare-name guess, so they run regardless of the flag.
+  //
+  // This one function is the single source of truth for both behaviours —
+  // `resolve()` and `resolveKnownCallee()` below are thin wrappers over it —
+  // so a caller can never drift from the rule by re-implementing it (this
+  // recurred once already: two dataflow call sites reintroduced the guess
+  // that `dataflow/engine.js` had already been fixed to avoid, simply
+  // because the guard lived only in that one file's helper instead of here).
+  function _resolveImpl(name, callerFile, allowTailGuess) {
     if (!name || typeof name !== 'string') return null;
     // Roadmap #3: same-file preference. A bare name (`handler`, `save`,
     // `query`) defined in several files would otherwise resolve to whichever
@@ -76,29 +214,58 @@ export function buildCallGraph(perFileIR, fileContents) {
     // defines the name, that is overwhelmingly the intended callee — prefer
     // it. Backward-compatible: with no callerFile (or no local match) the
     // original resolution order is unchanged, so no edge is ever dropped.
+    // (No cross-language guard needed here: a same-file match means the
+    // candidate and caller share one file, hence one parser — if the
+    // candidate carries a `qname`, callerFile is necessarily a qname file.)
     if (callerFile) {
       const local = byNameInFile.get(callerFile);
       if (local && local.has(name)) return local.get(name);
     }
     for (const m of byNameInFile.values()) {
-      if (m.has(name)) return m.get(name);
+      if (m.has(name) && !isCrossLanguageUnsafe(m.get(name), callerFile)) return m.get(name);
     }
-    if (classMethods.has(name)) return classMethods.get(name);
-    if (name.includes('.')) {
+    if (classMethods.has(name) && !isCrossLanguageUnsafe(classMethods.get(name), callerFile)) {
+      return classMethods.get(name);
+    }
+    if (allowTailGuess && name.includes('.')) {
       const tail = name.split('.').slice(-1)[0];
       for (const m of byNameInFile.values()) {
-        if (m.has(tail)) return m.get(tail);
+        if (m.has(tail) && !isCrossLanguageUnsafe(m.get(tail), callerFile)) return m.get(tail);
       }
     }
     // Follow re-exports: if name was re-exported from another file, resolve there
     for (const [key, { sourceName }] of reexportMap) {
       if (key.endsWith(`::${name}`) || (sourceName === name)) {
         for (const m of byNameInFile.values()) {
-          if (m.has(sourceName)) return m.get(sourceName);
+          if (m.has(sourceName) && !isCrossLanguageUnsafe(m.get(sourceName), callerFile)) return m.get(sourceName);
         }
       }
     }
+    // Cross-TU qualified-name index (C++ header/source pairing) — runs after
+    // all existing rules and only matches functions carrying a `qname`. Gated
+    // on the CALLER's file, not just the candidate: only resolve when
+    // `callerFile` is itself a file that emits `qname` (C/C++ today), so a
+    // same-named call from a different language can never bind to a C++
+    // definition just because the candidate index has an entry.
+    if (callerFile && qnameFiles.has(callerFile)) {
+      const viaQname = resolveQname(name);
+      if (viaQname) return viaQname;
+    }
     return null;
   }
-  return { functions, edges, callersOf, resolve };
+  // Permissive: includes the bare-tail guess. Existing callers that already
+  // accept that tradeoff (or pre-date this split) keep this name.
+  function resolve(name, callerFile) {
+    return _resolveImpl(name, callerFile, true);
+  }
+  // Safe-by-default: every match is exact or explicitly qualified; never
+  // invents an edge by guessing from a dotted name's last segment. This is
+  // the entry point new callers should reach for — anything resolving a
+  // callee purely to build/query a reverse call graph (who calls whom) has
+  // no use for a guessed edge, since a wrong one fabricates a dataflow path
+  // that does not exist.
+  function resolveKnownCallee(name, callerFile) {
+    return _resolveImpl(name, callerFile, false);
+  }
+  return { functions, edges, callersOf, resolve, resolveKnownCallee };
 }

package/src/ir/class-hierarchy.js

@@ -41,7 +41,27 @@ export function buildClassHierarchy(perFileIR) {
   }
 
   for (const [file, ir] of Object.entries(perFileIR)) {
-    if (!ir || !Array.isArray(ir.functions)) continue;
+    if (!ir) continue;
+    // Language-neutral inheritance input. A parser may attach a `classes`
+    // array to its IR record; parser-cpp.js does. Nothing else populates
+    // `extends`, for any language, so this is purely additive.
+    if (Array.isArray(ir.classes)) {
+      for (const c of ir.classes) {
+        if (!c || !c.name) continue;
+        let cls = classes.get(c.name);
+        if (!cls) {
+          cls = { name: c.name, file, line: c.line || 0, methods: new Set(), extends: null };
+          classes.set(c.name, cls);
+        }
+        // v1 keeps a single base: the CHA walk in resolveMethod follows one
+        // chain. Multiple inheritance is flattened to the first base, which is
+        // a deliberate over-simplification recorded in PRD §6.8.
+        if (!cls.extends && Array.isArray(c.bases) && c.bases.length) {
+          cls.extends = c.bases[0];
+        }
+      }
+    }
+    if (!Array.isArray(ir.functions)) continue;
     // Recover class names from method qids of the shape
     //   <file>::<scope>::<className.method>
     // Many of our existing parsers emit class methods as `Foo.bar` in qid.
@@ -51,7 +71,7 @@ export function buildClassHierarchy(perFileIR) {
       const dotIdx = tail.indexOf('.');
       if (dotIdx <= 0) continue;
       const className = tail.slice(0, dotIdx);
-      const methodName = tail.slice(dotIdx + 1);
+      const methodName = tail.slice(dotIdx + 1).replace(/@\d+#[0-9a-f]+$/, '');
       methodOwners.set(fn.qid, className);
       let cls = classes.get(className);
       if (!cls) {

package/src/ir/index.js

@@ -11,15 +11,74 @@ import {
   parsePythonFile as parsePythonFileCst,
   parsePythonFilesBatch as parsePythonFilesBatchCst,
   probePythonAvailable,
+  noteParserDegradation,
+  pythonParserDegradation,
+  resetPythonParserDegradation,
 } from './parser-py-cst.js';
 import { parseJavaFile } from './parser-java.js';
 import { parseGoFile } from './parser-go.js';
 import { parsePhpFile } from './parser-php.js';
 import { parseRubyFile } from './parser-rb.js';
+import { parseCppFile, cppExtRe } from './parser-cpp.js';
 import { buildCallGraph } from './callgraph.js';
 import { buildClassHierarchy } from './class-hierarchy.js';
 import { computeSSA, isSSAEnabled } from './ssa.js';
 
+// ── per-file parse-failure observability ────────────────────────────────────
+// Both dispatch loops below wrap every language's parser in a bare try/catch
+// so one pathological file cannot abort IR construction for the whole project
+// (the load-bearing case: a RangeError out of parser-cs.js on real Godot C#
+// sources). Bare, that makes a SYSTEMATIC parser failure indistinguishable
+// from "this language isn't present in the tree" — coverage just reads 0.
+//
+// So the failures are counted, and are printed on stderr when
+// AGENTIC_SECURITY_IR_PARSE_DEBUG=1, following the precedent set by
+// parser-py-cst.js's AGENTIC_SECURITY_PY_PARSER_DEBUG and
+// sast/cpp-dataflow.js's `_parseErrorCount`. The counter is cumulative for
+// the process and readable via `irParseFailures()`.
+const _parseFailures = { count: 0, byLanguage: Object.create(null), firstError: null };
+
+function _langOf(file) {
+  const m = /\.([A-Za-z0-9+]+)$/.exec(String(file || ''));
+  return m ? m[1].toLowerCase() : 'unknown';
+}
+
+// Exported under a `_`-prefixed name for tests: every parser in the tree is
+// hardened enough that synthesising a real throw from outside is unreliable,
+// so the counter/stderr behaviour is asserted directly against this helper
+// (the two catch sites below are its only production callers).
+export function _noteParseFailure(file, err) {
+  const lang = _langOf(file);
+  _parseFailures.count++;
+  _parseFailures.byLanguage[lang] = (_parseFailures.byLanguage[lang] || 0) + 1;
+  const msg = String((err && (err.message || err)) || 'unknown error');
+  if (!_parseFailures.firstError) _parseFailures.firstError = { file, message: msg };
+  if (process.env.AGENTIC_SECURITY_IR_PARSE_DEBUG === '1') {
+    process.stderr.write(
+      `[ir] parse failed (${lang}): ${file}: ${(err && err.name) || 'Error'}: ${msg.split('\n')[0]}\n`,
+    );
+  }
+}
+
+// Cumulative per-process view of files whose parser threw. Exported so a
+// caller (bench harness, ir-stats sidecar, a future telemetry surface) can
+// tell "no findings because the language is absent" apart from "no findings
+// because every file of that language failed to parse".
+export function irParseFailures() {
+  return {
+    count: _parseFailures.count,
+    byLanguage: { ..._parseFailures.byLanguage },
+    firstError: _parseFailures.firstError ? { ..._parseFailures.firstError } : null,
+  };
+}
+
+// Test-only reset so a counter assertion doesn't inherit another test's state.
+export function _resetIrParseFailures() {
+  _parseFailures.count = 0;
+  _parseFailures.byLanguage = Object.create(null);
+  _parseFailures.firstError = null;
+}
+
 // Pick the Python parser based on env + capability probe.
 //   AGENTIC_SECURITY_PY_PARSER=cst   — force AST parser; error if unavailable
 //   AGENTIC_SECURITY_PY_PARSER=regex — force the legacy regex parser
@@ -31,7 +90,11 @@ import { computeSSA, isSSAEnabled } from './ssa.js';
 // corpus has run clean for two consecutive releases.
 function _chooseParser() {
   const choice = (process.env.AGENTIC_SECURITY_PY_PARSER || 'auto').toLowerCase();
-  if (choice === 'regex') return { parser: 'regex' };
+  // Explicitly forced regex is still a loss of `fn.calls` (no interprocedural
+  // Python taint). Record it so a caller that REQUIRES the CST path — the
+  // CVE-replay corpus gate — reports an environment error instead of scoring
+  // the resulting miss as a detection regression.
+  if (choice === 'regex') { noteParserDegradation('forced-regex-parser'); return { parser: 'regex' }; }
   if (choice === 'cst') {
     const cap = probePythonAvailable();
     if (!cap.ok) {
@@ -39,9 +102,14 @@ function _chooseParser() {
     }
     return { parser: 'cst' };
   }
-  // auto: prefer cst when capability is present.
+  // auto: prefer cst when capability is present. A regex selection here is a
+  // DEGRADATION, not a neutral choice — the regex parser emits no `fn.calls`,
+  // so Python loses interprocedural taint for this run. Record it so callers
+  // that require the CST path (the CVE-replay corpus gate) can distinguish an
+  // environment failure from a detection regression.
   const cap = probePythonAvailable();
-  return { parser: cap.ok ? 'cst' : 'regex' };
+  if (!cap.ok) { noteParserDegradation(`python-unavailable:${cap.reason}`); return { parser: 'regex' }; }
+  return { parser: 'cst' };
 }
 
 function _parsePythonFiles(pyEntries) {
@@ -55,6 +123,7 @@ function _parsePythonFiles(pyEntries) {
     if (process.env.AGENTIC_SECURITY_PY_PARSER_DEBUG === '1') {
       process.stderr.write('parser-py-cst: batch failed; falling back to regex parser\n');
     }
+    noteParserDegradation('batch-fallback-to-regex');
   }
   // Regex per-file parse — matches the old behavior exactly.
   return pyEntries.map(({ file, content }) => parsePythonFileRegex(file, content)).filter(Boolean);
@@ -67,28 +136,39 @@ export function buildProjectIR(fileContents) {
   const perFile = {};
   const pyBatch = [];
   for (const [file, code] of Object.entries(fileContents || {})) {
-    if (/\.(?:js|jsx|ts|tsx|mjs|cjs)$/i.test(file)) {
-      const ir = parseJsFile(file, code);
-      if (ir) perFile[file] = ir;
-    } else if (/\.py$/i.test(file)) {
-      // Defer Python files to a single batched subprocess call.
-      pyBatch.push({ file, content: code });
-    } else if (/\.cs$/i.test(file)) {
-      const ir = parseCSharpFile(file, code);
-      if (ir) perFile[file] = ir;
-    } else if (/\.kt$/i.test(file)) {
-      const ir = parseKotlinFile(file, code);
-      if (ir) perFile[file] = ir;
-    } else if (/\.go$/i.test(file)) {
-      const ir = parseGoFile(file, code);
-      if (ir) perFile[file] = ir;
-    } else if (/\.(?:php|phtml)$/i.test(file)) {
-      const ir = parsePhpFile(file, code);
-      if (ir) perFile[file] = ir;
-    } else if (/\.rb$/i.test(file)) {
-      const ir = parseRubyFile(file, code);
-      if (ir) perFile[file] = ir;
-    }
+    // Each branch is wrapped so one pathological file (e.g. a deeply nested
+    // expression tree that blows the regex-parser's recursive descent, seen
+    // in practice on real-world C# under Godot's proof-corpus run) can never
+    // abort IR construction for the entire project. A single parser failure
+    // degrades to "unparsed" for that file, exactly like a parser returning
+    // null — it does not zero out every other language's coverage.
+    try {
+      if (/\.(?:js|jsx|ts|tsx|mjs|cjs)$/i.test(file)) {
+        const ir = parseJsFile(file, code);
+        if (ir) perFile[file] = ir;
+      } else if (/\.py$/i.test(file)) {
+        // Defer Python files to a single batched subprocess call.
+        pyBatch.push({ file, content: code });
+      } else if (/\.cs$/i.test(file)) {
+        const ir = parseCSharpFile(file, code);
+        if (ir) perFile[file] = ir;
+      } else if (/\.kt$/i.test(file)) {
+        const ir = parseKotlinFile(file, code);
+        if (ir) perFile[file] = ir;
+      } else if (/\.go$/i.test(file)) {
+        const ir = parseGoFile(file, code);
+        if (ir) perFile[file] = ir;
+      } else if (/\.(?:php|phtml)$/i.test(file)) {
+        const ir = parsePhpFile(file, code);
+        if (ir) perFile[file] = ir;
+      } else if (/\.rb$/i.test(file)) {
+        const ir = parseRubyFile(file, code);
+        if (ir) perFile[file] = ir;
+      } else if (cppExtRe().test(file)) {
+        const ir = parseCppFile(file, code);
+        if (ir) perFile[file] = ir;
+      }
+    } catch (err) { _noteParseFailure(file, err); /* skip this file; never abort the batch */ }
   }
   if (pyBatch.length) {
     for (const ir of _parsePythonFiles(pyBatch)) {
@@ -112,32 +192,39 @@ export async function buildProjectIRAsync(fileContents) {
   const perFile = {};
   const pyBatch = [];
   for (const [file, code] of Object.entries(fileContents || {})) {
-    if (/\.(?:js|jsx|ts|tsx|mjs|cjs)$/i.test(file)) {
-      const ir = parseJsFile(file, code);
-      if (ir) perFile[file] = ir;
-    } else if (/\.py$/i.test(file)) {
-      pyBatch.push({ file, content: code });
-    } else if (/\.cs$/i.test(file)) {
-      const ir = parseCSharpFile(file, code);
-      if (ir) perFile[file] = ir;
-    } else if (/\.kt$/i.test(file)) {
-      const ir = parseKotlinFile(file, code);
-      if (ir) perFile[file] = ir;
-    } else if (/\.java$/i.test(file)) {
-      try {
-        const ir = await parseJavaFile(file, code);
+    // See buildProjectIR's comment: per-file try/catch so one pathological
+    // file can't abort IR construction for the whole project.
+    try {
+      if (/\.(?:js|jsx|ts|tsx|mjs|cjs)$/i.test(file)) {
+        const ir = parseJsFile(file, code);
         if (ir) perFile[file] = ir;
-      } catch { /* skip */ }
-    } else if (/\.go$/i.test(file)) {
-      const ir = parseGoFile(file, code);
-      if (ir) perFile[file] = ir;
-    } else if (/\.(?:php|phtml)$/i.test(file)) {
-      const ir = parsePhpFile(file, code);
-      if (ir) perFile[file] = ir;
-    } else if (/\.rb$/i.test(file)) {
-      const ir = parseRubyFile(file, code);
-      if (ir) perFile[file] = ir;
-    }
+      } else if (/\.py$/i.test(file)) {
+        pyBatch.push({ file, content: code });
+      } else if (/\.cs$/i.test(file)) {
+        const ir = parseCSharpFile(file, code);
+        if (ir) perFile[file] = ir;
+      } else if (/\.kt$/i.test(file)) {
+        const ir = parseKotlinFile(file, code);
+        if (ir) perFile[file] = ir;
+      } else if (/\.java$/i.test(file)) {
+        try {
+          const ir = await parseJavaFile(file, code);
+          if (ir) perFile[file] = ir;
+        } catch (err) { _noteParseFailure(file, err); }
+      } else if (/\.go$/i.test(file)) {
+        const ir = parseGoFile(file, code);
+        if (ir) perFile[file] = ir;
+      } else if (/\.(?:php|phtml)$/i.test(file)) {
+        const ir = parsePhpFile(file, code);
+        if (ir) perFile[file] = ir;
+      } else if (/\.rb$/i.test(file)) {
+        const ir = parseRubyFile(file, code);
+        if (ir) perFile[file] = ir;
+      } else if (cppExtRe().test(file)) {
+        const ir = parseCppFile(file, code);
+        if (ir) perFile[file] = ir;
+      }
+    } catch (err) { _noteParseFailure(file, err); /* skip this file; never abort the batch */ }
   }
   if (pyBatch.length) {
     for (const ir of _parsePythonFiles(pyBatch)) {
@@ -170,4 +257,4 @@ export function parsePythonFile(file, code) {
   return parsePythonFileRegex(file, code);
 }
 
-export { parseJsFile, parseJavaFile, parseCSharpFile, parseKotlinFile, parseGoFile, parsePhpFile, parseRubyFile, buildCallGraph, buildClassHierarchy, computeSSA, isSSAEnabled, probePythonAvailable };
+export { parseJsFile, parseJavaFile, parseCSharpFile, parseKotlinFile, parseGoFile, parsePhpFile, parseRubyFile, parseCppFile, buildCallGraph, buildClassHierarchy, computeSSA, isSSAEnabled, probePythonAvailable, pythonParserDegradation, resetPythonParserDegradation };

package/src/ir/ir-stats.js

@@ -0,0 +1,126 @@
+// IR parse-coverage instrumentation (proof-corpus Phase 0). Default OFF.
+//
+// Answers one question the scanner could not previously answer: for each
+// language, how many of the files we claim to support did we actually turn
+// into IR? That is the difference between recognising an extension and
+// supporting a language, and it is the headline metric of the proof corpus
+// bench (docs/PROOF_CORPUS_PRD.md §5.4).
+//
+// Enable by setting AGENTIC_SECURITY_IR_STATS to an output path. The sidecar
+// deliberately contains NO timestamp so two runs over identical input produce
+// byte-identical output and the bench can diff them.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// Mirrors the dispatch in ./index.js. When a language is added there, add it
+// here or its files silently report as out of scope.
+//
+// C/C++ was originally listed here BEFORE ./index.js dispatched it, so the
+// pre-parser baseline (inScope>0 / parsed=0) was measurable. ./index.js now
+// dispatches C/C++ via parser-cpp.js in both buildProjectIR and
+// buildProjectIRAsync, so these extensions report real parse coverage.
+const EXT_TO_LANG = {
+  js: 'javascript', jsx: 'javascript', ts: 'javascript', tsx: 'javascript',
+  mjs: 'javascript', cjs: 'javascript',
+  py: 'python',
+  java: 'java',
+  cs: 'csharp',
+  kt: 'kotlin',
+  go: 'go',
+  php: 'php', phtml: 'php',
+  rb: 'ruby',
+  c: 'cpp', cc: 'cpp', cpp: 'cpp', cxx: 'cpp',
+  h: 'cpp', hh: 'cpp', hpp: 'cpp', hxx: 'cpp',
+};
+
+// Cap the per-language failure list so a multi-million-line repo can't write a
+// gigabyte sidecar. The counts stay exact; only the sample is truncated.
+const _MAX_FAILURES_LISTED = 200;
+
+export function languageOfFile(file) {
+  if (typeof file !== 'string') return null;
+  const dot = file.lastIndexOf('.');
+  if (dot < 0 || dot === file.length - 1) return null;
+  return EXT_TO_LANG[file.slice(dot + 1).toLowerCase()] || null;
+}
+
+export function collectIrStats(fileContents, perFile, callGraph) {
+  const languages = {};
+  const ir = perFile || {};
+  const failuresByLang = {};
+
+  for (const file of Object.keys(fileContents || {})) {
+    const lang = languageOfFile(file);
+    if (!lang) continue;
+    if (!languages[lang]) {
+      languages[lang] = { inScope: 0, parsed: 0, functionless: 0, functions: 0, failures: [] };
+      failuresByLang[lang] = [];
+    }
+    const bucket = languages[lang];
+    bucket.inScope++;
+    const rec = ir[file];
+    // "parsed" means an IR record exists for the file — the parser returned
+    // something — independent of whether that file happens to declare any
+    // functions. A file with zero functions (an `__init__.py`, a constants
+    // module) is NOT a parse failure; it is parsed-but-functionless. Only the
+    // absence of an IR record at all is a genuine parse failure.
+    if (rec) {
+      bucket.parsed++;
+      const fnCount = Array.isArray(rec.functions) ? rec.functions.length : 0;
+      bucket.functions += fnCount;
+      if (fnCount === 0) bucket.functionless++;
+    } else {
+      failuresByLang[lang].push(file);
+    }
+  }
+
+  // Sort then truncate — a stable sample rather than whichever files happened
+  // to be enumerated first.
+  for (const [lang, list] of Object.entries(failuresByLang)) {
+    list.sort();
+    languages[lang].failures = list.slice(0, _MAX_FAILURES_LISTED);
+  }
+
+  const edges = (callGraph && Array.isArray(callGraph.edges)) ? callGraph.edges : [];
+  const resolvedEdges = edges.filter(e => e && e.callee).length;
+  const fnMap = callGraph && callGraph.functions;
+  const cgFunctions = fnMap && typeof fnMap.size === 'number'
+    ? fnMap.size
+    : (fnMap ? Object.keys(fnMap).length : 0);
+
+  const totals = { inScope: 0, parsed: 0, functions: 0 };
+  for (const b of Object.values(languages)) {
+    totals.inScope += b.inScope;
+    totals.parsed += b.parsed;
+    totals.functions += b.functions;
+  }
+
+  // Rebuild the languages object in sorted key order so JSON.stringify is stable.
+  const sortedLanguages = {};
+  for (const k of Object.keys(languages).sort()) sortedLanguages[k] = languages[k];
+
+  return {
+    languages: sortedLanguages,
+    callGraph: {
+      functions: cgFunctions,
+      edges: edges.length,
+      resolvedEdges,
+      unresolvedEdges: edges.length - resolvedEdges,
+    },
+    totals,
+  };
+}
+
+export function irStatsTarget() {
+  const v = process.env.AGENTIC_SECURITY_IR_STATS;
+  return (typeof v === 'string' && v.length > 0) ? v : null;
+}
+
+export function writeIrStats(target, stats) {
+  const dir = path.dirname(target);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(target, JSON.stringify(stats, null, 2) + '\n', 'utf8');
+}
+
+export const _internals = { EXT_TO_LANG, _MAX_FAILURES_LISTED };