proof-pr 0.1.10 → 0.1.12

package/README.md

@@ -12,7 +12,15 @@ ProofPR 是给开源维护者和工程团队使用的 PR 证据门禁。它在
 npx proof-pr@latest --version
 ```
 
-当前应输出 `0.1.10`。
+当前应输出 `0.1.12`。
+
+不知道用哪个功能时：
+
+```bash
+npx proof-pr@latest
+# 或
+npx proof-pr@latest guide
+```
 
 初始化配置和 GitHub Action：
 
@@ -37,7 +45,7 @@ npx proof-pr@latest scan --diff-file examples/cases/workflow-untrusted-checkout.
 生成独立 HTML 可视化报告：
 
 ```bash
-npx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN --format html > proofpr-report.html
+npx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN --format html --output proofpr-report.html
 ```
 
 运行 benchmark：
@@ -49,7 +57,7 @@ npx proof-pr@latest benchmark --cases benchmarks/cases
 ## GitHub Action
 
 ```yaml
-- uses: linsk27/proof-pr@v0.1.10
+- uses: linsk27/proof-pr@v0.1.12
   with:
     fail-on: high
     comment: "true"
@@ -62,7 +70,7 @@ npx proof-pr@latest benchmark --cases benchmarks/cases
 - 证据评分：0-100 分。
 - Review 门禁：正常 review、重点 review、先补证据、风险处理前不要合并。
 - Review 行动清单：维护者可直接执行的 checklist。
-- 可选输出：GitHub annotations、SARIF、benchmark report、独立 HTML 可视化报告。
+- 可选输出：GitHub annotations、SARIF、benchmark report、独立 HTML 可视化报告；CLI 可用 `--output` 直接写文件。
 
 ## 常用预设
 

package/dist/index.js

@@ -25732,7 +25732,13 @@ 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.10");
+    .version("0.1.12");
+build_program
+    .command("guide")
+    .description("Show a copy-paste friendly guide for common ProofPR tasks.")
+    .action(() => {
+    process.stdout.write(renderGuide());
+});
 build_program
     .command("scan", { isDefault: true })
     .description("Scan a git diff and print a ProofPR report.")
@@ -25744,6 +25750,7 @@ build_program
     .option("--pr-body-file <path>", "Read a pull request body from a Markdown file.")
     .option("--config <path>", "Path to .proofpr.yml.", ".proofpr.yml")
     .option("--format <format>", "Output format: markdown, json, sarif, or html.", parseFormat, "markdown")
+    .option("--output <path>", "Write report output to a file instead of stdout.")
     .option("--locale <locale>", "Report language: en or zh-CN.")
     .option("--fail-on <level>", "Exit with code 1 on risk level: low, medium, high, or never.", parseFailLevel, "never")
     .action(async (options) => {
@@ -25758,7 +25765,13 @@ build_program
     const result = scanDiff(diffText, { config, pullRequest });
     const locale = parseLocale(options.locale, config.locale);
     const output = renderOutput(result, options.format, locale);
-    process.stdout.write(`${output}\n`);
+    if (options.output) {
+        await writeOutput(options.output, `${output}\n`);
+        process.stdout.write(`ProofPR ${options.format} report written to ${options.output}\n`);
+    }
+    else {
+        process.stdout.write(`${output}\n`);
+    }
     if (riskMeetsThreshold(result.risk, options.failOn)) {
         process.exitCode = 1;
     }
@@ -25774,7 +25787,7 @@ build_program
     .action(async (options) => {
     await writeIfMissing(options.configPath, renderConfigTemplate(options.preset), options.force);
     await writeIfMissing(options.workflowPath, renderWorkflowTemplate(options.failOn), options.force);
-    process.stdout.write(`ProofPR initialized.\n\nCreated:\n- ${options.configPath}\n- ${options.workflowPath}\n\nNext:\n1. Commit these files.\n2. Open or update a pull request.\n3. Read the ProofPR comment or Actions summary.\n\nLocal check:\nnpx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN\n`);
+    process.stdout.write(`ProofPR initialized.\n\nCreated:\n- ${options.configPath}\n- ${options.workflowPath}\n\nNext:\n1. Commit these files.\n2. Open or update a pull request.\n3. Read the ProofPR comment or Actions summary.\n\nLocal check:\nnpx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN\n\nNeed another task?\nnpx proof-pr@latest guide\n`);
 });
 build_program
     .command("benchmark")
@@ -25805,11 +25818,52 @@ build_program
         process.exitCode = 1;
     }
 });
-build_program.parseAsync(process.argv).catch((error) => {
+const args = process.argv.slice(2);
+const parseTask = args.length === 0
+    ? Promise.resolve(process.stdout.write(renderGuide()))
+    : build_program.parseAsync(process.argv);
+parseTask.catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
     process.stderr.write(`ProofPR failed: ${message}\n`);
     process.exitCode = 1;
 });
+function renderGuide() {
+    return `ProofPR 功能菜单
+
+最推荐先做第 1 步。已经接入过的项目，按目标复制下面的命令即可。
+
+1. 接入 GitHub PR 自动检查
+   npx proof-pr@latest init
+   然后提交 .proofpr.yml 和 .github/workflows/proofpr.yml，打开 PR 后看评论和 Actions summary。
+
+2. 本地检查当前分支
+   npx proof-pr@latest scan --base origin/main --head HEAD --locale zh-CN
+   适合在发 PR 前先看风险、证据评分和 Review 行动清单。
+
+3. 生成可分享 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
+   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 benchmark --cases benchmarks/cases
+   适合维护 ProofPR 规则或发版前回归。
+
+7. 调整审查强度
+   打开 .proofpr.yml，把 preset 改成 security-strict、dependency-careful 或 mcp-security。
+
+结果在哪里看：
+- GitHub Action：PR Conversation 评论、Actions summary、Checks 状态。
+- 本地 CLI：终端输出；如果用了 --output，就看写出的 HTML / JSON / SARIF / Markdown 文件。
+`;
+}
 async function readGitDiff(base, head) {
     const args = ["diff", "--no-ext-diff", "--unified=0"];
     if (base) {
@@ -25871,7 +25925,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: linsk27/proof-pr@v0.1.10
+      - uses: linsk27/proof-pr@v0.1.12
         with:
           fail-on: ${failOn}
           comment: "true"

package/package.json

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