@setsquare/review-sdk 0.0.1

package/dist/group.d.ts

@@ -0,0 +1,214 @@
+import type { RunGroupMeta, RunMeta, RunEnvelope } from './contract.js';
+import { type TestOutcome } from './envelope.js';
+import { type InferenceConfig } from './infer.js';
+/**
+ * Run groups: one LOGICAL run spanning several Playwright invocations.
+ *
+ * The case this exists for is real and observed: an orchestrator that must run
+ * its functional projects at `--workers=1` and its a11y sweep at `--workers=4`
+ * makes two `playwright test` calls per suite execution, and each used to mint
+ * its own run directory — two half-runs with identical source metadata,
+ * indistinguishable from two whole runs. Every consumer downstream of that
+ * (completeness accounting, history comparison, upload) would be quietly wrong
+ * on every execution.
+ *
+ * The mechanism is deliberately lock-light and crash-first:
+ *
+ *   - Each invocation writes a BEGUN marker when it starts and its own PART
+ *     file (its complete contribution, raw observations included) when it
+ *     ends. Both are uniquely named and written atomically, so concurrent
+ *     invocations cannot collide and a reader can never see a torn file.
+ *   - Every finishing invocation re-derives the merged `run.json`, `meta.json`
+ *     and `report.html` from ALL parts present, under a directory lock, then
+ *     re-lists and repeats if new parts arrived mid-merge. The last finisher
+ *     converges to the full union; earlier merges are honest interim states.
+ *   - The merge is `buildEnvelope` over the concatenated outcomes — the same
+ *     single implementation of every policy (best-evidence dedupe, visited-but-
+ *     never-scanned accounting, ruleset drift) now running over the union,
+ *     rather than a second merge-flavoured copy of each that would drift.
+ *
+ * The honesty rules are load-bearing here. A begun marker with no part means an
+ * invocation's evidence is ABSENT, and the merged artifact says so. And the
+ * merge never claims completeness it cannot know: without a declared census
+ * (`SETSQUARE_RUN_PARTS`), an invocation that crashed before announcing itself is
+ * invisible, so the verdict is `unknown` — said out loud — not `complete`.
+ */
+export interface GroupContext {
+    /** The orchestrator's id, after filesystem sanitisation. */
+    id: string;
+    /** `group-<id>` — never collides with the timestamp pattern of solo runs. */
+    dirName: string;
+    /** This invocation's lane label, when the orchestrator set one. */
+    lane?: string;
+    /** Declared invocation count, when the orchestrator stated one. */
+    expectedParts?: number;
+    /** Anything about the contract we could not honour verbatim, named. */
+    warnings: string[];
+}
+/**
+ * Read the run-group contract from the environment.
+ *
+ * Environment rather than `withSetsquare` options, and necessarily so: the reporter
+ * is constructed by Playwright from JSON-safe config, and the group id must
+ * change per suite execution while the config file does not. Absent
+ * `SETSQUARE_RUN_ID`, everything in this module stays out of the way and a solo
+ * invocation behaves exactly as it always has.
+ */
+export declare function readGroupContext(env?: NodeJS.ProcessEnv): GroupContext | undefined;
+export declare const PART_VERSION = 1;
+/** Playwright's verdict for a whole invocation, as `onEnd` reported it. */
+export type InvocationStatus = 'passed' | 'failed' | 'timedout' | 'interrupted' | 'unknown';
+export interface RunPart {
+    partVersion: typeof PART_VERSION;
+    partId: string;
+    lane?: string;
+    startedAt: string;
+    generatedAt: string;
+    durationMs: number;
+    /** `interrupted`/`timedout` means the invocation itself was cut short. */
+    playwrightStatus: InvocationStatus;
+    plannedTests?: number;
+    warnings: string[];
+    unknowns: string[];
+    /** This invocation's own Playwright HTML report, when it made one. */
+    reportPath?: string;
+    /**
+     * This invocation's config path and axis facts.
+     *
+     * Per-invocation, so they cannot be re-derived from the merged outcomes the way
+     * `suite` and `overhead` can — a merged group may span several configs, each with
+     * its own projects and its own theme/persona maps. They travel so the merge can
+     * combine them honestly rather than silently reporting one lane's as the run's.
+     */
+    configFile?: string;
+    coverage?: RunMeta['coverage'];
+    /**
+     * This invocation's configured parallelism.
+     *
+     * Travels because it cannot be re-derived: worker BUSY TIME is in the outcomes,
+     * but whether two workers could ever have run at once is a config fact. Without
+     * it a merged run cannot tell an imbalance from the shape of a serial suite's
+     * projects — which is the confident wrong answer this field was added to prevent
+     * in the first place.
+     */
+    configuredWorkers?: number;
+    source: {
+        branch: string;
+        commit: string;
+        runSource: 'ci' | 'local';
+        sdkVersion: string;
+        axeVersion: string;
+        ci?: RunEnvelope['source']['ci'];
+    };
+    /**
+     * Map-based inference only. Persona/theme CALLBACKS cannot cross a process
+     * boundary, so their results are baked into the records before writing (see
+     * `prepareOutcomesForPart`), and what is stored here is the serialisable rest.
+     */
+    inference: InferenceConfig;
+    outcomes: TestOutcome[];
+}
+export interface BegunMarker {
+    partId: string;
+    lane?: string;
+    startedAt: string;
+    pid: number;
+}
+/**
+ * Minted at `onBegin`, from the invocation's start time — the begun marker and
+ * the part file must share a name, and only the start exists at marker time.
+ * The random suffix is for two invocations starting in the same millisecond,
+ * which concurrent lanes make entirely possible.
+ */
+export declare function mintPartId(startedAt: string): string;
+export declare function writeBegunMarker(groupDir: string, marker: BegunMarker): Promise<void>;
+export declare function writePart(groupDir: string, part: RunPart): Promise<void>;
+/**
+ * Make an invocation's outcomes safe and self-contained before they touch disk.
+ *
+ * Two transformations, both load-bearing:
+ *
+ * **URLs are normalised to patterns NOW, not at merge.** Raw URLs carry
+ * identifiers and sometimes credentials — `/reset-password/<token>` is a real
+ * shape — and today they exist only transiently inside Playwright attachments.
+ * A part file is a durable artifact one careless `upload-artifact: .setsquare/**`
+ * away from leaving the machine, so the raw string must never be written to
+ * it. `toUrlPattern` is idempotent over its own output, so the merge applying
+ * it again is a no-op rather than a double-redaction.
+ *
+ * **Callback-based persona/theme resolution is applied now.** The customer's
+ * `persona`/`theme` functions live in this invocation's config and cannot be
+ * serialised; resolving here and recording the answer in `declared` produces
+ * the identical envelope value the merge would have produced with the callback
+ * in hand. Surfaces are left alone — their inference is map-based and the map
+ * travels in the part.
+ */
+export declare function prepareOutcomesForPart(outcomes: TestOutcome[], infrastructureProjects: ReadonlySet<string>, inference: InferenceConfig): TestOutcome[];
+/** The maps survive serialisation; the callbacks were already applied. */
+export declare function serialisableInference(inference: InferenceConfig): InferenceConfig;
+export interface MergeInputs {
+    groupDir: string;
+    group: GroupContext;
+    /**
+     * Renders the merged HTML report. Injected so this module stays independent
+     * of the renderer; a missing or throwing renderer costs the report and
+     * nothing else, through the same warnings channel as everything the run
+     * could not do.
+     */
+    renderReport?: (envelope: RunEnvelope, meta: RunMeta, 
+    /** The merged outcomes, for the local-only facts the envelope cannot carry. */
+    outcomes: readonly TestOutcome[]) => string;
+    /**
+     * Renders the merged visual contact sheet, and is handed the merged outcomes
+     * because that is where the screenshot paths are — they are local facts, so
+     * they never enter the envelope. Injected and independently fallible for the
+     * same reasons as `renderReport`; returning `undefined` means "this run has
+     * nothing to show", which is not a failure and writes no file.
+     */
+    renderScreens?: (outcomes: readonly TestOutcome[], runDir: string, envelope: RunEnvelope, meta: RunMeta) => string | undefined;
+}
+export interface MergeResult {
+    runDir: string;
+    envelopePath: string;
+    metaPath: string;
+    htmlReportPath?: string;
+    screensPath?: string;
+    envelope: RunEnvelope;
+    meta: RunMeta;
+    group: RunGroupMeta;
+}
+export declare function mergeGroup(inputs: MergeInputs): Promise<MergeResult>;
+/**
+ * Combine the parts' per-invocation coverage facts.
+ *
+ * The two axes combine in OPPOSITE directions, and getting either backwards would
+ * produce a confident wrong answer:
+ *
+ *   - `declaredAxes` is a UNION. Every value any lane configured is a value this
+ *     run could have produced evidence for, so the denominator is the whole set.
+ *   - `unmeasuredAxes` is an INTERSECTION. An axis one lane sets IS measured
+ *     somewhere in the run, so only an axis no lane set anywhere is unmeasured.
+ *     A union here would report `forcedColors` as unmeasured on a run that
+ *     deliberately sharded it into its own lane, which is precisely wrong.
+ */
+export declare function mergedCoverage(parts: readonly {
+    coverage?: RunMeta['coverage'];
+}[]): Pick<RunMeta, 'coverage'>;
+/**
+ * The config path, only when every part agrees on it.
+ *
+ * A merged group spanning several configs has no single config, and naming one of
+ * them would make every derived repro command wrong for the other lanes. Omitted
+ * is the honest answer there.
+ */
+/**
+ * The parallelism a merged group ran at: the SUM across lanes.
+ *
+ * Summed rather than maxed because the lanes genuinely ran their own workers, and
+ * a merged run's imbalance question is about the whole fleet. Absent when no part
+ * reported it, so the imbalance framing stays withheld rather than assumed.
+ */
+export declare function mergedConfiguredWorkers(parts: readonly {
+    configuredWorkers?: number;
+}[]): number | undefined;
+//# sourceMappingURL=group.d.ts.map

package/dist/group.d.ts.map

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