@astra-kit/rp 0.0.0-stage → 0.10.0

package/src/monorepo/state.js

@@ -0,0 +1,206 @@
+/**
+ * Snapshot of a monorepo release: the repository part shared with the
+ * single-package mode (branch, working tree, `main` versus `origin/main`,
+ * pull request) plus, for every released package, its last release, the
+ * commits waiting to be released under its paths, its changelog and its
+ * published versions.
+ *
+ * Every reader is read-only; the network operations are `git fetch`,
+ * `git ls-remote`, `gh pr view` and the npm lookups.
+ *
+ * @module monorepo/state
+ */
+
+import path from "node:path";
+
+import { RELEASE_REMOTE, REMOTE_MAIN_REF } from "../constants/create-version.js";
+import { UNRELEASED_PLACEHOLDER_VERSION } from "../constants/versions.js";
+import { checkNpmPublishAccess, lookupPublishedVersions } from "../create-version/npm.js";
+import { readJsonManifest } from "../create-version/json.js";
+import { createGitReader, findVersionChangeCommit, listCommits, readPackageVersionAt } from "../create-version/process.js";
+import {
+  checkPackageAccess,
+  lookupPackageVersions,
+  lookupPullRequest,
+  readMigrations,
+  readPackageChangelogState,
+  readRepositorySnapshot,
+} from "../create-version/state.js";
+import { parseMonorepoReleaseSubject } from "./release-commit.js";
+import { formatPackageTag } from "./workspaces.js";
+
+/**
+ * @typedef {import("./workspaces.js").ReleaseUnit} ReleaseUnit
+ * @typedef {import("../create-version/process.js").GitReader} GitReader
+ * @typedef {import("../create-version/process.js").CommitRecord} CommitRecord
+ * @typedef {import("../create-version/npm.js").NpmLookup} NpmLookup
+ * @typedef {import("../create-version/npm.js").NpmAuthCheck} NpmAuthCheck
+ * @typedef {import("../create-version/config.js").MigrationCheck} MigrationCheck
+ * @typedef {{
+ *   sha: string,
+ *   version: string | null,
+ *   subject: string | null,
+ *   tag: string | null,
+ *   tagged: boolean,
+ *   tagOnOrigin: boolean,
+ * }} PackageLastRelease
+ *   Newest commit of `origin/main` that changed the package `version`; `tagged` when its tag points
+ *   at that commit locally, `tagOnOrigin` when `origin` has the tag.
+ * @typedef {{
+ *   unit: ReleaseUnit,
+ *   manifest: Record<string, unknown>,
+ *   releasedVersion: string | null,
+ *   lastRelease: PackageLastRelease | null,
+ *   unreleasedCommits: CommitRecord[],
+ *   changelog: { exists: boolean, entryCount: number, unknownSections: string[], updated: boolean, reason: string | null },
+ *   npm: NpmLookup | null,
+ *   npmAuth: NpmAuthCheck | null,
+ * }} PackageSnapshot
+ * @typedef {import("../create-version/state.js").RepositorySnapshot & {
+ *   headSha: string | null,
+ *   headSubject: string | null,
+ *   packages: PackageSnapshot[],
+ *   migrations: MigrationCheck | null,
+ * }} MonorepoSnapshot
+ */
+
+/**
+ * Lists the tags `origin` has, so pending publications only resume releases whose tag reached it.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @returns {Promise<Set<string>>} Tag names.
+ * @throws {Error} When `origin` cannot be read: an empty set would hide tags that already reached it.
+ */
+async function readRemoteTags(reader) {
+  const output = await reader.tryGit(["ls-remote", "--tags", "--refs", RELEASE_REMOTE]);
+  if (output === null) {
+    throw new Error(
+      `No se pudieron listar los tags de ${RELEASE_REMOTE} (git ls-remote --tags ${RELEASE_REMOTE} falló): sin ellos no se sabe qué releases llegaron a ${RELEASE_REMOTE}. Revisá la conexión y el acceso a ${RELEASE_REMOTE} y volvé a correr el comando.`
+    );
+  }
+  return new Set(
+    output
+      .split("\n")
+      .map((line) => line.trim().split(/\s+/u)[1] ?? "")
+      .filter((ref) => ref.startsWith("refs/tags/"))
+      .map((ref) => ref.slice("refs/tags/".length))
+  );
+}
+
+/**
+ * Finds the last release of a package on a revision: the newest commit that changed its `version`,
+ * unless that version is an untagged `0.0.0` placeholder of a package that was never released.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} revision - Revision such as `origin/main`.
+ * @param {ReleaseUnit} unit - Released package.
+ * @param {string} tagFormat - Tag format.
+ * @param {ReadonlySet<string>} remoteTags - Tags on `origin`.
+ * @returns {Promise<PackageLastRelease | null>} Last release, or `null` without history or when the
+ *   newest version change is the untagged commit that added the package or leaves it at `0.0.0`
+ *   (neither pointed at by the package's own tag nor listed in a `release: …` commit).
+ */
+export async function findLastPackageRelease(reader, revision, unit, tagFormat, remoteTags) {
+  const sha = await findVersionChangeCommit(reader, revision, unit.manifestPath);
+
+  if (!sha) {
+    return null;
+  }
+
+  const version = await readPackageVersionAt(reader, sha, unit.manifestPath);
+  const subject = await reader.tryGit(["log", "-1", "--format=%s", sha]);
+  const tag = version ? formatPackageTag(tagFormat, unit, version) : null;
+  const taggedSha = tag ? await reader.tryGit(["rev-parse", "--verify", "--quiet", `refs/tags/${tag}^{commit}`]) : null;
+  // Only the package's own tag, or a release commit that lists it (its tag may follow an older
+  // tagFormat), makes the commit a release when it adds the package or leaves it at the `0.0.0` placeholder.
+  const listedInReleaseCommit = parseMonorepoReleaseSubject(subject)?.some((release) => release.name === unit.name && release.version === version) ?? false;
+  const releasedHere = taggedSha === sha || listedInReleaseCommit;
+  if (!releasedHere && version === UNRELEASED_PLACEHOLDER_VERSION) {
+    return null;
+  }
+  if (!releasedHere && (await reader.tryGit(["cat-file", "-e", `${sha}^:${unit.manifestPath}`])) === null) {
+    return null;
+  }
+  return { sha, version, subject, tag, tagged: taggedSha === sha, tagOnOrigin: tag !== null && remoteTags.has(tag) };
+}
+
+/**
+ * Gathers the monorepo release snapshot.
+ *
+ * @param {{
+ *   repositoryRoot: string,
+ *   units: readonly ReleaseUnit[],
+ *   tagFormat: string,
+ *   trackNpm?: boolean,
+ *   checkMigrations?: (() => Promise<MigrationCheck> | MigrationCheck) | null,
+ *   onProgress?: (label: string) => void,
+ *   lookupNpm?: typeof lookupPublishedVersions,
+ *   checkNpmAuthFor?: ((snapshot: MonorepoSnapshot) => string[]) | null,
+ *   checkNpmAccess?: typeof checkNpmPublishAccess,
+ *   lookupPullRequestFor?: typeof lookupPullRequest,
+ *   registrySelection?: import("../create-version/registry.js").RegistrySelection,
+ * }} options - Repository, released packages, adapters and progress callback. `checkNpmAuthFor`
+ *   receives the snapshot without credentials and names the packages whose credentials are checked.
+ * @returns {Promise<MonorepoSnapshot>} Snapshot accepted by `buildMonorepoPlan`.
+ */
+export async function collectMonorepoState({
+  repositoryRoot,
+  units,
+  tagFormat,
+  trackNpm = false,
+  checkMigrations = null,
+  onProgress = () => {},
+  lookupNpm = lookupPublishedVersions,
+  checkNpmAuthFor = null,
+  checkNpmAccess = checkNpmPublishAccess,
+  lookupPullRequestFor = lookupPullRequest,
+  registrySelection,
+}) {
+  const reader = createGitReader(repositoryRoot);
+  const repository = await readRepositorySnapshot({ repositoryRoot, reader, onProgress, lookupPullRequestFor });
+  const headSha = await reader.tryGit(["rev-parse", "HEAD"]);
+  const headSubject = await reader.tryGit(["log", "-1", "--format=%s", "HEAD"]);
+  const remoteTags = repository.remoteMainExists ? await readRemoteTags(reader) : new Set();
+
+  /** @type {PackageSnapshot[]} */
+  const packages = [];
+
+  for (const unit of units) {
+    onProgress(`Revisando ${unit.name}`);
+    const manifest = readJsonManifest(repositoryRoot, unit.manifestPath);
+    const releasedVersion = repository.remoteMainExists ? await readPackageVersionAt(reader, REMOTE_MAIN_REF, unit.manifestPath) : null;
+    const lastRelease = repository.remoteMainExists ? await findLastPackageRelease(reader, REMOTE_MAIN_REF, unit, tagFormat, remoteTags) : null;
+    const range = lastRelease ? `${lastRelease.sha}..${REMOTE_MAIN_REF}` : REMOTE_MAIN_REF;
+    const unreleasedCommits = repository.remoteMainExists ? await listCommits(reader, range, unit.changePaths) : [];
+    const packageRoot = path.join(repositoryRoot, unit.directory);
+    const npm = trackNpm ? await lookupPackageVersions(registrySelection, manifest, repositoryRoot, packageRoot, lookupNpm) : null;
+
+    packages.push({
+      unit,
+      manifest,
+      releasedVersion,
+      lastRelease,
+      unreleasedCommits,
+      changelog: await readPackageChangelogState(reader, repositoryRoot, packageRoot, unit.changelogPath, lastRelease?.sha ?? null),
+      npm,
+      npmAuth: null,
+    });
+  }
+
+  if (checkMigrations) {
+    onProgress("Consultando migraciones pendientes");
+  }
+
+  /** @type {MonorepoSnapshot} */
+  const snapshot = { ...repository, headSha, headSubject, packages, migrations: await readMigrations(checkMigrations) };
+  const packagesToCheck = new Set(checkNpmAuthFor?.(snapshot) ?? []);
+
+  for (const packageSnapshot of snapshot.packages) {
+    if (packagesToCheck.has(packageSnapshot.unit.name)) {
+      onProgress(`Verificando las credenciales de npm de ${packageSnapshot.unit.name}`);
+      packageSnapshot.npmAuth = await checkPackageAccess(registrySelection, packageSnapshot.manifest, repositoryRoot, path.join(repositoryRoot, packageSnapshot.unit.directory), checkNpmAccess, packageSnapshot.npm);
+    }
+  }
+
+  return snapshot;
+}

