@avi2dg/checks 0.24.0 → 0.24.2

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.24.2
+
+Released 2026-09-27.
+
+### Fixes
+
+- **scripts:** list commits merged in after a bump under that release [#82](https://github.com/avi2d/checks/pull/82)
+- **scripts:** leave versions with no listable commits out of the changelog [#81](https://github.com/avi2d/checks/pull/81)
+
+## 0.24.1
+
+Released 2026-09-27.
+
+### Fixes
+
+- **scripts:** let checks-changelog release a repository that gains its version late [#79](https://github.com/avi2d/checks/pull/79)
+
 ## 0.24.0
 
 Released 2026-09-27.

package/CONTRIBUTING.md

@@ -41,7 +41,8 @@ To release a version:
    The build writes the version's section into `CHANGELOG.md` from the conventional commits since the last release, so the changelog is never edited by hand.
 1. Commit both as `chore: release <version>` and title the pull request the same.
    The squash merge lands the title as the commit's subject, and a `feat` or `fix` title would add an entry the committed changelog lacks.
-1. Rebase the pull request onto `main` right before it merges, since a commit merged in between belongs to the release and the committed section would lack it.
+1. Merge `main` into the release branch and run `bun run build` again right before it merges, committing what it rewrote, since the build lists a commit merged in after the bump under the release.
+   Never rebase the release branch.
 1. Once it merges, tag that commit on `main` with the version and push the tag, since the version bump commit closes the release:
 
    ```sh

package/docs/gates/checks-changelog.md

@@ -10,16 +10,21 @@ audience: consumers
 
 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 lists the commits a branch merged in after its bump under that bump, since the squash merge releases them there.
+It leaves out what the branch added past its bump, since the squash merge folds it into the release commit.
+Only a branch carrying its own unlanded bump lists the commits of an unlanded branch it merges, so such a branch takes in only main.
+CI must build the pull request head commit, the `actions/checkout` ref `github.event.pull_request.head.sha`, and not the GitHub merge ref, since the merge ref puts main first and the branch's own bump off the first-parent chain.
 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.
+A version with no conventional commit worth listing writes no section.
 
 ## 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 reads a commit whose `package.json` is missing or has no version as unversioned, so the commit that adds the version is the first release and a repository that adopts a version late still writes its changelog.
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {

package/scripts/changelog-write.ts

@@ -1,6 +1,6 @@
 #!/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 { cuts, hasEntries, namesPullRequest, releaseDates, renderChangelog, type Bump, type Cut, type Release } from "./changelog.ts";
 import { git } from "./git.ts";
 import { runMain } from "./main.ts";
 
@@ -24,9 +24,14 @@ const decodeManifestJson = Schema.decodeUnknownEffect(
   ),
 );
 
+const decodeVersionJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ version: Schema.optional(Schema.String) })));
+
 const decodeManifest = (text: string, source: string) =>
   decodeManifestJson(text).pipe(Effect.mapError((cause) => new ChangelogUnreadable({ message: `${source}: ${cause.message}` })));
 
+const decodeVersion = (text: string, source: string) =>
+  decodeVersionJson(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 {
@@ -38,7 +43,9 @@ function repositoryWebUrl(repository: string): string | 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 blob = (yield* git(["ls-tree", "--object-only", sha, "--", MANIFEST], root)).trim();
+  if (blob === "") return undefined;
+  return (yield* decodeVersion(yield* git(["cat-file", "blob", blob], root), `${MANIFEST} at ${sha}`)).version;
 });
 
 const readBumps = Effect.fn("readBumps")(function* (root: string) {
@@ -51,6 +58,7 @@ const readBumps = Effect.fn("readBumps")(function* (root: string) {
     const [sha, date, parent] = line.split(FIELD);
     if (sha === undefined || date === undefined || parent === undefined) continue;
     const version = yield* versionAt(root, sha);
+    if (version === undefined) continue;
     if (parent === "" || (yield* versionAt(root, parent)) !== version) bumps.push({ sha, version, date });
   }
   return bumps;
@@ -61,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;
 });
 
@@ -86,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/changelog.ts

@@ -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/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/templates/changelog.md

@@ -4,6 +4,8 @@ Every release of <package>, newest first, written by the release from its conven
 
 ## <version>
 
+<Leave this section out when no release holds a conventional commit worth listing yet.>
+
 Released <YYYY-MM-DD>.
 
 ### Breaking changes