@zephyrdeng/pi-review 0.19.0 → 0.20.1

package/dist/verify.d.ts

@@ -0,0 +1,172 @@
+import { stepExecuted } from "./meta-footer.js";
+import type { ParsedArgs, SplitPayload, VerificationApproval, VerificationStepResult, VerificationSummary } from "./types.js";
+export declare const VERIFY_CONFIG_FILE = ".pi-review.json";
+export declare const DEFAULT_STEP_TIMEOUT_SEC = 300;
+export declare const MAX_STEP_TIMEOUT_SEC = 1800;
+export declare const OUTPUT_TAIL_LIMIT = 4000;
+export declare const DEFAULT_MAX_FOLLOW_UP_ROUNDS = 1;
+export interface PlanFile {
+    path: string;
+    content: string;
+}
+export interface PlanStep {
+    id: string;
+    argv: string[];
+    purpose: string;
+    cwd?: string;
+    expectedDurationSec?: number;
+    sideEffects?: string;
+    idempotent?: boolean;
+    isolated?: boolean;
+    timeoutSec?: number;
+    round?: number;
+    files?: PlanFile[];
+}
+export interface VerificationPlan {
+    version: 1;
+    proposer?: "host" | "pi";
+    summary?: string;
+    steps: PlanStep[];
+}
+export interface WhitelistCommand {
+    id: string;
+    argv: string[];
+    timeoutSec?: number;
+}
+export interface VerifyRepoConfig {
+    commands: WhitelistCommand[];
+    link: string[];
+    maxFollowUpRounds: number;
+}
+export interface ApprovalDecision {
+    id: string;
+    stepSha256: string;
+    /** What the step executes (argv, cwd, files); absent in older records, which stay id-scoped. */
+    commandSha256?: string;
+    decision: "approved" | "rejected";
+}
+export interface ApprovalRecord {
+    version: 1;
+    planSha256: string;
+    approvedBy?: string;
+    approvedAt?: string;
+    decisions: ApprovalDecision[];
+}
+/** Invalid plan / approval / config input (a usage problem, not a run failure). */
+export declare class VerifyInputError extends Error {
+    constructor(message: string);
+}
+export declare function sha256(text: string): string;
+/** Content hash an approval binds to; any edit to the step changes it. */
+export declare function stepSha256(step: PlanStep): string;
+/**
+ * Execution identity: what the step runs (argv, cwd, files), without its id or
+ * description. A human rejection binds to it, so re-proposing the same command
+ * under a new id or new wording is still rejected.
+ */
+export declare function commandSha256(step: Pick<PlanStep, "argv" | "cwd" | "files">): string;
+export declare function planSha256(plan: VerificationPlan): string;
+/** A relative path that stays inside its root (no absolute paths, no `..`). */
+export declare function isSafeRelativePath(value: unknown): value is string;
+/** Validate a plan object. Throws VerifyInputError with the first problem found. */
+export declare function parsePlan(raw: unknown, maxFollowUpRounds?: number): VerificationPlan;
+/** Parse `.pi-review.json` text. Only the `verify` key is read. */
+export declare function parseRepoConfig(text: string): VerifyRepoConfig;
+export declare function parseApproval(raw: unknown): ApprovalRecord;
+/** Build an approval record for the plan's current content. */
+export declare function createApproval(plan: VerificationPlan, options: {
+    all?: boolean;
+    approve?: string[];
+    reject?: string[];
+    by?: string;
+    now?: Date;
+}): ApprovalRecord;
+export interface ResolvedStep {
+    step: PlanStep;
+    origin: "whitelist" | "plan";
+    approval: VerificationApproval;
+    sha: string;
+    /** Effective timeout: the step's own, else the matching whitelist entry's. */
+    timeoutSec?: number;
+}
+/**
+ * Decide which steps may run. Without a plan, every whitelist command runs.
+ * With a plan: a rejection of this exact step, or of the same command under
+ * any id or wording (commandSha256), wins; a rejection recorded for a
+ * different version of the step makes it `stale` (never whitelist pre-approved);
+ * then exact-argv whitelist matches (no files, no cwd) are pre-approved; then a
+ * matching approval; any other decision for the same id is `stale`.
+ */
+export declare function resolveSteps(plan: VerificationPlan | undefined, config: VerifyRepoConfig, approvals: ApprovalRecord[]): ResolvedStep[];
+export declare function isRunnable(approval: VerificationApproval): boolean;
+/** Effective per-step timeout: own or whitelist budget, else the default, capped at the maximum. */
+export declare function effectiveTimeoutSec(resolved: Pick<ResolvedStep, "timeoutSec">): number;
+export { stepExecuted };
+/** Overall status from step outcomes (tree guard and setup errors are applied by the caller). */
+export declare function overallStatus(steps: VerificationStepResult[]): VerificationSummary["status"];
+/** Minimal environment for verification commands: allowlist minus anything secret-shaped. */
+export declare function verificationEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export interface CommandResult {
+    exitCode: number | null;
+    signal?: string;
+    timedOut: boolean;
+    durationMs: number;
+    outputTail: string;
+    truncated: boolean;
+    error?: string;
+    /** Informational; never changes the step status (e.g. output may be incomplete). */
+    note?: string;
+}
+/** Run argv without a shell in its own process group, with a timeout and a bounded output tail. */
+export declare function runCommand(argv: string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    outputLimit?: number;
+}): Promise<CommandResult>;
+/** Porcelain status of the original tree, compared before/after verification. */
+export declare function gitStatusSnapshot(repoRoot: string): string;
+/** Read the standing whitelist from HEAD; uncommitted edits never grant pre-approval. */
+export declare function loadRepoConfig(repoRoot: string): VerifyRepoConfig;
+/** Resolve `rel` inside `root`, refusing paths that escape it (including through symlinks). */
+export declare function resolveInside(root: string, rel: string): string;
+export interface IsolatedCopy {
+    dir: string;
+    cleanup: () => void;
+}
+/**
+ * Snapshot HEAD + tracked changes + untracked non-ignored files through a
+ * throwaway index (the real index, tree, and stash stay untouched), then
+ * check it out as a detached worktree with hooks disabled.
+ */
+export declare function createIsolatedCopy(repoRoot: string, link?: string[], base?: string): IsolatedCopy;
+export interface RunVerificationOptions {
+    cwd: string;
+    planFile?: string;
+    approvalFiles?: string[];
+    env?: NodeJS.ProcessEnv;
+    onLog?: (line: string) => void;
+    /** Test seam: override the per-step output tail size. */
+    outputLimit?: number;
+}
+/**
+ * Run verification once. Never throws: every setup problem degrades to
+ * `status: "unverified"` with a reason so the review still runs and says so.
+ */
+export declare function runVerification(options: RunVerificationOptions): Promise<VerificationSummary>;
+/** Reviewer-prompt section carrying the shared verification evidence. */
+export declare function formatVerificationSection(summary: VerificationSummary): string;
+/**
+ * Evidence applies only to targets in the verified repository at the verified
+ * HEAD. A target in another repository (or none), or a HEAD that moved since
+ * the snapshot, degrades the summary to `unverified` with the reason.
+ * `cwd` is always checked, so a text-only target still catches a moved HEAD.
+ */
+export declare function bindVerificationToTargets(summary: VerificationSummary, targets: string[], cwd?: string): VerificationSummary;
+/** Review targets (file refs and path targets) that evidence must match. */
+export declare function payloadTargets(payload: Pick<SplitPayload, "fileRefs" | "attachableFileRefs" | "pathTargets">): string[];
+/** Run verification for a review/loop round when it was requested; undefined otherwise. */
+export declare function verificationForReview(parsed: Pick<ParsedArgs, "verify" | "verifyPlan" | "verifyApprovals">, quiet?: boolean, targets?: string[]): Promise<VerificationSummary | undefined>;
+/** Append the shared verification section to a reviewer prompt (identity when verification is off). */
+export declare function withVerificationSection(prompt: string, summary: VerificationSummary | undefined): string;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

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