a11ign 0.1.0

package/dist/forms/coverage.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What a forms config can and cannot answer — ADR 0024's "properly tested", made computable.
+ *
+ * The states model exists so this is a CALCULATION rather than a judgement. Each criterion declares which
+ * states its evidence needs, so a config carrying only an error state reports 4.1.3 as half-answered and
+ * names the missing half, instead of the tool quietly assessing what it happens to have and calling it
+ * done.
+ *
+ * The three outcomes it keeps apart are the point, and today they collapse into one:
+ *   NOT CONFIGURED     the author's to supply, and the report says how
+ *   CONFIGURED         the states needed are present
+ *   PARTLY CONFIGURED  some evidence, and a named gap
+ */
+import type { FormSpec, StateName } from "./config.js";
+/**
+ * Which states each criterion's evidence needs.
+ *
+ * A single table, so the report and the docs cannot drift — ADR 0024 renders the same rows, and a second
+ * hand-kept copy of this mapping is the fact-stated-twice defect with a criterion attached.
+ *
+ * `either` means the evidence comes from FILLING rather than from submitting: 3.2.2 asks whether entering
+ * data changes context, so any state with values answers it. That is also why supplying values enables
+ * the typing probe by construction — we type the author's own value, into the field they named, at their
+ * instruction, so consent is not a second question.
+ */
+export declare const CRITERION_STATES: Readonly<Record<string, {
+    needs: StateName[];
+    mode: "all" | "either" | "partial";
+}>>;
+export type CriterionReadiness = "configured" | "partly" | "notConfigured";
+export interface FormCoverage {
+    form: string;
+    states: StateName[];
+    criteria: {
+        criterion: string;
+        readiness: CriterionReadiness;
+        why: string;
+    }[];
+}
+/** What this form's configuration can answer, criterion by criterion. */
+export declare function formCoverage(form: FormSpec): FormCoverage;
+/**
+ * What a run would SUBMIT, said before it submits anything — the `--plan` output.
+ *
+ * A guard that names the irreversible act in advance. `origin:` already stops a staging config being
+ * aimed at production, but it cannot tell an author that the file they just wrote completes a booking
+ * twice on every CI run. This can, and it is the only thing between "I configured a success state" and
+ * finding out what that meant.
+ */
+export declare function submissionPlan(forms: readonly FormSpec[], origin: string): string[];
+//# sourceMappingURL=coverage.d.ts.map

package/dist/forms/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/forms/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAA;CAAE,CAAC,CAM9G,CAAC;AAEL,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,QAAQ,GAAG,eAAe,CAAC;AAE3E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,QAAQ,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,kBAAkB,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/E;AA8BD,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,CAUzD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBnF"}

package/dist/forms/coverage.js

