@davidvornholt/standards 0.10.2 → 0.11.0

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),
+  };
+};

package/src/poller-tick.ts

@@ -0,0 +1,144 @@
+// One poller tick: sweep stale claims, then run approved jobs oldest-first —
+// review jobs before fix jobs, because reviews unblock merges — under the
+// per-tick Codex run cap. All state lives in GitHub, so a tick is re-runnable
+// and a crash costs at most one stale claim that the next tick sweeps.
+
+import type { PollerConfig } from './poller-config';
+import { runFixJob } from './poller-fix-run';
+import { repoDefaultBranch } from './poller-github';
+import type { JobDeps, JobResult } from './poller-job-shared';
+import { runReviewJob } from './poller-review-run';
+import { discoverRepositoryJobs, type ScheduledJob } from './poller-schedule';
+import type { RoleCache } from './poller-trust';
+
+export type TickReport = {
+  readonly lines: ReadonlyArray<string>;
+  readonly problems: ReadonlyArray<string>;
+};
+
+type RunBudget = {
+  remaining: number;
+};
+
+export type TickJobRunners = {
+  readonly review: typeof runReviewJob;
+  readonly fix: typeof runFixJob;
+};
+
+const DEFAULT_JOB_RUNNERS: TickJobRunners = {
+  review: runReviewJob,
+  fix: runFixJob,
+};
+
+type TypedScheduledJob = ScheduledJob & {
+  readonly kind: 'review' | 'fix';
+};
+
+const approvalTime = (job: ScheduledJob): number => {
+  const parsed = Date.parse(job.approvedAt);
+  return Number.isNaN(parsed) ? Number.NEGATIVE_INFINITY : parsed;
+};
+
+const kindPriority = (
+  left: TypedScheduledJob,
+  right: TypedScheduledJob,
+): number => {
+  if (left.kind === right.kind) {
+    return 0;
+  }
+  return left.kind === 'review' ? -1 : 1;
+};
+
+const byGlobalPriority = (
+  left: TypedScheduledJob,
+  right: TypedScheduledJob,
+): number =>
+  approvalTime(left) - approvalTime(right) ||
+  kindPriority(left, right) ||
+  left.deps.repo.localeCompare(right.deps.repo) ||
+  left.item.number - right.item.number;
+
+const runQueue = async (options: {
+  readonly queue: ReadonlyArray<TypedScheduledJob>;
+  readonly token: string | null;
+  readonly runners: TickJobRunners;
+  readonly budget: RunBudget;
+  readonly lines: Array<string>;
+  readonly problems: Array<string>;
+  readonly defaultBranches: Map<string, string>;
+}): Promise<void> => {
+  const { queue, token, runners, budget, lines, problems, defaultBranches } =
+    options;
+  for (const job of queue) {
+    try {
+      let result: JobResult;
+      const allowCodex = budget.remaining > 0;
+      if (job.kind === 'review') {
+        // biome-ignore lint/performance/noAwaitInLoops: jobs are heavyweight Codex runs and the shared run budget is the concurrency cap.
+        result = await runners.review(job.deps, job.item, allowCodex);
+      } else {
+        let defaultBranch = defaultBranches.get(job.deps.repo);
+        if (defaultBranch === undefined) {
+          defaultBranch = await repoDefaultBranch(token, job.deps.repo);
+          defaultBranches.set(job.deps.repo, defaultBranch);
+        }
+        result = await runners.fix(
+          job.deps,
+          job.item,
+          defaultBranch,
+          allowCodex,
+        );
+      }
+      lines.push(...result.lines.map((line) => `${job.deps.repo} ${line}`));
+      budget.remaining -= result.ranCodex ? 1 : 0;
+    } catch (error) {
+      problems.push(
+        `${job.deps.repo}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+};
+
+export const runPollerTick = async (
+  config: PollerConfig,
+  token: string | null,
+  now: number,
+  runners: TickJobRunners = DEFAULT_JOB_RUNNERS,
+): Promise<TickReport> => {
+  const lines: Array<string> = [];
+  const problems: Array<string> = [];
+  const roleCache: RoleCache = new Map();
+  const budget: RunBudget = { remaining: config.maxJobsPerTick };
+  const reviews: Array<ScheduledJob> = [];
+  const fixes: Array<ScheduledJob> = [];
+
+  for (const repo of config.repos) {
+    const deps: JobDeps = { config, token, repo, roleCache };
+    try {
+      // biome-ignore lint/performance/noAwaitInLoops: discovery includes GitHub timeline reads and stale-claim writes; sequential requests avoid secondary rate limits.
+      const discovered = await discoverRepositoryJobs(deps, now);
+      lines.push(...discovered.lines);
+      reviews.push(...discovered.reviews);
+      fixes.push(...discovered.fixes);
+    } catch (error) {
+      problems.push(
+        `${repo}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  const defaultBranches = new Map<string, string>();
+  const queue: ReadonlyArray<TypedScheduledJob> = [
+    ...reviews.map((job) => ({ ...job, kind: 'review' as const })),
+    ...fixes.map((job) => ({ ...job, kind: 'fix' as const })),
+  ].sort(byGlobalPriority);
+  await runQueue({
+    queue,
+    token,
+    runners,
+    budget,
+    lines,
+    problems,
+    defaultBranches,
+  });
+  return { lines, problems };
+};