@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/testing/gates.js

@@ -0,0 +1,182 @@
+import { compareEnvironmentSnapshot } from '../environment/evidence.js';
+import { planSiblingProjection } from '../surfaces/projection.js';
+import { GUARD_SURFACE_TARGETS } from '../surfaces/harness-registry.js';
+import { TESTING_STAGE_TIMEOUT_MAX_SECONDS } from '../schema.js';
+import { classifyRun } from './verdict.js';
+import { RefusalError, errorCause } from '../environment/contract.js';
+export const GATE_SELECTOR_OPTION = '--select';
+const SELECTOR_KINDS = Object.freeze(['spec', 'file', 'test', 'route']);
+const SELECTOR_VALUE = '{value}';
+const tiers = Object.freeze([
+    Object.freeze({ id: 'none', title: 'None', changes: 'Comments or documentation only, when no behavior changes', gate: 'No gate required' }),
+    Object.freeze({ id: 'targeted', title: 'Targeted', changes: 'Isolated behavior', gate: 'Select the narrowest proving product gate' }),
+    Object.freeze({ id: 'full', title: 'Full', changes: 'Shared or cross-system behavior', gate: 'Run the complete declared product gate' }),
+]);
+const issuedRegistries = new WeakSet();
+export const TESTING_GUIDE_REGISTRY = Object.freeze({ kind: 'unbound', tiers, stages: Object.freeze([]), gates: Object.freeze([]) });
+issuedRegistries.add(TESTING_GUIDE_REGISTRY);
+const NAME = /^[a-z][a-z0-9-]{0,63}$/;
+const text = (value) => typeof value === 'string' && value.length > 0 && value.length <= 4096 && !/[\x00-\x1f\x7f]/.test(value);
+export function createGateRegistry(input) {
+    if (!Array.isArray(input.stages) || !Array.isArray(input.gates) || !input.stages.length || !input.gates.length
+        || input.stages.length > 128 || input.gates.length > 128)
+        throw new RefusalError('gate registry requires bounded nonempty stages and gates');
+    const stageIds = new Set(input.stages.map(stage => stage.id));
+    if (stageIds.size !== input.stages.length || new Set(input.gates.map(gate => gate.id)).size !== input.gates.length
+        || input.stages.some(stage => !NAME.test(stage.id) || !Array.isArray(stage.command) || !stage.command.length
+            || stage.command.length > 128 || !stage.command.every(text) || typeof stage.requiresStack !== 'boolean'
+            || !Number.isSafeInteger(stage.timeoutSeconds) || stage.timeoutSeconds < 1 || stage.timeoutSeconds > TESTING_STAGE_TIMEOUT_MAX_SECONDS
+            || stage.select !== undefined && (typeof stage.select !== 'object' || stage.select === null
+                || Object.entries(stage.select).some(([kind, argv]) => !SELECTOR_KINDS.includes(kind) || !Array.isArray(argv)
+                    || !argv.length || argv.length > 32 || !argv.every(text) || !argv.some(value => value.includes(SELECTOR_VALUE)))))
+        || input.gates.some(gate => !NAME.test(gate.id) || !['targeted', 'full'].includes(gate.tier) || !text(gate.changes)
+            || !Array.isArray(gate.stages) || !gate.stages.length || new Set(gate.stages).size !== gate.stages.length
+            || gate.stages.some((id) => !stageIds.has(id))))
+        throw new RefusalError('gate registry contains invalid or duplicate declarations');
+    const registry = { kind: 'bound', tiers,
+        stages: input.stages.map(stage => ({ ...stage, command: [...stage.command],
+            ...(stage.select === undefined ? {} : { select: Object.fromEntries(Object.entries(stage.select)
+                    .map(([kind, argv]) => [kind, [...argv]])) }) })),
+        gates: input.gates.map(gate => ({ ...gate, stages: [...gate.stages] })), };
+    issuedRegistries.add(registry);
+    return registry;
+}
+export async function runGate(registry, request, deps) {
+    if (!issuedRegistries.has(registry) || registry.kind !== 'bound')
+        throw new RefusalError('gate execution requires an issued product-bound registry');
+    const gate = registry.gates.find(gate => gate.id === request.gate);
+    const requested = request.stages ?? gate?.stages ?? [];
+    if (!gate || !requested.length || requested.some(id => !gate.stages.includes(id)))
+        throw new RefusalError('gate selection is empty or unknown');
+    const select = request.select === undefined ? null : { ...request.select };
+    if (select && (!SELECTOR_KINDS.includes(select.kind) || !text(select.value)))
+        throw new RefusalError('gate selection has an invalid selector');
+    const selected = gate.stages.filter(id => requested.includes(id));
+    const observations = [];
+    let before;
+    let stability = 'stable';
+    const stabilityReasons = [];
+    // Without an available stack every stage needing it is reported unavailable and never runs, so
+    // there is no runtime to hold stable; capturing one would only bury that reason under its own.
+    const needsRuntime = request.stack?.state === 'available' && selected.some(id => registry.stages.find(stage => stage.id === id).requiresStack);
+    let runtimeBefore;
+    let runtimeFresh = true;
+    const capture = async () => {
+        try {
+            if (!deps.runtime)
+                throw new RefusalError('runtime stability capture not supplied');
+            const startedAt = Date.now();
+            const evidence = await deps.runtime.capture();
+            if (evidence.state === 'available' && (Date.parse(evidence.captureStartedAt) < startedAt || Date.parse(evidence.observedAt) > Date.now()))
+                runtimeFresh = false;
+            return evidence;
+        }
+        catch (error) {
+            stabilityReasons.push(`runtime stability unavailable: ${errorCause(error)}`);
+            stability = 'unavailable';
+            return undefined;
+        }
+    };
+    try {
+        before = await deps.subject();
+        if (!/^[a-f0-9]{64}$/.test(before))
+            throw new RefusalError('subject digest must be SHA-256');
+    }
+    catch (error) {
+        stability = 'unavailable';
+        stabilityReasons.push(`subject before: ${errorCause(error)}`);
+    }
+    if (needsRuntime)
+        runtimeBefore = await capture();
+    for (const id of selected) {
+        const stage = registry.stages.find(stage => stage.id === id);
+        let result;
+        const selection = select ? stage.select?.[select.kind] : undefined;
+        if (stage.requiresStack && request.stack?.state !== 'available') {
+            result = { kind: 'unavailable', reason: `stack unavailable: ${request.stack?.state === 'unavailable' ? request.stack.reason : 'no current stack observation'}` };
+        }
+        else if (select && !selection) {
+            // Running the whole stage would report a selection that never happened.
+            result = { kind: 'unavailable', reason: `stage ${id} declares no ${select.kind} selection; add testing.stages[].select.${select.kind} with the tool's own arguments` };
+        }
+        else {
+            const command = [...stage.command, ...(selection ?? []).map(value => value.replaceAll(SELECTOR_VALUE, select.value))];
+            try {
+                result = await deps.runProductTool({ gate: gate.id, stage: id, command, timeoutSeconds: stage.timeoutSeconds, select });
+            }
+            catch (error) {
+                result = { kind: 'unavailable', reason: `product tooling could not run: ${errorCause(error)}` };
+            }
+        }
+        observations.push({ ...result, id });
+    }
+    try {
+        const after = await deps.subject();
+        if (!/^[a-f0-9]{64}$/.test(after))
+            throw new RefusalError('subject digest must be SHA-256');
+        if (before !== undefined && before !== after && stability !== 'unavailable')
+            stability = 'void';
+    }
+    catch (error) {
+        stability = 'unavailable';
+        stabilityReasons.push(`subject after: ${errorCause(error)}`);
+    }
+    if (needsRuntime) {
+        const runtimeAfter = await capture();
+        if (deps.runtime && runtimeBefore && runtimeAfter) {
+            const comparison = compareEnvironmentSnapshot(deps.runtime.snapshot, runtimeBefore, runtimeAfter);
+            stabilityReasons.push(...comparison.diagnostics.map(row => row.message));
+            if (comparison.verdict === 'unavailable')
+                stability = 'unavailable';
+            else if (stability !== 'unavailable' && comparison.verdict !== 'stable')
+                stability = comparison.verdict;
+            if (!runtimeFresh && stability !== 'unavailable') {
+                stability = 'stale';
+                stabilityReasons.push('runtime capture predates the gate or is in the future');
+            }
+        }
+        else
+            stability = 'unavailable';
+    }
+    const result = classifyRun({ declared: gate.stages, selected, observations,
+        scope: request.staged ? 'staged' : select ? 'subset' : 'full', stability });
+    return { ...result, observations, reasons: [...result.reasons, ...stabilityReasons] };
+}
+// Without a declared gate there is nothing for test-run to run, and a tier table would send agents
+// looking for a gate that does not exist; so the guide says what to do instead and never promises PASS.
+const NO_GATE_GUIDE = '# Testing tiers\n\n'
+    + 'This cockpit declares no product test gate, so no change can be graded PASS.\n\n'
+    + 'Before changing behavior, add a characterization test at the nearest public boundary in the product\'s existing test runner and run it with that runner. If the product has no test runner, propose one to a person; do not add a test framework unasked. Comments or documentation changes that leave behavior unchanged need no test.\n\n'
+    + 'Never report work as verified or passing: report which tests you ran and how they exited, and that no gate graded them.\n\n'
+    + 'Ask a person to declare `[testing]` stages and gates in cockpit.toml, as the *Choose the proving test tier* section of `./node_modules/@b00dea/cockpit/docs/work-and-browser.md` describes.\n';
+export function renderTierGuide(registry, projection) {
+    if (!issuedRegistries.has(registry))
+        throw new RefusalError('testing guide requires an issued registry');
+    const cell = (value) => value.replaceAll('|', '\\|').replaceAll('`', '');
+    const rows = registry.tiers.map(tier => {
+        const gates = registry.gates.filter(gate => gate.tier === tier.id);
+        return `| ${tier.title} | ${gates.map(gate => cell(gate.changes)).join('; ') || tier.changes} | ${gates.map(gate => `\`${gate.id}\` (${gate.stages.join(', ')})`).join('; ') || tier.gate} |`;
+    });
+    const bytes = registry.kind === 'unbound' ? NO_GATE_GUIDE : `# Testing tiers\n\nChoose the narrowest product-owned gate that proves the change.\n\n`
+        + '| Tier | Change | Gate and ordered stages |\n| --- | --- | --- |\n' + rows.join('\n') + '\n\n'
+        + 'Extend an existing behavior test at the nearest public boundary when it can prove the change; add a test only when no existing test owns that behavior. Each test must fail when that behavior regresses. Do not duplicate proof already supplied by a stronger test.\n\n'
+        + `Run a gate with \`npx --no cockpit test-run --config cockpit.toml --gate <id>\`. Narrow it with \`npx --no cockpit test-run --config cockpit.toml --gate <id> ${GATE_SELECTOR_OPTION} <kind>:<value>\`, where kind is spec, file, test, or route. Each stage receives the value through its declared \`select\` arguments in its own tool's spelling; a stage that declares none for that kind is reported unavailable rather than run unselected.\n\n`
+        + 'Use the targeted gate while iterating. When a stage runs the affected or changed-since selection of the product build or test tool, let that tool choose the tests instead of narrowing by hand. If the declared tier is Full, run the complete gate once after implementation and review stabilize, before handing back. A targeted tier ends with its declared targeted gate.\n\n'
+        + 'Only the complete declared gate can PASS. Subsets and staged selftest are PARTIAL; unavailable checks are DEGRADED; changed subjects are VOID. Executed failures remain FAIL.\n\n'
+        + 'All selected stages run. Stack-dependent stages name an unavailable stack. Generated hooks run no tests; call correctness gates explicitly or through CI.\n';
+    const lines = bytes.trimEnd().split('\n').length;
+    const guidePath = 'packages/cockpit/surfaces/references/testing-tiers.md';
+    const checked = planSiblingProjection({ ...projection, standingSources: [...projection.standingSources.filter(source => source.path !== guidePath),
+            ...GUARD_SURFACE_TARGETS.filter(target => projection.targets?.includes(target) ?? true).map(target => ({ target,
+                path: guidePath, content: bytes, scope: 'always' }))] });
+    if (checked.kind === 'refusal')
+        return { kind: 'refusal', reason: checked.diagnostic.message };
+    const exceeded = checked.costs.find(cost => cost.status === 'exceeded');
+    if (exceeded?.status === 'exceeded')
+        return { kind: 'refusal',
+            reason: `the instructions ${exceeded.target} loads at start are ${exceeded.value} lines, over cockpit.guide_cap ${exceeded.cap}`,
+            exceeded: { target: exceeded.target, value: exceeded.value, cap: exceeded.cap } };
+    if (checked.costs.some(cost => cost.status !== 'within_cap'))
+        return { kind: 'refusal', reason: 'combined instruction cost is not characterized for every harness' };
+    return { kind: 'complete', bytes, lines, costs: checked.costs };
+}

