@davidvornholt/standards 0.10.2 → 0.11.1

package/src/poller-review-publication.ts

@@ -0,0 +1,153 @@
+import type { ClaimBinding } from './poller-claim';
+import type { PullRequest } from './poller-github-pulls';
+import { failJob, type JobDeps, type JobLabels } from './poller-job-shared';
+import {
+  changedWorkspaceQualityManifests,
+  lockedPathsOf,
+} from './poller-protected-paths';
+import { forbiddenDiffPaths, type ReviewOutcome } from './poller-protocol';
+import { publishReviewArtifacts } from './poller-review-artifacts';
+import {
+  type ReviewPublicationPlan,
+  readSealedReviewPlan,
+  reviewOutputBranch,
+  sealReviewPlan,
+} from './poller-review-output';
+import { publishReviewPlan, validateReviewClaim } from './poller-review-state';
+import { validateSealedReviewOutput } from './poller-review-validation';
+import {
+  changedPaths,
+  commitCount,
+  headSha,
+  localBranchExists,
+  pushBranch,
+} from './poller-workspace';
+
+const outputBranchFor = (plan: ReviewPublicationPlan): string =>
+  reviewOutputBranch(plan);
+
+export const resumeReviewedJob = async (options: {
+  readonly deps: JobDeps;
+  readonly labels: JobLabels;
+  readonly pr: PullRequest;
+  readonly claim: ClaimBinding;
+  readonly plan: ReviewPublicationPlan;
+  readonly cloneDir: string;
+}): Promise<string> => {
+  const { deps, labels, pr, claim, plan, cloneDir } = options;
+  if (claim.approval.id !== plan.approvalId) {
+    throw new Error('publication blocked: review plan approval changed');
+  }
+  const outputBranch = outputBranchFor(plan);
+  const sealed = readSealedReviewPlan(cloneDir, outputBranch);
+  if (sealed === null) {
+    const detail = localBranchExists(cloneDir, outputBranch)
+      ? 'is not valid sealed review output'
+      : 'is missing';
+    throw new Error(`publication blocked: ${outputBranch} ${detail}`);
+  }
+  if (JSON.stringify(sealed) !== JSON.stringify(plan)) {
+    throw new Error('publication blocked: sealed review plan changed');
+  }
+  await validateSealedReviewOutput({ deps, pr, plan, cloneDir });
+  if (pr.headSha === plan.approvedHead && plan.publishedHead !== pr.headSha) {
+    await validateReviewClaim({
+      deps,
+      pr,
+      claim,
+      plan,
+      expectedHead: plan.approvedHead,
+      requireDraft: true,
+    });
+    pushBranch(cloneDir, {
+      repo: deps.repo,
+      branch: pr.headRef,
+      token: deps.token,
+      sourceRef: plan.publishedHead,
+      expectedRemoteSha: plan.approvedHead,
+    });
+  }
+  await validateReviewClaim({
+    deps,
+    pr,
+    claim,
+    plan,
+    expectedHead: plan.publishedHead,
+    requireDraft: false,
+  });
+  return publishReviewArtifacts({ deps, labels, pr, claim, plan });
+};
+
+export const finishReviewedJob = async (options: {
+  readonly deps: JobDeps;
+  readonly labels: JobLabels;
+  readonly pr: PullRequest;
+  readonly claim: ClaimBinding;
+  readonly workDir: string;
+  readonly outcome: ReviewOutcome;
+}): Promise<string> => {
+  const { deps, labels, pr, claim, workDir, outcome } = options;
+  const commits = commitCount(workDir, pr.headSha);
+  const paths = commits > 0 ? changedPaths(workDir, pr.headSha) : [];
+  const forbidden = [
+    ...forbiddenDiffPaths(paths, await lockedPathsOf(workDir)),
+    ...changedWorkspaceQualityManifests(workDir, pr.headSha, paths),
+  ];
+  if (forbidden.length > 0) {
+    await failJob(
+      deps,
+      labels,
+      pr.number,
+      `review fixes modified protected paths:\n${forbidden.map((path) => `- ${path}`).join('\n')}`,
+    );
+    return `PR #${pr.number}: failed (protected paths)`;
+  }
+  const plan: ReviewPublicationPlan = {
+    repo: deps.repo,
+    prNumber: pr.number,
+    approvalId: claim.approval.id,
+    approvedHead: pr.headSha,
+    publishedHead: headSha(workDir),
+    baseRef: pr.baseRef,
+    baseSha: pr.baseSha,
+    report: outcome.report ?? '',
+    commits,
+    deferred: outcome.deferred ?? [],
+  };
+  const outputBranch = outputBranchFor(plan);
+  const sealedHead = sealReviewPlan(workDir, plan);
+  pushBranch(workDir, {
+    repo: deps.repo,
+    branch: outputBranch,
+    token: deps.token,
+    expectedRemoteSha: '',
+    sourceRef: sealedHead,
+  });
+  await publishReviewPlan(deps, pr, claim, plan);
+  if (commits > 0) {
+    await validateReviewClaim({
+      deps,
+      pr,
+      claim,
+      plan,
+      expectedHead: plan.approvedHead,
+      requireDraft: true,
+    });
+    pushBranch(workDir, {
+      repo: deps.repo,
+      branch: pr.headRef,
+      token: deps.token,
+      sourceRef: plan.publishedHead,
+      expectedRemoteSha: plan.approvedHead,
+    });
+  }
+  await validateReviewClaim({
+    deps,
+    pr,
+    claim,
+    plan,
+    expectedHead: plan.publishedHead,
+    requireDraft: true,
+  });
+  return publishReviewArtifacts({ deps, labels, pr, claim, plan });
+};

