@variance-authority/report 0.1.0

package/dist/composition.d.ts

@@ -0,0 +1,248 @@
+/**
+ * The suite as one graph, in the artifact.
+ *
+ * Every other part of a run report is *one subject against its baseline* — two
+ * revisions, one thing. This is the other axis, and it is the one a suite of
+ * examples has always implied and never written down:
+ *
+ * > A visual-regression example is a component built from components. The example
+ * > *is* a component, at a boundary; the same component appears again, with the
+ * > same or different props, inside larger examples.
+ *
+ * Once the boundaries are addressable, the run can say which of its examples are
+ * watching literally the same bytes, which of them disagree at one commit, and —
+ * for anything that moved — what in the run explains it. None of that needs a
+ * second render, a second image, or a store: it is a fold over digests the
+ * collection already produced.
+ *
+ * ## Why the shapes here are smaller than the ones that produced them
+ *
+ * `@variance-authority/core`'s `Composition` carries every site of every
+ * rendering, which is one entry per component boundary per subject — tens of
+ * thousands of objects on a real suite, and a report is a file people open. What
+ * survives into the artifact is what a *sentence* needs: the names, the counts,
+ * and the subject lists that let a reader go and look. A consumer that wants the
+ * full graph recomputes it from the snapshots, which is the same bargain the
+ * report already makes about masks and PNGs.
+ *
+ * The one thing kept in full is the movement list, because it is short by
+ * construction — only components that moved — and because it is the part somebody
+ * acts on.
+ */
+/** A component's census entry: where it is, what it is inside, what it reads. */
+export interface ComponentRecord {
+    readonly component: string;
+    /** Subjects holding at least one boundary of it, in plan order. */
+    readonly subjects: readonly string[];
+    /** Boundaries summed across every subject. Distinct from `subjects.length`. */
+    readonly instances: number;
+    /**
+     * Subjects whose shallowest attributed boundary is this component.
+     *
+     * The narrow example — the subject that exists to *show* this thing rather than
+     * a page that happens to contain it. Empty is a real answer and a common one: a
+     * component that appears only inside pages has no example, which is the gap a
+     * reviewer is usually looking for.
+     */
+    readonly examples: readonly string[];
+    /** Components that enclose it somewhere, sorted. The graph, upwards. */
+    readonly within: readonly string[];
+    /**
+     * Components that **mounted** it somewhere, sorted. Usually the useful edge.
+     *
+     * `within` is where the boundary sits and this is who wrote the element, and in
+     * a real application they are mostly different: measured on
+     * `examples/todomvc`, every `Chip` is `within: ["Stack"]` and
+     * `createdBy: ["TodoFooter"]`. `TodoFooter` renders nothing but other
+     * components, so it owns no DOM node, is a boundary nowhere, and would be
+     * absent from this graph entirely if only `within` were recorded — while being
+     * the file a reviewer has to open.
+     *
+     * Empty on a production build, where React's `_debugOwner` is gone. Empty is
+     * *not* "nothing mounted it".
+     */
+    readonly createdBy: readonly string[];
+    /** Components it encloses somewhere, sorted. The graph, downwards. */
+    readonly renders: readonly string[];
+    /** Custom properties its own nodes resolve through, anywhere in the suite. */
+    readonly tokens: readonly string[];
+    /**
+     * Distinct props digests it was rendered with, and distinct renderings it
+     * produced.
+     *
+     * Two numbers rather than the classes themselves, because the classes are
+     * digests and a digest tells a human nothing. What the pair says is worth a
+     * line: `variants: 4, renderings: 4` is a component whose output is a function
+     * of its input, and `variants: 1, renderings: 3` is one whose output is not —
+     * which is what `divergences` is about.
+     *
+     * `variants` counts the unknown-props class as one when it occurred, because
+     * instances with no provenance are a group this report can describe and not one
+     * it may join on.
+     */
+    readonly variants: number;
+    readonly renderings: number;
+}
+/**
+ * One rendering, several subjects. The dots, connected.
+ *
+ * The finding is a rendering that survives being mounted somewhere else — three
+ * identical chips in one list say nothing, and the same chip in a chip story and
+ * in a page footer says that a reviewer looking at two diffs is looking at one.
+ */
+export interface EchoRecord {
+    readonly component: string;
+    /** The joining digest: the four content digests of the boundary, together. */
+    readonly rendering: string;
+    /** At least two, in plan order. */
+    readonly subjects: readonly string[];
+    /** Boundaries, which is at least `subjects.length`. */
+    readonly sites: number;
+    /** The narrow example among them, when the suite has one. */
+    readonly example?: string;
+}
+/**
+ * The same component, the same **inputs**, more than one rendering. At one commit.
+ *
+ * Not a regression — there is no baseline anywhere in it. It says the component's
+ * own inputs do not determine its output, which is either a fact about the design
+ * (a token, a theme, an ancestor's cascade) or a reading that is not repeatable.
+ * `bands` says which kind, in the vocabulary a sensitivity absorbs, so a
+ * divergence entirely inside a relaxed band can be dismissed without opening it.
+ *
+ * *Inputs*, not *props*: a props digest excludes `children`, and `divergencesOf`
+ * in `core` refuses every pair the exclusion could explain. An empty list is a
+ * real and common answer — `examples/todomvc` produces exactly zero — and it
+ * means nothing in the suite rendered two ways from one input.
+ */
+export interface DivergenceRecord {
+    readonly component: string;
+    readonly bands: readonly string[];
+    /**
+     * The subjects behind each distinct rendering, widest group first. At least two.
+     *
+     * Grouped rather than counted, and that is the whole record. A divergence says
+     * one input produced more than one output, and the only sentence a reader can
+     * act on is *which* subjects sit on each side of it — `price` and `receipt`
+     * render one way, `promo` renders another, so `promo` is the one to open. A
+     * count with a flat subject list beside it, which is what this was, names every
+     * subject involved and withholds the only thing distinguishing them: the reader
+     * has three names, knows two of them agree, and cannot tell which two.
+     *
+     * Deduplicated per group, because a rendering reached twice in one subject is
+     * one subject to go and look at. `renderings.length` is the count this replaced.
+     */
+    readonly renderings: readonly (readonly string[])[];
+    /**
+     * Why each rendering after the first parted from it.
+     *
+     * The sentence, under the split. `renderings` says *promo is the odd one out*;
+     * this says *`Price` inherited a different `color` — an ancestor declared it*,
+     * which is the difference between a reader knowing where to look and knowing
+     * what they will find when they get there.
+     *
+     * Absent when the run kept no documents to read. Empty is never written.
+     */
+    readonly partings?: readonly PartingRecord[];
+}
+/** One rendering of a divergence, spoken. */
+export interface PartingRecord {
+    /** Index into {@link DivergenceRecord.renderings}, always at least 1. */
+    readonly rendering: number;
+    /** Already phrased for a reader; the first line is the triage slice. */
+    readonly lines: readonly string[];
+}
+/**
+ * Why one component moved in one subject, and what the suite held against it.
+ *
+ * The ladder is `edited` → `token` → `upstream` → `contradicted` → `unexplained`,
+ * and the last one is the finding. See
+ * [`flakiness.md`](../../../docs/flakiness.md) for what it is and is not allowed
+ * to conclude.
+ */
+export interface MovementRecord {
+    readonly subject: string;
+    readonly component: string;
+    /** Empty means *not known* — a name-only comparison — never *no band*. */
+    readonly bands: readonly string[];
+    readonly cause: 'edited' | 'token' | 'upstream' | 'contradicted' | 'unexplained';
+    /** One sentence, naming the evidence rather than the category. */
+    readonly because: string;
+    readonly file?: string;
+    readonly tokens?: readonly string[];
+    readonly upstream?: string;
+    /**
+     * Components between `upstream` and this one, outermost first.
+     *
+     * Present only on the `upstream` rung, and absent when the edited component
+     * draws this one directly. A reviewer sent to `ProductCard` because a
+     * `CardFooter` moved has exactly one question next — *how does that reach
+     * this* — and the answer is a couple of names the run already walked.
+     */
+    readonly through?: readonly string[];
+    /** Other subjects this same component moved in. The "one cause, N subjects" fold. */
+    readonly alsoIn: readonly string[];
+    /**
+     * Subjects where the same component, with the same props, did **not** move.
+     *
+     * The control group — the *stable states to refer to*. Empty means the suite
+     * offered no control, which weakens an unexplained movement rather than
+     * strengthening it, and is why this is a list and not a flag.
+     */
+    readonly held: readonly string[];
+    /**
+     * Renders of this component with the same props, other than this one, that the
+     * run read.
+     *
+     * The denominator `held` is a numerator of. Without it an empty control group
+     * is two opposite findings wearing one shape — nothing to compare against, or a
+     * comparison made in every render and answering the same way — and a reader
+     * that guesses picks the wrong one on any suite where the change reached
+     * everything.
+     *
+     * Optional because a report written before this was carried has no answer, and
+     * `0` is an answer.
+     */
+    readonly compared?: number;
+    /**
+     * For an unexplained movement only: whether the subject was already proven
+     * unstable in this run.
+     *
+     * `flake` means the subject failed to read the same way twice *and* nothing in
+     * the run explains what moved — the two halves of the sentence, together, for
+     * the first time. `suspect` means nobody has read it twice yet, so it is a
+     * shortlist entry and not a verdict.
+     *
+     * Absent on every explained movement, where the question does not arise.
+     */
+    readonly standing?: 'flake' | 'suspect';
+}
+/**
+ * What one run learned by comparing its subjects to each other.
+ *
+ * Absent from a report whose collection produced no semantic snapshots — a
+ * raster-only tier has no boundaries to join, and an empty graph would read as
+ * "this suite shares nothing", which is a different and false claim.
+ */
+export interface CompositionReport {
+    /** Subjects that contributed a snapshot, in plan order. The denominator. */
+    readonly subjects: readonly string[];
+    /** Sorted by name, code-unit order. */
+    readonly components: readonly ComponentRecord[];
+    /** Widest first. Capped — see `truncated`. */
+    readonly echoes: readonly EchoRecord[];
+    /** Sorted by component name. */
+    readonly divergences: readonly DivergenceRecord[];
+    /** Every component the run found moved, in the order the observations came. */
+    readonly movements: readonly MovementRecord[];
+    /**
+     * What was left out of the lists above, when anything was.
+     *
+     * A cap that says nothing is a cap that reads as coverage. Present only when a
+     * list was shortened, and counts what did not make it rather than what did.
+     */
+    readonly truncated?: {
+        readonly echoes: number;
+    };
+}
+//# sourceMappingURL=composition.d.ts.map

