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.
Routing
Section titled “Routing”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.
type | One unit per | name |
|---|---|---|
dependency | Changed entry in dependencies, devDependencies, peerDependencies, or optionalDependencies | dependencies.express |
override | Changed entry in overrides or resolutions, at any depth | overrides.react-scripts > nth-check |
lifecycle_script | Changed preinstall, install, postinstall, or prepare script | scripts.postinstall |
engines | Changed entry in engines | engines.node |
lockfile_package | Changed package, with its entries and lines grouped | express |
lockfile_overflow | One lockfile’s changed packages beyond the 40-package cap | (more packages) |
lockfile_deleted | Deleted lockfile | Its path |
lockfile_other | Lockfile lines outside a package entry shown in the diff | (lines outside a package entry) |
npmrc_setting | Changed .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.
Large lockfiles
Section titled “Large lockfiles”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.
Secrets in .npmrc
Section titled “Secrets in .npmrc”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.
Parsing strategy
Section titled “Parsing strategy”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.jsonandnpm-shrinkwrap.json(versions 1 to 3): npm indents by two spaces. At depth 2, anode_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 asapp@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.importersentries 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.
| Rule | Severity | What it catches |
|---|---|---|
NPM-001 | MEDIUM or LOW | A new direct dependency; dev dependencies are LOW |
NPM-002 | HIGH | A new lockfile package or changed source with no matching package.json change |
NPM-003 | MEDIUM | A loosened version spec: *, a dist-tag, or a widened range |
NPM-004 | HIGH | A dependency from outside the registry, such as an unpinned git source, tarball URL, file: path, or GitHub shorthand |
NPM-005 | MEDIUM | A lockfile source hosted outside the public npm and Yarn registries |
NPM-006 | HIGH | An integrity hash changed while the version stayed the same, or was removed |
NPM-007 | HIGH | A lifecycle script added or changed: preinstall, install, postinstall, or prepare |
NPM-008 | HIGH or MEDIUM | A literal .npmrc credential, strict-ssl=false, a registry host change, or removal of ignore-scripts=true |
NPM-009 | MEDIUM | An override that downgrades a package or widens its scope |
NPM-010 | MEDIUM | A downgrade or major-version change to an authentication, cryptography, TLS, or HTTP package |
NPM-PERF-001 | LOW | A second major version of a package in the lockfile |
NPM-PERF-002 | LOW | A new dependency with an install script or native build step |
NPM-REL-001 | MEDIUM | A lockfile deleted with no other lockfile added or changed |
NPM-REL-002 | LOW | An 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.