@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/application/src/features/lab-feature-session.js

@@ -0,0 +1,264 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { preOnboardedList } from "../actors/manage-actors.js";
+import { HOST_NETWORK_OWNERS } from "./check-host-network.js";
+import { RunScopedValues } from "./run-scoped-values.js";
+import { BindingError } from "../actors/binding-error.js";
+import { LoadLab } from "../lab/load-lab.js";
+import { hostChoiceProblem, introducedHosts, introducedNames, openAppProblem, sentenceViews } from "./feature-calls.js";
+import { FeaturePlanError } from "./feature-plan-error.js";
+import { AdvanceEnvironmentTime } from "../environment/advance-environment-time.js";
+import { FeatureScenario } from "./feature-scenario.js";
+import { planFeatureScenario } from "./plan-feature-scenario.js";
+import { assignPreparedCharacters } from "./prepared-characters.js";
+import { fixturePeopleRefusal } from "../fixtures/fixture-context.js";
+import { isolatedScenario, NEW_UNFUNDED_ACTOR_OWNER, RaceJitter, RaceSeed } from "@parity/product-lab/domain";
+import { ConditionProfiles } from "@parity/product-lab/domain/conditions";
+import { conditionUnavailable } from "./scenario-conditions.js";
+export class LabFeatureSession {
+    state;
+    runScenario;
+    manageActors;
+    redactor;
+    ids;
+    options;
+    conditions;
+    fixtures;
+    isolation;
+    stepChecks;
+    clock;
+    runStart;
+    begun = new Map();
+    constructor(state, runScenario, manageActors, redactor, ids, options, conditions, 
+    fixtures, 
+    isolation, 
+    stepChecks, 
+    clock, 
+    runStart) {
+        this.state = state;
+        this.runScenario = runScenario;
+        this.manageActors = manageActors;
+        this.redactor = redactor;
+        this.ids = ids;
+        this.options = options;
+        this.conditions = conditions;
+        this.fixtures = fixtures;
+        this.isolation = isolation;
+        this.stepChecks = stepChecks;
+        this.clock = clock;
+        this.runStart = runStart;
+    }
+    async notFor(tags) {
+        return this.conditions ? this.conditions.unmet(tags) : [];
+    }
+    sentences() {
+        const book = this.state.active?.environment.sentences?.book ?? LoadLab.declarative(this.state.lab, "feature steps").sentenceBook();
+        return sentenceViews(book);
+    }
+    async begin(request) {
+        const isolate = isolatedScenario(request.tags ?? []);
+        if (isolate && !this.isolation)
+            throw new Error(`Scenario "${request.name}" is @isolated, but this runtime cannot save and restore its state (no isolation use case)`);
+        const lent = isolate ? await this.isolation.lend("session") : undefined;
+        const giveBack = lent ? () => this.isolation.giveBack("session") : undefined;
+        try {
+            const scenario = await this.beginIsolated(request, giveBack);
+            return lent ? Object.assign(scenario, { isolation: lent }) : scenario;
+        }
+        catch (error) {
+            if (!giveBack)
+                throw error;
+            try {
+                await giveBack();
+            }
+            catch (restore) {
+                throw new AggregateError([error, restore], `${error.message} (giving the isolated state back also failed: ${restore.message})`, { cause: error });
+            }
+            throw error;
+        }
+    }
+    async beginIsolated(request, afterEnd) {
+        const fixture = await this.fixtures?.execute({
+            scenario: request.name,
+            tags: request.tags ?? [],
+            ...(request.fixtureGroup !== undefined ? { group: request.fixtureGroup } : {}),
+            ...(this.options.fixtures ? { policy: this.options.fixtures } : {}),
+            setupSession: (fixtureSetup) => new LabFeatureSession(this.state, this.runScenario, this.manageActors, this.redactor, this.ids, { binding: "manual", fixtureSetup, ...(this.options.surface ? { surface: this.options.surface } : {}), ...(this.options.surfaceConditions ? { surfaceConditions: this.options.surfaceConditions } : {}) }, this.conditions, this.fixtures, this.isolation, this.stepChecks, this.clock),
+        });
+        const start = fixture || isolatedScenario(request.tags ?? []) ? undefined : await this.runStart?.execute(this.ids.next());
+        const kept = start && "kept" in start ? start.kept : undefined;
+        const active = this.state.requireActive();
+        const environment = active.environment;
+        const release = await environment.holdBackground?.();
+        try {
+            return this.plan(request, release ? async () => { try {
+                await afterEnd?.();
+            }
+            finally {
+                release();
+            } } : afterEnd, fixture, kept, start, active);
+        }
+        catch (error) {
+            release?.();
+            throw error;
+        }
+    }
+    plan(request, afterEnd, fixture, kept, start, active) {
+        const startedFrom = fixture ?? kept;
+        const environment = active.environment;
+        const sentences = environment.sentences;
+        if (!sentences)
+            throw new Error("The running environment offers no sentences: feature steps need a declarative lab (defineLab with apps and integrations)");
+        const binding = this.options.binding ?? "fresh";
+        if (binding === "fresh" && Object.keys(request.bindings ?? {}).length)
+            throw new BindingError("Binding scenario actors to saved identities needs manual binding");
+        const characters = assignPreparedCharacters(request.steps, fixture, { ...(request.bindings ?? {}), ...(fixture?.bindings ?? {}) });
+        const bound = characters.bound;
+        const actorHosts = new Map();
+        const preparedActors = new Set([...characters.prepared.values()].map((step) => step.actor));
+        const saved = environment.actors();
+        const before = [];
+        const owners = new Map();
+        for (const [name, id] of Object.entries(bound)) {
+            const other = owners.get(id);
+            if (other)
+                before.push({ step: -1, text: "bindings", kind: "binding", message: `${other} and ${name} are both bound to identity ${id}; each actor needs its own` });
+            owners.set(id, name);
+            const identity = saved.find((actor) => actor.id === id);
+            if (!identity)
+                before.push({ step: -1, text: "bindings", kind: "binding", message: `${name} is bound to identity ${id}, which does not exist in this environment` });
+            else if (identity.status && identity.status !== "running")
+                before.push({ step: -1, text: "bindings", kind: "binding", message: `${name} is bound to ${identity.name}, which is ${identity.status}; start it first` });
+        }
+        const chosenHosts = request.hosts ?? {};
+        for (const [name, host] of Object.entries(chosenHosts)) {
+            const saved = binding === "manual" && Object.hasOwn(bound, name);
+            const problem = saved ? `${name} plays a saved identity, which keeps its own host; a host is chosen only for a new identity (asked: "${host}")` : hostChoiceProblem(environment, name, host);
+            if (problem)
+                before.push({ step: -1, text: "bindings", kind: "binding", message: problem.startsWith(name) ? problem : `${name} cannot be created on the "${host}" host: ${problem}` });
+        }
+        const early = active.public?.writable ? this.ids.next() : undefined;
+        const { plan, issues } = planFeatureScenario(sentences, request.steps, {
+            ...(request.custom ? { custom: request.custom } : {}),
+            actors: Object.keys(bound).filter((name) => !preparedActors.has(name)),
+            ...(characters.prepared.size ? { prepared: characters.prepared } : {}),
+            ...(request.outputs?.length ? { outputs: request.outputs } : {}),
+            before,
+            ...(early !== undefined ? { scoped: RunScopedValues.for(active.public, early) } : {}),
+            unavailable: (call) => this.unavailable(call, environment, sentences, binding, bound, actorHosts, chosenHosts),
+            profiles: this.state.lab?.catalog?.conditionProfiles?.() ?? ConditionProfiles.BUILT_IN,
+        });
+        if (issues.length)
+            throw new FeaturePlanError(request.name, issues.map((issue) => ({ ...issue, message: this.redactor.text(issue.message) })));
+        const id = early ?? this.ids.next();
+        const checks = this.stepChecks?.forScenario({ name: request.name, tags: request.tags ?? [], ...(request.source ? { uri: request.source.uri } : {}) }, active, id);
+        const race = this.race(request);
+        const scenario = new FeatureScenario(request.name, plan, active, sentences, binding, bound, {
+            id,
+            state: this.state,
+            runScenario: this.runScenario,
+            manageActors: this.manageActors,
+            redactor: this.redactor,
+            ...(this.options.surface ? { surface: this.options.surface } : {}),
+            ...(fixture ? { fixture: { report: fixture, reused: new Set(Object.keys(fixture.bindings)) } } : kept ? { fixture: { report: kept, reused: new Set() } } : {}),
+            ...(characters.traces.size ? { characters: characters.traces } : {}),
+            ...(afterEnd ? { afterEnd } : {}),
+            ...(checks ? { checks } : {}),
+            ...(race ? { race: race.jitter } : {}),
+            ...(request.outputs?.length ? { outputs: request.outputs } : {}),
+            ...(this.clock ? { clock: this.clock } : {}),
+            ...(request.hosts && Object.keys(request.hosts).length ? { hosts: request.hosts } : {}),
+        });
+        this.begun.set(request.name, scenario);
+        if (race)
+            this.state.scenarioRaces.set(request.name, race);
+        else
+            this.state.scenarioRaces.delete(request.name);
+        if (request.source)
+            this.state.scenarioSources.set(request.name, {
+                uri: request.source.uri,
+                ...(request.source.line !== undefined ? { line: request.source.line } : {}),
+                tags: [...(request.tags ?? [])],
+                ...(startedFrom ? { fixture: { name: startedFrom.name, action: startedFrom.action } } : {}),
+                ...(start && "notKept" in start ? { startNotKept: true } : {}),
+            });
+        else
+            this.state.scenarioSources.delete(request.name);
+        this.state.scenarioOutcomes.delete(request.name);
+        this.state.scenarioSteps.delete(request.name);
+        this.state.featureStepReadings.delete(request.name);
+        return scenario;
+    }
+    race(request) {
+        const race = this.options.race;
+        if (!race)
+            return undefined;
+        const run = RaceSeed.parse(race.seed);
+        const where = request.source ? `${request.source.uri}:${request.source.line ?? ""}` : request.name;
+        return { runSeed: run.toString(), jitter: new RaceJitter(race.exact ? run : run.scenario(where), race.maxMs) };
+    }
+    releaseIsolation() {
+        if (!this.isolation || this.isolation.lent())
+            return;
+        try {
+            this.isolation.release();
+        }
+        catch {
+        }
+    }
+    scenario(name) {
+        return this.begun.get(name);
+    }
+    identities(name) {
+        return this.begun.get(name)?.identities() ?? [];
+    }
+    unavailable(call, environment, sentences, binding, bound, actorHosts, chosenHosts) {
+        switch (call.entry.kind) {
+            case "identity": {
+                const names = introducedNames(call);
+                const existing = new Set(environment.preOnboarded?.().map((actor) => actor.name) ?? []);
+                const toCreate = names.filter((name) => !existing.has(name) && !(binding === "manual" && Object.hasOwn(bound, name)));
+                if (toCreate.length && !environment.createActor)
+                    return `This environment cannot create identities (${toCreate.join(", ")}); bind the scenario's actors to saved identities${preOnboardedList(environment)}`;
+                const keeps = this.options.fixtureSetup !== undefined ? fixturePeopleRefusal(this.state, this.options.fixtureSetup, toCreate) : undefined;
+                if (keeps)
+                    return keeps;
+                if (call.entry.owner === NEW_UNFUNDED_ACTOR_OWNER && toCreate.length && !environment.fundsOf)
+                    return `This environment cannot make ${toCreate.join(", ")} a new actor with no funds: it does not read what an actor holds on its chains (its sessions offer no fundsOf)`;
+                const named = introducedHosts(call);
+                for (const name of toCreate) {
+                    const fixed = named.get(name), chosen = chosenHosts[name];
+                    if (fixed !== undefined && chosen !== undefined && chosen !== fixed)
+                        return `${name}'s host is set by the scenario ("${fixed}"); the run chose "${chosen}" for it`;
+                    const host = fixed ?? chosen;
+                    if (host === undefined)
+                        continue;
+                    const problem = fixed !== undefined ? hostChoiceProblem(environment, name, host) : undefined;
+                    if (problem)
+                        return problem;
+                    actorHosts.set(name, host);
+                }
+                return undefined;
+            }
+            case "navigation":
+                if (call.entry.owner === "lab.hostBypass")
+                    return environment.hostSessions ? undefined : "This environment exposes no app host sessions for host bypass observation";
+                if (call.entry.owner === "lab.hostRequests")
+                    return environment.hostRequests ? undefined : "This environment keeps no record of what its apps ask their hosts for (it offers no hostRequests)";
+                if (HOST_NETWORK_OWNERS.has(call.entry.owner))
+                    return environment.hostSessions ? undefined : "This environment exposes no app host sessions, so no host's network can be checked";
+                if (call.entry.owner === "lab.openApp") {
+                    if (!environment.openApp)
+                        return "This environment cannot open an app for an actor (it offers no openApp)";
+                    return openAppProblem(call, this.state.lab?.navigation?.routes ?? [], environment);
+                }
+                return environment.navigation ? undefined : "This environment records no host navigation (its sessions do not use the navigation bridge)";
+            case "time":
+                return AdvanceEnvironmentTime.unavailable(environment, call.entry.owner);
+            case "condition":
+                return conditionUnavailable(call, environment, this.options, bound, call.actor !== undefined ? actorHosts.get(call.actor) : undefined);
+            default:
+                return sentences.unavailable(call.entry.owner);
+        }
+    }
+}

