@promptci/core 0.0.1 → 0.2.0

package/dist/command-validity.js

@@ -1,6 +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';
 /**
  * Command Validity Detector
  *
@@ -36,7 +41,18 @@ function fileExists(repoRoot, relativePath) {
         return false;
     }
 }
-function readPackageScripts(packageJsonPath) {
+function isDirectory(repoRoot, relativePath) {
+    try {
+        return fs.statSync(path.resolve(repoRoot, relativePath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function readPackageScripts(repoRoot, packageJsonPath) {
+    // A manifest committed as a symlink to a file outside the repo is not read.
+    if (!realPathWithinRoot(repoRoot, packageJsonPath))
+        return null;
     try {
         const raw = fs.readFileSync(packageJsonPath, 'utf8');
         const parsed = JSON.parse(raw);
@@ -101,8 +117,14 @@ function workspaceHasScript(context, selector, scriptName) {
     const normalizedSelector = normalizePnpmFilter(selector);
     if (!normalizedSelector)
         return false;
+    // Workspace manifests discovered while building the context (declared
+    // `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]);
+    }
     for (const candidate of workspacePackageJsonCandidates(context.repoRoot, normalizedSelector)) {
-        const pkg = readPackageScripts(candidate);
+        const pkg = readPackageScripts(context.repoRoot, candidate);
         if (!pkg)
             continue;
         const packageDir = path.dirname(candidate).replace(/\\/g, '/');
@@ -129,17 +151,32 @@ const PNPM_BUILTINS = new Set([
     'install', 'i', 'add', 'remove', 'uninstall', 'test', 'it', 'init',
     'create', 'publish', 'link', 'unlink', 'outdated', 'audit', 'update',
     'up', 'exec', 'dlx', 'run', 'store', 'list', 'ls', 'why', 'pack',
-    'recursive', 'm', 'multi', 'prune',
+    'recursive', 'm', 'multi', 'prune', 'version', 'run-script',
+    'env', 'config', 'fetch', 'rebuild', 'rb', 'patch', 'patch-commit', 'deploy',
+    'import', 'licenses', 'root', 'bin', 'setup', 'self-update', 'dedupe', 'doctor',
+    'approve-builds', 'sbom', 'cache',
 ]);
 const NPM_BUILTINS = new Set([
     'install', 'i', 'ci', 'uninstall', 'remove', 'update', 'outdated',
     'audit', 'start', 'stop', 'restart', 'test', 'it', 'init', 'create',
-    'publish', 'link', 'unlink', 'pack', 'exec', 'run',
+    'publish', 'link', 'unlink', 'pack', 'exec', 'run', 'run-script', 'version',
 ]);
 const YARN_BUILTINS = new Set([
     'install', 'add', 'remove', 'upgrade', 'outdated', 'audit', 'init',
-    'create', 'publish', 'link', 'unlink', 'why', 'pack', 'run',
+    'create', 'publish', 'link', 'unlink', 'why', 'pack', 'run', 'version',
+    'run-script', 'workspaces', 'exec', 'dlx', 'up', 'info', 'config', 'cache',
+    'bin', 'set', 'node', 'global', 'dedupe', 'patch', 'rebuild', 'plugin',
+    'constraints', 'unplug', 'npm',
+]);
+/** `bun <name>` runs a script (or file) only when <name> is not one of bun's own commands. */
+export const BUN_BUILTINS = new Set([
+    'install', 'i', 'add', 'a', 'remove', 'rm', 'update', 'test', 'build', 'init',
+    'create', 'c', 'x', 'bunx', 'pm', 'link', 'unlink', 'upgrade', 'repl', 'outdated',
+    'publish', 'patch', 'audit', 'info', 'why', 'completions', 'help', 'feedback',
+    'run', 'exec',
 ]);
