@jevitate/cli 0.1.0 → 0.2.0

package/dist/regression-cli.js

@@ -0,0 +1,232 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { RecordingSchema } from "@jevitate/recording";
+import { BrowseTheWebToken } from "@jevitate/screenplay";
+import { ok, fail } from "./envelope.js";
+import { runRegressionCapture, runRegressionRun, RegressionNotFoundError, RegressionHardSignalOracleError, RegressionExistsError } from "./regression-api.js";
+import { regressionFixtures, withFixtureFlags } from "./fixture-cli.js";
+import { rebindReplayNavigation } from "./mission-fixtures.js";
+import { withEngine } from "./engine.js";
+import { positiveIntArg } from "./cli-args.js";
+import { formatRegressionCaptureHuman, formatRegressionRunHuman } from "./cli-output.js";
+import { environmentFromFlags, isEnvironmentError, withEnvironmentFlags } from "./environments.js";
+import { resolveRegressionsDir, makeRealBrowserActor, withBrowserLaunchFlags, browserRunFromFlags, withDemoFlags, withEmulationFlags, emulationFromFlags, emitJson, environmentSeams, refuseUnsafeName, writeHumanResult, } from "./cli-shared.js";
+/** Registers `jevitate regression`: `capture` and `run`. */
+export function registerRegressionCommands(program, deps) {
+    // Additive: `@jevitate/regression` — reproduce -> minimize -> commit a
+    // failing Recording into a committed regression artifact (Ticket #5).
+    // Independent of the `journey`/`load` commands above; wires a real
+    // Playwright-backed `makeActor` (one fresh browser session per
+    // reproduce/minimize attempt, closed after each use) into
+    // `runRegressionCapture`.
+    const regression = program.command("regression").description("capture, run and manage regression tests from discovered failures");
+    withDemoFlags(withBrowserLaunchFlags(withEmulationFlags(withFixtureFlags(regression.command("capture")))))
+        .requiredOption("--from <file>", "path to the schema-valid failing Recording JSON to capture")
+        .requiredOption("--id <id>", "regression id (used for the committed <id>.recording.json/<id>.meta.json filenames)")
+        .option("--dir <path>", "regressions directory (default: the repo's .jevitate/regressions; outside a repo ~/.jevitate/regressions)")
+        .option("--attempts <n>", "reproduction attempts before labeling flaky", positiveIntArg, 3)
+        .option("--summary <text>", "optional human-readable bug summary recorded in the meta sidecar")
+        .option("--result <file>", "mission result JSON (as written alongside --from by `jevitate explore`) — supplies a failure oracle when the Recording alone never fails on replay")
+        .option("--fingerprint <fp>", "pin the required failure — a structural step signature (alone, restricts --from to failing at exactly that step), or (with --result, #119/#129) a defect/invariant fingerprint from the mission's own findings; with --result alone, cross-checks the derived oracle")
+        .option("--storage-state <file>", "Playwright storageState JSON to open the reproduce/minimize browser sessions authenticated (#129); must exist")
+        .option("--force", "overwrite an existing regression id's committed files (default: refused, #213)", false)
+        .option("--json", "emit a JSON envelope")
+        .action(async function () {
+        // #245: demo mode (--headed/--slow-mo), resolved before any browser opens.
+        let browser;
+        try {
+            browser = browserRunFromFlags(this.opts(), deps.explore?.env ?? process.env);
+        }
+        catch (err) {
+            emitJson(program, fail("E_REGRESSION_ARGS", err instanceof Error ? err.message : String(err)));
+            return;
+        }
+        const flags = this.opts();
+        const { from, id, dir, attempts, summary, result: resultPath, fingerprint, storageState, force, json } = flags;
+        if (refuseUnsafeName(program, id, "regression id"))
+            return;
+        // #218: unusable input is refused up front (64), never a capture that broke at runtime (2).
+        for (const [flag, path] of [["--from", from], ["--result", resultPath]]) {
+            if (path !== undefined && !existsSync(path)) {
+                emitJson(program, fail("E_REGRESSION_ARGS", `${flag} file not found: ${path}`));
+                return;
+            }
+        }
+        if (storageState !== undefined && !existsSync(storageState)) {
+            emitJson(program, fail("E_REGRESSION_ARGS", `storage state not found: ${storageState}`));
+            return;
+        }
+        let captureEmulationFlag;
+        try {
+            captureEmulationFlag = emulationFromFlags(flags);
+        }
+        catch (err) {
+            emitJson(program, fail("E_REGRESSION_ARGS", err instanceof Error ? err.message : String(err)));
+            return;
+        }
+        const opened = [];
+        let fx;
+        try {
+            const raw = JSON.parse(await readFile(from, "utf8"));
+            const recording = RecordingSchema.parse(raw);
+            // #149: --viewport/--device, else the Recording's OWN emulation (reproduces under the same device).
+            const captureEmulation = captureEmulationFlag ??
+                (recording.emulation === undefined
+                    ? undefined
+                    : recording.emulation.device !== undefined
+                        ? { device: recording.emulation.device }
+                        : { viewport: recording.emulation.viewport });
+            // #144: every reproduce/minimize replay restores the fixture state the Recording started from.
+            fx = regressionFixtures(flags, recording, resultPath === undefined ? undefined : JSON.parse(await readFile(resultPath, "utf8")), storageState);
+            const replayFixture = fx;
+            const result = await runRegressionCapture({
+                failingRecordingPath: from,
+                id,
+                regressionsDir: resolveRegressionsDir(dir),
+                attempts: Number(attempts),
+                bugSummary: summary,
+                resultPath,
+                fingerprint,
+                force,
+                makeActor: async () => {
+                    await replayFixture?.reset();
+                    const { actor, close } = await makeRealBrowserActor(recording.site, storageState, captureEmulation, browser, deps.explore?.browserPortFactory);
+                    opened.push(close);
+                    if (replayFixture !== undefined) {
+                        rebindReplayNavigation(actor.ability(BrowseTheWebToken).session.page, recording.fixture?.outputs ?? {}, replayFixture.publicOutputs());
+                    }
+                    return actor;
+                },
+            }).then((r) => withEngine(r));
+            await fx?.restore();
+            const envelope = ok(fx === undefined ? result : { ...result, fixtures: fx.record() });
+            if (json) {
+                emitJson(program, envelope);
+            }
+            else {
+                // #227/#230: a human summary (captured/flaky, where the files went, what to run next,
+                // carrying the same --dir the user passed) — never the raw result JSON, which used to
+                // print unconditionally without --json.
+                writeHumanResult(program, result, (r) => formatRegressionCaptureHuman(r, { dir }));
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            // #213: these two are usage refusals (64) — an existing id needing --force, or a
+            // hard-signal defect that needs `ledger add` instead — never a generic capture failure (2).
+            if (err instanceof RegressionExistsError || err instanceof RegressionHardSignalOracleError) {
+                emitJson(program, fail(err.code, err.message));
+            }
+            else {
+                emitJson(program, fail("E_REGRESSION_CAPTURE", String(err instanceof Error ? err.message : err)));
+            }
+        }
+        finally {
+            for (const close of opened)
+                await close();
+            await fx?.restore();
+        }
+    });
+    // Additive: `regression run <id>` (#129 item 4) — replays a committed regression (whatever
+    // `regression capture` wrote — a step-oracle, network-check, or declared-invariant one) and
+    // reports "reproduces" or "fixed". The one CLI/MCP surface `loadRegressions`/`replayRegression`
+    // (`@jevitate/regression`) previously had none of.
+    withEnvironmentFlags(withDemoFlags(withBrowserLaunchFlags(withEmulationFlags(regression.command("run")))))
+        .argument("<id>", "the committed regression id (its <id>.recording.json/<id>.meta.json)")
+        .option("--dir <path>", "regressions directory (default: the repo's .jevitate/regressions; outside a repo ~/.jevitate/regressions)")
+        .option("--attempts <n>", "fresh-context replays for a declared-invariant oracle (default 3)", positiveIntArg)
+        .option("--storage-state <file>", "Playwright storageState JSON to open the replay session authenticated (#129); must exist")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (id) {
+        // #245: demo mode (--headed/--slow-mo), resolved before any browser opens.
+        let browser;
+        try {
+            browser = browserRunFromFlags(this.opts(), deps.explore?.env ?? process.env);
+        }
+        catch (err) {
+            emitJson(program, fail("E_REGRESSION_ARGS", err instanceof Error ? err.message : String(err)));
+            return;
+        }
+        const { dir, attempts, storageState: storageStateFlag, json, env: envName, baseUrl, ...emulationFlags } = this.opts();
+        // #247: --env/--base-url choose where the regression replays (unknown env / bad file → 64).
+        let environment;
+        try {
+            environment = environmentFromFlags({ ...(envName === undefined ? {} : { env: envName }), ...(baseUrl === undefined ? {} : { baseUrl }) }, environmentSeams(deps));
+        }
+        catch (err) {
+            if (!isEnvironmentError(err))
+                throw err;
+            emitJson(program, fail(err.code, err.message));
+            return;
+        }
+        // --storage-state wins; else the environment's own session (~/.jevitate/targets.json[<origin>]).
+        const storageState = storageStateFlag ?? environment?.storageState;
+        if (storageState !== undefined && !existsSync(storageState)) {
+            emitJson(program, fail("E_REGRESSION_ARGS", `storage state not found: ${storageState}`));
+            return;
+        }
+        let runEmulationFlag;
+        try {
+            runEmulationFlag = emulationFromFlags(emulationFlags);
+        }
+        catch (err) {
+            emitJson(program, fail("E_REGRESSION_ARGS", err instanceof Error ? err.message : String(err)));
+            return;
+        }
+        if (refuseUnsafeName(program, id, "regression id"))
+            return;
+        const regressionsDir = resolveRegressionsDir(dir);
+        // #218: an unknown id is a usage error (64), refused before anything opens.
+        if (!existsSync(join(regressionsDir, `${id}.recording.json`))) {
+            const notFound = new RegressionNotFoundError(id, regressionsDir);
+            emitJson(program, fail(notFound.code, notFound.message));
+            return;
+        }
+        const opened = [];
+        try {
+            const recording = RecordingSchema.parse(JSON.parse(await readFile(join(regressionsDir, `${id}.recording.json`), "utf8")));
+            // #149: --viewport/--device, else the committed Recording's OWN emulation.
+            const runEmulation = runEmulationFlag ??
+                (recording.emulation === undefined
+                    ? undefined
+                    : recording.emulation.device !== undefined
+                        ? { device: recording.emulation.device }
+                        : { viewport: recording.emulation.viewport });
+            const report = await runRegressionRun({
+                id,
+                regressionsDir,
+                ...(attempts !== undefined ? { attempts: Number(attempts) } : {}),
+                ...(environment === undefined ? {} : { environment }),
+                makeActor: async () => {
+                    const { actor, close } = await makeRealBrowserActor(environment?.baseUrl ?? recording.site, storageState, runEmulation, browser, deps.explore?.browserPortFactory, environment?.allowedOrigins);
+                    opened.push(close);
+                    return actor;
+                },
+            });
+            const envelope = ok(withEngine(report));
+            if (json) {
+                emitJson(program, envelope);
+            }
+            else {
+                // #227/#230: the verdict/reason/next-step summary (carrying the same --dir the user
+                // passed) — never the raw report JSON.
+                program.configureOutput().writeOut?.(formatRegressionRunHuman(report, { dir }));
+            }
+            process.exitCode = report.verdict === "reproduces" ? 1 : report.verdict === "fixed" ? 0 : 2;
+        }
+        catch (err) {
+            if (err instanceof RegressionNotFoundError || isEnvironmentError(err)) {
+                emitJson(program, fail(err.code, err.message));
+            }
+            else {
+                emitJson(program, fail("E_REGRESSION_RUN", String(err instanceof Error ? err.message : err)));
+            }
+        }
+        finally {
+            for (const close of opened)
+                await close();
+        }
+    });
+}
+//# sourceMappingURL=regression-cli.js.map

