canary-test-cli 6.8.0 → 7.0.0

package/dist/engine/analysis/cli.js

@@ -25,7 +25,7 @@
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { Command, Option } from 'commander';
+import { Command, InvalidArgumentError, Option } from 'commander';
 import { jsonIndent2, normalizeUsageExit } from '../cli-common.js';
 import { gateOutcome } from '../core/gate-result.js';
 import { AnalysisEngine } from './engine.js';
@@ -89,6 +89,101 @@ function abstainOnEmptyHistory(store, deps, json, what) {
     }
     return true;
 }
+// --- unit-bearing flags (#673) -----------------------------------------------
+//
+// #670 put the unit in the NAME one layer down -- `analysis/reports.ts` takes
+// `windowRuns`, `deltaPp`, `minRatePct` -- and stopped at the CLI boundary
+// because renaming a flag is user-visible. The flags carried the same silence
+// they always had: the report prints `window: 30 runs`, `20.0pp increase` and
+// `>= 10.0%`, so the unit only ever arrived AFTER the user had guessed. This
+// section closes that gap using the same convention: `<measure><Unit>` in
+// camelCase becomes `--<measure>-<unit>` on the command line.
+//
+// `--delta` is the sharpest case. It is a percentage-POINT threshold that looks
+// like a percentage, so `--delta 20` against a failure rate moving 5% -> 6% is
+// the difference between firing and staying silent, with nothing on screen to
+// say which reading applied.
+/** One decimal or integer, no sign: the only shape these thresholds accept. */
+const UNSIGNED_NUMBER = /^(\d+(\.\d+)?|\.\d+)$/;
+/**
+ * A whole count of runs, >= 1.
+ *
+ * The bare `Number.parseInt` this replaces mapped `--window seven` to `NaN`,
+ * which the query layer happily compared against and matched nothing -- a
+ * silent abstention wearing a clean fleet's clothes. A value that cannot mean
+ * what the flag says is a usage error instead.
+ */
+function parseRuns(flag) {
+    return (raw) => {
+        if (!/^\d+$/.test(raw.trim()) || Number.parseInt(raw, 10) < 1) {
+            throw new InvalidArgumentError(`${flag} takes a whole number of RUNS, at least 1 (e.g. 30); ` +
+                `got "${raw}".`);
+        }
+        return Number.parseInt(raw, 10);
+    };
+}
+/**
+ * A 0-100 value on a percentage scale (`percent` for a rate, `percentage
+ * points` for a delta). Rejecting >100 is what catches the fraction habit from
+ * the other direction; `0.1` is still legal (a tenth of a percent), so the help
+ * text carries that half of the warning.
+ */
+function parsePercentScale(flag, unit) {
+    return (raw) => {
+        const n = Number.parseFloat(raw);
+        if (!UNSIGNED_NUMBER.test(raw.trim()) || !Number.isFinite(n) || n > 100) {
+            throw new InvalidArgumentError(`${flag} takes ${unit} between 0 and 100 (e.g. 10 means ten ${unit}, ` +
+                `not 0.1); got "${raw}".`);
+        }
+        return n;
+    };
+}
+const WINDOW_ALIAS = {
+    canonical: 'windowRuns',
+    legacy: 'window',
+    canonicalFlag: '--window-runs',
+    legacyFlag: '--window',
+    unit: 'a count of runs, not days',
+};
+const DELTA_ALIAS = {
+    canonical: 'deltaPp',
+    legacy: 'delta',
+    canonicalFlag: '--delta-pp',
+    legacyFlag: '--delta',
+    unit: 'percentage points, not percent',
+};
+const MIN_RATE_ALIAS = {
+    canonical: 'minRatePct',
+    legacy: 'minRate',
+    canonicalFlag: '--min-rate-pct',
+    legacyFlag: '--min-rate',
+    unit: 'a percentage, 0-100',
+};
+/**
+ * Fold any deprecated spellings the user typed onto their canonical keys.
+ *
+ * The canonical flag wins when BOTH are given -- the alias is the legacy path,
+ * so an explicit new-style flag is the more deliberate statement of intent.
+ * `getOptionValueSource` is what separates "the user typed it" from "commander
+ * filled in the default"; comparing values would let a canonical default that
+ * happens to equal the alias silently discard the alias.
+ */
+function resolveUnitFlags(opts, cmd, deps, aliases) {
+    // Commander hands option bags back as plain objects keyed by camelCase flag
+    // name; the per-command interfaces describe them but carry no index
+    // signature, so the alias keys are reached through one local widening.
+    const merged = { ...opts };
+    for (const alias of aliases) {
+        if (merged[alias.legacy] === undefined)
+            continue;
+        deps.err(`note: ${alias.legacyFlag} is deprecated; use ${alias.canonicalFlag} ` +
+            `(the value is ${alias.unit}).`);
+        if (cmd.getOptionValueSource(alias.canonical) !== 'cli') {
+            merged[alias.canonical] = merged[alias.legacy];
+        }
+    }
+    return merged;
+}
 function writeArtifacts(artifacts, output) {
     mkdirSync(output, { recursive: true });
     for (const [name, content] of Object.entries(artifacts)) {
@@ -100,12 +195,12 @@ function flakyCmd(opts, deps) {
     if (abstainOnEmptyHistory(store, deps, opts.json === true, 'flake rate')) {
         return;
     }
-    const rows = store.queryFlaky(opts.window, opts.suite ?? null, opts.minRate);
+    const rows = store.queryFlaky(opts.windowRuns, opts.suite ?? null, opts.minRatePct);
     if (opts.json) {
         deps.out(jsonIndent2(rows));
     }
     else {
-        deps.out(buildFlakyReport(rows, opts.window, opts.minRate));
+        deps.out(buildFlakyReport(rows, opts.windowRuns, opts.minRatePct));
     }
 }
 function spikesCmd(opts, deps) {
@@ -130,7 +225,7 @@ function spikesCmd(opts, deps) {
         deps.out(jsonIndent2(rows));
     }
     else {
-        deps.out(buildSpikesReport(rows, opts.delta));
+        deps.out(buildSpikesReport(rows, opts.deltaPp));
     }
 }
 function areaHealthCmd(opts, deps) {
@@ -197,8 +292,8 @@ function digestCmd(opts, deps) {
     }
     const engine = new AnalysisEngine(store);
     const result = engine.run({
-        window: opts.window,
-        delta: opts.delta,
+        windowRuns: opts.windowRuns,
+        deltaPp: opts.deltaPp,
         weeks: opts.weeks,
         minSuites: opts.minSuites,
         suite: opts.suite ?? null,
@@ -229,6 +324,16 @@ function printSlack(flakyCount, regCount, deps) {
     deps.out(lines.join('\n'));
 }
 // --- assembly ----------------------------------------------------------------
+// Option help shared across subcommands. Every analyze option carries a
+// description: a blank one is how the silent unit survived this long, since the
+// value's meaning lived only in the report it eventually printed.
+const DB_URL_ENV = 'CANARY_HISTORY_DB_URL';
+const DB_URL_DESC = 'History store URL (accepted, but analyze reads local NDJSON).';
+const JSON_DESC = 'Emit the rows as JSON instead of a Markdown report.';
+const WINDOW_RUNS_DESC = 'Rolling window measured in RUNS, not days.';
+const MIN_RATE_PCT_DESC = 'Minimum flake rate to report, in PERCENT 0-100 (10 means 10%, not 0.1).';
+const DELTA_PP_DESC = 'Spike threshold as a PERCENTAGE-POINT rise in failure rate ' +
+    '(20 means 5% -> 25%, not 5% -> 6%).';
 /** Build a fresh `analyze` command wired to `depsInit`. */
 export function createAnalyzeCommand(depsInit = {}) {
     const deps = { ...defaultAnalyzeDeps(), ...depsInit };
@@ -239,89 +344,94 @@ export function createAnalyzeCommand(depsInit = {}) {
     program
         .command('flaky')
         .description('Fleet-wide flake leaderboard.')
-        .addOption(new Option('-w, --window <n>')
+        .addOption(new Option('-w, --window-runs <runs>', WINDOW_RUNS_DESC)
         .default(30)
-        .argParser((v) => Number.parseInt(v, 10)))
-        .option('-s, --suite <suite>')
-        .addOption(new Option('--min-rate <pct>')
+        .argParser(parseRuns('--window-runs')))
+        .addOption(new Option('--window <runs>', 'Deprecated alias for --window-runs.').argParser(parseRuns('--window')))
+        .option('-s, --suite <suite>', 'Filter to a specific suite.')
+        .addOption(new Option('--min-rate-pct <percent>', MIN_RATE_PCT_DESC)
         .default(10.0)
-        .argParser((v) => Number.parseFloat(v)))
-        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
-        .option('--json')
-        .action((opts) => {
-        flakyCmd(opts, deps);
+        .argParser(parsePercentScale('--min-rate-pct', 'percent')))
+        .addOption(new Option('--min-rate <percent>', 'Deprecated alias for --min-rate-pct.').argParser(parsePercentScale('--min-rate', 'percent')))
+        .addOption(new Option('--db-url <url>', DB_URL_DESC).env(DB_URL_ENV))
+        .option('--json', JSON_DESC)
+        .action((opts, cmd) => {
+        flakyCmd(resolveUnitFlags(opts, cmd, deps, [WINDOW_ALIAS, MIN_RATE_ALIAS]), deps);
     });
     program
         .command('spikes')
         .description('Recent failure spikes across suites.')
         .option('--since <date>', 'ISO date filter, e.g. 2026-06-01')
-        .addOption(new Option('--delta <pp>')
+        .addOption(new Option('--delta-pp <points>', DELTA_PP_DESC)
         .default(20.0)
-        .argParser((v) => Number.parseFloat(v)))
-        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
-        .option('--json')
-        .action((opts) => {
-        spikesCmd(opts, deps);
+        .argParser(parsePercentScale('--delta-pp', 'percentage points')))
+        .addOption(new Option('--delta <points>', 'Deprecated alias for --delta-pp.').argParser(parsePercentScale('--delta', 'percentage points')))
+        .addOption(new Option('--db-url <url>', DB_URL_DESC).env(DB_URL_ENV))
+        .option('--json', JSON_DESC)
+        .action((opts, cmd) => {
+        spikesCmd(resolveUnitFlags(opts, cmd, deps, [DELTA_ALIAS]), deps);
     });
     program
         .command('area-health')
         .description('Area degradation trends over time.')
-        .addOption(new Option('--weeks <n>')
+        .addOption(new Option('--weeks <weeks>', 'Trend window, in whole weeks.')
         .default(4)
         .argParser((v) => Number.parseInt(v, 10)))
-        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
-        .option('--json')
+        .addOption(new Option('--db-url <url>', DB_URL_DESC).env(DB_URL_ENV))
+        .option('--json', JSON_DESC)
         .action((opts) => {
         areaHealthCmd(opts, deps);
     });
     program
         .command('common-failures')
         .description('Cross-suite failure fingerprinting.')
-        .option('--since <date>')
-        .addOption(new Option('--min-suites <n>')
+        .option('--since <date>', 'ISO date filter, e.g. 2026-06-01')
+        .addOption(new Option('--min-suites <suites>', 'Report a failure only once it appears in this many SUITES.')
         .default(2)
         .argParser((v) => Number.parseInt(v, 10)))
-        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
-        .option('--json')
+        .addOption(new Option('--db-url <url>', DB_URL_DESC).env(DB_URL_ENV))
+        .option('--json', JSON_DESC)
         .action((opts) => {
         commonFailuresCmd(opts, deps);
     });
     program
         .command('regression-candidates')
         .description('Tests newly and consistently broken after a green streak.')
-        .addOption(new Option('--min-green <n>')
+        .addOption(new Option('--min-green <runs>', 'Length of the prior green streak, in RUNS.')
         .default(5)
         .argParser((v) => Number.parseInt(v, 10)))
-        .addOption(new Option('--recent-failures <n>')
+        .addOption(new Option('--recent-failures <runs>', 'Consecutive failing RUNS required after the streak.')
         .default(3)
         .argParser((v) => Number.parseInt(v, 10)))
-        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
-        .option('--json')
+        .addOption(new Option('--db-url <url>', DB_URL_DESC).env(DB_URL_ENV))
+        .option('--json', JSON_DESC)
         .action((opts) => {
         regressionCandidatesCmd(opts, deps);
     });
     program
         .command('digest')
         .description('Combined digest of all five report types.')
-        .addOption(new Option('--window <n>')
+        .addOption(new Option('--window-runs <runs>', WINDOW_RUNS_DESC)
         .default(30)
-        .argParser((v) => Number.parseInt(v, 10)))
-        .addOption(new Option('--delta <pp>')
+        .argParser(parseRuns('--window-runs')))
+        .addOption(new Option('--window <runs>', 'Deprecated alias for --window-runs.').argParser(parseRuns('--window')))
+        .addOption(new Option('--delta-pp <points>', DELTA_PP_DESC)
         .default(20.0)
-        .argParser((v) => Number.parseFloat(v)))
-        .addOption(new Option('--weeks <n>')
+        .argParser(parsePercentScale('--delta-pp', 'percentage points')))
+        .addOption(new Option('--delta <points>', 'Deprecated alias for --delta-pp.').argParser(parsePercentScale('--delta', 'percentage points')))
+        .addOption(new Option('--weeks <weeks>', 'Area-health trend window, in whole weeks.')
         .default(4)
         .argParser((v) => Number.parseInt(v, 10)))
-        .addOption(new Option('--min-suites <n>')
+        .addOption(new Option('--min-suites <suites>', 'Report a failure only once it appears in this many SUITES.')
         .default(2)
         .argParser((v) => Number.parseInt(v, 10)))
-        .option('--suite <suite>')
-        .addOption(new Option('--output <dir>').default('test-results/analysis'))
-        .option('--json')
-        .option('--slack')
-        .addOption(new Option('--db-url <url>').env('CANARY_HISTORY_DB_URL'))
-        .action((opts) => {
-        digestCmd(opts, deps);
+        .option('--suite <suite>', 'Filter to a specific suite.')
+        .addOption(new Option('--output <dir>', 'Directory the Markdown artifacts are ' + 'written to.').default('test-results/analysis'))
+        .option('--json', 'Emit per-section counts as JSON instead of the digest.')
+        .option('--slack', 'Emit a short Slack-formatted summary.')
+        .addOption(new Option('--db-url <url>', DB_URL_DESC).env(DB_URL_ENV))
+        .action((opts, cmd) => {
+        digestCmd(resolveUnitFlags(opts, cmd, deps, [WINDOW_ALIAS, DELTA_ALIAS]), deps);
     });
     for (const sub of program.commands) {
         sub.exitOverride(normalizeUsageExit);

package/dist/engine/analysis/engine.js

@@ -32,19 +32,19 @@ export class AnalysisEngine {
         this.store = store;
     }
     run(opts = {}) {
-        const window = opts.window ?? 30;
-        const delta = opts.delta ?? 20.0;
+        const windowRuns = opts.windowRuns ?? 30;
+        const deltaPp = opts.deltaPp ?? 20.0;
         const weeks = opts.weeks ?? 4;
         const minSuites = opts.minSuites ?? 2;
-        const minFlakeRate = opts.minFlakeRate ?? 10.0;
+        const minFlakeRatePct = opts.minFlakeRatePct ?? 10.0;
         const minGreen = opts.minGreen ?? 5;
         const recentFailures = opts.recentFailures ?? 3;
         const suite = opts.suite ?? null;
-        const flaky = this.store.queryFlaky(window, suite, minFlakeRate);
+        const flaky = this.store.queryFlaky(windowRuns, suite, minFlakeRatePct);
         const suitesToQuery = suite ? [suite] : this.discoverSuites();
         const spikesRows = [];
         for (const s of suitesToQuery) {
-            const summary = this.store.querySummary(s, window * 2);
+            const summary = this.store.querySummary(s, windowRuns * 2);
             for (const row of def(summary.runs, [])) {
                 // query_summary rows omit suite; the spikes builder groups by it, so
                 // tag each pooled row with the suite it came from (matches Python).
@@ -67,14 +67,14 @@ export class AnalysisEngine {
             areaHealth: areaRows,
             commonFailures: commonRows,
             regressionCandidates,
-            window,
-            delta,
+            windowRuns,
+            deltaPp,
             weeks,
             minSuites,
         });
         const artifacts = {
-            'flaky.md': buildFlakyReport(flaky, window, minFlakeRate),
-            'spikes.md': buildSpikesReport(spikesRows, delta),
+            'flaky.md': buildFlakyReport(flaky, windowRuns, minFlakeRatePct),
+            'spikes.md': buildSpikesReport(spikesRows, deltaPp),
             'area-health.md': buildAreaHealthReport(areaRows, weeks),
             'common-failures.md': buildCommonFailuresReport(commonRows, minSuites),
             'regression-candidates.md': buildRegressionCandidatesReport(regressionCandidates),

package/dist/engine/cli-commands.js

@@ -19,7 +19,7 @@ import { ckInitCmd } from './company-knowledge-cli.js';
 import { extractFrameworkHint } from './core/classifier.js';
 import { VALID_CATEGORIES, buildFeedback } from './core/feedback.js';
 import { OverlayNotFound, listOverlays, resolveOverlay, } from './core/overlays.js';
-import { JS_TEST_EXTENSIONS, lintableFramework } from './core/static-linter.js';
+import { JS_TEST_EXTENSIONS, frameworkForPath } from './core/static-linter.js';
 import { RunSummary } from './core/ticket-updater.js';
 import { renderBanner } from './ui/banner.js';
 import { ARROW, CHECK, CHECK_MARK, CROSS, EM_DASH, HAMMER, NEXT, REDX, ROCKET, WARN, WRENCH, } from './main-deps.js';
@@ -462,7 +462,7 @@ function abstainOnZeroFiles(files, path, deps, json) {
  * from a scanner that could not parse the input is an abstention, not a pass.
  */
 function abstainOnUnlintableFile(path, deps, json) {
-    if (lintableFramework(path) !== null)
+    if (frameworkForPath(path) !== null)
         return;
     const ext = extname(path) || basename(path);
     abstain(`Cannot lint ${ext} — no ruleset parses it, so a clean result would be ` +