patchdrill 0.1.0

package/action.yml

@@ -0,0 +1,338 @@
+name: PatchDrill
+description: Generate deterministic patch verification evidence for pull requests.
+author: PatchDrill contributors
+inputs:
+  base:
+    description: Base ref to compare against.
+    required: false
+    default: origin/main
+  fail-on:
+    description: Severity threshold that should fail the action.
+    required: false
+    default: high
+  max-risk:
+    description: Maximum allowed risk score from 0 to 100.
+    required: false
+    default: "69"
+  max-risk-delta:
+    description: Maximum allowed risk increase against the optional baseline report.
+    required: false
+    default: ""
+  max-output-chars:
+    description: Maximum characters to retain from each command output stream.
+    required: false
+    default: "20000"
+  command-timeout-ms:
+    description: Optional timeout in milliseconds for each verification command.
+    required: false
+    default: ""
+  config:
+    description: Optional PatchDrill policy path.
+    required: false
+    default: ""
+  baseline:
+    description: Optional previous PatchDrill JSON report to compare against.
+    required: false
+    default: ""
+  run:
+    description: Execute required verification commands.
+    required: false
+    default: "false"
+  run-optional:
+    description: Execute optional inferred verification commands when run is true.
+    required: false
+    default: "false"
+  evidence:
+    description: Audit evidence manifest output path.
+    required: false
+    default: patchdrill-evidence.json
+  summary:
+    description: Compact Markdown summary output path for PR comments and step summaries.
+    required: false
+    default: patchdrill-summary.md
+  markdown:
+    description: Markdown report output path.
+    required: false
+    default: patchdrill-report.md
+  json:
+    description: JSON report output path.
+    required: false
+    default: patchdrill-report.json
+  sarif:
+    description: SARIF report output path.
+    required: false
+    default: patchdrill.sarif
+  html:
+    description: Static HTML dashboard output path.
+    required: false
+    default: patchdrill-dashboard.html
+  dashboard-history:
+    description: Newline-separated previous PatchDrill JSON report paths to include in the static HTML dashboard trend.
+    required: false
+    default: ""
+  annotations:
+    description: Emit GitHub Actions annotations for PatchDrill findings.
+    required: false
+    default: "true"
+  step-summary:
+    description: Append the compact Markdown summary to the GitHub Actions step summary.
+    required: false
+    default: "true"
+  pr-comment:
+    description: Upsert the compact Markdown summary as a pull request comment.
+    required: false
+    default: "false"
+  comment-marker:
+    description: Hidden marker used to find and update an existing PatchDrill PR comment.
+    required: false
+    default: "<!-- patchdrill-report -->"
+outputs:
+  report-evidence:
+    description: Path to the generated audit evidence manifest.
+    value: ${{ steps.paths.outputs.evidence }}
+  report-summary:
+    description: Path to the generated compact Markdown summary.
+    value: ${{ steps.paths.outputs.summary }}
+  report-json:
+    description: Path to the generated JSON report.
+    value: ${{ steps.paths.outputs.json }}
+  report-markdown:
+    description: Path to the generated Markdown report.
+    value: ${{ steps.paths.outputs.markdown }}
+  report-sarif:
+    description: Path to the generated SARIF report.
+    value: ${{ steps.paths.outputs.sarif }}
+  report-html:
+    description: Path to the generated HTML dashboard.
+    value: ${{ steps.paths.outputs.html }}
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@v6
+      with:
+        node-version: 22
+        cache: npm
+        cache-dependency-path: ${{ github.action_path }}/package-lock.json
+    - name: Install PatchDrill action dependencies
+      shell: bash
+      working-directory: ${{ github.action_path }}
+      run: npm ci --ignore-scripts
+    - name: Build PatchDrill action
+      shell: bash
+      working-directory: ${{ github.action_path }}
+      run: npm run build
+    - name: Run PatchDrill
+      id: run
+      shell: bash
+      env:
+        PATCHDRILL_BASE: ${{ inputs.base }}
+        PATCHDRILL_FAIL_ON: ${{ inputs.fail-on }}
+        PATCHDRILL_MAX_RISK: ${{ inputs.max-risk }}
+        PATCHDRILL_MAX_RISK_DELTA: ${{ inputs.max-risk-delta }}
+        PATCHDRILL_MAX_OUTPUT_CHARS: ${{ inputs.max-output-chars }}
+        PATCHDRILL_COMMAND_TIMEOUT_MS: ${{ inputs.command-timeout-ms }}
+        PATCHDRILL_CONFIG: ${{ inputs.config }}
+        PATCHDRILL_BASELINE: ${{ inputs.baseline }}
+        PATCHDRILL_RUN: ${{ inputs.run }}
+        PATCHDRILL_RUN_OPTIONAL: ${{ inputs.run-optional }}
+        PATCHDRILL_EVIDENCE: ${{ inputs.evidence }}
+        PATCHDRILL_SUMMARY: ${{ inputs.summary }}
+        PATCHDRILL_MARKDOWN: ${{ inputs.markdown }}
+        PATCHDRILL_JSON: ${{ inputs.json }}
+        PATCHDRILL_SARIF: ${{ inputs.sarif }}
+        PATCHDRILL_HTML: ${{ inputs.html }}
+        PATCHDRILL_ANNOTATIONS: ${{ inputs.annotations }}
+      run: |
+        args=(
+          scan
+          --base "$PATCHDRILL_BASE"
+          --evidence "$PATCHDRILL_EVIDENCE"
+          --summary-markdown "$PATCHDRILL_SUMMARY"
+          --markdown "$PATCHDRILL_MARKDOWN"
+          --json "$PATCHDRILL_JSON"
+          --sarif "$PATCHDRILL_SARIF"
+          --html "$PATCHDRILL_HTML"
+          --fail-on "$PATCHDRILL_FAIL_ON"
+          --max-risk "$PATCHDRILL_MAX_RISK"
+          --max-output-chars "$PATCHDRILL_MAX_OUTPUT_CHARS"
+          --run "${PATCHDRILL_RUN:-false}"
+          --run-optional "${PATCHDRILL_RUN_OPTIONAL:-false}"
+          --github-annotations "${PATCHDRILL_ANNOTATIONS:-false}"
+        )
+        if [ -n "$PATCHDRILL_CONFIG" ]; then
+          args+=(--config "$PATCHDRILL_CONFIG")
+        fi
+        if [ -n "$PATCHDRILL_BASELINE" ]; then
+          args+=(--baseline "$PATCHDRILL_BASELINE")
+        fi
+        if [ -n "$PATCHDRILL_MAX_RISK_DELTA" ]; then
+          args+=(--max-risk-delta "$PATCHDRILL_MAX_RISK_DELTA")
+        fi
+        if [ -n "$PATCHDRILL_COMMAND_TIMEOUT_MS" ]; then
+          args+=(--command-timeout-ms "$PATCHDRILL_COMMAND_TIMEOUT_MS")
+        fi
+        set +e
+        node "$GITHUB_ACTION_PATH/dist/cli.js" "${args[@]}"
+        STATUS=$?
+        echo "status=$STATUS" >> "$GITHUB_OUTPUT"
+        exit 0
+    - name: Render dashboard history
+      if: inputs.dashboard-history != ''
+      shell: bash
+      env:
+        PATCHDRILL_DASHBOARD_HISTORY: ${{ inputs.dashboard-history }}
+        PATCHDRILL_JSON: ${{ inputs.json }}
+        PATCHDRILL_HTML: ${{ inputs.html }}
+      run: |
+        args=(dashboard)
+        while IFS= read -r report_path; do
+          if [ -n "$report_path" ]; then
+            args+=(--json "$report_path")
+          fi
+        done <<< "$PATCHDRILL_DASHBOARD_HISTORY"
+        args+=(--json "$PATCHDRILL_JSON" --output "$PATCHDRILL_HTML")
+        node "$GITHUB_ACTION_PATH/dist/cli.js" "${args[@]}"
+    - name: Refresh evidence manifest
+      shell: bash
+      env:
+        PATCHDRILL_EVIDENCE: ${{ inputs.evidence }}
+        PATCHDRILL_SUMMARY: ${{ inputs.summary }}
+        PATCHDRILL_MARKDOWN: ${{ inputs.markdown }}
+        PATCHDRILL_JSON: ${{ inputs.json }}
+        PATCHDRILL_SARIF: ${{ inputs.sarif }}
+        PATCHDRILL_HTML: ${{ inputs.html }}
+      run: |
+        if [ -n "$PATCHDRILL_EVIDENCE" ] && [ -n "$PATCHDRILL_JSON" ]; then
+          args=(evidence --json "$PATCHDRILL_JSON" --evidence "$PATCHDRILL_EVIDENCE")
+          if [ -n "$PATCHDRILL_SUMMARY" ]; then
+            args+=(--summary-markdown "$PATCHDRILL_SUMMARY")
+          fi
+          if [ -n "$PATCHDRILL_MARKDOWN" ]; then
+            args+=(--markdown "$PATCHDRILL_MARKDOWN")
+          fi
+          if [ -n "$PATCHDRILL_SARIF" ]; then
+            args+=(--sarif "$PATCHDRILL_SARIF")
+          fi
+          if [ -n "$PATCHDRILL_HTML" ]; then
+            args+=(--html "$PATCHDRILL_HTML")
+          fi
+          node "$GITHUB_ACTION_PATH/dist/cli.js" "${args[@]}"
+        fi
+    - name: Verify evidence manifest
+      shell: bash
+      env:
+        PATCHDRILL_EVIDENCE: ${{ inputs.evidence }}
+      run: |
+        if [ -n "$PATCHDRILL_EVIDENCE" ]; then
+          node "$GITHUB_ACTION_PATH/dist/cli.js" verify --evidence "$PATCHDRILL_EVIDENCE"
+        fi
+    - name: Write step summary
+      shell: bash
+      env:
+        PATCHDRILL_STEP_SUMMARY: ${{ inputs.step-summary }}
+        PATCHDRILL_SUMMARY: ${{ inputs.summary }}
+      run: |
+        bool_true() {
+          local value="${1,,}"
+          case "$value" in
+            true|1|yes|on) return 0 ;;
+            false|0|no|off|"") return 1 ;;
+            *)
+              echo "Invalid boolean input for step-summary: $1" >&2
+              exit 1
+              ;;
+          esac
+        }
+        if ! bool_true "$PATCHDRILL_STEP_SUMMARY"; then
+          exit 0
+        fi
+        if [ -n "${GITHUB_STEP_SUMMARY:-}" ] && [ -f "$PATCHDRILL_SUMMARY" ]; then
+          cat -- "$PATCHDRILL_SUMMARY" >> "$GITHUB_STEP_SUMMARY"
+        fi
+    - name: Upsert PR comment
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v9
+      env:
+        PATCHDRILL_PR_COMMENT: ${{ inputs.pr-comment }}
+        PATCHDRILL_SUMMARY: ${{ inputs.summary }}
+        PATCHDRILL_MARKER: ${{ inputs.comment-marker }}
+      with:
+        script: |
+          const fs = require("fs");
+          const boolTrue = (name) => {
+            const raw = process.env[name] || "";
+            const value = raw.trim().toLowerCase();
+            if (["true", "1", "yes", "on"].includes(value)) return true;
+            if (["false", "0", "no", "off", ""].includes(value)) return false;
+            throw new Error(`Invalid boolean input for pr-comment: ${raw}`);
+          };
+          if (!boolTrue("PATCHDRILL_PR_COMMENT")) {
+            return;
+          }
+          const marker = process.env.PATCHDRILL_MARKER || "<!-- patchdrill-report -->";
+          const summaryPath = process.env.PATCHDRILL_SUMMARY || "patchdrill-summary.md";
+          if (!fs.existsSync(summaryPath)) {
+            core.warning(`PatchDrill summary report not found: ${summaryPath}`);
+            return;
+          }
+          const body = `${marker}\n${fs.readFileSync(summaryPath, "utf8")}`;
+          const { owner, repo } = context.repo;
+          const issue_number = context.payload.pull_request.number;
+          try {
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner,
+              repo,
+              issue_number,
+              per_page: 100
+            });
+            const existing = comments.find((comment) => comment.user?.type === "Bot" && comment.body?.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                comment_id: existing.id,
+                body
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number,
+                body
+              });
+            }
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            core.warning(`PatchDrill PR comment skipped: ${message}`);
+          }
+    - name: Export report paths
+      id: paths
+      shell: bash
+      env:
+        PATCHDRILL_EVIDENCE: ${{ inputs.evidence }}
+        PATCHDRILL_SUMMARY: ${{ inputs.summary }}
+        PATCHDRILL_MARKDOWN: ${{ inputs.markdown }}
+        PATCHDRILL_JSON: ${{ inputs.json }}
+        PATCHDRILL_SARIF: ${{ inputs.sarif }}
+        PATCHDRILL_HTML: ${{ inputs.html }}
+      run: |
+        write_output() {
+          local name="$1"
+          local value="$2"
+          local delimiter="patchdrill_${name}_EOF"
+          {
+            printf '%s<<%s\n' "$name" "$delimiter"
+            printf '%s\n' "$value"
+            printf '%s\n' "$delimiter"
+          } >> "$GITHUB_OUTPUT"
+        }
+        write_output evidence "$PATCHDRILL_EVIDENCE"
+        write_output summary "$PATCHDRILL_SUMMARY"
+        write_output json "$PATCHDRILL_JSON"
+        write_output markdown "$PATCHDRILL_MARKDOWN"
+        write_output sarif "$PATCHDRILL_SARIF"
+        write_output html "$PATCHDRILL_HTML"
+    - name: Fail on PatchDrill gate
+      if: steps.run.outputs.status != '0'
+      shell: bash
+      run: exit "${{ steps.run.outputs.status }}"