package/core/application/src/features/lint-lab.d.ts

@@ -0,0 +1,15 @@
+import type { LabLintReport, LintRequest } from "@parity/product-lab/ports/driving";
+import type { FeatureRunner } from "@parity/product-lab/ports/features";
+import type { ClientBundleChecker } from "@parity/product-lab/ports/lab";
+import type { Redactor } from "@parity/product-lab/ports/system";
+import type { LabState } from "../lab/lab-state.js";
+import type { ListFeatures } from "./list-features.js";
+export declare class LintLab {
+    private readonly state;
+    private readonly features;
+    private readonly runner;
+    private readonly redactor;
+    private readonly clientBundles?;
+    constructor(state: LabState, features: ListFeatures, runner: FeatureRunner | undefined, redactor: Redactor, clientBundles?: ClientBundleChecker | undefined);
+    execute(request?: LintRequest): Promise<LabLintReport>;
+}

package/core/application/src/features/lint-lab.js

@@ -0,0 +1,204 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { controlSpec, failsWithProblem, scenarioFixture, scenarioNeeds, SentencePattern } from "@parity/product-lab/domain";
+import { checkExtensions } from "../lab/check-extensions.js";
+import { LoadLab } from "../lab/load-lab.js";
+import { expandOutline } from "./expand-outline.js";
+import { togetherKey } from "./feature-calls.js";
+import { planFeatureScenario } from "./plan-feature-scenario.js";
+export class LintLab {
+    state;
+    features;
+    runner;
+    redactor;
+    clientBundles;
+    constructor(state, features, runner, redactor, clientBundles) {
+        this.state = state;
+        this.features = features;
+        this.runner = runner;
+        this.redactor = redactor;
+        this.clientBundles = clientBundles;
+    }
+    async execute(request = {}) {
+        const catalog = LoadLab.declarative(this.state.lab, "lint");
+        const lab = this.state.lab;
+        const problems = [];
+        const add = (problem) => problems.push({ ...problem, message: this.redactor.text(problem.message) });
+        for (const message of catalog.problems())
+            add({ rule: "configuration", severity: "error", message });
+        for (const message of catalog.configWarnings?.() ?? [])
+            add({ rule: "configuration", severity: "warning", message });
+        for (const extension of checkExtensions(catalog, this.clientBundles, this.redactor))
+            if (extension.refused !== undefined)
+                add({
+                    rule: "client-bundle",
+                    severity: this.clientBundles ? "error" : "warning",
+                    message: `UI module ${extension.key} (${extension.kind}, ${extension.file}) is refused: ${extension.refused}`,
+                });
+        const environments = request.environment !== undefined ? [request.environment] : catalog.environmentIds();
+        const configured = catalog.environmentIds();
+        for (const id of environments)
+            if (!configured.includes(id))
+                throw new Error(`Unknown environment ${id}. Configured: ${configured.join(", ")}`);
+        const configuration = this.runner?.configuration(lab.root, request.configuration);
+        if (request.configuration && !configuration)
+            add({ rule: "runner", severity: "error", message: `The Cucumber configuration ${request.configuration} does not exist` });
+        const mode = configuration ? "configuration" : "bundled";
+        const strict = !!request.strict || mode === "bundled";
+        const stepPatterns = catalog.stepPatterns() ?? [];
+        const support = await this.features.support();
+        if (stepPatterns.length && !support.length)
+            add({ rule: "step-files", severity: "warning", message: `No file matches the lab's steps globs (${stepPatterns.join(", ")})` });
+        const preflight = this.runner?.preflight ? await this.runner.preflight({ root: lab.root, support }) : { problems: [], customSteps: [] };
+        for (const message of preflight.problems)
+            add({ rule: "runner", severity: "error", message });
+        const custom = preflight.customSteps.map((pattern) => SentencePattern.parse(pattern));
+        const customUses = new Map(custom.map((pattern) => [pattern.text, 0]));
+        const customMatch = (text) => {
+            const found = custom.find((pattern) => pattern.regex.test(text));
+            if (found)
+                customUses.set(found.text, (customUses.get(found.text) ?? 0) + 1);
+            return !!found;
+        };
+        const book = catalog.sentenceBook();
+        const views = new Map(environments.map((id) => [id, catalog.declaredSentences(id)]));
+        const configFile = lab.path.slice(lab.path.lastIndexOf("/") + 1);
+        for (const name of Object.keys(catalog.characters?.() ?? {})) {
+            const seen = new Set();
+            const text = `Someone is ${name}`;
+            for (const environment of environments) {
+                const sentences = views.get(environment);
+                const { issues } = planFeatureScenario(sentences, [{ text }], {
+                    unavailable: (call) => (call.entry.kind === "action" || call.entry.kind === "assertion" ? sentences.unavailable(call.entry.owner) : undefined),
+                });
+                for (const issue of issues) {
+                    const perEnvironment = issue.kind === "capability";
+                    const key = `${perEnvironment ? environment : ""}\u0000${issue.message}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    add(problemOf({ ...issue, message: `Character "${name}": ${issue.message}` }, perEnvironment ? environment : undefined, request.environment !== undefined, { file: configFile, scenario: `character "${name}"`, step: text }));
+                }
+            }
+        }
+        const listing = await this.features.execute({ read: true, ...(request.configuration ? { configuration: request.configuration } : {}) });
+        let scenarios = 0;
+        let steps = 0;
+        const reasons = catalog.failureReasons?.() ?? {};
+        for (const feature of listing.features) {
+            const said = new Set();
+            for (const scenario of feature.scenarios) {
+                const spec = controlSpec([...feature.tags, ...scenario.tags]);
+                const problems = [
+                    ...spec.problems.map((message) => ({ message, severity: spec.control ? "error" : "warning" })),
+                    ...(spec.reason !== undefined ? [failsWithProblem(spec.reason, reasons)].filter((message) => !!message).map((message) => ({ message, severity: "error" })) : []),
+                    ...(spec.control && spec.atStep !== undefined && spec.atStep > (scenario.background?.length ?? 0) + scenario.steps.length
+                        ? [{ message: `@fails-at-step-${spec.atStep}: "${scenario.name}" has ${(scenario.background?.length ?? 0) + scenario.steps.length} step(s), its Background's included`, severity: "error" }]
+                        : []),
+                ];
+                for (const problem of problems) {
+                    if (said.has(problem.message))
+                        continue;
+                    said.add(problem.message);
+                    add({ rule: "negative-control", severity: problem.severity, message: problem.message, file: feature.path, scenario: scenario.name, line: scenario.line });
+                }
+            }
+        }
+        for (const feature of listing.features)
+            for (const scenario of feature.scenarios.flatMap(expandOutline)) {
+                scenarios++;
+                steps += scenario.steps.length;
+                const inputs = scenario.steps.map((step) => ({ text: step.text, ...(step.table ? { table: step.table } : {}), ...(step.docString ? { docString: step.docString.content } : {}) }));
+                const where = (index, docLine) => {
+                    const step = scenario.steps[index];
+                    const line = step && docLine !== undefined && step.docString ? step.docString.line + docLine : step?.line;
+                    return { file: feature.path, scenario: scenario.name, ...(step ? { line: line, step: step.text } : {}) };
+                };
+                const handWritten = (text) => !strict && !book.find(text).length;
+                for (const [index, step] of scenario.steps.entries()) {
+                    const isCustom = customMatch(step.text);
+                    if (!isCustom && handWritten(step.text))
+                        add({
+                            rule: "unchecked-step",
+                            severity: "warning",
+                            message: `No registered sentence or custom step matches "${step.text}"; only a step definition of ${configuration} can run it (not checked here; --strict makes this an error)`,
+                            ...where(index),
+                        });
+                    const worded = book.find(step.text).map((found) => found.entry.pattern.wording(step.text)).find((text) => text !== undefined);
+                    if (worded)
+                        add({ rule: "wording", severity: "warning", message: `"${step.text}": write "${worded}"`, ...where(index) });
+                }
+                const control = scenario.tags.includes("@negative-control");
+                const fixture = scenarioFixture(scenario.tags);
+                const declaredFixtures = catalog.fixtures?.() ?? {};
+                for (const problem of fixture.problems)
+                    add({ rule: "fixture", severity: "error", message: problem, file: feature.path, scenario: scenario.name });
+                if (fixture.name !== undefined && !declaredFixtures[fixture.name])
+                    add({
+                        rule: "fixture",
+                        severity: "error",
+                        message: `@fixture:${fixture.name}: the lab declares no fixture ${fixture.name} (${Object.keys(declaredFixtures).length ? `declared: ${Object.keys(declaredFixtures).join(", ")}` : "it declares none: add defineLab({ fixtures })"})`,
+                        file: feature.path,
+                        scenario: scenario.name,
+                    });
+                for (const id of scenarioNeeds(scenario.tags).environments ?? [])
+                    if (!catalog.environmentIds().includes(id))
+                        add({ rule: "environment", severity: "error", message: `@environment:${id}: the lab declares no environment ${id} (declared: ${catalog.environmentIds().join(", ")})`, file: feature.path, scenario: scenario.name });
+                const seen = new Set();
+                for (const environment of environments) {
+                    const sentences = views.get(environment);
+                    const { issues, plan } = planFeatureScenario(sentences, inputs, {
+                        custom: (text) => custom.some((pattern) => pattern.regex.test(text)) || handWritten(text),
+                        unavailable: (call) => (call.entry.kind === "action" || call.entry.kind === "assertion" ? sentences.unavailable(call.entry.owner) : undefined),
+                    });
+                    for (const issue of issues) {
+                        const perEnvironment = issue.kind === "capability";
+                        const key = `${perEnvironment ? environment : ""}\u0000${issue.step}\u0000${issue.message}`;
+                        if (seen.has(key))
+                            continue;
+                        seen.add(key);
+                        const problem = problemOf(issue, perEnvironment ? environment : undefined, request.environment !== undefined, where(issue.step, issue.docLine));
+                        add(control ? { ...problem, severity: "warning", message: `(negative control) ${problem.message}` } : problem);
+                    }
+                    for (const step of plan.steps) {
+                        const actors = new Set(step.calls.filter((call) => togetherKey(call) !== undefined && call.entry.kind !== "identity").map((call) => call.actor ?? ""));
+                        const [actor] = actors;
+                        const key = `together\u0000${step.index}`;
+                        if (actors.size !== 1 || !actor || seen.has(key))
+                            continue;
+                        seen.add(key);
+                        add({ rule: "together", severity: "warning", message: `Every part of "${step.text}" is ${actor}'s, so these run in turn: remove the group or add another person's step`, ...where(step.index) });
+                    }
+                }
+            }
+        for (const [pattern, uses] of customUses)
+            add({
+                rule: "custom-step",
+                severity: "warning",
+                message: `Custom step "${pattern}" (used by ${uses} step(s)): it runs and is labelled custom in the trace, but the builder cannot offer it; declare a sentence on an action or assertion instead when you can`,
+            });
+        const errors = problems.filter((problem) => problem.severity === "error").length;
+        return {
+            lab: catalog.name,
+            mode,
+            ...(configuration ? { configuration } : {}),
+            features: listing.features.length,
+            scenarios,
+            steps,
+            customSteps: [...customUses.keys()],
+            environments,
+            problems,
+            errors,
+            warnings: problems.length - errors,
+        };
+    }
+}
+function problemOf(issue, environment, environmentAsked, where) {
+    return {
+        rule: issue.kind,
+        severity: environment !== undefined && !environmentAsked ? "warning" : "error",
+        message: environment !== undefined ? `In ${environment}: ${issue.message}` : issue.message,
+        ...where,
+        ...(environment !== undefined ? { environment } : {}),
+    };
+}

