@davidvornholt/standards 0.17.2 → 0.18.0

package/src/github-api.ts

@@ -112,83 +112,3 @@ export const loadDeclared = async (
     existsSync(localPath) ? await readFile(localPath, 'utf8') : 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 PAT 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));
-  const [owner, name] = repo.split('/');
-  if (mapped.length === 0 || owner === undefined || name === undefined) {
-    return {};
-  }
-  const fields = mapped.map((key) => GRAPHQL_MERGE_FIELDS.get(key)).join(' ');
-  const response = await request(token, 'POST', '/graphql', {
-    query: `query { repository(owner: ${JSON.stringify(owner)}, name: ${JSON.stringify(name)}) { ${fields} } }`,
-  });
-  if (response.status !== HTTP_OK || !isRecord(response.body)) {
-    return {};
-  }
-  const data = isRecord(response.body.data) ? response.body.data : null;
-  const repository =
-    data !== null && isRecord(data.repository) ? data.repository : null;
-  if (repository === null) {
-    return {};
-  }
-  return Object.fromEntries(
-    mapped
-      .map((key) => [key, repository[GRAPHQL_MERGE_FIELDS.get(key) ?? '']])
-      .filter(([, value]) => value !== undefined && value !== null),
-  );
-};
-
-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.
-export const fetchLiveRulesets = async (
-  token: string | null,
-  repo: string,
-): Promise<LiveRulesets> => {
-  const list = await request(token, 'GET', `/repos/${repo}/rulesets`);
-  if (list.status !== HTTP_OK || !Array.isArray(list.body)) {
-    return { rulesets: null, problem: apiError('listing rulesets', list) };
-  }
-  const repoOwned = list.body
-    .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-apply.ts

@@ -4,13 +4,14 @@
 
 import {
   apiError,
-  fetchLiveRulesets,
   HTTP_CREATED,
   HTTP_NO_CONTENT,
   HTTP_OK,
   request,
 } from './github-api';
-import { diffRepositorySettings, diffRuleset } from './github-diff';
+import { diffRepositorySettings } from './github-diff';
+import { fetchLiveRulesets } from './github-ruleset-api';
+import { diffRuleset } from './github-ruleset-diff';
 import { type GithubSettings, isRecord } from './github-settings-parse';
 
 // GitHub answers a PATCH containing a plan-unavailable setting with HTTP 200

package/src/github-bypass-actors.ts

@@ -0,0 +1,56 @@
+// Reconciles ruleset bypass-actor lists REST hides, using the counts GraphQL
+// answers for tokens that cannot read the actors themselves. Pure logic; the
+// GraphQL call lives in github-graphql.ts.
+
+import { BYPASS_ACTORS_KEY } from './github-ruleset-diff';
+
+// Stand-ins for bypass actors GraphQL counted but would not name. They exist
+// only to carry the count into the ordinary length comparison, and are attached
+// exactly when the count and the declared length disagree or both are zero — so
+// their content is never observed: subsetMatches short-circuits at the length
+// check, two empty lists compare no element, and a declared ruleset with no
+// bypass_actors array never reaches that comparison. Nothing else looks inside
+// them; bypassActorCountDetail reads only `.length`, and github-live-drift.ts
+// is the sole importer, so a stand-in cannot reach a PATCH body. The guarantee
+// is not local: it also relies on declared ruleset names being unique, which
+// github-settings-parse.ts and github-settings-merge.ts enforce.
+const unreadableBypassActors = (count: number): ReadonlyArray<unknown> =>
+  Array.from({ length: count }, (_unused, index) => ({
+    unreadableBypassActor: index,
+  }));
+
+// A count of zero pins the live list to the empty list exactly. A count that
+// disagrees with the declared length is drift no identity could explain, so
+// that many unreadable actors stand in and the ordinary comparison reports it.
+// A matching non-zero count proves nothing about *which* actors bypass, so the
+// field stays hidden and the gate fails closed on it. A list REST already
+// answered is authoritative and never replaced.
+//
+// The counts are joined by ruleset id, the one identifier both APIs agree on:
+// names are not unique on the live side, so joining on them could pin one
+// ruleset's list from another ruleset's count. A live ruleset carrying no
+// numeric id gets no count and stays hidden.
+export const resolveHiddenBypassActors = (
+  declared: ReadonlyArray<Readonly<Record<string, unknown>>>,
+  live: ReadonlyArray<Readonly<Record<string, unknown>>>,
+  counts: ReadonlyMap<number, number>,
+): ReadonlyArray<Readonly<Record<string, unknown>>> => {
+  const declaredCounts = new Map(
+    declared
+      .filter((ruleset) => Array.isArray(ruleset[BYPASS_ACTORS_KEY]))
+      .map((ruleset) => [
+        String(ruleset.name),
+        (ruleset[BYPASS_ACTORS_KEY] as ReadonlyArray<unknown>).length,
+      ]),
+  );
+  return live.map((ruleset) => {
+    const count =
+      typeof ruleset.id === 'number' ? counts.get(ruleset.id) : undefined;
+    if (ruleset[BYPASS_ACTORS_KEY] !== undefined || count === undefined) {
+      return ruleset;
+    }
+    return count > 0 && count === declaredCounts.get(String(ruleset.name))
+      ? ruleset
+      : { ...ruleset, [BYPASS_ACTORS_KEY]: unreadableBypassActors(count) };
+  });
+};

package/src/github-command-shared.ts

@@ -32,14 +32,21 @@ export const optOutEligibilityProblem = (
     ? `.github/settings.local.json "rulesetEnforcement" may only be declared for a private repository; ${repo} is public`
     : null;
 
+export const ADMIN_VISIBILITY_ADVICE =
+  'Use a token with read access to repository administration (in CI: ci.github_settings_read_token in secrets/ci.yaml), or verify locally with admin auth';
+
 // Declared state the token cannot see is a gate failure, not a pass with a
-// log line: a gate that cannot perform its comparison fails closed.
+// log line: a gate that cannot perform its comparison fails closed. The advice
+// is the caller's, because not every invisible field has the same remedy —
+// ruleset bypass actors in particular are unreachable over REST for an
+// installation token at any permission level.
 export const unverifiableProblem = (
   scope: string,
   items: ReadonlyArray<string>,
+  advice: string,
 ): ReadonlyArray<string> =>
   items.length === 0
     ? []
     : [
-        `${scope} not visible to this token, so the gate cannot verify: ${items.join('; ')}. Use a token with read access to repository administration (in CI: ci.github_settings_read_token in secrets/ci.yaml), or verify locally with admin auth`,
+        `${scope} not visible to this token, so the gate cannot verify: ${items.join('; ')}. ${advice}`,
       ];

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