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

package/src/entries/workflow-steps.ts

@@ -0,0 +1,432 @@
+/**
+ * The command strings beside a target root's packages: a CI workflow's `run:` steps, the git
+ * hooks, the hook managers' commands and scripts 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 type { SourceFile } from "@typescript/native/ast";
+import type { HeldText } from "../commands/held.ts";
+import { pathsNamed, readCommands, type CommandReading } from "../commands/read.ts";
+import { PART } from "../commands/shell.ts";
+import type { Host } from "../host.ts";
+import { isRecord } from "../json-document.ts";
+import { joinPath, resolvePath } from "../paths.ts";
+import type { SourceFiles } from "../source-files.ts";
+import { filesIn } from "../fs/tree.ts";
+import { yamlDocument } from "../text/yaml.ts";
+
+/** One file a workflow step, git hook or recipe runs or names. */
+interface WorkflowEntry {
+  readonly file: SourceFile;
+  /** The word or the path that named it, as the command writes it. */
+  readonly source: string;
+}
+
+/** One command string and the directory it runs in. */
+interface CommandString {
+  readonly text: string;
+  /**
+   * The directory it runs in, absolute, or `undefined` where the file does not state what runs
+   * where: a directory holding a `${{ }}` expression, which GitHub Actions evaluates.
+   */
+  readonly dir: string | undefined;
+}
+
+const WORKFLOWS = ".github/workflows";
+
+/** The directories whose every file is a git hook script, run as the shell runs it. */
+const HOOK_DIRS = [".husky", ".githooks"] as const;
+
+/** The key setting the directory a workflow step, or each step a `defaults.run` covers, runs in. */
+const WORKING_DIRECTORY = "working-directory";
+
+/** One hook manager's file. */
+interface HookManager {
+  readonly name: string;
+  /** The key its commands are written under. */
+  readonly key: string;
+  /** The key of a command's directory: lefthook's `root`, https://lefthook.dev/configuration/root/ */
+  readonly dirKey?: string;
+  /** Whether its hooks name script files it runs, as lefthook's do. */
+  readonly scripts?: true;
+}
+
+const HOOK_MANAGERS: readonly HookManager[] = [
+  { name: ".pre-commit-config.yaml", key: "entry" },
+  ...["lefthook.yml", "lefthook.yaml", ".lefthook.yml"].map((name): HookManager => ({
+    name,
+    key: "run",
+    dirKey: "root",
+    scripts: true,
+  })),
+];
+
+/**
+ * The directories lefthook searches for a hook's scripts after the file's `source_dir` and
+ * `source_dir_local`: https://github.com/evilmartians/lefthook/blob/master/internal/command/run.go
+ */
+const LEFTHOOK_DIRS = [".config/lefthook", ".config/lefthook-local"] as const;
+
+/** The names GNU make reads a makefile under, in the order it tries them. */
+const MAKEFILES = ["GNUmakefile", "makefile", "Makefile"] as const;
+
+function readText(host: Host, path: string): string | undefined {
+  try {
+    return host.readFile(path);
+  } catch {
+    return undefined;
+  }
+}
+
+/** The text a YAML scalar's value stands for, or `undefined` for a collection or a null. */
+function scalarText(value: unknown): string | undefined {
+  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: Record<string, unknown>): string | undefined {
+  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: string,
+  root: string,
+  key: string,
+  dirKey: string | undefined,
+): readonly CommandString[] {
+  const found: CommandString[] = [];
+  const visit = (node: unknown, inherited: string | undefined): void => {
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        visit(item, inherited);
+      }
+      return;
+    }
+    if (!isRecord(node)) {
+      return;
+    }
+    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),
+      });
+    }
+    for (const value of Object.values(node)) {
+      visit(value, here);
+    }
+  };
+  visit(yamlDocument(text), undefined);
+  return found;
+}
+
+/**
+ * The command lefthook runs for each script a lefthook file's hooks name, each key of a hook's
+ * `scripts` and each `script` of a job in its `jobs`, a group's among them, from each directory
+ * it searches: its `runner`, then the path `<dir>/<hook>/<name>` quoted as lefthook quotes it,
+ * run in the target root: https://lefthook.dev/configuration/Scripts/
+ */
+function lefthookScripts(text: string, root: string): readonly CommandString[] {
+  const document = yamlDocument(text);
+  if (!isRecord(document)) {
+    return [];
+  }
+  const dirs = [
+    scalarText(document["source_dir"]) ?? ".lefthook/",
+    scalarText(document["source_dir_local"]) ?? ".lefthook-local/",
+    ...LEFTHOOK_DIRS,
+  ];
+  const found: CommandString[] = [];
+  const add = (hook: string, name: string, runner: string | undefined): void => {
+    for (const dir of dirs) {
+      const path = `'${joinPath(dir, hook, name).replaceAll("'", "'\\''")}'`;
+      found.push({
+        text: runner === undefined || runner.trim() === "" ? path : `${runner} ${path}`,
+        dir: root,
+      });
+    }
+  };
+  const jobs = (hook: string, list: unknown): void => {
+    for (const job of Array.isArray(list) ? list : []) {
+      const script = isRecord(job) ? scalarText(job["script"]) : undefined;
+      if (isRecord(job) && script !== undefined) {
+        add(hook, script, scalarText(job["runner"]));
+      }
+      const group = isRecord(job) ? job["group"] : undefined;
+      jobs(hook, isRecord(group) ? group["jobs"] : undefined);
+    }
+  };
+  for (const [hook, value] of Object.entries(document)) {
+    const scripts = isRecord(value) ? value["scripts"] : undefined;
+    for (const [name, options] of Object.entries(isRecord(scripts) ? scripts : {})) {
+      add(hook, name, isRecord(options) ? scalarText(options["runner"]) : undefined);
+    }
+    jobs(hook, isRecord(value) ? value["jobs"] : undefined);
+  }
+  return found;
+}
+
+/** The path of each git hook script at `root`, every file in {@link HOOK_DIRS}. */
+function hookScripts(host: Host, root: string): readonly string[] {
+  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: Host, root: string): string | undefined {
+  return MAKEFILES.map((name) => joinPath(root, name)).find(
+    (candidate) => host.kindOf(candidate) === "file",
+  );
+}
+
+/**
+ * One recipe line as make hands it to the shell: each `$$` a `$`, and each reference to a
+ * variable or a function, which make expands first, a part only the run knows:
+ * https://www.gnu.org/software/make/manual/html_node/Reference.html
+ */
+function expandedByMake(line: string): string {
+  let expanded = "";
+  for (let at = 0; at < line.length; at += 1) {
+    const char = line.charAt(at);
+    const next = line.charAt(at + 1);
+    if (char !== "$") {
+      expanded += char;
+    } else if (next === "$") {
+      expanded += "$";
+      at += 1;
+    } else {
+      let end = at + 1;
+      if (next === "(" || next === "{") {
+        const close = next === "(" ? ")" : "}";
+        for (let depth = 0; end < line.length; end += 1) {
+          depth += line.charAt(end) === next ? 1 : line.charAt(end) === close ? -1 : 0;
+          if (depth === 0) {
+            break;
+          }
+        }
+      }
+      expanded += PART;
+      at = Math.min(end, line.length);
+    }
+  }
+  return expanded;
+}
+
+/**
+ * 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,
+ * as make expands it. Make runs each line in a shell of its own.
+ */
+function recipeLines(host: Host, root: string): readonly CommandString[] {
+  const path = makefileAt(host, root);
+  const text = path === undefined ? undefined : readText(host, path);
+  return (text ?? "")
+    .replace(/\\\r?\n/gu, " ")
+    .split(/\r?\n/u)
+    .filter((line) => line.startsWith("\t"))
+    .map((line) => ({
+      text: expandedByMake(line.slice(1).replace(/^[@+-]+/u, "")),
+      dir: root,
+    }));
+}
+
+/**
+ * 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 and the scripts of a lefthook file and the makefile's recipe lines.
+ */
+export function workflowCommands(host: Host, targetRoot: string): readonly CommandString[] {
+  const root = resolvePath(host.workingDirectory(), targetRoot);
+  const workflows = filesIn(host, joinPath(root, WORKFLOWS), (name) => /\.ya?ml$/u.test(name));
+  return [
+    ...workflows.flatMap((name) =>
+      keyedCommands(
+        readText(host, joinPath(root, WORKFLOWS, name)) ?? "",
+        root,
+        "run",
+        WORKING_DIRECTORY,
+      ),
+    ),
+    ...hookScripts(host, root).map((path): CommandString => ({
+      text: readText(host, path) ?? "",
+      dir: root,
+    })),
+    ...HOOK_MANAGERS.flatMap(({ name, key, dirKey, scripts }) => {
+      const text = readText(host, joinPath(root, name)) ?? "";
+      return [
+        ...keyedCommands(text, root, key, dirKey),
+        ...(scripts === true ? lefthookScripts(text, root) : []),
+      ];
+    }),
+    ...recipeLines(host, root),
+  ];
+}
+
+/**
+ * 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, which the dependency rule reads.
+ */
+export function commandFileTexts(host: Host, targetRoot: string): readonly string[] {
+  return commandFiles(host, targetRoot).flatMap(({ path }) => readText(host, path) ?? []);
+}
+
+/** Each file {@link workflowCommands} reads a command from, with the key a YAML file writes its commands under. */
+function commandFiles(
+  host: Host,
+  targetRoot: string,
+): readonly { readonly path: string; readonly key: string | undefined }[] {
+  const root = resolvePath(host.workingDirectory(), targetRoot);
+  return [
+    ...filesIn(host, joinPath(root, WORKFLOWS), (name) => /\.ya?ml$/u.test(name)).map((name) => ({
+      path: joinPath(root, WORKFLOWS, name),
+      key: "run",
+    })),
+    ...hookScripts(host, root).map((path) => ({ path, key: undefined })),
+    ...HOOK_MANAGERS.map(({ name, key }) => ({ path: joinPath(root, name), key })),
+    ...[makefileAt(host, root) ?? []].flat().map((path) => ({ path, key: undefined })),
+  ];
+}
+
+/**
+ * The filters of a workflow's `on` key, which name the files and refs whose change triggers it
+ * and run none: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore
+ */
+const TRIGGER_FILTERS = new Set([
+  "paths",
+  "paths-ignore",
+  "branches",
+  "branches-ignore",
+  "tags",
+  "tags-ignore",
+]);
+
+/**
+ * The values of one YAML file that are no command, each with its key: every scalar but one
+ * written under `key`, which is read as a command string, and one of a trigger filter. A file
+ * `yamlDocument` does not read is one value, its whole text. No key and no comment is a value.
+ */
+function yamlValues(text: string, key: string): readonly HeldText[] {
+  const document = yamlDocument(text);
+  if (document === undefined) {
+    return [{ text, shell: false }];
+  }
+  const found: HeldText[] = [];
+  // `trigger` is 1 for the value of the top-level `on`, a map of events, and 2 for an event's.
+  const visit = (node: unknown, under: string | undefined, trigger = 0): void => {
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        visit(item, under);
+      }
+    } else if (isRecord(node)) {
+      for (const [name, value] of Object.entries(node)) {
+        const on = node === document && (name === "on" || name === "true");
+        if (
+          (name !== key || scalarText(value) === undefined) &&
+          !(trigger === 2 && TRIGGER_FILTERS.has(name))
+        ) {
+          visit(value, name, on ? 1 : trigger === 1 ? 2 : 0);
+        }
+      }
+    } else {
+      const value = scalarText(node);
+      if (value !== undefined) {
+        found.push({ text: value, shell: false, ...(under === undefined ? {} : { key: under }) });
+      }
+    }
+  };
+  visit(document, undefined);
+  return found;
+}
+
+/**
+ * The lines of a makefile that are no recipe line, joined with the lines a trailing `\`
+ * continues them onto, each without the comment a `#` make does not read as escaped starts.
+ */
+function makefileValues(text: string): readonly HeldText[] {
+  return text
+    .replace(/\\\r?\n/gu, " ")
+    .split(/\r?\n/u)
+    .filter((line) => !line.startsWith("\t"))
+    .map((line) => line.replace(/(?<!\\)#.*$/u, ""))
+    .filter((line) => line.trim() !== "")
+    .map((line) => ({ text: line, shell: false }));
+}
+
+/**
+ * The texts layer 3 reads of the target root's command files: each command string, and each
+ * value of a workflow file, a hook manager file and the makefile that is no command.
+ */
+function heldTexts(host: Host, targetRoot: string): readonly HeldText[] {
+  const makefile = makefileAt(host, resolvePath(host.workingDirectory(), targetRoot));
+  return [
+    ...workflowCommands(host, targetRoot).map(({ text }) => ({ text, shell: true })),
+    ...commandFiles(host, targetRoot).flatMap(({ path, key }) => {
+      const text = readText(host, path);
+      return text === undefined
+        ? []
+        : key !== undefined
+          ? yamlValues(text, key)
+          : path === makefile
+            ? makefileValues(text)
+            : [];
+    }),
+  ];
+}
+
+/** What the target root's workflow steps, git hooks, hook managers and makefile run, read once per run. */
+export interface Workflows {
+  /** Each command read. */
+  readonly readings: readonly CommandReading[];
+  /** The whole text of each file a command is read from, which the dependency rule reads. */
+  readonly texts: readonly string[];
+  /** What layer 3 reads of them: each command string, and each value that is no command. */
+  readonly held: readonly HeldText[];
+}
+
+/** Reads the target root's workflow steps, git hooks, hook managers and makefile. */
+export function readWorkflows(host: Host, targetRoot: string): Workflows {
+  return {
+    readings: workflowCommands(host, targetRoot).map(({ text, dir }) => readCommands(text, dir)),
+    texts: commandFileTexts(host, targetRoot),
+    held: heldTexts(host, targetRoot),
+  };
+}
+
+/**
+ * The own files the target root's workflow steps, git hooks and recipes run or name, as
+ * `pathsNamed` reads each command.
+ */
+export function workflowEntries(
+  workflows: Workflows,
+  files: SourceFiles,
+): readonly WorkflowEntry[] {
+  const found: WorkflowEntry[] = [];
+  for (const reading of workflows.readings) {
+    for (const { path, written } of pathsNamed(reading)) {
+      for (const file of files.named(path)) {
+        found.push({ file, source: written });
+      }
+    }
+  }
+  return found;
+}

package/src/exemptions/argument-places.ts

@@ -0,0 +1,198 @@
+/**
+ * Which parameter place each argument of a call binds, the one reading every question
+ * about a call's arguments asks. A plain argument fills the next place, and a spread or
+ * an `apply` list typed as a tuple whose elements are all required fills one place per
+ * element. Any other spread or list has no known length: from its first place on, each of
+ * its element types, and every later argument, may fill any place, so a value is never
+ * read as missing a parameter only because its place could not be read. The type at each
+ * place is the checker's answer for it, so this reading names places and never types them.
+ */
+
+import { isSpreadElement, type Expression } from "@typescript/native/ast";
+import { ElementFlags, type Signature, type Type } from "@typescript/native/sync";
+import { must } from "../query.ts";
+import type { ProjectView } from "../session.ts";
+
+/** The places one argument fills. */
+export interface Span {
+  /** The argument's index among the invocation's arguments. */
+  readonly argument: number;
+  /** The first place it can fill. */
+  readonly first: number;
+  /** The type at each place from `first` on, or, where `open`, at any place from it on. */
+  readonly given: readonly (Type | undefined)[];
+  /** Whether the argument's length, or the length of a spread before it, is unknown. */
+  readonly open: boolean;
+  /** Whether the argument is a spread or a list, whose value is its elements. */
+  readonly spread: boolean;
+}
+
+/** One argument at one parameter place, with the type it gives there. */
+export interface Placed {
+  readonly argument: number;
+  /** The index in the argument's span `given` of the type it gives there. */
+  readonly element: number;
+  readonly place: number;
+  readonly given: Type | undefined;
+  /** Whether the signature has no such place, so it says nothing of what the argument keeps. */
+  readonly uncovered: boolean;
+  /**
+   * Whether it stands for every place of a rest from `place` on, an argument of unknown
+   * length there taking any type the rest's element type holds.
+   */
+  readonly rest: boolean;
+}
+
+/**
+ * How many places a signature has. Where it `repeats`, its rest has no fixed length and
+ * `count` ends at the rest's first place: the checker answers each place past it, and an
+ * argument of unknown length meets every one of them.
+ */
+export interface Layout {
+  readonly count: number;
+  readonly repeats: boolean;
+}
+
+/** The element flags of a tuple type; none for another type. */
+function elementFlags<Brand>(project: ProjectView<Brand>, type: Type): readonly ElementFlags[] {
+  const target = type.isTupleType() ? must(project.queries.targetOf(type)) : undefined;
+  return target?.isTupleTypeTarget() === true ? target.elementFlags : [];
+}
+
+/** What a spread argument puts at the places it fills, and how many it fills at least. */
+function spread<Brand>(
+  project: ProjectView<Brand>,
+  type: Type | undefined,
+): {
+  readonly types: readonly (Type | undefined)[];
+  readonly fixed: boolean;
+  readonly least: number;
+} {
+  const { queries } = project;
+  if (type === undefined) {
+    return { types: [undefined], fixed: false, least: 0 };
+  }
+  if (type.isTupleType()) {
+    const flags = elementFlags(project, type);
+    return {
+      types: must(queries.typeArguments(type)).slice(0, flags.length),
+      fixed: flags.every((flag) => (flag & ElementFlags.Required) !== 0),
+      least: flags.filter((flag) => (flag & ElementFlags.Required) !== 0).length,
+    };
+  }
+  if (must(queries.isArray(type))) {
+    return { types: must(queries.typeArguments(type)), fixed: false, least: 0 };
+  }
+  // Another iterable's elements are read off its type arguments, as `Set<T>` holds `T`.
+  return { types: [type, ...must(queries.typeArguments(type))], fixed: false, least: 0 };
+}
+
+/** The element types of a tuple of `count` required elements; none for another type. */
+export function knownElements<Brand>(
+  project: ProjectView<Brand>,
+  type: Type,
+  count: number,
+): readonly (Type | undefined)[] | undefined {
+  if (!type.isTupleType()) {
+    return undefined;
+  }
+  const elements = spread(project, type);
+  return elements.fixed && elements.types.length === count ? elements.types : undefined;
+}
+
+/**
+ * The places each argument fills, `types` holding the type of each argument's value; it
+ * may be empty where no argument is a spread and no given type is read. `listed` reads
+ * the last argument as a list whose elements the places bind.
+ */
+export function spansOf<Brand>(
+  project: ProjectView<Brand>,
+  args: readonly Expression[],
+  listed: boolean,
+  types: readonly (Type | undefined)[],
+): readonly Span[] {
+  const spans: Span[] = [];
+  let place = 0;
+  let open = false;
+  for (const [at, argument] of args.entries()) {
+    const type = types[at];
+    if (!isSpreadElement(argument) && !(listed && at === args.length - 1)) {
+      spans.push({ argument: at, first: place, given: [type], open, spread: false });
+      place += 1;
+      continue;
+    }
+    const elements = spread(project, type);
+    open ||= !elements.fixed;
+    spans.push({ argument: at, first: place, given: elements.types, open, spread: true });
+    place += elements.least;
+  }
+  return spans;
+}
+
+/**
+ * The places of one signature as the checker counts them: one per parameter, and in
+ * place of a rest as many as the `length` the checker answers for its type, where that
+ * is a number literal or a union of them. Any other `length`, an array's or an array-like
+ * interface's `number` among them, leaves the rest open.
+ */
+export function layoutOf<Brand>(project: ProjectView<Brand>, signature: Signature): Layout {
+  const { queries } = project;
+  const fixed = signature.parameters.length;
+  const rest = must(queries.restTypeOf(signature));
+  if (rest === undefined) {
+    return { count: fixed, repeats: false };
+  }
+  const length = must(queries.propertyTypeOf(rest, "length"));
+  const lengths = length === undefined ? [] : must(queries.constituents(length));
+  const bounds = lengths.flatMap((one) => (one.isNumberLiteralType() ? [one.value] : []));
+  if (bounds.length > 0 && bounds.length === lengths.length) {
+    return { count: fixed - 1 + Math.max(...bounds), repeats: false };
+  }
+  return { count: fixed, repeats: true };
+}
+
+/**
+ * The parameter place each argument binds in a signature of `layout`, with the type it
+ * gives there. A span of unknown length binds every place from its first to the last the
+ * layout counts, and past them, where the rest is open, one `rest` placement for every
+ * later place, or else its first place alone. A place past every place of a layout that
+ * does not repeat is `uncovered`.
+ */
+export function placesIn(spans: readonly Span[], layout: Layout): readonly Placed[] {
+  const placed: Placed[] = [];
+  const add = (span: Span, place: number, rest: boolean): void => {
+    const uncovered = place >= layout.count && !layout.repeats;
+    const elements = span.open
+      ? span.given.map((given, element) => ({ given, element }))
+      : [{ given: span.given[place - span.first], element: place - span.first }];
+    placed.push(
+      ...elements.map((one) => ({ argument: span.argument, place, uncovered, rest, ...one })),
+    );
+  };
+  for (const span of spans) {
+    const open = span.open && layout.repeats;
+    const end = !span.open
+      ? span.first + span.given.length
+      : Math.max(layout.count, open ? span.first : span.first + 1);
+    for (let place = span.first; place < end; place += 1) {
+      add(span, place, false);
+    }
+    if (open) {
+      add(span, Math.max(layout.count, span.first), true);
+    }
+  }
+  return placed;
+}
+
+/**
+ * Whether a span fills the parameter declared at `index`, a rest parameter every place
+ * from it on; with `element`, whether that element of a span that is not open does.
+ */
+export function fills(span: Span, index: number, rest: boolean, element?: number): boolean {
+  if (element !== undefined && !span.open) {
+    const place = span.first + element;
+    return rest ? place >= index : place === index;
+  }
+  const last = span.open ? Number.POSITIVE_INFINITY : span.first + span.given.length - 1;
+  return rest ? last >= index : span.first <= index && index <= last;
+}