@davidvornholt/standards 0.17.3 → 0.19.0

package/src/github-diff.ts

@@ -1,5 +1,6 @@
 // Drift comparison between declared GitHub settings (github-settings.ts) and
-// the live state returned by the GitHub API. Pure logic; no network.
+// the live state returned by the GitHub API. Pure logic; no network. Ruleset
+// comparison lives in github-ruleset-diff.ts.
 
 import { isRecord } from './github-settings-parse';
 
@@ -41,114 +42,6 @@ export const subsetMatches = (declared: unknown, live: unknown): boolean => {
   return declared === live;
 };
 
-const RULESET_COMPARED_KEYS = [
-  'target',
-  'enforcement',
-  'conditions',
-  'bypass_actors',
-] as const;
-
-const diffRules = (
-  name: string,
-  declared: Readonly<Record<string, unknown>>,
-  live: Readonly<Record<string, unknown>>,
-): ReadonlyArray<string> => {
-  const drifted: Array<string> = [];
-  const declaredRules = Array.isArray(declared.rules)
-    ? declared.rules.filter(isRecord)
-    : [];
-  const liveRules = Array.isArray(live.rules)
-    ? live.rules.filter(isRecord)
-    : [];
-  const liveByType = new Map(
-    liveRules.map((rule) => [String(rule.type), rule]),
-  );
-  const declaredTypes = new Set(declaredRules.map((rule) => String(rule.type)));
-  for (const rule of declaredRules) {
-    const type = String(rule.type);
-    const liveRule = liveByType.get(type);
-    const declaredWithoutType = Object.fromEntries(
-      Object.entries(rule).filter(([key]) => key !== 'type'),
-    );
-    if (liveRule === undefined) {
-      drifted.push(`ruleset "${name}": missing rule "${type}"`);
-    } else if (!subsetMatches(declaredWithoutType, liveRule)) {
-      drifted.push(
-        `ruleset "${name}": rule "${type}" differs from the declared configuration`,
-      );
-    }
-  }
-  for (const type of liveByType.keys()) {
-    if (!declaredTypes.has(type)) {
-      drifted.push(`ruleset "${name}": has undeclared extra rule "${type}"`);
-    }
-  }
-  return drifted;
-};
-
-// Some ruleset fields — bypass_actors in particular — are only included in
-// API responses for admin viewers. A declared key that is absent on the live
-// side is unverifiable for this token, not drift: the same policy as
-// repository merge settings, so callers can fail with a targeted
-// missing-visibility message instead of a bogus value mismatch.
-export const diffRuleset = (
-  declared: Readonly<Record<string, unknown>>,
-  live: Readonly<Record<string, unknown>>,
-): SettingsDiff => {
-  const name = String(declared.name);
-  const drifted: Array<string> = [];
-  const unverifiable: Array<string> = [];
-  for (const key of RULESET_COMPARED_KEYS) {
-    if (declared[key] !== undefined) {
-      if (live[key] === undefined) {
-        unverifiable.push(`ruleset "${name}": ${key}`);
-      } else if (!subsetMatches(declared[key], live[key])) {
-        drifted.push(
-          `ruleset "${name}": ${key} differs from the declared configuration`,
-        );
-      }
-    }
-  }
-  drifted.push(...diffRules(name, declared, live));
-  return { drifted, unverifiable };
-};
-
-// Live rulesets must be exactly the declared set: additions, removals, and
-// in-place edits are all drift.
-export const diffRulesets = (
-  declared: ReadonlyArray<Readonly<Record<string, unknown>>>,
-  live: ReadonlyArray<Readonly<Record<string, unknown>>>,
-): SettingsDiff => {
-  const drifted: Array<string> = [];
-  const unverifiable: Array<string> = [];
-  const liveByName = new Map(
-    live.map((ruleset) => [String(ruleset.name), ruleset]),
-  );
-  const declaredNames = new Set(
-    declared.map((ruleset) => String(ruleset.name)),
-  );
-  for (const ruleset of declared) {
-    const liveRuleset = liveByName.get(String(ruleset.name));
-    if (liveRuleset === undefined) {
-      drifted.push(
-        `ruleset "${ruleset.name}" is declared but missing on GitHub`,
-      );
-    } else {
-      const diff = diffRuleset(ruleset, liveRuleset);
-      drifted.push(...diff.drifted);
-      unverifiable.push(...diff.unverifiable);
-    }
-  }
-  for (const name of liveByName.keys()) {
-    if (!declaredNames.has(name)) {
-      drifted.push(
-        `ruleset "${name}" exists on GitHub but is not declared; declare it in .github/settings.local.json or delete it`,
-      );
-    }
-  }
-  return { drifted, unverifiable };
-};
-
 // Repo merge settings are only visible to admin tokens; report invisible keys
 // as unverifiable instead of drifted so callers fail the gate with a
 // missing-visibility message that names the token fix, not a bogus value

