Merge pull request #5 from toebeann/dev

typedoc-plugin-versions-cli v0.1
toebeann · Sep 23, 2022 · daed198 · daed198
2 parents e00d56d + c924ae1
commit daed198
Show file tree

Hide file tree

Showing 45 changed files with 4,451 additions and 144 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+    versioning-strategy: widen
diff --git a/.github/workflows/npm-test.yml b/.github/workflows/npm-test.yml
@@ -0,0 +1,68 @@
+name: npm test
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      [
+        "*.ts",
+        "jest.config.js?(on)",
+        "package-lock.json",
+        ".github/workflows/npm-test.yml",
+      ]
+  pull_request:
+    branches: ["main", "dev"]
+    paths:
+      [
+        "*.ts",
+        "jest.config.js?(on)",
+        "package-lock.json",
+        ".github/workflows/npm-test.yml",
+      ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        version: [16]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Setup node.js @ ${{ matrix.version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.version }}
+
+      - name: Get npm cache directory
+        id: npm-cache
+        run: echo "::set-output name=dir::$(npm config get cache)"
+
+      - name: Cache node_modules
+        id: cache-npm
+        uses: actions/cache@v3
+        env:
+          cache-name: cache-node-modules
+        with:
+          path: ${{ steps.npm-cache.outputs.dir }}
+          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-build-${{ env.cache-name }}-
+            ${{ runner.os }}-build-
+            ${{ runner.os }}-
+
+      - if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
+        name: List the state of node modules
+        continue-on-error: true
+        run: npm list
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
diff --git a/.github/workflows/publish-code-coverage.yml b/.github/workflows/publish-code-coverage.yml
@@ -0,0 +1,59 @@
+name: publish code coverage
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      [
+        "**.ts",
+        "jest.config.js*",
+        ".github/workflows/publish-code-coverage.yml",
+      ]
+  workflow_dispatch:
+
+jobs:
+  publish-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Setup node.js @ 16
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+
+      - name: Get npm cache directory
+        id: npm-cache
+        run: echo "::set-output name=dir::$(npm config get cache)"
+
+      - name: Cache node_modules
+        id: cache-npm
+        uses: actions/cache@v3
+        env:
+          cache-name: cache-node-modules
+        with:
+          path: ${{ steps.npm-cache.outputs.dir }}
+          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-build-${{ env.cache-name }}-
+            ${{ runner.os }}-build-
+            ${{ runner.os }}-
+
+      - if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
+        name: List the state of node modules
+        continue-on-error: true
+        run: npm list
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate code coverage reports
+        run: npm test -- --coverage
+        continue-on-error: true
+
+      - name: Publish code coverage to codecov 🚀
+        uses: codecov/codecov-action@v3
+        with:
+          verbose: true
+          fail_ci_if_error: true
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
@@ -0,0 +1,65 @@
+name: publish docs
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v3
+
+      - name: Checkout gh-pages
+        uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+          path: "./gh-pages"
+
+      - name: Fix folder structure
+        run: mv gh-pages/docs docs
+        continue-on-error: true
+
+      - name: Clean up gh-pages
+        run: rm -rf gh-pages
+
+      - name: Setup node.js @ 16
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+
+      - name: Get npm cache directory
+        id: npm-cache
+        run: echo "::set-output name=dir::$(npm config get cache)"
+
+      - name: Cache node_modules
+        id: cache-npm
+        uses: actions/cache@v3
+        env:
+          cache-name: cache-node-modules
+        with:
+          path: ${{ steps.npm-cache.outputs.dir }}
+          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-build-${{ env.cache-name }}-
+            ${{ runner.os }}-build-
+            ${{ runner.os }}-
+
+      - if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
+        name: List the state of node modules
+        continue-on-error: true
+        run: npm list
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate API reference
+        run: npm run docs
+
+      - name: Publish to GitHub Pages 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs
+          target-folder: docs
diff --git a/.github/workflows/publish-package.yml b/.github/workflows/publish-package.yml
@@ -0,0 +1,55 @@
+name: publish package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Setup node.js @ 16
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+
+      - name: Get npm cache directory
+        id: npm-cache
+        run: echo "::set-output name=dir::$(npm config get cache)"
+
+      - name: Cache node_modules
+        id: cache-npm
+        uses: actions/cache@v3
+        env:
+          cache-name: cache-node-modules
+        with:
+          path: ${{ steps.npm-cache.outputs.dir }}
+          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-build-${{ env.cache-name }}-
+            ${{ runner.os }}-build-
+            ${{ runner.os }}-
+
+      - if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
+        name: List the state of node modules
+        continue-on-error: true
+        run: npm list
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to npm 🚀
+        uses: JS-DevTools/npm-publish@v1
+        with:
+          token: ${{ secrets.NPM_TOKEN }}
+          access: public
diff --git a/README.md b/README.md
@@ -0,0 +1,125 @@
+<center>
+
+# typedoc-plugin-versions-cli 🧑‍💻
+
+A companion CLI tool for working with [typedoc-plugin-versions](https://citkane.github.io/typedoc-plugin-versions).
+
+[![npm package version](https://img.shields.io/npm/v/typedoc-plugin-versions-cli.svg?logo=npm&label&labelColor=222&style=flat-square)](https://npmjs.org/package/typedoc-plugin-versions-cli "View typedoc-plugin-versions-cli on npm") [![npm package downloads](https://img.shields.io/npm/dw/typedoc-plugin-versions-cli.svg?logo=npm&labelColor=222&style=flat-square)](https://npmjs.org/package/typedoc-plugin-versions-cli "View typedoc-plugin-versions-cli on npm") [![typedocs](https://img.shields.io/badge/docs-informational.svg?logo=typescript&labelColor=222&style=flat-square)](https://toebeann.github.io/typedoc-plugin-versions-cli "Read the documentation on Github Pages") [![coverage](https://img.shields.io/codecov/c/github/toebeann/typedoc-plugin-versions-cli.svg?logo=codecov&labelColor=222&style=flat-square)](https://codecov.io/gh/toebeann/typedoc-plugin-versions-cli "View code coverage on Codecov") [![code quality](https://img.shields.io/codefactor/grade/github/toebeann/typedoc-plugin-versions-cli.svg?logo=codefactor&labelColor=222&style=flat-square)](https://www.codefactor.io/repository/github/toebeann/typedoc-plugin-versions-cli "View code quality on CodeFactor") [![license](https://img.shields.io/github/license/toebeann/typedoc-plugin-versions-cli.svg?color=informational&labelColor=222&style=flat-square)](https://github.com/toebeann/typedoc-plugin-versions-cli/blob/main/LICENSE "View the license on GitHub")
+
+[![npm test](https://img.shields.io/github/workflow/status/toebeann/typedoc-plugin-versions-cli/npm%20test.svg?logo=github&logoColor=aaa&label=npm%20test&labelColor=222&style=flat-square)](https://github.com/toebeann/typedoc-plugin-versions-cli/actions/workflows/npm-test.yml "View npm test on GitHub Actions") [![publish code coverage](https://img.shields.io/github/workflow/status/toebeann/typedoc-plugin-versions-cli/publish%20code%20coverage.svg?logo=github&logoColor=aaa&label=publish%20code%20coverage&labelColor=222&style=flat-square)](https://github.com/toebeann/typedoc-plugin-versions-cli/actions/workflows/publish-code-coverage.yml "View publish code coverage on GitHub Actions") [![publish package](https://img.shields.io/github/workflow/status/toebeann/typedoc-plugin-versions-cli/publish%20package.svg?logo=github&logoColor=aaa&label=publish%20package&labelColor=222&style=flat-square)](https://github.com/toebeann/typedoc-plugin-versions-cli/actions/workflows/publish-package.yml "View publish package on GitHub Actions") [![publish docs](https://img.shields.io/github/workflow/status/toebeann/typedoc-plugin-versions-cli/publish%20docs.svg?logo=github&logoColor=aaa&label=publish%20docs&labelColor=222&style=flat-square)](https://github.com/toebeann/typedoc-plugin-versions-cli/actions/workflows/publish-docs.yml "View publish docs on GitHub Actions")
+
+[![github](https://img.shields.io/badge/source-informational.svg?logo=github&labelColor=222&style=flat-square)](https://github.com/toebeann/typedoc-plugin-versions-cli "View typedoc-plugin-versions-cli on GitHub") [![twitter](https://img.shields.io/badge/follow-blue.svg?logo=twitter&label&labelColor=222&style=flat-square)](https://twitter.com/toebean__ "Follow @toebean__ on Twitter") [![GitHub Sponsors donation button](https://img.shields.io/badge/sponsor-e5b.svg?logo=github%20sponsors&labelColor=222&style=flat-square)](https://github.com/sponsors/toebeann "Sponsor typedoc-plugin-versions-cli on GitHub") [![PayPal donation button](https://img.shields.io/badge/donate-e5b.svg?logo=paypal&labelColor=222&style=flat-square)](https://paypal.me/tobeyblaber "Donate to typedoc-plugin-versions-cli with PayPal")
+
+</center>
+
+## Table of contents
+
+- [typedoc-plugin-versions-cli 🧑‍💻](#typedoc-plugin-versions-cli-)
+  - [Table of contents](#table-of-contents)
+  - [Install](#install)
+    - [npm](#npm)
+  - [Usage](#usage)
+    - [Commands](#commands)
+      - [purge](#purge)
+        - [Options](#options)
+      - [synchronize](#synchronize)
+        - [Options](#options-1)
+  - [License](#license)
+
+## Install
+
+### [npm](https://www.npmjs.com/package/toebean/typedoc-plugin-versions-cli "npm is a package manager for JavaScript")
+
+```text
+npm i -D typedoc-plugin-versions-cli typedoc-plugin-versions
+```
+
+## Usage
+
+Run any of the following from the command line:
+
+```text
+tpv <command> [options..]
+```
+
+```text
+typedoc-plugin-versions-cli <command> [options..]
+```
+
+```text
+typedoc-plugin-versions <command> [options..]
+```
+
+```text
+typedoc-versions <command> [options..]
+```
+
+See details about the various [commands](#commands) and their options via the `--help` flag:
+
+```text
+tpv --help
+```
+
+All `boolean` flags which are `true` by default can be negated by prefixing with `no-`, e.g., the following are equivalent:
+
+```text
+tpv purge --no-stale
+tpv purge --stale false
+```
+
+On Windows, you may need to prefix the commands with `npx `, e.g.:
+
+```text
+npx tpv <command> [options..]
+```
+
+### Commands
+
+#### purge
+
+Deletes old doc builds and/or versions matching semver ranges.
+
+```text
+tpv purge [versions..] [flags]
+```
+
+Displays a confirmation prompt before performing changes.
+
+##### Options
+
+- **`--stale [boolean] [default: true]`**<br/>Purge stale doc builds, e.g. `v1.0.0-alpha.1` is considered stale once `v1.0.0` has been built.<br/><br/>
+- **`--major <number> [default: Infinity]`**<br/>Purge all but the specified number of major versions.<br/><br/>
+- **`--minor <number> [default: Infinity]`**<br/>Purge all but the specified number of minor versions per major version.<br/><br/>
+- **`--patch <number> [default: Infinity]`**<br/>Purge all but the specified number of patch versions per minor version.<br/><br/>
+- **`--exclude <versions..>`**<br/>Exclude versions matching the specified semver ranges from the purge operation.<br/><br/>
+- **`--pre`**, **`--prerelease [boolean] [default: false]`**<br/>Include prerelease versions when evaluating semver ranges.<br/><br/>
+- **`-y`**, **`--yes [boolean] [default: false]`**<br/>Automatically confirms prompts.<br/><br/>
+- **`--out <string>`**<br/>The path to your typedoc output directory. By default this is inferred from your typedoc configuration.<br/><br/>
+- **`--typedoc <string> [default: "."]`**<br/>The path to your typedoc configuration file, e.g. `typedoc.json`. By default this is searched for in the current working directory.<br/><br/>
+- **`--tsconfig <string> [default: "."]`**<br/>The path to your TypeScript tsconfig file, e.g. `tsconfig.json`. By default this is searched for in the current working directory.
+
+#### synchronize
+
+Ensures your [typedoc-plugin-versions](https://citkane.github.io/typedoc-plugin-versions) metadata and symbolic links are up-to-date. Useful after deleting old doc builds.
+
+```text
+tpv synchronize [flags]
+```
+
+```text
+tpv sync [flags]
+```
+
+Displays a confirmation prompt before performing changes.
+
+##### Options
+
+- **`-y`**, **`--yes [boolean] [default: false]`**<br/>Automatically confirms prompts.<br/><br/>
+- **`--symlink [boolean] [default: false]`**<br/>Always ensures symbolic links are up-to-date, regardless of confirmation prompts.<br/><br/>
+- **`--out <string>`**<br/>The path to your typedoc output directory. By default this is inferred from your typedoc configuration.<br/><br/>
+- **`--typedoc <string> [default: "."]`**<br/>The path to your typedoc configuration file, e.g. `typedoc.json`. By default this is searched for in the current working directory.<br/><br/>
+- **`--tsconfig <string> [default: "."]`**<br/>The path to your TypeScript tsconfig file, e.g. `tsconfig.json`. By default this is searched for in the current working directory.
+
+## License
+
+typedoc-plugin-versions-cli is licensed under [MIT](https://github.com/toebeann/typedoc-plugin-versions-cli/blob/main/LICENSE) © 2022 Tobey Blaber.