@avi2dg/checks 0.14.0 → 0.16.0

package/scripts/size-budget.ts

@@ -2,23 +2,43 @@
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { changedPaths, collect, git, pathsAt, rangeEnds, type Change } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
-import { readQuality, renderJson, type Quality } from "./quality-file.ts";
+import { readQuality, renderJson } from "./quality-file.ts";
+import {
+  budgetOf,
+  budgetsOf,
+  SIZE_DEFAULTS,
+  SIZE_RULES,
+  TESTS_DIRECTORY,
+  type Applies,
+  type Budget,
+  type Budgets,
+  type LimitKey,
+  type Size,
+  type SizeRule,
+} from "./size-rules.ts";
 
-type Size = NonNullable<Quality["size"]>;
+type Held = { readonly path: string; readonly from: string };
 
-type Overrun = {
+type Site = {
   readonly file: string;
   readonly line: number | undefined;
+  readonly rule: SizeRule["rule"];
+  readonly overrun: number;
   readonly message: string;
 };
 
-type Measured = {
-  readonly scope: string;
-  readonly held: readonly string[];
-  readonly overruns: readonly Overrun[];
-  readonly advisory: readonly Overrun[];
+type Growth = {
+  readonly file: string;
+  readonly rule: SizeRule["rule"];
+  readonly base: number;
+  readonly head: number;
+  readonly sites: readonly Site[];
 };
 
+type Verdict =
+  | { readonly applies: "all"; readonly held: number; readonly overruns: readonly Site[]; readonly advisory: readonly Site[] }
+  | { readonly applies: "ratchet"; readonly held: number; readonly growths: readonly Growth[]; readonly advisory: readonly Site[] };
+
 class OxlintUnreadable extends Schema.TaggedError<OxlintUnreadable>()("OxlintUnreadable", {
   message: Schema.String,
 }) {}
@@ -27,115 +47,195 @@ const NAME = "size-budget";
 const USAGE = "usage: size-budget.ts <ref> | <base-ref> <head-ref>";
 const DECLARATIONS = ":(exclude,glob)**/*.d.ts";
 const TYPESCRIPT = [":(glob)**/*.ts", ":(glob)**/*.tsx", DECLARATIONS];
-const FILE_RULE = "eslint(max-lines)";
-const FUNCTION_RULE = "eslint(max-lines-per-function)";
+const TESTS = [`:(glob)${TESTS_DIRECTORY}/**/*.ts`, `:(glob)${TESTS_DIRECTORY}/**/*.tsx`];
+const CONFIG = ".size-budget.oxlintrc.json";
+const WHOLE_FILE: LimitKey = "fileLines";
 const OXLINT_FOUND_NOTHING = 0;
 const OXLINT_FOUND_ERRORS = 1;
+const SCOPE = {
+  ratchet: "the production and test files the range adds or changes",
+  all: "every production and test file",
+} satisfies Record<Applies, string>;
+
+const Diagnostic = Schema.Struct({
+  code: Schema.String,
+  message: Schema.String,
+  filename: Schema.String,
+  labels: Schema.Array(Schema.Struct({ span: Schema.Struct({ line: Schema.Int }) })),
+});
+
+const decodeReport = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ diagnostics: Schema.Array(Diagnostic) })));
 