package/src/poller-review-run.ts

@@ -0,0 +1,160 @@
+// One review job: a maintainer-approved draft PR gets a full review-fix
+// cycle — lens fan-out inside the Codex run, fixes as new commits — then the
+// poller posts the report, files deferred findings as issues, and flips the
+// PR to ready. GitHub writes stay in deterministic poller code; the agent
+// never holds credentials.
+
+import { prRevision } from './poller-approval';
+import { acquireClaim } from './poller-claim';
+import { getIssue, type IssueItem } from './poller-github';
+import { getPullRequest } from './poller-github-pulls';
+import { addLabels } from './poller-github-write';
+import {
+  failJob,
+  type JobDeps,
+  type JobLabels,
+  type JobResult,
+  jobPreamble,
+} from './poller-job-shared';
+import {
+  APPROVED_FOR_REVIEW,
+  REVIEW_FAILED,
+  REVIEW_IN_PROGRESS,
+} from './poller-protocol';
+import { executeReviewJob } from './poller-review-execution';
+import {
+  readSealedReviewPlan,
+  reviewOutputBranch,
+} from './poller-review-output';
+import { resumeReviewedJob } from './poller-review-publication';
+import { publishReviewPlan, readReviewPlan } from './poller-review-state';
+import { ensureCacheClone, localBranchExists } from './poller-workspace';
+
+const REVIEW_LABELS: JobLabels = {
+  approved: APPROVED_FOR_REVIEW,
+  inProgress: REVIEW_IN_PROGRESS,
+  failed: REVIEW_FAILED,
+};
+
+const currentReviewPlan = readReviewPlan;
+
+const hasInvalidLocalOutput = (
+  plan: Awaited<ReturnType<typeof readReviewPlan>>,
+  sealed: ReturnType<typeof readSealedReviewPlan>,
+  cloneDir: string,
+  branch: string,
+): boolean =>
+  plan === null && sealed === null && localBranchExists(cloneDir, branch);
+
+export const runReviewJob = async (
+  deps: JobDeps,
+  prItem: IssueItem,
+  allowCodex = true,
+): Promise<JobResult> => {
+  const { config, token, repo } = deps;
+  const pr = await getPullRequest(token, repo, prItem.number);
+  let plan = await currentReviewPlan(deps, pr);
+  const currentItem = await getIssue(token, repo, prItem.number);
+  const preamble = await jobPreamble(
+    deps,
+    currentItem,
+    REVIEW_LABELS,
+    prRevision(pr.baseRef, pr.baseSha, plan?.approvedHead ?? pr.headSha),
+  );
+  if (preamble.kind === 'rejected') {
+    return {
+      lines: [`PR #${prItem.number}: approval rejected`],
+      ranCodex: false,
+    };
+  }
+  if (preamble.kind === 'waiting') {
+    return {
+      lines: [`PR #${prItem.number}: waiting on an answer`],
+      ranCodex: false,
+    };
+  }
+  if (!pr.draft && plan === null) {
+    await failJob(
+      deps,
+      REVIEW_LABELS,
+      pr.number,
+      'automated review requires a draft PR',
+    );
+    return {
+      lines: [`PR #${pr.number}: rejected (not draft)`],
+      ranCodex: false,
+    };
+  }
+  // Fork PRs are out of scope: their head branch lives in a repository the
+  // poller must not push to, and pushing a same-named branch to the base repo
+  // would fake a review. Fail explicitly instead of pretending.
+  if (pr.headRepo !== repo) {
+    await failJob(
+      deps,
+      REVIEW_LABELS,
+      pr.number,
+      `this PR's head branch lives in ${pr.headRepo || 'an unknown repository'}; automated review runs only support same-repository branches`,
+    );
+    return {
+      lines: [`PR #${pr.number}: rejected (fork head)`],
+      ranCodex: false,
+    };
+  }
+  const cacheClone = ensureCacheClone(config.cacheDir, repo, token);
+  const outputBranch = reviewOutputBranch({
+    repo,
+    prNumber: pr.number,
+    baseSha: pr.baseSha,
+    approvedHead: plan?.approvedHead ?? pr.headSha,
+    approvalId: preamble.approval.id,
+  });
+  const sealed = readSealedReviewPlan(cacheClone, outputBranch);
+  if (hasInvalidLocalOutput(plan, sealed, cacheClone, outputBranch)) {
+    throw new Error(`sealed output on ${outputBranch} is invalid`);
+  }
+  if (plan === null && sealed === null && !allowCodex) {
+    return {
+      lines: [`PR #${pr.number}: waiting for run capacity`],
+      ranCodex: false,
+    };
+  }
+  await addLabels(token, repo, prItem.number, [REVIEW_IN_PROGRESS]);
+  const claim = await acquireClaim(
+    { token, repo, issueNumber: pr.number },
+    preamble.approval,
+    REVIEW_IN_PROGRESS,
+  );
+  if (claim === null) {
+    return {
+      lines: [`PR #${pr.number}: another poller owns the claim`],
+      ranCodex: false,
+    };
+  }
+  if (plan === null && sealed !== null) {
+    await publishReviewPlan(deps, pr, claim, sealed);
+    plan = sealed;
+  }
+  if (plan !== null) {
+    return {
+      lines: [
+        await resumeReviewedJob({
+          deps,
+          labels: REVIEW_LABELS,
+          pr,
+          claim,
+          plan,
+          cloneDir: cacheClone,
+        }),
+      ],
+      ranCodex: false,
+    };
+  }
+  return executeReviewJob({
+    deps,
+    labels: REVIEW_LABELS,
+    pr,
+    claim,
+    cacheClone,
+    answers: preamble.answers,
+  });
+};

