Convert update-release-branch.py to TypeScript

.github/actions/release-branches/action.yml

@@ -22,7 +22,6 @@ runs:
         MAJOR_VERSION: ${{ inputs.major_version }}
         LATEST_TAG: ${{ inputs.latest_tag }}
       run: |
-        npm ci
         npx tsx ./pr-checks/release-branches.ts \
             --major-version "$MAJOR_VERSION" \
             --latest-tag "$LATEST_TAG"

.github/actions/release-initialise/action.yml

@@ -21,6 +21,10 @@ runs:
         node-version: 24
         cache: 'npm'
 
+    - name: Install JavaScript dependencies
+      shell: bash
+      run: npm ci
+
     - name: Set up Python
       uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
       with:

.github/workflows/update-release-branch.yml

@@ -69,7 +69,7 @@ jobs:
       run: |
         echo SOURCE_BRANCH=${REF_NAME}
         echo TARGET_BRANCH=releases/${MAJOR_VERSION}
-        python .github/update-release-branch.py \
+        npx tsx ./pr-checks/update-release-branch.ts \
           --repository-nwo ${{ github.repository }} \
           --source-branch '${{ env.REF_NAME }}' \
           --target-branch 'releases/${{ env.MAJOR_VERSION }}' \
@@ -113,7 +113,7 @@ jobs:
       run: |
         echo SOURCE_BRANCH=${SOURCE_BRANCH}
         echo TARGET_BRANCH=${TARGET_BRANCH}
-        python .github/update-release-branch.py \
+        npx tsx ./pr-checks/update-release-branch.ts \
           --repository-nwo ${{ github.repository }} \
           --source-branch ${SOURCE_BRANCH} \
           --target-branch ${TARGET_BRANCH} \

pr-checks/changelog.test.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env npx tsx
+
+/**
+ * Tests for `changelog.ts`.
+ */
+
+import * as assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+  EMPTY_CHANGELOG,
+  getReleaseDateString,
+  processChangelogForBackports,
+  setVersionAndDate,
+} from "./changelog";
+
+const testDate = new Date(2026, 7, 14);
+
+describe("getReleaseDateString", async () => {
+  await it("formats dates as expected", async () => {
+    assert.equal(getReleaseDateString(testDate), "14 Aug 2026");
+  });
+});
+
+const emptyChangelogExpected = `# CodeQL Action Changelog
+
+## 9.99.9 - 14 Aug 2026
+
+No user facing changes.
+
+`;
+
+describe("setVersionAndDate", async () => {
+  await it("replaces the placeholder", async () => {
+    const result = setVersionAndDate("9.99.9", EMPTY_CHANGELOG, testDate);
+    assert.equal(result, emptyChangelogExpected);
+  });
+});
+
+const testChangelog = `# CodeQL Action Changelog
+
+## 4.12.3 - 14 Aug 2026
+
+No user facing changes.
+`;
+
+const testChangelogResult: string = `# CodeQL Action Changelog
+
+## 3.12.3 - 14 Aug 2026
+
+No user facing changes.
+`;
+
+describe("processChangelogForBackports", async () => {
+  await it("replaces major versions", async () => {
+    const result = processChangelogForBackports("4", "3", testChangelog);
+
+    assert.deepEqual(result.split("\n"), testChangelogResult.split("\n"));
+  });
+});

pr-checks/changelog.ts

