@versatiles/release-tool 1.2.7 → 2.1.0

package/LICENSE

@@ -1,21 +1,24 @@
-MIT License
+This is free and unencumbered software released into the public domain.
 
-Copyright (c) 2024 VersaTiles
+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.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+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 above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+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.
 
-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 OR COPYRIGHT HOLDERS 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

@@ -3,13 +3,14 @@
 
 # VersaTiles Release Tools
 
-Tools used internally for:
+Tools used 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)
-* releasing the current version as npm package: [`vrt release-npm`](#subcommand-vrt-release-npm)
+* creating a graph of the source code as mermaid: [`vrt deps-graph`](#subcommand-vrt-deps-graph)
+* upgrading all package dependencies: [`vrt deps-upgrade`](#subcommand-vrt-deps-upgrade)
+* creating Markdown documentation of executables: [`vrt doc-command`](#subcommand-vrt-doc-command)
+* inserting Markdown into documents: [`vrt doc-insert`](#subcommand-vrt-doc-insert)
+* updating "Table of Content" in Markdown files: [`vrt doc-toc`](#subcommand-vrt-doc-toc)
+* releasing the project as npm package: [`vrt release-npm`](#subcommand-vrt-release-npm)
 
 # Installation
 
@@ -37,8 +38,6 @@ You need to configure the scripts in the package.json:
 * `scripts.prepack` is **recommended** to ensure that all files are up-to-date before releasing. Here you can build code and documentation.
 * `scripts.release` is **recommended** to make it easy to release a new version.
 
-Have a look at this [package.json](https://github.com/versatiles-org/node-release-tool/blob/main/package.json) as an example.
-
 # Command `vrt`
 
 <!--- This chapter is generated automatically --->
@@ -47,95 +46,186 @@ Have a look at this [package.json](https://github.com/versatiles-org/node-releas
 $ vrt
 Usage: vrt [options] [command]
 
-versatiles release and documentaion tool
+CLI tool for releasing packages and generating documentation for
+Node.js/TypeScript projects.
 
 Options:
-  -h, --help                              display help for command
+  -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
-  release-npm [path]                      release a npm package
-  help [command]                          display help for command
+  check-package                             Check package.json for required scripts and other metadata.
+  deps-graph                                Analyze project files and output a dependency graph as Mermaid markup.
+  deps-upgrade                              Upgrade all dependencies in the current project to their latest versions.
+  doc-command <command>                     Generate Markdown documentation for a specified command and output the result.
+  doc-insert <readme> [heading] [foldable]  Insert Markdown from stdin into a specified section of a Markdown file.
+  doc-toc <readme> [heading]                Generate a Table of Contents (TOC) in a Markdown file.
+  doc-typescript [options]                  Generate documentation for a TypeScript project.
+  help [command]                            display help for command
+  release-npm [path]                        Publish an npm package from the specified path to the npm registry.
 ```
 
-## Subcommand: `vrt ts2md`
+## Subcommand: `vrt check-package`
 
 ```console
-$ vrt ts2md
-Usage: vrt ts2md [options] <typescript> <tsconfig>
+$ vrt check-package
+Usage: vrt check-package [options]
 
-documents a TypeScript file and outputs it to stdout
+Check package.json for required scripts and other metadata.
 
-Arguments:
-  typescript  Filename of the TypeScript file
-  tsconfig    Filename of tsconfig.json
+Options:
+  -h, --help  display help for command
+```
+
+## Subcommand: `vrt deps-graph`
+
+```console
+$ vrt deps-graph
+Usage: vrt deps-graph [options]
+
+Analyze project files and output a dependency graph as Mermaid markup.
+
+Options:
+  -h, --help  display help for command
+```
+
+## Subcommand: `vrt deps-upgrade`
+
+```console
+$ vrt deps-upgrade
+Usage: vrt deps-upgrade [options]
+
+Upgrade all dependencies in the current project to their latest versions.
 
 Options:
   -h, --help  display help for command
 ```
 
-## Subcommand: `vrt cmd2md`
+## Subcommand: `vrt doc-command`
 
 ```console
-$ vrt cmd2md
-Usage: vrt cmd2md [options] <command>
+$ vrt doc-command
+Usage: vrt doc-command [options] <command>
 
-documents a runnable command and outputs it to stdout
+Generate Markdown documentation for a specified command and output the result.
 
 Arguments:
-  command     command to run
+  command     Command to document (e.g., "npm run build").
 
 Options:
   -h, --help  display help for command
 ```
 
-## Subcommand: `vrt insertmd`
+## Subcommand: `vrt doc-insert`
 
 ```console
-$ vrt insertmd
-Usage: vrt insertmd [options] <readme> [heading] [foldable]
+$ vrt doc-insert
+Usage: vrt doc-insert [options] <readme> [heading] [foldable]
 
-takes Markdown from stdin and insert it into a Markdown file
+Insert Markdown from stdin into a specified section of 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)
+  readme      Path to the target Markdown file (e.g., README.md).
+  heading     Heading in the Markdown file where content should be placed.
+              Default is "# API". (default: "# API")
+  foldable    Whether to wrap the inserted content in a foldable section.
+              (default: false)
 
 Options:
   -h, --help  display help for command
 ```
 
-## Subcommand: `vrt inserttoc`
+## Subcommand: `vrt doc-toc`
 
 ```console
-$ vrt inserttoc
-Usage: vrt inserttoc [options] <readme> [heading]
+$ vrt doc-toc
+Usage: vrt doc-toc [options] <readme> [heading]
 
-updates the TOC in a Markdown file
+Generate a Table of Contents (TOC) in a Markdown file.
 
 Arguments:
-  readme      Markdown file, like a readme.md
-  heading     Heading in the Markdown file (default: "# Table of Content")
+  readme      Path to the Markdown file (e.g., README.md).
+  heading     Heading in the Markdown file where TOC should be inserted. Default
+              is "# Table of Content". (default: "# Table of Content")
 
 Options:
   -h, --help  display help for command
 ```
 
+## Subcommand: `vrt doc-typescript`
+
+```console
+$ vrt doc-typescript
+Usage: vrt doc-typescript [options]
+
+Generate documentation for a TypeScript project.
+
+Options:
+  -h, --help       display help for command
+  -i <entryPoint>  Entry point of the TypeScript project. Default is
+                   "./src/index.ts".
+  -o <outputPath>  Output path for the generated documentation. Default is
+                   "./docs".
+```
+
 ## Subcommand: `vrt release-npm`
 
 ```console
 $ vrt release-npm
 Usage: vrt release-npm [options] [path]
 
-release a npm package
+Publish an npm package from the specified path to the npm registry.
 
 Arguments:
-  path        root path of the Node.js project
+  path        Root path of the Node.js project. Defaults to the current
+              directory.
 
 Options:
   -h, --help  display help for command
 ```
+
+# Development
+
+## Dependency Graph
+
+<!--- This chapter is generated automatically --->
+
+```mermaid
+flowchart TB
+
+subgraph 0["src"]
+subgraph 1["commands"]
+2["check-package.ts"]
+5["deps-graph.ts"]
+6["deps-upgrade.ts"]
+8["doc-command.ts"]
+A["doc-typescript.ts"]
+B["markdown.ts"]
+C["release-npm.ts"]
+end
+subgraph 3["lib"]
+4["log.ts"]
+7["shell.ts"]
+9["utils.ts"]
+D["git.ts"]
+end
+E["index.ts"]
+end
+2-->4
+5-->4
+6-->4
+6-->7
+8-->9
+A-->4
+B-->9
+C-->D
+C-->4
+C-->7
+D-->7
+E-->2
+E-->5
+E-->6
+E-->8
+E-->A
+E-->B
+E-->C
+```

package/dist/commands/check-package.d.ts

@@ -0,0 +1 @@
+export declare function checkPackage(directory: string): void;

package/dist/commands/check-package.js

@@ -0,0 +1,53 @@
+import { readFileSync } from "node:fs";
+import { panic, info, warn } from '../lib/log.js';
+import { resolve } from 'node:path';
+export function checkPackage(directory) {
+    const pack = JSON.parse(readFileSync(resolve(directory, 'package.json'), 'utf8'));
+    const { scripts } = pack;
+    if (!scripts)
+        panic('scripts not found');
+    if (!scripts.test)
+        info('scripts.test is recommended');
+    if (!scripts.doc)
+        info('scripts.doc is recommended');
+    if (!scripts.build)
+        panic('scripts.build is required');
+    if (!scripts.check)
+        panic('scripts.check is required');
+    if (!scripts.check.includes('npm run build')) {
+        warn(`scripts.check should include "npm run build", but is "${scripts.check}"`);
+    }
+    if (!scripts.prepack)
+        panic('scripts.prepack is required');
+    if (scripts.prepack !== 'npm run build') {
+        warn(`scripts.prepack should be "npm run build", but is "${scripts.prepack}"`);
+    }
+    if (!scripts.release)
+        panic('scripts.release is required');
+    if (scripts.release !== 'vrt release-npm') {
+        warn(`scripts.release should be "vrt release-npm", but is "${scripts.release}"`);
+    }
+    if (!scripts.upgrade) {
+        warn('scripts.upgrade is recommended');
+    }
+    else if (scripts.upgrade !== 'vrt deps-upgrade') {
+        info(`scripts.upgrade should be "vrt deps-upgrade", but is "${scripts.upgrade}"`);
+    }
+    if (!scripts['doc-graph']) {
+        info(`scripts.doc-graph could be: "vrt deps-graph | vrt doc-insert README.md '## Dependency Graph'"`);
+    }
+    else {
+        if (scripts.doc && !scripts.doc.includes('npm run doc-graph')) {
+            info('scripts.doc should include "npm run doc-graph"');
+        }
+    }
+    ['npm-check-updates'].forEach((dep) => {
+        if (pack.dependencies?.[dep]) {
+            info(`dependencies "${dep}" is probably not needed`);
+        }
+        if (pack.devDependencies?.[dep]) {
+            info(`devDependencies "${dep}" is probably not needed`);
+        }
+    });
+}
+//# sourceMappingURL=check-package.js.map

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

@@ -0,0 +1 @@
+export declare function generateDependencyGraph(directory: string): Promise<void>;

package/dist/commands/deps-graph.js

@@ -0,0 +1,21 @@
+import { cruise } from 'dependency-cruiser';
+import { panic } from '../lib/log.js';
+export async function generateDependencyGraph(directory) {
+    let cruiseResult;
+    try {
+        cruiseResult = await cruise([directory], {
+            includeOnly: '^src',
+            outputType: 'mermaid',
+            exclude: ["\\.(test|d)\\.ts$", "node_modules"],
+        });
+    }
+    catch (pError) {
+        panic(String(pError));
+    }
+    let { output } = cruiseResult;
+    if (typeof output !== 'string')
+        panic('no output');
+    output = output.replace('flowchart LR', 'flowchart TB');
+    process.stdout.write(Buffer.from('```mermaid\n' + output + '```\n'));
+}
+//# sourceMappingURL=deps-graph.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * Upgrades the dependencies in a package.json file to their latest versions, removes existing
+ * installed modules, and reinstalls them in the specified directory.
+ *
+ * This function performs the following steps:
+ * 1. Checks for outdated dependencies by running `npm outdated --all --json`.
+ * 2. Reads the project's package.json file and updates any existing dependencies to their latest versions.
+ * 3. Removes all installed modules (`node_modules`) and the lock file (`package-lock.json`).
+ * 4. Reinstalls and updates all dependencies.
+ * 5. Logs a message indicating that all dependencies are up to date.
+ *
+ * @param directory - The path to the directory containing the Node.js project.
+ * @returns A promise that resolves when the process is complete.
+ */
+export declare function upgradeDependencies(directory: string): Promise<void>;

package/dist/commands/deps-upgrade.js

@@ -0,0 +1,97 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { check, info } from '../lib/log.js';
+import { getShell } from '../lib/shell.js';
+/**
+ * Upgrades the dependencies in a package.json file to their latest versions, removes existing
+ * installed modules, and reinstalls them in the specified directory.
+ *
+ * This function performs the following steps:
+ * 1. Checks for outdated dependencies by running `npm outdated --all --json`.
+ * 2. Reads the project's package.json file and updates any existing dependencies to their latest versions.
+ * 3. Removes all installed modules (`node_modules`) and the lock file (`package-lock.json`).
+ * 4. Reinstalls and updates all dependencies.
+ * 5. Logs a message indicating that all dependencies are up to date.
+ *
+ * @param directory - The path to the directory containing the Node.js project.
+ * @returns A promise that resolves when the process is complete.
+ */
+export async function upgradeDependencies(directory) {
+    const shell = getShell(directory);
+    // Step 1: Check and upgrade all versions
+    await check('Upgrade all versions', async () => {
+        const { stdout } = await shell.run('npm outdated --all --json', false);
+        const outdated = JSON.parse(stdout);
+        const latestVersion = new Map();
+        // Collect the latest version for each dependency
+        for (const [name, entry] of Object.entries(outdated)) {
+            let version = '0.0.0';
+            if (Array.isArray(entry)) {
+                for (const item of entry) {
+                    if (isGreaterSemver(item.latest, version))
+                        version = item.latest;
+                }
+            }
+            else {
+                version = entry.latest;
+            }
+            latestVersion.set(name, version);
+        }
+        // Load package.json
+        const pack = JSON.parse(readFileSync('package.json', 'utf8'));
+        // Update dependencies to their latest versions
+        patch(pack.dependencies);
+        patch(pack.devDependencies);
+        patch(pack.optionalDependencies);
+        patch(pack.peerDependencies);
+        // Write the updated package.json
+        writeFileSync('package.json', JSON.stringify(pack, null, 2) + '\n');
+        /**
+         * Mutates the provided dependency object by updating
+         * each dependency to the latest known version (if available).
+         *
+         * @param dependencies - A mapping of dependency names to their currently specified versions.
+         */
+        function patch(dependencies) {
+            if (!dependencies)
+                return;
+            for (const name of Object.keys(dependencies)) {
+                dependencies[name] = latestVersion.get(name) ?? dependencies[name];
+            }
+        }
+    });
+    // Step 2: Remove existing dependencies and lock file
+    await check('Remove all dependencies', async () => {
+        await shell.run('rm -rf node_modules');
+        await shell.run('rm -f package-lock.json');
+    });
+    // Step 3: Reinstall/upgrade all dependencies
+    await check('Upgrade all dependencies', shell.stdout('npm update --save'));
+    // Final log message
+    info('All dependencies are up to date');
+}
+/**
+ * Compares two semantic version strings (major.minor.patch) and checks if `a` is greater than `b`.
+ *
+ * @param a - A semantic version string (e.g., "1.2.3").
+ * @param b - Another semantic version string (e.g., "1.2.4").
+ * @returns `true` if `a` is greater than `b`, otherwise `false`.
+ * @throws If either version string is invalid (i.e., not in "x.x.x" format).
+ */
+function isGreaterSemver(a, b) {
+    const pa = a.split('.');
+    const pb = b.split('.');
+    for (let i = 0; i < 3; i++) {
+        const na = Number(pa[i]);
+        const nb = Number(pb[i]);
+        if (isNaN(na))
+            throw new Error('Invalid version number: ' + a);
+        if (isNaN(nb))
+            throw new Error('Invalid version number: ' + b);
+        if (na > nb)
+            return true;
+        if (na < nb)
+            return false;
+    }
+    return false;
+}
+//# sourceMappingURL=deps-upgrade.js.map

package/dist/commands/{command.js → doc-command.js}

@@ -31,7 +31,13 @@ export async function generateCommandDocumentation(command) {
  */
 async function getCommandResults(command) {
     return new Promise((resolve, reject) => {
-        const env = { ...process.env, NODE_ENV: undefined };
+        const env = {
+            ...process.env,
+            NODE_ENV: undefined,
+            NODE_DISABLE_COLORS: '1',
+            NO_COLORS: '1',
+            FORCE_COLOR: '0'
+        };
         // Spawn a child process to run the command with the '--help' flag.
         const childProcess = cp.spawn('npx', [...command.split(' '), '--help'], { env });
         let output = '';
@@ -81,4 +87,4 @@ function extractSubcommands(result) {
         return [subcommand];
     });
 }
-//# sourceMappingURL=command.js.map
+//# sourceMappingURL=doc-command.js.map

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

@@ -0,0 +1,4 @@
+export declare function generateTypescriptDocs(options: {
+    entryPoint?: string;
+    outputPath?: string;
+}): Promise<void>;

package/dist/commands/doc-typescript.js

@@ -0,0 +1,43 @@
+import * as td from 'typedoc';
+import * as tdMarkdown from 'typedoc-plugin-markdown';
+import * as tdTheme from 'typedoc-github-wiki-theme';
+import { panic, warn } from '../lib/log.js';
+export async function generateTypescriptDocs(options) {
+    const app = await td.Application.bootstrapWithPlugins({
+        entryPoints: [options.entryPoint ?? './src/index.ts'],
+        gitRevision: 'main',
+        outputs: [{ name: 'markdown', path: options.outputPath ?? './docs' }],
+    }, [
+        new td.ArgumentsReader(0),
+        new td.TypeDocReader(),
+        new td.PackageJsonReader(),
+        new td.TSConfigReader(),
+        new td.ArgumentsReader(300),
+    ]);
+    tdMarkdown.load(app);
+    tdTheme.load(app);
+    app.options.setValue('readme', 'none');
+    app.options.setValue('hidePageHeader', true);
+    app.options.setValue('classPropertiesFormat', 'table');
+    app.options.setValue('enumMembersFormat', 'table');
+    app.options.setValue('indexFormat', 'table');
+    app.options.setValue('interfacePropertiesFormat', 'table');
+    app.options.setValue('parametersFormat', 'table');
+    app.options.setValue('propertiesFormat', 'table');
+    app.options.setValue('propertyMembersFormat', 'table');
+    app.options.setValue('typeDeclarationFormat', 'table');
+    const project = await app.convert();
+    if (!project)
+        panic('Failed to convert project');
+    app.validate(project);
+    if (app.logger.hasWarnings())
+        warn('Warnings found during validation');
+    if (app.logger.hasErrors())
+        panic('Errors found during validation');
+    await app.generateOutputs(project);
+    if (app.logger.hasWarnings())
+        warn('Warnings found during validation');
+    if (app.logger.hasErrors())
+        panic('Errors found during validation');
+}
+//# sourceMappingURL=doc-typescript.js.map

package/dist/commands/{release.js → release-npm.js}

@@ -126,4 +126,4 @@ export async function release(directory, branch = 'main') {
         }
     }
 }
-//# sourceMappingURL=release.js.map
+//# sourceMappingURL=release-npm.js.map

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 #!/usr/bin/env -S node --enable-source-maps
 import { Command } from 'commander';
+/**
+ * Main CLI program, configured with custom text styling for titles, commands, options, etc.
+ */
 export declare const program: Command;

package/dist/index.js

@@ -1,67 +1,140 @@
 #!/usr/bin/env -S node --enable-source-maps
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { generateTsMarkdownDoc } from './commands/typedoc.js';
+import { styleText } from 'node:util';
 import { injectMarkdown, updateTOC } from './commands/markdown.js';
 import { Command, InvalidArgumentError } from 'commander';
 import { cwd } from 'node:process';
-import { generateCommandDocumentation } from './commands/command.js';
-import { release } from './commands/release.js';
+import { generateCommandDocumentation } from './commands/doc-command.js';
+import { release } from './commands/release-npm.js';
+import { upgradeDependencies } from './commands/deps-upgrade.js';
+import { generateDependencyGraph } from './commands/deps-graph.js';
+import { checkPackage } from './commands/check-package.js';
+import { generateTypescriptDocs } from './commands/doc-typescript.js';
+/**
+ * Main CLI program, configured with custom text styling for titles, commands, options, etc.
+ */
 export const program = new Command();
+program.configureHelp({
+    styleTitle: (str) => styleText('bold', str),
+    styleCommandText: (str) => styleText('bold', str),
+    styleOptionText: (str) => styleText('cyan', str),
+    styleArgumentText: (str) => styleText('green', str),
+    styleSubcommandText: (str) => styleText('yellow', str),
+    sortOptions: true,
+    sortSubcommands: true,
+});
 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 generateTsMarkdownDoc([tsFilename], tsConfig);
-    process.stdout.write(mdDocumentation);
+    .description('CLI tool for releasing packages and generating documentation for Node.js/TypeScript projects.');
+/**
+ * Command: check-package
+ * Checks that the project's package.json includes certain required scripts/fields.
+ */
+program.command('check-package')
+    .description('Check package.json for required scripts and other metadata.')
+    .action(() => {
+    void checkPackage(process.cwd());
+});
+/**
+ * Command: deps-graph
+ * Analyzes the project’s files to produce a dependency graph (in Mermaid format).
+ */
+program.command('deps-graph')
+    .description('Analyze project files and output a dependency graph as Mermaid markup.')
+    .action(() => {
+    void generateDependencyGraph(process.cwd());
 });
-program.command('cmd2md')
-    .description('documents a runnable command and outputs it to stdout')
-    .argument('<command>', 'command to run')
+/**
+ * Command: deps-upgrade
+ * Upgrades project dependencies in package.json to their latest versions and reinstalls them.
+ */
+program.command('deps-upgrade')
+    .description('Upgrade all dependencies in the current project to their latest versions.')
+    .action(() => {
+    void upgradeDependencies(process.cwd());
+});
+/**
+ * Command: doc-command
+ * Generates Markdown documentation for a given CLI command.
+ */
+program.command('doc-command')
+    .description('Generate Markdown documentation for a specified command and output the result.')
+    .argument('<command>', 'Command to document (e.g., "npm run build").')
     .action(async (command) => {
     const mdDocumentation = await 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)
+/**
+ * Command: doc-insert
+ * Inserts Markdown content from stdin into a specified Markdown file under a given heading.
+ * Optionally makes the inserted content foldable.
+ */
+program.command('doc-insert')
+    .description('Insert Markdown from stdin into a specified section of a Markdown file.')
+    .argument('<readme>', 'Path to the target Markdown file (e.g., README.md).', checkFilename)
+    .argument('[heading]', 'Heading in the Markdown file where content should be placed. Default is "# API".', '# API')
+    .argument('[foldable]', 'Whether to wrap the inserted content in a foldable section.', false)
     .action(async (mdFilename, heading, foldable) => {
     const buffers = [];
-    for await (const data of process.stdin)
+    for await (const data of process.stdin) {
         buffers.push(data);
-    const mdContent = '<!--- This chapter is generated automatically --->\n' + Buffer.concat(buffers).toString();
+    }
+    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')
+/**
+ * Command: doc-toc
+ * Updates or generates a Table of Contents in a Markdown file under a specified heading.
+ */
+program.command('doc-toc')
+    .description('Generate a Table of Contents (TOC) in a Markdown file.')
+    .argument('<readme>', 'Path to the Markdown file (e.g., README.md).', checkFilename)
+    .argument('[heading]', 'Heading in the Markdown file where TOC should be inserted. Default is "# Table of Content".', '# Table of Content')
     .action((mdFilename, heading) => {
     let mdFile = readFileSync(mdFilename, 'utf8');
     mdFile = updateTOC(mdFile, heading);
     writeFileSync(mdFilename, mdFile);
 });
+/**
+ * Command: doc-typescript
+ * Generates documentation for a TypeScript project.
+ * Allows specifying entry point and output location.
+ */
+program.command('doc-typescript')
+    .description('Generate documentation for a TypeScript project.')
+    .option('-i <entryPoint>', 'Entry point of the TypeScript project. Default is "./src/index.ts".')
+    .option('-o <outputPath>', 'Output path for the generated documentation. Default is "./docs".')
+    .action(async (options) => {
+    await generateTypescriptDocs(options);
+});
+/**
+ * Command: release-npm
+ * Releases/publishes an npm package from a specified project path to the npm registry.
+ */
 program.command('release-npm')
-    .description('release a npm package')
-    .argument('[path]', 'root path of the Node.js project')
+    .description('Publish an npm package from the specified path to the npm registry.')
+    .argument('[path]', 'Root path of the Node.js project. Defaults to the current directory.')
     .action((path) => {
-    void release(resolve(path ?? ',', process.cwd()), 'main');
+    void release(resolve(path ?? '.', process.cwd()), 'main');
 });
 if (process.env.NODE_ENV !== 'test') {
     await program.parseAsync();
 }
+/**
+ * Validates that the given filename exists.
+ * Throws an InvalidArgumentError if the file cannot be found.
+ *
+ * @param filename - The filename to check.
+ * @returns The resolved full path if the file exists.
+ */
 function checkFilename(filename) {
     const fullname = resolve(cwd(), filename);
     if (!existsSync(fullname)) {
-        throw new InvalidArgumentError('file not found');
+        throw new InvalidArgumentError(`File not found: ${filename}`);
     }
     return fullname;
 }

package/dist/lib/log.d.ts

@@ -2,4 +2,4 @@ export declare function panic(text: string): never;
 export declare function warn(text: string): void;
 export declare function info(text: string): void;
 export declare function abort(): never;
-export declare function check<T>(message: string, promise: Promise<T>): Promise<T>;
+export declare function check<T>(message: string, promise: (Promise<T>) | (() => Promise<T>)): Promise<T>;

package/dist/lib/log.js

@@ -15,14 +15,14 @@ export function abort() {
 export async function check(message, promise) {
     process.stderr.write(`\x1b[0;90m\u2B95 ${message}\x1b[0m`);
     try {
-        const result = await promise;
+        const result = await (typeof promise === 'function' ? promise() : promise);
         process.stderr.write(`\r\x1b[0;92m\u2714 ${message}\x1b[0m\n`);
         return result;
     }
     catch (error) {
         process.stderr.write(`\r\x1b[0;91m\u2718 ${message}\x1b[0m\n`);
         panic(error.message);
-        throw Error();
+        throw error;
     }
 }
 //# sourceMappingURL=log.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/release-tool",
-  "version": "1.2.7",
+  "version": "2.1.0",
   "description": "VersaTiles release and documentation tools",
   "bin": {
     "vrt": "./dist/index.js"
@@ -10,44 +10,49 @@
     "dist/**/*.d.ts"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/index.js",
+    "build": "npm run build-node && npm run doc",
+    "build-node": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/index.js",
     "check": "npm run lint && npm run build && npm run test",
-    "doc": "npx vrt cmd2md vrt | npx vrt insertmd README.md '# Command'",
+    "dev": "tsx src/index.ts",
+    "doc": "npm run doc-command && npm run doc-graph",
+    "doc-command": "tsx src/index.ts doc-command vrt | tsx src/index.ts doc-insert README.md '# Command'",
+    "doc-graph": "tsx src/index.ts deps-graph | tsx src/index.ts doc-insert README.md '## Dependency Graph'",
     "lint": "eslint . --color",
-    "prepack": "npm run build && npm run doc",
-    "release": "npm run build && npx vrt release-npm",
+    "prepack": "npm run build",
+    "release": "tsx src/index.ts release-npm",
     "test-coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest",
-    "upgrade": "npm-check-updates -u && rm -f package-lock.json; rm -rf node_modules; npm i && npm update"
+    "upgrade": "tsx src/index.ts deps-upgrade"
   },
-  "author": "yetzt <node@yetzt.me>, Michael Kreil <versatiles@michael-kreil.de>",
+  "author": "Michael Kreil <versatiles@michael-kreil.de>",
   "license": "Unlicense",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/versatiles-org/node-versatiles.git"
+    "url": "git+https://github.com/versatiles-org/node-release-tool.git"
   },
-  "homepage": "https://github.com/versatiles-org/node-versatiles/blob/main/versatiles-release-tool/README.md",
+  "homepage": "https://github.com/versatiles-org/node-release-tool",
   "devDependencies": {
-    "@types/inquirer": "^9.0.7",
+    "@schemastore/package": "^0.0.10",
     "@types/jest": "^29.5.14",
-    "@types/node": "^22.13.0",
+    "@types/node": "^22.13.5",
     "@typescript-eslint/eslint-plugin": "^8.22.0",
     "@typescript-eslint/parser": "^8.22.0",
-    "eslint": "^9.19.0",
+    "eslint": "^9.21.0",
     "jest": "^29.7.0",
-    "npm-check-updates": "^17.1.14",
     "ts-jest": "^29.2.5",
-    "ts-node": "^10.9.2",
-    "tsx": "^4.19.2",
+    "tsx": "^4.19.3",
     "typescript": "^5.7.3",
-    "typescript-eslint": "^8.22.0"
+    "typescript-eslint": "^8.24.1"
   },
   "dependencies": {
-    "@inquirer/select": "^4.0.7",
+    "@inquirer/select": "^4.0.9",
     "commander": "^13.1.0",
+    "dependency-cruiser": "^16.10.0",
     "remark": "^15.0.1",
-    "remark-gfm": "^4.0.0",
-    "typedoc": "^0.27.6"
+    "remark-gfm": "^4.0.1",
+    "typedoc": "^0.27.8",
+    "typedoc-github-wiki-theme": "^2.1.0",
+    "typedoc-plugin-markdown": "^4.4.2"
   }
 }

package/LICENSE.md

@@ -1,24 +0,0 @@
-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/dist/commands/typedoc.d.ts

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

package/dist/commands/typedoc.js

@@ -1,282 +0,0 @@
-import { Application, ReflectionKind, } from 'typedoc';
-/**
- * Generate markdown documentation from TypeScript files.
- * @param sourceFilePaths - Array of absolute TypeScript file paths.
- * @param tsConfigPath - Absolute file path of tsconfig.json.
- */
-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 TypeScript project.');
-    }
-    return Array.from(documentProject(project)).join('\n');
-}
-function* documentProject(project) {
-    if (!project.groups) {
-        throw new Error('No TypeScript code to document found! Is this a lib?');
-    }
-    for (const group of project.groups) {
-        yield '\n# ' + group.title;
-        for (const d of group.children) {
-            const declaration = d;
-            switch (declaration.kind) {
-                case ReflectionKind.Class:
-                    yield* documentClass(declaration);
-                    break;
-                case ReflectionKind.Function:
-                    yield* documentMethod(declaration, 2);
-                    break;
-                case ReflectionKind.Interface:
-                    yield* documentInterface(declaration);
-                    break;
-                case ReflectionKind.TypeAlias:
-                    yield* documentType(declaration);
-                    break;
-                case ReflectionKind.Variable:
-                    yield* documentVariable(declaration);
-                    break;
-                default:
-                    throw new Error('implement ' + declaration.kind);
-            }
-        }
-    }
-}
-function* documentInterface(declaration) {
-    yield `\n## Interface: \`${declaration.name}\`<a id="${createAnchorId(declaration)}"></a>`;
-    yield '\n```typescript';
-    yield 'interface {';
-    for (const child of declaration.children ?? []) {
-        if (child.kind !== ReflectionKind.Property)
-            throw Error('should be a property inside an interface');
-        if (child.type == null)
-            throw Error('should have a type');
-        const name = child.name + (child.flags.isOptional ? '?' : '');
-        yield `  ${name}: ${formatTypeDeclaration(child.type)};`;
-    }
-    yield '}';
-    yield '```';
-}
-function* documentType(declaration) {
-    yield `\n## Type: \`${declaration.name}\`<a id="${createAnchorId(declaration)}"></a>`;
-    if (declaration.type) {
-        yield `\n**Type:** <code>${formatTypeDeclaration(declaration.type)}</code>`;
-    }
-}
-function* documentClass(declaration) {
-    yield `\n## Class: \`${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)
-            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('publicMembers.length !== 1');
-                yield* documentMethod(publicMembers[0], 3, true);
-                continue;
-            case 'Accessors':
-                yield '\n### Accessors';
-                for (const member of publicMembers)
-                    yield documentAccessor(member);
-                continue;
-            case 'Properties':
-                yield '\n### Properties';
-                for (const member of publicMembers)
-                    yield documentProperty(member);
-                continue;
-            case 'Methods':
-                for (const member of publicMembers)
-                    yield* documentMethod(member, 3);
-                continue;
-            default:
-                console.log(group);
-                throw Error('Unknown group title');
-        }
-    }
-}
-function* documentMethod(method, depth, isConstructor = false) {
-    if (method.signatures?.length !== 1)
-        throw Error('should be 1');
-    const [signature] = method.signatures;
-    const parameters = formatMethodParameters(signature.parameters ?? []);
-    if (isConstructor) {
-        yield `\n${'#'.repeat(depth)} Constructor: \`new ${signature.name}(${parameters})\``;
-    }
-    else {
-        yield `\n${'#'.repeat(depth)} Method: \`${signature.name}(${parameters})\``;
-    }
-    yield* documentSummaryBlock(signature);
-    if (signature.parameters && signature.parameters.length > 0) {
-        yield '';
-        yield '**Parameters:**';
-        for (const parameter of signature.parameters) {
-            yield documentProperty(parameter);
-        }
-    }
-    if (signature.type && !isConstructor) {
-        yield `\n**Returns:** <code>${formatTypeDeclaration(signature.type)}</code>`;
-    }
-}
-function formatMethodParameters(parameters) {
-    return parameters.map(param => param.name).join(', ');
-}
-// Helper Functions
-function getDeclarationKindName(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 documentProperty(ref) {
-    let line = `  - <code>${ref.name}${resolveTypeDeclaration(ref.type)}</code>`;
-    if (ref.flags.isOptional)
-        line += ' (optional)';
-    const summary = extractSummary(ref.comment);
-    if (summary != null)
-        line += '  \n    ' + summary;
-    return line;
-}
-function* documentVariable(ref) {
-    const prefix = ref.flags.isConst ? 'const' : 'let';
-    yield `\n## \`${prefix} ${ref.name}\``;
-    const summary = extractSummary(ref.comment);
-    if (summary != null)
-        yield summary;
-}
-function documentAccessor(ref) {
-    let line = `  - <code>${ref.name}${resolveTypeDeclaration(ref.type)}</code>`;
-    const summary = extractSummary(ref.comment);
-    if (summary != null)
-        line += '  \n    ' + summary;
-    return line;
-}
-function extractSummary(comment) {
-    if (!comment)
-        return null;
-    return comment.summary.map(line => line.text).join('');
-}
-function* documentSummaryBlock(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('type.declaration.signatures?.length !== 1');
-        const [signature] = type.declaration.signatures;
-        if (signature.comment) {
-            yield formatComment(signature.comment);
-            return;
-        }
-    }
-    const sourceLink = createSourceLink(ref);
-    if (sourceLink != null)
-        yield sourceLink;
-    return;
-    function formatComment(comment) {
-        let summary = extractSummary(comment) ?? '';
-        const link = createSourceLink(ref);
-        if (link != null)
-            summary += ' ' + link;
-        return summary.replace(/\n/mg, '  \n') + '\n';
-    }
-}
-function resolveTypeDeclaration(someType) {
-    if (!someType)
-        return '';
-    return `: ${formatTypeDeclaration(someType)}`;
-}
-function formatTypeDeclaration(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}](#${createAnchorId(some.reflection)})`;
-                if (some.typeArguments?.length ?? 0)
-                    result += '&lt;'
-                        + (some.typeArguments ?? [])
-                            .map(getTypeRec).join(',')
-                        + '&gt;';
-                return result;
-            }
-            case 'reflection':
-                switch (some.declaration.kind) {
-                    case ReflectionKind.TypeLiteral: return decodeReflectionTypeLiteral(some.declaration);
-                    default:
-                        console.log('declarationKindName', getDeclarationKindName(some.declaration.kind));
-                        console.dir(some, { depth: 4 });
-                        throw Error();
-                }
-            case 'tuple':
-                return `[${some.elements.map(getTypeRec).join(', ')}]`;
-            case 'union':
-                return some.types.map(getTypeRec).join(' | ');
-            case 'array':
-                return getTypeRec(some.elementType) + '[]';
-            default:
-                console.log(some);
-                throw Error(some.type);
-        }
-        function decodeReflectionTypeLiteral(ref) {
-            try {
-                if (ref.variant !== 'declaration')
-                    throw Error();
-                if (ref.groups && !ref.signatures) {
-                    if (!Array.isArray(ref.groups))
-                        throw Error();
-                    if (ref.groups.length !== 1)
-                        throw Error();
-                    const [group] = ref.groups;
-                    if (group.title !== 'Properties')
-                        throw Error();
-                    const properties = group.children.map(r => r.escapedName + ':?');
-                    return `{${properties.join(', ')}}`;
-                }
-                if (!ref.groups && ref.signatures) {
-                    if (ref.signatures.length !== 1)
-                        throw Error('ref.signatures.length !== 1');
-                    const [signature] = ref.signatures;
-                    const returnType = signature.type ? getTypeRec(signature.type) : 'void';
-                    const parameters = (signature.parameters ?? [])
-                        .map(p => {
-                        return p.name + (p.type ? ': ' + getTypeRec(p.type) : '');
-                    }).join(', ');
-                    return `(${parameters}) => ${returnType}`;
-                }
-                throw Error();
-            }
-            catch (error) {
-                console.dir(ref, { depth: 3 });
-                throw error;
-            }
-        }
-    }
-}
-function createSourceLink(reference) {
-    if (!reference.sources || reference.sources.length < 1)
-        return null;
-    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 createAnchorId(reference) {
-    return `${getDeclarationKindName(reference.kind)}_${reference.name}`.toLowerCase();
-}
-//# sourceMappingURL=typedoc.js.map