@davidvornholt/standards 0.10.2 → 0.11.1

package/src/github-live-drift.ts

@@ -6,7 +6,9 @@ import {
   apiError,
   fetchLiveRulesets,
   fetchMergeSettingsViaGraphql,
+  HTTP_FORBIDDEN,
   HTTP_OK,
+  HTTP_UNAUTHORIZED,
   request,
   resolveGithubRepo,
   resolveToken,
@@ -17,8 +19,25 @@ import {
   unverifiableProblem,
 } from './github-command-shared';
 import { diffRepositorySettings, diffRulesets } from './github-diff';
+import { diffLabels, fetchLiveLabels } from './github-labels';
+import { GithubListResponseError } from './github-paginate';
 import { type GithubSettings, isRecord } from './github-settings-parse';
 
+const LABEL_VISIBILITY_PROBLEM =
+  'declared labels not visible to this token, so the gate cannot verify them. In CI, use a valid ci.github_settings_read_token from secrets/ci.yaml with read-only "Issues" access (or "Pull requests" read); locally use a token with one of those permissions';
+const PERMISSION_DENIAL_MESSAGES: ReadonlySet<string> = new Set([
+  'Resource not accessible by integration',
+  'Resource not accessible by personal access token',
+]);
+
+const isLabelPermissionDenial = (error: unknown): boolean =>
+  error instanceof GithubListResponseError &&
+  (error.status === HTTP_UNAUTHORIZED ||
+    (error.status === HTTP_FORBIDDEN &&
+      isRecord(error.responseBody) &&
+      typeof error.responseBody.message === 'string' &&
+      PERMISSION_DENIAL_MESSAGES.has(error.responseBody.message)));
+
 const repositoryDrift = async (
   token: string | null,
   repo: string,
@@ -87,11 +106,21 @@ export const collectLiveDrift = async (
   }
   const token = resolveToken();
   try {
+    // No declared labels means nothing to verify — skipping the fetch is
+    // exact, not lenient.
+    const labelDrift =
+      declared.labels.length === 0
+        ? []
+        : diffLabels(declared.labels, await fetchLiveLabels(token, repo));
     return [
       ...(await repositoryDrift(token, repo, declared)),
       ...(await rulesetDrift(token, repo, declared)),
+      ...labelDrift,
     ];
   } catch (error) {
+    if (isLabelPermissionDenial(error)) {
+      return [LABEL_VISIBILITY_PROBLEM];
+    }
     return [
       `GitHub API unreachable: ${error instanceof Error ? error.message : String(error)}`,
     ];

package/src/github-paginate.ts

@@ -0,0 +1,49 @@
+// Exhaustive pagination for GitHub list endpoints. Single-page reads are a
+// correctness hazard everywhere the caller needs "the latest" or "all" of
+// something: a truncated timeline mis-attributes label approvals, truncated
+// comments break answer detection, and truncated label lists read as drift.
+// Overflow past the page cap fails loudly instead of silently truncating.
+
+import { type ApiResponse, apiError, HTTP_OK, request } from './github-api';
+
+const PAGE_SIZE = 100;
+const MAX_PAGES = 30;
+
+export class GithubListResponseError extends Error {
+  readonly responseBody: unknown;
+  readonly status: number;
+
+  constructor(context: string, response: ApiResponse) {
+    super(apiError(context, response));
+    this.name = 'GithubListResponseError';
+    this.responseBody = response.body;
+    this.status = response.status;
+  }
+}
+
+export const listAllPages = async (
+  token: string | null,
+  path: string,
+  context: string,
+): Promise<ReadonlyArray<unknown>> => {
+  const items: Array<unknown> = [];
+  const separator = path.includes('?') ? '&' : '?';
+  for (let page = 1; page <= MAX_PAGES; page += 1) {
+    // biome-ignore lint/performance/noAwaitInLoops: pages are sequential by definition; the next request needs to know the previous page was full.
+    const response = await request(
+      token,
+      'GET',
+      `${path}${separator}per_page=${PAGE_SIZE}&page=${page}`,
+    );
+    if (response.status !== HTTP_OK || !Array.isArray(response.body)) {
+      throw new GithubListResponseError(context, response);
+    }
+    items.push(...response.body);
+    if (response.body.length < PAGE_SIZE) {
+      return items;
+    }
+  }
+  throw new Error(
+    `${context}: more than ${MAX_PAGES * PAGE_SIZE} items; refusing to act on a truncated list`,
+  );
+};

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/managed-files.ts

@@ -0,0 +1,64 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+
+// Never mirrored, even under a managed directory path: build output, VCS
+// metadata, and installed dependencies would otherwise pollute the lock when
+// syncing from a working tree that has them.
+const IGNORED_DIRECTORIES = new Set([
+  'node_modules',
+  '.git',
+  '.turbo',
+  'dist',
+  '.next',
+]);
+
+const directiveToken = Buffer.from(['biome', 'ignore'].join('-'));
+
+const toPosix = (path: string): string => path.split(sep).join('/');
+
+const walkManagedFiles = async (
+  path: string,
+  repositoryRoot: string,
+  files: Map<string, string>,
+): Promise<void> => {
+  const info = await stat(path).catch(() => null);
+  if (info === null) {
+    return;
+  }
+  if (info.isDirectory()) {
+    const entries = await readdir(path);
+    await Promise.all(
+      entries
+        .filter((entry) => !IGNORED_DIRECTORIES.has(entry))
+        .map((entry) =>
+          walkManagedFiles(join(path, entry), repositoryRoot, files),
+        ),
+    );
+    return;
+  }
+  files.set(toPosix(relative(repositoryRoot, path)), path);
+};
+
+export const listManagedFiles = async (
+  repositoryRoot: string,
+  paths: ReadonlyArray<string>,
+): Promise<ReadonlyMap<string, string>> => {
+  const files = new Map<string, string>();
+  await Promise.all(
+    paths.map((path) =>
+      walkManagedFiles(join(repositoryRoot, path), repositoryRoot, files),
+    ),
+  );
+  return files;
+};
+
+export const findManagedFilesContainingBiomeDirectiveToken = async (
+  files: ReadonlyMap<string, string>,
+): Promise<ReadonlyArray<string>> => {
+  const matches = await Promise.all(
+    [...files].map(async ([path, absolutePath]) =>
+      (await readFile(absolutePath)).includes(directiveToken) ? path : null,
+    ),
+  );
+  return matches.filter((path): path is string => path !== null).sort();
+};

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