[![NPM version](https://img.shields.io/npm/v/%40versatiles%2Frelease-tool)](https://www.npmjs.com/package/@versatiles/release-tool)
[![NPM downloads](https://img.shields.io/npm/dt/%40versatiles%2Frelease-tool)](https://www.npmjs.com/package/@versatiles/release-tool)
[![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)
[![CI 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)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

# VersaTiles Release Tools

Tools used for:

- 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

```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.

# Trimming a noisy dependency graph

For repos with high fan-out, `deps-graph` accepts repeatable globs to collapse or drop nodes:

```bash
# Merge all region scrapers into a single labelled node ("regions/*.ts (24 files)").
vrt deps-graph --collapse-dir 'src/regions/*.ts'

# Drop trivial barrels and stubs from the graph entirely.
vrt deps-graph --exclude '**/_planned.ts' --exclude '**/index.ts'
```

# Command `vrt`

<!--- This chapter is generated automatically --->

```console
$ vrt
Usage: vrt [options] [command]

CLI tool for releasing packages and generating documentation for
Node.js/TypeScript projects.

Options:
  -h, --help                                display help for command
  -v, --verbose                             Enable verbose output

Commands:
  check                                     Check repo for required scripts and other stuff.
  deps-graph [options]                      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 [options] [path]              Publish an npm package from the specified path to the npm registry.
```

## Subcommand: `vrt check`

```console
$ vrt check
Usage: vrt check [options]

Check repo for required scripts and other stuff.

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:
  --collapse-dir <glob>  Collapse all files matching the glob into a single node
                         (repeatable). (default: [])
  --exclude <glob>       Drop files matching the glob from the graph entirely
                         (repeatable). (default: [])
  -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 doc-command`

```console
$ vrt doc-command
Usage: vrt doc-command [options] <command>

Generate Markdown documentation for a specified command and output the result.

Arguments:
  command     Command to document (e.g., "npm run build").

Options:
  -h, --help  display help for command
```

## Subcommand: `vrt doc-insert`

```console
$ vrt doc-insert
Usage: vrt doc-insert [options] <readme> [heading] [foldable]

Insert Markdown from stdin into a specified section of a Markdown file.

Arguments:
  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 doc-toc`

```console
$ vrt doc-toc
Usage: vrt doc-toc [options] <readme> [heading]

Generate a Table of Contents (TOC) in a Markdown file.

Arguments:
  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:
  -f, --format <format>      Allowed are "markdown", "wiki" and "html". Default
                             is "markdown".
  -h, --help                 display help for command
  -i, --input <entryPoint>   Entry point of the TypeScript project. Default is
                             "./src/index.ts".
  -o, --output <outputPath>  Output path for the generated documentation.
                             Default is "./docs".
```

## Subcommand: `vrt release-npm`

```console
$ vrt release-npm
Usage: vrt release-npm [options] [path]

Publish an npm package from the specified path to the npm registry.

Arguments:
  path           Root path of the Node.js project. Defaults to the current
                 directory.

Options:
  -h, --help     display help for command
  -n, --dry-run  Show what would be done without making any changes
```

# Development

## Dependency Graph

<!--- This chapter is generated automatically --->

```mermaid
---
config:
  layout: elk
---
flowchart TB

subgraph 0["src"]
subgraph 1["commands"]
2["check.ts"]
6["deps-graph.ts"]
7["deps-upgrade.ts"]
9["doc-command.ts"]
B["doc-typescript.ts"]
C["markdown.ts"]
D["release-npm.ts"]
end
subgraph 3["lib"]
4["log.ts"]
5["errors.ts"]
8["shell.ts"]
A["utils.ts"]
E["changelog.ts"]
F["git.ts"]
G["retry.ts"]
I["benchmark.ts"]
end
H["index.ts"]
end
2-->4
4-->5
6-->4
7-->4
7-->8
8-->4
9-->A
B-->4
C-->5
C-->A
D-->E
D-->5
D-->F
D-->4
D-->G
D-->8
E-->F
F-->8
H-->2
H-->6
H-->7
H-->9
H-->B
H-->C
H-->D
H-->4

class 0,1,3 subgraphs;
classDef subgraphs fill-opacity:0.1, fill:#888, color:#888, stroke:#888;
```