package/src/github-graphql.ts

@@ -0,0 +1,198 @@
+// GraphQL fallbacks for repository state REST hides from tokens that can
+// legitimately read it. Each returns only what GraphQL actually answered, so a
+// remaining gap stays unverifiable instead of becoming a false pass.
+
+import { apiError, HTTP_OK, request } from './github-api';
+import { isRecord } from './github-settings-parse';
+
+// The `repository` node GraphQL answered with, or why there is no answer.
+type GraphqlAnswer = {
+  readonly repository: Readonly<Record<string, unknown>> | null;
+  readonly failure: string | null;
+};
+
+const errorSummary = (errors: ReadonlyArray<unknown>): string =>
+  errors
+    .map((error) =>
+      isRecord(error) && typeof error.message === 'string'
+        ? error.message
+        : JSON.stringify(error),
+    )
+    .join('; ');
+
+// GraphQL reports a permission failure as HTTP 200 with a partial `data` and a
+// non-empty `errors` array, so a body carrying errors is no answer at all: a
+// suppressed field that survives as a plausible value — `0` for a count — must
+// never be read as a verified one.
+const queryRepository = async (
+  token: string | null,
+  repo: string,
+  selection: string,
+): Promise<GraphqlAnswer> => {
+  const [owner, name] = repo.split('/');
+  if (owner === undefined || name === undefined) {
+    return {
+      repository: null,
+      failure: `"${repo}" is not an owner/name repository`,
+    };
+  }
+  const response = await request(token, 'POST', '/graphql', {
+    query: `query { repository(owner: ${JSON.stringify(owner)}, name: ${JSON.stringify(name)}) { ${selection} } }`,
+  });
+  if (response.status !== HTTP_OK || !isRecord(response.body)) {
+    return {
+      repository: null,
+      failure: apiError('querying the GraphQL API', response),
+    };
+  }
+  const { errors } = response.body;
+  if (Array.isArray(errors) && errors.length > 0) {
+    return {
+      repository: null,
+      failure: `HTTP ${response.status} ${errorSummary(errors)}`,
+    };
+  }
+  const data = isRecord(response.body.data) ? response.body.data : null;
+  if (data === null || !isRecord(data.repository)) {
+    return {
+      repository: null,
+      failure: `HTTP ${response.status} the response carried no repository`,
+    };
+  }
+  return { repository: data.repository, failure: null };
+};
+
+const GRAPHQL_MERGE_FIELDS: ReadonlyMap<string, string> = new Map([
+  ['allow_auto_merge', 'autoMergeAllowed'],
+  ['allow_merge_commit', 'mergeCommitAllowed'],
+  ['allow_rebase_merge', 'rebaseMergeAllowed'],
+  ['allow_squash_merge', 'squashMergeAllowed'],
+  ['delete_branch_on_merge', 'deleteBranchOnMerge'],
+  ['merge_commit_message', 'mergeCommitMessage'],
+  ['merge_commit_title', 'mergeCommitTitle'],
+  ['squash_merge_commit_message', 'squashMergeCommitMessage'],
+  ['squash_merge_commit_title', 'squashMergeCommitTitle'],
+]);
+
+// REST omits repository merge settings for read-only viewers (they surface
+// only with write access — community discussion #153258), but GraphQL serves
+// the same values, with identical enum spellings, to any token that can read
+// the repository. This keeps a read-only token sufficient for the check.
+// Returns only the keys GraphQL answered; the rest stay unverifiable.
+export const fetchMergeSettingsViaGraphql = async (
+  token: string | null,
+  repo: string,
+  keys: ReadonlyArray<string>,
+): Promise<Readonly<Record<string, unknown>>> => {
+  const mapped = keys.filter((key) => GRAPHQL_MERGE_FIELDS.has(key));
+  if (mapped.length === 0) {
+    return {};
+  }
+  const { repository } = await queryRepository(
+    token,
+    repo,
+    mapped.map((key) => GRAPHQL_MERGE_FIELDS.get(key)).join(' '),
+  );
+  if (repository === null) {
+    return {};
+  }
+  return Object.fromEntries(
+    mapped
+      .map((key) => [key, repository[GRAPHQL_MERGE_FIELDS.get(key) ?? '']])
+      .filter(([, value]) => value !== undefined && value !== null),
+  );
+};
+
+// One page is every ruleset any consumer declares. Nothing rests on that:
+// counts are only ever consulted for rulesets the REST loader listed, and a
+// ruleset GraphQL did not answer for stays unverifiable.
+const GRAPHQL_RULESET_PAGE = 100;
+
+// Asking for one actor makes the count self-corroborating at no extra cost:
+// `totalCount === 0` must yield an empty node list and `totalCount >= 1`
+// exactly one node.
+const BYPASS_ACTOR_PROBE = 1;
+
+// A repository-owned ruleset node paired with its bypass-actor count, keyed by
+// the id REST reports for the same ruleset, or null for anything else.
+// Org-inherited rulesets are outside this declaration's authority, the same
+// filter the REST loader applies. A node list that disagrees with its own
+// `totalCount` means the connection is being filtered rather than merely
+// redacted, so it supplies no count; a null *element* is the documented
+// identity-withholding shape, so only the length is checked.
+const countedRuleset = (node: unknown): readonly [number, number] | null => {
+  if (!isRecord(node) || typeof node.databaseId !== 'number') {
+    return null;
+  }
+  if (!isRecord(node.source) || node.source.__typename !== 'Repository') {
+    return null;
+  }
+  const actors = isRecord(node.bypassActors) ? node.bypassActors : null;
+  if (
+    actors === null ||
+    typeof actors.totalCount !== 'number' ||
+    !Array.isArray(actors.nodes)
+  ) {
+    return null;
+  }
+  const total = actors.totalCount;
+  return total >= 0 &&
+    actors.nodes.length === Math.min(total, BYPASS_ACTOR_PROBE)
+    ? [node.databaseId, total]
+    : null;
+};
+
+// Nothing promises an id appears once in the node list, and a repeated key
+// would silently take the last node's count. Dropping the id entirely degrades
+// it to unverifiable instead.
+const withoutRepeatedIds = (
+  entries: ReadonlyArray<readonly [number, number]>,
+): ReadonlyMap<number, number> => {
+  const seen = new Set<number>();
+  const repeated = new Set<number>();
+  for (const [id] of entries) {
+    if (seen.has(id)) {
+      repeated.add(id);
+    }
+    seen.add(id);
+  }
+  return new Map(entries.filter(([id]) => !repeated.has(id)));
+};
+
+export type BypassActorCounts = {
+  // Keyed by ruleset id, never by name: two live rulesets may share a name, and
+  // joining on it would let a harmless ruleset's count verify a bypassed
+  // ruleset's list.
+  readonly counts: ReadonlyMap<number, number>;
+  readonly failure: string | null;
+};
+
+// REST omits ruleset `bypass_actors` for viewers without repository
+// Administration access, and omits it from GitHub App installation tokens
+// whatever the App's permissions — so a brokered CI token can never read the
+// list there. GraphQL answers `bypassActors` on the same repository-owned
+// rulesets and serves an exact `totalCount` to those tokens, withholding only
+// the actor identities. Returns the count per ruleset id; an id GraphQL did
+// not answer for stays absent, so the caller keeps it unverifiable.
+export const fetchBypassActorCountsViaGraphql = async (
+  token: string | null,
+  repo: string,
+): Promise<BypassActorCounts> => {
+  const answer = await queryRepository(
+    token,
+    repo,
+    `rulesets(first: ${GRAPHQL_RULESET_PAGE}, includeParents: false) { nodes { databaseId source { __typename } bypassActors(first: ${BYPASS_ACTOR_PROBE}) { totalCount nodes { __typename } } } }`,
+  );
+  const rulesets =
+    answer.repository !== null && isRecord(answer.repository.rulesets)
+      ? answer.repository.rulesets
+      : null;
+  const nodes =
+    rulesets !== null && Array.isArray(rulesets.nodes) ? rulesets.nodes : [];
+  return {
+    counts: withoutRepeatedIds(
+      nodes.map(countedRuleset).filter((entry) => entry !== null),
+    ),
+    failure: answer.failure,
+  };
+};

