mjolnir-qa 0.4.0

package/dist/cli.d.mts

@@ -0,0 +1,234 @@
+//#region src/types.d.ts
+/**
+ * QA Doctor — canonical types (JSON contract v1, schemaVersion 1).
+ *
+ * STABILITY: This file is public API. Per Product-MVP.txt §24.2:
+ * additive changes only within schemaVersion 1; removing or renaming
+ * fields requires a schemaVersion bump.
+ */
+declare const SCHEMA_VERSION: 1;
+/** Severity ladder. Order matters for sorting and gating. */
+declare const SEVERITY_ORDER: readonly ["error", "warning", "info"];
+type Severity = (typeof SEVERITY_ORDER)[number];
+/**
+ * Confidence that the finding is real. `low` findings render dimmer and
+ * NEVER gate CI regardless of severity (Product-MVP.txt GAP-E).
+ */
+type Confidence = "high" | "medium" | "low";
+/** Epistemic type of the finding (§7). v1 ships deterministic-defect only. */
+type FindingType = "deterministic-defect" | "heuristic-risk" | "observation";
+/**
+ * Evidence levels (Product.txt §9, Honesty Core subset E0–E2):
+ *   E0 — observation only: no proof, informational by definition.
+ *   E1 — weak/partial evidence: heuristic pattern, may be context-dependent.
+ *   E2 — strong static evidence: deterministic defect at its boundary.
+ * The product must never turn missing evidence into confidence: an E0
+ * finding can never deduct points or gate CI, regardless of severity.
+ */
+declare const EVIDENCE_ORDER: readonly ["E0", "E1", "E2"];
+type EvidenceLevel = (typeof EVIDENCE_ORDER)[number];
+/**
+ * QA-native impact framing (#21 Legendary Tier 5): what this finding means
+ * for the QA engineer's actual job, in their vocabulary.
+ */
+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";
+interface Finding {
+  ruleId: string;
+  category: RuleCategory;
+  severity: Severity;
+  confidence: Confidence;
+  findingType: FindingType;
+  /** QA-native impact framing (Tier 5 #21). */
+  qaImpact: QaImpact;
+  /**
+   * How strong the evidence behind this finding is (Honesty Core).
+   * Derived from findingType+confidence unless the rule overrides it.
+   * Optional in the JSON contract (additive within schemaVersion 1).
+   */
+  evidenceLevel?: EvidenceLevel;
+  /** Repo-relative path with forward slashes, regardless of OS. */
+  file: string;
+  /** 1-based. */
+  line: number;
+  /** 1-based. */
+  column: number;
+  message: string;
+  /** Why it matters — one sentence. */
+  why: string;
+  /** How to fix — concrete action. */
+  fix: string;
+  docsUrl?: string;
+}
+interface DimensionScore {
+  category: RuleCategory;
+  score: number;
+  errors: number;
+  warnings: number;
+  infos: number;
+}
+type AnalysisStatus = "complete" | "partial";
+interface ScanResult {
+  schemaVersion: typeof SCHEMA_VERSION;
+  /** False when budget expired or files were skipped (§18.3). */
+  partial: boolean;
+  /** null when no tests found — never fake 100 (R2 empty-state rule). */
+  score: number | null;
+  reason?: "no-tests-found";
+  /** Present when --scope changed was requested. */
+  scope?: "all" | "changed";
+  scopeDegraded?: string;
+  /** Detected test frameworks (0.2). Empty + unknown=true when undetectable. */
+  frameworks: string[];
+  frameworkDetectionUnknown: boolean;
+  dimensions: DimensionScore[];
+  findings: Finding[];
+  analysisStatus: {
+    discovery: AnalysisStatus;
+    rules: AnalysisStatus;
+    skippedFiles: number;
+    durationMs: number;
+  };
+}
+//#endregion
+//#region src/cli.d.ts
+interface CliArgs {
+  target: string;
+  json: boolean;
+  verbose: boolean;
+  maxDurationMs: number;
+  scopeChanged: boolean;
+  format: "terminal" | "json" | "sarif" | "mermaid";
+  /** --width override for terminal box/gauge wrapping (Sprint 5 Task 22). */
+  width?: number;
+  /** --ascii / --no-ascii override for shouldUseAscii()'s heuristic. */
+  ascii?: boolean;
+  /** --tone blunt: opt-in blunter messages (Sprint 9 Task 40). */
+  tone?: "blunt";
+}
+declare function parseArgs(argv: string[]): CliArgs | null;
+declare function runScan(args: CliArgs): ScanResult;
+type Output = (...parts: unknown[]) => void;
+/**
+ * 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).
+ */
+declare function pathMatchesGlob(path: string, glob: string): boolean;
+/** Testable `ci install` handler. Returns the process exit code. */
+declare function runCiInstall(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `suppressions` handler. */
+declare function runSuppressions(io?: {
+  out: Output;
+}): number;
+/** Testable `forensics` handler. */
+declare function runForensicsCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `doctor:playwright` handler. */
+declare function runDoctorPlaywright(argv: string[], io?: {
+  out: Output;
+}): number;
+/** Testable `doctor` handler — self-audit of Mjölnir's own rule base. */
+declare function runDoctorCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `rules` handler — rule catalog with Trust Metadata. */
+declare function runRulesCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/**
+ * Testable `explain <RULE-ID>` handler (Plan.md Sprint 1.3,
+ * Master-Stabilization-Plan Sprint 5 Task 19). Metadata always renders
+ * offline from the registry; the concrete example is real detector
+ * output from the rule's own must-fire fixture when one is findable
+ * (this repo checkout, or --fixtures-root), and honestly omitted
+ * otherwise — never a fabricated example.
+ */
+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;
+/** Testable `triage` handler (Tier 5 #22). */
+declare function runTriageCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `badge` handler (Tier 1 #5). */
+declare function runBadgeCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `debt` handler (Tier 5 #27). */
+declare function runDebtCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `fix` handler (Tier 1 #3) — safe auto-fix with proof. */
+declare function runFixCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `create-rule` handler (Tier 6 #34). */
+declare function runCreateRuleCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `impact` handler (Sprint 6 Task 23). */
+declare function runImpactCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `baseline` handler (Sprint 6 Task 24). */
+declare function runBaselineCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `diff` handler (Sprint 6 Task 24) — new/worsened debt only. */
+declare function runDiffCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `pr-comment` handler (Sprint 6 Task 25). */
+declare function runPrCommentCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `stats` handler (Sprint 6 Task 26). */
+declare function runStatsCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `handover` handler (Tier 5 #28). */
+declare function runHandoverCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `init` handler (Tier 2 #10). */
+declare function runInitCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+/** Testable `pw-report` handler (Tier 2 #9 wedge). */
+declare function runPwReportCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+declare function main(argv?: string[]): number;
+declare function isEntryPoint(): boolean;
+//#endregion
+export { 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 };