@versatiles/release-tool 2.5.0 → 2.7.0

package/dist/commands/markdown.js

@@ -1,7 +1,20 @@
 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) {
+    const exit = state.enter('blockquote');
+    const tracker = state.createTracker(info);
+    tracker.move('> ');
+    tracker.shift(2);
+    let value = state.indentLines(state.containerFlow(node, tracker.current()), (line, _index, blank) => '>' + (blank ? '' : ' ') + line);
+    exit();
+    // Unescape GitHub alert markers that remark-stringify escapes
+    value = value.replace(/^(>\s*)\\\[!(NOTE|WARNING|TIP|IMPORTANT|CAUTION)\]/m, '$1[!$2]');
+    return value;
+}
 /**
  * Injects a Markdown segment under a specified heading in a Markdown document.
  * Optionally, the injected segment can be made foldable for better readability.
@@ -24,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);
@@ -45,6 +58,9 @@ export function injectMarkdown(document, segment, heading, foldable) {
         .use(remarkStringify, {
         bullet: '-',
         rule: '-',
+        handlers: {
+            blockquote: blockquoteHandler,
+        },
     })
         .stringify(documentAst);
     return result;
@@ -62,7 +78,7 @@ export function updateTOC(main, heading) {
     const headingText = extractTextFromMDAsHTML(parseMarkdown(heading));
     // Build the TOC by iterating over each heading in the document.
     const toc = mainAst.children
-        .flatMap(c => {
+        .flatMap((c) => {
         // Skip non-heading nodes and the specified heading.
         if (c.type !== 'heading' || extractTextFromMDAsHTML(c) === headingText)
             return [];
@@ -87,23 +103,23 @@ 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.
     const indexes = mainAst.children.flatMap((c, index) => {
-        if ((c.type === 'heading') && (c.depth === sectionDepth) && extractTextFromMDAsHTML(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');
+        throw markdownError('section not found');
     if (indexes.length > 1)
-        throw Error('too many sections found');
+        throw markdownError('too many sections found');
     return indexes[0];
 }
 /**
@@ -133,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;
 }
 /**
@@ -142,9 +158,9 @@ function getHeadingDepth(mainAst, index) {
  * @param depth The depth to which the segment should be indented.
  */
 function indentSegmentToDepth(segmentAst, depth) {
-    segmentAst.children.forEach(node => {
+    segmentAst.children.forEach((node) => {
         if (node.type == 'heading')
-            return node.depth += depth;
+            return (node.depth += depth);
     });
 }
 /**
@@ -159,53 +175,113 @@ 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:
-            console.log(node);
-            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:
-                console.log(c);
-                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.
-    text = text.toLowerCase()
+    text = text
+        .toLowerCase()
         .replace(/[()]+/g, '')
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
@@ -213,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) {
@@ -220,25 +298,62 @@ 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);
     ast.children = children;
     function closeDetails(depth) {
-        while ((openDetails.length > 0) && (openDetails[0] >= depth)) {
+        while (openDetails.length > 0 && openDetails[0] >= depth) {
             children.push({ type: 'html', value: '</details>' });
             openDetails.shift();
         }
@@ -247,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':
@@ -273,19 +396,25 @@ export function nodeToHtml(node) {
                 attributes.push(`title="${node.title}"`);
             return `<img ${attributes.join(' ')} />`;
         }
-        case 'footnoteReference': throw new Error('Not implemented yet: "footnoteReference" case');
-        case 'imageReference': throw new Error('Not implemented yet: "imageReference" case');
-        case 'linkReference': throw new Error('Not implemented yet: "linkReference" case');
-        default:
-            console.log(node);
-            throw Error('unknown type');
+        // Reference types require definition resolution which is not supported
+        case 'footnoteReference':
+            throw notImplementedError('footnoteReference - requires definition resolution');
+        case 'imageReference':
+            throw notImplementedError('imageReference - requires definition resolution');
+        case 'linkReference':
+            throw notImplementedError('linkReference - requires definition resolution');
+        default: {
+            // TypeScript exhaustive check
+            const _exhaustiveCheck = node;
+            throw markdownError(`unhandled phrasing content type: ${node.type}`);
+        }
     }
 }
 function nodesToHtml(children) {
     return children.map(nodeToHtml).join('');
 }
 function textToHtml(text) {
-    return text.replace(/[^a-z0-9 ,.\-:_?@äöüß]/gi, c => `&#${c.charCodeAt(0)};`);
+    return text.replace(/[^a-z0-9 ,.\-:_?@äöüß]/gi, (c) => `&#${c.charCodeAt(0)};`);
 }
 export function parseMarkdown(document) {
     return remark().use(remarkGfm).parse(document);

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

@@ -1,2 +1,45 @@
 #!/usr/bin/env npx tsx
-export declare function release(directory: string, branch?: string): Promise<void>;
+/**
+ * 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>;