package/src/github-live-drift.ts

@@ -4,8 +4,6 @@
 
 import {
   apiError,
-  fetchLiveRulesets,
-  fetchMergeSettingsViaGraphql,
   HTTP_FORBIDDEN,
   HTTP_OK,
   HTTP_UNAUTHORIZED,
@@ -13,14 +11,27 @@ import {
   resolveGithubRepo,
   resolveToken,
 } from './github-api';
+import { resolveHiddenBypassActors } from './github-bypass-actors';
 import {
+  ADMIN_VISIBILITY_ADVICE,
   enforceableRepositorySettings,
   optOutEligibilityProblem,
   unverifiableProblem,
 } from './github-command-shared';
-import { diffRepositorySettings, diffRulesets } from './github-diff';
+import { diffRepositorySettings } from './github-diff';
+import {
+  fetchBypassActorCountsViaGraphql,
+  fetchMergeSettingsViaGraphql,
+} from './github-graphql';
 import { diffLabels, fetchLiveLabels } from './github-labels';
 import { GithubListResponseError } from './github-paginate';
+import { fetchLiveRulesets } from './github-ruleset-api';
+import { diffRulesets } from './github-ruleset-diff';
+import {
+  GRAPHQL_NOT_CONSULTED,
+  isHiddenBypassActors,
+  rulesetVisibilityProblems,
+} from './github-ruleset-visibility';
 import { type GithubSettings, isRecord } from './github-settings-parse';
 
 const LABEL_VISIBILITY_PROBLEM =
@@ -73,10 +84,29 @@ const repositoryDrift = async (
   });
   return [
     ...rediff.drifted,
-    ...unverifiableProblem('repository setting(s)', rediff.unverifiable),
+    ...unverifiableProblem(
+      'repository setting(s)',
+      rediff.unverifiable,
+      ADMIN_VISIBILITY_ADVICE,
+    ),
   ];
 };
 
