@variance-authority/mcp 0.1.0

package/dist/tools/run-signals.js

@@ -0,0 +1,115 @@
+import { heading, tally, unattached } from './vantage-lines.js';
+/**
+ * What the suite is doing, right now.
+ *
+ * The listing an agent reads before it asks about one test. Ordered as the run
+ * opened them, because the useful reading of a suite in flight is chronological
+ * — the test that is hanging is the last one with an arrow next to it — and
+ * newest-first would put the answer at the top and the story in reverse.
+ */
+export const runSignals = {
+    name: 'variance_run_signals',
+    description: 'What the running test suite is doing now: every test that has reported, its state, and how much each has announced. Not limited to visual tests.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            state: {
+                type: 'string',
+                enum: ['running', 'passed', 'failed', 'timedOut', 'skipped', 'interrupted'],
+                description: 'Show only tests in this state.',
+            },
+            file: { type: 'string', description: 'Show only tests whose spec file contains this.' },
+            limit: {
+                type: 'integer',
+                minimum: 1,
+                description: 'How many of the most recent to list. Defaults to 50.',
+            },
+        },
+        additionalProperties: false,
+    },
+    run(state, input) {
+        if (state.tests.length === 0)
+            return unattached(state);
+        const wanted = stateArg(input);
+        const file = fileArg(input);
+        const matching = state.tests.filter((test) => (wanted === undefined || test.state === wanted) &&
+            (file === undefined || test.file.includes(file)));
+        if (matching.length === 0)
+            return nothingMatched(state, wanted, file);
+        const limit = limitArg(input);
+        const shown = matching.slice(Math.max(0, matching.length - limit));
+        const elided = matching.length - shown.length;
+        return [
+            summary(state, matching),
+            '',
+            ...shown.map(row),
+            ...(elided === 0 ? [] : ['', `… ${elided} earlier match(es) not listed; raise \`limit\`.`]),
+            ...(state.forgotten === 0
+                ? []
+                : ['', `${state.forgotten} earlier test(s) were dropped to keep this watcher bounded.`]),
+        ].join('\n');
+    },
+};
+function summary(state, matching) {
+    const counted = new Map();
+    for (const test of matching)
+        counted.set(test.state, (counted.get(test.state) ?? 0) + 1);
+    const breakdown = [...counted]
+        .sort((left, right) => right[1] - left[1])
+        .map(([one, count]) => `${count} ${one}`)
+        .join(', ');
+    const where = state.address === undefined ? '' : ` at ${state.address}`;
+    return `${matching.length} test(s)${where} — ${breakdown}.`;
+}
+function row(test) {
+    const mark = test.state === 'running' ? '▸' : ' ';
+    const lines = [`${mark} ${test.state.padEnd(11)} ${heading(test)} — ${tally(test)}`];
+    if (test.error !== undefined) {
+        lines.push(...test.error.split('\n').map((line) => `      ${line}`));
+    }
+    return lines.join('\n');
+}
+function nothingMatched(state, wanted, file) {
+    const asked = [
+        ...(wanted === undefined ? [] : [`state ${wanted}`]),
+        ...(file === undefined ? [] : [`file containing ${file}`]),
+    ].join(' and ');
+    const states = [...new Set(state.tests.map((test) => test.state))].sort().join(', ');
+    return `No test here matches ${asked}. ${state.tests.length} test(s) have reported, in: ${states}.`;
+}
+const STATES = new Set([
+    'running',
+    'passed',
+    'failed',
+    'timedOut',
+    'skipped',
+    'interrupted',
+]);
+function stateArg(input) {
+    const value = input['state'];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !STATES.has(value)) {
+        throw new Error(`\`state\` must be one of: ${[...STATES].join(', ')}`);
+    }
+    return value;
+}
+function fileArg(input) {
+    const value = input['file'];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value === '') {
+        throw new Error('`file` must be a non-empty string');
+    }
+    return value;
+}
+function limitArg(input) {
+    const value = input['limit'];
+    if (value === undefined)
+        return 50;
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error('`limit` must be a positive integer');
+    }
+    return value;
+}
+//# sourceMappingURL=run-signals.js.map

