@versatiles/release-tool 1.0.3 → 1.2.0

package/README.md

@@ -1,3 +1,6 @@
+[![Code Coverage](https://codecov.io/gh/versatiles-org/node-release-tool/branch/main/graph/badge.svg?token=IDHAI13M0K)](https://codecov.io/gh/versatiles-org/node-release-tool)
+[![GitHub Workflow Status)](https://img.shields.io/github/actions/workflow/status/versatiles-org/node-release-tool/ci.yml)](https://github.com/versatiles-org/node-release-tool/actions/workflows/ci.yml)
+
 # VersaTiles Release Tools
 
 Tools used internally for:
@@ -6,6 +9,35 @@ Tools used internally for:
 * 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)
+
+# Installation
+
+```bash
+npm i -D @versatiles/release-tool
+```
+
+# configure scripts
+
+You need to configure the scripts in the package.json:
+
+```JSON
+{
+  "scripts": {
+    "check": "npm run lint && npm run build && npm run test",
+    "prepack": "npm run build && npm run doc",
+    "release": "vrt release-npm",
+    ...
+  },
+  ...
+}
+```
+
+* `scripts.check` is **required** by the release command. Here you can lint, build and test your code.
+* `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`
 
@@ -25,6 +57,7 @@ Commands:
   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
 ```
 
@@ -91,3 +124,18 @@ Arguments:
 Options:
   -h, --help  display help for command
 ```
+
+## Subcommand: `vrt release-npm`
+
+```console
+$ vrt release-npm
+Usage: vrt release-npm [options] [path]
+
+release a npm package
+
+Arguments:
+  path        root path of the Node.js project
+
+Options:
+  -h, --help  display help for command
+```

package/dist/{lib → commands}/command.js

@@ -1,5 +1,5 @@
 import cp from 'child_process';
-import { getErrorMessage } from './utils.js';
+import { getErrorMessage } from '../lib/utils.js';
 /**
  * Generates documentation for a CLI command and its subcommands.
  * @param command The base CLI command to document.
@@ -31,8 +31,10 @@ export async function generateCommandDocumentation(command) {
  */
 async function getCommandResults(command) {
     return new Promise((resolve, reject) => {
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        const env = { ...process.env, NODE_ENV: undefined };
         // Spawn a child process to run the command with the '--help' flag.
-        const childProcess = cp.spawn('npx', [...command.split(' '), '--help']);
+        const childProcess = cp.spawn('npx', [...command.split(' '), '--help'], { env });
         let output = '';
         // Collect output data from the process.
         childProcess.stdout.on('data', data => output += String(data));

package/dist/{lib → commands}/markdown.js

@@ -1,6 +1,6 @@
 import { remark } from 'remark';
 import remarkGfm from 'remark-gfm';
-import { getErrorMessage } from './utils.js';
+import { getErrorMessage } from '../lib/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.
@@ -24,8 +24,7 @@ export function injectMarkdown(document, segment, heading, foldable) {
     }
     catch (error) {
         // Handle errors during the search for the start index.
-        console.error(`Error while searching for segment "${heading}": ${getErrorMessage(error)}`);
-        throw error;
+        throw new Error(`Error while searching for segment "${heading}": ${getErrorMessage(error)}`);
     }
     // Get the depth of the specified heading to maintain the structure.
     const depth = getHeadingDepth(documentAst, startIndex);
@@ -110,7 +109,7 @@ function findNextHeadingIndex(mainAst, startIndex, depth) {
     for (let i = startIndex; i < mainAst.children.length; i++) {
         const child = mainAst.children[i];
         // Return the index of the next heading at the same depth.
-        if (child.type === 'heading' && child.depth === depth)
+        if (child.type === 'heading' && child.depth <= depth)
             return i;
     }
     return mainAst.children.length;
@@ -269,10 +268,6 @@ export function nodeToHtml(node) {
             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 ?? '')
@@ -280,8 +275,6 @@ export function nodeToHtml(node) {
             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');

package/dist/commands/release.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env npx tsx
+export declare function release(directory: string, branch?: string): Promise<void>;

package/dist/commands/release.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env npx tsx
+import { readFileSync, writeFileSync } from 'node:fs';
+import inquirer from 'inquirer';
+import { check, info, panic, warn } from '../lib/log.js';
+import { getShell } from '../lib/shell.js';
+import { getGit } from '../lib/git.js';
+import { resolve } from 'node:path';
+export async function release(directory, branch = 'main') {
+    const shell = getShell(directory);
+    const { getCommitsBetween, getCurrentGitHubCommit, getLastGitHubTag } = getGit(directory);
+    info('starting release process');
+    // git: check if in the correct branch
+    const currentBranch = await check('get branch name', shell.stdout('git rev-parse --abbrev-ref HEAD'));
+    if (currentBranch !== branch)
+        panic(`current branch is "${currentBranch}" but should be "${branch}"`);
+    // git: check if no changes
+    await check('are all changes committed?', checkThatNoUncommittedChanges());
+    // git: pull
+    await check('git pull', shell.run('git pull -t'));
+    // check package.json
+    const pkg = JSON.parse(readFileSync(resolve(directory, 'package.json'), 'utf8'));
+    if (typeof pkg !== 'object' || pkg === null)
+        panic('package.json is not valid');
+    if (!('version' in pkg) || (typeof pkg.version !== 'string'))
+        panic('package.json is missing "version"');
+    if (!('scripts' in pkg) || (typeof pkg.scripts !== 'object') || (pkg.scripts == null))
+        panic('package.json is missing "scripts"');
+    if (!('check' in pkg.scripts))
+        panic('missing npm script "check" in package.json');
+    // get last version
+    const tag = await check('get last github tag', getLastGitHubTag());
+    const shaLast = tag?.sha;
+    const versionLastGithub = tag?.version;
+    const versionLastPackage = String(pkg.version);
+    if (versionLastPackage !== versionLastGithub)
+        warn(`versions differ in package.json (${versionLastPackage}) and last GitHub tag (${versionLastGithub})`);
+    // get current sha
+    const { sha: shaCurrent } = await check('get current github commit', getCurrentGitHubCommit());
+    // handle version
+    const nextVersion = await editVersion(versionLastPackage);
+    // prepare release notes
+    const releaseNotes = await check('prepare release notes', getReleaseNotes(nextVersion, shaLast, shaCurrent));
+    // update version
+    await check('update version', setNextVersion(nextVersion));
+    // test
+    await check('run checks', shell.run('npm run check'));
+    // npm publish
+    await check('npm publish', shell.run('npm publish --access public'));
+    // git push
+    await check('git add', shell.run('git add .'));
+    await check('git commit', shell.run(`git commit -m "v${nextVersion}"`, false));
+    await check('git tag', shell.run(`git tag -f -a "v${nextVersion}" -m "new release: v${nextVersion}"`));
+    await check('git push', shell.run('git push --no-verify --follow-tags'));
+    // github release
+    const releaseNotesPipe = `echo -e '${releaseNotes.replace(/[^a-z0-9,.?!:_<> -]/gi, c => '\\x' + ('00' + c.charCodeAt(0).toString(16)).slice(-2))}'`;
+    if (await check('check github release', shell.ok('gh release view v' + nextVersion))) {
+        await check('edit release', shell.run(`${releaseNotesPipe} | gh release edit "v${nextVersion}" -F -`));
+    }
+    else {
+        await check('create release', shell.run(`${releaseNotesPipe} | gh release create "v${nextVersion}" --draft --prerelease -F -`));
+    }
+    info('Finished');
+    return;
+    async function checkThatNoUncommittedChanges() {
+        if ((await shell.stdout('git status --porcelain')).length < 3)
+            return;
+        throw Error('please commit all changes before releasing');
+    }
+    async function setNextVersion(version) {
+        // set new version in package.json
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const packageJSON = JSON.parse(readFileSync(resolve(directory, 'package.json'), 'utf8'));
+        packageJSON.version = version;
+        writeFileSync(resolve(directory, 'package.json'), JSON.stringify(packageJSON, null, '  ') + '\n');
+        // rebuild package.json
+        await shell.run('npm i --package-lock-only');
+    }
+    async function getReleaseNotes(version, hashLast, hashCurrent) {
+        const commits = await getCommitsBetween(hashLast, hashCurrent);
+        let notes = commits.reverse()
+            .map(commit => '- ' + commit.message.replace(/\s+/g, ' '))
+            .join('\n');
+        notes = `# Release v${version}\n\nchanges: \n${notes}\n\n`;
+        return notes;
+    }
+    async function editVersion(versionPackage) {
+        // ask for new version
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const versionNew = (await inquirer.prompt({
+            message: 'What should be the new version?',
+            name: 'versionNew',
+            type: 'list',
+            choices: [versionPackage, bump(2), bump(1), bump(0)],
+            default: 1,
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+        })).versionNew;
+        if (!versionNew)
+            throw Error();
+        return versionNew;
+        function bump(index) {
+            const p = versionPackage.split('.').map(v => parseInt(v, 10));
+            if (p.length !== 3)
+                throw Error();
+            switch (index) {
+                case 0:
+                    p[0]++;
+                    p[1] = 0;
+                    p[2] = 0;
+                    break;
+                case 1:
+                    p[1]++;
+                    p[2] = 0;
+                    break;
+                case 2:
+                    p[2]++;
+                    break;
+            }
+            const name = p.map((n, i) => (i == index) ? `\x1b[1m${n}` : `${n}`).join('.') + '\x1b[22m';
+            const value = p.join('.');
+            return { name, value };
+        }
+    }
+}
+//# sourceMappingURL=release.js.map

package/dist/{lib → commands}/typedoc.js

@@ -206,10 +206,10 @@ function formatTypeDeclaration(someType) {
                 if (some.reflection)
                     result = `[${result}](#${createAnchorId(some.reflection)})`;
                 if (some.typeArguments?.length ?? 0)
-                    result += '<'
+                    result += '&lt;'
                         + (some.typeArguments ?? [])
                             .map(getTypeRec).join(',')
-                        + '>';
+                        + '&gt;';
                 return result;
             case 'reflection':
                 switch (some.declaration.kind) {

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env -S node --enable-source-maps
-export {};
+import { Command } from 'commander';
+export declare const program: Command;

package/dist/index.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env -S node --enable-source-maps
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { generateTsMarkdownDoc } from './lib/typedoc.js';
-import { injectMarkdown, updateTOC } from './lib/markdown.js';
+import { generateTsMarkdownDoc } from './commands/typedoc.js';
+import { injectMarkdown, updateTOC } from './commands/markdown.js';
 import { Command, InvalidArgumentError } from 'commander';
 import { cwd } from 'node:process';
-import { generateCommandDocumentation } from './lib/command.js';
-const program = new Command();
+import { generateCommandDocumentation } from './commands/command.js';
+import { release } from './commands/release.js';
+export const program = new Command();
 program
     .name('vrt')
     .description('versatiles release and documentaion tool');
@@ -48,7 +49,15 @@ program.command('inserttoc')
     mdFile = updateTOC(mdFile, heading);
     writeFileSync(mdFilename, mdFile);
 });
-program.parse();
+program.command('release-npm')
+    .description('release a npm package')
+    .argument('[path]', 'root path of the Node.js project')
+    .action((path) => {
+    void release(resolve(path ?? ',', process.cwd()), 'main');
+});
+if (process.env.NODE_ENV !== 'test') {
+    await program.parseAsync();
+}
 function checkFilename(filename) {
     const fullname = resolve(cwd(), filename);
     if (!existsSync(fullname)) {

package/dist/lib/git.d.ts

@@ -0,0 +1,14 @@
+export interface Commit {
+    sha: string;
+    message: string;
+    tag?: string;
+}
+export interface Git {
+    getLastGitHubTag: () => Promise<{
+        sha: string;
+        version: string;
+    } | undefined>;
+    getCurrentGitHubCommit: () => Promise<Commit>;
+    getCommitsBetween: (shaLast?: string, shaCurrent?: string) => Promise<Commit[]>;
+}
+export declare function getGit(cwd: string): Git;

package/dist/lib/git.js

@@ -0,0 +1,47 @@
+import { getShell } from './shell.js';
+export function getGit(cwd) {
+    const shell = getShell(cwd);
+    return {
+        getLastGitHubTag,
+        getCurrentGitHubCommit,
+        getCommitsBetween,
+    };
+    async function getLastGitHubTag() {
+        const commits = await getAllCommits();
+        const result = commits
+            .map(commit => ({
+            sha: commit.sha,
+            version: commit.tag?.match(/^v(\d+\.\d+\.\d+)$/)?.[1],
+        }))
+            .find(r => r.version);
+        return result;
+    }
+    async function getAllCommits() {
+        const result = await shell.stdout('git log --pretty=format:\'⍃%H⍄%s⍄%D⍄\'');
+        return result
+            .split('⍃')
+            .filter(line => line.length > 2)
+            .map(line => {
+            const obj = line.split('⍄');
+            return {
+                sha: obj[0],
+                message: obj[1],
+                tag: /tag: ([a-z0-9.]+)/.exec(obj[2])?.[1],
+            };
+        });
+    }
+    async function getCurrentGitHubCommit() {
+        return (await getAllCommits())[0];
+    }
+    async function getCommitsBetween(shaLast, shaCurrent) {
+        let commits = await getAllCommits();
+        const start = commits.findIndex(commit => commit.sha === shaCurrent);
+        if (start >= 0)
+            commits = commits.slice(start);
+        const end = commits.findIndex(commit => commit.sha === shaLast);
+        if (end >= 0)
+            commits = commits.slice(0, end);
+        return commits;
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/lib/log.d.ts

@@ -0,0 +1,5 @@
+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>;

package/dist/lib/log.js

@@ -0,0 +1,28 @@
+export function panic(text) {
+    process.stderr.write(`\x1b[1;31m! ERROR: ${text}\x1b[0m\n`);
+    abort();
+}
+export function warn(text) {
+    process.stderr.write(`\x1b[1;33m! warning: ${text}\x1b[0m\n`);
+}
+export function info(text) {
+    process.stderr.write(`\x1b[0mi ${text}\n`);
+}
+export function abort() {
+    info('abort');
+    process.exit();
+}
+export async function check(message, promise) {
+    process.stderr.write(`\x1b[0;90m\u2B95 ${message}\x1b[0m`);
+    try {
+        const result = await 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();
+    }
+}
+//# sourceMappingURL=log.js.map

package/dist/lib/shell.d.ts

@@ -0,0 +1,12 @@
+export interface Shell {
+    run: (command: string, errorOnCodeNonZero?: boolean) => Promise<{
+        code: number | null;
+        signal: string | null;
+        stdout: string;
+        stderr: string;
+    }>;
+    stderr: (command: string, errorOnCodeZero?: boolean) => Promise<string>;
+    stdout: (command: string, errorOnCodeZero?: boolean) => Promise<string>;
+    ok: (command: string) => Promise<boolean>;
+}
+export declare function getShell(cwd: string): Shell;

package/dist/lib/shell.js

@@ -0,0 +1,42 @@
+import { spawn } from 'child_process';
+export function getShell(cwd) {
+    async function run(command, errorOnCodeNonZero) {
+        try {
+            return await new Promise((resolve, reject) => {
+                const stdout = [];
+                const stderr = [];
+                const cp = spawn('bash', ['-c', command], { cwd })
+                    .on('error', error => {
+                    reject(error);
+                })
+                    .on('close', (code, signal) => {
+                    const result = {
+                        code,
+                        signal,
+                        stdout: Buffer.concat(stdout).toString(),
+                        stderr: Buffer.concat(stderr).toString(),
+                    };
+                    if ((errorOnCodeNonZero ?? true) && (code !== 0)) {
+                        reject(result);
+                    }
+                    else {
+                        resolve(result);
+                    }
+                });
+                cp.stdout.on('data', (chunk) => stdout.push(chunk));
+                cp.stderr.on('data', (chunk) => stderr.push(chunk));
+            });
+        }
+        catch (error) {
+            console.error(error);
+            throw error;
+        }
+    }
+    return {
+        run,
+        stderr: async (command, errorOnCodeZero) => (await run(command, errorOnCodeZero)).stderr.trim(),
+        stdout: async (command, errorOnCodeZero) => (await run(command, errorOnCodeZero)).stdout.trim(),
+        ok: async (command) => (await run(command, false)).code === 0,
+    };
+}
+//# sourceMappingURL=shell.js.map

package/dist/lib/utils.d.ts

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

package/dist/lib/utils.js

@@ -2,9 +2,38 @@ export function getErrorMessage(error) {
     if (error == null)
         return 'unknown';
     if (typeof error === 'object') {
-        if ('message' in error)
-            return String(error.message);
+        if ('message' in error) {
+            if (typeof error.message === 'string')
+                return error.message;
+            return JSON.stringify(error.message);
+        }
     }
     return 'unknown';
 }
+export function prettyStyleJSON(inputData) {
+    return recursive(inputData);
+    function recursive(data, prefix = '', path = '') {
+        if (path.endsWith('.bounds'))
+            return singleLine(data);
+        //if (path.includes('.vector_layers[].')) return singleLine(data);
+        if (path.startsWith('.layers[].filter'))
+            return singleLine(data);
+        if (path.startsWith('.layers[].paint.'))
+            return singleLine(data);
+        if (path.startsWith('.layers[].layout.'))
+            return singleLine(data);
+        if (typeof data === 'object') {
+            if (Array.isArray(data)) {
+                return '[\n\t' + prefix + data.map((value) => recursive(value, prefix + '\t', path + '[]')).join(',\n\t' + prefix) + '\n' + prefix + ']';
+            }
+            if (data) {
+                return '{\n\t' + prefix + Object.entries(data).map(([key, value]) => '"' + key + '": ' + recursive(value, prefix + '\t', path + '.' + key)).join(',\n\t' + prefix) + '\n' + prefix + '}';
+            }
+        }
+        return singleLine(data);
+    }
+    function singleLine(data) {
+        return JSON.stringify(data, null, '\t').replace(/[\t\n]+/g, ' ');
+    }
+}
 //# sourceMappingURL=utils.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/release-tool",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "VersaTiles release and documentation tools",
   "bin": {
     "vrt": "./dist/index.js"
@@ -11,11 +11,14 @@
   ],
   "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",
+    "check": "npm run lint && npm run build && npm run test",
     "doc": "npx vrt cmd2md vrt | npx vrt insertmd README.md '# Command'",
     "lint": "eslint . --color",
     "prepack": "npm run build && npm run doc",
-    "test": "cd ..; NODE_OPTIONS=--experimental-vm-modules jest --testPathPattern versatiles-release-tool"
+    "release": "npx vrt 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"
   },
   "author": "yetzt <node@yetzt.me>, Michael Kreil <versatiles@michael-kreil.de>",
   "license": "Unlicense",
@@ -26,14 +29,23 @@
   },
   "homepage": "https://github.com/versatiles-org/node-versatiles/blob/main/versatiles-release-tool/README.md",
   "devDependencies": {
-    "@types/node": "^20.10.0",
-    "tsx": "^4.4.0",
-    "typescript": "^5.2.2"
+    "@types/inquirer": "^9.0.7",
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.11.15",
+    "@typescript-eslint/eslint-plugin": "^6.20.0",
+    "@typescript-eslint/parser": "^6.20.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
   },
   "dependencies": {
     "commander": "^11.1.0",
+    "inquirer": "^9.2.13",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.0",
-    "typedoc": "^0.25.3"
+    "typedoc": "^0.25.7"
   }
 }