Sanctuary-scripts NPM

sanctuary-scripts

Shell scripts used in multiple Sanctuary projects. Many scripts are also compatible with non-Sanctuary projects.

Each script is referenced in the "bin" field of package.json, and symlink names are sanctuary--prefixed to avoid collisions. To use generate-readme, for example, one would use the path node_modules/.bin/sanctuary-generate-readme (or simply sanctuary-generate-readme when using npm scripts).

Installation

Add sanctuary-scripts to "devDependencies" in package.json.

Define the following "scripts" in package.json:

{
  "scripts": {
    "doctest": "sanctuary-doctest",
    "lint": "sanctuary-lint",
    "release": "sanctuary-release",
    "test": "npm run lint && sanctuary-test && npm run doctest"
  }
}

Add a file named .config in the project's root directory, with suitable repo-owner and repo-name values. For example:
```
repo-owner = sanctuary-js
repo-name = sanctuary-type-classes
```
Add a file named .eslintrc.json in the project's root directory, with the following JSON configuration:
```
{
  "root": true,
  "extends": ["./node_modules/sanctuary-style/eslint.json"]
}
```

Usage

`npm test`

Runs lint, test, and doctest.

`npm run lint`

Runs lint only.

`npm run doctest`

Runs doctest only.

`npm run release <increment>`

Runs release with the specified increment (major, minor, patch, premajor, preminor, prepatch, or prerelease).

Configuration

There are two layers of configuration available: variables and custom scripts.

Variables

Certain variables may be specified in a file named .config in the project's root directory. Each line in the file should be a ${name} = ${value} pair. For example:

repo-owner = sanctuary-js
repo-name = sanctuary-type-classes

Many variables have default values and are therefore optional.

Variable name	Default value	Description
`repo-owner`		The name of the GitHub user or organization who owns the repository.
`repo-name`		The name of the GitHub repository.
`default-branch`	`main`	The name of the repository's default branch.
`min-branch-coverage`	`100`	The minimum acceptable branch coverage (as a percentage).
`author-name`	`Sanctuary`	The name of the individual or group to whom copyright should be attributed.
`contributing-file`	`CONTRIBUTING.md`	The name of the CONTRIBUTING file.
`license-file`	`LICENSE`	The name of the licence file.
`source-files`	`index.js`	Space-separated list of filenames. Globbing is supported (with `globstar`).
`readme-source-files`	`index.js`	Space-separated list of filenames. Globbing is supported (with `globstar`).
`test-files`	`test/*/.js`	Space-separated list of filenames. Globbing is supported (with `globstar`).
`heading-level`	`4`	The `<h[1-6]>` level of headings transcribed from `heading-prefix` comments.
`heading-prefix`	`#`	The character which follows `//` to signify a heading to transcribe.
`comment-prefix`	`.`	The character which follows `//` to signify documentation to transcribe.
`opening-delimiter`	```javascript \| The opening delimiter of doctest blocks in the source files.
`closing-delimiter`	``` \| The closing delimiter of doctest blocks in the source files.
`module-type`	`esm`	The module system doctest should use (`amd`, `commonjs`, or `esm`).
`version-tag-prefix`	`v`	The prefix of annotated version tags (`version-tag-prefix =` for no prefix).

Custom scripts

Variables do not always provide sufficient control over a script's behaviour, so one can provide a custom script to be used in place of the default script. Custom scripts live in the scripts subdirectory of the project's root directory, and their names correspond to those of the scripts they replace (without sanctuary- prefixes).

To augment rather than override (or disable) the default behaviour, have the custom script run the default script.

Scripts

`check-required-files`

Asserts that the project contains important files such as a licence file.

Configurable via variables (contributing-file, license-file).

`doctest`

Runs doctest↗︎ with suitable --module, --prefix, --opening-delimiter, and --closing-delimiter values.

Configurable via variables (source-files, comment-prefix, opening-delimiter, closing-delimiter, module-type).

`generate-readme`

Runs transcribe↗︎ then performs the following replacements to produce a Markdown readme:

v:${owner}/${name} → https://github.com/${owner}/${name}/tree/v${version}
V:${owner}/${name} → https://github.com/${owner}/${name}/tree/${version}
v:${owner}/${name}#${ident} → https://github.com/${owner}/${name}/tree/v${version}#${ident}
V:${owner}/${name}#${ident} → https://github.com/${owner}/${name}/tree/${version}#${ident}

${version} comes from either the "dependencies" field or the "devDependencies" field in package.json. This necessitates that the dependency's version be specified exactly ("1.2.3" rather than "1.2.x", for example).

Configurable via variables (repo-owner, repo-name, readme-source-files, heading-level, heading-prefix, comment-prefix, version-tag-prefix).

`lint`

Runs the following linters:

Configurable via variables (source-files, test-files, and those respected by the aforementioned linters).

`lint-commit-messages`

Asserts that none of the commits on the current branch but not on the default branch has a summary which exceeds 72 characters.

Asserts that the current branch name is short enough to appear in a merge commit without the commit summary exceeding 72 characters.

Configurable via variables (default-branch).

`lint-json`

Asserts that the specified JSON files exist and are neatly formatted.

`lint-package-json`

Asserts that package.json exists and contains important fields with suitable values.

Configurable via variables (repo-owner, repo-name).

`prepublish`

Runs update-copyright-year and generate-readme, and marks (via git add) the licence file and readme for inclusion in the release commit.

Configurable via variables (license-file).

:warning: This script is intended to be run indirectly via release.

`release`

Runs xyz↗︎ to publish a new version of the package. $1 must be a valid increment: major, minor, patch, premajor, preminor, prepatch, or prerelease.

Configurable via variables (repo-owner, repo-name, default-branch, version-tag-prefix, and those respected by prepublish).