@quantakrypto/core 0.3.0 → 0.4.0

package/src/remediate-request.ts

@@ -0,0 +1,52 @@
+/**
+ * Remediation rubric, fix schema, and request-bundle builder — offline and
+ * deterministic, shared by `@quantakrypto/agent` (which prompts a model with
+ * them) and the MCP `remediate_findings` tool (which hands the bundle to the
+ * host agent). Keeping them here means the MCP server stays offline/key-free.
+ */
+import type { Finding } from "./types.js";
+import type { ContextLevel, RedactedContext } from "./agent-types.js";
+import { buildContext } from "./redact.js";
+
+/** The system rubric for a fix proposal. */
+export const REMEDIATE_RUBRIC =
+  "You are a post-quantum cryptography migration engineer. Given the FULL content " +
+  "of one source file plus a finding describing classical (quantum-vulnerable) " +
+  "cryptography in it, return the FULL corrected file content that removes the " +
+  "flagged usage, migrating to a post-quantum or hybrid construction " +
+  "(ML-KEM-768 / ML-DSA-65, hybrid X25519MLKEM768) where a safe replacement " +
+  "exists. Change as little as possible; preserve all other code and formatting " +
+  "exactly. If you cannot safely fix it, return newContent identical to the " +
+  "input. NEVER invent or alter secrets/keys. After proposing, VERIFY with the " +
+  "verify_fix tool and keep only fixes that clear the finding.";
+
+/** JSON Schema every fix proposal must satisfy. */
+export const FIX_REQUEST_SCHEMA: Record<string, unknown> = {
+  type: "object",
+  required: ["path", "newContent", "explanation"],
+  properties: {
+    path: { type: "string" },
+    newContent: { type: "string" },
+    explanation: { type: "string" },
+  },
+};
+
+/** A remediation request bundle for the host agent. */
+export interface RemediateRequest {
+  instructions: string;
+  schema: Record<string, unknown>;
+  contexts: RedactedContext[];
+}
+
+/** Build a remediation request bundle (offline; metadata level unless `readContent`). */
+export function buildRemediateRequest(
+  findings: readonly Finding[],
+  level: ContextLevel = "metadata",
+  readContent?: (finding: Finding) => string,
+): RemediateRequest {
+  const effectiveLevel: ContextLevel = readContent ? level : "metadata";
+  const contexts = findings.map((f) =>
+    buildContext(f, effectiveLevel, readContent ? readContent(f) : ""),
+  );
+  return { instructions: REMEDIATE_RUBRIC, schema: FIX_REQUEST_SCHEMA, contexts };
+}

package/src/remediation.ts

@@ -96,6 +96,31 @@ export function remediationText(algorithm: AlgorithmFamily): string {
   return REMEDIATIONS[algorithm].recommendation;
 }
 
+/**
+ * True when a family's PQC replacement is a KEM — i.e. it's used for
+ * confidentiality / key-agreement (and is therefore harvest-now-decrypt-later
+ * exposed). RSA is in both this set and {@link isSignatureFamily}. Single
+ * source of truth for the family→target taxonomy used by tier guidance and the
+ * multi-family remediation composer.
+ */
+export function isConfidentialityFamily(algorithm: AlgorithmFamily): boolean {
+  return (
+    algorithm === "RSA" ||
+    algorithm === "ECDH" ||
+    algorithm === "DH" ||
+    algorithm === "X25519" ||
+    algorithm === "X448" ||
+    algorithm === "ECIES"
+  );
+}
+
+/** True when a family's PQC replacement is a signature scheme (ML-DSA / SLH-DSA). */
+export function isSignatureFamily(algorithm: AlgorithmFamily): boolean {
+  return (
+    algorithm === "RSA" || algorithm === "ECDSA" || algorithm === "EdDSA" || algorithm === "DSA"
+  );
+}
+
 /* -------------------------------------------------------------------------- */
 /* Security-tier guidance (CNSA 2.0 Category 5) + stateful HBS (SP 800-208)     */
 /* -------------------------------------------------------------------------- */
