@setsquare/review-sdk 0.0.1

package/dist/contract.d.ts

@@ -0,0 +1,334 @@
+import type { AxeFinding, AxeScan, PageRuntime, Perf, ScanDocument, RuleInapplicable, RulePass, RunIngestRequest, UnscannedRow } from '@setsquare/schema';
+import type { WcagTarget } from './rules.js';
+import type { DeclaredAxes } from '@setsquare/schema/conformance';
+import type { OverheadFacts, SuiteFacts } from './suite.js';
+/**
+ * The fixture ↔ reporter contract.
+ *
+ * The seam is CAPTURE vs INTERPRETATION, and it is drawn here rather than
+ * anywhere convenient. The fixture runs in N worker processes and observes; the
+ * reporter runs once in the main process and decides. Everything that is a
+ * policy — dedupe, precedence, surface normalisation, persona and theme
+ * resolution, envelope assembly, output — belongs to the reporter, because a
+ * policy implemented in two places is a policy that will diverge.
+ *
+ * That is why a `ScanRecord` carries raw observations (`observed`) and not
+ * conclusions. The fixture can see things the reporter never can — the live DOM,
+ * a `data-theme` attribute mid-test, the order navigations actually happened in
+ * — so it records them faithfully and forms no opinion about what they mean.
+ *
+ * Sanitisation is the single exception to "the fixture decides nothing", and it
+ * is deliberate: page-derived strings must be capped and constrained BEFORE they
+ * cross the attachment boundary, because an attachment is also written into
+ * Playwright's own HTML report and trace. Letting an unbounded hostile selector
+ * out of the worker and cleaning it up later would mean it had already been
+ * written somewhere we do not control. Sanitisation is a pure function, so it
+ * carries no state across the seam.
+ */
+/** Attachment name. Namespaced so it cannot collide with a customer's own. */
+export declare const SCAN_RECORD_ATTACHMENT = "setsquare.scan-record";
+/**
+ * Bumped when the record shape changes incompatibly.
+ *
+ * Fixture and reporter are always the same install, so this is not a
+ * compatibility mechanism in the wire-format sense — it is a loud failure when
+ * a stale build lingers in a customer's `node_modules` after an upgrade, which
+ * would otherwise present as mysteriously missing evidence.
+ */
+export declare const SCAN_RECORD_VERSION = 1;
+/** A single main-frame navigation, as the fixture saw it happen. */
+export interface ObservedNavigation {
+    url: string;
+    /** Milliseconds since the context was created. Relative, so no clock is trusted. */
+    atMs: number;
+    /**
+     * How the URL came to change. `pushState`/`popstate` never fire a real
+     * navigation, and a trigger that listens only for `framenavigated` misses
+     * every SPA route change — which is most of a modern app.
+     */
+    kind: 'navigation' | 'pushState' | 'replaceState' | 'popstate';
+}
+/** What the fixture saw, with no interpretation applied. */
+export interface ObservedContext {
+    /** Playwright project name. The reporter maps this to persona/theme; the fixture does not. */
+    project: string;
+    engine: 'chromium' | 'firefox' | 'webkit';
+    /** Every main-frame URL this page held, in order. */
+    navigations: ObservedNavigation[];
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * `data-theme` (and friends) as read from the live document. The reporter
+     * ranks this BELOW an explicit config statement — an in-test toggle is
+     * truthful, but a customer telling us outranks us sniffing.
+     */
+    observedTheme?: string;
+}
+/**
+ * What the fixture saw a page do, attached at teardown.
+ *
+ * Per page rather than per test because a single test may open several — the
+ * reference implementation drives two sessions in one spec — and collapsing them
+ * would attribute one page's evidence to another's context.
+ */
+export interface ObservationRecord {
+    recordVersion: typeof SCAN_RECORD_VERSION;
+    kind: 'observation';
+    observed: ObservedContext;
+    /**
+     * Surfaces this page reached and could not scan, aggregated by reason.
+     *
+     * Absent means this page recorded no ledger events — NOT that nothing went
+     * unscanned, which is what an empty array would claim. The reporter sums these
+     * across records, which it must do for run groups anyway.
+     */
+    unscanned?: UnscannedRow[];
+    /** Events dropped past the ledger's distinct-row cap. Absent means none were. */
+    unscannedOmitted?: number;
+}
+/** Where a scan happened, as the page reported it at that moment. */
+export interface ScanPageFacts {
+    project: string;
+    engine: ObservedContext['engine'];
+    url: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    observedTheme?: string;
+}
+/**
+ * What the customer said about a scan they asked for.
+ *
+ * Separate from what we observed, and deliberately so: an explicit statement
+ * outranks inference everywhere, and keeping the two apart is what lets the
+ * reporter apply that precedence instead of guessing which is which.
+ */
+export interface DeclaredContext {
+    surface: string;
+    state?: string;
+    theme?: string;
+    persona?: string;
+}
+/**
+ * The result of one `setsquare.scan()` call — attached from the test body rather than
+ * from teardown, because that is where the customer asked for it.
+ *
+ * Carries its own `axeVersion` and `rulesetDigest`. Per scan, not per run: a
+ * sharded run can in principle be produced by runners with drifted dependencies,
+ * and a finding whose ruleset we cannot name is a finding we cannot defend.
+ */
+export interface ScanResultRecord {
+    recordVersion: typeof SCAN_RECORD_VERSION;
+    kind: 'scan';
+    page: ScanPageFacts;
+    declared: DeclaredContext;
+    /** Groups scans of one page load, so perf is not counted once per state. */
+    visitRef: string;
+    axeVersion: string;
+    rulesetDigest: string;
+    /** The conformance level assessed. Stated, never inferred from what was found. */
+    wcagTarget: WcagTarget;
+    findings: AxeFinding[];
+    passes: RulePass[];
+    /** Rules that ran and found nothing to check — EARL's inapplicable. */
+    inapplicable?: RuleInapplicable[];
+    /** Present on the FIRST scan of a page load only. Absent is valid and common. */
+    perf?: Perf;
+    /**
+     * What the page did while we were on it. First scan of a page load only, for
+     * the same reason `perf` is: these are facts about a LOAD, not about a scan.
+     */
+    runtime?: PageRuntime;
+    /** Document-level values for cross-surface consistency. */
+    document?: ScanDocument;
+    /**
+     * What this scan cost us, in milliseconds.
+     *
+     * Local-only — it never reaches the wire, because it is a measurement about US
+     * rather than about the customer's application, and the next run reproduces it.
+     * It exists so a run can state its own overhead instead of the customer having
+     * to wonder, which is a trust signal and pre-empts the "your SDK slowed our CI"
+     * story.
+     *
+     * Time SPENT, never time ADDED: these are summed across workers and scanning is
+     * concurrent with the customer's own tests, so the total is not wall clock added
+     * to the run. Nothing may render it as a delta or a percentage — that needs a
+     * control run, which is what `SETSQUARE_DISABLED` is for.
+     */
+    cost?: {
+        totalMs: number;
+        axeMs: number;
+        probesMs?: number;
+    };
+    /** How the page was judged ready. Absent on explicit scans — no heuristic ran. */
+    settle?: AxeScan['settle'];
+}
+export type ScanRecord = ObservationRecord | ScanResultRecord;
+/**
+ * The disk envelope's sidecar.
+ *
+ * Local-only facts live here and NOWHERE in `run.json`, which is the ingest
+ * request body byte-for-byte. That separation is what lets the SDK's own test
+ * suite validate the artifact against the generated JSON Schema and mean it: the
+ * file we write is the file the platform would have received, so "minus nothing"
+ * is a checkable claim rather than a description.
+ */
+/**
+ * What the merge can honestly say about a run group's coverage.
+ *
+ * `complete` is only claimable against a DECLARED census (`SETSQUARE_RUN_PARTS`):
+ * without one, an invocation that crashed before it ever announced itself is
+ * invisible, and "no invocation known to be in flight" is not "complete".
+ * `unknown` is that sentence said out loud. `partial` means evidence is known
+ * to be absent — absent, never clean.
+ */
+export type GroupCoverage = 'complete' | 'partial' | 'unknown';
+/** One invocation's contribution, as the merged sidecar accounts for it. */
+export interface RunGroupPartMeta {
+    partId: string;
+    lane?: string;
+    /** The label used to namespace this part's testIds in the merged envelope. */
+    label: string;
+    startedAt: string;
+    generatedAt: string;
+    durationMs: number;
+    /** Playwright's own verdict for the invocation. `interrupted` taints the merge. */
+    playwrightStatus: 'passed' | 'failed' | 'timedout' | 'interrupted' | 'unknown';
+    tests: number;
+    scans: number;
+    plannedTests?: number;
+    /** That invocation's own Playwright HTML report, when it made one. */
+    reportPath?: string;
+}
+/**
+ * The group accounting block of a merged run's sidecar.
+ *
+ * Local-only, like everything else in the sidecar. The envelope stays the pure
+ * wire body; which invocations produced it is provenance, and provenance lives
+ * here.
+ */
+export interface RunGroupMeta {
+    /** The orchestrator's id, after filesystem sanitisation. */
+    id: string;
+    /** The declared invocation count, or null when none was declared. */
+    expectedParts: number | null;
+    /** Invocations that announced themselves (wrote a begun marker). */
+    begun: number;
+    /** Invocations whose results made it into this merge. */
+    completed: number;
+    /** partIds that began but have no readable part — crashed, still running, or torn. */
+    missing: string[];
+    /** partIds excluded because they are hours older than the newest part. */
+    stale: string[];
+    coverage: GroupCoverage;
+    /** Wall-clock span from the earliest start to the latest finish across parts. */
+    spanMs: number;
+    /** Content hash of the run.json this sidecar describes. A mismatch means a torn pair. */
+    runJsonSha256: string;
+    parts: RunGroupPartMeta[];
+}
+export interface RunMeta {
+    /** Never a run id. The server assigns those, and no server was involved (P1-17.7). */
+    runId: null;
+    /** Said out loud, because a JSON file on disk has no other way to say it. */
+    submitted: false;
+    sdkVersion: string;
+    generatedAt: string;
+    outputDir: string;
+    envelopePath: string;
+    durationMs: number;
+    counts: {
+        tests: number;
+        pages: number;
+        scans: number;
+        /**
+         * How many tests the run intended to execute, when Playwright told us.
+         *
+         * Local-only for now, in the sidecar rather than the envelope. "82 of 112
+         * tests never ran" is genuinely evidence-relevant and will want a home on the
+         * wire eventually — but that is a schema change with a both-runtimes bar
+         * behind it, and the local path can be honest today without one.
+         */
+        plannedTests?: number;
+    };
+    /**
+     * The Playwright config this run came from, relative to `outputDir`'s base.
+     *
+     * Local-only, and it exists so a repro command can name the right `-c`. A
+     * monorepo with several configs writes several `.setsquare` directories, and a
+     * consumer reading one of them otherwise has no way to know which config
+     * produced it — which makes every derived `playwright test` invocation a guess.
+     *
+     * Absent when Playwright gave us no `configFile` (an inline config), in which
+     * case the honest output omits `-c` rather than inventing a path.
+     */
+    configFile?: string;
+    /**
+     * What the run cost us, and what it spent that cost on.
+     *
+     * **Time SPENT, never time ADDED.** These are summed across workers while
+     * scanning runs concurrently with the customer's own tests, so the total is not
+     * wall clock added to the suite. Nothing may render a delta or a percentage from
+     * it: a delta needs a control run, which is what `SETSQUARE_DISABLED=1` exists
+     * to provide. Printing an unmeasurable delta would be the exact sin `perf.ts`
+     * was written to prevent.
+     */
+    overhead?: OverheadFacts;
+    /**
+     * Suite-shaped facts from Playwright's own result object.
+     *
+     * Local-only because these describe the RUN's mechanics rather than the
+     * customer's application. `workerIndex` and `failure` do reach the wire, because
+     * they are per-test evidence a platform would trend; these aggregates are
+     * derivable from them and are precomputed only so the three renderers cannot
+     * disagree.
+     */
+    suite?: SuiteFacts;
+    /**
+     * Which axes this run's evidence actually spans, and which it never touched.
+     *
+     * `declaredAxes` comes from the customer's own theme/persona maps and project
+     * list, and is the ONLY real denominator available on any axis — "4 personas
+     * configured, 1 with evidence" is defensible where anything derived from
+     * observed values alone is not. Absent means we could not read the config, and
+     * renderers must then suppress the line rather than reporting N = M.
+     *
+     * `unmeasuredAxes` names Playwright `use` options that would create an evidence
+     * axis and were not set by any project — `forcedColors`, `reducedMotion`,
+     * `colorScheme`. Saying "those axes are unmeasured in this run" is true, costs
+     * nothing, and is a great deal more honest than the alternative of quietly
+     * scanning one setting and calling it coverage.
+     */
+    coverage?: {
+        /**
+         * Keyed by AXIS NAME (`theme`, `persona`, `state`), matching
+         * `conformance.ts`'s own vocabulary so the value can be handed straight to
+         * `axisCoverage` without translation. An earlier draft used plural nouns and
+         * had to be reconciled — two shapes for one concept is precisely the drift
+         * this codebase keeps single sources of truth to avoid.
+         */
+        declaredAxes?: DeclaredAxes;
+        /**
+         * Playwright project names.
+         *
+         * Kept apart from `declaredAxes` because a project is NOT an axis — it is the
+         * provenance a theme or persona is resolved FROM. Filing it under axes would
+         * make "3 of 5 projects have evidence" look like a coverage figure on the
+         * grid, which it is not.
+         */
+        declaredProjects?: string[];
+        unmeasuredAxes: string[];
+    };
+    /** Anything the SDK could not determine, named rather than guessed. */
+    unknowns: string[];
+    /** Warnings raised during the run. The SDK never fails a build; it says so here. */
+    warnings: string[];
+    /** Present only on merged run-group artifacts. See `RunGroupMeta`. */
+    group?: RunGroupMeta;
+}
+/** Convenience alias — the wire body, exactly as `packages/schema` defines it. */
+export type RunEnvelope = RunIngestRequest;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

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

