@avi2dg/checks 0.24.1 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -13,50 +13,49 @@
   "type": "module",
   "files": [
     "CHANGELOG.md",
-    "CONTRIBUTING.md",
     "docs/configs/",
     "docs/design.md",
     "docs/gates/",
     "bunfig.toml",
     "commitlint.config.js",
     "dependency-cruiser.config.js",
-    "scripts/lint-coverage.sh",
-    "scripts/main.ts",
-    "scripts/git.ts",
-    "scripts/gates.ts",
-    "scripts/lint.ts",
-    "scripts/changelog.ts",
-    "scripts/changelog-write.ts",
-    "scripts/release-notes.ts",
-    "scripts/release-report.ts",
-    "scripts/test-layout.ts",
-    "scripts/test.ts",
-    "scripts/test-skips.ts",
-    "scripts/swc.ts",
-    "scripts/test-report.ts",
-    "scripts/flake.ts",
-    "scripts/commit-identity.ts",
-    "scripts/mutation-compare.ts",
-    "scripts/subsumed-tests.ts",
-    "scripts/ci-wiring.ts",
-    "scripts/shell-command.ts",
-    "scripts/comment-matchers.ts",
-    "scripts/prose-matchers.ts",
-    "scripts/comments.ts",
-    "scripts/comment-gate.ts",
-    "scripts/suppressions-ratchet.ts",
-    "scripts/backtest.ts",
-    "scripts/range-gate.ts",
-    "scripts/repetition.ts",
-    "scripts/quarantine-clock.ts",
-    "scripts/docs.ts",
-    "scripts/vendor.ts",
-    "scripts/vendor-args.ts",
-    "scripts/doc-outline.ts",
-    "scripts/doc-rules.ts",
-    "scripts/doc-references.ts",
-    "scripts/doc-snapshot.ts",
-    "scripts/doc-templates.ts",
+    "knip-base.json",
+    "src/quality/lint-coverage.sh",
+    "src/core/main.ts",
+    "src/core/git.ts",
+    "src/core/gates.ts",
+    "src/core/lint.ts",
+    "src/delivery/changelog.ts",
+    "src/delivery/changelog-write.ts",
+    "src/delivery/release-notes.ts",
+    "src/delivery/release-report.ts",
+    "src/testing/test-layout.ts",
+    "src/testing/test.ts",
+    "src/testing/test-skips.ts",
+    "src/core/swc.ts",
+    "src/testing/test-report.ts",
+    "src/testing/flake.ts",
+    "src/delivery/commit-identity.ts",
+    "src/testing/mutation-compare.ts",
+    "src/testing/subsumed-tests.ts",
+    "src/delivery/ci-wiring.ts",
+    "src/delivery/shell-command.ts",
+    "src/quality/comment-matchers.ts",
+    "src/docs/prose-matchers.ts",
+    "src/quality/comments.ts",
+    "src/quality/comment-gate.ts",
+    "src/complexity/suppressions-ratchet.ts",
+    "src/complexity/repetition.ts",
+    "src/complexity/unused.ts",
+    "src/testing/quarantine-clock.ts",
+    "src/docs/docs.ts",
+    "src/dependencies/vendor.ts",
+    "src/dependencies/vendor-args.ts",
+    "src/docs/doc-outline.ts",
+    "src/docs/doc-rules.ts",
+    "src/docs/doc-references.ts",
+    "src/docs/doc-snapshot.ts",
+    "src/docs/doc-templates.ts",
     "templates/",
     "presets/effect.oxlint.json",
     "presets/effect.language-service.json",
@@ -67,77 +66,41 @@
     "dist/readability/index.js"
   ],
   "exports": {
-    "./bunfig.toml": "./bunfig.toml",
-    "./commitlint.config.js": "./commitlint.config.js",
     "./dependency-cruiser.config.js": "./dependency-cruiser.config.js",
-    "./scripts/lint-coverage.sh": "./scripts/lint-coverage.sh",
-    "./scripts/lint.ts": "./scripts/lint.ts",
-    "./scripts/changelog.ts": "./scripts/changelog.ts",
-    "./scripts/changelog-write.ts": "./scripts/changelog-write.ts",
-    "./scripts/release-notes.ts": "./scripts/release-notes.ts",
-    "./scripts/release-report.ts": "./scripts/release-report.ts",
-    "./scripts/test-layout.ts": "./scripts/test-layout.ts",
-    "./scripts/test.ts": "./scripts/test.ts",
-    "./scripts/test-skips.ts": "./scripts/test-skips.ts",
-    "./scripts/flake.ts": "./scripts/flake.ts",
-    "./scripts/commit-identity.ts": "./scripts/commit-identity.ts",
-    "./scripts/mutation-compare.ts": "./scripts/mutation-compare.ts",
-    "./scripts/subsumed-tests.ts": "./scripts/subsumed-tests.ts",
-    "./scripts/ci-wiring.ts": "./scripts/ci-wiring.ts",
-    "./scripts/comment-matchers.ts": "./scripts/comment-matchers.ts",
-    "./scripts/prose-matchers.ts": "./scripts/prose-matchers.ts",
-    "./scripts/comments.ts": "./scripts/comments.ts",
-    "./scripts/comment-gate.ts": "./scripts/comment-gate.ts",
-    "./scripts/suppressions-ratchet.ts": "./scripts/suppressions-ratchet.ts",
-    "./scripts/backtest.ts": "./scripts/backtest.ts",
-    "./scripts/repetition.ts": "./scripts/repetition.ts",
-    "./scripts/quarantine-clock.ts": "./scripts/quarantine-clock.ts",
-    "./scripts/docs.ts": "./scripts/docs.ts",
-    "./scripts/vendor.ts": "./scripts/vendor.ts",
-    "./templates/readme.md": "./templates/readme.md",
-    "./templates/changelog.md": "./templates/changelog.md",
-    "./templates/adr.md": "./templates/adr.md",
-    "./templates/agents.md": "./templates/agents.md",
-    "./templates/claude.md": "./templates/claude.md",
-    "./templates/tutorial.md": "./templates/tutorial.md",
-    "./templates/how-to.md": "./templates/how-to.md",
-    "./templates/reference.md": "./templates/reference.md",
-    "./templates/explanation.md": "./templates/explanation.md",
-    "./presets/effect.oxlint.json": "./presets/effect.oxlint.json",
-    "./presets/effect.language-service.json": "./presets/effect.language-service.json",
-    "./oxlintrc.json": "./oxlintrc.json",
+    "./knip-base.json": "./knip-base.json",
+    "./scripts/test-skips.ts": "./src/testing/test-skips.ts",
+    "./scripts/comment-matchers.ts": "./src/quality/comment-matchers.ts",
+    "./scripts/prose-matchers.ts": "./src/docs/prose-matchers.ts",
     "./stryker.preset.js": "./stryker.preset.js",
-    "./tsconfig.effect.json": "./tsconfig.effect.json",
-    "./dist/effect-channel/index.js": "./dist/effect-channel/index.js",
-    "./dist/readability/index.js": "./dist/readability/index.js"
+    "./tsconfig.effect.json": "./tsconfig.effect.json"
   },
   "bin": {
-    "checks-lint": "scripts/lint.ts",
-    "checks-changelog": "scripts/changelog-write.ts",
-    "checks-release-notes": "scripts/release-notes.ts",
-    "checks-release-report": "scripts/release-report.ts",
-    "checks-lint-coverage": "scripts/lint-coverage.sh",
-    "checks-test-layout": "scripts/test-layout.ts",
-    "checks-test": "scripts/test.ts",
-    "checks-flake": "scripts/flake.ts",
-    "checks-commit-identity": "scripts/commit-identity.ts",
-    "checks-mutation-compare": "scripts/mutation-compare.ts",
-    "checks-subsumed-tests": "scripts/subsumed-tests.ts",
-    "checks-ci-wiring": "scripts/ci-wiring.ts",
-    "checks-comment-gate": "scripts/comment-gate.ts",
-    "checks-suppressions-ratchet": "scripts/suppressions-ratchet.ts",
-    "checks-backtest": "scripts/backtest.ts",
-    "checks-repetition": "scripts/repetition.ts",
-    "checks-quarantine-clock": "scripts/quarantine-clock.ts",
-    "checks-docs": "scripts/docs.ts",
-    "checks-vendor": "scripts/vendor.ts"
+    "checks-lint": "src/core/lint.ts",
+    "checks-changelog": "src/delivery/changelog-write.ts",
+    "checks-release-notes": "src/delivery/release-notes.ts",
+    "checks-release-report": "src/delivery/release-report.ts",
+    "checks-lint-coverage": "src/quality/lint-coverage.sh",
+    "checks-test-layout": "src/testing/test-layout.ts",
+    "checks-test": "src/testing/test.ts",
+    "checks-flake": "src/testing/flake.ts",
+    "checks-commit-identity": "src/delivery/commit-identity.ts",
+    "checks-mutation-compare": "src/testing/mutation-compare.ts",
+    "checks-subsumed-tests": "src/testing/subsumed-tests.ts",
+    "checks-ci-wiring": "src/delivery/ci-wiring.ts",
+    "checks-comment-gate": "src/quality/comment-gate.ts",
+    "checks-suppressions-ratchet": "src/complexity/suppressions-ratchet.ts",
+    "checks-repetition": "src/complexity/repetition.ts",
+    "checks-unused": "src/complexity/unused.ts",
+    "checks-quarantine-clock": "src/testing/quarantine-clock.ts",
+    "checks-docs": "src/docs/docs.ts",
+    "checks-vendor": "src/dependencies/vendor.ts"
   },
   "scripts": {
-    "prepare": "bun scripts/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",
-    "build": "bun build effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build readability/index.ts --outdir dist/readability --target node --format esm && bun scripts/doc-templates-write.ts && bun scripts/changelog-write.ts && bun scripts/doc-blocks-write.ts",
-    "lint": "oxlint --type-aware && bun scripts/lint.ts && depcruise --config .dependency-cruiser.cjs .",
+    "prepare": "bun src/dependencies/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",
+    "build": "bun build src/quality/effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build src/complexity/readability/index.ts --outdir dist/readability --target node --format esm && bun scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
+    "lint": "oxlint --type-aware && bun src/core/lint.ts && depcruise --config .dependency-cruiser.cjs .",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
-    "test": "bun scripts/test.ts"
+    "test": "bun src/testing/test.ts"
   },
   "peerDependencies": {
     "@swc/core": "1.16.2",
@@ -165,6 +128,7 @@
     "@commitlint/cli": "21.2.3",
     "@commitlint/config-conventional": "21.2.3",
     "@effect/platform-bun": "4.0.0-rc.115",
-    "@effect/platform-node-shared": "4.0.0-rc.115"
+    "@effect/platform-node-shared": "4.0.0-rc.115",
+    "knip": "6.38.0"
   }
 }

