@setsquare/review-sdk 0.0.1

package/dist/autoscan.d.ts

@@ -0,0 +1,25 @@
+import type { BrowserContext, TestInfo } from '@playwright/test';
+import { type ResolvedSetsquareOptions } from './options.js';
+export declare function installAutoScan(context: BrowserContext, options: ResolvedSetsquareOptions, testInfo: TestInfo, warn: (message: string) => void): Promise<void>;
+/**
+ * Scan whatever the test left on screen, at teardown.
+ *
+ * This exists because of a measurement, and it is the single most important
+ * thing Stage 5 learned. Auto-scan fires 500ms after a page goes quiet — but a
+ * great many real tests finish in less than that. On the fixture suite, only two
+ * of ten surfaces were ever scanned: every fast test tore its context down before
+ * the settle callback could run, and the evidence for those surfaces simply never
+ * existed. A customer would have seen a grid with most of their application
+ * missing and no indication why.
+ *
+ * So teardown sweeps: for every page still open, if its current URL has not been
+ * scanned during this test, scan it now. The page has by definition finished
+ * settling — the test is over — which makes this the most reliable moment
+ * available, not a fallback.
+ *
+ * The settle heuristic still earns its place: it is what catches the surfaces a
+ * test passes THROUGH on its way somewhere else, which teardown can never see
+ * because they are no longer on screen.
+ */
+export declare function flushAutoScan(context: BrowserContext, options: ResolvedSetsquareOptions, testInfo: TestInfo, warn: (message: string) => void): Promise<void>;
+//# sourceMappingURL=autoscan.d.ts.map

package/dist/autoscan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoscan.d.ts","sourceRoot":"","sources":["../src/autoscan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAQ,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAavE,OAAO,EAAqB,KAAK,wBAAwB,EAAE,MAAM,cAAc,CAAC;AA+DhF,wBAAgB,eAAe,CAC7B,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,OAAO,CAAC,IAAI,CAAC,CAqEf;AA6LD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,OAAO,CAAC,IAAI,CAAC,CA0Df"}

package/dist/autoscan.js

