@davidvornholt/standards 0.10.1 → 0.11.0

package/src/github-settings-merge.ts

@@ -0,0 +1,167 @@
+// Merge logic for the canonical settings file and its repo-owned extension.
+// The seam may only add. Overriding a canonical repository key or redefining a
+// canonical ruleset or label could weaken the canonical floor; GitHub layers
+// multiple rulesets strictest-wins, so adding is always safe. The one
+// subtractive declaration is the ruleset-enforcement opt-out, which skips the
+// ruleset gate entirely rather than weakening any single rule.
+
+import { labelIdentity } from './github-label-identity';
+import {
+  ENFORCEMENT_OPT_OUT,
+  type GithubSettings,
+  isLabelDeclaration,
+  isNamedRuleset,
+  type ParsedGithubSettings,
+} from './github-settings-parse';
+
+const completeSettings = (
+  parsed: ParsedGithubSettings | null,
+): GithubSettings | null => {
+  if (
+    parsed === null ||
+    parsed.repository === null ||
+    parsed.rulesets === null ||
+    parsed.labels === null ||
+    parsed.rulesetEnforcement === null
+  ) {
+    return null;
+  }
+  const rulesets = parsed.rulesets.filter(isNamedRuleset);
+  const labels = parsed.labels.filter(isLabelDeclaration);
+  if (
+    rulesets.length !== parsed.rulesets.length ||
+    labels.length !== parsed.labels.length
+  ) {
+    return null;
+  }
+  return {
+    repository: parsed.repository,
+    rulesets,
+    labels,
+    rulesetEnforcement: parsed.rulesetEnforcement,
+  };
+};
+
+const enforcementMergeProblems = (
+  local: ParsedGithubSettings | null,
+): ReadonlyArray<string> => {
+  if (
+    local?.rulesetEnforcement !== ENFORCEMENT_OPT_OUT ||
+    local.rulesets === null ||
+    local.rulesets.length === 0
+  ) {
+    return [];
+  }
+  return [
+    `.github/settings.local.json declares additional rulesets while "rulesetEnforcement" is "${ENFORCEMENT_OPT_OUT}"; remove the rulesets or the opt-out`,
+  ];
+};
+
+const repositoryMergeProblems = (
+  canonical: ParsedGithubSettings | null,
+  local: ParsedGithubSettings | null,
+): ReadonlyArray<string> => {
+  if (
+    canonical === null ||
+    canonical.repository === null ||
+    local === null ||
+    local.repository === null
+  ) {
+    return [];
+  }
+  const canonicalRepository = canonical.repository;
+  return Object.keys(local.repository)
+    .filter((key) => key in canonicalRepository)
+    .map(
+      (key) =>
+        `.github/settings.local.json repository."${key}" would override a canonical value; canonical settings are read-only`,
+    );
+};
+
+const rulesetMergeProblems = (
+  canonical: ParsedGithubSettings | null,
+  local: ParsedGithubSettings | null,
+): ReadonlyArray<string> => {
+  if (
+    canonical === null ||
+    canonical.rulesets === null ||
+    local === null ||
+    local.rulesets === null
+  ) {
+    return [];
+  }
+  const canonicalNames = new Set(
+    canonical.rulesets.filter(isNamedRuleset).map((ruleset) => ruleset.name),
+  );
+  return local.rulesets
+    .filter(isNamedRuleset)
+    .filter((ruleset) => canonicalNames.has(ruleset.name))
+    .map(
+      (ruleset) =>
+        `.github/settings.local.json ruleset "${ruleset.name}" collides with a canonical ruleset; add a separately named ruleset to tighten further`,
+    );
+};
+
+const labelMergeProblems = (
+  canonical: ParsedGithubSettings | null,
+  local: ParsedGithubSettings | null,
+): ReadonlyArray<string> => {
+  if (
+    canonical === null ||
+    canonical.labels === null ||
+    local === null ||
+    local.labels === null
+  ) {
+    return [];
+  }
+  const canonicalNames = new Set(
+    canonical.labels
+      .filter(isLabelDeclaration)
+      .map((label) => labelIdentity(label.name)),
+  );
+  return local.labels
+    .filter(isLabelDeclaration)
+    .filter((label) => canonicalNames.has(labelIdentity(label.name)))
+    .map(
+      (label) =>
+        `.github/settings.local.json label "${label.name}" collides with a canonical label; canonical labels are read-only`,
+    );
+};
+
+export type MergedSettings = {
+  readonly merged: GithubSettings | null;
+  readonly problems: ReadonlyArray<string>;
+};
+
+export const mergeSettings = (
+  canonical: ParsedGithubSettings | null,
+  local: ParsedGithubSettings | null,
+): MergedSettings => {
+  const problems = [
+    ...enforcementMergeProblems(local),
+    ...repositoryMergeProblems(canonical, local),
+    ...rulesetMergeProblems(canonical, local),
+    ...labelMergeProblems(canonical, local),
+  ];
+  const completeCanonical = completeSettings(canonical);
+  const completeLocal = completeSettings(local);
+  if (
+    problems.length > 0 ||
+    completeCanonical === null ||
+    completeLocal === null
+  ) {
+    return { merged: null, problems };
+  }
+  return {
+    merged: {
+      repository: {
+        ...completeCanonical.repository,
+        ...completeLocal.repository,
+      },
+      rulesets: [...completeCanonical.rulesets, ...completeLocal.rulesets],
+      labels: [...completeCanonical.labels, ...completeLocal.labels],
+      rulesetEnforcement: completeLocal.rulesetEnforcement,
+    },
+    problems: [],
+  };
+};

