@versatiles/release-tool 2.5.0 → 2.7.0

package/README.md

@@ -51,6 +51,7 @@ Node.js/TypeScript projects.
 
 Options:
   -h, --help                                display help for command
+  -v, --verbose                             Enable verbose output
 
 Commands:
   check                                     Check repo for required scripts and other stuff.
@@ -61,7 +62,7 @@ Commands:
   doc-toc <readme> [heading]                Generate a Table of Contents (TOC) in a Markdown file.
   doc-typescript [options]                  Generate documentation for a TypeScript project.
   help [command]                            display help for command
-  release-npm [path]                        Publish an npm package from the specified path to the npm registry.
+  release-npm [options] [path]              Publish an npm package from the specified path to the npm registry.
 ```
 
 ## Subcommand: `vrt check`
@@ -178,11 +179,12 @@ Usage: vrt release-npm [options] [path]
 Publish an npm package from the specified path to the npm registry.
 
 Arguments:
-  path        Root path of the Node.js project. Defaults to the current
-              directory.
+  path           Root path of the Node.js project. Defaults to the current
+                 directory.
 
 Options:
-  -h, --help  display help for command
+  -h, --help     display help for command
+  -n, --dry-run  Show what would be done without making any changes
 ```
 
 # Development
@@ -201,39 +203,51 @@ flowchart TB
 subgraph 0["src"]
 subgraph 1["commands"]
 2["check.ts"]
-5["deps-graph.ts"]
-6["deps-upgrade.ts"]
-8["doc-command.ts"]
-A["doc-typescript.ts"]
-B["markdown.ts"]
-C["release-npm.ts"]
+6["deps-graph.ts"]
+7["deps-upgrade.ts"]
+9["doc-command.ts"]
+B["doc-typescript.ts"]
+C["markdown.ts"]
+D["release-npm.ts"]
 end
 subgraph 3["lib"]
 4["log.ts"]
-7["shell.ts"]
-9["utils.ts"]
-D["git.ts"]
+5["errors.ts"]
+8["shell.ts"]
+A["utils.ts"]
+E["changelog.ts"]
+F["git.ts"]
+G["retry.ts"]
+I["benchmark.ts"]
 end
-E["index.ts"]
+H["index.ts"]
 end
 2-->4
-5-->4
+4-->5
 6-->4
-6-->7
-8-->9
-A-->4
-B-->9
-C-->D
-C-->4
-C-->7
-D-->7
-E-->2
-E-->5
-E-->6
-E-->8
-E-->A
-E-->B
-E-->C
+7-->4
+7-->8
+8-->4
+9-->A
+B-->4
+C-->5
+C-->A
+D-->E
+D-->5
+D-->F
+D-->4
+D-->G
+D-->8
+E-->F
+F-->8
+H-->2
+H-->6
+H-->7
+H-->9
+H-->B
+H-->C
+H-->D
+H-->4
 
 class 0,1,3 subgraphs;
 classDef subgraphs fill-opacity:0.1, fill:#888, color:#888, stroke:#888;

package/dist/commands/check.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Runs all project checks including package.json and workflow validation.
+ *
+ * @param directory - The project directory to check
+ */
 export declare function check(directory: string): void;
+/**
+ * Validates package.json configuration for VersaTiles projects.
+ *
+ * Checks for:
+ * - Required scripts (build, check, prepack, release)
+ * - Recommended scripts (test, doc, upgrade, doc-graph)
+ * - Script configurations following best practices
+ * - Unnecessary dependencies
+ *
+ * @param directory - The project directory containing package.json
+ * @throws {VrtError} If package.json is missing required scripts
+ */
 export declare function checkPackage(directory: string): void;
+/**
+ * Validates GitHub Actions workflow configuration.
+ *
+ * Checks for the presence of expected workflow files.
+ *
+ * @param directory - The project directory to check
+ */
 export declare function checkWorkflow(directory: string): void;

package/dist/commands/check.js

@@ -1,10 +1,27 @@
 import { existsSync, readFileSync } from 'fs';
-import { panic, info, warn } from '../lib/log.js';
 import { resolve } from 'path';
+import { info, panic, warn } from '../lib/log.js';
+/**
+ * Runs all project checks including package.json and workflow validation.
+ *
+ * @param directory - The project directory to check
+ */
 export function check(directory) {
     checkPackage(directory);
     checkWorkflow(directory);
 }