package/dist/regression-cli.js.map

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

package/dist/report-api.d.ts

@@ -0,0 +1,146 @@
+import { type RunIndexDeps } from "./run-index.js";
+import { type ConsolidatedDefect, type FindingsDiff, type RunRecord } from "@jevitate/findings";
+import { type UsageAggregate } from "@jevitate/ai-core";
+/**
+ * The programmatic surface behind `jevitate report` (#139), `jevitate diff` / `--baseline` (#138)
+ * and `jevitate baseline tag`. It only READS what the runners already persisted — every result was
+ * redacted before it was written, so nothing here can surface a secret the result did not already
+ * hold; a report adds no page data and makes no model call.
+ *
+ * A "run reference" (a `<run>` argument) is, in order: a file path (a `<stem>.result.json`, a
+ * usability report, or a `jevitate check` record naming its results), a baseline tag name, or a
+ * run id (a result file's stem, looked up in the result dirs).
+ */
+export declare class ReportInputError extends Error {
+    readonly code: "E_REPORT_INPUT";
+    constructor(message: string);
+}
+/** Where results live by default: mission results next to their Recordings, and UX reports. */
+export declare function defaultResultDirs(): string[];
+/**
+ * #213: where a report reads by default. A bare `report` reads the CURRENT project only: its own
+ * `.jevitate/logs` (none outside a project) plus every run the run index recorded for this project —
+ * including runs written to an `--out` dir. With `--target`, every results dir is read too (the
+ * target filter keeps it to that app), plus the indexed runs.
+ */
+export declare function defaultReportSources(withTarget: boolean, deps?: RunIndexDeps): {
+    dirs: string[];
+    files: string[];
+};
+/** #213: where `diff`/`baseline tag` look a run id up: this project's sources first, then every results dir. */
+export declare function defaultLookupDirs(deps?: RunIndexDeps): string[];
+export declare function defaultBaselinesDir(): string;
+/** Reads one persisted result file into a run. Null for a file that is not a result. */
+export declare function loadRunFile(path: string): RunRecord | null;
+/**
+ * Every result in `dirs` and their subdirectories (#171: a `runs/<id>/…result.json` layout), oldest
+ * first. Missing dirs are skipped; dot-dirs, `node_modules` and symlinked dirs are not walked.
+ */
+export declare function scanRuns(dirs: readonly string[]): RunRecord[];
+export interface BaselineTag {
+    readonly version: 1;
+    readonly name: string;
+    readonly createdAt: string;
+    /** The result files it was tagged from (evidence; the runs below are a snapshot of them). */
+    readonly sources: readonly string[];
+    /** Snapshot of the tagged runs' findings, so a baseline survives its result files being pruned. */
+    readonly runs: readonly RunRecord[];
+}
+export declare function tagBaseline(opts: {
+    name: string;
+    runs: readonly RunRecord[];
+    dir?: string;
+    nowIso?: () => string;
+}): Promise<{
+    tag: BaselineTag;
+    path: string;
+}>;
+export declare function readBaseline(name: string, dir?: string): BaselineTag | null;
+export declare function listBaselines(dir?: string): Promise<Array<{
+    name: string;
+    createdAt: string;
+    runs: number;
+}>>;
+export interface RunRefContext {
+    readonly dirs: readonly string[];
+    readonly baselinesDir?: string;
+}
+/** Resolves one `<run>` reference to its runs (a check record or a baseline tag names several). */
+export declare function resolveRunRef(ref: string, ctx: RunRefContext): RunRecord[];
+export declare function resolveRunRefs(refs: readonly string[], ctx: RunRefContext): RunRecord[];
+/**
+ * `last`: for every (target, mode) the current runs cover, the most recent EARLIER run of that
+ * target and mode in `pool` — "the last run on this target", per mode.
+ */
+export declare function lastRunsBefore(current: readonly RunRecord[], pool: readonly RunRecord[]): RunRecord[];
+/** Resolves `--baseline <run|tag|last>` against the current runs. */
+export declare function resolveBaseline(ref: string, current: readonly RunRecord[], ctx: RunRefContext & {
+    pool?: readonly RunRecord[];
+}): RunRecord[];
+/**
+ * `--target <origin|name>`: an origin (or any URL on it), or a name — a suite target name stamped
+ * on results by `jevitate check`, or a registered mission target (`~/.jevitate/missions/targets`).
+ */
+export declare function resolveTargetFilter(target: string, missionTargetsDir: string): Promise<{
+    origins: string[];
+    name: string;
+}>;
+/** `--since <run|date>`: an ISO date/time, or a run reference whose start time is the cut-off. */
+export declare function resolveSince(since: string, ctx: RunRefContext): string;
+export interface BuildReportOptions {
+    readonly target?: string;
+    readonly since?: string;
+    readonly dirs?: readonly string[];
+    readonly baseline?: string;
+    readonly baselinesDir?: string;
+    readonly missionTargetsDir: string;
+    /** Explicit runs (e.g. `jevitate check`'s own results) instead of scanning `dirs`. */
+    readonly runs?: readonly RunRecord[];
+    /** #213: the project/run-index seam (cwd, home, index file) for the default sources. */
+    readonly index?: RunIndexDeps;
+}
+export interface RunSummary {
+    readonly runId: string;
+    readonly mode: string;
+    readonly path: string;
+    readonly target?: string;
+    readonly startedAt?: string;
+    readonly missionOutcome?: string;
+    /** #217: a goal run's own ending, beside the canonical `missionOutcome`. */
+    readonly goalOutcome?: string;
+    readonly targetBuild?: string;
+    readonly engineCommit?: string;
+    readonly findings: number;
+}
+export interface ReportResult {
+    readonly target?: string;
+    readonly since?: string;
+    readonly runs: readonly RunSummary[];
+    readonly defects: readonly ConsolidatedDefect[];
+    readonly summary: {
+        readonly defects: number;
+        readonly advisory: number;
+        readonly runs: number;
+    };
+    /**
+     * Model usage summed over the reported runs (#163). Runs whose result carries no `usage` (they made
+     * no model call, or predate usage accounting) are counted in `unreportedRuns`, not priced.
+     */
+    readonly usage: UsageAggregate;
+    readonly diff?: FindingsDiff;
+    readonly baselineRuns?: readonly RunSummary[];
+    readonly markdown: string;
+}
+export declare function summarizeRun(r: RunRecord): RunSummary;
+export declare function buildReport(opts: BuildReportOptions): Promise<ReportResult>;
+/** Sums the runs' persisted usage (#163). */
+export declare function usageOfRuns(runs: readonly RunRecord[]): UsageAggregate;
+/** The report's cost section: the full total, flagged when partial. */
+export declare function usageMarkdown(u: UsageAggregate): string;
+/** `jevitate diff <runA> <runB>`: A is the baseline side, B the current side. */
+export declare function diffRunRefs(a: string, b: string, ctx: RunRefContext): {
+    diff: FindingsDiff;
+    markdown: string;
+    baseline: RunSummary[];
+    current: RunSummary[];
+};