mjolnir-qa 0.5.2 → 0.5.4

package/README.th.md

@@ -61,7 +61,7 @@ npx mjolnir-qa@latest
 รัน `mjolnir explain QA-CI-001` กับ finding แรกด้านบน แล้วคุณจะได้:
 
 ```text
-▚▞ QA-CI-001 — continue-on-error masks a failing verification gate
+▚ QA-CI-001 — continue-on-error masks a failing verification gate
 
 Severity:    error
 Confidence:  high
@@ -370,7 +370,7 @@ repo ว่างจะได้คะแนน `null` ไม่ใช่เล
 ตัวชี้วัดพาดหัวสำหรับชุด Playwright — locator ของคุณทนทานแค่ไหน:
 
 ```text
-▚▞ SELECTOR HEALTH — e2e/checkout.spec.ts
+▚ SELECTOR HEALTH — e2e/checkout.spec.ts
 
   [█████████████████░░░]  83 / 100
   role/text: 2 · testid: 1 · css-chains: 1 ⚠ · xpath: 0
@@ -391,7 +391,7 @@ mjolnir forensics ./test-results/
 ```
 
 ```text
-▚▞ FLAKINESS LEADERBOARD
+▚ FLAKINESS LEADERBOARD
 
 3 tests · 1 failed · 1 flaky · 1 retried
 

package/README.tr.md

@@ -64,7 +64,7 @@ Yukarıdaki ilk bulgu için `mjolnir explain QA-CI-001` komutunu çalıştırın
 elde edeceğiniz:
 
 ```text
-▚▞ QA-CI-001 — continue-on-error masks a failing verification gate
+▚ QA-CI-001 — continue-on-error masks a failing verification gate
 
 Severity:    error
 Confidence:  high
@@ -377,7 +377,7 @@ Playwright takımları için başlık metriği — locator'larınız ne kadar
 dayanıklı:
 
 ```text
-▚▞ SELECTOR HEALTH — e2e/checkout.spec.ts
+▚ SELECTOR HEALTH — e2e/checkout.spec.ts
 
   [█████████████████░░░]  83 / 100
   role/text: 2 · testid: 1 · css-chains: 1 ⚠ · xpath: 0
@@ -400,7 +400,7 @@ mjolnir forensics ./test-results/
 ```
 
 ```text
-▚▞ FLAKINESS LEADERBOARD
+▚ FLAKINESS LEADERBOARD
 
 3 tests · 1 failed · 1 flaky · 1 retried
 

package/README.uk.md

@@ -63,7 +63,7 @@ npx mjolnir-qa@latest
 отримаєте:
 
 ```text
-▚▞ QA-CI-001 — continue-on-error masks a failing verification gate
+▚ QA-CI-001 — continue-on-error masks a failing verification gate
 
 Severity:    error
 Confidence:  high
@@ -376,7 +376,7 @@ OSS-коді** (по ≥ 10 вручну класифікованих знахі
 Головна метрика для Playwright-с'ютів — наскільки стійкі ваші локатори:
 
 ```text
-▚▞ SELECTOR HEALTH — e2e/checkout.spec.ts
+▚ SELECTOR HEALTH — e2e/checkout.spec.ts
 
   [█████████████████░░░]  83 / 100
   role/text: 2 · testid: 1 · css-chains: 1 ⚠ · xpath: 0
@@ -399,7 +399,7 @@ mjolnir forensics ./test-results/
 ```
 
 ```text
-▚▞ FLAKINESS LEADERBOARD
+▚ FLAKINESS LEADERBOARD
 
 3 tests · 1 failed · 1 flaky · 1 retried
 

package/README.vi.md

@@ -62,7 +62,7 @@ Chạy `mjolnir explain QA-CI-001` trên finding đầu tiên ở trên và bạ
 được:
 
 ```text
-▚▞ QA-CI-001 — continue-on-error masks a failing verification gate
+▚ QA-CI-001 — continue-on-error masks a failing verification gate
 
 Severity:    error
 Confidence:  high
@@ -374,7 +374,7 @@ Repo rỗng chấm `null`, không bao giờ 100 giả — xem
 Chỉ số tiêu đề cho suite Playwright — locator của bạn bền bao nhiêu:
 
 ```text
-▚▞ SELECTOR HEALTH — e2e/checkout.spec.ts
+▚ SELECTOR HEALTH — e2e/checkout.spec.ts
 
   [█████████████████░░░]  83 / 100
   role/text: 2 · testid: 1 · css-chains: 1 ⚠ · xpath: 0
@@ -396,7 +396,7 @@ mjolnir forensics ./test-results/
 ```
 
 ```text
-▚▞ FLAKINESS LEADERBOARD
+▚ FLAKINESS LEADERBOARD
 
 3 tests · 1 failed · 1 flaky · 1 retried
 

package/README.zh.md

@@ -59,7 +59,7 @@ reporter 渲染——无任何删减。通过 `npm run docs:demo` 重新生成
 对上面第一条发现运行 `mjolnir explain QA-CI-001`，你会得到：
 
 ```text
-▚▞ QA-CI-001 — continue-on-error masks a failing verification gate
+▚ QA-CI-001 — continue-on-error masks a failing verification gate
 
 Severity:    error
 Confidence:  high
@@ -363,7 +363,7 @@ TypeScript 与 Python 拥有最广的实测覆盖。Java 与 C# 已发布、有
 Playwright 套件的头号指标——你的定位器有多抗造：
 
 ```text