package/dist/baseline.d.ts

@@ -0,0 +1,9 @@
+import type { PatchReport, PatchStatus, RiskFinding } from "./types.js";
+export interface BaselineComparisonInput {
+    summary: {
+        status: PatchStatus;
+        riskScore: number;
+    };
+    findings: RiskFinding[];
+}
+export declare function compareBaseline(root: string, baselinePath: string, current: BaselineComparisonInput): NonNullable<PatchReport["baseline"]>;

package/dist/baseline.js

@@ -0,0 +1,38 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+export function compareBaseline(root, baselinePath, current) {
+    const resolved = isAbsolute(baselinePath) ? baselinePath : resolve(root, baselinePath);
+    if (!existsSync(resolved))
+        throw new Error(`PatchDrill baseline report not found: ${resolved}`);
+    const baseline = readBaselineReport(resolved);
+    const previousFindings = new Set((baseline.findings ?? []).map(findingFingerprint));
+    const currentFindings = new Set(current.findings.map(findingFingerprint));
+    const newFindingCount = [...currentFindings].filter((fingerprint) => !previousFindings.has(fingerprint)).length;
+    const resolvedFindingCount = [...previousFindings].filter((fingerprint) => !currentFindings.has(fingerprint)).length;
+    const unchangedFindingCount = [...currentFindings].filter((fingerprint) => previousFindings.has(fingerprint)).length;
+    return {
+        path: relative(root, resolved),
+        ...(baseline.summary?.status !== undefined ? { previousStatus: baseline.summary.status } : {}),
+        currentStatus: current.summary.status,
+        ...(baseline.summary?.riskScore !== undefined ? { previousRiskScore: baseline.summary.riskScore } : {}),
+        currentRiskScore: current.summary.riskScore,
+        riskDelta: current.summary.riskScore - (baseline.summary?.riskScore ?? 0),
+        newFindingCount,
+        resolvedFindingCount,
+        unchangedFindingCount
+    };
+}
+function readBaselineReport(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Failed to read PatchDrill baseline report ${path}: ${error instanceof Error ? error.message : String(error)}`, {
+            cause: error
+        });
+    }
+}
+function findingFingerprint(finding) {
+    return [finding.ruleId ?? "", finding.severity, finding.title, finding.file ?? "", finding.line ?? ""].join("\0");
+}
+//# sourceMappingURL=baseline.js.map

package/dist/baseline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { type Locale } from "./i18n.js";
+import { type GateOptions } from "./report.js";
+import { scan } from "./scan.js";
+export interface ParsedArgs {
+    command: string;
+    flags: Record<string, string | boolean | string[]>;
+    positionals: string[];
+}
+export declare function scanCommand(parsed: ParsedArgs): Promise<void>;
+export declare function dashboardCommand(parsed: ParsedArgs): void;
+export declare function demoCommand(parsed: ParsedArgs): void;
+export declare function doctorCommand(parsed?: ParsedArgs): void;
+export declare function evidenceCommand(parsed: ParsedArgs): void;
+export declare function explainCommand(): void;
+export declare function renderExplainText(): string;
+export declare function releaseCheckCommand(parsed?: ParsedArgs): void;
+export declare function renderConsoleSummary(report: Awaited<ReturnType<typeof scan>>, gateOptions: GateOptions, locale?: Locale): string;
+export declare function parseArgs(args: string[]): ParsedArgs;