package/src/poller-review-state.ts

@@ -0,0 +1,126 @@
+import { prRevision, readApprovalBinding } from './poller-approval';
+import { type ClaimBinding, validateClaim } from './poller-claim';
+import { collaboratorRole, listIssueComments } from './poller-github';
+import { getPullRequest, type PullRequest } from './poller-github-pulls';
+import { createComment } from './poller-github-write';
+import type { JobDeps } from './poller-job-shared';
+import { APPROVED_FOR_REVIEW, isTrustedRole } from './poller-protocol';
+import {
+  parseReviewPlan,
+  type ReviewPublicationPlan,
+  reviewPlanMarker,
+} from './poller-review-output';
+
+export const readReviewPlan = async (
+  deps: JobDeps,
+  pr: PullRequest,
+): Promise<ReviewPublicationPlan | null> => {
+  const comments = await listIssueComments(deps.token, deps.repo, pr.number);
+  const currentPlans: Array<ReviewPublicationPlan> = [];
+  for (const comment of comments) {
+    const plan = parseReviewPlan(comment.body);
+    if (
+      plan !== null &&
+      plan.repo === deps.repo &&
+      plan.prNumber === pr.number &&
+      plan.baseRef === pr.baseRef &&
+      plan.baseSha === pr.baseSha &&
+      (plan.approvedHead === pr.headSha || plan.publishedHead === pr.headSha)
+    ) {
+      // biome-ignore lint/performance/noAwaitInLoops: plan authorship is a publication trust boundary and must fail closed against the current role.
+      const role = await collaboratorRole(
+        deps.token,
+        deps.repo,
+        comment.authorLogin,
+      );
+      if (isTrustedRole(role)) {
+        const binding = await readApprovalBinding(
+          {
+            token: deps.token,
+            repo: deps.repo,
+            issueNumber: pr.number,
+          },
+          APPROVED_FOR_REVIEW,
+          prRevision(plan.baseRef, plan.baseSha, plan.approvedHead),
+        );
+        if (typeof binding !== 'string' && binding.id === plan.approvalId) {
+          currentPlans.push(plan);
+        }
+      }
+    }
+  }
+  const distinct = new Map(
+    currentPlans.map((plan) => [JSON.stringify(plan), plan]),
+  );
+  if (distinct.size > 1) {
+    throw new Error(
+      'publication blocked: conflicting review plans exist for this approval generation',
+    );
+  }
+  return distinct.values().next().value ?? null;
+};
+
+export const validateReviewClaim = async (options: {
+  readonly deps: JobDeps;
+  readonly pr: PullRequest;
+  readonly claim: ClaimBinding;
+  readonly plan: ReviewPublicationPlan;
+  readonly expectedHead: string;
+  readonly requireDraft: boolean;
+}): Promise<PullRequest> => {
+  const { deps, pr, claim, plan, expectedHead, requireDraft } = options;
+  const current = await getPullRequest(deps.token, deps.repo, pr.number);
+  if (
+    current.headSha !== expectedHead ||
+    current.baseRef !== plan.baseRef ||
+    current.baseSha !== plan.baseSha ||
+    current.headRepo !== deps.repo ||
+    (requireDraft && !current.draft)
+  ) {
+    throw new Error(
+      'publication blocked: PR head, base, repository, or draft state changed',
+    );
+  }
+  const problem = await validateClaim(
+    { token: deps.token, repo: deps.repo, issueNumber: pr.number },
+    claim,
+    prRevision(plan.baseRef, plan.baseSha, plan.approvedHead),
+  );
+  if (problem !== null) {
+    throw new Error(`publication blocked: ${problem}`);
+  }
+  return current;
+};
+
+export const publishReviewPlan = async (
+  deps: JobDeps,
+  pr: PullRequest,
+  claim: ClaimBinding,
+  plan: ReviewPublicationPlan,
+): Promise<void> => {
+  if (plan.approvalId !== claim.approval.id) {
+    throw new Error('publication blocked: sealed review approval changed');
+  }
+  if (plan.repo !== deps.repo || plan.prNumber !== pr.number) {
+    throw new Error('publication blocked: sealed review repository changed');
+  }
+  const existing = await readReviewPlan(deps, pr);
+  if (existing !== null) {
+    if (
+      existing.approvalId !== plan.approvalId ||
+      JSON.stringify(existing) !== JSON.stringify(plan)
+    ) {
+      throw new Error('publication blocked: a different review plan exists');
+    }
+    return;
+  }
+  await validateReviewClaim({
+    deps,
+    pr,
+    claim,
+    plan,
+    expectedHead: plan.approvedHead,
+    requireDraft: true,
+  });
+  await createComment(deps.token, deps.repo, pr.number, reviewPlanMarker(plan));
+};

