@davidvornholt/standards 0.10.1 → 0.11.0

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

package/src/poller-github.ts

@@ -0,0 +1,190 @@
+// Read-side GitHub helpers for the poller. Every function either returns a
+// narrow parsed shape or throws with the failing endpoint in the message; the
+// tick converts per-job throws into reported problems. Lists are always read
+// exhaustively (see github-paginate.ts) — the trust anchor is "the latest
+// label event", which a truncated page would silently falsify.
+
+import { apiError, HTTP_OK, request } from './github-api';
+import { labelIdentity } from './github-label-identity';
+import { listAllPages } from './github-paginate';
+import { isNonEmptyString, isRecord } from './github-settings-parse';
+
+export type IssueItem = {
+  readonly number: number;
+  readonly title: string;
+  readonly body: string;
+  readonly isPullRequest: boolean;
+  readonly labels: ReadonlyArray<string>;
+  readonly authorLogin: string;
+};
+
+export type IssueComment = {
+  readonly id: number;
+  readonly body: string;
+  readonly authorLogin: string;
+  readonly createdAt: string;
+};
+
+export type LabelEvent = {
+  readonly id: number;
+  readonly actorLogin: string;
+  readonly createdAt: string;
+};
+
+const asString = (value: unknown): string =>
+  typeof value === 'string' ? value : '';
+
+const labelNames = (raw: unknown): ReadonlyArray<string> =>
+  Array.isArray(raw)
+    ? raw
+        .map((label) => (isRecord(label) ? asString(label.name) : ''))
+        .filter((name) => name.length > 0)
+    : [];
+
+export const parseIssue = (raw: unknown): IssueItem | null => {
+  if (!(isRecord(raw) && typeof raw.number === 'number')) {
+    return null;
+  }
+  return {
+    number: raw.number,
+    title: asString(raw.title),
+    body: asString(raw.body),
+    isPullRequest: isRecord(raw.pull_request),
+    labels: labelNames(raw.labels),
+    authorLogin: isRecord(raw.user) ? asString(raw.user.login) : '',
+  };
+};
+
+export const getIssue = async (
+  token: string | null,
+  repo: string,
+  issueNumber: number,
+): Promise<IssueItem> => {
+  const response = await request(
+    token,
+    'GET',
+    `/repos/${repo}/issues/${issueNumber}`,
+  );
+  const issue = response.status === HTTP_OK ? parseIssue(response.body) : null;
+  if (issue === null) {
+    throw new Error(apiError(`read ${repo}#${issueNumber}`, response));
+  }
+  return issue;
+};
+
+export const listOpenIssuesWithLabel = async (
+  token: string | null,
+  repo: string,
+  label: string,
+): Promise<ReadonlyArray<IssueItem>> => {
+  const items = await listAllPages(
+    token,
+    `/repos/${repo}/issues?state=open&labels=${encodeURIComponent(label)}`,
+    `list ${repo} issues labeled ${label}`,
+  );
+  return items
+    .map(parseIssue)
+    .filter((issue): issue is IssueItem => issue !== null);
+};
+
+export const listIssueComments = async (
+  token: string | null,
+  repo: string,
+  issueNumber: number,
+): Promise<ReadonlyArray<IssueComment>> => {
+  const items = await listAllPages(
+    token,
+    `/repos/${repo}/issues/${issueNumber}/comments`,
+    `list ${repo}#${issueNumber} comments`,
+  );
+  return items.flatMap((raw) => {
+    if (!(isRecord(raw) && typeof raw.id === 'number')) {
+      return [];
+    }
+    return [
+      {
+        id: raw.id,
+        body: asString(raw.body),
+        authorLogin: isRecord(raw.user) ? asString(raw.user.login) : '',
+        createdAt: asString(raw.created_at),
+      },
+    ];
+  });
+};
+
+// The most recent `labeled` event for a label, from the full issue timeline.
+// This is the poller's trust anchor (who approved) and its claim clock (when
+// the in-progress label was applied); reading anything less than the full
+// timeline would let a stale event stand in for the latest one.
+export const lastLabelEvent = async (
+  token: string | null,
+  repo: string,
+  issueNumber: number,
+  label: string,
+): Promise<LabelEvent | null> => {
+  const expectedIdentity = labelIdentity(label);
+  const events = await listAllPages(
+    token,
+    `/repos/${repo}/issues/${issueNumber}/timeline`,
+    `read ${repo}#${issueNumber} timeline`,
+  );
+  let latest: LabelEvent | null = null;
+  for (const raw of events) {
+    if (
+      isRecord(raw) &&
+      typeof raw.id === 'number' &&
+      raw.event === 'labeled' &&
+      isRecord(raw.label) &&
+      typeof raw.label.name === 'string' &&
+      labelIdentity(raw.label.name) === expectedIdentity &&
+      isRecord(raw.actor) &&
+      isNonEmptyString(raw.actor.login) &&
+      isNonEmptyString(raw.created_at)
+    ) {
+      latest = {
+        id: raw.id,
+        actorLogin: raw.actor.login,
+        createdAt: raw.created_at,
+      };
+    }
+  }
+  return latest;
+};
+
+// role_name distinguishes maintain from write; the legacy `permission` field
+// collapses both to "write" and cannot express the trust boundary. A 404
+// means "not a collaborator" — an untrusted answer, not an API failure.
+export const collaboratorRole = async (
+  token: string | null,
+  repo: string,
+  username: string,
+): Promise<string> => {
+  const HttpNotFound = 404;
+  const response = await request(
+    token,
+    'GET',
+    `/repos/${repo}/collaborators/${encodeURIComponent(username)}/permission`,
+  );
+  if (response.status === HttpNotFound) {
+    return 'none';
+  }
+  if (response.status !== HTTP_OK || !isRecord(response.body)) {
+    throw new Error(apiError(`read ${repo} role for ${username}`, response));
+  }
+  return asString(response.body.role_name);
+};
+
+export const repoDefaultBranch = async (
+  token: string | null,
+  repo: string,
+): Promise<string> => {
+  const response = await request(token, 'GET', `/repos/${repo}`);
+  if (
+    response.status !== HTTP_OK ||
+    !isRecord(response.body) ||
+    !isNonEmptyString(response.body.default_branch)
+  ) {
+    throw new Error(apiError(`read ${repo} default branch`, response));
+  }
+  return response.body.default_branch;
+};

