@quantakrypto/core 0.2.2 → 0.4.0

package/src/report.ts

@@ -3,9 +3,10 @@
  * or a human-readable text summary. No third-party dependencies — ANSI colour
  * is emitted with raw escape codes and is off by default.
  */
-import type { Finding, ScanResult, Severity } from "./types.js";
+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 {
@@ -23,6 +24,14 @@ export interface ReportOptions {
    * snippet there IS the sensitive value.
    */
   redactSnippets?: boolean;
+  /**
+   * Full rule catalog to advertise in SARIF `tool.driver.rules[]`, even for
+   * rules that produced no finding in this run. Pass
+   * `defaultRegistry.ruleCatalog()`. When omitted, only the rules that actually
+   * fired are emitted (the historical behaviour). SARIF-only; ignored by
+   * {@link toJson}.
+   */
+  catalog?: RuleMeta[];
 }
 
 const SARIF_SCHEMA =
@@ -56,40 +65,88 @@ function sarifRank(severity: Severity): number {
   }
 }
 
+/** Build a SARIF `rules[]` entry from a rule's severity/title/message/etc. */
+function sarifRule(spec: {
+  id: string;
+  title: string;
+  message: string;
+  severity: Severity;
+  category: string;
+  algorithm?: string;
+  hndl: boolean;
+  cwe?: string;
+  remediation?: string;
+}): Record<string, unknown> {
+  return {
+    id: spec.id,
+    name: spec.id,
+    shortDescription: { text: spec.title },
+    fullDescription: { text: spec.message },
+    defaultConfiguration: { level: sarifLevel(spec.severity), rank: sarifRank(spec.severity) },
+    ...(spec.remediation ? { help: { text: `Remediation: ${spec.remediation}` } } : {}),
+    properties: {
+      category: spec.category,
+      ...(spec.algorithm ? { algorithm: spec.algorithm } : {}),
+      hndl: spec.hndl,
+      ...(spec.cwe ? { cwe: spec.cwe, "security-severity": securitySeverity(spec.severity) } : {}),
+      ...(spec.cwe ? { tags: ["security", spec.cwe] } : {}),
+    },
+    ...(spec.cwe
+      ? {
+          relationships: [
+            { target: { id: spec.cwe, toolComponent: { name: "CWE" } }, kinds: ["relevant"] },
+          ],
+        }
+      : {}),
+  };
+}
+
 /** Serialize a scan result as SARIF 2.1.0. */
 export function toSarif(result: ScanResult, opts?: ReportOptions): SarifLog {
   const redactSnippets = opts?.redactSnippets ?? false;
-  // Build the unique rule set (one rule per ruleId encountered) and collect the
-  // set of CWE taxa referenced by any rule.
+  // Build the rule set and collect the CWE taxa referenced by any rule. When a
+  // full catalog is supplied, advertise every rule (even ones that didn't fire);
+  // otherwise emit one rule per ruleId encountered (the historical behaviour).
   const ruleIndex = new Map<string, number>();
   const rules: Array<Record<string, unknown>> = [];
   const cweTaxa = new Set<string>();
+
+  for (const r of opts?.catalog ?? []) {
+    if (ruleIndex.has(r.id)) continue;
+    if (r.cwe) cweTaxa.add(r.cwe);
+    ruleIndex.set(r.id, rules.length);
+    rules.push(
+      sarifRule({
+        id: r.id,
+        title: r.title,
+        message: r.message,
+        severity: r.severity,
+        category: r.category,
+        algorithm: r.algorithm,
+        hndl: r.hndl,
+        cwe: r.cwe,
+        remediation: r.remediation,
+      }),
+    );
+  }
+
   for (const f of result.findings) {
     if (f.cwe) cweTaxa.add(f.cwe);
     if (ruleIndex.has(f.ruleId)) continue;
     ruleIndex.set(f.ruleId, rules.length);
-    rules.push({
-      id: f.ruleId,
-      name: f.ruleId,
-      shortDescription: { text: f.title },
-      fullDescription: { text: f.message },
-      defaultConfiguration: { level: sarifLevel(f.severity), rank: sarifRank(f.severity) },
-      ...(f.remediation ? { help: { text: `Remediation: ${f.remediation}` } } : {}),
-      properties: {
+    rules.push(
+      sarifRule({
+        id: f.ruleId,
+        title: f.title,
+        message: f.message,
+        severity: f.severity,
         category: f.category,
-        ...(f.algorithm ? { algorithm: f.algorithm } : {}),
+        algorithm: f.algorithm,
         hndl: f.hndl,
-        ...(f.cwe ? { cwe: f.cwe, "security-severity": securitySeverity(f.severity) } : {}),
-        ...(f.cwe ? { tags: ["security", f.cwe] } : {}),
-      },
-      ...(f.cwe
-        ? {
-            relationships: [
-              { target: { id: f.cwe, toolComponent: { name: "CWE" } }, kinds: ["relevant"] },
-            ],
-          }
-        : {}),
-    });
+        cwe: f.cwe,
+        remediation: f.remediation,
+      }),
+    );
   }
 
   const results = result.findings.map((f) => {
@@ -197,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,
@@ -283,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

@@ -23,6 +23,7 @@ interface WorkerToggles {
   config: boolean;
   deps: boolean;
   scanMinified: boolean;
+  disabledRules?: string[];
 }
 
 interface ChunkRequest {
@@ -41,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) {
@@ -49,26 +52,34 @@ 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;
         scannedNames.push(rel);
         findings.push(
-          ...detectFile(rel, content, dets, {
-            source: toggles.source,
-            config: toggles.config,
-            deps: toggles.deps,
-          }),
+          ...detectFile(
+            rel,
+            content,
+            dets,
+            {
+              source: toggles.source,
+              config: toggles.config,
+              deps: toggles.deps,
+            },
+            toggles.disabledRules,
+          ),
         );
       }
 
       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 {
@@ -52,8 +55,9 @@ export function detectFile(
   content: string,
   dets: readonly Detector[],
   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;
@@ -62,10 +66,24 @@ 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));
   }
 
+  // Per-rule suppression: drop findings whose ruleId was disabled. Applied here
+  // so both the serial scan and the worker path honour it identically.
+  if (disabledRules && disabledRules.length > 0) {
+    const disabled = new Set(disabledRules);
+    return out.filter((f) => !disabled.has(f.ruleId));
+  }
+
   return out;
 }
 
@@ -91,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;
@@ -127,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;
     }
 
