Flesh out node scripts.

scripts/node/utils/node.mjs

@@ -0,0 +1,175 @@
+/**
+ * Utility functions for working with npm packages and versions.
+ *
+ * @import { ExecOptions } from "node:child_process"
+ */
+
+import * as fs from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { $ } from "./commands.mjs";
+
+/**
+ * Find the nearest directory containing both package.json and package-lock.json,
+ * starting from the given directory and walking upward.
+ *
+ * @param {string} start The directory to start searching from.
+ * @returns {Promise<{ packageJSONPath: string, packageLockPath: string }>}
+ * @throws {Error} If no co-located package.json and package-lock.json are found.
+ */
+export async function findNPMPackage(start) {
+    let currentDir = start;
+
+    while (currentDir !== dirname(currentDir)) {
+        const packageJSONPath = join(currentDir, "package.json");
+        const packageLockPath = join(currentDir, "package-lock.json");
+
+        try {
+            await Promise.all([fs.access(packageJSONPath), fs.access(packageLockPath)]);
+            return {
+                packageJSONPath,
+                packageLockPath,
+            };
+        } catch {
+            // Continue searching up the directory tree
+        }
+
+        currentDir = dirname(currentDir);
+    }
+
+    throw new Error(`No co-located package.json and package-lock.json found above ${start}`);
+}
+
+/**
+ * @typedef {object} PackageJSON
+ * @property {string} name
+ * @property {string} version
+ * @property {Record<string, string>} [dependencies]
+ * @property {Record<string, string>} [devDependencies]
+ * @property {Record<string, string>} [peerDependencies]
+ * @property {Record<string, string>} [optionalDependencies]
+ * @property {Record<string, string>} [peerDependenciesMeta]
+ * @property {Record<string, string>} [engines]
+ * @property {Record<string, string>} [devEngines]
+ * @property {string} [packageManager]
+ */
+
+/**
+ * @param {string} jsonPath
+ * @returns {Promise<PackageJSON>}
+ */
+export function loadJSON(jsonPath) {
+    return fs
+        .readFile(jsonPath, "utf-8")
+        .then(JSON.parse)
+        .catch((cause) => {
+            throw new Error(`Failed to load JSON file at ${jsonPath}`, { cause });
+        });
+}
+
+const PackageJSONComparisionFields = /** @type {const} */ ([
+    "name",
+    "dependencies",
+    "devDependencies",
+    "optionalDependencies",
+    "peerDependencies",
+    "peerDependenciesMeta",
+]);
+
+/**
+ * @typedef {typeof PackageJSONComparisionFields[number]} PackageJSONComparisionField
+ */
+
+/**
+ * Extracts only the dependency fields from a package.json object for comparison purposes.
+ *
+ * @param {PackageJSON} data
+ * @returns {Pick<PackageJSON, PackageJSONComparisionField>}
+ */
+export function pluckDependencyFields(data) {
+    /**
+     * @type {Record<string, unknown>}
+     */
+    const result = {};
+
+    for (const field of PackageJSONComparisionFields) {
+        if (data[field]) {
+            result[field] = data[field];
+        }
+    }
+
+    return /** @type {Pick<PackageJSON, PackageJSONComparisionField>} */ (result);
+}
+
+//#region Versioning
+
+/**
+ * Compares two semantic version strings (e.g., "14.17.0").
+ *
+ * @param {string} a The first version string.
+ * @param {string} b The second version string.
+ * @returns {number}
+ */
+export function compareVersions(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i]) return 1;
+        if (pa[i] < pb[i]) return -1;
+    }
+    return 0;
+}
+
+/**
+ * Runs a Node.js command and returns its stdout output as a string.
+ *
+ * @param {TemplateStringsArray} strings
+ * @param  {...unknown} expressions
+ * @returns {(options?: ExecOptions) => Promise<string>}
+ */
+export const node = $.bind("node");
+
+/**
+ * @typedef {object} NPMCommandOptions
+ * @property {boolean} [useCorepack] Whether to prefix the command with "corepack " to use Corepack's shims.
+ * @returns {Promise<string>}
+ */
+
+/**
+ * Runs an npm command and returns its stdout output as a string.
+ *
+ * @param {TemplateStringsArray} strings
+ * @param  {...unknown} expressions
+ * @returns {(options?: ExecOptions & NPMCommandOptions) => Promise<string>}
+ */
+export function npm(strings, ...expressions) {
+    const subcommand = String.raw(strings, ...expressions);
+
+    return ({ useCorepack, ...options } = {}) => {
+        const command = [useCorepack ? "corepack" : "", "npm", subcommand]
+            .filter(Boolean)
+            .join(" ");
+
+        return $`${command}`(options);
+    };
+}
+
+/**
+ * Parses a version range string, stripping any leading >= and normalizing to three parts.
+ * @param {string} range
+ * @returns {{ operator: ">=" | "=", version: string }}
+ */
+export function parseRange(range) {
+    const hasGte = range.startsWith(">=");
+    const raw = hasGte ? range.slice(2) : range;
+    const parts = raw.split(".").map(Number);
+
+    while (parts.length < 3) parts.push(0);
+
+    return {
+        operator: hasGte ? ">=" : "=",
+        version: parts.join("."),
+    };
+}
+
+//#endregion