+// The live rulesets GraphQL answered a bypass-actor count for, named as the
+// REST response names them so the advice can say whether a hidden list was
+// counted-and-matched or never answered for at all.
+const countedRulesetNames = (
+  live: ReadonlyArray<Readonly<Record<string, unknown>>>,
+  counts: ReadonlyMap<number, number>,
+): ReadonlySet<string> =>
+  new Set(
+    live
+      .filter(
+        (ruleset) => typeof ruleset.id === 'number' && counts.has(ruleset.id),
+      )
+      .map((ruleset) => String(ruleset.name)),
+  );
+
 const rulesetDrift = async (
   token: string | null,
   repo: string,
@@ -90,9 +120,30 @@ const rulesetDrift = async (
     return [live.problem ?? 'unable to read rulesets'];
   }
   const diff = diffRulesets(declared.rulesets, live.rulesets);
+  if (!diff.unverifiable.some(isHiddenBypassActors)) {
+    return [
+      ...diff.drifted,
+      ...rulesetVisibilityProblems(diff.unverifiable, GRAPHQL_NOT_CONSULTED),
+    ];
+  }
+  // REST hides bypass actors from every non-admin token and from installation
+  // tokens outright; retry the hidden lists as GraphQL counts before failing
+  // the gate.
+  const answered = await fetchBypassActorCountsViaGraphql(token, repo);
+  const rediff = diffRulesets(
+    declared.rulesets,
+    resolveHiddenBypassActors(
+      declared.rulesets,
+      live.rulesets,
+      answered.counts,
+    ),
+  );
   return [
-    ...diff.drifted,
-    ...unverifiableProblem('ruleset field(s)', diff.unverifiable),
+    ...rediff.drifted,
+    ...rulesetVisibilityProblems(rediff.unverifiable, {
+      countedNames: countedRulesetNames(live.rulesets, answered.counts),
+      failure: answered.failure,
+    }),
   ];
 };
 

package/src/github-ruleset-api.ts

