Skip to content

Commit 04e4c23

Browse files
authored
dx(check): fail fast when node_modules lags the lockfile (#1967)
* dx(doctor): flag a worktree whose node_modules lags the lockfile Add a doctor probe and a check:affected preflight that compare node_modules/.pnpm/lock.yaml (the exact lockfile snapshot pnpm installed from) against pnpm-lock.yaml via a content hash — no subprocess. On mismatch both surfaces report the same one-liner: "node_modules was installed from a different lockfile; run pnpm install", so a stale install names its own cause instead of surfacing as bogus format diffs on files a change never touched (the #1956 incident). Closes #1963 * fix(doctor): scope the node-modules probe to a local source checkout The probe ran unconditionally from findProjectRoot(), so it fired in two contexts it cannot diagnose: - Packaged installs. Published packages ship neither pnpm-lock.yaml (not in the package.json `files` allowlist) nor an installed snapshot, so every end user's `doctor` gained a spurious node-modules line and a degraded overall status. - `--remote`, where the daemon's own root describes the server deployment rather than the caller's worktree, so the answer could not address #1963 at all. Whether a root is a source checkout is now decided by the presence of pnpm-lock.yaml itself rather than a heuristic about install location, and 'no-source-checkout' is a distinct result rather than a warning, so the packaged case cannot be represented as a defect. The probe returns undefined there and the route appends no check, matching how doctor already models an out-of-scope question (the device family is likewise absent under --remote). The fresh-worktree catch is preserved: a lockfile with no installed snapshot is still a hard failure. The check:affected preflight is unchanged in behavior. Route-level assertions cover all three contexts (source, packaged, remote); each was verified to fail against the pre-fix wiring. * refactor(check): keep stale-install probe worktree-local
1 parent 03c3984 commit 04e4c23

5 files changed

Lines changed: 263 additions & 2 deletions

File tree

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@
130130
"fallow:baseline": "fallow dead-code --save-baseline fallow-baselines/dead-code.json --summary && fallow health --report-only --save-baseline fallow-baselines/health.json --summary",
131131
"check:fallow": "fallow audit",
132132
"check:affected": "node --experimental-strip-types scripts/check-affected/run.ts",
133-
"check:affected:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/check-affected/model.test.ts scripts/check-affected/platform-packages.test.ts scripts/check-affected/device-lanes.test.ts scripts/check-affected/run.test.ts",
133+
"check:affected:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/check-affected/model.test.ts scripts/check-affected/platform-packages.test.ts scripts/check-affected/device-lanes.test.ts scripts/check-affected/lockfile-install-sync.test.ts scripts/check-affected/run.test.ts",
134134
"gate": "node --experimental-strip-types scripts/gate/run.ts",
135135
"check:gate-manifest": "node --experimental-strip-types scripts/gate/check.ts",
136136
"check:gate-manifest:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/gate/*.test.ts",
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
import assert from 'node:assert/strict';
2+
import fs from 'node:fs';
3+
import path from 'node:path';
4+
import { test } from 'node:test';
5+
import { mkdtempForTestSync } from '../../src/__tests__/test-utils/tmp-dir.ts';
6+
import { checkLockfileInstallSync } from './lockfile-install-sync.ts';
7+
8+
function writeLockfile(root: string, content: string): void {
9+
fs.writeFileSync(path.join(root, 'pnpm-lock.yaml'), content);
10+
}
11+
12+
function writeInstalledSnapshot(root: string, content: string): void {
13+
const dir = path.join(root, 'node_modules', '.pnpm');
14+
fs.mkdirSync(dir, { recursive: true });
15+
fs.writeFileSync(path.join(dir, 'lock.yaml'), content);
16+
}
17+
18+
test('reports in sync when the installed snapshot byte-matches the checked-out lockfile', () => {
19+
const root = mkdtempForTestSync('agent-device-lockfile-sync-match-');
20+
writeLockfile(root, 'lockfileVersion: 9.0\nimporters:\n .: {}\n');
21+
writeInstalledSnapshot(root, 'lockfileVersion: 9.0\nimporters:\n .: {}\n');
22+
23+
assert.deepEqual(checkLockfileInstallSync(root), { status: 'in-sync' });
24+
});
25+
26+
test('reports stale when the installed snapshot content differs from the checked-out lockfile', () => {
27+
const root = mkdtempForTestSync('agent-device-lockfile-sync-stale-');
28+
writeLockfile(
29+
root,
30+
'lockfileVersion: 9.0\nimporters:\n .:\n dependencies:\n newDep: 1.0.0\n',
31+
);
32+
writeInstalledSnapshot(root, 'lockfileVersion: 9.0\nimporters:\n .: {}\n');
33+
34+
assert.deepEqual(checkLockfileInstallSync(root), { status: 'out-of-sync', reason: 'stale' });
35+
});
36+
37+
test('reports install-missing when a source checkout has no installed snapshot', () => {
38+
const root = mkdtempForTestSync('agent-device-lockfile-sync-no-install-');
39+
writeLockfile(root, 'lockfileVersion: 9.0\n');
40+
41+
assert.deepEqual(checkLockfileInstallSync(root), {
42+
status: 'out-of-sync',
43+
reason: 'install-missing',
44+
});
45+
});
46+
47+
test('reports install-missing for a fresh worktree that has no node_modules directory at all', () => {
48+
const root = mkdtempForTestSync('agent-device-lockfile-sync-fresh-worktree-');
49+
writeLockfile(root, 'lockfileVersion: 9.0\n');
50+
assert.equal(fs.existsSync(path.join(root, 'node_modules')), false);
51+
52+
assert.deepEqual(checkLockfileInstallSync(root), {
53+
status: 'out-of-sync',
54+
reason: 'install-missing',
55+
});
56+
});
57+
58+
test('reports no-source-checkout when there is no pnpm-lock.yaml', () => {
59+
const root = mkdtempForTestSync('agent-device-lockfile-sync-packaged-');
60+
fs.writeFileSync(path.join(root, 'package.json'), '{"name":"agent-device"}\n');
61+
62+
assert.deepEqual(checkLockfileInstallSync(root), { status: 'no-source-checkout' });
63+
});
64+
65+
test('reports no-source-checkout even when an installed snapshot exists without a lockfile', () => {
66+
const root = mkdtempForTestSync('agent-device-lockfile-sync-no-lockfile-');
67+
writeInstalledSnapshot(root, 'lockfileVersion: 9.0\n');
68+
69+
assert.deepEqual(checkLockfileInstallSync(root), { status: 'no-source-checkout' });
70+
});
71+
72+
test('checks each worktree against its own lockfile state', () => {
73+
const worktreeA = mkdtempForTestSync('agent-device-lockfile-sync-worktree-a-');
74+
const worktreeB = mkdtempForTestSync('agent-device-lockfile-sync-worktree-b-');
75+
writeLockfile(worktreeA, 'lockfileVersion: 9.0\nimporters:\n .: {}\n');
76+
writeInstalledSnapshot(worktreeA, 'lockfileVersion: 9.0\nimporters:\n .: {}\n');
77+
writeLockfile(
78+
worktreeB,
79+
'lockfileVersion: 9.0\nimporters:\n .:\n dependencies:\n newDep: 1.0.0\n',
80+
);
81+
writeInstalledSnapshot(worktreeB, 'lockfileVersion: 9.0\nimporters:\n .: {}\n');
82+
83+
assert.deepEqual(checkLockfileInstallSync(worktreeA), { status: 'in-sync' });
84+
assert.deepEqual(checkLockfileInstallSync(worktreeB), { status: 'out-of-sync', reason: 'stale' });
85+
});
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
import fs from 'node:fs';
2+
import path from 'node:path';
3+
4+
const LOCKFILE_BASENAME = 'pnpm-lock.yaml';
5+
const INSTALLED_SNAPSHOT_RELATIVE_PATH = ['node_modules', '.pnpm', 'lock.yaml'];
6+
7+
export const STALE_NODE_MODULES_MESSAGE =
8+
"node_modules does not match this worktree's pnpm-lock.yaml";
9+
10+
export type LockfileInstallSyncResult =
11+
| { readonly status: 'no-source-checkout' }
12+
| { readonly status: 'in-sync' }
13+
| {
14+
readonly status: 'out-of-sync';
15+
readonly reason: 'install-missing' | 'stale';
16+
};
17+
18+
/**
19+
* Compares pnpm's installed lockfile snapshot with this worktree's lockfile.
20+
* This is intentionally synchronous and subprocess-free: it runs before any gate.
21+
*/
22+
export function checkLockfileInstallSync(repoRoot: string): LockfileInstallSyncResult {
23+
const lockfile = readFileIfExists(path.join(repoRoot, LOCKFILE_BASENAME));
24+
if (!lockfile) return { status: 'no-source-checkout' };
25+
26+
const installedSnapshot = readFileIfExists(
27+
path.join(repoRoot, ...INSTALLED_SNAPSHOT_RELATIVE_PATH),
28+
);
29+
if (!installedSnapshot) return { status: 'out-of-sync', reason: 'install-missing' };
30+
31+
return lockfile.equals(installedSnapshot)
32+
? { status: 'in-sync' }
33+
: { status: 'out-of-sync', reason: 'stale' };
34+
}
35+
36+
function readFileIfExists(filePath: string): Buffer | undefined {
37+
if (!fs.existsSync(filePath)) return undefined;
38+
return fs.readFileSync(filePath);
39+
}

‎scripts/check-affected/run.test.ts‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import os from 'node:os';
99
import path from 'node:path';
1010
import { test } from 'node:test';
1111
import { runCmdSync } from '../../src/utils/exec.ts';
12+
import { STALE_NODE_MODULES_MESSAGE } from './lockfile-install-sync.ts';
1213
import { CHECK_CATALOG } from './checks.ts';
1314
import { DEFAULT_VITEST_MAX_WORKERS } from '../lib/vitest-concurrency.ts';
1415
import { selectChecks } from './model.ts';
@@ -247,3 +248,111 @@ test('runChecks leaves coverage to CI and runs capped related tests once', async
247248
'the coverage gate is GitHub-authoritative and must not run locally',
248249
);
249250
});
251+
252+
test('runChecks fails fast on a stale install before running format or any other check', async () => {
253+
const executed: string[][] = [];
254+
const execute: CommandExecutor = async (command) => {
255+
executed.push(command);
256+
return 0;
257+
};
258+
const plan = selectChecks({
259+
changedFiles: ['packages/selectors/src/index.ts'],
260+
packageEntryFiles: [],
261+
});
262+
const code = await runChecks(plan, { scripts: ALL_SCRIPTS }, ARGS, {
263+
execute,
264+
cwd: '.',
265+
checkLockfileSync: () => ({ status: 'out-of-sync', reason: 'stale' }),
266+
});
267+
assert.equal(code, 1);
268+
assert.deepEqual(executed, [], 'no check — including format — may run against a stale install');
269+
});
270+
271+
test('runChecks fails fast when node_modules was never installed in this checkout', async () => {
272+
const executed: string[][] = [];
273+
const execute: CommandExecutor = async (command) => {
274+
executed.push(command);
275+
return 0;
276+
};
277+
const plan = selectChecks({
278+
changedFiles: ['packages/selectors/src/index.ts'],
279+
packageEntryFiles: [],
280+
});
281+
const code = await runChecks(plan, { scripts: ALL_SCRIPTS }, ARGS, {
282+
execute,
283+
cwd: '.',
284+
checkLockfileSync: () => ({ status: 'out-of-sync', reason: 'install-missing' }),
285+
});
286+
assert.equal(code, 1);
287+
assert.deepEqual(executed, []);
288+
});
289+
290+
test('runChecks does not block when there is no source checkout to compare against', async () => {
291+
const executed: string[][] = [];
292+
const execute: CommandExecutor = async (command) => {
293+
executed.push(command);
294+
return 0;
295+
};
296+
const plan = selectChecks({
297+
changedFiles: ['packages/selectors/src/index.ts'],
298+
packageEntryFiles: [],
299+
});
300+
const code = await runChecks(plan, { scripts: ALL_SCRIPTS }, ARGS, {
301+
execute,
302+
cwd: '.',
303+
checkLockfileSync: () => ({ status: 'no-source-checkout' }),
304+
});
305+
assert.equal(code, 0);
306+
assert.ok(executed.length > 0, 'checks still run when there is nothing to compare against');
307+
});
308+
309+
test('runChecks proceeds normally when the install is in sync', async () => {
310+
const executed: string[][] = [];
311+
const execute: CommandExecutor = async (command) => {
312+
executed.push(command);
313+
return 0;
314+
};
315+
const plan = selectChecks({
316+
changedFiles: ['packages/selectors/src/index.ts'],
317+
packageEntryFiles: [],
318+
});
319+
const code = await runChecks(plan, { scripts: ALL_SCRIPTS }, ARGS, {
320+
execute,
321+
cwd: '.',
322+
checkLockfileSync: () => ({ status: 'in-sync' }),
323+
});
324+
assert.equal(code, 0);
325+
assert.ok(executed.some((command) => command.includes('format:check')));
326+
});
327+
328+
test('runChecks names the real cause on stderr instead of surfacing as an unrelated failure', async () => {
329+
const stderrChunks: string[] = [];
330+
const originalWrite = process.stderr.write.bind(process.stderr);
331+
process.stderr.write = ((chunk: string | Uint8Array) => {
332+
stderrChunks.push(chunk.toString());
333+
return true;
334+
}) as typeof process.stderr.write;
335+
336+
try {
337+
const plan = selectChecks({
338+
changedFiles: ['packages/selectors/src/index.ts'],
339+
packageEntryFiles: [],
340+
});
341+
const code = await runChecks(plan, { scripts: ALL_SCRIPTS }, ARGS, {
342+
execute: async () => 0,
343+
cwd: '.',
344+
checkLockfileSync: () => ({ status: 'out-of-sync', reason: 'stale' }),
345+
});
346+
assert.equal(code, 1);
347+
assert.ok(
348+
stderrChunks.some((chunk) => chunk.includes(STALE_NODE_MODULES_MESSAGE)),
349+
`expected stderr to name the stale-install cause, got: ${stderrChunks.join('')}`,
350+
);
351+
const stderr = stderrChunks.join('');
352+
assert.match(stderr, /Worktree: \.\n/);
353+
assert.match(stderr, /pnpm install --frozen-lockfile/);
354+
assert.doesNotMatch(stderr, /agent-device doctor/);
355+
} finally {
356+
process.stderr.write = originalWrite;
357+
}
358+
});

