@versatiles/release-tool 2.5.0 → 2.7.0

package/dist/lib/benchmark.js

@@ -0,0 +1,148 @@
+/**
+ * Performance benchmarking utilities for CLI operations.
+ *
+ * Provides timing measurement and optional logging for tracking
+ * execution duration of key operations.
+ */
+/**
+ * Formats a duration in milliseconds to a human-readable string.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Formatted duration string (e.g., "1.23s", "456ms")
+ */
+export function formatDuration(ms) {
+    if (ms >= 1000) {
+        return `${(ms / 1000).toFixed(2)}s`;
+    }
+    return `${Math.round(ms)}ms`;
+}
+/**
+ * Measures the execution time of a synchronous function.
+ *
+ * @param fn - The function to benchmark
+ * @param options - Optional benchmark configuration
+ * @returns The function result along with timing information
+ *
+ * @example
+ * ```ts
+ * const { result, durationMs } = benchmarkSync(() => {
+ *   return heavyComputation();
+ * }, { label: 'Heavy computation', log: true });
+ * ```
+ */
+export function benchmarkSync(fn, options = {}) {
+    const { label, log = false, logger = console.log } = options;
+    const start = performance.now();
+    const result = fn();
+    const end = performance.now();
+    const durationMs = end - start;
+    const durationFormatted = formatDuration(durationMs);
+    if (log && label) {
+        logger(`[benchmark] ${label}: ${durationFormatted}`);
+    }
+    return { result, durationMs, durationFormatted };
+}
+/**
+ * Measures the execution time of an asynchronous function.
+ *
+ * @param fn - The async function to benchmark
+ * @param options - Optional benchmark configuration
+ * @returns Promise resolving to the function result along with timing information
+ *
+ * @example
+ * ```ts
+ * const { result, durationMs } = await benchmark(async () => {
+ *   return await fetchData();
+ * }, { label: 'API fetch', log: true });
+ * ```
+ */
+export async function benchmark(fn, options = {}) {
+    const { label, log = false, logger = console.log } = options;
+    const start = performance.now();
+    const result = await fn();
+    const end = performance.now();
+    const durationMs = end - start;
+    const durationFormatted = formatDuration(durationMs);
+    if (log && label) {
+        logger(`[benchmark] ${label}: ${durationFormatted}`);
+    }
+    return { result, durationMs, durationFormatted };
+}
+/**
+ * Creates a timer for manual timing control.
+ *
+ * @returns Timer object with start, stop, and elapsed methods
+ *
+ * @example
+ * ```ts
+ * const timer = createTimer();
+ * timer.start();
+ * // ... do work ...
+ * const elapsed = timer.stop();
+ * console.log(`Operation took ${elapsed.durationFormatted}`);
+ * ```
+ */
+export function createTimer() {
+    let startTime = null;
+    let endTime = null;
+    return {
+        start() {
+            startTime = performance.now();
+            endTime = null;
+        },
+        stop() {
+            if (startTime === null) {
+                throw new Error('Timer was not started');
+            }
+            endTime = performance.now();
+            const durationMs = endTime - startTime;
+            return { durationMs, durationFormatted: formatDuration(durationMs) };
+        },
+        elapsed() {
+            if (startTime === null) {
+                return 0;
+            }
+            const end = endTime ?? performance.now();
+            return end - startTime;
+        },
+        isRunning() {
+            return startTime !== null && endTime === null;
+        },
+    };
+}
+/**
+ * Calculates statistics from an array of benchmark durations.
+ *
+ * @param durations - Array of duration values in milliseconds
+ * @returns Statistical summary of the benchmarks
+ *
+ * @example
+ * ```ts
+ * const durations = [100, 150, 120, 130, 110];
+ * const stats = calculateStats(durations);
+ * console.log(`Average: ${stats.avgFormatted}`);
+ * ```
+ */
+export function calculateStats(durations) {
+    if (durations.length === 0) {
+        return {
+            count: 0,
+            totalMs: 0,
+            avgMs: 0,
+            minMs: 0,
+            maxMs: 0,
+            avgFormatted: '0ms',
+        };
+    }
+    const totalMs = durations.reduce((sum, d) => sum + d, 0);
+    const avgMs = totalMs / durations.length;
+    return {
+        count: durations.length,
+        totalMs,
+        avgMs,
+        minMs: Math.min(...durations),
+        maxMs: Math.max(...durations),
+        avgFormatted: formatDuration(avgMs),
+    };
+}
+//# sourceMappingURL=benchmark.js.map

package/dist/lib/changelog.d.ts

@@ -0,0 +1,23 @@
+import { type ParsedCommit } from './git.js';
+/**
+ * Generates a changelog entry for a release from parsed commits.
+ *
+ * @param version - The version being released
+ * @param commits - Array of parsed conventional commits
+ * @param date - The release date (defaults to today)
+ * @returns Formatted changelog entry string
+ */
+export declare function generateChangelogEntry(version: string, commits: ParsedCommit[], date?: Date): string;
+/**
+ * Updates or creates a CHANGELOG.md file with a new release entry.
+ *
+ * @param directory - The project directory containing CHANGELOG.md
+ * @param version - The version being released
+ * @param commits - Array of parsed conventional commits
+ * @param date - The release date (defaults to today)
+ * @returns Object indicating whether the file was created or updated
+ */
+export declare function updateChangelog(directory: string, version: string, commits: ParsedCommit[], date?: Date): {
+    created: boolean;
+    path: string;
+};