@@ -0,0 +1,135 @@
+import * as fs from "node:fs";
+
+import { CHANGELOG_FILE, DryRunOption } from "./config";
+
+/** Placeholder changelog content for a new release. */
+export const EMPTY_CHANGELOG = `# CodeQL Action Changelog
+
+## [UNRELEASED]
+
+No user facing changes.
+
+`;
+
+/** Returns `date` formatted as `DD Mon YYYY`. */
+export function getReleaseDateString(today: Date = new Date()): string {
+  return today.toLocaleDateString("en-GB", {
+    day: "2-digit",
+    month: "short",
+    year: "numeric",
+  });
+}
+
+export interface OpenChangelogOptions {
+  initChangelog?: boolean;
+}
+
+export function withChangelog(
+  transformer: (contents: string) => string,
+  options: DryRunOption & OpenChangelogOptions,
+): void {
+  let content: string;
+
+  if (options.initChangelog && !fs.existsSync(CHANGELOG_FILE)) {
+    content = EMPTY_CHANGELOG;
+  } else {
+    content = fs.readFileSync(CHANGELOG_FILE, "utf8");
+  }
+
+  if (!options.dryRun) {
+    fs.writeFileSync(CHANGELOG_FILE, transformer(content), "utf8");
+  } else {
+    console.info(`[DRY RUN] Would have written updated changelog.`);
+  }
+}
+
+/**
+ * Updates the `[UNRELEASED]` marker in `CHANGELOG.md` with the given version
+ * and today's date.
+ */
+export function setVersionAndDate(
+  version: string,
+  content: string,
+  date: Date = new Date(),
+): string {
+  const versionAndDate = `${version} - ${getReleaseDateString(date)}`;
+  return content.replace("[UNRELEASED]", versionAndDate);
+}
+
+/**
+ * Processes changelog entries for a backport, converting version references
+ * from the source major version to the target major version and filtering
+ * entries that only apply to newer versions.
+ */
+export function processChangelogForBackports(
+  sourceBranchMajorVersion: string,
+  targetBranchMajorVersion: string,
+  content: string,
+): string {
+  const lines = content.split("\n");
+
+  // Changelog entries can use the following format to indicate
+  // that they only apply to newer versions
+  const someVersionsOnlyRegex = /\[v(\d+)\+ only\]/;
+
+  let output = "";
+  let i = 0;
+
+  // Copy lines until we find the first section heading.
+  let foundFirstSection = false;
+  while (!foundFirstSection && i < lines.length) {
+    let line = lines[i];
+    if (line.startsWith("## ")) {
+      line = line.replace(
+        `## ${sourceBranchMajorVersion}`,
+        `## ${targetBranchMajorVersion}`,
+      );
+      foundFirstSection = true;
+    }
+    output += `${line}\n`;
+    i++;
+  }
+
+  if (!foundFirstSection) {
+    throw new Error("Could not find any change sections in CHANGELOG.md");
+  }
+
+  // Process remaining lines.
+  // `foundContent` tracks whether we hit two headings in a row
+  let foundContent = false;
+  output += "\n";
+
+  while (i < lines.length) {
+    let line = lines[i];
+    i++;
+
+    // Filter out changelog entries that only apply to newer versions.
+    const match = someVersionsOnlyRegex.exec(line);
+    if (match) {
+      if (
+        Number.parseInt(targetBranchMajorVersion) < Number.parseInt(match[1])
+      ) {
+        continue;
+      }
+    }
+
+    if (line.startsWith("## ")) {
+      line = line.replace(
+        `## ${sourceBranchMajorVersion}`,
+        `## ${targetBranchMajorVersion}`,
+      );
+      if (!foundContent) {
+        output += "No user facing changes.\n";
+      }
+      foundContent = false;
+      output += `\n${line}\n\n`;
+    } else {
+      if (line.trim() !== "") {
+        foundContent = true;
+        output += `${line}\n`;
+      }
+    }
+  }
+
+  return output;
+}

pr-checks/config.ts

@@ -12,6 +12,12 @@ export const REPO_ROOT = path.join(PR_CHECKS_DIR, "..");
 /** The path of the file configuring which checks shouldn't be required. */
 export const PR_CHECK_EXCLUDED_FILE = path.join(PR_CHECKS_DIR, "excluded.yml");
 
+/** The path of the main `package.json`. */
+export const PACKAGE_JSON = path.join(REPO_ROOT, "package.json");
+
+/** The path of the changelog. */
+export const CHANGELOG_FILE = path.join(REPO_ROOT, "CHANGELOG.md");
+
 /** The path to the esbuild metadata file. */
 export const BUNDLE_METADATA_FILE = path.join(REPO_ROOT, "meta.json");
 
@@ -30,3 +36,9 @@ export const API_COMPATIBILITY_FILE = path.join(
   SOURCE_ROOT,
   "api-compatibility.json",
 );
+
+/** A common interface for operations that support dry runs. */
+export interface DryRunOption {
+  /** A value indicating whether to perform operations with side effects. */
+  dryRun?: boolean;
+}