proof-pr 0.1.12 → 0.1.14

package/README.md

@@ -12,7 +12,7 @@ ProofPR 是给开源维护者和工程团队使用的 PR 证据门禁。它在
 npx proof-pr@latest --version
 ```
 
-当前应输出 `0.1.12`。
+当前应输出 `0.1.14`。
 
 不知道用哪个功能时：
 
@@ -22,6 +22,13 @@ npx proof-pr@latest
 npx proof-pr@latest guide
 ```
 
+不接入仓库，先体验报告：
+
+```bash
+npx proof-pr@latest demo workflow --locale zh-CN
+npx proof-pr@latest demo --list
+```
+
 初始化配置和 GitHub Action：
 
 ```bash
@@ -30,6 +37,14 @@ npx proof-pr@latest init
 
 这个命令会生成 `.proofpr.yml` 和 `.github/workflows/proofpr.yml`，提交后打开 PR 即可看到报告。
 
+体检接入状态：
+
+```bash
+npx proof-pr@latest doctor
+```
+
+这个命令会检查配置文件、workflow、Action 版本、PR 权限和本地 diff 是否可读。
+
 本地扫描当前分支：
 
 ```bash
@@ -57,7 +72,7 @@ npx proof-pr@latest benchmark --cases benchmarks/cases
 ## GitHub Action
 
 ```yaml
-- uses: linsk27/proof-pr@v0.1.12
+- uses: linsk27/proof-pr@v0.1.14
   with:
     fail-on: high
     comment: "true"

package/dist/index.js

@@ -25728,17 +25728,187 @@ function dedupeFindings(findings) {
 
 
 const execFileAsync = (0,external_node_util_namespaceObject.promisify)(external_node_child_process_.execFile);
+const CLI_VERSION = "0.1.14";
+const DEMO_CASES = [
+    {
+        id: "workflow",
+        title: "高权限 workflow 运行不可信 PR 代码",
+        description: "演示 pull_request_target 与 PR head checkout 组合风险。",
+        diffText: `diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
+index 1111111..2222222 100644
+--- a/.github/workflows/pr.yml
++++ b/.github/workflows/pr.yml
+@@ -1,7 +1,17 @@
+ name: PR automation
+ on:
++  pull_request_target:
++    types: [opened, synchronize]
++
+ jobs:
+   test:
+     runs-on: ubuntu-latest
+     steps:
+-      - uses: actions/checkout@v4
++      - uses: actions/checkout@v4
++        with:
++          repository: \${{ github.event.pull_request.head.repo.full_name }}
++          ref: \${{ github.event.pull_request.head.sha }}
++      - run: pnpm install
++      - run: pnpm test
+`
+    },
+    {
+        id: "secret",
+        title: "疑似 secret 被提交",
+        description: "演示 .env、OpenAI key、数据库连接串等敏感内容会被拦截。",
+        diffText: `diff --git a/.env b/.env
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/.env
+@@ -0,0 +1,2 @@
++OPENAI_API_KEY=sk-proj-examplevalueexamplevalue1234567890
++DATABASE_URL=postgres://demo:super-secret-password@example.com:5432/app
+`
+    },
+    {
+        id: "dependency",
+        title: "依赖大版本升级",
+        description: "演示依赖 major upgrade 需要 changelog、迁移说明和验证证据。",
+        diffText: `diff --git a/package.json b/package.json
+index 1111111..2222222 100644
+--- a/package.json
++++ b/package.json
+@@ -1,8 +1,8 @@
+ {
+   "dependencies": {
+-    "react": "^18.2.0",
++    "react": "^19.0.0",
+     "zod": "^3.25.1"
+   },
+   "devDependencies": {
+     "typescript": "^5.9.3"
+   }
+ }
+`
+    },
+    {
+        id: "mcp",
+        title: "MCP 本地命令和凭据面",
+        description: "演示 MCP / agent 配置中的 command、args、env 风险。",
+        diffText: `diff --git a/.cursor/mcp.json b/.cursor/mcp.json
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/.cursor/mcp.json
+@@ -0,0 +1,11 @@
++{
++  "mcpServers": {
++    "local-admin": {
++      "command": "node",
++      "args": ["scripts/admin-server.js"],
++      "env": {
++        "API_TOKEN": "\${LOCAL_API_TOKEN}"
++      }
++    }
++  }
++}
+`,
+        config: { preset: "mcp-security" }
+    },
+    {
+        id: "ui-evidence",
+        title: "UI 改动缺少截图证据",
+        description: "演示 Evidence Contract：组件改动必须提供截图和验证说明。",
+        diffText: `diff --git a/src/components/Button.tsx b/src/components/Button.tsx
+index 1111111..2222222 100644
+--- a/src/components/Button.tsx
++++ b/src/components/Button.tsx
+@@ -1,3 +1,7 @@
+ export function Button() {
+-  return <button>Save</button>;
++  return (
++    <button className="primary">
++      Save
++    </button>
++  );
+ }
+`,
+        config: {
+            evidence: {
+                contracts: [
+                    {
+                        id: "ui-screenshot",
+                        title: "UI changes need screenshots",
+                        paths: ["src/components/**"],
+                        requires: ["screenshot", "verification"],
+                        severity: "medium"
+                    }
+                ]
+            }
+        },
+        pullRequest: {
+            title: "Update button styling",
+            body: "This updates the primary button style and spacing so the layout is easier to scan."
+        }
+    }
+];
 const build_program = new Command();
 build_program
     .name("proof-pr")
     .description("Review pull request evidence, scope, and safety before maintainers spend time on it.")
-    .version("0.1.12");
+    .version(CLI_VERSION);
 build_program
     .command("guide")
     .description("Show a copy-paste friendly guide for common ProofPR tasks.")
     .action(() => {
     process.stdout.write(renderGuide());
 });
+build_program
+    .command("doctor")
+    .description("Check whether ProofPR is installed correctly in the current repository.")
+    .option("--config <path>", "Path to .proofpr.yml.", ".proofpr.yml")
+    .option("--workflow-path <path>", "Path to the GitHub Actions workflow.", ".github/workflows/proofpr.yml")
+    .option("--base <ref>", "Base git ref used for local diff checks.", "origin/main")
+    .option("--head <ref>", "Head git ref used for local diff checks.", "HEAD")
+    .action(async (options) => {
+    const report = await runDoctor(options);
+    process.stdout.write(renderDoctorReport(report));
+    if (report.checks.some((check) => check.level === "fail")) {
+        process.exitCode = 1;
+    }
+});
+build_program
+    .command("demo")
+    .description("Run a built-in ProofPR demo case without cloning this repository.")
+    .argument("[case]", "Demo case id. Use --list to see available cases.", "workflow")
+    .option("--list", "List built-in demo cases.", false)
+    .option("--format <format>", "Output format: markdown, json, sarif, or html.", parseFormat, "markdown")
+    .option("--output <path>", "Write demo report output to a file instead of stdout.")
+    .option("--locale <locale>", "Report language: en or zh-CN.", "zh-CN")
+    .action(async (caseId, options) => {
+    if (options.list) {
+        process.stdout.write(renderDemoList());
+        return;
+    }
+    const demoCase = DEMO_CASES.find((item) => item.id === caseId);
+    if (!demoCase) {
+        throw new Error(`Unknown demo case "${caseId}". Run "proof-pr demo --list" to see available cases.`);
+    }
+    const result = scanDiff(demoCase.diffText, {
+        config: demoCase.config,
+        pullRequest: demoCase.pullRequest
+    });
+    const locale = parseLocale(options.locale, "zh-CN");
+    const output = renderDemoOutput(demoCase, result, options.format, locale);
+    if (options.output) {
+        await writeOutput(options.output, `${output}\n`);
+        process.stdout.write(`ProofPR demo ${options.format} report written to ${options.output}\n`);
+    }
+    else {
+        process.stdout.write(`${output}\n`);
+    }
+});
 build_program
     .command("scan", { isDefault: true })
     .description("Scan a git diff and print a ProofPR report.")
@@ -25836,27 +26006,34 @@ function renderGuide() {
    npx proof-pr@latest init
    然后提交 .proofpr.yml 和 .github/workflows/proofpr.yml，打开 PR 后看评论和 Actions summary。
 
-2. 本地检查当前分支
+2. 体检当前仓库接入状态
+   npx proof-pr@latest doctor
+   检查配置文件、workflow、Action 版本、PR 权限和本地 diff 是否正常。
+
+3. 本地检查当前分支
    npx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN
    适合在发 PR 前先看风险、证据评分和 Review 行动清单。
 
-3. 生成可分享 HTML 报告
+4. 生成可分享 HTML 报告
    npx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN --format html --output proofpr-report.html
    生成后用浏览器打开 proofpr-report.html。
 
-4. 生成 GitHub Code Scanning 的 SARIF
+5. 生成 GitHub Code Scanning 的 SARIF
    npx proof-pr@latest scan --base origin/main --head HEAD --format sarif --output proofpr.sarif
    适合在 CI 里配合 github/codeql-action/upload-sarif 使用。
 
-5. 试跑内置风险案例
-   npx proof-pr@latest scan --diff-file examples/cases/workflow-untrusted-checkout.diff --locale zh-CN
-   不需要改项目代码，也能快速看到 ProofPR 会抓什么风险。
+6. 不接入仓库，先试跑内置案例
+   npx proof-pr@latest demo workflow --locale zh-CN
+   不需要 clone 仓库或寻找 examples 文件，也能快速看到 ProofPR 会抓什么风险。
 
-6. 验证规则样本是否仍然命中
+7. 查看所有内置案例
+   npx proof-pr@latest demo --list
+
+8. 验证规则样本是否仍然命中
    npx proof-pr@latest benchmark --cases benchmarks/cases
    适合维护 ProofPR 规则或发版前回归。
 
-7. 调整审查强度
+9. 调整审查强度
    打开 .proofpr.yml，把 preset 改成 security-strict、dependency-careful 或 mcp-security。
 
 结果在哪里看：
@@ -25864,6 +26041,188 @@ function renderGuide() {
 - 本地 CLI：终端输出；如果用了 --output，就看写出的 HTML / JSON / SARIF / Markdown 文件。
 `;
 }
