@variance-authority/report 0.1.0

package/dist/findings.d.ts

@@ -0,0 +1,157 @@
+/**
+ * How a list of defects is labelled, and how it is dated — once, for every surface.
+ *
+ * Two questions a reader asks of a findings panel, and until this file neither
+ * had an answer anywhere:
+ *
+ * **What kind of report is this?** The rows are rule slugs and clauses —
+ * `nested-interactive`, `label-mismatch` — under a heading that says `Findings`
+ * or, on the HTML report, nothing at all. A reader who does not already know what
+ * the inspector checks has to infer the subject of the report from the names of
+ * its rules. The honest label is not one word: nine of the eleven rules band
+ * `a11y` and two do not, so a panel headed *Accessibility* would be wrong about
+ * the box that overflows its container and the string that was never translated.
+ * The band is already on the record and is the axis a project blocks on
+ * (`blocking: ['a11y']`), so the heading a reader sees and the policy that stops
+ * their merge are the same word by construction.
+ *
+ * **Is this mine?** A finding is read from one render with no baseline consulted,
+ * which is the half a comparison structurally cannot produce — and the cost is
+ * that the same list prints on the run that introduced a defect and on the two
+ * hundred runs after it. `FindingRecord.standing` carries the answer when a
+ * baseline recorded one; the rules for reading it absent are the whole reason
+ * this is a shared fold rather than a ternary at each call site. Absent is *not
+ * dated*, never *new*: a surface that guessed would announce every inherited
+ * defect in a suite as freshly introduced, on the first run after an upgrade, to
+ * the person least equipped to check.
+ *
+ * **Which of them is this reviewer's problem right now?** The two above are
+ * readings; this one is an order, and it is the one the surfaces got wrong for
+ * longest. A panel that opens on a total and then counts the dates as equal
+ * clauses is telling somebody halfway through a button restyle about twenty-two
+ * defects they inherited and cannot fix today, before it tells them about the
+ * twenty they just caused. [`byArrival`](#byArrival) is the split, and every
+ * surface leads with `arrived` and folds the rest behind a count.
+ *
+ * One fold, many renderers. Five surfaces print these sentences — an HTML report,
+ * a review page and three terminal answers — and the part that has to be
+ * identical between them is the reading, not the markup.
+ */
+import type { FindingRecord } from './finding-record.js';
+/**
+ * The heading for a band, or the one honest heading for a record without one.
+ *
+ * `Unclassified` rather than a guess. A report written before the band was
+ * carried has none, and filing those under `Accessibility` would put the two
+ * rules that are not accessibility under a heading that says they are — which is
+ * the mislabelling this whole file exists to end, arriving through the default.
+ */
+export declare function bandTitle(band: string | undefined): string;
+/** Whether the baseline carried this defect too, as one of three states. */
+export type Age = 'standing' | 'new' | 'undated';
+/**
+ * Which of the three a record is, with absent kept out of the other two.
+ *
+ * The whole reading is the `undefined` branch. `standing` is only ever set from
+ * evidence — the render's document was byte-for-byte the baseline's, or the
+ * baseline recorded the marks to cross against — so a record without it is one
+ * nothing dated, not one dated *no*. Every surface goes through here rather than
+ * writing `finding.standing === true ? … : …`, because that ternary is correct
+ * on the two states it names and silently wrong on the third, and it is the
+ * third that arrives on the first run after an upgrade.
+ */
+export declare function ageOf(finding: FindingRecord): Age;
+/** The phrase that goes on the row. Short: it sits beside a component and a file. */
+export declare const AGE_WORDS: Readonly<Record<Age, string>>;
+/** The same three states at length, for a `title` a reader can hover for the why. */
+export declare const AGE_WHY: Readonly<Record<Age, string>>;
+/** One band's worth of defects, in the order the bands are reported. */
+export interface Grouped {
+    readonly band: string | undefined;
+    readonly title: string;
+    readonly findings: readonly FindingRecord[];
+}
+/**
+ * The defects, grouped under the heading each one belongs to.
+ *
+ * Loudest band first, from core's own order, so the accessibility defects lead a
+ * mixed list rather than sorting alphabetically under `Content`. A band nothing
+ * in this render fired is not an empty group — it is not a group, because a
+ * heading over nothing reads as a category that was checked and found clean, and
+ * these rules do not check bands, they check rules.
+ */
+export declare function byBand(findings: readonly FindingRecord[]): readonly Grouped[];
+/** Two piles and the one fact that says whether the split may be acted on. */
+export interface Arrival {
+    /** Recorded as absent from the baseline: this change is what put them here. */
+    readonly arrived: readonly FindingRecord[];
+    /** Everything the record does not put on this change — carried, or never dated. */
+    readonly rest: readonly FindingRecord[];
+    /** Whether anything in the list carries a date, which is what makes the split a claim. */
+    readonly dated: boolean;
+}
+/**
+ * The defects, split by whether the record puts them on this change.
+ *
+ * The one axis a reviewer mid-change is actually working along, and until this
+ * function no surface ordered by it. Every panel led with a total and the method
+ * — *42 defects read from this render, with no baseline compared* — and then
+ * counted the two dates as equal clauses, which hands somebody reviewing a
+ * button restyle twenty-two inherited defects in the same breath as the twenty
+ * they just caused. They cannot act on the twenty-two today. Printing them first
+ * is how a panel teaches a reviewer to stop reading it.
+ *
+ * Two piles, and `undated` is in neither by name. It goes with the rest because
+ * the rest is defined by what it is *not* — not recorded as arriving with this
+ * change — which is exactly true of a finding nothing dated, and stays true when
+ * the record improves. Calling that pile *inherited* would be the guess this
+ * whole axis exists to refuse.
+ *
+ * {@link Arrival.dated} is what decides whether a surface may fold at all. When
+ * nothing carries a date, `arrived` is empty and `rest` is the whole list, and a
+ * renderer that folded on that would hide every defect in the render behind a
+ * summary — on exactly the run where there is no baseline to have inherited them
+ * from.
+ */
+export declare function byArrival(findings: readonly FindingRecord[]): Arrival;
+/**
+ * The sentence that goes first, which is about this change and nothing else.
+ *
+ * Three answers, and the third is not a count. A run with no dating on it cannot
+ * say *nothing arrived* — that is a claim about a baseline nobody read — so it
+ * says what it does know, which is that the question has no answer here.
+ */
+export declare function arrivalLine(findings: readonly FindingRecord[]): string;
+/**
+ * The rest, counted once, for the summary a surface folds them behind.
+ *
+ * `undefined` when there is nothing to fold — either the list is all arrivals, or
+ * nothing is dated and the split would be an invention. The two states are
+ * counted apart even here: *already in the baseline* is a fact about a record
+ * somebody wrote, and *the baseline does not account for* is the absence of one,
+ * and a reviewer deciding whether to open the fold is entitled to know which.
+ */
+export declare function carriedLine(findings: readonly FindingRecord[]): string | undefined;
+/** Why nothing in the list moved the verdict. Method, so it goes last. */
+export declare function methodLine(findings: readonly FindingRecord[]): string;
+/**
+ * Whether the rows in one list disagree about their date.
+ *
+ * The gate on drawing a date per row, and it is per *list* rather than per
+ * report. A column of rows all saying `arrived with this change`, under a heading
+ * that already says it, is a word a reader stops seeing — and once a surface
+ * splits arrivals from the rest, every list it draws is uniform unless the fold
+ * happens to hold both a dated and an undated row. That case is the only one
+ * where the row is carrying the finding rather than repeating the heading.
+ */
+export declare function mixedAges(findings: readonly FindingRecord[]): boolean;
+/**
+ * The whole opening, for a surface with one line to spend rather than a panel.
+ *
+ * Same three parts in the same order the panels draw them: what arrived, what was
+ * already here, and last the method — which is the sentence that explains why
+ * none of this moved the verdict, and which used to be first because it explains
+ * the list rather than because anybody needed it before the count.
+ */
+export declare function findingTotals(findings: readonly FindingRecord[]): string;
+//# sourceMappingURL=findings.d.ts.map

