@setsquare/review-sdk 0.0.1

package/dist/group.js

@@ -0,0 +1,709 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, readdir, readFile, rm, stat, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { buildEnvelope, UNKNOWN } from './envelope.js';
+import { resolvePersona, resolveTheme, } from './infer.js';
+import { pruneRuns, runDirName, writeFileAtomic, writeRunInto } from './output.js';
+import { localFacts } from './suite.js';
+import { toUrlPattern } from './sanitise.js';
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * 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 function readGroupContext(env = process.env) {
+    const raw = env['SETSQUARE_RUN_ID']?.trim();
+    if (!raw)
+        return undefined;
+    const warnings = [];
+    /*
+     * An id we cannot use as a directory name is HASHED, never rejected and never
+     * mangled positionally: two invocations handed the same odd id must land in
+     * the same directory, or the group silently splits — which is the exact
+     * failure this feature exists to prevent.
+     */
+    let id = raw;
+    if (!SAFE_ID.test(raw)) {
+        id = createHash('sha256').update(raw, 'utf8').digest('hex').slice(0, 16);
+        warnings.push(`SETSQUARE_RUN_ID contains characters unsafe in a directory name; using a stable hash (${id}) instead.`);
+    }
+    const lane = readLane(env, warnings);
+    const expectedParts = readExpectedParts(env, warnings);
+    return {
+        id,
+        dirName: `group-${id}`,
+        ...(lane ? { lane } : {}),
+        ...(expectedParts !== undefined ? { expectedParts } : {}),
+        warnings,
+    };
+}
+function readLane(env, warnings) {
+    const raw = env['SETSQUARE_LANE']?.trim();
+    if (!raw)
+        return undefined;
+    // Printable ASCII only, bounded. The lane ends up inside testIds and in
+    // rendered output, so it gets the same suspicion as any page-derived string.
+    const cleaned = raw
+        .replace(/[^\x20-\x7E]/g, '')
+        .slice(0, 64)
+        .trim();
+    if (cleaned !== raw) {
+        warnings.push('SETSQUARE_LANE contained characters that were removed or truncated.');
+    }
+    return cleaned || undefined;
+}
+function readExpectedParts(env, warnings) {
+    const raw = env['SETSQUARE_RUN_PARTS']?.trim();
+    if (!raw)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1 || value > 1000) {
+        // A census we cannot read is a census that was never declared — reported,
+        // because a silently ignored declaration would let "complete" quietly mean
+        // less than the orchestrator believes it declared.
+        warnings.push(`SETSQUARE_RUN_PARTS is "${raw}", which is not a whole number of invocations; the declared census was ignored.`);
+        return undefined;
+    }
+    return value;
+}
+/* ------------------------------------------------------------------------- */
+/* Parts: one invocation's complete contribution                              */
+/* ------------------------------------------------------------------------- */
+export const PART_VERSION = 1;
+/**
+ * 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 function mintPartId(startedAt) {
+    return `${runDirName(startedAt)}-${randomBytes(4).toString('hex')}`;
+}
+function partsDir(groupDir) {
+    return join(groupDir, 'parts');
+}
+export async function writeBegunMarker(groupDir, marker) {
+    const dir = partsDir(groupDir);
+    await mkdir(dir, { recursive: true });
+    await writeFileAtomic(join(dir, `${marker.partId}.begun.json`), `${JSON.stringify(marker, null, 2)}\n`);
+}
+export async function writePart(groupDir, part) {
+    const dir = partsDir(groupDir);
+    await mkdir(dir, { recursive: true });
+    await writeFileAtomic(join(dir, `${part.partId}.json`), `${JSON.stringify(part, null, 2)}\n`);
+}
+/**
+ * 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 function prepareOutcomesForPart(outcomes, infrastructureProjects, inference) {
+    return outcomes.map((outcome) => ({
+        ...outcome,
+        infrastructure: infrastructureProjects.has(outcome.project ?? ''),
+        records: outcome.records.map((record) => {
+            if (record.kind === 'observation') {
+                return {
+                    ...record,
+                    observed: {
+                        ...record.observed,
+                        navigations: record.observed.navigations.map((navigation) => ({
+                            ...navigation,
+                            url: toUrlPattern(navigation.url).pattern,
+                        })),
+                    },
+                };
+            }
+            const context = {
+                project: record.page.project,
+                urlPattern: toUrlPattern(record.page.url).pattern,
+                ...(record.page.observedTheme ? { observedTheme: record.page.observedTheme } : {}),
+            };
+            const theme = record.declared.theme ?? resolveTheme(context, inference);
+            const persona = record.declared.persona ?? resolvePersona(context, inference);
+            return {
+                ...record,
+                page: { ...record.page, url: context.urlPattern ?? '/' },
+                declared: {
+                    ...record.declared,
+                    ...(theme ? { theme } : {}),
+                    ...(persona ? { persona } : {}),
+                },
+            };
+        }),
+    }));
+}
+/** The maps survive serialisation; the callbacks were already applied. */
+export function serialisableInference(inference) {
+    return {
+        ...(inference.surfaces ? { surfaces: inference.surfaces } : {}),
+        ...(inference.personas ? { personas: inference.personas } : {}),
+        ...(inference.themes ? { themes: inference.themes } : {}),
+    };
+}
+async function readGroupState(groupDir) {
+    const dir = partsDir(groupDir);
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return { parts: [], begun: [], corrupt: [], partFileNames: [] };
+    }
+    const begun = new Set();
+    const parts = [];
+    const corrupt = [];
+    const partFileNames = [];
+    for (const name of names.sort()) {
+        if (name.startsWith('.tmp-'))
+            continue;
+        if (name.endsWith('.begun.json')) {
+            begun.add(name.slice(0, -'.begun.json'.length));
+            continue;
+        }
+        if (!name.endsWith('.json'))
+            continue;
+        const partId = name.slice(0, -'.json'.length);
+        // A part is also proof its invocation began — a marker write that lost a
+        // race with a crash must not make the part's own evidence look uninvited.
+        begun.add(partId);
+        partFileNames.push(name);
+        try {
+            const parsed = JSON.parse(await readFile(join(dir, name), 'utf8'));
+            if (parsed.partVersion !== PART_VERSION || !Array.isArray(parsed.outcomes)) {
+                corrupt.push(partId);
+                continue;
+            }
+            parts.push(parsed);
+        }
+        catch {
+            // Unreadable is begun-but-not-merged, NEVER absent-and-fine: evidence we
+            // know existed and cannot read is missing evidence, and missing evidence
+            // must never look clean.
+            corrupt.push(partId);
+        }
+    }
+    parts.sort((a, b) => (a.partId < b.partId ? -1 : a.partId > b.partId ? 1 : 0));
+    return { parts, begun: [...begun].sort(), corrupt, partFileNames: partFileNames.sort() };
+}
+/* ------------------------------------------------------------------------- */
+/* The merge                                                                  */
+/* ------------------------------------------------------------------------- */
+/**
+ * Parts this much older than the newest part are another suite execution's
+ * leftovers, not this one's evidence. A reused SETSQUARE_RUN_ID (a branch name, a
+ * recycled build id) would otherwise merge yesterday's passing evidence over
+ * today's regression — wrong in the one direction this product must never be.
+ */
+const STALE_PART_MS = 6 * 60 * 60 * 1000;
+/** How long a merge lock can sit before it is presumed dead and taken over. */
+const LOCK_STALE_MS = 60 * 1000;
+/** How long to wait for a live lock before presuming the holder is stuck. */
+const LOCK_WAIT_MS = 30 * 1000;
+const MAX_MERGE_ROUNDS = 5;
+export async function mergeGroup(inputs) {
+    const { groupDir } = inputs;
+    let result;
+    /*
+     * List → build → write must be a critical section, or this interleaving
+     * loses evidence while claiming not to: merger A lists {A}, stalls; B lists
+     * {A,B}, writes the full merge; A wakes, writes its stale {A}-only merge over
+     * it, and is killed before its convergence re-list. The lock closes that
+     * window; the re-list loop below handles parts that arrive between rounds.
+     */
+    await withMergeLock(groupDir, async () => {
+        for (let round = 0; round < MAX_MERGE_ROUNDS; round += 1) {
+            const state = await readGroupState(groupDir);
+            result = await writeMerged(inputs, state);
+            const after = await readGroupState(groupDir);
+            if (sameNames(state.partFileNames, after.partFileNames))
+                break;
+        }
+    });
+    await cleanupTmpFiles(partsDir(groupDir));
+    if (!result)
+        throw new Error('run-group merge produced no artifact');
+    return result;
+}
+function sameNames(a, b) {
+    return a.length === b.length && a.every((name, i) => name === b[i]);
+}
+async function withMergeLock(groupDir, fn) {
+    const lockDir = join(groupDir, 'merge.lock');
+    await mkdir(groupDir, { recursive: true });
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            // mkdir is the one primitive that is atomically exclusive on every
+            // platform we run on — no lockfiles, no O_EXCL edge cases on NFS.
+            await mkdir(lockDir);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const held = await stat(lockDir).catch(() => undefined);
+            const heldFor = held ? Date.now() - held.mtimeMs : Number.POSITIVE_INFINITY;
+            // A lock owner that died holding the lock must not deadlock every later
+            // invocation; one that is merely slow gets waited for, then presumed dead.
+            if (heldFor > LOCK_STALE_MS || Date.now() > deadline) {
+                await rm(lockDir, { recursive: true, force: true }).catch(() => { });
+                continue;
+            }
+            await new Promise((r) => setTimeout(r, 150));
+        }
+    }
+    try {
+        await fn();
+    }
+    finally {
+        await rm(lockDir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+/** Crash leftovers from atomic writes; anyone's, once they are clearly dead. */
+async function cleanupTmpFiles(dir) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!name.startsWith('.tmp-'))
+            continue;
+        try {
+            const s = await stat(join(dir, name));
+            if (Date.now() - s.mtimeMs > 5 * 60 * 1000)
+                await unlink(join(dir, name));
+        }
+        catch {
+            // Already gone, or not ours to remove. Either way, not a problem.
+        }
+    }
+}
+/**
+ * Labels namespace each part's testIds in the merged envelope, because the
+ * same spec routinely runs in more than one lane and identity must not merge:
+ * a test that FAILED in the functional lane and passed in the a11y lane is two
+ * facts, and collapsing them by testId would render the failure as a flaky
+ * pass — the merge itself manufacturing a clean-looking claim.
+ *
+ * The lane is the label when it is unique; duplicated lanes (a retried lane,
+ * two shards of one lane) get a positional suffix so identity still cannot
+ * collide. Lane-less parts are labelled by position.
+ */
+function partLabels(parts) {
+    const counts = new Map();
+    for (const part of parts) {
+        const lane = part.lane ?? '';
+        counts.set(lane, (counts.get(lane) ?? 0) + 1);
+    }
+    const seen = new Map();
+    const labels = new Map();
+    parts.forEach((part, index) => {
+        const lane = part.lane ?? '';
+        if (lane && counts.get(lane) === 1) {
+            labels.set(part.partId, lane);
+            return;
+        }
+        if (lane) {
+            const nth = (seen.get(lane) ?? 0) + 1;
+            seen.set(lane, nth);
+            labels.set(part.partId, `${lane}-${nth}`);
+            return;
+        }
+        labels.set(part.partId, `part-${index + 1}`);
+    });
+    return labels;
+}
+function shortHash(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex').slice(0, 8);
+}
+/**
+ * Per FIELD, the first part that KNOWS wins. "First part in sort order" alone
+ * would enshrine UNKNOWN over a value a later part detected — recording
+ * ignorance while holding the evidence — and would then "warn" about drift
+ * between UNKNOWN and the truth, which is noise. Real drift between two known
+ * values is stated: parts of one logical run disagreeing on branch or SDK
+ * version is exactly the drifted-runners case, and picking a winner silently
+ * is the kind of claim this product exists not to make.
+ */
+function mergeSource(parts) {
+    const warnings = [];
+    const pick = (field) => {
+        const known = parts
+            .map((part) => part.source[field])
+            .filter((value) => value !== undefined && value !== UNKNOWN);
+        const distinct = [...new Set(known)];
+        if (distinct.length > 1) {
+            warnings.push(`Invocations in this run group disagree on ${field} (${distinct.join(' vs ')}); ` +
+                `the merged run records "${distinct[0]}". This usually means the group id was ` +
+                `shared across executions that are not one logical run.`);
+        }
+        return distinct[0] ?? UNKNOWN;
+    };
+    const ci = parts.map((part) => part.source.ci).find((value) => value !== undefined);
+    return {
+        branch: pick('branch'),
+        commit: pick('commit'),
+        runSource: pick('runSource') === 'ci' ? 'ci' : 'local',
+        sdkVersion: pick('sdkVersion'),
+        axeVersion: pick('axeVersion'),
+        ...(ci ? { ci } : {}),
+        warnings,
+    };
+}
+/**
+ * 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 function mergedCoverage(parts) {
+    const axes = {
+        theme: new Set(),
+        persona: new Set(),
+        state: new Set(),
+    };
+    const projects = new Set();
+    let unmeasured;
+    let any = false;
+    for (const part of parts) {
+        const coverage = part.coverage;
+        if (!coverage)
+            continue;
+        any = true;
+        for (const [axis, values] of Object.entries(coverage.declaredAxes ?? {})) {
+            const target = axes[axis];
+            if (!target)
+                continue;
+            for (const value of values ?? [])
+                target.add(value);
+        }
+        for (const value of coverage.declaredProjects ?? [])
+            projects.add(value);
+        const partUnmeasured = new Set(coverage.unmeasuredAxes);
+        if (unmeasured === undefined)
+            unmeasured = partUnmeasured;
+        else
+            unmeasured = new Set([...unmeasured].filter((axis) => partUnmeasured.has(axis)));
+    }
+    if (!any)
+        return {};
+    const declaredAxes = {};
+    for (const [axis, values] of Object.entries(axes)) {
+        if (values.size > 0)
+            declaredAxes[axis] = [...values].sort();
+    }
+    return {
+        coverage: {
+            ...(Object.keys(declaredAxes).length > 0
+                ? { declaredAxes: declaredAxes }
+                : {}),
+            ...(projects.size > 0 ? { declaredProjects: [...projects].sort() } : {}),
+            unmeasuredAxes: [...(unmeasured ?? [])].sort(),
+        },
+    };
+}
+/**
+ * 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 function mergedConfiguredWorkers(parts) {
+    const known = parts
+        .map((part) => part.configuredWorkers)
+        .filter((value) => typeof value === 'number' && value > 0);
+    if (known.length === 0)
+        return undefined;
+    return known.reduce((total, value) => total + value, 0);
+}
+function mergedConfigFile(parts) {
+    const paths = new Set(parts.map((part) => part.configFile).filter(Boolean));
+    if (paths.size !== 1)
+        return {};
+    const [only] = [...paths];
+    return only ? { configFile: only } : {};
+}
+function coverageOf(group, completed, missing, stale, interrupted) {
+    if (missing.length > 0 || stale.length > 0 || interrupted)
+        return 'partial';
+    const expected = group.expectedParts;
+    if (expected === undefined)
+        return 'unknown';
+    return completed === expected ? 'complete' : 'partial';
+}
+async function writeMerged(inputs, state) {
+    const { group, groupDir } = inputs;
+    const groupWarnings = [...group.warnings];
+    /*
+     * Freshness: parts hours older than the newest are another execution's
+     * leftovers under a reused id. Excluded and NAMED — silently merging them
+     * would let stale passing evidence mask a live regression.
+     */
+    const newest = state.parts.reduce((max, part) => (part.generatedAt > max ? part.generatedAt : max), '');
+    const fresh = [];
+    const stale = [];
+    for (const part of state.parts) {
+        const age = Date.parse(newest) - Date.parse(part.generatedAt);
+        if (Number.isFinite(age) && age > STALE_PART_MS) {
+            stale.push(part.partId);
+        }
+        else {
+            fresh.push(part);
+        }
+    }
+    if (stale.length > 0) {
+        groupWarnings.push(`${stale.length} invocation${stale.length === 1 ? '' : 's'} in this run group ` +
+            `(${stale.join(', ')}) finished hours before the newest one and ${stale.length === 1 ? 'was' : 'were'} ` +
+            'excluded from the merge. This usually means SETSQUARE_RUN_ID was reused across suite ' +
+            'executions; mint a fresh id per execution.');
+    }
+    const labels = partLabels(fresh);
+    // The union the whole feature exists to produce: every part's outcomes, with
+    // identity namespaced per invocation so nothing can collapse across lanes.
+    const outcomes = [];
+    const partWarnings = [];
+    for (const part of fresh) {
+        const label = labels.get(part.partId) ?? part.partId;
+        const visitPrefix = shortHash(part.partId);
+        for (const outcome of part.outcomes) {
+            outcomes.push({
+                ...outcome,
+                testId: `${label} :: ${outcome.testId}`,
+                lane: label,
+                inference: part.inference,
+                records: outcome.records.map((record) => record.kind === 'scan'
+                    ? { ...record, visitRef: `${visitPrefix}:${record.visitRef}` }
+                    : record),
+            });
+        }
+        // Provenance kept, duplication kept: the same warning firing in two lanes
+        // is two facts, not one repeated.
+        for (const warning of part.warnings)
+            partWarnings.push(`[${label}] ${warning}`);
+    }
+    const source = mergeSource(fresh);
+    groupWarnings.push(...source.warnings);
+    const generatedAt = newest || new Date().toISOString();
+    /*
+     * The accounting the artifact stands or falls on: who began, who was merged,
+     * and the difference between those numbers — which is evidence that is
+     * ABSENT, and must read that way. Computed BEFORE the envelope builds,
+     * because the coverage verdict now travels on the wire in `source.runGroup`.
+     */
+    const completedIds = new Set(fresh.map((part) => part.partId));
+    const missing = state.begun.filter((id) => !completedIds.has(id) && !stale.includes(id));
+    const interruptedParts = fresh.filter((part) => part.playwrightStatus === 'interrupted' || part.playwrightStatus === 'timedout');
+    const coverage = coverageOf(group, fresh.length, missing, stale, interruptedParts.length > 0);
+    /*
+     * Unknowns are RECOMPUTED for the merged source, never unioned from parts: a
+     * branch one lane could not detect but another did is KNOWN for the merged
+     * run, and carrying the lane's ignorance forward would record less than the
+     * artifact holds.
+     */
+    const { envelope, warnings: envelopeWarnings, unknowns, } = buildEnvelope({
+        outcomes,
+        sdkVersion: source.sdkVersion,
+        axeVersion: source.axeVersion,
+        branch: source.branch,
+        commit: source.commit,
+        runSource: source.runSource,
+        ...(source.ci ? { ci: source.ci } : {}),
+        runGroup: {
+            id: group.id,
+            coverage,
+            completed: fresh.length,
+            expectedParts: group.expectedParts ?? null,
+        },
+        generatedAt,
+    });
+    if (missing.length > 0) {
+        groupWarnings.push(`${missing.length} invocation${missing.length === 1 ? '' : 's'} in this run group ` +
+            `(${missing.join(', ')}) started but ${missing.length === 1 ? 'its' : 'their'} results were ` +
+            'never merged — crashed, cut short, or still running. That evidence is absent from this ' +
+            'artifact, not clean. Treat this merged run as partial, never as a baseline.');
+    }
+    if (interruptedParts.length > 0) {
+        groupWarnings.push(`Playwright reported ${interruptedParts.length === 1 ? 'an invocation' : 'invocations'} in this ` +
+            `run group as cut short (${interruptedParts
+                .map((part) => `${labels.get(part.partId)}: ${part.playwrightStatus}`)
+                .join(', ')}). ${interruptedParts.length === 1 ? 'Its' : 'Their'} evidence is truncated, so ` +
+            'this merged run is partial.');
+    }
+    if (group.expectedParts !== undefined && fresh.length > group.expectedParts) {
+        groupWarnings.push(`SETSQUARE_RUN_PARTS declared ${group.expectedParts} invocation${group.expectedParts === 1 ? '' : 's'} ` +
+            `but ${fresh.length} were merged. The census is wrong, so this artifact cannot claim completeness.`);
+    }
+    if (coverage === 'unknown') {
+        groupWarnings.push(`Merged ${fresh.length} invocation${fresh.length === 1 ? '' : 's'} of run group "${group.id}". ` +
+            'Whether more were intended is not knowable from this artifact — set SETSQUARE_RUN_PARTS to ' +
+            'declare the count, and treat the artifact as current rather than final until then.');
+    }
+    /*
+     * plannedTests survives the merge only when EVERY part could say it. A sum
+     * over parts where one is unknown clamps the not-run arithmetic toward zero
+     * — a partial census reading as MORE complete — so the honest value there is
+     * "we do not know", with the part that could not say named.
+     */
+    const planned = fresh.map((part) => part.plannedTests);
+    const plannedTests = planned.every((value) => value !== undefined)
+        ? planned.reduce((sum, value) => sum + value, 0)
+        : undefined;
+    if (plannedTests === undefined && fresh.length > 0 && planned.some((v) => v !== undefined)) {
+        const silent = fresh.filter((part) => part.plannedTests === undefined);
+        groupWarnings.push(`${silent.map((part) => labels.get(part.partId)).join(', ')} could not report how many tests ` +
+            'it intended to run, so the merged run cannot say how many never ran.');
+    }
+    const startedAts = fresh.map((part) => Date.parse(part.startedAt)).filter(Number.isFinite);
+    const endedAts = fresh.map((part) => Date.parse(part.generatedAt)).filter(Number.isFinite);
+    const spanMs = startedAts.length > 0 && endedAts.length > 0
+        ? Math.max(0, Math.max(...endedAts) - Math.min(...startedAts))
+        : 0;
+    const pages = outcomes.reduce((total, outcome) => total + outcome.records.length, 0);
+    const envelopeJson = `${JSON.stringify(envelope, null, 2)}\n`;
+    const runJsonSha256 = createHash('sha256').update(envelopeJson, 'utf8').digest('hex');
+    const partsMeta = fresh.map((part) => ({
+        partId: part.partId,
+        ...(part.lane ? { lane: part.lane } : {}),
+        label: labels.get(part.partId) ?? part.partId,
+        startedAt: part.startedAt,
+        generatedAt: part.generatedAt,
+        durationMs: part.durationMs,
+        playwrightStatus: part.playwrightStatus,
+        tests: part.outcomes.length,
+        scans: part.outcomes.reduce((total, outcome) => total + outcome.records.filter((r) => r.kind === 'scan').length, 0),
+        ...(part.plannedTests !== undefined ? { plannedTests: part.plannedTests } : {}),
+        ...(part.reportPath ? { reportPath: part.reportPath } : {}),
+    }));
+    const groupMeta = {
+        id: group.id,
+        expectedParts: group.expectedParts ?? null,
+        begun: state.begun.length,
+        completed: fresh.length,
+        missing: [...missing, ...state.corrupt.filter((id) => !missing.includes(id))],
+        stale,
+        coverage,
+        spanMs,
+        runJsonSha256,
+        parts: partsMeta,
+    };
+    const meta = {
+        runId: null,
+        submitted: false,
+        sdkVersion: envelope.source.sdkVersion,
+        generatedAt,
+        // The span, not a sum: summed durations overstate concurrent lanes and
+        // understate sequential ones, and either would be a fabricated number.
+        durationMs: spanMs,
+        counts: {
+            tests: envelope.results.length,
+            pages,
+            scans: envelope.scans.length,
+            ...(plannedTests !== undefined ? { plannedTests } : {}),
+        },
+        /*
+         * Re-derived from the MERGED outcomes, not carried in the parts.
+         *
+         * Outcomes ride through a part file whole, so every fact these reduce over is
+         * already here — and re-deriving means the merged numbers are computed by
+         * exactly the same code as a solo run's, which is the only way the two cannot
+         * drift apart.
+         */
+        ...localFacts(outcomes, spanMs, mergedConfiguredWorkers(fresh)),
+        ...mergedCoverage(fresh),
+        ...mergedConfigFile(fresh),
+        unknowns,
+        warnings: [...partWarnings, ...envelopeWarnings, ...groupWarnings],
+        group: groupMeta,
+    };
+    const outputRoot = join(groupDir, '..', '..');
+    let htmlReportPath;
+    let html;
+    const provisionalMeta = {
+        ...meta,
+        outputDir: outputRoot,
+        envelopePath: join(groupDir, 'run.json'),
+    };
+    if (inputs.renderReport) {
+        try {
+            html = inputs.renderReport(envelope, provisionalMeta, outcomes);
+            htmlReportPath = join(groupDir, 'report.html');
+        }
+        catch (error) {
+            meta.warnings.push(`The HTML report could not be rendered: ${error instanceof Error ? error.message : String(error)}. The run's evidence in run.json is unaffected.`);
+        }
+    }
+    let screensPath;
+    let screensHtml;
+    if (inputs.renderScreens) {
+        try {
+            screensHtml = inputs.renderScreens(outcomes, groupDir, envelope, provisionalMeta);
+            if (screensHtml !== undefined)
+                screensPath = join(groupDir, 'screens.html');
+        }
+        catch (error) {
+            meta.warnings.push(`The screens report could not be rendered: ${error instanceof Error ? error.message : String(error)}. The run's evidence in run.json is unaffected.`);
+        }
+    }
+    // `writeRunInto` lands run.json before the sidecar that describes it (down
+    // to its hash), so no reader can hold a meta.json whose envelope does not
+    // exist or does not match. The report goes last, and best-effort.
+    const written = await writeRunInto(groupDir, outputRoot, envelope, meta);
+    if (html !== undefined)
+        await writeFileAtomic(join(groupDir, 'report.html'), html);
+    if (screensHtml !== undefined)
+        await writeFileAtomic(join(groupDir, 'screens.html'), screensHtml);
+    await pruneRuns(join(groupDir, '..'), {
+        currentName: runDirName(generatedAt),
+        currentGroupName: group.dirName,
+    });
+    return {
+        runDir: written.runDir,
+        envelopePath: written.envelopePath,
+        metaPath: written.metaPath,
+        ...(htmlReportPath ? { htmlReportPath } : {}),
+        ...(screensPath ? { screensPath } : {}),
+        envelope,
+        meta: { ...meta, outputDir: outputRoot, envelopePath: written.envelopePath },
+        group: groupMeta,
+    };
+}
+//# sourceMappingURL=group.js.map