@astra-kit/rp 0.0.0-stage → 0.10.0

package/types/create-version/state.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Gathers the snapshot consumed by `plan.js`: current branch, uncommitted
+ * changes, `main` compared with `origin/main`, the version and subject of
+ * `HEAD`, the commit of a detached release tag on `origin`, the last release,
+ * the commits waiting to be released, the pull request of a feature branch,
+ * the published versions, the npm credentials (when the plan would publish to
+ * npm) and pending migrations.
+ *
+ * Every reader is read-only; the only network operations are `git fetch`,
+ * `git ls-remote`, `gh pr view`, `npm view`, `npm whoami`, `npm owner ls` and
+ * whatever the project migrations adapter reads.
+ *
+ * @module create-version/state
+ */
+import { checkNpmPublishAccess, lookupPublishedVersions } from "./npm.js";
+export type GitReader = import("./process.js").GitReader;
+export type ReleaseState = import("./plan.js").ReleaseState;
+export type PullRequestSnapshot = import("./plan.js").PullRequestSnapshot;
+export type MigrationCheck = import("./config.js").MigrationCheck;
+export type LastReleaseSnapshot = import("./plan.js").LastReleaseSnapshot;
+export type ReleaseSnapshot = ReleaseState & {
+    packageName: string;
+    releasedVersion: string | null;
+    lastRelease: LastReleaseSnapshot | null;
+};
+/**
+ * Finds the last release on a revision: the newest commit that changed the
+ * top-level `version` of `package.json`. It covers `X.Y.Z` release commits,
+ * other release subjects and projects that bumped versions by hand.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} revision - Revision such as `origin/main`.
+ * @returns {Promise<LastReleaseSnapshot | null>} Last release with its subject and whether its
+ *   `vX.Y.Z` tag points at it, or `null` without history.
+ */
+export declare function findLastRelease(reader: GitReader, revision: string): Promise<LastReleaseSnapshot | null>;
+/**
+ * Looks up the pull request of a branch with the GitHub CLI.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @param {string} branchName - Head branch.
+ * @returns {Promise<{ pullRequest: PullRequestSnapshot | null, githubError: string | null }>} Pull request or error.
+ */
+export declare function lookupPullRequest(repositoryRoot: string, branchName: string): Promise<{
+    pullRequest: PullRequestSnapshot | null;
+    githubError: string | null;
+}>;
+/**
+ * Reads the `[Unreleased]` block of the working-tree CHANGELOG.md.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {{ exists: boolean, entryCount: number, unknownSections: string[] }} Unreleased state.
+ */
+export declare function readChangelogState(repositoryRoot: string): {
+    exists: boolean;
+    entryCount: number;
+    unknownSections: string[];
+};
+/**
+ * Runs the project migrations check, turning any failure into an `unknown` result.
+ *
+ * @param {(() => Promise<MigrationCheck> | MigrationCheck) | null} checkMigrations - Adapter bound to its hook context.
+ * @returns {Promise<MigrationCheck | null>} Migration state, or `null` for projects without migrations.
+ */
+export declare function readMigrations(checkMigrations: (() => Promise<MigrationCheck> | MigrationCheck) | null): Promise<MigrationCheck | null>;
+/**
+ * Lists the published versions on the registry the working-tree manifest publishes to, so the
+ * diagnosis sees the same versions `npm publish` would conflict with.
+ *
+ * @param {typeof lookupPublishedVersions} lookupNpm - npm lookup adapter.
+ * @param {Record<string, unknown>} manifest - Working-tree `package.json`.
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {Promise<import("./npm.js").NpmLookup>} Published versions, or a failed lookup when the registry is invalid
+ *   or npm cannot report it.
+ */
+export declare function lookupNpmOnPublishRegistry(lookupNpm: typeof lookupPublishedVersions, manifest: Record<string, unknown>, repositoryRoot: string): Promise<import("./npm.js").NpmLookup>;
+/**
+ * Lists the published versions of a package for the diagnosis: on the selected registry, or on the
+ * registry the working-tree manifest publishes to when no registry is selected; shared with the monorepo mode.
+ *
+ * @param {import("./registry.js").RegistrySelection | undefined} registrySelection - Selected registry, if any.
+ * @param {Record<string, unknown>} manifest - Working-tree manifest of the package.
+ * @param {string} repositoryRoot - Repository root, where routing and credentials are read.
+ * @param {string} packageRoot - Package directory.
+ * @param {typeof lookupPublishedVersions} lookupNpm - npm lookup adapter.
+ * @returns {Promise<import("./npm.js").NpmLookup>} Published versions, or a failed lookup.
+ */
+export declare function lookupPackageVersions(registrySelection: import("./registry.js").RegistrySelection | undefined, manifest: Record<string, unknown>, repositoryRoot: string, packageRoot: string, lookupNpm: typeof lookupPublishedVersions): Promise<import("./npm.js").NpmLookup>;
+/**
+ * Checks the credentials that would publish a package and confirms a first publication against its
+ * published versions (see {@link confirmFirstPublication}); shared with the monorepo mode.
+ *
+ * @param {import("./registry.js").RegistrySelection | undefined} registrySelection - Selected registry, if any.
+ * @param {Record<string, unknown>} manifest - Working-tree manifest of the package.
+ * @param {string} repositoryRoot - Repository root, where routing and credentials are read.
+ * @param {string} packageRoot - Package directory.
+ * @param {typeof checkNpmPublishAccess} checkNpmAccess - npm credential check adapter.
+ * @param {import("./npm.js").NpmLookup | null} npm - Published versions, or `null` when npm is not tracked.
+ * @returns {Promise<import("./npm.js").NpmAuthCheck>} Credential check.
+ */
+export declare function checkPackageAccess(registrySelection: import("./registry.js").RegistrySelection | undefined, manifest: Record<string, unknown>, repositoryRoot: string, packageRoot: string, checkNpmAccess: typeof checkNpmPublishAccess, npm: import("./npm.js").NpmLookup | null): Promise<import("./npm.js").NpmAuthCheck>;
+/**
+ * Reads the changelog of a package for the diagnosis: its `[Unreleased]` block and whether it was
+ * updated since the last release; shared with the monorepo mode.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} repositoryRoot - Repository root.
+ * @param {string} packageRoot - Package directory holding the changelog.
+ * @param {string} changelogPath - Changelog path relative to the root.
+ * @param {string | null} lastReleaseSha - Commit of the last release, or `null` without one.
+ * @returns {Promise<ReleaseSnapshot["changelog"]>} Changelog state.
+ */
+export declare function readPackageChangelogState(reader: GitReader, repositoryRoot: string, packageRoot: string, changelogPath: string, lastReleaseSha: string | null): Promise<ReleaseSnapshot["changelog"]>;
+/**
+ * Checks the npm credentials on the registry the working-tree manifest publishes to.
+ *
+ * @param {typeof checkNpmPublishAccess} checkAccess - npm credential check adapter.
+ * @param {Record<string, unknown>} manifest - Working-tree `package.json`.
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {Promise<import("./npm.js").NpmAuthCheck>} Check result; an `unknown` one when the registry cannot be resolved.
+ */
+export declare function checkNpmAuthOnPublishRegistry(checkAccess: typeof checkNpmPublishAccess, manifest: Record<string, unknown>, repositoryRoot: string): Promise<import("./npm.js").NpmAuthCheck>;
+/**
+ * Confirms a first publication (`npm owner ls` answered E404) against the versions `npm view`
+ * listed with the same token. Registries hide a private package from users without access, so an
+ * owner E404 only means "new package" when `npm view` does not list versions either: when it does,
+ * the package exists and the token cannot manage it, which blocks like a user that is not an owner.
+ *
+ * @param {import("./npm.js").NpmAuthCheck} npmAuth - Credential check.
+ * @param {import("./npm.js").NpmLookup | null} npm - Published versions, or `null` when npm is not tracked.
+ * @returns {import("./npm.js").NpmAuthCheck} The same check, or a `notOwner` one when the package already has versions.
+ */
+export declare function confirmFirstPublication(npmAuth: import("./npm.js").NpmAuthCheck, npm: import("./npm.js").NpmLookup | null): import("./npm.js").NpmAuthCheck;
+export type RepositorySnapshot = {
+    currentBranch: string | null;
+    workingTreeChanges: string[];
+    branch: import("./plan.js").FeatureBranchSnapshot | null;
+    pullRequest: PullRequestSnapshot | null;
+    githubError: string | null;
+    main: {
+        aheadCommits: import("./process.js").CommitRecord[];
+        behindCount: number;
+    };
+    remoteMainExists: boolean;
+};
+/**
+ * @typedef {{
+ *   currentBranch: string | null,
+ *   workingTreeChanges: string[],
+ *   branch: import("./plan.js").FeatureBranchSnapshot | null,
+ *   pullRequest: PullRequestSnapshot | null,
+ *   githubError: string | null,
+ *   main: { aheadCommits: import("./process.js").CommitRecord[], behindCount: number },
+ *   remoteMainExists: boolean,
+ * }} RepositorySnapshot
+ *   What every release mode reads from Git before looking at packages: the branch and its pull
+ *   request, the working tree and `main` compared with `origin/main`.
+ */
+/**
+ * Fetches `origin` and reads the repository part of the snapshot, shared by the single-package and
+ * the monorepo modes.
+ *
+ * @param {{
+ *   repositoryRoot: string,
+ *   reader: GitReader,
+ *   onProgress: (label: string) => void,
+ *   lookupPullRequestFor: typeof lookupPullRequest,
+ * }} options - Repository, reader, progress callback and pull request adapter.
+ * @returns {Promise<RepositorySnapshot>} Repository snapshot.
+ */
+export declare function readRepositorySnapshot({ repositoryRoot, reader, onProgress, lookupPullRequestFor }: {
+    repositoryRoot: string;
+    reader: GitReader;
+    onProgress: (label: string) => void;
+    lookupPullRequestFor: typeof lookupPullRequest;
+}): Promise<RepositorySnapshot>;
+/**
+ * Gathers the complete release snapshot.
+ *
+ * @param {{
+ *   repositoryRoot: string,
+ *   trackNpm?: boolean,
+ *   checkMigrations?: (() => Promise<MigrationCheck> | MigrationCheck) | null,
+ *   onProgress?: (label: string) => void,
+ *   lookupNpm?: typeof lookupPublishedVersions,
+ *   checkNpmAuth?: ((snapshot: ReleaseSnapshot) => boolean) | null,
+ *   checkNpmAccess?: typeof checkNpmPublishAccess,
+ *   lookupPullRequestFor?: typeof lookupPullRequest,
+ *   registrySelection?: import("./registry.js").RegistrySelection,
+ * }} options - Repository, adapters and progress callback. `checkNpmAuth` receives the snapshot
+ *   without credentials and decides whether the npm credentials are checked (when the plan would publish to npm).
+ * @returns {Promise<ReleaseSnapshot>} Snapshot accepted by `buildReleasePlan`.
+ */
+export declare function collectReleaseState({ repositoryRoot, trackNpm, checkMigrations, onProgress, lookupNpm, checkNpmAuth, checkNpmAccess, lookupPullRequestFor, registrySelection, }: {
+    repositoryRoot: string;
+    trackNpm?: boolean;
+    checkMigrations?: (() => Promise<MigrationCheck> | MigrationCheck) | null;
+    onProgress?: (label: string) => void;
+    lookupNpm?: typeof lookupPublishedVersions;
+    checkNpmAuth?: ((snapshot: ReleaseSnapshot) => boolean) | null;
+    checkNpmAccess?: typeof checkNpmPublishAccess;
+    lookupPullRequestFor?: typeof lookupPullRequest;
+    registrySelection?: import("./registry.js").RegistrySelection;
+}): Promise<ReleaseSnapshot>;