package/dist/composition.js

@@ -0,0 +1,33 @@
+/**
+ * The suite as one graph, in the artifact.
+ *
+ * Every other part of a run report is *one subject against its baseline* — two
+ * revisions, one thing. This is the other axis, and it is the one a suite of
+ * examples has always implied and never written down:
+ *
+ * > A visual-regression example is a component built from components. The example
+ * > *is* a component, at a boundary; the same component appears again, with the
+ * > same or different props, inside larger examples.
+ *
+ * Once the boundaries are addressable, the run can say which of its examples are
+ * watching literally the same bytes, which of them disagree at one commit, and —
+ * for anything that moved — what in the run explains it. None of that needs a
+ * second render, a second image, or a store: it is a fold over digests the
+ * collection already produced.
+ *
+ * ## Why the shapes here are smaller than the ones that produced them
+ *
+ * `@variance-authority/core`'s `Composition` carries every site of every
+ * rendering, which is one entry per component boundary per subject — tens of
+ * thousands of objects on a real suite, and a report is a file people open. What
+ * survives into the artifact is what a *sentence* needs: the names, the counts,
+ * and the subject lists that let a reader go and look. A consumer that wants the
+ * full graph recomputes it from the snapshots, which is the same bargain the
+ * report already makes about masks and PNGs.
+ *
+ * The one thing kept in full is the movement list, because it is short by
+ * construction — only components that moved — and because it is the part somebody
+ * acts on.
+ */
+export {};
+//# sourceMappingURL=composition.js.map

