@cplieger/deadset-ts 8.0.0-dev.2 → 8.0.0-dev.20

package/src/commands/read.ts

@@ -0,0 +1,242 @@
+/**
+ * The one reader of every command string the analysis reads. Layer 3, the holding rule
+ * `roots/root-set.ts` applies through `commands/held.ts` and `text/named-files.ts`, reads every
+ * word of the string 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,
+  handedOn,
+  testRun,
+  type Outcome,
+  type Preload,
+  type TestRun,
+} from "./tools.ts";
+import { APPENDED_EXTENSIONS } from "../extensions.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;
+}
+
+/** One test run a command string writes, with the directory it runs in. */
+export interface CommandTests extends TestRun {
+  readonly dir: 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[];
+  /** Each test run of {@link commands}, as `testRun` reads the command a launcher hands on. */
+  readonly tests: readonly CommandTests[];
+  /** The string's whole text, which the dependency rule reads. */
+  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 tests: CommandTests[] = [];
+  const readTests = (words: readonly Word[], at: string): void => {
+    const run = testRun(words);
+    if (run !== undefined) {
+      tests.push({ dir: at, ...run });
+    }
+  };
+  const readCommand = (words: readonly Word[], at: string): void => {
+    commands.push({ dir: at, words: words.map((word) => word.value) });
+    const [handed, reading] = handedOn(words);
+    readTests(handed, at);
+    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 })));
+      readTests(handedOn(words)[0], dir);
+    }
+  }
+  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),
+    tests: unique(tests),
+    held: text,
+  };
+}
+
+/** 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,
+      ...APPENDED_EXTENSIONS.map((extension) => `${path}${extension}`),
+      ...APPENDED_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()];
+}

package/src/commands/shell.ts

@@ -0,0 +1,228 @@
+/**
+ * Layer 1 of the command reader: one command line, parsed by the vendored shell parser, as
+ * its and-or lists, their pipelines and the words of each simple command, and the one place
+ * that decides which parts of a word the shell computes and which words a brace expansion
+ * stands for, for layer 3 too.
+ */
+
+import {
+  parse,
+  type CommandNode,
+  type ParsedScript,
+  type PipelineNode,
+  type Word as ShellWord,
+  type WordPart,
+} from "../vendor/unbash/parser.ts";
+
+/**
+ * The character that stands, in a word's text as layer 3 reads it, for a part only the run
+ * knows. It is a private-use character, so no path holds it, and the parser reads it as
+ * literal text.
+ */
+export const PART = "\uE000";
+
+/** A GitHub Actions expression, which the runner substitutes before any shell reads the line. */
+const EXPRESSION = /\$\{\{[\s\S]*?\}\}/gu;
+
+/** `text` with each `${{ }}` expression in it read as a part only the run knows. */
+export function expressionsAsParts(text: string): string {
+  return text.replace(EXPRESSION, PART);
+}
+
+/** One command line parsed, each `${{ }}` expression in it read as a part only the run knows. */
+export function parseLine(source: string): ParsedScript {
+  return parse(expressionsAsParts(source));
+}
+
+/** The words a word's brace expansions stand for, at most this many. */
+const ALTERNATIVES = 64;
+
+/** One word of a simple command: its value, or `undefined` where the shell computes it. */
+export interface Word {
+  readonly value: string | undefined;
+  /** The word as the line writes it. */
+  readonly text: string;
+  /** Where the shell expands it to one text, that text with each part it computes as {@link PART}. */
+  readonly written?: string;
+}
+
+/** One pipeline of an and-or list. */
+export interface Pipeline {
+  /** The operator that joins it to the pipeline before it, `undefined` for a list's first. */
+  readonly operator: "&&" | "||" | undefined;
+  /** Whether a `!` inverts its status. */
+  readonly negated: boolean;
+  /** The words of each member that is a simple command with a program word. */
+  readonly commands: readonly (readonly Word[])[];
+  /**
+   * Whether it has one member, which runs in the line's own shell; with several, each member
+   * runs in a subshell of its own, whatever it is.
+   */
+  readonly alone: boolean;
+  /**
+   * Whether its one member is no simple command but a compound command, whose commands may
+   * change the line's shell's directory, or a function definition, whose later calls may.
+   */
+  readonly opaque: boolean;
+}
+
+/** One and-or list: its pipelines, run in a subshell where `&` sends it to the background. */
+interface List {
+  readonly background: boolean;
+  readonly pipelines: readonly Pipeline[];
+}
+
+/**
+ * The text one part of a word stands for: a literal's, a quoted text's or an escape's value,
+ * and {@link PART} for every part the shell computes, a glob among them.
+ */
+function partText(part: WordPart): string {
+  switch (part.type) {
+    case "Literal":
+    case "SingleQuoted":
+    case "AnsiCQuoted":
+      return part.value;
+    case "DoubleQuoted":
+      return part.parts.map((child) => (child.type === "Literal" ? child.value : PART)).join("");
+    default:
+      return PART;
+  }
+}
+
+/** The texts the word `piece` of a brace expansion stands for, or a part where it is no one word. */
+function alternativeTexts(piece: string): readonly string[] {
+  if (piece === "") {
+    return [""];
+  }
+  const script = parse(piece);
+  const [statement, ...more] = script.commands;
+  const command = statement?.command;
+  return (script.errors ?? []).length === 0 &&
+    more.length === 0 &&
+    command?.type === "Command" &&
+    command.name !== undefined &&
+    command.prefix.length === 0 &&
+    command.suffix.length === 0
+    ? heldTextsOf(command.name)
+    : [PART];
+}
+
+/**
+ * The texts a brace expansion stands for, its comma-separated alternatives, or a part where it
+ * has none, a sequence such as `{1..3}` among them.
+ */
+function braceTexts(text: string): readonly string[] {
+  const inner = text.slice(1, -1);
+  const pieces: string[] = [];
+  let depth = 0;
+  let from = 0;
+  let quote = "";
+  for (let at = 0; at < inner.length; at += 1) {
+    const char = inner.charAt(at);
+    if (char === "\\") {
+      at += 1;
+    } else if (quote !== "") {
+      quote = char === quote ? "" : quote;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+    } else if (char === "{" || char === "}") {
+      depth += char === "{" ? 1 : -1;
+    } else if (char === "," && depth === 0) {
+      pieces.push(inner.slice(from, at));
+      from = at + 1;
+    }
+  }
+  if (pieces.length === 0) {
+    return [PART];
+  }
+  pieces.push(inner.slice(from));
+  return pieces.flatMap(alternativeTexts);
+}
+
+/**
+ * Each word the shell may expand `word` to, as layer 3 reads it: its quotes removed, each brace
+ * expansion read as its alternatives, past {@link ALTERNATIVES} words as a part, and each part
+ * it computes, a tilde that starts it unquoted among them, as {@link PART}.
+ */
+export function heldTextsOf(word: ShellWord): readonly string[] {
+  const { parts } = word;
+  const [first] = parts ?? [];
+  const tilde =
+    parts === undefined
+      ? word.text.startsWith("~")
+      : first?.type === "Literal" && first.text.startsWith("~");
+  let texts: readonly string[] = [parts === undefined ? word.value : ""];
+  for (const part of parts ?? []) {
+    const options = part.type === "BraceExpansion" ? braceTexts(part.text) : [partText(part)];
+    const next = texts.flatMap((text) => options.map((option) => `${text}${option}`));
+    texts = next.length > ALTERNATIVES ? texts.map((text) => `${text}${PART}`) : next;
+  }
+  return tilde ? texts.map((text) => `${PART}${text.slice(1)}`) : texts;
+}
+
+/** One word as layer 1 reads it: static only where the shell expands it to one text with no part. */
+export function wordOf(word: ShellWord): Word {
+  const [only, ...more] = heldTextsOf(word);
+  const one = more.length === 0 ? only : undefined;
+  const known = one !== undefined && !one.includes(PART);
+  return {
+    value: known ? word.value : undefined,
+    text: word.text,
+    ...(one === undefined ? {} : { written: one }),
+  };
+}
+
+/**
+ * Whether one member of a pipeline, run in the line's own shell, may change that shell's
+ * directory without being a simple command: POSIX XCU 2.9.4 runs every compound command but
+ * `( )` in the current environment, and a function body runs there when called.
+ */
+function isOpaque(node: CommandNode): boolean {
+  switch (node.type) {
+    case "Command":
+    case "Subshell":
+    case "Coproc":
+    case "TestCommand":
+    case "ArithmeticCommand":
+      return false;
+    case "Redirected":
+      return isOpaque(node.command);
+    default:
+      return true;
+  }
+}
+
+function pipelineOf(node: PipelineNode, operator: Pipeline["operator"]): Pipeline {
+  const members = node.type === "Pipeline" ? node.commands : [node];
+  const negated =
+    node.type === "Pipeline" && node.prefixes.some((prefix) => prefix.type === "Negation");
+  const commands = members.flatMap((member) =>
+    member.type === "Command" && member.name !== undefined
+      ? [[member.name, ...member.suffix.filter((part) => part.type === "Word")].map(wordOf)]
+      : [],
+  );
+  const alone = members.length === 1;
+  return { operator, negated, commands, alone, opaque: alone && members.some(isOpaque) };
+}
+
+/**
+ * The and-or lists one command line runs, or none where any of it does not parse. A simple
+ * command's assignments and redirections are no words; a part that is no simple command
+ * gives no words, and marks its pipeline where it may change the line's directory.
+ */
+export function shellLine(source: string): readonly List[] {
+  const script = parseLine(source);
+  if ((script.errors ?? []).length > 0) {
+    return [];
+  }
+  return script.commands.map((statement) => {
+    const { command } = statement;
+    const pipelines =
+      command.type === "AndOr"
+        ? command.commands.map((one, at) =>
+            pipelineOf(one, at === 0 ? undefined : command.operators[at - 1]),
+          )
+        : [pipelineOf(command, undefined)];
+    return { background: statement.background === true, pipelines };
+  });
+}