@versatiles/release-tool 1.0.1 → 1.0.2

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-#!/usr/bin/env node --enable-source-maps
+#!/usr/bin/env -S node --enable-source-maps
 export {};

package/dist/index.js

@@ -1,7 +1,7 @@
-#!/usr/bin/env node --enable-source-maps
+#!/usr/bin/env -S node --enable-source-maps
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { generateMarkdownDocumentation } from './lib/typedoc.js';
+import { generateTsMarkdownDoc } from './lib/typedoc.js';
 import { injectMarkdown, updateTOC } from './lib/markdown.js';
 import { Command, InvalidArgumentError } from 'commander';
 import { cwd } from 'node:process';
@@ -15,14 +15,14 @@ program.command('ts2md')
     .argument('<typescript>', 'Filename of the TypeScript file', checkFilename)
     .argument('<tsconfig>', 'Filename of tsconfig.json', checkFilename)
     .action(async (tsFilename, tsConfig) => {
-    const mdDocumentation = await generateMarkdownDocumentation([tsFilename], tsConfig);
+    const mdDocumentation = await generateTsMarkdownDoc([tsFilename], tsConfig);
     process.stdout.write(mdDocumentation);
 });
 program.command('cmd2md')
     .description('documents a runnable command and outputs it to stdout')
     .argument('<command>', 'command to run')
-    .action((command) => {
-    const mdDocumentation = generateCommandDocumentation(command);
+    .action(async (command) => {
+    const mdDocumentation = await generateCommandDocumentation(command);
     process.stdout.write(mdDocumentation);
 });
 program.command('insertmd')

package/dist/lib/command.d.ts

@@ -1 +1,6 @@
-export declare function generateCommandDocumentation(command: string): string;
+/**
+ * Generates documentation for a CLI command and its subcommands.
+ * @param command The base CLI command to document.
+ * @returns A Promise resolving to a string containing the generated Markdown documentation.
+ */
+export declare function generateCommandDocumentation(command: string): Promise<string>;

package/dist/lib/command.js

@@ -1,42 +1,83 @@
-import { spawnSync } from 'node:child_process';
-export function generateCommandDocumentation(command) {
-    const result = getCommandResults(command);
-    let { markdown } = result;
-    const { subcommands } = result;
-    for (const subcommand of subcommands) {
-        const subResult = getCommandResults(command + ' ' + subcommand);
-        markdown += `\n# Subcommand: \`${command} ${subcommand}\`\n\n${subResult.markdown}`;
-    }
+import cp from 'child_process';
+import { getErrorMessage } from './utils.js';
+/**
+ * Generates documentation for a CLI command and its subcommands.
+ * @param command The base CLI command to document.
+ * @returns A Promise resolving to a string containing the generated Markdown documentation.
+ */
+export async function generateCommandDocumentation(command) {
+    // Get the base command's documentation and list of subcommands.
+    // eslint-disable-next-line prefer-const
+    let { markdown, subcommands } = await getCommandResults(command);
+    // Iterate over each subcommand to generate its documentation.
+    markdown += (await Promise.all(subcommands.map(async (subcommand) => {
+        const fullCommand = `${command} ${subcommand}`;
+        try {
+            // Get documentation for each subcommand.
+            const { markdown: subcommandMarkdown } = await getCommandResults(fullCommand);
+            return `\n# Subcommand: \`${fullCommand}\`\n\n${subcommandMarkdown}`;
+        }
+        catch (error) {
+            // Handle errors in generating subcommand documentation.
+            throw new Error(`Error generating documentation for subcommand '${fullCommand}': ${getErrorMessage(error)}`);
+        }
+    }))).join('');
     return markdown;
 }
-function getCommandResults(command) {
-    const cp = spawnSync('npx', [...command.split(' '), '--help']);
-    if (cp.error)
-        throw Error(cp.error.toString());
-    const result = cp.stdout.toString().trim();
-    const subcommands = result
-        .replace(/.*\nCommands:/msgi, '')
-        .replace(/\n[a-z]+:.*/msi, '')
-        .split('\n')
+/**
+ * Executes a CLI command with the '--help' flag and parses the output.
+ * @param command The CLI command to execute.
+ * @returns A Promise resolving to an object containing the Markdown documentation and a list of subcommands.
+ */
+async function getCommandResults(command) {
+    return new Promise((resolve, reject) => {
+        // Spawn a child process to run the command with the '--help' flag.
+        const childProcess = cp.spawn('npx', [...command.split(' '), '--help']);
+        let output = '';
+        // Collect output data from the process.
+        childProcess.stdout.on('data', data => output += String(data));
+        childProcess.stderr.on('data', data => {
+            console.error(`stderr: ${data}`);
+        });
+        // Handle process errors.
+        childProcess.on('error', error => {
+            reject(new Error(`Failed to start subprocess: ${error.message}`));
+        });
+        // Handle process exit.
+        childProcess.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`Command failed with exit code ${code}`));
+                return;
+            }
+            const result = output.trim();
+            // Resolve with the formatted output and a list of subcommands.
+            resolve({
+                markdown: `\`\`\`console\n$ ${command}\n${result}\n\`\`\`\n`,
+                subcommands: extractSubcommands(result),
+            });
+        });
+    });
+}
+/**
+ * Extracts a list of subcommands from the help output of a command.
+ * @param result The string output from a command's help flag.
+ * @returns An array of subcommand names.
+ */
+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.
+        .split('\n') // Split by newline to process each line.
         .flatMap((line) => {
+        // Extract subcommand names from each line.
         const extract = /^  ([^ ]{2,})/.exec(line);
         if (!extract)
             return [];
-        // eslint-disable-next-line @typescript-eslint/prefer-destructuring
-        const subcommand = extract[1];
+        const [, subcommand] = extract;
+        // Ignore the 'help' subcommand.
         if (subcommand === 'help')
             return [];
         return [subcommand];
     });