package/src/github-settings-parse.ts

@@ -4,21 +4,34 @@
 // github-diff.ts, and the API interaction in github-api.ts. Like cli.ts, this
 // module is zero-dependency so `bunx` can execute the published package.
 
+import { labelIdentity } from './github-label-identity';
+
 // GitHub only enforces rulesets on private repositories on paid plans. The
 // seam can declare that fact so the gate skips rulesets loudly instead of
 // failing closed forever (personal accounts) or trusting rulesets the API
 // reports as active but a free-plan organization silently does not enforce.
 export type RulesetEnforcement = 'enforced' | 'unavailable-on-plan';
 
+// Declared issue labels are an additive floor like rulesets: declared labels
+// must exist with the declared color and description; extra live labels are
+// not drift. The fix-poller protocol labels ride this seam to every consumer.
+export type LabelDeclaration = {
+  readonly name: string;
+  readonly color: string;
+  readonly description: string;
+};
+
 export type GithubSettings = {
   readonly repository: Readonly<Record<string, unknown>>;
   readonly rulesets: ReadonlyArray<Readonly<Record<string, unknown>>>;
+  readonly labels: ReadonlyArray<LabelDeclaration>;
   readonly rulesetEnforcement: RulesetEnforcement;
 };
 
 export type ParsedGithubSettings = {
   readonly repository: Readonly<Record<string, unknown>> | null;
   readonly rulesets: ReadonlyArray<unknown> | null;
+  readonly labels: ReadonlyArray<unknown> | null;
   readonly rulesetEnforcement: RulesetEnforcement | null;
 };
 
@@ -33,9 +46,21 @@ export const isNamedRuleset = (
 ): value is Readonly<Record<string, unknown>> & { readonly name: string } =>
   isRecord(value) && typeof value.name === 'string' && value.name.length > 0;
 