@@ -0,0 +1,57 @@
+// Loading the live repository rulesets. This lives outside github-api.ts
+// because the exhaustive pagination it needs (github-paginate.ts) is itself
+// built on github-api.ts, and calling it from there would be a mutual import.
+
+import { apiError, HTTP_OK, request } from './github-api';
+import { listAllPages } from './github-paginate';
+import { isRecord } from './github-settings-parse';
+
+export type LiveRulesets = {
+  readonly rulesets: ReadonlyArray<Record<string, unknown>> | null;
+  readonly problem: string | null;
+};
+
+// Only repository-sourced rulesets are managed; org-level rulesets a consumer
+// inherits are outside this declaration's authority. The list really
+// paginates — GitHub serves 30 per page by default and `includes_parents`
+// defaults to true — so a single-page read would hide an undeclared ruleset
+// that happens to land on page two, and the "not declared" branch would never
+// fire for it.
+//
+// listAllPages throws, but the drift collector tells a ruleset read failure
+// apart from a label read failure by the returned problem string, not by the
+// exception, so the throw is converted here rather than propagated.
+export const fetchLiveRulesets = async (
+  token: string | null,
+  repo: string,
+): Promise<LiveRulesets> => {
+  let summaries: ReadonlyArray<unknown>;
+  try {
+    summaries = await listAllPages(
+      token,
+      `/repos/${repo}/rulesets`,
+      'listing rulesets',
+    );
+  } catch (error) {
+    return {
+      rulesets: null,
+      problem: error instanceof Error ? error.message : String(error),
+    };
+  }
+  const repoOwned = summaries
+    .filter(isRecord)
+    .filter((ruleset) => ruleset.source_type === 'Repository');
+  const detailed = await Promise.all(
+    repoOwned.map((ruleset) =>
+      request(token, 'GET', `/repos/${repo}/rulesets/${ruleset.id}`),
+    ),
+  );
+  const failed = detailed.find((response) => response.status !== HTTP_OK);
+  if (failed !== undefined) {
+    return { rulesets: null, problem: apiError('reading a ruleset', failed) };
+  }
+  return {
+    rulesets: detailed.map((response) => response.body).filter(isRecord),
+    problem: null,
+  };
+};

package/src/github-ruleset-diff.ts

