@codesema/speccov 0.0.0-stage → 0.2.1

package/src/mutate/mutators.ts

@@ -0,0 +1,166 @@
+import ts from 'typescript';
+
+export type Mutant = {
+    /** Stable identifier: same mutated code ⇒ same identifier, from one run to the next. */
+    readonly id: string;
+    readonly file: string;
+    readonly line: number;
+    readonly mutator: string;
+    readonly start: number;
+    readonly end: number;
+    readonly original: string;
+    readonly replacement: string;
+};
+
+/**
+ * The alteration operators, reimplemented on the TypeScript AST.
+ *
+ * The catalogue comes from the state of the art in mutation testing (Stryker, PIT): these are
+ * the alterations that empirically reveal the most verification holes. We reimplement it rather
+ * than depend on Stryker, so that the scope and the budget stay ours to choose.
+ */
+const BINARY_SWAPS = new Map<ts.SyntaxKind, string>([
+    [ts.SyntaxKind.GreaterThanToken, '>='],
+    [ts.SyntaxKind.GreaterThanEqualsToken, '>'],
+    [ts.SyntaxKind.LessThanToken, '<='],
+    [ts.SyntaxKind.LessThanEqualsToken, '<'],
+    [ts.SyntaxKind.EqualsEqualsEqualsToken, '!=='],
+    [ts.SyntaxKind.ExclamationEqualsEqualsToken, '==='],
+    [ts.SyntaxKind.EqualsEqualsToken, '!='],
+    [ts.SyntaxKind.ExclamationEqualsToken, '=='],
+    [ts.SyntaxKind.AmpersandAmpersandToken, '||'],
+    [ts.SyntaxKind.BarBarToken, '&&'],
+    [ts.SyntaxKind.QuestionQuestionToken, '||'],
+    [ts.SyntaxKind.PlusToken, '-'],
+    [ts.SyntaxKind.MinusToken, '+'],
+    [ts.SyntaxKind.AsteriskToken, '/'],
+    [ts.SyntaxKind.SlashToken, '*'],
+    [ts.SyntaxKind.PercentToken, '*'],
+]);
+
+const MUTATOR_OF = new Map<ts.SyntaxKind, string>([
+    [ts.SyntaxKind.GreaterThanToken, 'comparison'],
+    [ts.SyntaxKind.GreaterThanEqualsToken, 'comparison'],
+    [ts.SyntaxKind.LessThanToken, 'comparison'],
+    [ts.SyntaxKind.LessThanEqualsToken, 'comparison'],
+    [ts.SyntaxKind.EqualsEqualsEqualsToken, 'equality'],
+    [ts.SyntaxKind.ExclamationEqualsEqualsToken, 'equality'],
+    [ts.SyntaxKind.EqualsEqualsToken, 'equality'],
+    [ts.SyntaxKind.ExclamationEqualsToken, 'equality'],
+    [ts.SyntaxKind.AmpersandAmpersandToken, 'logic'],
+    [ts.SyntaxKind.BarBarToken, 'logic'],
+    [ts.SyntaxKind.QuestionQuestionToken, 'logic'],
+]);
+
+export function findMutants(file: string, source: string): readonly Mutant[] {
+    const parsed = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+    const mutants: Mutant[] = [];
+
+    const add = (
+        node: ts.Node,
+        replacement: string,
+        mutator: string,
+        start = node.getStart(parsed),
+        end = node.getEnd(),
+    ): void => {
+        const { line } = parsed.getLineAndCharacterOfPosition(start);
+        const original = source.slice(start, end);
+        if (original === replacement) {
+            return;
+        }
+        mutants.push({
+            id: `${file}:${start}:${mutator}`,
+            file,
+            line: line + 1,
+            mutator,
+            start,
+            end,
+            original,
+            replacement,
+        });
+    };
+
+    const visit = (node: ts.Node): void => {
+        if (isErased(node)) {
+            return;
+        }
+        if (ts.isBinaryExpression(node)) {
+            const swap = BINARY_SWAPS.get(node.operatorToken.kind);
+            if (swap !== undefined) {
+                const token = node.operatorToken;
+                add(token, swap, MUTATOR_OF.get(token.kind) ?? 'arithmetic', token.getStart(parsed), token.getEnd());
+            }
+        }
+        if (node.kind === ts.SyntaxKind.TrueKeyword) {
+            add(node, 'false', 'boolean');
+        }
+        if (node.kind === ts.SyntaxKind.FalseKeyword) {
+            add(node, 'true', 'boolean');
+        }
+        if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.ExclamationToken) {
+            add(node, node.operand.getText(parsed), 'negation');
+        }
+        if (ts.isArrayLiteralExpression(node) && node.elements.length > 0) {
+            add(node, '[]', 'array emptied');
+        }
+        if (ts.isStringLiteral(node) && node.text !== '') {
+            add(node, '""', 'string emptied');
+        }
+        if (isOptionalChain(node)) {
+            add(
+                node.questionDotToken,
+                '.',
+                'optional chaining',
+                node.questionDotToken.getStart(parsed),
+                node.questionDotToken.getEnd(),
+            );
+        }
+        if (isEmptiableBody(node, parsed)) {
+            add(node, '{}', 'body emptied');
+        }
+        ts.forEachChild(node, visit);
+    };
+
+    visit(parsed);
+    return mutants;
+}
+
+function isOptionalChain(node: ts.Node): node is ts.PropertyAccessExpression & { questionDotToken: ts.QuestionDotToken } {
+    return ts.isPropertyAccessExpression(node) && node.questionDotToken !== undefined;
+}
+
+/** Emptying a non-empty function body: the most brutal alteration, and so the most revealing. */
+function isEmptiableBody(node: ts.Node, parsed: ts.SourceFile): node is ts.Block {
+    if (!ts.isBlock(node) || node.statements.length === 0) {
+        return false;
+    }
+    const parent = node.parent;
+    const isFunctionBody =
+        ts.isFunctionDeclaration(parent) ||
+        ts.isMethodDeclaration(parent) ||
+        ts.isArrowFunction(parent) ||
+        ts.isFunctionExpression(parent);
+    return isFunctionBody && node.getText(parsed) !== '{}';
+}
+
+/** Applies a mutant to the source text. Pure: touches no file. */
+export function applyMutant(source: string, mutant: Mutant): string {
+    return source.slice(0, mutant.start) + mutant.replacement + source.slice(mutant.end);
+}
+
+/**
+ * What the compiler erases before execution: types, interfaces, aliases, type imports.
+ * Placing a mutant there yields a guaranteed survivor — the compiled code is identical,
+ * no test can object.
+ *
+ * These false survivors are not neutral: they drown the real ones in the report, and a
+ * report nobody can sort through is no longer a report anyone decides from.
+ */
+function isErased(node: ts.Node): boolean {
+    return (
+        ts.isTypeNode(node) ||
+        ts.isTypeAliasDeclaration(node) ||
+        ts.isInterfaceDeclaration(node) ||
+        (ts.isImportDeclaration(node) && node.importClause?.isTypeOnly === true)
+    );
+}

