@avi2dg/checks 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.24.0
+
+Released 2026-09-27.
+
+### Features
+
+- **scripts:** ship checks-changelog, checks-release-notes and checks-release-report bins [#77](https://github.com/avi2d/checks/pull/77)
+
+### Fixes
+
+- **scripts:** make checks-vendor re-freeze a cached tree whose owner write bit came back [#76](https://github.com/avi2d/checks/pull/76)
+
 ## 0.23.0
 
 Released 2026-09-26.

package/README.md

@@ -126,6 +126,9 @@ These bins run on their own:
 - [`checks-mutation-compare`](docs/gates/checks-mutation-compare.md) holds every mutant in a pull request to no regression.
 - [`checks-subsumed-tests`](docs/gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
 - [`checks-backtest`](docs/gates/checks-backtest.md) reports what the comment check would have refused in recent history.
+- [`checks-changelog`](docs/gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
+- [`checks-release-notes`](docs/gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.
+- [`checks-release-report`](docs/gates/checks-release-report.md) tells whether the history holds unreleased features or fixes since the last tag.
 - [`checks-vendor`](docs/gates/checks-vendor.md) pins each library its `prepare` arguments name to a shared read-only clone and links it under `repos/`.
 
 `checks-lint` has [its own page](docs/gates/checks-lint.md), which says which range it resolves.

package/docs/design.md

@@ -96,6 +96,11 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   A directory the range deletes still counts as this repository's, so a path under it reads as stale rather than foreign.
 - The command check passes over a page whose front matter sets `audience: consumers`.
   Such a page speaks to a consuming repository, whose scripts are not this one's.
+- `checks-vendor` strips an owner write bit that came back on a cached tree and keeps the tree, rather than refusing it or cloning it again.
+  The GitHub Actions runner clears the read only mode of each item before it deletes `$RUNNER_TEMP`, and on a directory link that chmod lands on the shared tree's top directory.
+  Refusing the tree would fail every later job on the runner until a person cleared it, and cloning it again would need the network after every such job.
+  A write bit is not a write, so the run strips it and then holds the tree to the recorded commit as it holds any tree, and a write it finds there still fails the run.
+  A group or other write bit still fails the run, since another user could have edited `.git/config` through it before `git status` reads it.
 
 ## Related topics
 

package/docs/gates/checks-changelog.md

@@ -0,0 +1,57 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-changelog
+
+`checks-changelog` writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
+
+## What it checks
+
+It reads the version from `package.json` and treats that version as the release being prepared.
+It lists every conventional commit the release closes, grouped as Features, Fixes, Performance, Reverts and Breaking changes.
+It links each entry to its pull request under the repository address `package.json` names.
+It keeps the date a released section already carries and dates a new section today.
+It writes the whole file newest first, so the changelog is never edited by hand.
+A repository with no tag yet releases from its first commit.
+A release with no conventional commit worth listing keeps only its heading and its date.
+
+## What it reads
+
+It reads `package.json`, `CHANGELOG.md` and the git history from the repository root.
+It finds releases in the version bumps of `package.json` across all of `HEAD` ancestry, so a checkout without tags writes the same file.
+It refuses a shallow checkout, since the releases reach back past its history.
+It refuses a `package.json` with no repository address, since each entry links its pull request under it.
+It refuses a repository address that is no `https` address once `git+`, a trailing slash and `.git` are dropped, since a pull request link needs one.
+
+## Arguments
+
+```sh
+checks-changelog
+```
+
+It takes no arguments.
+Run it through the build, as the release workflow in [checks-release-notes](checks-release-notes.md) shows.
+
+## Exit codes
+
+| Code | Result |
+| --- | --- |
+| 0 | The changelog was written. |
+| 2 | The checkout is shallow, or `package.json` has no `https` repository address. |
+
+## Sample output
+
+```
+checks-changelog: wrote 2 release(s) to CHANGELOG.md
+```
+
+## Opting out
+
+Nothing runs it but the build of a repository that keeps a changelog.
+A repository with no versioned releases leaves it out.
+
+## Related topics
+
+- [checks-release-notes](checks-release-notes.md)
+- [checks-release-report](checks-release-report.md)

package/docs/gates/checks-release-notes.md

@@ -0,0 +1,141 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-notes
+
+`checks-release-notes` writes the `CHANGELOG.md` section of one version to a file for a GitHub release.
+
+## What it checks
+
+It reads the section the version heads and trims the blank lines around it.
+It writes the notes to the output path.
+It fails when the changelog holds no section for the version or the section is empty.
+
+## What it reads
+
+It reads `CHANGELOG.md` from the working directory.
+It reads the version from its arguments, not from `package.json`.
+
+## Arguments
+
+```sh
+checks-release-notes <version> <output>
+```
+
+The version names the `CHANGELOG.md` section to write, as `0.22.0` with no leading `v`.
+The output names the file to write.
+
+## Exit codes
+
+| Code | Result |
+| --- | --- |
+| 0 | The notes were written. |
+| 2 | The arguments do not parse, or `CHANGELOG.md` holds no notes for the version. |
+
+## Sample output
+
+```
+Released 2026-09-27.
+
+### Features
+
+- Add a release [#67](https://github.com/avi2d/checks/pull/67)
+```
+
+## Release workflow
+
+Each consumer owns `.github/workflows/release.yml` and calls the kit bins from it.
+The version lives in `package.json`, and the tag names the same version with a leading `v`.
+The build writes the changelog, so the release pull request carries the notes before the tag exists.
+A repository that publishes a package to npm releases with this workflow:
+
+```yaml
+name: release
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run build
+      - run: git diff --exit-code
+      - name: tag matches package version
+        run: test "v$(bun -p "require('./package.json').version")" = "$GITHUB_REF_NAME"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+      - run: npm publish
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - name: extract release notes
+        run: ./node_modules/.bin/checks-release-notes "${GITHUB_REF_NAME#v}" "$RUNNER_TEMP/release-notes.md"
+      - name: create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/release-notes.md"
+```
+
+A repository that never publishes to npm releases with this workflow instead, since only `checks` publishes a package:
+
+```yaml
+name: release
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+jobs:
+  github-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run build
+      - run: git diff --exit-code
+      - name: tag matches package version
+        run: test "v$(bun -p "require('./package.json').version")" = "$GITHUB_REF_NAME"
+      - name: extract release notes
+        run: ./node_modules/.bin/checks-release-notes "${GITHUB_REF_NAME#v}" "$RUNNER_TEMP/release-notes.md"
+      - name: create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/release-notes.md"
+```
+
+Cut a release by merging a pull request that holds only the version bump and the built changelog, then tagging the merge commit on the target branch and pushing the tag.
+The workflow refuses a tag that disagrees with `package.json`, so the tag always names the section the notes come from.
+
+## Opting out
+
+Nothing runs it but the release workflow of a repository that publishes GitHub releases.
+A repository with no versioned releases leaves it out.
+
+## Related topics
+
+- [checks-changelog](checks-changelog.md)
+- [checks-release-report](checks-release-report.md)

package/docs/gates/checks-release-report.md

@@ -0,0 +1,64 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-report
+
+`checks-release-report` tells whether the history holds unreleased features or fixes since the last tag.
+
+## What it checks
+
+It lists the conventional commits after the last tag reachable from `HEAD` that reads as a version such as `v0.2.0`.
+It counts a commit when its subject falls in Features, Fixes, Performance, Reverts or Breaking changes, the groups `checks-changelog` writes.
+It prints each unreleased subject on its own line under a count.
+A repository with no tag yet reports every such commit in its history.
+A history with no conventional release-worthy commit reports no unreleased changes.
+
+## What it reads
+
+It reads the tags and the commit subjects from the git history.
+It refuses a shallow checkout, since the tag it sees may not be the last one.
+It passes over any other tag, since only a release tag reads as a version.
+
+## Arguments
+
+```sh
+checks-release-report
+```
+
+It takes no arguments.
+Run it before cutting a tag to decide whether a release is due.
+
+## Exit codes
+
+| Code | Result |
+| --- | --- |
+| 0 | No unreleased changes were found. |
+| 1 | Unreleased changes were found. |
+| 2 | The arguments do not parse, or the history cannot be read. |
+
+## Sample output
+
+A history with unreleased changes prints the count and each subject:
+
+```
+release-report: 2 unreleased change(s) since v0.1.0:
+  feat: price a bill (#4)
+  fix(parts): keep the order of parts (#3)
+```
+
+A history with nothing to release prints one line:
+
+```
+release-report: no unreleased changes since v0.1.0
+```
+
+## Opting out
+
+Nothing runs it but a person or a scheduler deciding when to cut a release.
+A repository with no versioned releases leaves it out.
+
+## Related topics
+
+- [checks-changelog](checks-changelog.md)
+- [checks-release-notes](checks-release-notes.md)

package/docs/gates/checks-vendor.md

@@ -16,9 +16,12 @@ The clone is staged beside its cache entry and moves into place only once it is
 Every later run verifies the link rather than trusting it, and does so without contacting the remote.
 It confirms the tree sits on the recorded commit.
 It confirms the manifest inside the tree still names the installed version.
-It confirms no write bit came back and no write landed outside the recorded commit.
+It confirms no write bit is left once it has frozen the tree and no write landed outside the recorded commit.
 It never follows a link inside the tree, so no mode outside the cache is touched.
-Any failed confirmation fails the run.
+A tool that clears the read only mode of `repos/<name>` changes the tree's top directory through the link, as the GitHub Actions runner does when it empties `$RUNNER_TEMP`.
+A run that finds an owner write bit strips it from the tree again, then confirms no write landed outside the recorded commit.
+A group or other write bit is never stripped, and fails the run before it reads the tree's status.
+Any other failed confirmation fails the run, and so does a write the tree still holds once it is read only again.
 A failed library drops its `repos/<name>` link, so a reader falls back to `node_modules/<package>` rather than a tree the run could not vouch for.
 A missing tag, an unknown installed version or a manifest naming another version fails it too.
 A tag moved upstream after the first fetch is not followed, since a cached tree stays on its recorded commit.
@@ -68,6 +71,12 @@ checks-vendor: repos/effect still holds effect@4.0.0-rc.115, verified against it
 
 A later run reports the link it kept.
 
+```
+checks-vendor: found 1 path writable by its owner, starting with /home/runner/.cache/avi2dg-checks/repos/github.com/Effect-TS/effect/effect@4.0.0-rc.115, and froze the tree again, so repos/effect still holds effect@4.0.0-rc.115, verified against its recorded commit
+```
+
+A run that found an owner write bit reports how many paths carried one and the first of them.
+
 ## Wiring
 
 A consuming repository runs it from its `prepare` script, so every install pins and verifies the trees.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -25,6 +25,10 @@
     "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",
@@ -47,6 +51,7 @@
     "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",
@@ -67,6 +72,10 @@
     "./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",
@@ -104,6 +113,9 @@
   },
   "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",

package/scripts/changelog-write.ts

@@ -0,0 +1,95 @@
+#!/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";
+
+const NAME = "checks-changelog";
+const CHANGELOG = "CHANGELOG.md";
+const MANIFEST = "package.json";
+const FIELD = "\x1f";
+const TAG_PREFIX = "v";
+
+class ChangelogUnreadable extends Schema.TaggedError<ChangelogUnreadable>()("ChangelogUnreadable", {
+  message: Schema.String,
+}) {}
+
+const decodeManifestJson = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(
+    Schema.Struct({
+      name: Schema.String,
+      version: Schema.String,
+      repository: Schema.optional(Schema.Union([Schema.String, Schema.Struct({ url: Schema.optional(Schema.String) })])),
+    }),
+  ),
+);
+
+const decodeManifest = (text: string, source: string) =>
+  decodeManifestJson(text).pipe(Effect.mapError((cause) => new ChangelogUnreadable({ message: `${source}: ${cause.message}` })));
+
+const today = DateTime.nowInCurrentZone.pipe(DateTime.withCurrentZoneLocal, Effect.map(DateTime.formatIsoDate));
+
+function repositoryWebUrl(repository: string): string | undefined {
+  const url = repository
+    .replace(/^git\+/, "")
+    .replace(/\/$/, "")
+    .replace(/\.git$/, "");
+  return url.startsWith("https://") ? url : undefined;
+}
+
+const versionAt = Effect.fn("versionAt")(function* (root: string, sha: string) {
+  return (yield* decodeManifest(yield* git(["show", `${sha}:${MANIFEST}`], root), `${MANIFEST} at ${sha}`)).version;
+});
+
+const readBumps = Effect.fn("readBumps")(function* (root: string) {
+  const log = yield* git(
+    ["log", "--topo-order", "--reverse", "--full-history", "--no-merges", '-G"version"', "--format=%H%x1f%as%x1f%P", "HEAD", "--", MANIFEST],
+    root,
+  );
+  const bumps: Bump[] = [];
+  for (const line of log.split("\n")) {
+    const [sha, date, parent] = line.split(FIELD);
+    if (sha === undefined || date === undefined || parent === undefined) continue;
+    const version = yield* versionAt(root, sha);
+    if (parent === "" || (yield* versionAt(root, parent)) !== version) bumps.push({ sha, version, date });
+  }
+  return bumps;
+});
+
+const readPublished = Effect.fn("readPublished")(function* (root: string) {
+  const tags = yield* git(["for-each-ref", "--format=%(refname:strip=2)", `refs/tags/${TAG_PREFIX}*`], root);
+  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);
+  return { version, date, subjects: log.split("\n").filter((subject) => subject !== "") } satisfies Release;
+});
+
+const write = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  if ((yield* git(["rev-parse", "--is-shallow-repository"], root)).trim() === "true") {
+    return yield* new ChangelogUnreadable({ message: "the checkout is shallow, so the releases reach back past its history; fetch all of it" });
+  }
+  const target = path.join(root, CHANGELOG);
+  const { name, version, repository } = yield* decodeManifest(yield* fs.readFileString(path.join(root, MANIFEST)), MANIFEST);
+  const url = typeof repository === "string" ? repository : repository?.url;
+  if (url === undefined) {
+    return yield* new ChangelogUnreadable({ message: `${MANIFEST} has no repository.url, which the changelog links each pull request under` });
+  }
+  const repositoryUrl = repositoryWebUrl(url);
+  if (repositoryUrl === undefined) {
+    return yield* new ChangelogUnreadable({ message: `${MANIFEST} repository ${url} is no https address, which the changelog links each pull request under` });
+  }
+  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();
+  yield* fs.writeFileString(target, renderChangelog(name, found, repositoryUrl));
+  yield* Console.log(`${NAME}: wrote ${found.length} release(s) to ${CHANGELOG}`);
+  return true;
+});
+
+if (import.meta.main) runMain(NAME, write);