package/{scripts → src/complexity}/repetition.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import { changedPaths, checkoutFiles, collect, git, pathsAt, rangeFromArgs } from "./git.ts";
-import { runMain } from "./main.ts";
+import { changedPaths, checkoutFiles, collect, git, pathsAt, rangeFromArgs } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 
 export type Fragment = {
   readonly file: string;

package/{scripts → src/complexity}/suppressions-ratchet.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
-import { git, commitOf, parentOrEmptyTree, refArgs } from "./git.ts";
-import { runMain } from "./main.ts";
+import { git, commitOf, parentOrEmptyTree, refArgs } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 
 export const SUPPRESSIONS = "oxlint-suppressions.json";
 

package/src/complexity/unused.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env bun
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { collect, git } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
+
+export type Scan = { readonly tracked: number; readonly files: readonly string[] };
+
+const NAME = "unused";
+const CONFIGS = [
+  ".knip.json",
+  ".knip.jsonc",
+  "knip.json",
+  "knip.jsonc",
+  "knip.js",
+  "knip.ts",
+  "knip.config.js",
+  "knip.config.ts",
+] as const;
+const TYPESCRIPT = ["*.ts", "*.tsx"];
+const JUDGED = /\.tsx?$/;
+
+class UnusedError extends Schema.TaggedError<UnusedError>()("UnusedError", {
+  message: Schema.String,
+}) {}
+
+const decodeKnipReport = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(
+    Schema.Struct({
+      issues: Schema.Array(Schema.Struct({ files: Schema.optional(Schema.Array(Schema.Struct({ name: Schema.String }))) })),
+    }),
+  ),
+);
+
+export const filesOf = Effect.fn("filesOf")(function* (stdout: string) {
+  const { issues } = yield* decodeKnipReport(stdout).pipe(
+    Effect.mapError((cause) => new UnusedError({ message: `knip's JSON report does not decode: ${cause.message}` })),
+  );
+  return issues
+    .flatMap(({ files = [] }) => files.map(({ name }) => name))
+    .filter((file) => JUDGED.test(file))
+    .toSorted();
+});
+
+export function report({ tracked, files }: Scan): string {
+  if (files.length === 0) return `${NAME}: no unreferenced files among ${tracked} tracked .ts/.tsx file(s)`;
+  return [`${NAME}: ${files.length} unreferenced file(s):`, ...files.map((file) => `  ${file}`)].join("\n");
+}
+
+const hasConfig = Effect.fn("hasConfig")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  for (const name of CONFIGS) {
+    if (yield* fs.exists(path.join(root, name))) return true;
+  }
+  const manifest: unknown = yield* fs.readFileString(path.join(root, "package.json")).pipe(
+    Effect.flatMap((text) =>
+      Effect.try({
+        try: () => JSON.parse(text) as unknown,
+        catch: () => new UnusedError({ message: "package.json does not parse as JSON" }),
+      })
+    ),
+  );
+  return typeof manifest === "object" && manifest !== null && "knip" in manifest;
+});
+
+const knip = Effect.fn("knip")(function* () {
+  const path = yield* Path.Path;
+  const main = yield* Effect.try({
+    try: () => new URL("../bin/knip.js", import.meta.resolve("knip")),
+    catch: () => new UnusedError({ message: "cannot resolve knip from the installed kit" }),
+  });
+  return yield* path.fromFileUrl(main);
+});
+
+const unused = Effect.gen(function* () {
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  const tracked = (yield* git(["ls-files", "--", ...TYPESCRIPT], root))
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "");
+  if (tracked.length === 0) return yield* new UnusedError({ message: "no tracked .ts or .tsx files to scan" });
+  if (!(yield* hasConfig(root))) {
+    yield* Console.log(`${NAME}: no knip configuration names entry files, so add one extending the kit's knip-base.json`);
+    return false;
+  }
+  const run = yield* collect(process.execPath, [yield* knip(), "--files", "--reporter", "json"], root).pipe(
+    Effect.mapError((cause) => new UnusedError({ message: `cannot run knip: ${cause.message}` })),
+  );
+  if (run.exitCode !== 0 && run.exitCode !== 1) {
+    return yield* new UnusedError({ message: `knip exits ${run.exitCode}: ${(run.stdout + run.stderr).trim()}` });
+  }
+  const files = yield* filesOf(run.stdout);
+  yield* Console.log(report({ tracked: tracked.length, files }));
+  return files.length === 0;
+});
+
+if (import.meta.main) runMain(NAME, unused);