@@ -0,0 +1,181 @@
+// Drift comparison for repository rulesets: the declared set
+// (github-settings.ts) against live API state. Pure logic; no network. The
+// general value comparison lives in github-diff.ts.
+
+import { subsetMatches } from './github-diff';
+import { isRecord } from './github-settings-parse';
+
+export const BYPASS_ACTORS_KEY = 'bypass_actors';
+
+// A declared ruleset field the live side did not carry. It stays structured so
+// the caller owns both the wording and the test for *which* field it is;
+// formatting it here and recovering the signal by parsing the message suffix
+// would let a reformat silently disable the bypass-actor fallback.
+export type UnverifiableRulesetField = {
+  readonly key: string;
+  readonly name: string;
+};
+
+export type RulesetDiff = {
+  readonly drifted: ReadonlyArray<string>;
+  readonly unverifiable: ReadonlyArray<UnverifiableRulesetField>;
+};
+
+const RULESET_COMPARED_KEYS = [
+  'target',
+  'enforcement',
+  'conditions',
+  BYPASS_ACTORS_KEY,
+] as const;
+
+const diffRules = (
+  name: string,
+  declared: Readonly<Record<string, unknown>>,
+  live: Readonly<Record<string, unknown>>,
+): ReadonlyArray<string> => {
+  const drifted: Array<string> = [];
+  const declaredRules = Array.isArray(declared.rules)
+    ? declared.rules.filter(isRecord)
+    : [];
+  const liveRules = Array.isArray(live.rules)
+    ? live.rules.filter(isRecord)
+    : [];
+  const liveByType = new Map(
+    liveRules.map((rule) => [String(rule.type), rule]),
+  );
+  const declaredTypes = new Set(declaredRules.map((rule) => String(rule.type)));
+  for (const rule of declaredRules) {
+    const type = String(rule.type);
+    const liveRule = liveByType.get(type);
+    const declaredWithoutType = Object.fromEntries(
+      Object.entries(rule).filter(([key]) => key !== 'type'),
+    );
+    if (liveRule === undefined) {
+      drifted.push(`ruleset "${name}": missing rule "${type}"`);
+    } else if (!subsetMatches(declaredWithoutType, liveRule)) {
+      drifted.push(
+        `ruleset "${name}": rule "${type}" differs from the declared configuration`,
+      );
+    }
+  }
+  for (const type of liveByType.keys()) {
+    if (!declaredTypes.has(type)) {
+      drifted.push(`ruleset "${name}": has undeclared extra rule "${type}"`);
+    }
+  }
+  return drifted;
+};
+
+// Whoever hits bypass-actor drift holds, by construction, a token that cannot
+// name the actors, so the two lengths are the only facts worth printing — and
+// when the live list is stand-ins for a GraphQL count, they are the only facts
+// that exist. Equal lengths mean the identities differ, where a count would
+// say nothing.
+const bypassActorCountDetail = (
+  key: string,
+  declared: unknown,
+  live: unknown,
+): string =>
+  key === BYPASS_ACTORS_KEY &&
+  Array.isArray(declared) &&
+  Array.isArray(live) &&
+  declared.length !== live.length
+    ? ` (GitHub reports ${live.length} bypass actor(s); ${declared.length} declared)`
+    : '';
+
+// Some ruleset fields — bypass_actors in particular — are only included in
+// API responses for admin viewers. A declared key that is absent on the live
+// side is unverifiable for this token, not drift: the same policy as
+// repository merge settings, so callers can fail with a targeted
+// missing-visibility message instead of a bogus value mismatch. The live side
+// is not always an API response — github-bypass-actors.ts synthesises
+// unmatchable stand-in actors from a GraphQL count — so a `bypass_actors` list
+// arriving here may encode a count GitHub answered rather than actors it
+// named.
+export const diffRuleset = (
+  declared: Readonly<Record<string, unknown>>,
+  live: Readonly<Record<string, unknown>>,
+): RulesetDiff => {
+  const name = String(declared.name);
+  const drifted: Array<string> = [];
+  const unverifiable: Array<UnverifiableRulesetField> = [];
+  for (const key of RULESET_COMPARED_KEYS) {
+    if (declared[key] !== undefined) {
+      if (live[key] === undefined) {
+        unverifiable.push({ key, name });
+      } else if (!subsetMatches(declared[key], live[key])) {
+        drifted.push(
+          `ruleset "${name}": ${key} differs from the declared configuration${bypassActorCountDetail(key, declared[key], live[key])}`,
+        );
+      }
+    }
+  }
+  drifted.push(...diffRules(name, declared, live));
+  return { drifted, unverifiable };
+};
+
+const groupLiveByName = (
+  live: ReadonlyArray<Readonly<Record<string, unknown>>>,
+): ReadonlyMap<string, ReadonlyArray<Readonly<Record<string, unknown>>>> => {
+  const groups = new Map<string, Array<Readonly<Record<string, unknown>>>>();
+  for (const ruleset of live) {
+    const group = groups.get(String(ruleset.name));
+    if (group === undefined) {
+      groups.set(String(ruleset.name), [ruleset]);
+    } else {
+      group.push(ruleset);
+    }
+  }
+  return groups;
+};
+
+// GitHub does not require repository ruleset names to be unique, and the
+// declaration addresses rulesets by name alone. Picking one of a colliding
+// pair would compare the harmless one, pass, and never mention the other — a
+// bypassed default branch reported as converged — so a collision fails the
+// gate outright and names the ids that make it ambiguous.
+const nameCollisionDrift = (
+  name: string,
+  group: ReadonlyArray<Readonly<Record<string, unknown>>>,
+): string =>
+  `ruleset name "${name}" is used by ${group.length} rulesets on GitHub (ids ${group.map((ruleset) => String(ruleset.id)).join(', ')}); the declaration addresses rulesets by name, so none of them can be verified until all but one is renamed or deleted`;
+
+// Live rulesets must be exactly the declared set: additions, removals, and
+// in-place edits are all drift.
+export const diffRulesets = (
+  declared: ReadonlyArray<Readonly<Record<string, unknown>>>,
+  live: ReadonlyArray<Readonly<Record<string, unknown>>>,
+): RulesetDiff => {
+  const drifted: Array<string> = [];
+  const unverifiable: Array<UnverifiableRulesetField> = [];
+  const liveByName = groupLiveByName(live);
+  const declaredNames = new Set(
+    declared.map((ruleset) => String(ruleset.name)),
+  );
+  for (const ruleset of declared) {
+    const group = liveByName.get(String(ruleset.name)) ?? [];
+    const [only] = group;
+    // A colliding name is reported below and compared against nothing: no live
+    // ruleset in the group can be the declared one without picking a winner.
+    if (only === undefined) {
+      drifted.push(
+        `ruleset "${ruleset.name}" is declared but missing on GitHub`,
+      );
+    } else if (group.length === 1) {
+      const diff = diffRuleset(ruleset, only);
+      drifted.push(...diff.drifted);
+      unverifiable.push(...diff.unverifiable);
+    }
+  }
+  for (const [name, group] of liveByName) {
+    if (group.length > 1) {
+      drifted.push(nameCollisionDrift(name, group));
+    }
+    if (!declaredNames.has(name)) {
+      drifted.push(
+        `ruleset "${name}" exists on GitHub but is not declared; declare it in .github/settings.local.json or delete it`,
+      );
+    }
+  }
+  return { drifted, unverifiable };
+};