feat(context): capture related Rstest evidence

Author: ScriptedAlchemy

packages/context/package.json

@@ -51,6 +51,11 @@
   "peerDependencies": {
     "@rstest/coverage-istanbul": "0.11.6"
   },
+  "peerDependenciesMeta": {
+    "@rstest/coverage-istanbul": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=22.12.0"
   },

packages/context/src/codeEvidence.ts

@@ -59,6 +59,12 @@ type TestOutcomeEvidence = {
   matchingTests: number;
 };
 
+type TestRelationEvidence = {
+  state: 'related' | 'unrelated' | 'unknown' | 'unavailable';
+  reason?: 'no-test-snapshot' | 'not-captured' | 'source-not-selected' | 'selection-not-isolated';
+  testFiles: string[];
+};
+
 type CodeDiagnosticEvidence = {
   total: number;
   returned: number;
@@ -70,6 +76,7 @@ type CodeEvidenceResult = {
   path: string;
   line?: number;
   executionCoverage: ExecutionCoverageEvidence;
+  testRelation: TestRelationEvidence;
   testOutcome: TestOutcomeEvidence;
   diagnostics: CodeDiagnosticEvidence;
   module?: DeadCodeExplanation;
@@ -241,6 +248,33 @@ const testOutcome = (
   return { state: 'not-run', matchingFiles: files.length, matchingTests: tests.length };
 };
 
+const testRelation = (
+  sourcePath: string,
+  stored: StoredContextSnapshot | undefined,
+): TestRelationEvidence => {
+  if (stored === undefined) {
+    return { state: 'unavailable', reason: 'no-test-snapshot', testFiles: [] };
+  }
+  const facet = stored.snapshot.facets.test as unknown as TestFacet | undefined;
+  if (facet?.relation === undefined) {
+    return { state: 'unavailable', reason: 'not-captured', testFiles: [] };
+  }
+  if (!facet.relation.sources.includes(sourcePath)) {
+    return { state: 'unknown', reason: 'source-not-selected', testFiles: [] };
+  }
+  if (facet.relation.sources.length !== 1) {
+    return {
+      state: 'unknown',
+      reason: 'selection-not-isolated',
+      testFiles: [...facet.relation.testFiles],
+    };
+  }
+  return {
+    state: facet.relation.testFiles.length > 0 ? 'related' : 'unrelated',
+    testFiles: [...facet.relation.testFiles],
+  };
+};
+
 const compareDiagnostics = (left: DiagnosticRecord, right: DiagnosticRecord): number =>
   left.producer.localeCompare(right.producer) ||
   (left.line ?? 0) - (right.line ?? 0) ||
@@ -365,6 +399,7 @@ const readCodeEvidence = async (
   };
   const bounds = [
     'aggregate-execution-no-test-attribution',
+    'test-relation-static-build-graph',
     'test-outcome-exact-path-only',
     'diagnostics-exact-path-only',
     ...(module !== undefined && module.provenance.artifactBinding !== 'exact'
@@ -375,6 +410,7 @@ const readCodeEvidence = async (
     path: sourcePath,
     ...(query.line === undefined ? {} : { line: query.line }),
     executionCoverage: await executionCoverage(workspaceRoot, sourcePath, query.line, testSnapshot),
+    testRelation: testRelation(sourcePath, testSnapshot),
     testOutcome: testOutcome(sourcePath, testSnapshot),
     diagnostics,
     ...(module === undefined ? {} : { module }),
@@ -391,4 +427,5 @@ export type {
   ExecutionCoverageEvidence,
   SnapshotEvidence,
   TestOutcomeEvidence,
+  TestRelationEvidence,
 };

packages/context/src/index.ts

@@ -27,6 +27,7 @@ export {
   type TestErrorRecord,
   type TestFacet,
   type TestFileRecord,
+  type TestRelationRecord,
 } from './model.ts';
 export {
   readContextSnapshotById,
@@ -71,6 +72,8 @@ export {
 export {
   captureTestSnapshot,
   listTestResults,
+  type RelatedTestRequest,
+  type ResolveRelatedTests,
   type TestCaptureDependencies,
   type TestCaptureResult,
   type TestResultPage,

packages/context/src/mcp.ts

@@ -221,6 +221,14 @@ const lintSnapshotInput = z
 const testSnapshotInput = z
   .object({
     files: z.array(z.string().min(1)).optional(),
+    related: z
+      .array(z.string().min(1))
+      .min(1)
+      .max(200)
+      .describe(
+        'Source paths resolved from packageRoot; Rstest selects and runs only statically related test files.',
+      )
+      .optional(),
     testNamePattern: z.string().min(1).optional(),
     packageRoot: packageRootInput.optional(),
     configPath: configPathInput.optional(),
@@ -344,7 +352,7 @@ const formatCodeEvidence = (result: CodeEvidenceResult): string => {
     result.module === undefined
       ? 'not-requested'
       : `${result.module.classification}(binding=${result.module.provenance.artifactBinding})`;
-  return `Code evidence for ${result.path}: coverage=${result.executionCoverage.state}, test=${result.testOutcome.state}, diagnostics=${diagnostics}, module=${module}. See structuredContent for complete data.`;
+  return `Code evidence for ${result.path}: coverage=${result.executionCoverage.state}, relation=${result.testRelation.state}, test=${result.testOutcome.state}, diagnostics=${diagnostics}, module=${module}. See structuredContent for complete data.`;
 };
 
 const isLiteralEmpty = (value: unknown): boolean =>
@@ -607,7 +615,7 @@ const createContextMcpServer = (
     {
       title: 'Inspect code evidence',
       description:
-        'Join exact-path aggregate execution, test outcome, diagnostics, and optional explicit artifact module evidence without collapsing their bounds.',
+        'Join static related-test selection, exact-path test outcome, aggregate execution, diagnostics, and optional explicit artifact module evidence without collapsing their bounds.',
       inputSchema: codeEvidenceInput,
       annotations: readOnlyAnnotations,
     },
@@ -747,7 +755,8 @@ const createContextMcpServer = (
     'test_snapshot',
     {
       title: 'Capture test snapshot',
-      description: 'Run one explicit one-shot Rstest capture and store its immutable results.',
+      description:
+        'Run one explicit one-shot Rstest capture, optionally selected from related source files, and store its immutable results.',
       inputSchema: testSnapshotInput,
       annotations: {
         readOnlyHint: false,

packages/context/src/model.ts

@@ -127,8 +127,14 @@ type TestFileRecord = {
   tests: TestCaseRecord[];
 };
 
+type TestRelationRecord = {
+  sources: string[];
+  testFiles: string[];
+};
+
 type TestFacet = {
   producer: 'rstest';
+  relation?: TestRelationRecord;
   files: TestFileRecord[];
   stats: {
     tests: {
@@ -317,4 +323,5 @@ export type {
   TestExecutionStatement,
   TestFacet,
   TestFileRecord,
+  TestRelationRecord,
 };

packages/context/src/records.ts

@@ -159,10 +159,18 @@ const isTestFile = (value: unknown): boolean =>
   Array.isArray(value.tests) &&
   value.tests.every(isTestCase);
 
+const isTestRelation = (value: unknown): boolean =>
+  isRecordObject(value) &&
+  Array.isArray(value.sources) &&
+  value.sources.every(isRecordPath) &&
+  Array.isArray(value.testFiles) &&
+  value.testFiles.every(isRecordPath);
+
 const validateTestFacet = (value: unknown): TestFacet | undefined => {
   if (
     !isRecordObject(value) ||
     value.producer !== 'rstest' ||
+    (value.relation !== undefined && !isTestRelation(value.relation)) ||
     !Array.isArray(value.files) ||
     !value.files.every(isTestFile) ||
     !isRecordObject(value.stats) ||