package/src/core/gates.ts

@@ -0,0 +1,45 @@
+export type Program = {
+  readonly bin: string;
+  readonly script: string;
+};
+
+type TrackedContent = {
+  readonly pathspecs: readonly string[];
+  readonly content: string;
+};
+
+export const EVERY_REPOSITORY = "every repository";
+
+export const VECTORS = ["complexity", "quality", "testing", "docs", "delivery", "dependencies"] as const;
+
+export type Vector = (typeof VECTORS)[number];
+
+export type KitGate = {
+  readonly bin: string;
+  readonly vector: Vector;
+  readonly file: string;
+  readonly reads: "tree" | "range";
+  readonly args?: readonly string[];
+  readonly appliesTo: typeof EVERY_REPOSITORY | TrackedContent;
+};
+
+export const ENTRY_POINT: Program = { bin: "checks-lint", script: "core/lint.ts" };
+
+export const TEST_ENTRY_POINT: Program = { bin: "checks-test", script: "testing/test.ts" };
+
+export const DEFAULT_BRANCH = "main";
+
+const TYPESCRIPT_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx"], content: "TypeScript source" };
+
+export const KIT_GATES = [
+  { bin: "checks-lint-coverage", vector: "quality", file: "lint-coverage.sh", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-test-layout", vector: "testing", file: "test-layout.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-commit-identity", vector: "delivery", file: "commit-identity.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-comment-gate", vector: "quality", file: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-suppressions-ratchet", vector: "complexity", file: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-ci-wiring", vector: "delivery", file: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-docs", vector: "docs", file: "docs.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-repetition", vector: "complexity", file: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-unused", vector: "complexity", file: "unused.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-quarantine-clock", vector: "testing", file: "quarantine-clock.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+] as const satisfies readonly KitGate[];

package/{scripts → src/core}/lint.ts

@@ -151,8 +151,8 @@ function outcomeOf(exitCode: number): Outcome {
 
 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 script = (yield* Path.Path).join(import.meta.dir, "..", gate.vector, gate.file);
+  const program = gate.file.endsWith(".sh") ? "sh" : process.execPath;
   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" }))

package/{scripts → src/delivery}/changelog-write.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { Console, DateTime, Effect, FileSystem, Path, Schema } from "effect";
-import { cuts, releaseDates, renderChangelog, type Bump, type Cut, type Release } from "./changelog.ts";
-import { git } from "./git.ts";
-import { runMain } from "./main.ts";
+import { cuts, hasEntries, namesPullRequest, releaseDates, renderChangelog, type Bump, type Cut, type Release } from "./changelog.ts";
+import { git } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 
 const NAME = "checks-changelog";
 const CHANGELOG = "CHANGELOG.md";
@@ -69,8 +69,28 @@ const readPublished = Effect.fn("readPublished")(function* (root: string) {
   return new Set(tags.split("\n").flatMap((tag) => (tag.startsWith(TAG_PREFIX) ? [tag.slice(TAG_PREFIX.length)] : [])));
 });
 
-const subjectsOf = Effect.fn("subjectsOf")(function* (root: string, { version, date, through, after }: Cut) {
-  const log = yield* git(["log", "--topo-order", "--format=%s", through, "--not", ...after], root);
+const mergedTips = Effect.fn("mergedTips")(function* (root: string, through: string) {
+  // A bump that names its pull request or sits off the first-parent chain is main's release, so no squash merge of this branch releases more under it.
+  if (namesPullRequest((yield* git(["log", "-1", "--format=%s", through], root)).trim())) return [];
+  if (!(yield* git(["rev-list", "--first-parent", "HEAD"], root)).split("\n").includes(through)) return [];
+  const merges = yield* git(["log", "--merges", "--format=%P", `${through}..HEAD`], root);
+  const tips: string[] = [];
+  for (const [, ...parents] of merges.split("\n").filter((line) => line !== "").map((line) => line.split(" "))) {
+    for (const parent of parents) {
+      // A parent past the bump belongs to a later release, so only a parent beside it joins this one.
+      const past = yield* git(["merge-base", "--is-ancestor", through, parent], root).pipe(
+        Effect.as(true),
+        Effect.catchTag("GitFailure", () => Effect.succeed(false)),
+      );
+      if (!past) tips.push(parent);
+    }
+  }
+  return tips;
+});
+
+// The bump reaches no commit main gained after it, yet the squash merge releases them under it.
+const subjectsOf = Effect.fn("subjectsOf")(function* (root: string, { version, date, through, after }: Cut, extra: readonly string[] = []) {
+  const log = yield* git(["log", "--topo-order", "--format=%s", through, ...extra, "--not", ...after], root);
   return { version, date, subjects: log.split("\n").filter((subject) => subject !== "") } satisfies Release;
 });
 
@@ -94,7 +114,11 @@ const write = Effect.gen(function* () {
   const recorded = (yield* fs.exists(target)) ? releaseDates(yield* fs.readFileString(target)) : new Map<string, string>();
   const pending = version === (yield* versionAt(root, "HEAD")) ? undefined : { sha: "HEAD", version, date: yield* today };
   const released = cuts(yield* readBumps(root), recorded, yield* readPublished(root), pending);
-  const found = (yield* Effect.forEach(released, (cut) => subjectsOf(root, cut))).toReversed();
+  const tip = released.at(-1);
+  const extra = tip === undefined || tip.through === "HEAD" ? [] : yield* mergedTips(root, tip.through);
+  const found = (yield* Effect.forEach(released, (cut, index) => subjectsOf(root, cut, index === released.length - 1 ? extra : [])))
+    .filter(({ subjects }) => hasEntries(subjects))
+    .toReversed();
   yield* fs.writeFileString(target, renderChangelog(name, found, repositoryUrl));
   yield* Console.log(`${NAME}: wrote ${found.length} release(s) to ${CHANGELOG}`);
   return true;

package/{scripts → src/delivery}/changelog.ts

@@ -1,6 +1,6 @@
-import { firstText, parseOutline, VERSION } from "./doc-outline.ts";
-import { RELEASED } from "./doc-rules.ts";
-import { CHANGE_GROUPS, type ChangeGroup } from "./doc-templates.ts";
+import { firstText, parseOutline, VERSION } from "../docs/doc-outline.ts";
+import { RELEASED } from "../docs/doc-rules.ts";
+import { CHANGE_GROUPS, type ChangeGroup } from "../docs/doc-templates.ts";
 
 export type Bump = {
   readonly sha: string;
@@ -28,6 +28,8 @@ type Entry = {
 
 const CONVENTIONAL = /^([a-z]+)(?:\(([^()]*)\))?(!)?: (\S.*)$/;
 
+const PULL_REQUEST = / \(#(\d+)\)$/;
+
 const GROUP_OF_TYPE = new Map<string, ChangeGroup>([
   ["feat", "Features"],
   ["fix", "Fixes"],
@@ -42,11 +44,15 @@ export function groupOf(subject: string): ChangeGroup | undefined {
   return breaking === "!" ? "Breaking changes" : GROUP_OF_TYPE.get(type);
 }
 
+export function namesPullRequest(subject: string): boolean {
+  return PULL_REQUEST.test(subject);
+}
+
 function entryOf(subject: string, repositoryUrl: string): Entry | undefined {
   const group = groupOf(subject);
   if (group === undefined) return undefined;
   const [, , scope = "", , description = ""] = CONVENTIONAL.exec(subject) ?? [];
-  const linkedDescription = description.replace(/ \(#(\d+)\)$/, (_, number: string) => ` [#${number}](${repositoryUrl}/pull/${number})`);
+  const linkedDescription = description.replace(PULL_REQUEST, (_, number: string) => ` [#${number}](${repositoryUrl}/pull/${number})`);
   return { group, text: scope === "" ? linkedDescription : `**${scope}:** ${linkedDescription}` };
 }
 
@@ -82,6 +88,10 @@ export function cuts(
   }));
 }
 
+export function hasEntries(subjects: readonly string[]): boolean {
+  return subjects.some((subject) => groupOf(subject) !== undefined);
+}
+
 function renderRelease({ version, date, subjects }: Release, repositoryUrl: string): readonly string[] {
   const entries = subjects.flatMap((subject) => entryOf(subject, repositoryUrl) ?? []);
   const groups = CHANGE_GROUPS.flatMap((group) => {

package/{scripts → src/delivery}/ci-wiring.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import { defaultBranch, git } from "./git.ts";
-import { runMain } from "./main.ts";
-import { ENTRY_POINT, KIT_GATES, type KitGate } from "./gates.ts";
+import { defaultBranch, git } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
+import { ENTRY_POINT, KIT_GATES, type KitGate } from "../core/gates.ts";
 import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
 
 export type { Command };

package/{scripts → src/delivery}/commit-identity.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import { git, refArgs } from "./git.ts";
-import { runMain } from "./main.ts";
+import { git, refArgs } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 
 type Identity = { readonly name: string; readonly email: string };
 

package/{scripts → src/delivery}/release-notes.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Effect, FileSystem, Schema } from "effect";
-import { runMain, Usage } from "./main.ts";
+import { runMain, Usage } from "../core/main.ts";
 
 export class ReleaseSectionUnavailable extends Schema.TaggedError<ReleaseSectionUnavailable>()("ReleaseSectionUnavailable", {
   message: Schema.String,

package/{scripts → src/delivery}/release-report.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
 import { groupOf } from "./changelog.ts";
-import { git } from "./git.ts";
-import { runMain, Usage } from "./main.ts";
+import { git } from "../core/git.ts";
+import { runMain, Usage } from "../core/main.ts";
 
 export class ReleaseReportUnreadable extends Schema.TaggedError<ReleaseReportUnreadable>()("ReleaseReportUnreadable", {
   message: Schema.String,

package/{scripts → src/dependencies}/vendor-args.ts

@@ -1,5 +1,5 @@
 import { Effect, Schema } from "effect";
-import { Usage } from "./main.ts";
+import { Usage } from "../core/main.ts";
 
 export const NAME = "checks-vendor";
 export const OPENER = "--library";

package/{scripts → src/dependencies}/vendor.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Option, Path, Schema } from "effect";
-import { git } from "./git.ts";
-import { runMain } from "./main.ts";
+import { git } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 import { librariesFrom, NAME, OPENER, type Library } from "./vendor-args.ts";
 
 const CACHE_HOME = ".cache/avi2dg-checks";

package/{scripts → src/docs}/doc-snapshot.ts

@@ -1,6 +1,6 @@
 import { Effect, FileSystem, Path, Schema } from "effect";
 import { anchoredTargets, anchorsOf, PACKAGE_MANIFEST, packagesOf, snapshotOf, type Unresolved } from "./doc-references.ts";
-import { git, pathsAt } from "./git.ts";
+import { git, pathsAt } from "../core/git.ts";
 
 export class ManifestUnreadable extends Schema.TaggedError<ManifestUnreadable>()("ManifestUnreadable", {
   message: Schema.String,

package/{scripts → src/docs}/doc-templates.ts

@@ -91,7 +91,7 @@ export const TEMPLATES: Readonly<Record<Kind, Template>> = {
     title: { type: "fixed", text: "Changelog" },
     lead: ["Every release of <package>, newest first, written by the release from its conventional commits."],
     sections: [
-      open("<version>", "version", REQUIRED, ["Released <YYYY-MM-DD>."], {
+      open("<version>", "version", optional("no release holds a conventional commit worth listing yet"), ["Released <YYYY-MM-DD>."], {
         subsections: CHANGE_GROUPS.map((group) =>
           fixed(group, optional("the release holds no such commit"), ["- **<the commit's scope, when it has one>:** <its description>"]),
         ),

package/{scripts → src/docs}/docs.ts

@@ -3,8 +3,8 @@ import { Console, Effect } from "effect";
 import { rootsOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
 import { ADR_DIRECTORY, judge, placementOf, placementProblem, speaksToConsumers, type Placement } from "./doc-rules.ts";
 import { readTexts, snapshotAt, stillMissing } from "./doc-snapshot.ts";
-import { changedLines, changedPaths, git, pathsAt, rangeEnds, refArgs } from "./git.ts";
-import { runMain } from "./main.ts";
+import { changedLines, changedPaths, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 import { isLivingDoc, proseFindings, readerOf } from "./prose-matchers.ts";
 
 type Finding = {

package/{scripts → src/quality}/comment-gate.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { Console, Effect, Option } from "effect";
 import { refused, syntaxOf } from "./comments.ts";
-import { changedLines, git, parentOrEmptyTree, refArgs } from "./git.ts";
-import { runMain } from "./main.ts";
+import { changedLines, git, parentOrEmptyTree, refArgs } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
 
 export type GateResult = {
   readonly files: number;

package/{scripts → src/quality}/comment-matchers.ts

@@ -88,7 +88,7 @@ export function syntaxOf(path: string): Syntax | undefined {
 }
 
 export function unreadable(path: string): string {
-  return `${path} is code the comment checks cannot read: add a comment syntax for .${extensionOf(path)} to scripts/comment-matchers.ts`;
+  return `${path} is code the comment checks cannot read: add a comment syntax for .${extensionOf(path)} to src/quality/comment-matchers.ts`;
 }
 
 const WORD = /[\w$]/;

package/{scripts → src/testing}/flake.ts

@@ -1,7 +1,7 @@
 #!/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 { runMain, Usage } from "../core/main.ts";
 import { NAME_SEPARATOR, parseReport, ReportError, reporterArgs, type TestResult } from "./test-report.ts";
 
 export type Run = {