chore(release): link each CHANGELOG entry to its compare range

Changesets writes `## <version>` and the notes beneath it, and nothing
about which commits a release actually contained. Reviewing "what shipped
in 0.11.0" meant finding the version-bump commit by hand, which is harder
than it sounds: every one of them is called `chore: version packages`, so
the subject line cannot tell them apart and you have to read the version
out of `package.json` at each candidate.

`scripts/changelog-compare-links.ts` adds a `vPREV...vNEXT` compare link
under each heading, and runs from `pnpm bump` — which is what the Version
Packages workflow invokes — so the link lands in the same PR as the notes
it describes. The tag it points at does not exist yet at that moment;
`release-cli.yml` creates it after publishing, so the newest link is dead
for the minutes in between and correct forever after.

Releases before 0.9.0 were never tagged and will not be, so a link whose
left side is `v0.8.1` would be permanently broken rather than briefly so.
A documented `FIRST_TAGGED` floor leaves those headings alone; 0.9.0 itself
gets no link for the same reason.

Backfilled 0.10.0, 0.10.1 and 0.10.2, whose tags were just created. Both
`v0.10.1...v0.10.2` and `v0.9.0...v0.10.0` return HTTP 200. Re-running is a
no-op, and a simulated 0.11.0 heading takes exactly one new link.

Author: theCodeDrift

.github/workflows/release-cli-changeset.yml

@@ -59,6 +59,10 @@ jobs:
 
       # `version: pnpm bump` runs `changeset version` AND `sync-skill-versions`,
       # so the bumped version is propagated into skills/recipes in the same PR.
+      # It also runs `changelog-compare-links`, which adds the
+      # `vPREV...vNEXT` compare link under the new CHANGELOG heading. That link
+      # is dead until `release-cli.yml` creates the tag after publishing, which
+      # is expected: the notes and the link they describe belong in the same PR.
       # No `publish:` input — this job can never publish.
       - uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1
         with:

package.json

@@ -11,7 +11,8 @@
     "build:self": "run-s build:self:compile build:self:install",
     "build:self:compile": "pnpm --filter @taskless/cli build:self",
     "build:self:install": "node packages/cli/dist-self/index.js init --no-interactive",
-    "bump": "run-s bump:version bump:sync",
+    "bump": "run-s bump:version bump:changelog bump:sync",
+    "bump:changelog": "tsx scripts/changelog-compare-links.ts",
     "bump:sync": "tsx scripts/sync-skill-versions.ts",
     "bump:version": "changeset version",
     "changeset": "changeset",

packages/cli/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 0.10.2
 