package/src/poller-job-shared.ts

@@ -0,0 +1,132 @@
+// Shared job plumbing for fix and review runs: the failure and question
+// transitions are identical state-machine moves, parameterized only by which
+// approval/progress/failure labels the job family uses.
+
+import { hasLabel } from './github-label-identity';
+import { type ApprovalBinding, readApprovalBinding } from './poller-approval';
+import type { PollerConfig } from './poller-config';
+import { addLabels, createComment, removeLabel } from './poller-github-write';
+import {
+  FAILURE_MARKER,
+  NEEDS_CLARIFICATION,
+  QUESTION_MARKER,
+} from './poller-protocol';
+import { answerState, type RoleCache } from './poller-trust';
+
+export type JobDeps = {
+  readonly config: PollerConfig;
+  readonly token: string | null;
+  readonly repo: string;
+  readonly roleCache: RoleCache;
+};
+
+export type JobResult = {
+  readonly lines: ReadonlyArray<string>;
+  readonly ranCodex: boolean;
+};
+
+export type JobLabels = {
+  readonly approved: string;
+  readonly inProgress: string;
+  readonly failed: string;
+};
+
+const FAILURE_SNIPPET_LIMIT = 1500;
+
+export type JobPreamble =
+  | { readonly kind: 'rejected' }
+  | { readonly kind: 'waiting' }
+  | {
+      readonly kind: 'go';
+      readonly answers: ReadonlyArray<string>;
+      readonly approval: ApprovalBinding;
+    };
+
+// The shared front half of every job: verify the approval's actor, then
+// resolve the question/answer state. Both job families make exactly these
+// moves, differing only in which labels they use.
+export const jobPreamble = async (
+  deps: JobDeps,
+  item: { readonly number: number; readonly labels: ReadonlyArray<string> },
+  labels: JobLabels,
+  target: string,
+): Promise<JobPreamble> => {
+  const trust = {
+    token: deps.token,
+    repo: deps.repo,
+    issueNumber: item.number,
+    roleCache: deps.roleCache,
+  };
+  const approval = await readApprovalBinding(trust, labels.approved, target);
+  if (typeof approval === 'string') {
+    await removeLabel(deps.token, deps.repo, item.number, labels.approved);
+    await createComment(
+      deps.token,
+      deps.repo,
+      item.number,
+      `${FAILURE_MARKER}\nApproval not honored: ${approval}`,
+    );
+    return { kind: 'rejected' };
+  }
+  const answers = await answerState(trust);
+  if (answers.waiting) {
+    if (!hasLabel(item.labels, NEEDS_CLARIFICATION)) {
+      await addLabels(deps.token, deps.repo, item.number, [
+        NEEDS_CLARIFICATION,
+      ]);
+    }
+    await removeLabel(deps.token, deps.repo, item.number, labels.inProgress);
+    return { kind: 'waiting' };
+  }
+  if (hasLabel(item.labels, NEEDS_CLARIFICATION)) {
+    await removeLabel(deps.token, deps.repo, item.number, NEEDS_CLARIFICATION);
+  }
+  return { kind: 'go', answers: answers.answers, approval };
+};
+
+export const failJob = async (
+  deps: JobDeps,
+  labels: JobLabels,
+  issueNumber: number,
+  reason: string,
+): Promise<void> => {
+  await createComment(
+    deps.token,
+    deps.repo,
+    issueNumber,
+    `${FAILURE_MARKER}\nAutomated run failed and needs a human look:\n\n${reason.slice(0, FAILURE_SNIPPET_LIMIT)}\n\nRe-apply \`${labels.approved}\` after addressing this to retry.`,
+  );
+  await addLabels(deps.token, deps.repo, issueNumber, [labels.failed]);
+  await removeLabel(deps.token, deps.repo, issueNumber, labels.approved);
+  await removeLabel(deps.token, deps.repo, issueNumber, labels.inProgress);
+};
+
+export const askQuestion = async (
+  deps: JobDeps,
+  labels: JobLabels,
+  issueNumber: number,
+  question: string,
+): Promise<void> => {
+  await createComment(
+    deps.token,
+    deps.repo,
+    issueNumber,
+    `${QUESTION_MARKER}\n${question}`,
+  );
+  await addLabels(deps.token, deps.repo, issueNumber, [NEEDS_CLARIFICATION]);
+  await removeLabel(deps.token, deps.repo, issueNumber, labels.inProgress);
+};
+
+// Also clears a failed-label left by an earlier attempt: a completed retry
+// must not keep advertising "needs a human look".
+export const releaseLabels = async (
+  deps: JobDeps,
+  labels: JobLabels,
+  issueNumber: number,
+): Promise<void> => {
+  await removeLabel(deps.token, deps.repo, issueNumber, labels.inProgress);
+  await removeLabel(deps.token, deps.repo, issueNumber, labels.failed);
+  // Approval is the scheduler's retry signal, so remove it only after every
+  // other cleanup write has succeeded.
+  await removeLabel(deps.token, deps.repo, issueNumber, labels.approved);
+};

