@clear-capabilities/agentic-security-scanner 0.153.1 → 0.154.0

package/src/language/context.js

@@ -0,0 +1,199 @@
+// Project context for Haskell and Nix when a surface scans only part of a project (X-014).
+//
+// The MCP `scan_diff` / `verify_fix` / `synthesize_fix` tools and the LSP on-save scan hand the engine ONE file (or a
+// few). For Haskell and Nix that is not enough to be right: a taint flow crosses modules, and an effective NixOS value
+// is decided by the modules a configuration imports. So these surfaces add the import closure of the file(s) as
+// context, plus the manifests, read from disk, bounded in files and bytes. Findings are still reported only for the
+// files the caller asked about. Nothing here writes, executes or fetches anything.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { STATE_DIR_NAME } from '../posture/state-dir.js';
+import { isLanguageSource, isLanguageManifest, isLanguageExcludedPath, buildImportGraph, importClosure } from './discovery.js';
+import { planHaskellFix, validateHaskellFix, unifiedDiff as hsDiff } from './haskell-fix.js';
+import { planNixFix, validateNixFix, planNixUpgrade } from './nix-fix.js';
+import { planHaskellUpgrade, unifiedDiff as _hsDiff } from './haskell-fix.js';
+import { writeWithBackup } from './fix-lifecycle.js';
+import { recordExternalFix } from '../posture/fix-history.js';
+
+export const CONTEXT_BUDGETS = Object.freeze({ maxFiles: 600, maxBytes: 4 * 1024 * 1024, maxFileBytes: 400_000, maxDepth: 12 });
+const SKIP_DIRS = new Set(['node_modules', '.git', '.hg', 'dist-newstyle', '.stack-work', '.cabal-sandbox', '.direnv', 'result', STATE_DIR_NAME]);
+
+const norm = (p) => String(p).split(path.sep).join('/');
+export const isLanguagePath = (rel) => /\.(?:l?hs|hs-boot|hsc|nix)$/i.test(rel);
+
+/** Reads every Haskell/Nix source and manifest under `root`, bounded. Returns {files, manifests, truncated}. */
+export function loadLanguageProject(root, budgets = {}) {
+  const b = { ...CONTEXT_BUDGETS, ...budgets };
+  const files = {}; const manifests = {};
+  let count = 0; let bytes = 0; let truncated = false;
+  const walk = (dir, depth) => {
+    if (truncated || depth > b.maxDepth) { if (depth > b.maxDepth) truncated = true; return; }
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    entries.sort((x, y) => (x.name < y.name ? -1 : 1));
+    for (const e of entries) {
+      if (e.isSymbolicLink()) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) walk(full, depth + 1); continue; }
+      if (!e.isFile()) continue;
+      const rel = norm(path.relative(root, full));
+      const src = isLanguageSource(rel); const man = isLanguageManifest(rel);
+      if (!(src || man) || isLanguageExcludedPath(rel)) continue;
+      let st; try { st = fs.statSync(full); } catch { continue; }
+      if (st.size > b.maxFileBytes) continue;
+      if (count >= b.maxFiles || bytes + st.size > b.maxBytes) { truncated = true; return; }
+      try { (src ? files : manifests)[rel] = fs.readFileSync(full, 'utf8'); count++; bytes += st.size; } catch { /* unreadable: skipped */ }
+    }
+  };
+  walk(root, 0);
+  return { files, manifests, truncated };
+}
+
+/**
+ * Expands a partial scan with the language context it needs. `fileContents` entries always win over disk. With no
+ * Haskell/Nix file in `fileContents` the inputs come back unchanged (same objects), so other languages are untouched.
+ * @returns {{fileContents:object, depFileContents:object, context:string[], truncated:boolean}}
+ */
+export function withLanguageContext(root, fileContents, depFileContents = {}, budgets = {}) {
+  const wanted = Object.keys(fileContents || {}).map(norm).filter(isLanguagePath);
+  if (!wanted.length || !root) return { fileContents, depFileContents, context: [], truncated: false };
+  const proj = loadLanguageProject(root, budgets);
+  const merged = { ...proj.files, ...fileContents };
+  const { graph } = buildImportGraph(merged);
+  const need = new Set();
+  for (const f of wanted) { need.add(f); for (const d of importClosure(graph, f).files) need.add(d); }
+  // importers matter too: a changed callee can make a caller (un)safe
+  const rev = new Map();
+  for (const [k, ds] of graph) for (const d of ds) { if (!rev.has(d)) rev.set(d, []); rev.get(d).push(k); }
+  let frontier = [...wanted];
+  while (frontier.length) { const next = []; for (const f of frontier) for (const r of rev.get(f) || []) if (!need.has(r)) { need.add(r); next.push(r); } frontier = next; }
+  const out = { ...fileContents };
+  const context = [];
+  for (const k of need) if (!(k in out) && k in proj.files) { out[k] = proj.files[k]; context.push(k); }
+  return { fileContents: out, depFileContents: { ...proj.manifests, ...depFileContents }, context: context.sort(), truncated: proj.truncated };
+}
+
+/** The language fixer a finding belongs to, or null. */
+export function languageOfFinding(f) {
+  const file = String((f && (f.file || (f.sink && f.sink.file))) || '');
+  if (/\.l?hs$|\.hs-boot$|\.hsc$/i.test(file)) return 'haskell';
+  if (/\.nix$/i.test(file)) return 'nix';
+  return null;
+}
+
+/**
+ * A READ-ONLY fix preview for a Haskell/Nix finding: the planned patch, its tier, and what the verification gates say.
+ * Never writes. `files` is the project's language sources (see loadLanguageProject).
+ */
+export async function languageFixPreview(finding, files, { apply = false, root = null } = {}) {
+  const lang = languageOfFinding(finding);
+  if (!lang) return { ok: false, status: 'unsupported', reason: 'not a Haskell or Nix finding' };
+  const plan = lang === 'haskell' ? planHaskellFix(finding, files) : planNixFix(finding, files);
+  if (!plan || plan.ok === false) return { ok: false, status: (plan && plan.status) || 'unsupported', tier: (plan && plan.tier) || null, reason: (plan && plan.reason) || 'no deterministic fix', proposal: (plan && plan.proposal) || null };
+  let res;
+  try { res = lang === 'haskell' ? await validateHaskellFix(finding, { files, apply, root }) : await validateNixFix(finding, { files, apply, root }); } catch (e) { res = { status: 'blocked', reason: `verification failed: ${String((e && e.message) || e)}` }; }
+  return {
+    ok: res.status === 'verified' || res.status === 'applied',
+    status: res.status, applied: res.applied === true, backup: res.backup || null,
+    label: plan.label || null, tier: res.tier || plan.tier || null,
+    file: plan.file, before: plan.before, after: plan.after,
+    diff: res.preview || hsDiff(plan.file, plan.before, plan.after),
+    gates: res.gates || null, reason: (res.status === 'verified' || res.status === 'applied') ? null : (res.reason || null),
+    explanation: plan.explanation || null, consequences: res.consequences || plan.consequences || [],
+  };
+}
+
+/** A minimal line-range text edit turning `before` into `after` (for an LSP/editor workspace edit). */
+export function minimalEdit(before, after) {
+  const a = before.split('\n'); const b = after.split('\n');
+  let i = 0; while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  let ea = a.length; let eb = b.length;
+  while (ea > i && eb > i && a[ea - 1] === b[eb - 1]) { ea--; eb--; }
+  const endOfDoc = { line: a.length - 1, character: a[a.length - 1].length };
+  if (i >= a.length) return { range: { start: endOfDoc, end: endOfDoc }, newText: `\n${b.slice(i).join('\n')}` };   // appended lines
+  if (ea === a.length) return { range: { start: { line: i, character: 0 }, end: endOfDoc }, newText: b.slice(i, eb).join('\n') };
+  return { range: { start: { line: i, character: 0 }, end: { line: ea, character: 0 } }, newText: eb > i ? `${b.slice(i, eb).join('\n')}\n` : '' };
+}
+
+// ── model-assisted workflows ─────────────────────────────────────────────────
+import crypto from 'node:crypto';
+import { computeLanguageDigests } from './discovery.js';
+const _digestMemo = new WeakMap();
+
+/**
+ * A digest of `file` and everything its verdict depends on: the modules it imports, every manifest and lock file.
+ * Used where a cached model verdict must be invalidated when a DEPENDENCY changes, not only the file itself. For a
+ * non-language file the plain content hash is returned.
+ */
+export function languageClosureDigest(fileContents, file) {
+  if (!fileContents || !file) return '';
+  if (!isLanguagePath(file)) return crypto.createHash('sha256').update(String(fileContents[file] ?? '')).digest('hex').slice(0, 32);
+  let memo = _digestMemo.get(fileContents);
+  if (!memo) {
+    const manifests = {};
+    for (const k of Object.keys(fileContents)) if (isLanguageManifest(k)) manifests[k] = fileContents[k];
+    memo = computeLanguageDigests(fileContents, { manifests }).digests;
+    _digestMemo.set(fileContents, memo);
+  }
+  return String(memo.get(norm(file)) || crypto.createHash('sha256').update(String(fileContents[file] ?? '')).digest('hex')).slice(0, 32);
+}
+
+/**
+ * The extra context a model needs to judge a Haskell/Nix finding whose evidence is NOT on the reported line: the other
+ * files on its evidence chain and the files that decided a configuration value. Only files the finding itself names are
+ * included (never a project dump), a few lines each, bounded in total. Returns [{file, startLine, text}].
+ */
+export function languagePromptExtras(finding, fileContents, { maxFiles = 4, windowLines = 5, maxChars = 3000 } = {}) {
+  if (!finding || !fileContents || !isLanguagePath(String(finding.file || ''))) return [];
+  const want = []; const seen = new Set([finding.file]);
+  for (const step of Array.isArray(finding.chain) ? finding.chain : []) {
+    if (step && typeof step.file === 'string' && !seen.has(step.file) && typeof fileContents[step.file] === 'string') { seen.add(step.file); want.push({ file: step.file, line: Number.isInteger(step.line) ? step.line : 1 }); }
+  }
+  for (const f of Array.isArray(finding.controlFiles) ? finding.controlFiles : []) {
+    if (typeof f === 'string' && !seen.has(f) && typeof fileContents[f] === 'string') { seen.add(f); want.push({ file: f, line: 1 }); }
+  }
+  const out = []; let used = 0;
+  for (const w of want.slice(0, maxFiles)) {
+    const lines = fileContents[w.file].split('\n');
+    const start = Math.max(0, w.line - 1 - windowLines); const end = Math.min(lines.length, w.line + windowLines);
+    const text = lines.slice(start, end).map((l, i) => `${start + i + 1}: ${l}`).join('\n');
+    if (used + text.length > maxChars) break;
+    used += text.length; out.push({ file: w.file, startLine: start + 1, text });
+  }
+  return out;
+}
+
+// ── dependency upgrades ─────────────────────────────────────────────────────────
+/** Whether a finding is a dependency finding the language upgrade planners can act on. */
+export function isLanguageDependencyFinding(f) {
+  return !!f && f.family === 'vulnerable-dep' && (f.ecosystem === 'hackage' || (f.ecosystem === 'nix' && /(^|\/)flake\.nix$/.test(String(f.file || ''))));
+}
+
+/**
+ * A dependency fix for a Hackage dependency (raise the declared constraint to a fixed version) or a flake input (point its
+ * ref at `toRef`). Both are SOURCE edits whose real effect needs a re-resolve or a re-lock the scanner will not run, so they
+ * carry a tier that says so: nothing here claims the dependency is fixed until it has been re-resolved.
+ */
+export async function languageUpgradePreview(finding, files, { apply = false, root = null, toRef = null } = {}) {
+  let plan;
+  if (finding.ecosystem === 'hackage') {
+    plan = planHaskellUpgrade({ name: finding.package, fixedIn: Array.isArray(finding.fixedIn) ? finding.fixedIn : [], unfixed: !finding.fixedIn, file: finding.declaringFile || finding.file, line: finding.declaringLine }, files);
+    if (!plan.ok) return { ok: false, status: plan.status || 'blocked', tier: 'blocked', reason: plan.reason };
+    plan = { ...plan, file: plan.file, tier: plan.status === 'fixed' ? 'full-source-edit' : 'constraints-only (not re-resolved)', label: plan.status === 'fixed' ? 'FULL' : 'WORKAROUND', note: plan.note || null,
+      explanation: `Raise the declared bound of ${finding.package} from ${plan.from} to ${plan.to}.`, consequences: ['Re-resolve (for example `cabal build --dry-run`) and rescan: this edit changes a constraint, not the resolved version.'] };
+  } else {
+    if (!toRef) return { ok: false, status: 'blocked', tier: 'blocked', reason: 'a flake input fix needs a target: pass --to <ref or revision>' };
+    const up = planNixUpgrade({ files, input: finding.package, toRef });
+    if (!up.ok) return { ok: false, status: up.status || 'blocked', tier: up.tier || 'blocked', reason: up.reason };
+    plan = { ...up, file: up.edits[0].file, before: up.edits[0].before, after: up.edits[0].after, label: 'WORKAROUND', note: up.note || null, explanation: `Point input ${up.input} at ${up.to} (was ${up.from}).`, consequences: up.consequences || [] };
+  }
+  const out = { ok: true, status: plan.status, tier: plan.tier, label: plan.label, file: plan.file, before: plan.before, after: plan.after, diff: plan.preview || hsDiff(plan.file, plan.before, plan.after), explanation: plan.explanation, consequences: [...(plan.consequences || []), ...(plan.note ? [plan.note] : [])], applied: false, gates: { path: { ok: true }, syntax: { ok: true }, rescan: { ran: false }, compile: { ran: false } } };
+  if (apply) {
+    if (!root) return { ...out, ok: false, status: 'blocked', reason: 'apply requires a root directory' };
+    out.backup = writeWithBackup(root, plan.file, plan.before, plan.after);
+    out.applied = true; out.status = 'applied';
+    try { await recordExternalFix({ scanRoot: root, file: plan.file, originalContent: plan.before, newContent: plan.after, findingId: finding.id, ruleId: finding.osvId || 'dependency-upgrade', vuln: finding.vuln || 'Vulnerable dependency', stableId: finding.stableId || null, fixLabel: plan.label, verification: { tier: plan.tier, rescan: 'not-run' }, backup: out.backup }); } catch { /* the ledger is best effort here */ }
+  }
+  return out;
+}

