virmator

virmator

A package for centralizing and automating mind-numbingly repetitive repo tasks and checks. New commands can easily be added through a plugin system.

Note that as of v13, this package is now in ESM.

virmator usage

[npx] virmator [--flags] command subCommand [...optional args]

• npx is needed when the command is run directly from the terminal (not called from within an npm script) unless virmator has been globally installed (which I recommend against).
• [--flags] is any of the optional virmator flags. See Virmator Flags below.
• command, subCommand, and [...optional args] depend on the specific command you're running. See Available Commands below.

Available commands

• compile

  Type checks TypeScript files and compiles them into JS outputs using the TypeScript compiler. Any extra args are passed directly to tsc.

  Automatically compiles a mono-repo's sub packages in the correct order if called from a mono-repo root.

  • Examples
    • virmator compile
    • With tsc flags: virmator compile --noEmit
  • Configs
    • tsconfig.json
    • configs/tsconfig.base.json
  • Deps
    • typescript
    • mono-vir

• deps

  Various dependency commands. A sub-command must be provided.

  • Examples

    • check import dependencies: virmator deps check
    • upgrade npm dependencies: virmator deps upgrade
    • list unused npm dependencies: virmator deps unused
    • regenerate npm dependencies: virmator deps regen

  • Sub Commands

    • check

      Checks that import dependencies pass your dependency cruiser config. The base configuration blocks typical import errors such as circular dependencies and importing test files.

      • Examples
        • virmator deps check
      • Configs
        • configs/dep-cruiser.config.cts
      • Deps
        • dependency-cruiser
        • esbuild

    • unused

      Lists direct dependencies declared in package.json that are not referenced by a static import in the package's code. Dependencies used only by npm scripts or dynamically generated module names may be reported as unused.

      • Examples
        • virmator deps unused
      • Deps
        • dependency-cruiser

    • upgrade

      Upgrades dependencies using npm-check-update. Does not automatically run 'npm i'. It is recommended to run 'virmator deps regen' instead.

      If a package name or glob is passed as an argument, only the matching direct dependencies are upgraded via 'npm i @'. An optional '@' suffix on the argument selects which version to install (defaulting to 'latest' when omitted). Any flags or args supplied after the pattern are forwarded to npm verbatim (e.g. '--min-release-age 0'). In a mono-repo, this scans the root package.json as well as every workspace package.json, running an install in each one that has a match. Outside a mono-repo, it scans the current package only. The command errors out if no direct deps match in any package.json.

      • Examples
        • virmator deps upgrade
        • upgrade a single package across the mono-repo: virmator deps upgrade @augment-vir/common
        • upgrade all packages matching a glob: virmator deps upgrade "@augment-vir/*"
        • upgrade matches to a specific version: virmator deps upgrade "my-package@^2.0.0"
        • forward npm flags (e.g. bypass min-release-age): virmator deps upgrade "@augment-vir/*" --min-release-age 0
      • Configs
        • configs/ncu.config.ts
      • Deps
        • npm-check-updates

    • regen

      Force regeneration of all all dependencies by deleting all node_modules directories and package-lock.json and then running 'npm i'.

      • Examples
        • virmator deps regen

• docs

  Generates documentation using the typedoc package and inserts code examples into README files using the markdown-code-example-inserter package.

  • Examples

    • virmator docs

  • Configs

    • configs/typedoc.config.ts

  • Deps

    • markdown-code-example-inserter
    • typedoc

  • Sub Commands

    • check

      Checks that documentation is valid and passes all checks without generating documentation outputs.

      • Examples
        • virmator docs check

• format

  Formats with prettier.

  • Examples

    • virmator format

  • Configs

    • prettier.config.mjs
    • .prettierignore

  • Deps

    • prettier
    • prettier-plugin-jsdoc
    • prettier-plugin-multiline-arrays
    • prettier-plugin-organize-imports
    • prettier-plugin-packagejson
    • prettier-plugin-sort-json
    • prettier-plugin-toml
    • prettier-plugin-interpolated-html-tags

  • Sub Commands

    • check

      Checks that formatting is all valid.

      • Examples
        • virmator format check