package/src/poller-outcome.ts

@@ -0,0 +1,136 @@
+// Outcome-file parsing for poller Codex runs: the structured handoff the
+// agent writes into its worktree. Strict validation — an outcome that fails
+// any check is treated as no outcome at all, which routes the job to the
+// explicit failure path instead of acting on half-trusted data.
+
+import { existsSync, rmSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isNonEmptyString, isRecord } from './github-settings-parse';
+import {
+  type DeferredFinding,
+  type FixOutcome,
+  OUTCOME_FILE,
+  type ReviewOutcome,
+} from './poller-protocol';
+
+const readOutcomeRaw = async (workDir: string): Promise<unknown | null> => {
+  const path = join(workDir, OUTCOME_FILE);
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(await readFile(path, 'utf8')) as unknown;
+  } catch {
+    return null;
+  } finally {
+    rmSync(path, { force: true });
+  }
+};
+
+const FIX_STATUSES: ReadonlySet<string> = new Set([
+  'fixed',
+  'question',
+  'stale',
+  'cannot-fix',
+]);
+
+const REVIEW_STATUSES: ReadonlySet<string> = new Set([
+  'reviewed',
+  'question',
+  'cannot-review',
+]);
+
+// Conventional Commit subject: consumers lint PR titles in CI, so a
+// malformed title is caught here instead of as a red check later.
+const PR_TITLE_PATTERN = /^[a-z]+(?:\([^)]+\))?!?: .+/u;
+
+export const readFixOutcome = async (
+  workDir: string,
+): Promise<FixOutcome | null> => {
+  const raw = await readOutcomeRaw(workDir);
+  if (
+    !isRecord(raw) ||
+    typeof raw.status !== 'string' ||
+    !FIX_STATUSES.has(raw.status) ||
+    !isNonEmptyString(raw.summary)
+  ) {
+    return null;
+  }
+  const status = raw.status as FixOutcome['status'];
+  if (status === 'question' && !isNonEmptyString(raw.question)) {
+    return null;
+  }
+  if (
+    status === 'fixed' &&
+    !(
+      isNonEmptyString(raw.prTitle) &&
+      PR_TITLE_PATTERN.test(raw.prTitle) &&
+      isNonEmptyString(raw.prBody)
+    )
+  ) {
+    return null;
+  }
+  return {
+    status,
+    summary: raw.summary,
+    question: typeof raw.question === 'string' ? raw.question : undefined,
+    prTitle: typeof raw.prTitle === 'string' ? raw.prTitle : undefined,
+    prBody: typeof raw.prBody === 'string' ? raw.prBody : undefined,
+  };
+};
+
+export const readReviewOutcome = async (
+  workDir: string,
+): Promise<ReviewOutcome | null> => {
+  const raw = await readOutcomeRaw(workDir);
+  if (
+    !isRecord(raw) ||
+    typeof raw.status !== 'string' ||
+    !REVIEW_STATUSES.has(raw.status) ||
+    !isNonEmptyString(raw.summary)
+  ) {
+    return null;
+  }
+  const status = raw.status as ReviewOutcome['status'];
+  if (status === 'question' && !isNonEmptyString(raw.question)) {
+    return null;
+  }
+  if (status === 'reviewed' && !isNonEmptyString(raw.report)) {
+    return null;
+  }
+  const deferred = parseDeferred(raw.deferred);
+  if (deferred === null) {
+    return null;
+  }
+  return {
+    status,
+    summary: raw.summary,
+    question: typeof raw.question === 'string' ? raw.question : undefined,
+    report: typeof raw.report === 'string' ? raw.report : undefined,
+    deferred,
+  };
+};
+
+const parseDeferred = (raw: unknown): ReadonlyArray<DeferredFinding> | null => {
+  if (raw === undefined) {
+    return [];
+  }
+  if (!Array.isArray(raw)) {
+    return null;
+  }
+  const deferred: Array<DeferredFinding> = [];
+  for (const entry of raw) {
+    if (
+      !(
+        isRecord(entry) &&
+        isNonEmptyString(entry.title) &&
+        isNonEmptyString(entry.body)
+      )
+    ) {
+      return null;
+    }
+    deferred.push({ title: entry.title, body: entry.body });
+  }
+  return deferred;
+};

