mjolnir-qa 4.0.0 → 5.0.0

package/dist/cli.d.mts

@@ -1,3 +1,77 @@
+//#region src/v6/test-doubles.d.ts
+/** How serious the pattern is. Closed enum, so a renderer cannot invent a
+ *  fourth severity at a call site. */
+declare const DOUBLE_RISKS: readonly ["NO_ASSERTION", "DOUBLE_ONLY", "DOUBLE_MIXED", "DOUBLE_SUBJECT"];
+type DoubleRisk = (typeof DOUBLE_RISKS)[number];
+interface DoubleFinding {
+  risk: DoubleRisk;
+  /** How many assertions there are in total. */
+  assertions: number;
+  /** How many are about a double. */
+  doubleAssertions: number;
+  /** How many carry real evidence about the code under test. */
+  substantiatingAssertions: number;
+  /** 0..1 — the share of assertions that prove nothing. */
+  hollowRatio: number;
+  /** The one-line statement a surface can render verbatim. */
+  statement: string;
+}
+/**
+ * A roll-up across a suite. A suite is hollow when *no* test in it
+ * substantiates anything — which is a different and stronger statement
+ * than "some tests are hollow", and the one a user needs at the top of a
+ * report.
+ */
+declare function assessSuite(findings: readonly DoubleFinding[]): {
+  tests: number;
+  hollow: number;
+  substantiating: number;
+  hollowRatio: number;
+  verdict: "SUBSTANTIATED" | "PARTIALLY_HOLLOW" | "HOLLOW";
+};
+//#endregion
+//#region src/v6/tool-coverage.d.ts
+/** What the engine can do with a detected tool. Closed enum, so a
+ *  renderer cannot invent a fifth state. */
+declare const TOOL_COVERAGE_STATES: readonly ["UNDERSTOOD", "DECLARED", "OUT_OF_SCOPE", "IGNORED"];
+type ToolCoverageState = (typeof TOOL_COVERAGE_STATES)[number];
+interface ToolCoverageEntry {
+  name: string;
+  state: ToolCoverageState;
+  /** The census category, when one applies. */
+  category: string | null;
+  /** The census entry id, when the engine has one. */
+  censusId: string | null;
+  /** What the cost of not handling it is, in one sentence. */
+  consequence: string;
+}
+interface BlindSpot {
+  id: string;
+  /** What the engine cannot see. */
+  blindTo: string;
+  /** Why it matters, in one sentence. */
+  consequence: string;
+}
+interface ToolCoverage {
+  /** Every QA tool the probe saw, with what the engine does about it. */
+  tools: readonly ToolCoverageEntry[];
+  counts: Readonly<Record<ToolCoverageState, number>>;
+  /** Tools the engine sees and cannot act on. */
+  unhandled: readonly ToolCoverageEntry[];
+  /**
+   * What the engine cannot see **through**, whether or not the tool is
+   * known. This is the part a user cannot infer, and the part that makes
+   * a green run mean something.
+   */
+  blindSpots: readonly BlindSpot[];
+  /** The double-analysis roll-up, when the caller supplied test data. */
+  suite: ReturnType<typeof assessSuite> | null;
+  /** One line a surface may render verbatim. */
+  statement: string;
+  /** Never a claim of completeness. */
+  complete: false;
+}
+//#endregion
 //#region src/types.d.ts
 /**
  * Mjolnir — canonical types (JSON contract v1, schemaVersion 1).
@@ -383,12 +457,42 @@ interface ScanResult {
     durationMs: number;
     /**
      * Named reasons the scan stopped early (audit H-8): "deadline",
-     * "file-cap:<adapter>", "rule-loop-deadline". Present only when
-     * truncation actually happened — absence means the scan is whole.
+     * "file-cap:<adapter>", "rule-loop-deadline", "ast-budget-fallback".
+     * Present only when truncation actually happened — absence means the
+     * scan is whole.
+     *
+     * Open `string[]`, NOT a closed union: a producer may add a member
+     * without a schema bump. The cost of that choice is that a consumer
+     * asserting the EXACT set breaks on every new reason, so assertions
+     * here are containment assertions, never `toEqual([...])`.
+     *
+     * "ast-budget-fallback" specifically means the scan ran out of time
+     * before a file could be analyzed through its adapter's AST stage, and
+     * that file was analyzed by regex instead. It is a capability loss, not
+     * a speed trade, and the count of affected files is in `reasons` as
+     * "ast-budget-fallback-files:<n>".
      */
     truncationReasons?: string[];
     /** Canonical completion reasons, including scope and parser degradation. */
     reasons?: string[];