@@ -135,14 +160,7 @@ export function remediationForTier(
   const base = REMEDIATIONS[algorithm];
   const params = TIER_PARAMS[tier];
   // Confidentiality families lean on the KEM; signature families on the signer.
-  const isConfidentiality =
-    algorithm === "RSA" ||
-    algorithm === "ECDH" ||
-    algorithm === "DH" ||
-    algorithm === "X25519" ||
-    algorithm === "X448" ||
-    algorithm === "ECIES";
-  const primary = isConfidentiality ? params.kem : params.signature;
+  const primary = isConfidentialityFamily(algorithm) ? params.kem : params.signature;
   return {
     algorithm,
     recommendation: `${base.recommendation} — ${tier}: ${primary}`,
@@ -167,7 +185,5 @@ export const STATEFUL_HBS_NOTE =
 /** True when stateful HBS (SP 800-208) is a reasonable alternative for a family. */
 export function statefulHbsApplies(algorithm: AlgorithmFamily): boolean {
   // Signature families only — LMS/XMSS are signatures, not KEMs.
-  return (
-    algorithm === "RSA" || algorithm === "ECDSA" || algorithm === "EdDSA" || algorithm === "DSA"
-  );
+  return isSignatureFamily(algorithm);
 }

package/src/report.ts

@@ -6,6 +6,7 @@
 import type { Finding, RuleMeta, ScanResult, Severity } from "./types.js";
 import { VERSION } from "./version.js";
 import { SEVERITY_ORDER, sarifLevel } from "./severity.js";
+import { ANALYZABLE_LANGUAGES_LABEL } from "./detect-utils.js";
 
 /** Minimal SARIF 2.1.0 log shape (kept permissive on purpose). */
 export interface SarifLog {
@@ -253,6 +254,8 @@ export function toJson(result: ScanResult, opts?: ReportOptions): Record<string,
     startedAt: result.startedAt,
     finishedAt: result.finishedAt,
     filesScanned: result.filesScanned,
+    ...(result.analyzedFiles !== undefined ? { analyzedFiles: result.analyzedFiles } : {}),
+    ...(result.diagnostics ? { diagnostics: result.diagnostics } : {}),
     inventory: {
       readinessScore: result.inventory.readinessScore,
       hndlCount: result.inventory.hndlCount,
@@ -339,12 +342,35 @@ export function formatSummary(result: ScanResult, options?: { color?: boolean })
   lines.push(
     `Readiness score: ${c(`${ANSI.bold}${scoreColor(inv.readinessScore)}`, `${inv.readinessScore}/100`)}`,
   );
+  const analyzed =
+    result.analyzedFiles !== undefined
+      ? `   Analyzed (${ANALYZABLE_LANGUAGES_LABEL}): ${result.analyzedFiles}`
+      : "";
   lines.push(
-    `Files scanned:   ${result.filesScanned}   Findings: ${result.findings.length}   HNDL-exposed: ${c(
+    `Files scanned:   ${result.filesScanned}${analyzed}   Findings: ${result.findings.length}   HNDL-exposed: ${c(
       inv.hndlCount > 0 ? ANSI.red : ANSI.green,
       String(inv.hndlCount),
     )}`,
   );
+  // Coverage honesty: a score over zero analyzable files is not a clean bill of health.
+  if (result.analyzedFiles === 0 && result.filesScanned > 0) {
+    lines.push(
+      c(
+        ANSI.yellow,
+        `Note: 0 files were in a supported source language (${ANALYZABLE_LANGUAGES_LABEL}) — the readiness score does not reflect this codebase.`,
+      ),
+    );
+  }
+  // Coverage diagnostics: skipped files mean the finding count may be incomplete.
+  const diag = result.diagnostics;
+  if (diag && (diag.unreadable > 0 || diag.skippedMinified > 0)) {
+    lines.push(
+      c(
+        ANSI.yellow,
+        `Coverage: ${diag.unreadable} unreadable, ${diag.skippedMinified} skipped as minified — results may be incomplete.`,
+      ),
+    );
+  }
   lines.push("");
 
   // Severity breakdown.

package/src/scan-worker.ts

@@ -42,6 +42,8 @@ if (parentPort) {
     try {
       const findings: Finding[] = [];
       let filesScanned = 0;
+      let unreadable = 0;
+      let skippedMinified = 0;
       const scannedNames: string[] = [];
 
       for (const rel of req.files) {
@@ -50,9 +52,11 @@ if (parentPort) {
         try {
           content = readFileSync(abs, "utf8");
         } catch {
-          continue; // vanished / unreadable — skip.
+          unreadable += 1;
+          continue;
         }
         if (!toggles.scanMinified && !isManifestFile(rel) && looksMinified(content)) {
+          skippedMinified += 1;
           continue;
         }
         filesScanned += 1;
@@ -75,7 +79,7 @@ if (parentPort) {
       port.postMessage({
         index: req.index,
         files: scannedNames,
-        result: { findings, filesScanned },
+        result: { findings, filesScanned, unreadable, skippedMinified },
       });
     } catch (err) {
       port.postMessage({

package/src/scan.ts

@@ -13,22 +13,25 @@ import { readFile, stat } from "node:fs/promises";
 import * as path from "node:path";
 
 import type { Detector, Finding, ScanOptions, ScanResult } from "./types.js";
-import { walkFiles, toPosix, isBinaryPath, looksMinified } from "./walk.js";
-import { sourceDetectors } from "./detectors/source.js";
-import { pemDetector } from "./detectors/pem.js";
-import { defaultRegistry, detectorScope } from "./registry.js";
+import { walkFiles, toPosix, isBinaryPath, looksMinified, matchesAny } from "./walk.js";
+import { isAnalyzableSource } from "./detect-utils.js";
+import { stripCommentFindings, stripIgnoredFindings } from "./comments.js";
+import { hashContent, loadCache, rulesetFingerprint, saveCache } from "./cache.js";
+import type { CacheEntry } from "./cache.js";
+import { builtinDetectors, defaultRegistry, detectorScope } from "./registry.js";
 import { isManifestFile, scanManifest } from "./dependencies.js";
 import { buildInventory } from "./inventory.js";
 import { AbortError, BudgetExceededError } from "./errors.js";
 import { VERSION } from "./version.js";
 
 /**
- * The full set of built-in detectors exposed on the public API. The PEM
- * detector applies to every text file; the source detectors apply only to
- * JS/TS. The manifest scanner is handled separately (it parses JSON rather than
- * running a Detector).
+ * The full set of built-in detectors exposed on the public API. Re-exported
+ * from {@link builtinDetectors} in `registry.ts` — the single source of truth
+ * the {@link defaultRegistry} is also built from — so the public array and the
+ * registry can never drift apart. The manifest scanner is handled separately
+ * (it parses JSON rather than running a Detector).
  */
-export const detectors: Detector[] = [...sourceDetectors, pemDetector];
+export const detectors: Detector[] = builtinDetectors;
 
 /** Stable comparator: by file, then line, then ruleId. Exported for reuse. */
 export function compareFindings(a: Finding, b: Finding): number {
@@ -54,7 +57,7 @@ export function detectFile(
   toggles: { source: boolean; config: boolean; deps: boolean },
   disabledRules?: readonly string[],
 ): Finding[] {
-  const out: Finding[] = [];
+  let out: Finding[] = [];
 
   for (const det of dets) {
     if (!det.appliesTo(file)) continue;
@@ -63,6 +66,13 @@ export function detectFile(
     out.push(...det.detect({ file, content }));
   }
 
+  // Drop lexical false positives that land inside comments (`// migrated off
+  // createECDH()`), then honour inline `// qscan-ignore-line` /
+  // `qscan-ignore-next-line` directives. Both run before the dependency scan
+  // appends its findings (manifests carry neither).
+  out = stripCommentFindings(out, content, file);
+  out = stripIgnoredFindings(out, content);
+
   if (toggles.deps && isManifestFile(file)) {
     out.push(...scanManifest(file, content));
   }
@@ -99,7 +109,16 @@ export async function scan(options: ScanOptions): Promise<ScanResult> {
 
   const findings: Finding[] = [];
   let filesScanned = 0;
+  let analyzedFiles = 0;
   let bytesScanned = 0;
+  let unreadable = 0;
+  let skippedMinified = 0;
+
+  // Optional content-hash scan cache: unchanged files reuse prior findings.
+  const cacheFile = options.cacheFile;
+  const ruleset = cacheFile ? rulesetFingerprint(dets, options.disabledRules) : "";
+  const cache = cacheFile ? await loadCache(cacheFile, ruleset) : null;
+  const nextEntries: Map<string, CacheEntry> | null = cacheFile ? new Map() : null;
 
   // Work-budget / cancellation controls (all optional, unlimited when omitted).
   const signal = options.signal;
@@ -135,12 +154,14 @@ export async function scan(options: ScanOptions): Promise<ScanResult> {
     try {
       content = await readFile(absPath, "utf8");
     } catch {
-      continue; // unreadable / vanished file — skip.
+      unreadable += 1; // permissions / vanished / decode failure — tracked, not silent.
+      continue;
     }
 
     // Skip machine-minified / generated content (unless explicitly enabled).
     // Manifests are always scanned (their findings are dependency findings).
     if (!scanMinified && !isManifestFile(reportedPath) && looksMinified(content)) {
+      skippedMinified += 1;
       continue;
     }
 
@@ -151,21 +172,40 @@ export async function scan(options: ScanOptions): Promise<ScanResult> {
     }
 
     filesScanned += 1;
-    findings.push(
-      ...detectFile(
+    if (isAnalyzableSource(reportedPath)) analyzedFiles += 1;
+
+    // Cache: reuse prior findings when the content hash matches; otherwise scan
+    // and record. `nextEntries` becomes the new cache (dropping vanished files).
+    let fileFindings: Finding[];
+    if (cache && nextEntries) {
+      const hash = hashContent(content);
+      const hit = cache.get(reportedPath);
+      fileFindings =
+        hit && hit.hash === hash
+          ? hit.findings
+          : detectFile(
+              reportedPath,
+              content,
+              dets,
+              { source: doSource, config: doConfig, deps: doDeps },
+              options.disabledRules,
+            );
+      nextEntries.set(reportedPath, { hash, findings: fileFindings });
+    } else {
+      fileFindings = detectFile(
         reportedPath,
         content,
         dets,
-        {
-          source: doSource,
-          config: doConfig,
-          deps: doDeps,
-        },
+        { source: doSource, config: doConfig, deps: doDeps },
         options.disabledRules,
-      ),
-    );
+      );
+    }
+    findings.push(...fileFindings);
   }
 
+  // Persist the cache (best effort) before ordering/returning.
+  if (cacheFile && nextEntries) await saveCache(cacheFile, ruleset, nextEntries);
+
   // Stable ordering: by file, then line, then ruleId.
   findings.sort(compareFindings);
 
@@ -176,6 +216,8 @@ export async function scan(options: ScanOptions): Promise<ScanResult> {
     root: options.root,
     findings,
     filesScanned,
+    analyzedFiles,
+    diagnostics: { unreadable, skippedMinified },
     inventory,
     startedAt: startedAt.toISOString(),
     finishedAt: finishedAt.toISOString(),
@@ -221,14 +263,3 @@ export function filterExplicitFileList(
 async function* filterExplicitFiles(files: string[], options: ScanOptions): AsyncGenerator<string> {
   for (const rel of filterExplicitFileList(files, options)) yield rel;
 }
-
-/** Local substring/prefix matcher (mirrors the walker's pattern semantics). */
-function matchesAny(rel: string, patterns: readonly string[]): boolean {
-  for (const pattern of patterns) {
-    if (!pattern) continue;
-    const p = toPosix(pattern).replace(/\/+$/, "");
-    if (rel.includes(p)) return true;
-    if (rel === p || rel.startsWith(`${p}/`)) return true;
-  }
-  return false;
-}

package/src/triage.ts

@@ -0,0 +1,58 @@
+/**
+ * Triage rubric, verdict schema, and request-bundle builder — all offline and
+ * deterministic. Both planes share them: `@quantakrypto/agent` (networked)
+ * prompts a model with the rubric, while the MCP `triage_findings` tool emits a
+ * request bundle for the HOST agent to reason over. Keeping them here means the
+ * MCP server never imports the networked package and both sides use one rubric.
+ */
+import type { Finding } from "./types.js";
+import type { ContextLevel, RedactedContext } from "./agent-types.js";
+import { buildContext } from "./redact.js";
+
+/** The system rubric that defines what an exposure verdict means. */
+export const TRIAGE_RUBRIC =
+  "You are a post-quantum cryptography triage assistant. You are given ONE finding " +
+  "of classical (quantum-vulnerable) cryptography detected in a codebase, with " +
+  "limited, possibly-redacted context. Assess its REAL-WORLD exposure and urgency. " +
+  "exposureScore (0-100): how exploitable/exposed this usage is — a long-lived " +
+  "confidentiality key over the network (harvest-now-decrypt-later) scores high; a " +
+  "short-lived local signature scores lower. priority: 'now' for HNDL/high-exposure, " +
+  "'soon' for important-but-not-urgent, 'later' for low-exposure. You NEVER decide " +
+  "whether the finding is valid and you NEVER suppress it — you only rank exposure. " +
+  "Base your rationale only on the given context; do not invent facts.";
+
+/** JSON Schema every triage verdict must satisfy. */
+export const TRIAGE_VERDICT_SCHEMA: Record<string, unknown> = {
+  type: "object",
+  required: ["exposureScore", "priority", "rationale"],
+  properties: {
+    exposureScore: { type: "number", minimum: 0, maximum: 100 },
+    priority: { enum: ["now", "soon", "later"] },
+    rationale: { type: "string" },
+  },
+};
+
+/** A triage request bundle: the rubric, the verdict schema, and redacted contexts. */
+export interface TriageRequest {
+  rubric: string;
+  schema: Record<string, unknown>;
+  contexts: RedactedContext[];
+}
+
+/**
+ * Build a triage request bundle for a set of findings. Offline: for non-metadata
+ * levels, pass `readContent` to supply each finding's file text; without it,
+ * contexts are built at `metadata` level (no source), which is the safe default
+ * for the MCP plane where the host agent already has the code open.
+ */
+export function buildTriageRequest(
+  findings: readonly Finding[],
+  level: ContextLevel = "metadata",
+  readContent?: (finding: Finding) => string,
+): TriageRequest {
+  const effectiveLevel: ContextLevel = readContent ? level : "metadata";
+  const contexts = findings.map((f) =>
+    buildContext(f, effectiveLevel, readContent ? readContent(f) : ""),
+  );
+  return { rubric: TRIAGE_RUBRIC, schema: TRIAGE_VERDICT_SCHEMA, contexts };
+}

package/src/types.ts

@@ -50,6 +50,21 @@ export interface SourceLocation {
   snippet?: string;
 }
 
+/** Relative urgency an LLM triage pass assigns to a finding. */
+export type TriagePriority = "now" | "soon" | "later";
+
+/**
+ * Optional LLM triage annotation attached to a finding by `qscan --triage`.
+ * Purely additive: it re-ranks and explains, it never suppresses a finding and
+ * never influences the exit code (which is computed from `severity` alone).
+ */
+export interface TriageAnnotation {
+  /** 0–100 real-world exposure/exploitability estimate. */
+  exposureScore: number;
+  priority: TriagePriority;
+  rationale: string;
+}
+
 /** A single detected concern. */
 export interface Finding {
   /** Stable rule identifier, e.g. "rsa-keygen", "ecdh-usage", "tls-legacy-version", "dep-vulnerable". */
@@ -74,14 +89,19 @@ export interface Finding {
    * snippet for such findings, regardless of any redaction flag.
    */
   sensitive?: boolean;
+  /** Optional LLM triage annotation (`qscan --triage`); never affects exit code. */
+  triage?: TriageAnnotation;
   location: SourceLocation;
 }
 
+/** Package ecosystems the dependency scanner understands. */
+export type DependencyEcosystem = "npm" | "pypi" | "cargo" | "go" | "maven" | "rubygems";
+
 /** A known quantum-vulnerable dependency entry. */
 export interface VulnerableDependency {
-  /** Package name. */
+  /** Package name (as written in the ecosystem's manifest). */
   name: string;
-  ecosystem: "npm";
+  ecosystem: DependencyEcosystem;
   /** Why it's flagged (what classical crypto it provides). */
   reason: string;
   /** Algorithm families the package primarily exposes. */
@@ -99,7 +119,16 @@ export type DetectorScope = "source" | "config";
  * The programming language / surface a detector targets. `"any"` means the
  * detector is language-agnostic (e.g. PEM material, config files).
  */
-export type DetectorLanguage = "js" | "python" | "go" | "java" | "any";
+export type DetectorLanguage =
+  | "js"
+  | "python"
+  | "go"
+  | "java"
+  | "csharp"
+  | "rust"
+  | "ruby"
+  | "c"
+  | "any";
 
 /**
  * Declarative metadata for a single rule a detector can emit. This is the
@@ -224,6 +253,14 @@ export interface ScanOptions {
    * catalog ({@link DetectorRegistry.ruleCatalog}) for the valid ids.
    */
   disabledRules?: string[];
+  /**
+   * Path to an on-disk scan cache. When set, unchanged files (same content hash)
+   * reuse their previous findings instead of re-running detectors, and the cache
+   * is rewritten after the scan. Invalidated wholesale when the tool version,
+   * detector set, or `disabledRules` change. Optional; omitted = no caching.
+   * The cache forces the in-process (serial) path.
+   */
+  cacheFile?: string;
   /** Optional progress callback. */
   onFile?: (file: string) => void;
   /**
@@ -274,12 +311,38 @@ export interface CryptoInventory {
   readinessScore: number;
 }
 
+/**
+ * Non-fatal things that happened during a scan that reduce coverage. Surfaced so
+ * a silent under-scan (e.g. half the tree was unreadable) can't masquerade as a
+ * clean "0 findings" result — reporters warn when any count is non-zero.
+ */
+export interface ScanDiagnostics {
+  /** Files that could not be read (permissions, vanished, decode failure) and were skipped. */
+  unreadable: number;
+  /** Files skipped because they look machine-minified / generated (scan with `scanMinified` to include). */
+  skippedMinified: number;
+}
+
 /** The full result of a scan. */
 export interface ScanResult {
   /** The scan root (as provided). */
   root: string;
   findings: Finding[];
   filesScanned: number;
+  /**
+   * Coverage diagnostics: counts of files skipped as unreadable or minified.
+   * Optional for backward compatibility with hand-built results.
+   */
+  diagnostics?: ScanDiagnostics;
+  /**
+   * Of `filesScanned`, how many were in a source language the scanner can
+   * actually analyze for inline crypto (JS/TS, Python, Go, Java). When this is 0 but
+   * `filesScanned` > 0, the readiness score reflects NO analyzable code — the
+   * crypto likely lives in an unsupported language (Go, Java, Rust, …) — and
+   * reporters surface that so a bare 100/100 can't read as "safe". Optional for
+   * backward compatibility with hand-built results.
+   */
+  analyzedFiles?: number;
   inventory: CryptoInventory;
   /** ISO timestamps. */
   startedAt: string;

package/src/verify.ts

@@ -0,0 +1,82 @@
+/**
+ * Snippet-level fix verification: run the detectors over a piece of code (NOT
+ * the filesystem) and report any classical crypto that remains. This is the
+ * deterministic gate a fix must pass — the same logic the MCP `verify_fix` tool
+ * and the remediation pipeline both use, so they can never disagree on what
+ * "the finding is gone" means.
+ */
+import type { Finding } from "./types.js";
+import { detectFile, detectors } from "./scan.js";
+
+/**
+ * Map a language name (or a bare extension) to a source extension whose
+ * detectors we run. Returns null for languages the scanner does not analyze.
+ */
+export function languageToExtension(language: string): string | null {
+  const l = language.trim().toLowerCase().replace(/^\./, "");
+  const map: Record<string, string> = {
+    js: ".js",
+    javascript: ".js",
+    jsx: ".jsx",
+    ts: ".ts",
+    typescript: ".ts",
+    tsx: ".tsx",
+    mjs: ".mjs",
+    cjs: ".cjs",
+    py: ".py",
+    python: ".py",
+    go: ".go",
+    golang: ".go",
+    java: ".java",
+    kotlin: ".kt",
+    kt: ".kt",
+    cs: ".cs",
+    csharp: ".cs",
+    "c#": ".cs",
+    dotnet: ".cs",
+    rs: ".rs",
+    rust: ".rs",
+    rb: ".rb",
+    ruby: ".rb",
+    c: ".c",
+    "c++": ".cpp",
+    cpp: ".cpp",
+    cc: ".cc",
+    h: ".h",
+    hpp: ".hpp",
+  };
+  return map[l] ?? null;
+}
+
+/** Result of {@link verifyFix}: the findings that remain, and whether the
+ * language is one the scanner actually analyzes (so `findings: []` on an
+ * unsupported language is NOT a clean verification). */
+export interface VerifyResult {
+  supported: boolean;
+  findings: Finding[];
+}
+
+/**
+ * Run all detectors over `code`, selecting them by `filename` (extension) or
+ * `language`. Pure: no I/O. When neither identifies an analyzable language,
+ * `supported` is false and the empty findings list must not be read as "fixed".
+ */
+export function verifyFix(
+  code: string,
+  opts: { filename?: string; language?: string },
+): VerifyResult {
+  let name: string;
+  if (opts.filename && opts.filename.trim()) {
+    name = opts.filename.trim();
+  } else if (opts.language && opts.language.trim()) {
+    const ext = languageToExtension(opts.language);
+    if (!ext) return { supported: false, findings: [] };
+    name = `snippet${ext}`;
+  } else {
+    return { supported: false, findings: [] };
+  }
+  const dotExt = name.replace(/^.*(\.[^.]+)$/, "$1");
+  const supported = languageToExtension(dotExt) !== null;
+  const findings = detectFile(name, code, detectors, { source: true, config: true, deps: true });
+  return { supported, findings };
+}

package/src/version.ts

@@ -3,4 +3,4 @@
  * the scan orchestrator can import it without creating a cycle through index.ts.
  * Keep in sync with packages/core/package.json.
  */
-export const VERSION = "0.3.0";
+export const VERSION = "0.4.0";