@versatiles/release-tool 1.0.0

package/LICENSE.md

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to [unlicense.org](https://unlicense.org/)

package/README.md

@@ -0,0 +1,93 @@
+# VersaTiles Release Tools
+
+Tools used internally for:
+
+* creating Markdown documentation of TypeScript libraries: [`vrt ts2md`](#subcommand-vrt-ts2md)
+* creating Markdown documentation of executables: [`vrt cmd2md`](#subcommand-vrt-cmd2md)
+* inserting Markdown into documents: [`vrt insertmd`](#subcommand-vrt-insertmd)
+* updating "Table of Content" in Markdown files: [`vrt inserttoc`](#subcommand-vrt-inserttoc)
+
+# Command `vrt`
+
+<!--- This chapter is generated automatically --->
+
+```console
+$ vrt
+Usage: vrt [options] [command]
+
+versatiles release and documentaion tool
+
+Options:
+  -h, --help                              display help for command
+
+Commands:
+  ts2md <typescript> <tsconfig>           documents a TypeScript file and outputs it to stdout
+  cmd2md <command>                        documents a runnable command and outputs it to stdout
+  insertmd <readme> [heading] [foldable]  takes Markdown from stdin and insert it into a Markdown file
+  inserttoc <readme> [heading]            updates the TOC in a Markdown file
+  help [command]                          display help for command
+```
+
+## Subcommand: `vrt ts2md`
+
+```console
+$ vrt ts2md
+Usage: vrt ts2md [options] <typescript> <tsconfig>
+
+documents a TypeScript file and outputs it to stdout
+
+Arguments:
+  typescript  Filename of the TypeScript file
+  tsconfig    Filename of tsconfig.json
+
+Options:
+  -h, --help  display help for command
+```
+
+## Subcommand: `vrt cmd2md`
+
+```console
+$ vrt cmd2md
+Usage: vrt cmd2md [options] <command>
+
+documents a runnable command and outputs it to stdout
+
+Arguments:
+  command     command to run
+
+Options:
+  -h, --help  display help for command
+```
+
+## Subcommand: `vrt insertmd`
+
+```console
+$ vrt insertmd
+Usage: vrt insertmd [options] <readme> [heading] [foldable]
+
+takes Markdown from stdin and insert it into a Markdown file
+
+Arguments:
+  readme      Markdown file, like a readme.md
+  heading     Heading in the Markdown file (default: "# API")
+  foldable    Make content foldable (default: false)
+
+Options:
+  -h, --help  display help for command
+```
+
+## Subcommand: `vrt inserttoc`
+
+```console
+$ vrt inserttoc
+Usage: vrt inserttoc [options] <readme> [heading]
+
+updates the TOC in a Markdown file
+
+Arguments:
+  readme      Markdown file, like a readme.md
+  heading     Heading in the Markdown file (default: "# Table of Content")
+
+Options:
+  -h, --help  display help for command
+```

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node --enable-source-maps
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { generateMarkdownDocumentation } from './lib/typedoc.js';
+import { injectMarkdown, updateTOC } from './lib/markdown.js';
+import { Command, InvalidArgumentError } from 'commander';
+import { cwd } from 'node:process';
+import { generateCommandDocumentation } from './lib/command.js';
+const program = new Command();
+program
+    .name('vrt')
+    .description('versatiles release and documentaion tool');
+program.command('ts2md')
+    .description('documents a TypeScript file and outputs it to stdout')
+    .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);
+    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);
+    process.stdout.write(mdDocumentation);
+});
+program.command('insertmd')
+    .description('takes Markdown from stdin and insert it into a Markdown file')
+    .argument('<readme>', 'Markdown file, like a readme.md', checkFilename)
+    .argument('[heading]', 'Heading in the Markdown file', '# API')
+    .argument('[foldable]', 'Make content foldable', false)
+    .action(async (mdFilename, heading, foldable) => {
+    const buffers = [];
+    for await (const data of process.stdin)
+        buffers.push(data);
+    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);
+});
+program.command('inserttoc')
+    .description('updates the TOC in a Markdown file')
+    .argument('<readme>', 'Markdown file, like a readme.md', checkFilename)
+    .argument('[heading]', 'Heading in the Markdown file', '# Table of Content')
+    .action((mdFilename, heading) => {
+    let mdFile = readFileSync(mdFilename, 'utf8');
+    mdFile = updateTOC(mdFile, heading);
+    writeFileSync(mdFilename, mdFile);
+});
+program.parse();
+function checkFilename(filename) {
+    const fullname = resolve(cwd(), filename);
+    if (!existsSync(fullname)) {
+        throw new InvalidArgumentError('file not found');
+    }
+    return fullname;
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/command.d.ts

@@ -0,0 +1 @@
+export declare function generateCommandDocumentation(command: string): string;

package/dist/lib/command.js

@@ -0,0 +1,42 @@
+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}`;
+    }
+    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')
+        .flatMap((line) => {
+        const extract = /^  ([^ ]{2,})/.exec(line);
+        if (!extract)
+            return [];
+        // eslint-disable-next-line @typescript-eslint/prefer-destructuring
+        const subcommand = extract[1];
+        if (subcommand === 'help')
+            return [];
+        return [subcommand];
+    });
+    return {
+        markdown: [
+            '```console',
+            '$ ' + command,
+            result,
+            '```',
+            '',
+        ].join('\n'),
+        subcommands,
+    };
+}
+//# sourceMappingURL=command.js.map

