@variance-authority/mcp 0.1.0

package/dist/tools/describe.js

@@ -0,0 +1,279 @@
+import { AGE_WORDS, ageOf, byArrival, byBand, carriedLine, findingTotals, mixedAges, } from '@variance-authority/report';
+import { describePresentation } from '../presentation.js';
+import { subjectOf, unobserved } from './subject.js';
+/**
+ * `variance_describe`, and the region format nothing else prints.
+ *
+ * `regionLine` stays with the tool because the region list is this answer's whole
+ * substance, and everything around it is an ordering decision that belongs to
+ * this tool rather than to regions in general: the leak warning above the list
+ * because it changes what every line below means, the findings before it because
+ * an `unchanged` subject can carry nothing else, and the truncation count after
+ * it because a capped list that does not say so reads as a complete one.
+ */
+/**
+ * One subject, in full: what changed, where it is, and which file to open.
+ *
+ * The tool an agent calls after the summary, and the one that has to be complete
+ * — an agent that has to ask three more questions to locate an edit will guess
+ * instead.
+ */
+export const describe = {
+    name: 'variance_describe',
+    description: 'Everything known about one subject: the ranked regions, the component each belongs to, ' +
+        'a landmark description of where it is on the page, the source file to edit, and each ' +
+        "region's shape fingerprint — which is what `variance accept --shape` and an `ignore` " +
+        'rule are keyed on when a difference is not a code problem. Causes are listed before ' +
+        'collateral. A subject the run did not observe is answered with why, not refused.',
+    inputSchema: {
+        type: 'object',
+        properties: { subject: { type: 'string', description: 'Subject id from variance_summary.' } },
+        required: ['subject'],
+        additionalProperties: false,
+    },
+    run(report, input) {
+        const located = subjectOf(report, input);
+        if (!located.observed)
+            return unobserved(located.entry);
+        const { observation } = located;
+        const lines = [
+            `[${label(observation)}] ${observation.subject}`,
+            observation.because,
+            // Ahead of the leak note, because it disqualifies that one too. A clean
+            // world re-collection was never taken on this subject — its answer would
+            // have been a comparison between two readings that do not agree anyway —
+            // so there is no order-dependence claim here to place second.
+            ...(observation.unstable !== undefined && observation.unstable.absorbed === undefined
+                ? [
+                    `NOT A COMPONENT CHANGE: ${observation.unstable.because}. The regions below are`,
+                    'the difference between one of those two readings and the baseline, so which',
+                    'ones appear here is decided by a race. Do not review them and do not accept',
+                    'this subject. Fix what moves between two readings of the same page' +
+                        (observation.unstable.components.length === 0
+                            ? ', starting from the subject itself — no snapshot was collected, so nothing'
+                                + ' could name the component that moved.'
+                            : `, starting at ${unstableAt(observation.unstable.components)}` +
+                                (observation.unstable.bands.length === 0
+                                    ? '.'
+                                    : ` (${observation.unstable.bands.join(', ')}).`)),
+                ]
+                : []),
+            // What the record says, directly under the instruction it qualifies. An
+            // agent handed "fix what moves between two readings" acts differently when
+            // the answer is "this has fired in eleven of the last twelve sweeps" than
+            // when it is "twice in March, and nine sweeps have been clean since" — the
+            // second is a fix that already landed, and rewriting it is a day spent
+            // re-solving somebody's solved problem.
+            ...(observation.unstable !== undefined ? recurrence(report, observation.subject) : []),
+            // The experiment, spelled out. An agent that has just been told to fix
+            // what moves between two readings needs a way to find out whether it did,
+            // and the alternative it reaches for otherwise is a full run — three
+            // hundred subjects and a browser, to answer a question about one of them.
+            ...(observation.unstable !== undefined && observation.unstable.absorbed === undefined
+                ? [
+                    'VERIFY A FIX WITH:',
+                    `  variance run --subjects '${observation.subject}' --flakes`,
+                    'which reads this subject twice and nothing else, and exits 1 while the two',
+                    'readings still disagree — even when every verdict is green.',
+                ]
+                : []),
+            // The same movement, inside the boundary the subject declared. Said rather
+            // than suppressed: an agent that later sees this subject go green wants to
+            // know a level was doing work, and the rule's name is what makes that
+            // auditable. It carries no instruction, because there is nothing to do.
+            ...(observation.unstable?.absorbed !== undefined
+                ? [
+                    `read differently between two readings in ${(observation.unstable.bands ?? []).join(', ')}, ` +
+                        `and \`${observation.unstable.absorbed.rule}\` asserts on ` +
+                        `${observation.unstable.absorbed.level} — so none of it is asserted on here. ` +
+                        'Working as declared; the regions below are the comparison, not the movement.',
+                ]
+                : []),
+            // Placed under the verdict, because it changes what every line below it
+            // means. The regions are still correct — those pixels really did move, in
+            // those components — but they are the shape of a leak rather than the shape
+            // of an edit, and an agent that reads the region list first starts editing a
+            // component whose source nobody changed.
+            ...((observation.unstable === undefined || observation.unstable.absorbed !== undefined) &&
+                observation.alone?.reproduced === false
+                ? [
+                    `NOT A COMPONENT CHANGE: ${observation.alone?.because}. The regions below are real`,
+                    'but they are what the leak did, not what an edit did. Do not change these',
+                    'components. Find the subject that writes the state this one reads by bisecting',
+                    'run order — the run cannot name it, because module-level state is invisible to',
+                    'anything a rendered document can observe about itself.',
+                ]
+                : []),
+            ...(observation.missingFonts !== undefined && observation.missingFonts.length > 0
+                ? [
+                    `warning: the renderer lacked ${observation.missingFonts.join(', ')}; ` +
+                        'these images are of a substituted font and their metrics are not the product’s',
+                ]
+                : []),
+        ];
+        // What the record says about the components this subject's change was
+        // attributed to. Placed after the verdict and before the regions, because it
+        // changes how the region list should be read: a component that has caused an
+        // approved change in eleven of the last forty runs is a component whose next
+        // change is unremarkable, and one that has never moved before is the opposite.
+        lines.push(...componentChurn(report, observation));
+        // Findings before regions. A subject can be `unchanged` and still carry
+        // them, in which case they are the only thing this tool has to say, and a
+        // reader who stopped at "nothing changed" would never reach them.
+        if (observation.findings !== undefined && observation.findings.length > 0) {
+            lines.push('', findingTotals(observation.findings) + ':', ...findingLines(observation.findings));
+        }
+        if (observation.signals?.presentation !== undefined) {
+            lines.push('', ...describePresentation(observation.signals.presentation));
+        }
+        if (observation.regions.length === 0)
+            return lines.join('\n');
+        lines.push('', ...observation.regions.map(regionLine));
+        if (observation.truncated !== undefined && observation.truncated.regions > 0) {
+            // Never a silent cap: a truncated list that does not say so reads as
+            // complete coverage, and the reader has no way to tell the difference.
+            lines.push(`+${observation.truncated.regions} smaller region(s) not listed ` +
+                `(${observation.truncated.pixels}px)`);
+        }
+        if (observation.images !== undefined) {
+            lines.push('', 'images: ' +
+                Object.entries(observation.images)
+                    .map(([kind, path]) => `${kind}=${path}`)
+                    .join(' '));
+        }
+        return lines.join('\n');
+    },
+};
+/**
+ * What the subject *is*, which is not always its verdict.
+ *
+ * Three words over one, and the order is the precedence: instability disqualifies
+ * the clean-world answer, which in turn re-reads the verdict. All three subjects
+ * are `changed` — the pixels did move — and all three need different work, so a
+ * reader given the verdict alone acts on the wrong one two times out of three.
+ */
+function label(observation) {
+    if (observation.unstable !== undefined && observation.unstable.absorbed === undefined) {
+        return 'unstable';
+    }
+    if (observation.alone?.reproduced === false)
+        return 'order-dependent';
+    return observation.verdict;
+}
+/**
+ * How often the components named here have changed before.
+ *
+ * Only the causes, and only the ones the record answered for. A component this
+ * report has no entry for is not a component that has never changed — it is one
+ * nobody asked about, either because no store answered or because the run capped
+ * how many it asked. Silence is therefore silent rather than reassuring: nothing
+ * is printed for it, and the run's own warnings carry the reason.
+ */
+function componentChurn(report, observation) {
+    if (report.churn === undefined)
+        return [];
+    const named = [
+        ...new Set(observation.regions
+            .filter((region) => region.cause && region.component !== undefined)
+            .map((region) => region.component)),
+    ];
+    const lines = named.flatMap((component) => {
+        const record = report.churn?.[component];
+        return record === undefined ? [] : [`  ${record.because}`];
+    });
+    return lines.length === 0 ? [] : ['', 'HOW OFTEN THESE COMPONENTS CHANGE:', ...lines];
+}
+/**
+ * How often this has happened before, or the fact that nobody was asked.
+ *
+ * The absent arm is not politeness. Two readings put a floor under flakiness and
+ * never a ceiling, so "no record answered" and "this has never happened" are
+ * different sentences with different next actions — and only one of them is
+ * something this report can support.
+ */
+function recurrence(report, subject) {
+    const record = report.flakiness?.[subject];
+    if (record === undefined) {
+        return [
+            'No history record answered for this subject, so nothing here says whether it has',
+            'happened before. Absence of a record is not a first occurrence.',
+        ];
+    }
+    const named = record.causes
+        .map((cause) => [cause.component, cause.band].filter((part) => part !== undefined).join(' '))
+        .filter((label) => label !== '')
+        .slice(0, 3);
+    return [
+        `OVER THE RECORDED WINDOW: ${record.because}.` +
+            (named.length === 0 ? '' : ` Seen in: ${named.join(', ')}.`),
+        ...(record.sweepsSince > 0 && record.occurrences > 1
+            ? [
+                'It has been quiet for the last few sweeps, so check whether a fix already landed',
+                'before writing another one.',
+            ]
+            : []),
+    ];
+}
+/** The unstable components as `Name file:line`, which is what an editor opens. */
+function unstableAt(components) {
+    return components
+        .map((component) => component.file === undefined ? component.name : `${component.name} ${component.file}`)
+        .join(', ');
+}
+function regionLine(region) {
+    const head = region.unattributed === true
+        ? `unattributed — a region no box contained, which usually means the scale or origin was wrong`
+        : (region.component ?? region.path ?? 'unknown');
+    return [
+        `  ${region.cause ? 'cause     ' : 'collateral'} ${region.pixels}px ` +
+            `at ${region.x},${region.y} ${region.width}×${region.height} — ${head}`,
+        region.where !== undefined ? `      in ${region.where}` : null,
+        region.file !== undefined ? `      ${region.file}` : null,
+        // The digest, on the region it describes. An agent's two non-code responses
+        // to a recurring difference are `variance accept --shape <it>` and an
+        // `ignore` rule keyed on it, and neither is reachable without the value —
+        // printing it in a different section would make an agent guess which line it
+        // belonged to.
+        region.fingerprint !== undefined ? `      shape ${region.fingerprint}` : null,
+    ]
+        .filter((line) => line !== null)
+        .join('\n');
+}
+/**
+ * The defects under the band each was filed as, dated where the record says.
+ *
+ * The same two questions the review page and the HTML report answer above their
+ * own lists, and the same fold answering them — an agent reading a flat list of
+ * eleven rules has to know which of them the project blocks on and which of them
+ * it inherited, and neither is derivable from the rule name.
+ *
+ * The band heads a group rather than prefixing a row because most renders carry
+ * one band, and a word repeated down a column is a word a reader stops seeing.
+ *
+ * Above the bands is the split the review page and the HTML report draw: what
+ * this change brought, then — under its own count — what it did not. There is no
+ * folding to do in text, so the separation is an order and a line, and the order
+ * is the part that matters. An agent handed twenty inherited defects first will
+ * either fix twenty or fix none.
+ */
+function findingLines(findings) {
+    const { arrived, rest, dated } = byArrival(findings);
+    if (!dated)
+        return bandLines(findings);
+    const carried = carriedLine(findings);
+    return [
+        ...(arrived.length === 0 ? [] : bandLines(arrived)),
+        ...(carried === undefined ? [] : [`  ${carried} — separate work`, ...bandLines(rest)]),
+    ];
+}
+/** One list, banded, dated per row only where the rows disagree. */
+function bandLines(findings) {
+    const dated = mixedAges(findings);
+    return byBand(findings).flatMap((group) => [
+        `  ${group.title}`,
+        ...group.findings.map((finding) => `    [${finding.rule}] ${finding.what}` +
+            (dated ? ` — ${AGE_WORDS[ageOf(finding)]}` : '') +
+            (finding.file === undefined ? '' : `\n      ${finding.file}`)),
+    ]);
+}
+//# sourceMappingURL=describe.js.map