package/dist/testing/hooks.d.ts

@@ -0,0 +1,59 @@
+import type { ExecutionStep } from '../environment/contract.js';
+import { type NamedPathInput } from '../references/named.js';
+import { type SurfaceDesiredEntry } from '../surfaces/ownership.js';
+export type NativeHookEntry = Extract<SurfaceDesiredEntry, {
+    kind: 'file';
+}>;
+export interface NativeHookPolicy extends NamedPathInput {
+    readonly bytes: string;
+}
+export type NativeHookMeasurement = ExecutionStep;
+export interface NativeHookBudget {
+    readonly prepareMeasurement: (entry: NativeHookEntry) => Promise<NativeHookMeasurement>;
+    readonly policy: NativeHookPolicy;
+}
+export type NativeHookInput = Readonly<{
+    cockpitId: string;
+    harnesses: readonly string[];
+}> & (Readonly<{
+    install: 'inspect';
+    budget?: NativeHookBudget;
+}> | Readonly<{
+    install: 'explicit-native';
+    budget: NativeHookBudget;
+}>);
+type HookRefusal = Readonly<{
+    kind: 'refusal';
+    reason: string;
+}>;
+export type HookBudgetResult = Readonly<{
+    kind: 'within-budget';
+    scope: 'supplied-execution-environment';
+    executionSha256: string;
+    limitMs: number;
+    measuredMs: number;
+}> | Readonly<{
+    kind: 'ci-required';
+    reason: string;
+}> | HookRefusal;
+export type NativeHookProjection = Readonly<{
+    kind: 'complete';
+    entries: readonly NativeHookEntry[];
+    cost: Extract<HookBudgetResult, {
+        kind: 'within-budget';
+    }>;
+    activation: Readonly<{
+        kind: 'explicit-native-install';
+        hooksPath: '.githooks';
+        mode: 493;
+    }>;
+}> | Readonly<{
+    kind: 'not-installed';
+    reason: string;
+}> | Exclude<HookBudgetResult, {
+    kind: 'within-budget';
+}>;
+export declare const NATIVE_HOOK_COST_SCRIPT = "{\n    count=0\n    while [ \"$count\" -lt 128 ]; do\n        printf 'refs/heads/cost %s refs/heads/cost %s\\n' \"$2\" \"$3\"\n        count=$((count + 1))\n    done\n} | /bin/sh \"$1\"";
+export declare function checkNativeHookBudget(entry: NativeHookEntry, measurement: NativeHookMeasurement, policy: NativeHookPolicy): Promise<HookBudgetResult>;
+export declare function projectNativeHooks(input: NativeHookInput): Promise<NativeHookProjection>;
+export {};

