@variance-authority/mcp 0.1.0

package/dist/tools/adjudicate.js

@@ -0,0 +1,122 @@
+import { adjudicateRun, describeAdjudication } from '@variance-authority/report';
+/**
+ * `variance_adjudicate` — the run read back against what the agent said it did.
+ *
+ * Every other tool here answers about the run. This one answers about the
+ * *agent*, and it is the only tool in the set that takes evidence in rather than
+ * only handing it out: the declaration is something no report can contain,
+ * because the report was written by a process that never knew what the edit was
+ * for.
+ *
+ * What it buys is the arm nothing else in this category ships. `variance_changes`
+ * can tell an agent that `Button` moved in twelve subjects; it cannot tell it
+ * that `Card` — which the agent believes it just edited — did not move at all.
+ * That is not a diff finding, it is the *absence* of one, and an absence is only
+ * a finding once something declared it should have been there.
+ *
+ * The tool deliberately refuses to help an agent declare after the fact. It takes
+ * claims as an argument and derives none, so an agent that calls
+ * `variance_changes` first and then submits the answer back as its intent is
+ * scoring the run against itself — visibly, because the transcript shows the
+ * order. Nothing here can prevent that; what it can do is never do it *for* the
+ * agent.
+ */
+export const adjudicate = {
+    name: 'variance_adjudicate',
+    description: 'Read this run back against what you meant to change. Declare each intended change as a ' +
+        'claim — the component or shape, why, and at most how many subjects it should reach — and ' +
+        'get three answers: what you declared and delivered, what moved that you did not declare, ' +
+        'and what you declared that never happened. The last one is the point: it is how you find ' +
+        'out an edit did not take (wrong file, dead branch, an overridden rule, a stale build), ' +
+        'which no screenshot comparison can tell you. Declare before you read the diff; claims ' +
+        'copied out of `variance_changes` score the run against itself.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            claims: {
+                type: 'array',
+                minItems: 1,
+                description: 'What you intended to change. One entry per intended change.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        root: {
+                            type: 'string',
+                            description: 'What the change is about: `component:Button`, `shape:<fingerprint>`, or a ' +
+                                'bare name read as a component. Matched exactly, never by prefix.',
+                        },
+                        reason: {
+                            type: 'string',
+                            description: 'Why you changed it, in your own words. Carried into the answer.',
+                        },
+                        maxSubjects: {
+                            type: 'integer',
+                            minimum: 1,
+                            description: 'At most how many subjects this change should reach. Optional, and the most ' +
+                                'useful field here: exceeding it is not a failure, it is the blast radius ' +
+                                'you did not expect.',
+                        },
+                    },
+                    required: ['root', 'reason'],
+                    additionalProperties: true,
+                },
+            },
+        },
+        required: ['claims'],
+        additionalProperties: false,
+    },
+    run(report, input) {
+        const { claims, unchecked } = parseClaims(input['claims']);
+        if (claims.length === 0) {
+            // An empty declaration is not a clean run, and answering it as one would
+            // report "nothing you meant to do is missing" to an agent that declared
+            // nothing. Said plainly instead, because the fix is one field away.
+            return ('No claims were supplied, so there is nothing to adjudicate. This tool answers what ' +
+                'your run did against what you said you were doing; with no declaration it can only ' +
+                'repeat `variance_changes`. Declare the edits you made, then ask again.');
+        }
+        return describeAdjudication(adjudicateRun(report, claims, unchecked.length > 0 ? { unchecked } : {}));
+    },
+};
+/**
+ * Narrow whatever JSON a model produced, and keep what could not be checked.
+ *
+ * A declared field this resolution cannot verify is carried out rather than
+ * dropped. An agent that declares `bands: ['paint']` and is answered `delivered`
+ * has been told its band claim held; a run report keeps no band per change, so
+ * nothing looked, and the answer has to say which of the two it is.
+ */
+function parseClaims(value) {
+    if (!Array.isArray(value)) {
+        throw new Error('`claims` is required and must be an array of {root, reason, maxSubjects?}');
+    }
+    const claims = [];
+    const unchecked = new Set();
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== 'object' || entry === null) {
+            throw new Error(`claims[${index}] must be an object with \`root\` and \`reason\``);
+        }
+        const record = entry;
+        const root = record['root'];
+        const reason = record['reason'];
+        if (typeof root !== 'string' || root === '') {
+            throw new Error(`claims[${index}].root is required and must be a non-empty string`);
+        }
+        if (typeof reason !== 'string' || reason === '') {
+            throw new Error(`claims[${index}].reason is required and must be a non-empty string`);
+        }
+        const maxSubjects = record['maxSubjects'];
+        if (maxSubjects !== undefined && (typeof maxSubjects !== 'number' || maxSubjects < 1)) {
+            throw new Error(`claims[${index}].maxSubjects must be a positive integer when present`);
+        }
+        for (const key of Object.keys(record)) {
+            if (key !== 'root' && key !== 'reason' && key !== 'maxSubjects')
+                unchecked.add(key);
+        }
+        claims.push(maxSubjects === undefined
+            ? { root, reason }
+            : { root, reason, maxSubjects: Math.trunc(maxSubjects) });
+    }
+    return { claims, unchecked: [...unchecked] };
+}
+//# sourceMappingURL=adjudicate.js.map