package/dist/tools/describe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.js","sourceRoot":"","sources":["../../src/tools/describe.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  AGE_WORDS,\n  ageOf,\n  byArrival,\n  byBand,\n  carriedLine,\n  findingTotals,\n  mixedAges,\n} from '@variance-authority/report';\nimport type {\n  FindingRecord,\n  FlakinessRecord,\n  RegionRecord,\n  RunReport,\n} from '@variance-authority/report';\nimport { describePresentation } from '../presentation.js';\nimport { subjectOf, unobserved } from './subject.js';\nimport type { Tool } from './tool.js';\n\n/**\n * `variance_describe`, and the region format nothing else prints.\n *\n * `regionLine` stays with the tool because the region list is this answer's whole\n * substance, and everything around it is an ordering decision that belongs to\n * this tool rather than to regions in general: the leak warning above the list\n * because it changes what every line below means, the findings before it because\n * an `unchanged` subject can carry nothing else, and the truncation count after\n * it because a capped list that does not say so reads as a complete one.\n */\n\n/**\n * One subject, in full: what changed, where it is, and which file to open.\n *\n * The tool an agent calls after the summary, and the one that has to be complete\n * — an agent that has to ask three more questions to locate an edit will guess\n * instead.\n */\nexport const describe: Tool = {\n  name: 'variance_describe',\n  description:\n    'Everything known about one subject: the ranked regions, the component each belongs to, ' +\n    'a landmark description of where it is on the page, the source file to edit, and each ' +\n    \"region's shape fingerprint — which is what `variance accept --shape` and an `ignore` \" +\n    'rule are keyed on when a difference is not a code problem. Causes are listed before ' +\n    'collateral. A subject the run did not observe is answered with why, not refused.',\n  inputSchema: {\n    type: 'object',\n    properties: { subject: { type: 'string', description: 'Subject id from variance_summary.' } },\n    required: ['subject'],\n    additionalProperties: false,\n  },\n\n  run(report, input) {\n    const located = subjectOf(report, input);\n    if (!located.observed) return unobserved(located.entry);\n    const { observation } = located;\n\n    const lines = [\n      `[${label(observation)}] ${observation.subject}`,\n      observation.because,\n      // Ahead of the leak note, because it disqualifies that one too. A clean\n      // world re-collection was never taken on this subject — its answer would\n      // have been a comparison between two readings that do not agree anyway —\n      // so there is no order-dependence claim here to place second.\n      ...(observation.unstable !== undefined && observation.unstable.absorbed === undefined\n        ? [\n            `NOT A COMPONENT CHANGE: ${observation.unstable.because}. The regions below are`,\n            'the difference between one of those two readings and the baseline, so which',\n            'ones appear here is decided by a race. Do not review them and do not accept',\n            'this subject. Fix what moves between two readings of the same page' +\n              (observation.unstable.components.length === 0\n                ? ', starting from the subject itself — no snapshot was collected, so nothing'\n                  + ' could name the component that moved.'\n                : `, starting at ${unstableAt(observation.unstable.components)}` +\n                  (observation.unstable.bands.length === 0\n                    ? '.'\n                    : ` (${observation.unstable.bands.join(', ')}).`)),\n          ]\n        : []),\n      // What the record says, directly under the instruction it qualifies. An\n      // agent handed \"fix what moves between two readings\" acts differently when\n      // the answer is \"this has fired in eleven of the last twelve sweeps\" than\n      // when it is \"twice in March, and nine sweeps have been clean since\" — the\n      // second is a fix that already landed, and rewriting it is a day spent\n      // re-solving somebody's solved problem.\n      ...(observation.unstable !== undefined ? recurrence(report, observation.subject) : []),\n      // The experiment, spelled out. An agent that has just been told to fix\n      // what moves between two readings needs a way to find out whether it did,\n      // and the alternative it reaches for otherwise is a full run — three\n      // hundred subjects and a browser, to answer a question about one of them.\n      ...(observation.unstable !== undefined && observation.unstable.absorbed === undefined\n        ? [\n            'VERIFY A FIX WITH:',\n            `  variance run --subjects '${observation.subject}' --flakes`,\n            'which reads this subject twice and nothing else, and exits 1 while the two',\n            'readings still disagree — even when every verdict is green.',\n          ]\n        : []),\n      // The same movement, inside the boundary the subject declared. Said rather\n      // than suppressed: an agent that later sees this subject go green wants to\n      // know a level was doing work, and the rule's name is what makes that\n      // auditable. It carries no instruction, because there is nothing to do.\n      ...(observation.unstable?.absorbed !== undefined\n        ? [\n            `read differently between two readings in ${(observation.unstable.bands ?? []).join(', ')}, ` +\n              `and \\`${observation.unstable.absorbed.rule}\\` asserts on ` +\n              `${observation.unstable.absorbed.level} — so none of it is asserted on here. ` +\n              'Working as declared; the regions below are the comparison, not the movement.',\n          ]\n        : []),\n      // Placed under the verdict, because it changes what every line below it\n      // means. The regions are still correct — those pixels really did move, in\n      // those components — but they are the shape of a leak rather than the shape\n      // of an edit, and an agent that reads the region list first starts editing a\n      // component whose source nobody changed.\n      ...((observation.unstable === undefined || observation.unstable.absorbed !== undefined) &&\n      observation.alone?.reproduced === false\n        ? [\n            `NOT A COMPONENT CHANGE: ${observation.alone?.because}. The regions below are real`,\n            'but they are what the leak did, not what an edit did. Do not change these',\n            'components. Find the subject that writes the state this one reads by bisecting',\n            'run order — the run cannot name it, because module-level state is invisible to',\n            'anything a rendered document can observe about itself.',\n          ]\n        : []),\n      ...(observation.missingFonts !== undefined && observation.missingFonts.length > 0\n        ? [\n            `warning: the renderer lacked ${observation.missingFonts.join(', ')}; ` +\n              'these images are of a substituted font and their metrics are not the product’s',\n          ]\n        : []),\n    ];\n\n    // What the record says about the components this subject's change was\n    // attributed to. Placed after the verdict and before the regions, because it\n    // changes how the region list should be read: a component that has caused an\n    // approved change in eleven of the last forty runs is a component whose next\n    // change is unremarkable, and one that has never moved before is the opposite.\n    lines.push(...componentChurn(report, observation));\n\n    // Findings before regions. A subject can be `unchanged` and still carry\n    // them, in which case they are the only thing this tool has to say, and a\n    // reader who stopped at \"nothing changed\" would never reach them.\n    if (observation.findings !== undefined && observation.findings.length > 0) {\n      lines.push('', findingTotals(observation.findings) + ':', ...findingLines(observation.findings));\n    }\n\n    if (observation.signals?.presentation !== undefined) {\n      lines.push('', ...describePresentation(observation.signals.presentation));\n    }\n\n    if (observation.regions.length === 0) return lines.join('\\n');\n\n    lines.push('', ...observation.regions.map(regionLine));\n\n    if (observation.truncated !== undefined && observation.truncated.regions > 0) {\n      // Never a silent cap: a truncated list that does not say so reads as\n      // complete coverage, and the reader has no way to tell the difference.\n      lines.push(\n        `+${observation.truncated.regions} smaller region(s) not listed ` +\n          `(${observation.truncated.pixels}px)`,\n      );\n    }\n\n    if (observation.images !== undefined) {\n      lines.push(\n        '',\n        'images: ' +\n          Object.entries(observation.images)\n            .map(([kind, path]) => `${kind}=${path}`)\n            .join(' '),\n      );\n    }\n\n    return lines.join('\\n');\n  },\n};\n\n/**\n * What the subject *is*, which is not always its verdict.\n *\n * Three words over one, and the order is the precedence: instability disqualifies\n * the clean-world answer, which in turn re-reads the verdict. All three subjects\n * are `changed` — the pixels did move — and all three need different work, so a\n * reader given the verdict alone acts on the wrong one two times out of three.\n */\nfunction label(observation: {\n  readonly verdict: string;\n  readonly unstable?: { readonly absorbed?: unknown };\n  readonly alone?: { readonly reproduced: boolean };\n}): string {\n  if (observation.unstable !== undefined && observation.unstable.absorbed === undefined) {\n    return 'unstable';\n  }\n  if (observation.alone?.reproduced === false) return 'order-dependent';\n  return observation.verdict;\n}\n\n/**\n * How often the components named here have changed before.\n *\n * Only the causes, and only the ones the record answered for. A component this\n * report has no entry for is not a component that has never changed — it is one\n * nobody asked about, either because no store answered or because the run capped\n * how many it asked. Silence is therefore silent rather than reassuring: nothing\n * is printed for it, and the run's own warnings carry the reason.\n */\nfunction componentChurn(\n  report: RunReport,\n  observation: { readonly regions: readonly RegionRecord[] },\n): readonly string[] {\n  if (report.churn === undefined) return [];\n\n  const named = [\n    ...new Set(\n      observation.regions\n        .filter((region) => region.cause && region.component !== undefined)\n        .map((region) => region.component as string),\n    ),\n  ];\n\n  const lines = named.flatMap((component) => {\n    const record = report.churn?.[component];\n    return record === undefined ? [] : [`  ${record.because}`];\n  });\n\n  return lines.length === 0 ? [] : ['', 'HOW OFTEN THESE COMPONENTS CHANGE:', ...lines];\n}\n\n/**\n * How often this has happened before, or the fact that nobody was asked.\n *\n * The absent arm is not politeness. Two readings put a floor under flakiness and\n * never a ceiling, so \"no record answered\" and \"this has never happened\" are\n * different sentences with different next actions — and only one of them is\n * something this report can support.\n */\nfunction recurrence(report: RunReport, subject: string): readonly string[] {\n  const record = report.flakiness?.[subject];\n\n  if (record === undefined) {\n    return [\n      'No history record answered for this subject, so nothing here says whether it has',\n      'happened before. Absence of a record is not a first occurrence.',\n    ];\n  }\n\n  const named = record.causes\n    .map((cause: FlakinessRecord['causes'][number]) =>\n      [cause.component, cause.band].filter((part) => part !== undefined).join(' '),\n    )\n    .filter((label: string) => label !== '')\n    .slice(0, 3);\n\n  return [\n    `OVER THE RECORDED WINDOW: ${record.because}.` +\n      (named.length === 0 ? '' : ` Seen in: ${named.join(', ')}.`),\n    ...(record.sweepsSince > 0 && record.occurrences > 1\n      ? [\n          'It has been quiet for the last few sweeps, so check whether a fix already landed',\n          'before writing another one.',\n        ]\n      : []),\n  ];\n}\n\n/** The unstable components as `Name file:line`, which is what an editor opens. */\nfunction unstableAt(\n  components: readonly { readonly name: string; readonly file?: string }[],\n): string {\n  return components\n    .map((component) =>\n      component.file === undefined ? component.name : `${component.name} ${component.file}`,\n    )\n    .join(', ');\n}\n\nfunction regionLine(region: RegionRecord): string {\n  const head = region.unattributed === true\n    ? `unattributed — a region no box contained, which usually means the scale or origin was wrong`\n    : (region.component ?? region.path ?? 'unknown');\n\n  return [\n    `  ${region.cause ? 'cause     ' : 'collateral'} ${region.pixels}px ` +\n      `at ${region.x},${region.y} ${region.width}×${region.height} — ${head}`,\n    region.where !== undefined ? `      in ${region.where}` : null,\n    region.file !== undefined ? `      ${region.file}` : null,\n    // The digest, on the region it describes. An agent's two non-code responses\n    // to a recurring difference are `variance accept --shape <it>` and an\n    // `ignore` rule keyed on it, and neither is reachable without the value —\n    // printing it in a different section would make an agent guess which line it\n    // belonged to.\n    region.fingerprint !== undefined ? `      shape ${region.fingerprint}` : null,\n  ]\n    .filter((line): line is string => line !== null)\n    .join('\\n');\n}\n\n/**\n * The defects under the band each was filed as, dated where the record says.\n *\n * The same two questions the review page and the HTML report answer above their\n * own lists, and the same fold answering them — an agent reading a flat list of\n * eleven rules has to know which of them the project blocks on and which of them\n * it inherited, and neither is derivable from the rule name.\n *\n * The band heads a group rather than prefixing a row because most renders carry\n * one band, and a word repeated down a column is a word a reader stops seeing.\n *\n * Above the bands is the split the review page and the HTML report draw: what\n * this change brought, then — under its own count — what it did not. There is no\n * folding to do in text, so the separation is an order and a line, and the order\n * is the part that matters. An agent handed twenty inherited defects first will\n * either fix twenty or fix none.\n */\nfunction findingLines(findings: readonly FindingRecord[]): readonly string[] {\n  const { arrived, rest, dated } = byArrival(findings);\n  if (!dated) return bandLines(findings);\n\n  const carried = carriedLine(findings);\n\n  return [\n    ...(arrived.length === 0 ? [] : bandLines(arrived)),\n    ...(carried === undefined ? [] : [`  ${carried} — separate work`, ...bandLines(rest)]),\n  ];\n}\n\n/** One list, banded, dated per row only where the rows disagree. */\nfunction bandLines(findings: readonly FindingRecord[]): readonly string[] {\n  const dated = mixedAges(findings);\n\n  return byBand(findings).flatMap((group) => [\n    `  ${group.title}`,\n    ...group.findings.map(\n      (finding) =>\n        `    [${finding.rule}] ${finding.what}` +\n        (dated ? ` — ${AGE_WORDS[ageOf(finding)]}` : '') +\n        (finding.file === undefined ? '' : `\\n      ${finding.file}`),\n    ),\n  ]);\n}\n\n"]}