package/dist/composition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.js","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG","sourcesContent":["/**\n * The suite as one graph, in the artifact.\n *\n * Every other part of a run report is *one subject against its baseline* — two\n * revisions, one thing. This is the other axis, and it is the one a suite of\n * examples has always implied and never written down:\n *\n * > A visual-regression example is a component built from components. The example\n * > *is* a component, at a boundary; the same component appears again, with the\n * > same or different props, inside larger examples.\n *\n * Once the boundaries are addressable, the run can say which of its examples are\n * watching literally the same bytes, which of them disagree at one commit, and —\n * for anything that moved — what in the run explains it. None of that needs a\n * second render, a second image, or a store: it is a fold over digests the\n * collection already produced.\n *\n * ## Why the shapes here are smaller than the ones that produced them\n *\n * `@variance-authority/core`'s `Composition` carries every site of every\n * rendering, which is one entry per component boundary per subject — tens of\n * thousands of objects on a real suite, and a report is a file people open. What\n * survives into the artifact is what a *sentence* needs: the names, the counts,\n * and the subject lists that let a reader go and look. A consumer that wants the\n * full graph recomputes it from the snapshots, which is the same bargain the\n * report already makes about masks and PNGs.\n *\n * The one thing kept in full is the movement list, because it is short by\n * construction — only components that moved — and because it is the part somebody\n * acts on.\n */\n\n/** A component's census entry: where it is, what it is inside, what it reads. */\nexport interface ComponentRecord {\n  readonly component: string;\n  /** Subjects holding at least one boundary of it, in plan order. */\n  readonly subjects: readonly string[];\n  /** Boundaries summed across every subject. Distinct from `subjects.length`. */\n  readonly instances: number;\n\n  /**\n   * Subjects whose shallowest attributed boundary is this component.\n   *\n   * The narrow example — the subject that exists to *show* this thing rather than\n   * a page that happens to contain it. Empty is a real answer and a common one: a\n   * component that appears only inside pages has no example, which is the gap a\n   * reviewer is usually looking for.\n   */\n  readonly examples: readonly string[];\n\n  /** Components that enclose it somewhere, sorted. The graph, upwards. */\n  readonly within: readonly string[];\n\n  /**\n   * Components that **mounted** it somewhere, sorted. Usually the useful edge.\n   *\n   * `within` is where the boundary sits and this is who wrote the element, and in\n   * a real application they are mostly different: measured on\n   * `examples/todomvc`, every `Chip` is `within: [\"Stack\"]` and\n   * `createdBy: [\"TodoFooter\"]`. `TodoFooter` renders nothing but other\n   * components, so it owns no DOM node, is a boundary nowhere, and would be\n   * absent from this graph entirely if only `within` were recorded — while being\n   * the file a reviewer has to open.\n   *\n   * Empty on a production build, where React's `_debugOwner` is gone. Empty is\n   * *not* \"nothing mounted it\".\n   */\n  readonly createdBy: readonly string[];\n\n  /** Components it encloses somewhere, sorted. The graph, downwards. */\n  readonly renders: readonly string[];\n  /** Custom properties its own nodes resolve through, anywhere in the suite. */\n  readonly tokens: readonly string[];\n\n  /**\n   * Distinct props digests it was rendered with, and distinct renderings it\n   * produced.\n   *\n   * Two numbers rather than the classes themselves, because the classes are\n   * digests and a digest tells a human nothing. What the pair says is worth a\n   * line: `variants: 4, renderings: 4` is a component whose output is a function\n   * of its input, and `variants: 1, renderings: 3` is one whose output is not —\n   * which is what `divergences` is about.\n   *\n   * `variants` counts the unknown-props class as one when it occurred, because\n   * instances with no provenance are a group this report can describe and not one\n   * it may join on.\n   */\n  readonly variants: number;\n  readonly renderings: number;\n}\n\n/**\n * One rendering, several subjects. The dots, connected.\n *\n * The finding is a rendering that survives being mounted somewhere else — three\n * identical chips in one list say nothing, and the same chip in a chip story and\n * in a page footer says that a reviewer looking at two diffs is looking at one.\n */\nexport interface EchoRecord {\n  readonly component: string;\n  /** The joining digest: the four content digests of the boundary, together. */\n  readonly rendering: string;\n  /** At least two, in plan order. */\n  readonly subjects: readonly string[];\n  /** Boundaries, which is at least `subjects.length`. */\n  readonly sites: number;\n  /** The narrow example among them, when the suite has one. */\n  readonly example?: string;\n}\n\n/**\n * The same component, the same **inputs**, more than one rendering. At one commit.\n *\n * Not a regression — there is no baseline anywhere in it. It says the component's\n * own inputs do not determine its output, which is either a fact about the design\n * (a token, a theme, an ancestor's cascade) or a reading that is not repeatable.\n * `bands` says which kind, in the vocabulary a sensitivity absorbs, so a\n * divergence entirely inside a relaxed band can be dismissed without opening it.\n *\n * *Inputs*, not *props*: a props digest excludes `children`, and `divergencesOf`\n * in `core` refuses every pair the exclusion could explain. An empty list is a\n * real and common answer — `examples/todomvc` produces exactly zero — and it\n * means nothing in the suite rendered two ways from one input.\n */\nexport interface DivergenceRecord {\n  readonly component: string;\n  readonly bands: readonly string[];\n\n  /**\n   * The subjects behind each distinct rendering, widest group first. At least two.\n   *\n   * Grouped rather than counted, and that is the whole record. A divergence says\n   * one input produced more than one output, and the only sentence a reader can\n   * act on is *which* subjects sit on each side of it — `price` and `receipt`\n   * render one way, `promo` renders another, so `promo` is the one to open. A\n   * count with a flat subject list beside it, which is what this was, names every\n   * subject involved and withholds the only thing distinguishing them: the reader\n   * has three names, knows two of them agree, and cannot tell which two.\n   *\n   * Deduplicated per group, because a rendering reached twice in one subject is\n   * one subject to go and look at. `renderings.length` is the count this replaced.\n   */\n  readonly renderings: readonly (readonly string[])[];\n\n  /**\n   * Why each rendering after the first parted from it.\n   *\n   * The sentence, under the split. `renderings` says *promo is the odd one out*;\n   * this says *`Price` inherited a different `color` — an ancestor declared it*,\n   * which is the difference between a reader knowing where to look and knowing\n   * what they will find when they get there.\n   *\n   * Absent when the run kept no documents to read. Empty is never written.\n   */\n  readonly partings?: readonly PartingRecord[];\n}\n\n/** One rendering of a divergence, spoken. */\nexport interface PartingRecord {\n  /** Index into {@link DivergenceRecord.renderings}, always at least 1. */\n  readonly rendering: number;\n  /** Already phrased for a reader; the first line is the triage slice. */\n  readonly lines: readonly string[];\n}\n\n/**\n * Why one component moved in one subject, and what the suite held against it.\n *\n * The ladder is `edited` → `token` → `upstream` → `contradicted` → `unexplained`,\n * and the last one is the finding. See\n * [`flakiness.md`](../../../docs/flakiness.md) for what it is and is not allowed\n * to conclude.\n */\nexport interface MovementRecord {\n  readonly subject: string;\n  readonly component: string;\n  /** Empty means *not known* — a name-only comparison — never *no band*. */\n  readonly bands: readonly string[];\n  readonly cause: 'edited' | 'token' | 'upstream' | 'contradicted' | 'unexplained';\n  /** One sentence, naming the evidence rather than the category. */\n  readonly because: string;\n\n  readonly file?: string;\n  readonly tokens?: readonly string[];\n  readonly upstream?: string;\n\n  /**\n   * Components between `upstream` and this one, outermost first.\n   *\n   * Present only on the `upstream` rung, and absent when the edited component\n   * draws this one directly. A reviewer sent to `ProductCard` because a\n   * `CardFooter` moved has exactly one question next — *how does that reach\n   * this* — and the answer is a couple of names the run already walked.\n   */\n  readonly through?: readonly string[];\n\n  /** Other subjects this same component moved in. The \"one cause, N subjects\" fold. */\n  readonly alsoIn: readonly string[];\n\n  /**\n   * Subjects where the same component, with the same props, did **not** move.\n   *\n   * The control group — the *stable states to refer to*. Empty means the suite\n   * offered no control, which weakens an unexplained movement rather than\n   * strengthening it, and is why this is a list and not a flag.\n   */\n  readonly held: readonly string[];\n\n  /**\n   * Renders of this component with the same props, other than this one, that the\n   * run read.\n   *\n   * The denominator `held` is a numerator of. Without it an empty control group\n   * is two opposite findings wearing one shape — nothing to compare against, or a\n   * comparison made in every render and answering the same way — and a reader\n   * that guesses picks the wrong one on any suite where the change reached\n   * everything.\n   *\n   * Optional because a report written before this was carried has no answer, and\n   * `0` is an answer.\n   */\n  readonly compared?: number;\n\n  /**\n   * For an unexplained movement only: whether the subject was already proven\n   * unstable in this run.\n   *\n   * `flake` means the subject failed to read the same way twice *and* nothing in\n   * the run explains what moved — the two halves of the sentence, together, for\n   * the first time. `suspect` means nobody has read it twice yet, so it is a\n   * shortlist entry and not a verdict.\n   *\n   * Absent on every explained movement, where the question does not arise.\n   */\n  readonly standing?: 'flake' | 'suspect';\n}\n\n/**\n * What one run learned by comparing its subjects to each other.\n *\n * Absent from a report whose collection produced no semantic snapshots — a\n * raster-only tier has no boundaries to join, and an empty graph would read as\n * \"this suite shares nothing\", which is a different and false claim.\n */\nexport interface CompositionReport {\n  /** Subjects that contributed a snapshot, in plan order. The denominator. */\n  readonly subjects: readonly string[];\n  /** Sorted by name, code-unit order. */\n  readonly components: readonly ComponentRecord[];\n  /** Widest first. Capped — see `truncated`. */\n  readonly echoes: readonly EchoRecord[];\n  /** Sorted by component name. */\n  readonly divergences: readonly DivergenceRecord[];\n  /** Every component the run found moved, in the order the observations came. */\n  readonly movements: readonly MovementRecord[];\n\n  /**\n   * What was left out of the lists above, when anything was.\n   *\n   * A cap that says nothing is a cap that reads as coverage. Present only when a\n   * list was shortened, and counts what did not make it rather than what did.\n   */\n  readonly truncated?: {\n    readonly echoes: number;\n  };\n}\n"]}

