@parity/product-lab 0.0.1-placeholder → 0.1.1

package/core/application/src/suites/compare-suite-runs.js

@@ -0,0 +1,55 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { compareSuiteRuns, compatibilityNotifications } from "@parity/product-lab/domain/suites";
+import { summarizeSuiteRun } from "./summarize-suite-run.js";
+export const SUITE_RECORD_FILE = "product-lab-suite.json";
+export class CompareSuiteRuns {
+    files;
+    notifiers;
+    redactor;
+    constructor(files, notifiers, redactor) {
+        this.files = files;
+        this.notifiers = notifiers;
+        this.redactor = redactor;
+    }
+    async execute(request) {
+        const previous = this.read(request.previous, "previous");
+        const current = this.read(request.current, "current");
+        if (previous.suite !== current.suite)
+            throw new Error(`The runs are of different suites (${previous.suite} and ${current.suite}); compare two runs of one suite`);
+        if (previous.id === current.id)
+            throw new Error(`Both paths hold the same suite run ${current.id}; give the earlier run first and the later one second`);
+        const report = compareSuiteRuns(summarizeSuiteRun(previous), summarizeSuiteRun(current));
+        const notifications = this.redactor.value(compatibilityNotifications(report));
+        const target = request.notify ?? { kind: "none" };
+        if (target.kind !== "none" && !this.notifiers)
+            throw new Error(`This runtime has no notifier for ${target.kind}`);
+        const notifier = this.notifiers?.(target);
+        const receipts = [];
+        for (const notification of notifications) {
+            const receipt = notifier ? await notifier.send(notification) : { status: "skipped" };
+            receipts.push({ key: notification.key, title: notification.title, status: receipt.status, ...(receipt.location ? { location: receipt.location } : {}), notifier: notifier?.id ?? "none" });
+        }
+        return this.redactor.value({ report, notifications, receipts });
+    }
+    read(location, which) {
+        if (!this.files)
+            throw new Error("This runtime cannot read suite records");
+        return readSuiteRecord(this.files, location, which);
+    }
+}
+export function readSuiteRecord(files, location, which) {
+    const file = /\.json$/i.test(location) ? location : `${location.replace(/\/+$/, "")}/${SUITE_RECORD_FILE}`;
+    let data;
+    try {
+        data = files.readJson(file);
+    }
+    catch (error) {
+        throw new Error(`The ${which} run's ${file} is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!data)
+        throw new Error(`No suite run at ${file} (the ${which} run): give the report directory of a \`product-lab test --suite <name>\` run (its --report-dir), or its ${SUITE_RECORD_FILE}`);
+    if (typeof data.id !== "string" || typeof data.suite !== "string" || !Array.isArray(data.rows))
+        throw new Error(`${file} is not a suite record (id, suite and rows)`);
+    return data;
+}

package/core/application/src/suites/observed-versions-file.d.ts

@@ -0,0 +1,30 @@
+import type { SuiteCombination } from "@parity/product-lab/domain/suites";
+import type { RunObservation } from "@parity/product-lab/ports/lab";
+import type { FileSystem } from "@parity/product-lab/ports/system";
+/** The variable naming the file a run records what it observed in. */
+export declare const OBSERVED_VERSIONS_VARIABLE = "PRODUCT_LAB_OBSERVED_VERSIONS";
+/** The file's name in a row's directory. */
+export declare const OBSERVED_VERSIONS_FILE = "observed-versions.json";
+/** The file's content. */
+export interface ObservedVersionsData {
+    readonly kind: "product-lab-observed-versions";
+    readonly schemaVersion: 1;
+    readonly components: Readonly<Record<string, {
+        readonly version: string;
+        readonly digests: Readonly<Record<string, string>>;
+        readonly detail?: string;
+    }>>;
+}
+/**
+ * Records observations into one file: read, merged and rewritten (atomically,
+ * 0600) on every new or changed component, so several runtimes of one run
+ * (a lab's own and the bundled steps') add to the same record.
+ */
+export declare class ObservedVersionsFile {
+    private readonly files;
+    readonly path: string;
+    constructor(files: FileSystem, path: string);
+    readonly observe: (component: RunObservation) => void;
+    /** What a run recorded in `path`; absent or unsupported-schema files are empty, while read errors propagate. */
+    static read(files: FileSystem, path: string): SuiteCombination;
+}

package/core/application/src/suites/observed-versions-file.js

@@ -0,0 +1,30 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const OBSERVED_VERSIONS_VARIABLE = "PRODUCT_LAB_OBSERVED_VERSIONS";
+export const OBSERVED_VERSIONS_FILE = "observed-versions.json";
+export class ObservedVersionsFile {
+    files;
+    path;
+    constructor(files, path) {
+        this.files = files;
+        this.path = path;
+    }
+    observe = (component) => {
+        const entry = { version: component.version, digests: { ...component.digests }, ...(component.detail ? { detail: component.detail } : {}) };
+        const recorded = this.files.readJson(this.path);
+        const components = recorded?.kind === "product-lab-observed-versions" && recorded.schemaVersion === 1 ? { ...recorded.components } : {};
+        if (JSON.stringify(components[component.id]) === JSON.stringify(entry))
+            return;
+        components[component.id] = entry;
+        const data = { kind: "product-lab-observed-versions", schemaVersion: 1, components: Object.fromEntries(Object.entries(components).sort(([a], [b]) => a.localeCompare(b))) };
+        this.files.writePrivateJson(this.path, data);
+    };
+    static read(files, path) {
+        const data = files.readJson(path);
+        if (!data || data.kind !== "product-lab-observed-versions" || data.schemaVersion !== 1 || typeof data.components !== "object")
+            return {};
+        return Object.fromEntries(Object.entries(data.components)
+            .filter(([, entry]) => typeof entry?.version === "string" && entry.digests && typeof entry.digests === "object")
+            .map(([id, entry]) => [id, { version: entry.version, digests: { ...entry.digests }, origin: "observed", ...(entry.detail ? { detail: entry.detail } : {}) }]));
+    }
+}

package/core/application/src/suites/row-combination.d.ts

@@ -0,0 +1,9 @@
+import type { SuiteCombination } from "@parity/product-lab/domain/suites";
+import type { VersionResolutionData } from "@parity/product-lab/domain/versions";
+import type { SourceRevision } from "@parity/product-lab/ports/system";
+/** Every resolved component, as the resolution recorded it. */
+export declare function resolutionCombination(resolution: VersionResolutionData | undefined): SuiteCombination;
+/** A lab name as a component name (`Example` → `example`). */
+export declare function labComponentName(name: string): string;
+/** The lab's source as the `app:<lab>` component: its directory's tree, and what is uncommitted in it. */
+export declare function sourceCombination(lab: string, revision: SourceRevision | undefined): SuiteCombination;

package/core/application/src/suites/row-combination.js

@@ -0,0 +1,36 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function resolutionCombination(resolution) {
+    return Object.fromEntries(Object.entries(resolution?.components ?? {}).map(([id, entry]) => {
+        const source = entry.resolved.source;
+        const detail = source.type === "github-release"
+            ? `${source.repository} ${source.tag}`
+            : source.type === "git"
+                ? `${source.repository}@${source.commit.slice(0, 12)} (${source.ref})`
+                : source.type === "npm"
+                    ? `npm ${source.package}@${entry.resolved.version}`
+                    : `${source.network}/${source.chain} at #${source.block.number}`;
+        return [id, { version: entry.resolved.version, digests: { ...entry.resolved.digests }, origin: "resolution", detail: `${detail}, selector ${typeof entry.selector === "string" ? entry.selector : JSON.stringify(entry.selector)}` }];
+    }));
+}
+export function labComponentName(name) {
+    return (name
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[^a-z0-9]+|-+$/g, "")
+        .slice(0, 64) || "lab");
+}
+export function sourceCombination(lab, revision) {
+    if (!revision)
+        return {};
+    const uncommitted = revision.uncommitted;
+    return {
+        [`app:${labComponentName(lab)}`]: {
+            version: `tree ${revision.tree.slice(0, 12)}${uncommitted ? ` + ${uncommitted.files} uncommitted (${uncommitted.digest.slice(0, 12)})` : ""}`,
+            digests: { tree: revision.tree, ...(uncommitted ? { uncommitted: uncommitted.digest } : {}) },
+            origin: "source",
+            commit: revision.commit,
+            detail: `the lab's directory at commit ${revision.commit.slice(0, 12)}${uncommitted ? ` with ${uncommitted.files} uncommitted file(s)` : ""}`,
+        },
+    };
+}

