JSPM – @ilg/cli-start-options@0.3.0

Package Exports

@ilg/cli-start-options

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ilg/cli-start-options) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 (>7.x), since the ECMAScript 6 class syntax is used.

If this is your first encounter with npm, you need to install the node.js JavScript run-time. The process is straighforward and does not polute the system locations significantly; just pick the current version, download the package suitable for your platform and install it as usual. The result is a binary program called node that can be used to execute JavaScript code from the terminal, and a link called npm, pointing to the npm-cli.js script, which is part of the node module that implements the npm functionality. On Windows, it is recommended to first install the Git for Windows package.

Easy install

The module is available as @ilg/cli-start-options from the public repository, use npm to install it inside the module where it is needed:

$ npm install @ilg/cli-start-options --save

The module does not provide any executables, and generaly there are few reasons to install it globally.

The development repository is available from the GitHub 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.

// Equivalent of import { CliApplication, CliCommand, CliHelp, CliOptions } from 'cli-start-options'

const CliApplication = require('@ilg/cli-start-options').CliApplication
const CliCommand = require('@ilg/cli-start-options').CliCommand
const CliHelp = require('@ilg/cli-start-options').CliHelp
const CliOptions = require('@ilg/cli-start-options').CliOptions
const CliOptions = require('@ilg/cli-start-options').CliOptions
const CliError = require('@ilg/cli-start-options').CliError
const CliErrorSyntax = require('@ilg/cli-start-options').CliErrorSyntax
const CliErrorApplication = require('@ilg/cli-start-options').CliErrorApplication
const CliExitCodes = require('@ilg/cli-start-options').CliExitCodes

Developer info

Git repo

$ 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:

$ npm link @ilg/cli-start-options

Tests

The tests use the node-tap 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:

$ cd cli-start-options-js.git
$ npm install
$ npm test

A typical test result looks like:

$ npm run test

> @ilg/cli-start-options@0.1.15 test /Users/ilg/My Files/MacBookPro Projects/xPack/npm-modules/cli-start-options-js.git
> standard && npm run test-tap -s

test/tap/author.js .................................... 8/8
test/tap/cmd-copy.js ................................ 40/40
test/tap/errors.js .................................. 18/18
test/tap/interactive.js ............................. 14/14
test/tap/logger.js ................................ 147/147
test/tap/module-invocation.js ......................... 9/9
test/tap/options-common.js ........................ 126/126
total ............................................. 362/362

  362 passing (10s)

  ok

To run a specific test with more verbose output, use npm run tap:

$ npm run tap test/tap/cmd-copy.js -s

test/tap/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
    ✓ exit code is input
    ✓ stdout is empty
    ✓ strerr is ENOENT

  unpack
    ✓ cmd-code.tgz unpacked into /var/folders/n7/kxqjc5zs4qs0nb44v1l2r2j00000gn/T/xtest-copy
    ✓ chmod ro file
    ✓ mkdir folder
    ✓ chmod ro folder

  xtest cop --file input.json --output output.json
    ✓ exit code is success
    ✓ stdout is empty
    ✓ stderr is empty
    ✓ content is read in
    ✓ json was parsed
    ✓ has name

  xtest cop --file input --output output -v
    ✓ exit code
    ✓ message is Done
    ✓ stderr is empty

  xtest cop --file input --output ro/output -v
    ✓ exit code is output
    ✓ up to writing
    ✓ stderr is EACCES

  cleanup
    ✓ chmod rw file
    ✓ chmod rw folder
    ✓ remove tmpdir


  40 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:

$ npm run test-coverage

> @ilg/cli-start-options@0.1.15 test-coverage /Users/ilg/My Files/MacBookPro Projects/xPack/npm-modules/cli-start-options-js.git
> tap --coverage --reporter=classic --timeout 600 --no-color "test/tap/*.js"

test/tap/author.js .................................... 8/8
test/tap/cmd-copy.js ................................ 40/40
test/tap/errors.js .................................. 18/18
test/tap/interactive.js ............................. 14/14
test/tap/logger.js ................................ 147/147
test/tap/module-invocation.js ......................... 9/9
test/tap/options-common.js ........................ 126/126
total ............................................. 362/362

  362 passing (20s)

  ok
------------------------------|----------|----------|----------|----------|----------------|
File                          |  % Stmts | % Branch |  % Funcs |  % Lines |Uncovered Lines |
------------------------------|----------|----------|----------|----------|----------------|
All files                     |      100 |    89.01 |    96.43 |      100 |                |
 cli-start-options-js.git     |      100 |      100 |      100 |      100 |                |
  index.js                    |      100 |      100 |      100 |      100 |                |
 cli-start-options-js.git/lib |      100 |    89.01 |    96.43 |      100 |                |
  cli-application.js          |      100 |    85.71 |    90.91 |      100 |                |
  cli-command.js              |      100 |    78.57 |      100 |      100 |                |
  cli-error.js                |      100 |      100 |      100 |      100 |                |
  cli-help.js                 |      100 |    90.43 |      100 |      100 |                |
  cli-logger.js               |      100 |       72 |      100 |      100 |                |
  cli-options.js              |      100 |    98.39 |      100 |      100 |                |
------------------------------|----------|----------|----------|----------|----------------|

Continuous Integration (CI)

The continuous integration tests are performed via Travis CI and AppVeyor.

To speed up things, the node_modules folder is cached between builds.

Standard compliance

The module uses ECMAScript 6 class definitions.

As style, it uses the JavaScript Standard Style, 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):

$ npm run fix

> @ilg/cli-start-options@0.1.12 fix /Users/ilg/My Files/MacBookPro Projects/xPack/npm-modules/cli-start-options-js.git
> standard --fix

Documentation metadata

The documentation metadata follows the JSdoc tags.

To enforce checking at file level, add the following comments right after the use strict:

'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.

@ilg/cli-start-options