package/types/create-version/strict-utf8.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Strict UTF-8 decoding for files the release rewrites as text.
+ *
+ * @module create-version/strict-utf8
+ */
+/**
+ * Strict UTF-8 decoder: invalid bytes (such as an ISO-8859-1 file) throw instead of turning into
+ * U+FFFD, and a byte order mark is kept as text, so writing the text back never changes other bytes.
+ */
+export declare const STRICT_UTF8_DECODER: import("util").TextDecoder;

package/types/guard-publish.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `prepublishOnly` guard of the packages released with astra-rp: they are published with npm by
+ * `create-version` (run through the project's package manager), which verifies the tarball against
+ * `npm pack --dry-run`, so a `pnpm publish` (or yarn/bun) is blocked.
+ *
+ * The guard only blocks package managers it recognizes. Without a user agent,
+ * or with an unknown one, the publisher cannot be determined and it allows the
+ * publication. It can be bypassed on purpose with `--ignore-scripts`.
+ *
+ * @module guard-publish
+ */
+export type PublishGuardDecision = {
+    allowed: boolean;
+    packageManager: string | null;
+    message: string | null;
+    exitCode: number;
+};
+/**
+ * @typedef {{ allowed: boolean, packageManager: string | null, message: string | null, exitCode: number }} PublishGuardDecision
+ */
+/**
+ * Finds the blocked package manager that runs the publication.
+ *
+ * @param {string | undefined} userAgent - Value of `npm_config_user_agent`.
+ * @returns {string | null} Blocked package manager name, or `null` for npm, unknown or missing user agents.
+ */
+export declare function findBlockedPublishPackageManager(userAgent: string | undefined): string | null;
+/**
+ * Builds the explanation printed when a publication is blocked.
+ *
+ * @param {string} packageManager - Blocked package manager name (pnpm, yarn or bun), which is also
+ *   the one the project uses: the message names its own create-version command.
+ * @returns {string} Message in Spanish with what to run instead.
+ */
+export declare function buildBlockedPublishMessage(packageManager: string): string;
+/**
+ * Decides whether the publication may continue.
+ *
+ * @param {string | undefined} userAgent - Value of `npm_config_user_agent`.
+ * @returns {PublishGuardDecision} Decision, message to print on stderr and exit code.
+ */
+export declare function decidePublishGuard(userAgent: string | undefined): PublishGuardDecision;
+/**
+ * Decides with the user agent of an environment (the current process by default).
+ *
+ * @param {NodeJS.ProcessEnv} [environment] - Environment of the lifecycle script.
+ * @returns {PublishGuardDecision} Decision for its `npm_config_user_agent`.
+ */
+export declare function decidePublishGuardForEnvironment(environment?: NodeJS.ProcessEnv): PublishGuardDecision;

package/types/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@astra-kit/rp`: dependency-free release process.
+ *
+ * - `@astra-kit/rp/versions`: stable `X.Y.Z` rules; only the next patch, minor or major is allowed.
+ * - `@astra-kit/rp/build-gate`: Vercel `ignoreCommand` decision built on those rules.
+ * - `@astra-kit/rp/changelog`: release history generated from Git commits.
+ * - `@astra-kit/rp/guard-publish`: `prepublishOnly` guard that blocks pnpm, yarn and bun publications.
+ * - `@astra-kit/rp/package-manager`: detection of pnpm, bun, npm or yarn and the commands each one runs.
+ * - `@astra-kit/rp/version-files`: rewrites the marked version lines of `versionFiles`.
+ * - `@astra-kit/rp/terminal-ui`: boxes, spinners and prompts for release commands.
+ * - `@astra-kit/rp/testing`: shared version bump fixtures for consumer test suites.
+ * - `@astra-kit/rp/constants`: every constant above, grouped by domain.
+ *
+ * @module @astra-kit/rp
+ */
+export * from "./build-gate.js";
+export * from "./changelog.js";
+export * from "./guard-publish.js";
+export * from "./package-manager.js";
+export * from "./version-files.js";
+export * from "./versions.js";
+export { ICON, countTerminalRows, formatDuration, getPromptWaitMs, measureActiveMs, paint, print, renderBanner, renderBox, renderRow, renderStepHeader, resolveBoxWidth, resolveNumberKey, select, startSpinner, visibleWidth, wrapStyledLine, } from "./terminal-ui.js";
+export * from "./constants/index.js";

package/types/monorepo/plan.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pure planning of a monorepo release. Receives the snapshot of `state.js`
+ * and decides, without touching Git or npm, what is still missing:
+ *
+ * - a new release: the packages with commits under their paths are the
+ *   candidates; the run asks the version of each one (or skips it) before
+ *   verifying manual changelogs, applying migrations, running the checks and creating one release commit with a tag
+ *   per package (which closes the `[Unreleased]` section of every released changelog), prepares, pushes and publishes in dependency order;
+ * - the resume of a local release commit that never reached `origin`, or of
+ *   tagged releases on `origin/main` that npm does not have yet;
+ * - nothing, when no package changed;
+ * - blockers explaining what to fix first.
+ *
+ * @module monorepo/plan
+ */
+export type MonorepoSnapshot = import("./state.js").MonorepoSnapshot;
+export type PackageSnapshot = import("./state.js").PackageSnapshot;
+export type ReleaseCapabilities = import("../create-version/plan.js").ReleaseCapabilities;
+export type ReleasePlanStep = import("../create-version/plan.js").ReleasePlanStep;
+export type ReleaseBlocker = import("../create-version/plan.js").ReleaseBlocker;
+export type ProjectCommands = import("../package-manager.js").ProjectCommands;
+export type PendingPackageRelease = {
+    name: string;
+    version: string;
+    tag: string;
+    commitSha: string;
+    publish: boolean;
+};
+export type MonorepoPlan = {
+    mode: string;
+    steps: ReleasePlanStep[];
+    blockers: ReleaseBlocker[];
+    warnings: string[];
+    candidates: string[];
+    pendingReleases: PendingPackageRelease[];
+};
+/**
+ * Lists the uncommitted changes a run with `--ignore-local-changes` sets aside: every change,
+ * except the package changelogs in a new release (its bump commits them).
+ *
+ * @param {MonorepoSnapshot} state - Snapshot.
+ * @param {string} mode - Planned mode.
+ * @returns {string[]} `git status --porcelain` lines to set aside.
+ */
+export declare function listMonorepoChangesToSetAside(state: MonorepoSnapshot, mode: string): string[];
+/**
+ * Names the packages whose npm credentials the diagnosis checks: the ones the plan could publish.
+ *
+ * @param {MonorepoPlan} plan - Plan built without credentials.
+ * @returns {string[]} Package names.
+ */
+export declare function listPackagesToAuthenticate(plan: MonorepoPlan): string[];
+/**
+ * Decides what is still missing to release the monorepo from `main`.
+ *
+ * @param {MonorepoSnapshot} state - Snapshot gathered by `collectMonorepoState`.
+ * @param {ReleaseCapabilities} capabilities - Steps the project configured.
+ * @param {{ tagFormat: string, ignoreLocalChanges?: boolean, skipUnpublished?: boolean, selectAllPackages?: boolean }} options -
+ *   Tag format and command-line options. `skipUnpublished` allows a new release despite missing publications;
+ *   `selectAllPackages` requires updated changelogs for every candidate because the flags do not allow skips.
+ * @returns {MonorepoPlan} Ordered plan.
+ */
+export declare function buildMonorepoPlan(state: MonorepoSnapshot, capabilities: ReleaseCapabilities, { tagFormat, ignoreLocalChanges, skipUnpublished, selectAllPackages }: {
+    tagFormat: string;
+    ignoreLocalChanges?: boolean;
+    skipUnpublished?: boolean;
+    selectAllPackages?: boolean;
+}): MonorepoPlan;

package/types/monorepo/release-commit.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Subject of the single release commit of a monorepo release:
+ * `release: @scope/a@1.2.0, @scope/b@0.3.1`. It records which packages the
+ * commit released, so a run can resume a local release commit that never
+ * reached `origin`.
+ *
+ * @module monorepo/release-commit
+ */
+export type PackageRelease = {
+    name: string;
+    version: string;
+};
+/**
+ * @typedef {{ name: string, version: string }} PackageRelease
+ */
+/**
+ * Builds the subject of a release commit.
+ *
+ * @param {readonly PackageRelease[]} releases - Released packages, in publication order.
+ * @returns {string} Subject.
+ */
+export declare function buildMonorepoReleaseSubject(releases: readonly PackageRelease[]): string;
+/**
+ * Reads the packages a release commit subject lists.
+ *
+ * @param {string | null | undefined} subject - Commit subject.
+ * @returns {PackageRelease[] | null} Released packages, or `null` when the subject is not a release commit.
+ */
+export declare function parseMonorepoReleaseSubject(subject: string | null | undefined): PackageRelease[] | null;

package/types/monorepo/run.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Monorepo mode of `astra-rp create-version`: diagnoses every released
+ * workspace package, shows the plan and ships one release commit with a tag
+ * per package, then publishes each package in dependency order.
+ *
+ * It reuses the single-package steps that do not depend on the package
+ * (sync of `main`, migrations, checks, local changes, npm credentials,
+ * verified artifacts) and adds the per-package ones. Every step is derived
+ * from the current state, so running the command again after a failure
+ * resumes from the first missing step, including publications that npm never
+ * received: each one is prepared and published from its own release commit.
+ *
+ * @module monorepo/run
+ */
+export type ReleaseUnit = import("./workspaces.js").ReleaseUnit;
+export type MonorepoSnapshot = import("./state.js").MonorepoSnapshot;
+export type PackageSnapshot = import("./state.js").PackageSnapshot;
+export type MonorepoPlan = import("./plan.js").MonorepoPlan;
+export type PendingPackageRelease = import("./plan.js").PendingPackageRelease;
+export type ResolvedCreateVersionConfig = import("../create-version/config.js").ResolvedCreateVersionConfig;
+export type ReleaseOptions = import("../create-version/plan.js").ReleaseOptions;
+export type GitReader = import("../create-version/process.js").GitReader;
+export type ChosenRelease = {
+    unit: ReleaseUnit;
+    snapshot: PackageSnapshot;
+    version: string;
+    tag: string;
+    commitSha: string | null;
+};
+export type MonorepoContext = {
+    repositoryRoot: string;
+    config: ResolvedCreateVersionConfig;
+    state: MonorepoSnapshot;
+    options: ReleaseOptions;
+    reader: GitReader;
+    commands: import("../package-manager.js").ProjectCommands;
+    tagFormat: string;
+    units: ReleaseUnit[];
+    plan: MonorepoPlan;
+    chosen: ChosenRelease[];
+    changelogFiles: import("../create-version/changelog.js").PreservedReleaseFile[];
+    preparedRoots: Set<string>;
+    pushed: boolean;
+    published: {
+        name: string;
+        version: string;
+        registryUrl: string | null;
+        registryLabel?: string;
+        packageName?: string;
+    }[];
+};
+/**
+ * Runs `create-version` in monorepo mode (`packages` in the configuration).
+ *
+ * @param {{
+ *   repositoryRoot: string,
+ *   config: ResolvedCreateVersionConfig,
+ *   options: ReleaseOptions,
+ *   startedAt: number,
+ * }} run - Repository, resolved configuration, command-line options and start time.
+ * @returns {Promise<number>} Exit code.
+ */
+export declare function runMonorepoCreateVersion({ repositoryRoot, config, options: initialOptions, startedAt }: {
+    repositoryRoot: string;
+    config: ResolvedCreateVersionConfig;
+    options: ReleaseOptions;
+    startedAt: number;
+}): Promise<number>;

package/types/monorepo/state.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 { checkNpmPublishAccess, lookupPublishedVersions } from "../create-version/npm.js";
+import { lookupPullRequest } from "../create-version/state.js";
+export type ReleaseUnit = import("./workspaces.js").ReleaseUnit;
+export type GitReader = import("../create-version/process.js").GitReader;
+export type CommitRecord = import("../create-version/process.js").CommitRecord;
+export type NpmLookup = import("../create-version/npm.js").NpmLookup;
+export type NpmAuthCheck = import("../create-version/npm.js").NpmAuthCheck;
+export type MigrationCheck = import("../create-version/config.js").MigrationCheck;
+export type PackageLastRelease = {
+    sha: string;
+    version: string | null;
+    subject: string | null;
+    tag: string | null;
+    tagged: boolean;
+    tagOnOrigin: boolean;
+};
+export type PackageSnapshot = {
+    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;
+};
+export type MonorepoSnapshot = import("../create-version/state.js").RepositorySnapshot & {
+    headSha: string | null;
+    headSubject: string | null;
+    packages: PackageSnapshot[];
+    migrations: MigrationCheck | null;
+};
+/**
+ * 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 declare function findLastPackageRelease(reader: GitReader, revision: string, unit: ReleaseUnit, tagFormat: string, remoteTags: ReadonlySet<string>): Promise<PackageLastRelease | null>;
+/**
+ * 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 declare function collectMonorepoState({ repositoryRoot, units, tagFormat, trackNpm, checkMigrations, onProgress, lookupNpm, checkNpmAuthFor, checkNpmAccess, lookupPullRequestFor, registrySelection, }: {
+    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;
+}): Promise<MonorepoSnapshot>;

package/types/monorepo/workspaces.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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
+ */
+export type WorkspacePackage = {
+    name: string;
+    directory: string;
+    private: boolean;
+    version: string | null;
+    manifest: Record<string, unknown>;
+};
+export type ReleaseUnit = {
+    name: string;
+    directory: string;
+    component: string;
+    manifestPath: string;
+    changelogPath: string;
+    version: string | null;
+    changePaths: string[];
+    publishedDependencies: string[];
+};
+/**
+ * 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 declare function readDeclaredWorkspaces(rootManifest: Record<string, unknown> | null): 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 declare function expandWorkspacePatterns(repositoryRoot: string, patterns: readonly string[]): string[];
+/**
+ * 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 declare function discoverWorkspacePackages(repositoryRoot: string, packages: "workspaces" | readonly string[]): WorkspacePackage[];
+/**
+ * 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 declare function resolveReleaseUnits(workspacePackages: readonly WorkspacePackage[]): ReleaseUnit[];
+/**
+ * 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 declare function sortByPublicationOrder<T extends {
+    name: string;
+    publishedDependencies: string[];
+}>(units: readonly T[]): T[];
+/**
+ * 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 declare function formatPackageTag(tagFormat: string, unit: {
+    name: string;
+    component: string;
+}, version: string): string;