xpm
Version:
The xPack project manager command line tool
263 lines (192 loc) • 9.47 kB
Markdown
[](https://www.npmjs.com/package/@ilg/cli-start-options)
[](https://github.com/xpack/cli-start-options-js/blob/xpack/LICENSE)
[](https://standardjs.com/)
[](https://travis-ci.org/xpack/cli-start-options-js)
[](https://ci.appveyor.com/project/ilg-ul/cli-start-options-js)
[](https://github.com/xpack/cli-start-options-js/issues/)
[](https://github.com/xpack/cli-start-options-js/pulls)
## CLI startup and options processing
A Node.js module with classes to implement a command line Node.js application.
The module exports several classes (like CliApplication, CliCommand, ...)
that can be used as base classes for CLI applications.
## Prerequisites
A recent [Node.js](https://nodejs.org) (>=8.x), since the ECMAScript 6 class
syntax is used.
## Easy install
The module is available as
[`@ilg/cli-start-options`](https://www.npmjs.com/package/@ilg/cli-start-options)
from the public repository, use `npm` to install it inside the module where
it is needed:
```sh
npm install @ilg/cli-start-options --save
```
The module does not provide any executables, and generally there are few
reasons to install it globally.
The development repository is available from the GitHub
[xpack/cli-start-options-js](https://github.com/xpack/cli-start-options-js)
project.
## User info
The module can be included in CLI applications and the classes can be used
to derive application classes.
```javascript
// Equivalent of import { CliApplication, CliCommand, CliHelp, CliOptions } from 'cli-start-options'
const { CliApplication, CliCommand, CliHelp, CliOptions,
CliError, CliExitCodes } = require('@ilg/cli-start-options')
```
## Developer info
### Git repo
```sh
git clone https://github.com/xpack/cli-start-options-js.git cli-start-options-js.git
cd cli-start-options-js.git
npm install
sudo npm link
ls -l /usr/local/lib/node_modules/@ilg
```
A link to the development folder should be present in the system
`node_modules` folder.
In projects that use this module under development, link back from the
global location:
```sh
npm link @ilg/cli-start-options
```
### Tests
The tests use the [`node-tap`](http://www.node-tap.org) framework
(_A Test-Anything-Protocol library for Node.js_, written by Isaac Schlueter).
As for any `npm` package, the standard way to run the project tests is via
`npm test`:
```sh
cd cli-start-options-js.git
npm install
npm test
```
A typical test result looks like:
```console
$ npm run test
> @ilg/cli-start-options@0.8.2 test /Users/ilg/My Files/MacBookPro Projects/xPack/npm-modules/cli-start-options-js.git
> standard && npm run test-tap -s
test/tap/020-errors.js .............................. 18/18
test/tap/030-options-common.js .................... 117/117
test/tap/040-module-invocation.js ..................... 9/9
test/tap/050-interactive.js ......................... 14/14
test/tap/060-cmd-copy.js ............................ 21/21
test/tap/070-author.js ................................ 8/8
total ............................................. 187/187
187 passing (12s)
ok
```
To run a specific test with more verbose output, use `npm run tap`:
```console
% npm run tap test/tap/060-cmd-copy.js -s
test/tap/060-cmd-copy.js
xtest copy
✓ exit code is syntax
✓ has two errors
✓ has --file error
✓ has --output error
✓ has Usage
xtest copy -h
✓ exit code is success
✓ has enough output
✓ has title
✓ has Usage
✓ has copy options
✓ has --file
✓ has --output
✓ stderr is empty
xtest cop -h
✓ exit code is success
✓ has enough output
✓ has title
✓ has Usage
✓ stderr is empty
xtest cop --file xxx --output yyy -q
✓ exit code is input
✓ stdout is empty
✓ strerr is ENOENT
21 passing (2s)
```
### Coverage tests
Coverage tests are a good indication on how much of the source files is
exercised by the tests. Ideally all source files should be covered 100%,
for all 4 criteria (statements, branches, functions, lines).
To run the coverage tests, use `npm run test-coverage`:
```console
% npm run test-coverage
> @ilg/cli-start-options@0.9.0-pre test-coverage
> tap --coverage --reporter=classic --timeout 600 "test/tap/*.js"
test/tap/020-errors.js .............................. 18/18
test/tap/030-options-common.js .................... 117/117
test/tap/040-module-invocation.js ..................... 9/9
test/tap/050-interactive.js ......................... 14/14
test/tap/060-cmd-copy.js ............................ 21/21
test/tap/070-author.js ................................ 8/8
total ............................................. 187/187
187 passing (12s)
ok
ERROR: Coverage for lines (88.93%) does not meet global threshold (100%)
ERROR: Coverage for functions (89.07%) does not meet global threshold (100%)
ERROR: Coverage for branches (75.29%) does not meet global threshold (100%)
ERROR: Coverage for statements (88.93%) does not meet global threshold (100%)
------------------------------|---------|----------|---------|---------|-----------------------------------------------------------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
------------------------------|---------|----------|---------|---------|-----------------------------------------------------------------------
All files | 88.93 | 75.29 | 89.07 | 88.93 |
cli-start-options-js.git | 100 | 100 | 100 | 100 |
index.js | 100 | 100 | 100 | 100 |
cli-start-options-js.git/lib | 88.91 | 75.29 | 89.07 | 88.91 |
cli-application.js | 81.93 | 52.77 | 87.75 | 81.93 | ...156,185-189,453,812-815,823-841,861-865,879-928,993,1016,1024-1028
cli-command.js | 83.75 | 62.5 | 83.33 | 83.75 | 115,124-125,199-218,235
cli-error.js | 88.46 | 100 | 50 | 88.46 | 149-187
cli-help.js | 99.47 | 88.8 | 100 | 99.47 | 91
cli-options.js | 91.66 | 87.01 | 92 | 91.66 | 220-222,491,534-536,590-600
------------------------------|---------|----------|---------|---------|-----------------------------------------------------------------------
```
### Continuous Integration (CI)
TBD
### Standard compliance
The module uses ECMAScript 6 class definitions.
As style, it uses the [JavaScript Standard Style](https://standardjs.com/),
automatically checked at each commit via Travis CI.
Known and accepted exceptions:
- `// eslint-disable-line node/no-deprecated-api` to continue using the
deprecated `domain` module
To manually fix compliance with the style guide (where possible):
```console
$ npm run fix
> @ilg/cli-start-options@0.9.0-pre fix
> standard --fix --verbose
```
### Documentation metadata
The documentation metadata follows the [JSdoc](http://usejsdoc.org) tags.
To enforce checking at file level, add the following comments right after
the `use strict`:
```js
'use strict'
/* eslint valid-jsdoc: "error" */
/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */
```
Note: be sure C style comments are used, C++ styles are not parsed by
[ESLint](http://eslint.org).
### Publish to npmjs.com
- `npm run fix`
- commit all changes
- `npm run test-coverage` (not 100% yet)
- check the latest commits `npm run git-log`
- update `CHANGELOG.md`; commit with a message like __CHANGELOG: prepare v0.8.1
- `npm version patch` (bug fixes), `npm version minor` (compatible API
additions), `npm version major` (incompatible API changes)
- `npm pack` and check the content
- push all changes to GitHub; this should trigger CI
- **wait for CI tests to complete** (not yet)
- `npm publish --tag next` (use `--access public` when publishing for the first time)
Check if the version is present at
[@ilg/cli-start-options Versions](https://www.npmjs.com/package/@ilg/cli-start-options?activeTab=versions).
### Change tag to latest
When stable:
- `npm dist-tag ls @ilg/cli-start-options`
- `npm dist-tag add @ilg/cli-start-options@0.8.2 latest`
- `npm dist-tag ls @ilg/cli-start-options`
## License
The original content is released under the
[MIT License](https://opensource.org/licenses/MIT), with all rights
reserved to [Liviu Ionescu](https://github.com/ilg-ul/).