package/core/application/src/suites/row-host-route.d.ts

@@ -0,0 +1,26 @@
+import type { SuiteCombination } from "@parity/product-lab/domain/suites";
+import type { HostRelease, VersionResolutionData } from "@parity/product-lab/domain/versions";
+import type { HostRouting } from "@parity/product-lab/ports/host";
+import type { FileSystem } from "@parity/product-lab/ports/system";
+export declare const HOST_ROUTE_FILE = "host-route.json";
+/** The variable naming the route file a row's run reads: its host adapter runs the release that way. */
+export declare const HOST_ROUTE_VARIABLE = "PRODUCT_LAB_HOST_ROUTE";
+/** The route file: which host and component it is for, and the adapter's own selection. */
+export interface HostRouteFileData {
+    readonly kind: "product-lab-host-route";
+    readonly schemaVersion: 1;
+    readonly host: string;
+    readonly component: string;
+    readonly tag: string;
+    readonly route: "official" | "patched";
+    readonly selection: unknown;
+}
+/** The host release the row resolved for `kind` from a source, with the digests recorded for it; undefined when its host is the lock's. */
+export declare function resolvedHostRelease(resolution: VersionResolutionData | undefined, kind: string): {
+    release: HostRelease;
+    digests: Record<string, string>;
+} | undefined;
+/** The row's combination with its host component saying how it ran (and the patch set a patched build applied); after the observation is merged in. */
+export declare function withHostRoute(combination: SuiteCombination, routing: HostRouting): SuiteCombination;
+/** Write the route file for the row's run; its path. */
+export declare function writeHostRoute(files: FileSystem, path: string, host: string, routing: HostRouting): string;

