@promptci/core 0.2.1 → 0.3.0

package/dist/command-validity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-validity.d.ts","sourceRoot":"","sources":["../src/command-validity.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAqLhD,8FAA8F;AAC9F,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAK3C,CAAC;AA+mBH;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,WAAW,GAAG,aAAa,EAAE,CAG3E;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB;;;;;;;;OAQG;IACH,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CAC5C,CAAC;AAQF,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,eAAe,CAOrE"}
+{"version":3,"file":"command-validity.d.ts","sourceRoot":"","sources":["../src/command-validity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAoUhD,8FAA8F;AAC9F,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAK3C,CAAC;AAusBH;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,WAAW,GAAG,aAAa,EAAE,CAG3E;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB;;;;;;;;OAQG;IACH,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CAC5C,CAAC;AAQF,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,eAAe,CAOrE"}

package/dist/command-validity.js

@@ -1,11 +1,11 @@
-import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { fencedBlocks, scanFencedLines } from './markdown-fences.js';
 import { fileIdPath } from './finding-id.js';
 import { anyWorkspaceHasScript, isKnownBinary, selectWorkspaces } from './workspace-manifests.js';
 import { makefileDefines, readMakefile } from './makefile.js';
-import { realPathWithinRoot } from './path-containment.js';
+import { incompleteCheckIssue, isAbsoluteAnywhere, treeFor } from './repo-tree.js';
+import { closestUniqueMatch, isMechanicalRename } from './close-match.js';
 /**
  * Command Validity Detector
  *
@@ -19,9 +19,24 @@ import { realPathWithinRoot } from './path-containment.js';
  *  - Prose patterns like "run pnpm test"
  *  - Multi-command lines joined with && are split and each segment validated
  *
+ * Every path a command names is looked up through RepoTree (pcic-x1vl, the
+ * dead-reference containment of pcic-xhzb): inside the scan root only, with
+ * exact case. A path that leaves the root is not checked, and a directory that
+ * cannot be listed leaves its commands unchecked and named in one "check
+ * incomplete" warning instead of reported as missing.
+ *
  * Findings are heuristic — cautious wording is intentional.
  */
 // ── Helpers ───────────────────────────────────────────────────────────────────
+/** Occurrences of a plain substring in one line of text (pcic-oonz). */
+function countOnLine(line, needle) {
+    if (!needle)
+        return 0;
+    let count = 0;
+    for (let at = line.indexOf(needle); at !== -1; at = line.indexOf(needle, at + needle.length))
+        count++;
+    return count;
+}
 /** Stable per-finding ID based on file + command text. */
 function issueId(filePath, cmdText) {
     const hash = crypto
@@ -31,30 +46,101 @@ function issueId(filePath, cmdText) {
         .slice(0, 12);
     return `cmd-validity-${hash}`;
 }
-/** Returns true when a repo-relative path exists on disk. */
-function fileExists(repoRoot, relativePath) {
-    try {
-        const full = path.resolve(repoRoot, relativePath);
-        return fs.existsSync(full);
-    }
-    catch {
-        return false;
+/**
+ * Returned when the verdict depends on a directory that could not be listed:
+ * the command is neither validated nor reported, and the scan says what it
+ * skipped (pcic-x1vl, as dead-references does since pcic-xhzb).
+ */
+const UNJUDGED = Symbol('unjudged');
+/** Separators in a documented path: `/` everywhere, `\` too where the platform treats it as one. */
+const PATH_SEPARATORS = path.sep === '\\' ? /[\\/]/ : /\//;
+/**
+ * pcic-x1vl: `rel`, a path a command names, joined to `fromDir` (inside the
+ * root) one segment at a time; `null` when the path cannot be placed inside
+ * the scan root without knowing where the root is. That is:
+ * - absolute in any platform's form (`/x`, `C:\x`, `C:x`, `\\host\x`), even
+ *   when it happens to point into the root: its verdict would depend on where
+ *   the repository is checked out;
+ * - computed from the environment (`~/x`, `$HOME/x`, `%APPDATA%\x`, backticks);
+ * - climbing above the root at any point, even when a later segment names the
+ *   root's own directory again (`../<root name>/x`): resolving it would make
+ *   the verdict depend on, and so reveal, the name of the directory the scan
+ *   runs in.
+ */
+function withinRoot(tree, fromDir, rel) {
+    if (isAbsoluteAnywhere(rel) || /^~|[$`%]/.test(rel))
+        return null;
+    const parts = path.relative(tree.root, fromDir).split(path.sep).filter(Boolean);
+    if (parts.includes('..') || path.isAbsolute(parts.join(path.sep)))
+        return null;
+    for (const segment of rel.split(PATH_SEPARATORS)) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment !== '..')
+            parts.push(segment);
+        else if (parts.pop() === undefined)
+            return null;
     }
+    return path.join(tree.root, ...parts);
 }
-function isDirectory(repoRoot, relativePath) {
-    try {
-        return fs.statSync(path.resolve(repoRoot, relativePath)).isDirectory();
-    }
-    catch {
-        return false;
-    }
+/**
+ * pcic-x1vl: what the repository holds at `rel`, a path a command names,
+ * resolved against the command's directory. The only way this detector asks
+ * the filesystem about such a path. A path {@link withinRoot} cannot place is
+ * `outside` before any lookup, and RepoTree never touches anything outside the
+ * scan root: one through a committed link out of the tree is `outside` too.
+ * Names match with exact case, so the verdict is the same on every platform,
+ * and the same as on Linux and in CI.
+ */
+function locate(tree, baseDir, rel) {
+    const abs = withinRoot(tree, baseDir, rel);
+    return abs === null ? { state: 'outside' } : tree.lookup(abs);
 }
-function readPackageScripts(repoRoot, packageJsonPath) {
-    // A manifest committed as a symlink to a file outside the repo is not read.
-    if (!realPathWithinRoot(repoRoot, packageJsonPath))
+/**
+ * The finding for a path a command needs, by what {@link locate} found.
+ * pcic-x1vl: a path outside the scan root is not judged, whether or not it
+ * exists. Reporting it would claim a file is missing without having looked,
+ * and checking it would tell whoever wrote the instruction file whether a path
+ * on the scanning machine exists (in the hosted product, the server's). A
+ * monorepo package scanned on its own can legitimately run `../../scripts/x.sh`.
+ */
+function missingUnless(found, message) {
+    if (found.state === 'missing')
+        return message;
+    if (found.state === 'unreadable')
+        return UNJUDGED;
+    return null;
+}
+/**
+ * The name and scripts of a package.json; `null` when there is none to read
+ * (or it does not parse); `unreadable` when a directory on the way could not
+ * be listed, so whether it exists is unknown; `unfetched` when a caller's
+ * inventory says the manifest is there but its bytes were never fetched
+ * (pcic-csf) — nothing failed, so callers stay silent rather than warn.
+ */
+function readPackageScripts(tree, packageJsonPath) {
+    // pcic-x1vl: looked up through the tree, so a manifest path that leaves the
+    // root (`cd` through a link out of the tree) is never touched, and a
+    // manifest committed as a link out of the tree is not read.
+    const found = tree.lookup(packageJsonPath);
+    if (found.state === 'unreadable')
+        return 'unreadable';
+    if (found.state !== 'found' || found.isDir)
+        return null;
+    // pcic-csf: a caller's inventory can say the manifest is there without its
+    // bytes being on disk. Its scripts are then unknown, not absent — reporting
+    // them missing is the false positive the inventory exists to remove. The two
+    // "cannot read" answers stay apart: `unreadable` is a real failure the scan
+    // should name, `unfetched` is nothing to name (see RepoTree.readText).
+    const read = tree.readText(packageJsonPath);
+    if (read.state === 'unreadable' || read.state === 'too-large')
+        return 'unreadable';
+    if (read.state === 'unfetched')
+        return 'unfetched';
+    if (read.state !== 'found')
         return null;
     try {
-        const raw = fs.readFileSync(packageJsonPath, 'utf8');
+        const raw = read.content;
         const parsed = JSON.parse(raw);
         if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
             return null;
@@ -92,28 +178,37 @@ function normalizePnpmFilter(value) {
         .replace(/^!/, '')
         .trim();
 }
-function workspacePackageJsonCandidates(repoRoot, selector) {
+/**
+ * The package.json files a workspace selector may name. `complete` is false
+ * when a workspace directory could not be listed (pcic-x1vl): a selector that
+ * matches nothing may still name a package in it.
+ */
+function workspacePackageJsonCandidates(tree, selector) {
     const candidates = new Set();
+    let complete = true;
     const selectorAsPath = selector.replace(/\\/g, '/');
     if (selectorAsPath.startsWith('.') || selectorAsPath.includes('/')) {
-        candidates.add(path.join(repoRoot, selectorAsPath, 'package.json'));
+        // pcic-x1vl: a selector path that leaves the root is not looked up.
+        const dir = withinRoot(tree, tree.root, selectorAsPath);
+        if (dir !== null)
+            candidates.add(path.join(dir, 'package.json'));
     }
     for (const dir of ['apps', 'packages', 'libs']) {
-        const absDir = path.join(repoRoot, dir);
-        try {
-            for (const entry of fs.readdirSync(absDir, { withFileTypes: true })) {
-                if (entry.isDirectory()) {
-                    candidates.add(path.join(absDir, entry.name, 'package.json'));
-                }
+        const absDir = path.join(tree.root, dir);
+        const entries = tree.entries(absDir);
+        if (entries === 'unreadable')
+            complete = false;
+        if (typeof entries === 'string')
+            continue; // workspace directory absent (or not inside the root)
+        for (const entry of entries.values()) {
+            if (entry.isDirectory()) {
+                candidates.add(path.join(absDir, entry.name, 'package.json'));
             }
         }
-        catch {
-            // Workspace directory absent.
-        }
     }
-    return [...candidates];
+    return { candidates: [...candidates], complete };
 }
-function workspaceHasScript(context, selector, scriptName) {
+function workspaceHasScript(context, tree, selector, scriptName) {
     const normalizedSelector = normalizePnpmFilter(selector);
     if (!normalizedSelector)
         return false;
@@ -123,9 +218,16 @@ function workspaceHasScript(context, selector, scriptName) {
     if (context.workspaces) {
         return selectWorkspaces(context, normalizedSelector).some((ws) => !!ws.scripts[scriptName]);
     }
-    for (const candidate of workspacePackageJsonCandidates(context.repoRoot, normalizedSelector)) {
-        const pkg = readPackageScripts(context.repoRoot, candidate);
-        if (!pkg)
+    const { candidates, complete } = workspacePackageJsonCandidates(tree, normalizedSelector);
+    let unknown = !complete;
+    let silent = false;
+    for (const candidate of candidates) {
+        const pkg = readPackageScripts(tree, candidate);
+        if (pkg === 'unreadable')
+            unknown = true;
+        if (pkg === 'unfetched')
+            silent = true;
+        if (!pkg || pkg === 'unreadable' || pkg === 'unfetched')
             continue;
         const packageDir = path.dirname(candidate).replace(/\\/g, '/');
         const relDir = path.relative(context.repoRoot, packageDir).replace(/\\/g, '/');
@@ -135,7 +237,10 @@ function workspaceHasScript(context, selector, scriptName) {
         if (selectorMatches && !!pkg.scripts[scriptName])
             return true;
     }
-    return false;
+    if (unknown)
+        return 'unknown';
+    // A manifest that exists but was never fetched could define the script.
+    return silent ? 'silent' : false;
 }
 /** Returns true when a path string looks like a file reference (not a flag). */
 function isLikelyFilePath(str) {
@@ -188,9 +293,10 @@ function resolveCwd(current, target) {
     if (current === null)
         return null;
     const cleaned = target.replace(/^['"]|['"]$/g, '').trim();
-    if (!cleaned || cleaned.startsWith('/') || cleaned.startsWith('~') || /^[a-zA-Z]:[\\/]/.test(cleaned)) {
-        return null; // absolute or home path — not resolvable to a repo-relative dir
-    }
+    // Absolute in any platform's form (`/x`, `C:\x`, drive-relative `C:x`, `\\host\x`)
+    // or home: not resolvable to a repo-relative dir (pcic-x1vl: on every platform alike).
+    if (!cleaned || isAbsoluteAnywhere(cleaned) || cleaned.startsWith('~'))
+        return null;
     // `cd -`, `cd $DIR`, `cd "$(git rev-parse --show-toplevel)"`, `cd %TEMP%`,
     // `cd <dir>`: computed or placeholder targets name no knowable directory.
     if (/^-|[$`%<>{}*?]/.test(cleaned))
@@ -415,7 +521,7 @@ function cwdOverride(parts) {
     }
     return undefined;
 }
-function findMissingScript(context, cwd, parts, scriptName, builtins, tool, lookup, onScript) {
+function findMissingScript(context, tree, cwd, parts, scriptName, builtins, tool, lookup, onScript, suggest) {
     const names = scriptName.includes('/')
         ? scriptName.split('/').map((s) => s.trim()).filter(Boolean)
         : [scriptName];
@@ -435,17 +541,45 @@ function findMissingScript(context, cwd, parts, scriptName, builtins, tool, look
     }
     const selector = lookup.workspaceName ?? workspaceSelector(tool, parts);
     const allWorkspaces = runsInAllWorkspaces(tool, parts);
-    const inWorkspaceScope = (name) => allWorkspaces ? anyWorkspaceHasScript(context, name) : workspaceHasScript(context, selector, name);
+    const inWorkspaceScope = (name) => allWorkspaces ? anyWorkspaceHasScript(context, name) : workspaceHasScript(context, tree, selector, name);
     // With discovered workspaces, an explicit selector means ONLY the selected
     // packages: the root manifest's same-named script is not what runs, and a
     // selector that matches no package is itself the error.
     const selectedWorkspaces = selector && context.workspaces && !allWorkspaces
         ? selectWorkspaces(context, selector.replace(/^['"]|['"]$/g, '').replace(/^\.\.\./, '').replace(/\.\.\.$/, '').trim())
         : undefined;
+    /**
+     * pcic-oonz: offers the one close match for a name that is about to be
+     * reported missing, from the manifest(s) that would actually have run it.
+     *
+     * Deliberately silent for the slash shorthand (`pnpm lint/typecheck`): the
+     * rewrite would have to edit one component of a token that documents several
+     * scripts, which is not the mechanical single-token substitution the fix
+     * engine applies. Silent too whenever a workspace selector is in play
+     * without discovered workspaces to resolve it against — the candidate pool
+     * would then be the root manifest, which is not where the script would run.
+     */
+    const propose = (name, pool) => {
+        if (!suggest || names.length !== 1)
+            return;
+        const candidate = closestUniqueMatch(name, pool);
+        if (candidate !== undefined) {
+            suggest({ missing: name, candidate, mechanical: isMechanicalRename(name, candidate) });
+        }
+    };
+    const scopedToWorkspaces = selector !== undefined || allWorkspaces;
     const inSubdir = cwd !== '.' && cwd !== '';
     const dirPkg = inSubdir
-        ? readPackageScripts(context.repoRoot, path.join(context.repoRoot, cwd, 'package.json'))
+        ? readPackageScripts(tree, path.join(tree.root, cwd, 'package.json'))
         : null;
+    // pcic-csf: the manifest is there but was never fetched. Nothing failed and
+    // there is no location to name, so say nothing at all — a "check incomplete"
+    // warning here would name zero locations and tell the reader nothing.
+    if (dirPkg === 'unfetched')
+        return null;
+    // pcic-x1vl: a directory on the way could not be listed — say so, don't guess.
+    if (dirPkg === 'unreadable')
+        return UNJUDGED;
     // cd'd into a directory whose package.json we can't read — don't guess.
     if (inSubdir && !dirPkg)
         return null;
@@ -471,6 +605,13 @@ function findMissingScript(context, cwd, parts, scriptName, builtins, tool, look
             const target = selectedWorkspaces.length === 1
                 ? `${selectedWorkspaces[0].name ?? selectedWorkspaces[0].dir} (${selectedWorkspaces[0].dir}/package.json)`
                 : `the ${selectedWorkspaces.length} workspaces selected by "${selector}"`;
+            // The selected packages ARE the manifests that would run the script — all
+            // of them, so a candidate only SOME of them define would still leave the
+            // command broken where it is missing. The pool is therefore the
+            // intersection of their script names (which for one selected package is
+            // simply that package's scripts).
+            const pools = selectedWorkspaces.map((ws) => Object.keys(ws.scripts));
+            propose(name, pools.slice(1).reduce((shared, pool) => shared.filter((n) => pool.includes(n)), pools[0] ?? []));
             return `${tool} script "${name}" does not appear in ${target} scripts`;
         }
         if (dirPkg) {
@@ -481,15 +622,26 @@ function findMissingScript(context, cwd, parts, scriptName, builtins, tool, look
             // script.
             if (dirPkg.scripts[name])
                 continue;
-            if (inWorkspaceScope(name))
+            const inWorkspace = inWorkspaceScope(name);
+            if (inWorkspace === true || inWorkspace === 'silent')
                 continue;
+            if (inWorkspace === 'unknown')
+                return UNJUDGED;
+            if (!scopedToWorkspaces)
+                propose(name, Object.keys(dirPkg.scripts));
             return `${tool} script "${name}" does not appear in ${cwd}/package.json scripts`;
         }
         // Repo-root context: the workspace target(s) or the root manifest.
-        if (inWorkspaceScope(name))
+        const inWorkspace = inWorkspaceScope(name);
+        if (inWorkspace === true || inWorkspace === 'silent')
             continue;
         if (context.packageJson.scripts[name])
             continue;
+        // pcic-x1vl: a selected workspace may define it in a directory that could not be read.
+        if (inWorkspace === 'unknown')
+            return UNJUDGED;
+        if (!scopedToWorkspaces)
+            propose(name, Object.keys(context.packageJson.scripts));
         return `${tool} script "${name}" does not appear in package.json scripts`;
     }
     return null;
@@ -509,7 +661,7 @@ const BUILTINS_BY_TOOL = {
  * to an installed binary), `yarn workspace <name> <script>`, and workspace or
  * directory selectors.
  */
-function validatePackageManagerScript(tool, parts, context, cwd, baseDir, onScript) {
+function validatePackageManagerScript(tool, parts, context, tree, cwd, baseDir, onScript, suggest) {
     const subIdx = firstNonFlagArgIndex(parts);
     const sub = parts[subIdx];
     if (!sub)
@@ -540,15 +692,28 @@ function validatePackageManagerScript(tool, parts, context, cwd, baseDir, onScri
         if (!explicitRun && BUN_BUILTINS.has(scriptName))
             return null;
         if (isLikelyFilePath(scriptName)) {
-            if (baseDir && /\.[cm]?[jt]sx?$/.test(scriptName) && !fileExists(baseDir, scriptName)) {
-                return `File "${scriptName}" referenced by "bun" does not appear to exist in the repository`;
+            if (baseDir && /\.[cm]?[jt]sx?$/.test(scriptName)) {
+                return missingUnless(locate(tree, baseDir, scriptName), `File "${scriptName}" referenced by "bun" does not appear to exist in the repository`);
             }
             return null;
         }
     }
-    return findMissingScript(context, cwd, parts, scriptName, BUILTINS_BY_TOOL[tool], tool, 
+    // pcic-oonz: the rewrite keeps everything up to and including the script
+    // name, so the text looked for on the line is the command as documented
+    // (`npm run bulid`, `pnpm --filter web lnit`) rather than a bare word.
+    const prefix = parts.slice(0, nameIdx).join(' ');
+    const onSuggestion = suggest
+        ? ({ missing, candidate, mechanical }) => suggest({
+            find: prefix ? `${prefix} ${missing}` : missing,
+            replace: prefix ? `${prefix} ${candidate}` : candidate,
+            missing,
+            candidate,
+            mechanical,
+        })
+        : undefined;
+    return findMissingScript(context, tree, cwd, parts, scriptName, BUILTINS_BY_TOOL[tool], tool, 
     // npm/pnpm `run` only run scripts; every other form can fall through to a binary.
-    { allowBinary: !(explicitRun && (tool === 'npm' || tool === 'pnpm')), workspaceName }, onScript);
+    { allowBinary: !(explicitRun && (tool === 'npm' || tool === 'pnpm')), workspaceName }, onScript, onSuggestion);
 }
 // ── make targets ──────────────────────────────────────────────────────────────
 /** make options whose value is the NEXT token (unless attached: `-Cdir`, `-j4`). */
@@ -571,7 +736,7 @@ const MAKE_FLAGS_WITH_OPTIONAL_NUMBER = new Set(['-j', '-l', '--jobs', '--load-a
  * names make could build from a same-stem source via its built-in implicit
  * rules (`make hello` next to `hello.c`) are never reported.
  */
-function validateMakeTargets(parts, context, cwd, makefileFor) {
+function validateMakeTargets(parts, tree, cwd, makefileFor) {
     let dir = cwd;
     const goals = [];
     for (let i = 1; i < parts.length; i++) {
@@ -608,7 +773,6 @@ function validateMakeTargets(parts, context, cwd, makefileFor) {
     const facts = makefileFor(dir);
     if (!facts || facts.unverifiable)
         return null;
-    const baseDir = dir === '.' ? context.repoRoot : path.join(context.repoRoot, dir);
     let entries;
     for (const goal of goals) {
         const target = goal.replace(/^['"]|['"]$/g, '');
@@ -617,11 +781,13 @@ function validateMakeTargets(parts, context, cwd, makefileFor) {
         if (makefileDefines(facts, target))
             continue;
         // make can build `target` from `target.c` etc. with its built-in rules.
-        try {
-            entries ??= fs.readdirSync(baseDir);
-        }
-        catch {
-            entries = [];
+        // Listed through the tree (pcic-x1vl), like the Makefile it found there;
+        // a directory it cannot list leaves those rules unknowable, so stay silent.
+        if (entries === undefined) {
+            const listing = tree.entries(dir);
+            if (typeof listing === 'string')
+                return null;
+            entries = [...listing.keys()];
         }
         if (entries.some((e) => e === target || e.startsWith(`${target}.`)))
             continue;
@@ -643,15 +809,16 @@ function validateSegment(seg, context, cwd = '.', onScript, opts = {}) {
     if (parts.length === 0)
         return null;
     const tool = parts[0];
+    const tree = opts.tree ?? treeFor(context);
     // Base directory for file-existence checks — respects a `cd`-established cwd.
     const baseDir = cwd === null
         ? null
         : cwd !== '.' && cwd !== ''
-            ? path.join(context.repoRoot, cwd)
-            : context.repoRoot;
+            ? path.join(tree.root, cwd)
+            : tree.root;
     // ── Package manager scripts ────────────────────────────────────────────────
     if (tool === 'pnpm' || tool === 'npm' || tool === 'yarn' || tool === 'bun') {
-        return validatePackageManagerScript(tool, parts, context, cwd, baseDir, onScript);
+        return validatePackageManagerScript(tool, parts, context, tree, cwd, baseDir, onScript, opts.suggestScript);
     }
     // ── File-executing commands ────────────────────────────────────────────────
     const FILE_EXECUTORS = ['node', 'tsx', 'ts-node', 'bash', 'sh', 'python', 'python3'];
@@ -659,8 +826,10 @@ function validateSegment(seg, context, cwd = '.', onScript, opts = {}) {
         // Skip flags (and known flags' values, e.g. `--loader ts-node/esm`) to
         // find the actual script/file argument.
         const filePart = parts[firstNonFlagArgIndex(parts)];
-        if (filePart && isLikelyFilePath(filePart) && !fileExists(baseDir, filePart)) {
-            return `File "${filePart}" referenced by "${tool}" does not appear to exist in the repository`;
+        if (filePart && isLikelyFilePath(filePart)) {
+            const verdict = missingUnless(locate(tree, baseDir, filePart), `File "${filePart}" referenced by "${tool}" does not appear to exist in the repository`);
+            if (verdict !== null)
+                return verdict;
         }
     }
     // ── make <target> ──────────────────────────────────────────────────────────
@@ -672,39 +841,47 @@ function validateSegment(seg, context, cwd = '.', onScript, opts = {}) {
         // A code span like `make sure` is English, not a make invocation.
         if (!opts.fenced && parts.length === 2 && MAKE_PROSE_WORDS.has(parts[1].toLowerCase()))
             return null;
-        return validateMakeTargets(parts, context, makeCwd, opts.makefileFor);
+        return validateMakeTargets(parts, tree, makeCwd, opts.makefileFor);
     }
     // ── Direct script invocations: ./scripts/foo.sh ───────────────────────────
     if (baseDir && (tool.startsWith('./') || tool.startsWith('../'))) {
+        const found = locate(tree, baseDir, tool);
         // pcic-2b6.8: a bare `./src` or `./docs/` in an inline code span is a
         // directory mention, not a script invocation — it is dead-references' to
         // judge. Only a shell-fence line (meant to be run) still reports an absent
         // extensionless `./gradlew`; an existing directory is never a missing script.
         if (parts.length === 1 && path.extname(tool.replace(/\/+$/, '')) === '') {
-            if (isDirectory(baseDir, tool))
+            if (found.state === 'found' && found.isDir)
                 return null;
             if (!opts.fenced || tool.endsWith('/'))
                 return null;
         }
-        if (!fileExists(baseDir, tool)) {
-            return `Script "${tool}" does not appear to exist in the repository`;
-        }
+        const verdict = missingUnless(found, `Script "${tool}" does not appear to exist in the repository`);
+        if (verdict !== null)
+            return verdict;
     }
     // ── docker compose -f <file> ───────────────────────────────────────────────
     if (baseDir && tool === 'docker' && parts[1] === 'compose' && parts.includes('-f')) {
         const fIdx = parts.indexOf('-f');
         const composeFile = parts[fIdx + 1];
-        if (composeFile && isLikelyFilePath(composeFile) && !fileExists(baseDir, composeFile)) {
-            return `Docker Compose file "${composeFile}" does not appear to exist in the repository`;
+        if (composeFile && isLikelyFilePath(composeFile)) {
+            const verdict = missingUnless(locate(tree, baseDir, composeFile), `Docker Compose file "${composeFile}" does not appear to exist in the repository`);
+            if (verdict !== null)
+                return verdict;
         }
     }
     // ── dotnet test <project-or-solution> ─────────────────────────────────────
     if (baseDir && tool === 'dotnet' && parts[1] === 'test' && parts[2]) {
         const target = parts[2];
         if (isLikelyFilePath(target)) {
-            if (!fileExists(baseDir, target)) {
-                return `dotnet test target "${target}" does not appear to exist`;
-            }
+            const found = locate(tree, baseDir, target);
+            // Outside the root: not judged at all, so the extension check below
+            // cannot tell an existing outside file from a missing one either.
+            if (found.state === 'outside')
+                return null;
+            const verdict = missingUnless(found, `dotnet test target "${target}" does not appear to exist`);
+            if (verdict !== null)
+                return verdict;
             if (!/\.(sln|csproj|fsproj)$/.test(target)) {
                 return `dotnet test target "${target}" should be a .sln, .csproj, or .fsproj file`;
             }
@@ -742,6 +919,9 @@ function computeCommandAnalysis(context) {
     const issues = [];
     const evaluatedScripts = new Map();
     const reported = new Set();
+    const tree = treeFor(context);
+    // pcic-x1vl: commands left unchecked because part of the tree could not be listed.
+    const unchecked = new Map();
     // Makefiles by repo-relative directory: the root one comes from the context,
     // subdirectory ones (`make -C dir`, `cd dir && make`) are read once each.
     const makefiles = new Map();
@@ -749,11 +929,14 @@ function computeCommandAnalysis(context) {
         if (dir === '.' || dir === '')
             return context.makefile;
         if (!makefiles.has(dir))
-            makefiles.set(dir, readMakefile(context.repoRoot, dir));
+            makefiles.set(dir, readMakefile(context.repoRoot, dir, tree));
         return makefiles.get(dir);
     };
     for (const file of context.files) {
         const commands = extractCommands(file.content);
+        // pcic-oonz: the file's own lines, to confirm a rewrite's `find` text is
+        // unambiguous there before the finding claims to be auto-applicable.
+        const contentLines = file.content.split(/\r?\n/);
         const evaluated = new Set();
         const fileDir = path.relative(context.repoRoot, path.dirname(file.path)).replace(/\\/g, '/') || '.';
         evaluatedScripts.set(file.path, evaluated);
@@ -764,33 +947,83 @@ function computeCommandAnalysis(context) {
             // (prose, which never carries a `cd`) runs from the root; null stays
             // unverifiable.
             const cwd = cmd.cwd === undefined ? '.' : cmd.cwd;
+            let rewrite;
             const error = validateSegment(cmd.text, context, cwd, (name) => evaluated.add(`${cmd.line}:${name}`), {
                 fenced: cmd.fenced === true,
                 makefileFor,
                 fileDir: fileDir.startsWith('..') ? '.' : fileDir,
+                tree,
+                suggestScript: (r) => { rewrite = r; },
             });
             if (!error)
                 continue;
+            if (error === UNJUDGED) {
+                const evidence = `Not checked: \`${cmd.text}\``;
+                const entry = unchecked.get(evidence) ?? { filePaths: new Set(), fileLines: new Map(), evidence };
+                entry.filePaths.add(file.path);
+                const seen = entry.fileLines.get(file.path);
+                if (seen === undefined || cmd.line < seen)
+                    entry.fileLines.set(file.path, cmd.line);
+                unchecked.set(evidence, entry);
+                continue;
+            }
             // Deduplicate same command text appearing twice in the same file
             const dedupeKey = `${file.path}|${cmd.text}`;
             if (reported.has(dedupeKey))
                 continue;
             reported.add(dedupeKey);
+            // pcic-oonz: a MISSPELLED script name with exactly one close match in the
+            // manifest that would have run it is a mechanical rewrite — provided the
+            // difference is a typo rather than a reference to a real sibling script
+            // (`isMechanicalRename`; `test:api` vs `test:app` is not), and the text
+            // to replace appears exactly once on the line, so the edit cannot land on
+            // another command that shares it.
+            const fix = rewrite?.mechanical && countOnLine(contentLines[cmd.line - 1] ?? '', rewrite.find) === 1
+                ? rewrite
+                : undefined;
+            // A candidate too close to a different script to apply is still worth
+            // naming — cautiously, and in the recommendation rather than the summary,
+            // so nothing reads as a verdict.
+            const hint = rewrite && !fix
+                ? ` The manifest defines "${rewrite.candidate}", which is close to "${rewrite.missing}"; ` +
+                    'it may be what was meant, but it is near enough to be a different script, so check before changing it.'
+                : '';
             issues.push({
                 id: issueId(fileIdPath(file), cmd.text),
                 severity: 'warning',
                 category: 'command_validity',
                 title: `Possible reference to missing command or file: \`${cmd.text.split(/\s+/).slice(0, 3).join(' ')}\``,
-                summary: error,
+                summary: fix
+                    ? `${error}. The closest script name the manifest defines is "${fix.candidate}".`
+                    : error,
                 filePaths: [file.path],
                 locations: [{ filePath: file.path, startLine: cmd.line, endLine: cmd.line }],
                 evidence: [`Command: \`${cmd.text}\``, `In file: ${file.path}`],
                 recommendation: 'Verify the command. If the script was renamed, update the instruction file. ' +
-                    'If it is an illustrative example, wrap it in a placeholder like <script-name> to suppress this finding.',
+                    'If it is an illustrative example, wrap it in a placeholder like <script-name> to suppress this finding.' +
+                    hint,
+                ...(fix
+                    ? {
+                        fixRecipe: `Rename the script in this command: \`${fix.find}\` -> \`${fix.replace}\`.`,
+                        // `applyFixRecipe` replaces that one occurrence on that one line.
+                        autoApplySafe: true,
+                        fixEdits: [{ filePath: file.path, line: cmd.line, find: fix.find, replace: fix.replace }],
+                    }
+                    : {}),
                 confidence: 0.8,
             });
         }
     }
+    if (unchecked.size > 0) {
+        issues.push(incompleteCheckIssue(tree, [...unchecked.values()], {
+            id: issueId('', '(command check incomplete)'),
+            category: 'command_validity',
+            title: 'Command check incomplete: part of the repository could not be read',
+            unit: 'command',
+            unknown: 'The files they name may or may not exist',
+            finding: 'missing-command',
+        }));
+    }
     return { issues, evaluatedScripts };
 }
 //# sourceMappingURL=command-validity.js.map