Skip to content

Commit 59849f9

Browse files
JstnMcBrdclaude
andcommitted
fix(shared): probe PATH candidates when a directory listing fails
Only three failure reasons prove a PATH entry can never hold a command: NotFound (ENOENT), BadResource (ENOTDIR/EISDIR/ELOOP) and BadArgument. Everything else — EBUSY, EIO and EPERM, the last two arriving unclassified as Unknown — is transient or unproven, and treating it as an empty listing ruled out every candidate without the stat fallback and cached that false negative for the full 30s window, so an installed command could briefly appear missing. Unproven failures now list as null, which makes the caller probe candidates directly the way it did before this cache existed. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 5f15284 commit 59849f9

2 files changed

Lines changed: 60 additions & 57 deletions

File tree

‎packages/shared/src/shell.test.ts‎

Lines changed: 47 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -384,61 +384,56 @@ effectIt.layer(NodeServices.layer)("resolveCommandPath", (it) => {
384384
}).pipe(Effect.scoped),
385385
);
386386

387-
// A directory can grant search permission without read permission, so a
388-
// failed listing must fall back to probing the candidate paths.
389-
it.effect("probes a PATH directory that cannot be listed", () =>
390-
Effect.gen(function* () {
391-
const resolved = yield* resolveCommandPath("code", {
392-
env: { PATH: "C:\\search-only", PATHEXT: ".COM;.EXE;.BAT;.CMD" },
393-
}).pipe(Effect.provideService(HostProcessPlatform, "win32"), Effect.result);
394-
395-
expect(resolved._tag).toBe("Success");
396-
}).pipe(
397-
Effect.provide(
398-
FileSystem.layerNoop({
399-
readDirectory: () =>
400-
Effect.fail(
401-
PlatformError.systemError({
402-
_tag: "PermissionDenied",
403-
module: "FileSystem",
404-
method: "readDirectory",
405-
}),
406-
),
407-
stat: () => Effect.succeed({ type: "File" } as FileSystem.File.Info),
387+
const failingListingLayer = (reason: PlatformError.SystemErrorTag, onStat: () => void) =>
388+
FileSystem.layerNoop({
389+
readDirectory: () =>
390+
Effect.fail(
391+
PlatformError.systemError({
392+
_tag: reason,
393+
module: "FileSystem",
394+
method: "readDirectory",
395+
}),
396+
),
397+
stat: () =>
398+
Effect.sync(() => {
399+
onStat();
400+
return { type: "File" } as FileSystem.File.Info;
408401
}),
409-
),
410-
),
411-
);
412-
413-
it.effect("skips a PATH directory that does not exist", () => {
414-
let statCalls = 0;
415-
return Effect.gen(function* () {
416-
const resolved = yield* resolveCommandPath("code", {
417-
env: { PATH: "C:\\missing", PATHEXT: ".COM;.EXE;.BAT;.CMD" },
418-
}).pipe(Effect.provideService(HostProcessPlatform, "win32"), Effect.result);
402+
});
419403

420-
expect(resolved._tag).toBe("Failure");
421-
expect(statCalls).toBe(0);
422-
}).pipe(
423-
Effect.provide(
424-
FileSystem.layerNoop({
425-
readDirectory: () =>
426-
Effect.fail(
427-
PlatformError.systemError({
428-
_tag: "NotFound",
429-
module: "FileSystem",
430-
method: "readDirectory",
431-
}),
432-
),
433-
stat: () =>
434-
Effect.sync(() => {
435-
statCalls += 1;
436-
return { type: "File" } as FileSystem.File.Info;
437-
}),
438-
}),
439-
),
404+
// A listing that did not happen proves nothing. Trusting it would hide an
405+
// installed command for the whole cache window, so anything short of proof
406+
// that the directory cannot hold a command falls back to probing.
407+
for (const reason of ["PermissionDenied", "Busy", "Unknown"] as const) {
408+
it.effect(`probes a PATH directory that fails to list with ${reason}`, () =>
409+
Effect.gen(function* () {
410+
// A distinct directory per case: the listing cache is keyed by
411+
// directory and shared process-wide, so a reused path would answer
412+
// from the previous case instead of exercising this one.
413+
const resolved = yield* resolveCommandPath("code", {
414+
env: { PATH: `C:\\unreadable-${reason}`, PATHEXT: ".COM;.EXE;.BAT;.CMD" },
415+
}).pipe(Effect.provideService(HostProcessPlatform, "win32"), Effect.result);
416+
417+
expect(resolved._tag).toBe("Success");
418+
}).pipe(Effect.provide(failingListingLayer(reason, () => undefined))),
440419
);
441-
});
420+
}
421+
422+
// A directory that is absent or is not a walkable directory at all can never
423+
// hold a command, so it should be skipped.
424+
for (const reason of ["NotFound", "BadResource"] as const) {
425+
it.effect(`skips a PATH directory that fails to list with ${reason}`, () => {
426+
let statCalls = 0;
427+
return Effect.gen(function* () {
428+
const resolved = yield* resolveCommandPath("code", {
429+
env: { PATH: `C:\\unusable-${reason}`, PATHEXT: ".COM;.EXE;.BAT;.CMD" },
430+
}).pipe(Effect.provideService(HostProcessPlatform, "win32"), Effect.result);
431+
432+
expect(resolved._tag).toBe("Failure");
433+
expect(statCalls).toBe(0);
434+
}).pipe(Effect.provide(failingListingLayer(reason, () => (statCalls += 1))));
435+
});
436+
}
442437
});
443438

444439
effectIt.layer(NodeServices.layer)("resolveSpawnCommand", (it) => {

‎packages/shared/src/shell.ts‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -508,11 +508,19 @@ const PATH_LISTING_CACHE_TTL_NANOS = 30_000_000_000n;
508508
const PATH_LISTING_CACHE_MAX_ENTRIES = 256;
509509

510510
interface PathListingCacheEntry {
511-
/** `null` when the directory cannot be listed. */
511+
/** `null` when the listing failed but the directory may still hold commands. */
512512
readonly names: ReadonlySet<string> | null;
513513
readonly expiresAtNanos: bigint;
514514
}
515515

516+
// Failure reasons that prove the PATH entry can never hold a command, so an
517+
// empty listing is the correct answer.
518+
const UNUSABLE_DIRECTORY_REASONS: ReadonlySet<string> = new Set([
519+
"NotFound",
520+
"BadResource",
521+
"BadArgument",
522+
]);
523+
516524
// The cache lives in the Effect environment (like HostProcessPlatform above)
517525
// so tests and embedders can provide an isolated instance; the default is a
518526
// single process-wide map shared by all consumers.
@@ -525,9 +533,9 @@ export const PathListingCache = Context.Reference<Map<string, PathListingCacheEn
525533

526534
/**
527535
* Lists the file names in a PATH directory, memoized for
528-
* {@link PATH_LISTING_CACHE_TTL_NANOS}. A missing or invalid directory lists as
529-
* empty. A directory that denies read permission lists as `null`, which tells
530-
* callers to probe candidate paths directly.
536+
* {@link PATH_LISTING_CACHE_TTL_NANOS}. A directory that can never hold a
537+
* command lists as empty; see {@link UNUSABLE_DIRECTORY_REASONS}. Any other
538+
* failure lists as `null`, which tells callers to probe candidate paths directly.
531539
*/
532540
const listPathDirectory = Effect.fn("shell.listPathDirectory")(function* (
533541
directory: string,
@@ -545,7 +553,7 @@ const listPathDirectory = Effect.fn("shell.listPathDirectory")(function* (
545553
const entries = yield* fileSystem.readDirectory(directory).pipe(
546554
Effect.catchTags({
547555
PlatformError: (error) =>
548-
Effect.succeed(error.reason._tag === "PermissionDenied" ? null : []),
556+
Effect.succeed(UNUSABLE_DIRECTORY_REASONS.has(error.reason._tag) ? [] : null),
549557
}),
550558
);
551559
const names = entries === null ? null : new Set(entries.map((e) => e.toLowerCase()));

0 commit comments

Comments
 (0)