@avi2dg/checks 0.10.0 → 0.11.0

package/quality.schema.json

@@ -0,0 +1,197 @@
+{
+  "$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"
+            ]
+          },
+          "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
+    },
+    "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",
+  "$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 ./"
+    },
+    "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/gates.ts

@@ -14,6 +14,7 @@ export const EVERY_REPOSITORY = "every repository";
 
 export type KitGate = Program & {
   readonly reads: "tree" | "range";
+  readonly args?: readonly string[];
   readonly appliesTo: typeof EVERY_REPOSITORY | TrackedContent;
 };
 
@@ -23,8 +24,12 @@ 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 },
@@ -32,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);
@@ -39,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 };
+}