#!/usr/bin/env node
///
// @ts-check
import { execFile as execFileCb, spawn } from 'node:child_process';
import { readFile, writeFile } from 'node:fs/promises';
import path from 'node:path';
import process from 'node:process';
import { parseArgs, promisify } from 'node:util';
const execFile = promisify(execFileCb);
/**
* @typedef {(...args: unknown[]) => void} Announce
*/
/**
* @typedef {object} Context
* @property {Announce} [dryRun]
* @property {Announce} announce
*/
/**
* @typedef {object} NormalizedArgs
* @property {string} bump
* @property {boolean} dryRun
* @property {boolean} force
* @property {boolean} help
* @property {string | undefined} preid
* @property {string | undefined} pushRemote
* @property {string | undefined} releaseBranch
*/
/**
* @typedef {object} PackageJson
* @property {string} name
* @property {string} version
*/
/**
* @typedef {object} PackagePlan
* @property {string} location
* @property {string} packageJsonPath
* @property {string} packageJsonRepoPath
* @property {PackageJson} packageJson
* @property {string} text
* @property {string} desiredVersion
*/
const usage = `Usage: graduate-versions.mjs [options] []
Graduates workspace package versions from prerelease versions to release versions,
then creates package-version tags once no package.json rewrite is needed.
follows the same strategy names as "yarn version ":
major, minor, patch, premajor, preminor, prepatch, prerelease, decline,
or an explicit semver version.
Options:
-f, --force continue across package failures and replace existing tags
-n, --dry-run print planned changes without mutating files or Git state
--preid= prerelease identifier for pre* and prerelease bumps
--push[=] push created tags; defaults to origin when REMOTE is omitted
-h, --help show this help`;
/**
* @param {unknown} error
*/
const errorMessage = error => {
if (error && typeof error === 'object') {
const maybeError = /** @type {{ message?: unknown, stderr?: unknown }} */ (
error
);
const stderr =
typeof maybeError.stderr === 'string' ? maybeError.stderr.trim() : '';
const message =
typeof maybeError.message === 'string'
? maybeError.message
: String(error);
return stderr ? `${message}: ${stderr}` : message;
}
return String(error);
};
/**
* @param {string[]} argv
*/
const normalizePushArgv = argv =>
argv.map(arg => (arg === '--push' ? '--push=origin' : arg));
/**
* @param {string[]} args
* @param {{
* bump?: boolean;
* 'dry-run'?: boolean;
* force?: boolean;
* help?: boolean;
* preid?: string;
* push?: string;
* }} options
* @returns {NormalizedArgs}
*/
const normalizeArgs = (args, options) => {
if (options.help) {
return {
bump: 'decline',
dryRun: false,
force: false,
help: true,
preid: undefined,
pushRemote: undefined,
releaseBranch: undefined,
};
}
if (options.bump) {
throw new Error('--bump has been replaced by required positional ');
}
if (args.length < 1) {
throw new Error('missing required positional argument');
}
if (args.length > 2) {
throw new Error('too many positional arguments');
}
if (options.push === '') {
throw new Error('--push remote must not be empty');
}
if (options.preid === '') {
throw new Error('--preid must not be empty');
}
return {
bump: args[0],
dryRun: options['dry-run'] ?? false,
force: options.force ?? false,
help: false,
preid: options.preid,
pushRemote: options.push,
releaseBranch: args[1],
};
};
/**
* @param {string} command
* @param {string[]} args
* @param {{ cwd?: string }} [options]
*/
const run = async (command, args, options = {}) => {
const { stdout, stderr } = await execFile(command, args, {
cwd: options.cwd,
encoding: 'utf8',
});
return { stdout, stderr };
};
/**
* @param {string} command
* @param {string[]} args
* @param {{ cwd?: string }} [options]
*/
const runInherited = async (command, args, options = {}) => {
await new Promise((resolve, reject) => {
const child = spawn(command, args, {
cwd: options.cwd,
stdio: 'inherit',
});
child.once('error', reject);
child.once(
'exit',
/** @param {number | null} code */ code => {
if (code === 0) {
resolve(undefined);
return;
}
reject(new Error(`${command} exited with status ${code ?? 'unknown'}`));
},
);
});
};
/**
* @param {string} location
*/
const packageJsonRepoPath = location =>
path.posix.join(
location.split(path.sep).join(path.posix.sep),
'package.json',
);
/**
* @param {string} source
* @param {string} text
* @returns {PackageJson}
*/
const parsePackageJson = (source, text) => {
const packageJson = JSON.parse(text);
if (
!packageJson ||
typeof packageJson !== 'object' ||
typeof packageJson.name !== 'string' ||
typeof packageJson.version !== 'string'
) {
throw new Error(`${source} must have string name and version properties`);
}
return {
name: packageJson.name,
version: packageJson.version,
};
};
/**
* @typedef {object} Semver
* @property {number} major
* @property {number} minor
* @property {number} patch
* @property {string[]} prerelease
*/
/**
* @param {string} version
* @returns {Semver}
*/
const parseSemver = version => {
const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-.]+))?$/.exec(version);
if (!match) {
throw new Error(`unsupported semver version: ${version}`);
}
const [, major, minor, patch, prerelease = ''] = match;
return {
major: Number(major),
minor: Number(minor),
patch: Number(patch),
prerelease: prerelease ? prerelease.split('.') : [],
};
};
/**
* @param {Semver} version
*/
const formatSemver = version =>
`${version.major}.${version.minor}.${version.patch}${
version.prerelease.length > 0 ? `-${version.prerelease.join('.')}` : ''
}`;
/**
* @param {string[]} prerelease
* @param {string | undefined} preid
*/
const incrementPrerelease = (prerelease, preid = undefined) => {
if (preid) {
if (prerelease[0] === preid) {
return [preid, ...incrementPrerelease(prerelease.slice(1))];
}
return [preid, '0'];
}
if (prerelease.length === 0) {
return ['0'];
}
const next = [...prerelease];
const last = next.at(-1);
if (last && /^\d+$/.test(last)) {
next[next.length - 1] = `${Number(last) + 1}`;
} else {
next.push('0');
}
return next;
};
/**
* @param {string} version
* @param {string} bump
* @param {string | undefined} [preid]
*/
const nextVersion = (version, bump, preid) => {
if (/^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?$/.test(bump)) {
return formatSemver(parseSemver(bump));
}
const current = parseSemver(version);
const hasPrerelease = current.prerelease.length > 0;
switch (bump) {
case 'decline':
return version;
case 'major':
return formatSemver({
major: current.major + 1,
minor: 0,
patch: 0,
prerelease: [],
});
case 'minor':
return formatSemver({
major: current.major,
minor: current.minor + 1,
patch: 0,
prerelease: [],
});
case 'patch':
return formatSemver({
...current,
patch: hasPrerelease ? current.patch : current.patch + 1,
prerelease: [],
});
case 'premajor':
return formatSemver({
major: current.major + 1,
minor: 0,
patch: 0,
prerelease: incrementPrerelease([], preid),
});
case 'preminor':
return formatSemver({
major: current.major,
minor: current.minor + 1,
patch: 0,
prerelease: incrementPrerelease([], preid),
});
case 'prepatch':
return formatSemver({
...current,
patch: hasPrerelease ? current.patch : current.patch + 1,
prerelease: incrementPrerelease(current.prerelease, preid),
});
case 'prerelease':
return formatSemver({
...current,
patch: hasPrerelease ? current.patch : current.patch + 1,
prerelease: incrementPrerelease(current.prerelease, preid),
});
default:
throw new Error(`unsupported yarn version strategy: ${bump}`);
}
};
/**
* @param {string} left
* @param {string} right
*/
const compareSemver = (left, right) => {
const leftVersion = parseSemver(left);
const rightVersion = parseSemver(right);
for (const key of /** @type {const} */ (['major', 'minor', 'patch'])) {
if (leftVersion[key] > rightVersion[key]) return 1;
if (leftVersion[key] < rightVersion[key]) return -1;
}
if (leftVersion.prerelease.length === 0 && rightVersion.prerelease.length) {
return 1;
}
if (leftVersion.prerelease.length && rightVersion.prerelease.length === 0) {
return -1;
}
for (
let i = 0;
i < Math.max(leftVersion.prerelease.length, rightVersion.prerelease.length);
i += 1
) {
const leftPart = leftVersion.prerelease[i];
const rightPart = rightVersion.prerelease[i];
if (leftPart === undefined) return -1;
if (rightPart === undefined) return 1;
const leftNumeric = /^\d+$/.test(leftPart);
const rightNumeric = /^\d+$/.test(rightPart);
if (leftNumeric && rightNumeric) {
const leftNumber = Number(leftPart);
const rightNumber = Number(rightPart);
if (leftNumber > rightNumber) return 1;
if (leftNumber < rightNumber) return -1;
} else if (leftNumeric !== rightNumeric) {
return leftNumeric ? -1 : 1;
} else if (leftPart > rightPart) {
return 1;
} else if (leftPart < rightPart) {
return -1;
}
}
return 0;
};
/**
* @param {string} left
* @param {string} right
*/
const greaterSemver = (left, right) => {
if (compareSemver(left, right) >= 0) return left;
return right;
};
/**
* @param {string} text
* @param {string} oldVersion
* @param {string} newVersion
* @param {string} source
*/
const replaceVersionProperty = (text, oldVersion, newVersion, source) => {
const packageJson = JSON.parse(text);
if (
!packageJson ||
typeof packageJson !== 'object' ||
typeof packageJson.version !== 'string'
) {
throw new Error(`${source} must have a string version property`);
}
if (packageJson.version !== oldVersion) {
throw new Error(
`${source} planned version ${oldVersion}, but parsed ${packageJson.version}`,
);
}
packageJson.version = newVersion;
return `${JSON.stringify(packageJson, undefined, 2)}\n`;
};
const listWorkspaceLocations = async () => {
const { stdout } = await run('npm', ['query', '.workspace']);
const workspaces = JSON.parse(stdout);
if (!Array.isArray(workspaces)) {
throw new Error('npm query .workspace did not return an array');
}
const locations = workspaces.map(workspace => {
if (!workspace || typeof workspace.location !== 'string') {
throw new Error('workspace entry is missing a string location');
}
return workspace.location;
});
if (locations.length === 0) {
throw new Error('no npm workspaces found; has npm install been run?');
}
return locations;
};
/**
* @param {string} location
* @param {NormalizedArgs} args
* @returns {Promise}
*/
const planPackage = async (location, args) => {
const packageJsonPath = path.join(location, 'package.json');
const packageJsonRepo = packageJsonRepoPath(location);
const text = await readFile(packageJsonPath, 'utf8');
const packageJson = parsePackageJson(packageJsonPath, text);
let desiredVersion = nextVersion(packageJson.version, args.bump, args.preid);
if (args.releaseBranch) {
const { stdout: releasedText } = await run('git', [
'show',
`${args.releaseBranch}:${packageJsonRepo}`,
]);
const releasedPackageJson = parsePackageJson(
`${args.releaseBranch}:${packageJsonRepo}`,
releasedText,
);
if (releasedPackageJson.name !== packageJson.name) {
throw new Error(
`${packageJsonRepo} package name changed from ${releasedPackageJson.name} to ${packageJson.name}`,
);
}
desiredVersion = greaterSemver(
desiredVersion,
nextVersion(releasedPackageJson.version, args.bump, args.preid),
);
}
return {
location,
packageJsonPath,
packageJsonRepoPath: packageJsonRepo,
packageJson,
text,
desiredVersion,
};
};
/**
* @param {{ location: string, error: unknown }[]} failures
* @param {string} phase
*/
const throwFailures = (failures, phase) => {
if (failures.length === 0) {
return;
}
throw new Error(
`${phase} failed for ${failures.length} item(s):\n${failures
.map(({ location, error }) => `- ${location}: ${errorMessage(error)}`)
.join('\n')}`,
);
};
/**
* @param {Context} ctx
* @param {PackagePlan[]} packages
*/
const rewritePackages = async (ctx, packages) => {
for (const pkg of packages) {
const { packageJson, packageJsonPath, text, desiredVersion } = pkg;
ctx.announce(
'Updating',
packageJsonPath,
'from',
packageJson.version,
'to',
desiredVersion,
);
if (!ctx.dryRun) {
await writeFile(
packageJsonPath,
replaceVersionProperty(
text,
packageJson.version,
desiredVersion,
packageJsonPath,
),
);
}
}
};
/**
* @param {Context} ctx
* @param {PackagePlan[]} packages
* @param {boolean} force
*/
const createTags = async (ctx, packages, force) => {
/** @type {string[]} */
const tags = [];
/** @type {{ location: string, error: unknown }[]} */
const failures = [];
for (const pkg of packages) {
const tag = `${pkg.packageJson.name}@${pkg.packageJson.version}`;
tags.push(tag);
ctx.announce('Tagging', tag);
if (ctx.dryRun) {
continue;
}
try {
await runInherited('git', ['tag', ...(force ? ['-f'] : []), tag]);
} catch (error) {
if (!force) {
throw error;
}
failures.push({ location: pkg.location, error });
}
}
throwFailures(failures, 'tagging');
return tags;
};
/**
* @param {Context} ctx
* @param {string[]} tags
* @param {string | undefined} remote
* @param {boolean} force
*/
const pushTags = async (ctx, tags, remote, force) => {
if (!remote) {
return;
}
const refspecs = force
? tags.map(tag => `+refs/tags/${tag}:refs/tags/${tag}`)
: tags;
ctx.announce('Pushing', tags.length, 'tag(s) to', remote);
if (!ctx.dryRun) {
await runInherited('git', ['push', remote, ...refspecs]);
}
};
const main = async () => {
const { values, positionals } = parseArgs({
args: normalizePushArgv(process.argv.slice(2)),
options: {
'dry-run': {
short: 'n',
type: 'boolean',
},
force: {
short: 'f',
type: 'boolean',
},
help: {
short: 'h',
type: 'boolean',
},
preid: {
type: 'string',
},
push: {
type: 'string',
},
},
allowPositionals: true,
});
const parsed = normalizeArgs(positionals, values);
if (parsed.help) {
console.log(usage);
return;
}
/** @type {Announce} */
const log = (...args) => console.log(...args);
/** @type {Announce | undefined} */
const dryRunAnnounce = parsed.dryRun
? (...args) => log('[dry-run]', ...args)
: undefined;
/** @type {Context} */
const ctx = {
dryRun: dryRunAnnounce,
announce: dryRunAnnounce || log,
};
const locations = await listWorkspaceLocations();
/** @type {PackagePlan[]} */
const packages = [];
/** @type {{ location: string, error: unknown }[]} */
const failures = [];
for (const location of locations) {
try {
packages.push(await planPackage(location, parsed));
} catch (error) {
if (!parsed.force) {
throw error;
}
console.error(
'Continuing after package error:',
location,
errorMessage(error),
);
failures.push({ location, error });
}
}
const rewrites = packages.filter(
pkg => pkg.packageJson.version !== pkg.desiredVersion,
);
if (rewrites.length > 0) {
await rewritePackages(ctx, rewrites);
ctx.announce(
'Stopped before tagging because',
rewrites.length,
'package version(s) need to be committed first.',
);
throwFailures(failures, 'planning');
return;
}
throwFailures(failures, 'planning');
const tags = await createTags(ctx, packages, parsed.force);
await pushTags(ctx, tags, parsed.pushRemote, parsed.force);
ctx.announce('Success!');
};
main().catch(error => {
console.error('Failed with error:', error);
process.exitCode ||= 1;
process.exit();
});