patchdrill 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,206 @@
+import type { Locale } from "./i18n.js";
+export type Severity = "info" | "low" | "medium" | "high" | "critical";
+export type PatchStatus = "pass" | "warn" | "fail";
+export type FileStatus = "added" | "modified" | "deleted" | "renamed" | "copied" | "untracked" | "unknown";
+export interface ChangedFile {
+    path: string;
+    previousPath?: string;
+    status: FileStatus;
+    additions: number;
+    deletions: number;
+    binary: boolean;
+    owners?: string[];
+}
+export interface AddedLine {
+    file: string;
+    line: number;
+    content: string;
+}
+export interface ProjectSignal {
+    ecosystem: "node" | "python" | "rust" | "go" | "java" | "android" | "ruby" | "php" | "dotnet" | "swift" | "xcode" | "terraform" | "docker" | "kubernetes" | "bazel" | "buck" | "pants" | "github-actions" | "unknown";
+    manifestPath: string;
+    framework?: "django" | "fastapi" | "spring-boot" | "rails" | "laravel" | "aspnet-core";
+    entrypoint?: string;
+    packageManager?: string;
+    taskRunner?: "turbo" | "nx";
+    scripts?: Record<string, string>;
+    workspacePackages?: WorkspacePackage[];
+}
+export interface WorkspacePackage {
+    name: string;
+    projectName?: string;
+    path: string;
+    scripts: Record<string, string>;
+    targets?: string[];
+    dependencies?: string[];
+}
+export type DependencyChangeType = "added" | "removed" | "updated";
+export interface DependencyChange {
+    file: string;
+    packageName: string;
+    dependencyType: "dependencies" | "devDependencies" | "peerDependencies" | "optionalDependencies" | "lockfile";
+    changeType: DependencyChangeType;
+    packagePath?: string;
+    before?: string;
+    after?: string;
+}
+export type PackageScriptChangeType = "added" | "removed" | "updated";
+export interface PackageScriptChange {
+    file: string;
+    scriptName: string;
+    changeType: PackageScriptChangeType;
+    before?: string;
+    after?: string;
+}
+export interface CommandPlan {
+    id: string;
+    label: string;
+    command: string;
+    reason: string;
+    ecosystem: ProjectSignal["ecosystem"] | "general";
+    required: boolean;
+    packageName?: string;
+    packagePath?: string;
+}
+export interface CommandResult {
+    id: string;
+    command: string;
+    exitCode: number;
+    durationMs: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}
+export type VerificationStatus = "passed" | "failed" | "timed-out" | "not-run" | "skipped-optional";
+export interface VerificationSummary {
+    plannedRequired: number;
+    plannedOptional: number;
+    run: number;
+    passed: number;
+    failed: number;
+    timedOut: number;
+    missingRequired: number;
+    skippedOptional: number;
+    unplannedResults: number;
+}
+export interface VerificationCommand {
+    id: string;
+    label: string;
+    command: string;
+    reason: string;
+    ecosystem: CommandPlan["ecosystem"];
+    required: boolean;
+    planned: boolean;
+    status: VerificationStatus;
+    packageName?: string;
+    packagePath?: string;
+    exitCode?: number;
+    durationMs?: number;
+    timedOut?: boolean;
+}
+export interface PatchVerification {
+    summary: VerificationSummary;
+    commands: VerificationCommand[];
+}
+export interface RiskFinding {
+    ruleId?: string;
+    severity: Severity;
+    title: string;
+    detail: string;
+    file?: string;
+    line?: number;
+    remediation?: string;
+    tags?: string[];
+}
+export interface PolicyRule {
+    id: string;
+    title: string;
+    severity: Severity;
+    path?: string | string[];
+    detail?: string;
+    remediation?: string;
+    weight?: number;
+    tags?: string[];
+}
+export interface PatchPolicy {
+    ignoredPaths: string[];
+    failOn?: Severity;
+    maxRisk?: number;
+    rules: PolicyRule[];
+    requiredCommands: CommandPlan[];
+    optionalCommands: CommandPlan[];
+}
+export interface PatchSummary {
+    status: PatchStatus;
+    riskScore: number;
+    confidenceScore: number;
+    changedFileCount: number;
+    additions: number;
+    deletions: number;
+    requiredCommandCount: number;
+    failedCommandCount: number;
+}
+export interface PatchReport {
+    schemaVersion: "1";
+    generatedAt: string;
+    root: string;
+    base?: string;
+    head?: string;
+    summary: PatchSummary;
+    changedFiles: ChangedFile[];
+    addedLines: number;
+    projectSignals: ProjectSignal[];
+    affectedPackages: WorkspacePackage[];
+    dependencyChanges: DependencyChange[];
+    packageScriptChanges: PackageScriptChange[];
+    policy?: {
+        path: string;
+        ignoredPaths: string[];
+        failOn?: Severity;
+        maxRisk?: number;
+        ruleCount: number;
+        requiredCommandCount: number;
+        optionalCommandCount: number;
+    };
+    codeOwners?: {
+        path: string;
+        ruleCount: number;
+    };
+    baseline?: {
+        path: string;
+        previousStatus?: PatchStatus;
+        currentStatus: PatchStatus;
+        previousRiskScore?: number;
+        currentRiskScore: number;
+        riskDelta: number;
+        newFindingCount: number;
+        resolvedFindingCount: number;
+        unchangedFindingCount: number;
+    };
+    findings: RiskFinding[];
+    commandPlan: CommandPlan[];
+    commandResults: CommandResult[];
+    verification: PatchVerification;
+}
+export interface ScanOptions {
+    cwd: string;
+    base?: string;
+    head?: string;
+    run?: boolean;
+    runOptional?: boolean;
+    failOn?: Severity;
+    configPath?: string;
+    baselinePath?: string;
+    evidencePath?: string;
+    summaryMarkdownPath?: string;
+    markdownPath?: string;
+    jsonPath?: string;
+    sarifPath?: string;
+    htmlPath?: string;
+    maxOutputChars?: number;
+    commandTimeoutMs?: number;
+    /** Override the report timestamp for reproducible output; falls back to SOURCE_DATE_EPOCH then wall clock. */
+    generatedAt?: string;
+    /** Output locale for human-facing artifacts (markdown/summary/html). Default English. */
+    locale?: Locale;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/verification.d.ts

@@ -0,0 +1,11 @@
+import type { CommandResult, PatchReport, PatchVerification, VerificationCommand, VerificationSummary } from "./types.js";
+export interface VerificationExecution extends VerificationCommand {
+    result?: CommandResult;
+}
+export declare function verificationExecutions(report: Pick<PatchReport, "commandPlan" | "commandResults">): VerificationExecution[];
+export declare function verificationSummary(report: Pick<PatchReport, "commandPlan" | "commandResults">): VerificationSummary;
+export declare function formatVerificationStatus(execution: VerificationExecution): string;
+export declare function reportVerification(report: Pick<PatchReport, "commandPlan" | "commandResults">): PatchVerification;
+export declare function withVerification<T extends Omit<PatchReport, "verification">>(report: T): T & {
+    verification: PatchVerification;
+};

package/dist/verification.js

@@ -0,0 +1,108 @@
+export function verificationExecutions(report) {
+    const resultsById = new Map(report.commandResults.map((result) => [result.id, result]));
+    const plannedIds = new Set(report.commandPlan.map((plan) => plan.id));
+    const executions = report.commandPlan.map((plan) => {
+        const result = resultsById.get(plan.id);
+        return {
+            id: plan.id,
+            label: plan.label,
+            command: plan.command,
+            reason: plan.reason,
+            ecosystem: plan.ecosystem,
+            required: plan.required,
+            planned: true,
+            ...(plan.packageName ? { packageName: plan.packageName } : {}),
+            ...(plan.packagePath ? { packagePath: plan.packagePath } : {}),
+            ...(result ? { result } : {}),
+            ...(result ? { exitCode: result.exitCode, durationMs: result.durationMs } : {}),
+            ...(result?.timedOut !== undefined ? { timedOut: result.timedOut } : {}),
+            status: statusFor(plan, result)
+        };
+    });
+    for (const result of report.commandResults) {
+        if (plannedIds.has(result.id))
+            continue;
+        executions.push({
+            id: result.id,
+            label: "Unplanned command result",
+            command: result.command,
+            reason: "A command result was recorded without a matching verification plan entry.",
+            ecosystem: "general",
+            required: false,
+            planned: false,
+            result,
+            exitCode: result.exitCode,
+            durationMs: result.durationMs,
+            ...(result.timedOut !== undefined ? { timedOut: result.timedOut } : {}),
+            status: statusFor(undefined, result)
+        });
+    }
+    return executions;
+}
+export function verificationSummary(report) {
+    const executions = verificationExecutions(report);
+    return summarizeExecutions(report.commandPlan, executions);
+}
+function summarizeExecutions(commandPlan, executions) {
+    return {
+        plannedRequired: commandPlan.filter((command) => command.required).length,
+        plannedOptional: commandPlan.filter((command) => !command.required).length,
+        run: executions.filter((execution) => execution.result).length,
+        passed: executions.filter((execution) => execution.result && execution.status === "passed").length,
+        // Status-based so passed + failed + timedOut partitions `run`: a timed-out
+        // command has exitCode 124 and must not also be counted as failed.
+        failed: executions.filter((execution) => execution.result && execution.status === "failed").length,
+        timedOut: executions.filter((execution) => execution.result?.timedOut === true).length,
+        missingRequired: executions.filter((execution) => execution.status === "not-run").length,
+        skippedOptional: executions.filter((execution) => execution.status === "skipped-optional").length,
+        unplannedResults: executions.filter((execution) => !execution.planned).length
+    };
+}
+export function formatVerificationStatus(execution) {
+    const prefix = execution.planned ? "" : "unplanned ";
+    if (!execution.result)
+        return execution.status === "skipped-optional" ? "skipped optional" : "not run";
+    if (execution.result.timedOut)
+        return `${prefix}timed out (${execution.result.exitCode})`;
+    if (execution.result.exitCode === 0)
+        return `${prefix}passed`;
+    return `${prefix}failed (${execution.result.exitCode})`;
+}
+export function reportVerification(report) {
+    const executions = verificationExecutions(report);
+    return {
+        summary: summarizeExecutions(report.commandPlan, executions),
+        commands: executions.map(toVerificationCommand)
+    };
+}
+export function withVerification(report) {
+    return {
+        ...report,
+        verification: reportVerification(report)
+    };
+}
+function toVerificationCommand(execution) {
+    return {
+        id: execution.id,
+        label: execution.label,
+        command: execution.command,
+        reason: execution.reason,
+        ecosystem: execution.ecosystem,
+        required: execution.required,
+        planned: execution.planned,
+        status: execution.status,
+        ...(execution.packageName ? { packageName: execution.packageName } : {}),
+        ...(execution.packagePath ? { packagePath: execution.packagePath } : {}),
+        ...(execution.exitCode !== undefined ? { exitCode: execution.exitCode } : {}),
+        ...(execution.durationMs !== undefined ? { durationMs: execution.durationMs } : {}),
+        ...(execution.timedOut !== undefined ? { timedOut: execution.timedOut } : {})
+    };
+}
+function statusFor(plan, result) {
+    if (!result)
+        return plan?.required ? "not-run" : "skipped-optional";
+    if (result.timedOut)
+        return "timed-out";
+    return result.exitCode === 0 ? "passed" : "failed";
+}
+//# sourceMappingURL=verification.js.map

package/dist/verification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.js","sourceRoot":"","sources":["../src/verification.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,sBAAsB,CAAC,MAA2D;IAChG,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACxF,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IACtE,MAAM,UAAU,GAA4B,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC1E,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxC,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,OAAO,EAAE,IAAI;YACb,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/E,GAAG,CAAC,MAAM,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxE,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC;SAChC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;QAC3C,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAAE,SAAS;QACxC,UAAU,CAAC,IAAI,CAAC;YACd,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,KAAK,EAAE,0BAA0B;YACjC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,MAAM,EAAE,2EAA2E;YACnF,SAAS,EAAE,SAAS;YACpB,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK;YACd,MAAM;YACN,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvE,MAAM,EAAE,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;SACrC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAA2D;IAC7F,MAAM,UAAU,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAClD,OAAO,mBAAmB,CAAC,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,mBAAmB,CAAC,WAA0B,EAAE,UAAmC;IAC1F,OAAO;QACL,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,MAAM;QACzE,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,MAAM;QAC1E,GAAG,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,MAAM;QAC9D,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,MAAM;QAClG,2EAA2E;QAC3E,mEAAmE;QACnE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,MAAM;QAClG,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,MAAM;QACtF,eAAe,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,MAAM;QACxF,eAAe,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,KAAK,kBAAkB,CAAC,CAAC,MAAM;QACjG,gBAAgB,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,MAAM;KAC9E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,SAAgC;IACvE,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;IACrD,IAAI,CAAC,SAAS,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC,MAAM,KAAK,kBAAkB,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,SAAS,CAAC;IACvG,IAAI,SAAS,CAAC,MAAM,CAAC,QAAQ;QAAE,OAAO,GAAG,MAAM,cAAc,SAAS,CAAC,MAAM,CAAC,QAAQ,GAAG,CAAC;IAC1F,IAAI,SAAS,CAAC,MAAM,CAAC,QAAQ,KAAK,CAAC;QAAE,OAAO,GAAG,MAAM,QAAQ,CAAC;IAC9D,OAAO,GAAG,MAAM,WAAW,SAAS,CAAC,MAAM,CAAC,QAAQ,GAAG,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAA2D;IAC5F,MAAM,UAAU,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAClD,OAAO;QACL,OAAO,EAAE,mBAAmB,CAAC,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC;QAC5D,QAAQ,EAAE,UAAU,CAAC,GAAG,CAAC,qBAAqB,CAAC;KAChD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAA8C,MAAS;IACrF,OAAO;QACL,GAAG,MAAM;QACT,YAAY,EAAE,kBAAkB,CAAC,MAAM,CAAC;KACzC,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAAC,SAAgC;IAC7D,OAAO;QACL,EAAE,EAAE,SAAS,CAAC,EAAE;QAChB,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,OAAO,EAAE,SAAS,CAAC,OAAO;QAC1B,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,SAAS,EAAE,SAAS,CAAC,SAAS;QAC9B,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,OAAO,EAAE,SAAS,CAAC,OAAO;QAC1B,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,GAAG,CAAC,SAAS,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,GAAG,CAAC,SAAS,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnF,GAAG,CAAC,SAAS,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9E,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,IAA6B,EAAE,MAAiC;IACjF,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC;IACpE,IAAI,MAAM,CAAC,QAAQ;QAAE,OAAO,WAAW,CAAC;IACxC,OAAO,MAAM,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrD,CAAC"}

package/docs/ANNOTATIONS.md

@@ -0,0 +1,34 @@
+# GitHub Actions Annotations
+
+PatchDrill can emit GitHub Actions workflow-command annotations for findings:
+
+```bash
+patchdrill scan --base origin/main --github-annotations
+```
+
+The composite Action enables annotations by default:
+
+```yaml
+- uses: seungdori/patchdrill@v0
+  with:
+    base: origin/${{ github.base_ref }}
+    annotations: "true"
+```
+
+`patchdrill init` writes this setting explicitly in the generated workflow so reviewers can see that Checks annotations are part of the default PR evidence.
+
+Set `annotations: "false"` to disable Checks annotations. The Action accepts `"true"`, `"false"`, `"1"`, `"0"`, `"yes"`, `"no"`, `"on"`, and `"off"` for boolean inputs.
+
+These annotations appear in the Actions log and Checks UI. They are meant for immediate review attention, while Markdown, JSON, SARIF, and HTML remain the durable artifacts.
+
+## Severity Mapping
+
+| PatchDrill | GitHub annotation |
+| --- | --- |
+| `critical` | `error` |
+| `high` | `error` |
+| `medium` | `warning` |
+| `low` | `notice` |
+| `info` | `notice` |
+
+File-scoped findings include file and line metadata when available. Global findings are emitted without a file property.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,79 @@
+# Architecture
+
+PatchDrill is split into deterministic modules:
+
+| Module | Responsibility |
+| --- | --- |
+| `src/baseline.ts` | Compares current reports with previous JSON baselines and computes risk deltas. |
+| `src/codeowners.ts` | Reads GitHub CODEOWNERS files and annotates changed files with owners. |
+| `src/command-plan.ts` | Normalizes verification command plans, deduplicates matching commands, and preserves required-command strength when policy and detectors overlap. |
+| `src/git.ts` | Reads changed files from git ranges, staged changes, unstaged changes, and untracked files. |
+| `src/policy.ts` | Loads `.patchdrill.yml/json`, filters ignored paths, and merges repo-specific commands/rules. |
+| `src/project.ts` | Discovers ecosystem signals, nested project roots, package managers, task runners, solution filters, Xcode containers, and workspace dependency graphs from manifests. |
+| `src/dependency.ts` | Extracts package.json, pyproject.toml, requirements.txt, NuGet PackageReference/PackageVersion, Maven pom.xml, Gradle build files and version catalogs, Gemfile, composer.json, go.mod, Cargo.toml, npm, pnpm, Yarn, Bun, Go, Cargo, Poetry, uv, Pipfile, Bundler, and Composer dependency additions, removals, and version updates through a parser/diff analyzer registry. |
+| `src/doctor.ts` | Renders first-run repository readiness diagnostics without mutating the repository or running verification commands. |
+| `src/markdown-links.ts` | Checks public README, docs, and example Markdown local links so launch documentation cannot drift silently. |
+| `src/package-scripts.ts` | Extracts package.json script additions, removals, and updates so risk scoring can distinguish dependency intent from executable package automation changes. |
+| `src/evidence.ts` | Renders and verifies Proof Pack evidence manifests with tool version, report metadata, artifact, and command-output digests. |
+| `src/planner.ts` | Turns changed files, workspace package impact, project signals, nested package scopes, and platform metadata into a verification command plan through ecosystem planner handlers. |
+| `src/risk.ts` | Scores the patch and emits explainable findings, including missing required verification evidence, dependency proof gaps, and whole-workflow GitHub Actions trust-boundary checks. |
+| `src/runner.ts` | Executes required commands when `--run` is set and optional commands when `--run-optional` is also set. |
+| `src/verification.ts` | Joins verification plans with command results into passed, failed, timed-out, not-run, skipped-optional, and unplanned execution states for human reports and JSON automation consumers. |
+| `src/release-readiness.ts` | Performs local static release-readiness checks for npm package metadata, action wiring, provenance workflow settings, public release docs, demo artifact synchronization, and local Markdown links. |
+| `src/report-contract.ts` | Verifies JSON report self-consistency, including summary counts derived from changed files, command plans, and command results. |
+| `src/report.ts` | Renders Markdown summaries, evaluates fail thresholds, and keeps the public report-renderer re-export surface stable. |
+| `src/report-annotations.ts` | Renders escaped GitHub Actions annotation commands from findings. |
+| `src/report-html.ts` | Renders the self-contained Proof Pack HTML dashboard and run-trend view. |
+| `src/report-sarif.ts` | Renders SARIF 2.1.0 output and stable finding fingerprints for GitHub code scanning. |
+| `src/schema.ts` | Exposes embedded JSON Schemas for policy, report, evidence, doctor, and release-check contracts. |
+| `src/scan.ts` | Orchestrates the scan pipeline. |
+| `src/stack-coverage.ts` | Defines the public fixture-backed stack coverage matrix used by launch docs and tests. |
+| `src/cli.ts` | Parses arguments and handles user output. |
+
+## Pipeline
+
+```text
+git diff -> changed files + added lines -> policy filters -> CODEOWNERS hints
+                       |                                      |
+                       v                                      v
+       project signals + affected packages -> verification command plan
+                       |
+                       v
+     dependency diff + package automation enrichment
+                                      |
+                                      v
+                           opt-in command runner
+                                      |
+                                      v
+     command plan + command results -> verification status matrix
+                                      |
+                                      v
+                         risk assessment -> baseline comparison
+                                      |
+                                      v
+                   Proof Pack: Markdown / JSON / SARIF / HTML / evidence
+                                      |
+                                      v
+             fail-on severity + max-risk + max-risk-delta gate
+```
+
+## Extension Seams
+
+- Dependency formats register a name, matcher, parser, diff function, and empty snapshot in `src/dependency.ts`, so adding a manifest or lockfile format does not grow the scan orchestrator and can be reflected in coverage docs.
+- Verification command adapters add plans through `src/command-plan.ts`, so duplicate detector and policy commands are normalized before running or scoring evidence gaps.
+- Report contract checks live in `src/report-contract.ts`, so evidence verification can reject a JSON report whose summary counts or computed verification status no longer match its payload.
+- Project and workspace detection lives in `src/project.ts`; command planning consumes those signals through the handler registry in `src/planner.ts`.
+- Risk scoring stays explainable: every score increase in `src/risk.ts` must produce a human-readable finding and a stable rule ID documented in [RULE_CATALOG.md](RULE_CATALOG.md).
+
+## Non-Goals
+
+- Replacing human code review.
+- Calling an LLM by default.
+- Running destructive commands.
+- Becoming a full SAST, SCA, or test selection platform.
+
+PatchDrill should stay useful as the small, deterministic layer before those heavier tools.
+
+## Security Posture
+
+The repository also includes CI, CodeQL, OpenSSF Scorecard, Dependabot, and package dry-run verification. See [SECURITY_POSTURE.md](SECURITY_POSTURE.md).

package/docs/BASELINES.md

@@ -0,0 +1,32 @@
+# Baselines
+
+PatchDrill can compare a scan against a previous JSON report.
+
+```bash
+patchdrill scan \
+  --baseline previous-patchdrill-report.json \
+  --max-risk-delta 0 \
+  --json patchdrill-report.json \
+  --markdown patchdrill-report.md
+```
+
+The report includes:
+
+- Previous and current assessment status.
+- Previous and current risk score.
+- Risk delta.
+- New, resolved, and unchanged finding counts.
+
+Findings are compared by deterministic fingerprints built from rule id, severity, title, file, and line. The comparison is local and does not upload source code or reports.
+
+Use `--max-risk-delta 0` to fail on any risk increase, or a higher value to allow small expected increases while blocking larger regressions.
+
+In GitHub Actions, pass the baseline path after downloading or restoring a previous report artifact:
+
+```yaml
+- uses: seungdori/patchdrill@v0
+  with:
+    baseline: previous-patchdrill-report.json
+    max-risk-delta: "0"
+    json: patchdrill-report.json
+```

package/docs/CASE_STUDIES.md

@@ -0,0 +1,106 @@
+# Case Studies
+
+These case studies are designed for launch readers who ask, "What does PatchDrill catch that a normal CI green check or model review might not make obvious?"
+
+They are representative and deterministic. Each one maps a patch shape to the Proof Pack evidence PatchDrill emits: risk findings, command plan, report artifacts, and evidence verification.
+
+## Risky Agent PR
+
+Artifact path: [examples/risky-agent-pr](../examples/risky-agent-pr)
+
+Patch shape:
+
+- Privileged `pull_request_target` workflow behavior.
+- PR-head checkout inside a privileged workflow.
+- Secret-looking environment example.
+- package.json lifecycle script addition.
+- Required verification commands that should be reviewed before merge.
+
+PatchDrill output:
+
+- Critical workflow trust-boundary finding.
+- Secret-looking value finding.
+- Package lifecycle script finding.
+- SARIF output for GitHub code scanning.
+- Compact PR summary for reviewers.
+- HTML dashboard for a self-contained Proof Pack.
+
+Why it matters:
+
+Traditional CI can pass while the workflow permission boundary becomes unsafe. PatchDrill makes that boundary visible before a reviewer has to manually audit every workflow line.
+
+## Review-Ready Proof Pack
+
+Artifact path: [examples/demo](../examples/demo)
+
+Patch shape:
+
+- Product source changes.
+- Workspace-scoped package impact.
+- Required and optional command plan.
+- No command failures.
+
+PatchDrill output:
+
+- Markdown report for human review.
+- JSON report for bots.
+- SARIF report for code scanning.
+- HTML dashboard.
+- Compact PR summary.
+
+Why it matters:
+
+This is the "normal" case: PatchDrill does not need to invent drama. It gives reviewers a stable bundle that says what changed, what should be tested, and what residual risk remains.
+
+## Dependency Proof Gap
+
+Patch shape:
+
+- Manifest dependency changed without a matching lockfile change.
+- Or lockfile resolution changed without a matching manifest intent.
+
+PatchDrill output:
+
+- Dependency diff table with package, section, before, and after.
+- Proof-gap finding that explains whether intent or resolution evidence is missing.
+- Command plan still derived from the touched ecosystem.
+
+Why it matters:
+
+SCA tools answer vulnerability questions. PatchDrill answers a reviewer question: "Does this dependency change include enough intent and resolution evidence to trust the patch?"
+
+## Package Script Tampering
+
+Patch shape:
+
+- A test/lint/build script is removed, replaced with a no-op, or weakened.
+- An install/prepare/pack/publish lifecycle hook is added.
+- A script pipes a remote download into a shell or interpreter.
+
+PatchDrill output:
+
+- Structured package script change summary.
+- Risk findings for lifecycle hooks, removed verification scripts, no-op checks, and remote shell pipes.
+- Human-readable remediation in Markdown and SARIF.
+
+Why it matters:
+
+AI-authored patches can make a PR look green by weakening the command that CI already trusts. PatchDrill treats the command definition itself as review evidence.
+
+## Workflow OIDC Boundary
+
+Patch shape:
+
+- GitHub Actions job grants OIDC permissions.
+- Remote reusable workflow receives inherited secrets or caller permissions.
+- Environment protection is absent or unclear.
+
+PatchDrill output:
+
+- Trust-boundary findings for OIDC, secrets inheritance, mutable reusable workflow refs, and privileged trigger combinations.
+- Local reusable workflow expansion for downstream analysis.
+- SARIF and annotation output for review surfaces.
+
+Why it matters:
+
+OIDC and reusable workflow changes are easy to miss in code review because the risky behavior can be spread across several workflow files. PatchDrill loads local reusable workflow references and reports the combined boundary.

package/docs/CODEOWNERS.md

@@ -0,0 +1,23 @@
+# CODEOWNERS
+
+PatchDrill reads GitHub CODEOWNERS files and adds owner hints to changed files in Markdown and JSON reports.
+
+Search order matches GitHub:
+
+- `.github/CODEOWNERS`
+- `CODEOWNERS`
+- `docs/CODEOWNERS`
+
+When multiple rules match a file, the last matching rule wins. A matching rule with no owners clears owners for that path, which mirrors common CODEOWNERS usage for subdirectory exceptions.
+
+## Supported Syntax
+
+PatchDrill supports the common GitHub CODEOWNERS subset:
+
+- `*`, `?`, and `**` wildcards.
+- Root-anchored patterns such as `/src/`.
+- Directory patterns such as `apps/`.
+- Inline comments after owner tokens.
+- GitHub users, teams, and email owners as raw strings.
+
+PatchDrill skips unsupported negation (`!`) and bracket range patterns (`[a-z]`), matching GitHub's documented CODEOWNERS limitations.