p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/github/commit-reachability.ts

@@ -0,0 +1,184 @@
+import type { GitHubClient } from "./client.js";
+import { parseGitHubRepoUrl } from "./base-branch.js";
+import { parsePrUrl } from "./pr-url.js";
+
+export interface CommitReachabilityResult {
+  reachable: boolean;
+  status: string;
+  aheadBy: number;
+  behindBy: number;
+  productionHeadSha: string;
+}
+
+export async function isCommitReachableFromBranch(
+  client: GitHubClient,
+  owner: string,
+  repo: string,
+  commitSha: string,
+  productionBranch: string,
+): Promise<CommitReachabilityResult> {
+  const branchRef = await client.getBranchRef(owner, repo, productionBranch);
+  const productionHeadSha = branchRef.object.sha;
+  const compare = await client.compareCommits(
+    owner,
+    repo,
+    commitSha,
+    productionHeadSha,
+  );
+
+  const reachable =
+    compare.behind_by === 0 && compare.status !== "diverged";
+
+  return {
+    reachable,
+    status: compare.status,
+    aheadBy: compare.ahead_by,
+    behindBy: compare.behind_by,
+    productionHeadSha,
+  };
+}
+
+export interface PromotionProofSuccess {
+  proof: true;
+  method: "merge_commit_sha" | "pr_merge_commit";
+  mergeCommitSha: string;
+  productionHeadSha: string;
+}
+
+export interface PromotionProofFailure {
+  proof: false;
+  reason: string;
+  diagnosticIssueKeyCommits?: string[];
+}
+
+export type PromotionProofResult = PromotionProofSuccess | PromotionProofFailure;
+
+export interface ResolvePromotionProofInput {
+  client: GitHubClient;
+  targetRepo: string;
+  productionBranch: string;
+  mergeCommitSha?: string | null;
+  prUrl?: string | null;
+  prNumber?: number | null;
+  issueKey?: string;
+  baseBranch?: string;
+}
+
+export async function resolvePromotionProof(
+  input: ResolvePromotionProofInput,
+): Promise<PromotionProofResult> {
+  const parsed = parseGitHubRepoUrl(input.targetRepo);
+  if (!parsed) {
+    return { proof: false, reason: "invalid_target_repo" };
+  }
+
+  const { owner, repo } = parsed;
+  let diagnosticIssueKeyCommits: string[] | undefined;
+
+  if (input.mergeCommitSha) {
+    const reachability = await isCommitReachableFromBranch(
+      input.client,
+      owner,
+      repo,
+      input.mergeCommitSha,
+      input.productionBranch,
+    );
+    if (reachability.reachable) {
+      return {
+        proof: true,
+        method: "merge_commit_sha",
+        mergeCommitSha: input.mergeCommitSha,
+        productionHeadSha: reachability.productionHeadSha,
+      };
+    }
+  }
+
+  let prMergeCommitSha: string | null = null;
+  if (input.prUrl) {
+    const parsedPr = parsePrUrl(input.prUrl);
+    if (parsedPr) {
+      const pull = await input.client.getPullRequest(
+        parsedPr.owner,
+        parsedPr.repo,
+        parsedPr.pullNumber,
+      );
+      prMergeCommitSha = pull.merge_commit_sha;
+    }
+  } else if (input.prNumber) {
+    const pull = await input.client.getPullRequest(owner, repo, input.prNumber);
+    prMergeCommitSha = pull.merge_commit_sha;
+  }
+
+  if (prMergeCommitSha) {
+    const reachability = await isCommitReachableFromBranch(
+      input.client,
+      owner,
+      repo,
+      prMergeCommitSha,
+      input.productionBranch,
+    );
+    if (reachability.reachable) {
+      return {
+        proof: true,
+        method: "pr_merge_commit",
+        mergeCommitSha: prMergeCommitSha,
+        productionHeadSha: reachability.productionHeadSha,
+      };
+    }
+  }
+
+  if (input.issueKey) {
+    diagnosticIssueKeyCommits = await findIssueKeyCommitsOnProduction(
+      input.client,
+      owner,
+      repo,
+      input.productionBranch,
+      input.issueKey,
+      input.baseBranch,
+    );
+  }
+
+  return {
+    proof: false,
+    reason: "production_not_promoted",
+    diagnosticIssueKeyCommits,
+  };
+}
+
+export async function findIssueKeyCommitsOnProduction(
+  client: GitHubClient,
+  owner: string,
+  repo: string,
+  productionBranch: string,
+  issueKey: string,
+  baseBranch?: string,
+): Promise<string[]> {
+  const branchRef = await client.getBranchRef(owner, repo, productionBranch);
+  const productionHeadSha = branchRef.object.sha;
+
+  let compareBase = productionHeadSha;
+  if (baseBranch) {
+    try {
+      const baseRef = await client.getBranchRef(owner, repo, baseBranch);
+      compareBase = baseRef.object.sha;
+    } catch {
+      compareBase = productionHeadSha;
+    }
+  }
+
+  const compare = await client.compareCommits(
+    owner,
+    repo,
+    compareBase,
+    productionHeadSha,
+  );
+
+  const pattern = new RegExp(
+    issueKey.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+    "i",
+  );
+
+  return compare.commits
+    .filter((commit) => pattern.test(commit.commit.message))
+    .map((commit) => commit.sha);
+}