package/src/poller-review-validation.ts

@@ -0,0 +1,66 @@
+import { join } from 'node:path';
+import type { PullRequest } from './poller-github-pulls';
+import type { JobDeps } from './poller-job-shared';
+import {
+  changedPathsBetween,
+  commitCountBetween,
+  createValidationWorktree,
+  isAncestor,
+} from './poller-output-integrity';
+import {
+  changedWorkspaceQualityManifests,
+  lockedPathsOf,
+} from './poller-protected-paths';
+import { forbiddenDiffPaths } from './poller-protocol';
+import type { ReviewPublicationPlan } from './poller-review-output';
+
+export const validateSealedReviewOutput = async (options: {
+  readonly deps: JobDeps;
+  readonly pr: PullRequest;
+  readonly plan: ReviewPublicationPlan;
+  readonly cloneDir: string;
+}): Promise<void> => {
+  const { deps, pr, plan, cloneDir } = options;
+  if (
+    plan.repo !== deps.repo ||
+    plan.prNumber !== pr.number ||
+    plan.baseRef !== pr.baseRef ||
+    plan.baseSha !== pr.baseSha ||
+    !isAncestor(cloneDir, plan.approvedHead, plan.publishedHead) ||
+    commitCountBetween(cloneDir, plan.approvedHead, plan.publishedHead) !==
+      plan.commits
+  ) {
+    throw new Error('publication blocked: sealed review identity changed');
+  }
+  const paths = changedPathsBetween(
+    cloneDir,
+    plan.approvedHead,
+    plan.publishedHead,
+  );
+  const workspace = createValidationWorktree(
+    cloneDir,
+    plan.publishedHead,
+    join(
+      deps.config.cacheDir,
+      'work',
+      `${deps.repo.replace('/', '--')}-pr-${pr.number}-validate`,
+    ),
+  );
+  try {
+    const forbidden = [
+      ...forbiddenDiffPaths(paths, await lockedPathsOf(workspace.dir)),
+      ...changedWorkspaceQualityManifests(
+        workspace.dir,
+        plan.approvedHead,
+        paths,
+      ),
+    ];
+    if (forbidden.length > 0) {
+      throw new Error(
+        `publication blocked: sealed review modified protected paths:\n${forbidden.join('\n')}`,
+      );
+    }
+  } finally {
+    workspace.cleanup();
+  }
+};

