@astra-kit/rp 0.0.0-stage → 0.10.0

package/types/package-manager.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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
+ */
+export type PackageManagerName = "pnpm" | "npm" | "yarn" | "bun";
+export type ProjectCommands = {
+    packageManager: PackageManagerName;
+    runScript: (script: string) => string;
+    createVersion: string;
+};
+/**
+ * @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 declare function parsePackageManagerField(value: unknown): PackageManagerName | 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 declare function detectPackageManager(repositoryRoot: string, manifest?: Record<string, unknown>): PackageManagerName;
+/**
+ * Builds the commands printed or run for a package manager.
+ *
+ * @param {PackageManagerName} packageManager - Package manager.
+ * @returns {ProjectCommands} Commands.
+ */
+export declare function describeProjectCommands(packageManager: PackageManagerName): ProjectCommands;
+/**
+ * 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 declare function describeCreateVersionWithOptions(commands: ProjectCommands): string;
+/** Commands of a pnpm project: the default when a project cannot be inspected. */
+export declare const DEFAULT_PROJECT_COMMANDS: Readonly<ProjectCommands>;

package/types/terminal-ui.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Dependency-free terminal UI for release commands: colors, banner, rounded
+ * boxes, step headers, spinners and the interactive select prompt.
+ *
+ * Colors go through `util.styleText`, which drops ANSI codes automatically
+ * when stdout is not a TTY or `NO_COLOR` is set. Interactive prompts fall
+ * back to their default answer when stdin is not a TTY, so a command never
+ * hangs in a pipe.
+ *
+ * @module terminal-ui
+ */
+import { styleText } from "node:util";
+import { BOX_TONE, INTERRUPTED_EXIT_CODE } from "./constants/terminal-ui.js";
+export type TextFormat = Parameters<typeof styleText>[0];
+export type SelectOption = {
+    label: string;
+    hint?: string;
+    description?: string;
+    value: string;
+};
+/**
+ * Icons shared by status lines, colored once at import. They use Nerd Font
+ * glyphs, so the terminal needs a Nerd Font.
+ */
+export declare const ICON: {
+    success: string;
+    failure: string;
+    warning: string;
+    info: string;
+    pending: string;
+    arrow: string;
+    bullet: string;
+    star: string;
+    rocket: "";
+};
+/**
+ * Returns how long the command has waited for the user's answers.
+ *
+ * @returns {number} Milliseconds spent with a prompt open.
+ */
+export declare function getPromptWaitMs(): number;
+/**
+ * Measures the elapsed time since a start, without the time spent waiting for answers.
+ *
+ * @param {number} startedAt - `Date.now()` when the measured work started.
+ * @param {number} [promptWaitAtStart] - {@link getPromptWaitMs} at that moment.
+ * @returns {number} Active milliseconds.
+ */
+export declare function measureActiveMs(startedAt: number, promptWaitAtStart?: number): number;
+/**
+ * Applies one or more `util.styleText` formats.
+ *
+ * @param {TextFormat} format - Format names such as `"bold"` or `["cyan", "bold"]`.
+ * @param {string} text - Text to style.
+ * @returns {string} Styled text (plain when colors are disabled).
+ */
+export declare function paint(format: TextFormat, text: string): string;
+/**
+ * Measures the visible width of a string, ignoring ANSI codes.
+ *
+ * @param {string} text - Possibly styled text.
+ * @returns {number} Visible column count.
+ */
+export declare function visibleWidth(text: string): number;
+/**
+ * Word-wraps a styled line to a visible width without ever cutting it off:
+ * words move to the next line, continuation lines align after a leading
+ * marker (icon, arrow, bullet or `1.`), styles are closed at each break and
+ * reopened on the next line, and a word longer than the width is split.
+ *
+ * @param {string} text - Possibly styled line.
+ * @param {number} width - Maximum visible width.
+ * @returns {string[]} Lines that each fit in `width` columns.
+ */
+export declare function wrapStyledLine(text: string, width: number): string[];
+/**
+ * Returns the box width for the current terminal.
+ *
+ * @returns {number} Outer width in columns.
+ */
+export declare function resolveBoxWidth(): number;
+/**
+ * Renders a rounded box with an optional title in its top border. Long lines
+ * are word-wrapped, never truncated; a title that does not fit in the border
+ * moves inside the box as its first lines.
+ *
+ * @param {{ title?: string, lines: string[], tone?: TextFormat, width?: number }} options - Box content.
+ * @returns {string} Multi-line box.
+ */
+export declare function renderBox({ title, lines, tone, width }: {
+    title?: string;
+    lines: string[];
+    tone?: TextFormat;
+    width?: number;
+}): string;
+/**
+ * Renders a label/value row aligned for status panels.
+ *
+ * @param {string} icon - Leading icon.
+ * @param {string} label - Left column.
+ * @param {string} value - Right column.
+ * @param {number} [labelWidth] - Width of the label column.
+ * @returns {string} Row.
+ */
+export declare function renderRow(icon: string, label: string, value: string, labelWidth?: number): string;
+/**
+ * Renders the one-line header shown when a release command starts: an
+ * inverted `RELEASE` label, the project name, the published version aligned
+ * to the right and a rule underneath.
+ *
+ * @param {{ projectName: string, publishedLabel: string | null }} options - Header content.
+ * @returns {string} Header.
+ */
+export declare function renderBanner({ projectName, publishedLabel }: {
+    projectName: string;
+    publishedLabel: string | null;
+}): string;
+/**
+ * Renders the header that introduces each executed step: a blank line, the `━━ PASO N/M ━ title ━…`
+ * rule (only the step label in bold) and a blank line that separates it from the step output.
+ *
+ * @param {number} stepNumber - 1-based index.
+ * @param {number} stepCount - Total steps.
+ * @param {string} title - Step title, in regular weight.
+ * @returns {string} Header lines.
+ */
+export declare function renderStepHeader(stepNumber: number, stepCount: number, title: string): string;
+/**
+ * Writes a line to stdout.
+ *
+ * @param {string} [text] - Line content.
+ */
+export declare function print(text?: string): void;
+/**
+ * Formats a duration in a compact Spanish form.
+ *
+ * @param {number} milliseconds - Duration.
+ * @returns {string} Such as `3.2 s` or `4 min 05 s`.
+ */
+export declare function formatDuration(milliseconds: number): string;
+/**
+ * Starts a spinner; on non-TTY outputs it prints the label once instead.
+ *
+ * @param {string} label - Initial label.
+ * @returns {{ update: (label: string) => void, succeed: (label?: string) => void, fail: (label?: string) => void }} Controls.
+ */
+export declare function startSpinner(label: string): {
+    update: (label: string) => void;
+    succeed: (label?: string) => void;
+    fail: (label?: string) => void;
+};
+/**
+ * Counts the terminal rows that lines occupy, including the extra rows of
+ * lines wider than the terminal, so a prompt can erase exactly what it drew.
+ *
+ * @param {string[]} lines - Rendered lines, possibly styled.
+ * @param {number} columns - Terminal width in columns.
+ * @returns {number} Physical rows.
+ */
+export declare function countTerminalRows(lines: string[], columns: number): number;
+/**
+ * Maps a typed character to the option it selects.
+ *
+ * @param {string | undefined} text - Character typed by the user.
+ * @param {number} optionCount - Number of options in the prompt.
+ * @returns {number} Zero-based option index, or -1 when the key does not pick an option.
+ */
+export declare function resolveNumberKey(text: string | undefined, optionCount: number): number;
+/**
+ * Moves the selection of a prompt for a navigation key. Up and `k` go to the previous option;
+ * down, `j` and Tab to the next one, wrapping around. With nothing selected yet, the
+ * first "next" selects the first option and the first "previous" the last one.
+ *
+ * @param {number | null} selectedIndex - Selected option, or `null` when none is.
+ * @param {{ name?: string }} key - Parsed key.
+ * @param {number} optionCount - Number of options in the prompt.
+ * @returns {number | null} New selection; the same one when the key does not navigate.
+ */
+export declare function moveSelection(selectedIndex: number | null, key: {
+    name?: string;
+}, optionCount: number): number | null;
+/**
+ * Asks the user to choose one option: its number picks it right away, or the
+ * arrow keys move the selection and Enter confirms it. With `defaultIndex: null`
+ * nothing starts selected, so Enter does nothing until an option is picked.
+ *
+ * @param {{ message: string, options: SelectOption[], defaultIndex?: number | null }} prompt - Prompt; `description` renders on its own line below the option.
+ * @returns {Promise<string>} Selected value (the default one when stdin is not a TTY).
+ * @throws {Error} When stdin is not a TTY and there is no default option to answer with.
+ */
+export declare function select({ message, options, defaultIndex }: {
+    message: string;
+    options: SelectOption[];
+    defaultIndex?: number | null;
+}): Promise<string>;
+export { BOX_TONE, INTERRUPTED_EXIT_CODE };

