Skip to content
DashboardWebsite

npm Dependencies Pack

URL slug: npm-dependencies

The npm Dependencies Pack reviews dependency changes in a unified git diff of package.json, npm and Yarn lockfiles, pnpm-lock.yaml, and .npmrc. It creates analysis units for changed dependencies, lockfile packages, and registry settings.

The pack claims paths matching *package.json, *package-lock.json, *npm-shrinkwrap.json, *yarn.lock, *pnpm-lock.yaml, and *.npmrc. The parser reads only those exact file names. For example, a glob match such as mypackage.json produces no unit.

The pack does not override sniff(). Its ingest() reads unified diffs, so a lockfile pasted without a file path does not identify its format.

Core sends the pack all files it claims from the diff in one input. A lockfile and a package.json in the same diff therefore arrive together, letting a lockfile unit report whether the manifest changed the package.

typeOne unit pername
dependencyChanged entry in dependencies, devDependencies, peerDependencies, or optionalDependenciesdependencies.express
overrideChanged entry in overrides or resolutions, at any depthoverrides.react-scripts > nth-check
lifecycle_scriptChanged preinstall, install, postinstall, or prepare scriptscripts.postinstall
enginesChanged entry in enginesengines.node
lockfile_packageChanged package, with its entries and lines groupedexpress
lockfile_overflowOne lockfile’s changed packages beyond the 40-package cap(more packages)
lockfile_deletedDeleted lockfileIts path
lockfile_otherLockfile lines outside a package entry shown in the diff(lines outside a package entry)
npmrc_settingChanged .npmrc setting@acme:registry

Other package.json scripts and top-level fields produce no unit.

Each unit body starts with facts read from the whole diff, followed by the diff lines. A lockfile package unit reports versions, sources, and integrity before and after the change. It also reports whether an install script was added, whether the lockfile’s workspace entry declares the package, and what any package.json in the diff says about it.

metadata.group_path is the directory containing the file. For example, units from apps/web/package.json have the group path apps/web.

A regenerated lockfile can change hundreds of entries, and each unit costs one model call. The pack creates at most 40 package units per lockfile. Direct dependencies come first, followed by packages with a warning sign (an integrity change, an install script, or a non-registry source), then the rest in diff order. One lockfile_overflow unit lists remaining packages by name and version, and identifies any with a source outside a registry.

Before a unit is stored or sent to a model, the parser replaces literal _authToken, _auth, and _password values with their length. It keeps environment references such as ${NPM_TOKEN} as written.

A hunk contains only part of a file, so a complete JSON or YAML parser cannot parse it. The pack reads formats by indentation: a line belongs to the nearest earlier line that opens a block at a smaller indent. It reads removed and added lines as separate views of the file.

  • package.json: The section comes from the nearest enclosing key shown in the hunk. A hunk in the middle of a long dependency list may not show that key; a changed line can still count as a dependency if its value looks like a version spec.
  • package-lock.json and npm-shrinkwrap.json (versions 1 to 3): npm indents by two spaces. At depth 2, a node_modules/... key or package name identifies a package; "" or a path identifies a workspace. The version 1 tree, also present in version 2, groups under the same package.
  • yarn.lock: A header at column 0 names the entry. Yarn 2+ workspace entries such as app@workspace:. declare direct dependencies.
  • pnpm-lock.yaml (versions 5 to 9): The pack parses indentation locally, without a YAML library. Package keys carry their version ([email protected], /[email protected], /ms/2.1.3), so an upgrade appears as a removed key and an added key grouped under one package. importers entries are direct dependencies.

When a hunk starts below an entry’s key, a resolved URL or Yarn resolution line can identify the package. If the hunk has no such line, its lines go to the lockfile_other unit.

The pack has one implicit variant, rules/npm-dependencies-rules.md; list_rule_types() is empty. Performance and Reliability rules have LOW or MEDIUM severity and do not fail the merge check on their own.

RuleSeverityWhat it catches
NPM-001MEDIUM or LOWA new direct dependency; dev dependencies are LOW
NPM-002HIGHA new lockfile package or changed source with no matching package.json change
NPM-003MEDIUMA loosened version spec: *, a dist-tag, or a widened range
NPM-004HIGHA dependency from outside the registry, such as an unpinned git source, tarball URL, file: path, or GitHub shorthand
NPM-005MEDIUMA lockfile source hosted outside the public npm and Yarn registries
NPM-006HIGHAn integrity hash changed while the version stayed the same, or was removed
NPM-007HIGHA lifecycle script added or changed: preinstall, install, postinstall, or prepare
NPM-008HIGH or MEDIUMA literal .npmrc credential, strict-ssl=false, a registry host change, or removal of ignore-scripts=true
NPM-009MEDIUMAn override that downgrades a package or widens its scope
NPM-010MEDIUMA downgrade or major-version change to an authentication, cryptography, TLS, or HTTP package
NPM-PERF-001LOWA second major version of a package in the lockfile
NPM-PERF-002LOWA new dependency with an install script or native build step
NPM-REL-001MEDIUMA lockfile deleted with no other lockfile added or changed
NPM-REL-002LOWAn engines range removed or widened

Like other packs’ built-in rulesets, these rules seed into an organization’s editable custom_rules rows. Core keeps rows an organization has not edited in step with this file (OpenTremor-core#0034).

The demo adds a dependency from GitHub with an install script, downgrades jsonwebtoken, adds a postinstall script, and commits a registry token to .npmrc.