package/dist/tools/run-signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-signals.js","sourceRoot":"","sources":["../../src/tools/run-signals.ts"],"names":[],"mappings":"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","sourcesContent":["import type { TestState, VantageState, WatchedTest } from '@variance-authority/vantage';\nimport { heading, tally, unattached } from './vantage-lines.js';\nimport type { Tool } from './tool.js';\n\n/**\n * What the suite is doing, right now.\n *\n * The listing an agent reads before it asks about one test. Ordered as the run\n * opened them, because the useful reading of a suite in flight is chronological\n * — the test that is hanging is the last one with an arrow next to it — and\n * newest-first would put the answer at the top and the story in reverse.\n */\nexport const runSignals: Tool<VantageState> = {\n  name: 'variance_run_signals',\n  description:\n    'What the running test suite is doing now: every test that has reported, its state, and how much each has announced. Not limited to visual tests.',\n  inputSchema: {\n    type: 'object',\n    properties: {\n      state: {\n        type: 'string',\n        enum: ['running', 'passed', 'failed', 'timedOut', 'skipped', 'interrupted'],\n        description: 'Show only tests in this state.',\n      },\n      file: { type: 'string', description: 'Show only tests whose spec file contains this.' },\n      limit: {\n        type: 'integer',\n        minimum: 1,\n        description: 'How many of the most recent to list. Defaults to 50.',\n      },\n    },\n    additionalProperties: false,\n  },\n  run(state, input) {\n    if (state.tests.length === 0) return unattached(state);\n\n    const wanted = stateArg(input);\n    const file = fileArg(input);\n    const matching = state.tests.filter(\n      (test) =>\n        (wanted === undefined || test.state === wanted) &&\n        (file === undefined || test.file.includes(file)),\n    );\n    if (matching.length === 0) return nothingMatched(state, wanted, file);\n\n    const limit = limitArg(input);\n    const shown = matching.slice(Math.max(0, matching.length - limit));\n    const elided = matching.length - shown.length;\n\n    return [\n      summary(state, matching),\n      '',\n      ...shown.map(row),\n      ...(elided === 0 ? [] : ['', `… ${elided} earlier match(es) not listed; raise \\`limit\\`.`]),\n      ...(state.forgotten === 0\n        ? []\n        : ['', `${state.forgotten} earlier test(s) were dropped to keep this watcher bounded.`]),\n    ].join('\\n');\n  },\n};\n\nfunction summary(state: VantageState, matching: readonly WatchedTest[]): string {\n  const counted = new Map<TestState, number>();\n  for (const test of matching) counted.set(test.state, (counted.get(test.state) ?? 0) + 1);\n  const breakdown = [...counted]\n    .sort((left, right) => right[1] - left[1])\n    .map(([one, count]) => `${count} ${one}`)\n    .join(', ');\n  const where = state.address === undefined ? '' : ` at ${state.address}`;\n  return `${matching.length} test(s)${where} — ${breakdown}.`;\n}\n\nfunction row(test: WatchedTest): string {\n  const mark = test.state === 'running' ? '▸' : ' ';\n  const lines = [`${mark} ${test.state.padEnd(11)} ${heading(test)} — ${tally(test)}`];\n  if (test.error !== undefined) {\n    lines.push(...test.error.split('\\n').map((line) => `      ${line}`));\n  }\n  return lines.join('\\n');\n}\n\nfunction nothingMatched(\n  state: VantageState,\n  wanted: TestState | undefined,\n  file: string | undefined,\n): string {\n  const asked = [\n    ...(wanted === undefined ? [] : [`state ${wanted}`]),\n    ...(file === undefined ? [] : [`file containing ${file}`]),\n  ].join(' and ');\n  const states = [...new Set(state.tests.map((test) => test.state))].sort().join(', ');\n  return `No test here matches ${asked}. ${state.tests.length} test(s) have reported, in: ${states}.`;\n}\n\nconst STATES = new Set<string>([\n  'running',\n  'passed',\n  'failed',\n  'timedOut',\n  'skipped',\n  'interrupted',\n]);\n\nfunction stateArg(input: Readonly<Record<string, unknown>>): TestState | undefined {\n  const value = input['state'];\n  if (value === undefined) return undefined;\n  if (typeof value !== 'string' || !STATES.has(value)) {\n    throw new Error(`\\`state\\` must be one of: ${[...STATES].join(', ')}`);\n  }\n  return value as TestState;\n}\n\nfunction fileArg(input: Readonly<Record<string, unknown>>): string | undefined {\n  const value = input['file'];\n  if (value === undefined) return undefined;\n  if (typeof value !== 'string' || value === '') {\n    throw new Error('`file` must be a non-empty string');\n  }\n  return value;\n}\n\nfunction limitArg(input: Readonly<Record<string, unknown>>): number {\n  const value = input['limit'];\n  if (value === undefined) return 50;\n  if (!Number.isInteger(value) || (value as number) < 1) {\n    throw new Error('`limit` must be a positive integer');\n  }\n  return value as number;\n}\n"]}

package/dist/tools/scenarios.d.ts

@@ -0,0 +1,6 @@
+import type { ScenarioArchiveManifest } from '@variance-authority/scenario/archive';
+import { type Tool } from './tool.js';
+export type ScenarioEvidence = readonly ScenarioArchiveManifest[];
+/** Witnessed Arrange states and authored Act outcomes from retained scenario manifests. */
+export declare const scenarios: Tool<ScenarioEvidence>;
+//# sourceMappingURL=scenarios.d.ts.map

package/dist/tools/scenarios.js

