@davidvornholt/standards 0.10.2 → 0.11.0

package/src/poller-fix-run.ts

@@ -0,0 +1,175 @@
+// One fix job: a maintainer-approved issue becomes a verified draft PR, a
+// precise question, or an explicit failure — never silence. Every transition
+// is written back to GitHub so the next tick (or a human) resumes from there.
+
+import { join } from 'node:path';
+import { issueRevision } from './poller-approval';
+import { acquireClaim } from './poller-claim';
+import { runCodex } from './poller-codex';
+import { handleNonFixedOutcome } from './poller-fix-outcome';
+import { readSealedFixOutput } from './poller-fix-output';
+import {
+  type FixPublication,
+  finishFixedJob,
+  publishFixedOutput,
+  validateFixClaim,
+} from './poller-fix-publication';
+import { getIssue, type IssueItem } from './poller-github';
+import { addLabels } from './poller-github-write';
+import {
+  failJob,
+  type JobDeps,
+  type JobLabels,
+  type JobResult,
+  jobPreamble,
+} from './poller-job-shared';
+import { readFixOutcome } from './poller-outcome';
+import { fixPrompt } from './poller-prompts';
+import {
+  APPROVED_FOR_FIX,
+  branchNameForIssue,
+  FIX_FAILED,
+  FIX_IN_PROGRESS,
+} from './poller-protocol';
+import {
+  createWorktree,
+  ensureCacheClone,
+  localBranchExists,
+  type Workspace,
+} from './poller-workspace';
+
+const FIX_LABELS: JobLabels = {
+  approved: APPROVED_FOR_FIX,
+  inProgress: FIX_IN_PROGRESS,
+  failed: FIX_FAILED,
+};
+
+type FixJob = FixPublication & {
+  readonly workspace: Workspace;
+};
+
+const hasInvalidLocalOutput = (
+  sealed: ReturnType<typeof readSealedFixOutput>,
+  cloneDir: string,
+  branch: string,
+): boolean => sealed === null && localBranchExists(cloneDir, branch);
+
+export const runFixJob = async (
+  deps: JobDeps,
+  issue: IssueItem,
+  defaultBranch: string,
+  allowCodex = true,
+): Promise<JobResult> => {
+  const { config, token, repo } = deps;
+  const currentIssue = await getIssue(token, repo, issue.number);
+  const preamble = await jobPreamble(
+    deps,
+    currentIssue,
+    FIX_LABELS,
+    issueRevision(currentIssue),
+  );
+  if (preamble.kind === 'rejected') {
+    return { lines: [`#${issue.number}: approval rejected`], ranCodex: false };
+  }
+  if (preamble.kind === 'waiting') {
+    return {
+      lines: [`#${issue.number}: waiting on an answer`],
+      ranCodex: false,
+    };
+  }
+  const cacheClone = ensureCacheClone(config.cacheDir, repo, token);
+  const branch = branchNameForIssue(issue.number, preamble.approval.id);
+  const sealed = readSealedFixOutput(cacheClone, branch);
+  if (hasInvalidLocalOutput(sealed, cacheClone, branch)) {
+    throw new Error(
+      `refusing to overwrite ${branch}: it is not valid sealed output for this approval`,
+    );
+  }
+  if (sealed === null && !allowCodex) {
+    return {
+      lines: [`#${issue.number}: waiting for run capacity`],
+      ranCodex: false,
+    };
+  }
+  await addLabels(token, repo, issue.number, [FIX_IN_PROGRESS]);
+  const claim = await acquireClaim(
+    { token, repo, issueNumber: issue.number },
+    preamble.approval,
+    FIX_IN_PROGRESS,
+  );
+  if (claim === null) {
+    return {
+      lines: [`#${issue.number}: another poller owns the claim`],
+      ranCodex: false,
+    };
+  }
+  const resumableJob = {
+    deps,
+    issue: currentIssue,
+    defaultBranch,
+    claim,
+    branch,
+    cloneDir: cacheClone,
+  };
+  if (sealed !== null) {
+    if (
+      sealed.issueNumber !== issue.number ||
+      sealed.approvalId !== claim.approval.id
+    ) {
+      throw new Error(`sealed output on ${branch} has invalid ownership`);
+    }
+    return {
+      lines: [await publishFixedOutput(resumableJob, FIX_LABELS, sealed, null)],
+      ranCodex: false,
+    };
+  }
+  const workspace = createWorktree(
+    cacheClone,
+    defaultBranch,
+    branch,
+    join(
+      config.cacheDir,
+      'work',
+      `${repo.replace('/', '--')}-issue-${issue.number}`,
+    ),
+  );
+  const job: FixJob = {
+    ...resumableJob,
+    issue: currentIssue,
+    workspace,
+  };
+  try {
+    const run = runCodex(
+      workspace.dir,
+      fixPrompt({
+        repo,
+        issueNumber: issue.number,
+        title: currentIssue.title,
+        body: currentIssue.body,
+        answers: preamble.answers,
+      }),
+      config,
+    );
+    await validateFixClaim(job);
+    const outcome = run.succeeded ? await readFixOutcome(workspace.dir) : null;
+    if (outcome === null) {
+      await failJob(
+        deps,
+        FIX_LABELS,
+        issue.number,
+        run.failure ?? 'run wrote no valid outcome file',
+      );
+      return {
+        lines: [`#${issue.number}: failed (no valid outcome)`],
+        ranCodex: true,
+      };
+    }
+    const nonFixed = await handleNonFixedOutcome(job, FIX_LABELS, outcome);
+    return {
+      lines: [nonFixed ?? (await finishFixedJob(job, FIX_LABELS, outcome))],
+      ranCodex: true,
+    };
+  } finally {
+    workspace.cleanup();
+  }
+};