package/src/poller-schedule.ts

@@ -0,0 +1,121 @@
+import { hasLabel } from './github-label-identity';
+import {
+  type IssueItem,
+  lastLabelEvent,
+  listOpenIssuesWithLabel,
+} from './poller-github';
+import { createComment, removeLabel } from './poller-github-write';
+import type { JobDeps } from './poller-job-shared';
+import {
+  APPROVED_FOR_FIX,
+  APPROVED_FOR_REVIEW,
+  FIX_IN_PROGRESS,
+  REVIEW_IN_PROGRESS,
+} from './poller-protocol';
+
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_HOUR = 3600;
+const MS_PER_HOUR = SECONDS_PER_HOUR * MS_PER_SECOND;
+
+export type ScheduledJob = {
+  readonly deps: JobDeps;
+  readonly item: IssueItem;
+  readonly approvedAt: string;
+};
+
+export const byApprovalAge = (
+  left: ScheduledJob,
+  right: ScheduledJob,
+): number =>
+  Date.parse(left.approvedAt) - Date.parse(right.approvedAt) ||
+  left.deps.repo.localeCompare(right.deps.repo) ||
+  left.item.number - right.item.number;
+
+const sweepStaleClaims = async (
+  deps: JobDeps,
+  claimLabel: string,
+  now: number,
+): Promise<ReadonlyArray<string>> => {
+  const { config, token, repo } = deps;
+  const claimed = await listOpenIssuesWithLabel(token, repo, claimLabel);
+  const lines: Array<string> = [];
+  for (const item of claimed) {
+    // biome-ignore lint/performance/noAwaitInLoops: label removals and comments are GitHub writes; GitHub advises against concurrent write requests (secondary rate limits).
+    const event = await lastLabelEvent(token, repo, item.number, claimLabel);
+    const ageMs =
+      event === null
+        ? Number.POSITIVE_INFINITY
+        : now - Date.parse(event.createdAt);
+    if (ageMs > config.staleClaimHours * MS_PER_HOUR) {
+      await removeLabel(token, repo, item.number, claimLabel);
+      await createComment(
+        token,
+        repo,
+        item.number,
+        `Released a stale \`${claimLabel}\` claim (older than ${config.staleClaimHours}h); the job will retry on a later tick.`,
+      );
+      lines.push(`${repo}#${item.number}: released stale ${claimLabel}`);
+    }
+  }
+  return lines;
+};
+
+const unclaimed = (
+  items: ReadonlyArray<IssueItem>,
+  claimLabel: string,
+): ReadonlyArray<IssueItem> =>
+  [...items]
+    .filter((item) => !hasLabel(item.labels, claimLabel))
+    .sort((left, right) => left.number - right.number);
+
+const schedule = async (
+  deps: JobDeps,
+  items: ReadonlyArray<IssueItem>,
+  approvalLabel: string,
+): Promise<ReadonlyArray<ScheduledJob>> => {
+  const jobs: Array<ScheduledJob> = [];
+  for (const item of items) {
+    // biome-ignore lint/performance/noAwaitInLoops: approval times are trust-bearing timeline reads and sequential requests avoid GitHub secondary rate limits.
+    const event = await lastLabelEvent(
+      deps.token,
+      deps.repo,
+      item.number,
+      approvalLabel,
+    );
+    jobs.push({ deps, item, approvedAt: event?.createdAt ?? '' });
+  }
+  return jobs;
+};
+
+export const discoverRepositoryJobs = async (
+  deps: JobDeps,
+  now: number,
+): Promise<{
+  readonly lines: ReadonlyArray<string>;
+  readonly reviews: ReadonlyArray<ScheduledJob>;
+  readonly fixes: ReadonlyArray<ScheduledJob>;
+}> => {
+  const { token, repo } = deps;
+  const lines: Array<string> = [];
+  for (const claimLabel of [FIX_IN_PROGRESS, REVIEW_IN_PROGRESS]) {
+    // biome-ignore lint/performance/noAwaitInLoops: sweeps issue GitHub writes; GitHub advises against concurrent write requests (secondary rate limits).
+    lines.push(...(await sweepStaleClaims(deps, claimLabel, now)));
+  }
+  const reviewItems = unclaimed(
+    (await listOpenIssuesWithLabel(token, repo, APPROVED_FOR_REVIEW)).filter(
+      (item) => item.isPullRequest,
+    ),
+    REVIEW_IN_PROGRESS,
+  );
+  const fixItems = unclaimed(
+    (await listOpenIssuesWithLabel(token, repo, APPROVED_FOR_FIX)).filter(
+      (item) => !item.isPullRequest,
+    ),
+    FIX_IN_PROGRESS,
+  );
+  return {
+    lines,
+    reviews: await schedule(deps, reviewItems, APPROVED_FOR_REVIEW),
+    fixes: await schedule(deps, fixItems, APPROVED_FOR_FIX),
+  };
+};