‎scripts/check-affected/run.ts‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@ import fs from 'node:fs';
99
import path from 'node:path';
1010
import { pathToFileURL } from 'node:url';
1111
import { runCmdStreaming, runCmdSync } from '../../src/utils/exec.ts';
12+
import {
13+
checkLockfileInstallSync,
14+
STALE_NODE_MODULES_MESSAGE,
15+
type LockfileInstallSyncResult,
16+
} from './lockfile-install-sync.ts';
1217
import { parseScriptArgs } from '../lib/cli-args.ts';
1318
import { runEntrypoint } from '../lib/cli-entrypoint.ts';
1419
import {
@@ -184,9 +189,21 @@ export async function runChecks(
184189
plan: CheckPlan,
185190
pkg: PackageJson,
186191
args: Args,
187-
options: { cwd?: string; execute?: CommandExecutor; changedFiles?: readonly string[] } = {},
192+
options: {
193+
cwd?: string;
194+
execute?: CommandExecutor;
195+
changedFiles?: readonly string[];
196+
checkLockfileSync?: (cwd: string) => LockfileInstallSyncResult;
197+
} = {},
188198
): Promise<number> {
189199
const cwd = options.cwd ?? repoRoot;
200+
const checkLockfileSync = options.checkLockfileSync ?? checkLockfileInstallSync;
201+
// Fail before any gate can misdiagnose a stale worktree install (#1956).
202+
const lockfileSync = checkLockfileSync(cwd);
203+
if (lockfileSync.status === 'out-of-sync') {
204+
reportStaleInstall(lockfileSync.reason, cwd);
205+
return 1;
206+
}
190207
const execute = options.execute ?? streamingExecutor;
191208
const runnable = plan.checks.map(getCheckSpec).filter((spec: CheckSpec) => spec.localRunnable);
192209
const skipped = plan.checks.map(getCheckSpec).filter((spec: CheckSpec) => !spec.localRunnable);
@@ -212,6 +229,17 @@ export async function runChecks(
212229
return 0;
213230
}
214231

232+
function reportStaleInstall(reason: 'install-missing' | 'stale', cwd: string): void {
233+
process.stderr.write(`\ncheck:affected: ${STALE_NODE_MODULES_MESSAGE}\n`);
234+
process.stderr.write(
235+
reason === 'install-missing'
236+
? '(no node_modules/.pnpm/lock.yaml found — this checkout was never installed)\n'
237+
: '(node_modules/.pnpm/lock.yaml disagrees with pnpm-lock.yaml)\n',
238+
);
239+
process.stderr.write(`Worktree: ${cwd}\n`);
240+
process.stderr.write('Run `pnpm install --frozen-lockfile` in this worktree, then retry.\n');
241+
}
242+
215243
// Where a check the local run skips is authoritative. A parked check has no automatic
216244
// lane; say so instead of printing an empty job list.
217245
function describeOwner(id: CheckId, ciJobs: ReadonlyMap<CheckId, string[]>): string {

0 commit comments

Comments
 (0)