mjolnir-qa 2.1.0 → 4.0.0

package/dist/cli.d.mts

@@ -235,6 +235,68 @@ interface DimensionScore {
   infos: number;
 }
 type AnalysisStatus = "complete" | "partial";
+/**
+ * The normalized per-test runtime evidence record as it appears in a report
+ * (plan V5-011). Structurally the `EvidenceRecord` from
+ * `src/engine/evidence-core.ts`, restated here so the report schema does not
+ * depend on an engine module's internals — the wire shape is a contract.
+ */
+interface EvidenceRecordShape {
+  source: string;
+  artifact: string;
+  file: string;
+  title: string;
+  line?: number;
+  status: {
+    final: string;
+    failed: boolean;
+    retried: boolean;
+    passedOnRetry: boolean;
+    skipped: boolean;
+    timedOut: boolean;
+  };
+  attempts: number;
+  durationMs: number;
+  errors: string[];
+  attachments: string[];
+  provenance: {
+    core: string;
+    ingest: string;
+  };
+}
+/**
+ * Candidate binding (plan V5-010).
+ *
+ * The immutable identity of the release candidate a run was produced against.
+ * It is what makes a claim replayable: "this verdict belongs to candidate
+ * X, built from commit Y with lockfile Z" can be re-checked; "this verdict
+ * belongs to whatever was on the machine" cannot.
+ *
+ * Every field is required. A partial binding is worse than none, because a
+ * consumer cannot tell which link is missing — so an unbound run omits the
+ * whole object rather than filling in what it has.
+ */
+interface CandidateBinding {
+  /** The candidate manifest's own id. */
+  manifestId: string;
+  /** WORKING_CANDIDATE | RELEASE_CANDIDATE. */
+  state: "WORKING_CANDIDATE" | "RELEASE_CANDIDATE";
+  /**
+   * The immutable commit this candidate is bound to, or null for a working
+   * candidate — which by definition has no commit yet.
+   */
+  candidateSha: string | null;
+  /** The commit the candidate was branched from. */
+  baseSha: string;
+  /** sha256 of package.json as published for the candidate. */
+  packageSha256: string;
+  /** sha256 of the lockfile as published for the candidate. */
+  lockfileSha256: string;
+  /** Who owns the candidate. "UNASSIGNED" is a real, reportable value. */
+  owner: string;
+  /** NOT_AUTHORIZED | AUTHORIZED. Never inferred from evidence. */
+  releaseAuthorizationState: "NOT_AUTHORIZED" | "AUTHORIZED";
+}
 interface ScanResult {
   schemaVersion: typeof SCHEMA_VERSION;
   /** False when budget expired or files were skipped (§18.3). */
@@ -325,12 +387,15 @@ interface ScanResult {
      * truncation actually happened — absence means the scan is whole.
      */
     truncationReasons?: string[];
+    /** Canonical completion reasons, including scope and parser degradation. */
+    reasons?: string[];
     /**
      * Rule executions that threw and were swallowed by crash isolation
      * (audit R-9). 0 means no rule silently failed; absence means the
      * producer predates the counter.
      */
     rulesCrashed?: number;
+    parseFallbacks?: number;
   };
   /**
    * Scoring model version stamped into the result (ENGINE-001). Allows
@@ -378,6 +443,30 @@ interface ScanResult {
     trustModelVersion?: string;
     scoringModelVersion?: string;
     frameworkSupportMatrixVersion?: string;
+    commit?: string;
+    /** The worktree tree hash the run was bound to, when known. */
+    tree?: string;
+    /** The lockfile digest the run was bound to, when known. */
+    lockfile?: string;
+    /**
+     * Which identity links this run actually bound (plan V5-010). Derived, not
+     * asserted by each consumer: a claim is replayable only when every link it
+     * depends on is present.
+     *
+     * OPTIONAL on purpose. The machine contract is v1 additive-only, so a
+     * report written before this field existed has none, and a reader that
+     * required it would reject exactly the older artifacts it must tolerate.
+     * Absence means "produced by a build that did not record bindings" — never
+     * "bound to everything".
+     */
+    boundLinks?: Array<"input" | "rules" | "config" | "engine" | "commit" | "tree" | "lockfile" | "candidate">;
+    /**
+     * The release candidate this run is bound to (plan V5-010). Absent for an
+     * ordinary scan of a working tree — a run is not a release candidate, and
+     * saying otherwise would let a local scan stand in for authorized
+     * evidence.
+     */
+    candidate?: CandidateBinding;
   };
   /**
    * Evidence Graph (R4c): the chain-law links (VERDICT ← EVIDENCE ←
@@ -397,6 +486,34 @@ interface ScanResult {
       configFingerprint: string;
       engineVersion: string;
     };
+    /** The release candidate the verdict belongs to, when bound (V5-010). */
+    candidate?: {
+      manifestId: string;
+      candidateSha: string | null;
+    };
+  };
+  /**
+   * The normalized evidence core (plan V5-011).
+   *
+   * Present whenever the run ingested a runtime report. `records` is the
+   * canonical, deterministically-ordered set that every downstream consumer
+   * reads — before this, the core was computed and discarded inside the
+   * pipeline, so a re-derivation had to re-parse the report and could disagree
+   * with the verdict it was supposed to explain.
+   *
+   * Empty `records` with a null `artifact` means no runtime evidence was
+   * found, which is different from a run that found an empty report.
+   */
+  evidence?: {
+    records: Array<EvidenceRecordShape>;
+    counts: {
+      total: number;
+      failed: number;
+      flaky: number;
+      skipped: number;
+      timedOut: number;
+    };
+    artifact: string | null;
   };
   /**
    * Local incremental cache report (Beta-to-Stable plan, M5.2). Present
@@ -635,6 +752,9 @@ declare class DependencyGraph {
   getDependents(path: string): string[];
   get allPaths(): string[];
   get size(): number;
+  /** Whether the graph knows this exact key. Reachability must not
+   *  treat "not in the graph" as "nothing to traverse" without saying so. */
+  has(path: string): boolean;
 }
 //#endregion
 //#region src/discovery/workspace.d.ts