package/scripts/changelog.ts

@@ -0,0 +1,110 @@
+import { firstText, parseOutline, VERSION } from "./doc-outline.ts";
+import { RELEASED } from "./doc-rules.ts";
+import { CHANGE_GROUPS, type ChangeGroup } from "./doc-templates.ts";
+
+export type Bump = {
+  readonly sha: string;
+  readonly version: string;
+  readonly date: string;
+};
+
+export type Cut = {
+  readonly version: string;
+  readonly date: string;
+  readonly through: string;
+  readonly after: readonly string[];
+};
+
+export type Release = {
+  readonly version: string;
+  readonly date: string;
+  readonly subjects: readonly string[];
+};
+
+type Entry = {
+  readonly group: ChangeGroup;
+  readonly text: string;
+};
+
+const CONVENTIONAL = /^([a-z]+)(?:\(([^()]*)\))?(!)?: (\S.*)$/;
+
+const GROUP_OF_TYPE = new Map<string, ChangeGroup>([
+  ["feat", "Features"],
+  ["fix", "Fixes"],
+  ["perf", "Performance"],
+  ["revert", "Reverts"],
+]);
+
+// Only the subject is linted, and a squash merge's body is its branch's commit messages,
+// so a breaking change is read from the subject's `!` and never from a footer.
+export function groupOf(subject: string): ChangeGroup | undefined {
+  const [, type = "", , breaking] = CONVENTIONAL.exec(subject) ?? [];
+  return breaking === "!" ? "Breaking changes" : GROUP_OF_TYPE.get(type);
+}
+
+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})`);
+  return { group, text: scope === "" ? linkedDescription : `**${scope}:** ${linkedDescription}` };
+}
+
+// A bump not newer than the release before it is a revert: it cancels every release above the version it
+// returns to, except a published one.
+function standing(bumps: readonly Bump[], published: ReadonlySet<string>): readonly Bump[] {
+  return bumps.reduce<readonly Bump[]>((kept, bump) => {
+    const before = kept.at(-1);
+    if (before === undefined || Bun.semver.order(bump.version, before.version) === 1) return [...kept, bump];
+    return kept.filter(({ version }) => published.has(version) || Bun.semver.order(version, bump.version) !== 1);
+  }, []);
+}
+
+// The changelog records what was released: a version older than the newest it lists and absent from it
+// was never published, so its commits roll into the next release.
+export function cuts(
+  bumps: readonly Bump[],
+  recorded: ReadonlyMap<string, string>,
+  published: ReadonlySet<string>,
+  pending: Bump | undefined,
+): readonly Cut[] {
+  const newest = [...recorded.keys()].toSorted(Bun.semver.order).at(-1);
+  const candidates = standing(pending === undefined ? bumps : [...bumps, pending], published);
+  const released = candidates.filter(
+    ({ version }, index) =>
+      index === candidates.length - 1 || newest === undefined || recorded.has(version) || Bun.semver.order(version, newest) !== -1,
+  );
+  return released.map(({ sha, version, date }, index) => ({
+    version,
+    date: recorded.get(version) ?? date,
+    through: sha,
+    after: released.slice(0, index).map((earlier) => earlier.sha),
+  }));
+}
+
+function renderRelease({ version, date, subjects }: Release, repositoryUrl: string): readonly string[] {
+  const entries = subjects.flatMap((subject) => entryOf(subject, repositoryUrl) ?? []);
+  const groups = CHANGE_GROUPS.flatMap((group) => {
+    const listed = entries.filter((entry) => entry.group === group).map(({ text }) => `- ${text}`);
+    return listed.length === 0 ? [] : [`### ${group}`, listed.join("\n")];
+  });
+  return [`## ${version}`, `Released ${date}.`, ...groups];
+}
+
+export function renderChangelog(name: string, found: readonly Release[], repositoryUrl: string): string {
+  const blocks = [
+    "# Changelog",
+    `Every release of \`${name}\`, newest first, written by the release from its conventional commits.`,
+    ...found.flatMap((release) => renderRelease(release, repositoryUrl)),
+  ];
+  return `${blocks.join("\n\n")}\n`;
+}
+
+export function releaseDates(text: string): ReadonlyMap<string, string> {
+  return new Map(
+    parseOutline(text).sections.flatMap(({ heading, body }) => {
+      const date = RELEASED.exec(firstText(body)?.text.trim() ?? "")?.[1];
+      return VERSION.test(heading.title) && date !== undefined ? [[heading.title, date] as const] : [];
+    }),
+  );
+}