-    return {
-        markdown: [
-            '```console',
-            '$ ' + command,
-            result,
-            '```',
-            '',
-        ].join('\n'),
-        subcommands,
-    };
 }
 //# sourceMappingURL=command.js.map

package/dist/lib/markdown.d.ts

@@ -1,2 +1,21 @@
+import type { Root, PhrasingContent } 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.
+ * @param document The original Markdown document.
+ * @param segment The Markdown segment to be injected.
+ * @param heading The heading under which the segment is to be injected.
+ * @param foldable If true, makes the segment foldable.
+ * @returns The modified Markdown document.
+ */
 export declare function injectMarkdown(document: string, segment: string, heading: string, foldable?: boolean): string;
+/**
+ * Updates the Table of Contents (TOC) of a Markdown document.
+ * The TOC is rebuilt based on the headings present in the document.
+ * @param main The main Markdown document.
+ * @param heading The heading under which the TOC is to be updated.
+ * @returns The Markdown document with an updated TOC.
+ */
 export declare function updateTOC(main: string, heading: string): string;
+export declare function nodeToHtml(node: PhrasingContent): string;
+export declare function parseMarkdown(document: string): Root;

package/dist/lib/markdown.js

@@ -1,79 +1,139 @@
 import { remark } from 'remark';
+import remarkGfm from 'remark-gfm';
+import { getErrorMessage } from './utils.js';
+/**
+ * Injects a Markdown segment under a specified heading in a Markdown document.
+ * Optionally, the injected segment can be made foldable for better readability.
+ * @param document The original Markdown document.
+ * @param segment The Markdown segment to be injected.
+ * @param heading The heading under which the segment is to be injected.
+ * @param foldable If true, makes the segment foldable.
+ * @returns The modified Markdown document.
+ */
 // eslint-disable-next-line @typescript-eslint/max-params
 export function injectMarkdown(document, segment, heading, foldable) {
-    const documentAst = remark().parse(document);
-    const segmentAst = remark().parse(segment);
-    const headingAst = remark().parse(heading);
+    // Parse the input strings into Abstract Syntax Trees (ASTs).
+    const documentAst = parseMarkdown(document);
+    const segmentAst = parseMarkdown(segment);
+    const headingAst = parseMarkdown(heading);
+    // Initialize the start index of the injection.
     let startIndex;
     try {
-        startIndex = findSegmentStart(documentAst, headingAst);
+        // Find the start index where the new segment should be injected.
+        startIndex = findSegmentStartIndex(documentAst, headingAst);
     }
     catch (error) {
-        console.error(`While searching for segment "${heading}" …`);
+        // Handle errors during the search for the start index.
+        console.error(`Error while searching for segment "${heading}": ${getErrorMessage(error)}`);
         throw error;
     }
+    // Get the depth of the specified heading to maintain the structure.
     const depth = getHeadingDepth(documentAst, startIndex);
-    const endIndex = findNextHeading(documentAst, startIndex + 1, depth);
-    indentChapter(segmentAst, depth);
-    if (foldable ?? false)
-        makeFoldable(segmentAst);
-    spliceAst(documentAst, segmentAst, startIndex + 1, endIndex);
+    // Find the index of the next heading of the same depth to define the end of the segment.
+    const endIndex = findNextHeadingIndex(documentAst, startIndex + 1, depth);
+    // Adjust the indentation of the segment to align with the specified depth.
+    indentSegmentToDepth(segmentAst, depth);
+    // Convert the segment to a foldable section if required.
+    if (foldable === true)
+        convertToFoldable(segmentAst);
+    // Merge the original document AST with the new segment AST.
+    mergeSegments(documentAst, segmentAst, startIndex + 1, endIndex);
+    // Convert the modified AST back to a Markdown string and return.
     return remark().stringify(documentAst);
 }
