@davidvornholt/standards 0.16.0 → 0.17.1

package/src/poller-review-run.ts

@@ -1,11 +1,13 @@
 // 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.
+// Codex maintains the GitHub review ledger and commits fixes, then the poller
+// verifies and pushes those commits, posts the final report, and flips the PR
+// ready.
 
-import { prRevision } from './poller-approval';
+import { hasLabel } from './github-label-identity';
+import { approvalIsCurrent, prRevision } from './poller-approval';
 import { acquireClaim } from './poller-claim';
+import { runCodex } from './poller-codex';
 import { getIssue, type IssueItem } from './poller-github';
 import { getPullRequest } from './poller-github-pulls';
 import { addLabels } from './poller-github-write';
@@ -48,21 +50,58 @@ const hasInvalidLocalOutput = (
 ): boolean =>
   plan === null && sealed === null && localBranchExists(cloneDir, branch);
 
+const currentReviewTarget = async (
+  token: string | null,
+  repo: string,
+  prNumber: number,
+  plan: Awaited<ReturnType<typeof readReviewPlan>>,
+): Promise<string | null> => {
+  const current = await getPullRequest(token, repo, prNumber);
+  if (
+    plan !== null &&
+    current.headSha !== plan.approvedHead &&
+    current.headSha !== plan.publishedHead
+  ) {
+    return null;
+  }
+  return prRevision(
+    current.baseRef,
+    current.baseSha,
+    plan === null ? current.headSha : plan.approvedHead,
+  );
+};
+
 export const runReviewJob = async (
   deps: JobDeps,
   prItem: IssueItem,
   allowCodex = true,
+  runAgent: typeof runCodex = runCodex,
 ): Promise<JobResult> => {
   const { config, token, repo } = deps;
+  const currentItem = await getIssue(token, repo, prItem.number);
+  if (!hasLabel(currentItem.labels, APPROVED_FOR_REVIEW)) {
+    return {
+      lines: [`PR #${prItem.number}: approval no longer present; skipped`],
+      ranCodex: false,
+    };
+  }
   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),
