Checklist CLI

A command line tool to automate running checklists on projects, e.g:

• following development standards, e.g. presense of a README.md
• release checklists
• etc.

Installation

Requires Node.js 18 or above.

1. Install the tool (with global option):

Yarn:

yarn global add @rushdigital/checklist-cli

NPM:

npm install -g @rushdigital/checklist-cli

Usage

1. Put your checklists into checklists/ directory.

You can also create a repository of checklists, so you can install from it by running:

checklist-cli install

See "Checklists" section below for more details.

2. Run the tool

checklist-cli check --summary --reason

If you want to specify a subset of checklists use --checklists parameter, e.g:

checklist-cli check --summary --reason --checklists checklists/standard.yaml

Commands

checklist-cli <command>

Commands:

• config - Configures the tool to be able to install shared checklists repository
• install - Installs checklists into the current directory
• update - Updates checklists in the current directory to latest version fron the shared repository
• check - Runs the checks in the current direcory
• checklist [url] - Fetches a checklist in a specified format and displays it
• test <cmd> - Helper to test commands locally

Checklists

Checklists are defined in a yaml file that has the following structure:

manifestVersion: "0.5"
metadata:
  checksVersion: "<version, e.g. 1.0.0>"
  about: <description>
  reportTitle: <title>
checks:
  - id: <id, e.g STD-005>
    description: <description>
    why: <reason>
    category: <category, e.g Documentation>
    notes: <internal notes>
    contexts:
      - <context, e.g. develop or release>
    tags:
      - <tag>
    automation:
      - <automation>

Shared Repository

To create a shared repository of checklists:

1. Create a NPM package that contains your checklists in a checklists/ directory. Example package.json:

{
  "name": "my-checklists",
  "version": "0.0.1",
  "description": "My custom checklists",
  "files": [
    "checklists/**/*.yaml",
  ]
}

2. Publish that package to npmjs.com or push to a git repository

3. Install that package globally using npm:

From npm:

npm i -g my-checklists

Or from Git:

npm i -g [email protected]:<user>/my-checklists.git

4. Configure checklist to use that package:

checklist-cli config --add my-checklists

5. Now, when you need to add checklists to a project you can run the following command from the project directory:

checklist-cli install

It will show the list of available checklists to choose from and copy them to checklists/ directory.

Automation

An automation can have the following outcomes:

• passed - successfully checked
• failed - check not passed
• skipped - check is not applicable
• pending - manual check

The following automations are supported:

Shell automation

shell: <command>

Also a shorthand notation is supported:

<command>

Specifies a shell command which is used to perform the check. Command that returns exit code 0 indicates that the check has passed. Any other code indicates that the check failed.

Conditional automation

if:
  condition: <automation>
  then: <automation>
  else: <automation>

Also a shorthand notation is supported:

condition: <automation>
then: <automation>

Rules:

• Condition is satisfied if its automation returns passed.
• Condition that is satisfied and does not have a then will result in pending.
• Condition that is not satisfied and does not have an else will result in skipped. This is useful to create conditional manual checks.

"Outcome" automation

Specifies the outcome of the check

outcome: <automation>
reason: <reason>

Useful for skipping or enforcing a manual check.

"Any" automation

any:
  - <automation>
  - <automation>

Also a shorthand notation is supported:

- <automation>
- <automation>

This automation is used implicily in the automations: block of the check.

Rules:

• If no automations then result will be pending.
• If one automation then result will be of that automation.
• If more than one automation:
  • if any automation passed then overall result will be passed.
  • if any automation failed then overall result will be failed.
  • if any automation skipped then overall result will be skipped.
  • otherwise the overall result will be pending.

Examples

  - id: STD-001
    description: Ensure README.md exists which describes the project, how to build and deploy it.    
    automation:
      - shell: test -f README.md || test -f readme.md

  - id: STD-002
    description: The README file has been kept up to date
    why: To prevent document rot
    automation:
      - condition: test -f README.md

  - id: STD-003
    description: node_modules should be ignored
    automation:
      - condition: test -d node_modules
        then: grep -q node_modules .gitignor

Security Updates

To fix security updates, in develop branch:

1. Run npm audit to check for vulnerabilities.
2. Run npm run update:dependencies to fix discovered vulnerabilities (if fixes are available) and update other dependencies.
3. Run npm run tests to ensure things are working as expected.
4. Run npm audit to check that vulnerabilities have been fixed.
5. Commit changes to the repository, adding details of the vulnerabilities that have been fixed to the commit message (CVE number and vulnerable packages).
6. Run npm run version:next to bump the version number and create a new tag.
7. Push to origin and wait for the the build pipeline to finish successfully.
8. Merge develop to master with Fast-forward strategy.
9. Push to origin and wait for the the build pipeline to publish a new version of the package to npm.

Support

If you find a bug or have a feature request please log it at https://bitbucket.org/rushdigital/checklist-cli/issues

About RUSH

RUSH was founded on a simple principle; the exhilarating feeling of solving a difficult problem, a feeling that is common in the challenging projects RUSH tackles. We’re committed to bringing this enthusiasm to our work as a forward-looking, tech-engaged business with the purpose statement: We design and build technology to better serve humankind.

Our ways of working have been tested in some of the most demanding and impactful projects, resulting in effective and elegant award-winning digital experiences that millions of people benefit from every day.

We strive for continuous improvement to refine our practices and processes - like this tool, created to automate repetitive tasks and make the teams' lives easier. If you'd like to join or learn more about RUSH's team of strategic thinkers, empathetic designers and technical mavericks visit rush.co.nz/careers

License

CC-BY-NC-SA-4.0