package-linter v1.0.0-alpha.5
package-lint
A tool to lint your packages and dependencies automatically.
Installation
If using npm
:
npm install -D package-lint
If using yarn
:
yarn add -D package-lint
Usage
CLI
packagelint [--createExceptions]
Arguments:
--createExceptions
: When specified, each error will specify a JSON entry you can add to your exceptions file to disable the error.
API
You can invoke the linter programatically like so:
import { runLinter } from "package-lint";
const results = runLinter({
config: {
rules: {
"some-rule": "error",
},
errorOnUnusedExceptions: true,
},
exceptions: { configFilePath: ".packageLintExceptions.json" },
});
Argument
runLinter
takes one argument of type RuntimeApiArgs
.
args
(CliArgs
|undefined
) -- allows you to specify arguments normally passed in via the CLIconfig
({ configFilePath: string }
|Configuration
|undefined
) -- You can either specify a path to a configuration file, or specify the configuration inline.exceptions
({ configFilePath: string }
|RuleDisableFile
|undefined
) -- You can either specify a path to an exceptions file, or specify the exceptions inline.
Configuration
packagelint
uses cosmiconfig
for it's configuation. You can specify your configuartion file as any of the following:
package.json
fieldpackagelint
.packagelintrc
.packagelintrc.json
.packagelintrc.yaml
.packagelintrc.yml
.packagelintrc.js
.packagelintrc.cjs
packagelint.config.js
packagelint.config.cjs
Configuration format
The type Configuration
descripes the shape of the configuartion file.
rules
: ARecord<string, RuleEntry>
object that lists rules to run:- The key is the name of the rule, either one part of this package (
<rule name>
) or one from another package (<package name>/<rule name>
) - The value is either
RuleSeverity
("error" | "warn" | "off"
), or a tuple of[RuleSeverity, <rule options>]
, where<rule options>
is defined by each rule.
- The key is the name of the rule, either one part of this package (
errorOnUnusedExceptions
: An optionalboolean
that, whentrue
, will causepackagelint
to error when an exception is specified that doesn't map to any error thrown by a rule during the run.
Exceptions/disable directives
Since it is not possible to specify exceptions (sometimes called "disable directives" in other linters) directly in the JSON (particularly for external dependencies), all exceptions are specified in a separate file.
packagelint
uses cosmiconfig
for this. You can specify your exception file as any of the following:
package.json
fieldpackagelintexceptions
.packagelintexceptionsrc
.packagelintexceptionsrc.json
.packagelintexceptionsrc.yaml
.packagelintexceptionsrc.yml
.packagelintexceptionsrc.js
.packagelintexceptionsrc.cjs
packagelintexceptions.config.js
packagelintexceptions.config.cjs
Exception Format
The type RuleDisableFile
describes the shape of the configuration file, which is an array of objects that match one or more aspects of a rule error (ruleName
, packageName
, packageVersion
, or jsonPath
). Any rule error that matches all specified fields will be suppressed. Each entry can also specify a justification
for the exception.
Built-in rules
forbid-dependency
- Forbid specific dependencies or version ranges thereof from being included in the dependency tree- Options:
{ packageName: string | RegExp; semver?: string; }[]
packageName
can be astring
or aRegExp
to match against the name of a packagesemver
is a semantic versioning string that, when specified, restrict errors only to versions ofpackageName
that match the semver string.
- Options:
list-all-dependencies-in-root-package-json
- In a workspace repository, ensures that all external dependencies listed in indivdual packages are listed in the repository's rootpackage.json
with matching versionsno-duplicate-packages
- Reports an error when there are multiple copies (likely of two or more versions) of a dependency.no-pinned-dependency
- Reports an error when a package has a dependency on a single version (eg., no^
or~
semver range) of another dependency.no-tagged-versions
- Reports an error when a package has a dependency on a tagged version (eg.,1.0.0-beta.0
) of a dependency
Building your own rules
TODO: Fill this in
Testing
TODO: Fill this in
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Trademarks
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago