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

package/dist/src/entries/workflow-steps.js

@@ -0,0 +1,345 @@
+/**
+ * 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 { pathsNamed, readCommands } from "../commands/read.js";
+import { PART } from "../commands/shell.js";
+import { isRecord } from "../json-document.js";
+import { joinPath, resolvePath } from "../paths.js";
+import { filesIn } from "../fs/tree.js";
+import { yamlDocument } from "../text/yaml.js";
+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"];
+/** The key setting the directory a workflow step, or each step a `defaults.run` covers, runs in. */
+const WORKING_DIRECTORY = "working-directory";
+const HOOK_MANAGERS = [
+    { name: ".pre-commit-config.yaml", key: "entry" },
+    ...["lefthook.yml", "lefthook.yaml", ".lefthook.yml"].map((name) => ({
+        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"];
+/** The names GNU make reads a makefile under, in the order it tries them. */
+const MAKEFILES = ["GNUmakefile", "makefile", "Makefile"];
+function readText(host, path) {
+    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) {
+    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 = [];
+    const visit = (node, inherited) => {
+        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, root) {
+    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 = [];
+    const add = (hook, name, runner) => {
+        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, list) => {
+        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, 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");
+}
+/**
+ * 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) {
+    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, root) {
+    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, targetRoot) {
+    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) => ({
+            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, targetRoot) {
+    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, targetRoot) {
+    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, key) {
+    const document = yamlDocument(text);
+    if (document === undefined) {
+        return [{ text, shell: false }];
+    }
+    const found = [];
+    // `trigger` is 1 for the value of the top-level `on`, a map of events, and 2 for an event's.
+    const visit = (node, under, trigger = 0) => {
+        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) {
+    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, targetRoot) {
+    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)
+                        : [];
+        }),
+    ];
+}
+/** Reads the target root's workflow steps, git hooks, hook managers and makefile. */
+export function readWorkflows(host, targetRoot) {
+    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, files) {
+    const found = [];
+    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/dist/src/exemptions/argument-places.js

@@ -0,0 +1,131 @@
+/**
+ * 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 } from "@typescript/native/ast";
+import { ElementFlags } from "@typescript/native/sync";
+import { must } from "../query.js";
+/** The element flags of a tuple type; none for another type. */
+function elementFlags(project, type) {
+    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(project, type) {
+    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(project, type, count) {
+    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(project, args, listed, types) {
+    const spans = [];
+    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(project, signature) {
+    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, layout) {
+    const placed = [];
+    const add = (span, place, rest) => {
+        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, index, rest, element) {
+    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;
+}