a11ign 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# `a11ign`
+
+Drives a **real screen reader** through a real page and reports the WCAG 2.2 AA failures a rule scanner cannot
+see — the ones that need to know what a blind user actually heard, and whether they could still finish the task.
+
+**Alongside axe, never instead of it.** Both layers run; neither subsumes the other.
+
+**Two ways in that work today.** No install and no Windows machine of your own — add the action to a
+workflow:
+
+```yaml
+runs-on: windows-2022          # NVDA is Windows-only; the action fails fast and says so otherwise
+steps:
+  - uses: actions/checkout@v4
+  - uses: a11ign/a11ign@main
+    with:
+      url: https://example.com/contact
+      task: Send an enquiry
+      fail-on: never           # report first; gate when your team asks for it
+```
+
+Or run it yourself from a checkout:
+
+```bash
+git clone https://github.com/a11ign/a11ign.git
+cd a11ign
+npm install
+npm run witness -- https://example.com --task "Find the opening hours"
+```
+
+**See the [top-level README](../../README.md) for which of those two paths is yours** — this file does not
+repeat that decision.
+
+> **`npx a11ign` does NOT work yet, and that is why it is not the first thing on this page.**
+> `npx a11ign https://example.com --task "Find the opening hours"` is what the CLI *is*, and it
+> works from a checkout — but no package has been pushed to npm, so run as typed it returns `E404` and
+> teaches a reader only that the tool is broken. The name is still undecided (PLAN.md, B5); publishing is
+> tracked as PLAN.md B7. It will move to the top of this file on the day it is true.
+
+## What "a rule scanner cannot see" means, concretely
+
+Measured against the University of Washington "Accessible University" demo — a third-party, expert-built
+inaccessible page and its accessible twin:
+
+| | before (inaccessible) | after (accessible) |
+|---|---|---|
+| screen-reader layer | 1.1.1, 1.1.1, 4.1.2, **2.4.4**, **1.3.1** | none |
+| axe | 1.4.3, 3.1.1, 1.1.1, 4.1.2, 1.4.1, 2.5.8 | none |
+
+Two findings only the screen-reader layer produced, quoting what a user hears:
+
+```
+2.4.4 Link Purpose          heard: "click here, link"
+1.3.1 Info & Relationships  heard: "102 announcements, no heading among them"
+```
+
+axe reports neither, and not by oversight: its `link-name` rule asks whether a link *has* an accessible name,
+and "click here" has one. Meanwhile axe found four things a screen reader cannot perceive at all — contrast,
+target size, language. That is the argument for running both, and the accessible twin being clean on both
+matters more than either list.
+
+## It will not tell you about anything visual
+
+Contrast, focus-visible, reflow, target size: a screen reader cannot see them. Every report **says so** when
+the rule layer did not run, because "we checked and found nothing" and "we did not check" must never look
+alike. Reporting silence as a clean bill of health is the single most misleading thing this tool could do.
+
+```bash
+npx a11ign <url> --no-axe                    # screen-reader layer only, and the report says so
+npx a11ign <url> --axe-results axe.json      # import a run you already did
+npx a11ign <url> --json                      # machine-readable, for CI
+```
+
+## You need a Windows worker
+
+The capture runs on Windows, with NVDA, in an interactive desktop session — that is not a limitation to work
+around, it is what makes the evidence real. Point the CLI at one:
+
+```bash
+A11Y_WORKER=http://REDACTED-INTERNAL-ADDRESS:8765 npx a11ign <url> --task "..."
+```
+
+**UTM is DEPRECATED — it was a testing path, not the fleet.** `@a11ign/worker-fleet` can still lease a
+local UTM VM on macOS and put it back as it found it, and every UTM entry point now says so at runtime. Point
+`A11Y_WORKER` at a Windows machine you have, or use the GitHub Action if you have none. See
+`docs/getting-started.md` for setting a worker up, and `@a11ign/nvda-worker` for the worker itself.
+
+## Judging what the screen reader heard
+
+By default the judge is a small trained scorer shipped with this tool — no API key, no metered cost, no
+network call for the judgment itself. Point it at a rented model instead if you want a second opinion or
+do not trust the local one yet:
+
+```bash
+JUDGE_BACKEND=openai OPENAI_API_KEY=sk-... npx a11ign <url> --task "..."
+```
+
+`JUDGE_BACKEND=openai` speaks plain `/v1/chat/completions`, so it works against hosted OpenAI, Anthropic's
+OpenAI-compatible endpoint, or a local server (Ollama, LM Studio, vLLM, llama.cpp) — set `JUDGE_BASE_URL`
+to point it somewhere other than `api.openai.com`. `JUDGE_API_KEY` is accepted as a project-neutral alias
+for `OPENAI_API_KEY` if you would rather not put a provider's name on the variable. Other knobs, all
+optional: `JUDGE_MODEL` (which model to ask for), `JUDGE_TIMEOUT_MS` (default 120000), `JUDGE_REASONING`
+(default `medium`, for models that support a reasoning-effort parameter). If a server rejects
+constrained/structured JSON output, set `JUDGE_STRUCTURED=off` — most reject silently in ways that read as
+a truncated or malformed response, so this is the first thing to try if `openai` backend responses look
+corrupted against a self-hosted server.
+
+`codex` and `anthropic` backends also exist, for comparison; none of the three rented backends is ever the
+default.
+
+## A page behind a consent wall is REFUSED, not reported
+
+The screen reader gets held inside the modal, so the capture describes the dialog rather than the page.
+
+**What the CLI actually does — this paragraph used to say "the run exits 2", and it does not.** It writes a
+warning to stderr naming which kind of doubt it was, marks the result `captureVerified: false` with an
+`unverifiedReason`, and **reports no findings rather than describing the dialog**. The report says so in
+words. The run's exit code is decided by `--fail-on` as usual; the only thing here that exits 2 is a bad
+`--forms` config. (Exit 2 on an unverified capture is `capture-check.mjs`, a lab harness, and this README
+had inherited its behaviour.)
+
+This is deliberate and it is the check that matters most in the whole tool: on one real site the census
+found 793 links and 463 headings while the screen reader reached 1 heading and 0 links, and an earlier
+version reported "No lived-experience findings" — for a page it had never seen. **Refusing to report is the
+point; the exit code is not what does it.**
+
+## Rendering the report yourself
+
+```js
+import { reportLines } from "a11ign";
+
+console.log(reportLines(report).join("\n"));
+```
+
+`reportLines` and the `Report` type are the entire public API. Findings come back in the order a user meets
+them — perceive, then navigate, then interact — because a finding about operating a control is not useful to
+someone who could not perceive it.
+
+The pieces underneath are packages in their own right: `@a11ign/judge` for the judgment,
+`@a11ign/evidence` for the capture contract, `@a11ign/worker-fleet` for the VM lifecycle.

