@versatiles/release-tool 2.6.0 → 2.7.1

package/README.md

@@ -203,41 +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
 7-->4
-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
-E-->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;
@@ -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/deps-upgrade.js

@@ -24,7 +24,7 @@ export async function upgradeDependencies(directory) {
         });
     });
     const shell = new Shell(directory);
-    await check('Remove lock file and node_modules', shell.stdout('rm -f package-lock.json && rm -rf node_modules'));
+    await shell.run('rm -f package-lock.json && rm -rf node_modules', false);
     await check('Reinstall all dependencies', shell.stdout('npm i'));
     // Final log message
     info('All dependencies are up to date');

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';

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;

package/dist/commands/markdown.js

@@ -1,6 +1,7 @@
 import { remark } from 'remark';
 import remarkGfm from 'remark-gfm';
 import remarkStringify from 'remark-stringify';
+import { markdownError, notImplementedError } from '../lib/errors.js';
 import { getErrorMessage } from '../lib/utils.js';
 // Custom blockquote handler that preserves GitHub alert syntax
 function blockquoteHandler(node, _parent, state, info) {
@@ -36,7 +37,7 @@ export function injectMarkdown(document, segment, heading, foldable) {
     }
     catch (error) {
         // Handle errors during the search for the start index.
-        throw new Error(`Error while searching for segment "${heading}": ${getErrorMessage(error)}`);
+        throw markdownError(`Error while searching for segment "${heading}": ${getErrorMessage(error)}`);
     }
     // Get the depth of the specified heading to maintain the structure.
     const depth = getHeadingDepth(documentAst, startIndex);
@@ -102,9 +103,9 @@ export function updateTOC(main, heading) {
 function findSegmentStartIndex(mainAst, headingAst) {
     // Verify the structure of the headingAst.
     if (headingAst.children.length !== 1)
-        throw Error('headingAst.children.length !== 1');
+        throw markdownError('headingAst.children.length !== 1');
     if (headingAst.children[0].type !== 'heading')
-        throw Error("headingAst.children[0].type !== 'heading'");
+        throw markdownError("headingAst.children[0].type !== 'heading'");
     const sectionDepth = headingAst.children[0].depth;
     const sectionText = extractTextFromMDAsHTML(headingAst);
     // Search for the index of the heading in the main document AST.
@@ -116,9 +117,9 @@ function findSegmentStartIndex(mainAst, headingAst) {
     });
     // Handle the cases of no match or multiple matches.
     if (indexes.length < 1)
-        throw Error('section not found');
+        throw markdownError('section not found');
     if (indexes.length > 1)
-        throw Error('too many sections found');
+        throw markdownError('too many sections found');
     return indexes[0];
 }
 /**
@@ -148,7 +149,7 @@ function findNextHeadingIndex(mainAst, startIndex, depth) {
 function getHeadingDepth(mainAst, index) {
     const node = mainAst.children[index];
     if (node.type !== 'heading')
-        throw Error("node.type !== 'heading'");
+        throw markdownError("node.type !== 'heading'");
     return node.depth;
 }
 /**
@@ -174,47 +175,108 @@ function mergeSegments(mainAst, segmentAst, startIndex, endIndex) {
 }
 /**
  * Extracts the textual content from a node in the AST.
- * @param node The AST node.
- * @returns The extracted text content.
- * @throws Error if the node type is unknown.
+ * Recursively processes nodes with children and extracts text values.
+ *
+ * @param node The AST node (Root or any RootContent type).
+ * @returns The extracted text content as HTML-escaped string.
  */
 function extractTextFromMDAsHTML(node) {
     switch (node.type) {
+        // Nodes with direct text value
         case 'inlineCode':
         case 'text':
             return textToHtml(node.value);
+        // Nodes with children to recurse into
         case 'heading':
         case 'root':
-            return node.children.map(extractTextFromMDAsHTML).join('');
+        case 'paragraph':
+        case 'blockquote':
+        case 'listItem':
+        case 'tableCell':
+        case 'tableRow':
+        case 'link':
+        case 'emphasis':
+        case 'strong':
+        case 'delete':
+            return node.children.map((child) => extractTextFromMDAsHTML(child)).join('');
+        // Nodes with children but need special handling
+        case 'list':
+            return node.children.map((child) => extractTextFromMDAsHTML(child)).join('');
+        case 'table':
+            return node.children.map((child) => extractTextFromMDAsHTML(child)).join('');
+        // Nodes with alt text
+        case 'image':
+            return node.alt ? textToHtml(node.alt) : '';
+        // Nodes that don't contribute text content
         case 'html':
+        case 'code':
+        case 'thematicBreak':
+        case 'break':
+        case 'definition':
+        case 'footnoteDefinition':
+        case 'footnoteReference':
+        case 'imageReference':
+        case 'linkReference':
+        case 'yaml':
             return '';
-        default:
-            throw Error('unknown type: ' + node.type);
+        default: {
+            // TypeScript exhaustive check - this ensures we handle all types
+            const _exhaustiveCheck = node;
+            throw markdownError(`unhandled node type: ${node.type}`);
+        }
     }
 }
 /**
  * Generates an anchor ID for a Markdown heading based on its text content.
+ * Handles all PhrasingContent types that can appear in a heading.
+ *
  * @param node The heading node.
- * @returns The generated anchor ID.
- * @throws Error if the child node type is unknown.
+ * @returns The generated anchor ID, formatted for use in URLs.
  */
 function getMDAnchor(node) {
     let text = '';
     for (const c of node.children) {
         // Handle different types of child nodes to construct the anchor text.
         switch (c.type) {
+            // Check for explicit ID in HTML
             case 'html': {
                 const match = /<a\s.*id\s*=\s*['"]([^'"]+)/i.exec(c.value);
                 if (match)
                     return match[1];
                 break;
             }
+            // Nodes with direct text value
             case 'text':
             case 'inlineCode':
                 text += c.value;
                 break;
-            default:
-                throw Error('unknown type: ' + c.type);
+            // Nodes with children - recurse to extract text
+            case 'emphasis':
+            case 'strong':
+            case 'delete':
+            case 'link':
+                for (const child of c.children) {
+                    if (child.type === 'text' || child.type === 'inlineCode') {
+                        text += child.value;
+                    }
+                }
+                break;
+            // Image - use alt text
+            case 'image':
+                if (c.alt)
+                    text += c.alt;
+                break;
+            // Nodes that don't contribute to anchor text
+            case 'break':
+            case 'footnoteReference':
+            case 'imageReference':
+            case 'linkReference':
+                break;
+            default: {
+                // TypeScript exhaustive check
+                const _exhaustiveCheck = c;
+                throw markdownError(`unhandled phrasing content type: ${c.type}`);
+            }
         }
     }
     // Format the text to create a suitable anchor ID.
@@ -227,6 +289,8 @@ function getMDAnchor(node) {
 }
 /**
  * Converts a segment of the AST into a foldable HTML element.
+ * Headings become collapsible `<details>` sections.
+ *
  * @param ast The AST of the segment to be converted.
  */
 function convertToFoldable(ast) {
@@ -234,19 +298,56 @@ function convertToFoldable(ast) {
     const children = [];
     ast.children.forEach((c) => {
         switch (c.type) {
-            case 'html':
-            case 'list':
-            case 'paragraph':
-                children.push(c);
-                break;
+            // Headings start new foldable sections
             case 'heading':
                 closeDetails(c.depth);
                 children.push({ type: 'html', value: '<details>' });
                 children.push({ type: 'html', value: `<summary>${lineToHtml(c)}</summary>` });
                 openDetails.unshift(c.depth);
                 break;
-            default:
-                throw Error(`unknown type "${c.type}"`);
+            // Block content that gets included in sections
+            case 'html':
+            case 'list':
+            case 'paragraph':
+            case 'blockquote':
+            case 'code':
+            case 'table':
+            case 'thematicBreak':
+                children.push(c);
+                break;
+            // Definition content - include as-is
+            case 'definition':
+            case 'footnoteDefinition':
+                children.push(c);
+                break;
+            // YAML frontmatter - include as-is
+            case 'yaml':
+                children.push(c);
+                break;
+            // Inline/phrasing content that shouldn't appear at root level
+            // but handle gracefully if present
+            case 'text':
+            case 'inlineCode':
+            case 'emphasis':
+            case 'strong':
+            case 'delete':
+            case 'link':
+            case 'image':
+            case 'break':
+            case 'footnoteReference':
+            case 'imageReference':
+            case 'linkReference':
+            case 'listItem':
+            case 'tableCell':
+            case 'tableRow':
+                // These shouldn't normally appear at root level, but pass through
+                children.push(c);
+                break;
+            default: {
+                // TypeScript exhaustive check
+                const _exhaustiveCheck = c;
+                throw markdownError(`unhandled root content type: ${c.type}`);
+            }
         }
     });
     closeDetails(0);
@@ -261,6 +362,14 @@ function convertToFoldable(ast) {
 function lineToHtml(heading) {
     return `<h${heading.depth}>${nodesToHtml(heading.children)}</h${heading.depth}>`;
 }
+/**
+ * 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 function nodeToHtml(node) {
     switch (node.type) {
         case 'html':
@@ -287,14 +396,18 @@ export function nodeToHtml(node) {
                 attributes.push(`title="${node.title}"`);
             return `<img ${attributes.join(' ')} />`;
         }
+        // Reference types require definition resolution which is not supported
         case 'footnoteReference':
-            throw new Error('Not implemented yet: "footnoteReference" case');
+            throw notImplementedError('footnoteReference - requires definition resolution');
         case 'imageReference':
-            throw new Error('Not implemented yet: "imageReference" case');
+            throw notImplementedError('imageReference - requires definition resolution');
         case 'linkReference':
-            throw new Error('Not implemented yet: "linkReference" case');
-        default:
-            throw Error('unknown type');
+            throw notImplementedError('linkReference - requires definition resolution');
+        default: {
+            // TypeScript exhaustive check
+            const _exhaustiveCheck = node;
+            throw markdownError(`unhandled phrasing content type: ${node.type}`);
+        }
     }
 }
 function nodesToHtml(children) {

package/dist/commands/release-npm.d.ts

@@ -1,2 +1,45 @@
 #!/usr/bin/env npx tsx
+/**
+ * Options for the release process.
+ */
+export interface ReleaseOptions {
+    /** The project directory containing package.json (default: current directory) */
+    directory?: string;
+    /** The git branch to release from (default: 'main') */
+    branch?: string;
+    /** If true, simulate the release without making changes (default: false) */
+    dryRun?: boolean;
+}
+/**
+ * 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 declare function release(directory: string, branch?: string, dryRun?: boolean): Promise<void>;