package/core/application/src/features/list-features.d.ts

@@ -0,0 +1,26 @@
+import { type FeatureFile } from "@parity/product-lab/domain";
+import type { FeatureListing, FeatureListRequest } from "@parity/product-lab/ports/driving";
+import type { FeatureRunner, FeatureSource } from "@parity/product-lab/ports/features";
+import type { LabState } from "../lab/lab-state.js";
+import type { ReadScenarioConditions } from "./read-scenario-conditions.js";
+export declare class ListFeatures {
+    private readonly state;
+    private readonly source;
+    private readonly runner?;
+    /** The running environment's scenario conditions (inspection marks the scenarios that do not fit). */
+    private readonly conditions?;
+    constructor(state: LabState, source: FeatureSource | undefined, runner?: FeatureRunner | undefined, 
+    /** The running environment's scenario conditions (inspection marks the scenarios that do not fit). */
+    conditions?: ReadScenarioConditions | undefined);
+    /** The feature files the lab declares (none without declared globs or a FeatureSource). */
+    declared(): Promise<string[]>;
+    /** The lab's custom step files (its `steps` globs), for bundled runs. */
+    support(): Promise<string[]>;
+    /** Declared, else discovered; `read` parses each file and matches its steps against the registered sentences. */
+    execute(request?: FeatureListRequest): Promise<FeatureListing>;
+    /** The lab's feature files a runner configuration's paths (files or globs) name, parsed; nothing is inspected. */
+    selected(patterns: readonly string[]): Promise<FeatureFile[]>;
+    /** Parse feature files of the lab (or a builder draft) for their scenarios' names, lines and tags; nothing is inspected. */
+    parse(paths: readonly string[]): Promise<FeatureFile[]>;
+    private requireSource;
+}

