@avi2dg/checks 0.10.0 → 0.12.0

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,9 @@ 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 },
+  { bin: "checks-size-budget", script: "size-budget.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-feature-owners", script: "feature-owners.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
 ] as const satisfies readonly KitGate[];
 
 const UNCONDITIONAL = KIT_GATES.filter((gate) => gate.appliesTo === EVERY_REPOSITORY).map((gate) => gate.bin);
@@ -39,22 +47,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/git.ts

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

package/scripts/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,298 @@
+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 LITERAL_SEGMENT = String.raw`(?!\.\.?(?:/|$))[\w.@+-]+`;
+
+const DirectoryPath = Schema.String.check(
+  Schema.isPattern(new RegExp(`^${LITERAL_SEGMENT}(?:/${LITERAL_SEGMENT})*$`), {
+    expected: "a directory from the repository root such as src/billing, with no glob and no trailing slash",
+  }),
+).annotate({ identifier: "DirectoryPath" });
+
+const FilePath = Schema.String.check(
+  Schema.isPattern(new RegExp(`^(?:${LITERAL_SEGMENT}/)*[\\w.@+-]*\\.\\w+$`), {
+    expected: "a file from the repository root such as src/billing/index.ts, with no glob",
+  }),
+).annotate({ identifier: "FilePath" });
+
+export const PROOF_DIRECTORY = "tests/e2e/";
+
+const ProofPath = Schema.String.check(
+  Schema.isPattern(new RegExp(`^${PROOF_DIRECTORY}(?:${LITERAL_SEGMENT}/)*[\\w.@+-]+\\.test\\.tsx?$`), {
+    expected: `a test file under ${PROOF_DIRECTORY} such as ${PROOF_DIRECTORY}billing.test.ts`,
+  }),
+).annotate({ identifier: "ProofPath" });
+
+const Command = Schema.NonEmptyString.annotate({ identifier: "Command" });
+
+const RuleName = Schema.String.check(
+  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 LineBudget = Schema.Int.check(Schema.isGreaterThan(0));
+
+const Size = Schema.Struct({
+  fileLines: LineBudget.annotate({ description: "The most lines a file may hold, blank and comment lines counted" }),
+  functionLines: LineBudget.annotate({
+    description: "The most lines a function may span, blank and comment lines counted",
+  }),
+  applies: Schema.Literals(["changed", "all"]).annotate({
+    description:
+      "Which production files the budget holds: changed, the ones a range adds or changes; all, every one. The rest are reported as advisory",
+  }),
+});
+
+const Feature = Schema.Struct({
+  name: Schema.String.check(
+    Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { expected: "a feature name in kebab case" }),
+  ).annotate({ description: "The owner the dependency rule and the change signal name" }),
+  root: DirectoryPath.annotate({ description: "The directory the feature owns" }),
+  entries: Schema.NonEmptyArray(FilePath).annotate({
+    description: "The files under root that code outside it imports the feature through",
+  }),
+  allowFrom: Schema.optionalKey(
+    Schema.Array(PathGlob).annotate({
+      description: "Files outside root that may import past its entries, such as a CLI or a harness; tests/ always may",
+    }),
+  ),
+  proof: ProofPath.annotate({ description: "The end-to-end test that imports one of entries" }),
+}).check(
+  Schema.makeFilter(({ root, entries }) => {
+    const outside = entries.filter((entry) => !entry.startsWith(`${root}/`));
+    return outside.length === 0 || `lists ${outside.join(", ")} among its entries, outside its root ${root}`;
+  }),
+);
+export type Feature = typeof Feature.Type;
+
+function nests(outer: string, inner: string): boolean {
+  return outer === inner || inner.startsWith(`${outer}/`);
+}
+
+const Features = Schema.Array(Feature).check(
+  Schema.makeFilter((features) => {
+    const names = features.map((feature) => feature.name);
+    const repeated = names.filter((name, index) => names.indexOf(name) !== index);
+    if (repeated.length > 0) return `names ${[...new Set(repeated)].join(", ")} more than once`;
+    for (const outer of features) {
+      const inner = features.find((other) => other !== outer && nests(outer.root, other.root));
+      if (inner !== undefined) return `gives ${inner.root} to both ${outer.name} and ${inner.name}`;
+    }
+    return true;
+  }),
+);
+
+const AgentRules = Schema.Struct({
+  on: Schema.optionalKey(Schema.Array(RuleName).annotate({ description: "Catalogued Rules switched on here" })),
+  off: Schema.optionalKey(Schema.Array(RuleName).annotate({ description: "Catalogued Rules switched off here" })),
+}).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),
+  size: Schema.optionalKey(
+    Size.annotate({ description: "The line budget oxlint holds production files to, read by checks-size-budget" }),
+  ),
+  features: Schema.optionalKey(
+    Features.annotate({
+      description: "The feature owners dependency-cruiser holds to their entries and checks-feature-owners maps a change to",
+    }),
+  ),
+  changeSignal: Schema.optionalKey(
+    Schema.Literal("advisory").annotate({
+      description: "Report which feature owners a change touches, without failing on it",
+    }),
+  ),
+  agentRules: Schema.optionalKey(AgentRules),
+})
+  .annotate({
+    title: QUALITY_FILE,
+    description: "What a repository has opted into from @avi2dg/checks, read by its bins and agent Rule selection",
+  })
+  .check(
+    Schema.makeFilter(
+      ({ size, sources }) =>
+        size === undefined || (sources?.production ?? []).length > 0 || "declares size, which holds nothing without sources.production",
+      {
+        toJsonSchema: () => ({
+          if: { required: ["size"] },
+          then: { required: ["sources"], properties: { sources: { required: ["production"], properties: { production: { minItems: 1 } } } } },
+        }),
+      },
+    ),
+    Schema.makeFilter(
+      ({ changeSignal, features = [] }) =>
+        changeSignal === undefined || features.length > 0 || "declares changeSignal, which maps a change to no owner without features",
+      {
+        toJsonSchema: () => ({
+          if: { required: ["changeSignal"] },
+          then: { required: ["features"], properties: { features: { minItems: 1 } } },
+        }),
+      },
+    ),
+  );
+export type Quality = typeof Quality.Type;
+
+const LegacyManifest = Schema.Struct({
+  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 };
+}