@setsquare/review-sdk 0.0.1

package/dist/output.js

@@ -0,0 +1,231 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * Sortable, collision-resistant, and readable at a glance in a directory listing.
+ *
+ * Derived from `generatedAt` rather than a fresh clock so the directory name and
+ * the envelope's own timestamp can never disagree. Colons are stripped because
+ * they are illegal in filenames on Windows, and a customer on Windows finding
+ * that we cannot write our own output would be an unforced error.
+ *
+ * The engine used to be part of this name and deliberately is not any more. A
+ * single Playwright run can span three engines — the compatibility matrix
+ * requires it — so a directory named after one of them would be wrong for every
+ * mixed run, and quietly right-looking. The engine belongs to each test result,
+ * which is the only place it is ever singular.
+ */
+export function runDirName(generatedAt) {
+    return generatedAt.replace(/[:.]/g, '-').replace(/[zZ]$/, 'Z');
+}
+/**
+ * Write a file so no reader can ever observe it half-written.
+ *
+ * A plain `writeFile` is atomic against other writers of *different* files, but
+ * not against a reader that lists the directory the instant the file appears —
+ * which is exactly what a concurrent invocation's merge does. Content goes to a
+ * uniquely-named sibling first, then renames into place; rename is atomic on
+ * every filesystem we run on, so a reader sees the old bytes or the new bytes
+ * and never a prefix.
+ *
+ * The rename is retried because Windows refuses to replace a file another
+ * process holds open without FILE_SHARE_DELETE — antivirus scanners and search
+ * indexers do this routinely, briefly. A short backoff outlasts almost all of
+ * them; persistent failure propagates, because falling back to a plain
+ * overwrite would reintroduce the torn read this function exists to prevent.
+ */
+export async function writeFileAtomic(path, content) {
+    const tmp = join(dirname(path), `.tmp-${randomBytes(6).toString('hex')}`);
+    await writeFile(tmp, content, 'utf8');
+    let lastError;
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+        try {
+            await rename(tmp, path);
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            await new Promise((r) => setTimeout(r, 30 * (attempt + 1)));
+        }
+    }
+    await unlink(tmp).catch(() => { });
+    throw lastError;
+}
+export async function writeRun(outputDir, baseDir, envelope, meta) {
+    // Relative output resolves against the config's directory, never the process
+    // working directory: the same suite run from a monorepo root and from its own
+    // package must write to the same place, or the artifact moves depending on
+    // where the developer happened to be standing.
+    const root = resolve(baseDir, outputDir);
+    const runDir = join(root, 'runs', runDirName(envelope.generatedAt));
+    const result = await writeRunInto(runDir, root, envelope, meta);
+    await pruneRuns(join(root, 'runs'), { currentName: runDirName(envelope.generatedAt) });
+    return result;
+}
+/**
+ * The write itself, with the destination chosen by the caller.
+ *
+ * Split from `writeRun` because a grouped run's directory is keyed by the
+ * orchestrator's id rather than by this invocation's clock — but what goes IN
+ * the directory, and how it gets there, must not differ between the two paths.
+ *
+ * `run.json` lands before `meta.json`, deliberately: the sidecar describes the
+ * envelope (down to a content hash, when grouped), so a reader must never find
+ * a sidecar whose envelope does not exist yet.
+ */
+export async function writeRunInto(runDir, outputRoot, envelope, meta) {
+    await mkdir(runDir, { recursive: true });
+    const envelopePath = join(runDir, 'run.json');
+    const metaPath = join(runDir, 'meta.json');
+    const fullMeta = { ...meta, outputDir: outputRoot, envelopePath };
+    // Pretty-printed on purpose. This file is meant to be opened, read, diffed and
+    // kept by the person who ran the suite — it is the free layer's artifact, not
+    // a wire frame. Trailing newlines because it is a text file in a git repo.
+    await writeFileAtomic(envelopePath, `${JSON.stringify(envelope, null, 2)}\n`);
+    await writeFileAtomic(metaPath, `${JSON.stringify(fullMeta, null, 2)}\n`);
+    return { runDir, envelopePath, metaPath };
+}
+/**
+ * Only the latest run stays on disk. P1-6.4 draws the free-layer boundary at
+ * "no local history, ever" — and letting timestamped run directories pile up
+ * would have the SDK itself building the organised time-series that boundary
+ * forbids, run by run, on every machine and every persistent CI box.
+ *
+ * Pruning happens after the new run is fully written, never before: a crash
+ * mid-write costs the customer nothing, because the previous good run is still
+ * there. And only *older* runs go — a directory sorting after ours belongs to a
+ * concurrent or clock-skewed run that is not ours to delete.
+ *
+ * Best-effort on purpose. A directory we cannot remove (permissions, a file
+ * held open on Windows) must never fail the run that just wrote successfully.
+ */
+const RUN_DIR_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z$/;
+/** A run-group directory, keyed by the orchestrator's id rather than a clock. */
+export const GROUP_DIR_PATTERN = /^group-[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * A group dir is prunable only by AGE, never by looking finished.
+ *
+ * "Looks complete" is not knowable from the outside: a group between two
+ * sequential lanes looks exactly like a finished one, and pruning it there
+ * would let the next lane recreate the dir empty and merge a hollow run that
+ * claims nothing is missing. Staleness — no file touched for a day — is the
+ * only signal that cannot fire on a live group.
+ */
+const GROUP_STALE_MS = 24 * 60 * 60 * 1000;
+export async function pruneRuns(runsRoot, options) {
+    let entries;
+    try {
+        entries = await readdir(runsRoot, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    const doomed = [];
+    for (const entry of entries) {
+        // Only things we recognise as our own run directories. A stray file or a
+        // folder the customer put there themselves is theirs, not ours to prune.
+        if (!entry.isDirectory())
+            continue;
+        if (RUN_DIR_PATTERN.test(entry.name)) {
+            /*
+             * Timestamp dirs keep the original rule: only *older* ones go — a
+             * directory sorting after ours belongs to a concurrent or clock-skewed
+             * run that is not ours to delete. When the current run is a group, every
+             * timestamp dir predates the group's logical run and is prunable once
+             * the group has written (`currentName` carries the merge's timestamp).
+             */
+            if (options.currentName && entry.name < options.currentName)
+                doomed.push(entry.name);
+            continue;
+        }
+        if (GROUP_DIR_PATTERN.test(entry.name)) {
+            if (entry.name === options.currentGroupName)
+                continue;
+            if (await groupIsStale(join(runsRoot, entry.name), now))
+                doomed.push(entry.name);
+        }
+    }
+    await Promise.all(doomed.map((name) => rm(join(runsRoot, name), { recursive: true, force: true }).catch(() => { })));
+}
+/** Stale means nothing in the dir (or its parts) has been touched for a day. */
+async function groupIsStale(groupDir, now) {
+    let newest = 0;
+    for (const dir of [groupDir, join(groupDir, 'parts')]) {
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            try {
+                const s = await stat(join(dir, name));
+                if (s.mtimeMs > newest)
+                    newest = s.mtimeMs;
+            }
+            catch {
+                // A file vanishing mid-scan means the group is live. Do not prune it.
+                return false;
+            }
+        }
+    }
+    // An unreadable or empty dir is not evidence of staleness; leave it alone
+    // until it has an observable age.
+    return newest > 0 && now - newest > GROUP_STALE_MS;
+}
+/**
+ * The HTML report, written beside `run.json` in the same run directory.
+ *
+ * Separate from `writeRun` rather than folded into it, because the two must be
+ * allowed to fail independently: a template bug must cost the customer the
+ * report and nothing else — never the envelope, and never the terminal
+ * summary. The reporter wraps this call in its own try.
+ */
+export async function writeHtmlReport(runDir, html) {
+    const reportPath = join(runDir, 'report.html');
+    // Atomic like the JSON artifacts: a grouped run rewrites this file while a
+    // person may have it open, and a browser reading a half-written report would
+    // render something that looks finished and is not.
+    await writeFileAtomic(reportPath, html);
+    return reportPath;
+}
+/**
+ * The visual contact sheet, written beside `report.html` in the same run
+ * directory.
+ *
+ * Its own file and its own failure domain, for the same reason the HTML report
+ * has one: a template bug in the sheet must cost the customer the sheet and
+ * nothing else — not the envelope, not the accessibility report, not the
+ * terminal summary. The reporter wraps this call in its own try.
+ *
+ * The name is stable and boring on purpose. It is a path people put in a
+ * `.gitignore`, a CI artifact glob and a bookmark, and renaming it later would
+ * break all three.
+ */
+export async function writeScreensReport(runDir, html) {
+    const screensPath = join(runDir, 'screens.html');
+    await writeFileAtomic(screensPath, html);
+    return screensPath;
+}
+/**
+ * The summary as markdown, at a path the caller named.
+ *
+ * Directed by `SETSQUARE_SUMMARY_MD` and written nowhere by default, because this
+ * is not one of the run's artefacts — it is a second rendering of the terminal
+ * summary for a CI job-summary panel, and a file that appears in every
+ * `.setsquare/runs/` directory whether anyone asked for it or not would be one
+ * more thing to explain and one more thing to gitignore.
+ *
+ * `resolve` against the base directory rather than trusting the string, and its own
+ * failure domain like every other optional artefact here: a summary that could not
+ * be written must cost the summary and nothing else.
+ */
+export async function writeSummaryMarkdown(baseDir, path, markdown) {
+    const full = resolve(baseDir, path);
+    await mkdir(dirname(full), { recursive: true });
+    await writeFileAtomic(full, markdown.endsWith('\n') ? markdown : `${markdown}\n`);
+    return full;
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

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

package/dist/perf.d.ts

@@ -0,0 +1,11 @@
+import type { Perf } from '@setsquare/schema';
+import type { Page } from '@playwright/test';
+/**
+ * Capture performance for the page a scan is looking at.
+ *
+ * Returns `undefined` rather than an empty object when nothing could be measured,
+ * so the schema's optional block stays genuinely absent instead of arriving as a
+ * shell that implies a measurement took place.
+ */
+export declare function capturePerf(page: Page): Promise<Perf | undefined>;
+//# sourceMappingURL=perf.d.ts.map

package/dist/perf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf.d.ts","sourceRoot":"","sources":["../src/perf.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAoI7C;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAmBvE"}

package/dist/perf.js

@@ -0,0 +1,150 @@
+/**
+ * Pillar 3's capture block.
+ *
+ * These are CI-LAB MEASUREMENTS, not RUM. They are trend-comparable to
+ * themselves over time on the same runner, and they are never comparable across
+ * engines — which is why the engine is structurally attached (a scan resolves to
+ * a test result through `testId`, and that carries the engine) rather than being
+ * a field that could be dropped or averaged over.
+ *
+ * Nothing displays these in P1. They are captured now because the fixture is
+ * already on the page at scan time so the marginal cost is near zero, and because
+ * history not captured is history permanently lost — the same reasoning that put
+ * pass rows in from the first release.
+ *
+ * The governing rule here is stronger than usual: **a number that is absent is
+ * better than a number that is wrong.** A perf block is optional in the schema
+ * precisely so an engine that cannot measure something says nothing about it.
+ */
+/**
+ * Read timings from the page.
+ *
+ * Two capability traps discovered by measuring rather than reading docs, both of
+ * which produce fabricated evidence if you get them wrong:
+ *
+ *  1. `performance.getEntriesByType('largest-contentful-paint')` returns NOTHING,
+ *     in every engine. LCP entries are only ever delivered to a
+ *     `PerformanceObserver`. Reading the buffer looks like it works and silently
+ *     yields no LCP forever.
+ *
+ *  2. `observer.observe({ type })` does NOT throw for a type the engine does not
+ *     support — it simply never fires. So a naive CLS sum over zero entries
+ *     returns `0`, and `0` is indistinguishable from a genuinely perfect layout.
+ *     Firefox and WebKit do not implement `layout-shift`; both would have
+ *     reported flawless CLS on every page forever.
+ *
+ * `PerformanceObserver.supportedEntryTypes` is the reliable gate, and it is
+ * honest in both directions: it correctly reports `layout-shift` as unsupported
+ * in Firefox and WebKit, and `largest-contentful-paint` as supported in all
+ * three — which measurement confirms.
+ */
+const CAPTURE_SCRIPT = async (settleMs) => {
+    const supported = (type) => {
+        try {
+            return (PerformanceObserver.supportedEntryTypes ?? []).includes(type);
+        }
+        catch {
+            return false;
+        }
+    };
+    const navigation = performance.getEntriesByType('navigation')[0];
+    if (!navigation)
+        return null;
+    /*
+     * The navigation entry describes the DOCUMENT that was loaded, and it does not
+     * change when a single-page app pushes a new route. Measured: after a
+     * `pushState` to `/spa/one`, the entry is still named `/spa`.
+     *
+     * So if the entry's name no longer matches where we are, these timings belong
+     * to a different route and attributing them here would invent a page load that
+     * never happened. Reported as "no perf" instead, which is true.
+     */
+    if (navigation.name !== location.href)
+        return null;
+    const out = {};
+    const finite = (value, key) => {
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+            out[key] = value;
+    };
+    finite(navigation.responseStart, 'ttfbMs');
+    finite(navigation.domContentLoadedEventEnd, 'domContentLoadedMs');
+    finite(navigation.loadEventEnd, 'loadMs');
+    const observe = (type, onEntry) => new Promise((resolve) => {
+        if (!supported(type))
+            return resolve();
+        let observer;
+        try {
+            observer = new PerformanceObserver((list) => {
+                for (const entry of list.getEntries())
+                    onEntry(entry);
+            });
+            // `buffered` replays entries recorded before this observer existed, which
+            // is the only way to see an LCP that happened during page load.
+            observer.observe({ type, buffered: true });
+        }
+        catch {
+            return resolve();
+        }
+        setTimeout(() => {
+            try {
+                observer?.disconnect();
+            }
+            catch {
+                // Already gone. Nothing to do.
+            }
+            resolve();
+        }, settleMs);
+    });
+    let lcp;
+    await observe('largest-contentful-paint', (entry) => {
+        // The LAST candidate wins: LCP is redefined as larger elements render.
+        lcp = entry.startTime;
+    });
+    finite(lcp, 'lcpMs');
+    if (supported('layout-shift')) {
+        let cls = 0;
+        await observe('layout-shift', (entry) => {
+            const shift = entry;
+            // Shifts within 500ms of user input are excluded by the CLS definition —
+            // a layout change the user asked for is not a layout instability.
+            if (!shift.hadRecentInput && typeof shift.value === 'number')
+                cls += shift.value;
+        });
+        // Zero is a REAL measurement here, and only here: the engine supports the
+        // entry type, so "no shifts" is a finding rather than a silence.
+        out['cls'] = cls;
+    }
+    return out;
+};
+/** How long to wait for buffered observer entries. Long enough; not long enough to notice. */
+const SETTLE_MS = 60;
+/**
+ * Capture performance for the page a scan is looking at.
+ *
+ * Returns `undefined` rather than an empty object when nothing could be measured,
+ * so the schema's optional block stays genuinely absent instead of arriving as a
+ * shell that implies a measurement took place.
+ */
+export async function capturePerf(page) {
+    try {
+        const raw = await page.evaluate(CAPTURE_SCRIPT, SETTLE_MS);
+        if (!raw || Object.keys(raw).length === 0)
+            return undefined;
+        // Round to whole milliseconds; sub-millisecond precision on a CI runner is
+        // noise dressed as detail. CLS is unitless and keeps three decimals.
+        const perf = {};
+        for (const [key, value] of Object.entries(raw)) {
+            if (key === 'cls')
+                perf.cls = Math.round(value * 1000) / 1000;
+            else
+                perf[key] = Math.round(value);
+        }
+        return perf;
+    }
+    catch {
+        // A closed page, a navigation mid-read, a CSP that blocked evaluation. None
+        // of it is worth a warning, and none of it justifies inventing a number.
+        return undefined;
+    }
+}
+//# sourceMappingURL=perf.js.map

package/dist/perf.js.map

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

package/dist/reading-level.d.ts

@@ -0,0 +1,73 @@
+import type { Page } from '@playwright/test';
+import type { AxeFinding } from '@setsquare/schema';
+/**
+ * WCAG 3.1.5 Reading Level (AAA), as an honest heuristic.
+ *
+ * The SC's normative bar is text readable "without lower secondary education"
+ * — ISCED level 2, roughly nine years of schooling — measured *after removing
+ * proper names and titles*, and satisfiable by supplemental content or a
+ * simpler alternate version. No formula measures any of that. What formulas
+ * measure is word and sentence statistics, which approximate a reading grade,
+ * which approximates the bar. Three honesty rules follow:
+ *
+ *   1. **Never a violation.** The finding is always `incomplete` — a person
+ *      decides 3.1.5, this check only tells them where to look.
+ *   2. **Fire only above a margin.** Automated scoring cannot remove proper
+ *      names, which skews grades HIGH, so the finding fires a full grade above
+ *      the target (FK > 10 against a target of 9; LIX > 48 against 44). A page
+ *      at 9.4 is not a finding; a page at 11 is worth a person's time.
+ *   3. **Language-gated.** Flesch–Kincaid is calibrated for English; LIX is
+ *      the conventional measure for the Nordic languages (thresholds are
+ *      convention, not W3C-blessed: <35 easy, 45+ difficult, "lower
+ *      secondary" ≈ 44). This is the same routing Sa11y documents publicly —
+ *      the behaviour, never its GPL code. An unsupported or missing `lang`
+ *      skips silently: missing `lang` is already an axe violation (3.1.1),
+ *      and scoring text in a language the formula was never calibrated for
+ *      would manufacture a number.
+ *
+ * Extraction happens in-page (main content only — scoring navigation chrome
+ * would grade the menu, not the writing); scoring happens Node-side in the
+ * worker, which keeps text-readability out of the injected bundle and the
+ * page's text out of everything: only the scores and the language ever leave
+ * the worker.
+ */
+/** The one node the page-level finding points at. */
+export declare const READING_LEVEL_RULE_ID = "setsquare-reading-level";
+/** Versioned for the ruleset digest: bump when scoring or thresholds change. */
+export declare const READING_LEVEL_CHECK_VERSION = "setsquare-reading-level@1";
+export interface ExtractedText {
+    lang: string;
+    text: string;
+}
+export interface ReadingLevelScore {
+    lang: string;
+    formula: 'flesch-kincaid' | 'lix';
+    score: number;
+    target: number;
+    words: number;
+    flagged: boolean;
+}
+/**
+ * Main-content text and the document language, from the live page.
+ *
+ * `<main>`/`role=main` when the page declares one; otherwise the body minus
+ * nav/header/footer/aside, which is the same "grade the writing, not the
+ * chrome" heuristic every readability tool uses. Returns undefined on any
+ * failure — a page that cannot be read is a page that is not scored.
+ */
+export declare function extractMainText(page: Page): Promise<ExtractedText | undefined>;
+export declare function scoreReadingLevel(extracted: ExtractedText): ReadingLevelScore | undefined;
+/**
+ * The heuristic finding, only when the score clears the margin.
+ *
+ * Page-level, so `targets` names one node — the page — with no selectors. A
+ * `nodeCount` of 0 would make a surface failing only this check render as
+ * clean, which is the false pass this product exists to avoid.
+ */
+export declare function readingLevelFinding(score: ReadingLevelScore): AxeFinding | undefined;
+/**
+ * The whole check: extract, gate, score, and return a finding or nothing.
+ * Never throws — a readability heuristic must not be able to cost a scan.
+ */
+export declare function runReadingLevel(page: Page): Promise<AxeFinding | undefined>;
+//# sourceMappingURL=reading-level.d.ts.map

package/dist/reading-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reading-level.d.ts","sourceRoot":"","sources":["../src/reading-level.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAMpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,qDAAqD;AACrD,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAC/D,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,8BAA+B,CAAC;AAaxE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,gBAAgB,GAAG,KAAK,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAsBpF;AAmBD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,aAAa,GAAG,iBAAiB,GAAG,SAAS,CAoCzF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,GAAG,UAAU,GAAG,SAAS,CAsCpF;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAYjF"}