package/dist/tools/diff.d.ts

@@ -0,0 +1,20 @@
+import { type Tool } from './tool.js';
+export type StateDifference = {
+    readonly kind: 'added';
+    readonly path: string;
+    readonly value: unknown;
+} | {
+    readonly kind: 'removed';
+    readonly path: string;
+    readonly value: unknown;
+} | {
+    readonly kind: 'changed';
+    readonly path: string;
+    readonly before: unknown;
+    readonly after: unknown;
+};
+/** Compare two JSON-compatible states without assigning meaning to either one. */
+export declare function diffState(before: unknown, after: unknown): readonly StateDifference[];
+/** The one stateful tool every served subject receives. */
+export declare const diff: Tool<unknown>;
+//# sourceMappingURL=diff.d.ts.map

package/dist/tools/diff.js

@@ -0,0 +1,85 @@
+import { NO_ARGS } from './tool.js';
+/** Compare two JSON-compatible states without assigning meaning to either one. */
+export function diffState(before, after) {
+    const differences = [];
+    visit('$', before, after, differences);
+    return differences;
+}
+/** The one stateful tool every served subject receives. */
+export const diff = {
+    name: 'variance_diff',
+    description: 'Compare the current state with the state held from the previous successful MCP tool invocation. ' +
+        'The first invocation records state and has nothing to compare.',
+    inputSchema: NO_ARGS,
+    run(current, _input, invocation) {
+        if (invocation?.previous === undefined) {
+            return 'No previous MCP invocation state. The current state is now remembered.';
+        }
+        const differences = diffState(invocation.previous, current);
+        if (differences.length === 0) {
+            return 'The current state matches the previous MCP invocation.';
+        }
+        return [
+            `The current state differs from the previous MCP invocation at ${String(differences.length)} path(s).`,
+            ...differences.map(describe),
+        ].join('\n');
+    },
+};
+function visit(path, before, after, differences) {
+    if (Object.is(before, after))
+        return;
+    if (isRecord(before) && isRecord(after)) {
+        const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
+        for (const key of keys) {
+            const next = `${path}${property(key)}`;
+            if (!(key in before)) {
+                differences.push({ kind: 'added', path: next, value: after[key] });
+            }
+            else if (!(key in after)) {
+                differences.push({ kind: 'removed', path: next, value: before[key] });
+            }
+            else {
+                visit(next, before[key], after[key], differences);
+            }
+        }
+        return;
+    }
+    if (Array.isArray(before) && Array.isArray(after)) {
+        const length = Math.max(before.length, after.length);
+        for (let index = 0; index < length; index += 1) {
+            const next = `${path}[${String(index)}]`;
+            if (index >= before.length) {
+                differences.push({ kind: 'added', path: next, value: after[index] });
+            }
+            else if (index >= after.length) {
+                differences.push({ kind: 'removed', path: next, value: before[index] });
+            }
+            else {
+                visit(next, before[index], after[index], differences);
+            }
+        }
+        return;
+    }
+    differences.push({ kind: 'changed', path, before, after });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function property(key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? `.${key}` : `[${JSON.stringify(key)}]`;
+}
+function describe(difference) {
+    switch (difference.kind) {
+        case 'added':
+            return `+ ${difference.path}: ${valueOf(difference.value)}`;
+        case 'removed':
+            return `- ${difference.path}: ${valueOf(difference.value)}`;
+        case 'changed':
+            return `~ ${difference.path}: ${valueOf(difference.before)} -> ${valueOf(difference.after)}`;
+    }
+}
+function valueOf(value) {
+    const encoded = JSON.stringify(value);
+    return encoded === undefined ? String(value) : encoded;
+}
+//# sourceMappingURL=diff.js.map

package/dist/tools/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../src/tools/diff.ts"],"names":[],"mappings":"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","sourcesContent":["import { NO_ARGS, type Tool } from './tool.js';\n\nexport type StateDifference =\n  | { readonly kind: 'added'; readonly path: string; readonly value: unknown }\n  | { readonly kind: 'removed'; readonly path: string; readonly value: unknown }\n  | {\n      readonly kind: 'changed';\n      readonly path: string;\n      readonly before: unknown;\n      readonly after: unknown;\n    };\n\n/** Compare two JSON-compatible states without assigning meaning to either one. */\nexport function diffState(before: unknown, after: unknown): readonly StateDifference[] {\n  const differences: StateDifference[] = [];\n  visit('$', before, after, differences);\n  return differences;\n}\n\n/** The one stateful tool every served subject receives. */\nexport const diff: Tool<unknown> = {\n  name: 'variance_diff',\n  description:\n    'Compare the current state with the state held from the previous successful MCP tool invocation. ' +\n    'The first invocation records state and has nothing to compare.',\n  inputSchema: NO_ARGS,\n  run(current, _input, invocation) {\n    if (invocation?.previous === undefined) {\n      return 'No previous MCP invocation state. The current state is now remembered.';\n    }\n\n    const differences = diffState(invocation.previous, current);\n    if (differences.length === 0) {\n      return 'The current state matches the previous MCP invocation.';\n    }\n\n    return [\n      `The current state differs from the previous MCP invocation at ${String(differences.length)} path(s).`,\n      ...differences.map(describe),\n    ].join('\\n');\n  },\n};\n\nfunction visit(\n  path: string,\n  before: unknown,\n  after: unknown,\n  differences: StateDifference[],\n): void {\n  if (Object.is(before, after)) return;\n\n  if (isRecord(before) && isRecord(after)) {\n    const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();\n    for (const key of keys) {\n      const next = `${path}${property(key)}`;\n      if (!(key in before)) {\n        differences.push({ kind: 'added', path: next, value: after[key] });\n      } else if (!(key in after)) {\n        differences.push({ kind: 'removed', path: next, value: before[key] });\n      } else {\n        visit(next, before[key], after[key], differences);\n      }\n    }\n    return;\n  }\n\n  if (Array.isArray(before) && Array.isArray(after)) {\n    const length = Math.max(before.length, after.length);\n    for (let index = 0; index < length; index += 1) {\n      const next = `${path}[${String(index)}]`;\n      if (index >= before.length) {\n        differences.push({ kind: 'added', path: next, value: after[index] });\n      } else if (index >= after.length) {\n        differences.push({ kind: 'removed', path: next, value: before[index] });\n      } else {\n        visit(next, before[index], after[index], differences);\n      }\n    }\n    return;\n  }\n\n  differences.push({ kind: 'changed', path, before, after });\n}\n\nfunction isRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction property(key: string): string {\n  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? `.${key}` : `[${JSON.stringify(key)}]`;\n}\n\nfunction describe(difference: StateDifference): string {\n  switch (difference.kind) {\n    case 'added':\n      return `+ ${difference.path}: ${valueOf(difference.value)}`;\n    case 'removed':\n      return `- ${difference.path}: ${valueOf(difference.value)}`;\n    case 'changed':\n      return `~ ${difference.path}: ${valueOf(difference.before)} -> ${valueOf(difference.after)}`;\n  }\n}\n\nfunction valueOf(value: unknown): string {\n  const encoded = JSON.stringify(value);\n  return encoded === undefined ? String(value) : encoded;\n}\n"]}

package/dist/tools/explain-verdict.d.ts

@@ -0,0 +1,25 @@
+import type { Tool } from './tool.js';
+/**
+ * `variance_explain_verdict` — the answers that are not about the code.
+ *
+ * Kept apart from `variance_describe` although both start by locating a subject.
+ * `describe` answers about pixels that moved; this one answers about a comparison
+ * that never happened, and its whole job is to end with "there is no edit to
+ * make here" — a sentence a region list cannot say, and one that stops being
+ * said the moment the two tools share a body and a caller reaches for the
+ * regions because they are already in scope.
+ */
+/**
+ * Why a subject has no comparison.
+ *
+ * `incomparable` and `new` are the two verdicts an agent will otherwise treat as
+ * failures and try to fix in code, which is exactly wrong: neither is about the
+ * code. This makes the reason legible enough to act on — or to decide not to.
+ *
+ * A subject with no observation at all is the third such case and the worst one
+ * to refuse. "Unknown subject" tells an agent the subject does not exist, so it
+ * stops asking; the truth is that the subject exists and nothing is known about
+ * it, which is the opposite conclusion.
+ */
+export declare const explain: Tool;
+//# sourceMappingURL=explain-verdict.d.ts.map

package/dist/tools/explain-verdict.js

@@ -0,0 +1,92 @@
+import { subjectOf, unobserved } from './subject.js';
+/**
+ * `variance_explain_verdict` — the answers that are not about the code.
+ *
+ * Kept apart from `variance_describe` although both start by locating a subject.
+ * `describe` answers about pixels that moved; this one answers about a comparison
+ * that never happened, and its whole job is to end with "there is no edit to
+ * make here" — a sentence a region list cannot say, and one that stops being
+ * said the moment the two tools share a body and a caller reaches for the
+ * regions because they are already in scope.
+ */
+/**
+ * Why a subject has no comparison.
+ *
+ * `incomparable` and `new` are the two verdicts an agent will otherwise treat as
+ * failures and try to fix in code, which is exactly wrong: neither is about the
+ * code. This makes the reason legible enough to act on — or to decide not to.
+ *
+ * A subject with no observation at all is the third such case and the worst one
+ * to refuse. "Unknown subject" tells an agent the subject does not exist, so it
+ * stops asking; the truth is that the subject exists and nothing is known about
+ * it, which is the opposite conclusion.
+ */
+export const explain = {
+    name: 'variance_explain_verdict',
+    description: 'Why a subject was not compared. `incomparable` means a baseline exists but another ' +
+        'machine rendered it; `new` means none exists; a subject in the coverage list was never ' +
+        'observed at all. None is a code problem — call this before attempting a fix.',
+    inputSchema: {
+        type: 'object',
+        properties: { subject: { type: 'string' } },
+        required: ['subject'],
+        additionalProperties: false,
+    },
+    run(report, input) {
+        const located = subjectOf(report, input);
+        if (!located.observed) {
+            return [
+                unobserved(located.entry),
+                '',
+                nothingCompared(located.entry.kind),
+            ].join('\n');
+        }
+        const { observation } = located;
+        switch (observation.verdict) {
+            case 'incomparable':
+                return [
+                    observation.because,
+                    '',
+                    'This is not a code change and cannot be fixed in code. Either run on the machine ' +
+                        'that wrote the baseline, re-record the baseline on this one, or use an ephemeral ' +
+                        'comparison, which renders both sides here and needs no stored image at all.',
+                ].join('\n');
+            case 'new':
+                return [
+                    observation.because,
+                    '',
+                    'Nothing has regressed; there is no baseline to regress from. Record one, ' +
+                        'or compare ephemerally against the previous revision.',
+                ].join('\n');
+            case 'unchanged':
+                return `${observation.subject} was compared and did not change: ${observation.because}`;
+            case 'ignored':
+                return [
+                    observation.because,
+                    '',
+                    'This subject changed. Every changed pixel landed inside a region the project ' +
+                        'excluded, so the run is green and nothing here was reviewed. That is a ' +
+                        'configuration decision, not a fact about the code: if the change should have ' +
+                        'been caught, the ignore is too wide.',
+                ].join('\n');
+            case 'changed':
+                return `${observation.subject} was compared and changed. Call variance_describe for the regions.`;
+        }
+    },
+};
+/** What an agent should do about a subject nothing was compared for. */
+function nothingCompared(kind) {
+    switch (kind) {
+        case 'excluded':
+            return ('Nothing was compared, so nothing is known about this subject. There is no code ' +
+                'change to make here; if it should be watched, change the exclusion.');
+        case 'unreached':
+            return ('Nothing was compared, and nothing needed to be: the run resolved that this ' +
+                'change cannot reach this subject. There is no code change to make here.');
+        default:
+            return ('Nothing was compared, so nothing is known about this subject — an absent ' +
+                'observation is not an unchanged one. Fix whatever stopped the run from seeing ' +
+                'it before treating any part of this run as a pass for this subject.');
+    }
+}
+//# sourceMappingURL=explain-verdict.js.map

package/dist/tools/explain-verdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-verdict.js","sourceRoot":"","sources":["../../src/tools/explain-verdict.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAGrD;;;;;;;;;GASG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,OAAO,GAAS;IAC3B,IAAI,EAAE,0BAA0B;IAChC,WAAW,EACT,qFAAqF;QACrF,yFAAyF;QACzF,8EAA8E;IAChF,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;QAC3C,QAAQ,EAAE,CAAC,SAAS,CAAC;QACrB,oBAAoB,EAAE,KAAK;KAC5B;IAED,GAAG,CAAC,MAAM,EAAE,KAAK;QACf,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAEzC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;YACtB,OAAO;gBACL,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC;gBACzB,EAAE;gBACF,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;aACpC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACf,CAAC;QAED,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;QAEhC,QAAQ,WAAW,CAAC,OAAO,EAAE,CAAC;YAC5B,KAAK,cAAc;gBACjB,OAAO;oBACL,WAAW,CAAC,OAAO;oBACnB,EAAE;oBACF,mFAAmF;wBACjF,mFAAmF;wBACnF,6EAA6E;iBAChF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACf,KAAK,KAAK;gBACR,OAAO;oBACL,WAAW,CAAC,OAAO;oBACnB,EAAE;oBACF,2EAA2E;wBACzE,uDAAuD;iBAC1D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACf,KAAK,WAAW;gBACd,OAAO,GAAG,WAAW,CAAC,OAAO,qCAAqC,WAAW,CAAC,OAAO,EAAE,CAAC;YAC1F,KAAK,SAAS;gBACZ,OAAO;oBACL,WAAW,CAAC,OAAO;oBACnB,EAAE;oBACF,+EAA+E;wBAC7E,yEAAyE;wBACzE,+EAA+E;wBAC/E,sCAAsC;iBACzC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACf,KAAK,SAAS;gBACZ,OAAO,GAAG,WAAW,CAAC,OAAO,oEAAoE,CAAC;QACtG,CAAC;IACH,CAAC;CACF,CAAC;AAEF,wEAAwE;AACxE,SAAS,eAAe,CAAC,IAAyB;IAChD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,UAAU;YACb,OAAO,CACL,iFAAiF;gBACjF,qEAAqE,CACtE,CAAC;QACJ,KAAK,WAAW;YACd,OAAO,CACL,6EAA6E;gBAC7E,yEAAyE,CAC1E,CAAC;QACJ;YACE,OAAO,CACL,2EAA2E;gBAC3E,gFAAgF;gBAChF,qEAAqE,CACtE,CAAC;IACN,CAAC;AACH,CAAC","sourcesContent":["import type { NotObserved } from '@variance-authority/report';\nimport { subjectOf, unobserved } from './subject.js';\nimport type { Tool } from './tool.js';\n\n/**\n * `variance_explain_verdict` — the answers that are not about the code.\n *\n * Kept apart from `variance_describe` although both start by locating a subject.\n * `describe` answers about pixels that moved; this one answers about a comparison\n * that never happened, and its whole job is to end with \"there is no edit to\n * make here\" — a sentence a region list cannot say, and one that stops being\n * said the moment the two tools share a body and a caller reaches for the\n * regions because they are already in scope.\n */\n\n/**\n * Why a subject has no comparison.\n *\n * `incomparable` and `new` are the two verdicts an agent will otherwise treat as\n * failures and try to fix in code, which is exactly wrong: neither is about the\n * code. This makes the reason legible enough to act on — or to decide not to.\n *\n * A subject with no observation at all is the third such case and the worst one\n * to refuse. \"Unknown subject\" tells an agent the subject does not exist, so it\n * stops asking; the truth is that the subject exists and nothing is known about\n * it, which is the opposite conclusion.\n */\nexport const explain: Tool = {\n  name: 'variance_explain_verdict',\n  description:\n    'Why a subject was not compared. `incomparable` means a baseline exists but another ' +\n    'machine rendered it; `new` means none exists; a subject in the coverage list was never ' +\n    'observed at all. None is a code problem — call this before attempting a fix.',\n  inputSchema: {\n    type: 'object',\n    properties: { subject: { type: 'string' } },\n    required: ['subject'],\n    additionalProperties: false,\n  },\n\n  run(report, input) {\n    const located = subjectOf(report, input);\n\n    if (!located.observed) {\n      return [\n        unobserved(located.entry),\n        '',\n        nothingCompared(located.entry.kind),\n      ].join('\\n');\n    }\n\n    const { observation } = located;\n\n    switch (observation.verdict) {\n      case 'incomparable':\n        return [\n          observation.because,\n          '',\n          'This is not a code change and cannot be fixed in code. Either run on the machine ' +\n            'that wrote the baseline, re-record the baseline on this one, or use an ephemeral ' +\n            'comparison, which renders both sides here and needs no stored image at all.',\n        ].join('\\n');\n      case 'new':\n        return [\n          observation.because,\n          '',\n          'Nothing has regressed; there is no baseline to regress from. Record one, ' +\n            'or compare ephemerally against the previous revision.',\n        ].join('\\n');\n      case 'unchanged':\n        return `${observation.subject} was compared and did not change: ${observation.because}`;\n      case 'ignored':\n        return [\n          observation.because,\n          '',\n          'This subject changed. Every changed pixel landed inside a region the project ' +\n            'excluded, so the run is green and nothing here was reviewed. That is a ' +\n            'configuration decision, not a fact about the code: if the change should have ' +\n            'been caught, the ignore is too wide.',\n        ].join('\\n');\n      case 'changed':\n        return `${observation.subject} was compared and changed. Call variance_describe for the regions.`;\n    }\n  },\n};\n\n/** What an agent should do about a subject nothing was compared for. */\nfunction nothingCompared(kind: NotObserved['kind']): string {\n  switch (kind) {\n    case 'excluded':\n      return (\n        'Nothing was compared, so nothing is known about this subject. There is no code ' +\n        'change to make here; if it should be watched, change the exclusion.'\n      );\n    case 'unreached':\n      return (\n        'Nothing was compared, and nothing needed to be: the run resolved that this ' +\n        'change cannot reach this subject. There is no code change to make here.'\n      );\n    default:\n      return (\n        'Nothing was compared, so nothing is known about this subject — an absent ' +\n        'observation is not an unchanged one. Fix whatever stopped the run from seeing ' +\n        'it before treating any part of this run as a pass for this subject.'\n      );\n  }\n}\n"]}

package/dist/tools/findings.d.ts

@@ -0,0 +1,40 @@
+import type { Tool } from './tool.js';
+/**
+ * `variance_findings` — the one answer here that reads no comparison.
+ *
+ * Alone in a module because nothing else in this package groups by anything but
+ * a subject. This tool inverts that twice — by rule, then by the place the rule
+ * fired — and both inversions exist for the same reason the docket does: the
+ * unit a reader acts on is an edit, not an occurrence.
+ */
+/**
+ * Defects in the render itself, which no comparison could have reported.
+ *
+ * A separate tool rather than part of `variance_describe` because it answers a
+ * different question. `describe` answers "what did this change do"; this answers
+ * "what is wrong with this component regardless of whether anyone touched it" —
+ * and the second is the one a comparison structurally cannot reach, since a
+ * control that never had an accessible name compares equal to itself forever.
+ *
+ * Grouped by rule rather than by subject. One missing `alt` in twelve stories is
+ * one edit to one component, and listing it twelve times under twelve subject
+ * headings is the same fatigue the docket exists to prevent.
+ *
+ * ## Two things an agent cannot act on this list without
+ *
+ * **What kind of defect it is.** Most of these rules are accessibility and the
+ * description used to say all of them were, which is wrong about the two that
+ * are not — a string the locale pass never translated is a content defect, and
+ * a box past its container's edge is a layout one. The band is the same word the
+ * project blocks on, so the heading a reader sees and the policy that stops
+ * their merge are the same word.
+ *
+ * **Whether it is theirs.** A defect the baseline carried too is somebody else's
+ * afternoon, and an agent told twelve defects with no dating will either fix
+ * twelve or fix none. The date is only ever printed from a record; nothing here
+ * infers it from an absence — and the rules holding a defect this change brought
+ * are listed before the rules holding only inherited ones, so an agent that reads
+ * the first group and stops has read the part it can act on.
+ */
+export declare const findings: Tool;
+//# sourceMappingURL=findings.d.ts.map