fix(context): qualify lint snapshot freshness

Author: ScriptedAlchemy

packages/context/src/lint.ts

@@ -203,6 +203,20 @@ const lintCaptureSelection = (
         filePath: toWorkspacePath(workspaceRoot, path.resolve(packageRoot, request.filePath)),
       };
 
+const lintInputCompleteness = (
+  workspaceRoot: string,
+  packageRoot: string,
+  patterns: string[],
+  files: LintFileRecord[],
+): 'complete' | 'partial' => {
+  const selectedPaths = new Set(
+    patterns.map((pattern) => toWorkspacePath(workspaceRoot, path.resolve(packageRoot, pattern))),
+  );
+  return selectedPaths.size === files.length && files.every((file) => selectedPaths.has(file.path))
+    ? 'complete'
+    : 'partial';
+};
+
 const ensureWritten = (result: Awaited<ReturnType<typeof writeContextSnapshot>>): void => {
   if (!result.written)
     throw new Error('Could not write the context snapshot.', {
@@ -336,7 +350,12 @@ const captureLintSnapshot = async (
             path: filePath,
             digest: fileDigest,
           })),
-          inputCompleteness: 'complete',
+          inputCompleteness: lintInputCompleteness(
+            workspaceRoot,
+            target.packageRoot,
+            request.patterns ?? ['.'],
+            files,
+          ),
           captureSelection,
         };
   const status: ContextRunStatus = totals.errors > 0 ? 'fail' : 'pass';

packages/context/tests/lint.test.ts

@@ -112,7 +112,7 @@ await listDiagnostics(${JSON.stringify(workspaceRoot)}).catch(() => undefined);`
   });
 });
 
-test('captures a deterministic file snapshot with complete inputs and fail status', async () => {
+test('captures an open-ended file snapshot with partial inputs and fail status', async () => {
   await withTempWorkspace(async (workspaceRoot) => {
     const aPath = path.join(workspaceRoot, 'a.ts');
     const bPath = path.join(workspaceRoot, 'b.ts');
@@ -176,7 +176,7 @@ test('captures a deterministic file snapshot with complete inputs and fail statu
     expect(mocks.closeCalls).toBe(1);
     expect(result).toMatchObject({
       status: 'fail',
-      freshness: { state: 'fresh', changedPaths: [] },
+      freshness: { state: 'partial', changedPaths: [] },
       summary: {
         files: 2,
         errors: 1,
@@ -187,7 +187,7 @@ test('captures a deterministic file snapshot with complete inputs and fail statu
     });
     expect(stored?.snapshot.source).toMatchObject({
       captureSelection: { mode: 'files', patterns: ['.'] },
-      inputCompleteness: 'complete',
+      inputCompleteness: 'partial',
       inputs: [{ path: 'a.ts' }, { path: 'b.ts' }],
     });
     expect(stored?.snapshot.facets.lint).toMatchObject({
@@ -312,7 +312,7 @@ test('paginates and filters diagnostics from one frozen snapshot deterministical
     });
     expect(first).toMatchObject({
       snapshotId: capture.snapshotId,
-      freshness: { state: 'fresh', changedPaths: [] },
+      freshness: { state: 'partial', changedPaths: [] },
       total: 2,
       items: [{ path: 'src/a.ts', ruleId: 'a', severity: 'error', message: 'error' }],
     });
@@ -487,7 +487,11 @@ test('rejects a malformed diagnostics cursor', async () => {
         messages: [],
       },
     ];
-    const capture = await captureLintSnapshot(workspaceRoot, { mode: 'files' }, createRslint);
+    const capture = await captureLintSnapshot(
+      workspaceRoot,
+      { mode: 'files', patterns: ['a.ts'] },
+      createRslint,
+    );
 
     await expect(
       listDiagnostics(workspaceRoot, { snapshotId: capture.snapshotId, cursor: '?' }),
@@ -509,7 +513,11 @@ test('returns snapshot provenance for an empty diagnostics page', async () => {
         messages: [],
       },
     ];
-    const capture = await captureLintSnapshot(workspaceRoot, { mode: 'files' }, createRslint);
+    const capture = await captureLintSnapshot(
+      workspaceRoot,
+      { mode: 'files', patterns: ['a.ts'] },
+      createRslint,
+    );
     const stored = await readContextSnapshotById(workspaceRoot, capture.snapshotId);
 
     await expect(

website/docs/en/guide/cli/mcp.mdx

@@ -90,6 +90,8 @@ The development tools reuse the same immutable checkout-local store. `snapshot_l
 
 `lint_snapshot` is explicit execution. It runs Rslint once for file patterns (default `['.']`) or one supplied text buffer, then records diagnostics and optional fixed output without writing source files. Its optional `packageRoot` and `configPath` select a monorepo package and Rstack config as described above. It is annotated `readOnlyHint: false`, `destructiveHint: false`, and `openWorldHint: true` because configuration is loaded and lint runs. Ask before calling it.
 
+File-mode lint freshness is `fresh` only when every selected pattern is an explicit file returned by Rslint. Directory, glob, unmatched, and default selections are `partial` because files that match later are not part of the recorded input set.
+
 `test_snapshot` is also explicit execution. It invokes the installed experimental `runRstest()` API once, optionally narrowed by files or a test-name pattern, and records structured summaries without watch mode or console streams. It accepts the same optional checkout-relative `packageRoot` and `configPath` selectors. An optional `execution` object explicitly enables aggregate Istanbul coverage for that one run; its `include` and `exclude` arrays accept at most 200 patterns, and `allowExternal` defaults to false. Coverage is not enabled when `execution` is omitted. The tool is annotated `readOnlyHint: false`, `destructiveHint: true`, and `openWorldHint: true` because project configuration and tests execute. Ask before calling it.
 
 Freshness belongs to each producer and snapshot independently:

website/docs/zh/guide/cli/mcp.mdx

@@ -87,6 +87,8 @@ Rsbuild 只会为该命令加载已安装的收集器。构建会在检出目录
 
 `lint_snapshot` 是明确执行操作。它会针对文件模式（默认为 `['.']`）或一个给定文本缓冲区运行一次 Rslint，然后记录诊断和可选的修复输出，但不会写入源文件。可选的 `packageRoot` 和 `configPath` 会按上述规则选择 monorepo 包和 Rstack 配置。其标注为 `readOnlyHint: false`、`destructiveHint: false` 和 `openWorldHint: true`，因为它会加载配置并运行 lint。调用前应先询问用户。
 
+只有当每个选定模式都是 Rslint 实际返回的明确文件时，文件模式 lint 的新鲜度才会是 `fresh`。目录、glob、未匹配模式和默认选择会是 `partial`，因为之后新增的匹配文件不在已记录的输入集合中。
+
 `test_snapshot` 也是明确执行操作。它会调用一次已安装的实验性 `runRstest()` API，可按文件或测试名称模式缩小范围，并记录结构化摘要，不启动 watch 模式，也不记录控制台流。它接受相同的可选检出目录相对路径 `packageRoot` 和 `configPath` 选择器。可选的 `execution` 对象会为这一次运行明确启用 Istanbul 聚合覆盖率；其中 `include` 和 `exclude` 数组最多各接受 200 个模式，`allowExternal` 默认为 false。省略 `execution` 时不会启用覆盖率。其标注为 `readOnlyHint: false`、`destructiveHint: true` 和 `openWorldHint: true`，因为它会执行项目配置和测试。调用前应先询问用户。
 
 新鲜度按生产者和快照分别判断：