@davidvornholt/standards 0.17.3 → 0.18.0

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

package/src/github-ruleset-visibility.ts

@@ -0,0 +1,100 @@
+// Turns unverifiable ruleset fields into gate failures. This module owns both
+// the wording of an invisible field and the test for which field it is, so the
+// two cannot drift apart: an earlier version formatted the message in one
+// module and recovered the signal by parsing the suffix in another, where a
+// reformat would have silently stopped the bypass-actor fallback from firing.
+
+import {
+  ADMIN_VISIBILITY_ADVICE,
+  unverifiableProblem,
+} from './github-command-shared';
+import {
+  BYPASS_ACTORS_KEY,
+  type UnverifiableRulesetField,
+} from './github-ruleset-diff';
+
+const SCOPE = 'ruleset field(s)';
+
+export const isHiddenBypassActors = (
+  field: UnverifiableRulesetField,
+): boolean => field.key === BYPASS_ACTORS_KEY;
+
+const fieldLabel = (field: UnverifiableRulesetField): string =>
+  `ruleset "${field.name}": ${field.key}`;
+
+// What the GraphQL bypass-actor fallback established, so the advice can tell a
+// failed request from a permission gap. `countedNames` holds the live rulesets
+// GraphQL did answer a count for.
+export type BypassCountOutcome = {
+  readonly countedNames: ReadonlySet<string>;
+  readonly failure: string | null;
+};
+
+// Rulesets can be unverifiable for reasons other than a hidden bypass list, in
+// which case the fallback is never called.
+export const GRAPHQL_NOT_CONSULTED: BypassCountOutcome = {
+  countedNames: new Set(),
+  failure: null,
+};
+
+// The generic "read access to repository administration" remedy is
+// unactionable for brokered CI here: REST withholds this field from a GitHub
+// App installation token at every permission level, so widening the App only
+// broadens the blast radius while the gate stays red.
+const INSTALLATION_DEAD_END =
+  "A GitHub App installation token cannot read bypass_actors over REST at any permission level, so widening the App's permissions will not help";
+
+const COUNT_MATCHED_ADVICE = `GitHub reports the declared number of bypass actors but withholds their identities, so the repository is probably fine and only a local run with admin auth can confirm it. ${INSTALLATION_DEAD_END}`;
+
+const NOTHING_ANSWERED_ADVICE = `Neither REST nor the GraphQL bypass-actor count answered for the ruleset(s) listed, so nothing at all is known about who may bypass them; verify locally with admin auth. ${INSTALLATION_DEAD_END}`;
+
+// The two no-failure remedies differ per ruleset, so the fields are partitioned
+// rather than reported under whichever advice one of them happened to match: a
+// ruleset GraphQL never answered for must never be described as probably fine
+// because a sibling ruleset was counted.
+const hiddenBypassActorsProblems = (
+  fields: ReadonlyArray<UnverifiableRulesetField>,
+  outcome: BypassCountOutcome,
+): ReadonlyArray<string> => {
+  if (outcome.failure !== null) {
+    return unverifiableProblem(
+      SCOPE,
+      fields.map(fieldLabel),
+      `The GraphQL bypass-actor count did not answer (${outcome.failure}), so this is a failed request rather than a permission gap: re-run the check, and if it keeps failing verify locally with admin auth`,
+    );
+  }
+  const counted = fields.filter((field) =>
+    outcome.countedNames.has(field.name),
+  );
+  const unanswered = fields.filter(
+    (field) => !outcome.countedNames.has(field.name),
+  );
+  return [
+    ...unverifiableProblem(
+      SCOPE,
+      counted.map(fieldLabel),
+      COUNT_MATCHED_ADVICE,
+    ),
+    ...unverifiableProblem(
+      SCOPE,
+      unanswered.map(fieldLabel),
+      NOTHING_ANSWERED_ADVICE,
+    ),
+  ];
+};
+
+export const rulesetVisibilityProblems = (
+  unverifiable: ReadonlyArray<UnverifiableRulesetField>,
+  outcome: BypassCountOutcome,
+): ReadonlyArray<string> => {
+  const hidden = unverifiable.filter(isHiddenBypassActors);
+  const others = unverifiable.filter((field) => !isHiddenBypassActors(field));
+  return [
+    ...unverifiableProblem(
+      SCOPE,
+      others.map(fieldLabel),
+      ADMIN_VISIBILITY_ADVICE,
+    ),
+    ...hiddenBypassActorsProblems(hidden, outcome),
+  ];
+};

package/src/github-settings-parse.ts

@@ -1,8 +1,7 @@
-// Shape parsing for a single declarative GitHub settings file: the canonical
-// `.github/settings.json` or the repo-owned `.github/settings.local.json`
-// extension. Seam merging lives in github-settings.ts, drift comparison in
-// 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.
+// Parse one GitHub settings file: canonical `.github/settings.json` or the
+// repo-owned `.github/settings.local.json` extension. Seam merging, drift
+// comparison, and API interaction live in dedicated modules. This module stays
+// zero-dependency so `bunx` can execute the published package.
 
 import { labelIdentity } from './github-label-identity';
 
@@ -139,13 +138,15 @@ const parseDeclarationList = (
   options: ListField,
   problems: Array<string>,
 ): ReadonlyArray<unknown> | null => {
-  const list = raw ?? [];
-  if (!Array.isArray(list)) {
+  if (raw === undefined) {
+    return [];
+  }
+  if (!Array.isArray(raw)) {
     problems.push(`${options.label} "${options.field}" must be an array`);
     return null;
   }
-  problems.push(...options.listProblems(list, options.label));
-  return list;
+  problems.push(...options.listProblems(raw, options.label));
+  return raw;
 };
 
 export const parseSettings = (
@@ -162,7 +163,7 @@ export const parseSettings = (
       problems.push(`${label} has unknown key "${key}"`);
     }
   }
-  const repository = raw.repository ?? {};
+  const repository = 'repository' in raw ? raw.repository : {};
   if (!isRecord(repository)) {
     problems.push(`${label} "repository" must be an object`);
   }
@@ -179,6 +180,7 @@ export const parseSettings = (
   // 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 (
+    allowedKeys.has('rulesetEnforcement') &&
     raw.rulesetEnforcement !== undefined &&
     raw.rulesetEnforcement !== ENFORCEMENT_OPT_OUT
   ) {

package/src/github-settings.ts

@@ -1,7 +1,8 @@
 // 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.
+// github-settings-merge.ts, drift in github-diff.ts and
+// github-ruleset-diff.ts, and API work in github-api.ts; this stays
+// dependency-free.
 
 import { mergeSettings } from './github-settings-merge';
 import {