Dependency notes for JavaScript

package.json is JSON, and JSON has no comments. Why a package is there, why it is pinned, what to run before upgrading it: none of that fits in the file. It ends up in commit messages, pull requests and people's memory, and the next person — or the next AI agent — upgrades the package anyway.

Pacmon keeps that note in .pacmon/DEPENDENCY-NOTES.md, beside package.json, and shows it on the dependency's line: the first line at the end of the line, the whole note on hover.

package.json in IntelliJ IDEA: filled marks and the first line of the note after typescript, vite and vue-tsc, hollow marks before the packages that have no note yet — `package.json` in IntelliJ IDEA. Copyright © 2026 JetBrains s.r.o., used with permission. IntelliJ IDEA and the IntelliJ IDEA logo are trademarks of JetBrains s.r.o.

What Pacmon reads

Manifest: package.json
Notes file: .pacmon/DEPENDENCY-NOTES.md
Section heading: the package name: ## express, ## @types/node

Pacmon reads dependencies, devDependencies, peerDependencies and optionalDependencies.

It does not matter which package manager installs the packages — npm, pnpm, Yarn or Bun. Pacmon reads package.json itself and never runs any of them.

Example

{
  "dependencies": {
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  },
  "devDependencies": {
    "@types/node": "^22.10.2"
  }
}

.pacmon/DEPENDENCY-NOTES.md:

## @types/node

Types for the Node version in .nvmrc, not the newest one.

### Agent notes

- purpose: type definitions for the Node runtime the build scripts run on
- constraint: keep the major equal to the Node major in .nvmrc (22)

## react

Stay on 18 until the design system ships its React 19 build (DS-88).

### Agent notes

- purpose: UI library for the whole front end
- constraint: stay on ^18 — the design system still relies on APIs that React 19 removed
- bump-with: react-dom
- verify: `pnpm test` and the visual regression suite (`pnpm test:visual`)
- verified: 18.3.1

The heading is the package name as package.json spells it, scope included. Sections are sorted by name, so @types/node comes before react.

For AI coding agents

An agent reads a package's section before it adds, upgrades or removes the package. constraint: tells it what must not change, verify: what to run, and bump-with: which packages move together. It logs what it tried, including the upgrades it reverted, so the next agent does not try them again. See the rules agents follow.