@promptci/core 0.3.0 → 0.4.0

package/dist/command-validity.js

@@ -2,10 +2,12 @@ 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 { anyWorkspaceHasScript, hasScript, isKnownBinary, selectWorkspaces } from './workspace-manifests.js';
 import { makefileDefines, readMakefile } from './makefile.js';
 import { incompleteCheckIssue, isAbsoluteAnywhere, treeFor } from './repo-tree.js';
 import { closestUniqueMatch, isMechanicalRename } from './close-match.js';
+import { htmlCommentLines } from './sample-text.js';
+import { commandContext, directoryTokens, lineStructure } from './command-context.js';
 /**
  * Command Validity Detector
  *
@@ -28,6 +30,42 @@ import { closestUniqueMatch, isMechanicalRename } from './close-match.js';
  * Findings are heuristic — cautious wording is intentional.
  */
 // ── Helpers ───────────────────────────────────────────────────────────────────
+/**
+ * pcic-1ik0.2: why a script rewrite must NOT be applied unseen, as a clause that
+ * completes "it may be what was meant, but ...": `undefined` only when every
+ * condition for an unattended edit holds. An edit lands without a person looking,
+ * on a repository that is not ours: a missed fix costs nothing, a wrong one lands
+ * in a stranger's repo. Heuristics over prose do not converge, so the rule is
+ * default-deny and structural first:
+ *  - RULE 1: the repository is a single package (see {@link singlePackageRepo}), so
+ *    there is exactly one manifest the command can mean, whatever the prose says;
+ *    and the closest name is in that root manifest;
+ *  - RULE 2: nothing cautionary or negating frames the command, in a deliberately
+ *    wide scope (the whole heading chain, block, paragraph, enclosing list items,
+ *    table, blockquote and `<details>` summary, and a trailing comment);
+ *  - the command is not in a comment or an indented block, and runs from the root
+ *    with no `cd` before it in its block and no `--cwd`/`--prefix`/`-C`.
+ */
+function editBlocker(cmd, lines, inComment, context, earlierCd, singlePackage, viaRoot) {
+    if (inComment)
+        return 'this command is inside an HTML comment';
+    if (!cmd.fenced && /^(?: {4}|\t)/.test(lines[cmd.line - 1] ?? ''))
+        return 'this command is in an indented block';
+    if (typeof cmd.cwd === 'string' && cmd.cwd !== '.' && cmd.cwd !== '')
+        return 'this command runs from another directory';
+    // `-C site`, `-Csite`, `--cwd site`, `--cwd=site`.
+    if (/\s(?:--cwd|--dir|--prefix)(?:\s|=)|\s-C/.test(cmd.text))
+        return 'this command runs from another directory';
+    if (earlierCd)
+        return 'an earlier line of its block changes directory';
+    if (context.cautionary)
+        return 'the text around this command reads as an example not to follow, or as a warning';
+    if (!singlePackage)
+        return 'this repository has more than one package, which makes the manifest the command runs against uncertain';
+    if (!viaRoot)
+        return 'the closest name is not in the root manifest';
+    return undefined;
+}
 /** Occurrences of a plain substring in one line of text (pcic-oonz). */
 function countOnLine(line, needle) {
     if (!needle)
@@ -112,12 +150,16 @@ function missingUnless(found, message) {
     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.
+ * The name and scripts of a package.json; `null` when there is none to read;
+ * `unreadable` when a directory on the way could not be listed, so whether the
+ * script exists is unknown; `corrupt` when the manifest is not a JSON object (the
+ * detector says so in one info finding when it relied on that manifest, and
+ * checks nothing against it); `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.
  */
+/** A package.json larger than this is not read: a hostile or generated manifest must not stall a scan. */
+const MAX_MANIFEST_BYTES = 512 * 1024;
 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
@@ -132,18 +174,21 @@ function readPackageScripts(tree, packageJsonPath) {
     // 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')
+    const read = tree.readText(packageJsonPath, { maxBytes: MAX_MANIFEST_BYTES });
+    if (read.state === 'unreadable')
         return 'unreadable';
-    if (read.state === 'unfetched')
+    // Oversized is treated like listed-but-not-downloaded (pcic-1ik0.2): the scripts are unknown,
+    // not absent, and there is nothing a user could fix, so no finding and no warning.
+    if (read.state === 'unfetched' || read.state === 'too-large')
         return 'unfetched';
     if (read.state !== 'found')
         return null;
     try {
         const raw = read.content;
         const parsed = JSON.parse(raw);
+        // A manifest that is not a JSON object is corrupt, not absent.
         if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
-            return null;
+            return 'corrupt';
         const scripts = typeof parsed.scripts === 'object' && parsed.scripts !== null && !Array.isArray(parsed.scripts)
             ? Object.fromEntries(Object.entries(parsed.scripts).filter((entry) => typeof entry[1] === 'string'))
             : {};
@@ -153,8 +198,172 @@ function readPackageScripts(tree, packageJsonPath) {
         };
     }
     catch {
-        return null;
+        // Corrupt JSON is not "no scripts": whether the script exists is unknown.
+        return 'corrupt';
+    }
+}
+/**
+ * A script token that is a glob or placeholder (`build*`, `test:<name>`,
+ * `$SCRIPT`, `${NAME}`, `%NAME%`), never a misspelled name.
+ */
+const SCRIPT_PATTERN_RE = /[*?<>{}[\]$`]|%\w+%/;
+/** Directories walked looking for package.json files, and how deep: bounded so a huge repo cannot stall a scan. */
+const MAX_MANIFEST_DIRS = 2000;
+const MAX_MANIFEST_DEPTH = 12;
+/** Manifests a finding relied on (named by the text, or the directory a `cd` entered) that turned out to be corrupt. */
+const corruptUsed = new WeakMap();
+function noteCorrupt(tree, manifest) {
+    let set = corruptUsed.get(tree);
+    if (!set)
+        corruptUsed.set(tree, (set = new Set()));
+    set.add(manifest);
+}
+const packageIndexCache = new WeakMap();
+/**
+ * Scripts of every package.json under the root outside `.git` and `node_modules`
+ * (dot directories are walked: `.github/actions/release/package.json` is a package).
+ * Breadth-first and sorted, so the same repository always yields the same index;
+ * and it says when it is not the whole picture, so that a caller can tell "defined
+ * nowhere" from "not seen".
+ */
+function packageIndex(tree) {
+    const cached = packageIndexCache.get(tree);
+    if (cached)
+        return cached;
+    const index = { scripts: new Map(), unfetched: [], incomplete: false, foreign: false };
+    const queue = [{ dir: '', depth: 0 }];
+    for (let next = 0; next < queue.length; next++) {
+        if (next >= MAX_MANIFEST_DIRS) {
+            index.incomplete = true;
+            break;
+        }
+        const { dir, depth } = queue[next];
+        const abs = dir ? path.join(tree.root, dir) : tree.root;
+        const listing = tree.entries(abs);
+        if (listing === 'unreadable')
+            index.incomplete = true;
+        if (typeof listing === 'string')
+            continue;
+        const names = [...listing.keys()].sort();
+        if (names.includes('package.json')) {
+            const pkg = readPackageScripts(tree, path.join(abs, 'package.json'));
+            if (pkg === 'unfetched')
+                index.unfetched.push(dir || '.');
+            else if (pkg === 'unreadable' || pkg === 'corrupt')
+                index.incomplete = true;
+            else if (pkg)
+                index.scripts.set(dir || '.', pkg.scripts);
+        }
+        if (names.some((n) => FOREIGN_MANIFESTS.has(n)))
+            index.foreign = true;
+        for (const deno of ['deno.json', 'deno.jsonc']) {
+            if (!names.includes(deno))
+                continue;
+            const text = tree.readText(path.join(abs, deno), { maxBytes: MAX_MANIFEST_BYTES });
+            // Tasks are deno's scripts. A file that cannot be read may hold them.
+            if (text.state !== 'found' || /"tasks"\s*:/.test(text.content))
+                index.foreign = true;
+        }
+        for (const name of names) {
+            const entry = listing.get(name);
+            if (entry.isSymbolicLink()) {
+                // A link that leaves the repository points at content this scan never reads.
+                const target = tree.lookup(path.join(abs, name)).state;
+                if (target === 'outside')
+                    index.foreign = true;
+                else if (target === 'unreadable')
+                    index.incomplete = true;
+                continue;
+            }
+            if (!entry.isDirectory())
+                continue;
+            if (name === 'node_modules' || name === '.git')
+                continue;
+            // A directory below the depth bound could hold a manifest nobody read.
+            if (depth >= MAX_MANIFEST_DEPTH) {
+                index.incomplete = true;
+                continue;
+            }
+            queue.push({ dir: dir ? `${dir}/${name}` : name, depth: depth + 1 });
+        }
+    }
+    packageIndexCache.set(tree, index);
+    return index;
+}
+/** Repo-relative directories (never the root) of the packages that define `script`, sorted. */
+function packagesDefining(context, tree, script) {
+    const dirs = new Set();
+    for (const ws of context.workspaces ?? [])
+        if (ws.dir !== '.' && hasScript(ws.scripts, script))
+            dirs.add(ws.dir);
+    for (const [dir, scripts] of packageIndex(tree).scripts) {
+        if (dir !== '.' && !dir.split('/').some((segment) => segment.startsWith('.')) && hasScript(scripts, script))
+            dirs.add(dir);
+    }
+    return [...dirs].sort();
+}
+/** Files at the repository root that declare a multi-package layout. */
+const WORKSPACE_FILES = ['pnpm-workspace.yaml', 'lerna.json', 'nx.json', 'turbo.json', 'rush.json', '.gitmodules'];
+/** Manifests of other package managers: a repository holding one is not certainly a single npm package. */
+const FOREIGN_MANIFESTS = new Set(['package.yaml', 'package.json5', 'rush.json']);
+const singlePackageCache = new WeakMap();
+/**
+ * pcic-1ik0.2 (RULE 1, structural): true only when the repository is certainly ONE
+ * package: the inventory is complete and fully fetched (no unread manifest, no
+ * unlisted directory, no partial caller inventory), the root package.json is the
+ * only package.json, and nothing declares workspaces (`workspaces` field,
+ * pnpm-workspace.yaml, lerna.json, nx.json, turbo.json). The unattended typo edit
+ * is offered only then: in any other repository which manifest a command runs
+ * against depends on prose, and prose heuristics do not converge.
+ */
+function singlePackageRepo(context, tree) {
+    const cached = singlePackageCache.get(tree);
+    if (cached !== undefined)
+        return cached;
+    const index = packageIndex(tree);
+    let single = !index.incomplete &&
+        !index.foreign &&
+        index.unfetched.length === 0 &&
+        index.scripts.size === 1 &&
+        index.scripts.has('.') &&
+        (tree.inventory === undefined || tree.inventory.complete);
+    if (single && /"workspaces"\s*:/.test(context.packageJson.raw ?? ''))
+        single = false;
+    if (single) {
+        for (const file of WORKSPACE_FILES) {
+            if (tree.lookup(path.join(tree.root, file)).state !== 'missing')
+                single = false;
+        }
     }
+    singlePackageCache.set(tree, single);
+    return single;
+}
+/**
+ * The existing directories among the tokens the text around a command names,
+ * as repo-relative POSIX paths: resolved from the repository root and, failing
+ * that, from the instruction file's own directory. Whether a named directory
+ * defines the script is the caller's check, so a stray mention can only silence
+ * a finding when that directory really holds the script.
+ */
+function resolveHintDirs(tokens, fileDir, tree) {
+    const dirs = [];
+    const seen = new Set();
+    for (const token of tokens) {
+        for (const base of fileDir === '.' ? ['.'] : ['.', fileDir]) {
+            const abs = withinRoot(tree, tree.root, base === '.' ? token : `${base}/${token}`);
+            if (abs === null)
+                continue;
+            const rel = path.relative(tree.root, abs).split(path.sep).join('/');
+            if (!rel || seen.has(rel))
+                continue;
+            const found = tree.lookup(abs);
+            if (found.state !== 'found' || !found.isDir)
+                continue;
+            seen.add(rel);
+            dirs.push(rel);
+        }
+    }
+    return dirs;
 }
 function pnpmFilterValue(parts) {
     for (let i = 1; i < parts.length; i++) {
@@ -216,7 +425,7 @@ function workspaceHasScript(context, tree, selector, scriptName) {
     // `workspaces` globs, any layout). The path-based lookup below is only for
     // contexts built without them.
     if (context.workspaces) {
-        return selectWorkspaces(context, normalizedSelector).some((ws) => !!ws.scripts[scriptName]);
+        return selectWorkspaces(context, normalizedSelector).some((ws) => hasScript(ws.scripts, scriptName));
     }
     const { candidates, complete } = workspacePackageJsonCandidates(tree, normalizedSelector);
     let unknown = !complete;
@@ -225,16 +434,16 @@ function workspaceHasScript(context, tree, selector, scriptName) {
         const pkg = readPackageScripts(tree, candidate);
         if (pkg === 'unreadable')
             unknown = true;
-        if (pkg === 'unfetched')
+        if (pkg === 'unfetched' || pkg === 'corrupt')
             silent = true;
-        if (!pkg || pkg === 'unreadable' || pkg === 'unfetched')
+        if (!pkg || pkg === 'unreadable' || pkg === 'unfetched' || pkg === 'corrupt')
             continue;
         const packageDir = path.dirname(candidate).replace(/\\/g, '/');
         const relDir = path.relative(context.repoRoot, packageDir).replace(/\\/g, '/');
         const selectorMatches = pkg.name === normalizedSelector ||
             relDir === normalizedSelector ||
             relDir.endsWith(`/${normalizedSelector}`);
-        if (selectorMatches && !!pkg.scripts[scriptName])
+        if (selectorMatches && hasScript(pkg.scripts, scriptName))
             return true;
     }
     if (unknown)
@@ -316,6 +525,37 @@ function resolveCwd(current, target) {
     }
     return parts.length === 0 ? '.' : parts.join('/');
 }
+/**
+ * pcic-1ik0.2: what the earlier lines of the fenced block holding line `line` do to
+ * the working directory: whether any `cd`, `pushd` or `popd` came first, and the
+ * directory they leave (`null` when it cannot be known). The detector still judges
+ * each line from the root (CV6); this only feeds the text-names-a-directory logic
+ * and withholds edits.
+ */
+function earlierCd(s, line) {
+    const open = s.opener.get(line);
+    let dir = '.';
+    let any = false;
+    if (open === undefined)
+        return { any, dir };
+    for (let n = open + 1; n < line; n++) {
+        const text = (s.lines[n - 1] ?? '').trim().replace(/^\$\s*/, '');
+        if (!text || text.startsWith('#'))
+            continue;
+        for (const segment of splitOnAmpersand(text)) {
+            const change = /^(?:cd|pushd)\s+(.+)$/.exec(segment);
+            if (change) {
+                any = true;
+                dir = resolveCwd(dir, change[1].trim());
+            }
+            else if (/^(?:cd|pushd|popd)$/.test(segment) || segment.startsWith('popd ')) {
+                any = true;
+                dir = null;
+            }
+        }
+    }
+    return { any, dir };
+}
 /**
  * Splits a command string on `&&`, `||`, `;`, and newlines, yielding
  * individual segments. This allows a single `run:` block or backtick
@@ -330,9 +570,18 @@ function resolveCwd(current, target) {
 function splitOnAmpersand(cmd) {
     return cmd
         .split(/&&|\|\||;|\n/)
-        .map((s) => s.trim())
+        .map((s) => unwrapSubshell(s.trim()))
         .filter(Boolean);
 }
+/** `(cd site` and `npm run dev)`: the parentheses of a subshell belong to the shell, not to a word of the command. */
+function unwrapSubshell(segment) {
+    let out = segment;
+    while (out.startsWith('('))
+        out = out.slice(1).trim();
+    while (out.endsWith(')') && (out.match(/\)/g)?.length ?? 0) > (out.match(/\(/g)?.length ?? 0))
+        out = out.slice(0, -1).trim();
+    return out;
+}
 /** Returns true if a text looks like it could be a shell command to validate. */
 function isPotentialCommand(text) {
     const KNOWN_PREFIXES = [
@@ -521,7 +770,7 @@ function cwdOverride(parts) {
     }
     return undefined;
 }
-function findMissingScript(context, tree, cwd, parts, scriptName, builtins, tool, lookup, onScript, suggest) {
+function findMissingScript(context, tree, cwd, parts, scriptName, builtins, tool, lookup, onScript, suggest, scope) {
     const names = scriptName.includes('/')
         ? scriptName.split('/').map((s) => s.trim()).filter(Boolean)
         : [scriptName];
@@ -559,12 +808,12 @@ function findMissingScript(context, tree, cwd, parts, scriptName, builtins, tool
      * 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) => {
+    const propose = (name, pool, viaRoot = false) => {
         if (!suggest || names.length !== 1)
             return;
         const candidate = closestUniqueMatch(name, pool);
         if (candidate !== undefined) {
-            suggest({ missing: name, candidate, mechanical: isMechanicalRename(name, candidate) });
+            suggest({ missing: name, candidate, mechanical: isMechanicalRename(name, candidate), viaRoot });
         }
     };
     const scopedToWorkspaces = selector !== undefined || allWorkspaces;
@@ -577,6 +826,11 @@ function findMissingScript(context, tree, cwd, parts, scriptName, builtins, tool
     // warning here would name zero locations and tell the reader nothing.
     if (dirPkg === 'unfetched')
         return null;
+    // A corrupt manifest in the directory the command names: nothing to judge it against.
+    if (dirPkg === 'corrupt') {
+        noteCorrupt(tree, path.join(tree.root, cwd, 'package.json'));
+        return null;
+    }
     // pcic-x1vl: a directory on the way could not be listed — say so, don't guess.
     if (dirPkg === 'unreadable')
         return UNJUDGED;
@@ -587,6 +841,7 @@ function findMissingScript(context, tree, cwd, parts, scriptName, builtins, tool
     // No manifest we can check anywhere — stay silent.
     if (!dirPkg && !rootScriptsLoaded)
         return null;
+    let pendingElsewhere;
     for (const name of names) {
         if (builtins.has(name))
             continue;
@@ -600,7 +855,7 @@ function findMissingScript(context, tree, cwd, parts, scriptName, builtins, tool
                     continue; // only a sample of the workspace was read
                 return `no workspace matches "${selector}" for ${tool} script "${name}"`;
             }
-            if (selectedWorkspaces.some((ws) => !!ws.scripts[name]))
+            if (selectedWorkspaces.some((ws) => hasScript(ws.scripts, name)))
                 continue;
             const target = selectedWorkspaces.length === 1
                 ? `${selectedWorkspaces[0].name ?? selectedWorkspaces[0].dir} (${selectedWorkspaces[0].dir}/package.json)`
@@ -620,7 +875,7 @@ function findMissingScript(context, tree, cwd, parts, scriptName, builtins, tool
             // from an explicit --filter workspace target. A same-named root script is
             // NOT reachable here, so it must not mask a genuinely missing subdir
             // script.
-            if (dirPkg.scripts[name])
+            if (hasScript(dirPkg.scripts, name))
                 continue;
             const inWorkspace = inWorkspaceScope(name);
             if (inWorkspace === true || inWorkspace === 'silent')
@@ -635,15 +890,52 @@ function findMissingScript(context, tree, cwd, parts, scriptName, builtins, tool
         const inWorkspace = inWorkspaceScope(name);
         if (inWorkspace === true || inWorkspace === 'silent')
             continue;
-        if (context.packageJson.scripts[name])
+        if (hasScript(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));
+        if (!scopedToWorkspaces) {
+            // pcic-1ik0.2: the root manifest is not the only place a documented
+            // script can live. A directory the text names that defines it settles the
+            // command; a package elsewhere that defines it turns the finding into a
+            // note and withdraws the typo suggestion (the name is not misspelled).
+            //
+            // Each name of a slash-joined list is judged on its own: one that is
+            // settled or only elsewhere must not hide a sibling that is missing.
+            // Text that says "at the repo root" is an explicit root: no hint applies.
+            let settled = false;
+            if (!scope?.explicitRoot) {
+                for (const dir of scope?.hintDirs?.() ?? []) {
+                    const pkg = readPackageScripts(tree, path.join(tree.root, dir, 'package.json'));
+                    // Listed by a caller's inventory but never fetched: the script may be there. Say nothing.
+                    if (pkg === 'unfetched')
+                        settled = true;
+                    else if (pkg === 'corrupt') {
+                        noteCorrupt(tree, path.join(tree.root, dir, 'package.json'));
+                        settled = true;
+                    }
+                    else if (pkg === 'unreadable')
+                        return UNJUDGED;
+                    else if (pkg && hasScript(pkg.scripts, name))
+                        settled = true;
+                }
+                if (settled)
+                    continue;
+                const elsewhere = packagesDefining(context, tree, name);
+                if (elsewhere.length > 0) {
+                    pendingElsewhere ??= { name, dirs: elsewhere };
+                    continue;
+                }
+            }
+            propose(name, Object.keys(context.packageJson.scripts), true);
+        }
         return `${tool} script "${name}" does not appear in package.json scripts`;
     }
+    if (pendingElsewhere) {
+        scope?.elsewhere?.(pendingElsewhere.name, pendingElsewhere.dirs);
+        return `${tool} script "${pendingElsewhere.name}" does not appear in package.json scripts`;
+    }
     return null;
 }
 const BUILTINS_BY_TOOL = {
@@ -661,7 +953,7 @@ const BUILTINS_BY_TOOL = {
  * to an installed binary), `yarn workspace <name> <script>`, and workspace or
  * directory selectors.
  */
-function validatePackageManagerScript(tool, parts, context, tree, cwd, baseDir, onScript, suggest) {
+function validatePackageManagerScript(tool, parts, context, tree, cwd, baseDir, onScript, suggest, scope) {
     const subIdx = firstNonFlagArgIndex(parts);
     const sub = parts[subIdx];
     if (!sub)
@@ -687,6 +979,14 @@ function validatePackageManagerScript(tool, parts, context, tree, cwd, baseDir,
     const scriptName = parts[nameIdx];
     if (!scriptName || scriptName.startsWith('-'))
         return null;
+    // pcic-qc33: `pnpm build*` means every script that starts with `build`, and
+    // `npm run test:<name>` is a template. A pattern is never a misspelling, so
+    // there is nothing to report and nothing to rewrite. Recorded as judged so
+    // manifest-consistency does not read the same token as a missing script.
+    if (SCRIPT_PATTERN_RE.test(scriptName)) {
+        onScript?.(scriptName);
+        return null;
+    }
     if (tool === 'bun') {
         // `bun <x>` / `bun run <x>` also run files — a path is not a script name.
         if (!explicitRun && BUN_BUILTINS.has(scriptName))
@@ -703,17 +1003,18 @@ function validatePackageManagerScript(tool, parts, context, tree, cwd, baseDir,
     // (`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({
+        ? ({ missing, candidate, mechanical, viaRoot }) => suggest({
             find: prefix ? `${prefix} ${missing}` : missing,
             replace: prefix ? `${prefix} ${candidate}` : candidate,
             missing,
             candidate,
             mechanical,
+            viaRoot,
         })
         : 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, onSuggestion);
+    { allowBinary: !(explicitRun && (tool === 'npm' || tool === 'pnpm')), workspaceName }, onScript, onSuggestion, scope);
 }
 // ── make targets ──────────────────────────────────────────────────────────────
 /** make options whose value is the NEXT token (unless attached: `-Cdir`, `-j4`). */
@@ -818,7 +1119,7 @@ function validateSegment(seg, context, cwd = '.', onScript, opts = {}) {
             : tree.root;
     // ── Package manager scripts ────────────────────────────────────────────────
     if (tool === 'pnpm' || tool === 'npm' || tool === 'yarn' || tool === 'bun') {
-        return validatePackageManagerScript(tool, parts, context, tree, cwd, baseDir, onScript, opts.suggestScript);
+        return validatePackageManagerScript(tool, parts, context, tree, cwd, baseDir, onScript, opts.suggestScript, opts.scope);
     }
     // ── File-executing commands ────────────────────────────────────────────────
     const FILE_EXECUTORS = ['node', 'tsx', 'ts-node', 'bash', 'sh', 'python', 'python3'];
@@ -937,8 +1238,11 @@ function computeCommandAnalysis(context) {
         // 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 commentLines = htmlCommentLines(file.content);
+        const structure = lineStructure(file.content);
         const evaluated = new Set();
         const fileDir = path.relative(context.repoRoot, path.dirname(file.path)).replace(/\\/g, '/') || '.';
+        const nearDir = fileDir.startsWith('..') ? '.' : fileDir;
         evaluatedScripts.set(file.path, evaluated);
         for (const cmd of commands) {
             // pcic-2b6.13: `cmd.cwd ?? '.'` used to turn an unknown directory (null,
@@ -948,15 +1252,37 @@ function computeCommandAnalysis(context) {
             // unverifiable.
             const cwd = cmd.cwd === undefined ? '.' : cmd.cwd;
             let rewrite;
+            let elsewhere;
+            // pcic-1ik0.2: what the text around the command says, read only when it is needed.
+            const namesDirectory = (text) => resolveHintDirs(directoryTokens([text]), nearDir, tree).length > 0;
+            let framing;
+            const framingOf = () => (framing ??= commandContext(structure, cmd.line, cmd.text, namesDirectory));
+            const blockCd = earlierCd(structure, cmd.line);
+            const blockDirs = () => blockCd.dir !== null && blockCd.dir !== '.' ? resolveHintDirs([blockCd.dir], nearDir, tree) : [];
+            let hints;
+            const hintDirs = () => (hints ??=
+                cwd === '.'
+                    ? [...new Set([...blockDirs(), ...resolveHintDirs(directoryTokens(framingOf().text), nearDir, tree)])]
+                    : []);
             const error = validateSegment(cmd.text, context, cwd, (name) => evaluated.add(`${cmd.line}:${name}`), {
                 fenced: cmd.fenced === true,
                 makefileFor,
-                fileDir: fileDir.startsWith('..') ? '.' : fileDir,
+                fileDir: nearDir,
                 tree,
                 suggestScript: (r) => { rewrite = r; },
+                scope: {
+                    // Only a command run from the repo root is placed by the text around it.
+                    hintDirs,
+                    get explicitRoot() { return cwd === '.' && framingOf().explicitRoot; },
+                    elsewhere: (script, dirs) => { elsewhere = { script, dirs }; },
+                },
             });
             if (!error)
                 continue;
+            // A command in an HTML comment is text no reader sees: judged (so no other
+            // detector re-reads it), never reported.
+            if (commentLines[cmd.line - 1] === true)
+                continue;
             if (error === UNJUDGED) {
                 const evidence = `Not checked: \`${cmd.text}\``;
                 const entry = unchecked.get(evidence) ?? { filePaths: new Set(), fileLines: new Map(), evidence };
@@ -978,16 +1304,45 @@ function computeCommandAnalysis(context) {
             // (`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
+            //
+            // Only where the edit cannot change what the sentence means (editBlocker):
+            // an edit is applied unseen in a fix PR on someone else's repository.
+            const mechanical = rewrite?.mechanical === true && countOnLine(contentLines[cmd.line - 1] ?? '', rewrite.find) === 1;
+            const editContext = mechanical
+                ? editBlocker(cmd, contentLines, commentLines[cmd.line - 1] === true, framingOf(), blockCd.any, singlePackageRepo(context, tree), rewrite?.viaRoot === true)
                 : undefined;
+            const fix = mechanical && editContext === undefined ? 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.'
+                    (editContext
+                        ? `it may be what was meant, but ${editContext}, so it was left unedited; check before changing it.`
+                        : 'it may be what was meant, but it is near enough to be a different script, so check before changing it.')
                 : '';
+            if (elsewhere) {
+                // pcic-1ik0.2: the script exists, in a package the text does not point at.
+                const named = elsewhere.dirs.slice(0, 3).map((d) => `${d}/package.json`);
+                const more = elsewhere.dirs.length - named.length;
+                const where = `${named.join(', ')}${more > 0 ? ` and ${more} more` : ''}`;
+                const dir = elsewhere.dirs[0];
+                issues.push({
+                    id: issueId(fileIdPath(file), cmd.text),
+                    severity: 'info',
+                    category: 'command_validity',
+                    title: `Command may need a working directory: \`${cmd.text.split(/\s+/).slice(0, 3).join(' ')}\``,
+                    summary: `${error}, but ${where} defines "${elsewhere.script}". ` +
+                        'Nothing near the command names that directory, so it may be meant to run from there.',
+                    filePaths: [file.path],
+                    locations: [{ filePath: file.path, startLine: cmd.line, endLine: cmd.line }],
+                    evidence: [`Command: \`${cmd.text}\``, `In file: ${file.path}`, `Defined in: ${where}`],
+                    recommendation: `If the command runs from \`${dir}/\`, say so next to it (for example "from \`${dir}/\`", or \`cd ${dir} && ${cmd.text}\`) ` +
+                        'so a reader or an agent runs it in the right place. If the script was renamed or removed, update the instruction file.',
+                    confidence: 0.6,
+                });
+                continue;
+            }
             issues.push({
                 id: issueId(fileIdPath(file), cmd.text),
                 severity: 'warning',
@@ -1014,6 +1369,23 @@ function computeCommandAnalysis(context) {
             });
         }
     }
+    // One info finding per manifest the check relied on and could not parse: about the manifest, not
+    // about anyone's instructions, so it never carries the weight of a warning.
+    for (const manifest of [...(corruptUsed.get(tree) ?? [])].sort()) {
+        const rel = path.relative(tree.root, manifest).split(path.sep).join('/');
+        issues.push({
+            id: issueId('', `(unparsable ${rel})`),
+            severity: 'info',
+            category: 'command_validity',
+            title: `Could not parse ${rel}`,
+            summary: `${rel} is not a valid JSON object, so the commands that depend on its scripts were not checked.`,
+            filePaths: [manifest],
+            locations: [{ filePath: manifest }],
+            evidence: [`File: ${rel}`],
+            recommendation: `Fix the syntax of ${rel}; commands documented to run there are checked once it parses.`,
+            confidence: 0.9,
+        });
+    }
     if (unchecked.size > 0) {
         issues.push(incompleteCheckIssue(tree, [...unchecked.values()], {
             id: issueId('', '(command check incomplete)'),