+/**
+ * Validates package.json configuration for VersaTiles projects.
+ *
+ * Checks for:
+ * - Required scripts (build, check, prepack, release)
+ * - Recommended scripts (test, doc, upgrade, doc-graph)
+ * - Script configurations following best practices
+ * - Unnecessary dependencies
+ *
+ * @param directory - The project directory containing package.json
+ * @throws {VrtError} If package.json is missing required scripts
+ */
 export function checkPackage(directory) {
     const pack = JSON.parse(readFileSync(resolve(directory, 'package.json'), 'utf8'));
     const { scripts } = pack;
@@ -17,8 +34,8 @@ export function checkPackage(directory) {
         info('scripts.doc is recommended');
     if (!scripts.build)
         warn('scripts.build is required');
-    else if (!scripts.build.includes("npm run doc")) {
-        warn(`scripts.build should include "npm run doc-graph", but is "${scripts.build}"`);
+    else if (!scripts.build.includes('npm run doc')) {
+        warn(`scripts.build should include "npm run doc", but is "${scripts.build}"`);
     }
     if (!scripts.check)
         warn('scripts.check is required');
@@ -60,6 +77,13 @@ export function checkPackage(directory) {
         }
     });
 }
+/**
+ * Validates GitHub Actions workflow configuration.
+ *
+ * Checks for the presence of expected workflow files.
+ *
+ * @param directory - The project directory to check
+ */
 export function checkWorkflow(directory) {
     if (!existsSync(resolve(directory, '.github/workflows/pages.yml'))) {
         info('GitHub Pages workflow not found');

package/dist/commands/deps-graph.d.ts

@@ -1 +1,23 @@
+/**
+ * Generates a Mermaid dependency graph for the project's source files.
+ *
+ * Uses dependency-cruiser to analyze imports and outputs a Mermaid flowchart
+ * diagram to stdout. The output is wrapped in markdown code blocks for
+ * easy inclusion in documentation.
+ *
+ * Configuration:
+ * - Only includes files from `src/` directory
+ * - Excludes test files, declaration files, and mocks
+ * - Uses ELK layout for better graph rendering
+ *
+ * @param directory - The project directory to analyze
+ * @throws {VrtError} If dependency analysis fails
+ *
+ * @example
+ * ```ts
+ * // Generate graph and pipe to doc-insert
+ * await generateDependencyGraph('./');
+ * // Output: ```mermaid\nflowchart TB\n...\n```
+ * ```
+ */
 export declare function generateDependencyGraph(directory: string): Promise<void>;

package/dist/commands/deps-graph.js

@@ -1,12 +1,34 @@
 import { cruise } from 'dependency-cruiser';
 import { panic } from '../lib/log.js';
+/**
+ * Generates a Mermaid dependency graph for the project's source files.
+ *
+ * Uses dependency-cruiser to analyze imports and outputs a Mermaid flowchart
+ * diagram to stdout. The output is wrapped in markdown code blocks for
+ * easy inclusion in documentation.
+ *
+ * Configuration:
+ * - Only includes files from `src/` directory
+ * - Excludes test files, declaration files, and mocks
+ * - Uses ELK layout for better graph rendering
+ *
+ * @param directory - The project directory to analyze
+ * @throws {VrtError} If dependency analysis fails
+ *
+ * @example
+ * ```ts
+ * // Generate graph and pipe to doc-insert
+ * await generateDependencyGraph('./');
+ * // Output: ```mermaid\nflowchart TB\n...\n```
+ * ```
+ */
 export async function generateDependencyGraph(directory) {
     let cruiseResult;
     try {
         cruiseResult = await cruise([directory], {
             includeOnly: '^src',
             outputType: 'mermaid',
-            exclude: ["\\.(test|d)\\.ts$", "node_modules", "__mocks__/"],
+            exclude: ['\\.(test|d|mock)\\.ts$', 'node_modules', '__mocks__/'],
         });
     }
     catch (pError) {

package/dist/commands/doc-command.js

@@ -36,18 +36,18 @@ async function getCommandResults(command) {
             NODE_ENV: undefined,
             NODE_DISABLE_COLORS: '1',
             NO_COLORS: '1',
-            FORCE_COLOR: '0'
+            FORCE_COLOR: '0',
         };
         // Spawn a child process to run the command with the '--help' flag.
         const childProcess = cp.spawn('npm', ['--offline', 'exec', '--', ...command.split(' '), '--help'], { env });
         let output = '';
         // Collect output data from the process.
-        childProcess.stdout.on('data', data => output += String(data));
-        childProcess.stderr.on('data', data => {
+        childProcess.stdout.on('data', (data) => (output += String(data)));
+        childProcess.stderr.on('data', (data) => {
             console.error(`stderr: ${data}`);
         });
         // Handle process errors.
-        childProcess.on('error', error => {
+        childProcess.on('error', (error) => {
             reject(new Error(`Failed to start subprocess: ${error.message}`));
         });
         // Handle process exit.
@@ -72,8 +72,8 @@ async function getCommandResults(command) {
  */
 function extractSubcommands(result) {
     return result
-        .replace(/.*\nCommands:/msgi, '') // Remove everything before the "Commands:" section.
-        .replace(/\n[a-z]+:.*/msi, '') // Remove everything after the subcommands list.
+        .replace(/.*\nCommands:/gims, '') // Remove everything before the "Commands:" section.
+        .replace(/\n[a-z]+:.*/ims, '') // Remove everything after the subcommands list.
         .split('\n') // Split by newline to process each line.
         .flatMap((line) => {
         // Extract subcommand names from each line.

package/dist/commands/doc-typescript.d.ts

@@ -1,6 +1,42 @@
-export declare function generateTypescriptDocs(options: {
+/**
+ * Output format for generated TypeScript documentation.
+ */
+export type DocFormat = 'markdown' | 'wiki' | 'html';
+/**
+ * Options for generating TypeScript documentation.
+ */
+export interface TypescriptDocOptions {
+    /** Path to the entry point file (default: './src/index.ts') */
     entryPoint?: string;
+    /** Output directory for generated docs (default: './docs') */
     outputPath?: string;
-    format?: 'markdown' | 'wiki' | 'html';
+    /** Documentation format: 'markdown', 'wiki', or 'html' (default: 'markdown') */
+    format?: DocFormat;
+    /** Suppress info-level logging (default: false) */
     quiet?: boolean;
-}): Promise<void>;
+}
+/**
+ * Generates TypeScript documentation using TypeDoc.
+ *
+ * Supports multiple output formats:
+ * - `markdown`: Standard Markdown files using typedoc-plugin-markdown
+ * - `wiki`: GitHub Wiki compatible Markdown using typedoc-github-wiki-theme
+ * - `html`: HTML documentation using typedoc-github-theme
+ *
+ * @param options - Configuration options for documentation generation
+ * @throws {VrtError} If project conversion fails or validation errors occur
+ *
+ * @example
+ * ```ts
+ * // Generate markdown docs from default entry point
+ * await generateTypescriptDocs({ format: 'markdown' });
+ *
+ * // Generate HTML docs to custom directory
+ * await generateTypescriptDocs({
+ *   entryPoint: './src/main.ts',
+ *   outputPath: './api-docs',
+ *   format: 'html'
+ * });
+ * ```
+ */
+export declare function generateTypescriptDocs(options: TypescriptDocOptions): Promise<void>;

package/dist/commands/doc-typescript.js

@@ -1,5 +1,29 @@
 import * as td from 'typedoc';
 import { panic, warn } from '../lib/log.js';
+/**
+ * Generates TypeScript documentation using TypeDoc.
+ *
+ * Supports multiple output formats:
+ * - `markdown`: Standard Markdown files using typedoc-plugin-markdown
+ * - `wiki`: GitHub Wiki compatible Markdown using typedoc-github-wiki-theme
+ * - `html`: HTML documentation using typedoc-github-theme
+ *
+ * @param options - Configuration options for documentation generation
+ * @throws {VrtError} If project conversion fails or validation errors occur
+ *
+ * @example
+ * ```ts
+ * // Generate markdown docs from default entry point
+ * await generateTypescriptDocs({ format: 'markdown' });
+ *
+ * // Generate HTML docs to custom directory
+ * await generateTypescriptDocs({
+ *   entryPoint: './src/main.ts',
+ *   outputPath: './api-docs',
+ *   format: 'html'
+ * });
+ * ```
+ */
 export async function generateTypescriptDocs(options) {
     const { entryPoint, outputPath, quiet } = options;
     const format = options.format ?? 'markdown';
@@ -16,11 +40,7 @@ export async function generateTypescriptDocs(options) {
         logLevel: quiet ? 'Warn' : 'Info',
         highlightLanguages: ['typescript', 'javascript', 'json', 'shell', 'bash', 'sh', 'css', 'html'],
         groupOrder: ['Classes', 'Variables', 'Functions', '*'],
-    }, [
-        new td.TypeDocReader(),
-        new td.PackageJsonReader(),
-        new td.TSConfigReader(),
-    ]);
+    }, [new td.TypeDocReader(), new td.PackageJsonReader(), new td.TSConfigReader()]);
     app.options.setValue('readme', 'none');
     if (isMarkdown) {
         app.options.setValue('hidePageHeader', true);

package/dist/commands/markdown.d.ts

@@ -1,4 +1,4 @@
-import type { Root, PhrasingContent } from 'mdast';
+import type { PhrasingContent, Root } from 'mdast';
 /**
  * Injects a Markdown segment under a specified heading in a Markdown document.
  * Optionally, the injected segment can be made foldable for better readability.
@@ -17,5 +17,13 @@ export declare function injectMarkdown(document: string, segment: string, headin
  * @returns The Markdown document with an updated TOC.
  */
 export declare function updateTOC(main: string, heading: string): string;
+/**
+ * Converts a PhrasingContent node to its HTML representation.
+ * Handles all PhrasingContent types defined in mdast.
+ *
+ * @param node The phrasing content node to convert.
+ * @returns The HTML string representation.
+ * @throws {VrtError} For reference types that require resolution (footnote, image, link references).
+ */
 export declare function nodeToHtml(node: PhrasingContent): string;
 export declare function parseMarkdown(document: string): Root;