package/src/poller-fix-validation.ts

@@ -0,0 +1,64 @@
+import { join } from 'node:path';
+import type { SealedFixOutput } from './poller-fix-output';
+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';
+
+export const validateSealedFixOutput = async (
+  job: {
+    readonly deps: JobDeps;
+    readonly issueNumber: number;
+    readonly defaultBranch: string;
+    readonly approvalId: string;
+    readonly cloneDir: string;
+  },
+  output: SealedFixOutput,
+): Promise<void> => {
+  if (
+    output.repo !== job.deps.repo ||
+    output.issueNumber !== job.issueNumber ||
+    output.approvalId !== job.approvalId ||
+    !isAncestor(job.cloneDir, output.baseSha, job.defaultBranch) ||
+    !isAncestor(job.cloneDir, output.baseSha, output.generatedHead) ||
+    commitCountBetween(job.cloneDir, output.baseSha, output.generatedHead) !==
+      output.commits
+  ) {
+    throw new Error('sealed fix output does not match this job');
+  }
+  const paths = changedPathsBetween(
+    job.cloneDir,
+    output.baseSha,
+    output.generatedHead,
+  );
+  const workspace = createValidationWorktree(
+    job.cloneDir,
+    output.generatedHead,
+    join(
+      job.deps.config.cacheDir,
+      'work',
+      `${job.deps.repo.replace('/', '--')}-issue-${job.issueNumber}-validate`,
+    ),
+  );
+  try {
+    const forbidden = [
+      ...forbiddenDiffPaths(paths, await lockedPathsOf(workspace.dir)),
+      ...changedWorkspaceQualityManifests(workspace.dir, output.baseSha, paths),
+    ];
+    if (forbidden.length > 0) {
+      throw new Error(
+        `sealed fix output modified protected paths:\n${forbidden.join('\n')}`,
+      );
+    }
+  } finally {
+    workspace.cleanup();
+  }
+};

package/src/poller-github-publication.ts

@@ -0,0 +1,23 @@
+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]
+      : [],
+  );
+};

package/src/poller-github-pulls.ts

