Asks the filesystem what is at a typed path — one of four answers, and never a thrown error.

findPath and not resolve: path.resolve is imported in almost every file in this codebase and does something else entirely, so Files.resolve(…) beside path.resolve(…) was two lines apart and two different jobs. Grepping for callers of one found ninety files using the other.

Synchronous on purpose, and measured: statSync is 0.0018ms against fs.promises.stat's 0.0265ms — fourteen times, because async goes through libuv's thread pool — and the prefill walk does one per path segment. There is nothing to overlap it with either: one path, one command, somebody waiting at a prompt. Going async would also drag .cat and .tree from synchronous mains to asynchronous ones for no gain at all.

Nothing here can be replaced by a line or two of plain fs: three of the four answers are, but prefill is a walk up the path looking for the longest run that is a real directory, and it is what makes a mistyped path cost a few keystrokes instead of all of them.

import { findPath } from './path-argument.ts';

findPath('lib/nowhere.ts', process.cwd()); // { kind: 'missing', prefill: 'lib/' }
findPath('lib', process.cwd()); // { kind: 'directory', prefill: 'lib/' }