package/dist/contract.js

@@ -0,0 +1,35 @@
+/**
+ * The fixture ↔ reporter contract.
+ *
+ * The seam is CAPTURE vs INTERPRETATION, and it is drawn here rather than
+ * anywhere convenient. The fixture runs in N worker processes and observes; the
+ * reporter runs once in the main process and decides. Everything that is a
+ * policy — dedupe, precedence, surface normalisation, persona and theme
+ * resolution, envelope assembly, output — belongs to the reporter, because a
+ * policy implemented in two places is a policy that will diverge.
+ *
+ * That is why a `ScanRecord` carries raw observations (`observed`) and not
+ * conclusions. The fixture can see things the reporter never can — the live DOM,
+ * a `data-theme` attribute mid-test, the order navigations actually happened in
+ * — so it records them faithfully and forms no opinion about what they mean.
+ *
+ * Sanitisation is the single exception to "the fixture decides nothing", and it
+ * is deliberate: page-derived strings must be capped and constrained BEFORE they
+ * cross the attachment boundary, because an attachment is also written into
+ * Playwright's own HTML report and trace. Letting an unbounded hostile selector
+ * out of the worker and cleaning it up later would mean it had already been
+ * written somewhere we do not control. Sanitisation is a pure function, so it
+ * carries no state across the seam.
+ */
+/** Attachment name. Namespaced so it cannot collide with a customer's own. */
+export const SCAN_RECORD_ATTACHMENT = 'setsquare.scan-record';
+/**
+ * Bumped when the record shape changes incompatibly.
+ *
+ * Fixture and reporter are always the same install, so this is not a
+ * compatibility mechanism in the wire-format sense — it is a loud failure when
+ * a stale build lingers in a customer's `node_modules` after an upgrade, which
+ * would otherwise present as mysteriously missing evidence.
+ */
+export const SCAN_RECORD_VERSION = 1;
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,sBAAsB,GAAG,uBAAuB,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC"}