+const LABEL_COLOR = /^[0-9a-f]{6}$/u;
+const LABEL_DECLARATION_KEY_COUNT = 3;
+
+export const isLabelDeclaration = (value: unknown): value is LabelDeclaration =>
+  isRecord(value) &&
+  Object.keys(value).length === LABEL_DECLARATION_KEY_COUNT &&
+  isNonEmptyString(value.name) &&
+  typeof value.color === 'string' &&
+  LABEL_COLOR.test(value.color) &&
+  isNonEmptyString(value.description);
+
 export const SETTINGS_KEYS: ReadonlySet<string> = new Set([
   'repository',
   'rulesets',
+  'labels',
 ]);
 export const LOCAL_SETTINGS_KEYS: ReadonlySet<string> = new Set([
   ...SETTINGS_KEYS,
@@ -78,6 +103,51 @@ const rulesetListProblems = (
   return problems;
 };
 
+const labelListProblems = (
+  labels: ReadonlyArray<unknown>,
+  label: string,
+): ReadonlyArray<string> => {
+  const problems: Array<string> = [];
+  const names = new Set<string>();
+  for (const [index, declaration] of labels.entries()) {
+    if (!isLabelDeclaration(declaration)) {
+      problems.push(
+        `${label} labels[${index}] must be {"name","color","description"} with a non-empty name, a 6-digit lowercase hex color, and a non-empty description`,
+      );
+    } else if (names.has(labelIdentity(declaration.name))) {
+      problems.push(
+        `${label} declares label "${declaration.name}" more than once`,
+      );
+    } else {
+      names.add(labelIdentity(declaration.name));
+    }
+  }
+  return problems;
+};
+
+type ListField = {
+  readonly label: string;
+  readonly field: string;
+  readonly listProblems: (
+    list: ReadonlyArray<unknown>,
+    label: string,
+  ) => ReadonlyArray<string>;
+};
+
+const parseDeclarationList = (
+  raw: unknown,
+  options: ListField,
+  problems: Array<string>,
+): ReadonlyArray<unknown> | null => {
+  const list = raw ?? [];
+  if (!Array.isArray(list)) {
+    problems.push(`${options.label} "${options.field}" must be an array`);
+    return null;
+  }
+  problems.push(...options.listProblems(list, options.label));
+  return list;
+};
+
 export const parseSettings = (
   raw: unknown,
   label: string,
@@ -96,12 +166,16 @@ export const parseSettings = (
   if (!isRecord(repository)) {
     problems.push(`${label} "repository" must be an object`);
   }
-  const rulesets = raw.rulesets ?? [];
-  if (Array.isArray(rulesets)) {
-    problems.push(...rulesetListProblems(rulesets, label));
-  } else {
-    problems.push(`${label} "rulesets" must be an array`);
-  }
+  const rulesets = parseDeclarationList(
+    raw.rulesets,
+    { label, field: 'rulesets', listProblems: rulesetListProblems },
+    problems,
+  );
+  const labels = parseDeclarationList(
+    raw.labels,
+    { label, field: 'labels', listProblems: labelListProblems },
+    problems,
+  );
   // Only the opt-out value is accepted: enforcement is the default, and an
   // explicit "enforced" would be a second way to spell the same state.
   if (
@@ -115,7 +189,8 @@ export const parseSettings = (
   return {
     settings: {
       repository: isRecord(repository) ? repository : null,
-      rulesets: Array.isArray(rulesets) ? rulesets : null,
+      rulesets,
+      labels,
       rulesetEnforcement: parseRulesetEnforcement(raw.rulesetEnforcement),
     },
     problems,

package/src/github-settings.ts

@@ -1,12 +1,12 @@
-// Merge canonical GitHub settings with the repo-owned extension. Parsing,
-// drift, and API work live in named modules; this stays dependency-free.
+// Load and merge canonical GitHub settings with the repo-owned extension.
+// Parsing lives in github-settings-parse.ts, merge policy in
+// github-settings-merge.ts, drift in github-diff.ts, and API work in
+// github-api.ts; this stays dependency-free.
 
+import { mergeSettings } from './github-settings-merge';
 import {
-  ENFORCEMENT_OPT_OUT,
   type GithubSettings,
-  isNamedRuleset,
   LOCAL_SETTINGS_KEYS,
-  type ParsedGithubSettings,
   parseSettings,
   SETTINGS_KEYS,
 } from './github-settings-parse';
@@ -16,124 +16,6 @@ export type LoadedGithubSettings = {
   readonly problems: ReadonlyArray<string>;
 };
 
-const completeSettings = (
-  parsed: ParsedGithubSettings | null,
-): GithubSettings | null => {
-  if (
-    parsed === null ||
-    parsed.repository === null ||
-    parsed.rulesets === null ||
-    parsed.rulesetEnforcement === null
-  ) {
-    return null;
-  }
-  const rulesets = parsed.rulesets.filter(isNamedRuleset);
-  if (rulesets.length !== parsed.rulesets.length) {
-    return null;
-  }
-  return {
-    repository: parsed.repository,
-    rulesets,
-    rulesetEnforcement: parsed.rulesetEnforcement,
-  };
-};
-
-const enforcementMergeProblems = (
-  local: ParsedGithubSettings | null,
-): ReadonlyArray<string> => {
-  if (
-    local?.rulesetEnforcement !== ENFORCEMENT_OPT_OUT ||
-    local.rulesets === null ||
-    local.rulesets.length === 0
-  ) {
-    return [];
-  }
-  return [
-    `.github/settings.local.json declares additional rulesets while "rulesetEnforcement" is "${ENFORCEMENT_OPT_OUT}"; remove the rulesets or the opt-out`,
-  ];
-};
-
-const repositoryMergeProblems = (
-  canonical: ParsedGithubSettings | null,
-  local: ParsedGithubSettings | null,
-): ReadonlyArray<string> => {
-  if (
-    canonical === null ||
-    canonical.repository === null ||
-    local === null ||
-    local.repository === null
-  ) {
-    return [];
-  }
-  const canonicalRepository = canonical.repository;
-  return Object.keys(local.repository)
-    .filter((key) => key in canonicalRepository)
-    .map(
-      (key) =>
-        `.github/settings.local.json repository."${key}" would override a canonical value; canonical settings are read-only`,
-    );
-};
-
-const rulesetMergeProblems = (
-  canonical: ParsedGithubSettings | null,
-  local: ParsedGithubSettings | null,
-): ReadonlyArray<string> => {
-  if (
-    canonical === null ||
-    canonical.rulesets === null ||
-    local === null ||
-    local.rulesets === null
-  ) {
-    return [];
-  }
-  const canonicalNames = new Set(
-    canonical.rulesets.filter(isNamedRuleset).map((ruleset) => ruleset.name),
-  );
-  return local.rulesets
-    .filter(isNamedRuleset)
-    .filter((ruleset) => canonicalNames.has(ruleset.name))
-    .map(
-      (ruleset) =>
-        `.github/settings.local.json ruleset "${ruleset.name}" collides with a canonical ruleset; add a separately named ruleset to tighten further`,
-    );
-};
-
-// The seam may only add. Overriding a canonical repository key or redefining a
-// canonical ruleset could weaken the canonical floor; GitHub layers multiple
-// rulesets strictest-wins, so adding a ruleset is always safe. The one
-// subtractive declaration is the ruleset-enforcement opt-out, which skips the
-// ruleset gate entirely rather than weakening any single rule.
-const mergeSettings = (
-  canonical: ParsedGithubSettings | null,
-  local: ParsedGithubSettings | null,
-) => {
-  const problems = [
-    ...enforcementMergeProblems(local),
-    ...repositoryMergeProblems(canonical, local),
-    ...rulesetMergeProblems(canonical, local),
-  ];
-  const completeCanonical = completeSettings(canonical);
-  const completeLocal = completeSettings(local);
-  if (
-    problems.length > 0 ||
-    completeCanonical === null ||
-    completeLocal === null
-  ) {
-    return { merged: null, problems };
-  }
-  return {
-    merged: {
-      repository: {
-        ...completeCanonical.repository,
-        ...completeLocal.repository,
-      },
-      rulesets: [...completeCanonical.rulesets, ...completeLocal.rulesets],
-      rulesetEnforcement: completeLocal.rulesetEnforcement,
-    },
-    problems: [],
-  };
-};
-
 type JsonParse = {
   readonly value: unknown;
   readonly problem: string | null;

package/src/poller-approval.ts

@@ -0,0 +1,80 @@
+import { createHash } from 'node:crypto';
+import { hasLabel } from './github-label-identity';
+import {
+  collaboratorRole,
+  getIssue,
+  type IssueItem,
+  lastLabelEvent,
+} from './poller-github';
+import { isTrustedRole } from './poller-protocol';
+
+export type ApprovalBinding = {
+  readonly id: string;
+  readonly repo: string;
+  readonly issueNumber: number;
+  readonly eventId: number;
+  readonly label: string;
+  readonly actorLogin: string;
+  readonly approvedAt: string;
+  readonly target: string;
+};
+
+type ApprovalContext = {
+  readonly token: string | null;
+  readonly repo: string;
+  readonly issueNumber: number;
+};
+
+const stableDigest = (value: unknown): string =>
+  createHash('sha256').update(JSON.stringify(value)).digest('hex');
+
+export const issueRevision = (issue: IssueItem): string =>
+  `issue:${stableDigest({ title: issue.title, body: issue.body })}`;
+
+export const prRevision = (
+  baseRef: string,
+  baseSha: string,
+  headSha: string,
+): string => `pr:${stableDigest({ baseRef, baseSha, headSha })}`;
+
+export const readApprovalBinding = async (
+  context: ApprovalContext,
+  label: string,
+  target: string,
+): Promise<ApprovalBinding | string> => {
+  const issue = await getIssue(
+    context.token,
+    context.repo,
+    context.issueNumber,
+  );
+  if (!hasLabel(issue.labels, label)) {
+    return `"${label}" is not currently present on ${context.repo}#${context.issueNumber}`;
+  }
+  const event = await lastLabelEvent(
+    context.token,
+    context.repo,
+    context.issueNumber,
+    label,
+  );
+  if (event === null) {
+    return `no "${label}" label event found on ${context.repo}#${context.issueNumber}`;
+  }
+  const role = await collaboratorRole(
+    context.token,
+    context.repo,
+    event.actorLogin,
+  );
+  if (!isTrustedRole(role)) {
+    return `"${label}" on ${context.repo}#${context.issueNumber} was applied by ${event.actorLogin} (role: ${role}); only admin or maintain roles may approve automation`;
+  }
+  const fields = {
+    repo: context.repo,
+    issueNumber: context.issueNumber,
+    eventId: event.id,
+    label,
+    actorLogin: event.actorLogin,
+    approvedAt: event.createdAt,
+    target,
+  };
+  return { id: stableDigest(fields), ...fields };
+};

package/src/poller-claim.ts

@@ -0,0 +1,154 @@
+import { randomUUID } from 'node:crypto';
+import { hasLabel } from './github-label-identity';
+import { type ApprovalBinding, readApprovalBinding } from './poller-approval';
+import {
+  collaboratorRole,
+  getIssue,
+  type IssueComment,
+  lastLabelEvent,
+  listIssueComments,
+} from './poller-github';
+import { createComment } from './poller-github-write';
+import { CLAIM_MARKER, isTrustedRole } from './poller-protocol';
+
+export type ClaimBinding = {
+  readonly approval: ApprovalBinding;
+  readonly claimLabel: string;
+  readonly claimEpoch: string;
+  readonly markerId: number;
+};
+
+type ClaimMarker = Omit<ClaimBinding, 'markerId'> & {
+  readonly nonce: string;
+};
+
+type ClaimContext = {
+  readonly token: string | null;
+  readonly repo: string;
+  readonly issueNumber: number;
+};
+
+const markerBody = (marker: ClaimMarker): string =>
+  `${CLAIM_MARKER}\n${JSON.stringify(marker)}`;
+
+const parseMarker = (comment: IssueComment): ClaimMarker | null => {
+  if (!comment.body.startsWith(`${CLAIM_MARKER}\n`)) {
+    return null;
+  }
+  try {
+    const raw = JSON.parse(comment.body.slice(CLAIM_MARKER.length + 1)) as {
+      readonly approval?: ApprovalBinding;
+      readonly claimLabel?: unknown;
+      readonly claimEpoch?: unknown;
+      readonly nonce?: unknown;
+    };
+    if (
+      typeof raw.claimLabel !== 'string' ||
+      typeof raw.claimEpoch !== 'string' ||
+      typeof raw.nonce !== 'string' ||
+      raw.approval === undefined ||
+      typeof raw.approval.id !== 'string'
+    ) {
+      return null;
+    }
+    return {
+      approval: raw.approval,
+      claimLabel: raw.claimLabel,
+      claimEpoch: raw.claimEpoch,
+      nonce: raw.nonce,
+    };
+  } catch {
+    return null;
+  }
+};
+
+const winningMarkerId = async (
+  context: ClaimContext,
+  binding: Omit<ClaimBinding, 'markerId'>,
+): Promise<number | null> => {
+  const comments = await listIssueComments(
+    context.token,
+    context.repo,
+    context.issueNumber,
+  );
+  let winner: number | null = null;
+  for (const comment of comments) {
+    const marker = parseMarker(comment);
+    const differs =
+      marker?.approval.id !== binding.approval.id ||
+      marker.claimLabel !== binding.claimLabel ||
+      marker.claimEpoch !== binding.claimEpoch;
+    if (!differs) {
+      // biome-ignore lint/performance/noAwaitInLoops: claim authors must be checked against their current role; the usually-one-item list is deliberately fail-closed.
+      const role = await collaboratorRole(
+        context.token,
+        context.repo,
+        comment.authorLogin,
+      );
+      if (isTrustedRole(role) && (winner === null || comment.id < winner)) {
+        winner = comment.id;
+      }
+    }
+  }
+  return winner;
+};
+
+export const acquireClaim = async (
+  context: ClaimContext,
+  approval: ApprovalBinding,
+  claimLabel: string,
+): Promise<ClaimBinding | null> => {
+  const event = await lastLabelEvent(
+    context.token,
+    context.repo,
+    context.issueNumber,
+    claimLabel,
+  );
+  if (event === null) {
+    throw new Error(`no "${claimLabel}" claim event found`);
+  }
+  const provisional = {
+    approval,
+    claimLabel,
+    claimEpoch: String(event.id),
+  };
+  const nonce = randomUUID();
+  const markerId = await createComment(
+    context.token,
+    context.repo,
+    context.issueNumber,
+    markerBody({ ...provisional, nonce }),
+  );
+  const winner = await winningMarkerId(context, provisional);
+  return winner === markerId ? { ...provisional, markerId } : null;
+};
+
+export const validateClaim = async (
+  context: ClaimContext,
+  claim: ClaimBinding,
+  currentTarget: string,
+): Promise<string | null> => {
+  const current = await readApprovalBinding(
+    context,
+    claim.approval.label,
+    currentTarget,
+  );
+  if (typeof current === 'string') {
+    return current;
+  }
+  if (current.id !== claim.approval.id) {
+    return 'approval no longer matches the exact approved revision/head';
+  }
+  const issue = await getIssue(
+    context.token,
+    context.repo,
+    context.issueNumber,
+  );
+  if (!hasLabel(issue.labels, claim.claimLabel)) {
+    return `"${claim.claimLabel}" is no longer present`;
+  }
+  const winner = await winningMarkerId(context, claim);
+  return winner === claim.markerId
+    ? null
+    : 'claim ownership changed or could not be proven';
+};