package/dist/lib/changelog.js

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { COMMIT_TYPES, groupCommitsByType } from './git.js';
+/**
+ * Generates a changelog entry for a release from parsed commits.
+ *
+ * @param version - The version being released
+ * @param commits - Array of parsed conventional commits
+ * @param date - The release date (defaults to today)
+ * @returns Formatted changelog entry string
+ */
+export function generateChangelogEntry(version, commits, date = new Date()) {
+    const dateStr = date.toISOString().split('T')[0];
+    const reversed = [...commits].reverse();
+    const grouped = groupCommitsByType(reversed);
+    let entry = `## [${version}] - ${dateStr}\n\n`;
+    // Order: breaking changes first, then features, fixes, and others
+    const typeOrder = [
+        'feat',
+        'fix',
+        'perf',
+        'refactor',
+        'docs',
+        'test',
+        'build',
+        'ci',
+        'chore',
+        'style',
+        'revert',
+        'other',
+    ];
+    // Add breaking changes section if any
+    const breakingCommits = reversed.filter((c) => c.breaking);
+    if (breakingCommits.length > 0) {
+        entry += '### Breaking Changes\n\n';
+        for (const commit of breakingCommits) {
+            entry += `- ${commit.description.replace(/\s+/g, ' ')}\n`;
+        }
+        entry += '\n';
+    }
+    // Add grouped commits
+    for (const type of typeOrder) {
+        const typeCommits = grouped.get(type);
+        if (!typeCommits || typeCommits.length === 0)
+            continue;
+        // Skip commits already shown in breaking changes
+        const nonBreaking = typeCommits.filter((c) => !c.breaking);
+        if (nonBreaking.length === 0)
+            continue;
+        const label = type === 'other' ? 'Other Changes' : COMMIT_TYPES[type];
+        entry += `### ${label}\n\n`;
+        for (const commit of nonBreaking) {
+            const scope = commit.scope ? `**${commit.scope}:** ` : '';
+            entry += `- ${scope}${commit.description.replace(/\s+/g, ' ')}\n`;
+        }
+        entry += '\n';
+    }
+    return entry;
+}
+/**
+ * Default changelog header for new CHANGELOG.md files
+ */
+const DEFAULT_CHANGELOG_HEADER = `# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+`;
+/**
+ * Updates or creates a CHANGELOG.md file with a new release entry.
+ *
+ * @param directory - The project directory containing CHANGELOG.md
+ * @param version - The version being released
+ * @param commits - Array of parsed conventional commits
+ * @param date - The release date (defaults to today)
+ * @returns Object indicating whether the file was created or updated
+ */
+export function updateChangelog(directory, version, commits, date = new Date()) {
+    const changelogPath = resolve(directory, 'CHANGELOG.md');
+    const entry = generateChangelogEntry(version, commits, date);
+    let content;
+    let created = false;
+    if (existsSync(changelogPath)) {
+        const existing = readFileSync(changelogPath, 'utf8');
+        // Insert new entry after the header (after the first double newline or at the start if no header)
+        const headerEndIndex = findHeaderEnd(existing);
+        content = existing.slice(0, headerEndIndex) + entry + existing.slice(headerEndIndex);
+    }
+    else {
+        content = DEFAULT_CHANGELOG_HEADER + entry;
+        created = true;
+    }
+    writeFileSync(changelogPath, content);
+    return { created, path: changelogPath };
+}
+/**
+ * Finds the end of the changelog header section.
+ * Looks for patterns like "# Changelog" followed by description text,
+ * ending before the first "## " section header.
+ */
+function findHeaderEnd(content) {
+    // Look for the first version section (## [x.y.z] or ## x.y.z)
+    const versionSectionMatch = content.match(/^## \[?\d+\.\d+\.\d+\]?/m);
+    if (versionSectionMatch?.index !== undefined) {
+        return versionSectionMatch.index;
+    }
+    // If no version section found, look for any ## heading
+    const anySectionMatch = content.match(/^## /m);
+    if (anySectionMatch?.index !== undefined) {
+        return anySectionMatch.index;
+    }
+    // No sections found, append at end (after ensuring trailing newline)
+    return content.endsWith('\n') ? content.length : content.length;
+}
+//# sourceMappingURL=changelog.js.map

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,22 +102,30 @@ 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
-            .map(commit => ({
+            .map((commit) => ({
             sha: commit.sha,
-            version: commit.tag?.match(/^v(\d+\.\d+\.\d+)$/)?.[1],
+            version: commit.tag?.match(/^v(\d+\.\d+\.\d+(?:-[\w.]+)?(?:\+[\w.]+)?)$/)?.[1],
         }))
-            .find(r => r.version);
+            .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⍄\'');
+        const result = await shell.stdout("git log --pretty=format:'⍃%H⍄%s⍄%D⍄'");
         return result
             .split('⍃')
-            .filter(line => line.length > 2)
-            .map(line => {
+            .filter((line) => line.length > 2)
+            .map((line) => {
             const obj = line.split('⍄');
             return {
                 sha: obj[0],
@@ -30,15 +134,23 @@ 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);
+        const start = commits.findIndex((commit) => commit.sha === shaCurrent);
         if (start >= 0)
             commits = commits.slice(start);
-        const end = commits.findIndex(commit => commit.sha === shaLast);
+        const end = commits.findIndex((commit) => commit.sha === shaLast);
         if (end >= 0)
             commits = commits.slice(0, end);
         return commits;