package/dist/dedupe.d.ts

@@ -0,0 +1,79 @@
+import type { AxeScan } from '@setsquare/schema';
+/**
+ * Which scan survives when several describe the same thing.
+ *
+ * This file exists because of one observation about the reference
+ * implementation, made before any code was written: **Eos's `warmup` project
+ * visits every entry route in the application first**, purely to pay
+ * cold-compile costs. Under the dedupe the phase plan originally specified —
+ * keyed on URL, first-wins — every surface's evidence in the run would have come
+ * from that shallow warm-up pass, and every real spec's scan would have been
+ * discarded. Not an edge case: the default outcome on the target we chose.
+ *
+ * So the rule is keyed on the full context tuple, and it is BEST-wins rather than
+ * first-wins.
+ */
+export interface DedupeInput {
+    scan: AxeScan;
+    /** The Playwright project that produced it. */
+    project: string;
+    /** True when the project exists to prepare the suite rather than to test it. */
+    infrastructure: boolean;
+    /** Order encountered, used only to break ties deterministically. */
+    index: number;
+}
+/**
+ * Identity of a scan for dedupe purposes: WHERE it looked, in WHAT context.
+ *
+ * The full tuple, not the URL alone. Two scans of one surface under different
+ * themes are different evidence — collapsing them reports a themed surface as
+ * clean when only one of its themes was — and the same is true of state and
+ * persona.
+ *
+ * The *where* is the ROUTE PATTERN, not the surface name, and that distinction
+ * was bought with a bug. The surface name is something we choose: an explicit
+ * `setsquare.scan('hostile-page')` and the auto-scan of the very same URL produced
+ * `hostile-page` and `hostile`, two different strings, so both survived and every
+ * count in the run was doubled. Keying on the name lets our own naming decide
+ * what counts as the same page — and it gets it wrong precisely when a customer
+ * has told us something, which is the one case that must work.
+ *
+ * The route pattern is the page's identity as the application defines it, and
+ * parameterised routes are normalised into it already (`/items/42/edit` →
+ * `/items/:id/edit`), so it collapses exactly what should collapse. The surface
+ * name then comes from whichever scan WINS, which is how an explicit label ends
+ * up on the row instead of competing with an inferred one for a place in the list.
+ */
+export declare function contextKey(scan: AxeScan): string;
+/**
+ * Collapse scans to one per context, keeping the best.
+ *
+ * Ties are broken by LAST-encountered, which is just as deterministic as first
+ * and materially more correct: a later scan of the same context has had longer to
+ * settle. Output order still follows first encounter, so two runs of the same
+ * suite produce byte-identical, diffable envelopes.
+ */
+export declare function dedupeScans(inputs: DedupeInput[]): {
+    kept: AxeScan[];
+    dropped: number;
+};
+/**
+ * Projects that exist to prepare the suite rather than to test it.
+ *
+ * Derived from the customer's OWN dependency graph rather than from a
+ * configuration list they would have to remember to write: in Playwright, a
+ * project named in another project's `dependencies` is by definition setup for
+ * it. On the reference implementation this identifies `preflight`, `setup`,
+ * `auth` and `warmup` with no configuration at all — which is the difference
+ * between a rule that works on the first run and one that works after someone
+ * reads the docs.
+ *
+ * A suite where every project depends on every other would mark them all as
+ * infrastructure; that is degenerate enough not to be worth guarding, and the
+ * effect would only be to make the scores uniform again.
+ */
+export declare function infrastructureProjects(projects: readonly {
+    name: string;
+    dependencies?: readonly string[];
+}[]): Set<string>;
+//# sourceMappingURL=dedupe.d.ts.map

