canary-test-cli 7.0.0 → 7.1.0

package/dist/engine/core/persona.js

@@ -0,0 +1,421 @@
+/**
+ * Personas as a first-class engine concept (issue #462).
+ *
+ * Audience adaptation used to be hand-rolled per skill: each one restated some
+ * variant of "if tester, use simpler words" in its own prose, with its own
+ * vocabulary and its own inference rules. Nothing shared a definition, so tone
+ * drifted between skills and an overlay had nothing to override. The drift was
+ * measurable — `canary-edge-case-discovery` documented
+ * `--level sdet|junior|manual` while {@link
+ * import('./environment-detect.js').detectUserLevel} returned
+ * `sdet|manual|unknown`, and no code read either.
+ *
+ * This module replaces that with one definition skills **consult**:
+ *
+ *   - a **registry** (`ts/src/data/personas/registry.json`) naming each
+ *     audience, how much explanation it wants, which output formats suit it,
+ *     and whether choices should be annotated with their reasoning;
+ *   - a pure **resolver** that picks one from an explicit choice, a detected
+ *     signal, or a fallback, and reports **which** and **why**;
+ *   - **overlay extension** through the same `precedence` arbitration the
+ *     overlay contract already defines for skill-name collisions (#333).
+ *
+ * Three deliberate boundaries, each of which was a decision rather than an
+ * omission:
+ *
+ * **Voice is not a persona field.** `voice/discovery.md` already resolves a
+ * named voice profile from its own project config, scoped by its own globs.
+ * Audience depth and character voice are orthogonal axes — a senior SDET may
+ * want a voiced-but-terse report while a manual tester wants the same voice
+ * with more explanation — so collapsing them into one field would make half
+ * the combinations inexpressible.
+ *
+ * **The fallback is explanatory, not degraded.** Most users will never
+ * configure this, so the no-signal answer has to be a good answer. Erring
+ * explanatory is the repo owner's stated default on #341 and #342: over-
+ * explaining is a mild annoyance, under-explaining silently fails a manual
+ * tester. It is *not* the maximum-explanation persona either, which would
+ * assert an audience nobody claimed.
+ *
+ * **Nothing here reads the environment.** Like `environment-detect.ts`, every
+ * input arrives as an argument, so the resolver is deterministic and the
+ * decision of where a signal comes from stays with the caller.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { uncertainDetectionMessage } from './detection.js';
+import { listOverlays, registryPrecedence, resolveOverlay, } from './overlays.js';
+/** How much explanation a persona wants around the same finding. */
+const DEPTHS = ['terse', 'brief', 'guided'];
+/**
+ * Confidence floor applied when a registry declares none.
+ *
+ * Note what the detector's confidence actually is: `|sdet - manual| / total`,
+ * a *margin* between two tallies, not a probability. One open `.ts` file with
+ * no opposing signal scores 1.0. So this floor screens out genuine ties and
+ * near-ties and nothing else; {@link DEFAULT_MIN_DETECTION_SIGNALS} is the
+ * screen that does the real discriminating.
+ */
+const DEFAULT_MIN_DETECTION_CONFIDENCE = 0.5;
+/**
+ * Independent signals required before a detected level is trusted.
+ *
+ * A confidence floor cannot carry this decision on its own: because confidence
+ * is a margin, one unopposed observation arrives at a perfect 1.0, and a floor
+ * that screens ties but not single observations is confident-and-wrong — the
+ * failure mode this repo keeps rooting out. Two signals of genuinely different
+ * kinds is the screen that discriminates.
+ *
+ * "Independent" is per {@link independentSignalKinds}: distinct *kinds* of
+ * evidence, not a raw count. Ten open TypeScript files are one observation
+ * restated ten times.
+ */
+const DEFAULT_MIN_DETECTION_SIGNALS = 2;
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isDepth(v) {
+    return DEPTHS.includes(v);
+}
+function stringArray(v) {
+    if (!Array.isArray(v))
+        return null;
+    return v.every((x) => typeof x === 'string') ? [...v] : null;
+}
+/**
+ * Validate one raw persona entry, or return null.
+ *
+ * Dropping a malformed entry rather than throwing is deliberate for the
+ * *overlay* path: one bad downstream file must not take the engine's own
+ * personas down with it. The count is observable through {@link personaIds},
+ * so a dropped entry shows up as a missing id rather than as silence.
+ */
+function parsePersona(raw) {
+    if (!isRecord(raw))
+        return null;
+    const { id, label, audience, depth, reasoning } = raw;
+    const formats = stringArray(raw['formats']);
+    if (typeof id !== 'string' || id.trim() === '')
+        return null;
+    if (typeof label !== 'string' || typeof audience !== 'string')
+        return null;
+    if (!isDepth(depth) || formats === null)
+        return null;
+    if (typeof reasoning !== 'boolean')
+        return null;
+    return { id: id.trim(), label, audience, depth, formats, reasoning };
+}
+function parsePersonas(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        const parsed = parsePersona(entry);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+function parseDetectionMap(raw) {
+    if (!isRecord(raw))
+        return {};
+    const out = {};
+    for (const [level, target] of Object.entries(raw)) {
+        if (typeof target === 'string')
+            out[level] = target;
+    }
+    return out;
+}
+/** Default registry path: `<module dir>/../data/personas/registry.json`. */
+function defaultPersonaRegistryPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // here = <core> -> sibling data/ dir (src/data under vitest, dist/data once
+    // built and copied by ts/scripts/copy-data.mjs).
+    return resolve(here, '..', 'data', 'personas', 'registry.json');
+}
+/**
+ * Read and validate a persona registry.
+ *
+ * Throws — rather than degrading to an empty registry — because the engine's
+ * own registry going missing is a build/packaging fault, and a silently empty
+ * one would make every resolution return the same fallback while reporting
+ * nothing. Overlay registries take the forgiving path instead; see
+ * {@link readOverlayPersonaLayers}.
+ */
+function loadPersonaRegistry(registryPath = defaultPersonaRegistryPath()) {
+    let text;
+    try {
+        text = readFileSync(registryPath, 'utf-8');
+    }
+    catch (err) {
+        // `String(err)` rather than `err.message`: both throwers here raise real
+        // Errors, so an `instanceof` guard would only add an unreachable branch.
+        throw new Error(`could not read persona registry ${registryPath}: ${String(err)}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`persona registry ${registryPath} is not JSON: ${String(err)}`);
+    }
+    if (!isRecord(raw)) {
+        throw new Error(`persona registry ${registryPath} must be a JSON object, not an array` +
+            ' or scalar');
+    }
+    const version = typeof raw['version'] === 'number' ? raw['version'] : 1;
+    const fallback = typeof raw['fallback'] === 'string' ? raw['fallback'] : '';
+    const floor = raw['minDetectionConfidence'];
+    const signalFloor = raw['minDetectionSignals'];
+    return {
+        version,
+        fallback,
+        minDetectionConfidence: typeof floor === 'number' ? floor : DEFAULT_MIN_DETECTION_CONFIDENCE,
+        minDetectionSignals: typeof signalFloor === 'number'
+            ? signalFloor
+            : DEFAULT_MIN_DETECTION_SIGNALS,
+        detectionMap: parseDetectionMap(raw['detectionMap']),
+        personas: parsePersonas(raw['personas']),
+    };
+}
+// ---------------------------------------------------------------------------
+// Lookup
+// ---------------------------------------------------------------------------
+/**
+ * The distinct *kinds* of evidence in a detector signal list.
+ *
+ * `detectUserLevel` emits signals shaped `"<kind>: <detail>"` — for example
+ * `"code/test file open: a.ts"`, `"project manifest present: package.json"` —
+ * plus one kindless string (`"cwd path suggests manual testing"`), which is
+ * treated as its own kind. Grouping on the part before the first `": "` is what
+ * makes ten open TypeScript files count once: they are one observation restated,
+ * and a raw length check would have read them as ten independent facts.
+ *
+ * Splitting on `": "` rather than `":"` keeps a Windows path (`C:\src\a.ts`)
+ * from being mistaken for a separator.
+ */
+function independentSignalKinds(signals) {
+    const kinds = new Set();
+    for (const signal of signals) {
+        const at = signal.indexOf(': ');
+        kinds.add(at === -1 ? signal : signal.slice(0, at));
+    }
+    return [...kinds];
+}
+/** Ids in registry order — the discoverable persona vocabulary. */
+function personaIds(registry) {
+    return registry.personas.map((p) => p.id);
+}
+/** The persona with this id (case-insensitive), or null. */
+function findPersona(registry, id) {
+    if (typeof id !== 'string')
+        return null;
+    const want = id.trim().toLowerCase();
+    if (want === '')
+        return null;
+    return registry.personas.find((p) => p.id.toLowerCase() === want) ?? null;
+}
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+function fallbackPersona(registry) {
+    const named = findPersona(registry, registry.fallback);
+    if (named)
+        return named;
+    const first = registry.personas[0];
+    if (first)
+        return first;
+    // Never invent one. An empty registry is the denominator-zero case: the
+    // caller asked for an audience and there is no vocabulary to answer from.
+    throw new Error('persona registry defines no personas, so no persona can be resolved');
+}
+/**
+ * Choose a persona and say where the choice came from.
+ *
+ * Precedence, highest first: an explicit id, then a detected level whose
+ * confidence clears the registry floor, then the fallback. An explicit id that
+ * names nothing does **not** suppress the rest of the cascade — a typo is a
+ * mistake, not an instruction to ignore the signal — but it is always named in
+ * the reason, so the mistake surfaces instead of being swallowed.
+ */
+export function resolvePersona(input = {}) {
+    // `exactOptionalPropertyTypes` forbids passing an explicit `undefined`, so
+    // omit the key rather than forwarding it.
+    const registry = input.registry ??
+        effectivePersonaRegistry(input.home === undefined ? {} : { home: input.home });
+    const signals = [...(input.detected?.signals ?? [])];
+    const notes = [];
+    const explicit = input.explicit;
+    if (typeof explicit === 'string' && explicit.trim() !== '') {
+        const chosen = findPersona(registry, explicit);
+        if (chosen) {
+            return {
+                persona: chosen,
+                source: 'explicit',
+                reason: `explicit persona '${chosen.id}'`,
+                signals,
+            };
+        }
+        notes.push(uncertainDetectionMessage('persona', {
+            reason: `'${explicit.trim()}' is not a known persona`,
+            candidates: personaIds(registry),
+        }));
+    }
+    const detected = input.detected;
+    if (detected) {
+        const floor = registry.minDetectionConfidence;
+        const signalFloor = registry.minDetectionSignals;
+        const kinds = independentSignalKinds(signals);
+        const target = registry.detectionMap[detected.level];
+        const mapped = findPersona(registry, target);
+        if (!mapped) {
+            // Reported ahead of the signal count on purpose: an unmapped level is a
+            // vocabulary problem, and "open more files" would be the wrong next step.
+            notes.push(`detected user level '${detected.level}' maps to no persona, so the` +
+                ' fallback applies');
+        }
+        else if (kinds.length < signalFloor) {
+            // Named as a count rather than as "no signal": a reader has to be able to
+            // tell "I looked and found too little" from "I found nothing", because
+            // only one of those is fixed by giving the detector more to look at.
+            notes.push(`detected '${detected.level}' from ${kinds.length} independent ` +
+                `signal(s) (${signalFloor} required), so the fallback applies`);
+        }
+        else if (detected.confidence < floor) {
+            notes.push(`detected '${detected.level}' at confidence ` +
+                `${detected.confidence} is below the ${floor} floor, so the` +
+                ' fallback applies');
+        }
+        else {
+            notes.push(`detected user level '${detected.level}' at confidence ` +
+                `${detected.confidence}`);
+            return {
+                persona: mapped,
+                source: 'detected',
+                reason: notes.join('; '),
+                signals,
+            };
+        }
+    }
+    const persona = fallbackPersona(registry);
+    notes.push(`fell back to '${persona.id}'`);
+    return { persona, source: 'fallback', reason: notes.join('; '), signals };
+}
+/**
+ * A JSON-serialisable view for embedding in an MCP response.
+ *
+ * Flat rather than nested, and it carries `source`, `reason`, and `signals`
+ * beside the definition: a consumer that adapts its output owes the user an
+ * answer to "why did you decide I was that?".
+ */
+export function personaToDict(resolved) {
+    const { persona, source, reason, signals } = resolved;
+    return {
+        id: persona.id,
+        label: persona.label,
+        audience: persona.audience,
+        depth: persona.depth,
+        formats: [...persona.formats],
+        reasoning: persona.reasoning,
+        source,
+        reason,
+        signals: [...signals],
+    };
+}
+// ---------------------------------------------------------------------------
+// Overlay extension (#333 precedence)
+// ---------------------------------------------------------------------------
+/**
+ * Read each installed overlay's `.canary/personas.json`.
+ *
+ * Forgiving by design: a missing file means the overlay simply has no opinion,
+ * and an unreadable or malformed one is skipped rather than fatal, because a
+ * downstream overlay must not be able to break the engine's own vocabulary.
+ *
+ * The clone path comes from `resolveOverlay` rather than being rebuilt here, so
+ * `~/.canary/overlays/<name>` stays defined in exactly one place.
+ */
+function readOverlayPersonaLayers(home) {
+    const precedence = registryPrecedence(home);
+    const layers = [];
+    for (const overlay of listOverlays(home)) {
+        const path = join(resolveOverlay(overlay, home), '.canary', 'personas.json');
+        if (!existsSync(path))
+            continue;
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(path, 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(raw))
+            continue;
+        const fallback = raw['fallback'];
+        layers.push({
+            overlay,
+            precedence: precedence[overlay] ?? 0,
+            personas: parsePersonas(raw['personas']),
+            fallback: typeof fallback === 'string' ? fallback : null,
+        });
+    }
+    return layers;
+}
+/**
+ * Fold overlay layers onto the base registry.
+ *
+ * Layers are applied in ascending `(precedence, overlay-name)` order and the
+ * last writer wins — byte-for-byte the rule `skill-registry.ts` uses for
+ * skill-name collisions, so a downstream operator who has already reasoned
+ * about which overlay wins a skill does not have to learn a second model for
+ * personas. An id already in the base is replaced **in place**, so extending
+ * the vocabulary never reorders it.
+ */
+function mergePersonaRegistries(base, layers) {
+    const ordered = [...layers].sort((a, b) => a.precedence - b.precedence || a.overlay.localeCompare(b.overlay));
+    const personas = [...base.personas];
+    let fallback = base.fallback;
+    for (const layer of ordered) {
+        for (const persona of layer.personas) {
+            const at = personas.findIndex((p) => p.id.toLowerCase() === persona.id.toLowerCase());
+            if (at >= 0)
+                personas[at] = persona;
+            else
+                personas.push(persona);
+        }
+        if (layer.fallback !== null)
+            fallback = layer.fallback;
+    }
+    const merged = { ...base, personas, fallback };
+    // A fallback naming nothing is worse than no opinion: it would silently
+    // demote resolution to "first persona in the list".
+    if (!findPersona(merged, merged.fallback))
+        merged.fallback = base.fallback;
+    return merged;
+}
+/**
+ * The registry a resolution actually sees: shipped, plus every overlay.
+ *
+ * This is the function that makes overlay extension real rather than
+ * decorative. {@link resolvePersona} calls it whenever the caller does not
+ * hand over a registry outright, so a downstream `.canary/personas.json` reaches
+ * every consumer without each one remembering to merge — which is the mistake
+ * #341 is a record of: a signal that was produced correctly and read by nobody.
+ *
+ * Re-read per call rather than cached. `analyze_file` already scans the project
+ * tree, so one small JSON read plus a directory listing is not the cost worth
+ * trading a stale-config bug for.
+ *
+ * `registryPath` points the base registry somewhere other than the shipped
+ * file. It is the whole public seam onto the loader: the parsing and merging
+ * helpers below are intentionally module-private, so this is how both a caller
+ * with its own registry and a test exercising a malformed one get in.
+ */
+export function effectivePersonaRegistry(options = {}) {
+    return mergePersonaRegistries(loadPersonaRegistry(options.registryPath), readOverlayPersonaLayers(options.home));
+}
+//# sourceMappingURL=persona.js.map

package/dist/engine/core/promotion-verdict.js

@@ -0,0 +1,261 @@
+/**
+ * The structured verdict `canary-promote-test` gates on (#477).
+ *
+ * ## Why this exists now, when the issue says it is blocked
+ *
+ * #477 was parked on the emit side: `harness:test-craft` runs an 8-axis per-test
+ * LLM critique with no machine-readable output, so there was nothing to consume
+ * and building a consumer against an unspecified shape meant building it twice.
+ * That is still true of the LLM critique. It is no longer true of the gate:
+ * #605 (soundness) and #612 (vacuity) emit structured, per-test, DETERMINISTIC
+ * verdicts, and those are the ones that were ever going to be allowed to block.
+ *
+ * ## The three decisions #477 asked for
+ *
+ * **Which axes gate.** Deterministic defects gate; style reports.
+ *
+ * | Axis              | Rules                        | Gates | Why                                                              |
+ * | ----------------- | ---------------------------- | ----- | ---------------------------------------------------------------- |
+ * | `soundness`       | `SOUND-001/002/003`          | yes   | Pins a value no correct implementation must produce              |
+ * | `assertions`      | `LINT-006`                   | yes   | A test that asserts nothing always passes                        |
+ * | `flakiness`       | `FLAKE-001/002`              | yes   | The issue's own named blocker; both are `critical`               |
+ * | `vacuity`         | `VAC-001/003`, annotated 002 | yes   | Deterministic, or the author declared the target themselves      |
+ * | `selectors`       | `LINT-001/002/003`           | no    | Brittle, not wrong; a reviewer's call                            |
+ * | `maintainability` | `LINT-005`, `FLAKE-003/004`  | no    | Style and softer signals                                        |
+ *
+ * Gating on all of them would block nearly every promotion, which is exactly the
+ * outcome #477 predicted for a naive 8-axis gate.
+ *
+ * **What happens with no verdict.** `abstain`, exit 3, and say so. Promotion
+ * falls back to today's manual review. It must never become silently stricter
+ * (a `block` nobody can act on) or silently looser (a `promote` over a file the
+ * scanner could not read) -- and two distinct zeros are guarded: a file no
+ * ruleset parses, and a parseable file holding no tests.
+ *
+ * **Whether an LLM judgement may block.** No. Everything that gates in this repo
+ * is deterministic, and this change does not spend that. The decision is
+ * structural rather than documentary: {@link VerdictSource} admits one value, so
+ * there is no field an LLM verdict can arrive in and quietly acquire authority.
+ * `harness:test-craft` stays what `canary-promote-test` already calls it -- an
+ * optional deeper audit for a human.
+ *
+ * ## The fidelity ladder
+ *
+ * `VAC-002` is inference, and #477's real anxiety was making a heuristic
+ * load-bearing on a promotion gate. So the rung decides the authority, mirroring
+ * the guardian's `coverage-verified > graph-verified > heuristic`:
+ * `annotated` (the author named the target) blocks; `import-inferred` reports.
+ */
+import { EXIT_ABSTAINED, errnoCode, gateOutcome, } from './gate-result.js';
+import { StaticLinter, UnsupportedTestFileError, frameworkForPath, } from './static-linter.js';
+import { scanVacuity, } from './vacuity-scanner.js';
+/**
+ * Which rules land on which axis, and whether that axis gates.
+ *
+ * A rule matching NO row here is invisible to the verdict: not gating, not
+ * advisory, not printed. `LINT-004` -- an unawaited Playwright action, the
+ * linter's other `critical` and the canonical false-green defect -- was omitted
+ * from the first cut and walked straight through the gate built to stop it.
+ * `test-signal-review-findings.test.ts` now asserts that every rule a real lint
+ * produces lands somewhere, because the omission is otherwise silent.
+ */
+const AXES = [
+    { axis: 'soundness', gating: true, rules: /^SOUND-/ },
+    { axis: 'assertions', gating: true, rules: /^LINT-006$/ },
+    // LINT-004 sits here rather than in its own axis because an unawaited action
+    // IS the classic race: the assertion runs before the action lands.
+    { axis: 'flakiness', gating: true, rules: /^FLAKE-00[12]$|^LINT-004$/ },
+    { axis: 'vacuity', gating: true, rules: /^VAC-/ },
+    { axis: 'selectors', gating: false, rules: /^LINT-00[123]$/ },
+    {
+        axis: 'maintainability',
+        gating: false,
+        rules: /^LINT-005$|^FLAKE-00[34]$/,
+    },
+];
+/**
+ * Whether a finding on a gating axis may actually block.
+ *
+ * The one place the fidelity ladder is spent. `VAC-002` at `import-inferred` is
+ * an inference about which symbol a test was meant to exercise; blocking a
+ * promotion on that would make a heuristic load-bearing, which is the specific
+ * thing #477 asked not to do by accident. At `annotated` fidelity the author
+ * wrote the target down, so the finding is a contradiction of a stated contract
+ * and blocks.
+ */
+function mayBlock(f) {
+    if (f.rule !== 'VAC-002')
+        return true;
+    return f.fidelity === 'annotated';
+}
+function normalizeLint(f) {
+    return {
+        rule: f.rule,
+        line: f.line,
+        severity: f.severity,
+        message: f.message,
+        suggestion: f.suggestion,
+    };
+}
+function normalizeVacuity(f) {
+    const out = {
+        rule: f.rule,
+        line: f.line,
+        severity: f.severity,
+        message: `${f.test}: ${f.message}`,
+        suggestion: f.suggestion,
+    };
+    if (f.fidelity)
+        out.fidelity = f.fidelity;
+    return out;
+}
+const ABSTAIN_REMEDY = 'No verdict could be produced, so promotion falls back to manual review ' +
+    '(canary-promote-test Phase 1) -- it has NOT been approved. ' +
+    'Point at a single generated test file that contains at least one test.';
+function abstained(file, skipped, axes) {
+    const outcome = gateOutcome({ checked: 0, findings: [], skipped }, 'gate');
+    return {
+        file,
+        decision: 'abstain',
+        source: 'deterministic',
+        checked: 0,
+        axes,
+        blocked: [],
+        skipped,
+        summaryLine: outcome.summaryLine,
+        remedy: ABSTAIN_REMEDY,
+        exitCode: EXIT_ABSTAINED,
+    };
+}
+function emptyAxes() {
+    return AXES.map((a) => ({ axis: a.axis, gating: a.gating, findings: [] }));
+}
+/**
+ * Produce the promotion verdict for one generated test file.
+ *
+ * Deliberately single-file: promotion is a per-file decision, and a directory
+ * roll-up would let one clean file's verdict read as cover for a sibling's.
+ */
+export function promotionVerdict(path) {
+    if (frameworkForPath(path) === null) {
+        return abstained(path, [
+            {
+                name: path,
+                reason: 'no ruleset parses this extension, so a clean result would be meaningless',
+            },
+        ], emptyAxes());
+    }
+    const lint = lintOrAbstain(path);
+    if (!Array.isArray(lint))
+        return lint;
+    const vacuity = scanVacuity(path);
+    const axes = groupIntoAxes([
+        ...lint.map(normalizeLint),
+        ...vacuity.findings.map(normalizeVacuity),
+    ]);
+    const skipped = vacuity.skipped ?? [];
+    // A parseable file with no tests is another zero, and it must not read as a
+    // pass: promotion would let an empty file into the committed suite. Note that
+    // `lint` can still be non-empty here (a stray `Date.now()` outside any test),
+    // so the check is on the TEST count, not on the finding count.
+    if (vacuity.checked === 0) {
+        return abstained(path, [
+            ...skipped,
+            {
+                name: path,
+                reason: 'file holds no test declarations, so there is nothing to promote',
+            },
+        ], axes);
+    }
+    return decide(path, axes, skipped, vacuity.checked);
+}
+/**
+ * The lint findings, or a ready-made abstention when the linter refused.
+ *
+ * Two distinct refusals, and BOTH have to become an abstention rather than an
+ * exception. Letting a read error propagate meant the CLI printed a raw ENOENT
+ * stack and exited 0 -- a promotion gate that could not open the draft,
+ * reporting success. Anything without an `errno`-style `code` still throws,
+ * because swallowing an unknown fault is how a scanner learns to go quiet.
+ */
+function lintOrAbstain(path) {
+    try {
+        return new StaticLinter().lint(path);
+    }
+    catch (e) {
+        if (e instanceof UnsupportedTestFileError) {
+            return abstained(path, [{ name: path, reason: e.message }], emptyAxes());
+        }
+        // ERRNO-shaped only. Keying off "has a string `code`" swept in every Node
+        // PROGRAMMER error too -- `ERR_INVALID_ARG_TYPE`, `ERR_STRING_TOO_LONG` --
+        // so a genuine defect inside the linter was reported as a clean ABSTAIN with
+        // a misleading reason instead of surfacing. An unknown fault must still
+        // throw; that is the difference between degrading honestly and going quiet.
+        const code = errnoCode(e);
+        if (code === null)
+            throw e;
+        return abstained(path, [{ name: path, reason: `could not be read (${code})` }], emptyAxes());
+    }
+}
+/** Every axis, in registry order, each carrying its findings sorted by line. */
+function groupIntoAxes(all) {
+    return AXES.map((spec) => ({
+        axis: spec.axis,
+        gating: spec.gating,
+        findings: all
+            .filter((f) => spec.rules.test(f.rule))
+            .sort((a, b) => a.line - b.line),
+    }));
+}
+/** Turn evaluated axes into the promote/block decision and its copy. */
+function decide(path, axes, skipped, checked) {
+    const blocked = [
+        ...new Set(axes
+            .filter((a) => a.gating)
+            .flatMap((a) => a.findings)
+            .filter(mayBlock)
+            .map((f) => f.rule)),
+    ];
+    // `gateOutcome` owns the summary line so promotion reports its denominator in
+    // the same shape as every other gate, rather than inventing a private format.
+    const outcome = gateOutcome({ checked, findings: blocked, skipped }, 'gate', {
+        noun: 'test(s)',
+    });
+    const decision = blocked.length > 0 ? 'block' : 'promote';
+    const advisoryCount = axes
+        .filter((a) => !a.gating)
+        .reduce((n, a) => n + a.findings.length, 0);
+    return {
+        file: path,
+        decision,
+        source: 'deterministic',
+        checked,
+        axes,
+        blocked,
+        skipped,
+        summaryLine: outcome.summaryLine,
+        remedy: remedyFor(decision, blocked, advisoryCount, skipped.length),
+        exitCode: decision === 'block' ? 1 : 0,
+    };
+}
+function remedyFor(decision, blocked, advisoryCount, skipCount) {
+    if (decision === 'block') {
+        return (`Blocked on ${blocked.join(', ')}. Fix the test or regenerate it ` +
+            'with a sharper prompt -- do not hand-patch a generated draft ' +
+            '(canary-promote-test Phase 1).');
+    }
+    const parts = ['Promotable.'];
+    if (advisoryCount > 0) {
+        parts.push(`${advisoryCount} advisory finding(s) are a reviewer's call, not a blocker.`);
+    }
+    // A `promote` whose rules went dark must not read as an unqualified pass.
+    // `checked` legitimately counts the tests VAC-001 did run on, so the
+    // denominator is right -- but a reader seeing only "promotable" would never
+    // learn that two of the three vacuity rules could not be evaluated at all.
+    if (skipCount > 0) {
+        parts.push(`${skipCount} check(s) could not run on this file -- see the skip list; ` +
+            'those rules did NOT pass, they abstained.');
+    }
+    return advisoryCount > 0 || skipCount > 0 ? parts.join(' ') : '';
+}
+//# sourceMappingURL=promotion-verdict.js.map