@sdods/core 0.8.0 → 0.10.0

package/dist/shots/narrator.js

@@ -1,7 +1,9 @@
-import { existsSync } from 'node:fs';
+import { copyFileSync, existsSync, writeFileSync } from 'node:fs';
+import { relative } from 'node:path';
 import { expect } from '@playwright/test';
 import { attachmentNames, scenarioFiles, } from '@sdods/contracts';
 import { Logger } from '../logger.js';
+import { baselineKey, parseVisualError, pngSize, visualCheckOptions } from './baselines.js';
 /** Takes the before/after/scenario screenshots dictated by the policy and attaches them with shared names. */
 export class ScreenshotNarrator {
     deps;
@@ -71,17 +73,36 @@ export class ScreenshotNarrator {
     stepShot(stepIndex, phase) {
         return this.capture(this.deps.scenario.file(scenarioFiles.stepShot(stepIndex, phase)), attachmentNames.shotStep(stepIndex, phase));
     }
-    /** Visual baseline check (`@visual`): `expect(page).toHaveScreenshot(name)`. */
-    async visual(name, stepIndex) {
+    /**
+     * Visual baseline check (`@visual`): `expect(page).toHaveScreenshot(name)` with the merged mask
+     * and threshold (see {@link visualCheckOptions}). A failure leaves a {@link VisualFailure} record
+     * and copies of the images in the scenario directory for `sdods baselines` to review and accept.
+     */
+    async visual(name, stepIndex, extraMask = []) {
         const { page, policy, testInfo } = this.deps;
         const fileName = name.endsWith('.png') ? name : `${name}.png`;
-        await expect(page).toHaveScreenshot(fileName, {
-            fullPage: policy.fullPage,
-            animations: 'disabled',
-            caret: 'hide',
-            mask: policy.mask.map((sel) => page.locator(sel)),
-            maxDiffPixelRatio: 0.01,
-        });
+        const opts = visualCheckOptions(fileName, policy, extraMask);
+        const hadBaseline = existsSync(testInfo.snapshotPath(fileName));
+        try {
+            await expect(page).toHaveScreenshot(fileName, {
+                fullPage: policy.fullPage,
+                animations: 'disabled',
+                caret: 'hide',
+                mask: opts.mask.map((sel) => page.locator(sel)),
+                maxDiffPixelRatio: opts.maxDiffPixelRatio,
+            });
+        }
+        catch (e) {
+            this.recordVisualFailure(fileName, stepIndex, opts.maxDiffPixelRatio, e);
+            throw e;
+        }
+        // With Playwright's default `updateSnapshots: 'missing'` a missing baseline does not throw: it
+        // writes the actual image as the baseline and fails the test afterwards (a soft error). That is
+        // the first run on a new platform, and exactly the check `sdods baselines` must offer.
+        if (!hadBaseline && testInfo.config.updateSnapshots === 'missing')
+            this.recordVisualFailure(fileName, stepIndex, opts.maxDiffPixelRatio, new Error("A snapshot doesn't exist, writing actual."));
+        else
+            this.recordVisualPass(fileName);
         const snapshot = testInfo.snapshotPath(fileName);
         if (existsSync(snapshot))
             await testInfo.attach(attachmentNames.visual(stepIndex, name), {
@@ -89,6 +110,81 @@ export class ScreenshotNarrator {
                 contentType: 'image/png',
             });
     }
+    visualIdentity(fileName) {
+        const { scenario, testInfo } = this.deps;
+        return {
+            name: baselineKey(fileName),
+            runnerProject: testInfo.project.name,
+            fingerprint: scenario.fingerprint,
+            retry: testInfo.retry,
+        };
+    }
+    recordVisualPass(fileName) {
+        const id = this.visualIdentity(fileName);
+        try {
+            writeFileSync(this.deps.scenario.file(scenarioFiles.visualPassed(id.runnerProject, id.name)), JSON.stringify({ ...id, recordedAt: new Date().toISOString() }));
+        }
+        catch (err) {
+            this.log.debug(`visual pass marker skipped: ${err.message}`);
+        }
+    }
+    /** Never throws: the check's own error is what the scenario reports. */
+    recordVisualFailure(fileName, stepIndex, maxDiffPixelRatio, error) {
+        const { scenario, testInfo } = this.deps;
+        try {
+            const id = this.visualIdentity(fileName);
+            const base = fileName.replace(/\.png$/i, '');
+            // Playwright attaches `<name>-actual.png` etc. and writes them to the test's output dir.
+            const source = (phase) => {
+                const att = testInfo.attachments.find((a) => a.name === `${base}-${phase}.png`)?.path;
+                const p = att ?? testInfo.outputPath(`${base}-${phase}.png`);
+                return existsSync(p) ? p : undefined;
+            };
+            const parsed = parseVisualError(error?.message ?? String(error));
+            const copies = {};
+            for (const phase of ['actual', 'expected', 'diff']) {
+                // A missing baseline's "expected" attachment is the actual image Playwright just wrote.
+                if (phase !== 'actual' && parsed.reason === 'missing')
+                    continue;
+                const src = source(phase);
+                if (!src)
+                    continue;
+                const dest = scenario.file(scenarioFiles.visualImage(id.runnerProject, id.name, phase));
+                copyFileSync(src, dest);
+                copies[phase] = relative(scenario.runDir, dest).split('\\').join('/');
+            }
+            // No actual image means the page could not be captured at all: nothing to accept.
+            if (!copies.actual)
+                return;
+            const size = pngSize(scenario.file(scenarioFiles.visualImage(id.runnerProject, id.name, 'actual')));
+            const record = {
+                ...id,
+                snapshot: fileName,
+                project: scenario.data.project,
+                platform: process.platform,
+                scenarioName: scenario.data.scenarioName,
+                featureUri: scenario.data.featureUri,
+                stepIndex,
+                reason: parsed.reason,
+                baseline: relative(scenario.projectRoot, testInfo.snapshotPath(fileName))
+                    .split('\\')
+                    .join('/'),
+                actual: copies.actual,
+                expected: copies.expected,
+                diff: copies.diff,
+                diffPixels: parsed.diffPixels,
+                diffRatio: parsed.diffPixels !== undefined && size
+                    ? parsed.diffPixels / (size.width * size.height)
+                    : undefined,
+                maxDiffPixelRatio,
+                recordedAt: new Date().toISOString(),
+            };
+            writeFileSync(scenario.file(scenarioFiles.visualFailure(id.runnerProject, id.name)), JSON.stringify(record, null, 2));
+        }
+        catch (err) {
+            this.log.debug(`visual failure record skipped: ${err.message}`);
+        }
+    }
 }
 function safeUrl(page) {
     try {

package/dist/shots/policy.d.ts

@@ -1,9 +1,13 @@
-import type { ShotPolicy } from '@sdods/contracts';
+import type { BaselineConfig, ShotPolicy } from '@sdods/contracts';
 import type { ResolvedConfig } from '../config/resolve.js';
 export interface ShotPolicyResolved {
     mode: ShotPolicy;
     fullPage: boolean;
     mask: string[];
+    /** default share of pixels a visual baseline check may differ by */
+    maxDiffPixelRatio: number;
+    /** per-baseline mask and threshold, keyed by name without `.png` */
+    baselines: Record<string, BaselineConfig>;
     viewport: {
         width: number;
         height: number;

package/dist/shots/policy.js

@@ -24,6 +24,8 @@ export function resolvePolicy(tags, config) {
         mode,
         fullPage: s.fullPage,
         mask: s.mask,
+        maxDiffPixelRatio: s.maxDiffPixelRatio ?? 0.01,
+        baselines: s.baselines ?? {},
         viewport: s.viewport,
         scenario: mode === 'scenario' || mode === 'step' || mode === 'visual',
         step: mode === 'step' || mode === 'visual',

package/dist/steps/a11y.steps.d.ts

@@ -1,57 +1,24 @@
 import './params.js';
+import { type A11yResults } from '../a11y/audit.js';
 /**
- * Structural subset of axe-core's result types. Declared locally rather than imported from
- * `axe-core`: that package is a transitive dependency of `@axe-core/playwright`, not a direct
- * dependency of this one, so importing its types would couple the whole step library's
- * compilation to a package a consumer may not have installed.
- */
-export interface A11yViolationNode {
-    target: unknown[];
-    html?: string;
-    failureSummary?: string;
-}
-export interface A11yViolation {
-    id: string;
-    impact?: string | null;
-    help?: string;
-    helpUrl?: string;
-    nodes: A11yViolationNode[];
-}
-export interface A11yResults {
-    violations: A11yViolation[];
-    passes: {
-        id: string;
-    }[];
-    incomplete: {
-        id: string;
-    }[];
-    inapplicable: {
-        id: string;
-    }[];
-    url?: string;
-}
-/** axe impact levels, weakest first. `impact: null` is treated as `minor`. */
-export declare const IMPACT_ORDER: readonly ["minor", "moderate", "serious", "critical"];
-/**
- * WCAG 2.0/2.1/2.2 level A and AA, and deliberately nothing else. axe's `best-practice` tag set
- * changes between axe releases, so including it would let the same unchanged page pass one week
- * and fail the next — a step whose verdict moves on its own teaches teams to ignore it.
- */
-export declare const WCAG_AA_TAGS: string[];
-/** Rank of an axe impact level; an absent impact ranks as `minor` rather than vanishing. */
-export declare function impactRank(impact: string | null | undefined): number;
-/** Rejects an impact level the feature file invented, instead of silently matching nothing. */
-export declare function parseImpactFloor(level: string): number;
-export declare function violationsAtOrAbove(violations: A11yViolation[], floor: number): A11yViolation[];
-/** Human-readable violation list: rule, impact, help text and the first few offending nodes. */
-export declare function describeViolations(violations: A11yViolation[]): string;
-/**
- * PROVES the audit actually executed. axe reporting zero violations is indistinguishable from
- * axe never having run: a nonce'd CSP that blocks the injected source, an `about:blank` page, or
- * an `include` that matched nothing all produce an empty, green-looking result. If no rule landed
- * in passes, violations or incomplete, then nothing was examined and the verdict means nothing.
+ * Accessibility steps: an axe-core audit plus the structural checks a rule engine cannot see.
+ *
+ * DESIGN — the browser gathers, node judges. Every DOM probe below returns plain serialisable
+ * records and nothing else; the pass/fail decision lives in an exported pure function. That split
+ * exists so the one rule that matters here is testable without a browser: a step that quantifies
+ * over a set MUST fail when the set is empty. "Every image has an alt" over a page with no images
+ * and "no violations" inside a region that does not exist are not passes, they are silence, and
+ * silence is what makes an accessibility suite worthless. `assertRegion` and `assertGathered` are
+ * the guards, and they throw rather than assert so the message can say what to do instead.
+ *
+ * WHY NO `heal.*` HERE. The rest of the UI library heals because it resolves ONE interactive
+ * element by role/name/text, and a near-miss substitute is still the control the author meant.
+ * These steps quantify over a POPULATION inside a region: healing a region selector to a
+ * different element would silently re-point the audit at a different set of nodes and report a
+ * green result for a surface nobody asked about. A missing region is a defect in the step, so it
+ * is reported as one.
  */
-export declare function assertAxeChecked(results: A11yResults, where: string): void;
+export { IMPACT_ORDER, WCAG_AA_TAGS, assertAxeChecked, describeViolations, impactRank, parseImpactFloor, violationsAtOrAbove, type A11yResults, type A11yViolation, type A11yViolationNode, } from '../a11y/audit.js';
 export type RuleBucket = 'violations' | 'passes' | 'incomplete' | 'inapplicable' | 'none';
 /** Which of axe's four result buckets a rule landed in. `none` means the rule never ran. */
 export declare function ruleBucket(results: A11yResults, ruleId: string): RuleBucket;

package/dist/steps/a11y.steps.js

@@ -4,6 +4,7 @@ import { attachmentNames, scenarioFiles } from '@sdods/contracts';
 import './params.js';
 import { Then } from '../fixtures/test.js';
 import { renderStrict } from '../api/template.js';
+import { IMPACT_ORDER, assertAxeChecked, describeViolations, markPageAudited, parseImpactFloor, runAxe, violationsAtOrAbove, } from '../a11y/audit.js';
 import { SdodsError } from '../errors.js';
 import { Logger } from '../logger.js';
 /**
@@ -24,63 +25,11 @@ import { Logger } from '../logger.js';
  * green result for a surface nobody asked about. A missing region is a defect in the step, so it
  * is reported as one.
  */
+// The audit and its judges moved to `../a11y/audit.ts` so the `@a11y` tag hook can share them
+// without importing (and so re-registering) this step file. Re-exported for existing importers.
+export { IMPACT_ORDER, WCAG_AA_TAGS, assertAxeChecked, describeViolations, impactRank, parseImpactFloor, violationsAtOrAbove, } from '../a11y/audit.js';
 const log = new Logger('a11y');
 const scopesOf = (apiContext, env) => [apiContext.vars.toObject(), env.vars];
-/** axe impact levels, weakest first. `impact: null` is treated as `minor`. */
-export const IMPACT_ORDER = ['minor', 'moderate', 'serious', 'critical'];
-/**
- * WCAG 2.0/2.1/2.2 level A and AA, and deliberately nothing else. axe's `best-practice` tag set
- * changes between axe releases, so including it would let the same unchanged page pass one week
- * and fail the next — a step whose verdict moves on its own teaches teams to ignore it.
- */
-export const WCAG_AA_TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'];
-/* ── pure judges (exported so the vacuity guards are unit-testable) ─────── */
-/** Rank of an axe impact level; an absent impact ranks as `minor` rather than vanishing. */
-export function impactRank(impact) {
-    const i = IMPACT_ORDER.indexOf((impact ?? 'minor'));
-    return i === -1 ? 0 : i;
-}
-/** Rejects an impact level the feature file invented, instead of silently matching nothing. */
-export function parseImpactFloor(level) {
-    const i = IMPACT_ORDER.indexOf(level);
-    if (i === -1)
-        throw new SdodsError('CONFIG_INVALID', `"${level}" is not an axe impact level.`, {
-            hint: `Use one of: ${IMPACT_ORDER.join(', ')}.`,
-        });
-    return i;
-}
-export function violationsAtOrAbove(violations, floor) {
-    return violations.filter((v) => impactRank(v.impact) >= floor);
-}
-/** Human-readable violation list: rule, impact, help text and the first few offending nodes. */
-export function describeViolations(violations) {
-    return violations
-        .map((v) => {
-        const nodes = v.nodes ?? [];
-        const shown = nodes
-            .slice(0, 3)
-            .map((n) => (Array.isArray(n.target) ? n.target.join(' ') : String(n.target)))
-            .join(' | ');
-        const more = nodes.length > 3 ? ` (+${nodes.length - 3} more node(s))` : '';
-        return `${v.id} [${v.impact ?? 'minor'}] ${v.help ?? ''} → ${nodes.length} node(s): ${shown}${more}`;
-    })
-        .join('\n');
-}
-/**
- * PROVES the audit actually executed. axe reporting zero violations is indistinguishable from
- * axe never having run: a nonce'd CSP that blocks the injected source, an `about:blank` page, or
- * an `include` that matched nothing all produce an empty, green-looking result. If no rule landed
- * in passes, violations or incomplete, then nothing was examined and the verdict means nothing.
- */
-export function assertAxeChecked(results, where) {
-    const checked = (results.passes?.length ?? 0) +
-        (results.violations?.length ?? 0) +
-        (results.incomplete?.length ?? 0);
-    if (checked === 0)
-        throw new SdodsError('RUN_FAILED', `axe examined nothing ${where}; the audit proves nothing.`, {
-            hint: 'The page may be blank, the scoped selector may match an empty element, or a Content-Security-Policy may have blocked axe from running. Open the attached sdods/a11y JSON to see what axe reported.',
-        });
-}
 /** Which of axe's four result buckets a rule landed in. `none` means the rule never ran. */
 export function ruleBucket(results, ruleId) {
     if (results.violations?.some((r) => r.id === ruleId))
@@ -354,58 +303,6 @@ export const gatherFocusIndicators = (sel) => {
     }
     return { regionFound: true, items: out };
 };
-/**
- * Runs axe through `@axe-core/playwright`, which injects the source with `page.evaluate` rather
- * than `addScriptTag`. That matters: an app serving a nonce'd CSP blocks an injected `<script>`
- * silently, and the audit would report zero violations because it never ran.
- *
- * The import is lazy so a project that never writes an a11y step does not need the dependency —
- * a top-level import would fail the load of this whole step file and take the rest of the core
- * library down with it.
- */
-async function runAxe(page, opts) {
-    let AxeBuilder;
-    try {
-        const mod = await import('@axe-core/playwright');
-        // Named export first: the package exports the class as both `AxeBuilder` and `default`, and a
-        // CJS interop path can hand `default` back as the namespace object rather than the class.
-        AxeBuilder = (mod.AxeBuilder ?? mod.default);
-    }
-    catch (cause) {
-        throw new SdodsError('NOT_SUPPORTED', 'Accessibility steps need @axe-core/playwright.', {
-            hint: 'Install it in the project that runs these steps: `npm i -D @axe-core/playwright`.',
-            cause,
-        });
-    }
-    const builder = new AxeBuilder({ page });
-    if (opts.include)
-        builder.include(opts.include);
-    // withTags and withRules are mutually exclusive in axe-core; never set both.
-    if (opts.rules)
-        builder.withRules(opts.rules);
-    else
-        builder.withTags(opts.tags ?? WCAG_AA_TAGS);
-    try {
-        return await builder.analyze();
-    }
-    catch (cause) {
-        // axe raises "unknown rule `x` in options.runOnly" for a rule id that does not exist, and
-        // "No elements found for include in page Context" for a selector that matched nothing. Both
-        // are defects in the step rather than in the page under test, so both are re-raised as such.
-        const message = cause instanceof Error ? cause.message : String(cause);
-        if (/unknown rule/i.test(message))
-            throw new SdodsError('CONFIG_INVALID', `axe rejected the rule id: ${message}`, {
-                hint: 'Check the rule id against https://dequeuniversity.com/rules/axe.',
-                cause,
-            });
-        if (/no elements found for include/i.test(message))
-            throw new SdodsError('RUN_FAILED', `axe found nothing to scan: ${message}`, {
-                hint: `The selector "${opts.include ?? ''}" matched no element by the time axe ran. Wait for the region to render before this step.`,
-                cause,
-            });
-        throw new SdodsError('RUN_FAILED', `axe failed to analyse the page: ${message}`, { cause });
-    }
-}
 /**
  * Writes the full axe result next to the scenario and attaches it under `sdods/a11y/<step>`.
  * Always attached, pass or fail: on a failure it is what makes the verdict diagnosable, and on a
@@ -439,6 +336,7 @@ async function requireRegion(page, selector) {
  */
 Then('the page should have no accessibility violations', async ({ page, scenario, $bddContext, $testInfo }) => {
     const results = await runAxe(page, {});
+    markPageAudited(scenario, page.url());
     attachA11y({ scenario, testInfo: $testInfo, stepIndex: $bddContext.stepIndex }, results);
     assertAxeChecked(results, `on ${page.url()}`);
     expect(results.violations.length, `${results.violations.length} WCAG A/AA violation(s) on ${page.url()}:\n${describeViolations(results.violations)}`).toBe(0);
@@ -464,6 +362,7 @@ Then('the page should have no accessibility violations within {string}', async (
 Then('the page should have no accessibility violations of impact {string} or worse', async ({ page, scenario, apiContext, env, $bddContext, $testInfo }, level) => {
     const floor = parseImpactFloor(renderStrict(level, ...scopesOf(apiContext, env)));
     const results = await runAxe(page, {});
+    markPageAudited(scenario, page.url());
     attachA11y({ scenario, testInfo: $testInfo, stepIndex: $bddContext.stepIndex }, results);
     assertAxeChecked(results, `on ${page.url()}`);
     const blocking = violationsAtOrAbove(results.violations, floor);

package/dist/steps/data.steps.js

@@ -3,6 +3,7 @@ import './params.js';
 import { Given, When } from '../fixtures/test.js';
 import { tokenFileFor } from '../auth/capture.js';
 import { renderStrict } from '../api/template.js';
+import { scenarioLeaseClock } from '../data/user-pool.js';
 import { SdodsError } from '../errors.js';
 import { Logger } from '../logger.js';
 const log = new Logger('data');
@@ -20,8 +21,8 @@ Given('I generate a {string} from the factory as {string}', async ({ data, apiCo
     apiContext.vars.set(as, await data.factory(factory));
 });
 /* ── user pool ────────────────────────────────────────────────────────── */
-Given('I use a leased user with role {string}', async ({ userPool, authCache, auth, sdods, apiContext, page, context, browser, $testInfo }, role) => {
-    const user = await userPool.lease(role, $testInfo.parallelIndex);
+Given('I use a leased user with role {string}', async ({ userPool, authCache, auth, sdods, apiContext, page, context, browser, config, $testInfo }, role) => {
+    const user = await leaseInScenario(userPool, config, role, $testInfo);
     apiContext.vars.setAll({
         username: user.username,
         password: user.password,
@@ -33,12 +34,12 @@ Given('I use a leased user with role {string}', async ({ userPool, authCache, au
     if (sdods.layer !== 'api')
         await authCache.apply({ context, page, user, auth, browser });
 });
-Given('I use the user {string} from the pool', async ({ userPool, apiContext, $testInfo }, username) => {
+Given('I use the user {string} from the pool', async ({ userPool, apiContext, config, $testInfo }, username) => {
     const status = await userPool.status();
     const entry = status.find((u) => u.username === username);
     if (!entry)
         throw new SdodsError('DATASET_ROW_NOT_FOUND', `No pool user named "${username}".`);
-    const user = await userPool.lease(entry.role, $testInfo.parallelIndex);
+    const user = await leaseInScenario(userPool, config, entry.role, $testInfo);
     apiContext.vars.setAll({
         username: user.username,
         password: user.password,
@@ -84,7 +85,7 @@ Given('I use the user {string} from the pool', async ({ userPool, apiContext, $t
  * Either way the attached credential is logged at info.
  */
 Given('I use a leased user with role {string} for API calls', async ({ userPool, apiContext, auth, config, $testInfo }, role) => {
-    const user = await userPool.lease(role, $testInfo.parallelIndex);
+    const user = await leaseInScenario(userPool, config, role, $testInfo);
     apiContext.vars.setAll({
         username: user.username,
         password: user.password,
@@ -126,6 +127,17 @@ Given("I authenticate the API with the leased user's token", async ({ apiContext
 });
 /** The user the scenario leased, so the explicit token step authenticates as that same account. */
 const LEASED = new WeakMap();
+/**
+ * Lease for this scenario. With `leaseScope: scenario` the wait for a free account is added to the
+ * scenario's timeout, and `$sdodsScenarioLeases` releases the account when the scenario ends.
+ */
+async function leaseInScenario(userPool, config, role, testInfo) {
+    // `data` is always present on a resolved config; unit tests hand steps a partial one.
+    const clock = scenarioLeaseClock(config.project.data?.userPool, testInfo);
+    const user = await userPool.lease(role, testInfo.parallelIndex);
+    clock.settle();
+    return user;
+}
 function apiTokenMode(config, auth) {
     return config.project.auth?.apiToken ?? (auth?.strategy === 'custom' ? 'explicit' : 'implicit');
 }

package/dist/steps/hooks.steps.d.ts

@@ -1,2 +1,3 @@
 import '../shots/hooks.js';
+import '../quality/hooks.js';
 //# sourceMappingURL=hooks.steps.d.ts.map

package/dist/steps/hooks.steps.js

@@ -1,5 +1,7 @@
-// Registers the screenshot-narrative, finalize, browser-skip and HAR hooks when bddgen loads the core step glob.
+// Registers the screenshot-narrative, finalize, browser-skip, HAR, @a11y and @perf hooks when bddgen loads the core step glob.
 import '../shots/hooks.js';
+// After the screenshot hooks: after-hooks run in reverse order, so these run before sdods:finalize.
+import '../quality/hooks.js';
 import { registerHarHooks } from '../har/hooks.js';
 import { Before } from '../fixtures/test.js';
 registerHarHooks({ Before });

package/dist/steps/index.d.ts

@@ -20,5 +20,6 @@ import './perf.steps.js';
 import './email.steps.js';
 import './canvas.steps.js';
 import '../shots/hooks.js';
+import '../quality/hooks.js';
 export { coreStepsGlob, coreStepsPatterns, coreStepNames, coreStepsDir } from './glob.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/steps/index.js

@@ -20,5 +20,6 @@ import './perf.steps.js';
 import './email.steps.js';
 import './canvas.steps.js';
 import '../shots/hooks.js';
+import '../quality/hooks.js';
 export { coreStepsGlob, coreStepsPatterns, coreStepNames, coreStepsDir } from './glob.js';
 //# sourceMappingURL=index.js.map

package/dist/steps/perf.steps.d.ts

@@ -1,136 +1,11 @@
 import './params.js';
 import type { Page, TestInfo } from '@playwright/test';
-import type { EnvConfig, PerformanceMetrics } from '@sdods/contracts';
+import type { EnvConfig } from '@sdods/contracts';
 import type { ApiClient, HttpMethod } from '../api/client.js';
 import type { ApiContext } from '../fixtures/api-context.js';
 import type { ScenarioMeta } from '../fixtures/scenario.js';
-/**
- * Performance budgets.
- *
- * `PerfBudgetsSchema` (pageLoadMs / lcpMs / fcpMs / ttfbMs / apiP95Ms), the `perf.budgets` block in
- * the project and env yaml, the `perfBudgets: true` release gate and `attachmentNames.perf` all
- * existed before this file; nothing read any of them. These steps close that loop.
- *
- * Two rules run through every step here, both learned from hand-written project steps that got
- * them wrong:
- *
- *  1. A BUDGET IS READ FROM CONFIG, NEVER FROM THE FEATURE FILE. A number typed into a `.feature`
- *     is a number that drifts from the environment it runs on — staging and a laptop do not share
- *     a page-load budget. `Then the response time should be under {int} ms` (api.steps.ts) is the
- *     literal-threshold form and stays exactly as it is; the budget-driven forms below are new
- *     patterns, not a widening of it. A local literal is still reachable where a scenario genuinely
- *     needs one — `should be under {int} ms` — so the escape hatch is visible in the step text.
- *  2. AN UNMEASURED VITAL FAILS. LCP does not fire on a page with no contentful paint, and WebKit
- *     does not implement it at all; paint timings and the navigation entry can be missing too.
- *     Recording those as `0` makes every budget assertion pass — a whole perf module
- *     goes green while measuring nothing. So a vital that did not fire is recorded as `null`
- *     together with the reason, and asserting on it FAILS naming that reason. A real navigation
- *     cannot produce a genuine 0 ms vital (they are all offsets from navigation start), so treating
- *     "absent or 0" as "not measured" loses no honest signal.
- *
- * A budget that is not configured is likewise a hard `CONFIG_INVALID` naming the missing key, not
- * a skip: silently skipping is the same vacuous green in a different costume.
- *
- * The two comparison operators are deliberately different and deliberately visible in the step
- * text: `under {int} ms` is strict `<` (matching `the response time should be under {int} ms` in
- * api.steps.ts), `within its configured budget` is `<=` — a budget is a ceiling you may sit on.
- */
-/** The page vitals SDODS records. Each name is also its key in `perf.budgets`. */
-export declare const VITAL_KEYS: readonly ["pageLoadMs", "lcpMs", "fcpMs", "ttfbMs"];
-export type VitalKey = (typeof VITAL_KEYS)[number];
-/** The `perf.budgets` key a sampled API latency distribution is judged against. */
-export declare const API_P95_BUDGET_KEY = "apiP95Ms";
-type BudgetLayer = {
-    budgets?: Record<string, number | undefined>;
-} | undefined;
-/** The slice of a resolved config these steps read. Nothing here writes config. */
-export interface BudgetConfig {
-    project: {
-        perf?: BudgetLayer;
-    };
-    env: {
-        name?: string;
-        perf?: BudgetLayer;
-    };
-}
-/**
- * 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 declare function resolvedBudgets(config: BudgetConfig): Record<string, number>;
-/**
- * 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 declare function requireBudget(config: BudgetConfig, key: string): number;
-/** One `When I record the page vitals`. `null` in `vitals` means NOT MEASURED, never "0 ms". */
-export interface VitalsRecording {
-    url: string;
-    vitals: Record<VitalKey, number | null>;
-    /** Why a vital is null, keyed by vital. Surfaced verbatim in the failure message. */
-    unmeasured: Partial<Record<VitalKey, string>>;
-    /** The contract shape written to `sdods/perf/<step>` and ingested into `steps.perf_json`. */
-    metrics: PerformanceMetrics;
-}
-export interface LatencySample {
-    status: number;
-    ms: number;
-}
-export interface LatencySampleSet {
-    method: string;
-    path: string;
-    samples: LatencySample[];
-    p95Ms: number;
-}
-interface PerfStore {
-    recordings: VitalsRecording[];
-    sampleSets: LatencySampleSet[];
-}
-export declare function perfStore(key: object): PerfStore;
-/**
- * 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 declare function p95Of(msValues: readonly number[]): number;
-/** What the page hands back. Every timing is `number | null`; null always means "did not fire". */
-export interface RawVitals {
-    hasNavigationEntry: boolean;
-    navigationStartEpochMs: number | null;
-    pageLoadMs: number | null;
-    ttfbMs: number | null;
-    fcpMs: number | null;
-    lcpMs: number | null;
-    domContentLoadedMs: number | null;
-    totalResources: number;
-    totalResourceSizeKB: number;
-    lcpSupported: boolean;
-    fcpSupported: boolean;
-}
-/**
- * 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 declare function collectRawVitals(settleMs: number): Promise<RawVitals>;
-/**
- * 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 declare function toRecording(raw: RawVitals, url: string, browserName?: string): VitalsRecording;
+import { type BudgetConfig } from '../perf/vitals.js';
+export { API_P95_BUDGET_KEY, VITAL_KEYS, collectRawVitals, p95Of, perfStore, requireBudget, resolvedBudgets, toRecording, type BudgetConfig, type LatencySample, type LatencySampleSet, type RawVitals, type VitalKey, type VitalsRecording, } from '../perf/vitals.js';
 interface VitalsFixtures {
     page: Page;
     config: BudgetConfig;
@@ -244,5 +119,4 @@ export declare const assertP95NoWorseThanPrevious: ({ scenario }: {
 export declare const assertEverySampleStatus: ({ scenario }: {
     scenario: ScenarioMeta;
 }, status: number) => Promise<void>;
-export {};
 //# sourceMappingURL=perf.steps.d.ts.map