package/dist/dedupe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../src/dedupe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,cAAc,EAAE,OAAO,CAAC;IACxB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAGhD;AA6BD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG;IAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAoBvF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,GACtE,GAAG,CAAC,MAAM,CAAC,CAQb"}

package/dist/dedupe.js

@@ -0,0 +1,102 @@
+/**
+ * Identity of a scan for dedupe purposes: WHERE it looked, in WHAT context.
+ *
+ * The full tuple, not the URL alone. Two scans of one surface under different
+ * themes are different evidence — collapsing them reports a themed surface as
+ * clean when only one of its themes was — and the same is true of state and
+ * persona.
+ *
+ * The *where* is the ROUTE PATTERN, not the surface name, and that distinction
+ * was bought with a bug. The surface name is something we choose: an explicit
+ * `setsquare.scan('hostile-page')` and the auto-scan of the very same URL produced
+ * `hostile-page` and `hostile`, two different strings, so both survived and every
+ * count in the run was doubled. Keying on the name lets our own naming decide
+ * what counts as the same page — and it gets it wrong precisely when a customer
+ * has told us something, which is the one case that must work.
+ *
+ * The route pattern is the page's identity as the application defines it, and
+ * parameterised routes are normalised into it already (`/items/42/edit` →
+ * `/items/:id/edit`), so it collapses exactly what should collapse. The surface
+ * name then comes from whichever scan WINS, which is how an explicit label ends
+ * up on the row instead of competing with an inferred one for a place in the list.
+ */
+export function contextKey(scan) {
+    const { surface, urlPattern, theme, persona, state } = scan.context;
+    return [urlPattern ?? surface, theme ?? '', persona ?? '', state ?? ''].join('\u0000');
+}
+/**
+ * How good a scan is as evidence for its context, higher being better.
+ *
+ * Deliberately NOT "how many findings it has". Ranking by finding count would
+ * make the noisiest scan win, which rewards scanning a page mid-render — the
+ * exact failure mode the settle heuristic exists to prevent.
+ */
+function score(input) {
+    let value = 0;
+    // A customer who called `setsquare.scan('job-editor', { state: … })` knows something
+    // we could never infer. It outranks anything automatic.
+    if (input.scan.context.surfaceSource === 'explicit')
+        value += 1000;
+    // A spec that tests the surface beats a project that merely warmed it.
+    if (!input.infrastructure)
+        value += 100;
+    // A scan that reached the page quietly beats one the ceiling cut short.
+    if (!input.scan.settle?.settleTimedOut)
+        value += 10;
+    // Richer context is more useful evidence, all else equal.
+    if (input.scan.context.persona)
+        value += 1;
+    if (input.scan.context.theme)
+        value += 1;
+    return value;
+}
+/**
+ * Collapse scans to one per context, keeping the best.
+ *
+ * Ties are broken by LAST-encountered, which is just as deterministic as first
+ * and materially more correct: a later scan of the same context has had longer to
+ * settle. Output order still follows first encounter, so two runs of the same
+ * suite produce byte-identical, diffable envelopes.
+ */
+export function dedupeScans(inputs) {
+    const best = new Map();
+    for (const input of inputs) {
+        const key = contextKey(input.scan);
+        const incumbent = best.get(key);
+        // >= rather than >: on equal evidence the LATER scan wins.
+        //
+        // Later means more settled. A page whose content arrives after its first
+        // quiet window gets scanned twice — once as a shell, once complete — and both
+        // scans score identically, so a first-wins tie-break would enshrine the shell
+        // and report a clean page that is not. Measured on the fixture site: /slow
+        // reported zero violations until this line changed direction.
+        if (!incumbent || score(input) >= score(incumbent))
+            best.set(key, input);
+    }
+    const kept = [...best.values()].sort((a, b) => a.index - b.index).map((input) => input.scan);
+    return { kept, dropped: inputs.length - kept.length };
+}
+/**
+ * Projects that exist to prepare the suite rather than to test it.
+ *
+ * Derived from the customer's OWN dependency graph rather than from a
+ * configuration list they would have to remember to write: in Playwright, a
+ * project named in another project's `dependencies` is by definition setup for
+ * it. On the reference implementation this identifies `preflight`, `setup`,
+ * `auth` and `warmup` with no configuration at all — which is the difference
+ * between a rule that works on the first run and one that works after someone
+ * reads the docs.
+ *
+ * A suite where every project depends on every other would mark them all as
+ * infrastructure; that is degenerate enough not to be worth guarding, and the
+ * effect would only be to make the scores uniform again.
+ */
+export function infrastructureProjects(projects) {
+    const infrastructure = new Set();
+    for (const project of projects) {
+        for (const dependency of project.dependencies ?? [])
+            infrastructure.add(dependency);
+    }
+    return infrastructure;
+}
+//# sourceMappingURL=dedupe.js.map