package/dist/testing/hooks.js

@@ -0,0 +1,139 @@
+import { sha256Hex } from '../sha256.js';
+import { authenticatedExecutionOutcome, executeProbe } from '../environment-exec/execute.js';
+import { resolveNamedPath } from '../references/named.js';
+import { bindSurfaceOwnershipIdentity } from '../surfaces/ownership.js';
+import { resolveExecutablePath } from '../environment/executable.js';
+import { errorCause } from '../environment/contract.js';
+export const NATIVE_HOOK_COST_SCRIPT = `{
+    count=0
+    while [ "$count" -lt 128 ]; do
+        printf 'refs/heads/cost %s refs/heads/cost %s\\n' "$2" "$3"
+        count=$((count + 1))
+    done
+} | /bin/sh "$1"`;
+const refusal = (reason) => ({ kind: 'refusal', reason });
+function policyLimit(policy) {
+    const reference = resolveNamedPath(policy);
+    if (reference.kind !== 'resolved')
+        return refusal(`native hook budget policy is unavailable: ${policy.path}`);
+    const owner = policy.manifest.entries.find(entry => entry.path === policy.path);
+    if (!owner || owner.kind !== 'file' || typeof policy.bytes !== 'string' || Buffer.byteLength(policy.bytes) > 64
+        || sha256Hex(policy.bytes) !== owner.sha256)
+        return refusal('native hook budget must bind exact policy bytes to the ownership manifest');
+    const marker = /^native-hook-ms=([1-9][0-9]*)\n$/.exec(policy.bytes);
+    const limitMs = marker ? Number(marker[1]) : Number.NaN;
+    return Number.isSafeInteger(limitMs) ? limitMs : refusal('native hook policy must declare one positive native-hook-ms cap');
+}
+export async function checkNativeHookBudget(entry, measurement, policy) {
+    const cap = policyLimit(policy);
+    if (typeof cap !== 'number')
+        return cap;
+    const resolvedShell = await resolveExecutablePath('/bin/sh');
+    if (resolvedShell.state !== 'available')
+        return refusal('native hook requires an authenticated system shell');
+    const file = measurement?.consumedFiles?.find(file => !file.executable && file.sha256 === entry.sha256
+        && measurement.argv.length === 7 && measurement.argv[4] === file.path && file.argvIndexes.length === 1 && file.argvIndexes[0] === 4);
+    const argv = measurement?.argv;
+    const oid = (value) => /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value) && /[1-9a-f]/.test(value);
+    const shell = measurement?.consumedFiles?.find(file => file.executable && file.path === resolvedShell.value.canonicalPath
+        && file.sha256 === resolvedShell.value.sha256 && file.executionMode === resolvedShell.value.executionMode
+        && file.argvIndexes.length === 1 && file.argvIndexes[0] === 0);
+    const workload = shell && argv && argv[0] === resolvedShell.value.canonicalPath && argv[1] === '-c' && argv[2] === NATIVE_HOOK_COST_SCRIPT
+        && argv[3] === 'native-hook-cost' && oid(argv[5]) && oid(argv[6]) && argv[5].length === argv[6].length && argv[5] !== argv[6];
+    const marker = /^# cockpit:budget name=native-hook-ms limit-ms=([1-9][0-9]*)$/m.exec(entry.bytes);
+    const limitMs = marker ? Number(marker[1]) : Number.NaN;
+    if (!file || !workload || entry.writer !== 'cockpit' || sha256Hex(entry.bytes) !== entry.sha256 || limitMs !== cap) {
+        return refusal('native hook requires intact bytes, an authenticated policy cap and the exact 128-update ancestry workload');
+    }
+    const executionSha256 = sha256Hex(JSON.stringify(measurement));
+    const started = performance.now();
+    const outcome = authenticatedExecutionOutcome(await executeProbe(measurement), measurement);
+    const measuredMs = Math.ceil(performance.now() - started);
+    if (!outcome || outcome.kind !== 'complete' || outcome.execution.exitCode !== 0) {
+        return refusal(`native hook cost execution failed: ${outcome?.kind === 'refusal' ? outcome.code : 'missing authenticated successful receipt'}`);
+    }
+    return measuredMs > limitMs
+        ? { kind: 'ci-required', reason: `native hook cost ${measuredMs}ms exceeds native-hook-ms=${limitMs}; move this check to CI` }
+        : { kind: 'within-budget', scope: 'supplied-execution-environment', executionSha256, limitMs, measuredMs };
+}
+function nativeScript(cockpitId, limitMs) {
+    return `#!/bin/sh
+# cockpit:writer ${cockpitId}
+# cockpit:budget name=native-hook-ms limit-ms=${limitMs}
+count=0
+while IFS=' ' read -r local_ref local_oid remote_ref remote_oid extra || [ -n "$local_ref$local_oid$remote_ref$remote_oid$extra" ]; do
+    count=$((count + 1))
+    if [ "$count" -gt 128 ]; then
+        echo 'native push guard: more than 128 ref updates; review and split the push' >&2
+        exit 2
+    fi
+    case "$local_ref:$remote_ref:$extra" in
+        refs/*:refs/*:) ;;
+        *) echo 'native push guard: malformed ref update' >&2; exit 2 ;;
+    esac
+    for oid in "$local_oid" "$remote_oid"; do
+        case "$oid" in
+            ''|*[!0-9a-f]*) echo 'native push guard: malformed object identity' >&2; exit 2 ;;
+        esac
+        if [ "\${#oid}" -ne 40 ] && [ "\${#oid}" -ne 64 ]; then
+            echo 'native push guard: malformed object identity length' >&2
+            exit 2
+        fi
+    done
+    if [ "\${#local_oid}" -ne "\${#remote_oid}" ]; then
+        echo 'native push guard: object identity formats differ' >&2
+        exit 2
+    fi
+    case "$local_oid" in
+        *[!0]*) ;;
+        *) echo 'native push guard: branch or tag deletion requires explicit review' >&2; exit 2 ;;
+    esac
+    case "$remote_oid" in
+        *[!0]*) ;;
+        *) continue ;;
+    esac
+    git merge-base --is-ancestor "$remote_oid" "$local_oid"
+    status=$?
+    case "$status" in
+        0) ;;
+        1) echo 'native push guard: non-fast-forward update requires explicit review' >&2; exit 2 ;;
+        *) echo 'native push guard: ancestry check failed; inspect repository state' >&2; exit 2 ;;
+    esac
+done
+exit 0
+`;
+}
+export async function projectNativeHooks(input) {
+    if (input.install === 'inspect')
+        return { kind: 'not-installed', reason: 'native hooks require explicit installation' };
+    if (input.install !== 'explicit-native' || !/^cockpit:[a-z0-9][a-z0-9-]*:[a-f0-9]{64}$/.test(input.cockpitId)
+        || input.budget.policy.authority.cockpitId !== input.cockpitId) {
+        return refusal('native hook requires explicit installation, cockpit identity and a named positive budget');
+    }
+    const limit = policyLimit(input.budget.policy);
+    if (typeof limit !== 'number')
+        return limit;
+    const bytes = nativeScript(input.cockpitId, limit);
+    const harnesses = [...new Set(input.harnesses)].sort();
+    if (!harnesses.length)
+        return refusal('native hook requires configured harness ownership');
+    const entry = { path: '.githooks/pre-push', kind: 'file', ownership: 'whole-file',
+        harnesses: harnesses, writer: 'cockpit', schemaVersion: 1, scope: 'scoped', capability: 'instructed', bytes, sha256: sha256Hex(bytes) };
+    if (typeof input.budget.prepareMeasurement !== 'function')
+        return refusal('native hook requires a bounded measurement plan callback');
+    let measurement;
+    try {
+        measurement = await input.budget.prepareMeasurement(entry);
+    }
+    catch (error) {
+        return refusal(`native hook measurement failed: ${errorCause(error)}`);
+    }
+    const cost = await checkNativeHookBudget(entry, measurement, input.budget.policy);
+    if (cost.kind !== 'within-budget')
+        return cost;
+    const owned = bindSurfaceOwnershipIdentity([entry], input.cockpitId);
+    if (owned.kind === 'refusal')
+        return refusal(owned.diagnostic.message);
+    return { kind: 'complete', entries: [entry], cost,
+        activation: { kind: 'explicit-native-install', hooksPath: '.githooks', mode: 0o755 } };
+}

