@setsquare/review-sdk 0.0.1

package/dist/reporter.js

@@ -0,0 +1,709 @@
+import { existsSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { SCAN_RECORD_ATTACHMENT, } from './contract.js';
+import { infrastructureProjects } from './dedupe.js';
+import { detectOrigin } from './ci.js';
+import { buildEnvelope } from './envelope.js';
+import { mergeGroup, mintPartId, prepareOutcomesForPart, readGroupContext, serialisableInference, writeBegunMarker, writePart, PART_VERSION, } from './group.js';
+import { resolveOptions, summaryMarkdownPath } from './options.js';
+import { renderHtmlReport } from './html-report.js';
+import { writeHtmlReport, writeRun, writeScreensReport, writeSummaryMarkdown } from './output.js';
+import { renderScreensPage, screenRows } from './screens.js';
+import { collectShots, reachableShots } from './shots.js';
+import { render } from './summary.js';
+import { failureFacts, localFacts, slowestSteps } from './suite.js';
+import { axeVersion, sdkVersion } from './versions.js';
+import { criterionRuleMap } from './wcag-map.js';
+/**
+ * The interpretation half of the SDK, and the only thing that exists once per
+ * run.
+ *
+ * Everything that is a policy lives here — envelope assembly, output, and (as
+ * later stages land) dedupe, precedence, surface normalisation and persona/theme
+ * resolution. The fixture observes in N workers and decides nothing; this decides
+ * everything and observes nothing. Splitting it any other way means two places
+ * implementing one policy, and they drift.
+ *
+ * Nothing in this file makes a network call, and nothing in this file can. That
+ * is not a configuration — there is no client, no URL, and no code path that
+ * would use one. "Zero network calls with no token" is asserted in the test suite
+ * against the real Node http stack, because a promise of restraint is not a
+ * property.
+ */
+export default class SetsquareReporter {
+    options;
+    outcomes = [];
+    warnings = [];
+    startedAt = 0;
+    baseDir = process.cwd();
+    infrastructure = new Set();
+    reportPath;
+    plannedTests;
+    /** Set only when the orchestrator declared a run group via SETSQUARE_RUN_ID. */
+    group;
+    groupDir = '';
+    partId = '';
+    startedAtIso = '';
+    /** The begun-marker write, started in onBegin and settled before the merge. */
+    begunWrite;
+    /** Image attachments Playwright held in memory, which nothing can link to. */
+    inMemoryShots = 0;
+    unmeasuredAxes = [];
+    projectNames = [];
+    configuredWorkers;
+    configFile;
+    constructor(options = {}) {
+        this.options = resolveOptions(options);
+    }
+    /** Playwright reads this to decide whether stdout should be captured. */
+    printsToStdio() {
+        return true;
+    }
+    /**
+     * `playwright test --list` enumerates tests and runs none of them.
+     *
+     * Playwright still calls `onBegin` and `onEnd` for a listing, and the reporter
+     * used to treat that as a run: it wrote a `run.json` with zero results, printed a
+     * summary, and — because `pruneRuns` replaces older run directories, by the "no
+     * local history" design — **DELETED the previous real run's evidence.** Measured:
+     * a run of 14 scans, then one `--list`, and the 14-scan directory was gone,
+     * replaced by an empty one. `setsquare report` then pointed at an empty report.
+     *
+     * In a run group it was worse than data loss: the listing wrote a begun marker
+     * and never completed, so the group's census counted a part that never existed
+     * and the merged coverage read `partial` forever.
+     *
+     * Detected from argv rather than from "no tests ended", because a run that was
+     * interrupted before its first test looks identical from the Reporter API — and
+     * that IS a real run whose emptiness is worth recording. What the user typed is
+     * the only signal that separates the two.
+     */
+    listOnly = process.argv.includes('--list');
+    onBegin(config, suite) {
+        // Nothing about a listing is evidence, including a run-group begun marker.
+        if (this.listOnly)
+            return;
+        this.startedAt = Date.now();
+        /*
+         * How many tests this run INTENDED to execute, taken from Playwright's own
+         * suite tree because it is the only place the answer exists.
+         *
+         * Counting results cannot see a test that never ran, and on Eos's e2e lane a
+         * failing setup project took 82 of 112 tests down with it. Without this the
+         * summary reported ten scanned surfaces with nothing to say that it was a
+         * quarter of a suite — evidence from a partial run looking exactly like
+         * evidence from a whole one.
+         *
+         * Guarded rather than trusted: `suite` is a Playwright internal shape we only
+         * read, and a future version that changes it must degrade to "we do not know"
+         * rather than to a wrong number or a crashed reporter.
+         */
+        try {
+            this.plannedTests = suite?.allTests?.().length;
+        }
+        catch {
+            this.plannedTests = undefined;
+        }
+        // `configFile`, NOT `rootDir`. Playwright derives `rootDir` from `testDir`,
+        // so a config with `testDir: './specs'` reports `rootDir` as the specs
+        // directory — and output landed in `fixtures/specs/.setsquare`, buried inside the
+        // customer's test tree. The config file's own directory is what a customer
+        // means by "next to my config", and it is what `setsquare init` will have written
+        // a `.gitignore` line for.
+        this.baseDir = config.configFile
+            ? dirname(config.configFile)
+            : (config.rootDir ?? process.cwd());
+        /*
+         * Which projects exist to prepare the suite rather than to test it, read from
+         * the customer's OWN dependency graph rather than from a config list they
+         * would have to remember to write. On the reference implementation this
+         * identifies preflight, setup, auth and warmup with no configuration at all.
+         */
+        this.infrastructure = infrastructureProjects(config.projects);
+        this.reportPath = htmlReportPath(config, this.baseDir);
+        /*
+         * The run-group contract, read from the environment because the group id
+         * must change per suite execution while the config file does not — and
+         * because Playwright constructs reporters from JSON-safe config entries,
+         * so options could never carry it anyway. No SETSQUARE_RUN_ID, no group: the
+         * solo path below is byte-identical to what it always was.
+         */
+        this.unmeasuredAxes = unmeasuredAxes(config.projects);
+        this.projectNames = config.projects.map((project) => project.name).filter(Boolean);
+        // The PARALLELISM, which is what decides whether per-worker spread is an
+        // imbalance or just the shape of the projects.
+        if (typeof config.workers === 'number' && config.workers > 0) {
+            this.configuredWorkers = config.workers;
+        }
+        /*
+         * The config's own path, kept so a repro command can name the right `-c`.
+         * Absent for an inline config, where the honest output omits the flag rather
+         * than inventing a path.
+         */
+        if (config.configFile) {
+            // Relative to the config's own directory, which is `baseDir` and therefore
+            // the base every other path in `meta.json` is relative to. An absolute path
+            // would leak the machine's directory layout into a file people paste into
+            // issues, and would be wrong on anybody else's checkout.
+            this.configFile = relative(this.baseDir, config.configFile) || basename(config.configFile);
+        }
+        this.group = readGroupContext(process.env);
+        if (this.group) {
+            this.startedAtIso = new Date(this.startedAt).toISOString();
+            this.partId = mintPartId(this.startedAtIso);
+            this.groupDir = join(resolve(this.baseDir, this.options.outputDir), 'runs', this.group.dirName);
+            // Announce the invocation NOW, so a crash between here and onEnd leaves a
+            // begun marker with no part — which is how the merge knows evidence is
+            // absent rather than complete. onBegin cannot await; onEnd settles this.
+            const marker = {
+                partId: this.partId,
+                ...(this.group.lane ? { lane: this.group.lane } : {}),
+                startedAt: this.startedAtIso,
+                pid: process.pid,
+            };
+            this.begunWrite = writeBegunMarker(this.groupDir, marker).catch((error) => {
+                this.warnings.push(`The run-group begun marker could not be written: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }
+    }
+    onTestEnd(test, result) {
+        const project = test.parent.project()?.name;
+        /*
+         * The screenshots Playwright already wrote, recorded as paths.
+         *
+         * This is the only place the visual report gets its material, and it is a
+         * read: no capture happens here, and no image is written anywhere by this
+         * package (asserted in `boundaries.test.ts`). A test whose config takes no
+         * screenshots yields an empty list, which is why this costs a suite that
+         * does not want the feature exactly nothing.
+         */
+        const shots = collectShots(result.attachments);
+        this.inMemoryShots += shots.inMemory;
+        const failure = failureFacts(result.errors, result.steps);
+        const slowest = slowestSteps(result.steps);
+        this.outcomes.push({
+            testId: test.titlePath().filter(Boolean).join(' > '),
+            title: test.title,
+            ...(project ? { project } : {}),
+            // Playwright reports every attempt separately, and each is its own row.
+            // P7's flake detection reads this history; not capturing it would mean
+            // flake analysis could only ever begin from the day we added the field.
+            retry: result.retry,
+            status: mapStatus(result.status),
+            durationMs: result.duration,
+            records: readScanRecords(result, this.warnings),
+            ...(shots.shots.length > 0 ? { shots: shots.shots } : {}),
+            /*
+             * Three fields that were on this object all along and were being dropped.
+             *
+             * `workerIndex` is `-1` for a test that never got a worker; that maps to
+             * ABSENT, never to zero, because worker zero is real and the difference is
+             * the whole imbalance signal.
+             *
+             * `failure` is what makes `run.json` triageable by someone who did not watch
+             * the run. Free now, unrecoverable afterwards.
+             *
+             * `slowestSteps` is reduced HERE rather than carried as a tree, because the
+             * tree is unbounded and only the tail is useful.
+             */
+            ...(result.workerIndex >= 0 ? { workerIndex: result.workerIndex } : {}),
+            ...(failure ? { failure } : {}),
+            ...(slowest.length > 0 ? { slowestSteps: slowest } : {}),
+        });
+    }
+    async onEnd(result) {
+        if (this.listOnly)
+            return;
+        const generatedAt = new Date().toISOString();
+        const origin = detectOrigin(process.env, this.baseDir);
+        if (this.group) {
+            await this.endGrouped(result, generatedAt, origin);
+            return;
+        }
+        const { envelope, unknowns, warnings } = buildEnvelope({
+            outcomes: this.outcomes,
+            infrastructureProjects: this.infrastructure,
+            inference: this.options.inference,
+            sdkVersion: sdkVersion(),
+            axeVersion: axeVersion(),
+            /*
+             * Detected against the CONFIG's directory rather than the process working
+             * directory: the same suite run from a monorepo root and from its own
+             * package must report the same branch.
+             */
+            runSource: origin.runSource,
+            branch: origin.branch,
+            commit: origin.commit,
+            ...(origin.ci ? { ci: origin.ci } : {}),
+            generatedAt,
+        });
+        const pages = this.outcomes.reduce((total, outcome) => total + outcome.records.length, 0);
+        const declaredAxes = declaredAxesOf(this.options.inference);
+        const meta = {
+            runId: null,
+            submitted: false,
+            sdkVersion: envelope.source.sdkVersion,
+            generatedAt,
+            durationMs: Date.now() - this.startedAt,
+            counts: {
+                tests: envelope.results.length,
+                pages,
+                scans: envelope.scans.length,
+                ...(this.plannedTests !== undefined ? { plannedTests: this.plannedTests } : {}),
+            },
+            ...localFacts(this.outcomes, Date.now() - this.startedAt, this.configuredWorkers),
+            coverage: {
+                ...(declaredAxes ? { declaredAxes } : {}),
+                ...(this.projectNames.length > 0
+                    ? { declaredProjects: [...new Set(this.projectNames)].sort() }
+                    : {}),
+                unmeasuredAxes: this.unmeasuredAxes,
+            },
+            ...(this.configFile ? { configFile: this.configFile } : {}),
+            unknowns: [...origin.unknowns, ...unknowns],
+            warnings: [...this.warnings, ...warnings],
+        };
+        try {
+            const { runDir, envelopePath } = await writeRun(this.options.outputDir, this.baseDir, envelope, meta);
+            const criterionRules = criterionRuleMap();
+            /*
+             * The HTML report gets its own try, deliberately inside the outer one: a
+             * template bug must degrade to "no report.html" — never suppress the
+             * envelope that was already written, and never swallow the terminal
+             * summary that follows. The failure is reported through the same
+             * warnings channel as everything else the run could not do.
+             */
+            /*
+             * Built before the accessibility report, because that report embeds the
+             * same section. One renderer, two homes — see `screens.ts`.
+             */
+            const embeddedScreens = buildScreens(this.outcomes, runDir, envelope, this.inMemoryShots);
+            let htmlReportPath;
+            try {
+                htmlReportPath = await writeHtmlReport(runDir, renderHtmlReport({
+                    envelope,
+                    warnings: meta.warnings,
+                    ...(criterionRules ? { criterionRules } : {}),
+                    ...(embeddedScreens ? { screens: embeddedScreens.input } : {}),
+                    ...(meta.suite ? { suite: meta.suite } : {}),
+                    ...(meta.overhead ? { overhead: meta.overhead } : {}),
+                    ...(meta.coverage?.declaredAxes ? { declaredAxes: meta.coverage.declaredAxes } : {}),
+                    ...(meta.coverage ? { unmeasuredAxes: meta.coverage.unmeasuredAxes } : {}),
+                }));
+            }
+            catch (error) {
+                meta.warnings.push(`The HTML report could not be written: ${error instanceof Error ? error.message : String(error)}. The run's evidence in run.json is unaffected.`);
+            }
+            let screensPath;
+            try {
+                const screens = embeddedScreens;
+                if (screens) {
+                    screens.notes.forEach((note) => meta.warnings.push(note));
+                    if (screens.input.rows.length > 0) {
+                        screensPath = await writeScreensReport(runDir, renderScreensPage(screens.input));
+                    }
+                }
+            }
+            catch (error) {
+                meta.warnings.push(`The screens report could not be written: ${error instanceof Error ? error.message : String(error)}. The run's evidence in run.json is unaffected.`);
+            }
+            const summaryInput = {
+                envelope,
+                envelopePath,
+                warnings: meta.warnings,
+                promo: this.options.promo,
+                grid: this.options.grid,
+                ...(criterionRules ? { criterionRules } : {}),
+                ...(htmlReportPath ? { htmlReportPath } : {}),
+                ...(screensPath ? { screensPath } : {}),
+                ...(this.reportPath ? { reportPath: this.reportPath } : {}),
+                ...(this.plannedTests !== undefined ? { plannedTests: this.plannedTests } : {}),
+                ...(meta.suite ? { suite: meta.suite } : {}),
+                ...(meta.overhead ? { overhead: meta.overhead } : {}),
+                ...(meta.coverage?.declaredAxes ? { declaredAxes: meta.coverage.declaredAxes } : {}),
+                ...(meta.coverage ? { unmeasuredAxes: meta.coverage.unmeasuredAxes } : {}),
+            };
+            console.log(render(summaryInput, this.options.format, process.stdout.columns));
+            await this.writeSummaryFile(summaryInput);
+        }
+        catch (error) {
+            // The SDK never fails a customer's build — not even by failing to write its
+            // own output. A warning is the loudest thing we are entitled to do.
+            console.log(`\n  Setsquare could not write its run output: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * The grouped ending: write this invocation's part, then re-derive the
+     * merged logical run from every part present.
+     *
+     * The terminal keeps speaking for THIS invocation — a CI log per lane must
+     * describe its lane, and two complete-looking merged summaries in one
+     * pipeline log is how someone quotes the wrong one — with a group block
+     * naming the merged artifact and what is known about its coverage. The
+     * merged run.json / meta.json / report.html are the logical run.
+     */
+    async endGrouped(result, generatedAt, origin) {
+        if (!this.group)
+            return;
+        try {
+            // Settle the begun marker first: the part must never exist without it,
+            // or the census could count us as uninvited evidence.
+            await this.begunWrite;
+            const part = {
+                partVersion: PART_VERSION,
+                partId: this.partId,
+                ...(this.group.lane ? { lane: this.group.lane } : {}),
+                startedAt: this.startedAtIso,
+                generatedAt,
+                durationMs: Date.now() - this.startedAt,
+                playwrightStatus: mapInvocationStatus(result?.status),
+                ...(this.plannedTests !== undefined ? { plannedTests: this.plannedTests } : {}),
+                warnings: [...this.warnings],
+                unknowns: [...origin.unknowns],
+                ...(this.reportPath ? { reportPath: this.reportPath } : {}),
+                ...(this.configFile ? { configFile: this.configFile } : {}),
+                ...(this.configuredWorkers !== undefined
+                    ? { configuredWorkers: this.configuredWorkers }
+                    : {}),
+                coverage: {
+                    ...(declaredAxesOf(this.options.inference)
+                        ? { declaredAxes: declaredAxesOf(this.options.inference) }
+                        : {}),
+                    ...(this.projectNames.length > 0
+                        ? { declaredProjects: [...new Set(this.projectNames)].sort() }
+                        : {}),
+                    unmeasuredAxes: this.unmeasuredAxes,
+                },
+                source: {
+                    branch: origin.branch,
+                    commit: origin.commit,
+                    runSource: origin.runSource,
+                    sdkVersion: sdkVersion(),
+                    axeVersion: axeVersion(),
+                    ...(origin.ci ? { ci: origin.ci } : {}),
+                },
+                inference: serialisableInference(this.options.inference),
+                outcomes: prepareOutcomesForPart(this.outcomes, this.infrastructure, this.options.inference),
+            };
+            await writePart(this.groupDir, part);
+            const criterionRules = criterionRuleMap();
+            /*
+             * The merged sheet is built from the MERGED outcomes, not this
+             * invocation's — a sharded suite's captures are spread across lanes, and a
+             * sheet showing only the lane that happened to merge last would be the
+             * most misleading artifact in the directory. Shot paths ride through the
+             * part files to make that possible; the ones that were captured on another
+             * machine are named as unreachable rather than shown broken.
+             */
+            const merged = await mergeGroup({
+                groupDir: this.groupDir,
+                group: this.group,
+                renderReport: (envelope, meta, outcomes) => {
+                    const screens = buildScreens(outcomes, this.groupDir, envelope, this.inMemoryShots);
+                    return renderHtmlReport({
+                        envelope,
+                        warnings: meta.warnings,
+                        ...(criterionRules ? { criterionRules } : {}),
+                        ...(meta.group ? { group: meta.group } : {}),
+                        ...(screens ? { screens: screens.input } : {}),
+                        // The MERGED facts here, unlike the terminal above: this report
+                        // describes the whole group, which is what the file is for.
+                        ...(meta.suite ? { suite: meta.suite } : {}),
+                        ...(meta.overhead ? { overhead: meta.overhead } : {}),
+                        ...(meta.coverage?.declaredAxes ? { declaredAxes: meta.coverage.declaredAxes } : {}),
+                        ...(meta.coverage ? { unmeasuredAxes: meta.coverage.unmeasuredAxes } : {}),
+                    });
+                },
+                renderScreens: (outcomes, runDir, envelope, meta) => {
+                    const screens = buildScreens(outcomes, runDir, envelope, this.inMemoryShots);
+                    if (!screens || screens.input.rows.length === 0)
+                        return undefined;
+                    for (const note of screens.notes)
+                        meta.warnings.push(note);
+                    return renderScreensPage(screens.input);
+                },
+            });
+            // This invocation's own numbers, for this invocation's own log.
+            const own = buildEnvelope({
+                outcomes: this.outcomes,
+                infrastructureProjects: this.infrastructure,
+                inference: this.options.inference,
+                sdkVersion: sdkVersion(),
+                axeVersion: axeVersion(),
+                runSource: origin.runSource,
+                branch: origin.branch,
+                commit: origin.commit,
+                ...(origin.ci ? { ci: origin.ci } : {}),
+                generatedAt,
+            });
+            const ownFacts = localFacts(this.outcomes, Date.now() - this.startedAt, this.configuredWorkers);
+            const summaryInput = {
+                envelope: own.envelope,
+                envelopePath: merged.envelopePath,
+                warnings: [...this.warnings, ...own.warnings],
+                promo: this.options.promo,
+                grid: this.options.grid,
+                ...(criterionRules ? { criterionRules } : {}),
+                ...(merged.htmlReportPath ? { htmlReportPath: merged.htmlReportPath } : {}),
+                ...(merged.screensPath ? { screensPath: merged.screensPath } : {}),
+                ...(this.reportPath ? { reportPath: this.reportPath } : {}),
+                ...(this.plannedTests !== undefined ? { plannedTests: this.plannedTests } : {}),
+                /*
+                 * THIS invocation's own facts, not the merged group's.
+                 *
+                 * The terminal summary above the run-group block describes this
+                 * invocation only (its own comment says so), so quoting the merged
+                 * overhead or the merged worker spread here would attribute other
+                 * lanes' work to this one. The merged figures live in the merged
+                 * artifacts, which the block below points at.
+                 */
+                ...(ownFacts.suite ? { suite: ownFacts.suite } : {}),
+                ...(ownFacts.overhead ? { overhead: ownFacts.overhead } : {}),
+                ...(declaredAxesOf(this.options.inference)
+                    ? { declaredAxes: declaredAxesOf(this.options.inference) }
+                    : {}),
+                unmeasuredAxes: this.unmeasuredAxes,
+                group: {
+                    id: this.group.id,
+                    ...(this.group.lane ? { lane: this.group.lane } : {}),
+                    partId: this.partId,
+                    mergedParts: merged.group.completed,
+                    labels: merged.group.parts.map((p) => p.label),
+                    expectedParts: merged.group.expectedParts,
+                    missing: merged.group.missing.length,
+                    coverage: merged.group.coverage,
+                },
+            };
+            console.log(render(summaryInput, this.options.format, process.stdout.columns));
+            await this.writeSummaryFile(summaryInput);
+        }
+        catch (error) {
+            console.log(`\n  Setsquare could not write its run-group output: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * The same summary again, as markdown, when someone asked for a copy.
+     *
+     * Rendered from the SAME `SummaryInput` the terminal was given, which is the
+     * whole point: a CI job summary that disagreed with the log above it would be
+     * worse than no job summary at all. `format` is not consulted — this
+     * destination is markdown by definition, and a suite configured for `json`
+     * still wants a readable panel.
+     *
+     * Silent on failure, and deliberately so. This is the last thing the reporter
+     * does; a path the process cannot write must not swallow the summary that was
+     * already printed or the evidence that was already saved.
+     */
+    async writeSummaryFile(input) {
+        const path = summaryMarkdownPath();
+        if (path === undefined)
+            return;
+        try {
+            await writeSummaryMarkdown(this.baseDir, path, render(input, 'markdown'));
+        }
+        catch {
+            // Intentionally silent: see above.
+        }
+    }
+}
+/**
+ * Assemble the contact sheet's input, and say what it could not show.
+ *
+ * The one place reachability is checked, because it is a policy decision rather
+ * than a rendering one: a merged run group can hold parts captured on other
+ * machines, and a suite that cleans its output directory between the run and the
+ * reading leaves every path dangling. Either way the honest artifact links to
+ * the files that are there and NAMES the ones that are not — a page of broken
+ * image icons is how a QA-facing report loses its reader for good, and a silently
+ * shortened page is worse, because it looks complete.
+ *
+ * Returns `undefined` only when the run produced no image attachments at all, so
+ * a suite that takes no screenshots pays nothing and sees nothing.
+ */
+function buildScreens(outcomes, runDir, envelope, inMemory) {
+    if (!outcomes.some((outcome) => (outcome.shots?.length ?? 0) > 0) && inMemory === 0) {
+        return undefined;
+    }
+    let missing = 0;
+    const resolved = outcomes.map((outcome) => {
+        if (!outcome.shots || outcome.shots.length === 0)
+            return outcome;
+        const check = reachableShots(outcome.shots);
+        missing += check.missing;
+        return { ...outcome, shots: check.shots };
+    });
+    const rows = screenRows(resolved);
+    const notes = [];
+    if (missing > 0) {
+        notes.push(`${missing} screenshot${missing === 1 ? '' : 's'} referenced by this run ${missing === 1 ? 'is' : 'are'} no longer at the path Playwright recorded, so the screens report cannot show ${missing === 1 ? 'it' : 'them'}. On a merged run group this normally means another machine captured ${missing === 1 ? 'it' : 'them'}; otherwise the test output directory has been cleaned or moved.`);
+    }
+    if (inMemory > 0) {
+        notes.push(`${inMemory} image attachment${inMemory === 1 ? '' : 's'} in this run ${inMemory === 1 ? 'was' : 'were'} attached as a body rather than a path, so ${inMemory === 1 ? 'it exists' : 'they exist'} only in Playwright's memory and the screens report cannot link to ${inMemory === 1 ? 'it' : 'them'}. Attach with \`path\` to include ${inMemory === 1 ? 'it' : 'them'}.`);
+    }
+    const withShots = rows.length;
+    const testsWithoutShots = Math.max(0, outcomes.length - withShots);
+    return {
+        input: {
+            rows,
+            runDir,
+            testsWithoutShots,
+            generatedAt: envelope.generatedAt,
+            branch: envelope.source.branch,
+            commit: envelope.source.commit,
+            notes,
+        },
+        notes,
+    };
+}
+/** Playwright's whole-invocation verdict, defensively mapped. */
+function mapInvocationStatus(status) {
+    switch (status) {
+        case 'passed':
+        case 'failed':
+        case 'timedout':
+        case 'interrupted':
+            return status;
+        default:
+            return 'unknown';
+    }
+}
+function mapStatus(status) {
+    switch (status) {
+        case 'passed':
+        case 'failed':
+        case 'timedOut':
+        case 'skipped':
+            return status;
+        default:
+            // `interrupted`, and anything Playwright adds later. Reported as failed
+            // rather than dropped: a test that did not finish is not a test that passed.
+            return 'failed';
+    }
+}
+/**
+ * Pull our attachments back out of the test result.
+ *
+ * Tolerates both shapes Playwright uses — an in-memory `body`, or a `path` when
+ * attachments have been spilled to disk — because which one you get depends on
+ * the customer's config rather than on anything we control.
+ */
+function readScanRecords(result, warnings) {
+    const records = [];
+    for (const attachment of result.attachments) {
+        if (attachment.name !== SCAN_RECORD_ATTACHMENT)
+            continue;
+        try {
+            const raw = attachment.body?.toString('utf8');
+            if (!raw) {
+                // A path-only attachment needs a synchronous read, which this hook cannot
+                // do. Recorded rather than dropped silently — missing evidence must never
+                // look like clean evidence.
+                warnings.push('A scan record was written to disk rather than kept in memory and could not be read back.');
+                continue;
+            }
+            records.push(JSON.parse(raw));
+        }
+        catch (error) {
+            warnings.push(`A scan record could not be parsed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return records;
+}
+/**
+ * Where Playwright put its own HTML report, if it made one.
+ *
+ * Read from the customer's reporter configuration rather than assumed, because
+ * `outputFolder` is routinely overridden — and a link to a directory that does not
+ * exist is worse than no link, since it sends someone looking for a file that was
+ * never written.
+ *
+ * Checked for existence at the end of the run for the same reason: the html
+ * reporter can be configured and still produce nothing, and this line is only
+ * worth printing when there is something behind it.
+ */
+/**
+ * Playwright `use` options that would create an evidence axis and that no project set.
+ *
+ * The honest, cheap answer to the gap analysis's "`forced-colors` and
+ * `prefers-reduced-motion` are one context option away". For the CUSTOMER'S config
+ * that is true; for the SDK it is not — as evidence axes they would change the
+ * scan context, the DEDUPE KEY and the grid, and getting that wrong makes evidence
+ * silently collapse across settings, which is worse than not having the axis.
+ *
+ * So this states what was not measured and stops there. Recommending the projects
+ * is `setsquare doctor`'s job.
+ */
+const AXIS_OPTIONS = ['colorScheme', 'reducedMotion', 'forcedColors'];
+export function unmeasuredAxes(projects) {
+    const set = new Set(AXIS_OPTIONS);
+    for (const project of projects) {
+        const use = project.use;
+        /*
+         * Both places, because only ONE of them is even legal for two of these axes.
+         *
+         * `colorScheme` is a first-class `use:` option, but `forcedColors` and
+         * `reducedMotion` are not: Playwright's `PlaywrightTestOptions` does not
+         * declare them, and its own documented example sets them through
+         * `use: { contextOptions: { reducedMotion: 'reduce' } }`. Reading `use` alone
+         * meant a customer who had configured forced-colors the only way the types
+         * allow was still told the axis was unmeasured — a false statement about
+         * their own configuration, in the output whose whole job is not making those.
+         *
+         * Found while writing the recipes: the snippet demonstrating it did not compile.
+         */
+        const contextOptions = use?.['contextOptions'];
+        for (const option of AXIS_OPTIONS) {
+            // `null` is a deliberate Playwright value ("no preference"), which IS a
+            // setting — so only genuine absence counts as unmeasured.
+            const set_here = (use && option in use && use[option] !== undefined) ||
+                (contextOptions && option in contextOptions && contextOptions[option] !== undefined);
+            if (set_here)
+                set.delete(option);
+        }
+    }
+    return [...set];
+}
+/**
+ * The axis values the CUSTOMER declared, which is the only real denominator.
+ *
+ * Read from their own `themes`/`personas` maps and their project list — never from
+ * what happened to be scanned, because a value nobody ever visited leaves no trace
+ * to count. "4 personas configured, 1 with evidence" is a defensible sentence;
+ * anything derived from observed values alone is circular.
+ *
+ * Returns `undefined` when the config declared nothing we can read, so a renderer
+ * suppresses the line entirely rather than falling back to N = M and reporting
+ * perfect coverage of whatever ran. Callbacks are deliberately not consulted: a
+ * function can only be asked about a value we already have, so it can confirm an
+ * observation but never enumerate the possibilities.
+ */
+function declaredAxesOf(inference) {
+    const declared = {};
+    const themes = inference?.themes
+        ? [...new Set(Object.values(inference.themes))].sort()
+        : [];
+    if (themes.length > 0)
+        declared['theme'] = themes;
+    const personas = inference?.personas
+        ? [...new Set(Object.values(inference.personas))].sort()
+        : [];
+    if (personas.length > 0)
+        declared['persona'] = personas;
+    return Object.keys(declared).length > 0 ? declared : undefined;
+}
+function htmlReportPath(config, baseDir) {
+    const entries = Array.isArray(config.reporter) ? config.reporter : [];
+    for (const entry of entries) {
+        const [name, options] = Array.isArray(entry) ? entry : [entry, undefined];
+        if (name !== 'html' && !String(name).endsWith('html'))
+            continue;
+        const folder = options?.outputFolder;
+        return resolve(baseDir, folder ?? 'playwright-report');
+    }
+    // Playwright writes `playwright-report/` by default when no reporter is
+    // configured at all, which is the common case for a suite that has not been
+    // customised.
+    const fallback = join(baseDir, 'playwright-report');
+    return existsSync(fallback) ? fallback : undefined;
+}
+//# sourceMappingURL=reporter.js.map