@avi2dg/checks 0.9.0 → 0.11.0

package/scripts/flake.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env bun
+import { Config, Console, Effect, FileSystem, Option, Path, Random, Schema } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { runMain, Usage } from "./main.ts";
+import { NAME_SEPARATOR, parseReport, ReportError, reporterArgs, type TestResult } from "./test-report.ts";
+
+export type Run = {
+  readonly seed: number;
+  readonly passed: boolean;
+  readonly tests: number;
+  readonly failed: readonly TestResult[];
+};
+
+export type Failure = {
+  readonly file: string;
+  readonly test: string;
+  readonly line: number;
+  readonly seeds: readonly number[];
+};
+
+export type RunRecord = Omit<Run, "failed"> & { readonly failed: readonly string[] };
+
+export type FlakeRecord = {
+  readonly runs: readonly RunRecord[];
+  readonly failures: readonly Failure[];
+  readonly outsideTests: readonly number[];
+};
+
+type Plan = { readonly seeds: readonly number[] } | { readonly runs: number };
+
+const NAME = "checks-flake";
+const USAGE = `usage: ${NAME} [--runs <count> | --seed <seed>...] [--report <file>]`;
+const DEFAULT_RUNS = 10;
+const MAX_SEED = 2 ** 32 - 1;
+
+const wholeBetween = (minimum: number, maximum: number) =>
+  Schema.decodeUnknownEffect(Schema.NumberFromString.check(Schema.isInt(), Schema.isBetween({ minimum, maximum })));
+const decodeRuns = wholeBetween(1, 1000);
+const decodeSeed = wholeBetween(0, MAX_SEED);
+
+const parseArgs = Effect.fnUntraced(function* (args: readonly string[]) {
+  const usage = (reason?: string) => new Usage({ message: reason === undefined ? USAGE : `${reason}; ${USAGE}` });
+  let runs: string | undefined;
+  let report: string | undefined;
+  const seeds: string[] = [];
+  for (let index = 0; index < args.length; index += 2) {
+    const [flag, value] = [args[index], args[index + 1]];
+    if (value === undefined) return yield* usage();
+    if (flag === "--runs" && runs === undefined) runs = value;
+    else if (flag === "--seed") seeds.push(value);
+    else if (flag === "--report" && report === undefined) report = value;
+    else return yield* usage();
+  }
+  if (runs !== undefined && seeds.length > 0) return yield* usage();
+  const invalid = (flag: string) => (cause: { readonly message: string }) => usage(`${flag}: ${cause.message}`);
+  const plan: Plan =
+    seeds.length > 0
+      ? { seeds: yield* Effect.forEach(seeds, (seed) => decodeSeed(seed).pipe(Effect.mapError(invalid("--seed")))) }
+      : { runs: runs === undefined ? DEFAULT_RUNS : yield* decodeRuns(runs).pipe(Effect.mapError(invalid("--runs"))) };
+  return { plan, report };
+});
+
+const seedsOf = (plan: Plan) =>
+  "seeds" in plan ? Effect.succeed(plan.seeds) : Effect.replicateEffect(Random.nextIntBetween(0, MAX_SEED), plan.runs);
+
+const runOnce = Effect.fn("runOnce")(function* (seed: number, outfile: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const args = ["test", "--randomize", `--seed=${seed}`, ...reporterArgs(outfile)];
+  const exitCode = yield* spawner.exitCode(
+    ChildProcess.make(process.execPath, args, { stdin: "ignore", stdout: "ignore", stderr: "ignore" }),
+  );
+  const passed = exitCode === ChildProcessSpawner.ExitCode(0);
+  if (!(yield* fs.exists(outfile))) {
+    if (passed) return yield* new ReportError({ message: `bun test passed with seed ${seed} but wrote no report` });
+    return { seed, passed, tests: 0, failed: [] } satisfies Run;
+  }
+  const results = yield* parseReport(yield* fs.readFileString(outfile));
+  return { seed, passed, tests: results.length, failed: results.filter((result) => result.outcome === "failed") } satisfies Run;
+});
+
+function outcomeOf(run: Run): string {
+  if (run.passed) return "passed";
+  return run.failed.length === 0 ? "failed outside any test" : `failed, ${run.failed.length} test(s) failing`;
+}
+
+function nameOf(result: TestResult): string {
+  return `${result.file}${NAME_SEPARATOR}${result.name}`;
+}
+
+export function recordOf(runs: readonly Run[]): FlakeRecord {
+  const failures = new Map<string, { file: string; test: string; line: number; seeds: number[] }>();
+  for (const run of runs) {
+    const failing = new Map(run.failed.map((result) => [nameOf(result), result]));
+    for (const [name, result] of failing) {
+      const failure = failures.get(name) ?? { file: result.file, test: result.name, line: result.line, seeds: [] };
+      failure.seeds.push(run.seed);
+      failures.set(name, failure);
+    }
+  }
+  return {
+    runs: runs.map(({ seed, passed, tests, failed }) => ({ seed, passed, tests, failed: failed.map(nameOf) })),
+    failures: [...failures.values()].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line),
+    outsideTests: runs.filter((run) => !run.passed && run.failed.length === 0).map((run) => run.seed),
+  };
+}
+
+function cell(text: string): string {
+  return text.replaceAll("|", "\\|");
+}
+
+export function summary(record: FlakeRecord): string {
+  const total = record.runs.length;
+  const failedRuns = record.runs.filter((run) => !run.passed).length;
+  if (failedRuns === 0) return `${NAME}: ${total} run(s) passed, with seeds ${record.runs.map((run) => run.seed).join(", ")}`;
+  const lines = [`${NAME}: ${failedRuns} of ${total} run(s) failed, ${record.failures.length} test(s) failing in them`];
+  if (record.failures.length > 0) {
+    lines.push("", "| Test | Failed | Seeds |", "| --- | --- | --- |");
+    for (const failure of record.failures) {
+      const place = cell(`${failure.file}:${failure.line} ${failure.test}`);
+      lines.push(`| ${place} | ${failure.seeds.length} of ${total} runs | ${failure.seeds.join(", ")} |`);
+    }
+  }
+  if (record.outsideTests.length > 0) {
+    lines.push("", `${record.outsideTests.length} run(s) failed outside any test, with seeds ${record.outsideTests.join(", ")}`);
+  }
+  lines.push("", "Reproduce a failing run with bun test --randomize --seed=<seed>.");
+  return lines.join("\n");
+}
+
+const flake = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const { plan, report } = yield* parseArgs(process.argv.slice(2));
+  const seeds = yield* seedsOf(plan);
+  const dir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-flake-" });
+
+  const runs = yield* Effect.forEach(seeds, (seed, index) =>
+    runOnce(seed, path.join(dir, `${index}.xml`)).pipe(
+      Effect.tap((run) => Console.log(`${NAME}: run ${index + 1} of ${seeds.length}, seed ${seed}: ${outcomeOf(run)}`)),
+    ),
+  );
+  const record = recordOf(runs);
+  const text = summary(record);
+  yield* Console.log(text);
+
+  if (report !== undefined) yield* fs.writeFileString(report, `${JSON.stringify(record, null, 2)}\n`);
+  const stepSummary = yield* Config.option(Config.String("GITHUB_STEP_SUMMARY"));
+  if (Option.isSome(stepSummary)) yield* fs.writeFileString(stepSummary.value, `${text}\n`, { flag: "a" });
+  return runs.every((run) => run.passed);
+}).pipe(Effect.scoped);
+
+if (import.meta.main) runMain(NAME, flake);