+    /**
+     * Per-reason counts of capability lost inside a `catch` that returned a
+     * clean default — the degradation ledger (`src/engine/degradation-ledger.ts`).
+     *
+     * Distinct from `truncationReasons`, which means the scan STOPPED, and
+     * from `reasons`, which is a flat string set. This one is structured and
+     * reason-coded so "the AST mask was unavailable for 3 files" and "3 files
+     * were skipped" cannot be confused. Each entry is ALSO surfaced in
+     * `reasons` as `degraded:<reason>:<count>`.
+     *
+     * Present only when at least one degradation happened; absence means the
+     * scan lost no capability to a swallowed error, OR the producer predates
+     * the ledger. A non-empty value always forces `partial: true`.
+     */
+    degradations?: Array<{
+      reason: string;
+      count: number;
+    }>;
     /**
      * Rule executions that threw and were swallowed by crash isolation
      * (audit R-9). 0 means no rule silently failed; absence means the
@@ -429,6 +533,18 @@ interface ScanResult {
     /** The named scope reasons, present only when PARTIAL. */
     reasons?: string[];
   };
+  /**
+   * Tool coverage (v6): which QA tooling this scan actually saw, what the
+   * engine does about it, and what it is blind to.
+   *
+   * Present when the scan ran the ecosystem probe. Additive within
+   * schemaVersion 1; absent when the producer predates this field.
+   *
+   * complete is always false. A scan that could not see through a test
+   * double must never render as a scan with no blind spots, and that is
+   * the one claim a verification tool cannot make.
+   */
+  toolCoverage?: ToolCoverage;
   /**
    * Run Identity (R4c): the deterministic anchor binding verdict ←
    * evidence ← execution ← scope ← source ← rule(rev). Present when the
@@ -757,6 +873,53 @@ declare class DependencyGraph {
   has(path: string): boolean;
 }
 //#endregion
+//#region src/engine/degradation-ledger.d.ts
+/**
+ * One ledger for every silent capability loss.
+ *
+ * The defect class this exists to kill is not a deprecation warning. It is a
+ * `catch` in a DETECTION path that swallows an error and returns a clean
+ * default, so the scan still reports `analysisComplete` while quietly running
+ * with less capability than the reader was promised. Fifteen such sites were
+ * verified in this tree; the AST-layer ones are the worst, because the layer
+ * they degrade is the one that keeps prose comments and sample strings from
+ * becoming false-positive findings.
+ *
+ * Two shapes, one rule. The precedent already in the tree is
+ * `parserRetryDegradationCount` (`src/engine/tree-sitter-ast.ts`): a counted,
+ * readable number rather than a swallowed exception. This generalizes it —
+ * every site records a REASON from the closed set below, and the scan result
+ * carries the per-reason counts, so "the parser failed" becomes
+ * "the AST mask was unavailable for 3 files".
+ *
+ * The ledger is APPEND-ONLY and process-scoped, which has one consequence
+ * worth stating because it is the security-relevant direction: `beginWindow`
+ * returns a MARKER, not an ownership claim. Two concurrent `runScan` calls in
+ * one process (there is a test that does exactly this,
+ * `tests/stress/concurrent-same-process.spec.ts`) each read the records
+ * appended after their own marker, so a degradation one scan records may be
+ * counted by the other. That can only ever OVER-count — a scan reporting a
+ * degradation that happened to a sibling is more cautious than the truth, and
+ * never less — so the failure direction is the honest one. The alternative,
+ * a sink threaded through every rule context, is a diff across every call site
+ * in the tree to fix a problem that cannot make a scan look better than it is.
+ */
+/**
+ * Every reason a detection path may lose capability.
+ *
+ * Closed on purpose: a `catch` site that wants a new reason has to add it
+ * here, which is the moment a reviewer sees the claim. `tests/contract/
+ * no-uncounted-degradation.spec.ts` reads this list and fails on any `catch`
+ * in a detection path that neither rethrows, records one of these, nor
+ * appears in its allowlist with a stated reason.
+ */
+declare const DEGRADATION_REASONS: readonly ["ast-parse-failed", "ast-mask-unavailable", "ast-range-scan-failed", "ci-workflow-listing-unreadable", "workspace-manifest-unreadable", "java-build-listing-unreadable", "rules-tree-listing-unreadable", "trend-record-unparseable", "explain-fixture-unreadable", "explain-workflow-parse-failed", "explain-rule-crash", "rule-doc-rule-crash", "rule-doc-fixture-unreadable", "rule-doc-workflow-parse-failed"];
+type DegradationReason = (typeof DEGRADATION_REASONS)[number];
+interface DegradationCount {
+  readonly reason: DegradationReason;
+  readonly count: number;
+}
+//#endregion
 //#region src/discovery/workspace.d.ts
 /**
  * Repository discovery (Sprint-Plan W1-03).
@@ -1483,6 +1646,12 @@ interface FileAnalysisResult {
   parseFallbacks: number;
   scanned: number;
   analyzed: number;
+  /**
+   * Files that HAD an AST stage and lost it to the scan deadline, so they
+   * were analyzed by regex alone. Zero for every adapter that declares no
+   * `parseAst` — that is a capability envelope, not a downgrade.
+   */
+  astFallbackFiles: number;
 }
 declare function runFileAnalysisPhase(findings: Finding[], testFiles: string[], workspace: Workspace, activeRules: UniversalRule[], hooks: ScanHooks, cache: ScanCache, rulesDigest: string, deadline: number, truncationReasons: Set<string>, declarationsByFile: Map<string, number>, fileProvenance: Array<{
   path: string;
@@ -1530,6 +1699,14 @@ interface AssembleScanResultInput {
   scopeUnrecognized: number;
   parseFailed: number;
   parseFallbacks?: number;
+  /** Files that lost their AST stage to the scan deadline. See completion.ts. */
+  astFallbackFiles?: number;
+  /**
+   * Reason-coded capability losses recorded during this scan's window. See
+   * `src/engine/degradation-ledger.ts` for why the window is an index rather
+   * than an ownership claim.
+   */
+  degradations?: readonly DegradationCount[];
   scanned: number;
   analyzed?: number;
   testFiles: string[];
@@ -1585,7 +1762,7 @@ declare function runScan$1(args: CliArgs, hooks?: ScanHooks): Promise<ScanResult
  * scripts/sync-sarif-version.cjs and guarded by the version-consistency
  * spec. cli.ts re-exports this as CLI_VERSION.
  */
-declare const ENGINE_VERSION = "4.0.0";
+declare const ENGINE_VERSION = "5.0.0";
 //#endregion
 //#region src/cli-io.d.ts
 /**
@@ -1897,7 +2074,7 @@ export declare const MAX_DURATION_MS = 3600000;
 export declare function parseArgs(argv: string[], onError?: (detail: UsageErrorDetail) => void): CliArgs | null;
 /** Hand-rolled Levenshtein distance (plan M2: no new dependencies). */
 export declare function levenshtein(a: string, b: string): number;
-/** Nearest known flags within distance ≤ 2, nearest first. */
+/** Nearest known flags within distance ≤ 2, nearest first. */
 export declare function nearestFlags(flag: string, max?: number): string[];
 /**
  * Friendly usage error (plan M2, exit 10 preserved): nearest-flag