@@ -0,0 +1,62 @@
+import { stringArg } from './tool.js';
+/** Witnessed Arrange states and authored Act outcomes from retained scenario manifests. */
+export const scenarios = {
+    name: 'variance_scenarios',
+    description: 'List retained runtime scenarios, or show one witnessed Arrange state and each authored Act outcome without inventing missing frames.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            scenario: { type: 'string', description: 'Scenario id.' },
+            execution: { type: 'string', description: 'Optional execution id when a scenario has several.' },
+        },
+        additionalProperties: false,
+    },
+    run(manifests, input) {
+        if (input['scenario'] === undefined)
+            return listing(manifests);
+        const scenario = stringArg(input, 'scenario');
+        const execution = input['execution'] === undefined ? undefined : stringArg(input, 'execution');
+        const candidates = manifests.filter((manifest) => manifest.definition.id === scenario &&
+            (execution === undefined || manifest.execution.id === execution));
+        if (candidates.length === 0)
+            return `No retained scenario matches ${scenario}${execution === undefined ? '' : ` / ${execution}`}.`;
+        if (candidates.length > 1) {
+            return `${candidates.length} executions match ${scenario}; choose one:\n${candidates.map((manifest) => `  ${manifest.execution.id}`).join('\n')}`;
+        }
+        return describe(candidates[0]);
+    },
+};
+function listing(manifests) {
+    if (manifests.length === 0)
+        return 'The scenario archive contains no manifests.';
+    return [
+        `${manifests.length} retained scenario execution(s):`,
+        ...manifests.map((manifest) => `  ${manifest.definition.id} / ${manifest.execution.id} — Arrange ${manifest.execution.precondition.id}, ${Math.max(0, manifest.execution.frames.length - 1)} Act frame(s)`),
+    ].join('\n');
+}
+function describe(manifest) {
+    const execution = manifest.execution;
+    const frames = execution.frames.map((frame) => {
+        const name = frame.at === 0
+            ? `Arrange ${execution.precondition.id}`
+            : `Act ${frame.act?.key ?? 'missing identity'} #${frame.act?.occurrence ?? '?'}`;
+        if (frame.outcome.kind === 'observed')
+            return `  ${frame.at}. ${name} → observed state ${frame.outcome.state}`;
+        return `  ${frame.at}. ${name} → unobserved: ${frame.outcome.diagnostics.map((diagnostic) => diagnostic.message).join('; ')}`;
+    });
+    return [
+        `${manifest.definition.id} / ${execution.id}`,
+        `Profile: ${execution.profile}. Retained until ${manifest.retainUntil}.`,
+        execution.preconditionLink === undefined
+            ? 'Arrange relation: not supplied.'
+            : execution.preconditionLink.kind === 'resolved'
+                ? `Arrange relation: ${execution.preconditionLink.how} parent ${execution.preconditionLink.parent}.`
+                : `Arrange relation: unresolved — ${execution.preconditionLink.because}`,
+        '',
+        ...frames,
+        ...(execution.termination === undefined
+            ? []
+            : ['', `Witnessed prefix ended: ${execution.termination.map((diagnostic) => diagnostic.message).join('; ')}`]),
+    ].join('\n');
+}
+//# sourceMappingURL=scenarios.js.map

package/dist/tools/scenarios.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenarios.js","sourceRoot":"","sources":["../../src/tools/scenarios.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ScenarioArchiveManifest } from '@variance-authority/scenario/archive';\nimport { stringArg, type Tool } from './tool.js';\n\nexport type ScenarioEvidence = readonly ScenarioArchiveManifest[];\n\n/** Witnessed Arrange states and authored Act outcomes from retained scenario manifests. */\nexport const scenarios: Tool<ScenarioEvidence> = {\n  name: 'variance_scenarios',\n  description:\n    'List retained runtime scenarios, or show one witnessed Arrange state and each authored Act outcome without inventing missing frames.',\n  inputSchema: {\n    type: 'object',\n    properties: {\n      scenario: { type: 'string', description: 'Scenario id.' },\n      execution: { type: 'string', description: 'Optional execution id when a scenario has several.' },\n    },\n    additionalProperties: false,\n  },\n  run(manifests, input) {\n    if (input['scenario'] === undefined) return listing(manifests);\n    const scenario = stringArg(input, 'scenario');\n    const execution = input['execution'] === undefined ? undefined : stringArg(input, 'execution');\n    const candidates = manifests.filter((manifest) =>\n      manifest.definition.id === scenario &&\n      (execution === undefined || manifest.execution.id === execution));\n    if (candidates.length === 0) return `No retained scenario matches ${scenario}${execution === undefined ? '' : ` / ${execution}`}.`;\n    if (candidates.length > 1) {\n      return `${candidates.length} executions match ${scenario}; choose one:\\n${candidates.map((manifest) => `  ${manifest.execution.id}`).join('\\n')}`;\n    }\n    return describe(candidates[0]!);\n  },\n};\n\nfunction listing(manifests: ScenarioEvidence): string {\n  if (manifests.length === 0) return 'The scenario archive contains no manifests.';\n  return [\n    `${manifests.length} retained scenario execution(s):`,\n    ...manifests.map((manifest) =>\n      `  ${manifest.definition.id} / ${manifest.execution.id} — Arrange ${manifest.execution.precondition.id}, ${Math.max(0, manifest.execution.frames.length - 1)} Act frame(s)`),\n  ].join('\\n');\n}\n\nfunction describe(manifest: ScenarioArchiveManifest): string {\n  const execution = manifest.execution;\n  const frames = execution.frames.map((frame) => {\n    const name = frame.at === 0\n      ? `Arrange ${execution.precondition.id}`\n      : `Act ${frame.act?.key ?? 'missing identity'} #${frame.act?.occurrence ?? '?'}`;\n    if (frame.outcome.kind === 'observed') return `  ${frame.at}. ${name} → observed state ${frame.outcome.state}`;\n    return `  ${frame.at}. ${name} → unobserved: ${frame.outcome.diagnostics.map((diagnostic) => diagnostic.message).join('; ')}`;\n  });\n  return [\n    `${manifest.definition.id} / ${execution.id}`,\n    `Profile: ${execution.profile}. Retained until ${manifest.retainUntil}.`,\n    execution.preconditionLink === undefined\n      ? 'Arrange relation: not supplied.'\n      : execution.preconditionLink.kind === 'resolved'\n        ? `Arrange relation: ${execution.preconditionLink.how} parent ${execution.preconditionLink.parent}.`\n        : `Arrange relation: unresolved — ${execution.preconditionLink.because}`,\n    '',\n    ...frames,\n    ...(execution.termination === undefined\n      ? []\n      : ['', `Witnessed prefix ended: ${execution.termination.map((diagnostic) => diagnostic.message).join('; ')}`]),\n  ].join('\\n');\n}\n"]}