package/core/application/src/suites/row-host-route.js

@@ -0,0 +1,30 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const HOST_ROUTE_FILE = "host-route.json";
+export const HOST_ROUTE_VARIABLE = "PRODUCT_LAB_HOST_ROUTE";
+export function resolvedHostRelease(resolution, kind) {
+    const component = `host:${kind}`;
+    const entry = resolution?.components[component];
+    if (!entry || entry.origin !== "source")
+        return undefined;
+    const { source, version, digests } = entry.resolved;
+    const tag = source.type === "github-release" ? source.tag : source.type === "git" ? source.ref : source.type === "npm" ? `${source.package}@${version}` : version;
+    const commit = source.type === "git" ? source.commit : digests.commit?.startsWith("git-sha1:") ? digests.commit.slice("git-sha1:".length) : undefined;
+    return { release: { component, version, tag, ...(commit ? { commit } : {}) }, digests: { ...digests } };
+}
+export function withHostRoute(combination, routing) {
+    const id = routing.route.release.component;
+    const entry = combination[id];
+    if (!entry)
+        return combination;
+    const how = routing.route.route === "patched" ? `patched (${routing.route.patches.join(", ")}${routing.patchset ? `; patch set ${routing.patchset}` : ""})` : routing.route.route;
+    return { ...combination, [id]: { ...entry, detail: entry.detail ? `${entry.detail}; ran ${how}` : `ran ${how}`, digests: { ...entry.digests, ...(routing.patchset ? { patchset: routing.patchset } : {}) } } };
+}
+export function writeHostRoute(files, path, host, routing) {
+    const { route } = routing;
+    if (route.route === "unsupported")
+        throw new Error(`An unsupported route (${route.reason}) has no run to hand over`);
+    const data = { kind: "product-lab-host-route", schemaVersion: 1, host, component: route.release.component, tag: route.release.tag, route: route.route, selection: routing.selection ?? null };
+    files.writePrivateJson(path, data);
+    return path;
+}

package/core/application/src/suites/run-suite.d.ts