package/src/mutate/report.ts

@@ -0,0 +1,52 @@
+import type { MutateResult, Outcome } from './run';
+
+const MAX_SHOWN = 8;
+
+/**
+ * A surviving mutant is a question, not an accusation: the behaviour changed and nobody
+ * said a word. Whether somebody should have is what is left to settle.
+ */
+/**
+ * `all` exists for triage: eight survivors are enough to alert a human, never enough to
+ * decide what to fix when there are a hundred. Truncating by default keeps the report readable;
+ * never being able to see it all would make it unusable.
+ */
+export function reportMutants(result: MutateResult, all = false): string {
+    const survivors = result.outcomes.filter(({ fate }) => fate === 'survived');
+    const killed = result.outcomes.length - survivors.length;
+
+    const lines = ['', `  ${result.outcomes.length} mutants tried, ${killed} killed.`];
+    if (survivors.length === 0) {
+        lines.push('', '  No survivor: every alteration of the code was caught.');
+    } else {
+        lines.push(`  ⚠ ${survivors.length} survivor(s) — that many behaviours nobody guarantees.`, '');
+        const shown = all ? survivors.length : MAX_SHOWN;
+        for (const [index, outcome] of survivors.slice(0, shown).entries()) {
+            lines.push(...describe(outcome, index + 1, survivors.length));
+        }
+        if (survivors.length > shown) {
+            lines.push(`  … and ${survivors.length - shown} more survivor(s) — run again with --all to see them.`);
+        }
+    }
+    if (result.skipped > 0) {
+        lines.push('', '  ── Not measured ───────────────────────────────────────────');
+        lines.push(`     ${result.skipped} mutant(s) generated but not tried, out of budget.`);
+        lines.push('     Raise --limit or narrow the scope.');
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+
+function describe({ mutant }: Outcome, position: number, total: number): readonly string[] {
+    return [
+        `  survivor ${position}/${total}   ${mutant.file}:${mutant.line}  (${mutant.mutator})`,
+        `  “I replaced  ${truncate(mutant.original)}  with  ${truncate(mutant.replacement)}  and nothing`,
+        '    objected. Should this behaviour be guaranteed?”',
+        '',
+    ];
+}
+
+function truncate(text: string): string {
+    const single = text.replaceAll(/\s+/gu, ' ');
+    return single.length <= 40 ? single : `${single.slice(0, 40)}…`;
+}

package/src/mutate/run.ts

@@ -0,0 +1,79 @@
+import { spawn } from 'node:child_process';
+import { readFile, writeFile } from 'node:fs/promises';
+import { applyMutant, findMutants, type Mutant } from './mutators';
+
+export type Fate = 'killed' | 'survived';
+
+export type Outcome = {
+    readonly mutant: Mutant;
+    readonly fate: Fate;
+};
+
+export type MutateOptions = {
+    readonly files: readonly string[];
+    /** Command that judges the mutant. Non-zero exit ⇒ the mutant is killed. */
+    readonly command: readonly string[];
+    readonly cwd: string;
+    /** Budget: maximum number of mutants tried. */
+    readonly limit: number;
+    readonly onProgress?: (done: number, total: number) => void;
+};
+
+export type MutateResult = {
+    readonly outcomes: readonly Outcome[];
+    /** Mutants generated but not tried, out of budget. Counted, never silenced. */
+    readonly skipped: number;
+};
+
+/**
+ * Tries every mutant: alter the file, run the command, restore.
+ *
+ * A **surviving** mutant is a gap in the strong sense: the behaviour of the code was changed
+ * and nothing — no rule, no test — objected.
+ *
+ * The restore is in a `finally` and the original file is held in memory: even a command that
+ * crashes leaves the source intact. On top of that the caller must require a clean repository,
+ * so that a `git checkout` always remains a way out.
+ */
+export async function mutate(options: MutateOptions): Promise<MutateResult> {
+    const all = await generate(options.files);
+    const budgeted = all.slice(0, options.limit);
+    const outcomes: Outcome[] = [];
+
+    for (const [index, mutant] of budgeted.entries()) {
+        options.onProgress?.(index + 1, budgeted.length);
+        outcomes.push({ mutant, fate: await tryMutant(mutant, options) });
+    }
+    return { outcomes, skipped: all.length - budgeted.length };
+}
+
+export async function generate(files: readonly string[]): Promise<readonly Mutant[]> {
+    const mutants: Mutant[] = [];
+    for (const file of files) {
+        mutants.push(...findMutants(file, await readFile(file, 'utf8')));
+    }
+    return mutants;
+}
+
+async function tryMutant(mutant: Mutant, options: MutateOptions): Promise<Fate> {
+    const original = await readFile(mutant.file, 'utf8');
+    try {
+        await writeFile(mutant.file, applyMutant(original, mutant), 'utf8');
+        return (await run(options)) === 0 ? 'survived' : 'killed';
+    } finally {
+        await writeFile(mutant.file, original, 'utf8');
+    }
+}
+
+function run({ command, cwd }: MutateOptions): Promise<number> {
+    const [program, ...args] = command;
+    if (program === undefined) {
+        throw new Error('speccov: the command that judges a mutant is empty.');
+    }
+    return new Promise((settle, reject) => {
+        const child = spawn(program, args, { cwd, stdio: 'ignore' });
+        child.once('error', reject);
+        // No exit code means a signal ended the command: it did not pass, the mutant is killed.
+        child.once('exit', (code) => settle(code ?? 1));
+    });
+}

package/src/report.ts

@@ -0,0 +1,143 @@
+import type { Borderline, Infraction, Lacuna, Vacuous, Verdict } from './rule';
+
+/**
+ * Makes the verdict readable. The report is dominated by what is not guaranteed: a success
+ * carries no information, it fits on a single line.
+ */
+export function report(verdicts: readonly Verdict[], accepted: readonly Lacuna[] = []): string {
+    const held = verdicts.filter((verdict) => verdict.kind === 'held');
+    const infractions = verdicts.filter((verdict): verdict is Infraction => verdict.kind === 'infraction');
+    const lacunae = verdicts.filter((verdict): verdict is Lacuna => verdict.kind === 'lacuna');
+    const vacuous = verdicts.filter((verdict): verdict is Vacuous => verdict.kind === 'vacuous');
+    const borderline = verdicts.filter((verdict): verdict is Borderline => verdict.kind === 'borderline');
+
+    const lines = [''];
+    if (held.length > 0) {
+        // No tick when nothing is held: a ✓ in front of zero reads wrong.
+        lines.push(`  ✓ ${count(held.length, 'rule held', 'rules held')}`);
+    }
+    if (infractions.length > 0) {
+        lines.push(`  ✗ ${count(infractions.length, 'violation', 'violations')}`);
+    }
+    if (lacunae.length > 0) {
+        lines.push(`  ⚠ ${count(lacunae.length, 'gap', 'gaps')}`);
+    }
+    if (vacuous.length > 0) {
+        lines.push(`  ? ${count(vacuous.length, 'rule never exercised', 'rules never exercised')}`);
+    }
+    if (borderline.length > 0) {
+        lines.push(`  ~ ${count(borderline.length, 'rule held with no margin', 'rules held with no margin')}`);
+    }
+    if (accepted.length > 0) {
+        // Counted and never hidden: a forgotten acceptance is a blind spot.
+        lines.push(`  · ${count(accepted.length, 'gap already accepted', 'gaps already accepted')}`);
+    }
+
+    infractions.forEach((infraction, index) => {
+        lines.push('', `  violation ${index + 1}/${infractions.length}   ${infraction.rule.name}`);
+        lines.push(indent(`“${infraction.rule.intention}” does not hold.`));
+        lines.push(indent(infraction.detail));
+    });
+
+    lacunae.forEach((lacuna, index) => {
+        lines.push('', `  gap ${index + 1}/${lacunae.length}   ${lacuna.rule.name}`);
+        lines.push(indent(`“${lacuna.question}”`));
+        lines.push('', '     [y] this is a bug     [n] this is intended');
+    });
+
+    vacuous.forEach((verdict, index) => {
+        lines.push('', `  never exercised ${index + 1}/${vacuous.length}   ${verdict.rule.name}`);
+        lines.push(indent(`“${verdict.question}”`));
+        lines.push(indent('It is green because it saw nothing, not because it judged.'));
+    });
+
+    borderline.forEach((verdict, index) => {
+        lines.push('', `  no margin ${index + 1}/${borderline.length}   ${verdict.rule.name}`);
+        lines.push(indent(`“${verdict.question}”`));
+    });
+
+    if (infractions.length === 0 && lacunae.length === 0 && vacuous.length === 0 && borderline.length === 0) {
+        lines.push('', '  Nothing to report.');
+    }
+
+    const notMeasured = measurementWindow(verdicts);
+    lines.push('', '  ── Not measured ──────────────────────────────────────────');
+    if (notMeasured.largest === null) {
+        lines.push('     No input size was exercised: nothing is said about how cost grows.');
+    } else {
+        lines.push(`     Input sizes tried: ${notMeasured.sizes.join(', ')} — nothing beyond ${notMeasured.largest}.`);
+        lines.push('     A cost that only grows past that size would not have been seen.');
+    }
+    if (notMeasured.unobserved.length > 0) {
+        lines.push(
+            `     ${count(notMeasured.unobserved.length, 'rule observed nothing', 'rules observed nothing')}: ${notMeasured.unobserved.join(', ')}`,
+        );
+    }
+    lines.push('     The data comes from the rule file, not from production.');
+    lines.push('');
+    return lines.join('\n');
+}
+
+/** What the pass actually observed — and so, in negative, what it did not see. */
+export type MeasurementWindow = {
+    /** Distinct input sizes actually tried, sorted. */
+    readonly sizes: readonly number[];
+    /** The largest size tried, or `null` if no rule measured anything. */
+    readonly largest: number | null;
+    /** Rules that observed no measurement: they bound nothing at all. */
+    readonly unobserved: readonly string[];
+};
+
+/**
+ * A rule concludes only about the sizes it tried. Keeping that bound quiet would make a
+ * green report read as "cost never grows", when it only says "not up to 16". That is the
+ * exact charge levelled at 90% coverage.
+ *
+ * Prose and JSON both start here so they cannot contradict each other.
+ */
+export function measurementWindow(verdicts: readonly Verdict[]): MeasurementWindow {
+    const sizes = new Set<number>();
+    const unobserved: string[] = [];
+
+    for (const verdict of verdicts) {
+        if (verdict.measurements.length === 0) {
+            unobserved.push(verdict.rule.name);
+        }
+        for (const { size } of verdict.measurements) {
+            sizes.add(size);
+        }
+    }
+
+    const sorted = [...sizes].sort((a, b) => a - b);
+    return { sizes: sorted, largest: sorted.at(-1) ?? null, unobserved };
+}
+
+/** Only a violation fails the run: a gap is a question, not a refusal. */
+export function exitCode(verdicts: readonly Verdict[]): number {
+    return verdicts.some((verdict) => verdict.kind === 'infraction') ? 1 : 0;
+}
+
+function count(value: number, singular: string, plural: string): string {
+    return `${value} ${value > 1 ? plural : singular}`;
+}
+
+const WIDTH = 88;
+
+/** Wraps the text so a report stays readable in a narrow terminal. */
+function indent(text: string): string {
+    const lines: string[] = [];
+    let current = '';
+    for (const word of text.split(/\s+/).filter((part) => part !== '')) {
+        const candidate = current === '' ? word : `${current} ${word}`;
+        if (candidate.length > WIDTH && current !== '') {
+            lines.push(current);
+            current = word;
+        } else {
+            current = candidate;
+        }
+    }
+    if (current !== '') {
+        lines.push(current);
+    }
+    return lines.map((line) => `  ${line}`).join('\n');
+}

package/src/resource.ts

@@ -0,0 +1,76 @@
+import type { Gauge } from './gauge';
+import { requireIntention, type Judgement, type Measurement, type Origin, type Rule } from './rule';
+
+export type ResourceOptions = {
+    readonly name: string;
+    readonly intention?: string;
+    /** Unit observed, PLURAL. */
+    readonly unit?: string;
+    /** Tolerated peak. Choosing it is writing a rule — hence `origin: 'declared'`. */
+    readonly ceiling: number;
+    readonly sizes?: readonly number[];
+    readonly gauge: Gauge;
+    readonly subject: (size: number) => unknown;
+    readonly origin?: Origin;
+};
+
+const DEFAULT_SIZES = [1, 4, 16] as const;
+
+/**
+ * Resource rule: the observed peak stays under a ceiling, whatever the input.
+ *
+ * This is the one that catches an unbounded `Promise.all`: concurrency there follows the
+ * size of the collection, so it crosses any ceiling as soon as the data grows.
+ */
+export function resource(options: ResourceOptions): Rule {
+    const unit = options.unit ?? 'concurrent operations';
+    const sizes = options.sizes ?? DEFAULT_SIZES;
+    const intention = requireIntention(options.name, options.intention ?? `Peak ${unit} never exceeds ${options.ceiling}`);
+
+    if (!Number.isFinite(options.ceiling) || options.ceiling < 1) {
+        throw new Error(`speccov: invalid ceiling (${options.ceiling}) for “${options.name}”, expected an integer of 1 or more.`);
+    }
+
+    return {
+        name: options.name,
+        intention,
+        origin: options.origin ?? 'declared',
+
+        // A ceiling of 1 does not tighten: 0 would forbid every operation.
+        tighten: () => (options.ceiling > 1 ? resource({ ...options, ceiling: options.ceiling - 1 }) : undefined),
+
+        async measure(): Promise<readonly Measurement[]> {
+            const measurements: Measurement[] = [];
+            for (const size of sizes) {
+                options.gauge.reset();
+                await options.subject(size);
+                measurements.push({ size, cost: options.gauge.peak });
+            }
+            return measurements;
+        },
+
+        judge(measurements): Judgement {
+            if (measurements.length === 0) {
+                throw new Error(`speccov: no measurement for “${options.name}”.`);
+            }
+            const peak = Math.max(...measurements.map(({ cost }) => cost));
+            const series = measurements.map(({ size, cost }) => `${size}→${cost}`).join(', ');
+            // A zero peak: nothing was consumed, so no ceiling was ever exercised.
+            const exercised = peak > 0;
+            if (peak <= options.ceiling) {
+                return {
+                    held: true,
+                    exercised,
+                    magnitude: 0,
+                    detail: `Peak of ${peak} ${unit}, ceiling ${options.ceiling} (${series})`,
+                };
+            }
+            return {
+                held: false,
+                exercised,
+                magnitude: peak - options.ceiling,
+                detail: `Peak of ${peak} ${unit} against a ceiling of ${options.ceiling} (${series})`,
+            };
+        },
+    };
+}

package/src/rule.ts

@@ -0,0 +1,129 @@
+/**
+ * A *declared* rule was written by a human: breaking it is an infraction.
+ * A *default* rule was written by nobody: breaking it is not a proven bug,
+ * it is a question to ask — a gap.
+ */
+export type Origin = 'declared' | 'default';
+
+/** The cost observed for a given input size. */
+export type Measurement = {
+    readonly size: number;
+    readonly cost: number;
+};
+
+export type Judgement = {
+    readonly held: boolean;
+    /** Factual sentence describing what was measured. Never a value judgement. */
+    readonly detail: string;
+    /**
+     * How far past the threshold, monotonic: the larger it is, the more the rule is violated.
+     *
+     * Mandatory, and that is a choice: a rule unable to quantify its own gap cannot be
+     * accepted at a threshold, so the human answer to it cannot be mechanised.
+     */
+    readonly magnitude: number;
+    /**
+     * True if the measurements held at least one observation able to make the rule fail.
+     * False when it "held" without ever being exercised.
+     *
+     * This is vacuity, described for twenty years in formal verification: a property
+     * satisfied for a trivial reason. About one specification in five passes that way on
+     * the first checks, and a vacuous pass always points at a real problem — in the code,
+     * in the rule, or in what was measured.
+     *
+     * Mandatory, like `magnitude`: a rule unable to say whether it was ever exercised cannot
+     * be told apart from a rule that is green by absence.
+     */
+    readonly exercised: boolean;
+};
+
+export type Rule = {
+    readonly name: string;
+    /** Human-readable sentence. Mandatory: a rule that says nothing is worth nothing. */
+    readonly intention: string;
+    readonly origin: Origin;
+    measure(): Promise<readonly Measurement[]>;
+    judge(measurements: readonly Measurement[]): Judgement;
+    /**
+     * The same rule, one notch stricter — or `undefined` when it has no threshold to
+     * tighten (a ban holds or it does not; it has no margin).
+     *
+     * This is rule mutation, the inverse of code mutation: coverage mutates the system,
+     * vacuity mutates the specification. And it is free — `judge()` is pure over the
+     * measurements, so the variant rejudges the same observations without running anything.
+     *
+     * Contract: the `judge()` of the returned rule must depend on its argument alone.
+     */
+    tighten?(): Rule | undefined;
+};
+
+type Outcome = {
+    readonly rule: Rule;
+    readonly measurements: readonly Measurement[];
+    readonly magnitude: number;
+    /** What was measured, in one sentence. */
+    readonly detail: string;
+};
+
+/** The rule held. Nothing to report. */
+export type Held = {
+    readonly kind: 'held';
+} & Outcome;
+
+/**
+ * A rule is violated although a human had ruled on it. That is a bug.
+ *
+ * Two origins: a rule written by hand, or an accepted gap whose threshold has just been
+ * crossed — accepting is writing a rule.
+ */
+export type Infraction = {
+    readonly kind: 'infraction';
+} & Outcome;
+
+/**
+ * The rule held without ever being exercised. Green by absence, not by proof.
+ *
+ * This is not a violation — nothing proves the code is at fault. It is a green light worth
+ * nothing, and keeping quiet about it would be exactly the lie speccov exists to avoid.
+ */
+export type Vacuous = {
+    readonly kind: 'vacuous';
+    readonly question: string;
+} & Outcome;
+
+/**
+ * The rule holds, but with no margin at all: one notch stricter and it would fall.
+ *
+ * The observation sits exactly on the threshold. Either the code is at the limit and the
+ * next item crosses it, or — more likely — the threshold was chosen *after* the observation,
+ * to fit it. This is the "rule" version of "the test checks the constant against itself".
+ */
+export type Borderline = {
+    readonly kind: 'borderline';
+    readonly question: string;
+} & Outcome;
+
+/** No written rule frames this behaviour, and it does this. Open question. */
+export type Lacuna = {
+    readonly kind: 'lacuna';
+    readonly question: string;
+} & Outcome;
+
+/** True when the verdict is about a rule that did not hold, whatever the severity. */
+export function isBroken(verdict: Verdict): verdict is Infraction | Lacuna {
+    return verdict.kind === 'infraction' || verdict.kind === 'lacuna';
+}
+
+export type Verdict = Held | Infraction | Lacuna | Vacuous | Borderline;
+
+/**
+ * Refuses a rule with no intention sentence. It is the only rule speccov applies to itself:
+ * the field that makes the report readable cannot be optional.
+ */
+export function requireIntention(name: string, intention: string | undefined): string {
+    const trimmed = intention?.trim() ?? '';
+    if (trimmed === '') {
+        throw new Error(`speccov: rule “${name}” has no intention. Write the sentence a human will read.`);
+    }
+    return trimmed;
+}