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 CLI
• config ({ 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 field packagelint
• .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: A Record<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.
• errorOnUnusedExceptions: An optional boolean that, when true, will cause packagelint 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 field packagelintexceptions
• .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 a string or a RegExp to match against the name of a package
    • semver is a semantic versioning string that, when specified, restrict errors only to versions of packageName that match the semver string.
• 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 root package.json with matching versions
• no-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 [email protected] 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.