@@ -143,15 +172,40 @@ export async function scan(options: ScanOptions): Promise<ScanResult> {
     }
 
     filesScanned += 1;
-    findings.push(
-      ...detectFile(reportedPath, content, dets, {
-        source: doSource,
-        config: doConfig,
-        deps: doDeps,
-      }),
-    );
+    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 },
+        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);
 
@@ -162,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(),
@@ -207,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,56 @@ 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
+ * catalog entry: the stable, queryable description of a rule keyed by the
+ * `ruleId` it stamps onto findings. It is the single source of truth for a
+ * rule's title / severity / category / remediation, consumed by the SARIF
+ * `rules[]` block, the MCP `explain_finding` resolver, and future per-rule
+ * enable/disable + language-pack work.
+ *
+ * For most rules the metadata is fixed and `detect()` builds findings straight
+ * from it (see `findingFromRule`). A few rules are inherently multi-variant
+ * (e.g. `node-crypto-keygen` spans RSA/EC/DSA/DH/Ed25519 at different
+ * severities); for those the metadata here is a REPRESENTATIVE umbrella and
+ * `detect()` refines the per-finding fields at match time. The catalog always
+ * enumerates every emittable ruleId regardless.
+ */
+export interface RuleMeta {
+  /** Stable rule id — matches {@link Finding.ruleId}. Unique across the catalog. */
+  id: string;
+  /** Canonical human title. */
+  title: string;
+  category: FindingCategory;
+  severity: Severity;
+  /** Default confidence for findings of this rule. */
+  confidence: Confidence;
+  /** Harvest-now-decrypt-later exposure. */
+  hndl: boolean;
+  /** Representative classical algorithm family; refined per-finding when it varies. */
+  algorithm?: AlgorithmFamily;
+  /** Associated CWE identifier (e.g. "CWE-327"). */
+  cwe?: string;
+  /** Suggested post-quantum remediation. When omitted, derived from {@link algorithm}. */
+  remediation?: string;
+  /** Canonical one-line human explanation; may be refined per-finding. */
+  message: string;
+  /** True when this rule's matched snippet IS sensitive key material. */
+  sensitive?: boolean;
+  /** Short description of what the rule detects (for catalog / MCP surfaces). */
+  description?: string;
+}
 
 /** A pluggable source detector. Detectors are pure and stateless. */
 export interface Detector {
@@ -118,6 +187,13 @@ export interface Detector {
    * Defaults to `"js"` when omitted.
    */
   language?: DetectorLanguage;
+  /**
+   * The rules this detector can emit, as declarative metadata. Together across
+   * all detectors these form the rule catalog ({@link DetectorRegistry.ruleCatalog}).
+   * Optional for backward compatibility with externally-defined detectors, but
+   * all built-in detectors declare it.
+   */
+  rules?: RuleMeta[];
   /** Whether this detector should run against the given file path. */
   appliesTo(filePath: string): boolean;
   /** Inspect a single file's contents and return zero or more findings. */
@@ -170,6 +246,21 @@ export interface ScanOptions {
    * registry's detectors are used.
    */
   detectors?: Detector[];
+  /**
+   * Rule ids to suppress. Any finding whose `ruleId` is listed here is dropped
+   * after detection. Serializable (a plain string array), so it is honoured on
+   * both the serial and the worker-thread (`scanParallel`) paths. See the rule
+   * 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;
   /**
@@ -220,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;