package/scripts/release-notes.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+import { Effect, FileSystem, Schema } from "effect";
+import { runMain, Usage } from "./main.ts";
+
+export class ReleaseSectionUnavailable extends Schema.TaggedError<ReleaseSectionUnavailable>()("ReleaseSectionUnavailable", {
+  message: Schema.String,
+}) {}
+
+export function extractReleaseNotes(changelog: string, version: string): Effect.Effect<string, ReleaseSectionUnavailable> {
+  const lines = changelog.split(/\r?\n/);
+  const heading = lines.indexOf(`## ${version}`);
+  if (heading === -1) return Effect.fail(new ReleaseSectionUnavailable({ message: `CHANGELOG.md has no section for ${version}` }));
+
+  const next = lines.findIndex((line, index) => index > heading && line.startsWith("## "));
+  const body = lines.slice(heading + 1, next === -1 ? lines.length : next);
+  let start = 0;
+  let end = body.length;
+  while (start < end && body[start]?.trim() === "") start += 1;
+  while (end > start && body[end - 1]?.trim() === "") end -= 1;
+  const notes = body.slice(start, end).join("\n");
+  return notes === ""
+    ? Effect.fail(new ReleaseSectionUnavailable({ message: `CHANGELOG.md has an empty section for ${version}` }))
+    : Effect.succeed(notes);
+}
+
+const USAGE = "usage: release-notes.ts <version> <output>";
+
+const releaseNotes = Effect.gen(function* () {
+  const [version, output, ...extra] = process.argv.slice(2);
+  if (version === undefined || output === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
+  const fs = yield* FileSystem.FileSystem;
+  const notes = yield* extractReleaseNotes(yield* fs.readFileString("CHANGELOG.md"), version);
+  yield* fs.writeFileString(output, notes);
+  return true;
+});
+
+if (import.meta.main) runMain("checks-release-notes", releaseNotes);

package/scripts/release-report.ts

@@ -0,0 +1,50 @@
+#!/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";
+
+export class ReleaseReportUnreadable extends Schema.TaggedError<ReleaseReportUnreadable>()("ReleaseReportUnreadable", {
+  message: Schema.String,
+}) {}
+
+const USAGE = "usage: release-report.ts";
+const RELEASE_TAG = "v[0-9]*.[0-9]*.[0-9]*";
+
+export function unreleasedOf(subjects: readonly string[]): readonly string[] {
+  return subjects.filter((subject) => groupOf(subject) !== undefined);
+}
+
+export function formatReport(unreleased: readonly string[], since: string | undefined): string {
+  const where = since === undefined ? "with no tag yet" : `since ${since}`;
+  if (unreleased.length === 0) return `release-report: no unreleased changes ${where}`;
+  return [`release-report: ${unreleased.length} unreleased change(s) ${where}:`, ...unreleased.map((subject) => `  ${subject}`)].join("\n");
+}
+
+const lastTag = Effect.fn("lastTag")(function* (root: string) {
+  const described = yield* git(["describe", "--tags", "--abbrev=0", `--match=${RELEASE_TAG}`, "HEAD"], root).pipe(
+    Effect.map((tag) => tag.trim()),
+    Effect.catchTag("GitFailure", () => Effect.succeed("")),
+  );
+  return described === "" ? undefined : described;
+});
+
+const subjectsSince = Effect.fn("subjectsSince")(function* (root: string, since: string | undefined) {
+  const range = since === undefined ? "HEAD" : `${since}..HEAD`;
+  const log = yield* git(["log", "--topo-order", "--no-merges", "--format=%s", range], root);
+  return log.split("\n").filter((subject) => subject !== "");
+});
+
+const report = Effect.gen(function* () {
+  if (process.argv.slice(2).length > 0) return yield* new Usage({ message: USAGE });
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  if ((yield* git(["rev-parse", "--is-shallow-repository"], root)).trim() === "true") {
+    return yield* new ReleaseReportUnreadable({ message: "the checkout is shallow, so the tag it sees may not be the last one; fetch all of it" });
+  }
+  const since = yield* lastTag(root);
+  const unreleased = unreleasedOf(yield* subjectsSince(root, since));
+  yield* Console.log(formatReport(unreleased, since));
+  return unreleased.length === 0;
+});
+
+if (import.meta.main) runMain("checks-release-report", report);

package/scripts/vendor-args.ts

@@ -0,0 +1,54 @@
+import { Effect, Schema } from "effect";
+import { Usage } from "./main.ts";
+
+export const NAME = "checks-vendor";
+export const OPENER = "--library";
+const USAGE = `usage: ${NAME} [--library <name> --package <package> --repository <remote> --tag <template> [--path <manifest>]]...`;
+
+const Library = Schema.Struct({
+  name: Schema.String.check(Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)),
+  package: Schema.NonEmptyString,
+  repository: Schema.NonEmptyString,
+  tag: Schema.String.check(Schema.isPattern(/\{version\}/)),
+  path: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^(?:[\w.@+-]+\/)*[\w.@+-]+\.\w+$/))),
+});
+export type Library = typeof Library.Type;
+
+const Libraries = Schema.Array(Library).check(
+  Schema.makeFilter((libraries) => {
+    const names = libraries.map(({ name }) => name);
+    const repeated = names.find((name, index) => names.indexOf(name) !== index);
+    return repeated === undefined || `--library ${repeated} appears more than once`;
+  }),
+);
+
+const FIELDS = new Map<string, keyof Library>([
+  ["--package", "package"],
+  ["--repository", "repository"],
+  ["--tag", "tag"],
+  ["--path", "path"],
+]);
+
+function misuse(message: string): Usage {
+  return new Usage({ message: `${message}\n${USAGE}` });
+}
+
+export const librariesFrom = Effect.fn("librariesFrom")(function* (args: readonly string[]) {
+  const groups: Record<string, string>[] = [];
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index] ?? "";
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) return yield* misuse(`${flag} takes a value`);
+    if (flag === OPENER) {
+      groups.push({ name: value });
+      continue;
+    }
+    const field = FIELDS.get(flag);
+    const current = groups.at(-1);
+    if (field === undefined) return yield* misuse(`${flag} is not an argument`);
+    if (current === undefined) return yield* misuse(`${flag} comes before any ${OPENER}`);
+    if (field in current) return yield* misuse(`${flag} appears twice for ${OPENER} ${current["name"]}`);
+    current[field] = value;
+  }
+  return yield* Schema.decodeUnknownEffect(Libraries)(groups).pipe(Effect.mapError((cause) => misuse(cause.message)));
+});