package/src/poller-output-integrity.ts

@@ -0,0 +1,107 @@
+import { rmSync } from 'node:fs';
+import { runGit, type Workspace } from './poller-workspace';
+
+const lines = (value: string): ReadonlyArray<string> =>
+  value
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+const GIT_OBJECT_ID = /^[0-9a-f]{40}$/u;
+const WHITESPACE = /\s+/u;
+
+export const isGitObjectId = (value: string): boolean =>
+  GIT_OBJECT_ID.test(value);
+
+export const dirtyOutputPaths = (workDir: string): ReadonlyArray<string> =>
+  runGit(
+    [
+      '-C',
+      workDir,
+      'status',
+      '--porcelain=v1',
+      '--no-renames',
+      '-z',
+      '--untracked-files=all',
+    ],
+    null,
+  )
+    .split('\0')
+    .filter((line) => line.length > 0);
+
+export const assertCleanOutputWorktree = (workDir: string): void => {
+  const dirty = dirtyOutputPaths(workDir);
+  if (dirty.length > 0) {
+    throw new Error(
+      `refusing to seal a dirty output worktree:\n${dirty.join('\n')}`,
+    );
+  }
+};
+
+export const singleParentOf = (
+  cloneDir: string,
+  commit: string,
+): string | null => {
+  const [, parent, extra] = runGit(
+    ['-C', cloneDir, 'rev-list', '--parents', '-n', '1', commit],
+    null,
+  )
+    .trim()
+    .split(WHITESPACE);
+  return parent === undefined || extra !== undefined ? null : parent;
+};
+
+export const isAncestor = (
+  cloneDir: string,
+  ancestor: string,
+  descendant: string,
+): boolean => {
+  try {
+    runGit(
+      ['-C', cloneDir, 'merge-base', '--is-ancestor', ancestor, descendant],
+      null,
+    );
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const commitCountBetween = (
+  cloneDir: string,
+  base: string,
+  head: string,
+): number =>
+  Number.parseInt(
+    runGit(['-C', cloneDir, 'rev-list', '--count', `${base}..${head}`], null),
+    10,
+  );
+
+export const changedPathsBetween = (
+  cloneDir: string,
+  base: string,
+  head: string,
+): ReadonlyArray<string> =>
+  lines(runGit(['-C', cloneDir, 'diff', '--name-only', base, head], null));
+
+export const createValidationWorktree = (
+  cloneDir: string,
+  startRef: string,
+  workDir: string,
+): Workspace => {
+  rmSync(workDir, { recursive: true, force: true });
+  runGit(['-C', cloneDir, 'worktree', 'prune'], null);
+  runGit(
+    ['-C', cloneDir, 'worktree', 'add', '--detach', workDir, startRef],
+    null,
+  );
+  const cleanup = (): void => {
+    try {
+      runGit(['-C', cloneDir, 'worktree', 'remove', '--force', workDir], null);
+    } catch {
+      rmSync(workDir, { recursive: true, force: true });
+      runGit(['-C', cloneDir, 'worktree', 'prune'], null);
+    }
+  };
+  return { dir: workDir, baseSha: startRef, cleanup };
+};