@avi2dg/checks 0.10.0 → 0.12.0

package/quality.schema.json

@@ -0,0 +1,339 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "defaultBranch": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The branch pull requests merge into; main when absent"
+    },
+    "gates": {
+      "type": "object",
+      "properties": {
+        "ci": {
+          "type": "array",
+          "prefixItems": [
+            {
+              "$ref": "#/$defs/Command"
+            }
+          ],
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/Command"
+          },
+          "description": "The commands CI runs on every pull request to the default branch, each one plain command"
+        },
+        "scheduled": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Command"
+          },
+          "description": "The commands a cron-scheduled workflow runs"
+        },
+        "lint": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "checks-lint-coverage",
+              "checks-test-layout",
+              "checks-commit-identity",
+              "checks-comment-gate",
+              "checks-suppressions-ratchet",
+              "checks-ci-wiring",
+              "checks-quality",
+              "checks-size-budget",
+              "checks-feature-owners"
+            ]
+          },
+          "allOf": [
+            {
+              "contains": {
+                "const": "checks-commit-identity"
+              }
+            },
+            {
+              "contains": {
+                "const": "checks-comment-gate"
+              }
+            },
+            {
+              "contains": {
+                "const": "checks-suppressions-ratchet"
+              }
+            },
+            {
+              "contains": {
+                "const": "checks-ci-wiring"
+              }
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "commitIdentity": {
+      "type": "object",
+      "properties": {
+        "authors": {
+          "type": "array",
+          "prefixItems": [
+            {
+              "$ref": "#/$defs/Identity"
+            }
+          ],
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/Identity"
+          },
+          "description": "The identities allowed to author and commit, in place of the kit's default owner"
+        }
+      },
+      "required": [
+        "authors"
+      ],
+      "additionalProperties": false
+    },
+    "sources": {
+      "type": "object",
+      "properties": {
+        "production": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/PathGlob"
+          },
+          "description": "The source the repository ships, as against tests and tooling"
+        },
+        "effect": {
+          "type": "object",
+          "properties": {
+            "paths": {
+              "type": "array",
+              "prefixItems": [
+                {
+                  "$ref": "#/$defs/PathGlob"
+                }
+              ],
+              "minItems": 1,
+              "items": {
+                "$ref": "#/$defs/PathGlob"
+              },
+              "description": "Where source is written in Effect, held to the Effect rules of oxlint and the language service"
+            },
+            "exempt": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/PathGlob"
+              },
+              "description": "Files under paths the Effect rules pass over"
+            }
+          },
+          "required": [
+            "paths"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "size": {
+      "type": "object",
+      "properties": {
+        "fileLines": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "description": "The most lines a file may hold, blank and comment lines counted"
+        },
+        "functionLines": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "description": "The most lines a function may span, blank and comment lines counted"
+        },
+        "applies": {
+          "type": "string",
+          "enum": [
+            "changed",
+            "all"
+          ],
+          "description": "Which production files the budget holds: changed, the ones a range adds or changes; all, every one. The rest are reported as advisory"
+        }
+      },
+      "required": [
+        "fileLines",
+        "functionLines",
+        "applies"
+      ],
+      "additionalProperties": false,
+      "description": "The line budget oxlint holds production files to, read by checks-size-budget"
+    },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "The owner the dependency rule and the change signal name"
+          },
+          "root": {
+            "$ref": "#/$defs/DirectoryPath"
+          },
+          "entries": {
+            "type": "array",
+            "prefixItems": [
+              {
+                "$ref": "#/$defs/FilePath"
+              }
+            ],
+            "minItems": 1,
+            "items": {
+              "$ref": "#/$defs/FilePath"
+            },
+            "description": "The files under root that code outside it imports the feature through"
+          },
+          "allowFrom": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/PathGlob"
+            },
+            "description": "Files outside root that may import past its entries, such as a CLI or a harness; tests/ always may"
+          },
+          "proof": {
+            "$ref": "#/$defs/ProofPath"
+          }
+        },
+        "required": [
+          "name",
+          "root",
+          "entries",
+          "proof"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "changeSignal": {
+      "type": "string",
+      "enum": [
+        "advisory"
+      ],
+      "description": "Report which feature owners a change touches, without failing on it"
+    },
+    "agentRules": {
+      "type": "object",
+      "properties": {
+        "on": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/RuleName"
+          },
+          "description": "Catalogued Rules switched on here"
+        },
+        "off": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/RuleName"
+          },
+          "description": "Catalogued Rules switched off here"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "title": "quality.json",
+  "description": "What a repository has opted into from @avi2dg/checks, read by its bins and agent Rule selection",
+  "allOf": [
+    {
+      "if": {
+        "required": [
+          "size"
+        ]
+      },
+      "then": {
+        "required": [
+          "sources"
+        ],
+        "properties": {
+          "sources": {
+            "required": [
+              "production"
+            ],
+            "properties": {
+              "production": {
+                "minItems": 1
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "required": [
+          "changeSignal"
+        ]
+      },
+      "then": {
+        "required": [
+          "features"
+        ],
+        "properties": {
+          "features": {
+            "minItems": 1
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "Command": {
+      "type": "string",
+      "minLength": 1
+    },
+    "Identity": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "email": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "name",
+        "email"
+      ],
+      "additionalProperties": false
+    },
+    "PathGlob": {
+      "type": "string",
+      "pattern": "^(?!\\.\\.?(?:\\/|$))(?:\\*\\*|(?:[\\w.@+-]|\\*(?!\\*))+)(?:\\/(?!\\.\\.?(?:\\/|$))(?:\\*\\*|(?:[\\w.@+-]|\\*(?!\\*))+))*\\/(?:[\\w.@+-]|\\*(?!\\*))*\\.\\w+$",
+      "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 ./"
+    },
+    "DirectoryPath": {
+      "type": "string",
+      "pattern": "^(?!\\.\\.?(?:\\/|$))[\\w.@+-]+(?:\\/(?!\\.\\.?(?:\\/|$))[\\w.@+-]+)*$",
+      "description": "The directory the feature owns"
+    },
+    "FilePath": {
+      "type": "string",
+      "pattern": "^(?:(?!\\.\\.?(?:\\/|$))[\\w.@+-]+\\/)*[\\w.@+-]*\\.\\w+$"
+    },
+    "ProofPath": {
+      "type": "string",
+      "pattern": "^tests\\/e2e\\/(?:(?!\\.\\.?(?:\\/|$))[\\w.@+-]+\\/)*[\\w.@+-]+\\.test\\.tsx?$",
+      "description": "The end-to-end test that imports one of entries"
+    },
+    "RuleName": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    }
+  }
+}

package/scripts/ci-wiring.ts

@@ -2,15 +2,8 @@
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { git } from "./git.ts";
 import { runMain } from "./main.ts";
-import {
-  DEFAULT_BRANCH,
-  ENTRY_POINT,
-  EVERY_REPOSITORY,
-  KIT_GATES,
-  LintWiring,
-  selectedGates,
-  type KitGate,
-} from "./gates.ts";
+import { DEFAULT_BRANCH, ENTRY_POINT, EVERY_REPOSITORY, KIT_GATES, QUALITY_FILE, selectedGates, type KitGate } from "./gates.ts";
+import { readQuality, type Quality } from "./quality-file.ts";
 
 export type Command = readonly string[];
 
@@ -303,8 +296,6 @@ function gapLines(gaps: readonly Gap[]): readonly string[] {
   return lines;
 }
 
-const decodeWiring = Schema.decodeUnknownEffect(LintWiring);
-
 export function formatReport(declaration: Declaration, gaps: readonly Gap[]): string {
   const target = `pull requests to ${declaration.defaultBranch}`;
   if (gaps.length === 0) return `ci-wiring: ${declaration.gates.length} gate(s) run on ${target}`;
@@ -318,13 +309,13 @@ export function formatScheduledReport(declaration: Declaration, gaps: readonly G
 }
 
 const plainCommands = Effect.fnUntraced(function* (
-  listed: readonly unknown[],
+  listed: readonly string[],
   subject: string,
 ): Effect.fn.Return<readonly Gate[], WiringError> {
   const gates: Gate[] = [];
   for (const command of listed) {
-    const words = typeof command === "string" ? plainCommand(command) : undefined;
-    if (typeof command !== "string" || words === undefined) {
+    const words = plainCommand(command);
+    if (words === undefined) {
       return yield* new WiringError({ message: `${subject} ${JSON.stringify(command)} is not one plain command` });
     }
     gates.push({ command, words });
@@ -333,28 +324,17 @@ const plainCommands = Effect.fnUntraced(function* (
 });
 
 export const parseDeclaration = Effect.fnUntraced(function* (
-  manifest: unknown,
+  { defaultBranch, gates: declared }: Quality,
   source: string,
 ): Effect.fn.Return<Declaration, WiringError> {
-  const configured = isRecord(manifest) && isRecord(manifest["ciWiring"]) ? manifest["ciWiring"] : {};
-  const listed: unknown = configured["gates"];
-  if (!Array.isArray(listed) || listed.length === 0) {
-    return yield* new WiringError({ message: `${source} sets no ciWiring.gates, a non-empty array of commands` });
-  }
-  const gates = yield* plainCommands(listed, `${source} ciWiring gate`);
-  const scheduledListed = configured["scheduled"] ?? [];
-  if (!Array.isArray(scheduledListed)) {
-    return yield* new WiringError({ message: `${source} ciWiring.scheduled is not an array of commands` });
+  if (declared?.ci === undefined) {
+    return yield* new WiringError({ message: `${QUALITY_FILE} declares no gates.ci, a non-empty array of commands` });
   }
-  const scheduled = yield* plainCommands(scheduledListed, `${source} ciWiring scheduled command`);
-  const { ciWiring } = yield* decodeWiring(manifest).pipe(
-    Effect.mapError((cause) => new WiringError({ message: `${source}: ${cause.message}` })),
-  );
   return {
-    gates,
-    scheduled,
-    defaultBranch: ciWiring?.defaultBranch ?? DEFAULT_BRANCH,
-    lintGates: selectedGates(ciWiring?.lintGates),
+    gates: yield* plainCommands(declared.ci, `${source} gate`),
+    scheduled: yield* plainCommands(declared.scheduled ?? [], `${source} scheduled command`),
+    defaultBranch: defaultBranch ?? DEFAULT_BRANCH,
+    lintGates: selectedGates(declared.lint),
   };
 });
 
@@ -383,10 +363,10 @@ export function formatOmissions(lintGates: readonly KitGate[], omissions: readon
   if (omitted.length === 0) return undefined;
   if (omissions.length === 0) {
     const bins = omitted.map((gate) => gate.bin).join(", ");
-    return `ci-wiring: ciWiring.lintGates leaves out ${bins}, none of which this repository's contents make applicable`;
+    return `ci-wiring: ${QUALITY_FILE} gates.lint leaves out ${bins}, none of which this repository's contents make applicable`;
   }
   return [
-    `ci-wiring: ciWiring.lintGates leaves out ${omissions.length} gate(s) this repository's contents make applicable:`,
+    `ci-wiring: ${QUALITY_FILE} gates.lint leaves out ${omissions.length} gate(s) this repository's contents make applicable:`,
     ...omissions.map(({ gate, content, files }) => `  ${gate}: the repository tracks ${content} (${sample(files)})`),
   ].join("\n");
 }
@@ -397,16 +377,9 @@ export const parseWorkflow = (path: string, text: string): Effect.Effect<Workflo
     catch: (error) => new WiringError({ message: `cannot parse ${path}: ${String(error)}` }),
   });
 
-const parseJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));
-
 export const readDeclaration = Effect.fn("readDeclaration")(function* (root: string) {
-  const fs = yield* FileSystem.FileSystem;
-  const path = (yield* Path.Path).join(root, "package.json");
-  const manifest = yield* fs.readFileString(path).pipe(
-    Effect.flatMap(parseJson),
-    Effect.mapError((cause) => new WiringError({ message: `cannot read ${path} as JSON: ${cause.message}` })),
-  );
-  return yield* parseDeclaration(manifest, path);
+  const { source, quality } = yield* readQuality(root);
+  return yield* parseDeclaration(quality, source);
 });
 
 export const readWorkflows = Effect.fn("readWorkflows")(function* (root: string) {

package/scripts/commit-identity.ts

@@ -1,10 +1,8 @@
 #!/usr/bin/env bun
-import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { Console, Effect, Schema } from "effect";
 import { git } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
-
-const Identity = Schema.Struct({ name: Schema.String, email: Schema.String });
-type Identity = typeof Identity.Type;
+import { readQuality, type Identity } from "./quality-file.ts";
 
 type Commit = {
   readonly sha: string;
@@ -32,16 +30,6 @@ const RECORD = "\u001e";
 
 const USAGE = "usage: commit-identity.ts <ref> | <base-ref> <head-ref>";
 
-const Manifest = Schema.Struct({
-  commitIdentity: Schema.optional(Schema.Struct({ authors: Schema.NonEmptyArray(Identity) })),
-});
-const parseJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));
-const decodeManifest = Schema.decodeUnknownEffect(Manifest);
-
-class InvalidAllowlist extends Schema.TaggedError<InvalidAllowlist>()("InvalidAllowlist", {
-  message: Schema.String,
-}) {}
-
 class UnreadableLog extends Schema.TaggedError<UnreadableLog>()("UnreadableLog", {
   message: Schema.String,
 }) {}
@@ -51,25 +39,8 @@ function render(identity: Identity): string {
 }
 
 const allowedAuthors = Effect.gen(function* () {
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const manifestPath = path.join(root, "package.json");
-  if (!(yield* fs.exists(manifestPath))) return DEFAULT_AUTHORS;
-
-  const parsed = yield* fs.readFileString(manifestPath).pipe(
-    Effect.flatMap(parseJson),
-    Effect.mapError((cause) => new InvalidAllowlist({ message: `cannot read ${manifestPath} as JSON: ${cause.message}` })),
-  );
-  const manifest = yield* decodeManifest(parsed).pipe(
-    Effect.mapError(
-      () =>
-        new InvalidAllowlist({
-          message: `${manifestPath} sets commitIdentity without a non-empty authors array of {name, email}`,
-        }),
-    ),
-  );
-  return manifest.commitIdentity?.authors ?? DEFAULT_AUTHORS;
+  const { quality } = yield* readQuality((yield* git(["rev-parse", "--show-toplevel"])).trim());
+  return quality.commitIdentity?.authors ?? DEFAULT_AUTHORS;
 });
 
 const readCommits = Effect.fn("readCommits")(function* (revisions: readonly string[]) {

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