package/scripts/vendor.ts

@@ -1,10 +1,9 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Option, Path, Schema } from "effect";
 import { git } from "./git.ts";
-import { runMain, Usage } from "./main.ts";
+import { runMain } from "./main.ts";
+import { librariesFrom, NAME, OPENER, type Library } from "./vendor-args.ts";
 
-const NAME = "checks-vendor";
-const USAGE = `usage: ${NAME} [--library <name> --package <package> --repository <remote> --tag <template> [--path <manifest>]]...`;
 const CACHE_HOME = ".cache/avi2dg-checks";
 const RECORD_SUFFIX = ".commit";
 const LINKS = "repos";
@@ -21,55 +20,6 @@ export class Unreachable extends Schema.TaggedError<Unreachable>()("Unreachable"
   message: Schema.String,
 }) {}
 
-const Library = Schema.Struct({
-  name: Schema.String.check(Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)),
-  package: Schema.NonEmptyString,
-  repository: Schema.NonEmptyString,
-  tag: Schema.String.check(Schema.isPattern(/\{version\}/)),
-  path: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^(?:[\w.@+-]+\/)*[\w.@+-]+\.\w+$/))),
-});
-type Library = typeof Library.Type;
-
-const Libraries = Schema.Array(Library).check(
-  Schema.makeFilter((libraries) => {
-    const names = libraries.map(({ name }) => name);
-    const repeated = names.find((name, index) => names.indexOf(name) !== index);
-    return repeated === undefined || `--library ${repeated} appears more than once`;
-  }),
-);
-
-const OPENER = "--library";
-const FIELDS = new Map<string, keyof Library>([
-  ["--package", "package"],
-  ["--repository", "repository"],
-  ["--tag", "tag"],
-  ["--path", "path"],
-]);
-
-function misuse(message: string): Usage {
-  return new Usage({ message: `${message}\n${USAGE}` });
-}
-
-const librariesFrom = Effect.fn("librariesFrom")(function* (args: readonly string[]) {
-  const groups: Record<string, string>[] = [];
-  for (let index = 0; index < args.length; index += 2) {
-    const flag = args[index] ?? "";
-    const value = args[index + 1];
-    if (value === undefined || value.startsWith("--")) return yield* misuse(`${flag} takes a value`);
-    if (flag === OPENER) {
-      groups.push({ name: value });
-      continue;
-    }
-    const field = FIELDS.get(flag);
-    const current = groups.at(-1);
-    if (field === undefined) return yield* misuse(`${flag} is not an argument`);
-    if (current === undefined) return yield* misuse(`${flag} comes before any ${OPENER}`);
-    if (field in current) return yield* misuse(`${flag} appears twice for ${OPENER} ${current["name"]}`);
-    current[field] = value;
-  }
-  return yield* Schema.decodeUnknownEffect(Libraries)(groups).pipe(Effect.mapError((cause) => misuse(cause.message)));
-});
-
 export function tagFor(template: string, version: string): string {
   return template.replaceAll(VERSION_TOKEN, version);
 }
