check-engine

A utility to check your package.json engines in Node.js projects. Inspired by the Thali Project in validateBuildEnvironment.js

About

Why

For projects of all sizes, but especially for mid to large size teams, environments get out of sync. Even slight variations in these build / development environments can kill productivity.

What This Does

Validates your system to make sure you have the correct system tools and dependencies installed. Uses the engine object from a package.json located in the current or specified directory to determine what system dependencies or installed tools validate.

Supported Dependencies

Currently Supporting:

| Dependencies | Semantic Versioning | |--------------------------------------|:-------------------:| | OS X (MacOS) | | | Node.js | :white_check_mark: | | npm | :white_check_mark: | | jx (JXCore) | | | cordova | | | appium | | | ios-deploy | | | ios-sim | | | bower | :white_check_mark: | | ios-webkit-debug-proxy | | | ideviceinstaller | | | java | | | ant | | | git | | | gulp-cli | | | cocoapods | | | xcodebuild | | | carthage | | | xcpretty | | | libimobiledevice | | | deviceconsole | | | check-engine | | | yarn | :white_check_mark: | | nsp | | | pnpm | :white_check_mark: |

See the validatorRules.js file file for the full list of things that are supported.

Some dependencies support engines with Semantic Versioning.

Install

check-engine can be installed globally or in a local directory.

• Globally: npm install -g check-engine
• Local: npm install check-engine

Usage

CLI

Simply run:

check-engine [path_to_package.json] [options]

Where:

• path_to_package.json is an optional path to a package.json file containing a list of engines to validate. If omitted, a package.json file will be looked for in the current working directory.

and [options]:

• --ignore: Ignore package validation errors and do not return an error exit code. Parsing issues or fatal errors will still return a error code.
• --help: Display command line options
• --version: Display version

Note: If check-engine is installed locally and you are not running it as part of an npm script, you will have to specify the path to the check-engine executable, which will be ./node_modules/.bin/check-engine. Specifying this path is not necessary within npm scripts, because npm automatically puts the ./node_modules/.bin folder into the environment's PATH.

Programmatic

var checkEngine = require('check-engine');

checkEngine('<path to package.json>').then((result) => {
    if (result.status !== 0) {
        console.log('it failed!');
    } else {
        console.log('it worked!');
    }
}

The resolved object contains higher level status, as well as information for individual packages that were validated. The above example only shows the high level. The object structure for the result object is as follows:

{
    status: 0 if successful, -1 otherwise
    message: {
        text: 'overall error description'
        type: 'error' or 'success'
    },
    packages: [
        {
            name: 'name of package',
            type: 'error', 'success', or 'warn',
            validatorFound: true or false,
            expectedVersion: 'version listed in package.json for this package', // exists only if validatorFound is true
            commandError: 'error result from validator process execution', // exists only if error occurred
            foundVersion: 'version number found' // exists only if validatorFound is true and there was no commandError error
        }
    ]
}

For example usage of this, see check-engine.js.

Developing check-engine

Building and Testing

1. Fork and clone repo then cd check-engine.
2. Install ESLint: npm i -g eslint.
3. Make changes.
4. Run npm run lint.
5. Run npm test.
6. Push and send a PR.

Publishing to NPM and Releasing

1. Update the version by calling npm version [major, minor, or patch].
2. Run npm publish.
3. git push --tags
4. Create a release for the tag on GitHub and describe changes.