Support command line options from a file

[benquarmby]

Description

This PR enables yargs' first-class support for a command line options file. It works out of the box and costs very little.

Also updated the CLI options docs while I was here.

Motivation and Context

The commitlint CLI has many arguments now; I counted 20. Composing and encoding all the required arguments for a project at the terminal or in a package script can get hard to maintain. The ability to move those options to a regular JavaScript or JSON module makes them far easier to manage. It is more human readable and writable.

Usage examples

This fabricated example is deliberately verbose and a bit unrealistic to make the point:

{
-   "commit:lint": "commitlint --from $GIT_LAST_TAG --format @some/formatter --parser-preset @some/preset --extends @some/shared-config-1 @some/shared-config-2 --strict --cwd ../project --git-log-args \"--first-parent\""
+   "commit:lint": "commitlint --options ./commitlint.options.cjs"
}

// commitlint.options.cjs
module.exports = {
    from: process.env.GIT_LAST_TAG,
    format: '@some/formatter',
    parserPreset: '@some/preset',

    // Explanatory code comment for this option could go here.
    extends: ['@some/shared-config-1', '@some/shared-config-2'],

    strict: true,
    cwd: '../project',
    gitLogArgs: '--first-parent'
};

How Has This Been Tested?

Added some temporary options files and ran them directly on this repo. Firstly a Common.js module:

// commitlint.options.cjs
module.exports = {
    from: "v19.3.1",
    verbose: true
};

yarn run commitlint --options ./commitlint.options.cjs

CJS Options Output

And then a JSON file:

{
    "from": "v19.3.1",
    "verbose": true
}

yarn run commitlint --options ./commitlint.options.json

JSON Options Output

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• [x] My change requires a change to the documentation.
• [x] I have updated the documentation accordingly.
• [x] I have added tests to cover my changes.
• [x] All new and existing tests passed.

[codesandbox-ci[bot]]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

[escapedcat]

Hey @benquarmby , sounds great, thanks! Would you mind updating the failing test-snapshot to get this PR green?