Extensible standards auditing and linting tool. Nags like your mother but is probably a lot more technical.
With StandardLint, you use Checks to inform what standards you want to inspect, in effect being your standards yardstick:
A fact or standard by which you can judge the success or value of something. β Cambridge Dictionary
StandardLint makes it convenient and easy to set up guardrails and guidelines for development teams and making sure they follow your house conventions.
The result of a run could look like this:
β
PASS: Diagrams
β
PASS: Changelog
ποΈ No custom path assigned to check "Diagrams" - Using default path "diagrams"...
β οΈ WARN: Diagrams
β
PASS: Lock files
β
PASS: License
β FAIL: Code owners
β FAIL: Contribution information
ποΈ No custom path assigned to check "IAC configuration" - Using default path "serverless.yml"...
β
PASS: IAC configuration
ποΈ No custom path assigned to check "SLOs" - Using default path "manifest.json"...
β οΈ WARN: SLOs
ποΈ No custom path assigned to check "Tags" - Using default path "manifest.json"...
β
PASS: Tags
ποΈ No custom path assigned to check "CI configuration" - Using default path ".github/workflows/main.yml"...
β
PASS: CI configuration
β
PASS: Security information
ποΈ No custom path assigned to check "Service metadata" - Using default path "manifest.json"...
β
PASS: Service metadata
The majority of StandardLint checks are meant to assess the overall architecture, for example presence of certain files or documentation. While StandardLint has a few checks that inspect code (throwing errors and using console
), the majority of such use cases are better handled with something like ESLint.
There's a ready-to-use StandardLint GitHub Action in the Marketplace if you really want the minimum hassle. Plus, you get a great visual overview of your checks!
Install StandardLint with npm install standardlint
.
Before running StandardLint you need a configuration. This is a basic JSON file with the name standardlint.json
. Place it in the root of your project.
The format is:
{
"basePath": "",
"checks": [],
"defaultSeverity": ""
}
Key | Required | Default | Example | Description |
---|---|---|---|---|
basePath |
No | . |
./project_dir/ |
Sets the base path for any file lookups. |
ignorePaths |
No | [] |
["/tests/", "/src/problematic-file.ts"] |
Paths that will be ignored for some checks. Does not support globbing. |
checks |
Yes | - | ["checkForPresenceLicense"] |
A list of checks to run, either using string or object form. |
defaultSeverity |
No | error |
warn |
Sets the default severity level for any issues. |
path |
No | Multiple values | api/schema.yml |
Sets the exact path to a resource. Only used optionally by some checks. |
If you for some reason keep your project files "lower" than in the root where you want to do file lookups, you can add this optional argument.
It's recommended you do not change this unless you know what you are doing.
This provides the possibility to ignore certain paths.
These paths will be respected and discarded by the following checks:
checkForConsoleUsage
checkForPresenceTests
checkForThrowingPlainErrors
Checks can be provided in string form or object form:
- String format:
["checkForDefinedTags"]
- Object format:
[{ "name": "checkForPresenceContributing", "severity": "warn" }]
You need to use the object form if you want to override the overall severity level, and use the check's severity
level.
You can also combine the formats for different checks.
["checkForDefinedTags", { "name": "checkForPresenceContributing", "severity": "warn" }]
Some checks also provide the optional path
key. Use this when you want to override default values, for example to the location of an API schema.
[{ "name": "checkForPresenceApiSchema", "path": "api/schema.yml" }]
This can be either warn
or error
(the default value). Using it in error
mode means that any failure will produce an error, while the warn
mode simply warns for any non-compliance.
It's super easy to use StandardLint from the CLI! Just run npx standardlint
and it will use the configuration in your project.
To output the results into standardlint.results.json
, run npx standardlint --output
.
You can also import and use StandardLint like a conventional Node package.
It exposes a factory function to vend a new StandardLint
instance with a check()
method.
If using it as an imported package, you will need to provide either a configuration file (for example loaded with fs
) or the actual configuration as an object.
import { createNewStandardLint } from 'standardlint';
const config = {
checks: [
{ name: 'checkForPresenceContributing', severity: 'warn' },
{ name: 'checkForPresenceLicense', severity: 'error' }
]
};
const standardLint = createNewStandardLint(config);
const results = standardLint.check();
console.log(results);
To output the results into standardlint.results.json
, run:
const standardLint = createNewStandardLint(config);
const results = standardLint.check(true); // <--- Adding true here will output the results to disk
Service metadata definition checks assume you are using Catalogist or something with the same manifest file structure.
Any check with a default
value can be overridden using the path
argument.
Runs all checks.
Checks if there are conflicting Node package lock files (i.e. both a Yarn lock file and an NPM lock file).
Checks if console
is used, e.g. console.log()
and similar. This is useful when you want to ensure a more comprehensive logging approach is used.
Note that this uses a naive solution so even just a mention of console.log() (or similar) will fail this check.
Will respect ignorePaths
options.
Default: src
Checks if the service metadata defines system relations.
Default: manifest.json
Checks if the service metadata defines Service Level Objectives.
Default: manifest.json
Checks if the service metadata defines tags.
Default: manifest.json
Checks if there is an API schema.
Default: api/schema.json
Checks if there is a CHANGELOG.md
file.
Checks if there is a CI/CD configuration file.
Default: .github/workflows/main.yml
Checks if there is a CODEOWNERS
file.
Checks if there is a CONTRIBUTING.md
file.
Checks if there is a diagrams folder with diagram files in it. The check assumes .drawio
files.
Default: diagrams
Checks if there is Infrastructure-as-Code configuration present.
Default: serverless.yml
Checks if there is a LICENSE.md
file.
Checks if there is a README.md
file.
Checks if there is a SECURITY.md
file.
Checks if there a service metadata file present.
Default: manifest.json
Checks if there is a template for GitHub issues.
Default: .github/ISSUE_TEMPLATE/issue.md
Checks if there is a template for GitHub Pull Requests.
Default: .github/ISSUE_TEMPLATE/pull_request.md
Checks if there are any tests in the provided location. This will match anything ending in (test|spec).(ts|js)
.
Default: tests
Will respect ignorePaths
options.
Checks if any file uses throw Error
or throw new Error
. This is meant to push toward the use of actual loggers, rather than plain console output.
Will respect ignorePaths
options.
- Service metadata: Do you link to observability resources (logs/metrics/traces/dashboards etc.)?
- Support for external config