package/workspace-snapshot/files/src/github/links.ts

@@ -0,0 +1,23 @@
+import { parsePrUrl } from "./pr-url.js";
+
+export function parsePullRequestNumber(prUrl: string): number | null {
+  return parsePrUrl(prUrl)?.pullNumber ?? null;
+}
+
+export function formatPullRequestLink(prUrl: string): string {
+  const number = parsePullRequestNumber(prUrl);
+  const label = number ? `Pull request #${number}` : "Pull request";
+  return `[${label}](${prUrl})`;
+}
+
+export function formatCommitLink(
+  targetRepo: string,
+  mergeCommitSha: string,
+): string {
+  const normalized = targetRepo.replace(/\/$/, "");
+  return `[Merge commit](${normalized}/commit/${mergeCommitSha})`;
+}
+
+export function formatMarkdownLink(label: string, url: string): string {
+  return `[${label}](${url})`;
+}

package/workspace-snapshot/files/src/github/merge-result.ts

@@ -0,0 +1,31 @@
+import { GitHubApiError } from "./client.js";
+
+export interface GitHubMergeResponse {
+  sha: string;
+  merged: boolean;
+  message?: string;
+}
+
+export function classifyMergeError(
+  error: unknown,
+): "github_auth_failure" | "github_merge_failure" | "pr_already_merged" {
+  if (error instanceof GitHubApiError) {
+    if (error.status === 401) {
+      return "github_auth_failure";
+    }
+    if (error.status === 409) {
+      return "pr_already_merged";
+    }
+    if (error.status === 405) {
+      const message = error.message.toLowerCase();
+      if (message.includes("already been merged") || message.includes("already merged")) {
+        return "pr_already_merged";
+      }
+    }
+  }
+  return "github_merge_failure";
+}
+
+export function isAlreadyMergedError(error: unknown): boolean {
+  return classifyMergeError(error) === "pr_already_merged";
+}

package/workspace-snapshot/files/src/github/pr-discovery.ts

@@ -0,0 +1,55 @@
+import type { GitHubClient } from "./client.js";
+import { parseGitHubRepoUrl } from "./base-branch.js";
+
+export interface DiscoveredPullRequest {
+  prUrl: string;
+  prNumber: number;
+  branch: string;
+  headSha: string;
+  baseBranch: string;
+}
+
+export function buildIssueKeyBranchPattern(issueKey: string): RegExp {
+  const normalized = issueKey.trim().toLowerCase();
+  return new RegExp(`(^|[/-])${normalized.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([/-]|$)`, "i");
+}
+
+export function headBranchMatchesIssueKey(headRef: string, issueKey: string): boolean {
+  return buildIssueKeyBranchPattern(issueKey).test(headRef);
+}
+
+export async function findImplementationPullRequest(
+  client: GitHubClient,
+  targetRepo: string,
+  baseBranch: string,
+  issueKey: string,
+): Promise<DiscoveredPullRequest | null> {
+  const parsed = parseGitHubRepoUrl(targetRepo);
+  if (!parsed) {
+    return null;
+  }
+
+  const pulls = await client.listPullRequests(parsed.owner, parsed.repo, {
+    state: "open",
+    base: baseBranch,
+    sort: "created",
+    direction: "desc",
+  });
+
+  const matching = pulls.filter((pull) =>
+    headBranchMatchesIssueKey(pull.head.ref, issueKey),
+  );
+
+  if (matching.length === 0) {
+    return null;
+  }
+
+  const selected = matching[0];
+  return {
+    prUrl: selected.html_url,
+    prNumber: selected.number,
+    branch: selected.head.ref,
+    headSha: selected.head.sha,
+    baseBranch: selected.base.ref,
+  };
+}

package/workspace-snapshot/files/src/github/pr-inspector.ts

@@ -0,0 +1,297 @@
+import { repoUrlsEquivalent } from "../resolver/normalize-repo.js";
+import type { GitHubClient, GitHubCheckRun, GitHubCommitStatus } from "./client.js";
+import { GitHubApiError } from "./client.js";
+import type { ParsedPrUrl } from "./pr-url.js";
+
+export interface PrChangedFile {
+  path: string;
+  status: string;
+}
+
+export interface PrCheckInfo {
+  name: string;
+  status: string;
+  conclusion: string | null;
+  detailsUrl: string | null;
+}
+
+export interface PrInspectionResult {
+  title: string;
+  url: string;
+  branch: string;
+  /** Live PR branch head commit; use for check lookup and guarded merge. */
+  headSha: string;
+  baseBranch: string;
+  state: string;
+  merged: boolean;
+  isDraft: boolean;
+  mergeable: boolean | null;
+  mergeableState: string | null;
+  rebaseable: boolean | null;
+  /** Merge-result metadata only (synthetic test-merge on open PRs, merge commit when merged). */
+  mergeCommitSha: string | null;
+  mergedAt: string | null;
+  repoUrl: string;
+  changedFiles: PrChangedFile[];
+  checks: PrCheckInfo[];
+  checkSummary: string;
+  comments: { author: string; body: string; createdAt: string }[];
+  rawChecks: GitHubCheckRun[] | null;
+}
+
+function summarizeChecks(checks: PrCheckInfo[]): string {
+  if (checks.length === 0) {
+    return "No GitHub check runs reported for the PR head commit.";
+  }
+
+  const passed = checks.filter((c) => c.conclusion === "success").length;
+  const failed = checks.filter(
+    (c) => c.conclusion === "failure" || c.conclusion === "cancelled",
+  ).length;
+  const pending = checks.filter(
+    (c) => c.status !== "completed" || c.conclusion === null,
+  ).length;
+
+  const lines = [
+    `- Passed: ${passed}`,
+    `- Failed: ${failed}`,
+    `- Pending/unknown: ${pending}`,
+  ];
+
+  const notableFailures = checks.filter((c) => c.conclusion === "failure");
+  for (const check of notableFailures.slice(0, 5)) {
+    lines.push(`- Failed check: ${check.name}${check.detailsUrl ? ` (${check.detailsUrl})` : ""}`);
+  }
+
+  return lines.join("\n");
+}
+
+function mapCommitStatusToCheck(status: GitHubCommitStatus): PrCheckInfo {
+  const state = status.state.toLowerCase();
+  let conclusion: string | null = null;
+  let checkStatus = "completed";
+
+  if (state === "success") {
+    conclusion = "success";
+  } else if (state === "pending") {
+    conclusion = null;
+    checkStatus = "queued";
+  } else if (state === "failure" || state === "error") {
+    conclusion = "failure";
+  } else {
+    conclusion = state;
+  }
+
+  return {
+    name: status.context,
+    status: checkStatus,
+    conclusion,
+    detailsUrl: status.target_url,
+  };
+}
+
+function checksFromCombinedStatus(
+  combined: { state: string; statuses: GitHubCommitStatus[] },
+): PrCheckInfo[] {
+  if (combined.statuses.length > 0) {
+    return combined.statuses.map(mapCommitStatusToCheck);
+  }
+
+  const state = combined.state.toLowerCase();
+  if (state === "pending") {
+    return [
+      {
+        name: "combined-status",
+        status: "queued",
+        conclusion: null,
+        detailsUrl: null,
+      },
+    ];
+  }
+
+  return [
+    {
+      name: "combined-status",
+      status: "completed",
+      conclusion: state === "success" ? "success" : "failure",
+      detailsUrl: null,
+    },
+  ];
+}
+
+export async function inspectPullRequest(
+  client: GitHubClient,
+  parsed: ParsedPrUrl,
+  expectedTargetRepo: string,
+): Promise<PrInspectionResult> {
+  const result = await inspectPullRequestRaw(client, parsed, expectedTargetRepo);
+  if (result.state !== "open" || result.merged) {
+    throw new Error(`pr_closed: PR ${result.url} is not open`);
+  }
+  return result;
+}
+
+export async function inspectPullRequestForMerge(
+  client: GitHubClient,
+  parsed: ParsedPrUrl,
+  expectedTargetRepo: string,
+): Promise<PrInspectionResult> {
+  const result = await inspectPullRequestRaw(client, parsed, expectedTargetRepo);
+  if (result.merged) {
+    return result;
+  }
+  if (result.state !== "open") {
+    throw new Error(`pr_closed: PR ${result.url} is closed but not merged`);
+  }
+  return result;
+}
+
+export async function inspectPullRequestPostMerge(
+  client: GitHubClient,
+  parsed: ParsedPrUrl,
+  expectedTargetRepo: string,
+): Promise<PrInspectionResult> {
+  const result = await inspectPullRequestRaw(client, parsed, expectedTargetRepo);
+  if (!result.merged) {
+    throw new Error(`pr_not_merged: PR ${result.url} is not merged`);
+  }
+  return result;
+}
+
+export async function pollPullRequestMergeability(
+  client: GitHubClient,
+  parsed: ParsedPrUrl,
+  expectedTargetRepo: string,
+  options: {
+    timeoutSeconds: number;
+    intervalSeconds: number;
+  },
+): Promise<PrInspectionResult> {
+  const deadline = Date.now() + options.timeoutSeconds * 1000;
+  let latest = await inspectPullRequestForMerge(client, parsed, expectedTargetRepo);
+
+  while (Date.now() < deadline) {
+    const state = latest.mergeableState?.toLowerCase() ?? null;
+    if (latest.mergeable !== null && state !== "unknown") {
+      return latest;
+    }
+    await new Promise((resolve) => setTimeout(resolve, options.intervalSeconds * 1000));
+    latest = await inspectPullRequestForMerge(client, parsed, expectedTargetRepo);
+  }
+
+  return latest;
+}
+
+async function inspectPullRequestRaw(
+  client: GitHubClient,
+  parsed: ParsedPrUrl,
+  expectedTargetRepo: string,
+): Promise<PrInspectionResult> {
+  if (!repoUrlsEquivalent(parsed.repoUrl, expectedTargetRepo)) {
+    throw new Error(
+      `wrong_target_repo: PR repo ${parsed.repoUrl} does not match expected ${expectedTargetRepo}`,
+    );
+  }
+
+  let pull;
+  try {
+    pull = await client.getPullRequest(parsed.owner, parsed.repo, parsed.pullNumber);
+  } catch (error) {
+    if (error instanceof GitHubApiError && error.status === 401) {
+      throw error;
+    }
+    throw error;
+  }
+
+  let files: { filename: string; status: string }[] = [];
+  if (!pull.merged) {
+    files = await client.getPullRequestFiles(
+      parsed.owner,
+      parsed.repo,
+      parsed.pullNumber,
+    );
+  }
+
+  // merge_commit_sha is merge-result metadata (synthetic test-merge on open PRs).
+  // Never use it for check/status lookup or as headSha identity.
+  const checkRefSha = pull.head.sha;
+
+  let rawChecks: GitHubCheckRun[] | null = null;
+  let checks: PrCheckInfo[] = [];
+  try {
+    const checkPayload = await client.getCheckRunsForRef(
+      parsed.owner,
+      parsed.repo,
+      checkRefSha,
+    );
+    rawChecks = checkPayload.check_runs ?? [];
+    checks = rawChecks.map((run) => ({
+      name: run.name,
+      status: run.status,
+      conclusion: run.conclusion,
+      detailsUrl: run.details_url,
+    }));
+  } catch {
+    rawChecks = null;
+    checks = [];
+  }
+
+  if (checks.length === 0) {
+    try {
+      const combined = await client.getCombinedStatusForRef(
+        parsed.owner,
+        parsed.repo,
+        checkRefSha,
+      );
+      checks = checksFromCombinedStatus(combined);
+    } catch {
+      // Keep empty checks if combined status is unavailable.
+    }
+  }
+
+  const commentsRaw = await client.getIssueComments(
+    parsed.owner,
+    parsed.repo,
+    parsed.pullNumber,
+  );
+
+  const comments = commentsRaw.map((comment) => ({
+    author: comment.user?.login ?? "unknown",
+    body: comment.body,
+    createdAt: comment.created_at,
+  }));
+
+  const changedFiles = files.map((file) => ({
+    path: file.filename,
+    status: file.status,
+  }));
+
+  return {
+    title: pull.title,
+    url: pull.html_url,
+    branch: pull.head.ref,
+    headSha: pull.head.sha,
+    baseBranch: pull.base.ref,
+    state: pull.state,
+    merged: pull.merged,
+    isDraft: pull.draft === true,
+    mergeable: pull.mergeable ?? null,
+    mergeableState: pull.mergeable_state ?? null,
+    rebaseable: pull.rebaseable ?? null,
+    mergeCommitSha: pull.merge_commit_sha,
+    mergedAt: pull.merged_at,
+    repoUrl: parsed.repoUrl,
+    changedFiles,
+    checks,
+    checkSummary: summarizeChecks(checks),
+    comments,
+    rawChecks,
+  };
+}
+
+export function classifyGitHubError(error: unknown): "github_auth_failure" | "github_api_failure" {
+  if (error instanceof GitHubApiError && error.status === 401) {
+    return "github_auth_failure";
+  }
+  return "github_api_failure";
+}

package/workspace-snapshot/files/src/github/pr-url.ts

@@ -0,0 +1,23 @@
+export interface ParsedPrUrl {
+  owner: string;
+  repo: string;
+  pullNumber: number;
+  repoUrl: string;
+}
+
+export function parsePrUrl(prUrl: string): ParsedPrUrl | null {
+  const match = prUrl.trim().match(
+    /^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/pull\/(\d+)\/?$/,
+  );
+  if (!match) {
+    return null;
+  }
+  const owner = match[1];
+  const repo = match[2];
+  return {
+    owner,
+    repo,
+    pullNumber: Number.parseInt(match[3], 10),
+    repoUrl: `https://github.com/${owner}/${repo}`,
+  };
+}