package/dist/findings.js

@@ -0,0 +1,227 @@
+/**
+ * How a list of defects is labelled, and how it is dated — once, for every surface.
+ *
+ * Two questions a reader asks of a findings panel, and until this file neither
+ * had an answer anywhere:
+ *
+ * **What kind of report is this?** The rows are rule slugs and clauses —
+ * `nested-interactive`, `label-mismatch` — under a heading that says `Findings`
+ * or, on the HTML report, nothing at all. A reader who does not already know what
+ * the inspector checks has to infer the subject of the report from the names of
+ * its rules. The honest label is not one word: nine of the eleven rules band
+ * `a11y` and two do not, so a panel headed *Accessibility* would be wrong about
+ * the box that overflows its container and the string that was never translated.
+ * The band is already on the record and is the axis a project blocks on
+ * (`blocking: ['a11y']`), so the heading a reader sees and the policy that stops
+ * their merge are the same word by construction.
+ *
+ * **Is this mine?** A finding is read from one render with no baseline consulted,
+ * which is the half a comparison structurally cannot produce — and the cost is
+ * that the same list prints on the run that introduced a defect and on the two
+ * hundred runs after it. `FindingRecord.standing` carries the answer when a
+ * baseline recorded one; the rules for reading it absent are the whole reason
+ * this is a shared fold rather than a ternary at each call site. Absent is *not
+ * dated*, never *new*: a surface that guessed would announce every inherited
+ * defect in a suite as freshly introduced, on the first run after an upgrade, to
+ * the person least equipped to check.
+ *
+ * **Which of them is this reviewer's problem right now?** The two above are
+ * readings; this one is an order, and it is the one the surfaces got wrong for
+ * longest. A panel that opens on a total and then counts the dates as equal
+ * clauses is telling somebody halfway through a button restyle about twenty-two
+ * defects they inherited and cannot fix today, before it tells them about the
+ * twenty they just caused. [`byArrival`](#byArrival) is the split, and every
+ * surface leads with `arrived` and folds the rest behind a count.
+ *
+ * One fold, many renderers. Five surfaces print these sentences — an HTML report,
+ * a review page and three terminal answers — and the part that has to be
+ * identical between them is the reading, not the markup.
+ */
+/**
+ * What a reader is told the row is about, in the order the bands are reported.
+ *
+ * Typed against core's `Band` rather than reading core's `BANDS` array, which
+ * would be the same list at the cost of a runtime edge from this package into the
+ * comparison engine — and this module is bundled into a browser page. The type is
+ * the coupling that matters: a band added to core fails to compile here until
+ * somebody writes the word a reviewer will read, which is the failure worth
+ * having. Insertion order is loudest first, matching `BANDS`, so a mixed list
+ * leads with the accessibility defects rather than sorting under `Content`.
+ */
+const TITLES = {
+    a11y: 'Accessibility',
+    geometry: 'Layout',
+    token: 'Style',
+    content: 'Content',
+    texture: 'Rendering',
+};
+/** The reporting order, from the one list that has to name every band anyway. */
+const ORDER = Object.keys(TITLES);
+/**
+ * The heading for a band, or the one honest heading for a record without one.
+ *
+ * `Unclassified` rather than a guess. A report written before the band was
+ * carried has none, and filing those under `Accessibility` would put the two
+ * rules that are not accessibility under a heading that says they are — which is
+ * the mislabelling this whole file exists to end, arriving through the default.
+ */
+export function bandTitle(band) {
+    if (band === undefined)
+        return 'Unclassified';
+    return TITLES[band] ?? band;
+}
+/**
+ * Which of the three a record is, with absent kept out of the other two.
+ *
+ * The whole reading is the `undefined` branch. `standing` is only ever set from
+ * evidence — the render's document was byte-for-byte the baseline's, or the
+ * baseline recorded the marks to cross against — so a record without it is one
+ * nothing dated, not one dated *no*. Every surface goes through here rather than
+ * writing `finding.standing === true ? … : …`, because that ternary is correct
+ * on the two states it names and silently wrong on the third, and it is the
+ * third that arrives on the first run after an upgrade.
+ */
+export function ageOf(finding) {
+    if (finding.standing === undefined)
+        return 'undated';
+    return finding.standing ? 'standing' : 'new';
+}
+/** The phrase that goes on the row. Short: it sits beside a component and a file. */
+export const AGE_WORDS = {
+    new: 'arrived with this change',
+    standing: 'already in the baseline',
+    undated: 'not dated',
+};
+/** The same three states at length, for a `title` a reader can hover for the why. */
+export const AGE_WHY = {
+    new: 'The baseline recorded what was found in it, and this was not among it.',
+    standing: 'The baseline carried this defect too. Approving this change does not approve ' +
+        'the defect, and fixing it is separate work.',
+    undated: 'Nothing recorded what the baseline contained — there is no baseline yet, or it ' +
+        'was written before findings were kept beside it. This is not a claim that the ' +
+        'defect is new.',
+};
+/**
+ * The defects, grouped under the heading each one belongs to.
+ *
+ * Loudest band first, from core's own order, so the accessibility defects lead a
+ * mixed list rather than sorting alphabetically under `Content`. A band nothing
+ * in this render fired is not an empty group — it is not a group, because a
+ * heading over nothing reads as a category that was checked and found clean, and
+ * these rules do not check bands, they check rules.
+ */
+export function byBand(findings) {
+    const groups = new Map();
+    for (const finding of findings) {
+        const key = finding.band ?? undefined;
+        groups.set(key, [...(groups.get(key) ?? []), finding]);
+    }
+    const known = ORDER.filter((band) => groups.has(band)).map((band) => ({ band, title: bandTitle(band), findings: groups.get(band) ?? [] }));
+    const rest = [...groups.entries()]
+        .filter(([band]) => band === undefined || !ORDER.includes(band))
+        .map(([band, found]) => ({ band, title: bandTitle(band), findings: found }));
+    return [...known, ...rest];
+}
+/**
+ * The defects, split by whether the record puts them on this change.
+ *
+ * The one axis a reviewer mid-change is actually working along, and until this
+ * function no surface ordered by it. Every panel led with a total and the method
+ * — *42 defects read from this render, with no baseline compared* — and then
+ * counted the two dates as equal clauses, which hands somebody reviewing a
+ * button restyle twenty-two inherited defects in the same breath as the twenty
+ * they just caused. They cannot act on the twenty-two today. Printing them first
+ * is how a panel teaches a reviewer to stop reading it.
+ *
+ * Two piles, and `undated` is in neither by name. It goes with the rest because
+ * the rest is defined by what it is *not* — not recorded as arriving with this
+ * change — which is exactly true of a finding nothing dated, and stays true when
+ * the record improves. Calling that pile *inherited* would be the guess this
+ * whole axis exists to refuse.
+ *
+ * {@link Arrival.dated} is what decides whether a surface may fold at all. When
+ * nothing carries a date, `arrived` is empty and `rest` is the whole list, and a
+ * renderer that folded on that would hide every defect in the render behind a
+ * summary — on exactly the run where there is no baseline to have inherited them
+ * from.
+ */
+export function byArrival(findings) {
+    return {
+        arrived: findings.filter((finding) => ageOf(finding) === 'new'),
+        rest: findings.filter((finding) => ageOf(finding) !== 'new'),
+        dated: findings.some((finding) => ageOf(finding) !== 'undated'),
+    };
+}
+/**
+ * The sentence that goes first, which is about this change and nothing else.
+ *
+ * Three answers, and the third is not a count. A run with no dating on it cannot
+ * say *nothing arrived* — that is a claim about a baseline nobody read — so it
+ * says what it does know, which is that the question has no answer here.
+ */
+export function arrivalLine(findings) {
+    const { arrived, dated } = byArrival(findings);
+    if (arrived.length > 0)
+        return `${plural(arrived.length, 'defect')} arrived with this change`;
+    if (dated)
+        return 'Nothing here arrived with this change';
+    return 'Nothing recorded what the baseline held, so none of them can be dated to this change';
+}
+/**
+ * The rest, counted once, for the summary a surface folds them behind.
+ *
+ * `undefined` when there is nothing to fold — either the list is all arrivals, or
+ * nothing is dated and the split would be an invention. The two states are
+ * counted apart even here: *already in the baseline* is a fact about a record
+ * somebody wrote, and *the baseline does not account for* is the absence of one,
+ * and a reviewer deciding whether to open the fold is entitled to know which.
+ */
+export function carriedLine(findings) {
+    const { rest, dated } = byArrival(findings);
+    if (!dated || rest.length === 0)
+        return undefined;
+    const held = rest.filter((finding) => ageOf(finding) === 'standing').length;
+    const undated = rest.length - held;
+    return [
+        held === 0 ? undefined : `${String(held)} already in the baseline`,
+        undated === 0 ? undefined : `${String(undated)} the baseline does not account for`,
+    ]
+        .filter((clause) => clause !== undefined)
+        .join(', ');
+}
+/** Why nothing in the list moved the verdict. Method, so it goes last. */
+export function methodLine(findings) {
+    return `${plural(findings.length, 'defect')} read from this render, with no baseline compared`;
+}
+/**
+ * Whether the rows in one list disagree about their date.
+ *
+ * The gate on drawing a date per row, and it is per *list* rather than per
+ * report. A column of rows all saying `arrived with this change`, under a heading
+ * that already says it, is a word a reader stops seeing — and once a surface
+ * splits arrivals from the rest, every list it draws is uniform unless the fold
+ * happens to hold both a dated and an undated row. That case is the only one
+ * where the row is carrying the finding rather than repeating the heading.
+ */
+export function mixedAges(findings) {
+    return new Set(findings.map(ageOf)).size > 1;
+}
+/**
+ * The whole opening, for a surface with one line to spend rather than a panel.
+ *
+ * Same three parts in the same order the panels draw them: what arrived, what was
+ * already here, and last the method — which is the sentence that explains why
+ * none of this moved the verdict, and which used to be first because it explains
+ * the list rather than because anybody needed it before the count.
+ */
+export function findingTotals(findings) {
+    if (findings.length === 0)
+        return methodLine(findings);
+    return [arrivalLine(findings), carriedLine(findings), methodLine(findings)]
+        .filter((part) => part !== undefined)
+        .join(' · ');
+}
+function plural(count, noun) {
+    return `${String(count)} ${noun}${count === 1 ? '' : 's'}`;
+}
+//# sourceMappingURL=findings.js.map

