@cplieger/deadset-ts 7.2.0-dev.4 → 8.0.0-dev.10

package/src/verbs/explain.ts

@@ -1,7 +1,7 @@
+import { EXIT_CLEAN, EXIT_USAGE } from "../contract/contract.generated.ts";
 import { runAnalysis, type RunAnalysis } from "../analysis.ts";
 import { listing } from "../components.ts";
 import type { Cascade } from "../config.ts";
-import { ConfigError } from "../config.ts";
 import type { CompletedFinding } from "../finding.ts";
 import { OUTSIDE, swept as judged } from "../graph.ts";
 import type { InventorySymbol } from "../inventory.ts";
@@ -12,7 +12,10 @@ import { positionKey } from "../position.ts";
 import type { Reference } from "../references.ts";
 import { resolve } from "../resolve.ts";
 import type { Root } from "../roots.ts";
-import { EXIT_CLEAN, EXIT_USAGE, type Verb, type VerbOptions } from "./verb.ts";
+import { type Verb, type VerbOptions } from "./verb.ts";
+import { UsageError } from "../usage.ts";
+import { bytewise } from "../text/compare.ts";
+import { diagnose } from "../product.ts";
 
 /**
  * The three spellings of an explanation request, each naming the symbol to explain. They are
@@ -44,16 +47,12 @@ function namedSymbol(option: (name: string) => string | undefined): string {
   });
   const [only, ...more] = named;
   if (only === undefined) {
-    throw new ConfigError(
-      "malformed",
-      "",
+    throw new UsageError(
       "explain explains the symbol --why, --why-live or --why-not names, and none was named",
     );
   }
   if (more.length > 0) {
-    throw new ConfigError(
-      "malformed",
-      "",
+    throw new UsageError(
       `explain explains one symbol, and ${named.map((one) => `--${one.name}`).join(", ")} each name one`,
     );
   }
@@ -101,7 +100,7 @@ function subjectOf(
         symbol.ref.toLowerCase().includes(folded) || symbol.name.toLowerCase().includes(folded),
     )
     .map(described)
-    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    .sort(bytewise);
   return { candidates: partial.slice(0, MAX_PARTIAL_MATCHES) };
 }
 
@@ -315,12 +314,15 @@ function reported(found: CompletedFinding): string {
 /**
  * Every finding of the run that names the declaration by its reference and reports at
  * another position: a part of it, or a suppression record naming it. Each is published under
- * the reference asked about, so an explanation leaving it out would disagree with the report.
+ * the reference asked about, or a parameter's under one it starts, so an explanation leaving
+ * it out would disagree with the report.
  */
 function namedElsewhere(findings: readonly CompletedFinding[], subject: InventorySymbol): string {
   return findings
     .filter(
-      (found) => found.symbol.ref === subject.ref && positionKey(found.position) !== subject.id,
+      (found) =>
+        (found.symbol.holder ?? found.symbol.ref) === subject.ref &&
+        positionKey(found.position) !== subject.id,
     )
     .map(
       (found) =>
@@ -377,7 +379,7 @@ export const explainVerb: Verb = ({ out, err, host, inputs, scope, openClient, o
     targetRoot: resolvePath(host.workingDirectory(), scoped.target.path),
   });
   if (subject === undefined) {
-    err.write(`deadset-ts: ${JSON.stringify(named)} names no one symbol of the target\n`);
+    diagnose(err, `${JSON.stringify(named)} names no one symbol of the target`);
     for (const candidate of candidates) {
       err.write(`  ${candidate}\n`);
     }
@@ -388,7 +390,7 @@ export const explainVerb: Verb = ({ out, err, host, inputs, scope, openClient, o
     out.write(explanation(analysis, subject, config.reporters.cascade));
   }
   for (const note of notes) {
-    err.write(`deadset-ts: ${note}\n`);
+    diagnose(err, note);
   }
   return subject === undefined ? EXIT_USAGE : EXIT_CLEAN;
 };

package/src/verbs/print-config.ts

@@ -1,6 +1,7 @@
+import { EXIT_CLEAN } from "../contract/contract.generated.ts";
 import { printConfig } from "../print.ts";
 import { resolve } from "../resolve.ts";
-import { EXIT_CLEAN, type Verb } from "./verb.ts";
+import { type Verb } from "./verb.ts";
 
 /** Writes the resolved configuration with the source of every setting. */
 export const printConfigVerb: Verb = ({ out, inputs }) => {

package/src/verbs/print-projects.ts

@@ -1,8 +1,10 @@
+import { EXIT_CLEAN } from "../contract/contract.generated.ts";
 import { runProjects } from "../analysis.ts";
 import { partialNotes } from "../partial.ts";
 import { resolvePath } from "../paths.ts";
-import { resolveUnkinded } from "../resolve.ts";
-import { EXIT_CLEAN, type Verb } from "./verb.ts";
+import { resolvePartial } from "../resolve.ts";
+import { type Verb } from "./verb.ts";
+import { diagnose } from "../product.ts";
 
 /**
  * Writes the name of every project one run analyzes, one per line: the identifier the
@@ -12,7 +14,7 @@ import { EXIT_CLEAN, type Verb } from "./verb.ts";
  * instead, and one that fails the analysis fails this command the same way.
  */
 export const printProjectsVerb: Verb = ({ out, err, host, inputs, scope, openClient }) => {
-  const config = resolveUnkinded(inputs());
+  const config = resolvePartial(inputs());
   const scoped = scope();
   const answer = runProjects(openClient(config), host, scoped, config);
   for (const id of answer.configurations) {
@@ -23,7 +25,7 @@ export const printProjectsVerb: Verb = ({ out, err, host, inputs, scope, openCli
     unanswered: answer.unanswered,
     targetRoot: resolvePath(host.workingDirectory(), scoped.target.path),
   })) {
-    err.write(`deadset-ts: ${note}\n`);
+    diagnose(err, note);
   }
   return EXIT_CLEAN;
 };

package/src/verbs/print-retained.ts

@@ -1,9 +1,11 @@
+import { EXIT_CLEAN } from "../contract/contract.generated.ts";
 import { runSweep } from "../analysis.ts";
 import { retainedLines } from "../exempt.ts";
 import { partialNotes } from "../partial.ts";
 import { resolvePath } from "../paths.ts";
 import { resolve } from "../resolve.ts";
-import { EXIT_CLEAN, type Verb } from "./verb.ts";
+import { type Verb } from "./verb.ts";
+import { diagnose } from "../product.ts";
 
 /**
  * Writes every declaration an exemption held back in the production sweep a report is
@@ -27,7 +29,7 @@ export const printRetainedVerb: Verb = ({ out, err, host, inputs, scope, openCli
     unanswered: swept.unanswered,
     targetRoot: resolvePath(host.workingDirectory(), scoped.target.path),
   })) {
-    err.write(`deadset-ts: ${note}\n`);
+    diagnose(err, note);
   }
   return EXIT_CLEAN;
 };

package/src/verbs/print-roots.ts

@@ -1,8 +1,10 @@
+import { EXIT_CLEAN, EXIT_FINDINGS } from "../contract/contract.generated.ts";
 import { runRoots, type RunRoot } from "../analysis.ts";
 import { partialNotes } from "../partial.ts";
 import { resolvePath } from "../paths.ts";
 import { resolve } from "../resolve.ts";
-import { EXIT_CLEAN, EXIT_FINDINGS, type Verb } from "./verb.ts";
+import { type Verb } from "./verb.ts";
+import { diagnose } from "../product.ts";
 
 /**
  * One root as a line: the declaration's reference, why it is a root, and the string
@@ -41,7 +43,7 @@ export const printRootsVerb: Verb = ({ out, err, host, inputs, scope, openClient
     unanswered: answer.unanswered,
     targetRoot: resolvePath(host.workingDirectory(), scoped.target.path),
   })) {
-    err.write(`deadset-ts: ${note}\n`);
+    diagnose(err, note);
   }
   return answer.findings.length > 0 ? EXIT_FINDINGS : EXIT_CLEAN;
 };

package/src/verbs/verb.ts

@@ -1,15 +1,9 @@
-import type { Config, Inputs } from "../config.ts";
+import type { Inputs, PartialConfig } from "../config.ts";
 import type { Host } from "../host.ts";
 import type { Writer } from "../run.ts";
 import type { Scope } from "../scope.ts";
 import type { Engine } from "../session.ts";
 
-/** The exit codes the Contract's exit-code table names. */
-export const EXIT_CLEAN = 0;
-export const EXIT_FINDINGS = 1;
-export const EXIT_USAGE = 2;
-export const EXIT_FAILURE = 3;
-
 /**
  * What one verb is handed: the streams it writes, the platform it reads, and the
  * options that follow its name, read only when the verb asks for what they name, so
@@ -27,7 +21,7 @@ interface Invocation {
    * Opens the compiler client for a run under `config`. A client the verb opened is
    * closed if the verb throws.
    */
-  readonly openClient: (config: Config) => Engine;
+  readonly openClient: (config: PartialConfig) => Engine;
   /** The arguments after the verb's name, as written. */
   readonly args: readonly string[];
   /** The last value one of the verb's own options was given, undefined where none was. */

package/src/verbs/version.ts

@@ -1,8 +1,20 @@
-import { CONTRACT_VERSION } from "../version.ts";
-import { EXIT_CLEAN, type Verb } from "./verb.ts";
+import { CONTRACT_VERSION, EXIT_CLEAN } from "../contract/contract.generated.ts";
+import { productFault } from "../failure.ts";
+import type { Host } from "../host.ts";
+import { type Verb } from "./verb.ts";
+import { message, PRODUCT } from "../product.ts";
+
+/** The version the host reports for this analyzer; one it cannot read is a fault of the analyzer. */
+export function ownVersion(host: Host): string {
+  try {
+    return host.analyzerVersion();
+  } catch (error: unknown) {
+    throw productFault(`cannot read its own version: ${message(error)}`);
+  }
+}
 
 /** Writes the version the host reports and the Contract version this analyzer implements. */
 export const versionVerb: Verb = ({ out, host }) => {
-  out.write(`deadset-ts ${host.analyzerVersion()}\ncontract ${CONTRACT_VERSION}\n`);
+  out.write(`${PRODUCT} ${ownVersion(host)}\ncontract ${CONTRACT_VERSION}\n`);
   return EXIT_CLEAN;
 };

package/src/workflow-steps.ts

@@ -1,13 +1,15 @@
 /**
- * The source files a CI workflow's `run:` steps name by their path from the target root.
- * A workflow file is read as text, line by line, with no YAML parsed.
+ * 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.
  */
 
 import type { SourceFile } from "@typescript/native/ast";
 import type { Host } from "./host.ts";
-import { scriptTokens } from "./manifest.ts";
-import { joinPath, resolvePath } from "./paths.ts";
+import { joinPath, relativePath, resolvePath } from "./paths.ts";
 import type { SourceFiles } from "./source-files.ts";
+import { filesIn } from "./fs/tree.ts";
+import { commandsOf, scriptTokens, unquoted, withoutComment } from "./text/shell.ts";
 
 /** One file a workflow step names. */
 interface WorkflowEntry {
@@ -21,39 +23,57 @@ const WORKFLOWS = ".github/workflows";
 /** A line holding a run command: indentation and one sequence marker before `run:`. */
 const RUN_LINE = /^(\s*(?:- )?)run:(.*)$/u;
 
-const BLOCK_SCALAR = /^[|>][+-]?$/u;
+/** The directories whose every file is a git hook script, run as the shell runs it. */
+const HOOK_DIRS = [".husky", ".githooks"] as const;
+
+/** 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"] as const;
+
+/** 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. */
+const HOOK_MANAGERS: readonly (readonly [string, RegExp])[] = [
+  [".pre-commit-config.yaml", /^(\s*(?:- )?)entry:(.*)$/u],
+  ...LEFTHOOK_FILES.map((name) => [name, RUN_LINE] as const),
+];
+
+/** The names GNU make reads a makefile under, in the order it tries them. */
+const MAKEFILES = ["GNUmakefile", "makefile", "Makefile"] as const;
 
-const QUOTED = /^(["'])(.*)\1$/su;
+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;
 
-function workflowFiles(host: Host, dir: string): readonly string[] {
-  let entries;
+/** The files directly in one directory whose name `accepts`, by path in name order. */
+function pathsIn(host: Host, dir: string, accepts: (name: string) => boolean): readonly string[] {
+  return filesIn(host, dir, accepts).map((name) => joinPath(dir, name));
+}
+
+function readText(host: Host, path: string): string | undefined {
   try {
-    entries = host.readDirectory(dir);
+    return host.readFile(path);
   } catch {
-    return [];
+    return undefined;
   }
-  return entries
-    .filter((entry) => !entry.directory && /\.ya?ml$/u.test(entry.name))
-    .map((entry) => joinPath(dir, entry.name))
-    .sort();
 }
 
-/** Every command line one workflow file's `run:` steps hold. */
-export function runCommands(text: string): readonly string[] {
+/** Every line one workflow file's `run:` steps hold, or every line of the values written under `key`. */
+export function runCommands(text: string, key: RegExp = RUN_LINE): readonly string[] {
   const lines = text.split(/\r?\n/u);
   const found: string[] = [];
   for (let at = 0; at < lines.length; at += 1) {
-    const match = RUN_LINE.exec(lines[at] ?? "");
+    const match = key.exec(lines[at] ?? "");
     if (match === null) {
       continue;
     }
     const column = (match[1] ?? "").length;
-    const value = (match[2] ?? "").trim().replace(QUOTED, "$2");
+    const value = unquoted((match[2] ?? "").trim());
     if (!BLOCK_SCALAR.test(value)) {
       found.push(value);
       continue;
@@ -69,28 +89,112 @@ export function runCommands(text: string): readonly string[] {
   return found;
 }
 
-/** Every token the `run:` steps of the workflow files in the target root's `.github/workflows` hold. */
-export function workflowTokens(host: Host, targetRoot: string): readonly string[] {
-  const dir = joinPath(resolvePath(host.workingDirectory(), targetRoot), WORKFLOWS);
-  const found: string[] = [];
-  for (const path of workflowFiles(host, dir)) {
-    let text: string;
-    try {
-      text = host.readFile(path);
-    } catch {
-      continue;
-    }
-    for (const command of runCommands(text)) {
-      found.push(...scriptTokens(command));
+/**
+ * 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.
+ */
+function recipeLines(host: Host, root: string): readonly (readonly string[])[] {
+  const path = MAKEFILES.map((name) => joinPath(root, name)).find(
+    (candidate) => host.kindOf(candidate) === "file",
+  );
+  const text = path === undefined ? undefined : readText(host, path);
+  if (text === undefined) {
+    return [];
+  }
+  return text
+    .replace(/\\\r?\n/gu, " ")
+    .split(/\r?\n/u)
+    .filter((line) => line.startsWith("\t"))
+    .map((line) => commandsOf(withoutComment(line.slice(1).replace(/^[@+-]+/u, ""))));
+}
+
+/**
+ * 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: Host, root: string): readonly { token: string; dir: string }[] {
+  const found: { token: string; dir: string }[] = [];
+  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;
 }
 
 /**
- * The own files the `run:` steps of every workflow file in the target root's
- * `.github/workflows` name: a token equal to a file's path below the target root, with or
- * without a leading `./`, whatever directory the step runs in.
+ * 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.
+ */
+export function workflowCommands(host: Host, targetRoot: string): readonly string[] {
+  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: Host, targetRoot: string): readonly string[] {
+  const root = resolvePath(host.workingDirectory(), targetRoot);
+  return [
+    ...workflowFiles(host, root).flatMap((path) =>
+      runCommands(readText(host, path) ?? "", WORKING_DIRECTORY),
+    ),
+    ...LEFTHOOK_FILES.flatMap((name) =>
+      runCommands(readText(host, joinPath(root, name)) ?? "", LEFTHOOK_ROOT),
+    ),
+  ];
+}
+
+/** The workflow files in `.github/workflows` at one root, by path in name order. */
+function workflowFiles(host: Host, root: string): readonly string[] {
+  return pathsIn(host, joinPath(root, WORKFLOWS), (name) => /\.ya?ml$/u.test(name));
+}
+
+/** Every token the commands {@link workflowCommands} reads hold. */
+export function workflowTokens(host: Host, targetRoot: string): readonly string[] {
+  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: Host, root: string): readonly string[] {
+  const commands: string[] = [];
+  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;
+}
+
+/**
+ * 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.
  */
 export function workflowEntries(
   host: Host,
@@ -107,5 +211,16 @@ export function workflowEntries(
       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 });
+    }
+  }
   return found;
 }