package/dist/declarations.d.ts

@@ -0,0 +1,266 @@
+/**
+ * What the config *declared*, and what each declaration did in this run.
+ *
+ * The two ledgers a run keeps about its own settings. An ignore says *part of
+ * this page is not my subject*; a sensitivity says *assert on this much of it*.
+ * Both make a run less observant on purpose, and both are only safe because
+ * every run counts what they absorbed — a declaration that stopped being needed
+ * is invisible without a count of zero, and a mask that outlives its cause grows
+ * quietly over a real regression.
+ *
+ * They live here rather than with the command that computes them for the reason
+ * the rest of this package exists: they have several readers. The CLI folds them,
+ * a terminal prints them, an HTML page tabulates them, and a review service
+ * stores them so the audit survives the machine the run happened on. A shape
+ * owned by the first of those bends towards a terminal.
+ *
+ * ## One decision, taken once
+ *
+ * A rule's *state* — spent, mistyped, expired, or simply working — is a reading
+ * of the counts, not another count. It is taken by {@link ignoreState} and
+ * {@link sensitivityState} and nowhere else, because a second reader that
+ * re-derived it would eventually disagree: the first HTML report to try shipped
+ * `pixels === 0` as the whole test for *dead*, which calls every rule in a fresh
+ * checkout dead, on the run that proves least about any of them.
+ */
+/** What one ignore rule did this run. */
+export interface IgnoreUsage {
+    readonly rule: string;
+    readonly reason: string;
+    /** Changed pixels this rule absorbed across the run. */
+    readonly pixels: number;
+    /** Subjects where it excluded something, whether or not it absorbed anything. */
+    readonly subjects: number;
+    /**
+     * Subjects where it excluded something **and a comparison happened**.
+     *
+     * The denominator that stops "absorbed nothing" from being an accusation. A
+     * subject that is `new`, `incomparable`, or settled from a digest compared no
+     * pixels, so an ignore over it had nothing to absorb — which says nothing at
+     * all about whether the rule is still needed. Without this a fresh checkout
+     * reported every ignore in the config as dead.
+     */
+    readonly comparedIn: number;
+    /** Subjects where it excluded something and absorbed nothing there. */
+    readonly inertIn: number;
+    /** `true` when it never resolved to a place in any subject. */
+    readonly unresolved: boolean;
+    /**
+     * Tags the rule names that no subject in this run wears.
+     *
+     * The only defence a tag has. A misspelled *key* is refused by name because
+     * the config's objects are closed; a misspelled *tag* is a legal word that
+     * simply matches nothing, and the rule then silently applies nowhere while the
+     * operator reads their config and believes it applies somewhere. So the words
+     * nothing answered to are named, with the near-misses that were present, and
+     * an empty list is the ordinary case rather than the interesting one.
+     */
+    readonly unwornTags: readonly string[];
+    /** `true` when it is past `until` and no longer absorbing. */
+    readonly expired: boolean;
+}
+/** Every ignore rule the config named, and what the run as a whole absorbed. */
+export interface IgnoreLedger {
+    readonly rules: readonly IgnoreUsage[];
+    /**
+     * Rules that absorbed nothing anywhere this run.
+     *
+     * The list an operator is meant to act on. Named separately rather than left
+     * to be derived, because a derivation nobody writes is a report nobody reads.
+     */
+    readonly dead: readonly string[];
+    /** Subjects whose only differences were absorbed. Green, and not `unchanged`. */
+    readonly fullyIgnored: readonly string[];
+    readonly totalPixels: number;
+    /** Every tag worn by a subject this run planned, for the near-miss hint. */
+    readonly vocabulary: readonly string[];
+}
+/** What one sensitivity rule did this run. */
+export interface SensitivityUsage {
+    readonly rule: string;
+    readonly reason: string;
+    readonly level: string;
+    /** Subjects this rule was in scope for, whether or not it absorbed them. */
+    readonly scoped: number;
+    /** Subjects whose verdict it decided. */
+    readonly absorbed: readonly string[];
+    /** Bands it absorbed, across every subject it decided. */
+    readonly bands: readonly string[];
+    /**
+     * `true` when the rule matched no subject this run planned.
+     *
+     * A different failure from absorbing nothing, and worth its own word: a rule
+     * naming `route/*` in a project whose subjects are all `story:*` is a typo,
+     * not a policy that has outlived its cause.
+     */
+    readonly unscoped: boolean;
+}
+/** Every sensitivity rule the config named, and how much they relaxed. */
+export interface SensitivityLedger {
+    readonly rules: readonly SensitivityUsage[];
+    readonly totalAbsorbed: number;
+}
+/**
+ * What an ignore rule turned out to be, read from what it did.
+ *
+ * - `expired` — past its date. The differences it used to absorb are back.
+ * - `unworn` — it names a tag no subject in this run wears, so it applied nowhere.
+ * - `unresolved` — its selector matched no element in any subject.
+ * - `untested` — it excluded a subtree, and nothing it covered was compared.
+ * - `dead` — it excluded a subtree in subjects that *were* compared, and took nothing.
+ * - `live` — it absorbed something.
+ *
+ * The order is the order the checks run in, and it matters: an expired rule that
+ * also names a mistyped tag is expired, because that is the fact that explains
+ * the other. `untested` and `dead` are the pair worth keeping apart — the first
+ * is an absence of evidence and the second is evidence of absence, and a report
+ * that spells both *dead* tells an operator to delete a rule on the run that
+ * proves least about it.
+ */
+export type IgnoreState = 'expired' | 'unworn' | 'unresolved' | 'untested' | 'dead' | 'live';
+/**
+ * What a sensitivity rule turned out to be.
+ *
+ * - `unscoped` — it matched no subject this run planned.
+ * - `dead` — it was in scope and decided nothing; nothing here needed relaxing.
+ * - `live` — it decided at least one verdict.
+ */
+export type SensitivityState = 'unscoped' | 'dead' | 'live';
+/** The single reading of an ignore's counts. Every surface asks this one. */
+export declare function ignoreState(entry: IgnoreUsage): IgnoreState;
+/** The single reading of a sensitivity's counts. */
+export declare function sensitivityState(entry: SensitivityUsage): SensitivityState;
+/**
+ * Whether a state names something to do about the config.
+ *
+ * `untested` is deliberately not one. It is the absence of evidence, and a
+ * report that flagged it would ask an operator to act on a run that measured
+ * nothing — which is how audits stop being read.
+ */
+export declare function isActionable(state: IgnoreState | SensitivityState): boolean;
+/**
+ * The sentence behind an ignore's state.
+ *
+ * Here rather than in a renderer for the reason the state itself is here: an
+ * HTML table, a terminal and a review page all have to answer *why is this rule
+ * marked* and there is one answer. Two of them writing their own is how a report
+ * and a service come to disagree about the same run in front of the same person.
+ *
+ * The near-miss on `unworn` is the part worth carrying: the likeliest cause of a
+ * tag nothing wears is a typo, and naming the tags that *are* worn turns a
+ * report into a fix.
+ */
+export declare function ignoreSays(entry: IgnoreUsage, ledger: IgnoreLedger): string;
+/**
+ * The run-level line under the ignore table, vocabulary included.
+ *
+ * The last clause is the one that has to be there. With no vocabulary the
+ * unworn-tag check did not run at all, and a footer that said nothing about it
+ * would read as every tag having been checked and every tag having been found.
+ *
+ * The first clause counts the rules that *absorbed*, over the rules that were
+ * declared, and the two are only the same number on a run where every rule
+ * worked. Counting declarations there put the whole run's pixels behind the size
+ * of the config: two rules, one of them matching nothing, read as *647 pixels
+ * absorbed by 2 rules* directly above a table saying one of them resolved
+ * nowhere. The table is the audit; the footer must not contradict it.
+ */
+export declare function ignoreTotals(ledger: IgnoreLedger): string;
+/** The sentence behind a sensitivity's state. */
+export declare function sensitivitySays(entry: SensitivityUsage): string;
+/**
+ * The run-level line under the sensitivity table.
+ *
+ * Rules that decided something, over rules declared — the same reading as
+ * {@link ignoreTotals}, and for the same reason. *0 subjects not asserted on in
+ * full, by 1 rule* is a sentence with a rule in it that did nothing.
+ */
+export declare function sensitivityTotals(ledger: SensitivityLedger): string;
+/**
+ * How many of the declared ignores absorbed anything, over how many were written.
+ *
+ * A phrase rather than a number because there are four footers printing it — an
+ * HTML report, a review page and two terminal summaries — and the arithmetic is
+ * the part that has to be identical between them. Whether a rule counts here is
+ * the same reading {@link ignoreState} takes, and a surface that re-derived it
+ * would eventually take a different one.
+ */
+export declare function ignoreShare(ledger: IgnoreLedger): string;
+/** The same reading for sensitivities: rules that decided a verdict, over rules written. */
+export declare function sensitivityShare(ledger: SensitivityLedger): string;
+/**
+ * The bands a rule absorbed, or the fact that they were not kept.
+ *
+ * `undefined` is the third answer, and it is the whole reason this is a function
+ * rather than a field read. A rule that decided verdicts with no band recorded is
+ * not a rule that absorbed nothing — it is a report written before the bands were
+ * kept, or by a writer that dropped them, and an empty list says the first.
+ */
+export declare function absorbedBands(entry: SensitivityUsage): readonly string[] | undefined;
+/**
+ * The part of an observation that says why it came back green.
+ *
+ * Structural rather than the whole `ObservationRecord`, because the second
+ * caller is a review service whose subjects arrive from a database and carry
+ * only what was stored. Writing the relation over the fields it actually reads
+ * is what lets both of them ask the same question, and stops the answer from
+ * being re-derived on the far side of the wire.
+ */
+export interface GreenSubject {
+    readonly verdict: 'unchanged' | 'changed' | 'new' | 'incomparable' | 'ignored';
+    readonly ignored?: {
+        readonly pixels: number;
+        readonly boxes: number;
+        readonly byRule: Readonly<Record<string, number>>;
+    } | undefined;
+    readonly relaxed?: {
+        readonly rule: string;
+        readonly level: string;
+        readonly bands: readonly string[];
+    } | undefined;
+}
+/**
+ * Why one subject is green.
+ *
+ * - `measured` — nothing differed, and no declaration stood over it.
+ * - `masked` — nothing differed, and a rule was watching anyway. Its boxes
+ *   caught nothing here, which is how a mask starts outliving its cause.
+ * - `relaxed` — it differed, and every band that moved is one this subject is
+ *   not asserted on.
+ * - `absorbed` — it differed, and every differing pixel fell inside an excluded
+ *   subtree. The rules that took them are named.
+ * - `unsaid` — it is `ignored` and the record does not say what did it.
+ */
+export type Green = {
+    readonly kind: 'measured';
+} | {
+    readonly kind: 'masked';
+    readonly boxes: number;
+} | {
+    readonly kind: 'relaxed';
+    readonly rule: string;
+    readonly level: string;
+    readonly bands: readonly string[];
+} | {
+    readonly kind: 'absorbed';
+    readonly rules: readonly string[];
+    readonly pixels: number;
+} | {
+    readonly kind: 'unsaid';
+};
+/**
+ * What decided a green subject, in the words of whatever decided it.
+ *
+ * `unsaid` is the case this exists for. A subject reported `ignored` whose
+ * record carries neither block says *a declaration absorbed this* and does not
+ * say which — and both obvious renderings of that are false. Printing nothing
+ * reads as *nothing was absorbed*; printing `0 px` reads as *a rule absorbed
+ * nothing*. So the absence is a state, and every surface has to render it.
+ *
+ * It is reachable two ways and they are worth telling apart when reading a bug:
+ * an older report written before the blocks were kept, and a store that dropped
+ * them on the way in. The second is the one that turns a report and a service
+ * into two different accounts of one run.
+ */
+export declare function greenBecause(entry: GreenSubject): Green;
+//# sourceMappingURL=declarations.d.ts.map