+[Compare with v0.10.1](https://github.com/taskless/cli/compare/v0.10.1...v0.10.2)
+
 ### Patch Changes
 
 - 1cd0f89: Treat the Taskless organization UUID as the one canonical identity, and become
@@ -34,6 +36,8 @@
 
 ## 0.10.1
 
+[Compare with v0.10.0](https://github.com/taskless/cli/compare/v0.10.0...v0.10.1)
+
 ### Patch Changes
 
 - 53b2d30: Add a help recipe for the `detect` command.
@@ -47,6 +51,8 @@
 
 ## 0.10.0
 
+[Compare with v0.9.0](https://github.com/taskless/cli/compare/v0.9.0...v0.10.0)
+
 ### Minor Changes
 
 - da74920: Send an `x-taskless-cli-version` header on every request to the Taskless service (rule generation, reconcile, `whoami`, and the device-auth flow) declaring the CLI's version. The service uses this to gate capability-dependent responses — notably runtime rules — on the CLI being new enough to handle them; a request without the header is treated as a pre-runtime CLI. The version is also emitted with the CLI's telemetry so usage is recorded client-side rather than inferred server-side.

scripts/changelog-compare-links.ts

@@ -0,0 +1,108 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+/**
+ * Add a compare link under each version heading in the CLI's CHANGELOG.
+ *
+ * Changesets writes `## <version>` and the notes beneath it, and nothing that
+ * says which commits a release actually contained. Reviewing "what shipped in
+ * 0.11.0" then means finding the version-bump commit by hand, which is harder
+ * than it sounds because every one of them is called `chore: version packages`.
+ *
+ * Runs as part of `pnpm bump`, so the link lands in the Version Packages PR
+ * alongside the notes it describes. The tag it points at does not exist yet at
+ * that moment: `release-cli.yml` creates it after the publish. The link is dead
+ * for the minutes in between and correct forever after, which is the accepted
+ * trade rather than an oversight.
+ */
+
+const ROOT = resolve(import.meta.dirname, "..");
+const CHANGELOG = join(ROOT, "packages", "cli", "CHANGELOG.md");
+const CLI_PACKAGE_JSON = join(ROOT, "packages", "cli", "package.json");
+
+/**
+ * The oldest release with a tag, so the oldest version that can be the LEFT
+ * side of a compare link.
+ *
+ * Tagging began here: `v0.9.0` through `v0.10.2` were created retroactively,
+ * and releases before `0.9.0` were never tagged and will not be. Emitting a
+ * link whose left side is `v0.8.1` would produce a permanently broken URL,
+ * which is worse than no link, so those headings are left alone.
+ */
+const FIRST_TAGGED = "0.9.0";
+
+/** `## 1.2.3` at the start of a line. Changesets writes nothing else here. */
+const HEADING = /^## (\d+\.\d+\.\d+)\s*$/;
+
+/** A link this script already wrote, so a re-run is a no-op. */
+const COMPARE_LINK = /^\[Compare with v\d+\.\d+\.\d+\]\(/;
+
+/** Numeric ordering. Every version here is a plain release, never a prerelease. */
+function isAtLeast(version: string, floor: string): boolean {
+  const a = version.split(".").map(Number);
+  const b = floor.split(".").map(Number);
+  for (let index = 0; index < 3; index++) {
+    if ((a[index] ?? 0) !== (b[index] ?? 0))
+      return (a[index] ?? 0) > (b[index] ?? 0);
+  }
+  return true;
+}
+
+/**
+ * Insert a compare link beneath every heading that has an older sibling, and
+ * return the new text. Pure, so it can be exercised without touching the file.
+ */
+export function withCompareLinks(
+  markdown: string,
+  repositoryUrl: string
+): string {
+  const lines = markdown.split("\n");
+  const headings: Array<{ index: number; version: string }> = [];
+  for (const [index, line] of lines.entries()) {
+    const match = HEADING.exec(line);
+    if (match?.[1]) headings.push({ index, version: match[1] });
+  }
+
+  // Back to front, so an insertion never shifts an index still to be used.
+  for (let position = headings.length - 2; position >= 0; position--) {
+    const current = headings[position]!;
+    const previous = headings[position + 1]!;
+    if (!isAtLeast(previous.version, FIRST_TAGGED)) continue;
+
+    // Idempotent: the first non-empty line after the heading decides.
+    let cursor = current.index + 1;
+    while (cursor < lines.length && lines[cursor]!.trim() === "") cursor++;
+    if (COMPARE_LINK.test(lines[cursor] ?? "")) continue;
+
+    const from = `v${previous.version}`;
+    const to = `v${current.version}`;
+    lines.splice(
+      current.index + 1,
+      0,
+      "",
+      `[Compare with ${from}](${repositoryUrl}/compare/${from}...${to})`
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/** `https://github.com/owner/repo`, from the package's own metadata. */
+function repositoryUrl(): string {
+  const manifest = JSON.parse(readFileSync(CLI_PACKAGE_JSON, "utf8")) as {
+    repository?: { url?: string };
+  };
+  const raw = manifest.repository?.url;
+  if (!raw) throw new Error("packages/cli/package.json has no repository.url");
+  return raw.replace(/^git\+/, "").replace(/\.git$/, "");
+}
+
+const before = readFileSync(CHANGELOG, "utf8");
+const after = withCompareLinks(before, repositoryUrl());
+if (before === after) {
+  console.log("CHANGELOG compare links: already up to date.");
+} else {
+  writeFileSync(CHANGELOG, after, "utf8");
+  const added = after.split("\n").length - before.split("\n").length;
+  console.log(`CHANGELOG compare links: added ${added / 2} link(s).`);
+}