@davidrydberg/proofy 0.0.0-stage → 0.1.0

package/dist/detect.js

@@ -0,0 +1,96 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+export const COMPOSE_NAMES = ["compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml"];
+const INFRA = /(^|\/)(mysql|mariadb|postgres|postgis|redis|valkey|memcached|mongo|mailpit|mailhog|elasticsearch|opensearch|rabbitmq|minio|adminer|phpmyadmin|nginx-proxy|traefik)(:|$)/;
+const SECRET = /(KEY|SECRET|TOKEN|PASSWORD|PASS|PRIVATE|CREDENTIAL|DSN)/i;
+export async function detectCompose(root) {
+    for (const file of COMPOSE_NAMES) {
+        let raw;
+        try {
+            raw = await readFile(join(root, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        let doc;
+        try {
+            doc = parse(raw);
+        }
+        catch {
+            return { file, services: [] };
+        }
+        const services = isRecord(doc) && isRecord(doc.services) ? doc.services : {};
+        const app = guessApp(services);
+        return { file, services: Object.keys(services), ...(app ? { app } : {}) };
+    }
+    return undefined;
+}
+/** Reads .env.example so the sandbox gets the same setting names; secret-looking values become obvious fakes. */
+export async function detectEnv(root) {
+    const file = ".env.example";
+    let raw;
+    try {
+        raw = await readFile(join(root, file), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const values = {};
+    let replaced = 0;
+    for (const line of raw.split(/\r?\n/)) {
+        const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const [, key = "", rawValue = ""] = match;
+        if (SECRET.test(key)) {
+            values[key] = `proofy-fake-${key.toLowerCase().replace(/_/g, "-")}`;
+            replaced++;
+        }
+        else {
+            values[key] = unquote(rawValue.replace(/\s+#.*$/, "").trim());
+        }
+    }
+    return { file, values, replaced };
+}
+function guessApp(services) {
+    const candidates = [];
+    for (const [service, definition] of Object.entries(services)) {
+        if (!isRecord(definition))
+            continue;
+        const image = typeof definition.image === "string" ? definition.image : "";
+        if (INFRA.test(image) || INFRA.test(service))
+            continue;
+        const port = firstPort(definition.ports) ?? firstPort(definition.expose);
+        if (port !== undefined)
+            candidates.push({ service, port, built: definition.build !== undefined });
+    }
+    // A service built from the repository is the app more often than an image pulled from elsewhere.
+    const pick = candidates.find((c) => c.built) ?? candidates[0];
+    return pick ? { service: pick.service, port: pick.port } : undefined;
+}
+// The browser reaches the app inside the sandbox network, so the container side of a mapping is what counts.
+function firstPort(ports) {
+    if (!Array.isArray(ports))
+        return undefined;
+    for (const entry of ports) {
+        if (isRecord(entry) && typeof entry.target === "number")
+            return entry.target;
+        if (typeof entry === "number")
+            return entry;
+        if (typeof entry === "string") {
+            const container = entry.split("/")[0]?.split(":").at(-1) ?? "";
+            const port = Number(container.split("-")[0]);
+            if (Number.isInteger(port) && port > 0)
+                return port;
+        }
+    }
+    return undefined;
+}
+function unquote(value) {
+    const quoted = /^(['"])(.*)\1$/.exec(value);
+    return quoted ? (quoted[2] ?? "") : value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly suggestions: string[];
+    constructor(message: string, code: string, suggestions?: string[]);
+}
+export declare function exitCodeFor(error: unknown): number;

package/dist/errors.js

@@ -0,0 +1,21 @@
+export class CliError extends Error {
+    code;
+    suggestions;
+    constructor(message, code, suggestions = []) {
+        super(message);
+        this.name = "CliError";
+        this.code = code;
+        this.suggestions = suggestions;
+    }
+}
+// 1 is reserved for a failed requirement, so an unexpected crash must not look like a finding about the app.
+const EXIT_CODES = {
+    VALIDATION_ERROR: 2,
+    CONFIG_INVALID: 2,
+    NOT_SET_UP: 2,
+    ENVIRONMENT_ERROR: 3,
+    NOT_APPROVED: 4,
+};
+export function exitCodeFor(error) {
+    return error instanceof CliError ? (EXIT_CODES[error.code] ?? 3) : 3;
+}

package/dist/github.d.ts

@@ -0,0 +1,16 @@
+import type { RunReport } from "./run/results.js";
+import { type Proc } from "./sandbox/docker.js";
+export declare const REPORTS_BRANCH = "proofy-reports";
+export interface PullRequest {
+    number: number;
+    sha: string;
+    url: string;
+}
+export declare function pullRequest(proc: Proc, root: string, number?: number): Promise<PullRequest>;
+/** The pull request's files in a folder of their own. The working copy is never touched. `root` is the repository's top folder. */
+export declare function exportPullRequest(proc: Proc, root: string, pr: PullRequest, dir: string): Promise<void>;
+/**
+ * Pushes the run's screenshots to the reports branch, replaced on every push so the repository never grows,
+ * then writes or updates the one proofy comment on the pull request.
+ */
+export declare function postReport(proc: Proc, root: string, pr: PullRequest, report: RunReport, runDir: string, workDir: string): Promise<string>;

package/dist/github.js

@@ -0,0 +1,121 @@
+import { cp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CliError } from "./errors.js";
+import { renderMarkdown, verdict } from "./run/report.js";
+import { tail } from "./sandbox/docker.js";
+export const REPORTS_BRANCH = "proofy-reports";
+const MARKER = "<!-- proofy -->";
+const KEEP = 20;
+const HISTORY = 10;
+async function gh(proc, args, cwd) {
+    const result = await proc("gh", args, { cwd, timeoutMs: 60_000 });
+    if (result.code !== 0) {
+        const auth = /auth login|not logged/i.test(result.stderr);
+        throw new CliError(`gh ${args.slice(0, 2).join(" ")} failed: ${tail(result.stderr, 3)}`, "ENVIRONMENT_ERROR", [
+            auth ? "Run `gh auth login`" : "Check that this repository is on GitHub and gh can reach it",
+        ]);
+    }
+    return result.stdout;
+}
+export async function pullRequest(proc, root, number) {
+    const args = ["pr", "view", ...(number === undefined ? [] : [String(number)]), "--json", "number,headRefOid,url"];
+    let out;
+    try {
+        out = await gh(proc, args, root);
+    }
+    catch (error) {
+        if (number === undefined && error instanceof CliError) {
+            throw new CliError("The current branch has no pull request to post on", "VALIDATION_ERROR", ["Open one first, or name it with --pr <number>"]);
+        }
+        throw error;
+    }
+    const parsed = JSON.parse(out);
+    return { number: parsed.number, sha: parsed.headRefOid, url: parsed.url };
+}
+/** The pull request's files in a folder of their own. The working copy is never touched. `root` is the repository's top folder. */
+export async function exportPullRequest(proc, root, pr, dir) {
+    const fetch = await proc("git", ["-C", root, "fetch", "--quiet", "origin", `refs/pull/${pr.number}/head`], { timeoutMs: 300_000 });
+    if (fetch.code !== 0) {
+        throw new CliError(`Fetching pull request #${pr.number} failed`, "ENVIRONMENT_ERROR", [tail(fetch.stderr, 5)]);
+    }
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    const archive = join(dir, "..", `pr-${pr.number}.tar`);
+    const packed = await proc("git", ["-C", root, "archive", "--format=tar", "-o", archive, pr.sha]);
+    if (packed.code !== 0)
+        throw new CliError(`Exporting ${pr.sha.slice(0, 12)} failed`, "ENVIRONMENT_ERROR", [tail(packed.stderr, 5)]);
+    const unpacked = await proc("tar", ["-xf", archive, "-C", dir]);
+    await rm(archive, { force: true });
+    if (unpacked.code !== 0)
+        throw new CliError("Unpacking the pull request failed", "ENVIRONMENT_ERROR", [tail(unpacked.stderr, 5)]);
+}
+/**
+ * Pushes the run's screenshots to the reports branch, replaced on every push so the repository never grows,
+ * then writes or updates the one proofy comment on the pull request.
+ */
+export async function postReport(proc, root, pr, report, runDir, workDir) {
+    const slug = (await gh(proc, ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"], root)).trim();
+    await publishShots(proc, slug, report, runDir, workDir);
+    const imageBase = `https://github.com/${slug}/blob/${REPORTS_BRANCH}/runs/${report.id}`;
+    const comments = JSON.parse(await gh(proc, ["api", `repos/${slug}/issues/${pr.number}/comments`, "--paginate", "--slurp"], root));
+    const existing = comments.flat().find((comment) => comment.body.startsWith(MARKER));
+    const history = [historyLine(report), ...(existing ? previousHistory(existing.body) : [])].slice(0, HISTORY);
+    const body = [MARKER, renderMarkdown(report, (path) => `${imageBase}/${path}?raw=true`, { maxShots: 6 }), "### Run history", "", ...history.map((line) => `- ${line}`), ""].join("\n");
+    const payload = join(workDir, "comment.json");
+    await writeFile(payload, JSON.stringify({ body }));
+    if (existing) {
+        await gh(proc, ["api", "-X", "PATCH", `repos/${slug}/issues/comments/${existing.id}`, "--input", payload], root);
+    }
+    else {
+        await gh(proc, ["api", "-X", "POST", `repos/${slug}/issues/${pr.number}/comments`, "--input", payload], root);
+    }
+    return pr.url;
+}
+async function publishShots(proc, slug, report, runDir, workDir) {
+    const dir = join(workDir, "reports-branch");
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    const git = (args) => proc("git", ["-C", dir, "-c", "credential.helper=", "-c", "credential.helper=!gh auth git-credential", "-c", "user.name=proofy", "-c", "user.email=proofy@users.noreply.github.com", ...args], {
+        timeoutMs: 300_000,
+    });
+    await git(["init", "--quiet"]);
+    await git(["remote", "add", "origin", `https://github.com/${slug}.git`]);
+    if ((await git(["fetch", "--quiet", "--depth", "1", "origin", REPORTS_BRANCH])).code === 0) {
+        await git(["checkout", "--quiet", "FETCH_HEAD"]);
+    }
+    const target = join(dir, "runs", report.id);
+    await mkdir(target, { recursive: true });
+    for (const flow of report.flows) {
+        try {
+            await cp(join(runDir, "flows", flow.name), join(target, "flows", flow.name), { recursive: true, filter: (source) => !source.endsWith(".jsonl") });
+        }
+        catch {
+            // A flow that never reached a screenshot.
+        }
+    }
+    await cp(join(runDir, "report.md"), join(target, "report.md"));
+    const runs = (await readdir(join(dir, "runs"))).sort();
+    for (const old of runs.slice(0, Math.max(0, runs.length - KEEP))) {
+        await rm(join(dir, "runs", old), { recursive: true, force: true });
+    }
+    await writeFile(join(dir, "README.md"), `Screenshots for proofy reports. Replaced on every run and keeps the last ${KEEP} runs.\n`);
+    await git(["checkout", "--quiet", "--orphan", `proofy-${report.id}`]);
+    await git(["add", "-A"]);
+    const commit = await git(["commit", "--quiet", "-m", `proofy run ${report.id}`]);
+    if (commit.code !== 0)
+        throw new CliError("Committing screenshots failed", "ENVIRONMENT_ERROR", [tail(commit.stderr, 5)]);
+    const push = await git(["push", "--quiet", "--force", "origin", `HEAD:refs/heads/${REPORTS_BRANCH}`]);
+    if (push.code !== 0)
+        throw new CliError(`Pushing screenshots to ${REPORTS_BRANCH} failed`, "ENVIRONMENT_ERROR", [tail(push.stderr, 5), "Check that gh is logged in with push access"]);
+}
+function historyLine(report) {
+    const counts = report.flows.map((flow) => `${flow.name} ${flow.status}`).join(", ");
+    return `${report.id}: ${verdict(report)}${report.source.commit ? ` on ${report.source.commit.slice(0, 7)}` : ""}${counts ? ` (${counts})` : ""}`;
+}
+function previousHistory(body) {
+    const section = body.split("### Run history")[1] ?? "";
+    return section
+        .split("\n")
+        .filter((line) => line.startsWith("- "))
+        .map((line) => line.slice(2));
+}

package/dist/human.d.ts

@@ -0,0 +1,30 @@
+import type { Verdict } from "./run/report.js";
+import type { RunReport } from "./run/results.js";
+import { type Style } from "./style.js";
+export type Hint = [command: string, description: string];
+export interface Check {
+    label: string;
+    ok: boolean;
+    value: string;
+}
+export interface HomeView {
+    project: string;
+    checks: Check[];
+    flows: Array<{
+        name: string;
+        state: string;
+        reason?: string;
+    }>;
+    orphans: string[];
+    lastRun: string;
+}
+export interface InitView {
+    root: string;
+    found: string[];
+    written: string[];
+    skipped: string[];
+}
+export declare function renderHome(view: HomeView, hints: Hint[], style: Style): string;
+export declare function renderInit(view: InitView, hints: Hint[], style: Style): string;
+export declare function renderRun(report: RunReport, result: Verdict, reportPath: string, hints: Hint[], style: Style, posted?: string): string;
+export declare function renderErrorHuman(message: string, code: string, suggestions: string[], style: Style): string;

package/dist/human.js

@@ -0,0 +1,160 @@
+import { GLYPH, padVisible, painter, stripAnsi, truncate } from "./style.js";
+export function renderHome(view, hints, style) {
+    const p = painter(style);
+    const ready = view.checks.every((check) => check.ok);
+    const lines = [`${p.bold(view.project)}  ${ready ? p.green("set up") : p.yellow("setup incomplete")}`, "", p.bold("SETUP")];
+    lines.push(...checkRows(view.checks, p, style));
+    lines.push("", p.bold(`FLOWS (${view.flows.length})`));
+    if (view.flows.length === 0) {
+        lines.push(p.dim("  none yet"));
+    }
+    const width = Math.max(0, ...view.flows.map((flow) => flow.name.length));
+    for (const flow of view.flows) {
+        lines.push(`  ${padVisible(flow.name, width)}  ${stateText(flow.state, p)}${flow.reason ? p.dim(`  ${flow.reason}`) : ""}`);
+    }
+    for (const orphan of view.orphans) {
+        lines.push(`  ${padVisible(orphan, width)}  ${p.red(`${GLYPH.fail} test without requirements`)}`);
+    }
+    lines.push("", `${p.bold("LAST RUN")}  ${view.lastRun}`);
+    return [lines.join("\n"), nextSection(hints, p, style)].join("\n\n");
+}
+export function renderInit(view, hints, style) {
+    const p = painter(style);
+    const lines = [p.bold(`proofy init  ${view.root}`)];
+    if (view.found.length > 0) {
+        lines.push("", p.bold("FOUND"), ...view.found.map((line) => `  ${truncate(line, style.width - 2)}`));
+    }
+    lines.push("", p.bold("WROTE"));
+    lines.push(...(view.written.length > 0 ? view.written.map((file) => `  ${p.green(GLYPH.ok)} ${file}`) : [p.dim("  nothing, everything was there")]));
+    if (view.skipped.length > 0) {
+        lines.push("", p.bold("KEPT"), ...view.skipped.map((file) => p.dim(`  ${file} already exists`)));
+    }
+    return [lines.join("\n"), nextSection(hints, p, style)].join("\n\n");
+}
+const VERDICT_TEXT = {
+    pass: "PASS  every requirement of every approved flow held",
+    fail: "FAIL  an approved flow has a requirement that did not hold",
+    untrusted: "NOT TRUSTED  some flows are not approved, so this proves nothing yet",
+    environment: "ENVIRONMENT FAILURE  the sandbox did not work; this says nothing about the app",
+};
+export function renderRun(report, result, reportPath, hints, style, posted) {
+    const p = painter(style);
+    const color = result === "pass" ? p.green : result === "untrusted" ? p.yellow : p.red;
+    const lines = [`${color(p.bold(VERDICT_TEXT[result]))}`, p.dim(`run ${report.id}  ${reportPath}`)];
+    if (report.environmentError) {
+        lines.push("", ...report.environmentError.split("\n").slice(0, 8).map((line) => `  ${p.red(truncate(line, style.width - 2))}`));
+    }
+    for (const flow of report.flows) {
+        const trust = flow.approved ? "" : p.yellow("  not approved");
+        lines.push("", `${p.bold(flow.name)}  ${flow.status === "passed" ? p.green("passed") : p.red("failed")}${trust}`);
+        for (const requirement of flow.requirements) {
+            const detail = requirement.result === "pass"
+                ? requirement.text
+                : requirement.result === "not-covered"
+                    ? `${requirement.text}  ${p.dim(`(not covered: ${requirement.why ?? ""})`)}`
+                    : requirement.result === "not-checked"
+                        ? `${requirement.text}  ${p.yellow("(no claim checks it)")}`
+                        : requirement.result === "not-reached"
+                            ? `${requirement.text}  ${p.red("(not reached: the test stopped before checking it)")}`
+                            : `${requirement.text}  ${p.red(`expected ${requirement.expected ?? "?"}, got ${requirement.actual ?? "?"}`)}`;
+            lines.push(`  ${outcomeMark(requirement.result, p)} ${padVisible(requirement.id, 4)} ${truncateVisible(detail, style.width - 9)}`);
+        }
+    }
+    const broken = report.flows.flatMap((flow) => flow.tests.filter((test) => test.status !== "passed" && test.error && !/Requirements not met/.test(test.error)).map((test) => ({ flow: flow.name, test })));
+    if (broken.length > 0) {
+        lines.push("", p.bold("TEST ERRORS"));
+        for (const { flow, test } of broken) {
+            const first = (test.error ?? "").split("\n").filter((line) => line.trim()).slice(0, 3);
+            lines.push(`  ${p.bold(flow)}: ${test.title} (${test.status})`, ...first.map((line) => `    ${p.red(truncate(line.trim(), style.width - 4))}`));
+        }
+    }
+    const refused = report.outside.filter((call) => call.handledAs === "refused").map((call) => call.host);
+    if (report.outside.length > 0) {
+        const handled = report.outside.filter((call) => call.handledAs !== "refused").map((call) => `${call.host} ${call.handledAs} x${call.count}`);
+        lines.push("", p.bold("OUTSIDE CALLS"));
+        if (handled.length > 0)
+            lines.push(`  ${truncate(handled.join(", "), style.width - 2)}`);
+        if (refused.length > 0)
+            lines.push(`  ${p.yellow(truncate(`refused: ${refused.join(", ")}`, style.width - 2))}`);
+    }
+    if (posted)
+        lines.push("", `posted on ${posted}`);
+    return [lines.join("\n"), nextSection(hints, p, style)].join("\n\n");
+}
+function outcomeMark(result, p) {
+    switch (result) {
+        case "pass":
+            return p.green(GLYPH.ok);
+        case "not-covered":
+            return p.dim("-");
+        case "not-checked":
+            return p.yellow(GLYPH.warn);
+        default:
+            return p.red(GLYPH.fail);
+    }
+}
+// Keeps colors when the line fits and drops them when it has to be cut.
+function truncateVisible(text, max) {
+    const plain = stripAnsi(text);
+    return plain.length > max ? truncate(plain, max) : text;
+}
+export function renderErrorHuman(message, code, suggestions, style) {
+    const p = painter(style);
+    const lines = [`${p.red(`${GLYPH.fail} ${message}`)} ${p.dim(`(${code})`)}`];
+    for (const suggestion of suggestions) {
+        lines.push(`  ${suggestion}`);
+    }
+    return lines.join("\n");
+}
+function checkRows(checks, p, style) {
+    const width = Math.max(...checks.map((check) => check.label.length));
+    return checks.map((check) => {
+        const mark = check.ok ? p.green(GLYPH.ok) : p.yellow(GLYPH.warn);
+        const value = truncate(check.value, Math.max(10, style.width - width - 7));
+        return `  ${mark} ${padVisible(check.label, width)}  ${check.ok ? value : p.yellow(value)}`;
+    });
+}
+function stateText(state, p) {
+    switch (state) {
+        case "approved":
+            return p.green(`${GLYPH.ok} approved`);
+        case "ready":
+            return p.cyan("ready, waiting for the human to approve");
+        case "draft":
+            return p.yellow("draft, no test yet");
+        case "unproven":
+            return p.yellow("unproven");
+        case "unstable":
+            return p.red("unstable, runs differ");
+        case "out-of-date":
+            return p.yellow("out of date, changed since approval");
+        default:
+            return state;
+    }
+}
+function nextSection(hints, p, style) {
+    const width = Math.max(0, ...hints.filter(([, description]) => description).map(([command]) => command.length));
+    return [
+        p.bold("NEXT"),
+        ...hints.map(([command, description]) => description
+            ? `  ${padVisible(p.cyan(command), width)}  ${p.dim(truncate(description, Math.max(10, style.width - width - 4)))}`
+            : wrap(command, style.width, "  ", "    ")),
+    ].join("\n");
+}
+// Onboarding sentences are the instructions; they wrap instead of being cut off.
+function wrap(text, width, first, rest) {
+    const lines = [];
+    let line = first;
+    for (const word of text.split(" ")) {
+        const indent = lines.length === 0 ? first : rest;
+        if (line.length > indent.length && line.length + 1 + word.length > width) {
+            lines.push(line);
+            line = rest + word;
+        }
+        else {
+            line = line.length > indent.length ? `${line} ${word}` : line + word;
+        }
+    }
+    lines.push(line);
+    return lines.join("\n");
+}

package/dist/output.d.ts

@@ -0,0 +1,8 @@
+export type Data = Record<string, unknown>;
+export interface Result {
+    data: Data;
+    help: string[];
+}
+export declare function renderResult(result: Result): string;
+export declare function renderJson(value: unknown): string;
+export declare function renderError(message: string, code: string, suggestions: string[]): string;

package/dist/output.js

@@ -0,0 +1,21 @@
+import { encode } from "@toon-format/toon";
+// Help is rendered one hint per line, which TOON's inline primitive arrays would not do.
+export function renderResult(result) {
+    const parts = [];
+    if (Object.keys(result.data).length > 0) {
+        parts.push(encode(result.data));
+    }
+    if (result.help.length > 0) {
+        parts.push(renderHelp(result.help));
+    }
+    return parts.join("\n");
+}
+export function renderJson(value) {
+    return JSON.stringify(value, null, 2);
+}
+export function renderError(message, code, suggestions) {
+    return renderResult({ data: { error: message, code }, help: suggestions });
+}
+function renderHelp(help) {
+    return [`help[${help.length}]:`, ...help.map((line) => `  ${line}`)].join("\n");
+}

package/dist/project.d.ts

@@ -0,0 +1,21 @@
+export interface Paths {
+    root: string;
+    e2e: string;
+    config: string;
+    specs: string;
+    tests: string;
+    standins: string;
+}
+/** The git repository's top folder, if there is one. */
+export declare function gitRoot(cwd: string): Promise<string | undefined>;
+/**
+ * The project proofy works on: the nearest folder from cwd upwards, within the repository, that has
+ * e2e/proofy.json. Otherwise the repository root, or cwd outside git. Apps in a subfolder of a monorepo work too.
+ */
+export declare function findRoot(cwd: string): Promise<string>;
+export declare function pathsFor(root: string): Paths;
+/** Flow names: one per requirements file in e2e/specs. */
+export declare function flowNames(paths: Paths): Promise<string[]>;
+/** Tests without a requirements file: they cannot be traced to anything the user asked for. */
+export declare function orphanTests(paths: Paths): Promise<string[]>;
+export declare function exists(path: string): Promise<boolean>;

package/dist/project.js

@@ -0,0 +1,71 @@
+import { execFile } from "node:child_process";
+import { access, readdir, realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+/** The git repository's top folder, if there is one. */
+export async function gitRoot(cwd) {
+    try {
+        const { stdout } = await run("git", ["rev-parse", "--show-toplevel"], { cwd, timeout: 2000 });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The project proofy works on: the nearest folder from cwd upwards, within the repository, that has
+ * e2e/proofy.json. Otherwise the repository root, or cwd outside git. Apps in a subfolder of a monorepo work too.
+ */
+export async function findRoot(cwd) {
+    const top = await gitRoot(cwd);
+    // git reports real paths, so compare against the real path of cwd, not a symlinked one such as /var on macOS.
+    let dir = await realpath(cwd).catch(() => resolve(cwd));
+    for (;;) {
+        if (await exists(join(dir, "e2e", "proofy.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (dir === top || parent === dir)
+            break;
+        dir = parent;
+    }
+    return top ?? cwd;
+}
+export function pathsFor(root) {
+    const e2e = join(root, "e2e");
+    return {
+        root,
+        e2e,
+        config: join(e2e, "proofy.json"),
+        specs: join(e2e, "specs"),
+        tests: join(e2e, "tests"),
+        standins: join(e2e, "standins"),
+    };
+}
+/** Flow names: one per requirements file in e2e/specs. */
+export async function flowNames(paths) {
+    return (await stems(paths.specs, ".md")).sort();
+}
+/** Tests without a requirements file: they cannot be traced to anything the user asked for. */
+export async function orphanTests(paths) {
+    const specs = new Set(await stems(paths.specs, ".md"));
+    return (await stems(paths.tests, ".spec.ts")).filter((name) => !specs.has(name)).sort();
+}
+async function stems(dir, suffix) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((entry) => entry.isFile() && entry.name.endsWith(suffix)).map((entry) => basename(entry.name, suffix));
+    }
+    catch {
+        return [];
+    }
+}
+export async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/run/approvals.d.ts

@@ -0,0 +1,15 @@
+import type { Paths } from "../project.js";
+import type { Fingerprint } from "./fingerprint.js";
+export interface Approval extends Fingerprint {
+    approvedAt: string;
+    /** The runs whose identical results the approval rests on. */
+    runs: string[];
+    requirements: number;
+}
+export interface Approvals {
+    version: 1;
+    flows: Record<string, Approval>;
+}
+export declare function approvalsFile(paths: Paths): string;
+export declare function readApprovals(paths: Paths): Promise<Approvals>;
+export declare function writeApprovals(paths: Paths, approvals: Approvals): Promise<void>;

package/dist/run/approvals.js

@@ -0,0 +1,26 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CliError } from "../errors.js";
+export function approvalsFile(paths) {
+    return join(paths.e2e, "proofy.lock.json");
+}
+export async function readApprovals(paths) {
+    let raw;
+    try {
+        raw = await readFile(approvalsFile(paths), "utf8");
+    }
+    catch {
+        return { version: 1, flows: {} };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return { version: 1, flows: parsed.flows ?? {} };
+    }
+    catch {
+        throw new CliError("e2e/proofy.lock.json is not valid JSON", "CONFIG_INVALID", ["Restore it from git; it records approvals"]);
+    }
+}
+export async function writeApprovals(paths, approvals) {
+    const flows = Object.fromEntries(Object.entries(approvals.flows).sort(([a], [b]) => a.localeCompare(b)));
+    await writeFile(approvalsFile(paths), `${JSON.stringify({ version: 1, flows }, null, 2)}\n`);
+}