package/dist/action/post-comment.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Does a real summary file exist at `path`? The ONE fact this module exists to check before choosing a
+ * message, rather than assuming the earlier step succeeded because this step was reached at all --
+ * `if: always()` on the caller means this runs whether or not anything upstream produced output.
+ * @param {string} path
+ * @returns {boolean}
+ */
+export declare function reportSummaryExists(path: string): boolean;
+/**
+ * The message to print when the PR comment could not be posted, as a pure function of whether a real
+ * report exists -- #493's own acceptance: the two states must never print the same sentence. `reportExists:
+ * true` means `gh pr comment` itself failed (network, permissions, rate limit) while a real report sits in
+ * the job summary, so the ORIGINAL sentence is honest there and stays. `reportExists: false` means there
+ * was never anything to post -- and pointing the reader at a job summary that was never written is worse
+ * than saying nothing, per #493's own framing: "they now doubt their own reading rather than the tool."
+ * @param {boolean} reportExists
+ * @returns {string}
+ */
+export declare function commentFailureMessage(reportExists: boolean): string;
+//# sourceMappingURL=post-comment.d.ts.map

package/dist/action/post-comment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-comment.d.ts","sourceRoot":"","sources":["../../src/action/post-comment.ts"],"names":[],"mappings":"AAyCA;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,OAAO,GAAG,MAAM,CAKnE"}

package/dist/action/post-comment.js