package/core/application/src/features/list-features.js

@@ -0,0 +1,92 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { parseFeature, planScenario, UnsupportedCapabilityError } from "@parity/product-lab/domain";
+import { LoadLab } from "../lab/load-lab.js";
+import { inspectScenario } from "./inspect-scenario.js";
+import { introducedHosts, introducedNames } from "./feature-calls.js";
+const DISCOVER = [["**", "*.feature"].join("/")];
+export class ListFeatures {
+    state;
+    source;
+    runner;
+    conditions;
+    constructor(state, source, runner, 
+    conditions) {
+        this.state = state;
+        this.source = source;
+        this.runner = runner;
+        this.conditions = conditions;
+    }
+    async declared() {
+        const lab = this.state.lab;
+        const patterns = lab?.catalog?.featurePatterns();
+        if (!lab || !patterns?.length || !this.source)
+            return [];
+        return this.source.list(lab.root, patterns);
+    }
+    async support() {
+        const lab = this.state.lab;
+        const patterns = lab?.catalog?.stepPatterns();
+        if (!lab || !patterns?.length)
+            return [];
+        return this.requireSource().list(lab.root, patterns);
+    }
+    async execute(request = {}) {
+        if ((!this.state.lab && this.state.adopted) || (this.state.lab && !this.state.lab.catalog))
+            throw new UnsupportedCapabilityError("feature-source");
+        const catalog = LoadLab.declarative(this.state.lab, "the feature list");
+        const lab = this.state.lab;
+        const source = this.requireSource();
+        const patterns = catalog.featurePatterns();
+        const configuration = this.runner?.configuration(lab.root, request.configuration) ?? null;
+        const listing = patterns?.length
+            ? { source: "lab.config.ts features", paths: await source.list(lab.root, patterns), configuration }
+            : { source: "discovered (lab.config.ts declares no features)", paths: await source.list(lab.root, DISCOVER), configuration };
+        if (!request.read)
+            return { ...listing, features: [] };
+        const sentences = catalog.sentences();
+        const book = catalog.sentenceBook();
+        const active = this.state.active;
+        const environment = active?.selected ?? catalog.defaultEnvironment;
+        const reading = request.inspect && active ? await this.conditions?.execute() : undefined;
+        const inspection = request.inspect ? {
+            environment, source: active ? "running" : "declared",
+            sentences: active?.environment.sentences ?? catalog.declaredSentences(environment),
+            registry: active?.environment.registry ?? catalog.registry(environment),
+            ...(reading?.state === "read" ? { conditions: reading.conditions } : {}),
+            ...(catalog.scenarioEnvironments ? { environments: catalog.scenarioEnvironments() } : {}),
+        } : undefined;
+        const features = await Promise.all(listing.paths.map(async (path) => {
+            const feature = parseFeature(path, await source.read(lab.root, path), sentences);
+            return { ...feature, scenarios: feature.scenarios.map((scenario) => ({ ...scenario, ...scenarioActors(book, scenario), ...(inspection ? { inspection: inspectScenario(scenario, inspection) } : {}) })) };
+        }));
+        return { ...listing, features };
+    }
+    async selected(patterns) {
+        const lab = this.state.lab;
+        if (!lab)
+            return [];
+        return this.parse(await this.requireSource().list(lab.root, patterns));
+    }
+    async parse(paths) {
+        const lab = this.state.lab;
+        if (!lab)
+            return [];
+        const source = this.requireSource();
+        return Promise.all(paths.map(async (path) => parseFeature(path, await source.read(lab.root, path), [])));
+    }
+    requireSource() {
+        if (!this.source)
+            throw new UnsupportedCapabilityError("feature-source");
+        return this.source;
+    }
+}
+function scenarioActors(book, scenario) {
+    const steps = [...(scenario.background ?? []), ...scenario.steps].map((step) => ({ text: step.text, ...(step.table ? { table: step.table } : {}), ...(step.docString ? { docString: step.docString.content } : {}) }));
+    const calls = planScenario(book, steps).steps.flatMap((step) => step.calls).filter((call) => call.entry.kind === "identity");
+    const actorHosts = {};
+    for (const call of calls)
+        for (const [name, host] of introducedHosts(call))
+            actorHosts[name] ??= host;
+    return { actors: [...new Set(calls.flatMap((call) => introducedNames(call)))], ...(Object.keys(actorHosts).length ? { actorHosts } : {}) };
+}