@@ -0,0 +1,332 @@
+import { engineVersion, rulesetDigest, runAxe } from './axe.js';
+import { SCAN_RECORD_ATTACHMENT, SCAN_RECORD_VERSION } from './contract.js';
+import { toFindings, toInapplicable, toPasses } from './findings.js';
+import { runStatusMessages, runTextSpacing } from './checks/dynamic.js';
+import { setsquareCheckVersions } from './checks/versions.js';
+import { runReadingLevel } from './reading-level.js';
+import { readingLevelEnabled } from './runtime.js';
+import { capturePerf } from './perf.js';
+import { readDocumentFacts } from './document.js';
+import { pageRuntime } from './observe.js';
+import { recordUnscannable } from './unscannable.js';
+import { changedOnlyRoutes } from './options.js';
+import { tagsFor } from './rules.js';
+import { toUrlPattern } from './sanitise.js';
+import { MUTATION_TOTAL, SETTLE_BINDING, settleScript } from './settle.js';
+const state = new WeakMap();
+let visitCounter = 0;
+function stateFor(page, url) {
+    const existing = state.get(page);
+    if (existing && existing.visitUrl === url)
+        return existing;
+    const next = {
+        queue: existing?.queue ?? Promise.resolve(),
+        visitRef: `v${(visitCounter += 1)}`,
+        visitUrl: url,
+        perfCaptured: false,
+        scans: existing?.scans ?? 0,
+        scanned: existing?.scanned ?? new Map(),
+    };
+    state.set(page, next);
+    return next;
+}
+/**
+ * A per-page ceiling on automatic scans.
+ *
+ * Without one, a page that mutates in bursts — a poller, a chat widget, an
+ * animation that pauses — produces a settle signal per burst and we scan it
+ * repeatedly for the whole test. The dedupe in the reporter would collapse the
+ * results, but the RUN TIME would already have been spent, and run time is the
+ * canary this milestone exists to listen to.
+ *
+ * Deliberately generous: a genuinely multi-route test should not hit it. When it
+ * does, the run says so rather than silently capping.
+ */
+const MAX_AUTO_SCANS_PER_PAGE = 25;
+export function installAutoScan(context, options, testInfo, warn) {
+    const settle = options.settle;
+    const onSettled = async (page, signal) => {
+        // Nothing to record: a closed page cannot hold a ledger, and the page's own
+        // observation record has already been written or never will be.
+        if (page.isClosed())
+            return;
+        const pageState = stateFor(page, signal.url);
+        if (pageState.scans >= MAX_AUTO_SCANS_PER_PAGE) {
+            recordUnscannable(page, toUrlPattern(signal.url).pattern, 'scan-cap-reached');
+            if (pageState.scans === MAX_AUTO_SCANS_PER_PAGE) {
+                pageState.scans += 1;
+                warn(`A page settled more than ${MAX_AUTO_SCANS_PER_PAGE} times in one test ` +
+                    `(${signal.url}); further automatic scans were skipped. This usually means ` +
+                    `something on the page never stops changing.`);
+            }
+            return;
+        }
+        pageState.scans += 1;
+        /*
+         * Queued, never concurrent.
+         *
+         * Playwright serialises operations on a page anyway, so a scan running while
+         * the customer's test is mid-click does not corrupt anything — but it does
+         * make their action WAIT for our axe run. Chaining scans keeps that cost
+         * bounded and predictable instead of multiplying it.
+         */
+        pageState.queue = pageState.queue.then(async () => {
+            if (page.isClosed())
+                return;
+            try {
+                await scanSettledPage(page, signal, options, testInfo, warn);
+            }
+            catch (error) {
+                // Never the customer's problem. A failed automatic scan is a warning in
+                // our own output and nothing else — plus a counted ledger row, so the
+                // coverage figures cannot silently absorb it.
+                recordUnscannable(page, toUrlPattern(signal.url).pattern, 'scan-failed');
+                warn(`Automatic scan of ${signal.url} failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+        await pageState.queue;
+    };
+    return Promise.all([
+        /*
+         * A binding rather than polling.
+         *
+         * The alternative — asking the page every N milliseconds whether it has gone
+         * quiet — costs a round-trip per poll per page for the whole run, and still
+         * learns about the settle late. The binding costs one function on `window`,
+         * which is real pollution of a customer's page and is why it is namespaced
+         * and non-enumerable.
+         */
+        context.exposeBinding(SETTLE_BINDING, ({ page }, signal) => onSettled(page, signal)),
+        context.addInitScript(settleScript(settle)),
+    ]).then(() => undefined);
+}
+async function scanSettledPage(page, signal, options, testInfo, warn) {
+    const url = page.url();
+    /*
+     * The page moved on between settling and being scanned.
+     *
+     * Ordinary in a fast suite: a test clicks through two routes quicker than a
+     * scan takes. Attributing findings to the URL that settled would file them
+     * against a surface they did not come from, so the scan is abandoned instead.
+     * The new URL will settle and be scanned on its own.
+     */
+    if (url !== signal.url) {
+        // Counted, not merely skipped. A fast suite that outruns its own scans looks
+        // identical to a smaller application unless the misses are on the record.
+        recordUnscannable(page, toUrlPattern(signal.url).pattern, 'nav-aborted');
+        return;
+    }
+    const pageState = stateFor(page, url);
+    /*
+     * Changed-only mode: skip a surface the change cannot reach.
+     *
+     * The SDK does no route reasoning — it compares a pattern it already computed
+     * against a list the CLI wrote. A miss is RECORDED in the ledger rather than
+     * silently dropped, because a run that scanned a third of the app must not read
+     * like a run of a smaller app.
+     *
+     * Only a real array licenses skipping: `changedOnlyRoutes` returns undefined for
+     * a missing, null or malformed set, and undefined means scan everything.
+     */
+    const changedOnly = changedOnlyRoutes();
+    if (changedOnly !== undefined) {
+        const pattern = toUrlPattern(url).pattern;
+        if (!changedOnly.has(pattern)) {
+            recordUnscannable(page, pattern, 'not-in-changed-set');
+            return;
+        }
+    }
+    const scanStartedAt = Date.now();
+    const results = await runAxe(page, options.rules, options.scanTimeoutMs);
+    const axeMs = Date.now() - scanStartedAt;
+    /*
+     * The scan ran out of budget, so there is no scan.
+     *
+     * Recorded as a warning and NOT as an empty result: "we looked and found
+     * nothing" and "we ran out of time" are the two facts this product exists to
+     * keep apart, and conflating them here would be the confident false pass in its
+     * purest form.
+     */
+    if (!results) {
+        recordUnscannable(page, toUrlPattern(url).pattern, 'scan-timed-out');
+        warn(`A scan of ${url} was abandoned after ${options.scanTimeoutMs}ms so it could not ` +
+            'hold up the test. That surface has no evidence in this run rather than a clean result.');
+        return;
+    }
+    const axeVersion = engineVersion(results) ?? 'unknown';
+    const findings = toFindings(results);
+    // Setsquare's own checks, same channel and same never-fail discipline as
+    // the explicit-scan path. The digest names the run's configured check set,
+    // never which scans happened to execute one — see setsquareCheckVersions for why.
+    const setsquareChecks = setsquareCheckVersions(options.rules);
+    if (readingLevelEnabled()) {
+        const readingLevel = await runReadingLevel(page);
+        if (readingLevel)
+            findings.push(readingLevel);
+    }
+    const passes = toPasses(results);
+    const inapplicable = toInapplicable(results);
+    /*
+     * Dynamic checks only at TEARDOWN, never mid-test: the text-spacing probe
+     * mutates the live page, and an auto-scan firing between a customer's
+     * actions would make us the flake in their screenshot assertion. At
+     * teardown the test is over and the page is about to be discarded.
+     */
+    if (signal.reason === 'teardown') {
+        for (const check of [await runTextSpacing(page), await runStatusMessages(page)]) {
+            if (check.finding)
+                findings.push(check.finding);
+            if (check.pass)
+                passes.push(check.pass);
+            if (check.inapplicable)
+                inapplicable.push(check.inapplicable);
+        }
+    }
+    const record = {
+        recordVersion: SCAN_RECORD_VERSION,
+        kind: 'scan',
+        page: { project: testInfo.project.name, engine: engineOf(page), url },
+        // Auto-scan states nothing. The surface is inferred by the reporter from the
+        // route, and any persona or theme comes from configuration or the live DOM —
+        // never from this file guessing.
+        declared: { surface: '' },
+        visitRef: pageState.visitRef,
+        axeVersion,
+        rulesetDigest: rulesetDigest(axeVersion, results, tagsFor(options.rules), setsquareChecks),
+        wcagTarget: options.rules.target,
+        findings,
+        passes,
+        inapplicable,
+        settle: {
+            reason: signal.reason,
+            ...(signal.via ? { via: signal.via } : {}),
+            sinceNavMs: Math.round(signal.sinceNavMs),
+            mutations: signal.mutations,
+            settleTimedOut: signal.settleTimedOut,
+        },
+    };
+    const viewport = page.viewportSize();
+    if (viewport)
+        record.page.viewport = viewport;
+    const probesStartedAt = Date.now();
+    // Theme and document facts in one round-trip. Two `page.evaluate` calls on a
+    // path that runs for every scan in the suite is a cost with nothing to show for it.
+    const facts = await readDocumentFacts(page);
+    if (facts.theme)
+        record.page.observedTheme = facts.theme;
+    if (facts.document)
+        record.document = facts.document;
+    /*
+     * Perf and page-runtime are both properties of the PAGE LOAD, not of the scan,
+     * so both are emitted once per visit and gated together.
+     *
+     * Scanning one page as its state changes — modal closed, then modal open —
+     * produces several scans from a single navigation. Repeating either block would
+     * weight pillar 3's averages by how many states a surface happens to have and
+     * would report the same 500 four times.
+     */
+    if (!pageState.perfCaptured) {
+        const perf = await capturePerf(page);
+        if (perf)
+            record.perf = perf;
+        const runtime = pageRuntime(page);
+        if (runtime)
+            record.runtime = runtime;
+        // Set regardless of whether either block materialised: the gate means "this
+        // visit has had its page-load facts taken", and an engine that can measure
+        // neither must not be asked again on every subsequent state.
+        pageState.perfCaptured = true;
+    }
+    const probesMs = Date.now() - probesStartedAt;
+    record.cost = {
+        totalMs: Date.now() - scanStartedAt,
+        axeMs,
+        ...(probesMs > 0 ? { probesMs } : {}),
+    };
+    pageState.scanned.set(url, await mutationTotal(page));
+    await testInfo.attach(SCAN_RECORD_ATTACHMENT, {
+        body: Buffer.from(JSON.stringify(record), 'utf8'),
+        contentType: 'application/json',
+    });
+}
+/** How much the page has changed in total. Zero if the counter is unavailable. */
+async function mutationTotal(page) {
+    try {
+        return await page.evaluate((key) => window[key] ?? 0, MUTATION_TOTAL);
+    }
+    catch {
+        return 0;
+    }
+}
+function engineOf(page) {
+    const name = page.context().browser()?.browserType().name();
+    return name === 'firefox' || name === 'webkit' ? name : 'chromium';
+}
+/**
+ * Scan whatever the test left on screen, at teardown.
+ *
+ * This exists because of a measurement, and it is the single most important
+ * thing Stage 5 learned. Auto-scan fires 500ms after a page goes quiet — but a
+ * great many real tests finish in less than that. On the fixture suite, only two
+ * of ten surfaces were ever scanned: every fast test tore its context down before
+ * the settle callback could run, and the evidence for those surfaces simply never
+ * existed. A customer would have seen a grid with most of their application
+ * missing and no indication why.
+ *
+ * So teardown sweeps: for every page still open, if its current URL has not been
+ * scanned during this test, scan it now. The page has by definition finished
+ * settling — the test is over — which makes this the most reliable moment
+ * available, not a fallback.
+ *
+ * The settle heuristic still earns its place: it is what catches the surfaces a
+ * test passes THROUGH on its way somewhere else, which teardown can never see
+ * because they are no longer on screen.
+ */
+export async function flushAutoScan(context, options, testInfo, warn) {
+    for (const page of context.pages()) {
+        if (page.isClosed())
+            continue;
+        const url = page.url();
+        // `about:blank` is Playwright opening a context, not the suite visiting
+        // anything. Scanning it would put a surface in the grid nobody asked for.
+        if (!url || url === 'about:blank')
+            continue;
+        const pageState = stateFor(page, url);
+        /*
+         * Re-scan a URL already scanned during this test IF the page has changed
+         * since — which is the whole reason this tracks mutation counts rather than
+         * just which URLs were visited.
+         *
+         * Measured on the fixture site: `/slow` renders a conformant shell, goes
+         * quiet, is scanned at 500ms with zero violations, and only THEN injects its
+         * two real violations at 1000ms. Skipping the second scan because the URL was
+         * "already done" enshrined the shell and reported a clean page — the exact
+         * confident false pass this whole heuristic exists to prevent. The mutation
+         * counter distinguishes "already scanned" from "already scanned, and then
+         * everything changed".
+         */
+        const lastScannedAt = pageState.scanned.get(url);
+        if (lastScannedAt !== undefined && (await mutationTotal(page)) === lastScannedAt)
+            continue;
+        try {
+            // Chained onto the same queue as settle-triggered scans, so a scan that was
+            // already in flight when the test ended is not raced.
+            const mutations = await mutationTotal(page);
+            pageState.queue = pageState.queue.then(() => scanSettledPage(page, {
+                url,
+                // Honest about where this came from. A teardown scan is not a settle,
+                // and labelling it one would make the diagnostics — whose entire job
+                // is telling you how much to trust a result — lie.
+                reason: 'teardown',
+                sinceNavMs: 0,
+                mutations,
+                settleTimedOut: false,
+            }, options, testInfo, warn));
+            await pageState.queue;
+        }
+        catch (error) {
+            warn(`Final scan of ${url} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+//# sourceMappingURL=autoscan.js.map

package/dist/autoscan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoscan.js","sourceRoot":"","sources":["../src/autoscan.ts"],"names":[],"mappings":"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"}

package/dist/axe.d.ts

@@ -0,0 +1,96 @@
+import type { Page } from '@playwright/test';
+import { type RulePolicy } from './rules.js';
+/** The subset of axe's output this SDK reads. */
+export interface AxeCheckResult {
+    data?: unknown;
+}
+export interface AxeNode {
+    target: unknown[];
+    failureSummary?: string;
+    any?: AxeCheckResult[];
+    all?: AxeCheckResult[];
+    none?: AxeCheckResult[];
+}
+export interface AxeRuleResult {
+    id: string;
+    impact?: string | null;
+    tags: string[];
+    helpUrl?: string;
+    nodes: AxeNode[];
+}
+export interface AxeRunResults {
+    violations: AxeRuleResult[];
+    incomplete: AxeRuleResult[];
+    passes: AxeRuleResult[];
+    inapplicable: AxeRuleResult[];
+    testEngine?: {
+        name?: string;
+        version?: string;
+    };
+}
+/**
+ * Inject axe and run it against the page's current state.
+ *
+ * Injection happens per scan rather than per page, because a navigation wipes
+ * the document and any previously injected script with it. Re-injecting is
+ * cheap next to the run itself.
+ *
+ * Main frame only, and that is a stated limitation rather than an oversight:
+ * axe reports cross-origin iframes as `incomplete` unless it is injected into
+ * each frame, which needs same-origin access the SDK cannot assume. Reporting
+ * them as incomplete is the honest outcome — "we could not check this" — and it
+ * reaches the payload as such rather than as a pass.
+ *
+ * ## Why this does not use `window.axe`
+ *
+ * Because it did, and it broke a customer's suite.
+ *
+ * The reference implementation runs `@axe-core/playwright` in its own specs. Both
+ * it and the original version of this function loaded axe onto the shared
+ * `window.axe`, so an auto-scan firing while one of their scans was in flight hit
+ * axe-core's own guard — *"Axe is already running"* — and failed two of THEIR
+ * tests, which then passed on retry. The SDK had changed a verdict in the suite
+ * of the customer profile most likely to adopt it: the one already running axe.
+ *
+ * The fix is that our instance is never reachable as `window.axe`. Axe's UMD
+ * bundle assigns itself to the global, so the injection captures it, files it
+ * under our own key, and puts back whatever was there before — including
+ * `undefined`, so a page with no axe of its own is left with no axe of its own.
+ * A separate instance carries its own `_running` flag, so neither side can ever
+ * trip the other's guard.
+ *
+ * Politeness on top of correctness: if the customer's axe IS mid-run we wait for
+ * it, up to a short budget, rather than traversing the same DOM at the same time.
+ * Two concurrent runs are no longer an ERROR, but they are still two full tree
+ * walks competing for one main thread, and the customer's run is the one with a
+ * person waiting on it.
+ */
+export declare function runAxe(page: Page, policy: RulePolicy, timeoutMs?: number): Promise<AxeRunResults | undefined>;
+/** The axe build that produced a result, read from the run rather than assumed. */
+export declare function engineVersion(results: AxeRunResults): string | undefined;
+/**
+ * A digest of the rules that actually ran.
+ *
+ * Evidence claims are relative to a ruleset, so "this finding did not appear last
+ * week" is only meaningful if the same rules were evaluated both times. The
+ * digest is what makes that checkable rather than assumed.
+ *
+ * Computed from the union of every outcome bucket — violations, incompletes,
+ * passes and inapplicable — because that union IS the resolved rule set. axe
+ * ships 105 rules and evaluates ~89 by default; the remainder are experimental or
+ * off by default and never appear in any bucket. Digesting `getRules()` instead
+ * would name rules that never ran, and would not change when the default set did.
+ *
+ * Sorted before hashing so two runs of the same configuration agree regardless of
+ * the order axe happened to report in.
+ */
+export declare function rulesetDigest(axeVersion: string, results: AxeRunResults, tags?: string[], 
+/**
+ * Setsquare's own checks, when any are enabled — versioned ids like
+ * `setsquare-reading-level@1`. Evidence claims are relative to everything that
+ * assessed the page, not only axe, so two runs that differ in enabled setsquare
+ * checks must not share a digest. Empty (the default) leaves the digest
+ * byte-identical to what pre-check SDKs produced.
+ */
+setsquareChecks?: string[]): string;
+//# sourceMappingURL=axe.d.ts.map

package/dist/axe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axe.d.ts","sourceRoot":"","sources":["../src/axe.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AA0BtD,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,cAAc,EAAE,CAAC;IACvB,GAAG,CAAC,EAAE,cAAc,EAAE,CAAC;IACvB,IAAI,CAAC,EAAE,cAAc,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,YAAY,EAAE,aAAa,EAAE,CAAC;IAC9B,UAAU,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,MAAM,CAC1B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,UAAU,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CA6GpC;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAExE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,MAAM,EAAO;AACnB;;;;;;GAMG;AACH,eAAe,GAAE,MAAM,EAAO,GAC7B,MAAM,CAuBR"}