package/dist/testing/test-protection.d.ts

@@ -0,0 +1,34 @@
+export interface DiffFile {
+    old: string;
+    next: string;
+    hunk: boolean;
+    removed: boolean;
+    removedLines: string[];
+    added: string[];
+    renamed: boolean;
+    deleted: boolean;
+}
+export interface WeakeningFinding {
+    readonly path: string;
+    readonly kind: WeakeningKind;
+    readonly reason: string;
+}
+type WeakeningKind = 'test-file-removed' | 'test-skipped' | 'check-suppressed' | 'tests-removed' | 'assertions-removed' | 'assertions-loosened' | 'assertion-vacuous' | 'test-selection-narrowed';
+/** Reads `git diff` output (taken with --unified=0 and core.quotePath=true) into one record per file. */
+export declare function parseDiff(diff: string): DiffFile[];
+/**
+ * Why added lines turn off or short-circuit what runs. Only explicit added-line forms are measured;
+ * this is not JavaScript dataflow analysis.
+ */
+export declare function additiveBypassReasons(added: readonly string[]): string[];
+export interface TestRoles {
+    readonly isTest: (path: string) => boolean;
+    /** A runner's configuration, or a manifest that carries a test script. */
+    readonly isTestConfig: (path: string) => boolean;
+}
+/**
+ * The findings a diff earns over the files `roles` calls tests. A diff cannot prove that a
+ * replacement keeps its force, so a removal is flagged and a person acknowledges the legitimate ones.
+ */
+export declare function classifyTestWeakening(files: readonly DiffFile[], roles: TestRoles): WeakeningFinding[];
+export {};

