mjolnir-qa 0.5.0 → 0.5.3

package/dist/cli.d.mts

@@ -34,6 +34,52 @@ type EvidenceLevel = (typeof EVIDENCE_ORDER)[number];
 type QaImpact = "BLOCKS-RELEASE" | "FLAKY-RISK" | "FALSE-GREEN" | "HYGIENE";
 /** Rule namespaces are frozen public API (§18.4). IDs are never reused. */
 type RuleCategory = "QA-TEST" | "QA-TQUAL" | "QA-PW" | "QA-CI";
+/**
+ * Trust levels (Verification Trust Evolution Plan §16): the OVERALL
+ * trust a consumer can place in one finding, combining the static
+ * evidence ladder (E0–E2) with RUNTIME corroboration from a real run
+ * report. Exposed honestly, never overclaimed:
+ *   L0 — observation only (E0, no runtime evidence).
+ *   L1 — heuristic static evidence (E1), no runtime evidence.
+ *   L2 — deterministic static evidence (E2), no runtime evidence.
+ *   L3 — RUNTIME: the file containing this finding appeared in a real
+ *        run report (tests in that file executed).
+ *   L4 — RUNTIME: the specific test containing this finding was
+ *        identified in the report and executed (its outcome is known).
+ *   L5 — RUNTIME: the run verdict directly corroborates the DEFECT
+ *        class (e.g. a flake-risk finding whose test actually flaked,
+ *        retried, or timed out in the report).
+ * INVARIANT (structurally enforced): L3–L5 require runtime
+ * corroboration — a static-only finding can never claim L4/L5.
+ */
+declare const TRUST_ORDER: readonly ["L0", "L1", "L2", "L3", "L4", "L5"];
+type TrustLevel = (typeof TRUST_ORDER)[number];
+/**
+ * Runtime corroboration for one finding (plan §16): what a real run
+ * report says about the code this finding points at. Additive within
+ * schemaVersion 1; absent means "no runtime evidence" — never
+ * fabricated.
+ */
+interface RuntimeCorroboration {
+  /** Granularity of what the runtime report could vouch for. */
+  level: "file" | "test" | "defect";
+  /** Report format the evidence came from. */
+  source: "playwright-json" | "junit-xml";
+  /** Number of tests executed in the finding's file (any level). */
+  testsExecuted: number;
+  /**
+   * The containing test's verdict, when the finding line falls inside a
+   * test the report identifies (level "test"/"defect").
+   */
+  matchedTest?: {
+    title: string;
+    finalStatus: string;
+    attempts: number;
+    passedOnRetry: boolean;
+    everFailed: boolean;
+    skipped: boolean;
+  };
+}
 interface Finding {
   ruleId: string;
   category: RuleCategory;
@@ -57,6 +103,19 @@ interface Finding {
   measuredFpRate?: number;
   /** Classified (TP+FP) verdicts behind `measuredFpRate`. */
   measuredFpN?: number;
+  /**
+   * Runtime corroboration from a real run report (plan §16), stamped
+   * when a report was available and matched this finding's file/test.
+   * Absent means "no runtime evidence" — the static evidence ladder
+   * (E0–E2) is all the consumer has. Additive within schemaVersion 1.
+   */
+  runtimeCorroboration?: RuntimeCorroboration;
+  /**
+   * Overall trust level (plan §16, see TRUST_ORDER). Derived
+   * deterministically from evidenceLevel + runtimeCorroboration;
+   * stamped with the corroboration pass. Additive within schemaVersion 1.
+   */
+  trustLevel?: TrustLevel;
   /** Repo-relative path with forward slashes, regardless of OS. */
   file: string;
   /** 1-based. */
@@ -101,14 +160,326 @@ interface ScanResult {
   rawDeductions?: number;
   /** Number of findings suppressed by active config entries (suppression transparency). */
   suppressionCount?: number;
+  /**
+   * Third-party plugin code that executed during this scan (audit S-8).
+   * Plugins run with full Node privileges by documented design — anyone
+   * reading a report must be able to tell whether they ran. Absent
+   * when no plugins are configured.
+   */
+  plugins?: Array<{
+    name: string;
+    rules: number;
+  }>;
+  /**
+   * Agentic Trust Profile (plan §17): per-scan provenance metadata —
+   * share of test files carrying detected generative markers and the
+   * findings split across those surfaces. PROVENANCE IS NOT TRUST: the
+   * profile never changes scoring, evidence levels, or tier behavior
+   * (§17.4 — the same evidence standard applies regardless of author).
+   * Additive within schemaVersion 1; present on every completed scan.
+   */
+  agenticProfile?: {
+    testFiles: number;
+    generatedMarkedFiles: number;
+    codegenLikeFiles: number;
+    /** generatedMarkedFiles / testFiles (0..1). */
+    shareMarkedGenerated: number;
+    findingsInGeneratedFiles: number;
+    findingsInUnmarkedFiles: number;
+    note: string;
+  };
   analysisStatus: {
     discovery: AnalysisStatus;
     rules: AnalysisStatus;
     skippedFiles: number;
     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.
+     */
+    truncationReasons?: 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;
+  };
+  /**
+   * Local incremental cache report (Beta-to-Stable plan, M5.2). Present
+   * only when the scan ran with `--cache`; additive within
+   * schemaVersion 1. The cache is content-addressed and local-only
+   * (plan A-2) — it never leaves the machine and never touches the
+   * network.
+   */
+  cache?: {
+    /** Files whose rule verdicts were reused from the cache. */
+    hits: number;
+    /** Files analyzed fresh this run (cache misses). */
+    misses: number;
+    /** Absolute path of the cache file — auditable, gitignored. */
+    file: string;
   };
 }
 //#endregion
+//#region src/discovery/workspace.d.ts
+/**
+ * Repository discovery (Sprint-Plan W1-03).
+ * Finds project root, parses package.json, detects npm/yarn/pnpm workspaces.
+ * Monorepo depth beyond workspaces is a documented launch cut (§29.1).
+ */
+interface Workspace {
+  /** Absolute path of the workspace/project root. */
+  root: string;
+  name: string;
+  packageJson: Record<string, unknown>;
+  /** Glob patterns from the root package.json workspaces field. */
+  workspaceGlobs: string[];
+}
+//#endregion
+//#region src/engine/tier-policy.d.ts
+type Tier = "core" | "extended" | "quarantine";
+//#endregion
+//#region src/rules/rule.d.ts
+/**
+ * How the rule's primary detection decision is made (Verification Trust
+ * Evolution Plan §09.6/§12.1 — the enforced D6 enum, replacing free text):
+ * - "LEXICAL": pattern matching over source text (regex over `codeText`,
+ *   masked text, YAML/manifest text, suite-wide absence sweeps).
+ * - "AST": structural analysis of a parsed syntax tree (ts-morph node
+ *   walks, tree-sitter queries) is the core decision.
+ * - "SEMANTIC": name/type/symbol or call-graph reasoning beyond
+ *   single-file syntax (reserved — no rule ships this yet).
+ * - "FRAMEWORK": framework configuration/manifest semantics drive the
+ *   decision (CI workflow job/step structure, test-command gating).
+ * - "RUNTIME": execution evidence drives the decision (reserved —
+ *   Phase 6).
+ */
+type DetectionStrategy = "LEXICAL" | "AST" | "SEMANTIC" | "FRAMEWORK" | "RUNTIME";
+interface RuleMeta {
+  /** Frozen public API — never reused (§18.4). */
+  id: string;
+  category: RuleCategory;
+  title: string;
+  severity: Severity;
+  confidence: Confidence;
+  findingType: FindingType;
+  /** QA-native impact framing (#21): what this means for the QA engineer. */
+  qaImpact: QaImpact;
+  /**
+   * Honesty Core: explicit evidence level. When omitted, findings derive
+   * it from findingType+confidence (deriveEvidenceLevel). Only set this
+   * when the rule's evidence is genuinely stronger/weaker than the
+   * default derivation implies.
+   */
+  evidenceLevel?: EvidenceLevel;
+  /** Rule IDs that can fire on the same root cause (dedup pass, R6). */
+  overlapWith?: string[];
+  /** Languages this rule applies to, e.g. ["typescript", "python"]. */
+  languages?: string[];
+  /** Frameworks the rule is meaningful for, e.g. ["jest", "vitest", "playwright"]. */
+  frameworks?: string[];
+  /**
+   * Declared false-positive risk of the rule as shipped. Part of the
+   * north-star contract: a rule that cannot honestly classify its FP risk
+   * should not be enforced.
+   */
+  falsePositiveRisk?: "low" | "medium" | "high";
+  /** Whether `mjolnir fix` (or a future autofix) can safely repair it. */
+  autofix?: boolean;
+  /**
+   * How detection works, as an enforced enum (plan §09.6/§12.1 — D6
+   * closed). Free-text declarations were migrated to the enum in
+   * Phase 2; the registry ratchet (tests/rules.registry.spec.ts) makes
+   * omission or a bad value a CI failure, so new rules must declare it.
+   */
+  detectionStrategy?: DetectionStrategy;
+  /**
+   * Verbatim legacy detection-strategy description preserved from the
+   * pre-enum free-text era (D6 migration). Optional; carries the nuance
+   * the enum alone cannot ("regex pattern + inside-string oracle", …).
+   * Rendered by the rule docs pages alongside the enum.
+   */
+  detectionNotes?: string;
+  /** First released version (semver). Immutable once set. */
+  introduced?: string;
+  /**
+   * Tier assignment (Phase 4 — Tempering Plan; measurement-dependent
+   * default per Verification Trust Evolution Plan §11.2 Step 2).
+   * - "core": ships in the default report (≤10% measured FP rate)
+   * - "extended": included by default, lower confidence (≤30% FP)
+   * - "quarantine": opt-in only via --strict (>30% FP or unmeasured)
+   * When omitted, the tier resolves measurement-dependently via
+   * `effectiveTier` (src/rules/measurement.ts): core for rules with a
+   * valid corpus measurement, extended (displayed PROVISIONAL)
+   * otherwise — an unmeasured rule can never default into core.
+   */
+  tier?: "core" | "extended" | "quarantine";
+  /**
+   * Detector implementation revision (Verification Trust Evolution Plan
+   * §07). Increment on ANY detection-logic change — pattern, scoping,
+   * AST adoption, rung change. A `MEASURED_FP` entry recorded against a
+   * different revision is stale: the measurement is invalidated,
+   * displayed as PROVISIONAL, and the rule cannot sit in effective core
+   * until re-measured (registry ratchet, §20.3). Default when omitted: 1
+   * (the current first-generation detectors).
+   */
+  detectorRevision?: number;
+  /**
+   * This finding proves the reported pass does not cover what it claims.
+   *
+   * `.only` makes the runner skip every other test; a masked CI gate means a
+   * failure was ignored. Either way the suite's green is not evidence, and no
+   * amount of density normalization should be able to average that away — a
+   * two-test repo with `.only` is as compromised as a two-thousand-test one.
+   *
+   * Findings marked here cap the score into the UNWORTHY band regardless of
+   * exposure. Reserved for mechanisms where the bypass is unambiguous, not for
+   * findings that merely weaken a single test.
+   */
+  suiteInvalidating?: boolean;
+}
+interface SourceFileContext {
+  /** Repo-relative path, forward slashes. */
+  path: string;
+  text: string;
+  /**
+   * Parsed AST provided by the engine — ts-morph SourceFile for
+   * TypeScript files, tree-sitter Tree for Java/C# (Phase 0.5 parse
+   * stage), workflow DOM for GitHub Actions. Typed as unknown here to
+   * keep the core rule contract decoupled; each language's helper
+   * narrows it (getTsSourceFile / getTreeSitterTree).
+   */
+  ast?: unknown;
+  /**
+   * Code-only text view: string literals and comments blanked to spaces,
+   * newlines preserved so line/column indices stay exact (Phase 1 FP
+   * firewall). Rules that must never fire on prose inside strings or
+   * comments use this instead of `text`. Falls back to `text` when
+   * unavailable.
+   */
+  codeText?: string;
+}
+type RuleFn = (ctx: SourceFileContext) => Omit<Finding, "ruleId" | "category">[];
+/**
+ * Optional L2 structural-analysis hook (Verification Trust Evolution
+ * Plan §13.2). When the engine provides a parsed AST on the context
+ * (ts-morph SourceFile for TypeScript, tree-sitter Tree for Java/C#),
+ * the hook produces the findings; its regex path is the MANDATORY
+ * fallback, never optional — `undefined` return (or no `ctx.ast`)
+ * means "no AST — run the regex path", so fixture harnesses, grammar
+ * load failures, and degraded scans all keep working (ts-ast fallback
+ * discipline, QA-PW-002 pattern). This seam is what lets a rule
+ * declare `detectionStrategy: "AST"` honestly: the structural path is
+ * the decision when a tree exists, and the regex path is documented
+ * degraded detection, not a second source of truth.
+ */
+type AstQueryHook = (ctx: SourceFileContext) => Omit<Finding, "ruleId" | "category">[] | undefined;
+type AppliesTo = "test-files" | "ci-workflows" | "python" | "java" | "csharp" | "all";
+interface QADoctorRule extends RuleMeta {
+  /** Which file kinds this rule applies to. */
+  appliesTo: AppliesTo;
+  /**
+   * Config-hygiene rules: the engine only feeds these rules config
+   * files (and never feeds them test files), and never feeds test-file
+   * rules a config. Set on rules whose detection gates on a config
+   * filename (QA-PW-121/122/141/143/144). Without this flag the
+   * generic test rules would fire nonsense on configs (e.g. QA-TEST-003
+   * "no assertions" on every playwright.config.ts).
+   */
+  configRule?: boolean;
+  /**
+   * Config filename patterns (regex SOURCE strings) this config rule
+   * gates on (plan §15.2): the adapter matches these against the file's
+   * basename, replacing the hard-coded playwright.config.* regex that
+   * used to live in the adapter AND duplicated inside each config rule.
+   * The internal regex gate in `run` stays as belt-and-suspenders for
+   * direct harness invocation.
+   */
+  configFiles?: string[];
+  /**
+   * Framework opt-in (plan §15.1, defect D7): when declared, the rule
+   * runs on a file only if the file's own framework tags (its
+   * imports/usings) intersect it. Files without tags are always
+   * analyzed (open-when-unknown) — the dimension narrows, it never
+   * silently drops evidence. Mirror of UniversalRule.frameworks,
+   * threaded through asUniversal.
+   */
+  frameworksOverride?: string[];
+  /**
+   * L2 structural-analysis path (§13.2): runs when the engine supplies
+   * a parsed AST for the file. MUST be paired with a regex fallback in
+   * `run` (mandatory fallback discipline) — see AstQueryHook.
+   */
+  astQuery?: AstQueryHook;
+  run: RuleFn;
+}
+//#endregion
+//#region src/engine/adapter.d.ts
+/** Semantic operations a parsed file exposes to rules. */
+interface ParsedFile {
+  path: string;
+  text: string;
+  /** Adapter-specific AST; typed loosely until tree-sitter unifies it. */
+  ast?: unknown;
+  /**
+   * Code-only text view: string literals and comments blanked to spaces,
+   * newlines preserved so line/column indices stay exact. Regex rules
+   * that must never fire on prose inside strings or comments use this
+   * instead of `text`. Computed lazily per adapter.
+   */
+  codeText?: string;
+  /**
+   * Per-file framework tags (Verification Trust Evolution Plan §15.1,
+   * defect D7): derived from the file's OWN imports/usings/imports-lines
+   * by the adapter ("playwright", "jest", "cypress", "junit", "testng",
+   * "selenium", "nunit", "xunit", "mstest", "pytest", …). EMPTY/absent
+   * means "no per-file evidence" — framework filtering is then OPEN (a
+   * rule declaring `frameworks` still runs), never a silent skip.
+   */
+  frameworkTags?: readonly string[];
+}
+/**
+ * A rule that declares which adapters it supports. Backward compatible:
+ * legacy 'test-files' maps to ['typescript'], 'ci-workflows' to
+ * ['github-actions'].
+ */
+interface UniversalRule {
+  id: string;
+  category: string;
+  appliesTo: readonly string[];
+  /**
+   * Config-hygiene rule (see QADoctorRule.configRule): the adapter runs
+   * these ONLY on the config files named in `configFiles`, and runs
+   * every other rule only on test files. Keeps config rules measurable
+   * in real scans without letting generic test rules fire nonsense on
+   * configs.
+   */
+  configOnly?: boolean;
+  /**
+   * Config filename patterns (regex sources) this config rule gates on
+   * (plan §15.2 — replaces the hard-coded playwright.config.* regex
+   * that used to live in the TS adapter AND duplicated inside each
+   * config rule). Empty/absent + configOnly=true falls back to the
+   * adapter's built-in config list.
+   */
+  configFiles?: readonly string[];
+  /**
+   * Framework opt-in (plan §15.1, defect D7): when declared, the rule
+   * runs on a file only if the file's own `frameworkTags` intersect it.
+   * Files without tags are always analyzed (open-when-unknown).
+   */
+  frameworks?: readonly string[];
+  /**
+   * Detector implementation revision (§07), threaded through asUniversal
+   * so the M5.2 cache digest can fold it in; the stale-measurement
+   * machinery reads it from the registry, the cache from this field.
+   */
+  detectorRevision?: number;
+  run(file: ParsedFile): Array<Omit<Finding, "ruleId" | "category">>;
+}
+//#endregion
 //#region src/cli.d.ts
 /**
  * Tool version for `mjolnir --version`.
@@ -120,7 +491,17 @@ interface ScanResult {
  * `scripts/sync-sarif-version.cjs` on release and guarded by
  * `tests/version-consistency.spec.ts` locally.
  */
-declare const CLI_VERSION = "0.5.0";
+declare const CLI_VERSION = "0.5.3";
+declare function buildUniversalRules(root: string, strict?: boolean): Promise<{
+  rules: UniversalRule[];
+  pluginErrors: string[];
+  tierByRuleId: Map<string, Tier>;
+  pluginMeta: Array<{
+    name: string;
+    rules: number;
+  }>;
+  externalRules: QADoctorRule[];
+}>;
 interface CliArgs {
   target: string;
   json: boolean;
@@ -136,17 +517,81 @@ interface CliArgs {
   tone?: "blunt";
   /** --strict: include quarantine-tier rules in the scan (Phase 4). */
   strict?: boolean;
+  /** --base <ref>: base ref for --scope changed (audit H-10). */
+  base?: string;
+  /** --debug: print errors swallowed by crash isolation (audit R-9). */
+  debug?: boolean;
+  /** --record-milestones: let a scan write .mjolnir/stats.json (audit R-1). */
+  recordMilestones?: boolean;
+  /**
+   * --cache: reuse per-file rule verdicts from the local content-addressed
+   * cache (M5.2). Post-loop processing always re-runs; the cache only
+   * short-circuits the read+parse+rule loop for byte-identical files
+   * under an unchanged rule set. Local-only, never leaves the machine.
+   */
+  cache?: boolean;
+  /**
+   * --no-progress: never render the live scan-progress line, even on an
+   * interactive TTY (plan M3, additive flag). Progress is stderr-only
+   * and auto-disabled in CI/machine formats; this flag is the manual off.
+   */
+  noProgress?: boolean;
 }
-declare function parseArgs(argv: string[]): CliArgs | null;
-declare function runScan(args: CliArgs): ScanResult;
-type Output = (...parts: unknown[]) => void;
+/** A usage-error detail: the offending token, when one exists. */
+interface UsageErrorDetail {
+  /** The unknown flag or rejected value (e.g. `--nope`, `loud`). */
+  token?: string | undefined;
+  /** The flag whose value was rejected (`--tone` for `--tone loud`). */
+  flag?: string | undefined;
+}
+declare function parseArgs(argv: string[], onError?: (detail: UsageErrorDetail) => void): CliArgs | null;
+/** Hand-rolled Levenshtein distance (plan M2: no new dependencies). */
+declare function levenshtein(a: string, b: string): number;
+/** Nearest known flags within distance ≤ 2, nearest first. */
+declare function nearestFlags(flag: string, max?: number): string[];
 /**
- * Minimal glob match for suppression `files` patterns. Supports:
- *   "tests/**"  — everything under tests/
- *   "**‍/*.spec.ts" — any depth ending pattern
- *   "tests/foo.spec.ts" — exact path
- * Forward slashes only (findings always use normalized paths).
+ * Friendly usage error (plan M2, exit 10 preserved): nearest-flag
+ * suggestion, the valid neighbors, and the exact help command. Printed
+ * to stderr; findings/usage stay on their documented streams.
  */
+declare function usageErrorMessage(detail: UsageErrorDetail): string;
+interface ScanHooks {
+  /** Invoked when a rule throws on a file (audit R-9). */
+  onRuleCrash?: (ruleId: string, file: string, error: unknown) => void;
+  /** Invoked for non-fatal config warnings (bug-audit M4). */
+  onConfigWarning?: (message: string) => void;
+  /**
+   * Live-progress feed (plan M3, additive). Fired from the per-file
+   * parse+rules loop and the phase boundaries. Render-on-event only —
+   * the scan never waits on a timer, and output contracts are
+   * unchanged when the hook is absent.
+   */
+  onProgress?: (e: {
+    phase: "discover" | "parse" | "rules" | "score";
+    done?: number | undefined;
+    total?: number | undefined;
+    detail?: string | undefined;
+  }) => void;
+}
+/**
+ * Workspace fallback for targets with no discoverable project root
+ * (package.json-less repos, Python/Java/C# trees). Exported pure so the
+ * root-path degenerate case (`C:\` → basename "") is testable without
+ * scanning a filesystem root.
+ */
+declare function fallbackWorkspace(targetAbs: string): Workspace;
+/**
+ * Testable default scan path core. `hooks` lets callers observe
+ * normally-invisible events (swallowed rule crashes) without changing
+ * the ScanResult contract beyond the rulesCrashed counter.
+ *
+ * Async since the Verification Trust Evolution Plan Phase 0.5 (§10): the
+ * per-file loop awaits the adapter parse stage (WASM grammar load is
+ * inherently async); `runRules` and every rule stay synchronous and
+ * consume `ParsedFile.ast`. Callers await the returned promise.
+ */
+declare function runScan(args: CliArgs, hooks?: ScanHooks): Promise<ScanResult>;
+type Output = (...parts: unknown[]) => void;
 declare function pathMatchesGlob(path: string, glob: string): boolean;
 /** Testable `ci install` handler. Returns the process exit code. */
 declare function runCiInstall(argv: string[], io?: {
@@ -156,6 +601,7 @@ declare function runCiInstall(argv: string[], io?: {
 /** Testable `suppressions` handler. */
 declare function runSuppressions(io?: {
   out: Output;
+  err?: Output;
 }): number;
 /** Testable `forensics` handler. */
 declare function runForensicsCommand(argv: string[], io?: {
@@ -165,7 +611,8 @@ declare function runForensicsCommand(argv: string[], io?: {
 /** Testable `doctor:playwright` handler. */
 declare function runDoctorPlaywright(argv: string[], io?: {
   out: Output;
-}): number;
+  err?: Output;
+}): Promise<number>;
 /** Testable `doctor` handler — self-audit of Mjölnir's own rule base. */
 declare function runDoctorCommand(argv: string[], io?: {
   out: Output;
@@ -175,7 +622,7 @@ declare function runDoctorCommand(argv: string[], io?: {
 declare function runRulesCommand(argv: string[], io?: {
   out: Output;
   err: Output;
-}): number;
+}): Promise<number>;
 /**
  * Testable `explain <RULE-ID>` handler (Plan.md Sprint 1.3,
  * Master-Stabilization-Plan Sprint 5 Task 19). Metadata always renders
@@ -188,11 +635,16 @@ declare function runExplainCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): number;
-/** Testable default scan path. */
 declare function runScanCommand(argv: string[], io?: {
   out: Output;
   err: Output;
-}): number;
+}): Promise<number>;
+/**
+ * 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.
+ */
+declare function exitForFindings(findings: readonly Finding[], gate: "advisory" | "error" | "warning"): number;
 /** Testable `triage` handler (Tier 5 #22). */
 declare function runTriageCommand(argv: string[], io?: {
   out: Output;
@@ -202,17 +654,17 @@ declare function runTriageCommand(argv: string[], io?: {
 declare function runBadgeCommand(argv: string[], io?: {
   out: Output;
   err: Output;
-}): number;
+}): Promise<number>;
 /** Testable `debt` handler (Tier 5 #27). */
 declare function runDebtCommand(argv: string[], io?: {
   out: Output;
   err: Output;
-}): number;
+}): Promise<number>;
 /** Testable `fix` handler (Tier 1 #3) — safe auto-fix with proof. */
 declare function runFixCommand(argv: string[], io?: {
   out: Output;
   err: Output;
-}): number;
+}): Promise<number>;
 /** Testable `create-rule` handler (Tier 6 #34). */
 declare function runCreateRuleCommand(argv: string[], io?: {
   out: Output;
@@ -222,22 +674,22 @@ declare function runCreateRuleCommand(argv: string[], io?: {
 declare function runImpactCommand(argv: string[], io?: {
   out: Output;
   err: Output;
-}): number;
+}): Promise<number>;
 /** Testable `baseline` handler (Sprint 6 Task 24). */
 declare function runBaselineCommand(argv: string[], io?: {
   out: Output;
   err: Output;
-}): number;
+}): Promise<number>;
 /** Testable `diff` handler (Sprint 6 Task 24) — new/worsened debt only. */
 declare function runDiffCommand(argv: string[], io?: {
   out: Output;
   err: Output;
-}): number;
+}): Promise<number>;
 /** Testable `pr-comment` handler (Sprint 6 Task 25). */
 declare function runPrCommentCommand(argv: string[], io?: {
   out: Output;
   err: Output;
-}): number;
+}): Promise<number>;
 /** Testable `stats` handler (Sprint 6 Task 26). */
 declare function runStatsCommand(argv: string[], io?: {
   out: Output;
@@ -247,7 +699,7 @@ declare function runStatsCommand(argv: string[], io?: {
 declare function runHandoverCommand(argv: string[], io?: {
   out: Output;
   err: Output;
-}): number;
+}): Promise<number>;
 /** Testable `init` handler (Tier 2 #10). */
 declare function runInitCommand(argv: string[], io?: {
   out: Output;
@@ -258,7 +710,29 @@ declare function runPwReportCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): number;
-declare function main(argv?: string[]): number;
+declare function main(argv?: string[], io?: {
+  out: Output;
+  err: Output;
+}): Promise<number>;
+/**
+ * `mjolnir help` / `mjolnir help <verb>` (plan M2). `--help`/`-h` and
+ * `<verb> --help` route here too. Exit 0 — help answers a question.
+ * Two-word verbs (`ci install`) are resolved first via the join of the
+ * leading non-flag tokens, then the single-word form.
+ */
+declare function runHelpCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/**
+ * Friendly exit-20 path (plan M2): the crash says it's Mjölnir's bug,
+ * not the user's repo, carries the underlying message for a report, and
+ * prints the stack ONLY when `debug` is set (uniform across
+ * subcommands — they don't parse scan flags). Tests pin
+ * /internal error/i. Exported so the --debug stack arm is directly
+ * spec-coverable (spawning a real crash under --debug would be flaky).
+ */
+declare function internalErrorMessage(err: unknown, emit: (s: string) => void, debug: boolean): void;
 declare function isEntryPoint(): boolean;
 //#endregion
-export { CLI_VERSION, Output, isEntryPoint, main, parseArgs, pathMatchesGlob, runBadgeCommand, runBaselineCommand, runCiInstall, runCreateRuleCommand, runDebtCommand, runDiffCommand, runDoctorCommand, runDoctorPlaywright, runExplainCommand, runFixCommand, runForensicsCommand, runHandoverCommand, runImpactCommand, runInitCommand, runPrCommentCommand, runPwReportCommand, runRulesCommand, runScan, runScanCommand, runStatsCommand, runSuppressions, runTriageCommand };
+export { CLI_VERSION, Output, ScanHooks, UsageErrorDetail, buildUniversalRules, exitForFindings, fallbackWorkspace, internalErrorMessage, isEntryPoint, levenshtein, main, nearestFlags, parseArgs, pathMatchesGlob, runBadgeCommand, runBaselineCommand, runCiInstall, runCreateRuleCommand, runDebtCommand, runDiffCommand, runDoctorCommand, runDoctorPlaywright, runExplainCommand, runFixCommand, runForensicsCommand, runHandoverCommand, runHelpCommand, runImpactCommand, runInitCommand, runPrCommentCommand, runPwReportCommand, runRulesCommand, runScan, runScanCommand, runStatsCommand, runSuppressions, runTriageCommand, usageErrorMessage };