@@ -0,0 +1,80 @@
+/**
+ * Which states each criterion's evidence needs.
+ *
+ * A single table, so the report and the docs cannot drift — ADR 0024 renders the same rows, and a second
+ * hand-kept copy of this mapping is the fact-stated-twice defect with a criterion attached.
+ *
+ * `either` means the evidence comes from FILLING rather than from submitting: 3.2.2 asks whether entering
+ * data changes context, so any state with values answers it. That is also why supplying values enables
+ * the typing probe by construction — we type the author's own value, into the field they named, at their
+ * instruction, so consent is not a second question.
+ */
+export const CRITERION_STATES = Object.freeze({
+    "3.3.1": { needs: ["error"], mode: "all" },
+    "3.3.3": { needs: ["error"], mode: "all" },
+    "4.1.3": { needs: ["error", "success"], mode: "partial" },
+    "3.2.2": { needs: ["error", "success"], mode: "either" },
+});
+function readinessFor(criterion, present) {
+    const spec = CRITERION_STATES[criterion];
+    const missing = spec.needs.filter((state) => !present.has(state));
+    if (missing.length === 0) {
+        return { readiness: "configured", why: `every state this criterion needs is configured.` };
+    }
+    if (missing.length === spec.needs.length) {
+        return {
+            readiness: "notConfigured",
+            why: `needs a ${spec.needs.join(" or ")} state, and this form declares neither.`,
+        };
+    }
+    // Some present, some missing. What that COSTS differs by mode, and saying which is the whole value.
+    if (spec.mode === "either") {
+        return { readiness: "configured", why: "answered by filling the form; submitting is not required." };
+    }
+    if (spec.mode === "partial") {
+        return {
+            readiness: "partly",
+            why: `answered for the ${[...present].join(" and ")} path only. No ${missing.join(" or ")} state was `
+                + `supplied, so whether a ${missing.join("/")} status is announced is unknown.`,
+        };
+    }
+    return { readiness: "notConfigured", why: `needs a ${missing.join(" and ")} state.` };
+}
+/** What this form's configuration can answer, criterion by criterion. */
+export function formCoverage(form) {
+    const present = new Set(form.states.map((state) => state.state));
+    return {
+        form: form.form,
+        states: [...present],
+        criteria: Object.keys(CRITERION_STATES).map((criterion) => ({
+            criterion,
+            ...readinessFor(criterion, present),
+        })),
+    };
+}
+/**
+ * What a run would SUBMIT, said before it submits anything — the `--plan` output.
+ *
+ * A guard that names the irreversible act in advance. `origin:` already stops a staging config being
+ * aimed at production, but it cannot tell an author that the file they just wrote completes a booking
+ * twice on every CI run. This can, and it is the only thing between "I configured a success state" and
+ * finding out what that meant.
+ */
+export function submissionPlan(forms, origin) {
+    const lines = [];
+    for (const form of forms) {
+        // Error states first, matching the order a run uses: the less destructive state is observed before
+        // the one that completes the form, so a run that dies midway has done the safer thing.
+        const ordered = [...form.states].sort((a, b) => Number(a.state === "success") - Number(b.state === "success"));
+        lines.push(`Would submit ${JSON.stringify(form.form)} ${ordered.length} time(s) against ${origin}, via `
+            + `${JSON.stringify(form.submit)}:`);
+        ordered.forEach((state, index) => {
+            const because = state.because ? `  (because: ${state.because})` : "";
+            const warning = state.state === "success" ? "   <- THIS COMPLETES THE FORM" : "";
+            lines.push(`  ${index + 1}. state ${JSON.stringify(state.state)}${because}${warning}`);
+        });
+    }
+    lines.push("", "Nothing was submitted. Remove --plan to run.");
+    return lines;
+}
+//# sourceMappingURL=coverage.js.map

package/dist/forms/coverage.js.map

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

package/dist/forms/draft.d.ts

@@ -0,0 +1,62 @@
+/** What a draft found, so a caller can report on it rather than only print it. */
+export interface FormsDraft {
+    /** The YAML text. */
+    yaml: string;
+    /** Fields that can be addressed AND filled, each with the verb its control's role takes. */
+    addressable: {
+        name: string;
+        verb: "value" | "choose" | "check";
+        within?: string;
+        nth?: number;
+    }[];
+    /**
+     * Fields NVDA announced with NO name, by position in reading order.
+     *
+     * Not an error and not a warning — a finding. It is reported whether or not the author ever configures
+     * this form, because it is a fact about the page rather than about the config.
+     */
+    unnamed: {
+        position: number;
+        announced: string;
+    }[];
+    /**
+     * Buttons, offered as `submit:` candidates rather than as things to type into.
+     *
+     * `structure.formFields` is NVDA's FORM-FIELD quick-nav, and it visits buttons — the census comment says
+     * so outright: *"the census counts the roles NVDA's form-field quick-nav actually visits — buttons
+     * included."* Found by running the emitter against a real page, where `"Submit Search", button` was
+     * drafted with `value: ""`. Typing into a button is not a thing, so the verb was wrong for the control,
+     * which is the exact confusion the three-verb schema exists to prevent — arriving through the generator
+     * instead of through the config.
+     */
+    submitCandidates: string[];
+    /**
+     * Announcements the grammar could not resolve into an object at all.
+     *
+     * SEPARATE from `unnamed`, and keeping them apart is the whole point. `unnamed` is a claim about the
+     * PAGE — a control with no accessible name, which is 4.1.2. This is a claim about our own parser, and
+     * conflating them puts a false accessibility finding into a generated artefact.
+     *
+     * It is not hypothetical: measured 2026-09-02, `parseAnnouncement` returns NO objects for every
+     * checkbox, because `CONTROL_ROLES` carries `"checkbox"` and NVDA says `"check box"`. The local corpus
+     * copy holds 22 announcements with NVDA's spelling and 0 with the grammar's. So a real W3C tutorial page
+     * with a correctly-labelled `"Subscribe to newsletter, check box"` was reported as an unnamed field —
+     * a false 4.1.2 against a conformant control. See the backlog.
+     */
+    unparsed: {
+        position: number;
+        announced: string;
+    }[];
+}
+/**
+ * @param formFields the capture's `structure.formFields` — NVDA's announcements, in reading order
+ * @param options `origin` is required in the output, so it is required here rather than left as a TODO:
+ *   a config that is missing it is refused at parse time, and emitting a file that cannot load is worse
+ *   than emitting one that is incomplete.
+ */
+export declare function draftFormsConfig(formFields: readonly string[], options: {
+    origin: string;
+    formName?: string;
+    submitName?: string;
+}): FormsDraft;
+//# sourceMappingURL=draft.d.ts.map