package/dist/tools/source-tests.d.ts

@@ -0,0 +1,5 @@
+import { type ExecutionIndex } from '@variance-authority/sense/test-selection';
+import { type Tool } from './tool.js';
+/** Named tests that reached one source file, line, or function. */
+export declare const sourceTests: Tool<ExecutionIndex>;
+//# sourceMappingURL=source-tests.d.ts.map

package/dist/tools/source-tests.js

@@ -0,0 +1,95 @@
+import { coveringTests, coveringTestsInFile, } from '@variance-authority/sense/test-selection';
+import { stringArg } from './tool.js';
+/** Named tests that reached one source file, line, or function. */
+export const sourceTests = {
+    name: 'variance_source_tests',
+    description: 'Find named tests that reached a source file, line, or function, ranked by observed call-stack depth.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file: { type: 'string', description: 'Repository-relative source file.' },
+            line: { type: 'integer', minimum: 1, description: 'Optional one-based source line.' },
+            function: { type: 'string', description: 'Optional exact indexed function name.' },
+        },
+        required: ['file'],
+        additionalProperties: false,
+    },
+    run(index, input) {
+        const file = stringArg(input, 'file');
+        const line = optionalLine(input);
+        const functionName = optionalFunction(input);
+        if (line !== undefined && functionName !== undefined) {
+            throw new Error('`line` and `function` are alternatives; provide at most one');
+        }
+        const module = index.modules.find((candidate) => candidate.file === file);
+        if (module === undefined)
+            return unknownFile(index, file);
+        if (line !== undefined) {
+            if (!module.blocks.some((block) => block.source && block.startLine <= line && line <= block.endLine))
+                return `Line ${line} is not indexed in ${file}.`;
+            return focused(file, `line ${line}`, coveringTests(index, { file, line }));
+        }
+        if (functionName !== undefined) {
+            if (!module.blocks.some((block) => block.source && block.kind === 'function' && block.name === functionName))
+                return `Function ${functionName} is not indexed in ${file}.`;
+            return focused(file, `function ${functionName}`, coveringTests(index, {
+                file,
+                function: functionName,
+            }));
+        }
+        return wholeFile(index, file);
+    },
+};
+function optionalLine(input) {
+    const value = input['line'];
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error('`line` must be a positive integer');
+    }
+    return value;
+}
+function optionalFunction(input) {
+    if (input['function'] === undefined)
+        return undefined;
+    return stringArg(input, 'function');
+}
+function focused(file, target, tests) {
+    if (tests.length === 0)
+        return `No named test reached ${target} in ${file}.`;
+    return [
+        `${tests.length} named test(s) reached ${target} in ${file}:`,
+        ...tests.map(formatTest),
+    ].join('\n');
+}
+function wholeFile(index, file) {
+    const ranges = coveringTestsInFile(index, file);
+    if (ranges.length === 0)
+        return `No source lines are indexed for ${file}.`;
+    const identities = new Set(ranges.flatMap((range) => range.tests.map((test) => test.id)));
+    const lines = [
+        `${file} — ${ranges.length} source range(s), ${identities.size} named test(s)`,
+    ];
+    for (const range of ranges) {
+        lines.push(range.startLine === range.endLine
+            ? `line ${range.startLine}`
+            : `lines ${range.startLine}-${range.endLine}`);
+        lines.push(...(range.tests.length === 0
+            ? ['  no named test reached this range']
+            : range.tests.map((test) => `  ${formatTest(test)}`)));
+    }
+    return lines.join('\n');
+}
+function formatTest(test) {
+    return `depth ${test.distance} — ${test.name} — ${test.file} [${test.id}]`;
+}
+function unknownFile(index, file) {
+    const files = index.modules.map((module) => module.file).sort(codeUnitOrder);
+    return files.length === 0
+        ? `Unknown source file: ${file}. The execution index contains no source files.`
+        : `Unknown source file: ${file}. Indexed files:\n${files.map((candidate) => `  ${candidate}`).join('\n')}`;
+}
+function codeUnitOrder(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+//# sourceMappingURL=source-tests.js.map

package/dist/tools/source-tests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-tests.js","sourceRoot":"","sources":["../../src/tools/source-tests.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,mBAAmB,GAGpB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,SAAS,EAAa,MAAM,WAAW,CAAC;AAEjD,mEAAmE;AACnE,MAAM,CAAC,MAAM,WAAW,GAAyB;IAC/C,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EACT,sGAAsG;IACxG,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kCAAkC,EAAE;YACzE,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,iCAAiC,EAAE;YACrF,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,uCAAuC,EAAE;SACnF;QACD,QAAQ,EAAE,CAAC,MAAM,CAAC;QAClB,oBAAoB,EAAE,KAAK;KAC5B;IACD,GAAG,CAAC,KAAK,EAAE,KAAK;QACd,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,YAAY,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,IAAI,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACjF,CAAC;QAED,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QAC1E,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC1D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAChC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,CAAC,OAAO,CACjE;gBAAE,OAAO,QAAQ,IAAI,sBAAsB,IAAI,GAAG,CAAC;YACpD,OAAO,OAAO,CAAC,IAAI,EAAE,QAAQ,IAAI,EAAE,EAAE,aAAa,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC7E,CAAC;QACD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAChC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CACzE;gBAAE,OAAO,YAAY,YAAY,sBAAsB,IAAI,GAAG,CAAC;YAChE,OAAO,OAAO,CAAC,IAAI,EAAE,YAAY,YAAY,EAAE,EAAE,aAAa,CAAC,KAAK,EAAE;gBACpE,IAAI;gBACJ,QAAQ,EAAE,YAAY;aACvB,CAAC,CAAC,CAAC;QACN,CAAC;QACD,OAAO,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;CACF,CAAC;AAEF,SAAS,YAAY,CAAC,KAAwC;IAC5D,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAK,KAAgB,GAAG,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,KAAe,CAAC;AACzB,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAwC;IAChE,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACtD,OAAO,SAAS,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,OAAO,CAAC,IAAY,EAAE,MAAc,EAAE,KAA8B;IAC3E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,yBAAyB,MAAM,OAAO,IAAI,GAAG,CAAC;IAC7E,OAAO;QACL,GAAG,KAAK,CAAC,MAAM,0BAA0B,MAAM,OAAO,IAAI,GAAG;QAC7D,GAAG,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC;KACzB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAAC,KAAqB,EAAE,IAAY;IACpD,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAChD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,mCAAmC,IAAI,GAAG,CAAC;IAC3E,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1F,MAAM,KAAK,GAAG;QACZ,GAAG,IAAI,MAAM,MAAM,CAAC,MAAM,qBAAqB,UAAU,CAAC,IAAI,gBAAgB;KAC/E,CAAC;IACF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,OAAO;YAC1C,CAAC,CAAC,QAAQ,KAAK,CAAC,SAAS,EAAE;YAC3B,CAAC,CAAC,SAAS,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACjD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YACrC,CAAC,CAAC,CAAC,oCAAoC,CAAC;YACxC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,UAAU,CAAC,IAAkB;IACpC,OAAO,SAAS,IAAI,CAAC,QAAQ,MAAM,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,GAAG,CAAC;AAC7E,CAAC;AAED,SAAS,WAAW,CAAC,KAAqB,EAAE,IAAY;IACtD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC7E,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;QACvB,CAAC,CAAC,wBAAwB,IAAI,iDAAiD;QAC/E,CAAC,CAAC,wBAAwB,IAAI,qBAAqB,KAAK,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,KAAK,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC/G,CAAC;AAED,SAAS,aAAa,CAAC,IAAY,EAAE,KAAa;IAChD,OAAO,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC","sourcesContent":["import {\n  coveringTests,\n  coveringTestsInFile,\n  type CoveringTest,\n  type ExecutionIndex,\n} from '@variance-authority/sense/test-selection';\nimport { stringArg, type Tool } from './tool.js';\n\n/** Named tests that reached one source file, line, or function. */\nexport const sourceTests: Tool<ExecutionIndex> = {\n  name: 'variance_source_tests',\n  description:\n    'Find named tests that reached a source file, line, or function, ranked by observed call-stack depth.',\n  inputSchema: {\n    type: 'object',\n    properties: {\n      file: { type: 'string', description: 'Repository-relative source file.' },\n      line: { type: 'integer', minimum: 1, description: 'Optional one-based source line.' },\n      function: { type: 'string', description: 'Optional exact indexed function name.' },\n    },\n    required: ['file'],\n    additionalProperties: false,\n  },\n  run(index, input) {\n    const file = stringArg(input, 'file');\n    const line = optionalLine(input);\n    const functionName = optionalFunction(input);\n    if (line !== undefined && functionName !== undefined) {\n      throw new Error('`line` and `function` are alternatives; provide at most one');\n    }\n\n    const module = index.modules.find((candidate) => candidate.file === file);\n    if (module === undefined) return unknownFile(index, file);\n    if (line !== undefined) {\n      if (!module.blocks.some((block) =>\n        block.source && block.startLine <= line && line <= block.endLine,\n      )) return `Line ${line} is not indexed in ${file}.`;\n      return focused(file, `line ${line}`, coveringTests(index, { file, line }));\n    }\n    if (functionName !== undefined) {\n      if (!module.blocks.some((block) =>\n        block.source && block.kind === 'function' && block.name === functionName,\n      )) return `Function ${functionName} is not indexed in ${file}.`;\n      return focused(file, `function ${functionName}`, coveringTests(index, {\n        file,\n        function: functionName,\n      }));\n    }\n    return wholeFile(index, file);\n  },\n};\n\nfunction optionalLine(input: Readonly<Record<string, unknown>>): number | undefined {\n  const value = input['line'];\n  if (value === undefined) return undefined;\n  if (!Number.isInteger(value) || (value as number) < 1) {\n    throw new Error('`line` must be a positive integer');\n  }\n  return value as number;\n}\n\nfunction optionalFunction(input: Readonly<Record<string, unknown>>): string | undefined {\n  if (input['function'] === undefined) return undefined;\n  return stringArg(input, 'function');\n}\n\nfunction focused(file: string, target: string, tests: readonly CoveringTest[]): string {\n  if (tests.length === 0) return `No named test reached ${target} in ${file}.`;\n  return [\n    `${tests.length} named test(s) reached ${target} in ${file}:`,\n    ...tests.map(formatTest),\n  ].join('\\n');\n}\n\nfunction wholeFile(index: ExecutionIndex, file: string): string {\n  const ranges = coveringTestsInFile(index, file);\n  if (ranges.length === 0) return `No source lines are indexed for ${file}.`;\n  const identities = new Set(ranges.flatMap((range) => range.tests.map((test) => test.id)));\n  const lines = [\n    `${file} — ${ranges.length} source range(s), ${identities.size} named test(s)`,\n  ];\n  for (const range of ranges) {\n    lines.push(range.startLine === range.endLine\n      ? `line ${range.startLine}`\n      : `lines ${range.startLine}-${range.endLine}`);\n    lines.push(...(range.tests.length === 0\n      ? ['  no named test reached this range']\n      : range.tests.map((test) => `  ${formatTest(test)}`)));\n  }\n  return lines.join('\\n');\n}\n\nfunction formatTest(test: CoveringTest): string {\n  return `depth ${test.distance} — ${test.name} — ${test.file} [${test.id}]`;\n}\n\nfunction unknownFile(index: ExecutionIndex, file: string): string {\n  const files = index.modules.map((module) => module.file).sort(codeUnitOrder);\n  return files.length === 0\n    ? `Unknown source file: ${file}. The execution index contains no source files.`\n    : `Unknown source file: ${file}. Indexed files:\\n${files.map((candidate) => `  ${candidate}`).join('\\n')}`;\n}\n\nfunction codeUnitOrder(left: string, right: string): number {\n  return left < right ? -1 : left > right ? 1 : 0;\n}\n"]}

package/dist/tools/subject.d.ts

@@ -0,0 +1,45 @@
+import type { NotObserved, ObservationRecord, RunReport } from '@variance-authority/report';
+/**
+ * Naming a subject, and what to say when the run has nothing to say about it.
+ *
+ * Shared by the two tools an agent points at a single subject — `variance_describe`
+ * and `variance_explain_verdict` — and separate from both because the decision
+ * encoded here belongs to neither. A subject the run planned and could not see
+ * has to be answered rather than refused, and a lookup that returns `undefined`
+ * leaves each caller free to forget that on its own schedule.
+ */
+/**
+ * A subject named in the run, and which of the two lists it came from.
+ *
+ * A union rather than `ObservationRecord | undefined` so that "the run did not
+ * observe this" cannot be handled by accident. Every caller has to decide what to
+ * say about a subject with no observation, and the answer is never a verdict.
+ */
+export type Located = {
+    readonly observed: true;
+    readonly observation: ObservationRecord;
+} | {
+    readonly observed: false;
+    readonly entry: NotObserved;
+};
+export declare function subjectOf(report: RunReport, input: Readonly<Record<string, unknown>>): Located;
+/**
+ * What to say about a subject with no observation — the CLI's wording, verbatim.
+ *
+ * Duplicated text rather than a shared helper only because the packages point the
+ * other way round, and the duplication is deliberate where drift would be worst:
+ * a human running `variance report --subject x` and an agent calling
+ * `variance_describe` on the same subject must be told the same thing, or the two
+ * of them will argue about a run neither can re-observe.
+ */
+export declare function unobserved(entry: NotObserved): string;
+/**
+ * What the reader should do about a subject nobody looked at.
+ *
+ * One sentence per kind, and the three are different instructions. `failed` is
+ * work; `excluded` is a decision already on the record; `unreached` is the run
+ * having proved the change cannot arrive here, which is the only one of the
+ * three that is evidence rather than an absence of it.
+ */
+export declare function notObservedSentence(kind: NotObserved['kind']): string;
+//# sourceMappingURL=subject.d.ts.map

package/dist/tools/subject.js

@@ -0,0 +1,57 @@
+import { stringArg } from './tool.js';
+export function subjectOf(report, input) {
+    const subject = stringArg(input, 'subject');
+    const observation = report.observations.find((entry) => entry.subject === subject);
+    if (observation !== undefined)
+        return { observed: true, observation };
+    // The coverage list is searched too, and this is the point of it. A subject the
+    // run planned and could not see is a subject an agent will ask about; refusing
+    // the name tells it the subject does not exist, which is both false and the
+    // conclusion that ends the investigation.
+    const skipped = report.notObserved?.find((entry) => entry.subject === subject);
+    if (skipped !== undefined)
+        return { observed: false, entry: skipped };
+    // Listing the alternatives rather than only refusing: an agent that gets
+    // "unknown subject" retries with another guess, and an agent that gets the
+    // list picks the right one.
+    throw new Error(`unknown subject "${subject}"; this run has: ` +
+        [
+            ...report.observations.map((entry) => entry.subject),
+            ...(report.notObserved ?? []).map((entry) => entry.subject),
+        ].join(', '));
+}
+/**
+ * What to say about a subject with no observation — the CLI's wording, verbatim.
+ *
+ * Duplicated text rather than a shared helper only because the packages point the
+ * other way round, and the duplication is deliberate where drift would be worst:
+ * a human running `variance report --subject x` and an agent calling
+ * `variance_describe` on the same subject must be told the same thing, or the two
+ * of them will argue about a run neither can re-observe.
+ */
+export function unobserved(entry) {
+    return [
+        `[not observed] ${entry.subject}`,
+        entry.because,
+        notObservedSentence(entry.kind),
+    ].join('\n');
+}
+/**
+ * What the reader should do about a subject nobody looked at.
+ *
+ * One sentence per kind, and the three are different instructions. `failed` is
+ * work; `excluded` is a decision already on the record; `unreached` is the run
+ * having proved the change cannot arrive here, which is the only one of the
+ * three that is evidence rather than an absence of it.
+ */
+export function notObservedSentence(kind) {
+    switch (kind) {
+        case 'excluded':
+            return 'This was excluded by configuration, not by a failure.';
+        case 'unreached':
+            return 'The change under review cannot reach this subject, so it was not rendered.';
+        default:
+            return 'The run meant to observe this and could not. It is not a pass.';
+    }
+}
+//# sourceMappingURL=subject.js.map

package/dist/tools/subject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject.js","sourceRoot":"","sources":["../../src/tools/subject.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAuBtC,MAAM,UAAU,SAAS,CAAC,MAAiB,EAAE,KAAwC;IACnF,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAE5C,MAAM,WAAW,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;IACnF,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAEtE,gFAAgF;IAChF,+EAA+E;IAC/E,4EAA4E;IAC5E,0CAA0C;IAC1C,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;IAC/E,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAEtE,yEAAyE;IACzE,2EAA2E;IAC3E,4BAA4B;IAC5B,MAAM,IAAI,KAAK,CACb,oBAAoB,OAAO,mBAAmB;QAC5C;YACE,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC;YACpD,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC;SAC5D,CAAC,IAAI,CAAC,IAAI,CAAC,CACf,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAkB;IAC3C,OAAO;QACL,kBAAkB,KAAK,CAAC,OAAO,EAAE;QACjC,KAAK,CAAC,OAAO;QACb,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC;KAChC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAyB;IAC3D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,UAAU;YACb,OAAO,uDAAuD,CAAC;QACjE,KAAK,WAAW;YACd,OAAO,4EAA4E,CAAC;QACtF;YACE,OAAO,gEAAgE,CAAC;IAC5E,CAAC;AACH,CAAC","sourcesContent":["import type { NotObserved, ObservationRecord, RunReport } from '@variance-authority/report';\nimport { stringArg } from './tool.js';\n\n/**\n * Naming a subject, and what to say when the run has nothing to say about it.\n *\n * Shared by the two tools an agent points at a single subject — `variance_describe`\n * and `variance_explain_verdict` — and separate from both because the decision\n * encoded here belongs to neither. A subject the run planned and could not see\n * has to be answered rather than refused, and a lookup that returns `undefined`\n * leaves each caller free to forget that on its own schedule.\n */\n\n/**\n * A subject named in the run, and which of the two lists it came from.\n *\n * A union rather than `ObservationRecord | undefined` so that \"the run did not\n * observe this\" cannot be handled by accident. Every caller has to decide what to\n * say about a subject with no observation, and the answer is never a verdict.\n */\nexport type Located =\n  | { readonly observed: true; readonly observation: ObservationRecord }\n  | { readonly observed: false; readonly entry: NotObserved };\n\nexport function subjectOf(report: RunReport, input: Readonly<Record<string, unknown>>): Located {\n  const subject = stringArg(input, 'subject');\n\n  const observation = report.observations.find((entry) => entry.subject === subject);\n  if (observation !== undefined) return { observed: true, observation };\n\n  // The coverage list is searched too, and this is the point of it. A subject the\n  // run planned and could not see is a subject an agent will ask about; refusing\n  // the name tells it the subject does not exist, which is both false and the\n  // conclusion that ends the investigation.\n  const skipped = report.notObserved?.find((entry) => entry.subject === subject);\n  if (skipped !== undefined) return { observed: false, entry: skipped };\n\n  // Listing the alternatives rather than only refusing: an agent that gets\n  // \"unknown subject\" retries with another guess, and an agent that gets the\n  // list picks the right one.\n  throw new Error(\n    `unknown subject \"${subject}\"; this run has: ` +\n      [\n        ...report.observations.map((entry) => entry.subject),\n        ...(report.notObserved ?? []).map((entry) => entry.subject),\n      ].join(', '),\n  );\n}\n\n/**\n * What to say about a subject with no observation — the CLI's wording, verbatim.\n *\n * Duplicated text rather than a shared helper only because the packages point the\n * other way round, and the duplication is deliberate where drift would be worst:\n * a human running `variance report --subject x` and an agent calling\n * `variance_describe` on the same subject must be told the same thing, or the two\n * of them will argue about a run neither can re-observe.\n */\nexport function unobserved(entry: NotObserved): string {\n  return [\n    `[not observed] ${entry.subject}`,\n    entry.because,\n    notObservedSentence(entry.kind),\n  ].join('\\n');\n}\n\n/**\n * What the reader should do about a subject nobody looked at.\n *\n * One sentence per kind, and the three are different instructions. `failed` is\n * work; `excluded` is a decision already on the record; `unreached` is the run\n * having proved the change cannot arrive here, which is the only one of the\n * three that is evidence rather than an absence of it.\n */\nexport function notObservedSentence(kind: NotObserved['kind']): string {\n  switch (kind) {\n    case 'excluded':\n      return 'This was excluded by configuration, not by a failure.';\n    case 'unreached':\n      return 'The change under review cannot reach this subject, so it was not rendered.';\n    default:\n      return 'The run meant to observe this and could not. It is not a pass.';\n  }\n}\n"]}

package/dist/tools/summary.d.ts

@@ -0,0 +1,31 @@
+import { type Tool } from './tool.js';
+/**
+ * `variance_summary`, and the sections it is assembled from.
+ *
+ * The helpers below live with it rather than somewhere shared because none of
+ * them is a general fact about a report — each is one paragraph of this one
+ * answer, and each exists to stop this answer claiming something the run never
+ * established. Coverage, order dependence, findings and the closing sentence all
+ * repeat the same rule in different words: silence about a subject is not a pass.
+ * Read them in the order `run` prints them; that order is the argument.
+ */
+/**
+ * Overview: what happened, what needs attention, and what was never looked at.
+ *
+ * Deliberately does not list unchanged subjects. A run over 300 subjects where
+ * two changed should print two lines — a list as long as the suite is the "100
+ * changes? merge" failure in its purest form, and the reader stops reading long
+ * before the interesting line.
+ *
+ * The coverage section is the exception to that economy and is not negotiable.
+ * A run that planned 300 subjects, failed on 50 and found the other 250
+ * unchanged has an observation list in which every entry is clean; a summary
+ * computed from observations alone therefore reports it as a clean run, and an
+ * agent acts on that. So `nothing to review` is claimed only from a report that
+ * accounted for every subject it planned — never from silence, and never over a
+ * subject the run meant to see and could not. That is the same rule the CLI's
+ * exit code applies, stated in the same words, because a human and an agent
+ * reading one artifact must not be able to disagree about whether it was green.
+ */
+export declare const summarize: Tool;
+//# sourceMappingURL=summary.d.ts.map