package/dist/tools/adjudicate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adjudicate.js","sourceRoot":"","sources":["../../src/tools/adjudicate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAc,MAAM,4BAA4B,CAAC;AAG7F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAS;IAC9B,IAAI,EAAE,qBAAqB;IAC3B,WAAW,EACT,yFAAyF;QACzF,2FAA2F;QAC3F,2FAA2F;QAC3F,2FAA2F;QAC3F,yFAAyF;QACzF,wFAAwF;QACxF,gEAAgE;IAClE,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,OAAO;gBACb,QAAQ,EAAE,CAAC;gBACX,WAAW,EAAE,6DAA6D;gBAC1E,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,IAAI,EAAE;4BACJ,IAAI,EAAE,QAAQ;4BACd,WAAW,EACT,4EAA4E;gCAC5E,kEAAkE;yBACrE;wBACD,MAAM,EAAE;4BACN,IAAI,EAAE,QAAQ;4BACd,WAAW,EAAE,iEAAiE;yBAC/E;wBACD,WAAW,EAAE;4BACX,IAAI,EAAE,SAAS;4BACf,OAAO,EAAE,CAAC;4BACV,WAAW,EACT,6EAA6E;gCAC7E,2EAA2E;gCAC3E,qBAAqB;yBACxB;qBACF;oBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;oBAC5B,oBAAoB,EAAE,IAAI;iBAC3B;aACF;SACF;QACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;QACpB,oBAAoB,EAAE,KAAK;KAC5B;IAED,GAAG,CAAC,MAAM,EAAE,KAAK;QACf,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;QAE3D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,yEAAyE;YACzE,wEAAwE;YACxE,oEAAoE;YACpE,OAAO,CACL,qFAAqF;gBACrF,qFAAqF;gBACrF,wEAAwE,CACzE,CAAC;QACJ,CAAC;QAED,OAAO,oBAAoB,CACzB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACzE,CAAC;IACJ,CAAC;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAC;IAC/F,CAAC;IAED,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IAEpC,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,UAAU,KAAK,kDAAkD,CAAC,CAAC;QACrF,CAAC;QAED,MAAM,MAAM,GAAG,KAAgC,CAAC;QAChD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;QAEhC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,UAAU,KAAK,mDAAmD,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,UAAU,KAAK,qDAAqD,CAAC,CAAC;QACxF,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;QAC1C,IAAI,WAAW,KAAK,SAAS,IAAI,CAAC,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,GAAG,CAAC,CAAC,EAAE,CAAC;YACtF,MAAM,IAAI,KAAK,CAAC,UAAU,KAAK,uDAAuD,CAAC,CAAC;QAC1F,CAAC;QAED,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACtC,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,aAAa;gBAAE,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtF,CAAC;QAED,MAAM,CAAC,IAAI,CACT,WAAW,KAAK,SAAS;YACvB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE;YAClB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAC3D,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC;AAC/C,CAAC","sourcesContent":["import { adjudicateRun, describeAdjudication, type Claim } from '@variance-authority/report';\nimport type { Tool } from './tool.js';\n\n/**\n * `variance_adjudicate` — the run read back against what the agent said it did.\n *\n * Every other tool here answers about the run. This one answers about the\n * *agent*, and it is the only tool in the set that takes evidence in rather than\n * only handing it out: the declaration is something no report can contain,\n * because the report was written by a process that never knew what the edit was\n * for.\n *\n * What it buys is the arm nothing else in this category ships. `variance_changes`\n * can tell an agent that `Button` moved in twelve subjects; it cannot tell it\n * that `Card` — which the agent believes it just edited — did not move at all.\n * That is not a diff finding, it is the *absence* of one, and an absence is only\n * a finding once something declared it should have been there.\n *\n * The tool deliberately refuses to help an agent declare after the fact. It takes\n * claims as an argument and derives none, so an agent that calls\n * `variance_changes` first and then submits the answer back as its intent is\n * scoring the run against itself — visibly, because the transcript shows the\n * order. Nothing here can prevent that; what it can do is never do it *for* the\n * agent.\n */\nexport const adjudicate: Tool = {\n  name: 'variance_adjudicate',\n  description:\n    'Read this run back against what you meant to change. Declare each intended change as a ' +\n    'claim — the component or shape, why, and at most how many subjects it should reach — and ' +\n    'get three answers: what you declared and delivered, what moved that you did not declare, ' +\n    'and what you declared that never happened. The last one is the point: it is how you find ' +\n    'out an edit did not take (wrong file, dead branch, an overridden rule, a stale build), ' +\n    'which no screenshot comparison can tell you. Declare before you read the diff; claims ' +\n    'copied out of `variance_changes` score the run against itself.',\n  inputSchema: {\n    type: 'object',\n    properties: {\n      claims: {\n        type: 'array',\n        minItems: 1,\n        description: 'What you intended to change. One entry per intended change.',\n        items: {\n          type: 'object',\n          properties: {\n            root: {\n              type: 'string',\n              description:\n                'What the change is about: `component:Button`, `shape:<fingerprint>`, or a ' +\n                'bare name read as a component. Matched exactly, never by prefix.',\n            },\n            reason: {\n              type: 'string',\n              description: 'Why you changed it, in your own words. Carried into the answer.',\n            },\n            maxSubjects: {\n              type: 'integer',\n              minimum: 1,\n              description:\n                'At most how many subjects this change should reach. Optional, and the most ' +\n                'useful field here: exceeding it is not a failure, it is the blast radius ' +\n                'you did not expect.',\n            },\n          },\n          required: ['root', 'reason'],\n          additionalProperties: true,\n        },\n      },\n    },\n    required: ['claims'],\n    additionalProperties: false,\n  },\n\n  run(report, input) {\n    const { claims, unchecked } = parseClaims(input['claims']);\n\n    if (claims.length === 0) {\n      // An empty declaration is not a clean run, and answering it as one would\n      // report \"nothing you meant to do is missing\" to an agent that declared\n      // nothing. Said plainly instead, because the fix is one field away.\n      return (\n        'No claims were supplied, so there is nothing to adjudicate. This tool answers what ' +\n        'your run did against what you said you were doing; with no declaration it can only ' +\n        'repeat `variance_changes`. Declare the edits you made, then ask again.'\n      );\n    }\n\n    return describeAdjudication(\n      adjudicateRun(report, claims, unchecked.length > 0 ? { unchecked } : {}),\n    );\n  },\n};\n\n/**\n * Narrow whatever JSON a model produced, and keep what could not be checked.\n *\n * A declared field this resolution cannot verify is carried out rather than\n * dropped. An agent that declares `bands: ['paint']` and is answered `delivered`\n * has been told its band claim held; a run report keeps no band per change, so\n * nothing looked, and the answer has to say which of the two it is.\n */\nfunction parseClaims(value: unknown): { claims: Claim[]; unchecked: string[] } {\n  if (!Array.isArray(value)) {\n    throw new Error('`claims` is required and must be an array of {root, reason, maxSubjects?}');\n  }\n\n  const claims: Claim[] = [];\n  const unchecked = new Set<string>();\n\n  for (const [index, entry] of value.entries()) {\n    if (typeof entry !== 'object' || entry === null) {\n      throw new Error(`claims[${index}] must be an object with \\`root\\` and \\`reason\\``);\n    }\n\n    const record = entry as Record<string, unknown>;\n    const root = record['root'];\n    const reason = record['reason'];\n\n    if (typeof root !== 'string' || root === '') {\n      throw new Error(`claims[${index}].root is required and must be a non-empty string`);\n    }\n    if (typeof reason !== 'string' || reason === '') {\n      throw new Error(`claims[${index}].reason is required and must be a non-empty string`);\n    }\n\n    const maxSubjects = record['maxSubjects'];\n    if (maxSubjects !== undefined && (typeof maxSubjects !== 'number' || maxSubjects < 1)) {\n      throw new Error(`claims[${index}].maxSubjects must be a positive integer when present`);\n    }\n\n    for (const key of Object.keys(record)) {\n      if (key !== 'root' && key !== 'reason' && key !== 'maxSubjects') unchecked.add(key);\n    }\n\n    claims.push(\n      maxSubjects === undefined\n        ? { root, reason }\n        : { root, reason, maxSubjects: Math.trunc(maxSubjects) },\n    );\n  }\n\n  return { claims, unchecked: [...unchecked] };\n}\n"]}

package/dist/tools/attention.d.ts

@@ -0,0 +1,13 @@
+import type { Attention, EyesArchive, EyesPhase, EyesTestAttention, TargetSnapshot } from '@variance-authority/eyes';
+import { type Tool } from './tool.js';
+type Phase = EyesPhase | 'unphased';
+/** Test attention in authored AAA order, with selectors and attributed targets. */
+export declare const attention: Tool<EyesArchive>;
+export declare function locateEyesTest(archive: EyesArchive, asked: string): EyesTestAttention | string;
+export declare function phasedAttention(entries: readonly Attention[]): readonly {
+    phase: Phase;
+    entry: Attention;
+}[];
+export declare function targetsOf(entry: Attention): readonly TargetSnapshot[];
+export {};
+//# sourceMappingURL=attention.d.ts.map

package/dist/tools/attention.js

@@ -0,0 +1,151 @@
+import { stringArg } from './tool.js';
+/** Test attention in authored AAA order, with selectors and attributed targets. */
+export const attention = {
+    name: 'variance_test_attention',
+    description: 'List Eyes-instrumented tests, or explain one test’s selectors, Locator consumption, DOM events, and authored Arrange/Act/Assert boundaries in order.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            test: { type: 'string', description: 'A test id, exact title, or unambiguous title part.' },
+            phase: { enum: ['arrange', 'act', 'assert'], description: 'Optional authored AAA phase.' },
+        },
+        additionalProperties: false,
+    },
+    run(archive, input) {
+        if (input['test'] === undefined)
+            return listing(archive);
+        const found = locate(archive, stringArg(input, 'test'));
+        if (typeof found === 'string')
+            return found;
+        const phase = optionalPhase(input);
+        const lines = attentionLines(found.attention, phase);
+        return [
+            `${found.title} — ${found.file ?? 'file not supplied'} [${found.id}]`,
+            found.complete ? 'Attention journal: complete.' : `Attention journal: partial — ${found.because}`,
+            ...(phase === undefined ? [] : [`Authored phase: ${phase}.`]),
+            '',
+            ...(lines.length === 0
+                ? [`No attention was recorded${phase === undefined ? '' : ` in ${phase}`}.`]
+                : lines),
+        ].join('\n');
+    },
+};
+export function locateEyesTest(archive, asked) {
+    const byId = archive.tests.find((test) => test.id === asked);
+    if (byId !== undefined)
+        return byId;
+    const exact = archive.tests.filter((test) => test.title === asked);
+    if (exact.length === 1)
+        return exact[0];
+    const lowered = asked.toLowerCase();
+    const partial = archive.tests.filter((test) => test.title.toLowerCase().includes(lowered));
+    if (partial.length === 1)
+        return partial[0];
+    if (partial.length === 0)
+        return `No Eyes test matches ${asked}. ${archive.tests.length} test(s) are recorded.`;
+    return `${partial.length} Eyes tests match ${asked}; ask by id:\n${partial.map((test) => `  ${test.title} [${test.id}]`).join('\n')}`;
+}
+export function phasedAttention(entries) {
+    let phase = 'unphased';
+    const phased = [];
+    for (const entry of entries) {
+        if (entry.kind === 'eyes-phase')
+            phase = entry.phase;
+        phased.push({ phase, entry });
+    }
+    return phased;
+}
+export function targetsOf(entry) {
+    if (entry.kind === 'rtl-query' && entry.outcome === 'resolved')
+        return entry.targets;
+    if (entry.kind === 'document-event')
+        return [entry.target];
+    if (entry.kind === 'playwright-locator' && entry.operation !== 'planned') {
+        return [...(entry.before ?? []), ...(entry.outcome === 'resolved' ? entry.after ?? [] : [])];
+    }
+    return [];
+}
+function listing(archive) {
+    if (archive.tests.length === 0)
+        return 'Eyes measured an archive containing no tests.';
+    return [
+        `${archive.tests.length} Eyes test(s):`,
+        ...archive.tests.map((test) => `  ${test.complete ? 'complete' : 'partial'} — ${test.title} — ${test.file ?? 'file not supplied'} [${test.id}]`),
+    ].join('\n');
+}
+function locate(archive, asked) {
+    return locateEyesTest(archive, asked);
+}
+function optionalPhase(input) {
+    const value = input['phase'];
+    if (value === undefined)
+        return undefined;
+    if (value !== 'arrange' && value !== 'act' && value !== 'assert') {
+        throw new Error('`phase` must be arrange, act, or assert');
+    }
+    return value;
+}
+function attentionLines(entries, only) {
+    return phasedAttention(entries)
+        .filter(({ phase }) => only === undefined || phase === only)
+        .map(({ phase, entry }) => `#${entry.sequence} [${phase}] ${describe(entry)}`);
+}
+function describe(entry) {
+    if (entry.kind === 'eyes-phase')
+        return `phase → ${entry.phase}`;
+    if (entry.kind === 'react-commit') {
+        const rendered = entry.commit.components.length === 0
+            ? 'no composite renderers'
+            : entry.commit.components.join(', ');
+        if (entry.commit.updaters === undefined) {
+            return `React commit → rendered ${rendered}; update initiators unavailable`;
+        }
+        const updaters = entry.commit.updaters.length === 0
+            ? 'measured empty'
+            : entry.commit.updaters.map((updater) => updater.path.map((frame) => frame.name).join(' ← ')).join('; ');
+        return `React commit → rendered ${rendered}; update initiators: ${updaters}`;
+    }
+    if (entry.kind === 'document-event') {
+        return `document ${entry.event}${entry.trusted ? '' : ' (synthetic)'} → ${targetLine(entry.target)}`;
+    }
+    if (entry.kind === 'rtl-query') {
+        const call = `${entry.query}(${argumentsLine(entry.arguments)})`;
+        if (entry.outcome === 'threw')
+            return `${call} threw ${entry.error}`;
+        if (entry.outcome === 'absent')
+            return `${call} → absent`;
+        return `${call} → ${targetList(entry.targets)}`;
+    }
+    const locator = locatorLine(entry.locator);
+    if (entry.operation === 'planned')
+        return `planned ${locator}`;
+    if (entry.outcome === 'threw')
+        return `${entry.operation} ${entry.member} on ${locator} threw ${entry.error}`;
+    return `${entry.operation} ${entry.member} on ${locator} — before ${targetList(entry.before ?? [])}; after ${targetList(entry.after ?? [])}`;
+}
+function locatorLine(steps) {
+    return steps.map((step) => `${step.member}(${argumentsLine(step.arguments)})`).join('.');
+}
+function argumentsLine(values) {
+    return values.map((value) => JSON.stringify(value)).join(', ');
+}
+function targetList(targets) {
+    return targets.length === 0 ? '0 targets' : targets.map(targetLine).join('; ');
+}
+function targetLine(target) {
+    const identity = [
+        target.nodeName,
+        target.role === undefined ? undefined : `role=${target.role}`,
+        target.ariaLabel === undefined ? undefined : `name=${JSON.stringify(target.ariaLabel)}`,
+        target.id === undefined ? undefined : `#${target.id}`,
+    ].filter((part) => part !== undefined).join(' ');
+    if (target.provenance.status === 'no-fiber')
+        return `${identity} [no Fiber: ${target.provenance.reason}]`;
+    const provenance = target.provenance.provenance;
+    const owners = provenance.owners.map((owner) => owner.name).join(' ← ') || 'React root';
+    const source = provenance.source === undefined
+        ? ''
+        : ` at ${provenance.source.file}:${provenance.source.line}`;
+    return `${identity} [${owners}${source}]`;
+}
+//# sourceMappingURL=attention.js.map

package/dist/tools/attention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention.js","sourceRoot":"","sources":["../../src/tools/attention.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  Attention,\n  EyesArchive,\n  EyesPhase,\n  EyesTestAttention,\n  LocatorStep,\n  TargetSnapshot,\n} from '@variance-authority/eyes';\nimport { stringArg, type Tool } from './tool.js';\n\ntype Phase = EyesPhase | 'unphased';\n\n/** Test attention in authored AAA order, with selectors and attributed targets. */\nexport const attention: Tool<EyesArchive> = {\n  name: 'variance_test_attention',\n  description:\n    'List Eyes-instrumented tests, or explain one test’s selectors, Locator consumption, DOM events, and authored Arrange/Act/Assert boundaries in order.',\n  inputSchema: {\n    type: 'object',\n    properties: {\n      test: { type: 'string', description: 'A test id, exact title, or unambiguous title part.' },\n      phase: { enum: ['arrange', 'act', 'assert'], description: 'Optional authored AAA phase.' },\n    },\n    additionalProperties: false,\n  },\n  run(archive, input) {\n    if (input['test'] === undefined) return listing(archive);\n    const found = locate(archive, stringArg(input, 'test'));\n    if (typeof found === 'string') return found;\n    const phase = optionalPhase(input);\n    const lines = attentionLines(found.attention, phase);\n    return [\n      `${found.title} — ${found.file ?? 'file not supplied'} [${found.id}]`,\n      found.complete ? 'Attention journal: complete.' : `Attention journal: partial — ${found.because}`,\n      ...(phase === undefined ? [] : [`Authored phase: ${phase}.`]),\n      '',\n      ...(lines.length === 0\n        ? [`No attention was recorded${phase === undefined ? '' : ` in ${phase}`}.`]\n        : lines),\n    ].join('\\n');\n  },\n};\n\nexport function locateEyesTest(archive: EyesArchive, asked: string): EyesTestAttention | string {\n  const byId = archive.tests.find((test) => test.id === asked);\n  if (byId !== undefined) return byId;\n  const exact = archive.tests.filter((test) => test.title === asked);\n  if (exact.length === 1) return exact[0]!;\n  const lowered = asked.toLowerCase();\n  const partial = archive.tests.filter((test) => test.title.toLowerCase().includes(lowered));\n  if (partial.length === 1) return partial[0]!;\n  if (partial.length === 0) return `No Eyes test matches ${asked}. ${archive.tests.length} test(s) are recorded.`;\n  return `${partial.length} Eyes tests match ${asked}; ask by id:\\n${partial.map((test) => `  ${test.title} [${test.id}]`).join('\\n')}`;\n}\n\nexport function phasedAttention(entries: readonly Attention[]): readonly { phase: Phase; entry: Attention }[] {\n  let phase: Phase = 'unphased';\n  const phased: { phase: Phase; entry: Attention }[] = [];\n  for (const entry of entries) {\n    if (entry.kind === 'eyes-phase') phase = entry.phase;\n    phased.push({ phase, entry });\n  }\n  return phased;\n}\n\nexport function targetsOf(entry: Attention): readonly TargetSnapshot[] {\n  if (entry.kind === 'rtl-query' && entry.outcome === 'resolved') return entry.targets;\n  if (entry.kind === 'document-event') return [entry.target];\n  if (entry.kind === 'playwright-locator' && entry.operation !== 'planned') {\n    return [...(entry.before ?? []), ...(entry.outcome === 'resolved' ? entry.after ?? [] : [])];\n  }\n  return [];\n}\n\nfunction listing(archive: EyesArchive): string {\n  if (archive.tests.length === 0) return 'Eyes measured an archive containing no tests.';\n  return [\n    `${archive.tests.length} Eyes test(s):`,\n    ...archive.tests.map((test) =>\n      `  ${test.complete ? 'complete' : 'partial'} — ${test.title} — ${test.file ?? 'file not supplied'} [${test.id}]`),\n  ].join('\\n');\n}\n\nfunction locate(archive: EyesArchive, asked: string): EyesTestAttention | string {\n  return locateEyesTest(archive, asked);\n}\n\nfunction optionalPhase(input: Readonly<Record<string, unknown>>): EyesPhase | undefined {\n  const value = input['phase'];\n  if (value === undefined) return undefined;\n  if (value !== 'arrange' && value !== 'act' && value !== 'assert') {\n    throw new Error('`phase` must be arrange, act, or assert');\n  }\n  return value;\n}\n\nfunction attentionLines(entries: readonly Attention[], only: EyesPhase | undefined): string[] {\n  return phasedAttention(entries)\n    .filter(({ phase }) => only === undefined || phase === only)\n    .map(({ phase, entry }) => `#${entry.sequence} [${phase}] ${describe(entry)}`);\n}\n\nfunction describe(entry: Attention): string {\n  if (entry.kind === 'eyes-phase') return `phase → ${entry.phase}`;\n  if (entry.kind === 'react-commit') {\n    const rendered = entry.commit.components.length === 0\n      ? 'no composite renderers'\n      : entry.commit.components.join(', ');\n    if (entry.commit.updaters === undefined) {\n      return `React commit → rendered ${rendered}; update initiators unavailable`;\n    }\n    const updaters = entry.commit.updaters.length === 0\n      ? 'measured empty'\n      : entry.commit.updaters.map((updater) =>\n        updater.path.map((frame) => frame.name).join(' ← ')).join('; ');\n    return `React commit → rendered ${rendered}; update initiators: ${updaters}`;\n  }\n  if (entry.kind === 'document-event') {\n    return `document ${entry.event}${entry.trusted ? '' : ' (synthetic)'} → ${targetLine(entry.target)}`;\n  }\n  if (entry.kind === 'rtl-query') {\n    const call = `${entry.query}(${argumentsLine(entry.arguments)})`;\n    if (entry.outcome === 'threw') return `${call} threw ${entry.error}`;\n    if (entry.outcome === 'absent') return `${call} → absent`;\n    return `${call} → ${targetList(entry.targets)}`;\n  }\n  const locator = locatorLine(entry.locator);\n  if (entry.operation === 'planned') return `planned ${locator}`;\n  if (entry.outcome === 'threw') return `${entry.operation} ${entry.member} on ${locator} threw ${entry.error}`;\n  return `${entry.operation} ${entry.member} on ${locator} — before ${targetList(entry.before ?? [])}; after ${targetList(entry.after ?? [])}`;\n}\n\nfunction locatorLine(steps: readonly LocatorStep[]): string {\n  return steps.map((step) => `${step.member}(${argumentsLine(step.arguments)})`).join('.');\n}\n\nfunction argumentsLine(values: readonly unknown[]): string {\n  return values.map((value) => JSON.stringify(value)).join(', ');\n}\n\nfunction targetList(targets: readonly TargetSnapshot[]): string {\n  return targets.length === 0 ? '0 targets' : targets.map(targetLine).join('; ');\n}\n\nfunction targetLine(target: TargetSnapshot): string {\n  const identity = [\n    target.nodeName,\n    target.role === undefined ? undefined : `role=${target.role}`,\n    target.ariaLabel === undefined ? undefined : `name=${JSON.stringify(target.ariaLabel)}`,\n    target.id === undefined ? undefined : `#${target.id}`,\n  ].filter((part): part is string => part !== undefined).join(' ');\n  if (target.provenance.status === 'no-fiber') return `${identity} [no Fiber: ${target.provenance.reason}]`;\n  const provenance = target.provenance.provenance;\n  const owners = provenance.owners.map((owner) => owner.name).join(' ← ') || 'React root';\n  const source = provenance.source === undefined\n    ? ''\n    : ` at ${provenance.source.file}:${provenance.source.line}`;\n  return `${identity} [${owners}${source}]`;\n}\n"]}

