Shell scripts used in multiple Sanctuary projects
npm install sanctuary-scriptsShell 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).
1. Add sanctuary-scripts to "devDependencies" in __package.json__.
2. Define the following "scripts" in __package.json__:
``json`
{
"scripts": {
"doctest": "sanctuary-doctest",
"lint": "sanctuary-lint",
"release": "sanctuary-release",
"test": "npm run lint && sanctuary-test && npm run doctest"
}
}
3. Add a file named __.config__ in the project's root directory, with
suitable repo-owner and repo-name values. For example:
`text`
repo-owner = sanctuary-js
repo-name = sanctuary-type-classes
4. Add a file named __.eslintrc.json__ in the project's root directory,
with the following JSON configuration:
`json`
{
"root": true,
"extends": ["./node_modules/sanctuary-style/eslint.json"]
}
Runs [lint][], [test][], and [doctest][].
Runs [lint][] only.
Runs [doctest][] only.
Runs [release][] with the specified increment (major, minor, patch,premajor, preminor, prepatch, or prerelease).
There are two layers of configuration available: [variables][] and
[custom scripts][].
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 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). |
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.
Asserts that the project contains important files such as a licence file.
Configurable via [variables][] (contributing-file, license-file).
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).
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"1.2.3"
that the dependency's version be specified exactly ( rather"1.2.x"
than , for example).
Configurable via [variables][] (repo-owner, repo-name,readme-source-files, heading-level, heading-prefix, comment-prefix,version-tag-prefix).
Runs the following linters:
- [check-required-files][]eslint
- [↗︎][]lint-package-json
- [][]lint-commit-messages
- [][]
Configurable via [variables][] (source-files, test-files, and those
respected by the aforementioned linters).
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).
Asserts that the specified JSON files exist and are neatly formatted.
Asserts that __package.json__ exists and contains important fields with
suitable values.
Configurable via [variables][] (repo-owner, repo-name).
Runs [update-copyright-year][] and [generate-readme][], and marks (viagit 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][]._
Runs [xyz↗︎][] to publish a new version of the package. $1 must be a validmajor
increment: , minor, patch, premajor, preminor, prepatch, orprerelease.
Configurable via [variables][] (repo-owner, repo-name, default-branch,version-tag-prefix, and those respected by [prepublish][]).
Runs [oletus↗︎][] via [c8↗︎][] to run the project's test suite and assert
that it satisfies the project's coverage requirements.
Configurable via [variables][] (min-branch-coverage, test-files).
Replaces the copyright year in the licence file with the year of the project's
most recently authored commit on the current branch.
Assumes that the licence file contains Copyright (c) .
Configurable via [variables][] (author-name, license-file).
[check-required-files]: #check-required-filesdoctest
[]: #doctestgenerate-readme
[]: #generate-readmelint
[]: #lintlint-commit-messages
[]: #lint-commit-messageslint-package-json
[]: #lint-package-jsonprepublish
[]: #prepublishrelease
[]: #releasetest
[]: #testupdate-copyright-year
[]: #update-copyright-year
[custom scripts]: #custom-scripts
[variables]: #variables
[c8↗︎]: https://github.com/bcoe/c8doctest
[↗︎]: https://github.com/davidchambers/doctesteslint
[↗︎]: https://eslint.org/oletus
[↗︎]: https://github.com/bearror/oletustranscribe
[↗︎]: https://github.com/plaid/transcribexyz`↗︎]: https://github.com/davidchambers/xyz
[