npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

sanctuary-scripts

v7.0.0

Published

Shell scripts used in multiple Sanctuary projects

Downloads

8,125

Readme

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

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

  2. 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"
      }
    }
  3. 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
  4. 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).

test

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).

update-copyright-year

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) <year> <author-name>.

Configurable via variables (author-name, license-file).