package/dist/dedupe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.js","sourceRoot":"","sources":["../src/dedupe.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;IACpE,OAAO,CAAC,UAAU,IAAI,OAAO,EAAE,KAAK,IAAI,EAAE,EAAE,OAAO,IAAI,EAAE,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACzF,CAAC;AAED;;;;;;GAMG;AACH,SAAS,KAAK,CAAC,KAAkB;IAC/B,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,qFAAqF;IACrF,wDAAwD;IACxD,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,KAAK,UAAU;QAAE,KAAK,IAAI,IAAI,CAAC;IAEnE,uEAAuE;IACvE,IAAI,CAAC,KAAK,CAAC,cAAc;QAAE,KAAK,IAAI,GAAG,CAAC;IAExC,wEAAwE;IACxE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc;QAAE,KAAK,IAAI,EAAE,CAAC;IAEpD,0DAA0D;IAC1D,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO;QAAE,KAAK,IAAI,CAAC,CAAC;IAC3C,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK;QAAE,KAAK,IAAI,CAAC,CAAC;IAEzC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,MAAqB;IAC/C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAuB,CAAC;IAE5C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEhC,2DAA2D;QAC3D,EAAE;QACF,yEAAyE;QACzE,8EAA8E;QAC9E,8EAA8E;QAC9E,2EAA2E;QAC3E,8DAA8D;QAC9D,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAE7F,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAuE;IAEvE,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;IAEzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,YAAY,IAAI,EAAE;YAAE,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACtF,CAAC;IAED,OAAO,cAAc,CAAC;AACxB,CAAC"}

