Run standardisation tests on your Seneca.js plugin.

	This open source module is sponsored and supported by Voxgig.

This module is designed for contributors to the Seneca family of plugins. If you wish, you may make use of this to scan your own plugin prior to publishing to see if it meets our standardisation specifications.

If you're using this module, and need help, you can:

• Post a github issue,
• Tweet to @senecajs,
• Ask the author.

If you are new to Seneca in general, please take a look at senecajs.org. We have everything from tutorials to sample apps to help get you up and running quickly.

npm install -D @seneca/maintain

Run the above command from your plugin's root directory to install this tool. The -D flag (alternatively --save-dev) marks it as a devDependency - meaning it is used during development and not as part of production.

Check out the official docs on dependencies and devDependencies here.

const { Maintain } = require('@seneca/maintain')

Maintain()

This maintenance tool can be run alongside existing tests, by including the above code snippet within your test script (usually index.test.js or similar).

Run the script with Jest (see More Examples below), or simply with node and the path to your test file:

$ node <index.test.js>

On success, nothing will be printed to console, and the script will continue as normal. On a fail, the script will throw a custom error with details of what went wrong.

If you're only looking for a simplified output in the form of a boolean (all checks pass/at least one check has failed), then you only need to set the returnBool parameter to false.

let maintainBool = await Maintain({returnBool:true})

If for example you need to run the maintain tool on one directory from another, it's possible to specify a root path. This should be the top level of the local package to test, ie. where the package.json and README.md files reside. Note that it is possible to step up levels from the current path using the .. syntax. A forward slash must preceed any path.

await Maintain({runPath:'/../path/to/package'})

If this optional parameter is not defined, the tool will default to running from the directory it was launched from (process.cwd()).

It is possible to run only a select few checks, or to exclude certain ones, by making use of the optional parameters for the Maintain() function - an include array and an exclude array.

include - If checks are denoted in this array, they will be the only checks run.

exclude - Any checks denoted in this array will be excluded from the run.

To make use of these functionalities, simply include an object as the argument for the Maintain function - the key being the name of the array, and the value being the array of check names itself.

// to only run the Code of Conduct checks
Maintain({ include: ['exist_codeconduct', 'version_codeconduct'] })

// to exclude the default branch check, but run every other check
Maintain({ exclude: ['check_default'] })

Using the standard tool as a test suite for Jest is simple - a one line addition to your test file is all you need. In order to make use of the custom include and exclude lists however, the function call must be wrapped in an async/await block.

import { Maintain } from '@seneca/maintain'

// Standard run
test('maintain', Maintain)

// With parameters
test('maintain', async () => {
  await Maintain({
    exclude: ['exist_codeconduct', 'version_codeconduct'],
  })
})

Configurations are used to run additional checks based on the architecture of your specific plugin. At the moment, there are three configs - Base, JavaScript, and TypeScript. The base configuration is run by default, and the tool will apply language-specific configurations based on the language of your plugin. No action on your part is necessary.

$ cli-maintain

Sample output :

Total checks for this configuration: 8

Failed checks: 2
  exist_codeconduct (why: file not found)
  version_codeconduct (why: file not found)

Please refer to the README.md document for descriptions of all checks.
https://github.com/senecajs/seneca-maintain/blob/main/README.md

Check out our sponsors and supporters, Voxgig, on their website here.

No API functionality is currently shipped with this tool.

The SenecaJS org encourages participation. If you feel you can help in any way, be it with bug reporting, documentation, examples, extra testing, or new features, feel free to create an issue, or better yet - submit a Pull Request. For more information on contribution, please see our Contributing Guide.

Check out the SenecaJS roadmap here!

Licensed under MIT.