package/dist/tools/changelog.d.ts

@@ -0,0 +1,38 @@
+import type { Tool } from './tool.js';
+/**
+ * `variance_changelog` — what the baseline update would say, before it is made.
+ *
+ * Every other tool here answers *what changed*. This one answers *what would be
+ * written down about it*, and the difference matters because of where that
+ * writing goes: a baseline update is explained in the commit that carries it or
+ * in a review database, and both are written at the moment of acceptance and
+ * never again. An agent that runs `accept` without knowing what the record will
+ * say has already written it.
+ *
+ * ## Why it previews rather than proposes prose
+ *
+ * The answer is not this tool's phrasing of the change. It is the lines the
+ * commit will actually carry, rendered by the same function that renders them
+ * into the commit — `changelogBody` over a record from `changelogOf`. A tool
+ * that wrote its own summary would be a second account of a baseline update,
+ * edited separately from the first, and the two would disagree in the direction
+ * that matters: the one an agent read would not be the one that survived.
+ *
+ * The subject set is chosen by the same rules `accept` applies, for the same
+ * reason. `promotionOf` refuses an unstable subject and a subject the run left
+ * no image for; a preview that counted those would promise entries the command
+ * then refuses by name, which is worse than not previewing at all.
+ *
+ * ## What it deliberately does not do
+ *
+ * It does not render the trailers. Those are the record — versioned, encoded,
+ * append-only once committed — and a record exists when somebody accepted
+ * something. A trailer an agent could copy out of a preview is a record of a
+ * promotion that never happened, which is the one artifact this whole mechanism
+ * is arranged to prevent.
+ *
+ * It reads no clock. The instant a record carries is the instant of acceptance,
+ * and acceptance happens in another process, later, possibly not at all.
+ */
+export declare const changelog: Tool;
+//# sourceMappingURL=changelog.d.ts.map