+/**
+ * Updates the Table of Contents (TOC) of a Markdown document.
+ * The TOC is rebuilt based on the headings present in the document.
+ * @param main The main Markdown document.
+ * @param heading The heading under which the TOC is to be updated.
+ * @returns The Markdown document with an updated TOC.
+ */
 export function updateTOC(main, heading) {
-    const mainAst = remark().parse(main);
-    const headingText = getMDText(remark().parse(heading));
+    // Parse the main document and the heading for the TOC.
+    const mainAst = parseMarkdown(main);
+    const headingText = extractTextFromMDAsHTML(parseMarkdown(heading));
+    // Build the TOC by iterating over each heading in the document.
     const toc = mainAst.children
         .flatMap(c => {
-        if (c.type !== 'heading')
-            return [];
-        const text = getMDText(c);
-        if (text === headingText)
+        // Skip non-heading nodes and the specified heading.
+        if (c.type !== 'heading' || extractTextFromMDAsHTML(c) === headingText)
             return [];
+        // Format each heading as a TOC entry.
         const indention = '  '.repeat((c.depth - 1) * 2);
         const anchor = getMDAnchor(c);
-        return `${indention}* [${text}](#${anchor})\n`;
+        return `${indention}* [${extractTextFromMDAsHTML(c)}](#${anchor})\n`;
     })
         .join('');
+    // Inject the newly generated TOC under the specified heading in the document.
     return injectMarkdown(main, toc, heading);
 }
