@avi2dg/checks 0.10.0 → 0.12.0

package/scripts/quality.ts

@@ -0,0 +1,180 @@
+#!/usr/bin/env bun
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import kitOxlint from "../oxlintrc.json" with { type: "json" };
+import effectLanguageService from "../presets/effect.language-service.json" with { type: "json" };
+import effectOxlint from "../presets/effect.oxlint.json" with { type: "json" };
+import { git } from "./git.ts";
+import { runMain, Usage } from "./main.ts";
+import { readQuality, renderJson, type Quality } from "./quality-file.ts";
+
+// oxlint resolves an override's files, and the language service an override's include, against the
+// directory of the config that holds it, so a fragment anywhere but the root matches nothing there.
+export const OXLINT_FRAGMENT = "oxlintrc.quality.json";
+export const TSCONFIG_FRAGMENT = "tsconfig.quality.json";
+
+const NAME = "checks-quality";
+const USAGE = `usage: ${NAME} --check | generate`;
+const GENERATE = `${NAME} generate`;
+
+type EffectSources = NonNullable<NonNullable<Quality["sources"]>["effect"]>;
+
+export type Fragment = {
+  readonly file: typeof OXLINT_FRAGMENT | typeof TSCONFIG_FRAGMENT;
+  readonly extendedBy: string;
+  readonly reader: string;
+  readonly content: unknown;
+};
+
+class NativeConfigUnreadable extends Schema.TaggedError<NativeConfigUnreadable>()("NativeConfigUnreadable", {
+  message: Schema.String,
+}) {}
+
+function oxlintFragment({ paths, exempt = [] }: EffectSources): unknown {
+  const override = {
+    files: paths,
+    ...(exempt.length === 0 ? {} : { excludeFiles: exempt }),
+    // An override that leaves out any of the kit's plugins turns on the category rules of the ones it adds.
+    plugins: [...kitOxlint.plugins, ...effectOxlint.plugins.filter((plugin) => !kitOxlint.plugins.includes(plugin))],
+    rules: effectOxlint.rules,
+  };
+  return {
+    $schema: "./node_modules/oxlint/configuration_schema.json",
+    // A config without plugins brings oxlint's default plugins into the one extending it.
+    plugins: kitOxlint.plugins,
+    overrides: [override],
+  };
+}
+
+function tsconfigFragment({ paths, exempt = [] }: EffectSources): unknown {
+  const override = { include: paths, ...(exempt.length === 0 ? {} : { exclude: exempt }), options: effectLanguageService };
+  return { compilerOptions: { plugins: [{ name: "@effect/language-service", overrides: [override] }] } };
+}
+
+const FRAGMENTS = [
+  { file: OXLINT_FRAGMENT, extendedBy: ".oxlintrc.json", reader: "oxlint", build: oxlintFragment },
+  { file: TSCONFIG_FRAGMENT, extendedBy: "tsconfig.json", reader: "the language service", build: tsconfigFragment },
+] as const;
+
+export function fragmentsFor(quality: Quality): readonly Fragment[] {
+  const effect = quality.sources?.effect;
+  if (effect === undefined) return [];
+  return FRAGMENTS.map(({ build, ...fragment }) => ({ ...fragment, content: build(effect) }));
+}
+
+const NativeConfig = Schema.Struct({
+  extends: Schema.optionalKey(Schema.Union([Schema.String, Schema.Array(Schema.String)])),
+});
+const decodeNativeConfig = Schema.decodeUnknownEffect(NativeConfig);
+
+const parseJsonc = (text: string, file: string) =>
+  Effect.try({
+    try: (): unknown => Bun.JSONC.parse(text),
+    catch: (error) => new NativeConfigUnreadable({ message: `cannot parse ${file}: ${String(error)}` }),
+  });
+
+const extendsOf = Effect.fn("extendsOf")(function* (root: string, file: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const target = path.join(root, file);
+  if (!(yield* fs.exists(target))) return [];
+  const config = yield* fs.readFileString(target).pipe(
+    Effect.flatMap((text) => parseJsonc(text, file)),
+    Effect.flatMap(decodeNativeConfig),
+    Effect.mapError((cause) => new NativeConfigUnreadable({ message: `cannot read extends from ${file}: ${cause.message}` })),
+  );
+  const listed = config.extends ?? [];
+  return (typeof listed === "string" ? [listed] : listed).map((entry) => path.normalize(entry));
+});
+
+const decodeJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));
+
+const sameJson = (text: string, content: unknown): Effect.Effect<boolean> =>
+  decodeJson(text).pipe(
+    Effect.map((parsed) => Bun.deepEquals(parsed, content, true)),
+    Effect.orElseSucceed(() => false),
+  );
+
+const fragmentProblems = Effect.fn("fragmentProblems")(function* (root: string, source: string, expected: readonly Fragment[]) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const problems: string[] = [];
+  for (const { file } of FRAGMENTS) {
+    const target = path.join(root, file);
+    const fragment = expected.find((candidate) => candidate.file === file);
+    const present = yield* fs.exists(target);
+    if (fragment === undefined) {
+      if (present) problems.push(`${file} is left over, since no sources.effect is declared; run ${GENERATE}`);
+      continue;
+    }
+    if (!present) {
+      problems.push(`${file} is missing; run ${GENERATE}`);
+    } else if (!(yield* sameJson(yield* fs.readFileString(target), fragment.content))) {
+      problems.push(`${file} is stale against ${source} and the kit's presets; run ${GENERATE}`);
+    }
+    if (!(yield* extendsOf(root, fragment.extendedBy)).includes(file)) {
+      problems.push(`${fragment.extendedBy} does not extend ./${file}, so ${fragment.reader} never reads it`);
+    }
+  }
+  return problems;
+});
+
+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, key, holds } of declared) {
+    const matched = yield* git(["ls-files", "--cached", "--others", "--exclude-standard", "--", `:(glob)${glob}`], root);
+    if (matched.trim() === "") problems.push(`${key} ${glob} matches no file, so it holds ${holds}`);
+  }
+  return problems;
+});
+
+const check = Effect.fn("check")(function* (root: string) {
+  const { source, quality } = yield* readQuality(root);
+  const expected = fragmentsFor(quality);
+  const problems = [...(yield* fragmentProblems(root, source, expected)), ...(yield* unmatchedPaths(root, quality))];
+  if (problems.length > 0) {
+    yield* Console.error([`${NAME}: ${problems.length} problem(s) with what ${source} declares:`, ...problems.map((line) => `  ${line}`)].join("\n"));
+    return false;
+  }
+  yield* Console.log(
+    expected.length === 0
+      ? `${NAME}: no sources.effect is declared, so nothing is generated`
+      : `${NAME}: ${expected.map((fragment) => fragment.file).join(" and ")} hold what ${source} declares`,
+  );
+  return true;
+});
+
+const generate = Effect.fn("generate")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const { quality } = yield* readQuality(root);
+  const expected = fragmentsFor(quality);
+  for (const { file } of FRAGMENTS) {
+    const target = path.join(root, file);
+    const fragment = expected.find((candidate) => candidate.file === file);
+    if (fragment !== undefined) {
+      yield* fs.writeFileString(target, renderJson(fragment.content));
+      yield* Console.log(`${NAME}: wrote ${file}`);
+    } else if (yield* fs.exists(target)) {
+      yield* fs.remove(target);
+      yield* Console.log(`${NAME}: removed ${file}`);
+    }
+  }
+  return yield* check(root);
+});
+
+const main = Effect.gen(function* () {
+  const [mode, ...extra] = process.argv.slice(2);
+  if (extra.length > 0 || (mode !== "--check" && mode !== "generate")) return yield* new Usage({ message: USAGE });
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  return mode === "generate" ? yield* generate(root) : yield* check(root);
+});
+
+if (import.meta.main) runMain(NAME, main);

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);