@@ -0,0 +1,76 @@
+import type { DeviceProfile } from "@parity/product-lab/domain/devices";
+import { type SuitePlan, type SuitePlanRow } from "@parity/product-lab/domain/suites";
+import type { FeatureRunner } from "@parity/product-lab/ports/features";
+import type { FeatureRunHandle, FeatureRunRecord, ResolveVersionsReport, ResolveVersionsRequest, RunFeaturesRequest, RunSuiteRequest, SuiteRequest, SuiteRowRecord, SuiteRunRecord } from "@parity/product-lab/ports/driving";
+import type { SuiteEvidenceBundles } from "@parity/product-lab/ports/storage";
+import type { ChangeSource, Clock, FileSystem, IdGenerator, Redactor } from "@parity/product-lab/ports/system";
+import type { HostToolServices } from "../hosts/acquire-host.js";
+import type { LabState } from "../lab/lab-state.js";
+import type { ListFeatures } from "../features/list-features.js";
+export interface RunSuiteDeps {
+    state: LabState;
+    listFeatures: ListFeatures;
+    /** The feature runner: what its configuration selects for each row is what the suite plans (absent: the lab's features as listed). */
+    runner?: FeatureRunner;
+    runFeatures(request: RunFeaturesRequest): Promise<FeatureRunHandle>;
+    /** Runs started together as one group (each with its own variables); a mode's workers need it. */
+    runFeaturesTogether?(requests: readonly RunFeaturesRequest[]): Promise<FeatureRunHandle[]>;
+    /** Resolves a row's versions with its candidates; absent when the runtime has no versions ports. */
+    resolveVersions?(request: ResolveVersionsRequest): Promise<ResolveVersionsReport>;
+    changes?: ChangeSource;
+    /** Reads what each row's run observed; without it rows record only their resolution and source. */
+    files?: FileSystem;
+    evidenceBundles?: SuiteEvidenceBundles;
+    /** Lent to a host adapter deciding how a row runs a host release (backlog 27): commands, the upstream resolver, the sandbox. */
+    hostTools?: HostToolServices;
+    /** The browser adapter's named devices: a mode's row naming another is unsupported. Absent: devices are not checked. */
+    devices?: () => Promise<Readonly<Record<string, DeviceProfile>>>;
+    clock: Clock;
+    ids: IdGenerator;
+    redactor: Redactor;
+}
+export declare class RunSuite {
+    private readonly deps;
+    constructor(deps: RunSuiteDeps);
+    /** What the suite would run now; starts nothing. */
+    plan(request: SuiteRequest & {
+        env?: Readonly<Record<string, string>>;
+    }): Promise<SuitePlan>;
+    /**
+     * What each row's run would select, by host (a configuration may read PRODUCT_LAB_HOST): the runner's configuration
+     * loaded with the row's environment. Its feature files, unless the lab declares its own (`defineLab({ features })`,
+     * which the row's run then gets as its paths); its tags and fail-fast always. Nothing when the runner cannot say or
+     * the lab has no configuration (a bundled run selects the lab's features as listed).
+     */
+    private selections;
+    execute(request: RunSuiteRequest): Promise<SuiteRunRecord>;
+    /**
+     * Backlog 37: one scenario of one row, run as the row runs it but with `candidates` as its versions (a bisect pins
+     * every candidate to an exact version) and only that scenario selected. Host releases are routed as in a suite.
+     */
+    probe(request: {
+        suite: string;
+        row: string;
+        scenario: {
+            readonly name: string;
+            readonly uri: string;
+        };
+        candidates: Readonly<Record<string, string>>;
+        directory: string;
+        env?: Readonly<Record<string, string>>;
+        signal?: AbortSignal;
+        onOutput?: (text: string) => void;
+    }): Promise<SuiteRowRecord>;
+    private runRow;
+}
+/**
+ * The row's planned scenarios its run did not report, each with why when that is known: `stoppedBy` when the suite
+ * stopped the run (its budget, an interrupt), else after a failure in a run that stops at its first failure, "not run:
+ * stopped after the first failure". A scenario outline's examples report under
+ * its name with each `<parameter>` filled in.
+ */
+export declare function unreportedScenarios(row: Pick<SuitePlanRow, "scenarios" | "failFast">, run: Pick<FeatureRunRecord, "scenarios">, stoppedBy?: string): {
+    feature: string;
+    name: string;
+    reason?: string;
+}[];