@davidvornholt/standards 0.10.1 → 0.11.0

package/src/poller-fix-publication.ts

@@ -0,0 +1,187 @@
+import { issueRevision } from './poller-approval';
+import { type ClaimBinding, validateClaim } from './poller-claim';
+import { type SealedFixOutput, sealFixOutput } from './poller-fix-output';
+import { validateSealedFixOutput } from './poller-fix-validation';
+import { getIssue, type IssueItem } from './poller-github';
+import {
+  createDraftPullRequest,
+  findOpenPullRequestForHead,
+  getPullRequest,
+  updatePullRequest,
+} from './poller-github-pulls';
+import { createComment } from './poller-github-write';
+import {
+  failJob,
+  type JobDeps,
+  type JobLabels,
+  releaseLabels,
+} from './poller-job-shared';
+import {
+  changedWorkspaceQualityManifests,
+  lockedPathsOf,
+} from './poller-protected-paths';
+import {
+  APPROVED_FOR_REVIEW,
+  type FixOutcome,
+  forbiddenDiffPaths,
+} from './poller-protocol';
+import {
+  changedPaths,
+  commitCount,
+  pushBranch,
+  type Workspace,
+} from './poller-workspace';
+
+export type FixPublication = {
+  readonly deps: JobDeps;
+  readonly issue: IssueItem;
+  readonly defaultBranch: string;
+  readonly claim: ClaimBinding;
+  readonly branch: string;
+  readonly cloneDir: string;
+};
+
+const fixPullRequestBody = (output: SealedFixOutput): string =>
+  `<!-- standards-poller:fix issue=${output.issueNumber} approval=${output.approvalId} head=${output.sealedHead} -->\n${output.body}`;
+
+export const validateFixClaim = async (
+  job: Pick<FixPublication, 'deps' | 'issue' | 'claim'>,
+): Promise<void> => {
+  const current = await getIssue(
+    job.deps.token,
+    job.deps.repo,
+    job.issue.number,
+  );
+  const problem = await validateClaim(
+    {
+      token: job.deps.token,
+      repo: job.deps.repo,
+      issueNumber: job.issue.number,
+    },
+    job.claim,
+    issueRevision(current),
+  );
+  if (problem !== null) {
+    throw new Error(`publication blocked: ${problem}`);
+  }
+};
+
+export const publishFixedOutput = async (
+  job: FixPublication,
+  labels: JobLabels,
+  output: SealedFixOutput,
+  push: (() => void) | null,
+): Promise<string> => {
+  const { deps, issue, branch } = job;
+  await validateSealedFixOutput(
+    {
+      deps: job.deps,
+      issueNumber: job.issue.number,
+      defaultBranch: job.defaultBranch,
+      approvalId: job.claim.approval.id,
+      cloneDir: job.cloneDir,
+    },
+    output,
+  );
+  await validateFixClaim(job);
+  push?.();
+  await validateFixClaim(job);
+  const expectedBody = fixPullRequestBody(output);
+  const existing = await findOpenPullRequestForHead(
+    deps.token,
+    deps.repo,
+    branch,
+  );
+  let prNumber: number;
+  if (existing === null) {
+    prNumber = await createDraftPullRequest(deps.token, deps.repo, {
+      title: output.title,
+      body: expectedBody,
+      head: branch,
+      base: job.defaultBranch,
+    });
+  } else {
+    const pr = await getPullRequest(deps.token, deps.repo, existing);
+    if (
+      pr.headRepo !== deps.repo ||
+      pr.headRef !== branch ||
+      pr.headSha !== output.sealedHead ||
+      pr.baseRef !== job.defaultBranch ||
+      !pr.body.startsWith(
+        `<!-- standards-poller:fix issue=${issue.number} approval=${job.claim.approval.id} `,
+      )
+    ) {
+      throw new Error(
+        `existing PR #${existing} does not prove ownership of ${branch}`,
+      );
+    }
+    await validateFixClaim(job);
+    await updatePullRequest(deps.token, deps.repo, existing, {
+      title: output.title,
+      body: expectedBody,
+    });
+    prNumber = existing;
+  }
+  await validateFixClaim(job);
+  await createComment(
+    deps.token,
+    deps.repo,
+    issue.number,
+    `Opened draft PR #${prNumber} for this issue. Apply \`${APPROVED_FOR_REVIEW}\` on the PR to run the automated review-fix pass, or review it directly.`,
+  );
+  await validateFixClaim(job);
+  await releaseLabels(deps, labels, issue.number);
+  return `#${issue.number}: opened draft PR #${prNumber}`;
+};
+
+export const finishFixedJob = async (
+  job: FixPublication & { readonly workspace: Workspace },
+  labels: JobLabels,
+  outcome: FixOutcome,
+): Promise<string> => {
+  const { deps, issue, workspace, branch } = job;
+  if (commitCount(workspace.dir, workspace.baseSha) === 0) {
+    await failJob(
+      deps,
+      labels,
+      issue.number,
+      'run reported "fixed" but produced no commits',
+    );
+    return `#${issue.number}: failed (fixed without commits)`;
+  }
+  const paths = changedPaths(workspace.dir, workspace.baseSha);
+  const forbidden = [
+    ...forbiddenDiffPaths(paths, await lockedPathsOf(workspace.dir)),
+    ...changedWorkspaceQualityManifests(
+      workspace.dir,
+      workspace.baseSha,
+      paths,
+    ),
+  ];
+  if (forbidden.length > 0) {
+    await failJob(
+      deps,
+      labels,
+      issue.number,
+      `the fix modified protected paths, which automation must never do:\n${forbidden.map((path) => `- ${path}`).join('\n')}`,
+    );
+    return `#${issue.number}: failed (protected paths: ${forbidden.join(', ')})`;
+  }
+  const sealed = sealFixOutput(workspace.dir, {
+    repo: deps.repo,
+    issueNumber: issue.number,
+    approvalId: job.claim.approval.id,
+    title: outcome.prTitle ?? '',
+    body: outcome.prBody ?? '',
+    baseSha: workspace.baseSha,
+    commits: commitCount(workspace.dir, workspace.baseSha),
+  });
+  return publishFixedOutput(job, labels, sealed, () =>
+    pushBranch(workspace.dir, {
+      repo: deps.repo,
+      branch,
+      token: deps.token,
+      expectedRemoteSha: '',
+    }),
+  );
+};

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