@avi2dg/checks 0.6.0 → 0.9.0

package/scripts/backtest.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env bun
-import { comments, refused, SYNTAXES } from "./comments.ts";
+import { Console, Effect, Option } from "effect";
+import { comments, refused, syntaxOf } from "./comments.ts";
+import { git } from "./git.ts";
+import { runMain, Usage } from "./main.ts";
 
 type Landed = {
   readonly sha: string;
@@ -13,37 +16,20 @@ const USAGE = "usage: backtest.ts [commit-count]";
 
 const EXCLUDED = ["generated/", "vendor/", "repos/", "node_modules/", "dist/"];
 
-function die(message: string): never {
-  console.error(message);
-  process.exit(2);
-}
-
-function git(...args: readonly string[]): string {
-  const result = Bun.spawnSync(["git", ...args], { stdout: "pipe", stderr: "pipe" });
-  if (!result.success) {
-    die(`backtest: git ${args.join(" ")}: ${result.stderr.toString().trim()}`);
-  }
-  return result.stdout.toString();
-}
-
 function readable(path: string): boolean {
   if (EXCLUDED.some((prefix) => path.startsWith(prefix))) return false;
-  const extension = path.slice(path.lastIndexOf(".") + 1);
-  return extension in SYNTAXES;
+  return syntaxOf(path) !== undefined;
 }
 
-async function at(sha: string, path: string): Promise<string | undefined> {
-  const result = Bun.spawnSync(["git", "show", `${sha}:${path}`], { stdout: "pipe", stderr: "pipe" });
-  return result.success ? result.stdout.toString() : undefined;
-}
+const at = (sha: string, path: string) => git(["show", `${sha}:${path}`]).pipe(Effect.option);
 
 function withoutLine(refusal: string): string {
   return refusal.replace(/^(\S+?):\d+ /, "$1 ");
 }
 
-export async function backtest(count: string): Promise<string> {
+export const backtest = Effect.fn("backtest")(function* (count: string) {
   const lines: string[] = [];
-  const commits = git("log", "--first-parent", "--format=%H%x09%P%x09%s", "-n", count)
+  const commits = (yield* git(["log", "--first-parent", "--format=%H%x09%P%x09%s", "-n", count]))
     .trim()
     .split("\n")
     .map((row) => {
@@ -55,13 +41,13 @@ export async function backtest(count: string): Promise<string> {
   const landed: Landed[] = [];
 
   for (const { sha, parent, subject } of commits) {
-    const changed = git("diff", "--name-only", "--diff-filter=d", parent, sha)
+    const changed = (yield* git(["diff", "--name-only", "--diff-filter=d", parent, sha]))
       .trim()
       .split("\n")
       .filter((path) => path !== "" && readable(path));
     if (changed.length === 0) continue;
 
-    const numstat = git("diff", "--numstat", parent, sha, "--", ...changed).trim();
+    const numstat = (yield* git(["diff", "--numstat", parent, sha, "--", ...changed])).trim();
     const added =
       numstat === ""
         ? 0
@@ -71,17 +57,17 @@ export async function backtest(count: string): Promise<string> {
     const refusals: string[] = [];
 
     for (const path of changed) {
-      const after = await at(sha, path);
-      if (after === undefined) continue;
-      const before = (await at(parent, path)) ?? "";
+      const after = yield* at(sha, path);
+      if (Option.isNone(after)) continue;
+      const before = Option.getOrElse(yield* at(parent, path), () => "");
 
-      const wasRefused = new Set(refused(path, before).map(withoutLine));
-      for (const refusal of refused(path, after)) {
+      const wasRefused = new Set((yield* refused(path, before)).map(withoutLine));
+      for (const refusal of yield* refused(path, after.value)) {
         if (!wasRefused.has(withoutLine(refusal))) refusals.push(refusal);
       }
 
-      const wasComment = new Set(comments(path, before).map((one) => one.text));
-      for (const one of comments(path, after)) {
+      const wasComment = new Set((yield* comments(path, before)).map((one) => one.text));
+      for (const one of yield* comments(path, after.value)) {
         if (!wasComment.has(one.text)) commentLines += one.text.split("\n").length;
       }
     }
@@ -108,10 +94,13 @@ export async function backtest(count: string): Promise<string> {
     for (const refusal of one.refusals) lines.push(`    ${refusal}`);
   }
   return lines.join("\n");
-}
+});
 
-if (import.meta.main) {
+const main = Effect.gen(function* () {
   const [count = "60", ...extra] = process.argv.slice(2);
-  if (extra.length > 0) die(USAGE);
-  console.log(await backtest(count));
-}
+  if (extra.length > 0) return yield* new Usage({ message: USAGE });
+  yield* Console.log(yield* backtest(count));
+  return true;
+});
+
+if (import.meta.main) runMain("backtest", main);

package/scripts/ci-wiring.ts

@@ -1,6 +1,16 @@
 #!/usr/bin/env bun
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { git } from "./git.ts";
+import { runMain } from "./main.ts";
+import {
+  DEFAULT_BRANCH,
+  ENTRY_POINT,
+  EVERY_REPOSITORY,
+  KIT_GATES,
+  LintWiring,
+  selectedGates,
+  type KitGate,
+} from "./gates.ts";
 
 export type Command = readonly string[];
 
@@ -12,6 +22,7 @@ export type Gate = {
 export type Declaration = {
   readonly gates: readonly Gate[];
   readonly defaultBranch: string;
+  readonly lintGates: readonly KitGate[];
 };
 
 export type Workflow = {
@@ -24,8 +35,15 @@ export type BlockedInvocation = {
   readonly blocker: string;
 };
 
+export type Omission = {
+  readonly gate: string;
+  readonly content: string;
+  readonly files: readonly [string, ...string[]];
+};
+
 export type Gap = {
   readonly gate: string;
+  readonly entryPoint?: string;
   readonly blocked: readonly BlockedInvocation[];
 };
 
@@ -35,10 +53,11 @@ type RunStep = {
   readonly script: string;
 };
 
-export class WiringError extends Error {}
+export class WiringError extends Schema.TaggedError<WiringError>()("WiringError", {
+  message: Schema.String,
+}) {}
 
 const WORKFLOWS = ".github/workflows";
-const DEFAULT_BRANCH = "main";
 // Without these a pull_request workflow never sees the commits a pull request pushes.
 const GATING_TYPES = ["opened", "synchronize"];
 const CONSTANTS = new Map([
@@ -226,19 +245,32 @@ function runSteps(workflows: readonly Workflow[], branch: string): readonly RunS
   return steps;
 }
 
+function entryPointCommand(gate: Command, lintGates: readonly KitGate[]): Command | undefined {
+  const index = gate.findIndex((word) => lintGates.some((kitGate) => kitGate.bin === word));
+  return index === -1 ? undefined : [...gate.slice(0, index), ENTRY_POINT.bin];
+}
+
 export function findGaps(declaration: Declaration, workflows: readonly Workflow[]): readonly Gap[] {
   const steps = runSteps(workflows, declaration.defaultBranch);
   return declaration.gates.flatMap((gate) => {
-    const alone = `the step runs more than ${gate.command}; give it its own step with nothing else in it`;
+    const entryPoint = entryPointCommand(gate.words, declaration.lintGates);
+    const commands = [
+      { command: gate.command, words: gate.words },
+      ...(entryPoint === undefined ? [] : [{ command: entryPoint.join(" "), words: entryPoint }]),
+    ];
     const invoking = steps.flatMap(({ location, blocker, script }) => {
-      if (invokes(plainCommand(script), gate.words)) return [{ location, blocker }];
-      return mentions(script, gate.words) ? [{ location, blocker: blocker ?? alone }] : [];
+      const plain = plainCommand(script);
+      if (commands.some(({ words }) => invokes(plain, words))) return [{ location, blocker }];
+      const mentioned = commands.find(({ words }) => mentions(script, words));
+      if (mentioned === undefined) return [];
+      const alone = `the step runs more than ${mentioned.command}; give it its own step with nothing else in it`;
+      return [{ location, blocker: blocker ?? alone }];
     });
     if (invoking.some((step) => step.blocker === undefined)) return [];
     const blocked = invoking.flatMap(({ location, blocker }) =>
       blocker === undefined ? [] : [{ location, blocker }],
     );
-    return [{ gate: gate.command, blocked }];
+    return [{ gate: gate.command, entryPoint: entryPoint?.join(" "), blocked }];
   });
 }
 
@@ -248,80 +280,124 @@ export function formatReport(declaration: Declaration, gaps: readonly Gap[]): st
   const lines = [`ci-wiring: ${gaps.length} of ${declaration.gates.length} gate(s) do not run on ${target}:`];
   for (const gap of gaps) {
     lines.push(`  ${gap.gate}`);
-    if (gap.blocked.length === 0) lines.push("    no run step invokes it");
+    if (gap.blocked.length === 0) {
+      lines.push(gap.entryPoint === undefined ? "    no run step invokes it" : `    no run step invokes it or ${gap.entryPoint}`);
+    }
     for (const { location, blocker } of gap.blocked) lines.push(`    ${location}: ${blocker}`);
   }
   return lines.join("\n");
 }
 
-export function parseDeclaration(manifest: unknown, source: string): Declaration {
+const decodeWiring = Schema.decodeUnknownEffect(LintWiring);
+
+export const parseDeclaration = Effect.fnUntraced(function* (
+  manifest: unknown,
+  source: string,
+): Effect.fn.Return<Declaration, WiringError> {
   const configured = isRecord(manifest) && isRecord(manifest["ciWiring"]) ? manifest["ciWiring"] : {};
-  const listed = configured["gates"];
+  const listed: unknown = configured["gates"];
   if (!Array.isArray(listed) || listed.length === 0) {
-    throw new WiringError(`ci-wiring: ${source} sets no ciWiring.gates, a non-empty array of commands`);
+    return yield* new WiringError({ message: `${source} sets no ciWiring.gates, a non-empty array of commands` });
   }
-  const gates = listed.map((command: unknown): Gate => {
+  const commands: readonly unknown[] = listed;
+  const gates: Gate[] = [];
+  for (const command of commands) {
     const words = typeof command === "string" ? plainCommand(command) : undefined;
     if (typeof command !== "string" || words === undefined) {
-      throw new WiringError(`ci-wiring: ${source} ciWiring gate ${JSON.stringify(command)} is not one plain command`);
+      return yield* new WiringError({
+        message: `${source} ciWiring gate ${JSON.stringify(command)} is not one plain command`,
+      });
     }
-    return { command, words };
-  });
-  const defaultBranch = configured["defaultBranch"] ?? DEFAULT_BRANCH;
-  if (typeof defaultBranch !== "string" || defaultBranch === "") {
-    throw new WiringError(`ci-wiring: ${source} ciWiring.defaultBranch is not a branch name`);
+    gates.push({ command, words });
   }
-  return { gates, defaultBranch };
-}
+  const { ciWiring } = yield* decodeWiring(manifest).pipe(
+    Effect.mapError((cause) => new WiringError({ message: `${source}: ${cause.message}` })),
+  );
+  return {
+    gates,
+    defaultBranch: ciWiring?.defaultBranch ?? DEFAULT_BRANCH,
+    lintGates: selectedGates(ciWiring?.lintGates),
+  };
+});
 
-export function parseWorkflow(path: string, text: string): Workflow {
-  try {
-    return { path, document: Bun.YAML.parse(text) };
-  } catch (error) {
-    throw new WiringError(`ci-wiring: cannot parse ${path}: ${String(error)}`);
-  }
+function omittedFrom(lintGates: readonly KitGate[]): readonly KitGate[] {
+  return KIT_GATES.filter((gate) => !lintGates.includes(gate));
 }
 
-export function readDeclaration(root: string): Declaration {
-  const path = join(root, "package.json");
-  let manifest: unknown;
-  try {
-    manifest = JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    throw new WiringError(`ci-wiring: cannot read ${path} as JSON`);
+export const findOmissions = Effect.fn("findOmissions")(function* (root: string, lintGates: readonly KitGate[]) {
+  const omissions: Omission[] = [];
+  for (const gate of omittedFrom(lintGates)) {
+    // LintGates refuses a selection that leaves out a gate every repository runs.
+    if (gate.appliesTo === EVERY_REPOSITORY) continue;
+    const { pathspecs, content } = gate.appliesTo;
+    const [first, ...rest] = (yield* git(["ls-files", "-z", "--", ...pathspecs], root)).split("\0").filter(Boolean);
+    if (first !== undefined) omissions.push({ gate: gate.bin, content, files: [first, ...rest] });
   }
-  return parseDeclaration(manifest, path);
-}
+  return omissions;
+});
 
-export function readWorkflows(root: string): readonly Workflow[] {
-  const directory = join(root, WORKFLOWS);
-  if (!existsSync(directory)) return [];
-  return readdirSync(directory)
-    .filter((name) => name.endsWith(".yml") || name.endsWith(".yaml"))
-    .sort()
-    .map((name) => parseWorkflow(`${WORKFLOWS}/${name}`, readFileSync(join(directory, name), "utf8")));
+function sample([first, ...rest]: Omission["files"]): string {
+  return rest.length === 0 ? first : `${first} and ${rest.length} more`;
 }
 
-function repositoryRoot(): string {
-  const result = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], { stdout: "pipe", stderr: "pipe" });
-  if (!result.success) {
-    throw new WiringError(`ci-wiring: git rev-parse --show-toplevel: ${result.stderr.toString().trim()}`);
+export function formatOmissions(lintGates: readonly KitGate[], omissions: readonly Omission[]): string | undefined {
+  const omitted = omittedFrom(lintGates);
+  if (omitted.length === 0) return undefined;
+  if (omissions.length === 0) {
+    const bins = omitted.map((gate) => gate.bin).join(", ");
+    return `ci-wiring: ciWiring.lintGates leaves out ${bins}, none of which this repository's contents make applicable`;
   }
-  return result.stdout.toString().trim();
+  return [
+    `ci-wiring: ciWiring.lintGates leaves out ${omissions.length} gate(s) this repository's contents make applicable:`,
+    ...omissions.map(({ gate, content, files }) => `  ${gate}: the repository tracks ${content} (${sample(files)})`),
+  ].join("\n");
 }
 
-if (import.meta.main) {
-  try {
-    const root = repositoryRoot();
-    const declaration = readDeclaration(root);
-    const gaps = findGaps(declaration, readWorkflows(root));
-    if (gaps.length > 0) {
-      console.error(formatReport(declaration, gaps));
-      process.exit(1);
-    }
-    console.log(formatReport(declaration, gaps));
-  } catch (error) {
-    console.error(error instanceof WiringError ? error.message : `ci-wiring: ${String(error)}`);
-    process.exit(2);
+export const parseWorkflow = (path: string, text: string): Effect.Effect<Workflow, WiringError> =>
+  Effect.try({
+    try: () => ({ path, document: Bun.YAML.parse(text) }),
+    catch: (error) => new WiringError({ message: `cannot parse ${path}: ${String(error)}` }),
+  });
+
+const parseJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));
+
+export const readDeclaration = Effect.fn("readDeclaration")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = (yield* Path.Path).join(root, "package.json");
+  const manifest = yield* fs.readFileString(path).pipe(
+    Effect.flatMap(parseJson),
+    Effect.mapError((cause) => new WiringError({ message: `cannot read ${path} as JSON: ${cause.message}` })),
+  );
+  return yield* parseDeclaration(manifest, path);
+});
+
+export const readWorkflows = Effect.fn("readWorkflows")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const directory = path.join(root, WORKFLOWS);
+  if (!(yield* fs.exists(directory))) return [];
+  const files = (yield* fs.readDirectory(directory))
+    .filter((name) => name.endsWith(".yml") || name.endsWith(".yaml"))
+    .sort();
+  return yield* Effect.forEach(files, (name) =>
+    fs
+      .readFileString(path.join(directory, name))
+      .pipe(Effect.flatMap((text) => parseWorkflow(`${WORKFLOWS}/${name}`, text))),
+  );
+});
+
+const wiring = Effect.gen(function* () {
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  const declaration = yield* readDeclaration(root);
+  const gaps = findGaps(declaration, yield* readWorkflows(root));
+  const omissions = yield* findOmissions(root, declaration.lintGates);
+  const gapReport = formatReport(declaration, gaps);
+  yield* gaps.length > 0 ? Console.error(gapReport) : Console.log(gapReport);
+  const omissionReport = formatOmissions(declaration.lintGates, omissions);
+  if (omissionReport !== undefined) {
+    yield* omissions.length > 0 ? Console.error(omissionReport) : Console.log(omissionReport);
   }
-}
+  return gaps.length === 0 && omissions.length === 0;
+});
+
+if (import.meta.main) runMain("ci-wiring", wiring);

package/scripts/comment-gate.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env bun
-import { refused, SYNTAXES } from "./comments.ts";
+import { Console, Effect, Option } from "effect";
+import { refused, syntaxOf } from "./comments.ts";
+import { git, parentOrEmptyTree } from "./git.ts";
+import { runMain, Usage } from "./main.ts";
 
 export type GateResult = {
   readonly files: number;
@@ -9,21 +12,8 @@ export type GateResult = {
 
 const USAGE = "usage: comment-gate.ts <ref> | <base-ref> <head-ref>";
 
-function die(message: string): never {
-  console.error(message);
-  process.exit(2);
-}
-
-function git(root: string, ...args: readonly string[]): string {
-  const result = Bun.spawnSync(["git", ...args], { cwd: root, stdout: "pipe", stderr: "pipe" });
-  if (!result.success) {
-    die(`comment-gate: git ${args.join(" ")}: ${result.stderr.toString().trim()}`);
-  }
-  return result.stdout.toString();
-}
-
 function readable(path: string): boolean {
-  return path.slice(path.lastIndexOf(".") + 1) in SYNTAXES;
+  return syntaxOf(path) !== undefined;
 }
 
 function newPathOf(line: string): string | undefined {
@@ -68,29 +58,23 @@ export function parseAddedLines(diff: string): Map<string, Set<number>> {
   return added;
 }
 
-function show(rev: string, path: string, root: string): string | undefined {
-  const result = Bun.spawnSync(["git", "show", `${rev}:${path}`], {
-    cwd: root,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  return result.success ? result.stdout.toString() : undefined;
-}
+const show = (rev: string, path: string, root: string) =>
+  git(["show", `${rev}:${path}`], root).pipe(Effect.option);
 
-export function runRange(root: string, base: string, head: string): GateResult {
-  const diff = git(root, "-c", "core.quotePath=false", "diff", "-U0", "--no-color", "--no-prefix", base, head);
+export const runRange = Effect.fn("runRange")(function* (root: string, base: string, head: string) {
+  const diff = yield* git(["-c", "core.quotePath=false", "diff", "-U0", "--no-color", "--no-prefix", base, head], root);
   const added = parseAddedLines(diff);
   const violations: string[] = [];
   let addedLines = 0;
   for (const [path, lines] of added) {
     addedLines += lines.size;
     if (!readable(path)) continue;
-    const source = show(head, path, root);
-    if (source === undefined) continue;
-    violations.push(...refused(path, source, lines));
+    const source = yield* show(head, path, root);
+    if (Option.isNone(source)) continue;
+    violations.push(...(yield* refused(path, source.value, lines)));
   }
   return { files: added.size, addedLines, violations };
-}
+});
 
 export function report({ files, addedLines, violations }: GateResult): string {
   if (violations.length === 0) {
@@ -99,18 +83,16 @@ export function report({ files, addedLines, violations }: GateResult): string {
   return [`comment-gate: ${violations.length} violation(s):`, ...violations.map((one) => `  ${one}`)].join("\n");
 }
 
-function parentOf(root: string, rev: string): string {
-  return git(root, "rev-parse", "--verify", `${rev}^`).trim();
-}
-
-if (import.meta.main) {
+const gate = Effect.gen(function* () {
   const [first, second, ...extra] = process.argv.slice(2);
-  if (first === undefined || extra.length > 0) die(USAGE);
+  if (first === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
 
-  const root = git(process.cwd(), "rev-parse", "--show-toplevel").trim();
-  const result =
-    second !== undefined ? runRange(root, first, second) : runRange(root, parentOf(root, first), first);
+  const root = (yield* git(["rev-parse", "--show-toplevel"], process.cwd())).trim();
+  const base = second === undefined ? yield* parentOrEmptyTree(first, root) : first;
+  const result = yield* runRange(root, base, second ?? first);
 
-  console.log(report(result));
-  process.exit(result.violations.length === 0 ? 0 : 1);
-}
+  yield* Console.log(report(result));
+  return result.violations.length === 0;
+});
+
+if (import.meta.main) runMain("comment-gate", gate);