@@ -0,0 +1,189 @@
+// Pull-request operations for the poller: creating the draft PR that carries
+// a fix, reading PR state for review jobs, posting the review report, and
+// flipping draft to ready (GraphQL: REST cannot change the draft flag).
+
+import { apiError, HTTP_CREATED, HTTP_OK, request } from './github-api';
+import { listAllPages } from './github-paginate';
+import { isNonEmptyString, isRecord } from './github-settings-parse';
+
+export type PullRequest = {
+  readonly number: number;
+  readonly title: string;
+  readonly body: string;
+  readonly headRef: string;
+  readonly headSha: string;
+  readonly headRepo: string;
+  readonly baseRef: string;
+  readonly baseSha: string;
+  readonly nodeId: string;
+  readonly draft: boolean;
+};
+
+export const findOpenPullRequestForHead = async (
+  token: string | null,
+  repo: string,
+  head: string,
+): Promise<number | null> => {
+  const [owner = ''] = repo.split('/');
+  const response = await request(
+    token,
+    'GET',
+    `/repos/${repo}/pulls?state=open&head=${encodeURIComponent(`${owner}:${head}`)}`,
+  );
+  if (response.status !== HTTP_OK || !Array.isArray(response.body)) {
+    return null;
+  }
+  const [first] = response.body;
+  return isRecord(first) && typeof first.number === 'number'
+    ? first.number
+    : null;
+};
+
+export const createDraftPullRequest = async (
+  token: string | null,
+  repo: string,
+  options: {
+    readonly title: string;
+    readonly body: string;
+    readonly head: string;
+    readonly base: string;
+  },
+): Promise<number> => {
+  const response = await request(token, 'POST', `/repos/${repo}/pulls`, {
+    title: options.title,
+    body: options.body,
+    head: options.head,
+    base: options.base,
+    draft: true,
+  });
+  if (
+    response.status === HTTP_CREATED &&
+    isRecord(response.body) &&
+    typeof response.body.number === 'number'
+  ) {
+    return response.body.number;
+  }
+  throw new Error(apiError(`create draft PR in ${repo}`, response));
+};
+
+export const updatePullRequest = async (
+  token: string | null,
+  repo: string,
+  prNumber: number,
+  options: { readonly title: string; readonly body: string },
+): Promise<void> => {
+  const response = await request(
+    token,
+    'PATCH',
+    `/repos/${repo}/pulls/${prNumber}`,
+    options,
+  );
+  if (response.status !== HTTP_OK) {
+    throw new Error(apiError(`update ${repo}#${prNumber}`, response));
+  }
+};
+
+export const getPullRequest = async (
+  token: string | null,
+  repo: string,
+  prNumber: number,
+): Promise<PullRequest> => {
+  const response = await request(
+    token,
+    'GET',
+    `/repos/${repo}/pulls/${prNumber}`,
+  );
+  const { body } = response;
+  if (
+    response.status !== HTTP_OK ||
+    !isRecord(body) ||
+    !isRecord(body.head) ||
+    !isRecord(body.base) ||
+    !isNonEmptyString(body.node_id)
+  ) {
+    throw new Error(apiError(`read ${repo}#${prNumber}`, response));
+  }
+  const headRepo = isRecord(body.head.repo)
+    ? body.head.repo
+    : ({} as Record<string, unknown>);
+  return {
+    number: prNumber,
+    title: isNonEmptyString(body.title) ? body.title : '',
+    body: isNonEmptyString(body.body) ? body.body : '',
+    headRef: isNonEmptyString(body.head.ref) ? body.head.ref : '',
+    headSha: isNonEmptyString(body.head.sha) ? body.head.sha : '',
+    headRepo: isNonEmptyString(headRepo.full_name) ? headRepo.full_name : '',
+    baseRef: isNonEmptyString(body.base.ref) ? body.base.ref : '',
+    baseSha: isNonEmptyString(body.base.sha) ? body.base.sha : '',
+    nodeId: body.node_id,
+    draft: body.draft === true,
+  };
+};
+
+export const createPullRequestReview = async (options: {
+  readonly token: string | null;
+  readonly repo: string;
+  readonly prNumber: number;
+  readonly body: string;
+  readonly commitId: string;
+}): Promise<void> => {
+  const { token, repo, prNumber, body, commitId } = options;
+  const response = await request(
+    token,
+    'POST',
+    `/repos/${repo}/pulls/${prNumber}/reviews`,
+    {
+      event: 'COMMENT',
+      body,
+      // biome-ignore lint/style/useNamingConvention: GitHub's REST field is snake_case.
+      commit_id: commitId,
+    },
+  );
+  if (response.status !== HTTP_OK) {
+    throw new Error(apiError(`post review on ${repo}#${prNumber}`, response));
+  }
+};
+
+export const pullRequestReviewMarkerAuthors = async (options: {
+  readonly token: string | null;
+  readonly repo: string;
+  readonly prNumber: number;
+  readonly marker: string;
+  readonly commitId: string;
+}): Promise<ReadonlyArray<string>> => {
+  const { token, repo, prNumber, marker, commitId } = options;
+  const reviews = await listAllPages(
+    token,
+    `/repos/${repo}/pulls/${prNumber}/reviews`,
+    `list reviews on ${repo}#${prNumber}`,
+  );
+  return reviews.flatMap((review) =>
+    isRecord(review) &&
+    review.commit_id === commitId &&
+    typeof review.body === 'string' &&
+    review.body.includes(marker) &&
+    isRecord(review.user) &&
+    typeof review.user.login === 'string'
+      ? [review.user.login]
+      : [],
+  );
+};
+
+export const markPullRequestReady = async (
+  token: string | null,
+  pullRequestNodeId: string,
+): Promise<void> => {
+  const response = await request(token, 'POST', '/graphql', {
+    query:
+      // biome-ignore lint/security/noSecrets: a GraphQL mutation string, not a credential.
+      'mutation($id: ID!) { markPullRequestReadyForReview(input: {pullRequestId: $id}) { pullRequest { isDraft } } }',
+    variables: { id: pullRequestNodeId },
+  });
+  const succeeded =
+    response.status === HTTP_OK &&
+    isRecord(response.body) &&
+    response.body.errors === undefined;
+  if (!succeeded) {
+    throw new Error(apiError('mark PR ready for review', response));
+  }
+};