package/dist/lib/markdown.d.ts

@@ -0,0 +1,2 @@
+export declare function injectMarkdown(document: string, segment: string, heading: string, foldable?: boolean): string;
+export declare function updateTOC(main: string, heading: string): string;

package/dist/lib/markdown.js

@@ -0,0 +1,193 @@
+import { remark } from 'remark';
+// 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);
+    let startIndex;
+    try {
+        startIndex = findSegmentStart(documentAst, headingAst);
+    }
+    catch (error) {
+        console.error(`While searching for segment "${heading}" …`);
+        throw error;
+    }
+    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);
+    return remark().stringify(documentAst);
+}
+export function updateTOC(main, heading) {
+    const mainAst = remark().parse(main);
+    const headingText = getMDText(remark().parse(heading));
+    const toc = mainAst.children
+        .flatMap(c => {
+        if (c.type !== 'heading')
+            return [];
+        const text = getMDText(c);
+        if (text === headingText)
+            return [];
+        const indention = '  '.repeat((c.depth - 1) * 2);
+        const anchor = getMDAnchor(c);
+        return `${indention}* [${text}](#${anchor})\n`;
+    })
+        .join('');
+    return injectMarkdown(main, toc, heading);
+}
+function findSegmentStart(mainAst, headingAst) {
+    if (headingAst.children.length !== 1)
+        throw Error();
+    if (headingAst.children[0].type !== 'heading')
+        throw Error();
+    const sectionDepth = headingAst.children[0].depth;
+    const sectionText = getMDText(headingAst);
+    const indexes = mainAst.children.flatMap((c, index) => {
+        if ((c.type === 'heading') && (c.depth === sectionDepth) && getMDText(c).startsWith(sectionText)) {
+            return [index];
+        }
+        return [];
+    });
+    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) {
+    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 mainAst.children.length;
+}
+function getHeadingDepth(mainAst, index) {
+    const node = mainAst.children[index];
+    if (node.type !== 'heading')
+        throw Error();
+    return node.depth;
+}
+function indentChapter(segmentAst, depth) {
+    segmentAst.children.forEach(node => {
+        switch (node.type) {
+            case 'code':
+            case 'html':
+            case 'list':
+            case 'listItem':
+            case 'paragraph':
+            case 'text':
+                return;
+            case 'heading':
+                return node.depth += depth;
+            default:
+                console.log(node);
+                throw Error('unknown type: ' + node.type);
+        }
+    });
+}
+// eslint-disable-next-line @typescript-eslint/max-params
+function spliceAst(mainAst, segmentAst, startIndex, endIndex) {
+    mainAst.children.splice(startIndex, endIndex - startIndex, ...segmentAst.children);
+}
+function getMDText(node) {
+    switch (node.type) {
+        case 'inlineCode':
+        case 'text':
+            return node.value;
+        case 'heading':
+        case 'root':
+            return node.children.map(getMDText).join('');
+        case 'html':
+            return '';
+        default:
+            console.log(node);
+            throw Error('unknown type: ' + node.type);
+    }
+}
+function getMDAnchor(node) {
+    let text = '';
+    for (const c of node.children) {
+        switch (c.type) {
+            case 'html':
+                const match = /<a\s.*id\s*=\s*['"]([^'"]+)/i.exec(c.value);
+                if (match)
+                    return match[1];
+                break;
+            case 'text':
+            case 'inlineCode':
+                text += c.value;
+                break;
+            default:
+                console.log(c);
+                throw Error('unknown type: ' + c.type);
+        }
+    }
+    text = text.toLowerCase()
+        .replace(/[()]+/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^\-+|\-+$/g, '');
+    return text;
+}
+function makeFoldable(ast) {
+    const openDetails = [];
+    const children = [];
+    ast.children.forEach((c) => {
+        switch (c.type) {
+            case 'html':
+            case 'list':
+            case 'paragraph':
+                children.push(c);
+                break;
+            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}"`);
+        }
+    });
+    closeDetails(0);
+    ast.children = children;
+    function closeDetails(depth) {
+        while ((openDetails.length > 0) && (openDetails[0] >= depth)) {
+            children.push({ type: 'html', value: '</details>' });
+            openDetails.shift();
+        }
+    }
+}
+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 textToHtml(text) {
+    return text.replace(/[^a-z0-9 ,.-:_?@äöüß]/gi, c => `&#${c.charCodeAt(0)};`);
+}
+//# sourceMappingURL=markdown.js.map

