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 in the project's root directory, with
suitable and values. For example:
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:
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:
${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).