-  );
+  const readTarget = () => currentReviewTarget(token, repo, pr.number, plan);
+  const preamble = await jobPreamble(deps, currentItem, REVIEW_LABELS, {
+    approved: prRevision(
+      pr.baseRef,
+      pr.baseSha,
+      plan?.approvedHead ?? pr.headSha,
+    ),
+    readCurrent: readTarget,
+  });
+  if (preamble.kind === 'stale') {
+    return {
+      lines: [`PR #${prItem.number}: approval no longer present; skipped`],
+      ranCodex: false,
+    };
+  }
   if (preamble.kind === 'rejected') {
     return {
       lines: [`PR #${prItem.number}: approval rejected`],
@@ -99,6 +138,18 @@ export const runReviewJob = async (
   if (hasInvalidLocalOutput(plan, sealed, cacheClone, outputBranch)) {
     throw new Error(`sealed output on ${outputBranch} is invalid`);
   }
+  if (
+    !(await approvalIsCurrent(
+      { token, repo, issueNumber: pr.number },
+      preamble.approval,
+      readTarget,
+    ))
+  ) {
+    return {
+      lines: [`PR #${pr.number}: approval generation changed; skipped`],
+      ranCodex: false,
+    };
+  }
   if (plan === null && sealed === null && !allowCodex) {
     await acknowledgeQueuedJob(deps, pr.number, preamble.approval, 'review');
     return {
@@ -144,5 +195,6 @@ export const runReviewJob = async (
     claim,
     cacheClone,
     answers: preamble.answers,
+    runAgent,
   });
 };

package/src/poller-review-state.ts

@@ -43,7 +43,10 @@ export const readReviewPlan = async (
           APPROVED_FOR_REVIEW,
           prRevision(plan.baseRef, plan.baseSha, plan.approvedHead),
         );
-        if (typeof binding !== 'string' && binding.id === plan.approvalId) {
+        if (
+          binding.kind === 'approved' &&
+          binding.approval.id === plan.approvalId
+        ) {
           currentPlans.push(plan);
         }
       }

package/src/poller-review-thread-api.ts

@@ -0,0 +1,166 @@
+import { apiError, HTTP_OK, request } from './github-api';
+import { isRecord } from './github-settings-parse';
+
+export type ReviewThreadComment = {
+  readonly body: string;
+  readonly viewerDidAuthor: boolean;
+};
+
+export type ReviewThread = {
+  readonly id: string;
+  readonly repo: string;
+  readonly prNumber: number;
+  readonly isResolved: boolean;
+  readonly creation: ReviewThreadComment | null;
+  readonly viewerAuthoredBodies: ReadonlyArray<string>;
+};
+
+const asRecord = (
+  value: unknown,
+  context: string,
+): Readonly<Record<string, unknown>> => {
+  if (!isRecord(value)) {
+    throw new Error(`${context}: expected an object`);
+  }
+  return value;
+};
+
+const stringField = (
+  value: Readonly<Record<string, unknown>>,
+  key: string,
+  context: string,
+): string => {
+  const field = value[key];
+  if (typeof field !== 'string') {
+    throw new Error(`${context}: expected "${key}" to be a string`);
+  }
+  return field;
+};
+
+const booleanField = (
+  value: Readonly<Record<string, unknown>>,
+  key: string,
+  context: string,
+): boolean => {
+  const field = value[key];
+  if (typeof field !== 'boolean') {
+    throw new Error(`${context}: expected "${key}" to be a boolean`);
+  }
+  return field;
+};
+
+const numberField = (
+  value: Readonly<Record<string, unknown>>,
+  key: string,
+  context: string,
+): number => {
+  const field = value[key];
+  if (typeof field !== 'number') {
+    throw new Error(`${context}: expected "${key}" to be a number`);
+  }
+  return field;
+};
+
+const reviewThreadComment = (
+  value: unknown,
+  context: string,
+): ReviewThreadComment => {
+  const comment = asRecord(value, context);
+  return {
+    body: stringField(comment, 'body', context),
+    viewerDidAuthor: booleanField(comment, 'viewerDidAuthor', context),
+  };
+};
+
+const readThreadPage = async (
+  token: string | null,
+  threadId: string,
+  after: string | null,
+): Promise<{
+  readonly thread: ReviewThread;
+  readonly nextCursor: string | null;
+}> => {
+  const response = await request(token, 'POST', '/graphql', {
+    query:
+      'query($id: ID!, $after: String) { node(id: $id) { ... on PullRequestReviewThread { id isResolved pullRequest { number repository { nameWithOwner } } comments(first: 100, after: $after) { nodes { body viewerDidAuthor } pageInfo { hasNextPage endCursor } } } } }',
+    variables: { id: threadId, after },
+  });
+  if (response.status !== HTTP_OK) {
+    throw new Error(apiError(`read review thread ${threadId}`, response));
+  }
+  const context = `read review thread ${threadId}`;
+  const body = asRecord(response.body, context);
+  if (body.errors !== undefined) {
+    throw new Error(apiError(context, response));
+  }
+  const data = asRecord(body.data, context);
+  const node = asRecord(data.node, context);
+  if (stringField(node, 'id', context) !== threadId) {
+    throw new Error(`${context}: GitHub returned a different node`);
+  }
+  const pullRequest = asRecord(node.pullRequest, context);
+  const repository = asRecord(pullRequest.repository, context);
+  const comments = asRecord(node.comments, context);
+  const pageInfo = asRecord(comments.pageInfo, context);
+  if (!Array.isArray(comments.nodes)) {
+    throw new Error(`${context}: expected thread comments`);
+  }
+  const parsedComments = comments.nodes.map((comment) =>
+    reviewThreadComment(comment, context),
+  );
+  const viewerAuthoredBodies: Array<string> = [];
+  for (const comment of parsedComments) {
+    if (comment.viewerDidAuthor) {
+      viewerAuthoredBodies.push(comment.body);
+    }
+  }
+  const hasNextPage = booleanField(pageInfo, 'hasNextPage', context);
+  const { endCursor } = pageInfo;
+  if (hasNextPage && typeof endCursor !== 'string') {
+    throw new Error(`${context}: expected the next comment cursor`);
+  }
+  return {
+    thread: {
+      id: threadId,
+      repo: stringField(repository, 'nameWithOwner', context),
+      prNumber: numberField(pullRequest, 'number', context),
+      isResolved: booleanField(node, 'isResolved', context),
+      creation: parsedComments[0] ?? null,
+      viewerAuthoredBodies,
+    },
+    nextCursor: hasNextPage ? (endCursor as string) : null,
+  };
+};
+
+export const readReviewThread = async (
+  token: string | null,
+  threadId: string,
+): Promise<ReviewThread> => {
+  let after: string | null = null;
+  let combined: ReviewThread | null = null;
+  const viewerAuthoredBodies: Array<string> = [];
+  do {
+    // biome-ignore lint/performance/noAwaitInLoops: all comment pages are required for replay-safe marker lookup.
+    const page = await readThreadPage(token, threadId, after);
+    if (
+      combined !== null &&
+      (combined.repo !== page.thread.repo ||
+        combined.prNumber !== page.thread.prNumber ||
+        combined.isResolved !== page.thread.isResolved)
+    ) {
+      throw new Error(`read review thread ${threadId}: identity changed`);
+    }
+    if (combined === null) {
+      combined = { ...page.thread, viewerAuthoredBodies };
+    } else if (combined.creation === null && page.thread.creation !== null) {
+      const existing = combined as ReviewThread;
+      combined = { ...existing, creation: page.thread.creation };
+    }
+    viewerAuthoredBodies.push(...page.thread.viewerAuthoredBodies);
+    after = page.nextCursor;
+  } while (after !== null);
+  if (combined === null) {
+    throw new Error(`read review thread ${threadId}: no response`);
+  }
+  return combined;
+};

package/src/poller-review-thread-write.ts

@@ -0,0 +1,64 @@
+import { apiError, HTTP_OK, request } from './github-api';
+import { isRecord } from './github-settings-parse';
+
+const REPLY_MUTATION =
+  // biome-ignore lint/security/noSecrets: a GraphQL mutation string, not a credential.
+  'mutation($id: ID!, $body: String!) { addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $id, body: $body }) { comment { id } } }';
+
+const RESOLVE_MUTATION =
+  'mutation($id: ID!) { resolveReviewThread(input: { threadId: $id }) { thread { id isResolved } } }';
+
+const mutationBody = (
+  operation: 'reply' | 'resolve',
+  threadId: string,
+  response: Awaited<ReturnType<typeof request>>,
+): Readonly<Record<string, unknown>> => {
+  const context = `${operation} review thread ${threadId}`;
+  if (
+    response.status !== HTTP_OK ||
+    !isRecord(response.body) ||
+    response.body.errors !== undefined ||
+    !isRecord(response.body.data)
+  ) {
+    throw new Error(apiError(context, response));
+  }
+  return response.body.data;
+};
+
+export const replyToReviewThread = async (
+  token: string | null,
+  threadId: string,
+  body: string,
+): Promise<void> => {
+  const response = await request(token, 'POST', '/graphql', {
+    query: REPLY_MUTATION,
+    variables: { id: threadId, body },
+  });
+  const data = mutationBody('reply', threadId, response);
+  const payload = data.addPullRequestReviewThreadReply;
+  if (
+    !(isRecord(payload) && isRecord(payload.comment)) ||
+    typeof payload.comment.id !== 'string'
+  ) {
+    throw new Error(apiError(`reply review thread ${threadId}`, response));
+  }
+};
+
+export const resolveReviewThread = async (
+  token: string | null,
+  threadId: string,
+): Promise<void> => {
+  const response = await request(token, 'POST', '/graphql', {
+    query: RESOLVE_MUTATION,
+    variables: { id: threadId },
+  });
+  const data = mutationBody('resolve', threadId, response);
+  const payload = data.resolveReviewThread;
+  if (
+    !(isRecord(payload) && isRecord(payload.thread)) ||
+    payload.thread.id !== threadId ||
+    payload.thread.isResolved !== true
+  ) {
+    throw new Error(apiError(`resolve review thread ${threadId}`, response));
+  }
+};

package/src/poller-review-threads.ts

@@ -0,0 +1,119 @@
+import { createHash } from 'node:crypto';
+import type { ClaimBinding } from './poller-claim';
+import type { PullRequest } from './poller-github-pulls';
+import type { JobDeps } from './poller-job-shared';
+import type { ReviewThreadResolution } from './poller-protocol';
+import type { ReviewPublicationPlan } from './poller-review-output';
+import { validateReviewClaim } from './poller-review-state';
+import {
+  type ReviewThread,
+  readReviewThread,
+} from './poller-review-thread-api';
+import {
+  replyToReviewThread,
+  resolveReviewThread,
+} from './poller-review-thread-write';
+
+const AGENT_REVIEW_THREAD_MARKER =
+  /<!-- standards-poller:review-thread approval=(?<approval>[a-f0-9]{64}) operation=(?:[a-f0-9]{64}) -->/gu;
+
+export const agentReviewThreadMarker = (
+  approvalId: string,
+  operationId: string,
+): string =>
+  `<!-- standards-poller:review-thread approval=${approvalId} operation=${operationId} -->`;
+
+const hasAgentCreationMarker = (body: string, approvalId: string): boolean =>
+  [...body.matchAll(AGENT_REVIEW_THREAD_MARKER)].some(
+    (marker) => marker.groups?.approval === approvalId,
+  );
+
+export const threadResolutionMarker = (
+  plan: ReviewPublicationPlan,
+  resolution: ReviewThreadResolution,
+): string => {
+  const digest = createHash('sha256')
+    .update(
+      JSON.stringify({
+        repo: plan.repo,
+        prNumber: plan.prNumber,
+        approvalId: plan.approvalId,
+        threadId: resolution.threadId,
+        verificationReply: resolution.verificationReply,
+      }),
+    )
+    .digest('hex');
+  return `<!-- standards-poller:thread-resolution approval=${plan.approvalId} operation=${digest} -->`;
+};
+
+const assertThreadTarget = (
+  thread: ReviewThread,
+  plan: ReviewPublicationPlan,
+): void => {
+  if (thread.repo !== plan.repo || thread.prNumber !== plan.prNumber) {
+    throw new Error(
+      `publication blocked: review thread ${thread.id} belongs to ${thread.repo}#${thread.prNumber}`,
+    );
+  }
+  if (
+    thread.creation === null ||
+    !thread.creation.viewerDidAuthor ||
+    !hasAgentCreationMarker(thread.creation.body, plan.approvalId)
+  ) {
+    throw new Error(
+      `publication blocked: review thread ${thread.id} was not created by this approval generation`,
+    );
+  }
+};
+
+export const publishReviewThreadResolutions = async (options: {
+  readonly deps: JobDeps;
+  readonly pr: PullRequest;
+  readonly claim: ClaimBinding;
+  readonly plan: ReviewPublicationPlan;
+}): Promise<void> => {
+  const { deps, pr, claim, plan } = options;
+  for (const resolution of plan.threadsToResolve) {
+    const marker = threadResolutionMarker(plan, resolution);
+    const reply = `${resolution.verificationReply}\n\n${marker}`;
+    // biome-ignore lint/performance/noAwaitInLoops: each thread write has its own immediate claim revalidation.
+    let thread = await readReviewThread(deps.token, resolution.threadId);
+    assertThreadTarget(thread, plan);
+    if (!thread.viewerAuthoredBodies.includes(reply)) {
+      await validateReviewClaim({
+        deps,
+        pr,
+        claim,
+        plan,
+        expectedHead: plan.publishedHead,
+        requireDraft: true,
+      });
+      await replyToReviewThread(deps.token, resolution.threadId, reply);
+    }
+    thread = await readReviewThread(deps.token, resolution.threadId);
+    assertThreadTarget(thread, plan);
+    if (!thread.viewerAuthoredBodies.includes(reply)) {
+      throw new Error(
+        `publication blocked: verification reply missing from review thread ${resolution.threadId}`,
+      );
+    }
+    if (!thread.isResolved) {
+      await validateReviewClaim({
+        deps,
+        pr,
+        claim,
+        plan,
+        expectedHead: plan.publishedHead,
+        requireDraft: true,
+      });
+      await resolveReviewThread(deps.token, resolution.threadId);
+    }
+    thread = await readReviewThread(deps.token, resolution.threadId);
+    assertThreadTarget(thread, plan);
+    if (!thread.isResolved) {
+      throw new Error(
+        `publication blocked: review thread ${resolution.threadId} remained unresolved`,
+      );
+    }
+  }
+};

package/src/poller-status.ts

@@ -74,7 +74,8 @@ const isStillQueueable = async (
     target,
   );
   return (
-    typeof currentApproval !== 'string' && currentApproval.id === approval.id
+    currentApproval.kind === 'approved' &&
+    currentApproval.approval.id === approval.id
   );
 };
 
@@ -87,6 +88,7 @@ export const acknowledgeQueuedJob = async (
   const expected = queueMarkerFor(approval, kind);
   const current = await getIssue(deps.token, deps.repo, issueNumber);
   if (
+    !hasLabel(current.labels, approvalLabelFor(kind)) ||
     hasLabel(current.labels, inProgressLabelFor(kind)) ||
     hasLabel(current.labels, NEEDS_CLARIFICATION)
   ) {

package/src/poller-tick.ts

@@ -77,15 +77,17 @@ const runQueue = async (options: {
         // 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,
+          async () => {
+            let branch = defaultBranches.get(job.deps.repo);
+            if (branch === undefined) {
+              branch = await repoDefaultBranch(token, job.deps.repo);
+              defaultBranches.set(job.deps.repo, branch);
+            }
+            return branch;
+          },
           allowCodex,
         );
       }

package/src/poller-github-publication.ts

@@ -1,23 +0,0 @@
-import { listAllPages } from './github-paginate';
-import { isRecord } from './github-settings-parse';
-
-export const repositoryIssueMarkerAuthors = async (
-  token: string | null,
-  repo: string,
-  marker: string,
-): Promise<ReadonlyArray<string>> => {
-  const items = await listAllPages(
-    token,
-    `/repos/${repo}/issues?state=all`,
-    `list ${repo} issues for publication marker`,
-  );
-  return items.flatMap((item) =>
-    isRecord(item) &&
-    typeof item.body === 'string' &&
-    item.body.includes(marker) &&
-    isRecord(item.user) &&
-    typeof item.user.login === 'string'
-      ? [item.user.login]
-      : [],
-  );
-};