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

package/src/dependencies.ts

@@ -54,18 +54,24 @@ import type { DependencySection, Module } from "./ref.ts";
 import { UNANSWERED } from "./query.ts";
 import type { Handle, ProjectView } from "./session.ts";
 import { sourceFilesOf, type SourceFiles } from "./source-files.ts";
-import { manifestCommands } from "./manifest.ts";
-import { workflowCommands, workflowTokens } from "./workflow-steps.ts";
+import { manifestCommands, nodemonTexts } from "./manifest.ts";
+import { commandFileTexts, workflowCommands } from "./workflow-steps.ts";
+import {
+  pathsNamed,
+  preloadedPackages,
+  readCommands,
+  type CommandReading,
+} from "./commands/read.ts";
+import { heldNames } from "./text/named-files.ts";
 import { bytewise } from "./text/compare.ts";
 import { isRecord } from "./json-document.ts";
 import { inInstalledPackages, INSTALLED_PACKAGES, MANIFEST, readDocument } from "./fs/manifest.ts";
-import { commandsOf, scriptTokens } from "./text/shell.ts";
 
 const MODULES_SEGMENT = `/${INSTALLED_PACKAGES}/`;
 const TYPES_SCOPE = "@types/";
 
-/** A script token naming a JavaScript file by a path no expansion changes. */
-const SCRIPT_FILE = /^[^$`{*?[~]+\.(?:js|mjs|cjs)$/u;
+/** A path a command names that is a JavaScript file's. */
+const SCRIPT_FILE = /\.(?:js|mjs|cjs)$/u;
 
 /** The manifest sections a dependency is declared in, each by the selector its reference spells. */
 const SECTIONS: readonly (readonly [string, DependencySection])[] = [
@@ -444,10 +450,10 @@ export function projectNeeds<Brand>(
 }
 
 /**
- * The JavaScript files no program holds that a script of a manifest at or above one of the
- * project's files runs, each with the directory of that manifest, and those a workflow
- * step or git hook runs, with the target root's: a token naming such a file below the
- * target root and in no `node_modules`, read against the manifest's directory.
+ * The JavaScript files no program holds that a command string of a manifest at or above one of
+ * the project's files runs or names, each with the directory of that manifest, and those a
+ * workflow step or git hook names, with the target root's: a path `pathsNamed` reads, below the
+ * target root and in no `node_modules`.
  */
 function scriptRunFiles(
   host: Host,
@@ -464,23 +470,28 @@ function scriptRunFiles(
       dirs.add(dir);
     }
   }
-  const tokens = new Map<string, ReadonlySet<string>>([
-    [root, new Set(workflowTokens(host, root))],
+  const named = new Map<string, readonly string[]>([
+    [
+      root,
+      workflowReadings(host, root)
+        .flatMap(pathsNamed)
+        .map((one) => one.path),
+    ],
   ]);
   for (const dir of dirs) {
     const read = readDocument(host, joinPath(dir, MANIFEST));
     if (read !== undefined && isRecord(read.value)) {
-      const own = scriptTokensOf(read.value);
-      tokens.set(dir, dir === root ? new Set([...own, ...(tokens.get(root) ?? [])]) : own);
+      const own = manifestReadings(host, dir, read.value)
+        .flatMap(pathsNamed)
+        .map((one) => one.path);
+      named.set(dir, [...own, ...(named.get(dir) ?? [])]);
     }
   }
   const found: { path: string; manifestDir: string }[] = [];
-  for (const [manifestDir, held] of tokens) {
-    for (const token of held) {
-      const path = SCRIPT_FILE.test(token) ? resolvePath(manifestDir, token) : undefined;
-      const below = path === undefined ? undefined : relativePath(root, path);
+  for (const [manifestDir, paths] of named) {
+    for (const path of new Set(paths)) {
+      const below = SCRIPT_FILE.test(path) ? relativePath(root, path) : undefined;
       if (
-        path !== undefined &&
         below !== undefined &&
         !inInstalledPackages(below) &&
         !files.byName.has(path) &&
@@ -493,6 +504,65 @@ function scriptRunFiles(
   return found;
 }
 
+/** What the command strings of one manifest, its scripts and nodemon's command, run. */
+function manifestReadings(
+  host: Host,
+  dir: string,
+  manifest: Record<string, unknown>,
+): readonly CommandReading[] {
+  return manifestCommands(host, dir, manifest).map(({ command }) => readCommands(command, dir));
+}
+
+/** What one manifest's command strings use, held with the whole text of nodemon's configuration. */
+function manifestUses(host: Host, dir: string, manifest: Record<string, unknown>): CommandUses {
+  const uses = usesOf(manifestReadings(host, dir, manifest));
+  const texts = nodemonTexts(host, dir, manifest).map(({ text }) => text);
+  return { ...uses, held: [uses.held, ...texts].join("\n") };
+}
+
+/** What the target root's workflow steps, git hooks and recipes use, held with their files' whole text. */
+function workflowUses(host: Host, targetRoot: string): CommandUses {
+  const uses = usesOf(workflowReadings(host, targetRoot));
+  return { ...uses, held: [uses.held, ...commandFileTexts(host, targetRoot)].join("\n") };
+}
+
+/**
+ * What the target root's workflow steps, git hooks, hook managers and recipes run, each held
+ * with the directory the file writes for it.
+ */
+function workflowReadings(host: Host, targetRoot: string): readonly CommandReading[] {
+  return workflowCommands(host, targetRoot).map(({ text, dir, writtenDirectory }) => {
+    const reading = readCommands(text, dir);
+    return { ...reading, held: [reading.held, writtenDirectory ?? ""].join("\n") };
+  });
+}
+
+/** What some command strings say about the packages they use. */
+interface CommandUses {
+  /** Every static word of their commands, which uses a dependency whose command it is. */
+  readonly words: ReadonlySet<string>;
+  /** The package each module a read command preloads by name is in. */
+  readonly preloads: ReadonlySet<string>;
+  /** The text layer 3 reads, all of every string, whose every package or command name is a use. */
+  readonly held: string;
+}
+
+function usesOf(readings: readonly CommandReading[]): CommandUses {
+  return {
+    words: new Set(
+      readings.flatMap((one) =>
+        one.commands.flatMap((command) => command.words.flatMap((word) => word ?? [])),
+      ),
+    ),
+    preloads: new Set(
+      readings
+        .flatMap((one) => one.runs.flatMap(preloadedPackages))
+        .flatMap((specifier) => packageOfSpecifier(specifier) ?? []),
+    ),
+    held: readings.map((one) => one.held).join("\n"),
+  };
+}
+
 /** The declarations of the inventory a use written at one node belongs to. */
 function ownersOf(file: SourceFile, held: Inventory, node: Node): readonly string[] {
   const parent = node.parent as Node | undefined;
@@ -846,102 +916,6 @@ export function declarationKey(dependency: DeclaredDependency): string {
   return `${dependency.position.path}\u0000${dependency.name}`;
 }
 
-/** Every token of every value of one manifest's `scripts` member. */
-function scriptTokensOf(manifest: Record<string, unknown>): ReadonlySet<string> {
-  const scripts = manifest["scripts"];
-  const found = new Set<string>();
-  if (isRecord(scripts)) {
-    for (const command of Object.values(scripts)) {
-      if (typeof command === "string") {
-        scriptTokens(command).forEach((token) => found.add(token));
-      }
-    }
-  }
-  return found;
-}
-
-/**
- * The runtime flags whose value is a module loaded before the entry, as `--flag value` or
- * `--flag=value`: https://nodejs.org/api/cli.html#--importmodule,
- * https://nodejs.org/api/cli.html#--experimental-loadermodule,
- * https://nodejs.org/api/cli.html#-r---require-module
- */
-const PRELOAD_FLAGS: ReadonlySet<string> = new Set([
-  "--experimental-loader",
-  "--import",
-  "--loader",
-  "--require",
-  "-r",
-]);
-
-/**
- * The programs that pass a preload flag to the runtime they start: Node itself, and the
- * runners that forward Node's flags or read the same `--require`:
- * https://mochajs.org/#-require-module-r-module, https://tsx.is/node-enhancement,
- * https://typestrong.org/ts-node/docs/options#require,
- * https://github.com/remy/nodemon#running-non-node-scripts
- */
-const PRELOADING_PROGRAMS: ReadonlySet<string> = new Set([
-  "mocha",
-  "node",
-  "nodemon",
-  "ts-node",
-  "tsx",
-]);
-
-/** The programs that run the command after them, and an environment assignment before it. */
-const LAUNCHERS: ReadonlySet<string> = new Set(["cross-env", "env", "npx"]);
-const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/u;
-
-/**
- * The packages `scripts` preload by a runtime flag's bare module specifier, a flag
- * counting only in a command whose program passes it to the runtime, and for Node only
- * before the script it runs, whose own arguments come after it.
- */
-function preloadsOf(scripts: readonly string[]): ReadonlySet<string> {
-  const found = new Set<string>();
-  for (const script of scripts) {
-    for (const command of commandsOf(script)) {
-      const tokens = scriptTokens(command);
-      let at = 0;
-      while (
-        at < tokens.length &&
-        (ASSIGNMENT.test(tokens[at] ?? "") || LAUNCHERS.has(tokens[at] ?? ""))
-      ) {
-        at += 1;
-      }
-      const path = tokens[at] ?? "";
-      const program = path.slice(path.lastIndexOf("/") + 1);
-      if (!PRELOADING_PROGRAMS.has(program)) {
-        continue;
-      }
-      for (at += 1; at < tokens.length; at += 1) {
-        const token = tokens[at] ?? "";
-        if (!token.startsWith("-")) {
-          if (program === "node") {
-            break;
-          }
-          continue;
-        }
-        const equals = token.indexOf("=");
-        const flag = equals < 0 ? token : token.slice(0, equals);
-        if (!PRELOAD_FLAGS.has(flag)) {
-          continue;
-        }
-        if (equals < 0) {
-          at += 1;
-        }
-        const value = equals < 0 ? tokens[at] : token.slice(equals + 1);
-        const name = value === undefined ? undefined : packageOfSpecifier(value);
-        if (name !== undefined) {
-          found.add(name);
-        }
-      }
-    }
-  }
-  return found;
-}
-
 /** Whether a path below the target root lies in the directory `dir` below it, `""` being the root. */
 function isInside(path: string, dir: string): boolean {
   return dir === "" || path.startsWith(`${dir}/`);
@@ -1036,8 +1010,7 @@ export function dependenciesOf(
       unbuilt.add(path);
     }
   }
-  const workflow = new Set(workflowTokens(host, targetRoot));
-  const workflowPreloads = preloadsOf(workflowCommands(host, targetRoot));
+  const workflow = workflowUses(host, targetRoot);
   const declared: DeclaredDependency[] = [];
   const ran = new Set<string>();
   const peers = new Map<string, readonly string[]>();
@@ -1047,25 +1020,28 @@ export function dependenciesOf(
     if (read === undefined || !isRecord(read.value)) {
       continue;
     }
-    const tokens = scriptTokensOf(read.value);
-    const preloads = preloadsOf(
-      manifestCommands(host, dir, read.value).map(({ command }) => command),
-    );
+    const own = manifestUses(host, dir, read.value);
+    const held = `${own.held}\n${workflow.held}`;
     for (const dependency of declaredIn(read.text, read.value, path, scopeOf(path))) {
       const found = installedOf(host, dir, dependency.name);
       if (found === undefined && uninstalledHere.has(dir)) {
         continue;
       }
       declared.push(dependency);
-      if (preloads.has(dependency.name) || workflowPreloads.has(dependency.name)) {
+      if (
+        own.preloads.has(dependency.name) ||
+        workflow.preloads.has(dependency.name) ||
+        heldNames(held, [dependency.name]).size > 0
+      ) {
         ran.add(declarationKey(dependency));
       }
       if (found === undefined) {
         continue;
       }
       peers.set(declarationKey(dependency), found.peers);
-      const runs = (command: string): boolean => tokens.has(command) || workflow.has(command);
-      if (found.commands.some(runs)) {
+      const runs = (command: string): boolean =>
+        own.words.has(command) || workflow.words.has(command);
+      if (found.commands.some(runs) || heldNames(held, found.commands).size > 0) {
         ran.add(declarationKey(dependency));
       }
     }

package/src/load/synthesize.ts

@@ -5,6 +5,7 @@
  * is written for.
  */
 
+import { readCommands } from "../commands/read.ts";
 import { CONVENTION_ROWS } from "../convention-rows.ts";
 import type { Conventions } from "../conventions.ts";
 import { holdsManifest, MANIFEST, readManifestAt, type ManifestRead } from "../fs/manifest.ts";
@@ -12,6 +13,7 @@ import { filesBelow } from "../fs/tree.ts";
 import type { Host } from "../host.ts";
 import { JAVASCRIPT_FILE, minified, minifiedByName } from "../javascript-file.ts";
 import { isRecord } from "../json-document.ts";
+import { manifestCommands } from "../manifest.ts";
 import { ancestors, dirnamePath, joinPath, relativePath } from "../paths.ts";
 import type { Engine } from "../session.ts";
 import { bytewise } from "../text/compare.ts";
@@ -133,12 +135,22 @@ const RUNTIME_OPTIONS = {
 /** The manifest members that say a package is written for Node. */
 const NODE_MEMBERS = ["main", "exports", "bin", "type"] as const;
 
-/** Whether one manifest says its package runs under Node, `engines.node` included; its scripts are not read. */
-function writtenForNode(manifest: Readonly<Record<string, unknown>>): boolean {
+/**
+ * Whether one manifest says its package runs under Node: a Node member, `engines.node`
+ * included, or a command string of it that runs a file with `node`, as `commands/read.ts` reads it.
+ */
+function writtenForNode(
+  host: Host,
+  dir: string,
+  manifest: Readonly<Record<string, unknown>>,
+): boolean {
   const { engines } = manifest;
   return (
     NODE_MEMBERS.some((member) => manifest[member] !== undefined) ||
-    (isRecord(engines) && engines["node"] !== undefined)
+    (isRecord(engines) && engines["node"] !== undefined) ||
+    manifestCommands(host, dir, manifest).some(({ command }) =>
+      readCommands(command, dir).runs.some((run) => run.runtime === "node"),
+    )
   );
 }
 
@@ -172,7 +184,8 @@ interface Forming {
 /**
  * Each group's program, given the module system of the runtime its package is written for: a
  * bundler's where a row of a tool that bundles applies through the group's manifest or the
- * root's, else Node's where its manifest says the package runs under Node, under which a file's
+ * root's, else Node's where its manifest says the package runs under Node or a command string of
+ * it runs a file with `node`, under which a file's
  * extension and its package's `type` decide its module format, else a bundler's, which reads a
  * file with no module syntax as a classic script, as a browser loads it.
  */
@@ -189,7 +202,7 @@ export function formedPrograms(
       !bundling.has(MANIFEST) &&
       (below === undefined || !bundling.has(below)) &&
       group.manifest.kind === "read" &&
-      writtenForNode(group.manifest.manifest)
+      writtenForNode(host, group.dir, group.manifest.manifest)
         ? "node"
         : "bundler";
     const configFile = writtenPath(host, joinPath(group.dir, GROUP_CONFIGURATION));

package/src/manifest.ts

@@ -9,9 +9,7 @@ import type { Host } from "./host.ts";
 import { isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 import { isRecord } from "./json-document.ts";
 import { MANIFEST, manifestAt, readJSON } from "./fs/manifest.ts";
-import { scriptTokens } from "./text/shell.ts";
-
-/** The manifest's own name. */
+import { pathsNamed, readCommands } from "./commands/read.ts";
 
 /** The three members that name an entry point beside `exports` and `bin`. */
 const LEGACY_MEMBERS = ["main", "module", "types"] as const;
@@ -22,17 +20,17 @@ type EntryRole =
   | "import"
   /** A shell running the package's command, which is a caller that exists. */
   | "run"
-  /** A token of one of the package's scripts, or the whole of a command string the package runs. */
+  /** A path one of the package's scripts names or runs, or a text layer 3 holds for the package. */
   | "script";
 
-/** One entry point the manifest names, or the whole of one command string the package runs. */
+/** One entry point the manifest names, or one text layer 3 holds for the package. */
 export interface ManifestEntry {
   /**
    * The member that named it as a maintainer edits it, `main`, `bin["deadset-ts"]` or
    * `exports["."]["import"]`: what a root reports as the string that named it.
    */
   readonly member: string;
-  /** The target the member carries, resolved against the manifest's directory, or that directory for a whole command string. */
+  /** The target the member carries, resolved against the manifest's directory, or that directory for a held text. */
   readonly path: string;
   readonly role: EntryRole;
   /**
@@ -43,11 +41,12 @@ export interface ManifestEntry {
   /** The directory of the manifest that names it, which `path` was resolved against. */
   readonly dir: string;
   /**
-   * On the entry of a whole command string, which names no entry point and whose path is the
-   * manifest's directory, that string: rooting enters no file for it and holds each file
-   * `spelledFiles` reads it to name.
+   * On an entry that names no entry point, whose path is the manifest's directory, the text
+   * layer 3 holds: a whole command string the package runs, or the whole text of nodemon's
+   * configuration one is read from. Rooting enters no file for it and holds each file
+   * `spelledFiles` reads the text to name.
    */
-  readonly command?: string;
+  readonly held?: string;
 }
 
 /**
@@ -67,6 +66,29 @@ function below(member: string, key: string): string {
   return `${member}[${JSON.stringify(key)}]`;
 }
 
+/**
+ * The whole text of nodemon's configuration, the manifest's `nodemonConfig` member and the
+ * `nodemon.json` beside it, by the member each is. Layer 3 holds it whole, because nodemon runs
+ * commands from keys besides `exec`, `events` among them: https://github.com/remy/nodemon#config-files
+ */
+export function nodemonTexts(
+  host: Host,
+  dir: string,
+  manifest: Record<string, unknown>,
+): readonly { readonly member: string; readonly text: string }[] {
+  const member = manifest["nodemonConfig"];
+  let file: string | undefined;
+  try {
+    file = host.readFile(joinPath(dir, "nodemon.json"));
+  } catch {
+    file = undefined;
+  }
+  return [
+    ...(member === undefined ? [] : [{ member: "nodemonConfig", text: JSON.stringify(member) }]),
+    ...(file === undefined ? [] : [{ member: "nodemon.json", text: file }]),
+  ];
+}
+
 /**
  * The command strings one manifest runs, each at the member it is written under: each of its
  * `scripts`, and the `exec` command of nodemon's configuration, in the manifest's `nodemonConfig`
@@ -127,9 +149,10 @@ function exportTargets(value: unknown, member: string, found: Omit<ManifestEntry
 export interface Manifest {
   /**
    * Every entry the manifest names, by absolute path, in the order read: the entry points `main`,
-   * `module`, `types`, `browser` and each file it maps, each `bin` command, every `exports` target
-   * and per script each token, which names a file only where one is at its path; and per command
-   * string {@link manifestCommands} reads one entry of its whole text, which is no entry point.
+   * `module`, `types`, `browser` and each file it maps, each `bin` command, every `exports` target,
+   * and per command string {@link manifestCommands} reads each path `pathsNamed` reads, which
+   * names a file only where one is at it, then one entry of its whole text, and one entry of
+   * each of {@link nodemonTexts}, which are no entry point.
    */
   readonly entries: readonly ManifestEntry[];
   /**
@@ -191,20 +214,15 @@ export function readManifest(host: Host, targetRoot: string): Manifest {
 
   exportTargets(manifest["exports"], "exports", found);
 
-  const scripts = manifest["scripts"];
-  if (isRecord(scripts)) {
-    for (const [name, command] of Object.entries(scripts)) {
-      if (typeof command !== "string") {
-        continue;
-      }
-      const member = below("scripts", name);
-      for (const path of new Set(scriptTokens(command))) {
-        found.push({ member, path, role: "script", published: false });
-      }
+  for (const { member, command } of manifestCommands(host, targetRoot, manifest)) {
+    // Read against ".", so each path stays relative until the entries are resolved below.
+    for (const path of new Set(pathsNamed(readCommands(command, ".")).map((one) => one.path))) {
+      found.push({ member, path, role: "script", published: false });
     }
+    found.push({ member, path: ".", role: "script", published: false, held: command });
   }
-  for (const { member, command } of manifestCommands(host, targetRoot, manifest)) {
-    found.push({ member, path: ".", role: "script", published: false, command });
+  for (const { member, text } of nodemonTexts(host, targetRoot, manifest)) {
+    found.push({ member, path: ".", role: "script", published: false, held: text });
   }
 
   return {

package/src/roots.ts

@@ -54,7 +54,8 @@ import { bytewise } from "./text/compare.ts";
 import { holdsManifest } from "./fs/manifest.ts";
 import { globExpression } from "./text/glob.ts";
 import { spelledFiles } from "./text/named-files.ts";
-import { commandDirectories, workflowCommands } from "./workflow-steps.ts";
+import { commandFileTexts, workflowCommands } from "./workflow-steps.ts";
+import { readCommands } from "./commands/read.ts";
 
 /** Why one declaration is a root. */
 export type RootKind =
@@ -66,7 +67,7 @@ export type RootKind =
   | "manifest-entry"
   /** A file the manifest names as a command, and what it exports outside the published API. */
   | "manifest-binary"
-  /** A file a token of a manifest's script names, and what it exports. */
+  /** A file a manifest's script names or runs, as `commands/read.ts` reads it, and what it exports. */
   | "script"
   /**
    * A global a declaration file declares as an alias of a module's export, and the
@@ -123,7 +124,7 @@ export interface Roots {
   readonly unanswered: readonly string[];
   /** Every manifest entry naming a file to import or run that reads back to no file of this project. */
   readonly unmappedEntries: readonly ManifestEntry[];
-  /** Every package whose command strings name, as `spelledFiles` reads them, an own file no root enters with all it exports. */
+  /** Every package whose command strings, in what no command reader understands, name an own file no root enters with all it exports. */
   readonly heldScripts: readonly HeldScripts[];
 }
 
@@ -346,11 +347,11 @@ function childrenOf(held: Inventory): ReadonlyMap<string, readonly InventorySymb
 }
 
 /**
- * Per package, the own files its command strings name as plain text, but those a root enters
- * with all they export: a command can use no more of such a file than the root keeps live. A
- * manifest's are its entries' whole command strings, and the target root's package has the
- * workflow steps, git hooks and makefile recipes beside its own, with the directories its
- * workflow steps and lefthook commands run in, where a `.` names that directory's index file.
+ * Per package, the own files its held texts name, as `spelledFiles` reads them, but those a
+ * root enters with all they export: a command can use no more of such a file than the root
+ * keeps live. A manifest's are its entries' held texts, and the target root's package has the
+ * workflow steps, git hooks and makefile recipes beside its own, with the whole text of each
+ * file `commandFileTexts` reads.
  */
 function scriptHolds(
   entries: readonly ManifestEntry[],
@@ -373,13 +374,19 @@ function scriptHolds(
   const commands = new Map<string, string[]>([
     [
       resolvePath(cwd, targetRoot),
-      [...workflowCommands(host, targetRoot), ...commandDirectories(host, targetRoot)],
+      [
+        ...workflowCommands(host, targetRoot).flatMap(({ text, dir, writtenDirectory }) => [
+          readCommands(text, dir).held,
+          ...(writtenDirectory === undefined ? [] : [writtenDirectory]),
+        ]),
+        ...commandFileTexts(host, targetRoot),
+      ],
     ],
   ]);
   for (const entry of entries) {
-    if (entry.command !== undefined) {
+    if (entry.held !== undefined) {
       const dir = resolvePath(cwd, entry.dir);
-      commands.set(dir, [...(commands.get(dir) ?? []), entry.command]);
+      commands.set(dir, [...(commands.get(dir) ?? []), entry.held]);
     }
   }
   const held: HeldScripts[] = [];
@@ -464,7 +471,7 @@ export function roots<Brand>(
     })),
   ];
   const scripted = entries.flatMap(({ entry }) =>
-    entry.role === "script" && entry.command === undefined ? files.named(entry.path) : [],
+    entry.role === "script" && entry.held === undefined ? files.named(entry.path) : [],
   );
   const readBackTo = [
     ...scripted,
@@ -517,7 +524,7 @@ export function roots<Brand>(
   const unmapped: ManifestEntry[] = [];
   const mapped = patterned.map(({ file }) => file);
   for (const { entry } of entries) {
-    if (entry.command !== undefined) {
+    if (entry.held !== undefined) {
       continue;
     }
     const named = entryFiles(entry);

package/src/text/named-files.ts

@@ -1,7 +1,7 @@
 /**
- * The files a command's text names, read as plain text: the text is searched for each file's
- * names, which every spelling of its path contains, so no part of it is split, unquoted or
- * skipped first.
+ * Layer 3 of the command reader: the files and the package names a command's text names, read
+ * as plain text. The text is searched for each name, which every spelling of what it names
+ * contains, so no part of it is split, unquoted or skipped first.
  */
 
 import { dirnamePath, normalizePath, relativePath } from "../paths.ts";
@@ -66,3 +66,26 @@ export function spelledFiles<File>(
   }
   return [...found];
 }
+
+/** A character a package's or a command's name may hold, so one beside a name makes it part of a longer one. */
+const NAME_CHARACTER = /[\w.@-]/u;
+
+/**
+ * Each of `names`, a package's or a command's name, that `text` holds with no name character
+ * before it and no character after it but one a path or a version may go on with, `/`, `.` or
+ * `@` among them: `module-alias/register` holds `module-alias`, and `tsxx` holds no `tsx`.
+ */
+export function heldNames(text: string, names: readonly string[]): ReadonlySet<string> {
+  const found = new Set<string>();
+  for (const name of names) {
+    for (let at = text.indexOf(name); at >= 0 && name !== ""; at = text.indexOf(name, at + 1)) {
+      const before = text.charAt(at - 1);
+      const after = text.charAt(at + name.length);
+      if (!NAME_CHARACTER.test(before) && !/[\w-]/u.test(after)) {
+        found.add(name);
+        break;
+      }
+    }
+  }
+  return found;
+}