@@ -653,9 +773,18 @@ interface Workspace {
 }
 //#endregion
 //#region src/discovery/frameworks.d.ts
-type TestFramework = "jest" | "vitest" | "playwright";
+/**
+ * The catalogued frameworks whose detection is implemented today.
+ *
+ * Every entry must exist in the inventory — enforced by the parity spec, not
+ * by comment.
+ */
+declare const DETECTABLE_TEST_FRAMEWORKS: readonly ["jest", "vitest", "playwright"];
+/** The detection output type, in the inventory's vocabulary. */
+type DetectedFramework = (typeof DETECTABLE_TEST_FRAMEWORKS)[number];
 interface FrameworkInfo$1 {
-  frameworks: TestFramework[];
+  /** Detected frameworks, as inventory ids. */
+  frameworks: DetectedFramework[];
   /** True when no config evidence was found at all. */
   unknown: boolean;
 }
@@ -956,9 +1085,9 @@ interface ScanContext {
   maxFiles: number;
   /** R4c Scope Integrity: counted matcher exclusions (optional — adapters
    * whose discovery walks sharedWalk pass this through to the counters). */
-  onIgnored?: () => void;
+  onIgnored?: (path: string) => void;
   /** R4c Scope Integrity: counted files no adapter claims (optional). */
-  onUnrecognized?: () => void;
+  onUnrecognized?: (path: string) => void;
   /**
    * Called when a rule throws on a file (audit R-9): crash isolation
    * stays silent by default, but the scan counts it and `--debug`
@@ -987,8 +1116,19 @@ interface LanguageAdapter {
    * Contract: resolve to a ParsedAst on success, `undefined` when this
    * adapter has no AST layer (or parsing failed — rules fall back to the
    * regex path either way). Never throws.
+   *
+   * May return the result directly as well as a promise: the ts-morph path
+   * (plan V5-021) is synchronous, and forcing it to allocate a promise per
+   * file would be a cost the shared seam has no business imposing. The
+   * pipeline awaits either form.
+   *
+   * Declared as a PROPERTY, not a method signature. A method signature
+   * promises a `this` binding that no adapter uses, and it makes every
+   * consumer that reads `adapter.parseAst` trip the unbound-method rule —
+   * which is a lint error that gets suppressed rather than a design that
+   * gets fixed, so the shape has to say what it means.
    */
-  parseAst?(file: ParsedFile): Promise<ParsedAst | undefined>;
+  parseAst?: (file: ParsedFile) => ParsedAst | undefined | Promise<ParsedAst | undefined>;
   /**
    * Run all rules this adapter hosts against one file. `onCrash` is
    * invoked when a rule throws (audit R-9) — the crash is still
@@ -1041,6 +1181,55 @@ interface UniversalRule {
   run(file: ParsedFile): Array<Omit<Finding, "ruleId" | "category">>;
 }
 //#endregion
+//#region src/engine/evidence-core.d.ts
+/**
+ * The core's own version — stamped into every record's provenance so a
+ * consumer can tell which normalization contract produced a record.
+ * Bump ONLY on a semantic change to the normalization itself.
+ */
+declare const EVIDENCE_CORE_VERSION = "evidence-core@1";
+/** Evidence source formats the core understands today (WI-17 adds trace.zip). */
+type EvidenceSource = ForensicsReport["source"];
+/** Normalized per-test runtime evidence (plan WI-2 field contract). */
+interface EvidenceRecord {
+  /** Where this evidence came from (format identity). */
+  source: EvidenceSource;
+  /** Ingested artifact identity — the report path the records derive from. */
+  artifact: string;
+  /** Test identity: file + title (+ declaration line when known). */
+  file: string;
+  title: string;
+  /** 1-based declaration line when the source carries one (JUnit: absent). */
+  line?: number;
+  /** Normalized execution status facts. */
+  status: {
+    /** Last attempt's outcome. */
+    final: RunStatus;
+    /** Failed at least once across attempts. */
+    failed: boolean;
+    /** Executed more than once. */
+    retried: boolean;
+    /** Passed only on attempt >= 2 (TRUE-FLAKE). */
+    passedOnRetry: boolean;
+    skipped: boolean;
+    /** Final attempt timed out. */
+    timedOut: boolean;
+  };
+  /** Number of attempts (retries = attempts − 1). */
+  attempts: number;
+  /** Total duration across attempts. */
+  durationMs: number;
+  /** Error messages, in report order. Empty: not captured by this source yet. */
+  errors: string[];
+  /** Attachment names/paths. Empty: not captured by this source yet (WI-17). */
+  attachments: string[];
+  /** Where the record came from and under which normalization contract. */
+  provenance: {
+    core: typeof EVIDENCE_CORE_VERSION;
+    ingest: "mjolnir.forensics";
+  };
+}
+//#endregion
 //#region src/engine/provenance.d.ts
 type FileProvenance = "unmarked" | "generated-marked" | "codegen-like";
 /** Classify one file's provenance. Pure. */
@@ -1068,7 +1257,7 @@ interface IgnoreEntry {
   ruleId: string;
   files?: string[];
   reason: string;
-  /** ISO date; defaults to 90 days from creation (S11). */
+  /** ISO date; omitted means the suppression has no expiry. */
   expires?: string;
 }
 interface QADoctorConfig {
@@ -1291,7 +1480,9 @@ interface FileAnalysisResult {
   testDeclarationCount: number;
   rulesPartial: boolean;
   parseFailed: number;
+  parseFallbacks: number;
   scanned: number;
+  analyzed: 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;
@@ -1306,6 +1497,13 @@ interface PostScanResult {
   suppressionCount: number;
   frameworks: ReturnType<typeof detectFrameworks>;
   runtimeReportPath: string | undefined;
+  runtimeIncomplete: boolean;
+  /**
+   * The normalized evidence core (V5-011). Persisted rather than discarded,
+   * so every post-ingest projection reads records instead of re-parsing a
+   * report that may have changed underneath it.
+   */
+  evidenceRecords: EvidenceRecord[];
   /** Aggregate forensic classifications from the ingested runtime report. */
   forensicVerdicts: ForensicVerdictSummary | undefined;
   config: ReturnType<typeof loadConfig>["config"];
@@ -1331,7 +1529,9 @@ interface AssembleScanResultInput {
   scopeIgnored: number;
   scopeUnrecognized: number;
   parseFailed: number;
+  parseFallbacks?: number;
   scanned: number;
+  analyzed?: number;
   testFiles: string[];
   workspace: Workspace;
   scanRoot: Workspace;
@@ -1350,6 +1550,8 @@ interface AssembleScanResultInput {
   suppressionCount: number;
   frameworks: ReturnType<typeof detectFrameworks>;
   runtimeReportPath: string | undefined;
+  runtimeIncomplete?: boolean;
+  evidenceRecords?: EvidenceRecord[];
   forensicVerdicts: ForensicVerdictSummary | undefined;
   config: ReturnType<typeof loadConfig>["config"];
   fileProvenance: Array<{
@@ -1383,7 +1585,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 = "2.1.0";
+declare const ENGINE_VERSION = "4.0.0";
 //#endregion
 //#region src/cli-io.d.ts
 /**
@@ -1565,11 +1767,17 @@ export declare function runReleaseTrustCommand(argv: string[], io?: {
  * Entry point for `mjolnir business-case`.
  *
  * Flags:
- *   --industry <type>    Industry cost profile (default/fintech/healthcare/...)
- *   --history <months>   Use git history for the last N months (estimates from
- *                        actual scan improvements, not projections)
- *   --projected <months> Show projected savings over N months
+ *   --incident-cost <n>  The cost of ONE false-green incident in your
+ *                        organisation. Until you supply it, no dollar
+ *                        figure is printed at all.
  *   --strict             Include quarantine-tier findings
+ *
+ * `--history` and `--projected` are GONE. Both promised arithmetic this
+ * tool cannot do: `--history` claimed to estimate from actual scan
+ * improvements while reading no history at all, and `--projected` divided
+ * the total by six and called the quotient a monthly rate. A flag that
+ * does not do what its help says is worse than no flag, because the help
+ * is the promise.
  */
 export declare function runBusinessCaseCommand(argv: string[], io?: {
   out: Output;
@@ -1613,7 +1821,7 @@ export declare function runPolicyCommand(argv: string[], io: {
 export declare function runQuarantineCommand(argv: string[], io: {
   out: Output;
   err: Output;
-}): Promise<number>;
+}): number;
 //#endregion
 //#region src/commands/analyze.d.ts
 export declare function runAnalyzeCommand(argv: string[], io: {
@@ -1684,6 +1892,8 @@ export interface UsageErrorDetail {
   /** The flag whose value was rejected (`--tone` for `--tone loud`). */
   flag?: string | undefined;
 }
+export declare const DEFAULT_MAX_DURATION_MS = 600000;
+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;
@@ -1712,9 +1922,14 @@ export declare function parseArgsOrUsage(argv: string[], io: {
  */
 export declare function validateScanTarget(target: string, err: Output): number | null;
 /**
- * Exit-code decision for a finished scan under the given gate level
- * (audit H-7): the previously-dead config.gate field now selects which
- * severities block. Advisory (E0) findings never gate at any level.
+ * Exit-code decision for findings only (audit H-7): the previously-dead
+ * config.gate field selects which severities block. Advisory (E0) findings
+ * never gate at any level.
+ *
+ * This is a findings-only view of the one exit matrix in `claim-evidence`.
+ * Callers that have just finished an ANALYSIS must use `scanExitCode`
+ * instead — this function cannot see `partial`, and a truncated scan with
+ * zero findings is exactly the case that turns a bug into a green build.
  */
 export declare function exitForFindings(findings: readonly Finding[], gate: "advisory" | "error" | "warning"): number;
 /** Testable `ci install` handler. Returns the process exit code. */
@@ -1744,4 +1959,5 @@ export declare function runHelpCommand(argv: string[], io?: {
 }): number;
 export declare function isEntryPoint(): boolean;
 //#endregion
-export { ENGINE_VERSION as CLI_VERSION, type CliArgs, type Output, type ScanHooks };
+export { ENGINE_VERSION as CLI_VERSION, type CliArgs, type Output, type ScanHooks };
+//# sourceMappingURL=cli.d.mts.map