package/dist/tools/changelog.js

@@ -0,0 +1,201 @@
+import { changelogBody, changelogOf, isRecorded, promotionOf, selectByShape, whyNotWhole, } from '@variance-authority/report';
+/**
+ * `variance_changelog` — what the baseline update would say, before it is made.
+ *
+ * Every other tool here answers *what changed*. This one answers *what would be
+ * written down about it*, and the difference matters because of where that
+ * writing goes: a baseline update is explained in the commit that carries it or
+ * in a review database, and both are written at the moment of acceptance and
+ * never again. An agent that runs `accept` without knowing what the record will
+ * say has already written it.
+ *
+ * ## Why it previews rather than proposes prose
+ *
+ * The answer is not this tool's phrasing of the change. It is the lines the
+ * commit will actually carry, rendered by the same function that renders them
+ * into the commit — `changelogBody` over a record from `changelogOf`. A tool
+ * that wrote its own summary would be a second account of a baseline update,
+ * edited separately from the first, and the two would disagree in the direction
+ * that matters: the one an agent read would not be the one that survived.
+ *
+ * The subject set is chosen by the same rules `accept` applies, for the same
+ * reason. `promotionOf` refuses an unstable subject and a subject the run left
+ * no image for; a preview that counted those would promise entries the command
+ * then refuses by name, which is worse than not previewing at all.
+ *
+ * ## What it deliberately does not do
+ *
+ * It does not render the trailers. Those are the record — versioned, encoded,
+ * append-only once committed — and a record exists when somebody accepted
+ * something. A trailer an agent could copy out of a preview is a record of a
+ * promotion that never happened, which is the one artifact this whole mechanism
+ * is arranged to prevent.
+ *
+ * It reads no clock. The instant a record carries is the instant of acceptance,
+ * and acceptance happens in another process, later, possibly not at all.
+ */
+export const changelog = {
+    name: 'variance_changelog',
+    description: 'Preview what accepting this run would write into the baseline changelog: the same lines ' +
+        'the commit message will carry, the subjects that would land in it, and the subjects that ' +
+        'would be refused and why. Takes the same selection as `variance accept` — a shape, named ' +
+        'subjects, or everything. Ask this before proposing an accept command; the record is ' +
+        'written once, at acceptance, and is the only explanation of the baseline that outlives ' +
+        'the run.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            shape: {
+                type: 'string',
+                description: 'Optional. A shape digest from `variance_changes`. Previews `accept --shape`, which ' +
+                    'takes the subjects this shape wholly explains and refuses the rest by name.',
+            },
+            subjects: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Optional. Subject ids, as `accept` would take them by name.',
+            },
+        },
+        additionalProperties: false,
+    },
+    run(report, input) {
+        const shape = typeof input['shape'] === 'string' ? input['shape'] : undefined;
+        const named = Array.isArray(input['subjects'])
+            ? input['subjects'].filter((value) => typeof value === 'string')
+            : undefined;
+        if (shape !== undefined && named !== undefined && named.length > 0) {
+            // Refused rather than resolved by precedence. These are two different
+            // commands, and picking one silently would preview an update the agent did
+            // not ask about and then hand it a command that performs the other.
+            return ('Ask for one selection at a time: a shape, or subjects by name. They are two ' +
+                'different accept commands and this would preview one while naming the other.');
+        }
+        const selection = shape !== undefined ? 'shape' : named !== undefined && named.length > 0 ? 'named' : 'all';
+        const chosen = select(report, shape, named);
+        if (typeof chosen === 'string')
+            return chosen;
+        const promotable = [];
+        const refused = [...chosen.refused];
+        let alreadyBaseline = 0;
+        for (const observation of chosen.targets) {
+            const promotion = promotionOf(observation);
+            if (promotion.kind === 'promotable')
+                promotable.push(observation.subject);
+            else if (promotion.kind === 'already-baseline')
+                alreadyBaseline += 1;
+            else
+                refused.push({ subject: observation.subject, because: promotion.because });
+        }
+        const record = changelogOf({
+            report,
+            accepted: promotable,
+            selection,
+            // The run's own instant, never this process's. A record is stamped when
+            // somebody accepts, in another process; a clock read here would put a time
+            // in a preview that the record will not carry.
+            at: report.at,
+        });
+        if (!isRecorded(record)) {
+            return [
+                `Nothing would be recorded: ${record.because}.`,
+                ...(refused.length > 0
+                    ? ['', `Refused (${String(refused.length)}):`, ...refused.map(line)]
+                    : []),
+                ...(alreadyBaseline > 0
+                    ? ['', `${String(alreadyBaseline)} subject(s) already are the baseline.`]
+                    : []),
+            ].join('\n');
+        }
+        const unshaped = promotable.filter((subject) => !inRecord(record.entries, subject));
+        return [
+            `Accepting this would record ${String(record.entries.length)} change(s) across ` +
+                `${String(promotable.length)} subject(s). These are the lines the commit will carry:`,
+            '',
+            ...changelogBody(record),
+            '',
+            `  ${command(selection, shape, promotable)}`,
+            ...(unshaped.length > 0
+                ? [
+                    '',
+                    `Promoted but not described (${String(unshaped.length)}): ${unshaped.join(', ')}`,
+                    '  The run named no difference shape in these, so the record counts them and ' +
+                        'cannot say what changed in them. Nothing later can recover it.',
+                ]
+                : []),
+            ...(refused.length > 0
+                ? ['', `Refused, and absent from the record (${String(refused.length)}):`, ...refused.map(line)]
+                : []),
+            ...(alreadyBaseline > 0
+                ? ['', `${String(alreadyBaseline)} subject(s) already are the baseline and record nothing.`]
+                : []),
+        ].join('\n');
+    },
+};
+/**
+ * The subjects the named selection reaches, or the sentence saying it reaches none.
+ *
+ * `--shape` carries its own refusals — the subjects where the shape is present
+ * beside something else — and they are part of the preview rather than a detail
+ * of the command, because they are the part of the change this update would
+ * leave in the suite.
+ */
+function select(report, shape, named) {
+    if (shape !== undefined) {
+        const selected = selectByShape(report.observations, new Set([shape]));
+        if (selected.whole.length === 0 && selected.partial.length === 0) {
+            return (`The shape ${shape} appears in no region of this run. A fingerprint is copied from a ` +
+                'region in a report; check it came from this one.');
+        }
+        return {
+            targets: selected.whole,
+            refused: selected.partial.map((observation) => ({
+                subject: observation.subject,
+                because: whyNotWhole(observation),
+            })),
+        };
+    }
+    if (named !== undefined && named.length > 0) {
+        const targets = [];
+        const missing = [];
+        for (const subject of named) {
+            const found = report.observations.find((entry) => entry.subject === subject);
+            if (found === undefined)
+                missing.push(subject);
+            else
+                targets.push(found);
+        }
+        if (targets.length === 0) {
+            return `None of those subjects are in this run: ${missing.join(', ')}.`;
+        }
+        return {
+            targets,
+            refused: missing.map((subject) => ({
+                subject,
+                because: 'this run has no observation for it, so `accept` would refuse the command',
+            })),
+        };
+    }
+    return { targets: report.observations, refused: [] };
+}
+/**
+ * The command that writes it, spelled out.
+ *
+ * `--message-file` is on every one of them. The message is where the record
+ * goes, and an accept run without it promotes the images and explains nothing —
+ * which is the state this tool exists to make visible before it happens.
+ */
+function command(selection, shape, promotable) {
+    const how = selection === 'shape'
+        ? `--shape ${shape ?? ''}`
+        : selection === 'named'
+            ? promotable.map((subject) => `"${subject}"`).join(' ')
+            : '--all';
+    return `variance accept ${how} --message-file .variance/commit-message.txt`;
+}
+function inRecord(entries, subject) {
+    return entries.some((entry) => entry.subjects.includes(subject));
+}
+function line(refusal) {
+    return `  ${refusal.subject} — ${refusal.because}`;
+}
+//# sourceMappingURL=changelog.js.map