-function findSegmentStart(mainAst, headingAst) {
+// Below are the helper functions used in the above main functions. Each helper function
+// is designed for a specific operation and is provided with detailed comments for clarity.
+/**
+ * Finds the start index of the segment under a specific heading in the AST.
+ * @param mainAst The AST of the main document.
+ * @param headingAst The AST of the heading under which the segment is to be inserted.
+ * @returns The start index of the segment in the main document AST.
+ * @throws Error if headingAst does not have exactly one child or the child is not a heading.
+ */
+function findSegmentStartIndex(mainAst, headingAst) {
+    // Verify the structure of the headingAst.
     if (headingAst.children.length !== 1)
-        throw Error();
+        throw Error('headingAst.children.length !== 1');
     if (headingAst.children[0].type !== 'heading')
-        throw Error();
+        throw Error('headingAst.children[0].type !== \'heading\'');
     const sectionDepth = headingAst.children[0].depth;
-    const sectionText = getMDText(headingAst);
+    const sectionText = extractTextFromMDAsHTML(headingAst);
+    // Search for the index of the heading in the main document AST.
     const indexes = mainAst.children.flatMap((c, index) => {
-        if ((c.type === 'heading') && (c.depth === sectionDepth) && getMDText(c).startsWith(sectionText)) {
+        if ((c.type === 'heading') && (c.depth === sectionDepth) && extractTextFromMDAsHTML(c).startsWith(sectionText)) {
             return [index];
         }
         return [];
     });
+    // Handle the cases of no match or multiple matches.
     if (indexes.length < 1)
         throw Error('section not found');
     if (indexes.length > 1)
         throw Error('too many sections found');
     return indexes[0];
 }
-function findNextHeading(mainAst, startIndex, depth) {
+/**
+ * Finds the index of the next heading at the same depth in the AST.
+ * @param mainAst The AST of the main document.
+ * @param startIndex The index to start searching from.
+ * @param depth The depth of the headings to match.
+ * @returns The index of the next heading of the same depth, or the length of the children array if none is found.
+ */
+function findNextHeadingIndex(mainAst, startIndex, depth) {
+    // Iterate over the AST nodes starting from startIndex.
     for (let i = startIndex; i < mainAst.children.length; i++) {
         const child = mainAst.children[i];
-        if (child.type !== 'heading')
-            continue;
-        if (child.depth !== depth)
-            continue;
-        return i;
+        // Return the index of the next heading at the same depth.
+        if (child.type === 'heading' && child.depth === depth)
+            return i;
     }
     return mainAst.children.length;
 }
+/**
+ * Gets the depth of the heading at a given index in the AST.
+ * @param mainAst The AST of the main document.
+ * @param index The index of the heading.
+ * @returns The depth of the heading.
+ * @throws Error if the node at the index is not a heading.
+ */
 function getHeadingDepth(mainAst, index) {
     const node = mainAst.children[index];
     if (node.type !== 'heading')
-        throw Error();
+        throw Error('node.type !== \'heading\'');
     return node.depth;
 }
-function indentChapter(segmentAst, depth) {
+/**
+ * Indents each segment in the AST to match a specified depth, modifying headings accordingly.
+ * @param segmentAst The AST of the segment to be indented.
+ * @param depth The depth to which the segment should be indented.
+ */
+function indentSegmentToDepth(segmentAst, depth) {
     segmentAst.children.forEach(node => {
         switch (node.type) {
             case 'code':
@@ -91,18 +151,31 @@ function indentChapter(segmentAst, depth) {
         }
     });
 }
+/**
+ * Merges a segment AST into the main document AST at specified start and end indexes.
+ * @param mainAst The AST of the main document.
+ * @param segmentAst The AST of the segment to be merged.
+ * @param startIndex The start index in the main AST.
+ * @param endIndex The end index in the main AST.
+ */
 // eslint-disable-next-line @typescript-eslint/max-params
-function spliceAst(mainAst, segmentAst, startIndex, endIndex) {
+function mergeSegments(mainAst, segmentAst, startIndex, endIndex) {
     mainAst.children.splice(startIndex, endIndex - startIndex, ...segmentAst.children);
 }
-function getMDText(node) {
+/**
+ * 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.
+ */
+function extractTextFromMDAsHTML(node) {
     switch (node.type) {
         case 'inlineCode':
         case 'text':
-            return node.value;
+            return textToHtml(node.value);
         case 'heading':
         case 'root':
-            return node.children.map(getMDText).join('');
+            return node.children.map(extractTextFromMDAsHTML).join('');
         case 'html':
             return '';
         default:
@@ -110,9 +183,16 @@ function getMDText(node) {
             throw Error('unknown type: ' + node.type);
     }
 }
+/**
+ * Generates an anchor ID for a Markdown heading based on its text content.
+ * @param node The heading node.
+ * @returns The generated anchor ID.
+ * @throws Error if the child node type is unknown.
+ */
 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) {
             case 'html':
                 const match = /<a\s.*id\s*=\s*['"]([^'"]+)/i.exec(c.value);
@@ -128,13 +208,18 @@ function getMDAnchor(node) {
                 throw Error('unknown type: ' + c.type);
         }
     }
+    // Format the text to create a suitable anchor ID.
     text = text.toLowerCase()
         .replace(/[()]+/g, '')
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^\-+|\-+$/g, '');
     return text;
 }
-function makeFoldable(ast) {
+/**
+ * Converts a segment of the AST into a foldable HTML element.
+ * @param ast The AST of the segment to be converted.
+ */
+function convertToFoldable(ast) {
     const openDetails = [];
     const children = [];
     ast.children.forEach((c) => {
@@ -163,31 +248,52 @@ function makeFoldable(ast) {
         }
     }
 }
-function lineToHtml(child) {
-    const html = child.children.map(c => {
-        switch (c.type) {
-            case 'html': return c.value;
-            case 'text': return c.value;
-            case 'inlineCode': return `<code>${textToHtml(c.value)}</code>`;
-            //case "break": { throw new Error('Not implemented yet: "break" case') }
-            //case "delete": { throw new Error('Not implemented yet: "delete" case') }
-            //case "emphasis": { throw new Error('Not implemented yet: "emphasis" case') }
-            //case "footnoteReference": { throw new Error('Not implemented yet: "footnoteReference" case') }
-            //case "image": { throw new Error('Not implemented yet: "image" case') }
-            //case "imageReference": { throw new Error('Not implemented yet: "imageReference" case') }
-            //case "inlineCode": { throw new Error('Not implemented yet: "inlineCode" case') }
-            //case "link": { throw new Error('Not implemented yet: "link" case') }
-            //case "linkReference": { throw new Error('Not implemented yet: "linkReference" case') }
-            //case "strong": { throw new Error('Not implemented yet: "strong" case') }
-            //case "text": { throw new Error('Not implemented yet: "text" case') }
-            default:
-                console.log(c);
-                throw Error(`unknown type "${c.type}"`);
-        }
-    });
-    return `<h${child.depth}>${html.join('')}</h${child.depth}>`;
+function lineToHtml(heading) {
+    return `<h${heading.depth}>${nodesToHtml(heading.children)}</h${heading.depth}>`;
+}
+export function nodeToHtml(node) {
+    switch (node.type) {
+        case 'html':
+            return node.value;
+        case 'text':
+            return textToHtml(node.value);
+        case 'inlineCode':
+            return `<code>${textToHtml(node.value)}</code>`;
+        case 'break':
+            return '<br />';
+        case 'delete':
+            return `<del>${nodesToHtml(node.children)}</del>`;
+        case 'emphasis':
+            return `<em>${nodesToHtml(node.children)}</em>`;
+        case 'strong':
+            return `<strong>${nodesToHtml(node.children)}</strong>`;
+        case 'link':
+            return `<a href="${node.url}"${node.title == null ? '' : ` title="${node.title}"`}>${nodesToHtml(node.children)}</a>`;
+        case 'linkReference':
+            throw new Error('"linkReference to html" not implemented');
+        case 'footnoteReference':
+            throw new Error('"footnoteReference to html" not implemented');
+        case 'image':
+            const attributes = [`src="${node.url}"`];
+            if (node.alt ?? '')
+                attributes.push(`alt="${node.alt}"`);
+            if (node.title ?? '')
+                attributes.push(`title="${node.title}"`);
+            return `<img ${attributes.join(' ')} />`;
+        case 'imageReference':
+            throw new Error('"imageReference to html" not implemented');
+        default:
+            console.log(node);
+            throw Error('unknown type');
+    }
+}
+function nodesToHtml(children) {
+    return children.map(nodeToHtml).join('');
 }
 function textToHtml(text) {
     return text.replace(/[^a-z0-9 ,.-:_?@äöüß]/gi, c => `&#${c.charCodeAt(0)};`);
 }
+export function parseMarkdown(document) {
+    return remark().use(remarkGfm).parse(document);
+}
 //# sourceMappingURL=markdown.js.map

package/dist/lib/typedoc.d.ts

@@ -1,6 +1,6 @@
 /**
  * Generate markdown documentation from TypeScript files.
- * @param entryPoints - Array of absolute TypeScript file paths.
- * @param tsconfig - Absolute file path of tsconfig.json.
+ * @param sourceFilePaths - Array of absolute TypeScript file paths.
+ * @param tsConfigPath - Absolute file path of tsconfig.json.
  */
-export declare function generateMarkdownDocumentation(entryPoints: string[], tsconfig: string): Promise<string>;
+export declare function generateTsMarkdownDoc(sourceFilePaths: string[], tsConfigPath: string): Promise<string>;

package/dist/lib/typedoc.js

@@ -1,31 +1,31 @@
 import { Application, ReflectionKind, } from 'typedoc';
 /**
  * Generate markdown documentation from TypeScript files.
- * @param entryPoints - Array of absolute TypeScript file paths.
- * @param tsconfig - Absolute file path of tsconfig.json.
+ * @param sourceFilePaths - Array of absolute TypeScript file paths.
+ * @param tsConfigPath - Absolute file path of tsconfig.json.
  */
-export async function generateMarkdownDocumentation(entryPoints, tsconfig) {
-    const app = await Application.bootstrap({ entryPoints, tsconfig });
+export async function generateTsMarkdownDoc(sourceFilePaths, tsConfigPath) {
+    const app = await Application.bootstrap({ entryPoints: sourceFilePaths, tsconfig: tsConfigPath });
     const project = await app.convert();
     if (!project) {
-        throw new Error('Failed to convert project.');
+        throw new Error('Failed to convert TypeScript project.');
     }
-    return Array.from(renderProjectDocumentation(project)).join('\n');
+    return Array.from(documentProject(project)).join('\n');
 }
-function* renderProjectDocumentation(project) {
+function* documentProject(project) {
     if (!project.groups) {
-        throw new Error('No code to document found! Is this a lib?');
+        throw new Error('No TypeScript code to document found! Is this a lib?');
     }
     for (const group of project.groups) {
-        for (const declaration of group.children) {
-            yield* renderDeclaration(declaration);
+        for (const item of group.children) {
+            yield* documentDeclaration(item);
         }
     }
 }
-function* renderDeclaration(declaration) {
-    const typeName = formatTypeName(declaration.kind);
-    yield `# ${typeName}: \`${declaration.name}\`<a id="${generateAnchor(declaration)}"></a>`;
-    yield* renderSummaryBlock(declaration);
+function* documentDeclaration(declaration) {
+    const declarationType = getDeclarationTypeName(declaration.kind);
+    yield `# ${declarationType}: \`${declaration.name}\`<a id="${createAnchorId(declaration)}"></a>`;
+    yield* documentSummaryBlock(declaration);
     for (const group of declaration.groups ?? []) {
         const publicMembers = group.children.filter(member => !member.flags.isPrivate && !member.flags.isProtected);
         if (publicMembers.length === 0)
@@ -35,20 +35,20 @@ function* renderDeclaration(declaration) {
         switch (group.title) {
             case 'Constructors':
                 if (publicMembers.length !== 1)
-                    throw Error();
-                yield* renderMethod(publicMembers[0], true);
+                    throw Error('publicMembers.length !== 1');
+                yield* documentMethod(publicMembers[0], true);
                 continue;
             case 'Properties':
                 //yield '';
                 //yield '**Properties**';
                 for (const member of publicMembers)
-                    yield formatParameter(member);
+                    yield documentProperty(member);
                 continue;
             case 'Methods':
                 //yield '';
                 //yield '**Methods**';
                 for (const member of publicMembers)
-                    yield* renderMethod(member);
+                    yield* documentMethod(member);
                 continue;
             default:
                 console.log(group);
@@ -56,45 +56,47 @@ function* renderDeclaration(declaration) {
         }
     }
     if (declaration.type) {
-        yield `\n**Type:** <code>${formatType(declaration.type)}</code>`;
+        yield `\n**Type:** <code>${formatTypeDeclaration(declaration.type)}</code>`;
     }
 }
-function* renderMethod(declaration, isConstructor = false) {
-    if (declaration.signatures?.length !== 1)
+function* documentMethod(method, isConstructor = false) {
+    if (method.signatures?.length !== 1)
         throw Error('should be 1');
-    const [signature] = declaration.signatures;
-    const functionName = signature.name;
+    const [signature] = method.signatures;
+    const methodName = signature.name;
     const parameters = formatMethodParameters(signature.parameters ?? []);
     const returnType = signature.type;
-    const prefix = isConstructor ? 'Constructor' : 'Method';
-    yield `## ${prefix}: \`${functionName}(${parameters})\``;
+    const methodType = isConstructor ? 'Constructor' : 'Method';
+    yield `## ${methodType}: \`${methodName}(${parameters})\``;
     yield '';
-    yield* renderSummaryBlock(signature);
+    yield* documentSummaryBlock(signature);
     if (signature.parameters && signature.parameters.length > 0) {
         yield '';
         yield '**Parameters:**';
         for (const parameter of signature.parameters) {
-            yield formatParameter(parameter);
+            yield documentProperty(parameter);
         }
     }
     if (returnType) {
         yield '';
-        yield `**Returns:** <code>${formatType(returnType)}</code>`;
+        yield `**Returns:** <code>${formatTypeDeclaration(returnType)}</code>`;
     }
 }
 function formatMethodParameters(parameters) {
     return parameters.map(param => param.name).join(', ');
 }
 // Helper Functions
-function formatTypeName(kind) {
+function getDeclarationTypeName(kind) {
     switch (kind) {
         case ReflectionKind.Class: return 'Class';
+        case ReflectionKind.Function: return 'Function';
         case ReflectionKind.Interface: return 'Interface';
         case ReflectionKind.TypeAlias: return 'Type';
+        case ReflectionKind.Variable: return 'Variable';
         default: throw new Error(`Unknown reflection kind: ${kind}`);
     }
 }
-function formatParameter(ref) {
+function documentProperty(ref) {
     let line = `  - <code>${ref.name}${resolveTypeDeclaration(ref.type)}</code>`;
     if (ref.flags.isOptional)
         line += ' (optional)';
@@ -108,7 +110,7 @@ function extractSummary(comment) {
         return '';
     return comment.summary.map(line => line.text).join('');
 }
-function* renderSummaryBlock(ref) {
+function* documentSummaryBlock(ref) {
     yield '';
     if (ref.comment) {
         yield formatComment(ref.comment);
@@ -117,25 +119,25 @@ function* renderSummaryBlock(ref) {
     const { type } = ref;
     if (type?.type === 'reflection') {
         if (type.declaration.signatures?.length !== 1)
-            throw Error();
+            throw Error('type.declaration.signatures?.length !== 1');
         const [signature] = type.declaration.signatures;
         if (signature.comment) {
             yield formatComment(signature.comment);
             return;
         }
     }
-    yield generateSourceLink(ref) + '\n';
+    yield createSourceLink(ref) + '\n';
     return;
     function formatComment(comment) {
-        return (extractSummary(comment) + ' ' + generateSourceLink(ref)).replace(/\n/m, '  \n') + '\n';
+        return (extractSummary(comment) + ' ' + createSourceLink(ref)).replace(/\n/m, '  \n') + '\n';
     }
 }
 function resolveTypeDeclaration(someType) {
     if (!someType)
         return '';
-    return `: ${formatType(someType)}`;
+    return `: ${formatTypeDeclaration(someType)}`;
 }
-function formatType(someType) {
+function formatTypeDeclaration(someType) {
     return getTypeRec(someType);
     function getTypeRec(some) {
         switch (some.type) {
@@ -146,7 +148,7 @@ function formatType(someType) {
             case 'reference':
                 let result = some.name;
                 if (some.reflection)
-                    result = `[${result}](#${generateAnchor(some.reflection)})`;
+                    result = `[${result}](#${createAnchorId(some.reflection)})`;
                 if (some.typeArguments?.length ?? 0)
                     result += '<'
                         + (some.typeArguments ?? [])
@@ -155,9 +157,9 @@ function formatType(someType) {
                 return result;
             case 'reflection':
                 if (!some.declaration.signatures)
-                    throw Error();
+                    throw Error('!some.declaration.signatures');
                 if (some.declaration.signatures.length !== 1)
-                    throw Error();
+                    throw Error('some.declaration.signatures.length !== 1');
                 const [signature] = some.declaration.signatures;
                 const type = signature.type ? getTypeRec(signature.type) : 'void';
                 const parameters = (signature.parameters ?? [])
@@ -171,34 +173,19 @@ function formatType(someType) {
                 return some.types.map(getTypeRec).join(' | ');
             default:
                 console.log(some);
-                throw Error();
+                throw Error(some.type);
         }
     }
 }
-function generateSourceLink(ref) {
-    if (!ref.sources || ref.sources.length < 1)
+function createSourceLink(reference) {
+    if (!reference.sources || reference.sources.length < 1)
         return '';
-    if (ref.sources.length > 1)
-        throw Error();
-    const [source] = ref.sources;
+    if (reference.sources.length > 1)
+        throw Error('ref.sources.length > 1');
+    const [source] = reference.sources;
     return `<sup><a href="${source.url}">[src]</a></sup>`;
 }
-function generateAnchor(ref) {
-    let typeName;
-    switch (ref.kind) {
-        case ReflectionKind.Class:
-            typeName = 'class';
-            break;
-        case ReflectionKind.Interface:
-            typeName = 'interface';
-            break;
-        case ReflectionKind.TypeAlias:
-            typeName = 'type';
-            break;
-        default:
-            console.log(ref);
-            throw new Error('Unknown reflection kind');
-    }
-    return `${typeName}_${ref.name}`.toLowerCase();
+function createAnchorId(reference) {
+    return `${getDeclarationTypeName(reference.kind)}_${reference.name}`.toLowerCase();
 }
 //# sourceMappingURL=typedoc.js.map

package/dist/lib/utils.d.ts

@@ -0,0 +1 @@
+export declare function getErrorMessage(error: unknown): string;

package/dist/lib/utils.js

@@ -0,0 +1,10 @@
+export function getErrorMessage(error) {
+    if (error == null)
+        return 'unknown';
+    if (typeof error === 'object') {
+        if ('message' in error)
+            return String(error.message);
+    }
+    return 'unknown';
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/release-tool",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "VersaTiles release and documentation tools",
   "bin": {
     "vrt": "./dist/index.js"
@@ -14,7 +14,7 @@
     "check": "npm run lint && npm run test && npm run build",
     "doc": "npx vrt cmd2md vrt | npx vrt insertmd README.md '# Command'",
     "lint": "eslint . --color",
-    "prepublish": "npm run build && npm run doc",
+    "prepack": "npm run build && npm run doc",
     "test": "cd ..; NODE_OPTIONS=--experimental-vm-modules jest --testPathPattern versatiles-release-tool"
   },
   "author": "yetzt <node@yetzt.me>, Michael Kreil <versatiles@michael-kreil.de>",
@@ -26,13 +26,14 @@
   },
   "homepage": "https://github.com/versatiles-org/node-versatiles/blob/main/versatiles-release-tool/README.md",
   "devDependencies": {
-    "@types/node": "^20.9.2",
-    "tsx": "^4.1.4",
+    "@types/node": "^20.10.0",
+    "tsx": "^4.4.0",
     "typescript": "^5.2.2"
   },
   "dependencies": {
     "commander": "^11.1.0",
     "remark": "^15.0.1",
+    "remark-gfm": "^4.0.0",
     "typedoc": "^0.25.3"
   }
 }