package/dist/lib/typedoc.d.ts

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

package/dist/lib/typedoc.js

@@ -0,0 +1,204 @@
+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.
+ */
+export async function generateMarkdownDocumentation(entryPoints, tsconfig) {
+    const app = await Application.bootstrap({ entryPoints, tsconfig });
+    const project = await app.convert();
+    if (!project) {
+        throw new Error('Failed to convert project.');
+    }
+    return Array.from(renderProjectDocumentation(project)).join('\n');
+}
+function* renderProjectDocumentation(project) {
+    if (!project.groups) {
+        throw new Error('No code to document found! Is this a lib?');
+    }
+    for (const group of project.groups) {
+        for (const declaration of group.children) {
+            yield* renderDeclaration(declaration);
+        }
+    }
+}
+function* renderDeclaration(declaration) {
+    const typeName = formatTypeName(declaration.kind);
+    yield `# ${typeName}: \`${declaration.name}\`<a id="${generateAnchor(declaration)}"></a>`;
+    yield* renderSummaryBlock(declaration);
+    for (const group of declaration.groups ?? []) {
+        const publicMembers = group.children.filter(member => !member.flags.isPrivate && !member.flags.isProtected);
+        if (publicMembers.length === 0)
+            continue;
+        // Sort by order in code
+        publicMembers.sort((a, b) => a.id - b.id);
+        switch (group.title) {
+            case 'Constructors':
+                if (publicMembers.length !== 1)
+                    throw Error();
+                yield* renderMethod(publicMembers[0], true);
+                continue;
+            case 'Properties':
+                //yield '';
+                //yield '**Properties**';
+                for (const member of publicMembers)
+                    yield formatParameter(member);
+                continue;
+            case 'Methods':
+                //yield '';
+                //yield '**Methods**';
+                for (const member of publicMembers)
+                    yield* renderMethod(member);
+                continue;
+            default:
+                console.log(group);
+                throw Error('Unknown group title');
+        }
+    }
+    if (declaration.type) {
+        yield `\n**Type:** <code>${formatType(declaration.type)}</code>`;
+    }
+}
+function* renderMethod(declaration, isConstructor = false) {
+    if (declaration.signatures?.length !== 1)
+        throw Error('should be 1');
+    const [signature] = declaration.signatures;
+    const functionName = signature.name;
+    const parameters = formatMethodParameters(signature.parameters ?? []);
+    const returnType = signature.type;
+    const prefix = isConstructor ? 'Constructor' : 'Method';
+    yield `## ${prefix}: \`${functionName}(${parameters})\``;
+    yield '';
+    yield* renderSummaryBlock(signature);
+    if (signature.parameters && signature.parameters.length > 0) {
+        yield '';
+        yield '**Parameters:**';
+        for (const parameter of signature.parameters) {
+            yield formatParameter(parameter);
+        }
+    }
+    if (returnType) {
+        yield '';
+        yield `**Returns:** <code>${formatType(returnType)}</code>`;
+    }
+}
+function formatMethodParameters(parameters) {
+    return parameters.map(param => param.name).join(', ');
+}
+// Helper Functions
+function formatTypeName(kind) {
+    switch (kind) {
+        case ReflectionKind.Class: return 'Class';
+        case ReflectionKind.Interface: return 'Interface';
+        case ReflectionKind.TypeAlias: return 'Type';
+        default: throw new Error(`Unknown reflection kind: ${kind}`);
+    }
+}
+function formatParameter(ref) {
+    let line = `  - <code>${ref.name}${resolveTypeDeclaration(ref.type)}</code>`;
+    if (ref.flags.isOptional)
+        line += ' (optional)';
+    const summary = extractSummary(ref.comment);
+    if (summary)
+        line += '  \n    ' + summary;
+    return line;
+}
+function extractSummary(comment) {
+    if (!comment)
+        return '';
+    return comment.summary.map(line => line.text).join('');
+}
+function* renderSummaryBlock(ref) {
+    yield '';
+    if (ref.comment) {
+        yield formatComment(ref.comment);
+        return;
+    }
+    const { type } = ref;
+    if (type?.type === 'reflection') {
+        if (type.declaration.signatures?.length !== 1)
+            throw Error();
+        const [signature] = type.declaration.signatures;
+        if (signature.comment) {
+            yield formatComment(signature.comment);
+            return;
+        }
+    }
+    yield generateSourceLink(ref) + '\n';
+    return;
+    function formatComment(comment) {
+        return (extractSummary(comment) + ' ' + generateSourceLink(ref)).replace(/\n/m, '  \n') + '\n';
+    }
+}
+function resolveTypeDeclaration(someType) {
+    if (!someType)
+        return '';
+    return `: ${formatType(someType)}`;
+}
+function formatType(someType) {
+    return getTypeRec(someType);
+    function getTypeRec(some) {
+        switch (some.type) {
+            case 'intrinsic':
+                return some.name;
+            case 'literal':
+                return JSON.stringify(some.value);
+            case 'reference':
+                let result = some.name;
+                if (some.reflection)
+                    result = `[${result}](#${generateAnchor(some.reflection)})`;
+                if (some.typeArguments?.length ?? 0)
+                    result += '<'
+                        + (some.typeArguments ?? [])
+                            .map(getTypeRec).join(',')
+                        + '>';
+                return result;
+            case 'reflection':
+                if (!some.declaration.signatures)
+                    throw Error();
+                if (some.declaration.signatures.length !== 1)
+                    throw Error();
+                const [signature] = some.declaration.signatures;
+                const type = signature.type ? getTypeRec(signature.type) : 'void';
+                const parameters = (signature.parameters ?? [])
+                    .map(p => {
+                    return p.name + (p.type ? ': ' + getTypeRec(p.type) : '');
+                }).join(', ');
+                return `(${parameters}) => ${type}`;
+            case 'tuple':
+                return `[${some.elements.map(getTypeRec).join(', ')}]`;
+            case 'union':
+                return some.types.map(getTypeRec).join(' | ');
+            default:
+                console.log(some);
+                throw Error();
+        }
+    }
+}
+function generateSourceLink(ref) {
+    if (!ref.sources || ref.sources.length < 1)
+        return '';
+    if (ref.sources.length > 1)
+        throw Error();
+    const [source] = ref.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();
+}
+//# sourceMappingURL=typedoc.js.map

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@versatiles/release-tool",
+  "version": "1.0.0",
+  "description": "VersaTiles release and documentation tools",
+  "bin": {
+    "vrt": "./dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/index.js",
+    "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",
+    "test": "cd ..; NODE_OPTIONS=--experimental-vm-modules jest --testPathPattern versatiles-release-tool"
+  },
+  "author": "yetzt <node@yetzt.me>, Michael Kreil <versatiles@michael-kreil.de>",
+  "license": "Unlicense",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/versatiles-org/node-versatiles.git"
+  },
+  "homepage": "https://github.com/versatiles-org/node-versatiles/blob/main/versatiles-release-tool/README.md",
+  "devDependencies": {
+    "@types/node": "^20.9.2",
+    "remark": "^15.0.1",
+    "tsx": "^4.1.4",
+    "typedoc": "^0.25.3",
+    "typescript": "^5.2.2"
+  },
+  "dependencies": {
+    "commander": "^11.1.0"
+  }
+}