package/dist/tools/changelog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/tools/changelog.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  changelogBody,\n  changelogOf,\n  isRecorded,\n  promotionOf,\n  selectByShape,\n  whyNotWhole,\n  type ChangelogSelection,\n  type ObservationRecord,\n  type RunReport,\n} from '@variance-authority/report';\nimport type { Tool } from './tool.js';\n\n/**\n * `variance_changelog` — what the baseline update would say, before it is made.\n *\n * Every other tool here answers *what changed*. This one answers *what would be\n * written down about it*, and the difference matters because of where that\n * writing goes: a baseline update is explained in the commit that carries it or\n * in a review database, and both are written at the moment of acceptance and\n * never again. An agent that runs `accept` without knowing what the record will\n * say has already written it.\n *\n * ## Why it previews rather than proposes prose\n *\n * The answer is not this tool's phrasing of the change. It is the lines the\n * commit will actually carry, rendered by the same function that renders them\n * into the commit — `changelogBody` over a record from `changelogOf`. A tool\n * that wrote its own summary would be a second account of a baseline update,\n * edited separately from the first, and the two would disagree in the direction\n * that matters: the one an agent read would not be the one that survived.\n *\n * The subject set is chosen by the same rules `accept` applies, for the same\n * reason. `promotionOf` refuses an unstable subject and a subject the run left\n * no image for; a preview that counted those would promise entries the command\n * then refuses by name, which is worse than not previewing at all.\n *\n * ## What it deliberately does not do\n *\n * It does not render the trailers. Those are the record — versioned, encoded,\n * append-only once committed — and a record exists when somebody accepted\n * something. A trailer an agent could copy out of a preview is a record of a\n * promotion that never happened, which is the one artifact this whole mechanism\n * is arranged to prevent.\n *\n * It reads no clock. The instant a record carries is the instant of acceptance,\n * and acceptance happens in another process, later, possibly not at all.\n */\n\nexport const changelog: Tool = {\n  name: 'variance_changelog',\n  description:\n    'Preview what accepting this run would write into the baseline changelog: the same lines ' +\n    'the commit message will carry, the subjects that would land in it, and the subjects that ' +\n    'would be refused and why. Takes the same selection as `variance accept` — a shape, named ' +\n    'subjects, or everything. Ask this before proposing an accept command; the record is ' +\n    'written once, at acceptance, and is the only explanation of the baseline that outlives ' +\n    'the run.',\n  inputSchema: {\n    type: 'object',\n    properties: {\n      shape: {\n        type: 'string',\n        description:\n          'Optional. A shape digest from `variance_changes`. Previews `accept --shape`, which ' +\n          'takes the subjects this shape wholly explains and refuses the rest by name.',\n      },\n      subjects: {\n        type: 'array',\n        items: { type: 'string' },\n        description: 'Optional. Subject ids, as `accept` would take them by name.',\n      },\n    },\n    additionalProperties: false,\n  },\n\n  run(report, input) {\n    const shape = typeof input['shape'] === 'string' ? input['shape'] : undefined;\n    const named = Array.isArray(input['subjects'])\n      ? input['subjects'].filter((value): value is string => typeof value === 'string')\n      : undefined;\n\n    if (shape !== undefined && named !== undefined && named.length > 0) {\n      // Refused rather than resolved by precedence. These are two different\n      // commands, and picking one silently would preview an update the agent did\n      // not ask about and then hand it a command that performs the other.\n      return (\n        'Ask for one selection at a time: a shape, or subjects by name. They are two ' +\n        'different accept commands and this would preview one while naming the other.'\n      );\n    }\n\n    const selection: ChangelogSelection =\n      shape !== undefined ? 'shape' : named !== undefined && named.length > 0 ? 'named' : 'all';\n\n    const chosen = select(report, shape, named);\n    if (typeof chosen === 'string') return chosen;\n\n    const promotable: string[] = [];\n    const refused: { readonly subject: string; readonly because: string }[] = [...chosen.refused];\n    let alreadyBaseline = 0;\n\n    for (const observation of chosen.targets) {\n      const promotion = promotionOf(observation);\n      if (promotion.kind === 'promotable') promotable.push(observation.subject);\n      else if (promotion.kind === 'already-baseline') alreadyBaseline += 1;\n      else refused.push({ subject: observation.subject, because: promotion.because });\n    }\n\n    const record = changelogOf({\n      report,\n      accepted: promotable,\n      selection,\n      // The run's own instant, never this process's. A record is stamped when\n      // somebody accepts, in another process; a clock read here would put a time\n      // in a preview that the record will not carry.\n      at: report.at,\n    });\n\n    if (!isRecorded(record)) {\n      return [\n        `Nothing would be recorded: ${record.because}.`,\n        ...(refused.length > 0\n          ? ['', `Refused (${String(refused.length)}):`, ...refused.map(line)]\n          : []),\n        ...(alreadyBaseline > 0\n          ? ['', `${String(alreadyBaseline)} subject(s) already are the baseline.`]\n          : []),\n      ].join('\\n');\n    }\n\n    const unshaped = promotable.filter((subject) => !inRecord(record.entries, subject));\n\n    return [\n      `Accepting this would record ${String(record.entries.length)} change(s) across ` +\n        `${String(promotable.length)} subject(s). These are the lines the commit will carry:`,\n      '',\n      ...changelogBody(record),\n      '',\n      `  ${command(selection, shape, promotable)}`,\n      ...(unshaped.length > 0\n        ? [\n            '',\n            `Promoted but not described (${String(unshaped.length)}): ${unshaped.join(', ')}`,\n            '  The run named no difference shape in these, so the record counts them and ' +\n              'cannot say what changed in them. Nothing later can recover it.',\n          ]\n        : []),\n      ...(refused.length > 0\n        ? ['', `Refused, and absent from the record (${String(refused.length)}):`, ...refused.map(line)]\n        : []),\n      ...(alreadyBaseline > 0\n        ? ['', `${String(alreadyBaseline)} subject(s) already are the baseline and record nothing.`]\n        : []),\n    ].join('\\n');\n  },\n};\n\n/**\n * The subjects the named selection reaches, or the sentence saying it reaches none.\n *\n * `--shape` carries its own refusals — the subjects where the shape is present\n * beside something else — and they are part of the preview rather than a detail\n * of the command, because they are the part of the change this update would\n * leave in the suite.\n */\nfunction select(\n  report: RunReport,\n  shape: string | undefined,\n  named: readonly string[] | undefined,\n):\n  | string\n  | {\n      readonly targets: readonly ObservationRecord[];\n      readonly refused: readonly { readonly subject: string; readonly because: string }[];\n    } {\n  if (shape !== undefined) {\n    const selected = selectByShape(report.observations, new Set([shape]));\n    if (selected.whole.length === 0 && selected.partial.length === 0) {\n      return (\n        `The shape ${shape} appears in no region of this run. A fingerprint is copied from a ` +\n        'region in a report; check it came from this one.'\n      );\n    }\n    return {\n      targets: selected.whole,\n      refused: selected.partial.map((observation) => ({\n        subject: observation.subject,\n        because: whyNotWhole(observation),\n      })),\n    };\n  }\n\n  if (named !== undefined && named.length > 0) {\n    const targets: ObservationRecord[] = [];\n    const missing: string[] = [];\n\n    for (const subject of named) {\n      const found = report.observations.find((entry) => entry.subject === subject);\n      if (found === undefined) missing.push(subject);\n      else targets.push(found);\n    }\n\n    if (targets.length === 0) {\n      return `None of those subjects are in this run: ${missing.join(', ')}.`;\n    }\n\n    return {\n      targets,\n      refused: missing.map((subject) => ({\n        subject,\n        because: 'this run has no observation for it, so `accept` would refuse the command',\n      })),\n    };\n  }\n\n  return { targets: report.observations, refused: [] };\n}\n\n/**\n * The command that writes it, spelled out.\n *\n * `--message-file` is on every one of them. The message is where the record\n * goes, and an accept run without it promotes the images and explains nothing —\n * which is the state this tool exists to make visible before it happens.\n */\nfunction command(\n  selection: ChangelogSelection,\n  shape: string | undefined,\n  promotable: readonly string[],\n): string {\n  const how =\n    selection === 'shape'\n      ? `--shape ${shape ?? ''}`\n      : selection === 'named'\n        ? promotable.map((subject) => `\"${subject}\"`).join(' ')\n        : '--all';\n\n  return `variance accept ${how} --message-file .variance/commit-message.txt`;\n}\n\nfunction inRecord(\n  entries: readonly { readonly subjects: readonly string[] }[],\n  subject: string,\n): boolean {\n  return entries.some((entry) => entry.subjects.includes(subject));\n}\n\nfunction line(refusal: { readonly subject: string; readonly because: string }): string {\n  return `  ${refusal.subject} — ${refusal.because}`;\n}\n"]}