package/scripts/gates.ts

@@ -14,15 +14,22 @@ export const EVERY_REPOSITORY = "every repository";
 
 export type KitGate = Program & {
   readonly reads: "tree" | "range";
+  readonly args?: readonly string[];
   readonly appliesTo: typeof EVERY_REPOSITORY | TrackedContent;
 };
 
 export const ENTRY_POINT: Program = { bin: "checks-lint", script: "lint.ts" };
 
+export const TEST_ENTRY_POINT: Program = { bin: "checks-test", script: "test.ts" };
+
 export const DEFAULT_BRANCH = "main";
 
+export const QUALITY_FILE = "quality.json";
+
 const TYPESCRIPT_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx"], content: "TypeScript source" };
 
+const QUALITY_DECLARATION: TrackedContent = { pathspecs: [QUALITY_FILE], content: `a ${QUALITY_FILE}` };
+
 export const KIT_GATES = [
   { bin: "checks-lint-coverage", script: "lint-coverage.sh", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-test-layout", script: "test-layout.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
@@ -30,6 +37,7 @@ 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-quality", script: "quality.ts", reads: "tree", args: ["--check"], appliesTo: QUALITY_DECLARATION },
 ] as const satisfies readonly KitGate[];
 
 const UNCONDITIONAL = KIT_GATES.filter((gate) => gate.appliesTo === EVERY_REPOSITORY).map((gate) => gate.bin);
@@ -37,22 +45,16 @@ const UNCONDITIONAL = KIT_GATES.filter((gate) => gate.appliesTo === EVERY_REPOSI
 // A selection without ci-wiring would go unchecked under checks-lint, so a gate every repository runs
 // is refused where checks-lint decodes the selection, not by ci-wiring.
 export const LintGates = Schema.Array(Schema.Literals(KIT_GATES.map((gate) => gate.bin))).check(
-  Schema.makeFilter((selected) => {
-    const missing = UNCONDITIONAL.filter((bin) => !selected.includes(bin));
-    if (missing.length === 0) return true;
-    const verb = missing.length === 1 ? "applies" : "apply";
-    return `checks-lint must run ${missing.join(", ")}, which ${verb} to ${EVERY_REPOSITORY}`;
-  }),
-);
-
-export const LintWiring = Schema.Struct({
-  ciWiring: Schema.optionalKey(
-    Schema.Struct({
-      defaultBranch: Schema.optionalKey(Schema.NonEmptyString),
-      lintGates: Schema.optionalKey(LintGates),
-    }),
+  Schema.makeFilter(
+    (selected) => {
+      const missing = UNCONDITIONAL.filter((bin) => !selected.includes(bin));
+      if (missing.length === 0) return true;
+      const verb = missing.length === 1 ? "applies" : "apply";
+      return `checks-lint must run ${missing.join(", ")}, which ${verb} to ${EVERY_REPOSITORY}`;
+    },
+    { toJsonSchema: () => ({ allOf: UNCONDITIONAL.map((bin) => ({ contains: { const: bin } })) }) },
   ),
-});
+);
 
 export function selectedGates(lintGates: typeof LintGates.Type | undefined): readonly KitGate[] {
   return lintGates === undefined ? KIT_GATES : KIT_GATES.filter((gate) => lintGates.includes(gate.bin));

package/scripts/lint.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env bun
 import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { DEFAULT_BRANCH, LintWiring, selectedGates, type KitGate } from "./gates.ts";
+import { DEFAULT_BRANCH, selectedGates, type KitGate } from "./gates.ts";
 import { git } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
+import { readQuality } from "./quality-file.ts";
 
 type Range = {
   readonly refs: readonly [tip: string] | readonly [base: string, head: string];
@@ -20,10 +21,6 @@ class GatesUndecided extends Schema.TaggedError<GatesUndecided>()("GatesUndecide
   message: Schema.String,
 }) {}
 
-class WiringUnreadable extends Schema.TaggedError<WiringUnreadable>()("WiringUnreadable", {
-  message: Schema.String,
-}) {}
-
 const NAME = "checks-lint";
 const USAGE = "usage: lint.ts [<base-ref> <head-ref>]";
 const PULL_REQUEST_EVENT = "pull_request";
@@ -56,16 +53,9 @@ const pullRequestEnds = Effect.fn("pullRequestEnds")(function* (eventPath: strin
   };
 });
 
-const decodeWiring = Schema.decodeUnknownEffect(Schema.fromJsonString(LintWiring));
-
 const readWiring = Effect.gen(function* () {
-  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const manifest = (yield* Path.Path).join(root, "package.json");
-  const { ciWiring } = yield* (yield* FileSystem.FileSystem).readFileString(manifest).pipe(
-    Effect.flatMap(decodeWiring),
-    Effect.mapError((cause) => new WiringUnreadable({ message: `cannot read ciWiring from ${manifest}: ${cause.message}` })),
-  );
-  return { defaultBranch: ciWiring?.defaultBranch ?? DEFAULT_BRANCH, lintGates: ciWiring?.lintGates };
+  const { source, quality } = yield* readQuality((yield* git(["rev-parse", "--show-toplevel"])).trim());
+  return { source, defaultBranch: quality.defaultBranch ?? DEFAULT_BRANCH, lintGates: quality.gates?.lint };
 });
 
 const originEnds = (defaultBranch: string) =>
@@ -142,7 +132,7 @@ const runGate = Effect.fn("runGate")(function* (gate: KitGate, range: Range) {
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const script = (yield* Path.Path).join(import.meta.dir, gate.script);
   const program = gate.script.endsWith(".sh") ? "sh" : process.execPath;
-  const args = gate.reads === "range" ? [script, ...range.refs] : [script];
+  const args = gate.reads === "range" ? [script, ...range.refs] : [script, ...(gate.args ?? [])];
   const exitCode = yield* spawner
     .exitCode(ChildProcess.make(program, args, { stdin: "ignore", stdout: "inherit", stderr: "inherit" }))
     .pipe(
@@ -154,12 +144,12 @@ const runGate = Effect.fn("runGate")(function* (gate: KitGate, range: Range) {
 });
 
 const lint = Effect.gen(function* () {
-  const { defaultBranch, lintGates } = yield* readWiring;
+  const { source, defaultBranch, lintGates } = yield* readWiring;
   const range = yield* resolveRange(process.argv.slice(2), defaultBranch);
   yield* Console.log(`${NAME}: ${describe(range)} from ${range.source}`);
   const gates = selectedGates(lintGates);
   if (lintGates !== undefined) {
-    yield* Console.log(`${NAME}: ciWiring.lintGates selects ${gates.map((gate) => gate.bin).join(", ")}`);
+    yield* Console.log(`${NAME}: ${source} selects ${gates.map((gate) => gate.bin).join(", ")}`);
   }
 
   const verdicts = yield* Effect.forEach(gates, (gate) => runGate(gate, range));

package/scripts/quality-file.ts

@@ -0,0 +1,188 @@
+import { Console, Effect, FileSystem, JsonSchema, Path, Schema } from "effect";
+import { LintGates, QUALITY_FILE } from "./gates.ts";
+
+const SEGMENT = String.raw`(?!\.\.?(?:/|$))(?:\*\*|(?:[\w.@+-]|\*(?!\*))+)`;
+
+const FILE = String.raw`(?:[\w.@+-]|\*(?!\*))*\.\w+`;
+
+// oxlint matches a glob without a slash against a file's name at any depth, where tsc, the
+// language service and git match it at the root alone, so a glob names a directory first.
+// The language service drops an include ending in ** and oxlint reads a bare name as a file,
+// so a glob ends in a file name with an extension.
+const PathGlob = Schema.String.check(
+  Schema.isPattern(new RegExp(`^${SEGMENT}(?:/${SEGMENT})*/${FILE}$`), {
+    expected:
+      "a glob from the repository root such as src/**/*.ts: a directory first, * within a segment, ** as a whole one, a file name with an extension last",
+  }),
+).annotate({
+  identifier: "PathGlob",
+  description:
+    "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 Command = Schema.NonEmptyString.annotate({ identifier: "Command" });
+
+const RuleName = Schema.String.check(
+  Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { expected: "a Rule name in kebab case" }),
+).annotate({ identifier: "RuleName" });
+
+export const Identity = Schema.Struct({ name: Schema.NonEmptyString, email: Schema.NonEmptyString }).annotate({
+  identifier: "Identity",
+});
+export type Identity = typeof Identity.Type;
+
+const CommitIdentity = Schema.Struct({
+  authors: Schema.NonEmptyArray(Identity).annotate({
+    description: "The identities allowed to author and commit, in place of the kit's default owner",
+  }),
+});
+
+const Gates = Schema.Struct({
+  ci: Schema.optionalKey(
+    Schema.NonEmptyArray(Command).annotate({
+      description: "The commands CI runs on every pull request to the default branch, each one plain command",
+    }),
+  ),
+  scheduled: Schema.optionalKey(
+    Schema.Array(Command).annotate({ description: "The commands a cron-scheduled workflow runs" }),
+  ),
+  lint: Schema.optionalKey(LintGates),
+});
+
+const EffectSources = Schema.Struct({
+  paths: Schema.NonEmptyArray(PathGlob).annotate({
+    description: "Where source is written in Effect, held to the Effect rules of oxlint and the language service",
+  }),
+  exempt: Schema.optionalKey(
+    Schema.Array(PathGlob).annotate({ description: "Files under paths the Effect rules pass over" }),
+  ),
+});
+
+const Sources = Schema.Struct({
+  production: Schema.optionalKey(
+    Schema.Array(PathGlob).annotate({ description: "The source the repository ships, as against tests and tooling" }),
+  ),
+  effect: Schema.optionalKey(EffectSources),
+});
+
+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" })),
+}).check(
+  Schema.makeFilter(({ on = [], off = [] }) => {
+    const both = on.filter((rule) => off.includes(rule));
+    return both.length === 0 || `switches ${both.join(", ")} both on and off`;
+  }),
+);
+
+export const Quality = Schema.Struct({
+  $schema: Schema.optionalKey(Schema.String),
+  defaultBranch: Schema.optionalKey(
+    Schema.NonEmptyString.annotate({ description: "The branch pull requests merge into; main when absent" }),
+  ),
+  gates: Schema.optionalKey(Gates),
+  commitIdentity: Schema.optionalKey(CommitIdentity),
+  sources: Schema.optionalKey(Sources),
+  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",
+});
+export type Quality = typeof Quality.Type;
+
+const LegacyManifest = Schema.Struct({
+  ciWiring: Schema.optionalKey(
+    Schema.Struct({
+      gates: Schema.optionalKey(Schema.NonEmptyArray(Command)),
+      scheduled: Schema.optionalKey(Schema.Array(Command)),
+      lintGates: Schema.optionalKey(LintGates),
+      defaultBranch: Schema.optionalKey(Schema.NonEmptyString),
+    }),
+  ),
+  commitIdentity: Schema.optionalKey(CommitIdentity),
+});
+type LegacyManifest = typeof LegacyManifest.Type;
+
+const LEGACY_KEYS = ["ciWiring", "commitIdentity"] as const;
+
+export type LegacyDeclaration = {
+  readonly keys: readonly (typeof LEGACY_KEYS)[number][];
+  readonly quality: Quality;
+};
+
+export class QualityUnreadable extends Schema.TaggedError<QualityUnreadable>()("QualityUnreadable", {
+  message: Schema.String,
+}) {}
+
+const MANIFEST = "package.json";
+
+export type Declared = {
+  readonly source: typeof QUALITY_FILE | typeof MANIFEST;
+  readonly quality: Quality;
+};
+
+const decodeQualityJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Quality), { onExcessProperty: "error" });
+const decodeManifestJson = Schema.decodeUnknownEffect(Schema.fromJsonString(LegacyManifest));
+
+export const decodeQuality = (text: string, source: string): Effect.Effect<Quality, QualityUnreadable> =>
+  decodeQualityJson(text).pipe(Effect.mapError((cause) => new QualityUnreadable({ message: `${source}: ${cause.message}` })));
+
+function fromLegacy({ ciWiring, commitIdentity }: LegacyManifest): Quality {
+  const gates = {
+    ...(ciWiring?.gates === undefined ? {} : { ci: ciWiring.gates }),
+    ...(ciWiring?.scheduled === undefined ? {} : { scheduled: ciWiring.scheduled }),
+    ...(ciWiring?.lintGates === undefined ? {} : { lint: ciWiring.lintGates }),
+  };
+  return {
+    ...(ciWiring?.defaultBranch === undefined ? {} : { defaultBranch: ciWiring.defaultBranch }),
+    ...(Object.keys(gates).length === 0 ? {} : { gates }),
+    ...(commitIdentity === undefined ? {} : { commitIdentity }),
+  };
+}
+
+export const decodeManifest = (text: string, source: string): Effect.Effect<LegacyDeclaration, QualityUnreadable> =>
+  decodeManifestJson(text).pipe(
+    Effect.map((manifest) => ({
+      keys: LEGACY_KEYS.filter((key) => manifest[key] !== undefined),
+      quality: fromLegacy(manifest),
+    })),
+    Effect.mapError((cause) => new QualityUnreadable({ message: `${source}: ${cause.message}` })),
+  );
+
+const UNDECLARED: LegacyDeclaration = { keys: [], quality: {} };
+
+export const readQuality = Effect.fn("readQuality")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const read = (file: string) =>
+    fs
+      .readFileString(path.join(root, file))
+      .pipe(Effect.mapError((cause) => new QualityUnreadable({ message: `cannot read ${file}: ${cause.message}` })));
+
+  const legacy = (yield* fs.exists(path.join(root, MANIFEST)))
+    ? yield* decodeManifest(yield* read(MANIFEST), MANIFEST)
+    : UNDECLARED;
+  const keys = legacy.keys.join(" and ");
+  if (yield* fs.exists(path.join(root, QUALITY_FILE))) {
+    if (legacy.keys.length > 0) {
+      return yield* new QualityUnreadable({
+        message: `${MANIFEST} still sets ${keys}, which ${QUALITY_FILE} replaces; move what it holds there`,
+      });
+    }
+    return { source: QUALITY_FILE, quality: yield* decodeQuality(yield* read(QUALITY_FILE), QUALITY_FILE) } satisfies Declared;
+  }
+  if (legacy.keys.length > 0) {
+    const them = legacy.keys.length === 1 ? "it" : "them";
+    yield* Console.error(`${MANIFEST} sets ${keys}, which a later minor release stops reading; move ${them} into ${QUALITY_FILE}`);
+  }
+  return { source: MANIFEST, quality: legacy.quality } satisfies Declared;
+});
+
+export function renderJson(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+export function qualityJsonSchema(): JsonSchema.JsonSchema {
+  const { schema, definitions } = Schema.toJsonSchemaDocument(Quality, { onExcessProperty: "error" });
+  return { $schema: JsonSchema.META_SCHEMA_URI_DRAFT_2020_12, ...schema, $defs: definitions };
+}

package/scripts/quality.ts

@@ -0,0 +1,172 @@
+#!/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 problems: string[] = [];
+  for (const glob of quality.sources?.effect?.paths ?? []) {
+    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`);
+  }
+  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);