package/src/poller-github-write.ts

@@ -0,0 +1,87 @@
+// Write-side label and comment operations for the poller. Kept apart from the
+// read helpers so each module stays a single reviewable concern.
+
+import { apiError, HTTP_CREATED, HTTP_OK, request } from './github-api';
+import { isRecord } from './github-settings-parse';
+
+const HTTP_NOT_FOUND = 404;
+
+export const addLabels = async (
+  token: string | null,
+  repo: string,
+  issueNumber: number,
+  labels: ReadonlyArray<string>,
+): Promise<void> => {
+  const response = await request(
+    token,
+    'POST',
+    `/repos/${repo}/issues/${issueNumber}/labels`,
+    { labels: [...labels] },
+  );
+  if (response.status !== HTTP_OK) {
+    throw new Error(
+      apiError(`add ${labels.join(', ')} to ${repo}#${issueNumber}`, response),
+    );
+  }
+};
+
+// Removing an already-absent label is success, not failure: ticks are
+// re-runnable and a crashed predecessor may have completed this step.
+export const removeLabel = async (
+  token: string | null,
+  repo: string,
+  issueNumber: number,
+  label: string,
+): Promise<void> => {
+  const response = await request(
+    token,
+    'DELETE',
+    `/repos/${repo}/issues/${issueNumber}/labels/${encodeURIComponent(label)}`,
+  );
+  if (response.status !== HTTP_OK && response.status !== HTTP_NOT_FOUND) {
+    throw new Error(
+      apiError(`remove ${label} from ${repo}#${issueNumber}`, response),
+    );
+  }
+};
+
+export const createIssue = async (
+  token: string | null,
+  repo: string,
+  options: {
+    readonly title: string;
+    readonly body: string;
+    readonly labels: ReadonlyArray<string>;
+  },
+): Promise<void> => {
+  const response = await request(token, 'POST', `/repos/${repo}/issues`, {
+    title: options.title,
+    body: options.body,
+    labels: [...options.labels],
+  });
+  if (response.status !== HTTP_CREATED) {
+    throw new Error(apiError(`create issue in ${repo}`, response));
+  }
+};
+
+export const createComment = async (
+  token: string | null,
+  repo: string,
+  issueNumber: number,
+  body: string,
+): Promise<number> => {
+  const response = await request(
+    token,
+    'POST',
+    `/repos/${repo}/issues/${issueNumber}/comments`,
+    { body },
+  );
+  if (
+    response.status !== HTTP_CREATED ||
+    !isRecord(response.body) ||
+    typeof response.body.id !== 'number'
+  ) {
+    throw new Error(apiError(`comment on ${repo}#${issueNumber}`, response));
+  }
+  return response.body.id;
+};