@@ -0,0 +1,93 @@
+// #493: "Could not post the PR comment. The job summary still has the report" used to print unconditionally
+// on ANY `gh pr comment` failure -- including the one the V1 rehearsal hit on all three of its runs, where
+// the build died before `run.ts` ever produced a summary at all. `run.ts` writes $GITHUB_STEP_SUMMARY and
+// its `--summary-out` file in the SAME call, after the SAME early-exit checks (a missing/unreadable result,
+// or a result with no verdict) -- so an absent summary FILE means the step summary is absent too, never
+// just a different place the reader missed. This repo's own most-recorded fault class -- "a diagnostic that
+// cannot report itself" -- pointed at a user instead of at us.
+//
+// Deliberately separate from `run.ts`, mirroring that file's own split from `action.yml`: the POLICY (which
+// message, and whether the file genuinely exists) is testable here without a real `gh` call; the mechanics
+// of actually posting stay in `main()`, which nothing but `action.yml` invokes.
+//
+// #567: NO WORKSPACE IMPORT, DELIBERATELY -- this file used to import `flagValue` from
+// `@a11ign/worker-fleet/cli-flags`, which needs BOTH `node_modules` and a completed build
+// (`pre-install-import-graph.test.ts`'s own header). This step runs `if: always()` in `action.yml`,
+// specifically so it still reports when an EARLIER step failed -- and "Install a11ign" (the step that
+// creates `node_modules` in the action's own checkout) is itself one of the steps that can fail or never
+// run (measured live: the V1 rehearsal's #568, a `setup-node` cache step dying before "Install a11ign"
+// ever starts). So the one step whose entire job is to report honestly on failure was, itself, silently
+// unable to run under exactly the failure shape it exists to handle -- the identical class #535 fixed in
+// `packages/guards/src/piped-exit-status-guard.mjs` the same day, missed here because this file was only ever tested
+// inside this repo's own fully-installed checkout, never through the real composite-action path a
+// consumer's workflow actually uses. `flagValue`'s own body is four lines; reproduced inline below rather
+// than imported.
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+/**
+ * `flagValue`'s own logic, reproduced rather than imported -- see this file's header for why. Pure and
+ * tiny enough that a second copy is cheaper than the workspace dependency it would otherwise require.
+ * @param {string[]} argv
+ * @param {string} name
+ * @returns {string | undefined}
+ */
+function flagValue(argv, name) {
+    const prefix = `--${name}=`;
+    const hit = argv.find((a) => a.startsWith(prefix));
+    return hit === undefined ? undefined : hit.slice(prefix.length);
+}
+/**
+ * Does a real summary file exist at `path`? The ONE fact this module exists to check before choosing a
+ * message, rather than assuming the earlier step succeeded because this step was reached at all --
+ * `if: always()` on the caller means this runs whether or not anything upstream produced output.
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function reportSummaryExists(path) {
+    return existsSync(path);
+}
+/**
+ * The message to print when the PR comment could not be posted, as a pure function of whether a real
+ * report exists -- #493's own acceptance: the two states must never print the same sentence. `reportExists:
+ * true` means `gh pr comment` itself failed (network, permissions, rate limit) while a real report sits in
+ * the job summary, so the ORIGINAL sentence is honest there and stays. `reportExists: false` means there
+ * was never anything to post -- and pointing the reader at a job summary that was never written is worse
+ * than saying nothing, per #493's own framing: "they now doubt their own reading rather than the tool."
+ * @param {boolean} reportExists
+ * @returns {string}
+ */
+export function commentFailureMessage(reportExists) {
+    return reportExists
+        ? "::warning::Could not post the PR comment. The job summary still has the report."
+        : "::warning::No report was produced -- the run failed before a result existed to summarize. "
+            + "See the earlier step's own error above for what actually went wrong.";
+}
+function main() {
+    const arg = (name) => flagValue(process.argv, name);
+    const summaryPath = arg("summary");
+    const prNumber = arg("pr");
+    const repo = arg("repo");
+    if (!summaryPath || !prNumber || !repo) {
+        process.stderr.write("usage: tsx packages/cli/src/action/post-comment.ts --summary=<file> --pr=<n> --repo=<owner/name>\n");
+        process.exit(2);
+    }
+    // CHECKED, NOT ASSUMED -- the whole point of this file. A missing summary is not something `gh pr
+    // comment` needs to be asked about; there is nothing honest it could report by being run against a file
+    // that was never written.
+    if (!reportSummaryExists(summaryPath)) {
+        process.stderr.write(`${commentFailureMessage(false)}\n`);
+        return;
+    }
+    try {
+        execFileSync("gh", ["pr", "comment", prNumber, "--body-file", summaryPath, "--edit-last", "--create-if-none", "--repo", repo], { stdio: "inherit" });
+    }
+    catch {
+        process.stderr.write(`${commentFailureMessage(true)}\n`);
+    }
+}
+// RUN ONLY WHEN INVOKED -- `pathToFileURL`, never a template literal, for the identical reason `run.ts`
+// carries beside its own copy of this guard: concatenation does not percent-encode a space in the path.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href)
+    main();
+//# sourceMappingURL=post-comment.js.map

