@versatiles/release-tool 2.5.0 → 2.7.0

package/dist/commands/release-npm.js

@@ -1,34 +1,85 @@
 #!/usr/bin/env npx tsx
 import { readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
 import select from '@inquirer/select';
+import { updateChangelog } from '../lib/changelog.js';
+import { releaseError, validationError } from '../lib/errors.js';
+import { COMMIT_TYPES, getGit, getSuggestedBump, groupCommitsByType, parseConventionalCommit, } from '../lib/git.js';
 import { check, info, panic, warn } from '../lib/log.js';
+import { withRetry } from '../lib/retry.js';
 import { Shell } from '../lib/shell.js';
-import { getGit } from '../lib/git.js';
-import { resolve } from 'path';
-export async function release(directory, branch = 'main') {
+/**
+ * Type guard to validate package.json structure.
+ */
+function isValidPackageJson(pkg) {
+    if (typeof pkg !== 'object' || pkg === null)
+        return false;
+    if (!('version' in pkg) || typeof pkg.version !== 'string')
+        return false;
+    if (!('scripts' in pkg) || typeof pkg.scripts !== 'object' || pkg.scripts === null)
+        return false;
+    return true;
+}
+/**
+ * Executes the npm release process.
+ *
+ * This function performs a complete release workflow:
+ * 1. Validates git state (correct branch, no uncommitted changes)
+ * 2. Pulls latest changes from remote
+ * 3. Verifies npm authentication
+ * 4. Prompts for new version (with suggestion based on conventional commits)
+ * 5. Runs project checks
+ * 6. Updates package.json version
+ * 7. Updates CHANGELOG.md
+ * 8. Publishes to npm (if not private)
+ * 9. Creates git commit and tag
+ * 10. Pushes to remote and creates GitHub release
+ *
+ * @param directory - The project directory containing package.json
+ * @param branch - The git branch to release from (default: 'main')
+ * @param dryRun - If true, simulate the release without making changes
+ * @throws {VrtError} If any step in the release process fails
+ *
+ * @example
+ * ```ts
+ * // Standard release from main branch
+ * await release('/path/to/project');
+ *
+ * // Dry run to preview release
+ * await release('/path/to/project', 'main', true);
+ *
+ * // Release from a different branch
+ * await release('/path/to/project', 'release');
+ * ```
+ */
+export async function release(directory, branch = 'main', dryRun = false) {
     const shell = new Shell(directory);
     const { getCommitsBetween, getCurrentGitHubCommit, getLastGitHubTag } = getGit(directory);
-    info('starting release process');
+    info(dryRun ? 'starting release process (dry-run)' : 'starting release process');
     // git: check if in the correct branch
     const currentBranch = await check('get branch name', shell.stdout('git rev-parse --abbrev-ref HEAD'));
     if (currentBranch !== branch)
         panic(`current branch is "${currentBranch}" but should be "${branch}"`);
     // git: check if no changes
     await check('are all changes committed?', checkThatNoUncommittedChanges());
-    // git: pull
-    await check('git pull', shell.run('git pull -t'));
+    // git: pull (with retry for transient network failures)
+    await check('git pull', withRetry(() => shell.run('git pull -t'), {
+        onRetry: (attempt, error) => warn(`git pull failed (attempt ${attempt}): ${error.message}, retrying...`),
+    }));
     // check package.json
-    const pkg = JSON.parse(readFileSync(resolve(directory, 'package.json'), 'utf8'));
-    if (typeof pkg !== 'object' || pkg === null)
+    const pkgRaw = JSON.parse(readFileSync(resolve(directory, 'package.json'), 'utf8'));
+    if (!isValidPackageJson(pkgRaw))
         panic('package.json is not valid');
-    if (!('version' in pkg) || (typeof pkg.version !== 'string'))
-        panic('package.json is missing "version"');
-    if (!('scripts' in pkg) || (typeof pkg.scripts !== 'object') || (pkg.scripts == null))
-        panic('package.json is missing "scripts"');
-    if (!('check' in pkg.scripts))
+    if (!('check' in pkgRaw.scripts))
         panic('missing npm script "check" in package.json');
-    if (!('prepack' in pkg.scripts))
+    if (!('prepack' in pkgRaw.scripts))
         panic('missing npm script "prepack" in package.json');
+    const pkg = pkgRaw;
+    const isPrivatePackage = pkg.private === true;
+    // npm: verify authentication (skip for private packages)
+    if (!isPrivatePackage) {
+        await check('verify npm authentication', verifyNpmAuth());
+    }
     // get last version
     const tag = await check('get last github tag', getLastGitHubTag());
     const shaLast = tag?.sha;
@@ -38,37 +89,90 @@ export async function release(directory, branch = 'main') {
         warn(`versions differ in package.json (${versionLastPackage}) and last GitHub tag (${versionLastGithub})`);
     // get current sha
     const { sha: shaCurrent } = await check('get current github commit', getCurrentGitHubCommit());
-    // handle version
-    const nextVersion = await getNewVersion(versionLastPackage);
+    // get and parse commits for conventional commit support
+    const commits = await check('get commits since last release', getCommitsBetween(shaLast, shaCurrent));
+    const parsedCommits = commits.map(parseConventionalCommit);
+    // handle version (with suggested bump based on conventional commits)
+    const nextVersion = await getNewVersion(versionLastPackage, parsedCommits);
+    // prepare release notes (grouped by conventional commit type)
+    const releaseNotes = getReleaseNotes(nextVersion, parsedCommits);
+    info('prepared release notes');
+    if (dryRun) {
+        info('Dry-run mode - the following actions would be performed:');
+        info(`  Version: ${versionLastPackage} -> ${nextVersion}`);
+        info('  Release notes:');
+        releaseNotes.split('\n').forEach((line) => info(`    ${line}`));
+        info('  Commands that would be executed:');
+        info('    npm run check');
+        info('    npm i --package-lock-only');
+        info('    Update CHANGELOG.md');
+        if (!isPrivatePackage) {
+            info('    npm publish --access public');
+        }
+        info('    git add .');
+        info(`    git commit -m "v${nextVersion}"`);
+        info(`    git tag -f -a "v${nextVersion}" -m "new release: v${nextVersion}"`);
+        info('    git push --no-verify --follow-tags');
+        info(`    gh release create/edit "v${nextVersion}"`);
+        info('Dry-run complete - no changes were made');
+        return;
+    }
     // test
     await check('run checks', shell.run('npm run check'));
     // update version
     await check('update version', setNextVersion(nextVersion));
-    // prepare release notes
-    const releaseNotes = await check('prepare release notes', getReleaseNotes(nextVersion, shaLast, shaCurrent));
-    if (!('private' in pkg) || !pkg.private) {
-        // npm publish
-        await check('npm publish', shell.runInteractive('npm publish --access public'));
+    // update changelog
+    const changelogResult = updateChangelog(directory, nextVersion, parsedCommits);
+    if (changelogResult.created) {
+        info('created CHANGELOG.md');
+    }
+    else {
+        info('updated CHANGELOG.md');
+    }
+    if (!isPrivatePackage) {
+        // npm publish (with retry for transient network failures)
+        await check('npm publish', withRetry(() => shell.runInteractive('npm publish --access public'), {
+            onRetry: (attempt, error) => warn(`npm publish failed (attempt ${attempt}): ${error.message}, retrying...`),
+        }));
     }
     // git push
     await check('git add', shell.run('git add .'));
     await check('git commit', shell.run(`git commit -m "v${nextVersion}"`, false));
     await check('git tag', shell.run(`git tag -f -a "v${nextVersion}" -m "new release: v${nextVersion}"`));
-    await check('git push', shell.run('git push --no-verify --follow-tags'));
-    // github release
-    const releaseNotesPipe = `echo -e '${releaseNotes.replace(/[^a-z0-9,.?!:_<> -]/gi, c => '\\x' + ('00' + c.charCodeAt(0).toString(16)).slice(-2))}'`;
-    if (await check('check github release', shell.ok('gh release view v' + nextVersion))) {
-        await check('edit release', shell.run(`${releaseNotesPipe} | gh release edit "v${nextVersion}" -F -`));
+    await check('git push', withRetry(() => shell.run('git push --no-verify --follow-tags'), {
+        onRetry: (attempt, error) => warn(`git push failed (attempt ${attempt}): ${error.message}, retrying...`),
+    }));
+    // github release (with retry for transient network failures)
+    const releaseTag = `v${nextVersion}`;
+    if (await check('check github release', shell.ok(`gh release view ${releaseTag}`))) {
+        await check('edit release', withRetry(() => shell.exec('gh', ['release', 'edit', releaseTag, '--notes', releaseNotes]), {
+            onRetry: (attempt, error) => warn(`gh release edit failed (attempt ${attempt}): ${error.message}, retrying...`),
+        }));
     }
     else {
-        await check('create release', shell.run(`${releaseNotesPipe} | gh release create "v${nextVersion}" -F -`));
+        await check('create release', withRetry(() => shell.exec('gh', ['release', 'create', releaseTag, '--notes', releaseNotes]), {
+            onRetry: (attempt, error) => warn(`gh release create failed (attempt ${attempt}): ${error.message}, retrying...`),
+        }));
     }
     info('Finished');
     return;
+    async function verifyNpmAuth() {
+        try {
+            const username = await shell.stdout('npm whoami');
+            if (!username || username.trim().length === 0) {
+                throw releaseError('npm authentication failed: no username returned');
+            }
+            info(`authenticated as npm user: ${username.trim()}`);
+        }
+        catch {
+            throw releaseError('npm authentication required. Please run "npm login" first.\n' +
+                'If you are using a CI environment, ensure NPM_TOKEN is set.');
+        }
+    }
     async function checkThatNoUncommittedChanges() {
         if ((await shell.stdout('git status --porcelain')).length < 3)
             return;
-        throw Error('please commit all changes before releasing');
+        throw releaseError('please commit all changes before releasing');
     }
     async function setNextVersion(version) {
         // set new version in package.json
@@ -78,34 +182,76 @@ export async function release(directory, branch = 'main') {
         // rebuild package.json
         await shell.run('npm i --package-lock-only');
     }
-    async function getReleaseNotes(version, hashLast, hashCurrent) {
-        const commits = await getCommitsBetween(hashLast, hashCurrent);
-        let notes = commits.reverse()
-            .map(commit => '- ' + commit.message.replace(/\s+/g, ' '))
-            .join('\n');
-        notes = `# Release v${version}\n\nchanges:\n${notes}\n\n`;
+    function getReleaseNotes(version, commits) {
+        const reversed = [...commits].reverse();
+        const grouped = groupCommitsByType(reversed);
+        let notes = `# Release v${version}\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) {
+            notes += '## Breaking Changes\n\n';
+            for (const commit of breakingCommits) {
+                notes += `- ${commit.description.replace(/\s+/g, ' ')}\n`;
+            }
+            notes += '\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];
+            notes += `## ${label}\n\n`;
+            for (const commit of nonBreaking) {
+                const scope = commit.scope ? `**${commit.scope}:** ` : '';
+                notes += `- ${scope}${commit.description.replace(/\s+/g, ' ')}\n`;
+            }
+            notes += '\n';
+        }
         return notes;
     }
-    async function getNewVersion(versionPackage) {
-        // ask for new version
-        const choices = [
-            { value: versionPackage },
-            { ...bump(2) },
-            { ...bump(1) },
-            { ...bump(0) }
-        ];
-        const versionNew = (await select({
+    async function getNewVersion(versionPackage, commits) {
+        // Determine suggested bump based on conventional commits
+        const suggestedBump = getSuggestedBump(commits);
+        // choices: [current, patch, minor, major] -> indices [0, 1, 2, 3]
+        const suggestedIndex = suggestedBump === 'major' ? 3 : suggestedBump === 'minor' ? 2 : 1;
+        const choices = [{ value: versionPackage }, { ...bump(2) }, { ...bump(1) }, { ...bump(0) }];
+        // Add recommendation label to suggested version
+        const suggestedChoice = choices[suggestedIndex];
+        if (suggestedChoice && 'name' in suggestedChoice) {
+            suggestedChoice.name += ' (recommended)';
+        }
+        const versionNew = await select({
             message: 'What should be the new version?',
             choices,
-            default: choices[1].value,
-        }));
+            default: suggestedChoice?.value ?? choices[1].value,
+        });
         if (!versionNew)
-            throw Error();
+            throw releaseError('no version selected');
         return versionNew;
         function bump(index) {
-            const p = versionPackage.split('.').map(v => parseInt(v, 10));
+            const p = versionPackage.split('.').map((v) => parseInt(v, 10));
             if (p.length !== 3)
-                throw Error();
+                throw validationError('invalid version format, expected x.y.z');
             switch (index) {
                 case 0:
                     p[0]++;
@@ -120,7 +266,7 @@ export async function release(directory, branch = 'main') {
                     p[2]++;
                     break;
             }
-            const name = p.map((n, i) => (i == index) ? `\x1b[1m${n}` : `${n}`).join('.') + '\x1b[22m';
+            const name = p.map((n, i) => (i == index ? `\x1b[1m${n}` : `${n}`)).join('.') + '\x1b[22m';
             const value = p.join('.');
             return { name, value };
         }

package/dist/index.js

@@ -11,6 +11,7 @@ import { upgradeDependencies } from './commands/deps-upgrade.js';
 import { generateDependencyGraph } from './commands/deps-graph.js';
 import { check } from './commands/check.js';
 import { generateTypescriptDocs } from './commands/doc-typescript.js';
+import { setVerbose } from './lib/log.js';
 /**
  * Main CLI program, configured with custom text styling for titles, commands, options, etc.
  */
@@ -26,12 +27,19 @@ program.configureHelp({
 });
 program
     .name('vrt')
-    .description('CLI tool for releasing packages and generating documentation for Node.js/TypeScript projects.');
+    .description('CLI tool for releasing packages and generating documentation for Node.js/TypeScript projects.')
+    .option('-v, --verbose', 'Enable verbose output')
+    .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.verbose)
+        setVerbose(true);
+});
 /**
  * Command: check-package
  * Checks that the project's package.json includes certain required scripts/fields.
  */
-program.command('check')
+program
+    .command('check')
     .description('Check repo for required scripts and other stuff.')
     .action(() => {
     void check(process.cwd());
@@ -40,7 +48,8 @@ program.command('check')
  * Command: deps-graph
  * Analyzes the project’s files to produce a dependency graph (in Mermaid format).
  */
-program.command('deps-graph')
+program
+    .command('deps-graph')
     .description('Analyze project files and output a dependency graph as Mermaid markup.')
     .action(() => {
     void generateDependencyGraph(process.cwd());
@@ -49,7 +58,8 @@ program.command('deps-graph')
  * Command: deps-upgrade
  * Upgrades project dependencies in package.json to their latest versions and reinstalls them.
  */
-program.command('deps-upgrade')
+program
+    .command('deps-upgrade')
     .description('Upgrade all dependencies in the current project to their latest versions.')
     .action(() => {
     void upgradeDependencies(process.cwd());
@@ -58,7 +68,8 @@ program.command('deps-upgrade')
  * Command: doc-command
  * Generates Markdown documentation for a given CLI command.
  */
-program.command('doc-command')
+program
+    .command('doc-command')
     .description('Generate Markdown documentation for a specified command and output the result.')
     .argument('<command>', 'Command to document (e.g., "npm run build").')
     .action(async (command) => {
@@ -70,7 +81,8 @@ program.command('doc-command')
  * Inserts Markdown content from stdin into a specified Markdown file under a given heading.
  * Optionally makes the inserted content foldable.
  */
-program.command('doc-insert')
+program
+    .command('doc-insert')
     .description('Insert Markdown from stdin into a specified section of a Markdown file.')
     .argument('<readme>', 'Path to the target Markdown file (e.g., README.md).', checkFilename)
     .argument('[heading]', 'Heading in the Markdown file where content should be placed. Default is "# API".', '# API')
@@ -80,8 +92,7 @@ program.command('doc-insert')
     for await (const data of process.stdin) {
         buffers.push(data);
     }
-    const mdContent = '<!--- This chapter is generated automatically --->\n'
-        + Buffer.concat(buffers).toString();
+    const mdContent = '<!--- This chapter is generated automatically --->\n' + Buffer.concat(buffers).toString();
     let mdFile = readFileSync(mdFilename, 'utf8');
     mdFile = injectMarkdown(mdFile, mdContent, heading, foldable);
     writeFileSync(mdFilename, mdFile);
@@ -90,7 +101,8 @@ program.command('doc-insert')
  * Command: doc-toc
  * Updates or generates a Table of Contents in a Markdown file under a specified heading.
  */
-program.command('doc-toc')
+program
+    .command('doc-toc')
     .description('Generate a Table of Contents (TOC) in a Markdown file.')
     .argument('<readme>', 'Path to the Markdown file (e.g., README.md).', checkFilename)
     .argument('[heading]', 'Heading in the Markdown file where TOC should be inserted. Default is "# Table of Content".', '# Table of Content')
@@ -104,7 +116,8 @@ program.command('doc-toc')
  * Generates documentation for a TypeScript project.
  * Allows specifying entry point and output location.
  */
-program.command('doc-typescript')
+program
+    .command('doc-typescript')
     .description('Generate documentation for a TypeScript project.')
     .option('-i, --input <entryPoint>', 'Entry point of the TypeScript project. Default is "./src/index.ts".')
     .option('-o, --output <outputPath>', 'Output path for the generated documentation. Default is "./docs".')
@@ -116,11 +129,13 @@ program.command('doc-typescript')
  * Command: release-npm
  * Releases/publishes an npm package from a specified project path to the npm registry.
  */
-program.command('release-npm')
+program
+    .command('release-npm')
     .description('Publish an npm package from the specified path to the npm registry.')
+    .option('-n, --dry-run', 'Show what would be done without making any changes')
     .argument('[path]', 'Root path of the Node.js project. Defaults to the current directory.')
-    .action((path) => {
-    void release(resolve(path ?? '.', process.cwd()), 'main');
+    .action((path, options) => {
+    void release(resolve(process.cwd(), path ?? '.'), 'main', options.dryRun ?? false);
 });
 if (process.env.NODE_ENV !== 'test') {
     await program.parseAsync();

package/dist/lib/benchmark.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Performance benchmarking utilities for CLI operations.
+ *
+ * Provides timing measurement and optional logging for tracking
+ * execution duration of key operations.
+ */
+/**
+ * Result of a benchmarked operation
+ */
+export interface BenchmarkResult<T> {
+    /** The result returned by the benchmarked function */
+    result: T;
+    /** Execution duration in milliseconds */
+    durationMs: number;
+    /** Human-readable duration string */
+    durationFormatted: string;
+}
+/**
+ * Options for benchmark execution
+ */
+export interface BenchmarkOptions {
+    /** Label for the operation being benchmarked */
+    label?: string;
+    /** Whether to log timing to console */
+    log?: boolean;
+    /** Custom logger function (defaults to console.log) */
+    logger?: (message: string) => void;
+}
+/**
+ * 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 declare function formatDuration(ms: number): string;
+/**
+ * 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 declare function benchmarkSync<T>(fn: () => T, options?: BenchmarkOptions): BenchmarkResult<T>;
+/**
+ * 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 declare function benchmark<T>(fn: () => Promise<T>, options?: BenchmarkOptions): Promise<BenchmarkResult<T>>;
+/**
+ * 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 declare function createTimer(): {
+    start: () => void;
+    stop: () => {
+        durationMs: number;
+        durationFormatted: string;
+    };
+    elapsed: () => number;
+    isRunning: () => boolean;
+};
+/**
+ * Aggregates multiple benchmark results for statistical analysis.
+ */
+export interface BenchmarkStats {
+    /** Number of samples */
+    count: number;
+    /** Total duration in milliseconds */
+    totalMs: number;
+    /** Average duration in milliseconds */
+    avgMs: number;
+    /** Minimum duration in milliseconds */
+    minMs: number;
+    /** Maximum duration in milliseconds */
+    maxMs: number;
+    /** Formatted average duration */
+    avgFormatted: string;
+}
+/**
+ * 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 declare function calculateStats(durations: number[]): BenchmarkStats;