Package JSON Linter
Lint package.json files for missing fields, dependency issues, security risks, and best practices violations.
Commands
All commands use the bundled Python script at scripts/package_json_linter.py.
1. Lint a package.json file
python3 scripts/package_json_linter.py lint <file-or-directory> [--strict] [--format text|json|markdown]
Runs all lint rules against one or more package.json files. If given a directory, scans for package.json files recursively (excluding node_modules).
Flags:
--strict— exit code 1 on any warning (not just errors)--format— output format:text(default),json,markdown
2. Audit for security issues
python3 scripts/package_json_linter.py security <file-or-directory> [--format text|json|markdown]
Checks for supply chain risks: postinstall/preinstall/install scripts, and scripts containing curl, wget, eval, or piping to shell.
3. Analyze scripts section
python3 scripts/package_json_linter.py scripts <file-or-directory> [--format text|json|markdown]
Analyzes the scripts section for missing common scripts (test, start, build), placeholder test scripts, dependency issues, and deprecated packages.
4. Validate required fields and structure
python3 scripts/package_json_linter.py validate <file-or-directory> [--strict] [--format text|json|markdown]
Validates required fields (name, version, description), semver format, npm naming rules, dependency issues, and best practice fields.
Lint Rules (22 rules)
Required Fields (5 rules)
| Rule | Severity | Description |
|---|---|---|
missing-name | error | No name field |
missing-version | error | No version field |
invalid-name | error | Name doesn't match npm naming rules |
invalid-version | error | Version not valid semver |
missing-description | warning | No description field |
Dependencies (6 rules)
| Rule | Severity | Description |
|---|---|---|
wildcard-dependency | error | Version is *, empty, or latest |
git-dependency | warning | Points to git URL (fragile) |
file-dependency | warning | Uses file: protocol |
pinned-dependency | info | All deps pinned to exact versions |
duplicate-dependency | warning | Same package in deps and devDeps |
deprecated-package | warning | Known deprecated package (~20 tracked) |
Security (4 rules)
| Rule | Severity | Description |
|---|---|---|
postinstall-script | warning | Supply chain risk |
preinstall-script | warning | Supply chain risk |
install-script | warning | Supply chain risk |
suspicious-script | warning | Contains curl/wget/eval/pipe-to-shell |
Best Practices (7 rules)
| Rule | Severity | Description |
|---|---|---|
missing-license | warning | No license field |
missing-repository | info | No repository field |
missing-engines | info | No engines field |
missing-keywords | info | No keywords field |
missing-main | info | No main or exports field |
missing-scripts | info | No scripts section |
non-https-url | warning | URLs not using HTTPS |
Exit Codes
0— no errors found1— errors found (or warnings in--strictmode)
Output Formats
text— human-readable, one issue per line (default)json— structured JSON with summary countsmarkdown— table format for reports and PRs