+/** npm and pnpm treat `run-script` as an alias of `run`. */
+const RUN_ALIASES = new Set(['run', 'run-script']);
 /**
  * CV6: Resolves a `cd <target>` against the current repo-relative directory so
  * that a `cd apps/web && pnpm test:e2e` line validates `test:e2e` against
@@ -154,6 +191,10 @@ function resolveCwd(current, target) {
     if (!cleaned || cleaned.startsWith('/') || cleaned.startsWith('~') || /^[a-zA-Z]:[\\/]/.test(cleaned)) {
         return null; // absolute or home path — not resolvable to a repo-relative dir
     }
+    // `cd -`, `cd $DIR`, `cd "$(git rev-parse --show-toplevel)"`, `cd %TEMP%`,
+    // `cd <dir>`: computed or placeholder targets name no knowable directory.
+    if (/^-|[$`%<>{}*?]/.test(cleaned))
+        return null;
     const parts = current === '.' ? [] : current.split('/');
     for (const seg of cleaned.replace(/\\/g, '/').split('/')) {
         if (seg === '' || seg === '.')
@@ -214,80 +255,57 @@ const SHELL_FENCE_LANGS = new Set([
 /** Extracts commands from a single instruction-file content string. */
 function extractCommands(content) {
     const commands = [];
-    const lines = content.split(/\r?\n/);
-    // CV1: track fence char + length (matching scanner.ts/vague-guidance.ts/
-    // stale-instructions.ts/conflicts.ts) so we know we're inside SOME fence
-    // even for languages we don't scan for commands. The old regex only
-    // recognized bare ``` or a fixed shell-language list as an OPENER — a
-    // ```json fence's opener didn't match, so its bare ``` CLOSER was misread
-    // as a NEW opener, inverting inBlock state for the rest of the file.
-    let inBlock = false;
-    let inShellBlock = false;
-    let fenceChar = null;
-    let fenceLen = 0;
-    let blockStartLine = -1;
-    // CV2: keep the block's raw (untrimmed) lines so each entry's index still
-    // corresponds 1:1 to its physical line offset from blockStartLine. The old
-    // code joined the block into one string and called `.trim()` on it before
-    // re-splitting — that silently dropped leading/trailing blank lines, so
-    // blockLines[j] no longer matched the physical line blockStartLine + j + 1
-    // whenever the fenced block had leading blank lines.
-    let blockContent = [];
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        if (!inBlock) {
-            const openMatch = /^ {0,3}([`~]{3,})\s*([a-zA-Z0-9_-]*)/.exec(line);
-            if (openMatch) {
-                inBlock = true;
-                fenceChar = openMatch[1][0] ?? null;
-                fenceLen = openMatch[1].length;
-                const lang = (openMatch[2] ?? '').toLowerCase();
-                inShellBlock = lang === '' || SHELL_FENCE_LANGS.has(lang);
-                blockStartLine = i + 1;
-                blockContent = [];
+    // Fenced blocks first, prose second, then sorted back into document order
+    // below — findings quote the first occurrence of a command, so the order the
+    // two passes produce has to match the order a single interleaved pass did.
+    //
+    // Only CLOSED blocks contribute: an unclosed fence is a malformed document,
+    // and its tail was never meant to read as example commands. Non-shell fences
+    // (```json, ```ts, …) are skipped by language — tracking them at all is what
+    // keeps a ```json block's bare ``` closer from being misread as an opener,
+    // which used to invert the in-block state for the rest of the file.
+    for (const block of fencedBlocks(content)) {
+        // The shared scanner reports the full info string ('{.bash}', 'json,');
+        // classify on its leading identifier run, matching the historical opener
+        // regex `([a-zA-Z0-9_-]*)`. That keeps a pandoc-attribute fence like
+        // ```{.bash} classified as bare-and-therefore-shell (identifier run is
+        // empty) instead of being silently skipped as an unknown language.
+        const lang = /^[a-zA-Z0-9_-]*/.exec(block.lang)[0];
+        const isShell = lang === '' || SHELL_FENCE_LANGS.has(lang);
+        if (!isShell || !block.closed)
+            continue;
+        // Each entry's index corresponds 1:1 to its physical line offset from the
+        // block's first content line, so blank leading lines cannot shift the
+        // reported line number.
+        for (let j = 0; j < block.lines.length; j++) {
+            const rawTrimmed = block.lines[j].trim();
+            if (rawTrimmed.startsWith('#'))
                 continue;
-            }
-        }
-        else {
-            const closeMatch = /^ {0,3}([`~]{3,})\s*$/.exec(line);
-            if (closeMatch && closeMatch[1][0] === fenceChar && closeMatch[1].length >= fenceLen) {
-                inBlock = false;
-                if (inShellBlock) {
-                    for (let j = 0; j < blockContent.length; j++) {
-                        const raw = blockContent[j];
-                        const rawTrimmed = raw.trim();
-                        if (rawTrimmed.startsWith('#'))
-                            continue;
-                        const trimmed = rawTrimmed.replace(/^\$\s*/, '');
-                        if (!trimmed)
-                            continue;
-                        // CV6: each documented line is treated as an independent example run
-                        // from the repo root, so `cd` only affects commands chained after it
-                        // on the SAME line (e.g. `cd apps/web && pnpm test:e2e`). Setup blocks
-                        // are written this way — repeating `cd apps/web` on separate lines —
-                        // so a standalone `cd` must not bleed into later lines.
-                        let lineCwd = '.';
-                        for (const seg of splitOnAmpersand(trimmed)) {
-                            const cdMatch = /^cd\s+(.+)$/.exec(seg);
-                            if (cdMatch) {
-                                lineCwd = resolveCwd(lineCwd, cdMatch[1].trim());
-                            }
-                            commands.push({ text: seg, line: blockStartLine + j + 1, cwd: lineCwd });
-                        }
-                    }
-                }
-                inShellBlock = false;
-                fenceChar = null;
-                fenceLen = 0;
+            const trimmed = rawTrimmed.replace(/^\$\s*/, '');
+            if (!trimmed)
                 continue;
+            // CV6: each documented line is treated as an independent example run
+            // from the repo root, so `cd` only affects commands chained after it
+            // on the SAME line (e.g. `cd apps/web && pnpm test:e2e`). Setup blocks
+            // are written this way — repeating `cd apps/web` on separate lines —
+            // so a standalone `cd` must not bleed into later lines.
+            let lineCwd = '.';
+            for (const seg of splitOnAmpersand(trimmed)) {
+                const cdMatch = /^cd\s+(.+)$/.exec(seg);
+                if (cdMatch) {
+                    lineCwd = resolveCwd(lineCwd, cdMatch[1].trim());
+                }
+                commands.push({ text: seg, line: block.contentStartLine + j, cwd: lineCwd, fenced: true });
             }
-            // Still inside the fence — accumulate only if it's a shell-ish block;
-            // non-shell fences (```json, ```ts, …) are tracked for state but their
-            // content is never scanned for commands.
-            if (inShellBlock)
-                blockContent.push(line);
-            continue;
         }
+    }
+    for (const fenceLine of scanFencedLines(content)) {
+        if (fenceLine.inFence)
+            continue;
+        const i = fenceLine.lineNumber - 1;
+        // A trailing CR would block the prose patterns below: `.` does not match
+        // it, so the end-of-line lookahead never fires on a CRLF file.
+        const line = fenceLine.text.replace(/\r$/, '');
         // Inline backticks
         for (const m of line.matchAll(/`([^`]+)`/g)) {
             const inner = m[1].trim();
@@ -312,7 +330,8 @@ function extractCommands(content) {
             commands.push({ text: fullCmd, line: i + 1 });
         }
     }
-    return commands;
+    // Stable sort: segments split from one line keep their left-to-right order.
+    return commands.sort((a, b) => a.line - b.line);
 }
 // ── Command validation ────────────────────────────────────────────────────────
 /** Placeholder patterns that indicate a command is intentionally abstract. */
@@ -324,10 +343,15 @@ const PLACEHOLDER_RE = /[<{]|\.{3,}|your-file|your-script|example|placeholder/i;
  * like `--filter` or `--loader` gets mistaken for the subcommand, and its
  * VALUE (a package name or loader module) gets mistaken for a file path.
  */
-const FLAGS_WITH_VALUE = new Set(['--filter', '-F', '--cwd', '-C', '--loader', '--require', '-r']);
+const FLAGS_WITH_VALUE = new Set([
+    '--filter', '-F', '--cwd', '-C', '--dir', '--loader', '--require', '-r', '--workspace', '--prefix',
+]);
 function flagTakesValue(tool, flag) {
     if (tool === 'pnpm' && flag === '-r')
         return false;
+    // npm `-w <workspace>` takes a value; pnpm's `-w` (workspace root) does not.
+    if (flag === '-w')
+        return tool === 'npm';
     return FLAGS_WITH_VALUE.has(flag);
 }
 /**
@@ -341,8 +365,8 @@ function flagTakesValue(tool, flag) {
  * "ts-node/esm" (the loader flag's VALUE, which happens to contain a slash)
  * as the file being executed, instead of the real target "src/x.ts".
  */
-function firstNonFlagArgIndex(parts) {
-    let idx = 1;
+function firstNonFlagArgIndex(parts, startIdx = 1) {
+    let idx = startIdx;
     const tool = parts[0] ?? '';
     while (idx < parts.length) {
         const p = parts[idx];
@@ -355,30 +379,72 @@ function firstNonFlagArgIndex(parts) {
     }
     return idx;
 }
-/**
- * CV6/CV7: Validates one or more package-manager script names, honoring both a
- * `cd`-established working directory and slash-joined shorthand.
- *
- * CV6 (cwd): when a command runs after `cd <subdir>`, its scripts live in
- * `<subdir>/package.json`, NOT the repo-root manifest — so
- * `cd apps/web && pnpm test:e2e` is valid whenever apps/web defines `test:e2e`.
- *
- * CV7 (slash shorthand): `pnpm lint/typecheck/test/build` is a documentation
- * shorthand for four separate scripts, not one literal script named
- * "lint/typecheck/test/build". Each `/`-separated part is validated on its own.
- *
- * Returns an error string for the first genuinely-missing script, or null.
- */
-function findMissingScript(context, cwd, parts, scriptName, builtins, tool) {
-    // Unknown working directory (unresolvable `cd`) — cannot verify.
-    if (cwd === null)
-        return null;
+/** The `--filter`/`-F` (pnpm, bun) or `-w`/`--workspace` (npm) selector, if any. */
+function workspaceSelector(tool, parts) {
+    const filter = pnpmFilterValue(parts);
+    if (filter)
+        return filter;
+    if (tool !== 'npm')
+        return undefined;
+    for (let i = 1; i < parts.length; i++) {
+        const part = parts[i];
+        if (part === '-w' || part === '--workspace')
+            return parts[i + 1];
+        if (part.startsWith('--workspace='))
+            return part.slice('--workspace='.length);
+    }
+    return undefined;
+}
+/** `pnpm -r` / `pnpm --recursive` / `npm --workspaces`: the script may live in any workspace. */
+function runsInAllWorkspaces(tool, parts) {
+    if (tool === 'pnpm')
+        return parts.some((p) => p === '-r' || p === '--recursive');
+    if (tool === 'npm')
+        return parts.some((p) => p === '--workspaces' || p === '-ws');
+    return false;
+}
+/** A directory override (`--cwd`, `-C`, `--prefix`) re-roots the command like a `cd` would. */
+function cwdOverride(parts) {
+    for (let i = 1; i < parts.length; i++) {
+        const part = parts[i];
+        if (part === '--cwd' || part === '-C' || part === '--dir' || part === '--prefix')
+            return parts[i + 1];
+        const eq = /^(?:--cwd|--dir|--prefix)=(.+)$/.exec(part);
+        if (eq)
+            return eq[1];
+    }
+    return undefined;
+}
+function findMissingScript(context, cwd, parts, scriptName, builtins, tool, lookup, onScript) {
     const names = scriptName.includes('/')
         ? scriptName.split('/').map((s) => s.trim()).filter(Boolean)
         : [scriptName];
+    // Recorded before any early return so callers know this command was judged —
+    // including when it could not be checked (unknown working directory).
+    for (const name of names)
+        onScript?.(name);
+    // Unknown working directory (unresolvable `cd`) — cannot verify.
+    if (cwd === null)
+        return null;
+    const override = cwdOverride(parts);
+    if (override !== undefined) {
+        const resolved = resolveCwd(cwd, override);
+        if (resolved === null)
+            return null;
+        cwd = resolved;
+    }
+    const selector = lookup.workspaceName ?? workspaceSelector(tool, parts);
+    const allWorkspaces = runsInAllWorkspaces(tool, parts);
+    const inWorkspaceScope = (name) => allWorkspaces ? anyWorkspaceHasScript(context, name) : workspaceHasScript(context, 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;
     const inSubdir = cwd !== '.' && cwd !== '';
     const dirPkg = inSubdir
-        ? readPackageScripts(path.join(context.repoRoot, cwd, 'package.json'))
+        ? readPackageScripts(context.repoRoot, path.join(context.repoRoot, cwd, 'package.json'))
         : null;
     // cd'd into a directory whose package.json we can't read — don't guess.
     if (inSubdir && !dirPkg)
@@ -390,6 +456,23 @@ function findMissingScript(context, cwd, parts, scriptName, builtins, tool) {
     for (const name of names) {
         if (builtins.has(name))
             continue;
+        // `pnpm vitest run`, `yarn tsc --noEmit`: no script of that name, but it is
+        // an installed dependency's binary — the package manager runs that instead.
+        if (lookup.allowBinary && isKnownBinary(context, name))
+            continue;
+        if (selectedWorkspaces) {
+            if (selectedWorkspaces.length === 0) {
+                if (context.workspacesTruncated)
+                    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]))
+                continue;
+            const target = selectedWorkspaces.length === 1
+                ? `${selectedWorkspaces[0].name ?? selectedWorkspaces[0].dir} (${selectedWorkspaces[0].dir}/package.json)`
+                : `the ${selectedWorkspaces.length} workspaces selected by "${selector}"`;
+            return `${tool} script "${name}" does not appear in ${target} scripts`;
+        }
         if (dirPkg) {
             // A command that runs inside a subdir resolves scripts ONLY from that
             // subdir's manifest (pnpm/npm/yarn do not search parent directories) or
@@ -398,12 +481,12 @@ function findMissingScript(context, cwd, parts, scriptName, builtins, tool) {
             // script.
             if (dirPkg.scripts[name])
                 continue;
-            if (workspaceHasScript(context, pnpmFilterValue(parts), name))
+            if (inWorkspaceScope(name))
                 continue;
             return `${tool} script "${name}" does not appear in ${cwd}/package.json scripts`;
         }
-        // Repo-root context: the pnpm --filter workspace target or the root manifest.
-        if (workspaceHasScript(context, pnpmFilterValue(parts), name))
+        // Repo-root context: the workspace target(s) or the root manifest.
+        if (inWorkspaceScope(name))
             continue;
         if (context.packageJson.scripts[name])
             continue;
@@ -411,6 +494,141 @@ function findMissingScript(context, cwd, parts, scriptName, builtins, tool) {
     }
     return null;
 }
+const BUILTINS_BY_TOOL = {
+    pnpm: PNPM_BUILTINS,
+    npm: NPM_BUILTINS,
+    yarn: YARN_BUILTINS,
+    // bun's own commands are filtered before this lookup (bare form only), so
+    // `bun run test` is judged against the manifest like any other script.
+    bun: new Set(),
+};
+/**
+ * Resolves which script (or file, for bun) a `pnpm`/`npm`/`yarn`/`bun` command
+ * invokes and checks it. Handles the `run` / `run-script` forms, the bare
+ * `pnpm <script>` / `yarn <script>` / `bun <script>` forms (which fall through
+ * to an installed binary), `yarn workspace <name> <script>`, and workspace or
+ * directory selectors.
+ */
+function validatePackageManagerScript(tool, parts, context, cwd, baseDir, onScript) {
+    const subIdx = firstNonFlagArgIndex(parts);
+    const sub = parts[subIdx];
+    if (!sub)
+        return null;
+    let explicitRun = false;
+    let nameIdx = subIdx;
+    let workspaceName;
+    if (RUN_ALIASES.has(sub)) {
+        explicitRun = true;
+        nameIdx = firstNonFlagArgIndex(parts, subIdx + 1);
+    }
+    else if (tool === 'npm') {
+        return null; // a bare `npm <x>` is an npm command, never a script
+    }
+    else if (tool === 'yarn' && sub === 'workspace') {
+        workspaceName = parts[subIdx + 1];
+        nameIdx = subIdx + 2;
+        if (RUN_ALIASES.has(parts[nameIdx] ?? '')) {
+            explicitRun = true;
+            nameIdx++;
+        }
+    }
+    const scriptName = parts[nameIdx];
+    if (!scriptName || scriptName.startsWith('-'))
+        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))
+            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`;
+            }
+            return null;
+        }
+    }
+    return findMissingScript(context, 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);
+}
+// ── make targets ──────────────────────────────────────────────────────────────
+/** make options whose value is the NEXT token (unless attached: `-Cdir`, `-j4`). */
+const MAKE_FLAGS_WITH_VALUE = new Set([
+    '-C', '-f', '-o', '-W', '-I', '-E', '--directory', '--file', '--makefile', '--old-file', '--what-if',
+    '--include-dir', '--new-file', '--assume-old', '--assume-new', '--eval',
+]);
+/** Words that follow "make" in English prose (`make sure`), never checked as targets in a code span. */
+const MAKE_PROSE_WORDS = new Set([
+    'sure', 'it', 'this', 'that', 'them', 'these', 'those', 'certain', 'sense', 'changes', 'room', 'use', 'way',
+]);
+/** make options with an OPTIONAL numeric value (`-j`, `-j 4`, `-l 2.5`). */
+const MAKE_FLAGS_WITH_OPTIONAL_NUMBER = new Set(['-j', '-l', '--jobs', '--load-average', '--max-load']);
+/**
+ * pcic-2b6.10: `make <target>` against the Makefile make would read. Reports a
+ * target only when a Makefile exists in the command's directory, this reader
+ * could enumerate every target it defines (no `include`, no computed names),
+ * and neither an explicit target, a `.PHONY` name nor a pattern rule covers it.
+ * Variable assignments (`make X=1`), file-path goals (`make build/app.o`) and
+ * 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) {
+    let dir = cwd;
+    const goals = [];
+    for (let i = 1; i < parts.length; i++) {
+        const p = parts[i];
+        // Shell plumbing ends the make invocation.
+        if (/^(?:[|&<>#]|\d*>)/.test(p))
+            break;
+        if (p.startsWith('-')) {
+            const eq = p.indexOf('=');
+            const name = eq === -1 ? p : p.slice(0, eq);
+            if (name === '-f' || name === '--file' || name === '--makefile' || /^-f./.test(p))
+                return null; // another file
+            let value;
+            if (MAKE_FLAGS_WITH_VALUE.has(name)) {
+                value = eq !== -1 ? p.slice(eq + 1) : parts[++i];
+            }
+            else if (/^-C./.test(p)) {
+                value = p.slice(2);
+            }
+            else if (MAKE_FLAGS_WITH_OPTIONAL_NUMBER.has(p) && /^\d+(?:\.\d+)?$/.test(parts[i + 1] ?? '')) {
+                i++;
+            }
+            if ((name === '-C' || name === '--directory' || /^-C./.test(p)) && value !== undefined) {
+                dir = resolveCwd(dir, value);
+            }
+            continue;
+        }
+        if (p.includes('='))
+            continue; // `make CC=clang build`
+        goals.push(p);
+    }
+    if (dir === null || goals.length === 0)
+        return null;
+    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, '');
+        if (!target || isLikelyFilePath(target) || !/^[A-Za-z0-9_.+-]+$/.test(target))
+            continue;
+        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 = [];
+        }
+        if (entries.some((e) => e === target || e.startsWith(`${target}.`)))
+            continue;
+        return `make target "${target}" does not appear in ${facts.file}`;
+    }
+    return null;
+}
 /**
  * Validates a single command segment against the repo context.
  * Returns a human-readable error string, or null if the command looks valid.
@@ -418,7 +636,7 @@ function findMissingScript(context, cwd, parts, scriptName, builtins, tool) {
  * @param cwd Repo-relative directory the command runs in ('.' = root, null =
  *            unknown after an unresolvable `cd` — validation is skipped).
  */
-function validateSegment(seg, context, cwd = '.') {
+function validateSegment(seg, context, cwd = '.', onScript, opts = {}) {
     if (PLACEHOLDER_RE.test(seg))
         return null;
     const parts = seg.trim().split(/\s+/);
@@ -432,35 +650,8 @@ function validateSegment(seg, context, cwd = '.') {
             ? path.join(context.repoRoot, cwd)
             : context.repoRoot;
     // ── Package manager scripts ────────────────────────────────────────────────
-    if (tool === 'pnpm') {
-        const subIdx = firstNonFlagArgIndex(parts);
-        const sub = parts[subIdx];
-        if (!sub)
-            return null;
-        const scriptName = sub === 'run' ? parts[subIdx + 1] : sub;
-        if (!scriptName)
-            return null;
-        return findMissingScript(context, cwd, parts, scriptName, PNPM_BUILTINS, 'pnpm');
-    }
-    if (tool === 'npm') {
-        const subIdx = firstNonFlagArgIndex(parts);
-        if (parts[subIdx] === 'run' && parts[subIdx + 1]) {
-            return findMissingScript(context, cwd, parts, parts[subIdx + 1], NPM_BUILTINS, 'npm');
-        }
-    }
-    if (tool === 'yarn') {
-        const subIdx = firstNonFlagArgIndex(parts);
-        const sub = parts[subIdx];
-        if (!sub)
-            return null;
-        const scriptName = sub === 'run'
-            ? parts[subIdx + 1]
-            : sub === 'workspace'
-                ? parts[subIdx + 2]
-                : sub;
-        if (!scriptName)
-            return null;
-        return findMissingScript(context, cwd, parts, scriptName, YARN_BUILTINS, 'yarn');
+    if (tool === 'pnpm' || tool === 'npm' || tool === 'yarn' || tool === 'bun') {
+        return validatePackageManagerScript(tool, parts, context, cwd, baseDir, onScript);
     }
     // ── File-executing commands ────────────────────────────────────────────────
     const FILE_EXECUTORS = ['node', 'tsx', 'ts-node', 'bash', 'sh', 'python', 'python3'];
@@ -472,8 +663,29 @@ function validateSegment(seg, context, cwd = '.') {
             return `File "${filePart}" referenced by "${tool}" does not appear to exist in the repository`;
         }
     }
+    // ── make <target> ──────────────────────────────────────────────────────────
+    if (tool === 'make' && cwd !== null && opts.makefileFor) {
+        // An instruction file that sits next to its own Makefile (`tools/AGENTS.md`
+        // beside `tools/Makefile`) documents that one, not the root's.
+        const fileDir = opts.fileDir ?? '.';
+        const makeCwd = cwd === '.' && fileDir !== '.' && opts.makefileFor(fileDir) ? fileDir : cwd;
+        // 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);
+    }
     // ── Direct script invocations: ./scripts/foo.sh ───────────────────────────
     if (baseDir && (tool.startsWith('./') || tool.startsWith('../'))) {
+        // 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))
+                return null;
+            if (!opts.fenced || tool.endsWith('/'))
+                return null;
+        }
         if (!fileExists(baseDir, tool)) {
             return `Script "${tool}" does not appear to exist in the repository`;
         }
@@ -510,12 +722,53 @@ function validateSegment(seg, context, cwd = '.') {
  * out of scope.
  */
 export function detectCommandValidity(context) {
+    // Copies: the cached analysis is shared with manifest-consistency.
+    return analyzeCommands(context).issues.map((issue) => ({ ...issue }));
+}
+/**
+ * Both command-validity and manifest-consistency need the analysis; compute it
+ * once per context.
+ */
+const analysisCache = new WeakMap();
+export function analyzeCommands(context) {
+    let analysis = analysisCache.get(context);
+    if (!analysis) {
+        analysis = computeCommandAnalysis(context);
+        analysisCache.set(context, analysis);
+    }
+    return analysis;
+}
+function computeCommandAnalysis(context) {
     const issues = [];
+    const evaluatedScripts = new Map();
     const reported = new Set();
+    // 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();
+    const makefileFor = (dir) => {
+        if (dir === '.' || dir === '')
+            return context.makefile;
+        if (!makefiles.has(dir))
+            makefiles.set(dir, readMakefile(context.repoRoot, dir));
+        return makefiles.get(dir);
+    };
     for (const file of context.files) {
         const commands = extractCommands(file.content);
+        const evaluated = new Set();
+        const fileDir = path.relative(context.repoRoot, path.dirname(file.path)).replace(/\\/g, '/') || '.';
+        evaluatedScripts.set(file.path, evaluated);
         for (const cmd of commands) {
-            const error = validateSegment(cmd.text, context, cmd.cwd ?? '.');
+            // pcic-2b6.13: `cmd.cwd ?? '.'` used to turn an unknown directory (null,
+            // after `cd /srv/app` or `cd $DIR`) into the repo root and validate the
+            // command against the root manifest. Only a command with no cwd at all
+            // (prose, which never carries a `cd`) runs from the root; null stays
+            // unverifiable.
+            const cwd = cmd.cwd === undefined ? '.' : cmd.cwd;
+            const error = validateSegment(cmd.text, context, cwd, (name) => evaluated.add(`${cmd.line}:${name}`), {
+                fenced: cmd.fenced === true,
+                makefileFor,
+                fileDir: fileDir.startsWith('..') ? '.' : fileDir,
+            });
             if (!error)
                 continue;
             // Deduplicate same command text appearing twice in the same file
@@ -524,7 +777,7 @@ export function detectCommandValidity(context) {
                 continue;
             reported.add(dedupeKey);
             issues.push({
-                id: issueId(file.path, cmd.text),
+                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(' ')}\``,
@@ -538,6 +791,6 @@ export function detectCommandValidity(context) {
             });
         }
     }
-    return issues;
+    return { issues, evaluatedScripts };
 }
 //# sourceMappingURL=command-validity.js.map