@setsquare/review-sdk 0.0.1

package/dist/options.d.ts

@@ -0,0 +1,249 @@
+import type { InferenceConfig } from './infer.js';
+import type { MaskConfig } from './mask.js';
+import { type RulePolicy } from './rules.js';
+import { type SettleConfig } from './settle.js';
+/**
+ * Configuration for `withSetsquare()`.
+ *
+ * Everything here is optional, and that is the product claim rather than a
+ * convenience: the promise is a single config line, so an empty options object
+ * has to produce a useful run. Options exist to correct inference, never to
+ * enable it.
+ */
+export interface SetsquareOptions {
+    /**
+     * Where the run envelope and its sidecar are written.
+     *
+     * Relative paths resolve against the Playwright config's directory, not the
+     * process working directory — a suite run from a monorepo root and the same
+     * suite run from its own package must put their output in the same place, or
+     * the artifact moves depending on where you were standing.
+     */
+    outputDir?: string;
+    /**
+     * Print the closing block that explains what the platform adds.
+     *
+     * Once per run, at the end, five lines at most, derived from the run's own
+     * numbers. Off is honoured without complaint — a tool that nags is a tool
+     * people configure around, and then they have configured away the summary too.
+     */
+    promo?: boolean;
+    /**
+     * The WCAG conformance level to assess against. Defaults to `AA`.
+     *
+     * AA is the floor because it is what conformance normally means in practice
+     * and what procurement, EN 301 549 and the EAA actually ask for. AAA is opt-in
+     * rather than default because it is a deliberate commitment — WCAG itself does
+     * not recommend AAA as a general policy, since some AAA criteria cannot be
+     * satisfied for all content, so defaulting to it would report every team as
+     * failing a bar they never set.
+     */
+    wcag?: 'AA' | 'AAA';
+    /**
+     * Include axe's 30 advisory `best-practice` rules. Defaults to `false`.
+     *
+     * They catch real problems and are worth turning on. They are off by default
+     * because they are NOT WCAG failures, and a conformance grid that mixes advice
+     * with conformance cannot honestly answer "does this meet AA?". Findings from
+     * them are always distinguishable in the payload — a best-practice rule carries
+     * no `wcag` block.
+     */
+    bestPractice?: boolean;
+    /** Scan automatically on settled navigation. On by default — it is the promise. */
+    autoScan?: boolean;
+    /** How long a page must be quiet before it counts as settled. Default 500ms. */
+    quietMs?: number;
+    /**
+     * Hard ceiling before scanning anyway. Default 5000ms.
+     *
+     * A page that never goes quiet is common — a spinner, a poller, a carousel —
+     * and declining to scan it would produce 'no findings', which reads as 'no
+     * problems'. On expiry the scan happens and the payload records that it did.
+     */
+    settleTimeoutMs?: number;
+    /** Route pattern to surface name: `{ '/items/:id/edit': 'item-editor' }`. */
+    surfaces?: InferenceConfig['surfaces'];
+    /** Playwright project name to persona. */
+    personas?: InferenceConfig['personas'];
+    /** Playwright project name to theme. */
+    themes?: InferenceConfig['themes'];
+    /** The escape hatch for suites whose project names carry neither. */
+    persona?: InferenceConfig['persona'];
+    theme?: InferenceConfig['theme'];
+    /**
+     * Extra regions to mask, composed WITH the built-in defaults.
+     *
+     * Masking has no effect on the local path, which writes no images at all —
+     * it is configured here so the posture is set before any bytes are ever
+     * captured, rather than being bolted on when upload arrives.
+     */
+    mask?: MaskConfig['mask'];
+    /** Drop the built-in mask defaults. A deliberate, documented act. */
+    maskDefaults?: MaskConfig['maskDefaults'];
+    /**
+     * How the run's summary is printed.
+     *
+     * `text` is for a human at a terminal. `markdown` survives being pasted into
+     * Slack, an issue, or an LLM prompt — which is the main thing that happens to
+     * this output. `json` is for a machine, and omits the closing block entirely.
+     */
+    format?: 'text' | 'markdown' | 'json';
+    /**
+     * How the conformance grid renders in the terminal summary. Default `matrix`.
+     *
+     * `matrix` draws criteria × surfaces as aligned single-glyph columns — no
+     * box-drawing, so it survives being pasted — and falls back to per-criterion
+     * rows by itself when the run has more surfaces than the width budget fits.
+     * `rows` skips the matrix always, for people who find it noise.
+     */
+    grid?: 'matrix' | 'rows';
+    /**
+     * Estimate reading level (WCAG 3.1.5, AAA) on scanned pages.
+     *
+     * Defaults to on when the run targets AAA — 3.1.5 is an AAA criterion — and
+     * off at AA unless opted in. Always a needs-review heuristic, never a
+     * violation: formulas approximate a grade, and the SC itself allows
+     * supplemental content and alternate versions no formula can see.
+     */
+    readingLevel?: boolean;
+    /**
+     * The longest a single scan may hold a customer's test.
+     *
+     * Exists because it was missing and that turned out to matter. The SDK's first
+     * promise is that it never fails a build, and an unbounded axe run on a heavy
+     * page breaks it in the most confusing way available — the customer's test
+     * times out, blames itself, and nothing points at us.
+     */
+    scanTimeoutMs?: number;
+}
+/** Options after defaulting, which is what the reporter actually holds. */
+export interface ResolvedSetsquareOptions {
+    outputDir: string;
+    promo: boolean;
+    rules: RulePolicy;
+    autoScan: boolean;
+    settle: SettleConfig;
+    inference: InferenceConfig;
+    mask: MaskConfig;
+    format: 'text' | 'markdown' | 'json';
+    grid: 'matrix' | 'rows';
+    readingLevel: boolean;
+    scanTimeoutMs: number;
+    /** Off entirely. Set by `SETSQUARE_DISABLED`, and nothing else. */
+    disabled: boolean;
+}
+/**
+ * `.setsquare/` rather than something prettier: it sorts with the other tool
+ * directories, it is obviously ours, and `setsquare init` suggests exactly this line
+ * for the customer's `.gitignore`.
+ */
+export declare const DEFAULT_OUTPUT_DIR = ".setsquare";
+/**
+ * Ten seconds, and the number is a compromise with a reason on each side.
+ *
+ * axe on a large real page legitimately takes seconds — a drag-and-drop builder
+ * with thousands of nodes is not being slow, it is being big — so a tight budget
+ * would throw away exactly the evidence hardest to get any other way. But a test
+ * that a customer wrote against a 30-second budget cannot afford to lend us most
+ * of it.
+ *
+ * Ten seconds fits every scan measured on the fixture site and on the reference
+ * implementation's ordinary pages, and cuts off the pathological case before it
+ * can take a test down with it.
+ */
+export declare const DEFAULT_SCAN_TIMEOUT_MS = 10000;
+/**
+ * The kill switch, read from the environment rather than from config.
+ *
+ * A customer who suspects the SDK of breaking their suite needs to test that
+ * suspicion in one command, on a branch they have not touched, in CI they cannot
+ * edit. Making them change a config file first means the check is annoying enough
+ * to skip — and "is it you or is it me" is the question we most want them to be
+ * able to answer quickly, because the answer is sometimes yes.
+ *
+ * It is also how we get a baseline for our own measurements without asking anyone
+ * to revert anything.
+ */
+export declare function isDisabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Per-invocation auto-scan override, from the environment.
+ *
+ * Exists for multi-invocation suites: axe is the bulk of the SDK's per-test
+ * cost, and a functional lane whose surfaces the a11y lane scans anyway is
+ * paying that cost twice for evidence the merge would deduplicate. The config
+ * file cannot carry this — it is the same file for every lane — so the lane
+ * that should not scan says so: `SETSQUARE_AUTOSCAN=0`.
+ *
+ * Deliberately narrower than the kill switch. `SETSQUARE_DISABLED` removes the SDK
+ * from the run entirely; this keeps observations, test outcomes and the run
+ * artifact — the lane still contributes to the merged run's e2e visibility and
+ * to the visited-but-never-scanned union — and skips only the scanning.
+ * Explicit `setsquare.scan()` calls still run: the customer asked for those by name.
+ *
+ * Returns undefined when unset, so config and defaults keep deciding.
+ */
+export declare function autoScanOverride(env?: NodeJS.ProcessEnv): boolean | undefined;
+/**
+ * Per-invocation output directory, from the environment.
+ *
+ * Exists for `setsquare verify`, and the reason is a hazard rather than a
+ * convenience. Verify re-runs one surface to see whether a rule still fires — which
+ * means invoking the customer's own Playwright, which means the SDK writes a run.
+ * Writing it into `.setsquare/runs/` would make the re-scan **become the latest
+ * run**: `audit`, `report`, `findings` and `sarif` all read that, and `pruneRuns`
+ * would delete the real run it replaced. A command that silently overwrites the
+ * artefact every other command reads is worse than no command, so verify redirects
+ * the output instead.
+ *
+ * An env rather than a config option, for the same reason `SETSQUARE_RUN_ID` and
+ * `SETSQUARE_AUTOSCAN` are: it changes per invocation while the config file does
+ * not, and Playwright constructs reporters from JSON-safe config entries.
+ *
+ * Useful beyond verify — a CI lane that wants its evidence somewhere specific can
+ * set it — which is why it is a general option and not a `SETSQUARE_VERIFY=1` flag.
+ *
+ * Returns undefined when unset, so config and defaults keep deciding.
+ */
+export declare function outputDirOverride(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Where to write the run summary as markdown.
+ *
+ * `SETSQUARE_SUMMARY_MD=<path>` makes the reporter write the summary it just
+ * printed, rendered through `renderMarkdown`, to that path as well. Nothing else
+ * changes: the terminal still gets whatever `format` asks for, and the file is a
+ * second rendering of the SAME input rather than a second summary.
+ *
+ * It exists for CI job summaries — GitHub's `$GITHUB_STEP_SUMMARY`, GitLab's
+ * report pages — and it is deliberately a path rather than a `github: true` flag,
+ * because the SDK has no business knowing which CI it is running under. The
+ * official Action points this at a file it owns and appends that file itself, so
+ * append-versus-replace stays the caller's decision.
+ *
+ * An env rather than a config option for the same reason as `SETSQUARE_OUTPUT_DIR`:
+ * it changes per invocation while the config file does not.
+ *
+ * The alternative was a CLI command that renders markdown from `run.json` — but
+ * `@setsquare/review-sdk` depends on `@setsquare/review-cli`, so the CLI cannot read the
+ * SDK's renderer, and rewriting it there is exactly the second renderer that
+ * `report.ts` forbids. One renderer, a second destination.
+ */
+export declare function summaryMarkdownPath(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Changed-only mode: scan just the surfaces a change can reach.
+ *
+ * `SETSQUARE_CHANGED_ONLY=<path>` points at the file `setsquare changed` writes.
+ * The SDK does no route reasoning of its own — it compares patterns it already
+ * computes against a list, which is why this is a few lines rather than an adapter.
+ * The route knowledge lives in the CLI, where the adapters are, and
+ * `sdk/src/style.ts` records the standing decision that CLI code must not enter a
+ * test process's import graph.
+ *
+ * Two shapes in that file mean different things and must not be conflated:
+ * `routes: []` is "nothing changed that touches a route", and `routes: null` is
+ * "we could not work it out". Only the first licenses skipping anything; `null`
+ * means scan everything, because a set that might be missing surfaces is worse
+ * than no set at all.
+ */
+export declare function changedOnlyRoutes(env?: NodeJS.ProcessEnv, read?: (path: string) => string): Set<string> | undefined;
+export declare function resolveOptions(options?: SetsquareOptions): ResolvedSetsquareOptions;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

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

package/dist/options.js

@@ -0,0 +1,185 @@
+import { readFileSync } from 'node:fs';
+import { DEFAULT_RULE_POLICY } from './rules.js';
+import { DEFAULT_SETTLE } from './settle.js';
+/**
+ * `.setsquare/` rather than something prettier: it sorts with the other tool
+ * directories, it is obviously ours, and `setsquare init` suggests exactly this line
+ * for the customer's `.gitignore`.
+ */
+export const DEFAULT_OUTPUT_DIR = '.setsquare';
+/**
+ * Ten seconds, and the number is a compromise with a reason on each side.
+ *
+ * axe on a large real page legitimately takes seconds — a drag-and-drop builder
+ * with thousands of nodes is not being slow, it is being big — so a tight budget
+ * would throw away exactly the evidence hardest to get any other way. But a test
+ * that a customer wrote against a 30-second budget cannot afford to lend us most
+ * of it.
+ *
+ * Ten seconds fits every scan measured on the fixture site and on the reference
+ * implementation's ordinary pages, and cuts off the pathological case before it
+ * can take a test down with it.
+ */
+export const DEFAULT_SCAN_TIMEOUT_MS = 10_000;
+/**
+ * The kill switch, read from the environment rather than from config.
+ *
+ * A customer who suspects the SDK of breaking their suite needs to test that
+ * suspicion in one command, on a branch they have not touched, in CI they cannot
+ * edit. Making them change a config file first means the check is annoying enough
+ * to skip — and "is it you or is it me" is the question we most want them to be
+ * able to answer quickly, because the answer is sometimes yes.
+ *
+ * It is also how we get a baseline for our own measurements without asking anyone
+ * to revert anything.
+ */
+export function isDisabled(env = process.env) {
+    const value = env['SETSQUARE_DISABLED'];
+    return value !== undefined && value !== '' && value !== '0' && value !== 'false';
+}
+/**
+ * Per-invocation auto-scan override, from the environment.
+ *
+ * Exists for multi-invocation suites: axe is the bulk of the SDK's per-test
+ * cost, and a functional lane whose surfaces the a11y lane scans anyway is
+ * paying that cost twice for evidence the merge would deduplicate. The config
+ * file cannot carry this — it is the same file for every lane — so the lane
+ * that should not scan says so: `SETSQUARE_AUTOSCAN=0`.
+ *
+ * Deliberately narrower than the kill switch. `SETSQUARE_DISABLED` removes the SDK
+ * from the run entirely; this keeps observations, test outcomes and the run
+ * artifact — the lane still contributes to the merged run's e2e visibility and
+ * to the visited-but-never-scanned union — and skips only the scanning.
+ * Explicit `setsquare.scan()` calls still run: the customer asked for those by name.
+ *
+ * Returns undefined when unset, so config and defaults keep deciding.
+ */
+export function autoScanOverride(env = process.env) {
+    const value = env['SETSQUARE_AUTOSCAN'];
+    if (value === undefined || value === '')
+        return undefined;
+    return value !== '0' && value !== 'false';
+}
+/**
+ * Per-invocation output directory, from the environment.
+ *
+ * Exists for `setsquare verify`, and the reason is a hazard rather than a
+ * convenience. Verify re-runs one surface to see whether a rule still fires — which
+ * means invoking the customer's own Playwright, which means the SDK writes a run.
+ * Writing it into `.setsquare/runs/` would make the re-scan **become the latest
+ * run**: `audit`, `report`, `findings` and `sarif` all read that, and `pruneRuns`
+ * would delete the real run it replaced. A command that silently overwrites the
+ * artefact every other command reads is worse than no command, so verify redirects
+ * the output instead.
+ *
+ * An env rather than a config option, for the same reason `SETSQUARE_RUN_ID` and
+ * `SETSQUARE_AUTOSCAN` are: it changes per invocation while the config file does
+ * not, and Playwright constructs reporters from JSON-safe config entries.
+ *
+ * Useful beyond verify — a CI lane that wants its evidence somewhere specific can
+ * set it — which is why it is a general option and not a `SETSQUARE_VERIFY=1` flag.
+ *
+ * Returns undefined when unset, so config and defaults keep deciding.
+ */
+export function outputDirOverride(env = process.env) {
+    const value = env['SETSQUARE_OUTPUT_DIR'];
+    if (value === undefined || value.trim() === '')
+        return undefined;
+    return value.trim();
+}
+/**
+ * Where to write the run summary as markdown.
+ *
+ * `SETSQUARE_SUMMARY_MD=<path>` makes the reporter write the summary it just
+ * printed, rendered through `renderMarkdown`, to that path as well. Nothing else
+ * changes: the terminal still gets whatever `format` asks for, and the file is a
+ * second rendering of the SAME input rather than a second summary.
+ *
+ * It exists for CI job summaries — GitHub's `$GITHUB_STEP_SUMMARY`, GitLab's
+ * report pages — and it is deliberately a path rather than a `github: true` flag,
+ * because the SDK has no business knowing which CI it is running under. The
+ * official Action points this at a file it owns and appends that file itself, so
+ * append-versus-replace stays the caller's decision.
+ *
+ * An env rather than a config option for the same reason as `SETSQUARE_OUTPUT_DIR`:
+ * it changes per invocation while the config file does not.
+ *
+ * The alternative was a CLI command that renders markdown from `run.json` — but
+ * `@setsquare/review-sdk` depends on `@setsquare/review-cli`, so the CLI cannot read the
+ * SDK's renderer, and rewriting it there is exactly the second renderer that
+ * `report.ts` forbids. One renderer, a second destination.
+ */
+export function summaryMarkdownPath(env = process.env) {
+    const value = env['SETSQUARE_SUMMARY_MD'];
+    if (value === undefined || value.trim() === '')
+        return undefined;
+    return value.trim();
+}
+/**
+ * Changed-only mode: scan just the surfaces a change can reach.
+ *
+ * `SETSQUARE_CHANGED_ONLY=<path>` points at the file `setsquare changed` writes.
+ * The SDK does no route reasoning of its own — it compares patterns it already
+ * computes against a list, which is why this is a few lines rather than an adapter.
+ * The route knowledge lives in the CLI, where the adapters are, and
+ * `sdk/src/style.ts` records the standing decision that CLI code must not enter a
+ * test process's import graph.
+ *
+ * Two shapes in that file mean different things and must not be conflated:
+ * `routes: []` is "nothing changed that touches a route", and `routes: null` is
+ * "we could not work it out". Only the first licenses skipping anything; `null`
+ * means scan everything, because a set that might be missing surfaces is worse
+ * than no set at all.
+ */
+export function changedOnlyRoutes(env = process.env, read = (path) => readFileSync(path, 'utf8')) {
+    const path = env['SETSQUARE_CHANGED_ONLY'];
+    if (path === undefined || path.trim() === '')
+        return undefined;
+    try {
+        const parsed = JSON.parse(read(path.trim()));
+        // `null`, a missing key, or anything that is not an array: not a licence to skip.
+        if (!Array.isArray(parsed.routes))
+            return undefined;
+        return new Set(parsed.routes.filter((route) => typeof route === 'string'));
+    }
+    catch {
+        // Unreadable or malformed. Scanning everything is the safe failure.
+        return undefined;
+    }
+}
+export function resolveOptions(options = {}) {
+    return {
+        scanTimeoutMs: options.scanTimeoutMs ?? DEFAULT_SCAN_TIMEOUT_MS,
+        disabled: isDisabled(),
+        // The env wins over the config: it is the per-invocation statement, and the
+        // config file is the same file for every lane.
+        outputDir: outputDirOverride() ?? options.outputDir ?? DEFAULT_OUTPUT_DIR,
+        promo: options.promo ?? true,
+        rules: {
+            target: options.wcag ?? DEFAULT_RULE_POLICY.target,
+            bestPractice: options.bestPractice ?? DEFAULT_RULE_POLICY.bestPractice,
+        },
+        // Env outranks config here, because the config is shared across lanes and
+        // the whole point of the override is to differ per lane.
+        autoScan: autoScanOverride() ?? options.autoScan ?? true,
+        format: options.format ?? 'text',
+        grid: options.grid ?? 'matrix',
+        readingLevel: options.readingLevel ?? (options.wcag ?? DEFAULT_RULE_POLICY.target) === 'AAA',
+        settle: {
+            quietMs: options.quietMs ?? DEFAULT_SETTLE.quietMs,
+            settleTimeoutMs: options.settleTimeoutMs ?? DEFAULT_SETTLE.settleTimeoutMs,
+        },
+        mask: {
+            ...(options.mask ? { mask: options.mask } : {}),
+            ...(options.maskDefaults !== undefined ? { maskDefaults: options.maskDefaults } : {}),
+        },
+        inference: {
+            ...(options.surfaces ? { surfaces: options.surfaces } : {}),
+            ...(options.personas ? { personas: options.personas } : {}),
+            ...(options.themes ? { themes: options.themes } : {}),
+            ...(options.persona ? { persona: options.persona } : {}),
+            ...(options.theme ? { theme: options.theme } : {}),
+        },
+    };
+}
+//# sourceMappingURL=options.js.map

package/dist/options.js.map

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

package/dist/output.d.ts

@@ -0,0 +1,113 @@
+import type { RunEnvelope, RunMeta } from './contract.js';
+/**
+ * Write the run to disk: the envelope, and its sidecar.
+ *
+ * Two files, and the split is the whole design. `run.json` is the ingest request
+ * body byte-for-byte — nothing added, nothing removed — so the SDK's own test
+ * suite can validate it against the generated JSON Schema and the claim "the
+ * same artifact the platform would have received" is checkable. Every local fact
+ * that would otherwise have to be smuggled into the wire shape goes in
+ * `meta.json` instead.
+ *
+ * This is also why there is no `x-setsquare-local` extension field. The envelope is
+ * `.strict()`, and that strictness is exactly the mechanism that stopped `runId`
+ * creeping back after P1-17.7 removed it. Putting a licensed hole in it to carry
+ * a file path would trade a real guarantee for a small convenience.
+ */
+export interface WriteRunResult {
+    runDir: string;
+    envelopePath: string;
+    metaPath: string;
+}
+/**
+ * Sortable, collision-resistant, and readable at a glance in a directory listing.
+ *
+ * Derived from `generatedAt` rather than a fresh clock so the directory name and
+ * the envelope's own timestamp can never disagree. Colons are stripped because
+ * they are illegal in filenames on Windows, and a customer on Windows finding
+ * that we cannot write our own output would be an unforced error.
+ *
+ * The engine used to be part of this name and deliberately is not any more. A
+ * single Playwright run can span three engines — the compatibility matrix
+ * requires it — so a directory named after one of them would be wrong for every
+ * mixed run, and quietly right-looking. The engine belongs to each test result,
+ * which is the only place it is ever singular.
+ */
+export declare function runDirName(generatedAt: string): string;
+/**
+ * Write a file so no reader can ever observe it half-written.
+ *
+ * A plain `writeFile` is atomic against other writers of *different* files, but
+ * not against a reader that lists the directory the instant the file appears —
+ * which is exactly what a concurrent invocation's merge does. Content goes to a
+ * uniquely-named sibling first, then renames into place; rename is atomic on
+ * every filesystem we run on, so a reader sees the old bytes or the new bytes
+ * and never a prefix.
+ *
+ * The rename is retried because Windows refuses to replace a file another
+ * process holds open without FILE_SHARE_DELETE — antivirus scanners and search
+ * indexers do this routinely, briefly. A short backoff outlasts almost all of
+ * them; persistent failure propagates, because falling back to a plain
+ * overwrite would reintroduce the torn read this function exists to prevent.
+ */
+export declare function writeFileAtomic(path: string, content: string): Promise<void>;
+export declare function writeRun(outputDir: string, baseDir: string, envelope: RunEnvelope, meta: Omit<RunMeta, 'envelopePath' | 'outputDir'>): Promise<WriteRunResult>;
+/**
+ * The write itself, with the destination chosen by the caller.
+ *
+ * Split from `writeRun` because a grouped run's directory is keyed by the
+ * orchestrator's id rather than by this invocation's clock — but what goes IN
+ * the directory, and how it gets there, must not differ between the two paths.
+ *
+ * `run.json` lands before `meta.json`, deliberately: the sidecar describes the
+ * envelope (down to a content hash, when grouped), so a reader must never find
+ * a sidecar whose envelope does not exist yet.
+ */
+export declare function writeRunInto(runDir: string, outputRoot: string, envelope: RunEnvelope, meta: Omit<RunMeta, 'envelopePath' | 'outputDir'>): Promise<WriteRunResult>;
+/** A run-group directory, keyed by the orchestrator's id rather than a clock. */
+export declare const GROUP_DIR_PATTERN: RegExp;
+export interface PruneOptions {
+    /** A timestamp-named run dir to keep; timestamp dirs sorting before it go. */
+    currentName?: string;
+    /** A group dir name to keep unconditionally — the run being written now. */
+    currentGroupName?: string;
+}
+export declare function pruneRuns(runsRoot: string, options: PruneOptions): Promise<void>;
+/**
+ * The HTML report, written beside `run.json` in the same run directory.
+ *
+ * Separate from `writeRun` rather than folded into it, because the two must be
+ * allowed to fail independently: a template bug must cost the customer the
+ * report and nothing else — never the envelope, and never the terminal
+ * summary. The reporter wraps this call in its own try.
+ */
+export declare function writeHtmlReport(runDir: string, html: string): Promise<string>;
+/**
+ * The visual contact sheet, written beside `report.html` in the same run
+ * directory.
+ *
+ * Its own file and its own failure domain, for the same reason the HTML report
+ * has one: a template bug in the sheet must cost the customer the sheet and
+ * nothing else — not the envelope, not the accessibility report, not the
+ * terminal summary. The reporter wraps this call in its own try.
+ *
+ * The name is stable and boring on purpose. It is a path people put in a
+ * `.gitignore`, a CI artifact glob and a bookmark, and renaming it later would
+ * break all three.
+ */
+export declare function writeScreensReport(runDir: string, html: string): Promise<string>;
+/**
+ * The summary as markdown, at a path the caller named.
+ *
+ * Directed by `SETSQUARE_SUMMARY_MD` and written nowhere by default, because this
+ * is not one of the run's artefacts — it is a second rendering of the terminal
+ * summary for a CI job-summary panel, and a file that appears in every
+ * `.setsquare/runs/` directory whether anyone asked for it or not would be one
+ * more thing to explain and one more thing to gitignore.
+ *
+ * `resolve` against the base directory rather than trusting the string, and its own
+ * failure domain like every other optional artefact here: a summary that could not
+ * be written must cost the summary and nothing else.
+ */
+export declare function writeSummaryMarkdown(baseDir: string, path: string, markdown: string): Promise<string>;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBlF;AAED,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,WAAW,EACrB,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,WAAW,CAAC,GAChD,OAAO,CAAC,cAAc,CAAC,CAazB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,WAAW,EACrB,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,WAAW,CAAC,GAChD,OAAO,CAAC,cAAc,CAAC,CAezB;AAkBD,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,QAA4C,CAAC;AAa3E,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCtF;AA8BD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAItF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAKjB"}