-const decodeReport = Schema.decodeUnknownEffect(
-  Schema.fromJsonString(
-    Schema.Struct({
-      diagnostics: Schema.Array(
-        Schema.Struct({
-          code: Schema.String,
-          message: Schema.String,
-          filename: Schema.String,
-          labels: Schema.Array(Schema.Struct({ span: Schema.Struct({ line: Schema.Int }) })),
-        }),
-      ),
+function rulesOf(budget: Budget): Record<string, unknown> {
+  return Object.fromEntries(
+    SIZE_RULES.map(({ key, rule, options }) => {
+      const max = budget[key];
+      return [rule, max === undefined ? "off" : ["error", { max, ...options }]];
     }),
-  ),
-);
+  );
+}
 
-function sizeConfig({ fileLines, functionLines }: Size): unknown {
-  const counted = { skipBlankLines: false, skipComments: false };
+function sizeConfig({ production, tests }: Budgets): unknown {
   return {
     plugins: [],
     categories: { correctness: "off" },
-    rules: {
-      "max-lines": ["error", { max: fileLines, ...counted }],
-      "max-lines-per-function": ["error", { max: functionLines, ...counted }],
-    },
+    rules: rulesOf(production),
+    overrides: [{ files: [`${TESTS_DIRECTORY}/**`], rules: rulesOf(tests) }],
   };
 }
 
-function heldByChange(changes: readonly Change[]): readonly string[] {
+function heldByChange(changes: readonly Change[]): readonly Held[] {
   return changes.flatMap((change) => {
-    if (change.kind === "written" || (change.kind === "renamed" && change.edited)) return [change.path];
+    if (change.kind === "written") return [{ path: change.path, from: change.path }];
+    if (change.kind === "renamed" && change.edited) return [{ path: change.path, from: change.from }];
     return [];
   });
 }
 
-const materialize = Effect.fn("materialize")(function* (root: string, head: string, files: readonly string[], scratch: string) {
-  const path = yield* Path.Path;
-  const env = { GIT_INDEX_FILE: path.join(scratch, "index") };
+// oxlint reads files from disk, and the working tree need not hold the head: a merge checkout or an uncommitted edit.
+const materializeHead = Effect.fn("materializeHead")(function* (root: string, head: string, files: readonly string[], tree: string) {
+  const env = { GIT_INDEX_FILE: `${tree}.index` };
   yield* git(["read-tree", head], root, { env });
-  const tree = `${path.join(scratch, "tree")}${path.sep}`;
-  yield* git(["checkout-index", "-z", "--stdin", `--prefix=${tree}`], root, { env, input: files.map((file) => `${file}\0`).join("") });
-  return tree;
+  yield* git(["checkout-index", "-z", "--stdin", `--prefix=${tree}/`], root, { env, input: files.map((file) => `${file}\0`).join("") });
 });
 
-// oxlint reads files from disk, and the working tree need not hold the head: a merge checkout or an uncommitted edit.
-const measure = Effect.fn("measure")(
-  function* (root: string, head: string, size: Size, files: readonly string[]) {
-    if (files.length === 0) return [];
+// Each file is written at its head path, so a rename is measured against the budget it is held to now.
+const materializeBase = Effect.fn("materializeBase")(function* (root: string, base: string, held: readonly Held[], tree: string) {
+  const env = { GIT_INDEX_FILE: `${tree}.index` };
+  const found = (yield* git(["cat-file", "--batch-check=%(objecttype) %(objectname)"], root, {
+    input: held.map(({ from }) => `${base}:${from}\n`).join(""),
+  })).split("\n");
+  const entries = held.flatMap(({ path }, index) => {
+    const [type, blob] = (found[index] ?? "").split(" ");
+    return type === "blob" ? [`100644 ${blob}\t${path}\0`] : [];
+  });
+  if (entries.length === 0) return;
+  yield* git(["update-index", "-z", "--index-info"], root, { env, input: entries.join("") });
+  yield* git(["checkout-index", "--all", `--prefix=${tree}/`], root, { env });
+});
+
+const siteOf = (budgets: Budgets) =>
+  Effect.fn("siteOf")(function* ({ code, message, filename, labels }: typeof Diagnostic.Type) {
+    const rule = SIZE_RULES.find((candidate) => code === `eslint(${candidate.rule})`);
+    if (rule === undefined) return [];
+    const measured = rule.measured.exec(message)?.[1];
+    const max = budgetOf(budgets, filename)[rule.key];
+    if (measured === undefined || max === undefined) {
+      return yield* new OxlintUnreadable({ message: `cannot read ${rule.rule} for ${filename} from oxlint: ${message}` });
+    }
+    const wholeFile = rule.key === WHOLE_FILE;
+    return [
+      {
+        file: filename,
+        line: wholeFile ? undefined : labels[0]?.span.line,
+        rule: rule.rule,
+        overrun: Number(measured) - max,
+        message: wholeFile ? `${message} Maximum allowed is ${max}.` : message,
+      } satisfies Site,
+    ];
+  });
+
+const measure = Effect.fn("measure")(function* (tree: string, budgets: Budgets) {
+  const fs = yield* FileSystem.FileSystem;
+  if (!(yield* fs.exists(tree))) return [];
+  // oxlint reads an override's glob from the directory of the config that holds it, so the config sits in the tree.
+  yield* fs.writeFileString((yield* Path.Path).join(tree, CONFIG), renderJson(sizeConfig(budgets)));
+
+  const { stdout, stderr, exitCode } = yield* collect("oxlint", ["-c", CONFIG, "-f", "json", "."], tree).pipe(
+    Effect.mapError((cause) => new OxlintUnreadable({ message: `cannot run oxlint: ${cause.message}` })),
+  );
+  if (exitCode !== OXLINT_FOUND_NOTHING && exitCode !== OXLINT_FOUND_ERRORS) {
+    return yield* new OxlintUnreadable({ message: `oxlint exited ${exitCode}: ${stderr.trim() || stdout.trim()}` });
+  }
+  const { diagnostics } = yield* decodeReport(stdout).pipe(
+    Effect.mapError((cause) => new OxlintUnreadable({ message: `cannot read oxlint's report: ${cause.message}` })),
+  );
+  const sites = (yield* Effect.forEach(diagnostics, siteOf(budgets))).flat();
+  return sites.toSorted((a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0));
+});
+
+function byFileAndRule(sites: readonly Site[]): ReadonlyMap<string, readonly Site[]> {
+  return Map.groupBy(sites, ({ file, rule }) => `${file}\0${rule}`);
+}
+
+function total(sites: readonly Site[]): number {
+  return sites.reduce((sum, { overrun }) => sum + overrun, 0);
+}
+
+function growthsOf(head: readonly Site[], base: readonly Site[]): readonly Growth[] {
+  const before = byFileAndRule(base);
+  return [...byFileAndRule(head).entries()].flatMap(([group, sites]) => {
+    const [first] = sites;
+    const growth = { base: total(before.get(group) ?? []), head: total(sites), sites };
+    return first !== undefined && growth.head > growth.base ? [{ file: first.file, rule: first.rule, ...growth }] : [];
+  });
+}
+
+const heldFiles = Effect.fn("heldFiles")(function* (root: string, applies: Applies, pathspecs: readonly string[], base: string, head: string) {
+  if (applies === "all") return (yield* pathsAt(head, pathspecs, root)).map((path): Held => ({ path, from: path }));
+  return heldByChange(yield* changedPaths(base, head, pathspecs, root));
+});
+
+const runBudget = Effect.fn("runBudget")(
+  function* (root: string, size: Size, production: readonly string[], base: string, head: string) {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
+    const applies = size.applies ?? SIZE_DEFAULTS.applies;
+    const budgets = budgetsOf(size);
+    const pathspecs = [...production.map((glob) => `:(glob)${glob}`), ...TESTS, DECLARATIONS];
+    const held = yield* heldFiles(root, applies, pathspecs, base, head);
+    const holds = new Set(held.map((file) => file.path));
+    const others = (yield* pathsAt(head, TYPESCRIPT, root)).filter((file) => !holds.has(file));
     const scratch = yield* fs.makeTempDirectoryScoped({ prefix: "checks-size-budget-" });
-    const config = path.join(scratch, "size.oxlintrc.json");
-    yield* fs.writeFileString(config, renderJson(sizeConfig(size)));
-    const tree = yield* materialize(root, head, files, scratch);
-
-    const { stdout, stderr, exitCode } = yield* collect("oxlint", ["-c", config, "-f", "json", "."], tree).pipe(
-      Effect.mapError((cause) => new OxlintUnreadable({ message: `cannot run oxlint: ${cause.message}` })),
-    );
-    if (exitCode !== OXLINT_FOUND_NOTHING && exitCode !== OXLINT_FOUND_ERRORS) {
-      return yield* new OxlintUnreadable({ message: `oxlint exited ${exitCode}: ${stderr.trim() || stdout.trim()}` });
+
+    const headTree = path.join(scratch, "head");
+    if (held.length + others.length > 0) yield* materializeHead(root, head, [...holds, ...others], headTree);
+    const sites = yield* measure(headTree, budgets);
+    const heldSites = sites.filter((site) => holds.has(site.file));
+    if (applies !== "ratchet") {
+      return { applies, held: held.length, overruns: heldSites, advisory: sites.filter((site) => !holds.has(site.file)) } satisfies Verdict;
     }
-    const { diagnostics } = yield* decodeReport(stdout).pipe(
-      Effect.mapError((cause) => new OxlintUnreadable({ message: `cannot read oxlint's report: ${cause.message}` })),
-    );
-    return diagnostics.flatMap(({ code, message, filename, labels }): Overrun[] => {
-      if (code === FILE_RULE) return [{ file: filename, line: undefined, message }];
-      if (code === FUNCTION_RULE) return [{ file: filename, line: labels[0]?.span.line, message }];
-      return [];
-    });
+
+    const baseTree = path.join(scratch, "base");
+    if (held.length > 0) yield* materializeBase(root, base, held, baseTree);
+    const growths = growthsOf(heldSites, yield* measure(baseTree, budgets));
+    const failing = new Set(growths.flatMap((growth) => growth.sites));
+    return { applies, held: held.length, growths, advisory: sites.filter((site) => !failing.has(site)) } satisfies Verdict;
   },
   Effect.scoped,
 );
 
-const runBudget = Effect.fn("runBudget")(function* (root: string, size: Size, production: readonly string[], base: string, head: string) {
-  const pathspecs = [...production.map((glob) => `:(glob)${glob}`), DECLARATIONS];
-  const held =
-    size.applies === "all" ? yield* pathsAt(head, pathspecs, root) : heldByChange(yield* changedPaths(base, head, pathspecs, root));
-  const holds = new Set(held);
-  const others = (yield* pathsAt(head, TYPESCRIPT, root)).filter((file) => !holds.has(file));
-  const overruns = (yield* measure(root, head, size, [...held, ...others])).toSorted(
-    (a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0),
-  );
-  return {
-    scope: size.applies === "all" ? "every production file" : "the production files the range adds or changes",
-    held,
-    overruns: overruns.filter((overrun) => holds.has(overrun.file)),
-    advisory: overruns.filter((overrun) => !holds.has(overrun.file)),
-  } satisfies Measured;
-});
+function describe({ file, line, message }: Site, indent = "  "): string {
+  return `${indent}${file}${line === undefined ? "" : `:${line}`}: ${message}`;
+}
 
-function describe({ file, line, message }: Overrun): string {
-  return `  ${file}${line === undefined ? "" : `:${line}`}: ${message}`;
+function verdictLines(verdict: Verdict): readonly string[] {
+  const scope = SCOPE[verdict.applies];
+  if (verdict.applies === "ratchet") {
+    if (verdict.growths.length === 0) return [`${NAME}: ${verdict.held} file(s), ${scope}, raise no overrun past the base`];
+    return [
+      `${NAME}: ${verdict.growths.length} overrun(s) grew past the base in ${scope}:`,
+      ...verdict.growths.flatMap(({ file, rule, base, head, sites }) => [
+        `  ${file}: ${rule} over by ${head} in total, up from ${base}`,
+        ...sites.map((site) => describe(site, "    ")),
+      ]),
+    ];
+  }
+  if (verdict.overruns.length === 0) return [`${NAME}: ${verdict.held} file(s), ${scope}, keep within the budget`];
+  return [`${NAME}: ${verdict.overruns.length} overrun(s) of the budget in ${scope}:`, ...verdict.overruns.map((site) => describe(site))];
 }
 
-function report({ scope, held, overruns, advisory }: Measured, { fileLines, functionLines }: Size): string {
-  const budget = `${fileLines} lines per file and ${functionLines} per function`;
-  const verdict =
-    overruns.length === 0
-      ? [`${NAME}: ${held.length} file(s), ${scope}, keep within ${budget}`]
-      : [`${NAME}: ${overruns.length} overrun(s) of ${budget} in ${scope}:`, ...overruns.map(describe)];
+function report(verdict: Verdict): string {
+  const { advisory } = verdict;
   const notice =
     advisory.length === 0
       ? []
-      : [`${NAME}: advisory, ${advisory.length} overrun(s) where the budget does not hold yet:`, ...advisory.map(describe)];
-  return [...verdict, ...notice].join("\n");
+      : [`${NAME}: advisory, ${advisory.length} overrun(s) where the budget does not hold yet:`, ...advisory.map((site) => describe(site))];
+  return [...verdictLines(verdict), ...notice].join("\n");
+}
+
+function passes(verdict: Verdict): boolean {
+  return verdict.applies === "ratchet" ? verdict.growths.length === 0 : verdict.overruns.length === 0;
 }
 
 const budget = Effect.gen(function* () {
@@ -149,10 +249,10 @@ const budget = Effect.gen(function* () {
     return true;
   }
   const { base, head } = yield* rangeEnds(first, second, root);
-  const measured = yield* runBudget(root, quality.size, quality.sources?.production ?? [], base, head);
+  const verdict = yield* runBudget(root, quality.size, quality.sources?.production ?? [], base, head);
 
-  yield* Console.log(report(measured, quality.size));
-  return measured.overruns.length === 0;
+  yield* Console.log(report(verdict));
+  return passes(verdict);
 });
 
 if (import.meta.main) runMain(NAME, budget);

package/scripts/size-rules.ts

@@ -0,0 +1,117 @@
+import { Schema } from "effect";
+
+export const TESTS_DIRECTORY = "tests";
+
+const COUNTED = { skipBlankLines: false, skipComments: false };
+
+const FILE_LINES = {
+  key: "fileLines",
+  rule: "max-lines",
+  options: COUNTED,
+  measured: /has too many lines \((\d+)\)/,
+  limits: "The most lines a file may hold, blank and comment lines counted",
+} as const;
+
+const FUNCTION_LINES = {
+  key: "functionLines",
+  rule: "max-lines-per-function",
+  options: COUNTED,
+  measured: /has too many lines \((\d+)\)/,
+  limits: "The most lines a function may span, blank and comment lines counted",
+} as const;
+
+const STATEMENTS = {
+  key: "statements",
+  rule: "max-statements",
+  options: {},
+  measured: /has too many statements \((\d+)\)/,
+  limits: "The most statements a function may hold",
+} as const;
+
+const COMPLEXITY = {
+  key: "complexity",
+  rule: "complexity",
+  options: { variant: "modified" },
+  measured: /has a complexity of (\d+)/,
+  limits: "The highest cyclomatic complexity a function may reach, a switch counted once",
+} as const;
+
+const DEPTH = {
+  key: "depth",
+  rule: "max-depth",
+  options: {},
+  measured: /nested too deeply \((\d+)\)/,
+  limits: "The deepest a block may nest inside a function",
+} as const;
+
+export const SIZE_RULES = [FILE_LINES, FUNCTION_LINES, STATEMENTS, COMPLEXITY, DEPTH] as const;
+
+export type SizeRule = (typeof SIZE_RULES)[number];
+export type LimitKey = SizeRule["key"];
+
+// An absent limit turns its rule off.
+export type Budget = { readonly [K in LimitKey]?: number };
+
+export type Budgets = { readonly production: Budget; readonly tests: Budget };
+
+const APPLIES = ["ratchet", "all"] as const;
+export type Applies = (typeof APPLIES)[number];
+
+export const SIZE_DEFAULTS = {
+  applies: "ratchet",
+  production: { fileLines: 400, functionLines: 100, statements: 30, complexity: 15, depth: 4 },
+  tests: { fileLines: 600, statements: 50, complexity: 15, depth: 4 },
+} as const satisfies Budgets & { readonly applies: Applies };
+
+const Limit = Schema.Int.check(Schema.isGreaterThan(0));
+
+function limit({ limits }: SizeRule, fallback: number) {
+  return Schema.optionalKey(Limit.annotate({ description: `${limits}; ${fallback} when absent` }));
+}
+
+const ProductionBudget = Schema.Struct({
+  fileLines: limit(FILE_LINES, SIZE_DEFAULTS.production.fileLines),
+  functionLines: limit(FUNCTION_LINES, SIZE_DEFAULTS.production.functionLines),
+  statements: limit(STATEMENTS, SIZE_DEFAULTS.production.statements),
+  complexity: limit(COMPLEXITY, SIZE_DEFAULTS.production.complexity),
+  depth: limit(DEPTH, SIZE_DEFAULTS.production.depth),
+});
+
+const TestBudget = Schema.Struct({
+  fileLines: limit(FILE_LINES, SIZE_DEFAULTS.tests.fileLines),
+  statements: limit(STATEMENTS, SIZE_DEFAULTS.tests.statements),
+  complexity: limit(COMPLEXITY, SIZE_DEFAULTS.tests.complexity),
+  depth: limit(DEPTH, SIZE_DEFAULTS.tests.depth),
+});
+
+export const Size = Schema.Struct({
+  applies: Schema.optionalKey(
+    Schema.Literals(APPLIES).annotate({
+      description: `Which production and test files the budget holds: ratchet, the ones a range adds or changes, to no more overrun per rule than at the range's base; all, every one. ${SIZE_DEFAULTS.applies} when absent. The rest are listed as advisory`,
+      message: "Expected ratchet or all, and ratchet replaces changed",
+    }),
+  ),
+  production: Schema.optionalKey(
+    ProductionBudget.annotate({
+      description: `The budget of the files under sources.production, and of the files listed as advisory outside ${TESTS_DIRECTORY}/`,
+    }),
+  ),
+  tests: Schema.optionalKey(
+    TestBudget.annotate({ description: `The budget of the files under ${TESTS_DIRECTORY}/, which sets no limit on a function's lines` }),
+  ),
+}).annotate({
+  description: "The size budget oxlint holds production and test files to, read by checks-size-budget",
+  messageUnexpectedKey: "Expected only applies, production and tests, since each limit is set inside production or tests",
+});
+export type Size = typeof Size.Type;
+
+export function budgetsOf(size: Size): Budgets {
+  return {
+    production: { ...SIZE_DEFAULTS.production, ...size.production },
+    tests: { ...SIZE_DEFAULTS.tests, ...size.tests },
+  };
+}
+
+export function budgetOf({ production, tests }: Budgets, file: string): Budget {
+  return file.startsWith(`${TESTS_DIRECTORY}/`) ? tests : production;
+}