package/dist/document.d.ts

@@ -0,0 +1,29 @@
+import type { Page } from '@playwright/test';
+import type { ScanDocument } from '@setsquare/schema';
+/**
+ * Document-level facts, read in one round-trip alongside the theme.
+ *
+ * The envelope has always carried rule OUTCOMES — `document-title`,
+ * `html-has-lang`, `bypass` — and never the VALUES, which is why no existing
+ * artefact can say "these three surfaces all claim to be Dashboard". On its own
+ * each of those pages has a perfectly good title; the finding only exists across
+ * surfaces, which is the class of thing only a multi-surface run can see.
+ *
+ * Folded into the theme read rather than added as a second `page.evaluate`: one
+ * protocol round-trip per scan instead of two, on a path that already runs for
+ * every scan in the suite.
+ */
+export interface DocumentFacts {
+    theme?: string;
+    document?: ScanDocument;
+}
+/**
+ * Read theme and document facts from the live page.
+ *
+ * Returns `{}` on any failure. Every field is independently optional, and absence
+ * always means "not captured", never a negative finding — `documentConsistency`
+ * relies on that to keep an uncaptured surface out of `skipLinkAbsent`, which
+ * would otherwise manufacture findings out of our own gaps.
+ */
+export declare function readDocumentFacts(page: Page): Promise<DocumentFacts>;
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AA6BD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CAwE1E"}