From 7ff1344e697524d592bd2e77e370686f99a6b3d1 Mon Sep 17 00:00:00 2001
From: "Michael B. Gale" <mbg@github.com>
Date: Fri, 16 Oct 2026 17:28:08 +0100
Subject: [PATCH] Add `macOSVersion` helper

---
 src/platform.test.ts | 40 +++++++++++++++++++++++++++++++++++++++-
 src/platform.ts      | 29 +++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 1 deletion(-)

diff --git a/src/platform.test.ts b/src/platform.test.ts
index c8a6a7955..803e28b90 100644
--- a/src/platform.test.ts
+++ b/src/platform.test.ts
@@ -1,6 +1,7 @@
 import test from "ava";
 
-import { BundlePlatform, getBundlePlatform } from "./platform";
+import { BundlePlatform, getBundlePlatform, macOSVersion } from "./platform";
+import { initAllState } from "./testing-utils";
 
 for (const [platform, arch, expected] of [
   ["linux", "x64", BundlePlatform.Linux64],
@@ -16,3 +17,40 @@ for (const [platform, arch, expected] of [
     t.is(getBundlePlatform(platform, arch), expected);
   });
 }
+
+const platforms: NodeJS.Platform[] = ["linux", "win32", "freebsd"];
+for (const platform of platforms) {
+  test(`macOSVersion returns undefined on ${platform}`, (t) => {
+    t.is(macOSVersion(initAllState({ platform })), undefined);
+  });
+}
+
+test("macOSVersion returns raw string if semver parsing fails", (t) => {
+  const invalidSemVer = "sealOS-2026";
+  t.is(
+    macOSVersion(
+      initAllState({ platform: "darwin", osRelease: invalidSemVer }),
+    ),
+    invalidSemVer,
+  );
+});
+
+test("macOSVersion returns semver if parsing succeeds", (t) => {
+  const validSemVer = "27.0.1";
+
+  const version = macOSVersion(
+    initAllState({ platform: "darwin", osRelease: validSemVer }),
+  );
+
+  // Check that `version` is not undefined and narrow the type; throws if undefined.
+  if (t.truthy(version)) {
+    // Check that it's also not just a string.
+    t.not(typeof version, "string");
+
+    // Should be an object with the expected properties.
+    t.is(typeof version, "object");
+    t.is(version["major"], 27);
+    t.is(version["minor"], 0);
+    t.is(version["patch"], 1);
+  }
+});
diff --git a/src/platform.ts b/src/platform.ts
index 1cc085d6a..59785d312 100644
--- a/src/platform.ts
+++ b/src/platform.ts
@@ -1,3 +1,7 @@
+import * as semver from "semver";
+
+import type { ActionState } from "./action-common";
+
 /** Platform identifiers used in CodeQL bundle asset names. */
 export enum BundlePlatform {
   Linux64 = "linux64",
@@ -24,3 +28,28 @@ export function getBundlePlatform(
       return undefined;
   }
 }
+
+/**
+ * Tries to determine the version of macOS.
+ *
+ * @returns
+ *  The version as either a semantic version object, the raw version string
+ *  if it is not a semantic version, or `undefined` if we are not on macOS.
+ */
+export function macOSVersion(
+  action: ActionState<["Base"]>,
+): semver.SemVer | string | undefined {
+  // Skip if we are not running on macOS.
+  if (action.platform !== "darwin") {
+    return undefined;
+  }
+
+  // Try to parse the OS version string.
+  const version = semver.parse(action.osRelease);
+
+  if (version === null) {
+    return action.osRelease;
+  }
+
+  return version;
+}