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

package/dist/src/workflow-steps.js

@@ -1,36 +1,29 @@
 /**
- * The source files a CI workflow's `run:` steps and the repository's git hooks name by their
- * path from the target root. A workflow or hook file is read as text, line by line, with no
- * YAML parsed.
+ * The command strings beside a target root's packages: a CI workflow's `run:` steps, the git
+ * hooks, the hook managers' commands and the makefile's recipe lines, each with the directory
+ * it runs in. A workflow or hook manager file is read by `text/yaml.ts`, and one it does not
+ * read gives no command; each command is read by `commands/read.ts`.
  */
-import { joinPath, relativePath, resolvePath } from "./paths.js";
+import { pathsNamed, readCommands } from "./commands/read.js";
+import { isRecord } from "./json-document.js";
+import { joinPath, resolvePath } from "./paths.js";
 import { filesIn } from "./fs/tree.js";
-import { commandsOf, scriptTokens, unquoted, withoutComment } from "./text/shell.js";
+import { yamlDocument } from "./text/yaml.js";
 const WORKFLOWS = ".github/workflows";
-/** A line holding a run command: indentation and one sequence marker before `run:`. */
-const RUN_LINE = /^(\s*(?:- )?)run:(.*)$/u;
 /** The directories whose every file is a git hook script, run as the shell runs it. */
 const HOOK_DIRS = [".husky", ".githooks"];
-/** A line setting the directory a workflow step, or each step a `defaults.run` covers, runs in. */
-const WORKING_DIRECTORY = /^(\s*(?:- )?)working-directory:(.*)$/u;
-const LEFTHOOK_FILES = ["lefthook.yml", "lefthook.yaml", ".lefthook.yml"];
-/** A line setting the directory a lefthook command runs in. */
-const LEFTHOOK_ROOT = /^(\s*(?:- )?)root:(.*)$/u;
-/** The hook manager files whose commands are written under a key, with that key. */
+/** The key setting the directory a workflow step, or each step a `defaults.run` covers, runs in. */
+const WORKING_DIRECTORY = "working-directory";
+/**
+ * The hook manager files, each with the key its commands are written under and the key of their
+ * directory: lefthook's `root`, https://lefthook.dev/configuration/root/
+ */
 const HOOK_MANAGERS = [
-    [".pre-commit-config.yaml", /^(\s*(?:- )?)entry:(.*)$/u],
-    ...LEFTHOOK_FILES.map((name) => [name, RUN_LINE]),
+    [".pre-commit-config.yaml", "entry", undefined],
+    ...["lefthook.yml", "lefthook.yaml", ".lefthook.yml"].map((name) => [name, "run", "root"]),
 ];
 /** The names GNU make reads a makefile under, in the order it tries them. */
 const MAKEFILES = ["GNUmakefile", "makefile", "Makefile"];