@@ -171,6 +121,11 @@ function clearing(dir: string): string {
   return `clear it with \`chmod -R u+w ${dir} && rm -rf ${dir}\` and rerun ${NAME}`;
 }
 
+function writableAt(dir: string, paths: readonly string[], by: string): string {
+  const [first = dir] = paths;
+  return `${paths.length === 1 ? "1 path" : `${paths.length} paths`} writable by ${by}, starting with ${first}`;
+}
+
 const freeze = Effect.fn("freeze")(function* (dir: string) {
   const fs = yield* FileSystem.FileSystem;
   for (const { entry, mode } of yield* modes(dir)) {
@@ -212,7 +167,8 @@ const recorded = Effect.fn("recorded")(function* (dir: string) {
   return Option.some(text.trim());
 });
 
-const verify = Effect.fn("verify")(function* (dir: string, library: Library, installed: string, tag: string) {
+// Returns the paths still carrying the owner write bit and fails on every other finding, reading the status only once none are left.
+const inspect = Effect.fn("inspect")(function* (dir: string, library: Library, installed: string, tag: string) {
   const held = yield* recorded(dir);
   if (Option.isNone(held)) {
     return yield* new VendorError({ message: `${recordOf(dir)} is missing, so ${dir} has no commit to hold to; ${clearing(dir)}` });
@@ -223,13 +179,13 @@ const verify = Effect.fn("verify")(function* (dir: string, library: Library, ins
     return yield* new VendorError({ message: `${dir} sits on ${head}, not the recorded ${record}; ${clearing(dir)}` });
   }
   yield* checkVersion(dir, library, installed, tag);
-  const tampered = (yield* modes(dir)).filter(({ mode }) => (mode & WRITE_BITS) !== 0).map(({ entry }) => entry);
-  if (tampered.length > 0) {
-    const [first = dir] = tampered;
-    return yield* new VendorError({
-      message: `${dir} leaves ${tampered.length} paths writable, starting with ${first}; ${clearing(dir)}`,
-    });
+  const found = yield* modes(dir);
+  const shared = found.filter(({ mode }) => (mode & WRITE_BITS & ~OWNER_WRITE) !== 0).map(({ entry }) => entry);
+  if (shared.length > 0) {
+    return yield* new VendorError({ message: `${dir} leaves ${writableAt(dir, shared, "group or others")}; ${clearing(dir)}` });
   }
+  const writable = found.filter(({ mode }) => (mode & OWNER_WRITE) !== 0).map(({ entry }) => entry);
+  if (writable.length > 0) return writable;
   const status = yield* git(["status", "--porcelain", "--ignored"], dir).pipe(
     Effect.mapError((cause) => new VendorError({ message: `${dir} reports no status: ${cause.message}` })),
   );
@@ -237,6 +193,7 @@ const verify = Effect.fn("verify")(function* (dir: string, library: Library, ins
     const [first = ""] = status.trim().split("\n");
     return yield* new VendorError({ message: `${dir} holds writes outside the recorded commit, starting with ${first}; ${clearing(dir)}` });
   }
+  return writable;
 });
 
 const ensureLink = Effect.fn("ensureLink")(function* (root: string, library: Library, dir: string) {
@@ -315,8 +272,26 @@ const land = Effect.fn("land")(function* (library: Library, installed: string, t
   return yield* stage(staging, library, installed, tag, dir).pipe(Effect.ensuring(discard(staging)));
 });
 
-const vend = Effect.fn("vend")(function* (root: string, cache: string, library: Library) {
+function verified(library: Library, tag: string): string {
+  return `${LINKS}/${library.name} still holds ${tag}, verified against its recorded commit`;
+}
+
+const settle = Effect.fn("settle")(function* (library: Library, installed: string, tag: string, dir: string) {
   const fs = yield* FileSystem.FileSystem;
+  if (!(yield* fs.exists(dir)) && (yield* land(library, installed, tag, dir))) {
+    return `cloned ${tag} from ${library.repository} and linked ${LINKS}/${library.name}`;
+  }
+  const writable = yield* inspect(dir, library, installed, tag);
+  if (writable.length === 0) return verified(library, tag);
+  yield* freeze(dir);
+  const left = yield* inspect(dir, library, installed, tag);
+  if (left.length > 0) {
+    return yield* new VendorError({ message: `${dir} leaves ${writableAt(dir, left, "its owner")}; ${clearing(dir)}` });
+  }
+  return `found ${writableAt(dir, writable, "its owner")}, and froze the tree again, so ${verified(library, tag)}`;
+});
+
+const vend = Effect.fn("vend")(function* (root: string, cache: string, library: Library) {
   const path = yield* Path.Path;
   const installed = yield* manifestVersion(
     path.join(root, "node_modules", ...library.package.split("/"), "package.json"),
@@ -324,12 +299,7 @@ const vend = Effect.fn("vend")(function* (root: string, cache: string, library:
   );
   const tag = tagFor(library.tag, installed);
   const dir = path.join(cache, LINKS, ...remoteSegments(library.repository), tag);
-  if (!(yield* fs.exists(dir)) && (yield* land(library, installed, tag, dir))) {
-    yield* Console.error(`${NAME}: cloned ${tag} from ${library.repository} and linked ${LINKS}/${library.name}`);
-  } else {
-    yield* verify(dir, library, installed, tag);
-    yield* Console.error(`${NAME}: ${LINKS}/${library.name} still holds ${tag}, verified against its recorded commit`);
-  }
+  yield* Console.error(`${NAME}: ${yield* settle(library, installed, tag, dir)}`);
   yield* ensureLink(root, library, dir);
 });