package/core/application/src/features/manage-breakpoints.d.ts

@@ -0,0 +1,45 @@
+import { type FeatureScenario } from "@parity/product-lab/domain";
+import type { LabBreakpoints, StepBreakpointView } from "@parity/product-lab/ports/driving";
+import type { BreakpointStore } from "@parity/product-lab/ports/storage";
+import type { PlannedBreakpoint } from "./feature-run.js";
+import type { ListFeatures } from "./list-features.js";
+/** A scenario a run selects, with the names its pickles carry (an outline's selected variants). */
+export interface SelectedScenario {
+    path: string;
+    scenario: FeatureScenario;
+    names: readonly string[];
+}
+export declare class ManageBreakpoints implements LabBreakpoints {
+    private readonly features;
+    private readonly store?;
+    constructor(features: ListFeatures, store?: BreakpointStore | undefined);
+    private requireStore;
+    private load;
+    /** A path the lab lists, relative to its directory; anything else is refused. */
+    private featurePath;
+    private file;
+    list(request?: {
+        path?: string;
+        scenario?: string;
+    }): Promise<StepBreakpointView[]>;
+    set(request: {
+        path: string;
+        scenario: string;
+        index: number;
+    }): Promise<StepBreakpointView>;
+    clear(request: {
+        path: string;
+        scenario: string;
+        index?: number;
+    }): Promise<{
+        removed: number;
+    }>;
+    /**
+     * The breakpoints of the scenarios a run selects: the gate's map (pickle name to the steps to pause before) and every
+     * breakpoint with its state (`waiting`, or `stale` with why; stale ones are not applied). No store: none.
+     */
+    forRun(selected: readonly SelectedScenario[]): {
+        gate: Record<string, number[]>;
+        planned: PlannedBreakpoint[];
+    };
+}