-▚▞ SELECTOR HEALTH — e2e/checkout.spec.ts
+▚ SELECTOR HEALTH — e2e/checkout.spec.ts
 
   [█████████████████░░░]  83 / 100
   role/text: 2 · testid: 1 · css-chains: 1 ⚠ · xpath: 0
@@ -384,7 +384,7 @@ mjolnir forensics ./test-results/
 ```
 
 ```text
-▚▞ FLAKINESS LEADERBOARD
+▚ FLAKINESS LEADERBOARD
 
 3 tests · 1 failed · 1 flaky · 1 retried
 

package/README.zht.md

@@ -59,7 +59,7 @@ reporter 渲染——毫無刪減。以 `npm run docs:demo` 重新產生；
 對上面第一項發現執行 `mjolnir explain QA-CI-001`，你會得到：
 
 ```text
-▚▞ QA-CI-001 — continue-on-error masks a failing verification gate
+▚ QA-CI-001 — continue-on-error masks a failing verification gate
 
 Severity:    error
 Confidence:  high
@@ -363,7 +363,7 @@ TypeScript 與 Python 擁有最廣的實測涵蓋。Java 與 C# 已發布、有
 Playwright 套件的首要指標——你的定位器有多耐操：
 
 ```text
-▚▞ SELECTOR HEALTH — e2e/checkout.spec.ts
+▚ SELECTOR HEALTH — e2e/checkout.spec.ts
 
   [█████████████████░░░]  83 / 100
   role/text: 2 · testid: 1 · css-chains: 1 ⚠ · xpath: 0
@@ -384,7 +384,7 @@ mjolnir forensics ./test-results/
 ```
 
 ```text
-▚▞ FLAKINESS LEADERBOARD
+▚ FLAKINESS LEADERBOARD
 
 3 tests · 1 failed · 1 flaky · 1 retried
 

package/dist/cli.d.mts

@@ -128,6 +128,21 @@ interface Finding {
   /** How to fix — concrete action. */
   fix: string;
   docsUrl?: string;
+  /**
+   * Stable semantic identity of a remediation group: findings that can
+   * be reasoned about and potentially remediated as one root-cause unit
+   * (agent-handoff plan §5.1). This is intentionally a DIFFERENT
+   * concept from `ruleId` (which identifies the detector/rule).
+   *
+   * Current implementation strategy: fixGroupId = ruleId, because each
+   * rule currently represents one remediation group. Future rules may
+   * emit multiple findings belonging to one fix group, or multiple
+   * remediation groups. Consumers MUST NOT rely on
+   * fixGroupId === ruleId permanently.
+   *
+   * Additive within schemaVersion 1.
+   */
+  fixGroupId?: string;
 }
 interface DimensionScore {
   category: RuleCategory;
@@ -147,6 +162,16 @@ interface ScanResult {
   /** Present when --scope changed was requested. */
   scope?: "all" | "changed";
   scopeDegraded?: string;
+  /**
+   * Present when --staged was requested (agent-handoff plan §5.7):
+   * the scan surface was restricted to git staged files, and `files`
+   * is how many survived the intersection. The score reflects THAT
+   * surface — never present it as a full-repo score. Additive within
+   * schemaVersion 1.
+   */
+  staged?: {
+    files: number;
+  };
   /** Detected test frameworks (0.2). Empty + unknown=true when undetectable. */
   frameworks: string[];
   frameworkDetectionUnknown: boolean;
@@ -491,7 +516,7 @@ interface UniversalRule {
  * `scripts/sync-sarif-version.cjs` on release and guarded by
  * `tests/version-consistency.spec.ts` locally.
  */
-declare const CLI_VERSION = "0.5.2";
+declare const CLI_VERSION = "0.5.4";
 declare function buildUniversalRules(root: string, strict?: boolean): Promise<{
   rules: UniversalRule[];
   pluginErrors: string[];
@@ -530,13 +555,75 @@ interface CliArgs {
    * 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;
+  /**
+   * --category <cat> (repeatable): presentation filter — narrows the
+   * TERMINAL findings display (and handoff/why output) to the given
+   * rule categories. NEVER filters the scan, the JSON/SARIF output,
+   * or the score (agent-handoff plan §5.5).
+   */
+  categories?: RuleCategory[];
+  /**
+   * --score: print only the numeric score (or `unknown` when the repo
+   * has no tests) instead of the full report. Pure rendering flag:
+   * scan semantics and exit codes are unchanged (plan §5.6).
+   */
+  scoreOnly?: boolean;
+  /**
+   * --staged: scan-surface restriction (plan §5.7) — intersect the
+   * discovered test files with the git staged file list. Does NOT
+   * change rule semantics; score implications come only from the
+   * narrowed surface (labeled as such in the report).
+   */
+  staged?: boolean;
+  /**
+   * --blocking error|warning|none (plan §5.8): invocation-level gate
+   * override. Controls PROCESS EXIT BEHAVIOR ONLY via the existing
+   * exitForFindings mechanism — detection, rendering, JSON and score
+   * are identical under all three values. Overrides config.gate.
+   */
+  blocking?: "error" | "warning" | "none";
+}
+/** 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[]): CliArgs | null;
+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[];
+/**
+ * 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
@@ -675,7 +762,29 @@ declare function runPwReportCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): number;
-declare function main(argv?: string[]): Promise<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, ScanHooks, buildUniversalRules, exitForFindings, fallbackWorkspace, 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 };