package/dist/testing/test-protection.js

@@ -0,0 +1,137 @@
+// Detects a change that makes tests pass by weakening them. It has no imports on purpose: CI runs
+// the base revision's copy of scripts/check-test-protection.mjs beside this file, so the detector
+// that judges a change is never the one the change edited, and the same code judges a consumer's
+// checkout when `work grade` runs.
+function gitPath(value) {
+    if (!value.startsWith('"'))
+        return value;
+    // Git quotes paths as C strings, including octal UTF-8 bytes.
+    const bytes = [];
+    for (let i = 1; i < value.length - 1; i++) {
+        if (value[i] !== '\\') {
+            bytes.push(...Buffer.from(value[i]));
+            continue;
+        }
+        const octal = /^[0-7]{1,3}/.exec(value.slice(i + 1))?.[0];
+        if (octal) {
+            bytes.push(Number.parseInt(octal, 8));
+            i += octal.length;
+            continue;
+        }
+        const escaped = value[++i];
+        const controls = { t: '\t', n: '\n', r: '\r', b: '\b', f: '\f', v: '\v', '\\': '\\', '"': '"' };
+        if (!(escaped in controls))
+            throw new Error('unsupported Git path escape');
+        bytes.push(...Buffer.from(controls[escaped]));
+    }
+    return Buffer.from(bytes).toString('utf8');
+}
+/** Reads `git diff` output (taken with --unified=0 and core.quotePath=true) into one record per file. */
+export function parseDiff(diff) {
+    const files = [];
+    let file;
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('diff --git ')) {
+            const names = /^diff --git ("(?:\\.|[^"])*"|a\/\S+) ("(?:\\.|[^"])*"|b\/\S+)$/.exec(line);
+            file = { old: names ? gitPath(names[1]).slice(2) : '', next: names ? gitPath(names[2]).slice(2) : '', hunk: false, removed: false, removedLines: [], renamed: false, deleted: false, added: [] };
+            files.push(file);
+        }
+        else if (file) {
+            if (line.startsWith('@@ '))
+                file.hunk = true;
+            else if (!file.hunk && line.startsWith('--- '))
+                file.old = gitPath(line.slice(4)).replace(/^a\//, '');
+            else if (!file.hunk && line.startsWith('+++ '))
+                file.next = gitPath(line.slice(4)).replace(/^b\//, '');
+            else if (line.startsWith('rename from ')) {
+                file.old = gitPath(line.slice(12));
+                file.renamed = true;
+            }
+            else if (line.startsWith('rename to '))
+                file.next = gitPath(line.slice(10));
+            else if (line.startsWith('deleted file mode '))
+                file.deleted = true;
+            else if (line.startsWith('-') && line.slice(1).trim()) {
+                file.removed = true;
+                file.removedLines.push(line.slice(1));
+            }
+            else if (line.startsWith('+'))
+                file.added.push(line.slice(1));
+            else if (line.startsWith('Binary files '))
+                file.removed = true;
+        }
+    }
+    return files;
+}
+/**
+ * Why added lines turn off or short-circuit what runs. Only explicit added-line forms are measured;
+ * this is not JavaScript dataflow analysis.
+ */
+export function additiveBypassReasons(added) {
+    const reasons = [];
+    if (/(?:\.\s*|\[\s*['"])(?:skip|todo|only|skipIf|runIf|fails)\b|\b(?:skip|todo|only)\s*:\s*true/.test(added.join('\n'))) {
+        reasons.push('test selection or expected-failure semantics added');
+    }
+    if (added.some(line => /^[ \t]*return[ \t]*;?[ \t]*(?:\/\/.*)?$/.test(line))) {
+        reasons.push('potential additive control-flow bypass: bare return added');
+    }
+    if (added.some(line => /^[ \t]*(?:if\s*\(\s*(?:true|1)\s*\)\s*(?:\{\s*)?return\s*;?(?:\s*\})?\s*(?:\/\/.*)?$|if\s*\(\s*(?:false|0|null|undefined)\s*\)\s*\{|(?:false\s*&&|true\s*\|\|)\s*(?:describe|test|it|suite)\s*\(|process\s*\.\s*exit\s*\(\s*(?:0\s*)?\))/.test(line))) {
+        reasons.push('potential additive control-flow bypass: explicit static bypass added');
+    }
+    return reasons;
+}
+// JS/TS first, then the Python forms that mean the same. A match in an added comment still counts:
+// a directive is a comment.
+const SKIPPED = /\b(?:it|test|describe|suite|context|bench)\s*\.\s*(?:skip|only|todo|skipIf|runIf|fails|failing|fixme)\b|\b(?:xit|xtest|xdescribe|xcontext|fit|fdescribe)\s*\(|\b(?:skip|only)\s*:\s*true|\bpytest\s*\.\s*(?:mark\s*\.\s*(?:skip|skipif|xfail)|skip)\b|\bunittest\s*\.\s*(?:skip|skipIf|skipUnless|expectedFailure)\b|^\s*@(?:skip|skipIf|skipUnless|expectedFailure)\b|\bself\s*\.\s*skipTest\s*\(/;
+const SUPPRESSED = /@ts-ignore|@ts-nocheck|eslint-disable|\bnoqa\b|\btype:\s*ignore\b|\bpylint:\s*disable\b/;
+const TEST_DECLARATION = /^\s*(?:(?:it|test)\s*(?:\.\s*\w+)*\s*(?:\.\s*each\s*\([^)]*\))?\s*\(|def\s+test_|async\s+def\s+test_)/;
+const ASSERTION = /\bexpect\s*\(|\bassert\b|\bassert[A-Z]\w*\s*\(|\.should\b|\bt\.(?:is|true|deepEqual|equal|throws)\s*\(/;
+const STRONG = /\.(?:toBe|toEqual|toStrictEqual|toMatchObject|toHaveBeenCalledWith|toHaveLength|toThrow\w*|toContain\w*|toMatch)\s*\(|\bassert(?:Equal|Equals|In|Raises|IsNone)\b|\bassert\s+\S+\s*(?:==|!=|in)\s/;
+const WEAK = /\.(?:toBeDefined|toBeTruthy|toBeFalsy|toBeUndefined)\s*\(|\bexpect\.(?:anything|any)\s*\(|\.not\.toBeNull\s*\(|\bassert\s+\w+\s*$|\bassertTrue\s*\(\s*\w+\s*\)/;
+const VACUOUS = /\bexpect\s*\(\s*(?:true|1|false|0|null|'[^']*'|"[^"]*")\s*\)\s*\.\s*(?:toBe|toEqual|toStrictEqual)\s*\(|\bassert\s+(?:True|1|not\s+False)\s*$|\bassert\s*\(?\s*true\s*\)?\s*;?\s*$|\bassertTrue\s*\(\s*True\s*\)/;
+// What a test runner's own configuration says about which files it runs.
+const NARROWING = /\b(?:exclude|testPathIgnorePatterns|testIgnore|ignore|deselect|norecursedirs|skip)\b|--ignore\b|--deselect\b|--exclude\b|--passWithNoTests|\|\|\s*true\b|\bexit\s+0\b/;
+const WIDENING = /\b(?:include|testMatch|testRegex|testpaths|projects)\b/;
+const TEST_SCRIPT = /^\s*"(?:pre|post)?test[^"]*"\s*:/;
+const count = (lines, pattern) => lines.filter(line => pattern.test(line)).length;
+/**
+ * The findings a diff earns over the files `roles` calls tests. A diff cannot prove that a
+ * replacement keeps its force, so a removal is flagged and a person acknowledges the legitimate ones.
+ */
+export function classifyTestWeakening(files, roles) {
+    const findings = [];
+    for (const file of files) {
+        const path = file.deleted || file.next === '/dev/null' ? file.old : file.next;
+        const finding = (kind, reason) => findings.push({ path, kind, reason });
+        const wasTest = roles.isTest(file.old);
+        if (wasTest && (file.deleted || file.next === '/dev/null' || file.renamed && !roles.isTest(file.next))) {
+            finding('test-file-removed', 'a test file was deleted or moved out of the tests');
+            continue;
+        }
+        if (roles.isTest(path)) {
+            if (count(file.added, SKIPPED))
+                finding('test-skipped', 'a test was skipped, focused, marked todo or expected to fail');
+            if (count(file.added, SUPPRESSED))
+                finding('check-suppressed', 'a type or lint check was suppressed in a test');
+            if (count(file.removedLines, TEST_DECLARATION) > count(file.added, TEST_DECLARATION))
+                finding('tests-removed', 'more tests were removed than added');
+            if (count(file.removedLines, ASSERTION) > count(file.added, ASSERTION))
+                finding('assertions-removed', 'more assertions were removed than added');
+            else if (count(file.removedLines, STRONG) > count(file.added, STRONG) && count(file.added, WEAK) > count(file.removedLines, WEAK)) {
+                finding('assertions-loosened', 'specific assertions were replaced by weaker ones');
+            }
+            if (count(file.added, VACUOUS))
+                finding('assertion-vacuous', 'an assertion that cannot fail was added');
+        }
+        else if (roles.isTestConfig(path)) {
+            const manifest = /(?:^|\/)package\.json$/.test(path);
+            const scriptsAdded = manifest ? file.added.filter(line => TEST_SCRIPT.test(line)) : file.added;
+            if (count(scriptsAdded, NARROWING))
+                finding('test-selection-narrowed', 'test configuration now excludes, ignores or tolerates the absence of tests');
+            else if (manifest ? count(file.removedLines, TEST_SCRIPT) > count(scriptsAdded, TEST_SCRIPT)
+                : count(file.removedLines, WIDENING) > count(file.added, WIDENING))
+                finding('test-selection-narrowed', 'test configuration no longer selects what it selected');
+        }
+    }
+    return findings;
+}

package/dist/testing/verdict.d.ts

@@ -0,0 +1,29 @@
+export declare const RUN_VERDICTS: readonly ['PASS', 'FAIL', 'PARTIAL', 'DEGRADED', 'VOID'];
+export type RunVerdict = typeof RUN_VERDICTS[number];
+export type StageResult = Readonly<{
+    kind: 'executed';
+    exitCode: number;
+    signal: string | null;
+    outputBytes: number;
+    assertion: 'passed' | 'failed' | 'missing';
+}> | Readonly<{
+    kind: 'unavailable';
+    reason: string;
+}>;
+export type StageObservation = StageResult & Readonly<{
+    id: string;
+}>;
+export interface RunInput {
+    readonly declared: readonly string[];
+    readonly selected: readonly string[];
+    readonly observations: readonly StageObservation[];
+    readonly scope: 'full' | 'subset' | 'staged';
+    readonly stability: 'stable' | 'void' | 'stale' | 'unavailable';
+}
+export interface RunClassification {
+    readonly verdict: RunVerdict;
+    readonly satisfiesGate: boolean;
+    readonly executed: number;
+    readonly reasons: readonly string[];
+}
+export declare function classifyRun(input: RunInput): RunClassification;

package/dist/testing/verdict.js

@@ -0,0 +1,62 @@
+export const RUN_VERDICTS = ['PASS', 'FAIL', 'PARTIAL', 'DEGRADED', 'VOID'];
+export function classifyRun(input) {
+    const declared = new Set(input.declared);
+    const selected = new Set(input.selected);
+    const seen = new Set();
+    const reasons = [];
+    let failed = false;
+    let executed = 0;
+    let degraded = !declared.size || declared.size !== input.declared.length || !selected.size
+        || selected.size !== input.selected.length || input.selected.some(id => !declared.has(id))
+        || !['full', 'subset', 'staged'].includes(input.scope) || !['stable', 'void', 'stale', 'unavailable'].includes(input.stability);
+    if (degraded)
+        reasons.push('stage selection must be nonempty, unique and declared');
+    for (const row of input.observations) {
+        const first = !seen.has(row.id);
+        if (!selected.has(row.id) || seen.has(row.id)) {
+            degraded = true;
+            reasons.push(`${row.id}: unexpected or duplicate stage evidence`);
+        }
+        seen.add(row.id);
+        if (row.kind === 'executed' && (row.assertion === 'failed'
+            || row.signal === null && Number.isInteger(row.exitCode) && row.exitCode > 0)) {
+            failed = true;
+            reasons.push(`${row.id}: executed check disagreed (exit ${row.exitCode})`);
+        }
+        if (row.kind === 'unavailable') {
+            degraded = true;
+            reasons.push(`${row.id}: ${row.reason}`);
+        }
+        else if (row.kind !== 'executed' || row.signal !== null || !Number.isInteger(row.exitCode) || row.exitCode < 0) {
+            degraded = true;
+            reasons.push(`${row.id}: execution interrupted or invalid (${row.signal ?? row.exitCode})`);
+        }
+        else {
+            // The authenticated exit status of a process that ran to completion proves the stage ran;
+            // its output does not. Grading silence as unproven made tsc --noEmit, node --check and quiet
+            // linters unable to satisfy a gate. A runner that selects no tests reports that through its
+            // own exit status, and a narrowed run is PARTIAL whatever it prints.
+            if (first && selected.has(row.id))
+                executed++;
+            if (row.assertion !== 'passed' && row.assertion !== 'failed') {
+                degraded = true;
+                reasons.push(`${row.id}: no structured assertion result`);
+            }
+        }
+    }
+    for (const id of selected)
+        if (!seen.has(id)) {
+            degraded = true;
+            reasons.push(`${id}: selected stage never ran`);
+        }
+    if (input.stability === 'unavailable') {
+        degraded = true;
+        reasons.push('subject stability evidence unavailable');
+    }
+    const voided = input.stability === 'void' || input.stability === 'stale';
+    if (voided)
+        reasons.push('subject changed or evidence authority is stale; evidence satisfies no gate');
+    const partial = input.scope !== 'full' || selected.size !== declared.size;
+    const verdict = failed ? 'FAIL' : degraded ? 'DEGRADED' : voided ? 'VOID' : partial ? 'PARTIAL' : 'PASS';
+    return { verdict, satisfiesGate: verdict === 'PASS', executed, reasons };
+}