@sdods/core 0.8.0 → 0.9.0

package/dist/perf/vitals.js

@@ -0,0 +1,236 @@
+import { SdodsError } from '../errors.js';
+/**
+ * Page vitals, latency percentiles and the budgets they are judged against, shared by the explicit
+ * perf steps (`steps/perf.steps.ts`) and the end-of-scenario check every `@perf` scenario gets
+ * (`quality/hooks.ts`). Outside the step file for the reason `a11y/audit.ts` gives: importing a step
+ * file registers its phrases, and `steps.core.exclude: [perf]` must stay able to switch them off.
+ * The rules these functions keep are written up at the top of `steps/perf.steps.ts`.
+ */
+/* ── budgets ──────────────────────────────────────────────────────────── */
+/** The page vitals SDODS records. Each name is also its key in `perf.budgets`. */
+export const VITAL_KEYS = ['pageLoadMs', 'lcpMs', 'fcpMs', 'ttfbMs'];
+/** The `perf.budgets` key a sampled API latency distribution is judged against. */
+export const API_P95_BUDGET_KEY = 'apiP95Ms';
+/**
+ * Effective budgets, env overriding project per key.
+ *
+ * `resolveConfig` already deep-merges `env.perf` into `config.project.perf`, so on a resolved
+ * config the project side is the whole answer. Merging the env side again is idempotent and keeps
+ * this correct for a config assembled by hand. Non-numeric values are dropped rather than spread —
+ * an explicit `undefined` in the env layer would otherwise erase a real project budget and turn a
+ * configured assertion into an unconfigured one.
+ */
+export function resolvedBudgets(config) {
+    const out = {};
+    for (const layer of [config.project.perf?.budgets, config.env.perf?.budgets]) {
+        for (const [key, value] of Object.entries(layer ?? {})) {
+            if (typeof value === 'number' && Number.isFinite(value))
+                out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * The configured budget for one key, or a hard error naming it.
+ *
+ * PROVES the assertion that follows is gated on something real. A missing budget must never
+ * degrade to a skip or to `Infinity`: an unconfigured budget is the single failure mode that lets
+ * an entire perf suite report success while asserting nothing at all.
+ */
+export function requireBudget(config, key) {
+    const budget = resolvedBudgets(config)[key];
+    const envName = config.env.name ?? 'unknown';
+    if (typeof budget !== 'number' || !(budget > 0)) {
+        throw new SdodsError('CONFIG_INVALID', `Perf budget "${key}" is not configured for environment "${envName}".`, {
+            hint: `Set perf.budgets.${key} in the project's sdods.project.yaml, or override it in envs/${envName}.yaml. Without it this assertion would pass no matter how slow the application is.`,
+        });
+    }
+    return budget;
+}
+export function requireVitalKey(name) {
+    if (VITAL_KEYS.includes(name))
+        return name;
+    throw new SdodsError('CONFIG_INVALID', `"${name}" is not a page vital SDODS records.`, {
+        hint: `Known vitals: ${VITAL_KEYS.join(', ')}. Each is also its key in perf.budgets.`,
+    });
+}
+/**
+ * Measurements have to survive from a `When` step to a `Then` step. They do not go in
+ * `apiContext.vars`: that store doubles as a `{{…}}` template scope, so an array of samples parked
+ * there would leak into every later rendering. Keyed on the per-test `scenario` object, so two
+ * scenarios in parallel workers can never read each other's numbers and nothing outlives the
+ * scenario that measured it.
+ */
+const stores = new WeakMap();
+export function perfStore(key) {
+    let store = stores.get(key);
+    if (!store) {
+        store = { recordings: [], sampleSets: [] };
+        stores.set(key, store);
+    }
+    return store;
+}
+export function lastRecording(key) {
+    const recording = perfStore(key).recordings.at(-1);
+    if (!recording) {
+        throw new SdodsError('RUN_FAILED', 'No page vitals have been recorded in this scenario.', {
+            hint: 'Add `When I record the page vitals` after the navigation you want to measure.',
+        });
+    }
+    return recording;
+}
+export function lastSampleSet(key) {
+    const set = perfStore(key).sampleSets.at(-1);
+    if (!set) {
+        throw new SdodsError('RUN_FAILED', 'No latency samples have been taken in this scenario.', {
+            hint: 'Add `When I sample the latency of GET "/path" over 20 requests` before asserting a p95.',
+        });
+    }
+    return set;
+}
+/* ── statistics ───────────────────────────────────────────────────────── */
+/**
+ * Nearest-rank p95 — deterministic for a given set of samples, with no interpolation to argue
+ * about. Below 20 samples the nearest rank IS the maximum; the sample count travels in the
+ * attachment and in every failure message so a reader can see when "p95" means "slowest of five".
+ *
+ * Throws rather than returning 0 on an empty sample: a p95 of 0 slides under every budget.
+ */
+export function p95Of(msValues) {
+    if (msValues.length === 0) {
+        throw new SdodsError('RUN_FAILED', 'Cannot compute a p95 over an empty sample.', {
+            hint: 'Sample at least one request before asserting a p95.',
+        });
+    }
+    const sorted = [...msValues].sort((a, b) => a - b);
+    const index = Math.max(0, Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1));
+    return sorted[index];
+}
+/* ── browser-side collection ──────────────────────────────────────────── */
+/**
+ * How long the LCP observer is given to settle. LCP arrives as a stream of ever-larger candidates;
+ * `buffered: true` replays the ones already emitted and this window catches any still in flight.
+ * A fixed constant rather than a computed wait, so two runs of one scenario observe the same
+ * window and a baseline stays comparable.
+ */
+export const LCP_SETTLE_MS = 500;
+/** Bounded wait for the load event before reading `loadEventEnd`. */
+export const LOAD_WAIT_MS = 5_000;
+/**
+ * Runs inside the page. Serialised by Playwright, so it closes over nothing but its argument — the
+ * type aliases above are erased at compile time and are safe to reference; the constants are not,
+ * which is why the settle window is passed in.
+ */
+export async function collectRawVitals(settleMs) {
+    const perf = performance;
+    const Observer = globalThis
+        .PerformanceObserver;
+    // Every vital is an offset from navigation start, so a genuine measurement is always > 0.
+    const positive = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.round(value) : null;
+    const supported = Observer?.supportedEntryTypes ?? [];
+    const lcpSupported = supported.includes('largest-contentful-paint');
+    const fcpSupported = supported.includes('paint');
+    // TRAP: paint timings can land AFTER the load event. Reading the paint entry eagerly while only
+    // LCP waited for the settle window reported `fcpMs: null` beside a real `lcpMs` on a page that
+    // had painted perfectly well — impossible, since first paint always precedes the largest one —
+    // and a budget assertion would then have failed it as "not measured". So nothing is read until
+    // the window closes, and the window is opened whether or not LCP is supported.
+    let largestPaint = 0;
+    await new Promise((resolve) => {
+        let observer;
+        try {
+            if (Observer && lcpSupported) {
+                observer = new Observer((list) => {
+                    for (const entry of list.getEntries()) {
+                        const start = entry.startTime;
+                        if (typeof start === 'number' && start > largestPaint)
+                            largestPaint = start;
+                    }
+                });
+                observer.observe({ type: 'largest-contentful-paint', buffered: true });
+            }
+        }
+        catch {
+            observer = undefined;
+        }
+        setTimeout(() => {
+            try {
+                observer?.disconnect();
+            }
+            catch {
+                /* already gone */
+            }
+            resolve();
+        }, settleMs);
+    });
+    const nav = perf.getEntriesByType('navigation')[0];
+    const fcpEntry = perf.getEntriesByName('first-contentful-paint')[0];
+    const lcpMs = largestPaint > 0 ? Math.round(largestPaint) : null;
+    let totalResources = 0;
+    let totalBytes = 0;
+    for (const entry of perf.getEntriesByType('resource')) {
+        totalResources++;
+        const size = entry.transferSize;
+        if (typeof size === 'number' && Number.isFinite(size))
+            totalBytes += size;
+    }
+    const startTime = nav && typeof nav.startTime === 'number' ? nav.startTime : 0;
+    return {
+        hasNavigationEntry: Boolean(nav),
+        navigationStartEpochMs: nav && typeof perf.timeOrigin === 'number' ? Math.round(perf.timeOrigin + startTime) : null,
+        pageLoadMs: nav ? positive(nav.loadEventEnd) : null,
+        ttfbMs: nav ? positive(nav.responseStart) : null,
+        fcpMs: fcpEntry ? positive(fcpEntry.startTime) : null,
+        lcpMs,
+        domContentLoadedMs: nav ? positive(nav.domContentLoadedEventEnd) : null,
+        totalResources,
+        totalResourceSizeKB: Math.round(totalBytes / 1024),
+        lcpSupported,
+        fcpSupported,
+    };
+}
+/**
+ * Turns the page's answer into a recording, capturing WHY a vital is null while the browser's
+ * capabilities are still in hand. By the time a `Then` step fails, "lcpMs was not measured" on its
+ * own sends the reader hunting for a bug in a page that is merely running in a browser that does
+ * not implement LCP (WebKit). Support is read from `PerformanceObserver.supportedEntryTypes`, never
+ * assumed from the browser name.
+ */
+export function toRecording(raw, url, browserName) {
+    const vitals = {
+        pageLoadMs: raw.pageLoadMs,
+        lcpMs: raw.lcpMs,
+        fcpMs: raw.fcpMs,
+        ttfbMs: raw.ttfbMs,
+    };
+    const where = browserName ? ` in ${browserName}` : ' in this browser';
+    const unmeasured = {};
+    if (raw.pageLoadMs === null)
+        unmeasured.pageLoadMs = `the load event had not fired ${LOAD_WAIT_MS} ms after the vitals step began`;
+    if (raw.ttfbMs === null)
+        unmeasured.ttfbMs = 'the navigation entry reported no response start';
+    if (raw.fcpMs === null)
+        unmeasured.fcpMs = raw.fcpSupported
+            ? 'the page painted no contentful frame'
+            : `paint timings are not implemented${where}`;
+    if (raw.lcpMs === null)
+        unmeasured.lcpMs = raw.lcpSupported
+            ? 'the page produced no largest-contentful-paint candidate'
+            : `largest-contentful-paint is not implemented${where} — restrict the scenario to a browser that supports it`;
+    // The contract's three non-nullable fields carry 0 for an unmeasured value; the nullable
+    // `budgets.measured` block written alongside is what the assertions read, so a 0 here can never
+    // be mistaken for a measurement.
+    const metrics = {
+        url,
+        timestamp: new Date(raw.navigationStartEpochMs ?? Date.now()).toISOString(),
+        domContentLoaded: raw.domContentLoadedMs ?? 0,
+        pageLoadTime: raw.pageLoadMs ?? 0,
+        timeToFirstByte: raw.ttfbMs ?? 0,
+        totalResources: raw.totalResources,
+        totalResourceSizeKB: raw.totalResourceSizeKB,
+        firstContentfulPaint: raw.fcpMs,
+        largestContentfulPaint: raw.lcpMs,
+    };
+    return { url, vitals, unmeasured, metrics };
+}
+//# sourceMappingURL=vitals.js.map

package/dist/quality/a11y-scenario.d.ts

@@ -0,0 +1,68 @@
+import { type Page } from '@playwright/test';
+import { type A11yConfig } from '@sdods/contracts';
+import { type A11yResults } from '../a11y/audit.js';
+/**
+ * The audit an `@a11y` tag buys. Before this existed the tag was a label: the linter accepted it,
+ * the docs said it ran axe, and nothing read it.
+ *
+ * At the END of an `@a11y` UI or hybrid scenario, the page the scenario finished on is audited with
+ * axe (WCAG 2.x A/AA, as the explicit steps are) and the scenario fails on any violation at or above
+ * `a11y.failOn`. The report is attached as `sdods/a11y-scenario` pass or fail, and it is also what
+ * the `a11y` process gate reads.
+ *
+ * What it deliberately does not do:
+ *   · audit a scenario that already failed. The page it stopped on is wherever the failure left it,
+ *     and a violation list on top of the real error only buries the error;
+ *   · audit a URL an explicit whole-page audit step already covered in the same scenario. That step
+ *     ran with the threshold its author chose, and it passed (a failed step would have failed the
+ *     scenario);
+ *   · audit every page the scenario passed through. It audits the final page. A flow that needs each
+ *     page checked writes the explicit step after each navigation.
+ */
+export type A11yScenarioStatus = 'audited' | 'covered-by-step' | 'skipped';
+/** What `sdods/a11y-scenario` contains, and what the `a11y` process gate reads back. */
+export interface A11yScenarioReport {
+    kind: 'a11y-scenario';
+    runnerProject: string;
+    fingerprint: string;
+    retry: number;
+    url: string;
+    status: A11yScenarioStatus;
+    reason?: string;
+    failOn: A11yConfig['failOn'];
+    include: string[];
+    exclude: string[];
+    /** Every violation axe reported, at any impact. */
+    violations: number;
+    /** Violations at or above `failOn`: the ones that fail the scenario. */
+    blocking: number;
+    blockingRules: string[];
+    results?: A11yResults;
+}
+export interface A11yScenarioDeps {
+    page: Page;
+    config: {
+        project: {
+            a11y?: Partial<A11yConfig>;
+        };
+    };
+    scenario: {
+        data: {
+            runnerProject: string;
+            fingerprint: string;
+            retry: number;
+        };
+        file(rel: string): string;
+    };
+    testInfo: {
+        status?: string;
+        attach(name: string, opts: {
+            path: string;
+            contentType: string;
+        }): Promise<void>;
+    };
+}
+/** Effective a11y settings with the schema defaults, so a hand-built config behaves like a parsed one. */
+export declare function a11ySettings(config: A11yScenarioDeps['config']): A11yConfig;
+export declare function auditScenarioEnd(deps: A11yScenarioDeps): Promise<A11yScenarioReport>;
+//# sourceMappingURL=a11y-scenario.d.ts.map

package/dist/quality/a11y-scenario.js

@@ -0,0 +1,63 @@
+import { expect } from '@playwright/test';
+import { attachmentNames, scenarioFiles } from '@sdods/contracts';
+import { IMPACT_ORDER, assertAxeChecked, describeViolations, parseImpactFloor, runAxe, violationsAtOrAbove, wasPageAudited, writeAndAttachJson, } from '../a11y/audit.js';
+import { SdodsError } from '../errors.js';
+/** Effective a11y settings with the schema defaults, so a hand-built config behaves like a parsed one. */
+export function a11ySettings(config) {
+    const a = config.project.a11y ?? {};
+    return { failOn: a.failOn ?? 'serious', include: a.include ?? [], exclude: a.exclude ?? [] };
+}
+export async function auditScenarioEnd(deps) {
+    const { page, scenario, testInfo } = deps;
+    const settings = a11ySettings(deps.config);
+    const floor = parseImpactFloor(settings.failOn);
+    const url = page.url();
+    const base = {
+        kind: 'a11y-scenario',
+        runnerProject: scenario.data.runnerProject,
+        fingerprint: scenario.data.fingerprint,
+        retry: scenario.data.retry,
+        url,
+        failOn: settings.failOn,
+        include: settings.include,
+        exclude: settings.exclude,
+        violations: 0,
+        blocking: 0,
+        blockingRules: [],
+    };
+    const file = scenario.file(scenarioFiles.a11yScenarioJson(scenario.data.runnerProject));
+    const write = (report) => writeAndAttachJson(testInfo, attachmentNames.a11yScenario, file, report).then(() => report);
+    if (testInfo.status && testInfo.status !== 'passed') {
+        return write({
+            ...base,
+            status: 'skipped',
+            reason: `the scenario ${testInfo.status} before the audit, so the page it stopped on proves nothing`,
+        });
+    }
+    if (!url || url === 'about:blank') {
+        throw new SdodsError('RUN_FAILED', 'This @a11y scenario never navigated anywhere, so there is no page to audit.', {
+            hint: 'Navigate to the page under test in the scenario, or drop @a11y from a scenario that has no page.',
+        });
+    }
+    if (wasPageAudited(scenario, url)) {
+        return write({
+            ...base,
+            status: 'covered-by-step',
+            reason: 'an explicit whole-page accessibility step already audited this URL in the scenario',
+        });
+    }
+    const results = await runAxe(page, { include: settings.include, exclude: settings.exclude });
+    const blocking = violationsAtOrAbove(results.violations, floor);
+    const report = await write({
+        ...base,
+        status: 'audited',
+        violations: results.violations.length,
+        blocking: blocking.length,
+        blockingRules: blocking.map((v) => v.id),
+        results,
+    });
+    assertAxeChecked(results, `on ${url}`);
+    expect(blocking.length, `@a11y: ${blocking.length} violation(s) at ${IMPACT_ORDER[floor]} or worse on ${url} (of ${results.violations.length} total; a11y.failOn is "${settings.failOn}"):\n${describeViolations(blocking)}`).toBe(0);
+    return report;
+}
+//# sourceMappingURL=a11y-scenario.js.map

package/dist/quality/gates.d.ts

@@ -0,0 +1,54 @@
+import type { GateResult, GateRow, ProcessGates } from '@sdods/contracts';
+import type { A11yScenarioReport } from './a11y-scenario.js';
+import type { PerfScenarioReport } from './perf-scenario.js';
+export type { GateResult, GateRow };
+/**
+ * Process gates: `gates:` on a process in `sdods.project.yaml`.
+ *
+ * Until this existed the web UI saved `minPassRate`, `maxFlaky`, `a11y` and `perfBudgets`, the
+ * release process declared all four, and nothing anywhere evaluated them. A gate that is read by
+ * nothing is worse than no gate: it is the reason a release goes out believing it was checked.
+ *
+ * Evaluated by `sdods run --process <name>` from the run it just finished:
+ *   · `minPassRate` — (passed + flaky) / (total − skipped), as a percentage, the same arithmetic as
+ *     the run dashboard. A scenario that passed only on retry counts as passed here and as flaky
+ *     below. A run that executed nothing has no pass rate, and fails the gate.
+ *   · `maxFlaky` — scenarios that failed and then passed on a retry.
+ *   · `a11y` — every `@a11y` audit in the run found nothing at or above `a11y.failOn`, AND at least
+ *     one audit ran. Violations already fail their scenarios; what this gate adds is the proof that
+ *     the audits happened at all, because a process declaring `a11y: true` over a selection with no
+ *     `@a11y` scenario would otherwise pass having checked nothing.
+ *   · `perfBudgets` — the same for `@perf`: no breach in any judged scenario, and at least one
+ *     scenario was judged.
+ *
+ * The a11y and perf evidence is read from the scenario reports the tag hooks write into the run
+ * directory, taking the last attempt of each scenario on each runner project.
+ */
+export interface GateTotals {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    flaky: number;
+}
+export interface GateEvidence {
+    a11y: A11yScenarioReport[];
+    perf: PerfScenarioReport[];
+}
+/** True when the process declares at least one gate worth evaluating. */
+export declare function hasGates(gates: Partial<ProcessGates> | undefined): boolean;
+/** Pure: the verdict for one process's gates over a run's totals and evidence. */
+export declare function evaluateGates(input: {
+    process: string;
+    gates: Partial<ProcessGates> | undefined;
+    totals: GateTotals | undefined;
+    evidence: GateEvidence;
+}): GateResult;
+/**
+ * Reads the `@a11y` and `@perf` scenario reports out of a run directory
+ * (`<runDir>/<slug>/<fingerprint>/r<retry>/{a11y,perf}/scenario--<runner project>.json`), keeping
+ * only the highest retry of each scenario on each runner project: an attempt that was retried is not
+ * the scenario's verdict.
+ */
+export declare function collectGateEvidence(runDir: string): GateEvidence;
+//# sourceMappingURL=gates.d.ts.map

package/dist/quality/gates.js

@@ -0,0 +1,144 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** True when the process declares at least one gate worth evaluating. */
+export function hasGates(gates) {
+    return Boolean(gates &&
+        (gates.minPassRate !== undefined ||
+            gates.maxFlaky !== undefined ||
+            gates.a11y === true ||
+            gates.perfBudgets === true));
+}
+/** Pure: the verdict for one process's gates over a run's totals and evidence. */
+export function evaluateGates(input) {
+    const { gates = {}, totals, evidence } = input;
+    const rows = [];
+    if (gates.minPassRate !== undefined) {
+        const executed = totals ? totals.total - totals.skipped : 0;
+        if (!totals || executed <= 0) {
+            rows.push({
+                gate: 'minPassRate',
+                threshold: `≥ ${gates.minPassRate}%`,
+                actual: 'n/a',
+                passed: false,
+                detail: totals
+                    ? 'no scenario executed, so there is no pass rate to meet the gate'
+                    : 'the run produced no results to compute a pass rate from',
+            });
+        }
+        else {
+            const rate = ((totals.passed + totals.flaky) / executed) * 100;
+            rows.push({
+                gate: 'minPassRate',
+                threshold: `≥ ${gates.minPassRate}%`,
+                actual: `${formatPct(rate)}% (${totals.passed + totals.flaky}/${executed})`,
+                passed: rate >= gates.minPassRate,
+            });
+        }
+    }
+    if (gates.maxFlaky !== undefined) {
+        rows.push({
+            gate: 'maxFlaky',
+            threshold: `≤ ${gates.maxFlaky}`,
+            actual: totals ? String(totals.flaky) : 'n/a',
+            passed: Boolean(totals) && (totals?.flaky ?? 0) <= gates.maxFlaky,
+            detail: totals ? undefined : 'the run produced no results to count flaky scenarios from',
+        });
+    }
+    if (gates.a11y) {
+        const audited = evidence.a11y.filter((r) => r.status !== 'skipped');
+        const blocking = audited.reduce((n, r) => n + r.blocking, 0);
+        const failing = audited.filter((r) => r.blocking > 0);
+        rows.push({
+            gate: 'a11y',
+            threshold: 'no blocking violation',
+            actual: `${blocking} blocking in ${audited.length} audit(s)`,
+            passed: audited.length > 0 && blocking === 0,
+            detail: audited.length === 0
+                ? 'no @a11y audit ran in this run, so the gate has nothing to prove'
+                : failing.length
+                    ? failing
+                        .slice(0, 5)
+                        .map((r) => `${r.url} [${r.runnerProject}]: ${r.blockingRules.join(', ')}`)
+                        .join('; ')
+                    : undefined,
+        });
+    }
+    if (gates.perfBudgets) {
+        const judged = evidence.perf.filter((r) => r.status === 'judged' && r.judged > 0);
+        const breaches = judged.flatMap((r) => r.breaches.map((b) => ({ ...b, runnerProject: r.runnerProject })));
+        rows.push({
+            gate: 'perfBudgets',
+            threshold: 'no budget breach',
+            actual: `${breaches.length} breach(es) in ${judged.length} scenario(s)`,
+            passed: judged.length > 0 && breaches.length === 0,
+            detail: judged.length === 0
+                ? 'no @perf scenario was judged against a budget in this run, so the gate has nothing to prove'
+                : breaches.length
+                    ? breaches
+                        .slice(0, 5)
+                        .map((b) => `${b.budget} ${b.measuredMs ?? 'unmeasured'}/${b.limitMs} ms at ${b.where}`)
+                        .join('; ')
+                    : undefined,
+        });
+    }
+    return { process: input.process, passed: rows.every((r) => r.passed), rows };
+}
+function formatPct(n) {
+    return Number.isInteger(n) ? String(n) : n.toFixed(1);
+}
+/**
+ * Reads the `@a11y` and `@perf` scenario reports out of a run directory
+ * (`<runDir>/<slug>/<fingerprint>/r<retry>/{a11y,perf}/scenario--<runner project>.json`), keeping
+ * only the highest retry of each scenario on each runner project: an attempt that was retried is not
+ * the scenario's verdict.
+ */
+export function collectGateEvidence(runDir) {
+    const latest = new Map();
+    const keep = (report) => {
+        const key = `${report.kind}|${report.fingerprint}|${report.runnerProject}`;
+        const prev = latest.get(key);
+        if (prev && prev.retry > report.retry)
+            return;
+        latest.set(key, report.kind === 'a11y-scenario'
+            ? { retry: report.retry, a11y: report }
+            : { retry: report.retry, perf: report });
+    };
+    for (const file of scenarioReportFiles(runDir)) {
+        try {
+            const parsed = JSON.parse(readFileSync(file, 'utf8'));
+            if (parsed.kind === 'a11y-scenario' || parsed.kind === 'perf-scenario')
+                keep(parsed);
+        }
+        catch {
+            /* a half-written report is not evidence */
+        }
+    }
+    const values = [...latest.values()];
+    return {
+        a11y: values.flatMap((v) => (v.a11y ? [v.a11y] : [])),
+        perf: values.flatMap((v) => (v.perf ? [v.perf] : [])),
+    };
+}
+function scenarioReportFiles(runDir) {
+    const out = [];
+    const dirs = (p) => existsSync(p) ? readdirSync(p).filter((n) => statSync(join(p, n)).isDirectory()) : [];
+    for (const slug of dirs(runDir)) {
+        // Fingerprints are 16 hex characters; this keeps the walk out of the report directories.
+        for (const fp of dirs(join(runDir, slug)).filter((n) => /^[0-9a-f]{16}$/.test(n))) {
+            for (const attempt of dirs(join(runDir, slug, fp))) {
+                if (!/^r\d+$/.test(attempt))
+                    continue;
+                for (const kind of ['a11y', 'perf']) {
+                    const dir = join(runDir, slug, fp, attempt, kind);
+                    if (!existsSync(dir))
+                        continue;
+                    for (const name of readdirSync(dir))
+                        if (name.startsWith('scenario--') && name.endsWith('.json'))
+                            out.push(join(dir, name));
+                }
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=gates.js.map

package/dist/quality/hooks.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/quality/hooks.js

@@ -0,0 +1,38 @@
+import { AfterScenario, BeforeScenario } from '../fixtures/test.js';
+import { auditScenarioEnd } from './a11y-scenario.js';
+import { judgeScenarioPerf, watchNavigations } from './perf-scenario.js';
+/**
+ * `@a11y` and `@perf` tag hooks.
+ *
+ * Tag-filtered scenario hooks rather than auto fixtures, for the reason `shots/hooks.ts` gives: a
+ * hook's fixtures are requested only by the scenarios its tag expression matches (playwright-bdd
+ * decides that when it generates the spec), so an `@api @perf` scenario never opens a browser to be
+ * judged. playwright-bdd reads the fixture names from the destructuring below, so each hook lists
+ * its fixtures literally and hands them to a plain function the unit tests call directly.
+ *
+ * Registered after the screenshot hooks and before nothing else: after-hooks run in reverse
+ * registration order, so these run BEFORE `sdods:finalize` and can leave their verdict on the
+ * scenario for it to record. A failure here is otherwise invisible to `meta.json`, because
+ * Playwright only marks the test failed once every after-hook has returned.
+ */
+const PAGE = '(@ui or @hybrid)';
+async function noting(scenario, run) {
+    try {
+        return await run();
+    }
+    catch (e) {
+        scenario.noteFailure(e instanceof Error ? e.message : String(e));
+        throw e;
+    }
+}
+BeforeScenario({ name: 'sdods:perf:watch', tags: `@perf and ${PAGE}` }, async ({ page, scenario }) => {
+    await watchNavigations({ page, scenario });
+});
+// Registered before the a11y hook, so it runs after it: the audit's axe injection is not a navigation.
+AfterScenario({ name: 'sdods:perf', tags: '@perf' }, async ({ config, scenario, apiContext, $testInfo }) => {
+    await noting(scenario, () => judgeScenarioPerf({ config, scenario, apiContext, testInfo: $testInfo }));
+});
+AfterScenario({ name: 'sdods:a11y', tags: `@a11y and ${PAGE}` }, async ({ page, config, scenario, $testInfo }) => {
+    await noting(scenario, () => auditScenarioEnd({ page, config, scenario, testInfo: $testInfo }));
+});
+//# sourceMappingURL=hooks.js.map

package/dist/quality/index.d.ts

@@ -0,0 +1,4 @@
+export { collectGateEvidence, evaluateGates, hasGates, type GateEvidence, type GateResult, type GateRow, type GateTotals, } from './gates.js';
+export type { A11yScenarioReport, A11yScenarioStatus } from './a11y-scenario.js';
+export type { PerfBreach, PerfScenarioReport } from './perf-scenario.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/quality/index.js

@@ -0,0 +1,2 @@
+export { collectGateEvidence, evaluateGates, hasGates, } from './gates.js';
+//# sourceMappingURL=index.js.map