+function renderDemoList() {
+    const rows = DEMO_CASES.map((item) => `- ${item.id}: ${item.title}\n  ${item.description}`).join("\n");
+    return `ProofPR 内置案例
+
+用法：
+npx proof-pr@latest demo <case> --locale zh-CN
+
+可用案例：
+${rows}
+`;
+}
+function renderDemoOutput(demoCase, result, format, locale) {
+    if (format === "json") {
+        return JSON.stringify({
+            demo: {
+                id: demoCase.id,
+                title: demoCase.title,
+                description: demoCase.description
+            },
+            result
+        }, null, 2);
+    }
+    if (format === "markdown") {
+        return `# ProofPR demo: ${demoCase.title}
+
+${demoCase.description}
+
+${renderMarkdownReport(result, locale)}`;
+    }
+    return renderOutput(result, format, locale);
+}
+async function runDoctor(options) {
+    const checks = [];
+    const nextSteps = new Set();
+    if (await pathExists(options.config)) {
+        try {
+            const config = await loadConfig(options.config);
+            checks.push({
+                level: "pass",
+                title: `${options.config} 可读取`,
+                detail: `locale=${config.locale}, preset=${config.preset}, riskThreshold=${config.riskThreshold}`
+            });
+            if (config.comment.enabled) {
+                checks.push({ level: "pass", title: "PR 评论已启用", detail: "comment.enabled=true" });
+            }
+            else {
+                checks.push({ level: "warn", title: "PR 评论未启用", detail: "comment.enabled=false" });
+                nextSteps.add("如果希望在 PR Conversation 里看到报告，把 .proofpr.yml 的 comment.enabled 改成 true。");
+            }
+        }
+        catch (error) {
+            checks.push({
+                level: "fail",
+                title: `${options.config} 解析失败`,
+                detail: error instanceof Error ? error.message : String(error)
+            });
+            nextSteps.add("修复 .proofpr.yml 的 YAML 格式，或重新运行 npx proof-pr@latest init --force。");
+        }
+    }
+    else {
+        checks.push({ level: "fail", title: `缺少 ${options.config}` });
+        nextSteps.add("运行 npx proof-pr@latest init 生成 .proofpr.yml 和 GitHub Actions workflow。");
+    }
+    if (await pathExists(options.workflowPath)) {
+        const workflow = await (0,promises_namespaceObject.readFile)(options.workflowPath, "utf8");
+        checks.push({ level: "pass", title: `${options.workflowPath} 已存在` });
+        inspectWorkflow(workflow, checks, nextSteps);
+    }
+    else {
+        checks.push({ level: "fail", title: `缺少 ${options.workflowPath}` });
+        nextSteps.add("运行 npx proof-pr@latest init 生成 .github/workflows/proofpr.yml。");
+    }
+    await inspectGitDiff(options, checks, nextSteps);
+    if (nextSteps.size === 0) {
+        nextSteps.add("当前接入状态正常；可以打开 PR，或运行 npx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN 做本地自查。");
+    }
+    return { checks, nextSteps: [...nextSteps] };
+}
+function inspectWorkflow(workflow, checks, nextSteps) {
+    if (/pull_request\s*:/.test(workflow)) {
+        checks.push({ level: "pass", title: "workflow 会在 Pull Request 事件运行" });
+    }
+    else {
+        checks.push({ level: "fail", title: "workflow 没有监听 pull_request" });
+        nextSteps.add("确认 .github/workflows/proofpr.yml 包含 on.pull_request。");
+    }
+    const actionVersion = workflow.match(/linsk27\/proof-pr@(v[0-9]+\.[0-9]+\.[0-9]+)/)?.[1];
+    if (!actionVersion) {
+        checks.push({ level: "fail", title: "workflow 没有使用 linsk27/proof-pr Action" });
+        nextSteps.add(`把 workflow step 更新为 uses: linsk27/proof-pr@v${CLI_VERSION}。`);
+    }
+    else if (actionVersion === `v${CLI_VERSION}`) {
+        checks.push({ level: "pass", title: `GitHub Action 版本为 ${actionVersion}` });
+    }
+    else {
+        checks.push({
+            level: "warn",
+            title: `GitHub Action 版本较旧：${actionVersion}`,
+            detail: `当前 CLI 版本是 v${CLI_VERSION}`
+        });
+        nextSteps.add(`把 workflow 里的 uses 更新为 linsk27/proof-pr@v${CLI_VERSION}。`);
+    }
+    if (/pull-requests\s*:\s*write/.test(workflow)) {
+        checks.push({ level: "pass", title: "workflow 具备写 PR 评论权限" });
+    }
+    else {
+        checks.push({ level: "warn", title: "workflow 可能缺少 pull-requests: write 权限" });
+        nextSteps.add("如果需要自动评论 PR，在 workflow permissions 中加入 pull-requests: write。");
+    }
+    if (/contents\s*:\s*read/.test(workflow)) {
+        checks.push({ level: "pass", title: "workflow 具备读取仓库内容权限" });
+    }
+    else {
+        checks.push({ level: "warn", title: "workflow 未显式声明 contents: read" });
+        nextSteps.add("建议在 workflow permissions 中加入 contents: read。");
+    }
+}
+async function inspectGitDiff(options, checks, nextSteps) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--is-inside-work-tree"]);
+        if (stdout.trim() !== "true") {
+            checks.push({ level: "warn", title: "当前目录不是 Git 仓库" });
+            nextSteps.add("进入项目 Git 仓库根目录后再运行 npx proof-pr@latest doctor。");
+            return;
+        }
+    }
+    catch {
+        checks.push({ level: "warn", title: "当前目录不是 Git 仓库" });
+        nextSteps.add("进入项目 Git 仓库根目录后再运行 npx proof-pr@latest doctor。");
+        return;
+    }
+    checks.push({ level: "pass", title: "当前目录位于 Git 仓库中" });
+    try {
+        const branch = (await execFileAsync("git", ["branch", "--show-current"])).stdout.trim();
+        checks.push({
+            level: "info",
+            title: branch ? `当前分支：${branch}` : "当前处于 detached HEAD"
+        });
+    }
+    catch {
+        checks.push({ level: "info", title: "无法读取当前分支名" });
+    }
+    try {
+        const diff = await readGitDiff(options.base, options.head);
+        checks.push({
+            level: "pass",
+            title: `可以读取 ${options.base}...${options.head} diff`,
+            detail: diff.length === 0 ? "当前没有可扫描的 diff。" : `diff 大小约 ${diff.length} 字符。`
+        });
+    }
+    catch (error) {
+        checks.push({
+            level: "warn",
+            title: `无法读取 ${options.base}...${options.head} diff`,
+            detail: error instanceof Error ? error.message : String(error)
+        });
+        nextSteps.add(`运行 git fetch origin 后重试；如果主分支不是 main，请使用 --base origin/master 或你的实际主分支。`);
+    }
+}
+function renderDoctorReport(report) {
+    const failCount = report.checks.filter((check) => check.level === "fail").length;
+    const warnCount = report.checks.filter((check) => check.level === "warn").length;
+    const status = failCount > 0 ? "需要先修复" : warnCount > 0 ? "基本可用，但建议优化" : "接入正常";
+    const checks = report.checks
+        .map((check) => {
+        const detail = check.detail ? `\n       ${check.detail}` : "";
+        return `[${check.level}] ${check.title}${detail}`;
+    })
+        .join("\n");
+    const nextSteps = report.nextSteps.map((step) => `- ${step}`).join("\n");
+    return `ProofPR doctor
+
+状态：${status}
+统计：${failCount} fail, ${warnCount} warn, ${report.checks.length} checks
+
+Checks:
+${checks}
+
+Next:
+${nextSteps}
+`;
+}
 async function readGitDiff(base, head) {
     const args = ["diff", "--no-ext-diff", "--unified=0"];
     if (base) {
@@ -25925,7 +26284,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: linsk27/proof-pr@v0.1.12
+      - uses: linsk27/proof-pr@v${CLI_VERSION}
         with:
           fail-on: ${failOn}
           comment: "true"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proof-pr",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "CLI for ProofPR, a maintainer-focused pull request evidence scanner.",
   "license": "MIT",
   "type": "module",