package/dist/findings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../src/findings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How a list of defects is labelled, and how it is dated — once, for every surface.\n *\n * Two questions a reader asks of a findings panel, and until this file neither\n * had an answer anywhere:\n *\n * **What kind of report is this?** The rows are rule slugs and clauses —\n * `nested-interactive`, `label-mismatch` — under a heading that says `Findings`\n * or, on the HTML report, nothing at all. A reader who does not already know what\n * the inspector checks has to infer the subject of the report from the names of\n * its rules. The honest label is not one word: nine of the eleven rules band\n * `a11y` and two do not, so a panel headed *Accessibility* would be wrong about\n * the box that overflows its container and the string that was never translated.\n * The band is already on the record and is the axis a project blocks on\n * (`blocking: ['a11y']`), so the heading a reader sees and the policy that stops\n * their merge are the same word by construction.\n *\n * **Is this mine?** A finding is read from one render with no baseline consulted,\n * which is the half a comparison structurally cannot produce — and the cost is\n * that the same list prints on the run that introduced a defect and on the two\n * hundred runs after it. `FindingRecord.standing` carries the answer when a\n * baseline recorded one; the rules for reading it absent are the whole reason\n * this is a shared fold rather than a ternary at each call site. Absent is *not\n * dated*, never *new*: a surface that guessed would announce every inherited\n * defect in a suite as freshly introduced, on the first run after an upgrade, to\n * the person least equipped to check.\n *\n * **Which of them is this reviewer's problem right now?** The two above are\n * readings; this one is an order, and it is the one the surfaces got wrong for\n * longest. A panel that opens on a total and then counts the dates as equal\n * clauses is telling somebody halfway through a button restyle about twenty-two\n * defects they inherited and cannot fix today, before it tells them about the\n * twenty they just caused. [`byArrival`](#byArrival) is the split, and every\n * surface leads with `arrived` and folds the rest behind a count.\n *\n * One fold, many renderers. Five surfaces print these sentences — an HTML report,\n * a review page and three terminal answers — and the part that has to be\n * identical between them is the reading, not the markup.\n */\n\nimport type { Band } from '@variance-authority/core';\nimport type { FindingRecord } from './finding-record.js';\n\n/**\n * What a reader is told the row is about, in the order the bands are reported.\n *\n * Typed against core's `Band` rather than reading core's `BANDS` array, which\n * would be the same list at the cost of a runtime edge from this package into the\n * comparison engine — and this module is bundled into a browser page. The type is\n * the coupling that matters: a band added to core fails to compile here until\n * somebody writes the word a reviewer will read, which is the failure worth\n * having. Insertion order is loudest first, matching `BANDS`, so a mixed list\n * leads with the accessibility defects rather than sorting under `Content`.\n */\nconst TITLES: Readonly<Record<Band, string>> = {\n  a11y: 'Accessibility',\n  geometry: 'Layout',\n  token: 'Style',\n  content: 'Content',\n  texture: 'Rendering',\n};\n\n/** The reporting order, from the one list that has to name every band anyway. */\nconst ORDER: readonly string[] = Object.keys(TITLES);\n\n/**\n * The heading for a band, or the one honest heading for a record without one.\n *\n * `Unclassified` rather than a guess. A report written before the band was\n * carried has none, and filing those under `Accessibility` would put the two\n * rules that are not accessibility under a heading that says they are — which is\n * the mislabelling this whole file exists to end, arriving through the default.\n */\nexport function bandTitle(band: string | undefined): string {\n  if (band === undefined) return 'Unclassified';\n  return (TITLES as Readonly<Record<string, string>>)[band] ?? band;\n}\n\n/** Whether the baseline carried this defect too, as one of three states. */\nexport type Age = 'standing' | 'new' | 'undated';\n\n/**\n * Which of the three a record is, with absent kept out of the other two.\n *\n * The whole reading is the `undefined` branch. `standing` is only ever set from\n * evidence — the render's document was byte-for-byte the baseline's, or the\n * baseline recorded the marks to cross against — so a record without it is one\n * nothing dated, not one dated *no*. Every surface goes through here rather than\n * writing `finding.standing === true ? … : …`, because that ternary is correct\n * on the two states it names and silently wrong on the third, and it is the\n * third that arrives on the first run after an upgrade.\n */\nexport function ageOf(finding: FindingRecord): Age {\n  if (finding.standing === undefined) return 'undated';\n  return finding.standing ? 'standing' : 'new';\n}\n\n/** The phrase that goes on the row. Short: it sits beside a component and a file. */\nexport const AGE_WORDS: Readonly<Record<Age, string>> = {\n  new: 'arrived with this change',\n  standing: 'already in the baseline',\n  undated: 'not dated',\n};\n\n/** The same three states at length, for a `title` a reader can hover for the why. */\nexport const AGE_WHY: Readonly<Record<Age, string>> = {\n  new: 'The baseline recorded what was found in it, and this was not among it.',\n  standing:\n    'The baseline carried this defect too. Approving this change does not approve ' +\n    'the defect, and fixing it is separate work.',\n  undated:\n    'Nothing recorded what the baseline contained — there is no baseline yet, or it ' +\n    'was written before findings were kept beside it. This is not a claim that the ' +\n    'defect is new.',\n};\n\n/** One band's worth of defects, in the order the bands are reported. */\nexport interface Grouped {\n  readonly band: string | undefined;\n  readonly title: string;\n  readonly findings: readonly FindingRecord[];\n}\n\n/**\n * The defects, grouped under the heading each one belongs to.\n *\n * Loudest band first, from core's own order, so the accessibility defects lead a\n * mixed list rather than sorting alphabetically under `Content`. A band nothing\n * in this render fired is not an empty group — it is not a group, because a\n * heading over nothing reads as a category that was checked and found clean, and\n * these rules do not check bands, they check rules.\n */\nexport function byBand(findings: readonly FindingRecord[]): readonly Grouped[] {\n  const groups = new Map<string | undefined, FindingRecord[]>();\n  for (const finding of findings) {\n    const key = finding.band ?? undefined;\n    groups.set(key, [...(groups.get(key) ?? []), finding]);\n  }\n\n  const known = ORDER.filter((band) => groups.has(band)).map(\n    (band): Grouped => ({ band, title: bandTitle(band), findings: groups.get(band) ?? [] }),\n  );\n  const rest = [...groups.entries()]\n    .filter(([band]) => band === undefined || !ORDER.includes(band))\n    .map(([band, found]): Grouped => ({ band, title: bandTitle(band), findings: found }));\n\n  return [...known, ...rest];\n}\n\n/** Two piles and the one fact that says whether the split may be acted on. */\nexport interface Arrival {\n  /** Recorded as absent from the baseline: this change is what put them here. */\n  readonly arrived: readonly FindingRecord[];\n  /** Everything the record does not put on this change — carried, or never dated. */\n  readonly rest: readonly FindingRecord[];\n  /** Whether anything in the list carries a date, which is what makes the split a claim. */\n  readonly dated: boolean;\n}\n\n/**\n * The defects, split by whether the record puts them on this change.\n *\n * The one axis a reviewer mid-change is actually working along, and until this\n * function no surface ordered by it. Every panel led with a total and the method\n * — *42 defects read from this render, with no baseline compared* — and then\n * counted the two dates as equal clauses, which hands somebody reviewing a\n * button restyle twenty-two inherited defects in the same breath as the twenty\n * they just caused. They cannot act on the twenty-two today. Printing them first\n * is how a panel teaches a reviewer to stop reading it.\n *\n * Two piles, and `undated` is in neither by name. It goes with the rest because\n * the rest is defined by what it is *not* — not recorded as arriving with this\n * change — which is exactly true of a finding nothing dated, and stays true when\n * the record improves. Calling that pile *inherited* would be the guess this\n * whole axis exists to refuse.\n *\n * {@link Arrival.dated} is what decides whether a surface may fold at all. When\n * nothing carries a date, `arrived` is empty and `rest` is the whole list, and a\n * renderer that folded on that would hide every defect in the render behind a\n * summary — on exactly the run where there is no baseline to have inherited them\n * from.\n */\nexport function byArrival(findings: readonly FindingRecord[]): Arrival {\n  return {\n    arrived: findings.filter((finding) => ageOf(finding) === 'new'),\n    rest: findings.filter((finding) => ageOf(finding) !== 'new'),\n    dated: findings.some((finding) => ageOf(finding) !== 'undated'),\n  };\n}\n\n/**\n * The sentence that goes first, which is about this change and nothing else.\n *\n * Three answers, and the third is not a count. A run with no dating on it cannot\n * say *nothing arrived* — that is a claim about a baseline nobody read — so it\n * says what it does know, which is that the question has no answer here.\n */\nexport function arrivalLine(findings: readonly FindingRecord[]): string {\n  const { arrived, dated } = byArrival(findings);\n\n  if (arrived.length > 0) return `${plural(arrived.length, 'defect')} arrived with this change`;\n  if (dated) return 'Nothing here arrived with this change';\n  return 'Nothing recorded what the baseline held, so none of them can be dated to this change';\n}\n\n/**\n * The rest, counted once, for the summary a surface folds them behind.\n *\n * `undefined` when there is nothing to fold — either the list is all arrivals, or\n * nothing is dated and the split would be an invention. The two states are\n * counted apart even here: *already in the baseline* is a fact about a record\n * somebody wrote, and *the baseline does not account for* is the absence of one,\n * and a reviewer deciding whether to open the fold is entitled to know which.\n */\nexport function carriedLine(findings: readonly FindingRecord[]): string | undefined {\n  const { rest, dated } = byArrival(findings);\n  if (!dated || rest.length === 0) return undefined;\n\n  const held = rest.filter((finding) => ageOf(finding) === 'standing').length;\n  const undated = rest.length - held;\n\n  return [\n    held === 0 ? undefined : `${String(held)} already in the baseline`,\n    undated === 0 ? undefined : `${String(undated)} the baseline does not account for`,\n  ]\n    .filter((clause): clause is string => clause !== undefined)\n    .join(', ');\n}\n\n/** Why nothing in the list moved the verdict. Method, so it goes last. */\nexport function methodLine(findings: readonly FindingRecord[]): string {\n  return `${plural(findings.length, 'defect')} read from this render, with no baseline compared`;\n}\n\n/**\n * Whether the rows in one list disagree about their date.\n *\n * The gate on drawing a date per row, and it is per *list* rather than per\n * report. A column of rows all saying `arrived with this change`, under a heading\n * that already says it, is a word a reader stops seeing — and once a surface\n * splits arrivals from the rest, every list it draws is uniform unless the fold\n * happens to hold both a dated and an undated row. That case is the only one\n * where the row is carrying the finding rather than repeating the heading.\n */\nexport function mixedAges(findings: readonly FindingRecord[]): boolean {\n  return new Set(findings.map(ageOf)).size > 1;\n}\n\n/**\n * The whole opening, for a surface with one line to spend rather than a panel.\n *\n * Same three parts in the same order the panels draw them: what arrived, what was\n * already here, and last the method — which is the sentence that explains why\n * none of this moved the verdict, and which used to be first because it explains\n * the list rather than because anybody needed it before the count.\n */\nexport function findingTotals(findings: readonly FindingRecord[]): string {\n  if (findings.length === 0) return methodLine(findings);\n\n  return [arrivalLine(findings), carriedLine(findings), methodLine(findings)]\n    .filter((part): part is string => part !== undefined)\n    .join(' · ');\n}\n\nfunction plural(count: number, noun: string): string {\n  return `${String(count)} ${noun}${count === 1 ? '' : 's'}`;\n}\n"]}