@avi2dg/checks 0.11.0 → 0.13.0

package/scripts/feature-owners.ts

@@ -0,0 +1,142 @@
+#!/usr/bin/env bun
+import { parse } from "@swc/core";
+import { Console, Effect, Path, Schema } from "effect";
+import { changedPaths, git, pathsAt, rangeEnds, type Change } from "./git.ts";
+import { runMain, Usage } from "./main.ts";
+import { PROOF_DIRECTORY, readQuality, type Feature } from "./quality-file.ts";
+
+type Unproven = {
+  readonly feature: string;
+  readonly reason: string;
+};
+
+type Touch = {
+  readonly feature: string;
+  readonly paths: readonly string[];
+};
+
+class ProofUnparsed extends Schema.TaggedError<ProofUnparsed>()("ProofUnparsed", {
+  message: Schema.String,
+}) {}
+
+const NAME = "feature-owners";
+const USAGE = "usage: feature-owners.ts <ref> | <base-ref> <head-ref>";
+const RELATIVE = /^\.\.?\//;
+const SCRIPT_EXTENSIONS = new Map([
+  [".js", [".ts", ".tsx"]],
+  [".jsx", [".tsx"]],
+  [".mjs", [".mts"]],
+  [".cjs", [".cts"]],
+]);
+
+const runtimeSpecifiers = Effect.fn("runtimeSpecifiers")(function* (file: string, source: string) {
+  const module = yield* Effect.tryPromise({
+    try: () => parse(source, { syntax: "typescript", tsx: file.endsWith(".tsx"), target: "esnext" }),
+    catch: (error) => new ProofUnparsed({ message: `${file} does not parse: ${String(error)}` }),
+  });
+  return module.body.flatMap((item) => {
+    if (item.type === "ImportDeclaration" && !item.typeOnly) return [item.source.value];
+    // swc types source as optional, but a local export such as `export { x }` carries null.
+    if (item.type === "ExportNamedDeclaration" && !item.typeOnly && item.source) return [item.source.value];
+    if (item.type === "ExportAllDeclaration") return [item.source.value];
+    return [];
+  });
+});
+
+const candidatesFor = Effect.fn("candidatesFor")(function* (importer: string, specifier: string) {
+  if (!RELATIVE.test(specifier)) return [];
+  const path = yield* Path.Path;
+  const target = path.join(path.dirname(importer), specifier);
+  const extension = path.extname(target);
+  const sources = SCRIPT_EXTENSIONS.get(extension);
+  if (sources !== undefined) return [target, ...sources.map((source) => `${target.slice(0, -extension.length)}${source}`)];
+  if (extension !== "") return [target];
+  return [`${target}.ts`, `${target}.tsx`, `${target}/index.ts`, `${target}/index.tsx`];
+});
+
+const proofImportsAnEntry = Effect.fn("proofImportsAnEntry")(function* (root: string, head: string, feature: Feature) {
+  const source = yield* git(["cat-file", "blob", `${head}:${feature.proof}`], root);
+  const specifiers = yield* runtimeSpecifiers(feature.proof, source);
+  const reached = yield* Effect.forEach(specifiers, (specifier) => candidatesFor(feature.proof, specifier));
+  return reached.flat().some((path) => feature.entries.includes(path));
+});
+
+const unproven = Effect.fn("unproven")(function* (root: string, head: string, features: readonly Feature[]) {
+  const declared = features.flatMap((feature) => [feature.proof, ...feature.entries]);
+  const present = new Set(yield* pathsAt(head, declared.map((path) => `:(literal)${path}`), root));
+  const found: Unproven[] = [];
+  for (const feature of features) {
+    const refuse = (reason: string) => found.push({ feature: feature.name, reason });
+    for (const entry of feature.entries.filter((path) => !present.has(path))) refuse(`entry ${entry} is not in the head commit`);
+    if (!present.has(feature.proof)) {
+      refuse(`proof ${feature.proof} is not in the head commit`);
+      continue;
+    }
+    const reason = yield* proofImportsAnEntry(root, head, feature).pipe(
+      Effect.map((imports) => (imports ? undefined : `proof ${feature.proof} imports none of its entries, ${feature.entries.join(", ")}`)),
+      Effect.catchTag("ProofUnparsed", (error) => Effect.succeed(`proof ${error.message}`)),
+    );
+    if (reason !== undefined) refuse(reason);
+  }
+  return found;
+});
+
+function ownerOf(features: readonly Feature[], path: string): string | undefined {
+  return features.find((feature) => path.startsWith(`${feature.root}/`) || path === feature.proof)?.name;
+}
+
+function touches(features: readonly Feature[], changes: readonly Change[]): readonly Touch[] {
+  const byOwner = new Map<string, string[]>();
+  for (const change of changes) {
+    for (const path of change.kind === "renamed" ? [change.from, change.path] : [change.path]) {
+      const owner = ownerOf(features, path);
+      if (owner === undefined) continue;
+      byOwner.set(owner, [...(byOwner.get(owner) ?? []), path]);
+    }
+  }
+  return features.flatMap((feature) => {
+    const paths = byOwner.get(feature.name);
+    return paths === undefined ? [] : [{ feature: feature.name, paths }];
+  });
+}
+
+function proofReport(features: readonly Feature[], found: readonly Unproven[]): string {
+  if (found.length === 0) {
+    return `${NAME}: ${features.length} feature(s) keep a proof under ${PROOF_DIRECTORY} that imports an entry`;
+  }
+  return [
+    `${NAME}: ${found.length} problem(s) with the features' runnable proofs:`,
+    ...found.map(({ feature, reason }) => `  ${feature}: ${reason}`),
+  ].join("\n");
+}
+
+function signalReport(touched: readonly Touch[]): string {
+  if (touched.length === 0) return `${NAME}: advisory, the range touches no feature owner`;
+  const judge = touched.length > 1 ? "; a reviewer judges whether they make one slice" : "";
+  return [
+    `${NAME}: advisory, the range touches ${touched.length} feature owner(s)${judge}:`,
+    ...touched.map(({ feature, paths }) => `  ${feature}: ${paths.join(", ")}`),
+  ].join("\n");
+}
+
+const owners = Effect.gen(function* () {
+  const [first, second, ...extra] = process.argv.slice(2);
+  if (first === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
+
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  const { source, quality } = yield* readQuality(root);
+  const features = quality.features ?? [];
+  if (features.length === 0) {
+    yield* Console.log(`${NAME}: ${source} declares no feature`);
+    return true;
+  }
+  const { base, head } = yield* rangeEnds(first, second, root);
+  const found = yield* unproven(root, head, features);
+  yield* Console.log(proofReport(features, found));
+  if (quality.changeSignal === "advisory") {
+    yield* Console.log(signalReport(touches(features, yield* changedPaths(base, head, [], root))));
+  }
+  return found.length === 0;
+});
+
+if (import.meta.main) runMain(NAME, owners);

package/scripts/gates.ts

@@ -37,7 +37,10 @@ export const KIT_GATES = [
   { bin: "checks-comment-gate", script: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-suppressions-ratchet", script: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-ci-wiring", script: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-docs", script: "docs.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-quality", script: "quality.ts", reads: "tree", args: ["--check"], appliesTo: QUALITY_DECLARATION },
+  { bin: "checks-size-budget", script: "size-budget.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-feature-owners", script: "feature-owners.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
 ] as const satisfies readonly KitGate[];
 
 const UNCONDITIONAL = KIT_GATES.filter((gate) => gate.appliesTo === EVERY_REPOSITORY).map((gate) => gate.bin);

package/scripts/git.ts

@@ -8,24 +8,76 @@ export class GitFailure extends Schema.TaggedError<GitFailure>()("GitFailure", {
 const text = <E>(bytes: Stream.Stream<Uint8Array, E>): Effect.Effect<string, E> =>
   bytes.pipe(Stream.decodeText(), Stream.mkString);
 
-// Both pipes drain while git runs: one left unread fills its buffer and stalls git.
-export const git = Effect.fn("git")(
-  function* (args: readonly string[], cwd?: string) {
+export type Feed = {
+  readonly env?: Readonly<Record<string, string>>;
+  readonly input?: string;
+};
+
+// Both pipes drain while the program runs: one left unread fills its buffer and stalls it.
+export const collect = Effect.fn("collect")(
+  function* (program: string, args: readonly string[], cwd?: string, { env, input }: Feed = {}) {
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-    const command = `git ${args.join(" ")}`;
-    const failed = (stderr: string): GitFailure => new GitFailure({ message: `${command}: ${stderr.trim()}` });
-    const handle = yield* spawner
-      .spawn(ChildProcess.make("git", args, { cwd }))
-      .pipe(Effect.mapError((cause) => failed(cause.message)));
+    const stdin = input === undefined ? undefined : Stream.make(new TextEncoder().encode(input));
+    const handle = yield* spawner.spawn(ChildProcess.make(program, args, { cwd, env, extendEnv: true, stdin }));
     const [stdout, stderr, exitCode] = yield* Effect.all([text(handle.stdout), text(handle.stderr), handle.exitCode], {
       concurrency: "unbounded",
-    }).pipe(Effect.mapError((cause) => failed(cause.message)));
-    if (exitCode !== ChildProcessSpawner.ExitCode(0)) return yield* failed(stderr);
-    return stdout;
+    });
+    return { stdout, stderr, exitCode };
   },
   Effect.scoped,
 );
 
+export const git = Effect.fn("git")(function* (args: readonly string[], cwd?: string, feed?: Feed) {
+  const failed = (reason: string): GitFailure => new GitFailure({ message: `git ${args.join(" ")}: ${reason.trim()}` });
+  const { stdout, stderr, exitCode } = yield* collect("git", args, cwd, feed).pipe(
+    Effect.mapError((cause) => failed(cause.message)),
+  );
+  if (exitCode !== ChildProcessSpawner.ExitCode(0)) return yield* failed(stderr);
+  return stdout;
+});
+
+export type Change =
+  | { readonly kind: "written" | "deleted"; readonly path: string }
+  | { readonly kind: "renamed"; readonly from: string; readonly path: string; readonly edited: boolean };
+
+const UNCHANGED_RENAME = "R100";
+
+function parseNameStatus(output: string): readonly Change[] {
+  const fields = output.split("\0");
+  const changes: Change[] = [];
+  let index = 0;
+  while (index < fields.length - 1) {
+    const status = fields[index] ?? "";
+    if (status.startsWith("R")) {
+      changes.push({ kind: "renamed", from: fields[index + 1] ?? "", path: fields[index + 2] ?? "", edited: status !== UNCHANGED_RENAME });
+      index += 3;
+    } else if (status.startsWith("C")) {
+      changes.push({ kind: "written", path: fields[index + 2] ?? "" });
+      index += 3;
+    } else {
+      changes.push({ kind: status === "D" ? "deleted" : "written", path: fields[index + 1] ?? "" });
+      index += 2;
+    }
+  }
+  return changes;
+}
+
+export const changedPaths = Effect.fn("changedPaths")(function* (
+  base: string,
+  head: string,
+  pathspecs: readonly string[],
+  cwd?: string,
+) {
+  return parseNameStatus(yield* git(["diff", "--name-status", "-z", "-M", base, head, "--", ...pathspecs], cwd));
+});
+
+const emptyTree = (cwd?: string) => git(["hash-object", "-t", "tree", "/dev/null"], cwd).pipe(Effect.map((sha) => sha.trim()));
+
+export const pathsAt = Effect.fn("pathsAt")(function* (rev: string, pathspecs: readonly string[], cwd?: string) {
+  const listed = yield* git(["diff", "--name-only", "-z", "--no-renames", yield* emptyTree(cwd), rev, "--", ...pathspecs], cwd);
+  return listed.split("\0").filter((path) => path !== "");
+});
+
 function namesAParent(commitObject: string): boolean {
   const [headers = ""] = commitObject.split("\n\n", 1);
   return headers.split("\n").some((header) => header.startsWith("parent "));
@@ -34,8 +86,12 @@ function namesAParent(commitObject: string): boolean {
 // A shallow clone's boundary commit reads as parentless to rev-parse and log, and judged against
 // the empty tree it would carry the whole repository; only the commit object still names its parents.
 export const parentOrEmptyTree = Effect.fn("parentOrEmptyTree")(function* (rev: string, cwd?: string) {
-  if (!namesAParent(yield* git(["cat-file", "commit", rev], cwd))) {
-    return (yield* git(["hash-object", "-t", "tree", "/dev/null"], cwd)).trim();
-  }
+  if (!namesAParent(yield* git(["cat-file", "commit", rev], cwd))) return yield* emptyTree(cwd);
   return (yield* git(["rev-parse", "--verify", `${rev}^`], cwd)).trim();
 });
+
+// From the base branch's tip, a range would charge the head with what the base branch changed after it branched off.
+export const rangeEnds = Effect.fn("rangeEnds")(function* (first: string, second: string | undefined, cwd?: string) {
+  if (second === undefined) return { base: yield* parentOrEmptyTree(first, cwd), head: first };
+  return { base: (yield* git(["merge-base", first, second], cwd)).trim(), head: second };
+});

package/scripts/quality-file.ts

@@ -20,6 +20,28 @@ const PathGlob = Schema.String.check(
     "A glob from the repository root that oxlint, the Effect language service and git read alike: a directory first, * within a segment, ** as a whole one, a file name with an extension last, and no braces, ?, [ or leading ./",
 });
 
+const LITERAL_SEGMENT = String.raw`(?!\.\.?(?:/|$))[\w.@+-]+`;
+
+const DirectoryPath = Schema.String.check(
+  Schema.isPattern(new RegExp(`^${LITERAL_SEGMENT}(?:/${LITERAL_SEGMENT})*$`), {
+    expected: "a directory from the repository root such as src/billing, with no glob and no trailing slash",
+  }),
+).annotate({ identifier: "DirectoryPath" });
+
+const FilePath = Schema.String.check(
+  Schema.isPattern(new RegExp(`^(?:${LITERAL_SEGMENT}/)*[\\w.@+-]*\\.\\w+$`), {
+    expected: "a file from the repository root such as src/billing/index.ts, with no glob",
+  }),
+).annotate({ identifier: "FilePath" });
+
+export const PROOF_DIRECTORY = "tests/e2e/";
+
+const ProofPath = Schema.String.check(
+  Schema.isPattern(new RegExp(`^${PROOF_DIRECTORY}(?:${LITERAL_SEGMENT}/)*[\\w.@+-]+\\.test\\.tsx?$`), {
+    expected: `a test file under ${PROOF_DIRECTORY} such as ${PROOF_DIRECTORY}billing.test.ts`,
+  }),
+).annotate({ identifier: "ProofPath" });
+
 const Command = Schema.NonEmptyString.annotate({ identifier: "Command" });
 
 const RuleName = Schema.String.check(
@@ -65,6 +87,58 @@ const Sources = Schema.Struct({
   effect: Schema.optionalKey(EffectSources),
 });
 
+const LineBudget = Schema.Int.check(Schema.isGreaterThan(0));
+
+const Size = Schema.Struct({
+  fileLines: LineBudget.annotate({ description: "The most lines a file may hold, blank and comment lines counted" }),
+  functionLines: LineBudget.annotate({
+    description: "The most lines a function may span, blank and comment lines counted",
+  }),
+  applies: Schema.Literals(["changed", "all"]).annotate({
+    description:
+      "Which production files the budget holds: changed, the ones a range adds or changes; all, every one. The rest are reported as advisory",
+  }),
+});
+
+const Feature = Schema.Struct({
+  name: Schema.String.check(
+    Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { expected: "a feature name in kebab case" }),
+  ).annotate({ description: "The owner the dependency rule and the change signal name" }),
+  root: DirectoryPath.annotate({ description: "The directory the feature owns" }),
+  entries: Schema.NonEmptyArray(FilePath).annotate({
+    description: "The files under root that code outside it imports the feature through",
+  }),
+  allowFrom: Schema.optionalKey(
+    Schema.Array(PathGlob).annotate({
+      description: "Files outside root that may import past its entries, such as a CLI or a harness; tests/ always may",
+    }),
+  ),
+  proof: ProofPath.annotate({ description: "The end-to-end test that imports one of entries" }),
+}).check(
+  Schema.makeFilter(({ root, entries }) => {
+    const outside = entries.filter((entry) => !entry.startsWith(`${root}/`));
+    return outside.length === 0 || `lists ${outside.join(", ")} among its entries, outside its root ${root}`;
+  }),
+);
+export type Feature = typeof Feature.Type;
+
+function nests(outer: string, inner: string): boolean {
+  return outer === inner || inner.startsWith(`${outer}/`);
+}
+
+const Features = Schema.Array(Feature).check(
+  Schema.makeFilter((features) => {
+    const names = features.map((feature) => feature.name);
+    const repeated = names.filter((name, index) => names.indexOf(name) !== index);
+    if (repeated.length > 0) return `names ${[...new Set(repeated)].join(", ")} more than once`;
+    for (const outer of features) {
+      const inner = features.find((other) => other !== outer && nests(outer.root, other.root));
+      if (inner !== undefined) return `gives ${inner.root} to both ${outer.name} and ${inner.name}`;
+    }
+    return true;
+  }),
+);
+
 const AgentRules = Schema.Struct({
   on: Schema.optionalKey(Schema.Array(RuleName).annotate({ description: "Catalogued Rules switched on here" })),
   off: Schema.optionalKey(Schema.Array(RuleName).annotate({ description: "Catalogued Rules switched off here" })),
@@ -75,6 +149,26 @@ const AgentRules = Schema.Struct({
   }),
 );
 
+export const MODES = ["tutorial", "how-to", "reference", "explanation"] as const;
+export type Mode = (typeof MODES)[number];
+
+const pagesIn = (mode: string) =>
+  Schema.optionalKey(Schema.Array(PathGlob).annotate({ description: `The pages written as ${mode}` }));
+
+const Docs = Schema.Struct({
+  pages: Schema.optionalKey(
+    Schema.Struct({
+      tutorial: pagesIn("a tutorial, which teaches by building one thing"),
+      "how-to": pagesIn("a how-to, which walks one task"),
+      reference: pagesIn("reference, which describes a thing to be looked up"),
+      explanation: pagesIn("an explanation, which says why"),
+    } satisfies Record<Mode, unknown>).annotate({
+      description: "The Diátaxis mode of each page, whose template checks-docs holds the page to; a page under docs/ needs one",
+    }),
+  ),
+});
+export type Docs = typeof Docs.Type;
+
 export const Quality = Schema.Struct({
   $schema: Schema.optionalKey(Schema.String),
   defaultBranch: Schema.optionalKey(
@@ -83,11 +177,48 @@ export const Quality = Schema.Struct({
   gates: Schema.optionalKey(Gates),
   commitIdentity: Schema.optionalKey(CommitIdentity),
   sources: Schema.optionalKey(Sources),
+  size: Schema.optionalKey(
+    Size.annotate({ description: "The line budget oxlint holds production files to, read by checks-size-budget" }),
+  ),
+  features: Schema.optionalKey(
+    Features.annotate({
+      description: "The feature owners dependency-cruiser holds to their entries and checks-feature-owners maps a change to",
+    }),
+  ),
+  changeSignal: Schema.optionalKey(
+    Schema.Literal("advisory").annotate({
+      description: "Report which feature owners a change touches, without failing on it",
+    }),
+  ),
   agentRules: Schema.optionalKey(AgentRules),
-}).annotate({
-  title: QUALITY_FILE,
-  description: "What a repository has opted into from @avi2dg/checks, read by its bins and agent Rule selection",
-});
+  docs: Schema.optionalKey(Docs.annotate({ description: "What checks-docs reads to map a doc file to its template" })),
+})
+  .annotate({
+    title: QUALITY_FILE,
+    description: "What a repository has opted into from @avi2dg/checks, read by its bins and agent Rule selection",
+  })
+  .check(
+    Schema.makeFilter(
+      ({ size, sources }) =>
+        size === undefined || (sources?.production ?? []).length > 0 || "declares size, which holds nothing without sources.production",
+      {
+        toJsonSchema: () => ({
+          if: { required: ["size"] },
+          then: { required: ["sources"], properties: { sources: { required: ["production"], properties: { production: { minItems: 1 } } } } },
+        }),
+      },
+    ),
+    Schema.makeFilter(
+      ({ changeSignal, features = [] }) =>
+        changeSignal === undefined || features.length > 0 || "declares changeSignal, which maps a change to no owner without features",
+      {
+        toJsonSchema: () => ({
+          if: { required: ["changeSignal"] },
+          then: { required: ["features"], properties: { features: { minItems: 1 } } },
+        }),
+      },
+    ),
+  );
 export type Quality = typeof Quality.Type;
 
 const LegacyManifest = Schema.Struct({

package/scripts/quality.ts

@@ -119,10 +119,18 @@ const fragmentProblems = Effect.fn("fragmentProblems")(function* (root: string,
 });
 
 const unmatchedPaths = Effect.fn("unmatchedPaths")(function* (root: string, quality: Quality) {
+  const declared = [
+    ...(quality.size === undefined ? [] : (quality.sources?.production ?? [])).map((glob) => ({
+      glob,
+      key: "sources.production",
+      holds: "no source to the size budget",
+    })),
+    ...(quality.sources?.effect?.paths ?? []).map((glob) => ({ glob, key: "sources.effect.paths", holds: "nothing to the Effect rules" })),
+  ];
   const problems: string[] = [];
-  for (const glob of quality.sources?.effect?.paths ?? []) {
+  for (const { glob, key, holds } of declared) {
     const matched = yield* git(["ls-files", "--cached", "--others", "--exclude-standard", "--", `:(glob)${glob}`], root);
-    if (matched.trim() === "") problems.push(`sources.effect.paths ${glob} matches no file, so it holds nothing to the Effect rules`);
+    if (matched.trim() === "") problems.push(`${key} ${glob} matches no file, so it holds ${holds}`);
   }
   return problems;
 });

package/scripts/size-budget.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env bun
+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";
+
+type Size = NonNullable<Quality["size"]>;
+
+type Overrun = {
+  readonly file: string;
+  readonly line: number | undefined;
+  readonly message: string;
+};
+
+type Measured = {
+  readonly scope: string;
+  readonly held: readonly string[];
+  readonly overruns: readonly Overrun[];
+  readonly advisory: readonly Overrun[];
+};
+
+class OxlintUnreadable extends Schema.TaggedError<OxlintUnreadable>()("OxlintUnreadable", {
+  message: Schema.String,
+}) {}
+
+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 OXLINT_FOUND_NOTHING = 0;
+const OXLINT_FOUND_ERRORS = 1;
+
+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 sizeConfig({ fileLines, functionLines }: Size): unknown {
+  const counted = { skipBlankLines: false, skipComments: false };
+  return {
+    plugins: [],
+    categories: { correctness: "off" },
+    rules: {
+      "max-lines": ["error", { max: fileLines, ...counted }],
+      "max-lines-per-function": ["error", { max: functionLines, ...counted }],
+    },
+  };
+}
+
+function heldByChange(changes: readonly Change[]): readonly string[] {
+  return changes.flatMap((change) => {
+    if (change.kind === "written" || (change.kind === "renamed" && change.edited)) return [change.path];
+    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") };
+  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;
+});
+
+// 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 [];
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    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 { 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 [];
+    });
+  },
+  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 }: Overrun): string {
+  return `  ${file}${line === undefined ? "" : `:${line}`}: ${message}`;
+}
+
+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)];
+  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");
+}
+
+const budget = Effect.gen(function* () {
+  const [first, second, ...extra] = process.argv.slice(2);
+  if (first === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
+
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  const { source, quality } = yield* readQuality(root);
+  if (quality.size === undefined) {
+    yield* Console.log(`${NAME}: ${source} declares no size budget`);
+    return true;
+  }
+  const { base, head } = yield* rangeEnds(first, second, root);
+  const measured = yield* runBudget(root, quality.size, quality.sources?.production ?? [], base, head);
+
+  yield* Console.log(report(measured, quality.size));
+  return measured.overruns.length === 0;
+});
+
+if (import.meta.main) runMain(NAME, budget);

package/templates/adr.md

@@ -0,0 +1,29 @@
+# <number>. <The decision, as a sentence>
+
+Date: <YYYY-MM-DD, the day the record was written>
+
+## Status
+
+<Proposed, Accepted, Rejected, Deprecated, Superseded or Retired as its first word, then what it amends or what replaced it.>
+
+## Context
+
+<What forced a decision, and what was true when it was made.>
+
+## <Another part of the record, such as What was considered and rejected>
+
+<Leave this section out when the record needs no more.>
+
+<A section like this may also follow any section below it.>
+
+<Its text.>
+
+## Decision
+
+<What was decided, stated as what now holds.>
+
+## Consequences
+
+<Leave this section out when nothing follows from the decision but the decision.>
+
+<What follows from the decision, its cost included.>

package/templates/agents.md

@@ -0,0 +1,17 @@
+# Project agent memory
+
+<What this repository is, in one sentence, and that README.md holds what a person reads.>
+
+## <A topic an agent needs>
+
+<Leave this section out when the lead holds every constraint.>
+
+- <A constraint an agent cannot infer from the code, and the file that holds its detail.>
+
+## Maintaining this file
+
+Keep this file for knowledge useful to almost every future agent session in this project.
+Do not repeat what the codebase already shows.
+Point to the authoritative file or command instead.
+Prefer rewriting or pruning existing entries over appending new ones.
+When updating this file, preserve this bar for all agents and keep entries concise.