package/types/testing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Version bump fixtures for the test suites of every repository that uses
+ * `astra-rp`, so `create-version`, the Vercel build gate and any custom release
+ * command are checked against the same rule: from a stable version only the
+ * next patch, minor or major is allowed.
+ *
+ * @module testing
+ */
+/** Stable version every fixture bumps from. */
+export declare const CURRENT_STABLE_VERSION = "1.2.3";
+/** The only versions allowed after {@link CURRENT_STABLE_VERSION}: next patch, minor and major. */
+export declare const ALLOWED_NEXT_VERSIONS: readonly string[];
+/** Every rejected kind of bump from {@link CURRENT_STABLE_VERSION}, grouped by why it is rejected. */
+export declare const REJECTED_VERSION_BUMPS: Readonly<{
+    unchanged: readonly string[];
+    lower: readonly string[];
+    "skips patches": readonly string[];
+    "skips minors": readonly string[];
+    "skips majors": readonly string[];
+    "minor bump without resetting the patch": readonly string[];
+    "major bump without resetting minor and patch": readonly string[];
+    prerelease: readonly string[];
+    "build metadata": readonly string[];
+    "not a plain X.Y.Z": readonly string[];
+}>;
+/**
+ * All rejected bumps as `[reason, version]` pairs for table-driven tests.
+ *
+ * @type {ReadonlyArray<readonly [string, string]>}
+ */
+export declare const REJECTED_VERSION_BUMP_CASES: ReadonlyArray<readonly [string, string]>;

