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#

bash

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#

bash

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#

bash

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#

bash

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)#

RuleSeverityDescriptionmissing-nameerrorNo name fieldmissing-versionerrorNo version fieldinvalid-nameerrorName doesn't match npm naming rulesinvalid-versionerrorVersion not valid semvermissing-descriptionwarningNo description field

Dependencies (6 rules)#

RuleSeverityDescriptionwildcard-dependencyerrorVersion is *, empty, or latest``git-dependencywarningPoints to git URL (fragile)file-dependencywarningUses file: protocolpinned-dependencyinfoAll deps pinned to exact versionsduplicate-dependencywarningSame package in deps and devDepsdeprecated-packagewarningKnown deprecated package (~20 tracked)

Security (4 rules)#

RuleSeverityDescriptionpostinstall-scriptwarningSupply chain riskpreinstall-scriptwarningSupply chain riskinstall-scriptwarningSupply chain risksuspicious-scriptwarningContains curl/wget/eval/pipe-to-shell

Best Practices (7 rules)#

RuleSeverityDescriptionmissing-licensewarningNo license fieldmissing-repositoryinfoNo repository fieldmissing-enginesinfoNo engines fieldmissing-keywordsinfoNo keywords fieldmissing-maininfoNo main or exports fieldmissing-scriptsinfoNo scripts sectionnon-https-urlwarningURLs not using HTTPS

Exit Codes#

• 0 — no errors found
• 1 — errors found (or warnings in --strict mode)

Output Formats#

• text — human-readable, one issue per line (default)
• json — structured JSON with summary counts
• markdown — table format for reports and PRs