package/src/language/contracts.js

@@ -0,0 +1,339 @@
+// Language pipeline contracts for Haskell and Nix (CORE-003).
+//
+// Three jobs, all additive over the existing finding / component / scan-health /
+// DataFlowGraph shapes (no required field is removed or renamed):
+//
+//   1. METADATA. Optional `language`, `capability`, `evidenceKind`, `scope`,
+//      `uncertainty` and `originalLocation` fields, validated by
+//      validateLanguageFinding / validateLanguageComponent. `parser`/`family`
+//      stay required exactly as before.
+//   2. PRODUCERS. Every language analyzer is registered (with the shared
+//      pipeline/producer-registry.js as well as a local table that carries the
+//      capability and evidence kinds). A finding from an unregistered producer
+//      is dropped from the result and recorded as an `unregistered-producer`
+//      outcome, so it cannot silently reach a verdict.
+//   3. COVERAGE OUTCOMES. runLanguageAnalysis drives registered adapters over a
+//      file set and records, per file and per analyzer, exactly one of
+//      analyzed / excluded / unresolved / failed / timed_out / missing_grammar.
+//      reconcileLanguageLedger proves those counts add up to the real inputs.
+//      languageHealth turns the ledger into scan-health conditions.
+//
+// Nothing here executes scanned code: adapters are caller-supplied functions
+// over file text.
+
+import { isRegisteredProducer, registerProducer } from '../pipeline/producer-registry.js';
+import { isLanguageExcludedPath, isLanguageSource, languageOf } from './discovery.js';
+
+export const LANGUAGE_CONTRACT_VERSION = 1;
+
+export const LANGUAGES = Object.freeze(['haskell', 'nix']);
+
+/**
+ * `type` of a supply-chain entry that is a build/fetch/cache TRUST finding rather than an
+ * advisory match (NIX-005). It travels in the same `supplyChain` bucket as `vulnerable_dep`,
+ * so SCA policy, SCA verdicts and scan health read it without a side channel.
+ */
+export const BUILD_TRUST_TYPE = 'nix_build_trust';
+
+// Evidence kinds. For Nix, a script generated by a derivation, the static
+// configuration it declares, and observed runtime state are different claims
+// and must never share a kind.
+export const EVIDENCE_KINDS = Object.freeze([
+  'source', 'manifest', 'lock', 'config', 'generated-script', 'runtime',
+]);
+
+export const CAPABILITIES = Object.freeze([
+  'parse', 'sast', 'taint', 'sca', 'config', 'iac', 'privacy', 'route-inventory',
+]);
+
+export const FILE_STATUSES = Object.freeze([
+  'analyzed', 'excluded', 'unresolved', 'failed', 'timed_out', 'missing_grammar',
+]);
+
+// Why an outcome was recorded. `unresolved-branch` is a file that WAS analyzed
+// but left a branch the adapter could not resolve; it is reported on top of the
+// file's status, not instead of it.
+export const OUTCOME_KINDS = Object.freeze([
+  'missing-grammar', 'adapter-exception', 'unresolved-branch', 'timeout',
+  'unregistered-producer', 'excluded-path', 'unsupported-language',
+]);
+
+export const UNCERTAINTY_KINDS = Object.freeze([
+  'unresolved-import', 'unresolved-branch', 'generated-source', 'preprocessed', 'partial-parse',
+  // a call whose target is not known (higher-order parameter, unbound name, typeclass without a visible
+  // instance) or whose code is not analysed (foreign function): taint is widened across it, never dropped
+  'unresolved-target', 'foreign-boundary',
+  // the analysed library version is not one the model was written against: results are best-effort
+  'untested-model',
+]);
+
+// ── 2. producers ───────────────────────────────────────────────────────────
+
+const _producers = new Map();
+
+/**
+ * @param {object} def
+ * @param {string} def.id            unique, `language:<name>` by convention
+ * @param {string} def.language      one of LANGUAGES
+ * @param {string} def.capability    one of CAPABILITIES
+ * @param {string[]} [def.evidenceKinds]  subset of EVIDENCE_KINDS it may emit
+ * @param {string} [def.version]
+ */
+export function registerLanguageProducer(def) {
+  if (!def || typeof def !== 'object') throw new Error('registerLanguageProducer: definition required');
+  const { id, language, capability, evidenceKinds = ['source'], version = '1' } = def;
+  if (typeof id !== 'string' || !id) throw new Error('registerLanguageProducer: id required');
+  if (!LANGUAGES.includes(language)) throw new Error(`registerLanguageProducer: "${id}" unknown language "${language}"`);
+  if (!CAPABILITIES.includes(capability)) throw new Error(`registerLanguageProducer: "${id}" unknown capability "${capability}"`);
+  for (const k of evidenceKinds) {
+    if (!EVIDENCE_KINDS.includes(k)) throw new Error(`registerLanguageProducer: "${id}" unknown evidence kind "${k}"`);
+  }
+  if (_producers.has(id)) throw new Error(`registerLanguageProducer: duplicate producer id "${id}"`);
+  _producers.set(id, Object.freeze({ id, language, capability, evidenceKinds: Object.freeze([...evidenceKinds]), version }));
+  if (!isRegisteredProducer(id)) registerProducer({ id, version, phase: 'sast', languages: [language] });
+  return _producers.get(id);
+}
+
+export function isRegisteredLanguageProducer(id) {
+  return _producers.has(id);
+}
+
+export function listLanguageProducers() {
+  return [..._producers.values()];
+}
+
+/** Test-only. */
+export function _resetLanguageProducersForTests() {
+  _producers.clear();
+}
+
+// ── 1. metadata + validators ───────────────────────────────────────────────
+
+const REQUIRED_FINDING_FIELDS = ['id', 'severity', 'file', 'line', 'vuln', 'cwe', 'description', 'remediation', 'parser', 'family'];
+const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+
+function validLocation(loc) {
+  return !!loc && typeof loc === 'object'
+    && Number.isInteger(loc.line) && loc.line >= 1
+    && (loc.column === undefined || (Number.isInteger(loc.column) && loc.column >= 0))
+    && (loc.file === undefined || typeof loc.file === 'string');
+}
+
+function validateLanguageFields(obj, errors, label) {
+  if (obj.language !== undefined && !LANGUAGES.includes(obj.language)) errors.push(`${label}: unknown language "${obj.language}"`);
+  if (obj.capability !== undefined && !CAPABILITIES.includes(obj.capability)) errors.push(`${label}: unknown capability "${obj.capability}"`);
+  if (obj.evidenceKind !== undefined && !EVIDENCE_KINDS.includes(obj.evidenceKind)) errors.push(`${label}: unknown evidenceKind "${obj.evidenceKind}"`);
+  if (obj.scope !== undefined) {
+    const s = obj.scope;
+    if (!s || typeof s !== 'object' || Array.isArray(s)) errors.push(`${label}: scope must be an object`);
+    else {
+      for (const k of ['target', 'configuration', 'component']) {
+        if (s[k] !== undefined && s[k] !== null && typeof s[k] !== 'string') errors.push(`${label}: scope.${k} must be a string or null`);
+      }
+    }
+  }
+  if (obj.uncertainty !== undefined) {
+    if (!Array.isArray(obj.uncertainty)) errors.push(`${label}: uncertainty must be an array`);
+    else {
+      for (const u of obj.uncertainty) {
+        if (!u || !UNCERTAINTY_KINDS.includes(u.kind)) errors.push(`${label}: unknown uncertainty kind "${u && u.kind}"`);
+      }
+    }
+  }
+  if (obj.originalLocation !== undefined && !validLocation(obj.originalLocation)) errors.push(`${label}: originalLocation needs an integer line >= 1`);
+}
+
+/**
+ * Validates the finding contract. The legacy required fields are unchanged, so
+ * an output written before this contract existed still validates; the language
+ * fields are checked only when present. `producer`, when present, must be
+ * registered.
+ */
+export function validateLanguageFinding(f) {
+  const errors = [];
+  if (!f || typeof f !== 'object') return { valid: false, errors: ['finding must be an object'] };
+  for (const k of REQUIRED_FINDING_FIELDS) {
+    if (f[k] === undefined || f[k] === null || f[k] === '') {
+      // `line` may legitimately be null for struct detectors, but then it is not suppressible; keep it required here.
+      errors.push(`missing required field "${k}"`);
+    }
+  }
+  if (f.severity !== undefined && !SEVERITIES.includes(f.severity)) errors.push(`invalid severity "${f.severity}"`);
+  validateLanguageFields(f, errors, 'finding');
+  if (f.producer !== undefined && !isRegisteredLanguageProducer(f.producer)) errors.push(`finding: producer "${f.producer}" is not registered`);
+  return { valid: errors.length === 0, errors };
+}
+
+/** Component contract (SBOM/inventory entry). Legacy `name` + `version` stay required. */
+export function validateLanguageComponent(c) {
+  const errors = [];
+  if (!c || typeof c !== 'object') return { valid: false, errors: ['component must be an object'] };
+  if (typeof c.name !== 'string' || !c.name) errors.push('missing required field "name"');
+  if (c.version !== undefined && c.version !== null && typeof c.version !== 'string') errors.push('component: version must be a string or null');
+  validateLanguageFields(c, errors, 'component');
+  return { valid: errors.length === 0, errors };
+}
+
+/** Adds language metadata to a finding without overwriting detector-set values. */
+export function withLanguageMetadata(finding, meta = {}) {
+  const out = { ...finding };
+  const lang = out.language ?? meta.language ?? languageOf(out.file || '');
+  if (lang) out.language = lang;
+  for (const k of ['capability', 'evidenceKind', 'scope', 'uncertainty', 'originalLocation', 'producer']) {
+    if (out[k] === undefined && meta[k] !== undefined) out[k] = meta[k];
+  }
+  return out;
+}
+
+// ── 3. coverage outcomes ───────────────────────────────────────────────────
+
+function emptyCounts() {
+  return { discovered: 0, analyzed: 0, excluded: 0, unresolved: 0, failed: 0, timedOut: 0, missingGrammar: 0 };
+}
+
+const STATUS_COUNT_KEY = {
+  analyzed: 'analyzed', excluded: 'excluded', unresolved: 'unresolved',
+  failed: 'failed', timed_out: 'timedOut', missing_grammar: 'missingGrammar',
+};
+
+function withTimeout(promiseLike, ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return Promise.resolve(promiseLike);
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(Object.assign(new Error(`timed out after ${ms}ms`), { code: 'LANG_TIMEOUT' })), ms);
+  });
+  return Promise.race([Promise.resolve(promiseLike), timeout]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * Drives registered adapters over a file set.
+ *
+ * @param {object} input
+ * @param {Record<string,string>} input.files  rel path -> content (the real inputs)
+ * @param {Array<{id:string, language:string, hasGrammar?:()=>boolean,
+ *   analyze:(file:string, content:string)=>({findings?:object[], unresolved?:object[]}|Promise<object>)}>} input.adapters
+ * @param {number} [input.timeoutMs]
+ * @returns {Promise<{findings:object[], ledger:object, outcomes:object[]}>}
+ *   ledger.byFile[file][analyzerId] is a status string; ledger.byAnalyzer[id] holds counts.
+ */
+export async function runLanguageAnalysis({ files = {}, adapters = [], timeoutMs = 0 } = {}) {
+  const findings = [];
+  const outcomes = [];
+  const byFile = {};
+  const byAnalyzer = {};
+  const discoveredFiles = [];
+  const excludedFiles = [];
+
+  for (const a of adapters) byAnalyzer[a.id] = { language: a.language, ...emptyCounts() };
+
+  for (const rel of Object.keys(files).sort()) {
+    const lang = languageOf(rel);
+    if (!lang || !isLanguageSource(rel)) continue; // manifests and unrelated files are not analyzer inputs
+    if (isLanguageExcludedPath(rel)) {
+      excludedFiles.push(rel);
+      outcomes.push({ kind: 'excluded-path', file: rel, language: lang });
+      continue;
+    }
+    discoveredFiles.push(rel);
+    byFile[rel] = {};
+    const applicable = adapters.filter((a) => a.language === lang);
+    if (!applicable.length) {
+      outcomes.push({ kind: 'unsupported-language', file: rel, language: lang });
+      continue;
+    }
+    for (const a of applicable) {
+      const counts = byAnalyzer[a.id];
+      counts.discovered += 1;
+      const setStatus = (status) => { byFile[rel][a.id] = status; counts[STATUS_COUNT_KEY[status]] += 1; };
+
+      if (!isRegisteredLanguageProducer(a.id)) {
+        // Unregistered producers never contribute findings; the file is unresolved, not clean.
+        setStatus('unresolved');
+        outcomes.push({ kind: 'unregistered-producer', file: rel, analyzer: a.id, language: lang });
+        continue;
+      }
+      if (typeof a.hasGrammar === 'function' && !a.hasGrammar()) {
+        setStatus('missing_grammar');
+        outcomes.push({ kind: 'missing-grammar', file: rel, analyzer: a.id, language: lang });
+        continue;
+      }
+      let result;
+      try {
+        result = await withTimeout(a.analyze(rel, files[rel]), timeoutMs);
+      } catch (err) {
+        if (err && err.code === 'LANG_TIMEOUT') {
+          setStatus('timed_out');
+          outcomes.push({ kind: 'timeout', file: rel, analyzer: a.id, language: lang, detail: String(err.message) });
+        } else {
+          setStatus('failed');
+          outcomes.push({ kind: 'adapter-exception', file: rel, analyzer: a.id, language: lang, detail: String((err && err.message) || err) });
+        }
+        continue;
+      }
+      const producer = _producers.get(a.id);
+      for (const f of (result && result.findings) || []) {
+        findings.push(withLanguageMetadata(f, { language: lang, capability: producer.capability, producer: a.id }));
+      }
+      const unresolved = (result && result.unresolved) || [];
+      for (const u of unresolved) {
+        outcomes.push({ kind: 'unresolved-branch', file: rel, analyzer: a.id, language: lang, line: Number.isInteger(u.line) ? u.line : null, detail: u.reason || null });
+      }
+      // A file with an unresolved branch was read but is not fully understood.
+      setStatus(unresolved.length ? 'unresolved' : 'analyzed');
+    }
+  }
+
+  return { findings, ledger: { byFile, byAnalyzer, discoveredFiles, excludedFiles }, outcomes };
+}
+
+/**
+ * Checks that ledger counts reconcile with the real inputs: every discovered
+ * file has exactly one status per applicable analyzer, per-analyzer counts equal
+ * the sum of its statuses, and discovered + excluded equals the language
+ * sources actually present in `files`.
+ * @returns {{ok:boolean, errors:string[]}}
+ */
+export function reconcileLanguageLedger(ledger, files) {
+  const errors = [];
+  const real = Object.keys(files).filter((k) => isLanguageSource(k));
+  const accounted = new Set([...ledger.discoveredFiles, ...ledger.excludedFiles]);
+  if (accounted.size !== ledger.discoveredFiles.length + ledger.excludedFiles.length) errors.push('a file is both discovered and excluded');
+  for (const k of real) if (!accounted.has(k)) errors.push(`input file "${k}" is not accounted for`);
+  for (const k of accounted) if (!real.includes(k)) errors.push(`ledger file "${k}" is not a real input`);
+
+  for (const [id, c] of Object.entries(ledger.byAnalyzer)) {
+    const sum = c.analyzed + c.excluded + c.unresolved + c.failed + c.timedOut + c.missingGrammar;
+    if (sum !== c.discovered) errors.push(`analyzer "${id}": statuses sum to ${sum}, discovered ${c.discovered}`);
+    let fromFiles = 0;
+    for (const row of Object.values(ledger.byFile)) if (row[id] !== undefined) fromFiles += 1;
+    if (fromFiles !== c.discovered) errors.push(`analyzer "${id}": ${fromFiles} per-file rows, discovered ${c.discovered}`);
+  }
+  for (const [file, row] of Object.entries(ledger.byFile)) {
+    for (const [id, status] of Object.entries(row)) {
+      if (!FILE_STATUSES.includes(status)) errors.push(`file "${file}" analyzer "${id}": unknown status "${status}"`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Converts a run's ledger + outcomes into the shape computeScanHealth accepts as
+ * `languageCoverage`: totals plus human-readable conditions. Only an
+ * all-analyzed run with no unresolved branch is `complete`.
+ */
+export function languageHealth({ ledger, outcomes }) {
+  const totals = emptyCounts();
+  for (const c of Object.values(ledger.byAnalyzer)) {
+    for (const k of Object.keys(totals)) totals[k] += c[k];
+  }
+  totals.excluded += ledger.excludedFiles.length;
+  const byKind = {};
+  for (const o of outcomes) byKind[o.kind] = (byKind[o.kind] || 0) + 1;
+  const conditions = [];
+  if (byKind['missing-grammar']) conditions.push(`${byKind['missing-grammar']} language file(s) skipped: grammar unavailable`);
+  if (byKind['adapter-exception']) conditions.push(`${byKind['adapter-exception']} language adapter exception(s)`);
+  if (byKind['timeout']) conditions.push(`${byKind['timeout']} language file(s) timed out`);
+  if (byKind['unresolved-branch']) conditions.push(`${byKind['unresolved-branch']} unresolved language branch(es)`);
+  if (byKind['unregistered-producer']) conditions.push(`${byKind['unregistered-producer']} result(s) from an unregistered language producer were discarded`);
+  return { schemaVersion: LANGUAGE_CONTRACT_VERSION, totals, byKind, conditions };
+}