-const BLOCK_SCALAR = /^[|>][+-]?$/u;
-/** A token holding one of these is computed or a pattern, so it names no file. */
-const COMPUTED = /[${*?[]/u;
-const INDENT = /^\s*/u;
-/** The files directly in one directory whose name `accepts`, by path in name order. */
-function pathsIn(host, dir, accepts) {
-    return filesIn(host, dir, accepts).map((name) => joinPath(dir, name));
-}
 function readText(host, path) {
     try {
         return host.readFile(path);
@@ -39,144 +32,129 @@ function readText(host, path) {
         return undefined;
     }
 }
-/** Every line one workflow file's `run:` steps hold, or every line of the values written under `key`. */
-export function runCommands(text, key = RUN_LINE) {
-    const lines = text.split(/\r?\n/u);
+/** The text a YAML scalar's value stands for, or `undefined` for a collection or a null. */
+function scalarText(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean"
+        ? String(value)
+        : undefined;
+}
+/** The `defaults.run.working-directory` one mapping writes, as YAML decodes it. */
+function defaultDirectory(mapping) {
+    const defaults = mapping["defaults"];
+    const run = isRecord(defaults) ? defaults["run"] : undefined;
+    return isRecord(run) ? scalarText(run[WORKING_DIRECTORY]) : undefined;
+}
+/**
+ * Every command one workflow or hook manager file writes under `key`, in every mapping of the
+ * document, each with the directory it runs in: its mapping's `dirKey` value, else, in a workflow
+ * file, the innermost `defaults.run.working-directory` of a mapping holding it, else `root`. A
+ * file `yamlDocument` does not read gives none.
+ */
+function keyedCommands(text, root, key, dirKey) {
     const found = [];
-    for (let at = 0; at < lines.length; at += 1) {
-        const match = key.exec(lines[at] ?? "");
-        if (match === null) {
-            continue;
+    const visit = (node, inherited) => {
+        if (Array.isArray(node)) {
+            for (const item of node) {
+                visit(item, inherited);
+            }
+            return;
         }
-        const column = (match[1] ?? "").length;
-        const value = unquoted((match[2] ?? "").trim());
-        if (!BLOCK_SCALAR.test(value)) {
-            found.push(value);
-            continue;
+        if (!isRecord(node)) {
+            return;
         }
-        for (let next = at + 1; next < lines.length; next += 1) {
-            const line = lines[next] ?? "";
-            if (line.trim() !== "" && (INDENT.exec(line)?.[0].length ?? 0) <= column) {
-                break;
-            }
-            found.push(line);
+        const here = (dirKey === WORKING_DIRECTORY ? defaultDirectory(node) : undefined) ?? inherited;
+        const command = scalarText(node[key]);
+        if (command !== undefined && command.trim() !== "") {
+            const written = (dirKey === undefined ? undefined : scalarText(node[dirKey])) ?? here;
+            found.push({
+                text: command,
+                dir: written === undefined
+                    ? root
+                    : written.includes("${{")
+                        ? undefined
+                        : resolvePath(root, written),
+                writtenDirectory: written,
+            });
         }
-    }
+        for (const value of Object.values(node)) {
+            visit(value, here);
+        }
+    };
+    visit(yamlDocument(text), undefined);
     return found;
 }
+/** The path of each git hook script at `root`, every file in {@link HOOK_DIRS}. */
+function hookScripts(host, root) {
+    return HOOK_DIRS.flatMap((dir) => filesIn(host, joinPath(root, dir), () => true).map((name) => joinPath(root, dir, name)));
+}
+/** The makefile make reads at `root`, the first of {@link MAKEFILES} there. */
+function makefileAt(host, root) {
+    return MAKEFILES.map((name) => joinPath(root, name)).find((candidate) => host.kindOf(candidate) === "file");
+}
 /**
- * The commands of the recipe lines of the target root's makefile, each line's in order: a
- * recipe line is one that starts with a tab, joined with the lines a trailing `\`
- * continues it onto.
+ * Each recipe line of the target root's makefile: a line that starts with a tab, joined with
+ * the lines a trailing `\` continues it onto, less the `@`, `-` and `+` make reads before it.
+ * Make runs each line in a shell of its own.
  */
 function recipeLines(host, root) {
-    const path = MAKEFILES.map((name) => joinPath(root, name)).find((candidate) => host.kindOf(candidate) === "file");
+    const path = makefileAt(host, root);
     const text = path === undefined ? undefined : readText(host, path);
-    if (text === undefined) {
-        return [];
-    }
-    return text
+    return (text ?? "")
         .replace(/\\\r?\n/gu, " ")
         .split(/\r?\n/u)
         .filter((line) => line.startsWith("\t"))
-        .map((line) => commandsOf(withoutComment(line.slice(1).replace(/^[@+-]+/u, ""))));
+        .map((line) => ({
+        text: line.slice(1).replace(/^[@+-]+/u, ""),
+        dir: root,
+        writtenDirectory: undefined,
+    }));
 }
 /**
- * Every token the recipe lines of the target root's makefile hold, each with the directory
- * below the root it is read against: make runs each line in a shell of its own, so a `cd`
- * moves the directory of the later commands of its line alone.
- */
-function recipeTokens(host, root) {
-    const found = [];
-    for (const line of recipeLines(host, root)) {
-        let dir = root;
-        for (const command of line) {
-            const tokens = scriptTokens(command);
-            const [first, target, ...rest] = tokens;
-            if (first === "cd" && target !== undefined && rest.length === 0 && !COMPUTED.test(target)) {
-                dir = resolvePath(dir, target);
-                continue;
-            }
-            for (const token of tokens) {
-                found.push({ token, dir: relativePath(root, dir) ?? "" });
-            }
-        }
-    }
-    return found;
-}
-/**
- * Every command the target root's workflow steps, git hooks and makefile run: the `run:`
- * steps of the workflow files in `.github/workflows`, every line of each file in `.husky`
- * and `.githooks`, the `entry:` commands of `.pre-commit-config.yaml`, the `run:` commands
- * of a lefthook file and the makefile's recipe lines.
+ * Every command the target root's workflow steps, git hooks, hook managers and makefile run:
+ * the `run:` steps of the workflow files in `.github/workflows`, each file in `.husky` and
+ * `.githooks` as one shell script, the `entry:` commands of `.pre-commit-config.yaml`, the
+ * `run:` commands of a lefthook file and the makefile's recipe lines.
  */
 export function workflowCommands(host, targetRoot) {
     const root = resolvePath(host.workingDirectory(), targetRoot);
-    return [...stepCommands(host, root), ...recipeLines(host, root).flat()];
-}
-/**
- * Every directory the target root's workflow steps and lefthook commands are set to run in, as
- * written: each `working-directory` of a workflow file and each `root` of a lefthook file.
- */
-export function commandDirectories(host, targetRoot) {
-    const root = resolvePath(host.workingDirectory(), targetRoot);
+    const workflows = filesIn(host, joinPath(root, WORKFLOWS), (name) => /\.ya?ml$/u.test(name));
     return [
-        ...workflowFiles(host, root).flatMap((path) => runCommands(readText(host, path) ?? "", WORKING_DIRECTORY)),
-        ...LEFTHOOK_FILES.flatMap((name) => runCommands(readText(host, joinPath(root, name)) ?? "", LEFTHOOK_ROOT)),
+        ...workflows.flatMap((name) => keyedCommands(readText(host, joinPath(root, WORKFLOWS, name)) ?? "", root, "run", WORKING_DIRECTORY)),
+        ...hookScripts(host, root).map((path) => ({
+            text: readText(host, path) ?? "",
+            dir: root,
+            writtenDirectory: undefined,
+        })),
+        ...HOOK_MANAGERS.flatMap(([name, key, dirKey]) => keyedCommands(readText(host, joinPath(root, name)) ?? "", root, key, dirKey)),
+        ...recipeLines(host, root),
     ];
 }
-/** The workflow files in `.github/workflows` at one root, by path in name order. */
-function workflowFiles(host, root) {
-    return pathsIn(host, joinPath(root, WORKFLOWS), (name) => /\.ya?ml$/u.test(name));
-}
-/** Every token the commands {@link workflowCommands} reads hold. */
-export function workflowTokens(host, targetRoot) {
+/**
+ * The whole text of each file {@link workflowCommands} reads a command from, each workflow file,
+ * git hook, hook manager file and makefile at the target root. Layer 3 holds it whole, so a part
+ * no command is read from, a comment included, or one the reading of the structure misses, still
+ * holds every file it names.
+ */
+export function commandFileTexts(host, targetRoot) {
     const root = resolvePath(host.workingDirectory(), targetRoot);
     return [
-        ...stepCommands(host, root).flatMap((command) => scriptTokens(command)),
-        ...recipeTokens(host, root).map(({ token }) => token),
-    ];
-}
-/** The commands of the workflow steps, git hooks and hook managers at one root. */
-function stepCommands(host, root) {
-    const commands = [];
-    for (const path of workflowFiles(host, root)) {
-        commands.push(...runCommands(readText(host, path) ?? ""));
-    }
-    for (const dir of HOOK_DIRS) {
-        for (const path of pathsIn(host, joinPath(root, dir), () => true)) {
-            commands.push(...(readText(host, path) ?? "").split(/\r?\n/u).map(withoutComment));
-        }
-    }
-    for (const [name, key] of HOOK_MANAGERS) {
-        commands.push(...runCommands(readText(host, joinPath(root, name)) ?? "", key));
-    }
-    return commands;
+        ...filesIn(host, joinPath(root, WORKFLOWS), (name) => /\.ya?ml$/u.test(name)).map((name) => joinPath(root, WORKFLOWS, name)),
+        ...hookScripts(host, root),
+        ...HOOK_MANAGERS.map(([name]) => joinPath(root, name)),
+        ...[makefileAt(host, root) ?? []].flat(),
+    ].flatMap((path) => readText(host, path) ?? []);
 }
 /**
- * The own files the target root's workflow steps and git hooks name, as
- * {@link workflowTokens} reads them: a token equal to a file's path below the target root,
- * with or without a leading `./`, whatever directory the step runs in.
+ * The own files the target root's workflow steps, git hooks and recipes run or name, as
+ * `pathsNamed` reads each command.
  */
 export function workflowEntries(host, targetRoot, files) {
     const found = [];
-    for (const token of workflowTokens(host, targetRoot)) {
-        if (COMPUTED.test(token)) {
-            continue;
-        }
-        const file = files.byPath.get(token.startsWith("./") ? token.slice(2) : token);
-        if (file !== undefined) {
-            found.push({ file, source: token });
-        }
-    }
-    const root = resolvePath(host.workingDirectory(), targetRoot);
-    for (const { token, dir } of recipeTokens(host, root)) {
-        const below = COMPUTED.test(token) || dir === ""
-            ? undefined
-            : relativePath(root, resolvePath(joinPath(root, dir), token));
-        const file = below === undefined ? undefined : files.byPath.get(below);
-        if (file !== undefined) {
-            found.push({ file, source: token });
+    for (const { text, dir } of workflowCommands(host, targetRoot)) {
+        for (const { path, written } of pathsNamed(readCommands(text, dir))) {
+            for (const file of files.named(path)) {
+                found.push({ file, source: written });
+            }
         }
     }
     return found;

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "8.0.0-dev.12",
+  "version": "8.0.0-dev.14",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"
@@ -9,6 +9,7 @@
     "include": [
       "LICENSE",
       "NOTICE",
+      "THIRD_PARTY_NOTICES.md",
       "README.md",
       "bin/**",
       "src/**",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "8.0.0-dev.12",
+  "version": "8.0.0-dev.14",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",
@@ -20,6 +20,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "gen": "node scripts/gen-contract.ts",
+    "vendor": "node scripts/vendor-unbash.ts",
     "prepack": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
     "typecheck:tests": "tsc -p tsconfig.test.json",
@@ -46,7 +47,7 @@
     "fast-check": "4.10.2",
     "prettier": "3.9.10",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.71.2",
+    "typescript-eslint": "8.72.1",
     "vitest": "5.0.5"
   },
   "publishConfig": {
@@ -72,6 +73,7 @@
   "files": [
     "LICENSE",
     "NOTICE",
+    "THIRD_PARTY_NOTICES.md",
     "dist/",
     "src/",
     "!src/**/*.test.ts",

package/src/build-scripts.ts

@@ -40,11 +40,11 @@ import type { Host } from "./host.ts";
 import { ancestors, dirnamePath, relativePath, resolvePath } from "./paths.ts";
 import type { SourceFiles } from "./source-files.ts";
 import { bytewise } from "./text/compare.ts";
-import { isRecord } from "./json-document.ts";
 import { unwrapped } from "./unwrap.ts";
 import { holdsManifest, inInstalledPackages, manifestAt } from "./fs/manifest.ts";
 import { globExpression } from "./text/glob.ts";
-import { scriptTokens } from "./text/shell.ts";
+import { pathsNamed, readCommands } from "./commands/read.ts";
+import { manifestCommands } from "./manifest.ts";
 
 /** One bundler API: the module, the functions it exports that build, and the option naming entries. */
 interface BundlerAPI {
@@ -473,19 +473,12 @@ function scriptEntries(file: SourceFile, dir: string, files: SourceFiles): reado
   return found;
 }
 
-/** The modules one manifest's scripts run, by absolute path, each below the target root. */
+/** The modules one manifest's command strings run or name, by absolute path, each below the target root. */
 function scriptModules(host: Host, root: string, dir: string): readonly string[] {
-  const scripts = manifestAt(host, dir)?.["scripts"];
-  if (!isRecord(scripts)) {
-    return [];
-  }
+  const manifest = manifestAt(host, dir);
   const found = new Set<string>();
-  for (const command of Object.values(scripts)) {
-    if (typeof command !== "string") {
-      continue;
-    }
-    for (const token of scriptTokens(command)) {
-      const path = resolvePath(dir, token);
+  for (const { command } of manifest === undefined ? [] : manifestCommands(host, dir, manifest)) {
+    for (const { path } of pathsNamed(readCommands(command, dir))) {
       if (
         MODULE_EXTENSION.test(path) &&
         relativePath(root, path) !== undefined &&

package/src/commands/read.ts

@@ -0,0 +1,230 @@
+/**
+ * The one reader of every command string the analysis reads. Layer 3, the holding rule
+ * `roots.ts` applies through `text/named-files.ts`, reads all of the string's text whatever
+ * the other two layers make of it; layer 1 parses the string and layer 2 reads each simple
+ * command a tool's reader understands, and they only add the files and modules it runs.
+ */
+
+import { joinPath, resolvePath } from "../paths.ts";
+import { shellLine, type Pipeline, type Word } from "./shell.ts";
+import {
+  configurationsOf,
+  preloadTarget,
+  readBuiltin,
+  readTool,
+  type Outcome,
+  type Preload,
+  type Reading,
+} from "./tools.ts";
+
+/** One program a read command runs. */
+interface Run {
+  /** The directory it runs in, absolute where the string's directory is. */
+  readonly dir: string;
+  /** The path of the file it runs, as written. */
+  readonly entry: string | undefined;
+  /** The modules it loads before the entry. */
+  readonly preloads: readonly Preload[];
+  readonly runtime: "node" | undefined;
+}
+
+/** One simple command's words, `undefined` for a dynamic one, with the directory it runs in. */
+interface CommandWords {
+  readonly dir: string;
+  readonly words: readonly (string | undefined)[];
+}
+
+/** One configuration file a command names by its tool's configuration option, as written, with its command's directory. */
+interface NamedConfiguration {
+  readonly dir: string;
+  readonly written: string;
+}
+
+/** What one command string runs. */
+export interface CommandReading {
+  readonly runs: readonly Run[];
+  /**
+   * Each simple command read in the directory it runs in, and each one of the string's own
+   * line in the string's directory too, wherever and whether it runs.
+   */
+  readonly commands: readonly CommandWords[];
+  readonly configurations: readonly NamedConfiguration[];
+  /** The text layer 3 reads: all of the string. */
+  readonly held: string;
+}
+
+/**
+ * The outcomes of one pipeline run in `dir`: those of the builtin that is its one member, as
+ * `readBuiltin` gives them, a directory the analysis does not know after a part layer 1 does
+ * not read, and either status in `dir` otherwise, a pipeline of several members included,
+ * whose members each run in a subshell.
+ */
+function outcomesOf(pipeline: Pipeline, dir: string | undefined): readonly Outcome[] {
+  const [only] = pipeline.alone ? pipeline.commands : [];
+  const outcomes = pipeline.opaque
+    ? [
+        { dir: undefined, ok: true },
+        { dir: undefined, ok: false },
+      ]
+    : ((only === undefined ? undefined : readBuiltin(only, dir)) ?? [
+        { dir, ok: true },
+        { dir, ok: false },
+      ]);
+  return outcomes.map((one) => ({ dir: one.dir, ok: one.ok !== pipeline.negated }));
+}
+
+/** The one directory every outcome is in, or `undefined` where they differ or none is known. */
+function oneDirectory(outcomes: readonly Outcome[]): string | undefined {
+  const dirs = new Set(outcomes.map((one) => one.dir));
+  return dirs.size === 1 ? [...dirs][0] : undefined;
+}
+
+/**
+ * What `text`, run in `dir`, `undefined` where not known, runs. A pipeline is read where every
+ * way its and-or list reaches it leaves the shell in one known directory, none after an `exit`;
+ * a background list moves and ends no later one. The words and configuration files of every
+ * simple command of the string's own line are read in `dir` as well, wherever they run.
+ */
+export function readCommands(text: string, dir: string | undefined): CommandReading {
+  const runs: Run[] = [];
+  const commands: CommandWords[] = [];
+  const configurations: NamedConfiguration[] = [];
+  const readCommand = (words: readonly Word[], at: string): void => {
+    commands.push({ dir: at, words: words.map((word) => word.value) });
+    let handed = words;
+    let reading: Reading | undefined = readTool(handed);
+    while (reading?.kind === "command") {
+      handed = reading.words;
+      reading = readTool(handed);
+    }
+    if (reading?.kind === "line") {
+      readLine(reading.text, at);
+      return;
+    }
+    configurations.push(...configurationsOf(handed).map((written) => ({ dir: at, written })));
+    if (reading !== undefined && (reading.entry !== undefined || reading.preloads.length > 0)) {
+      runs.push({
+        dir: at,
+        entry: reading.entry,
+        preloads: reading.preloads,
+        runtime: reading.runtime,
+      });
+    }
+  };
+  const readLine = (source: string, start: string | undefined): void => {
+    let at = start;
+    for (const list of shellLine(source)) {
+      let outcomes: readonly Outcome[] = [{ dir: at, ok: true }];
+      for (const pipeline of list.pipelines) {
+        const { operator } = pipeline;
+        const reached = outcomes.filter(
+          (one) => operator === undefined || one.ok === (operator === "&&"),
+        );
+        const where = reached.length === 0 ? undefined : oneDirectory(reached);
+        if (where !== undefined) {
+          pipeline.commands.forEach((words) => {
+            readCommand(words, where);
+          });
+        }
+        const next = reached.flatMap((one) => outcomesOf(pipeline, one.dir));
+        const passed = outcomes.filter((one) => !reached.includes(one));
+        outcomes = [
+          ...new Map(
+            [...passed, ...next].map((one) => [`${String(one.ok)}\u0000${one.dir ?? ""}`, one]),
+          ).values(),
+        ];
+      }
+      if (!list.background) {
+        at = oneDirectory(outcomes);
+      }
+    }
+  };
+  readLine(text, dir);
+  if (dir !== undefined) {
+    for (const words of shellLine(text).flatMap((list) =>
+      list.pipelines.flatMap((pipeline) => pipeline.commands),
+    )) {
+      commands.push({ dir, words: words.map((word) => word.value) });
+      configurations.push(...configurationsOf(words).map((written) => ({ dir, written })));
+    }
+  }
+  const unique = <T>(all: readonly T[]): T[] => [
+    ...new Map(all.map((one) => [JSON.stringify(one), one])).values(),
+  ];
+  return {
+    runs,
+    commands: unique(commands),
+    configurations: unique(configurations),
+    held: text,
+  };
+}
+
+/** The extensions a runtime or a loader tries after a path written without one. */
+const TRIED_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"] as const;
+
+/** One file a run loads, as written, and every absolute path it may be at. */
+interface Load {
+  readonly written: string;
+  readonly paths: readonly string[];
+}
+
+/**
+ * The files `run` loads: its entry, and each preload written as a path. Each may be at its
+ * path, with each extension tried, and as a directory's `index` file.
+ */
+export function loadsOf(run: Run): readonly Load[] {
+  const written = [
+    ...(run.entry === undefined
+      ? []
+      : [{ written: run.entry, path: resolvePath(run.dir, run.entry) }]),
+    ...run.preloads.flatMap((preload) => {
+      const target = preloadTarget(preload, run.dir);
+      return target !== undefined && "path" in target
+        ? [{ written: preload.specifier, path: target.path }]
+        : [];
+    }),
+  ];
+  return written.map(({ written: one, path }) => ({
+    written: one,
+    paths: [
+      path,
+      ...TRIED_EXTENSIONS.map((extension) => `${path}${extension}`),
+      ...TRIED_EXTENSIONS.map((extension) => joinPath(path, `index${extension}`)),
+    ],
+  }));
+}
+
+/** The module specifiers `run` preloads that name a package rather than a path. */
+export function preloadedPackages(run: Run): readonly string[] {
+  return run.preloads.flatMap((preload) => {
+    const target = preloadTarget(preload, run.dir);
+    return target !== undefined && "package" in target ? [target.package] : [];
+  });
+}
+
+/** One path a command string names, with the word or the load that names it. */
+interface NamedPath {
+  readonly path: string;
+  readonly written: string;
+}
+
+/**
+ * Every path `reading` names: each static word of its commands read against the directory the
+ * command runs in, a word holding `*` aside, which a tool reads as a pattern, and every path a
+ * file a read command runs or preloads may be at.
+ */
+export function pathsNamed(reading: CommandReading): readonly NamedPath[] {
+  const named = [
+    ...reading.commands.flatMap(({ dir, words }) =>
+      words.flatMap((word) =>
+        word === undefined || word.includes("*")
+          ? []
+          : [{ path: resolvePath(dir, word), written: word }],
+      ),
+    ),
+    ...reading.runs
+      .flatMap(loadsOf)
+      .flatMap(({ written, paths }) => paths.map((path) => ({ path, written }))),
+  ];
+  return [...new Map(named.map((one) => [`${one.path}\u0000${one.written}`, one])).values()];
+}