package/dist/forms/draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.d.ts","sourceRoot":"","sources":["../../src/forms/draft.ts"],"names":[],"mappings":"AAmBA,kFAAkF;AAClF,MAAM,WAAW,UAAU;IACzB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnG;;;;;OAKG;IACH,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnD;;;;;;;;;OASG;IACH,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACrD;AAmGD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAClE,UAAU,CAwDZ"}

package/dist/forms/draft.js

@@ -0,0 +1,165 @@
+/**
+ * Draft a forms config from what the screen reader actually announced — ADR 0024's "make it easy" half.
+ *
+ * Nobody writes the config from scratch. A capture already records every form field's announced name in
+ * `structure.formFields`, so the skeleton can be generated and the author only supplies values.
+ *
+ * **The draft is itself an accessibility report**, and that is the part worth protecting. A field NVDA
+ * announced with no name cannot be addressed by this config — and cannot be addressed by a screen reader
+ * user either, which is the 4.1.2 failure. So it is emitted as a NAMED COMMENT rather than skipped: an
+ * author who never fills the file in has still learned something, and a silently omitted field would be
+ * the empty-channel defect arriving in a generated artefact.
+ *
+ * Disambiguation is solved HERE rather than in the schema, because the easiest API for a name collision
+ * is one the author never writes. Two fields sharing a name get `within:` filled in from the group NVDA
+ * announced around them — which is how a screen reader user tells them apart — and `nth:` only when there
+ * is no group to name.
+ */
+import { parseAnnouncement } from "@a11ign/evidence";
+/**
+ * Which VERB a control's role takes — the schema's three verbs, matched to the controls that accept them.
+ *
+ * A button is absent on purpose (it is a `submit:` candidate, not something to fill), and so is static
+ * prose. The mapping exists because getting it wrong is not cosmetic: a draft that offers `value: ""` on
+ * a checkbox has told the author to type into it, which is the confusion the three-verb schema was
+ * designed to prevent. Both halves of that were live bugs found by running this against real pages —
+ * a button drafted as typeable, then a checkbox drafted the same way the moment the grammar could see one.
+ */
+const VERB_FOR_ROLE = Object.freeze({
+    "edit": "value", "edit text": "value", "spin button": "value", "slider": "value",
+    "combo box": "choose", "list box": "choose",
+    "check box": "check", "radio button": "check", "radio": "check",
+});
+/**
+ * One field's name, role and enclosing group, from the capture's OWN grammar.
+ *
+ * `role` is carried rather than discarded because the control's type decides which verb applies, and
+ * running this against a real page proved the point: without it, a button was drafted as something to
+ * type into.
+ */
+function describe(announced) {
+    const parsed = parseAnnouncement(announced, "sweep");
+    const object = parsed.objects.find((o) => o.name !== "" || o.role !== "");
+    // The INNERMOST container is the useful one for disambiguation: "Billing address" tells the two
+    // "Address line 1" fields apart, where the page-wrapping landmark they share tells you nothing.
+    const group = parsed.containers.length ? parsed.containers[parsed.containers.length - 1].name : undefined;
+    return { name: object?.name ?? "", role: object?.role ?? "", group: group || undefined };
+}
+const quote = (value) => JSON.stringify(value);
+/**
+ * Build the addressable list, filling in a disambiguator ONLY where a name actually collides.
+ *
+ * Adding `within:` everywhere would be noise, and worse: it would bind every field to a container that
+ * may change for reasons unrelated to the field, so a page edit elsewhere breaks a config that did not
+ * need the constraint.
+ */
+function addressable(fields) {
+    const seen = new Map();
+    for (const field of fields)
+        seen.set(field.name, (seen.get(field.name) ?? 0) + 1);
+    const used = new Map();
+    return fields.map((field) => {
+        const base = { name: field.name, verb: field.verb };
+        if ((seen.get(field.name) ?? 0) < 2)
+            return base;
+        const ordinal = (used.get(field.name) ?? 0) + 1;
+        used.set(field.name, ordinal);
+        // `within` first, `nth` only when there is no group to name — the ordering ADR 0024 settled, because
+        // a group is how a person distinguishes them and a count is how a machine does.
+        return field.group ? { ...base, within: field.group } : { ...base, nth: ordinal };
+    });
+}
+/** The starting value a verb is drafted with — blank for the author to fill, never a guess. */
+const BLANK_FOR = Object.freeze({
+    value: '""', choose: '""', check: "false",
+});
+function fieldLines(entries) {
+    return entries.flatMap((entry) => [
+        `          - field: ${quote(entry.name)}`,
+        ...(entry.within ? [`            within: ${quote(entry.within)}   # DRAFTED: two fields share this name`] : []),
+        ...(entry.nth ? [`            nth: ${entry.nth}   # DRAFTED: two fields share this name and no group names them`] : []),
+        `            ${entry.verb}: ${BLANK_FOR[entry.verb]}              # TODO`,
+    ]);
+}
+function unnamedLines(unnamed) {
+    return unnamed.flatMap((field) => [
+        "",
+        `      # UNNAMED FIELD, ${field.position} in reading order. NVDA announced ${quote(field.announced)}.`,
+        "      # This tool cannot address it, and neither can a screen reader user.",
+        "      # Reported as 4.1.2 whether or not you configure this form.",
+    ]);
+}
+/**
+ * Phrases this tool could not read, said as such.
+ *
+ * Deliberately worded as a limitation of the tool rather than of the page. The author cannot fix our
+ * parser and must not be sent looking for a defect that is ours — which is what putting these under
+ * "UNNAMED FIELD" did.
+ */
+function unparsedLines(unparsed) {
+    return unparsed.flatMap((field) => [
+        "",
+        `      # NOT UNDERSTOOD by a11ign, ${field.position} in reading order:`,
+        `      #   ${field.announced}`,
+        "      # This is a gap in THIS TOOL's announcement grammar, not a finding about your page.",
+        "      # Add the field by hand if you need it configured.",
+    ]);
+}
+/**
+ * @param formFields the capture's `structure.formFields` — NVDA's announcements, in reading order
+ * @param options `origin` is required in the output, so it is required here rather than left as a TODO:
+ *   a config that is missing it is refused at parse time, and emitting a file that cannot load is worse
+ *   than emitting one that is incomplete.
+ */
+export function draftFormsConfig(formFields, options) {
+    const described = formFields.map((announced, index) => ({ announced, index, ...describe(announced) }));
+    const at = (field) => ({ position: field.index + 1, announced: field.announced });
+    // FOUR outcomes, and collapsing any two of them is how this goes wrong.
+    //
+    // A button is a submit candidate, not something to type into. A named fillable control is what the
+    // config is for. A control announced with no name is a 4.1.2 finding about the PAGE. And a phrase the
+    // grammar could not resolve at all is a fact about OUR PARSER, which must never be reported as the
+    // third — that is a false accessibility finding, and it is what this emitter did on its first run
+    // against a real page.
+    const unparsed = described.filter((field) => field.role === "" && field.name === "").map(at);
+    const resolved = described.filter((field) => field.role !== "" || field.name !== "");
+    const submitCandidates = [...new Set(resolved.filter((field) => field.role === "button" && field.name !== "").map((field) => field.name))];
+    const fillable = resolved.filter((field) => VERB_FOR_ROLE[field.role] !== undefined);
+    // EVERY resolved-but-unnamed control, not only the fillable ones -- an unnamed BUTTON is exactly as
+    // much a 4.1.2 finding as an unnamed edit field, and deriving this from `fillable` silently dropped it:
+    // a button is excluded from `fillable` (it takes no verb) and from `submitCandidates` (no name to
+    // offer), so it vanished from the draft entirely. Measured: `[", button"]` produced `unnamed: []`,
+    // contradicting this file's own header -- "an author who never fills the file in has still learned
+    // something" promises no silent omission, and this was one.
+    const unnamed = resolved.filter((field) => field.name === "").map(at);
+    const entries = addressable(fillable
+        .filter((field) => field.name !== "")
+        .map((f) => ({ name: f.name, verb: VERB_FOR_ROLE[f.role], group: f.group })));
+    const yaml = [
+        "# Drafted by a11ign from what NVDA announced. Fill in the values; the names are already right.",
+        "#",
+        "# A `success` state COMPLETES the form. Supplying one is how you say that is acceptable — leave it out",
+        "# and nothing is submitted with valid data. Run with --plan to see exactly what would be submitted.",
+        "version: 1",
+        `origin: ${quote(options.origin)}`,
+        "forms:",
+        `  - form: ${quote(options.formName ?? "TODO the form's accessible name")}`,
+        // DRAFTED from the buttons actually announced, rather than left as a TODO the author has to go and
+        // look up. Where several were found the rest are listed beside it, because guessing which one submits
+        // is not something this tool can do and pretending otherwise would put the wrong control in the file.
+        `    submit: ${quote(options.submitName ?? submitCandidates[0] ?? "TODO the control that submits it")}`
+            + (submitCandidates.length > 1
+                ? `   # buttons found: ${submitCandidates.map((c) => JSON.stringify(c)).join(", ")}`
+                : ""),
+        "    states:",
+        "      - state: error",
+        '        because: ""             # TODO what does this form reject?',
+        "        fields:",
+        ...fieldLines(entries),
+        ...unnamedLines(unnamed),
+        ...unparsedLines(unparsed),
+        "",
+    ].join("\n");
+    return { yaml, addressable: entries, unnamed, submitCandidates, unparsed };
+}
+//# sourceMappingURL=draft.js.map