package/types/version-files.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `versionFiles`: files besides `package.json` that carry the version (a CLI
+ * `--version`, a user agent, a constant) and are rewritten in the release
+ * commit. Only marked lines change:
+ *
+ * - a line with `astra-rp-version` (or release-please's `x-release-please-version`);
+ * - every line between `astra-rp-start-version` and `astra-rp-end` (or
+ *   `x-release-please-start-version` / `x-release-please-end`).
+ *
+ * @module version-files
+ */
+export type VersionFileUpdate = {
+    content: string;
+    markedLines: number;
+    replacements: number;
+};
+export type VersionBlockProblem = "unterminated" | "unopened" | "nested" | "mismatched";
+/**
+ * @typedef {{ content: string, markedLines: number, replacements: number }} VersionFileUpdate
+ *   `markedLines` counts the lines the markers selected; `replacements` the versions rewritten.
+ */
+/**
+ * @typedef {"unterminated" | "unopened" | "nested" | "mismatched"} VersionBlockProblem
+ *   How the block markers are paired wrongly; see `VERSION_BLOCK_PROBLEM`.
+ */
+/**
+ * Version block markers paired wrongly: nothing is rewritten, since guessing where the block ends
+ * could change versions outside the intended section.
+ */
+export declare class VersionBlockError extends Error {
+    problem: VersionBlockProblem;
+    lineNumber: number;
+    marker: string;
+    openingLineNumber: number | undefined;
+    openingMarker: string | undefined;
+    /**
+     * @param {{ problem: VersionBlockProblem, lineNumber: number, marker: string, openingLineNumber?: number, openingMarker?: string }} details
+     *   `lineNumber` (1-based) and `marker` locate the offending marker; `openingLineNumber` and
+     *   `openingMarker` the start marker of the block still open, when there is one.
+     */
+    constructor({ problem, lineNumber, marker, openingLineNumber, openingMarker }: {
+        problem: VersionBlockProblem;
+        lineNumber: number;
+        marker: string;
+        openingLineNumber?: number;
+        openingMarker?: string;
+    });
+}
+/**
+ * Rewrites the versions of the marked lines of a file, keeping everything else (line endings
+ * included) byte for byte. `\n`, `\r\n` and a lone `\r` all end a line.
+ *
+ * @param {string} content - File content.
+ * @param {string} version - Version to write.
+ * @returns {VersionFileUpdate} New content and what the markers selected.
+ * @throws {VersionBlockError} When a block is left open, closed without being opened, opened
+ *   inside another block or closed with the end marker of the other tool.
+ */
+export declare function updateVersionMarkers(content: string, version: string): VersionFileUpdate;

package/types/versions.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Release version rules: only stable `X.Y.Z` versions exist, and after a
+ * version only its next patch, minor or major is allowed (from `1.2.3`:
+ * `1.2.4`, `1.3.0` or `2.0.0`). No version can be skipped, repeated or
+ * lowered, and prereleases or build metadata are never released.
+ *
+ * @module versions
+ */
+export type ReleaseType = "patch" | "minor" | "major";
+export type NextVersion = {
+    releaseType: ReleaseType;
+    version: string;
+};
+/**
+ * @typedef {"patch" | "minor" | "major"} ReleaseType
+ * @typedef {{ releaseType: ReleaseType, version: string }} NextVersion
+ */
+/**
+ * Returns whether a value is a stable `X.Y.Z` release version.
+ *
+ * @param {unknown} version - Candidate version.
+ * @returns {boolean} `true` only for plain `X.Y.Z` without prerelease, metadata, prefix or leading zeros.
+ */
+export declare function isStableReleaseVersion(version: unknown): boolean;
+/**
+ * Parses a stable `X.Y.Z` version.
+ *
+ * @param {string} version - Version such as `0.93.0`.
+ * @returns {[number, number, number]} Major, minor and patch numbers.
+ * @throws {Error} When the version is not a stable release version.
+ */
+export declare function parseReleaseVersion(version: string): [number, number, number];
+/**
+ * Compares two stable `X.Y.Z` versions numerically.
+ *
+ * @param {string} leftVersion - First version.
+ * @param {string} rightVersion - Second version.
+ * @returns {number} Negative when `leftVersion` is lower, `0` when equal, positive when higher.
+ * @throws {Error} When either version is not a stable release version.
+ */
+export declare function compareReleaseVersions(leftVersion: string, rightVersion: string): number;
+/**
+ * Tells whether a stable version is above any semver version, prereleases included: `1.0.0` is
+ * above `1.0.0-beta.1` and `0.9.0`, but not above `1.1.0-beta.1`.
+ *
+ * @param {string} stableVersion - Stable `X.Y.Z` version.
+ * @param {string} otherVersion - Version to compare with, such as the `latest` dist-tag of npm.
+ * @returns {boolean} `true` when `stableVersion` is higher; `false` otherwise or when `otherVersion` is not semver.
+ */
+export declare function isStableVersionAbove(stableVersion: string, otherVersion: string): boolean;
+/**
+ * Returns the highest stable version of a list, ignoring prereleases and invalid entries.
+ *
+ * @param {unknown[]} versions - Versions, such as the ones `npm view <pkg> versions` lists.
+ * @returns {string | null} Highest stable `X.Y.Z` version, or `null` when there is none.
+ */
+export declare function findHighestStableVersion(versions: unknown[]): string | null;
+/**
+ * Returns the next version for a semver release type.
+ *
+ * @param {string} version - Current `X.Y.Z` version.
+ * @param {ReleaseType} releaseType - One of {@link RELEASE_TYPE}.
+ * @returns {string} Next `X.Y.Z` version.
+ * @throws {Error} When the version is not stable or the release type is unknown.
+ */
+export declare function bumpReleaseVersion(version: string, releaseType: ReleaseType): string;
+/**
+ * Lists the only versions allowed after the current one: the next patch,
+ * minor and major. Anything else would skip versions or go backwards.
+ *
+ * @param {string} currentVersion - Current `X.Y.Z` version.
+ * @returns {NextVersion[]} Allowed next versions, patch first.
+ */
+export declare function listNextVersions(currentVersion: string): NextVersion[];
+/**
+ * Lists the versions allowed after any previous semver version. A previous
+ * prerelease is also followed by its own stable release (`1.0.0-beta.1` →
+ * `1.0.0`).
+ *
+ * @param {string} previousVersion - Previous version, stable or prerelease.
+ * @returns {string[] | null} Allowed versions, or `null` when the previous version is not semver.
+ */
+export declare function listAllowedVersionsAfter(previousVersion: string): string[] | null;
+/**
+ * Resolves the version requested through `--bump` or `--set-version`.
+ *
+ * @param {string} currentVersion - Current `X.Y.Z` version.
+ * @param {{ bump: ReleaseType | null, setVersion: string | null }} request - Parsed CLI options.
+ * @returns {NextVersion | null} Requested version, or `null` to ask interactively.
+ * @throws {Error} With a Spanish message when the request is invalid.
+ */
+export declare function resolveRequestedVersion(currentVersion: string, { bump, setVersion }: {
+    bump: ReleaseType | null;
+    setVersion: string | null;
+}): NextVersion | null;
+/**
+ * Builds the Git tag name of a release version.
+ *
+ * @param {string} version - `X.Y.Z` version.
+ * @returns {string} Tag such as `v0.94.0`.
+ */
+export declare function toReleaseTag(version: string): string;
+/**
+ * Returns whether a commit subject is a release bump commit (`0.93.0`).
+ *
+ * @param {string} subject - Commit subject.
+ * @returns {boolean} `true` for version-only subjects.
+ */
+export declare function isReleaseCommitSubject(subject: string): boolean;
+/**
+ * Suggests the semver release type for the commits that will ship.
+ *
+ * Breaking changes suggest `major`; features (conventional `feat` or legacy
+ * imperative subjects such as "Add ...") suggest `minor`; a set made only of
+ * conventional maintenance commits (`fix`, `chore`, `docs`, ...) suggests
+ * `patch`. Unknown legacy subjects suggest `minor`.
+ *
+ * @param {{ subject: string, body?: string }[]} commits - Commits since the last release.
+ * @returns {{ releaseType: ReleaseType, reason: string }} Suggested type and a Spanish explanation.
+ */
+export declare function suggestReleaseType(commits: {
+    subject: string;
+    body?: string;
+}[]): {
+    releaseType: ReleaseType;
+    reason: string;
+};
+/**
+ * Tells whether `preMajorShift` lowers the release levels after `currentVersion`: only when the
+ * option is on and the version is `0.x`, except the `0.0.0` placeholder of a package never released.
+ *
+ * @param {string} currentVersion - Current `X.Y.Z` version.
+ * @param {{ preMajorShift?: boolean }} [options] - Project versioning options.
+ * @returns {boolean} `true` when the release levels move one level down.
+ */
+export declare function isPreMajorShiftActive(currentVersion: string, { preMajorShift }?: {
+    preMajorShift?: boolean;
+}): boolean;
+/**
+ * Suggests the release type of the next version after `currentVersion`: {@link suggestReleaseType},
+ * shifted one level down while the version is `0.x` when `preMajorShift` is on (breaking changes
+ * suggest `minor` and features `patch`, so a suggestion never jumps to `1.0.0`). The first release
+ * of a `0.0.0` package is not shifted.
+ *
+ * @param {{ subject: string, body?: string }[]} commits - Commits since the last release.
+ * @param {string} currentVersion - Current `X.Y.Z` version.
+ * @param {{ preMajorShift?: boolean }} [options] - Project versioning options.
+ * @returns {{ releaseType: ReleaseType, reason: string }} Suggested type and a Spanish explanation.
+ */
+export declare function suggestNextReleaseType(commits: {
+    subject: string;
+    body?: string;
+}[], currentVersion: string, { preMajorShift }?: {
+    preMajorShift?: boolean;
+}): {
+    releaseType: ReleaseType;
+    reason: string;
+};