package/src/monorepo/workspaces.js

@@ -0,0 +1,327 @@
+/**
+ * Workspace discovery of the monorepo mode: which packages a repository
+ * holds, which of them are released (every non-`private` one) and which paths
+ * count as changes of each released package.
+ *
+ * A released package changes when its own directory changes, and also when a
+ * `private` workspace package it depends on changes (transitively): internal
+ * packages are usually bundled into their consumers (`noExternal`), so a fix
+ * there ships only through a new release of each consumer.
+ *
+ * @module monorepo/workspaces
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { CHANGELOG_FILE } from "../constants/changelog.js";
+import { PACKAGE_MANIFEST_FILE, PUBLISHED_DEPENDENCY_FIELDS } from "../constants/create-version.js";
+import {
+  DEPENDENCY_FIELDS,
+  TAG_FORMAT_PLACEHOLDER,
+  WORKSPACE_EXCLUSION_PREFIX,
+  WORKSPACE_WILDCARD_SUFFIX,
+  WORKSPACES_PACKAGES,
+} from "../constants/monorepo.js";
+import { isPathInsideRoot } from "../create-version/config.js";
+import { describeError } from "../create-version/errors.js";
+import { isRecord } from "../create-version/json.js";
+import { isStableReleaseVersion } from "../versions.js";
+
+/**
+ * @typedef {{
+ *   name: string,
+ *   directory: string,
+ *   private: boolean,
+ *   version: string | null,
+ *   manifest: Record<string, unknown>,
+ * }} WorkspacePackage
+ *   `directory` is relative to the repository root, with `/` separators.
+ * @typedef {{
+ *   name: string,
+ *   directory: string,
+ *   component: string,
+ *   manifestPath: string,
+ *   changelogPath: string,
+ *   version: string | null,
+ *   changePaths: string[],
+ *   publishedDependencies: string[],
+ * }} ReleaseUnit
+ *   A released package: `component` names its tag, `changePaths` are the Git pathspecs whose commits
+ *   count as its changes (its own directory plus its private workspace dependencies, excluding the
+ *   released packages nested inside it), `publishedDependencies`
+ *   the released packages it installs (they are published first).
+ */
+
+/**
+ * @param {string} relativePath - Path relative to the root.
+ * @returns {string} Same path with `/` separators and no trailing slash.
+ */
+function toPosixPath(relativePath) {
+  return relativePath.split(path.sep).join("/").replace(/\/+$/u, "");
+}
+
+/**
+ * Reads a JSON manifest without throwing.
+ *
+ * @param {string} manifestPath - Absolute path.
+ * @returns {Record<string, unknown> | null} Manifest, or `null` when missing or invalid.
+ */
+function readManifest(manifestPath) {
+  try {
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reads the manifest of a matched workspace directory.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @param {string} directory - Workspace directory relative to the root.
+ * @returns {Record<string, unknown>} Manifest.
+ * @throws {Error} When the manifest is not valid JSON or not an object.
+ */
+function readWorkspaceManifest(repositoryRoot, directory) {
+  const manifestPath = `${directory}/${PACKAGE_MANIFEST_FILE}`;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path.join(repositoryRoot, manifestPath), "utf8"));
+  } catch (error) {
+    throw new Error(`astra-rp create-version: no se pudo leer ${manifestPath}: ${describeError(error)}; corregilo o excluí ese workspace`, { cause: error });
+  }
+  if (!isRecord(parsed)) {
+    throw new Error(`astra-rp create-version: ${manifestPath} no es un objeto JSON; corregilo o excluí ese workspace`);
+  }
+  return parsed;
+}
+
+/**
+ * Reads the workspace patterns the root `package.json` declares (`workspaces` as a list, or as an
+ * object with `packages`, as Yarn and Bun accept).
+ *
+ * @param {Record<string, unknown> | null} rootManifest - Root `package.json`.
+ * @returns {string[]} Patterns.
+ */
+export function readDeclaredWorkspaces(rootManifest) {
+  const workspaces = rootManifest?.workspaces;
+  const patterns = Array.isArray(workspaces) ? workspaces : /** @type {{ packages?: unknown }} */ (workspaces ?? {}).packages;
+  return Array.isArray(patterns) ? patterns.filter((pattern) => typeof pattern === "string") : [];
+}
+
+/**
+ * Expands workspace patterns into package directories. Supported: exact directories
+ * (`packages/cli`), direct children (`packages/*`) and exclusions (`!packages/internal`).
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @param {readonly string[]} patterns - Workspace patterns.
+ * @returns {string[]} Directories relative to the root that hold a `package.json`, sorted.
+ * @throws {Error} When a pattern escapes the repository or uses a glob beyond a trailing `/*`.
+ */
+export function expandWorkspacePatterns(repositoryRoot, patterns) {
+  const included = new Set();
+  const excluded = new Set();
+
+  for (const rawPattern of patterns) {
+    const isExclusion = rawPattern.startsWith(WORKSPACE_EXCLUSION_PREFIX);
+    if (!isPathInsideRoot(isExclusion ? rawPattern.slice(WORKSPACE_EXCLUSION_PREFIX.length) : rawPattern)) {
+      throw new Error(`astra-rp create-version: el patrón de workspace "${rawPattern}" sale del repositorio; usá rutas relativas a la raíz, sin ".." ni rutas absolutas`);
+    }
+    const pattern = toPosixPath(isExclusion ? rawPattern.slice(WORKSPACE_EXCLUSION_PREFIX.length) : rawPattern).replace(/^\.\//u, "");
+    const base = pattern.endsWith(WORKSPACE_WILDCARD_SUFFIX) ? pattern.slice(0, -WORKSPACE_WILDCARD_SUFFIX.length) : pattern;
+
+    if (/[*?{}[\]]/u.test(base)) {
+      throw new Error(`astra-rp create-version: workspace pattern "${rawPattern}" is not supported; use exact directories or a trailing /*`);
+    }
+
+    const directories = pattern.endsWith(WORKSPACE_WILDCARD_SUFFIX)
+      ? existsSync(path.join(repositoryRoot, base))
+        ? readdirSync(path.join(repositoryRoot, base), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => `${base}/${entry.name}`)
+        : []
+      : [base];
+
+    for (const directory of directories) {
+      (isExclusion ? excluded : included).add(directory);
+    }
+  }
+
+  return [...included]
+    .filter((directory) => !excluded.has(directory) && existsSync(path.join(repositoryRoot, directory, PACKAGE_MANIFEST_FILE)))
+    .toSorted();
+}
+
+/**
+ * Lists the workspace packages of a repository.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @param {"workspaces" | readonly string[]} packages - `packages` of the configuration: the root workspaces, or explicit patterns.
+ * @returns {WorkspacePackage[]} Packages with a `name` (private ones without it are skipped), sorted by directory.
+ * @throws {Error} When a matched manifest is malformed, non-private without a `name` or without a stable `X.Y.Z` `version`, no package is found or two packages share a name.
+ */
+export function discoverWorkspacePackages(repositoryRoot, packages) {
+  const patterns = packages === WORKSPACES_PACKAGES ? readDeclaredWorkspaces(readManifest(path.join(repositoryRoot, PACKAGE_MANIFEST_FILE))) : packages;
+  const found = expandWorkspacePatterns(repositoryRoot, patterns).flatMap((directory) => {
+    const manifest = readWorkspaceManifest(repositoryRoot, directory);
+    if (typeof manifest.name !== "string" || manifest.name === "") {
+      if (manifest.private === true) {
+        return [];
+      }
+      throw new Error(`astra-rp create-version: ${directory}/${PACKAGE_MANIFEST_FILE} no tiene "name"; agregale un "name" para publicarlo, o "private": true (o excluí ese workspace) para omitirlo`);
+    }
+    if (manifest.private !== true && !isStableReleaseVersion(manifest.version)) {
+      const currentVersion = manifest.version === undefined ? "no tiene \"version\"" : `tiene "version": ${JSON.stringify(manifest.version)}`;
+      throw new Error(`astra-rp create-version: ${directory}/${PACKAGE_MANIFEST_FILE} ${currentVersion}; un paquete publicado necesita una versión estable X.Y.Z (por ejemplo "0.1.0"), o "private": true (o excluí ese workspace) para omitirlo`);
+    }
+    return [
+      {
+        name: manifest.name,
+        directory,
+        private: manifest.private === true,
+        version: typeof manifest.version === "string" ? manifest.version : null,
+        manifest,
+      },
+    ];
+  });
+
+  if (found.length === 0) {
+    throw new Error(`astra-rp create-version: no workspace package found for packages ${JSON.stringify(packages)}`);
+  }
+
+  const seen = new Map();
+  for (const workspacePackage of found) {
+    if (seen.has(workspacePackage.name)) {
+      throw new Error(`astra-rp create-version: ${workspacePackage.name} is declared in both ${seen.get(workspacePackage.name)} and ${workspacePackage.directory}`);
+    }
+    seen.set(workspacePackage.name, workspacePackage.directory);
+  }
+
+  return found;
+}
+
+/**
+ * Names of the workspace packages a manifest depends on through the given fields.
+ *
+ * @param {Record<string, unknown>} manifest - Package manifest.
+ * @param {readonly string[]} fields - Dependency fields to read.
+ * @param {ReadonlySet<string>} workspaceNames - Names of every workspace package.
+ * @returns {string[]} Workspace dependency names.
+ */
+function listWorkspaceDependencies(manifest, fields, workspaceNames) {
+  return fields
+    .flatMap((field) => Object.keys(/** @type {Record<string, unknown>} */ (manifest[field] ?? {})))
+    .filter((dependencyName, index, all) => workspaceNames.has(dependencyName) && all.indexOf(dependencyName) === index);
+}
+
+/**
+ * Turns the workspace packages into release units: one per non-`private` package.
+ *
+ * @param {readonly WorkspacePackage[]} workspacePackages - Result of {@link discoverWorkspacePackages}.
+ * @returns {ReleaseUnit[]} Released packages, sorted by directory.
+ */
+export function resolveReleaseUnits(workspacePackages) {
+  const byName = new Map(workspacePackages.map((workspacePackage) => [workspacePackage.name, workspacePackage]));
+  const workspaceNames = new Set(byName.keys());
+
+  /**
+   * Directories of the private packages `packageName` depends on, transitively.
+   *
+   * @param {string} packageName - Package whose private dependencies are collected.
+   * @param {Set<string>} visited - Packages already walked (cycles).
+   * @returns {string[]} Directories.
+   */
+  const privateDependencyDirectories = (packageName, visited) => {
+    const workspacePackage = byName.get(packageName);
+    if (!workspacePackage || visited.has(packageName)) {
+      return [];
+    }
+    visited.add(packageName);
+    return listWorkspaceDependencies(workspacePackage.manifest, DEPENDENCY_FIELDS, workspaceNames).flatMap((dependencyName) => {
+      const dependency = /** @type {WorkspacePackage} */ (byName.get(dependencyName));
+      return dependency.private ? [dependency.directory, ...privateDependencyDirectories(dependencyName, visited)] : [];
+    });
+  };
+
+  /**
+   * Git pathspecs whose commits count as changes of a package: its directory and its private
+   * dependencies, minus the released packages nested inside its directory (they release their own commits).
+   *
+   * @param {WorkspacePackage} workspacePackage - Released package.
+   * @param {string[]} dependencyDirectories - Directories of its private dependencies.
+   * @returns {string[]} Git pathspecs.
+   */
+  const listChangePaths = (workspacePackage, dependencyDirectories) => {
+    const nestedExclusions = workspacePackages
+      .filter((nestedPackage) => !nestedPackage.private && nestedPackage.directory.startsWith(`${workspacePackage.directory}/`))
+      .map((nestedPackage) => `:(exclude)${nestedPackage.directory}`);
+    return [...new Set([workspacePackage.directory, ...dependencyDirectories]), ...nestedExclusions];
+  };
+
+  return workspacePackages
+    .filter((workspacePackage) => !workspacePackage.private)
+    .map((workspacePackage) => ({
+      name: workspacePackage.name,
+      directory: workspacePackage.directory,
+      component: workspacePackage.directory.split("/").at(-1) ?? workspacePackage.directory,
+      manifestPath: `${workspacePackage.directory}/${PACKAGE_MANIFEST_FILE}`,
+      changelogPath: `${workspacePackage.directory}/${CHANGELOG_FILE}`,
+      version: workspacePackage.version,
+      changePaths: listChangePaths(workspacePackage, privateDependencyDirectories(workspacePackage.name, new Set())),
+      publishedDependencies: listWorkspaceDependencies(workspacePackage.manifest, PUBLISHED_DEPENDENCY_FIELDS, workspaceNames).filter(
+        (dependencyName) => byName.get(dependencyName)?.private === false
+      ),
+    }));
+}
+
+/**
+ * Orders packages so every one comes after the released packages it installs.
+ *
+ * @template {{ name: string, publishedDependencies: string[] }} T
+ * @param {readonly T[]} units - Packages to publish.
+ * @returns {T[]} Same packages, dependencies first (stable for independent packages).
+ */
+export function sortByPublicationOrder(units) {
+  const byName = new Map(units.map((unit) => [unit.name, unit]));
+  /** @type {T[]} */
+  const ordered = [];
+  const placed = new Set();
+
+  /** @param {T} unit - Package to place after its dependencies. @param {Set<string>} walk - Packages on the current walk (cycles). */
+  const place = (unit, walk) => {
+    if (placed.has(unit.name) || walk.has(unit.name)) {
+      return;
+    }
+    walk.add(unit.name);
+    for (const dependencyName of unit.publishedDependencies) {
+      const dependency = byName.get(dependencyName);
+      if (dependency) {
+        place(dependency, walk);
+      }
+    }
+    placed.add(unit.name);
+    ordered.push(unit);
+  };
+
+  for (const unit of units) {
+    place(unit, new Set());
+  }
+  return ordered;
+}
+
+/**
+ * Builds the Git tag of a package release.
+ *
+ * @param {string} tagFormat - Format with `{version}` and optionally `{component}` / `{name}`.
+ * @param {{ name: string, component: string }} unit - Released package.
+ * @param {string} version - Released version.
+ * @returns {string} Tag such as `widget-v1.2.0`.
+ */
+export function formatPackageTag(tagFormat, unit, version) {
+  return tagFormat
+    .replaceAll(TAG_FORMAT_PLACEHOLDER.version, version)
+    .replaceAll(TAG_FORMAT_PLACEHOLDER.component, unit.component)
+    .replaceAll(TAG_FORMAT_PLACEHOLDER.name, unit.name);
+}

package/src/package-manager.js

@@ -0,0 +1,107 @@
+/**
+ * Detects the package manager of a project and builds the commands astra-rp
+ * prints or runs for it, so a bun, npm or yarn project is told to run its own
+ * commands instead of pnpm ones.
+ *
+ * @module package-manager
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  CREATE_VERSION_SCRIPT,
+  DEFAULT_PACKAGE_MANAGER,
+  LOCKFILE_PACKAGE_MANAGERS,
+  PACKAGE_MANAGER,
+  PACKAGE_MANAGER_FIELD,
+  PACKAGE_MANAGER_FIELD_PATTERN,
+  SCRIPT_RUNNER,
+} from "./constants/package-manager.js";
+import { CREATE_VERSION_FLAG, PACKAGE_MANIFEST_FILE } from "./constants/create-version.js";
+
+/**
+ * @typedef {"pnpm" | "npm" | "yarn" | "bun"} PackageManagerName
+ * @typedef {{
+ *   packageManager: PackageManagerName,
+ *   runScript: (script: string) => string,
+ *   createVersion: string,
+ * }} ProjectCommands
+ *   `runScript("ci")` is the command line that runs a `package.json` script; `createVersion` is how
+ *   the project runs `astra-rp create-version` through its script.
+ */
+
+/**
+ * Reads the package manager a `packageManager` value declares.
+ *
+ * @param {unknown} value - `packageManager` field of `package.json`.
+ * @returns {PackageManagerName | null} Package manager, or `null` when the value is missing or unknown.
+ */
+export function parsePackageManagerField(value) {
+  const match = typeof value === "string" ? PACKAGE_MANAGER_FIELD_PATTERN.exec(value) : null;
+  return match ? /** @type {PackageManagerName} */ (match[1]) : null;
+}
+
+/**
+ * Detects the package manager of a project: the `packageManager` field of its `package.json`,
+ * else its lockfile, else pnpm (the historical default).
+ *
+ * @param {string} repositoryRoot - Project root.
+ * @param {Record<string, unknown>} [manifest] - Its `package.json`, when already read.
+ * @returns {PackageManagerName} Package manager.
+ */
+export function detectPackageManager(repositoryRoot, manifest) {
+  const declared = parsePackageManagerField((manifest ?? readManifest(repositoryRoot))?.[PACKAGE_MANAGER_FIELD]);
+
+  if (declared) {
+    return declared;
+  }
+
+  const lockfile = LOCKFILE_PACKAGE_MANAGERS.find(([fileName]) => existsSync(path.join(repositoryRoot, fileName)));
+  return /** @type {PackageManagerName} */ (lockfile?.[1] ?? DEFAULT_PACKAGE_MANAGER);
+}
+
+/**
+ * Builds the commands printed or run for a package manager.
+ *
+ * @param {PackageManagerName} packageManager - Package manager.
+ * @returns {ProjectCommands} Commands.
+ */
+export function describeProjectCommands(packageManager) {
+  const scriptRunner = SCRIPT_RUNNER[packageManager];
+  return {
+    packageManager,
+    runScript: (script) => `${packageManager} run ${script}`,
+    createVersion: `${scriptRunner} ${CREATE_VERSION_SCRIPT}`,
+  };
+}
+
+/**
+ * Builds the command that runs `create-version` with options. npm reads every option before its
+ * `--` separator as its own configuration (`npm run create-version --retry-ci v1.2.3` forwards only
+ * `v1.2.3`), so npm projects need `npm run create-version -- <opciones>`; pnpm, bun and yarn forward
+ * them as is. Every printed or dispatched command that carries options must start with it.
+ *
+ * @param {ProjectCommands} commands - Project commands.
+ * @returns {string} Command to which the options are appended.
+ */
+export function describeCreateVersionWithOptions(commands) {
+  return commands.packageManager === PACKAGE_MANAGER.npm ? `${commands.createVersion} ${CREATE_VERSION_FLAG.endOfOptions}` : commands.createVersion;
+}
+
+/** Commands of a pnpm project: the default when a project cannot be inspected. */
+export const DEFAULT_PROJECT_COMMANDS = Object.freeze(describeProjectCommands(DEFAULT_PACKAGE_MANAGER));
+
+/**
+ * Reads `package.json` without throwing.
+ *
+ * @param {string} repositoryRoot - Project root.
+ * @returns {Record<string, unknown> | null} Manifest, or `null` when it is missing or invalid.
+ */
+function readManifest(repositoryRoot) {
+  try {
+    return JSON.parse(readFileSync(path.join(repositoryRoot, PACKAGE_MANIFEST_FILE), "utf8"));
+  } catch {
+    return null;
+  }
+}