@cplieger/deadset-ts 8.0.0-dev.12 → 8.0.0-dev.13

package/dist/src/commands/tools.js

@@ -0,0 +1,460 @@
+/**
+ * Layer 2 of the command reader: one row per tool, its reader of a simple command's words after
+ * its program word and the options it names its configuration file by, each as the tool
+ * documents them, and one reader per shell builtin that moves the shell's directory. A reader
+ * never guesses: an option it does not handle, or a dynamic word where it needs a value, leaves
+ * the command unread.
+ */
+import { resolvePath } from "../paths.js";
+/** The options `words` start with, or `undefined` where one is unhandled or a needed word is dynamic. */
+function optionsOf(words, options) {
+    const values = new Map();
+    const keep = (name, value) => {
+        values.set(name, [...(values.get(name) ?? []), value]);
+    };
+    for (let at = 0; at < words.length; at += 1) {
+        const word = words[at]?.value;
+        if (word === undefined) {
+            return undefined;
+        }
+        if (word === "--") {
+            return { values, at: at + 1, ended: true };
+        }
+        if (!word.startsWith("-") || options.flags.has(word)) {
+            if (!word.startsWith("-")) {
+                return { values, at, ended: false };
+            }
+            continue;
+        }
+        const equals = word.startsWith("--") ? word.indexOf("=") : -1;
+        const name = equals < 0 ? word : word.slice(0, equals);
+        if (options.valued.has(name)) {
+            const value = equals < 0 ? words[(at += 1)]?.value : word.slice(equals + 1);
+            if (value === undefined) {
+                return undefined;
+            }
+            keep(name, value);
+        }
+        else if (options.attached === true &&
+            options.valued.has(word.slice(0, 2)) &&
+            !word.startsWith("--")) {
+            keep(word.slice(0, 2), word.slice(2));
+        }
+        else {
+            return undefined;
+        }
+    }
+    return { values, at: words.length, ended: false };
+}
+/** A specifier that starts with a URL scheme, `file:` and `node:` among them. */
+const SCHEME = /^[a-z][a-z\d+.-]*:/iu;
+/** A specifier written as a path: `.`, `..`, or one starting `./`, `../` or `/`. */
+const RELATIVE = /^(?:\.{1,2}(?:\/|$)|\/)/u;
+/**
+ * The path a URL's path text names, percent-decoded as Node's `fileURLToPath` does, with a
+ * backslash read as the URL parser reads it, or `undefined` where it does not decode or
+ * encodes a separator: https://nodejs.org/api/url.html#urlfileurltopathurl-options
+ */
+function urlPath(text) {
+    const path = text.replace(/[?#].*$/su, "").replaceAll("\\", "/");
+    if (/%2f|%5c/iu.test(path)) {
+        return undefined;
+    }
+    try {
+        return decodeURIComponent(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Where one preload is, read in `dir`: the absolute path of a file, a package's name, or
+ * `undefined` where it names neither. `require` reads a path as written; an ECMAScript
+ * specifier is a URL, so a relative one or a `file:` one is percent-decoded and any other
+ * scheme loads no file: https://nodejs.org/api/esm.html#urls
+ */
+export function preloadTarget(preload, dir) {
+    const { specifier, resolution } = preload;
+    if (resolution === "require") {
+        return RELATIVE.test(specifier)
+            ? { path: resolvePath(dir, specifier) }
+            : SCHEME.test(specifier)
+                ? undefined
+                : { package: specifier };
+    }
+    if (!RELATIVE.test(specifier) && !SCHEME.test(specifier)) {
+        return { package: specifier };
+    }
+    const local = /^file:(?:\/\/(?=\/))?/iu.exec(specifier);
+    const rest = specifier.slice(local?.[0].length ?? 0);
+    // `file://host/…` names a file on another host.
+    if ((SCHEME.test(specifier) && local === null) || rest.startsWith("//")) {
+        return undefined;
+    }
+    const path = urlPath(rest);
+    return path === undefined ? undefined : { path: resolvePath(dir, path) };
+}
+/** A runtime: its preload options, then its entry, and every later word handed to the program. */
+function runtime(preloads, flags, runsNode, subcommand) {
+    const options = { valued: new Set(preloads.keys()), flags: new Set(flags) };
+    return (words) => {
+        const from = subcommand !== undefined && words[0]?.value === subcommand ? 1 : 0;
+        const read = optionsOf(words.slice(from), options);
+        if (read === undefined) {
+            return undefined;
+        }
+        const entry = words[from + read.at];
+        const loads = [...preloads].flatMap(([name, resolution]) => (read.values.get(name) ?? []).map((specifier) => ({ specifier, resolution })));
+        if ((entry !== undefined && entry.value === undefined) ||
+            loads.some((one) => preloadTarget(one, "/") === undefined)) {
+            return undefined;
+        }
+        return {
+            kind: "run",
+            entry: entry?.value,
+            preloads: loads,
+            runtime: runsNode && entry !== undefined ? "node" : undefined,
+        };
+    };
+}
+/**
+ * `node [options] [entry] [arguments]`, https://nodejs.org/api/cli.html: the options that load
+ * a module before the entry, `-r` as `require` does and the rest as an ECMAScript module.
+ * `-e`, `-p` and `-` run text that is no file, so they are unhandled.
+ */
+const node = runtime(new Map([
+    ["-r", "require"],
+    ["--require", "require"],
+    ["--import", "import"],
+    ["--loader", "import"],
+    ["--experimental-loader", "import"],
+]), [], true);
+/** `tsx [watch] [options] <file> [arguments]`, https://tsx.is/usage, https://tsx.is/node-enhancement */
+const tsx = runtime(new Map([
+    ["-r", "require"],
+    ["--require", "require"],
+    ["--import", "import"],
+]), [], false, "watch");
+/** `ts-node [options] [script] [arguments]`, https://typestrong.org/ts-node/docs/options; `--esm` picks no file. */
+const tsNode = runtime(new Map([
+    ["-r", "require"],
+    ["--require", "require"],
+]), ["--esm"], false);
+/** Hands on the command `words` from `at`, after the assignments `assigns` accepts. */
+function afterAssignments(words, at, assigns) {
+    let end = at;
+    while (end < words.length && words[end]?.value?.includes("=") === true) {
+        if (!assigns(words[end]?.value ?? "")) {
+            return undefined;
+        }
+        end += 1;
+    }
+    const program = words[end];
+    if (program !== undefined && (program.value === undefined || program.value.startsWith("-"))) {
+        return undefined;
+    }
+    return program === undefined
+        ? { kind: "run", entry: undefined, preloads: [], runtime: undefined }
+        : { kind: "command", words: words.slice(end) };
+}
+/**
+ * `env [option]... [name=value]... [command [argument]...]`,
+ * https://www.gnu.org/software/coreutils/manual/html_node/env-invocation.html: the options that
+ * change only the environment, `-i`, `-u` and `-v` in each spelling. GNU env takes any word
+ * holding an `=` after its first character as an assignment, and fails before running anything
+ * on a `-u` name that is empty or holds an `=`.
+ */
+const env = (words) => {
+    const read = optionsOf(words, {
+        valued: new Set(["-u", "--unset"]),
+        flags: new Set(["-i", "--ignore-environment", "-", "-v", "--debug"]),
+        attached: true,
+    });
+    const unset = [...(read?.values.get("-u") ?? []), ...(read?.values.get("--unset") ?? [])];
+    return read === undefined || unset.some((name) => name === "" || name.includes("="))
+        ? undefined
+        : afterAssignments(words, read.at, (value) => !value.startsWith("="));
+};
+/** `cross-env [name=value]... command [argument]...`, https://github.com/kentcdodds/cross-env#usage */
+const crossEnv = (words) => {
+    const reading = afterAssignments(words, 0, (value) => /^\w+=/u.test(value));
+    return reading?.kind === "command" ? reading : undefined;
+};
+/** The command a package runner hands on: its first word a package's or a command's name. */
+function runnerCommand(words, packaged) {
+    const [first, ...rest] = words;
+    if (first?.value === undefined || first.value.startsWith("-")) {
+        return undefined;
+    }
+    // A package specifier names the package's command; a version picks no other command.
+    const name = packaged ? first.value.replace(/(?<=.)@[^/@]*$/u, "") : first.value;
+    return { kind: "command", words: [{ value: name, text: first.text }, ...rest] };
+}
+/**
+ * npx and npm exec, https://docs.npmjs.com/cli/v11/commands/npx and
+ * https://docs.npmjs.com/cli/v11/commands/npm-exec: `--package` (and npx's `-p`), `--call`,
+ * `--yes` and `--no`, before the first positional word, which is the package whose command
+ * runs unless a `--package` names one. npm exec reads options after it too, unless a `--` ends them.
+ */
+function packageExec(shortPackage, laterOptions) {
+    const valued = new Set(["--package", "-c", "--call", ...(shortPackage ? ["-p"] : [])]);
+    return (words) => {
+        const read = optionsOf(words, { valued, flags: new Set(["-y", "--yes", "--no"]) });
+        if (read === undefined) {
+            return undefined;
+        }
+        const operands = words.slice(read.at);
+        if (laterOptions &&
+            !read.ended &&
+            operands.some((word) => word.value?.startsWith("-") !== false)) {
+            return undefined;
+        }
+        const call = [...(read.values.get("-c") ?? []), ...(read.values.get("--call") ?? [])];
+        if (call.length > 0) {
+            return call.length === 1 && operands.length === 0 && call[0] !== undefined
+                ? { kind: "line", text: call[0] }
+                : undefined;
+        }
+        const packages = [...(read.values.get("--package") ?? []), ...(read.values.get("-p") ?? [])];
+        return runnerCommand(operands, packages.length === 0);
+    };
+}
+const npx = packageExec(true, false);
+const npmExec = packageExec(false, true);
+/**
+ * `npm run <script> [-- <arguments>]`, https://docs.npmjs.com/cli/v11/commands/npm-run-script:
+ * it runs another script of the same manifest, which is read on its own.
+ */
+const npmRun = (words) => {
+    const [script, ...rest] = words;
+    const ended = rest.findIndex((word) => word.value === "--");
+    const before = ended < 0 ? rest : rest.slice(0, ended);
+    if (script?.value === undefined ||
+        script.value.startsWith("-") ||
+        before.some((word) => word.value?.startsWith("-") !== false)) {
+        return undefined;
+    }
+    return { kind: "run", entry: undefined, preloads: [], runtime: undefined };
+};
+/** A tool whose second word picks the reader of the rest. */
+function subcommands(readers) {
+    return ([first, ...rest]) => first?.value === undefined ? undefined : readers.get(first.value)?.(rest);
+}
+/** `npm exec`, `npm x` and `npm run` with `run-script`. */
+const npm = subcommands(new Map([
+    ["exec", npmExec],
+    ["x", npmExec],
+    ["run", npmRun],
+    ["run-script", npmRun],
+]));
+/**
+ * `pnpm exec <command>`, https://pnpm.io/cli/exec, which hands on every later word, and
+ * `pnpm dlx [--package <name>]... <command>`, https://pnpm.io/cli/dlx.
+ */
+const pnpm = subcommands(new Map([
+    ["exec", (words) => runnerCommand(words, false)],
+    [
+        "dlx",
+        (words) => {
+            const read = optionsOf(words, { valued: new Set(["--package"]), flags: new Set() });
+            return read === undefined
+                ? undefined
+                : runnerCommand(words.slice(read.at), !read.values.has("--package"));
+        },
+    ],
+]));
+/**
+ * `yarn node`, https://yarnpkg.com/cli/node, and `yarn dlx [-p <name>]... <command>`,
+ * https://yarnpkg.com/cli/dlx, whose command runs in the current directory.
+ */
+const yarn = subcommands(new Map([
+    ["node", (words) => ({ kind: "command", words: [{ value: "node", text: "node" }, ...words] })],
+    [
+        "dlx",
+        (words) => {
+            const read = optionsOf(words, {
+                valued: new Set(["-p", "--package"]),
+                flags: new Set(["-q", "--quiet"]),
+            });
+            return read === undefined
+                ? undefined
+                : runnerCommand(words.slice(read.at), !read.values.has("-p") && !read.values.has("--package"));
+        },
+    ],
+]));
+/** `bunx [-p <name>] <command>[@version] [arguments]`, https://bun.com/docs/pm/bunx */
+const bunx = (words) => {
+    const read = optionsOf(words, { valued: new Set(["-p", "--package"]), flags: new Set() });
+    return read === undefined ? undefined : runnerCommand(words.slice(read.at), true);
+};
+/** The row of a tool whose reader is `read`. */
+function reading(read) {
+    return { read };
+}
+/** The row of a tool that names its configuration file by `options` anywhere before a `--`. */
+function configuredBy(...options) {
+    return { configurations: { valued: new Set(options) } };
+}
+/** The row of each tool, by its program word: its name, or a path to it in `node_modules/.bin`. */
+const TOOLS = new Map([
+    ["node", reading(node)],
+    ["tsx", reading(tsx)],
+    ["ts-node", reading(tsNode)],
+    ["env", reading(env)],
+    ["cross-env", reading(crossEnv)],
+    [
+        "npx",
+        {
+            read: npx,
+            // `-c` takes a command line, which is read as a configuration file's name as well, so
+            // every configuration `fixtures/commands/observed.json` records stays named.
+            configurations: {
+                valued: new Set(["-c"]),
+                beforeOperand: new Set(["--package", "-p", "--call"]),
+            },
+        },
+    ],
+    ["npm", reading(npm)],
+    ["pnpm", reading(pnpm)],
+    ["yarn", reading(yarn)],
+    ["bunx", reading(bunx)],
+    // https://eslint.org/docs/latest/use/command-line-interface
+    ["eslint", configuredBy("-c", "--config")],
+    // https://prettier.io/docs/cli, whose `-c` is `--check`.
+    ["prettier", configuredBy("--config")],
+    // https://stylelint.io/user-guide/cli
+    ["stylelint", configuredBy("-c", "--config")],
+    // https://jestjs.io/docs/cli
+    ["jest", configuredBy("-c", "--config")],
+    // https://vitest.dev/guide/cli
+    ["vitest", configuredBy("-c", "--config")],
+    // https://vite.dev/guide/cli
+    ["vite", configuredBy("-c", "--config")],
+    // https://webpack.js.org/api/cli/
+    ["webpack", configuredBy("-c", "--config")],
+    // https://mochajs.org/#command-line-usage, whose `-c` is `--color`.
+    ["mocha", configuredBy("--config")],
+]);
+/** The row of a simple command's program word, by its name or a path to it in `node_modules/.bin`. */
+function rowOf(program) {
+    const name = program?.value === undefined
+        ? undefined
+        : /^(?:.*\/)?node_modules\/\.bin\/([^/]+)$|^([^/]+)$/u.exec(program.value);
+    const tool = name?.[1] ?? name?.[2];
+    return tool === undefined ? undefined : TOOLS.get(tool);
+}
+/**
+ * What the reader of one simple command's program reads it as, or `undefined` where none
+ * understands it. A program word that is any other path runs that file, whatever its name.
+ */
+export function readTool(words) {
+    const [program, ...rest] = words;
+    return rowOf(program)?.read?.(rest);
+}
+/**
+ * The configuration files one simple command names, as written: each static value of an option
+ * its program's row names a configuration file by, and none for a program with no such row.
+ */
+export function configurationsOf(words) {
+    const [program, ...rest] = words;
+    const options = rowOf(program)?.configurations;
+    const found = [];
+    for (let at = 0; options !== undefined && at < rest.length; at += 1) {
+        const word = rest[at]?.value;
+        if (word === "--" || (word === undefined && options.beforeOperand !== undefined)) {
+            break;
+        }
+        const equals = word?.startsWith("--") === true ? word.indexOf("=") : -1;
+        const name = equals < 0 ? word : word?.slice(0, equals);
+        if (name !== undefined && options.valued.has(name)) {
+            const value = equals < 0 ? rest[(at += 1)]?.value : word?.slice(equals + 1);
+            found.push(...(value === undefined || value === "" ? [] : [value]));
+        }
+        else if (options.beforeOperand !== undefined && name !== undefined) {
+            if (!name.startsWith("-")) {
+                break;
+            }
+            at += options.beforeOperand.has(name) && equals < 0 ? 1 : 0;
+        }
+    }
+    return found;
+}
+/** Either status, in a directory the analysis does not know. */
+const ELSEWHERE = [
+    { dir: undefined, ok: true },
+    { dir: undefined, ok: false },
+];
+const elsewhere = () => ELSEWHERE;
+/** The directory a builtin's one operand states, where it is static and starts with no character of `options`. */
+function statedDirectory(operands, options) {
+    const [dir] = operands;
+    return operands.length === 1 && dir?.value !== undefined && !options.includes(dir.value.charAt(0))
+        ? dir.value
+        : undefined;
+}
+/** `cd` to a stated directory is taken to enter it, as `roots.13` states. */
+const cd = (operands, dir) => {
+    const to = statedDirectory(operands, "-");
+    return to === undefined
+        ? ELSEWHERE
+        : [{ dir: dir === undefined ? undefined : resolvePath(dir, to), ok: true }];
+};
+/** `pushd` enters a stated directory, or fails and leaves the shell where it was. */
+const pushd = (operands, dir) => {
+    const to = statedDirectory(operands, "-+");
+    return to === undefined
+        ? ELSEWHERE
+        : [
+            { dir: dir === undefined ? undefined : resolvePath(dir, to), ok: true },
+            { dir, ok: false },
+        ];
+};
+/**
+ * `exec` with a command replaces the shell, which exits where it cannot; with none it only
+ * redirects: https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#exec
+ */
+const exec = ([command]) => {
+    if (command === undefined) {
+        return undefined;
+    }
+    return command.value === undefined || command.value.startsWith("-") ? ELSEWHERE : [];
+};
+/** `exit` ends the shell whatever its operands, in dash and in bash. */
+const exit = () => [];
+/** The builtins that run another command in the same shell, where that one may be any builtin. */
+const runsBuiltin = (operands) => operands.some((word) => word.value === undefined || BUILTINS.has(word.value))
+    ? ELSEWHERE
+    : undefined;
+/**
+ * The shell builtins that may move or end the shell running them: `cd`,
+ * https://pubs.opengroup.org/onlinepubs/9799919799/utilities/cd.html; `pushd` and `popd`,
+ * https://www.gnu.org/software/bash/manual/html_node/Directory-Stack-Builtins.html; `exit`,
+ * `exec`, and `return`, whose effect outside a function POSIX leaves unspecified,
+ * https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#return; and `.`,
+ * `eval`, `source`, `command` and `builtin`, which run other text or another builtin.
+ */
+const BUILTINS = new Map([
+    ["cd", cd],
+    ["pushd", pushd],
+    ["popd", elsewhere],
+    ["exit", exit],
+    ["exec", exec],
+    ["return", elsewhere],
+    [".", elsewhere],
+    ["source", elsewhere],
+    ["eval", elsewhere],
+    ["command", runsBuiltin],
+    ["builtin", runsBuiltin],
+]);
+/**
+ * Each way the shell running one simple command in its own environment, in `dir`, goes on
+ * after a builtin that may move or end it, or `undefined` where the command is no such
+ * builtin. A program word the shell computes may be any builtin.
+ */
+export function readBuiltin(words, dir) {
+    const [program, ...rest] = words;
+    if (program === undefined) {
+        return undefined;
+    }
+    return program.value === undefined ? ELSEWHERE : BUILTINS.get(program.value)?.(rest, dir);
+}

package/dist/src/configuration-files.js

@@ -12,7 +12,8 @@ import { bytewise } from "./text/compare.js";
 import { isRecord } from "./json-document.js";
 import { filesIn } from "./fs/tree.js";
 import { DEPENDENCY_SECTIONS, holdsManifest, inInstalledPackages, manifestAt, readJSON, } from "./fs/manifest.js";
-import { shellWords } from "./text/shell.js";
+import { readCommands } from "./commands/read.js";
+import { manifestCommands } from "./manifest.js";
 /** A configuration module's name, each form with the spelling a root reports it by. */
 const MODULE_FORMS = [
     { name: /^[\w-]+\.config\.(?:js|mjs|cjs|ts|mts|cts)$/u, form: "<stem>.config.<ext>" },
@@ -64,40 +65,25 @@ export function configurationModuleForm(name) {
 export function isConfigurationDocumentName(name) {
     return DOCUMENT_NAME.test(name);
 }
-/** The flags a tool's command line names its configuration file with. */
-const CONFIG_FLAGS = new Set(["--config", "-c"]);
 /** The extensions of a module a configuration flag may name. */
 const MODULE_EXTENSIONS = [".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"];
 /**
- * The files the scripts of the manifest in one directory name after a configuration flag,
- * `--config <file>`, `-c <file>` or `--config=<file>`, each a JSON file or a module below
- * the target root and in no `node_modules`.
+ * The files the command strings of the manifest in one directory name after a configuration
+ * flag, as `commands/read.ts` reads them against the directory each command runs in, each a
+ * JSON file or a module below the target root and in no `node_modules`.
  */
 function scriptConfigurations(host, root, dir) {
-    const scripts = manifestAt(host, dir)?.["scripts"];
-    if (!isRecord(scripts)) {
-        return [];
-    }
+    const manifest = manifestAt(host, dir);
     const found = [];
-    for (const command of Object.values(scripts)) {
-        if (typeof command !== "string") {
-            continue;
-        }
-        const words = shellWords(command);
-        words.forEach((word, at) => {
-            const named = word !== undefined && CONFIG_FLAGS.has(word)
-                ? words[at + 1]
-                : word === undefined
-                    ? undefined
-                    : /^--config=(.+)$/su.exec(word)?.[1];
-            const path = named === undefined ? undefined : resolvePath(dir, named);
-            if (path !== undefined &&
-                [".json", ...MODULE_EXTENSIONS].some((extension) => path.endsWith(extension)) &&
+    for (const { command } of manifest === undefined ? [] : manifestCommands(host, dir, manifest)) {
+        for (const { dir: runs, written } of readCommands(command, dir).configurations) {
+            const path = resolvePath(runs, written);
+            if ([".json", ...MODULE_EXTENSIONS].some((extension) => path.endsWith(extension)) &&
                 isProjectPath(root, path) &&
                 host.kindOf(path) === "file") {
                 found.push(path);
             }
-        });
+        }
     }
     return found;
 }

package/dist/src/conformance-record.js

@@ -4,7 +4,7 @@ export const RECORD = {
     conformance: {
         corpusVersion: "6.0.0",
         result: "pass",
-        digest: "sha256:0d33564807a356fd3e2760ddaa0645d758bdb9a96ee74a392675e444343bbf20",
+        digest: "sha256:58ac31fa90fcbefdbbcbcbd6d2c7a8af6dd4cd883c04d79abfe96f979ffe10e1",
     },
     gaps: [],
 };