• frontend

  Runs a frontend dev server with Vite.

  • Examples

    • virmator frontend

  • Configs

    • configs/vite.config.ts

  • Deps

    • typescript
    • vite

  • Sub Commands

    • build

      Builds a frontend for deployment using Vite (and Rollup).

      • Examples
        • virmator frontend build

    • preview

      Builds a frontend and previews that build in a local dev server.

      • Examples
        • virmator frontend preview

• help

  Prints help messages for all supported plugins/commands.

  • Examples
    • virmator help

• init

  Init all default configs. Needs env and package type args.

  • Examples
    • virmator init web mono-repo
    • virmator init node package
  • Configs
    • .github/workflows/build-for-gh-pages.yml
    • .github/workflows/tagged-release.yml
    • .github/workflows/pr-review-status.yml
    • .github/workflows/pr-review-trigger.yml
    • .github/workflows/tests.yml
    • configs/pull-request-vir.config.ts
    • .vscode/settings.json
    • src/ui/elements/vir-app.element.ts
    • src/index.html
    • www-static/index.css
    • www-static/_redirects
    • .gitattributes
    • .npmrc
    • .nvmrc
    • .gitignore
    • LICENSE-MIT
    • LICENSE-CC0
    • .npmignore
    • package.json

• lint

  Runs ESLint.

  • Examples

    • virmator lint

  • Configs

    • eslint.config.ts

  • Deps

    • eslint
    • eslint-plugin-unicorn
    • @eslint/js
    • @stylistic/eslint-plugin
    • @stylistic/eslint-plugin-ts
    • @typescript-eslint/eslint-plugin
    • eslint-config-prettier
    • eslint-plugin-jsdoc
    • eslint-plugin-playwright
    • eslint-plugin-prettier
    • eslint-plugin-sonarjs
    • typescript-eslint

  • Sub Commands

    • fix

      Auto fix all fixable ESLint issues.

      • Examples
        • virmator lint fix

• publish

  Stage a package or mono-repo for publishing to NPM (via npm's staged publishing) with an optional test script and auto-incrementing package version.

  Staged versions are not live on NPM until they are approved on the npm website or via 'npm stage approve' (both require 2FA). Requires npm >= 11.15.0.

  • Examples
    • With tests: virmator publish npm test
    • Without tests: virmator publish

• spellcheck

  Checks spelling for all files using the cspell package. All arguments are passed directly to cspell.

  • Examples
    • virmator spellcheck
    • Check a specific file: virmator spellcheck src/index.ts
  • Configs
    • cspell.config.cjs
  • Deps
    • cspell

• test

  Runs tests. An environment is required.

  This cannot be run in a mono-repo root, it can only be run for mono-repo sub-packages or a top-level singular package.

  Pass --footprint to record which functions each test file actually ran, as raw v8 coverage in node_modules/.cache/virmator/footprints. Tests still run normally, coverage is not calculated. This cannot be combined with the coverage command, which needs the same v8 output.

  • Examples

    • Run tests in a browser: virmator test web
    • Record what each test ran: virmator test node --footprint
    • Run tests in Node: virmator test node

  • Deps

    • @augment-vir/test
    • @augment-vir/assert

  • Sub Commands

    • web

      Runs web tests in a browser using web-test-runner.

      • Examples

        • virmator test web

      • Configs

        • configs/web-test-runner.config.mjs

      • Deps

        • @web/dev-server-esbuild
        • @web/test-runner-playwright
        • @web/test-runner
        • istanbul-smart-text-reporter
        • typescript

      • Sub Commands

        • coverage

          Run tests and calculate code coverage.

          • Examples
            • virmator test web coverage

        • update

          Run tests and update snapshots.

          • Examples
            • virmator test web update

    • node

      Runs backend tests in Node.js using its built-in test runner.

      • Examples

        • virmator test node

      • Sub Commands

        • coverage

          Run tests and calculate code coverage.

          • Examples
            • virmator test node coverage
          • Configs
            • configs/c8.config.json
          • Deps
            • c8
            • istanbul-smart-text-reporter
            • @types/node

        • update

          Run tests and update snapshots.

          • Examples
            • virmator test node update

Virmator Flags

All virmator flags are optional and typically not needed.

• --no-configs: Prevents command config files from being copied.
• --no-deps: Prevents command npm deps from being installed.
• --help: Print the help message.