package/dist/forms/draft.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The renderer, so a consumer can print our report shape without reimplementing it.
+ *
+ * Deliberately the whole public surface. The CLI itself is a `bin`, not a library: it leases a worker, drives a
+ * capture over HTTP, judges it, optionally merges an axe run, and prints. Every one of those pieces is already
+ * a package of its own, so exporting a second way to orchestrate them would be two APIs to keep honest.
+ */
+export { reportLines } from "./report.js";
+export type { Report } from "./report.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * The renderer, so a consumer can print our report shape without reimplementing it.
+ *
+ * Deliberately the whole public surface. The CLI itself is a `bin`, not a library: it leases a worker, drives a
+ * capture over HTTP, judges it, optionally merges an axe run, and prints. Every one of those pieces is already
+ * a package of its own, so exporting a second way to orchestrate them would be two APIs to keep honest.
+ */
+export { reportLines } from "./report.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/report.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The report a person reads, as lines of text.
+ *
+ * Separated from printing it because this is the product's output — the thing a user judges their
+ * site by — and it was the only part of the CLI that could not be tested at all: `cli.ts` calls
+ * `main()` on import, so importing it to check a heading runs a capture.
+ *
+ * Building the lines here and letting the CLI do nothing but `console.log` them is the Humble Object
+ * pattern: the interesting half becomes a pure function, and the half that touches the world becomes
+ * too small to hold a bug.
+ */
+import type { Judgment } from "@a11ign/judge";
+import type { AxeFinding } from "./scan/axe.js";
+import { type ConformanceRequirement } from "@a11ign/evidence/conformance";
+import { type CriterionOutcome } from "@a11ign/judge/outcomes";
+export interface Report {
+    url: string;
+    task: string;
+    screenReader: string;
+    announcements: number;
+    verdict: Judgment;
+    /** null when the rule-based layer did not run — distinct from "ran and found nothing". */
+    axe: AxeFinding[] | null;
+    /**
+     * What this run establishes against WCAG's five CONFORMANCE REQUIREMENTS (§5.2), which govern whether
+     * a conformance claim is valid at all and are not success criteria. Optional so an older caller still
+     * renders — but when it is absent the section says so rather than being silently dropped, because a
+     * missing limit is exactly what makes a findings list read as a clean bill of health.
+     */
+    conformance?: ConformanceRequirement[];
+    /**
+     * Per-criterion ACT outcomes. Optional so an older caller still renders, but its absence is stated
+     * rather than skipped — see `outcomesSection`.
+     */
+    outcomes?: CriterionOutcome[];
+    /**
+     * The capture's own `environment` block, from the RUNNING WORKER, never from a pin or a manifest —
+     * publish blocker B4. `screenReaderVersion` and `guidepupVersion` matter most: the shipped scorer was
+     * trained on evidence from the fleet's NVDA, so a consumer's report has to say which NVDA build (and
+     * which client drove it) actually produced these announcements, not which one a lockfile or an
+     * installer manifest merely NAMES. The `browserVersion` memo defect, precisely: a pin says what was
+     * asked for, and only the instrument can say what was there. Optional so an older caller still renders.
+     */
+    environment?: Record<string, string>;
+}
+/** The whole report, ready to print. */
+export declare function reportLines({ url, task, screenReader, announcements, verdict, axe, conformance, outcomes, environment }: Report): string[];
+//# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAwB,KAAK,sBAAsB,EAAE,MACrD,8BAA8B,CAAC;AACtC,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAM7E,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,QAAQ,CAAC;IAClB,0FAA0F;IAC1F,GAAG,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IACzB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AA6SD,wCAAwC;AACxC,wBAAgB,WAAW,CACzB,EAAE,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,MAAM,GACnG,MAAM,EAAE,CA2BV"}