package/dist/action/post-comment.js.map

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

package/dist/action/run.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run.d.ts.map

package/dist/action/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/action/run.ts"],"names":[],"mappings":""}

package/dist/action/run.js

@@ -0,0 +1,119 @@
+// The Action's entry point: read a witness run's JSON, write the summary, decide the exit code.
+//
+//   tsx packages/cli/src/action/run.ts --result=run.json [--fail-on=never|any|blocker|serious|moderate|minor]
+//                         [--summary-out=summary.md] [--marker=a11ign]
+//
+// Deliberately separate from `src/cli.ts`. The CLI's job is to capture and judge; this one's job is to
+// present that to GitHub and decide whether the check passes. Keeping them apart means the Action's
+// policy is testable (`summary.test.ts`) without a Windows runner, and a change to how findings are
+// displayed cannot break how they are produced.
+import { readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { logLines, renderSummary, shouldFail } from "./summary.js";
+import { taskVerdictLabel } from "@a11ign/judge";
+import { announcedStateChanges } from "@a11ign/judge/rules";
+import { flagValue } from "@a11ign/worker-fleet/cli-flags";
+// audit §9 "argv parsing": this was its own copy of the fifteen-file idiom. `flagValue` is the shared,
+// tested extraction; `?? fallback` stays here because defaulting is this call site's business, not the
+// extractor's.
+/**
+ * The Action's whole body, so importing this file does not RUN it.
+ *
+ * It was top-level code ending in `process.exit`, which meant nothing could import it — not a test, not
+ * another entry point — and `entry-points.test.ts` could not see that, because it discovers entry points
+ * from `package.json` scripts and this one is invoked by `action.yml`. Two blindnesses, one file: a guard
+ * that was never there, in a place the guard for it could not look.
+ *
+ * `process.exit` stays inside rather than becoming a returned code. This IS the process's last act, the
+ * exit codes are the Action's documented contract (2 = we could not look, 1 = findings met the
+ * threshold), and routing them through a return value would put a second place where that contract can be
+ * got wrong. What the wrapper buys is that the code no longer runs merely because somebody imported the
+ * module.
+ */
+/**
+ * #1391: which state changes were announced correctly is the JUDGE's call, through the same gates as
+ * `4.1.2:state-change-silent`; the renderer only shows the list, the way it only shows the task label. A result
+ * written before the probe carries no `interaction`, and then there is nothing to show.
+ */
+function observedStateChanges(result) {
+    return announcedStateChanges(result.interaction?.stateChanges ?? []);
+}
+function main() {
+    const arg = (name, fallback) => flagValue(process.argv, name) ?? fallback;
+    const resultPath = arg("result");
+    if (!resultPath) {
+        process.stderr.write("usage: tsx packages/cli/src/action/run.ts --result=<file.json> [--fail-on=...] [--summary-out=...]\n");
+        process.exit(2);
+    }
+    const failOn = arg("fail-on", "never");
+    const marker = arg("marker", "a11ign");
+    let result;
+    try {
+        result = JSON.parse(readFileSync(resolve(resultPath), "utf8"));
+    }
+    catch (error) {
+        // A capture that never produced JSON is an infrastructure failure, not a clean page. Failing loudly
+        // here is the difference between "your page is fine" and "we did not manage to look at it" — the
+        // distinction this whole project is built around.
+        process.stderr.write(`a11ign: could not read the run result at ${resultPath}: ${error.message}\n`);
+        process.exit(2);
+    }
+    if (!result?.verdict || !Array.isArray(result.verdict.findings)) {
+        process.stderr.write("a11ign: the run result has no verdict — the judge did not complete, so nothing was assessed.\n");
+        process.exit(2);
+    }
+    const label = taskVerdictLabel();
+    const markdown = renderSummary(result, {
+        marker, taskQuestion: label.question, isTaskClaim: label.isTaskClaim, stateChangesObserved: observedStateChanges(result),
+    });
+    // An unverified capture is an infrastructure failure, not a verdict about the page — so it exits 2, the
+    // same code used for "could not read the result". Green would say "we checked and it is fine"; red (1)
+    // would say "your page has a problem". Neither is true: we did not manage to look at it.
+    //
+    // The summary is written FIRST so the reader still gets the explanation. Found on gov.uk, where the
+    // capture read Edge's image-magnifier overlay, the retry warned three times, and the run reported a 4.1.2
+    // finding about the browser's own Zoom In / Rotate buttons.
+    const unverified = result.captureVerified === false;
+    // $GITHUB_STEP_SUMMARY is append-only and shared with other steps, so append rather than overwrite.
+    const stepSummary = process.env.GITHUB_STEP_SUMMARY;
+    if (stepSummary)
+        appendFileSync(stepSummary, `${markdown}\n`);
+    const summaryOut = arg("summary-out");
+    if (summaryOut)
+        writeFileSync(resolve(summaryOut), `${markdown}\n`, "utf8");
+    if (!stepSummary && !summaryOut)
+        process.stdout.write(`${markdown}\n`);
+    // The summary has already been written above, so this only decides the exit code. Writing it again here
+    // appended it TWICE to $GITHUB_STEP_SUMMARY, which is append-only.
+    if (unverified) {
+        process.stderr.write("a11ign: the capture could not be confirmed to have read the requested page; "
+            + "reporting no findings. This is a failed measurement, not a clean page.\n");
+        process.exit(2);
+    }
+    const { findings } = result.verdict;
+    let fail;
+    try {
+        fail = shouldFail(findings, failOn);
+    }
+    catch (error) {
+        // An unrecognised `fail-on` is a workflow typo, and the dangerous outcome is treating it as "never":
+        // the check goes green and nobody looks again. Refuse instead.
+        process.stderr.write(`a11ign: ${error.message}. Use never|any|blocker|serious|moderate|minor.\n`);
+        process.exit(2);
+    }
+    // #1363: the log is what a reader sees without opening the summary, so it says where the examination ended
+    // BEFORE it counts findings -- a bare count reads as a verdict about everything the run touched.
+    for (const line of logLines(result, failOn))
+        process.stderr.write(`${line}\n`);
+    if (fail) {
+        process.stderr.write(`a11ign: failing the check — asserted findings met the ${failOn} threshold.\n`);
+        process.exit(1);
+    }
+}
+// RUN ONLY WHEN INVOKED. `pathToFileURL`, never a template literal: concatenation does not
+// percent-encode, so a checkout under a path containing a SPACE compares false, the guard never fires,
+// and the Action exits 0 having assessed nothing -- which a workflow reads as a passing check.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href)
+    main();
+//# sourceMappingURL=run.js.map

package/dist/action/run.js.map

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

package/dist/action/summary.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Render a witness run as Markdown for a GitHub job summary or PR comment, and decide pass/fail.
+ *
+ * Kept pure and separate from the Action's YAML so the output is testable without pushing a commit and
+ * waiting for a Windows runner. That matters more here than usual: the whole point of the Action is to
+ * tell someone their page has an accessibility problem, so a renderer that drops a finding, or a gate
+ * that passes when it should fail, is worse than no Action at all.
+ */
+export type Severity = "blocker" | "serious" | "moderate" | "minor";
+import type { CaptureInteraction } from "@a11ign/evidence";
+import type { Judgment } from "@a11ign/judge";
+import type { announcedStateChanges } from "@a11ign/judge/rules";
+export interface RunFinding {
+    issue: string;
+    wcag: string;
+    severity: Severity;
+    evidence: string;
+    confidence: number;
+    /**
+     * #1366: whether this finding ASSERTS the criterion (`conformance`) or REFERS it (absent or `secondary`) -- the
+     * judge's own `RequirementMapping`, taken from its `Judgment` type so it has one definition. The result JSON has
+     * carried it all along; this renderer dropped it, so a referral rated `serious` was logged as "1 serious".
+     */
+    mapping?: Judgment["findings"][number]["mapping"];
+}
+export interface RunResult {
+    /**
+     * False when the capture could not be confirmed to have read the requested page.
+     *
+     * Not cosmetic. On gov.uk the capture read Edge's image-magnifier overlay, the retry fired three times
+     * and warned, and the run still reported a 4.1.2 finding about the browser's own Zoom In / Rotate
+     * buttons as if the site were at fault. Findings from an unverified capture are not merely unreliable,
+     * they can blame a page for its browser — so they are not shown at all.
+     */
+    captureVerified?: boolean;
+    /**
+     * Why the capture is unverified: `"wrong-content"` (it read something else) or `"contained"` (it read
+     * only part of the right page, almost always a consent or cookie modal holding the screen reader).
+     * Absent on older results, which are explained with the original wrong-content wording.
+     */
+    captureUnverifiedReason?: "wrong-content" | "contained";
+    url: string;
+    task: string;
+    screenReader: string;
+    transcript?: string[];
+    /** null when the rule layer did not run — NOT the same as running and finding nothing. */
+    ruleBased: {
+        impact: string;
+        wcag: string[];
+        rule: string;
+        help: string;
+        nodes?: {
+            target?: unknown[];
+        }[];
+    }[] | null;
+    verdict: {
+        taskCompletable: boolean;
+        summary: string;
+        findings: RunFinding[];
+        confidence: number;
+    };
+    /**
+     * Per-criterion ACT outcomes, when the result carries them.
+     *
+     * `cli.ts --json` has emitted these all along and this renderer dropped them, so the most PUBLIC output
+     * this tool produces — a comment on somebody's pull request, in bold — could not say `cantTell`. A page
+     * where six of the ten covered criteria came back undetermined rendered identically to one where all ten
+     * passed. The CLI prints the tally with "Neither is clean"; the PR comment could not.
+     *
+     * Optional because an older result JSON has none, and absent must render as SILENCE rather than as a
+     * tally of zeroes — a fabricated "0 untested" would be worse than the omission it replaced.
+     */
+    outcomes?: {
+        criterion: string;
+        outcome: string;
+        reason: string;
+    }[];
+    /**
+     * Where the examination ENDED because an activation took the browser off the page's site (#1363). Nothing
+     * after it was examined and no finding describes it. Absent on results whose activations stayed on the
+     * page, and on results written before the check existed.
+     */
+    leftSite?: {
+        control: string;
+        to: string | null;
+        source: "recorded" | "derived";
+    } | null;
+    /**
+     * The disclosure probe's before/after pairs: a control as first announced, and what took focus after it was
+     * activated. Declared for #1391 only -- `run.ts` reads it to compute which changes were announced correctly --
+     * and TYPED FROM `@a11ign/evidence`'s own `CaptureInteraction`, never restated, so the shape has one definition.
+     * The import is `import type`: erased at runtime, so this renderer still imports nothing when it runs. Absent on
+     * results written before the probe.
+     */
+    interaction?: Partial<Pick<CaptureInteraction, "stateChanges">> | null;
+    /**
+     * WCAG §5.2's five conformance requirements, as `cli.ts --json` emits them (`@a11ign/evidence/conformance`).
+     * Declared for one sentence only (#1387): Requirement 2 names a capture that spanned more than one document,
+     * and until this field was declared the summary could not show it. Absent on older results, which say nothing.
+     */
+    conformance?: {
+        number: number;
+        name: string;
+        establishes: string;
+        limitation: string;
+    }[];
+}
+export declare function documentsSpannedSentence(conformance: RunResult["conformance"]): string | null;
+/** How many undetermined criteria rest on an examination known to be partial. Zero with no outcomes at all. */
+export declare function partialExaminationCount(outcomes: RunResult["outcomes"]): number;
+export type FailOn = "never" | "any" | Severity;
+/**
+ * Should this run fail the check?
+ *
+ * `never` is the default deliberately. A tool that starts failing builds the day it is installed gets
+ * uninstalled; one that reports first, and fails when the team asks it to, gets adopted. The same
+ * reasoning is why the rule layer is opt-out rather than mandatory.
+ */
+export declare function shouldFail(findings: RunFinding[], failOn: FailOn): boolean;
+/**
+ * #1388: IS THIS RULE-LAYER ROW ABOUT CONTENT INSIDE A FRAME?
+ *
+ * axe's `target` holds one selector per frame boundary it crossed, so a target of more than one entry points inside an
+ * iframe. It says the node is in A frame, never WHOSE: a same-origin frame is the author's own, and the result records no
+ * frame origin, so the marker claims no more than that. A single entry that is itself an array is a shadow-DOM path, not
+ * a frame. A row with no nodes (an older result) cannot be told, so it is not marked.
+ */
+export declare function insideFrame(row: NonNullable<RunResult["ruleBased"]>[number]): boolean;
+/**
+ * #1391: ONE STATE CHANGE ANNOUNCED CORRECTLY -- exactly the judge's `announcedStateChanges` element type, taken from
+ * it by a type-only import (erased at runtime; this renderer still loads nothing), so the shape has one definition.
+ * `from` and `to` are the expandable-state words the rule reads; `control` and `after` are the two announcements.
+ */
+export type ObservedStateChange = ReturnType<typeof announcedStateChanges>[number];
+export interface SummaryOptions {
+    /** Rows per table. Bounded because a job summary has a hard size limit and truncation must be stated. */
+    limit?: number;
+    /** Included as an HTML comment so a PR comment can be found and UPDATED rather than duplicated. */
+    marker?: string;
+    /**
+     * What `taskCompletable` should be LABELLED as, because it means different things per backend.
+     *
+     * Passed in rather than read from the environment here: this renderer is deliberately pure so the
+     * output is testable without a Windows runner, and reading process.env would end that.
+     *
+     * The default is the honest one for the shipped `local` scorer, which has no head for task completion
+     * and never sees the task — local-judge.ts computes `!findings.some(f => f.severity === "blocker")`
+     * and its own comment says claiming a task answer would be inventing one. This comment is posted on
+     * someone's PULL REQUEST in bold, so inventing it there is the worst place to do it. The LLM backends
+     * do read the task, and pass their own wording.
+     */
+    taskQuestion?: string;
+    /**
+     * `taskVerdictLabel().isTaskClaim` (`@a11ign/judge`), passed in for the identical reason `taskQuestion`
+     * is: this renderer is pure. `report.ts`'s own `verdictHeadline` already makes this split -- a bare
+     * "Yes"/"No" only when `taskCompletable` really answers a question about the task (the LLM backends).
+     * For the shipped `local` scorer it is `!findings.some(f => f.severity === "blocker")`, so a report of
+     * six SERIOUS findings answered "**No blocking findings** Yes" until this flag existed: true, and
+     * indistinguishable from a clean page to anyone who did not read past the first line. Defaults to
+     * `false`, the honest default for the backend that ships.
+     */
+    isTaskClaim?: boolean;
+    /**
+     * #1391: the state changes the screen reader announced correctly, computed by `run.ts` through the judge's
+     * `announcedStateChanges` -- the SAME gates as the `4.1.2:state-change-silent` rule, so this renderer never
+     * decides what counts. Passed in for the identical reason `taskQuestion` is: this renderer is pure. Absent or
+     * empty renders nothing, which is also what a result without the probe gets.
+     */
+    stateChangesObserved?: readonly ObservedStateChange[];
+}
+/**
+ * The Action's log lines -- EXPORTED so a test drives the real wording (#1363).
+ *
+ * When the examination ended because an activation left the site, that is said FIRST. Rehearsal 2's log read
+ * `a11ign: 1 finding(s) (1 serious)` about a finding observed on youtube.com, and a reader of that line alone
+ * would have filed a 2.4.2 bug against the W3C.
+ */
+export declare function logLines(result: RunResult, failOn: FailOn): string[];
+export declare function renderSummary(result: RunResult, options?: SummaryOptions): string;
+//# sourceMappingURL=summary.d.ts.map

package/dist/action/summary.d.ts.map

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