@versatiles/release-tool 2.6.0 → 2.7.0

package/dist/lib/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Error codes for categorizing different types of errors in the release tool.
+ */
+export type VrtErrorCode = 'VALIDATION_ERROR' | 'MARKDOWN_ERROR' | 'GIT_ERROR' | 'RELEASE_ERROR' | 'NOT_IMPLEMENTED';
+/**
+ * Custom error class for the VersaTiles Release Tool.
+ * Provides consistent error handling with categorization via error codes.
+ */
+export declare class VrtError extends Error {
+    readonly code: VrtErrorCode;
+    constructor(message: string, code?: VrtErrorCode);
+}
+/**
+ * Helper function to create a validation error.
+ */
+export declare function validationError(message: string): VrtError;
+/**
+ * Helper function to create a markdown processing error.
+ */
+export declare function markdownError(message: string): VrtError;
+/**
+ * Helper function to create a git operation error.
+ */
+export declare function gitError(message: string): VrtError;
+/**
+ * Helper function to create a release process error.
+ */
+export declare function releaseError(message: string): VrtError;
+/**
+ * Helper function to create a not implemented error.
+ */
+export declare function notImplementedError(feature: string): VrtError;

package/dist/lib/errors.js

@@ -0,0 +1,47 @@
+/**
+ * Custom error class for the VersaTiles Release Tool.
+ * Provides consistent error handling with categorization via error codes.
+ */
+export class VrtError extends Error {
+    code;
+    constructor(message, code = 'VALIDATION_ERROR') {
+        super(message);
+        this.name = 'VrtError';
+        this.code = code;
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, VrtError);
+        }
+    }
+}
+/**
+ * Helper function to create a validation error.
+ */
+export function validationError(message) {
+    return new VrtError(message, 'VALIDATION_ERROR');
+}
+/**
+ * Helper function to create a markdown processing error.
+ */
+export function markdownError(message) {
+    return new VrtError(message, 'MARKDOWN_ERROR');
+}
+/**
+ * Helper function to create a git operation error.
+ */
+export function gitError(message) {
+    return new VrtError(message, 'GIT_ERROR');
+}
+/**
+ * Helper function to create a release process error.
+ */
+export function releaseError(message) {
+    return new VrtError(message, 'RELEASE_ERROR');
+}
+/**
+ * Helper function to create a not implemented error.
+ */
+export function notImplementedError(feature) {
+    return new VrtError(`Not implemented yet: "${feature}"`, 'NOT_IMPLEMENTED');
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/git.d.ts

@@ -1,14 +1,106 @@
+/**
+ * Represents a Git commit with its SHA, message, and optional tag.
+ */
 export interface Commit {
+    /** The full SHA hash of the commit. */
     sha: string;
+    /** The commit message (first line / subject). */
     message: string;
+    /** The tag associated with this commit, if any. */
     tag?: string;
 }
+/**
+ * Conventional commit types and their display labels
+ */
+export declare const COMMIT_TYPES: {
+    readonly feat: "Features";
+    readonly fix: "Bug Fixes";
+    readonly docs: "Documentation";
+    readonly style: "Styles";
+    readonly refactor: "Code Refactoring";
+    readonly perf: "Performance Improvements";
+    readonly test: "Tests";
+    readonly build: "Build System";
+    readonly ci: "CI/CD";
+    readonly chore: "Chores";
+    readonly revert: "Reverts";
+};
+export type CommitType = keyof typeof COMMIT_TYPES;
+/**
+ * Represents a parsed conventional commit
+ */
+export interface ParsedCommit extends Commit {
+    /** The conventional commit type (feat, fix, etc.) */
+    type?: CommitType;
+    /** The scope of the change (e.g., "api" in "feat(api): add endpoint") */
+    scope?: string;
+    /** The commit description without the type/scope prefix */
+    description: string;
+    /** Whether this is a breaking change */
+    breaking: boolean;
+}
+/**
+ * Parses a commit message according to the Conventional Commits specification.
+ * @see https://www.conventionalcommits.org/
+ *
+ * @param commit - The commit to parse
+ * @returns A ParsedCommit with type, scope, description, and breaking change info
+ */
+export declare function parseConventionalCommit(commit: Commit): ParsedCommit;
+/**
+ * Determines the suggested semver bump based on parsed commits.
+ * - Breaking changes -> major
+ * - Features -> minor
+ * - Everything else -> patch
+ *
+ * @param commits - Array of parsed commits
+ * @returns The suggested bump type: 'major', 'minor', or 'patch'
+ */
+export declare function getSuggestedBump(commits: ParsedCommit[]): 'major' | 'minor' | 'patch';
+/**
+ * Groups parsed commits by their type for release notes.
+ *
+ * @param commits - Array of parsed commits
+ * @returns A Map of commit type to array of commits, plus 'other' for non-conventional commits
+ */
+export declare function groupCommitsByType(commits: ParsedCommit[]): Map<string, ParsedCommit[]>;
+/**
+ * Interface for Git operations used by the release tool.
+ */
 export interface Git {
+    /**
+     * Gets the most recent semver tag from the repository.
+     * @returns The SHA and version string of the last tag, or undefined if no semver tags exist.
+     */
     getLastGitHubTag: () => Promise<{
         sha: string;
         version: string;
     } | undefined>;
+    /**
+     * Gets the current (most recent) commit.
+     * @returns The current commit object.
+     */
     getCurrentGitHubCommit: () => Promise<Commit>;
+    /**
+     * Gets all commits between two commit SHAs.
+     * @param shaLast - The older commit SHA (exclusive).
+     * @param shaCurrent - The newer commit SHA (inclusive).
+     * @returns Array of commits between the two SHAs.
+     */
     getCommitsBetween: (shaLast?: string, shaCurrent?: string) => Promise<Commit[]>;
 }
+/**
+ * Creates a Git interface for the specified directory.
+ * Provides methods to query commit history and tags.
+ *
+ * @param cwd - The working directory of the Git repository.
+ * @returns An object with methods to interact with the Git repository.
+ *
+ * @example
+ * ```ts
+ * const git = getGit('/path/to/repo');
+ * const lastTag = await git.getLastGitHubTag();
+ * const commits = await git.getCommitsBetween(lastTag?.sha, 'HEAD');
+ * ```
+ */
 export declare function getGit(cwd: string): Git;

package/dist/lib/git.js

@@ -1,4 +1,100 @@
 import { Shell } from './shell.js';
+/**
+ * Conventional commit types and their display labels
+ */
+export const COMMIT_TYPES = {
+    feat: 'Features',
+    fix: 'Bug Fixes',
+    docs: 'Documentation',
+    style: 'Styles',
+    refactor: 'Code Refactoring',
+    perf: 'Performance Improvements',
+    test: 'Tests',
+    build: 'Build System',
+    ci: 'CI/CD',
+    chore: 'Chores',
+    revert: 'Reverts',
+};
+/**
+ * Parses a commit message according to the Conventional Commits specification.
+ * @see https://www.conventionalcommits.org/
+ *
+ * @param commit - The commit to parse
+ * @returns A ParsedCommit with type, scope, description, and breaking change info
+ */
+export function parseConventionalCommit(commit) {
+    const message = commit.message.trim();
+    // Pattern: type(scope)!: description OR type!: description OR type(scope): description OR type: description
+    // Note: No space allowed before colon per Conventional Commits spec
+    const conventionalPattern = /^(\w+)(?:\(([^)]+)\))?(!)?:\s*(.+)$/;
+    const match = message.match(conventionalPattern);
+    if (!match) {
+        // Not a conventional commit - return with original message as description
+        return {
+            ...commit,
+            description: message,
+            breaking: message.toUpperCase().includes('BREAKING CHANGE'),
+        };
+    }
+    const [, typeStr, scope, breakingMark, description] = match;
+    const type = typeStr.toLowerCase();
+    const isKnownType = type in COMMIT_TYPES;
+    return {
+        ...commit,
+        type: isKnownType ? type : undefined,
+        scope: scope || undefined,
+        description: description.trim(),
+        breaking: breakingMark === '!' || message.toUpperCase().includes('BREAKING CHANGE'),
+    };
+}
+/**
+ * Determines the suggested semver bump based on parsed commits.
+ * - Breaking changes -> major
+ * - Features -> minor
+ * - Everything else -> patch
+ *
+ * @param commits - Array of parsed commits
+ * @returns The suggested bump type: 'major', 'minor', or 'patch'
+ */
+export function getSuggestedBump(commits) {
+    const hasBreaking = commits.some((c) => c.breaking);
+    if (hasBreaking)
+        return 'major';
+    const hasFeature = commits.some((c) => c.type === 'feat');
+    if (hasFeature)
+        return 'minor';
+    return 'patch';
+}
+/**
+ * Groups parsed commits by their type for release notes.
+ *
+ * @param commits - Array of parsed commits
+ * @returns A Map of commit type to array of commits, plus 'other' for non-conventional commits
+ */
+export function groupCommitsByType(commits) {
+    const groups = new Map();
+    for (const commit of commits) {
+        const key = commit.type ?? 'other';
+        const existing = groups.get(key) ?? [];
+        existing.push(commit);
+        groups.set(key, existing);
+    }
+    return groups;
+}
+/**
+ * Creates a Git interface for the specified directory.
+ * Provides methods to query commit history and tags.
+ *
+ * @param cwd - The working directory of the Git repository.
+ * @returns An object with methods to interact with the Git repository.
+ *
+ * @example
+ * ```ts
+ * const git = getGit('/path/to/repo');
+ * const lastTag = await git.getLastGitHubTag();
+ * const commits = await git.getCommitsBetween(lastTag?.sha, 'HEAD');
+ * ```
+ */
 export function getGit(cwd) {
     const shell = new Shell(cwd);
     return {
@@ -6,6 +102,10 @@ export function getGit(cwd) {
         getCurrentGitHubCommit,
         getCommitsBetween,
     };
+    /**
+     * Finds the most recent commit tagged with a semver version (vX.Y.Z format).
+     * Supports pre-release and build metadata suffixes.
+     */
     async function getLastGitHubTag() {
         const commits = await getAllCommits();
         const result = commits
@@ -16,6 +116,10 @@ export function getGit(cwd) {
             .find((r) => r.version);
         return result;
     }
+    /**
+     * Retrieves all commits from the repository's history.
+     * Parses the git log output to extract SHA, message, and tag information.
+     */
     async function getAllCommits() {
         const result = await shell.stdout("git log --pretty=format:'⍃%H⍄%s⍄%D⍄'");
         return result
@@ -30,9 +134,17 @@ export function getGit(cwd) {
             };
         });
     }
+    /**
+     * Returns the most recent commit in the repository.
+     */
     async function getCurrentGitHubCommit() {
         return (await getAllCommits())[0];
     }
+    /**
+     * Gets commits between two SHA hashes.
+     * If shaCurrent is provided, starts from that commit.
+     * If shaLast is provided, stops before that commit.
+     */
     async function getCommitsBetween(shaLast, shaCurrent) {
         let commits = await getAllCommits();
         const start = commits.findIndex((commit) => commit.sha === shaCurrent);

package/dist/lib/log.d.ts

@@ -1,8 +1,65 @@
+/**
+ * Enables or disables verbose logging mode.
+ * When enabled, debug messages will be printed to stderr.
+ *
+ * @param enabled - Whether to enable verbose mode.
+ */
 export declare function setVerbose(enabled: boolean): void;
+/**
+ * Checks if verbose mode is currently enabled.
+ *
+ * @returns `true` if verbose mode is enabled, `false` otherwise.
+ */
 export declare function isVerbose(): boolean;
+/**
+ * Logs a fatal error message and terminates the process.
+ * The message is displayed in bold red text.
+ *
+ * @param text - The error message to display.
+ * @returns Never returns as the process is terminated.
+ */
 export declare function panic(text: string): never;
+/**
+ * Logs a warning message to stderr.
+ * The message is displayed in bold yellow text.
+ *
+ * @param text - The warning message to display.
+ */
 export declare function warn(text: string): void;
+/**
+ * Logs an informational message to stderr.
+ *
+ * @param text - The informational message to display.
+ */
 export declare function info(text: string): void;
+/**
+ * Logs a debug message to stderr if verbose mode is enabled.
+ * The message is displayed in gray text.
+ *
+ * @param text - The debug message to display.
+ */
 export declare function debug(text: string): void;
+/**
+ * Logs an abort message and terminates the process with exit code 1.
+ *
+ * @returns Never returns as the process is terminated.
+ */
 export declare function abort(): never;
+/**
+ * Executes an async operation with progress indication.
+ * Displays a spinner-like message while the operation is in progress,
+ * then shows a success checkmark or failure X based on the result.
+ *
+ * @typeParam T - The return type of the promise.
+ * @param message - The message to display while the operation is running.
+ * @param promise - The promise to await, or a function that returns a promise.
+ * @returns The resolved value of the promise.
+ * @throws Calls `panic()` if the promise rejects, terminating the process.
+ *
+ * @example
+ * ```ts
+ * const result = await check('Fetching data', fetchData());
+ * const result = await check('Processing', async () => processData());
+ * ```
+ */
 export declare function check<T>(message: string, promise: Promise<T> | (() => Promise<T>)): Promise<T>;

package/dist/lib/log.js

@@ -1,29 +1,88 @@
+import { VrtError } from './errors.js';
+/** Internal flag to track verbose mode state. */
 let verboseMode = false;
+/**
+ * Enables or disables verbose logging mode.
+ * When enabled, debug messages will be printed to stderr.
+ *
+ * @param enabled - Whether to enable verbose mode.
+ */
 export function setVerbose(enabled) {
     verboseMode = enabled;
 }
+/**
+ * Checks if verbose mode is currently enabled.
+ *
+ * @returns `true` if verbose mode is enabled, `false` otherwise.
+ */
 export function isVerbose() {
     return verboseMode;
 }
+/**
+ * Logs a fatal error message and terminates the process.
+ * The message is displayed in bold red text.
+ *
+ * @param text - The error message to display.
+ * @returns Never returns as the process is terminated.
+ */
 export function panic(text) {
     process.stderr.write(`\x1b[1;31m! ERROR: ${text}\x1b[0m\n`);
     abort();
 }
+/**
+ * Logs a warning message to stderr.
+ * The message is displayed in bold yellow text.
+ *
+ * @param text - The warning message to display.
+ */
 export function warn(text) {
     process.stderr.write(`\x1b[1;33m! warning: ${text}\x1b[0m\n`);
 }
+/**
+ * Logs an informational message to stderr.
+ *
+ * @param text - The informational message to display.
+ */
 export function info(text) {
     process.stderr.write(`\x1b[0mi ${text}\n`);
 }
+/**
+ * Logs a debug message to stderr if verbose mode is enabled.
+ * The message is displayed in gray text.
+ *
+ * @param text - The debug message to display.
+ */
 export function debug(text) {
     if (verboseMode) {
         process.stderr.write(`\x1b[0;90m  ${text}\x1b[0m\n`);
     }
 }
+/**
+ * Logs an abort message and terminates the process with exit code 1.
+ *
+ * @returns Never returns as the process is terminated.
+ */
 export function abort() {
     info('abort');
     process.exit(1);
 }
+/**
+ * Executes an async operation with progress indication.
+ * Displays a spinner-like message while the operation is in progress,
+ * then shows a success checkmark or failure X based on the result.
+ *
+ * @typeParam T - The return type of the promise.
+ * @param message - The message to display while the operation is running.
+ * @param promise - The promise to await, or a function that returns a promise.
+ * @returns The resolved value of the promise.
+ * @throws Calls `panic()` if the promise rejects, terminating the process.
+ *
+ * @example
+ * ```ts
+ * const result = await check('Fetching data', fetchData());
+ * const result = await check('Processing', async () => processData());
+ * ```
+ */
 export async function check(message, promise) {
     process.stderr.write(`\x1b[0;90m\u2B95 ${message}\x1b[0m`);
     try {
@@ -33,7 +92,10 @@ export async function check(message, promise) {
     }
     catch (error) {
         process.stderr.write(`\r\x1b[0;91m\u2718 ${message}\x1b[0m\n`);
-        panic(error.message);
+        if (error instanceof VrtError) {
+            panic(`[${error.code}] ${error.message}`);
+        }
+        panic(error.message ?? String(error));
     }
 }
 //# sourceMappingURL=log.js.map

package/dist/lib/retry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Options for retry behavior
+ */
+export interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay in milliseconds before first retry (default: 1000) */
+    initialDelayMs?: number;
+    /** Multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelayMs?: number;
+    /** Optional callback called before each retry */
+    onRetry?: (attempt: number, error: Error, nextDelayMs: number) => void;
+}
+/**
+ * Executes an async function with retry logic and exponential backoff.
+ *
+ * @param fn - The async function to execute
+ * @param options - Retry configuration options
+ * @returns The result of the function if successful
+ * @throws The last error encountered after all retries are exhausted
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/lib/retry.js

@@ -0,0 +1,44 @@
+const DEFAULT_OPTIONS = {
+    maxRetries: 3,
+    initialDelayMs: 1000,
+    backoffMultiplier: 2,
+    maxDelayMs: 30000,
+};
+/**
+ * Executes an async function with retry logic and exponential backoff.
+ *
+ * @param fn - The async function to execute
+ * @param options - Retry configuration options
+ * @returns The result of the function if successful
+ * @throws The last error encountered after all retries are exhausted
+ */
+export async function withRetry(fn, options = {}) {
+    const { maxRetries, initialDelayMs, backoffMultiplier, maxDelayMs } = { ...DEFAULT_OPTIONS, ...options };
+    const { onRetry } = options;
+    let lastError;
+    let currentDelay = initialDelayMs;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt < maxRetries) {
+                const nextDelay = Math.min(currentDelay, maxDelayMs);
+                if (onRetry) {
+                    onRetry(attempt + 1, lastError, nextDelay);
+                }
+                await sleep(nextDelay);
+                currentDelay *= backoffMultiplier;
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * Sleep for a specified number of milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=retry.js.map