@davidvornholt/standards 0.17.3 → 0.19.0

package/src/creds-login-github-manifest.ts

@@ -10,13 +10,20 @@ import { isRecord } from './github-settings-parse';
 
 export const MANIFEST_STATE_BYTES = 32;
 
-// Root-credential ceiling: everything the broker may ever delegate. Actual
-// grants are narrowed per installation token at mint time.
-const DEFAULT_PERMISSIONS = Object.fromEntries(
-  'administration actions contents issues pull_requests secrets workflows'
-    .split(' ')
-    .map((permission) => [permission, 'write']),
-);
+// Root-credential ceiling: everything the broker may ever delegate. The
+// `permission-*` inputs a workflow passes when minting are a request, not a
+// constraint — anything holding the durable private key can request the whole
+// ceiling — so this, not those inputs, is the blast radius of the App identity
+// sitting in every consumer's secrets/ci.yaml. It therefore lists only grants a
+// workflow actually uses today; widening it is a deliberate edit here plus a
+// settings-page change on the existing App, not a default to grow into.
+const DEFAULT_PERMISSIONS = {
+  actions: 'read',
+  contents: 'write',
+  issues: 'write',
+  metadata: 'read',
+  pull_requests: 'write',
+} as const;
 
 export const buildAppManifest = (
   name: string,

package/src/dependabot-directory-character-class.ts

@@ -0,0 +1,139 @@
+export type CharacterMatcher =
+  | { readonly kind: 'literal'; readonly value: number }
+  | { readonly kind: 'non-slash' }
+  | {
+      readonly kind: 'class';
+      readonly ranges: ReadonlyArray<readonly [number, number]>;
+      readonly negated: boolean;
+    };
+
+type CharacterRange = readonly [number, number];
+
+type ClassValue = {
+  readonly escaped: boolean;
+  readonly value: number;
+};
+
+const BEFORE_SLASH = '/'.codePointAt(0) ?? 0;
+const AFTER_SLASH = BEFORE_SLASH + 1;
+const HYPHEN = '-'.codePointAt(0) ?? 0;
+const MAXIMUM_CODE_POINT = 0x10_ff_ff;
+
+const NON_SLASH_RANGES: ReadonlyArray<CharacterRange> = [
+  [0, BEFORE_SLASH - 1],
+  [AFTER_SLASH, MAXIMUM_CODE_POINT],
+];
+
+const intersectRanges = (
+  left: ReadonlyArray<CharacterRange>,
+  right: ReadonlyArray<CharacterRange>,
+): ReadonlyArray<CharacterRange> => {
+  const intersection: Array<CharacterRange> = [];
+  for (const [leftStart, leftEnd] of left) {
+    for (const [rightStart, rightEnd] of right) {
+      const start = Math.max(leftStart, rightStart);
+      const end = Math.min(leftEnd, rightEnd);
+      if (start <= end) {
+        intersection.push([start, end]);
+      }
+    }
+  }
+  return intersection;
+};
+
+const subtractRanges = (
+  ranges: ReadonlyArray<CharacterRange>,
+  excluded: ReadonlyArray<CharacterRange>,
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Range subtraction keeps the finite character-class intersection exact.
+): ReadonlyArray<CharacterRange> => {
+  let remaining = [...ranges];
+  for (const [excludedStart, excludedEnd] of excluded) {
+    const next: Array<CharacterRange> = [];
+    for (const [start, end] of remaining) {
+      if (excludedEnd < start || excludedStart > end) {
+        next.push([start, end]);
+      } else {
+        if (start < excludedStart) {
+          next.push([start, excludedStart - 1]);
+        }
+        if (excludedEnd < end) {
+          next.push([excludedEnd + 1, end]);
+        }
+      }
+    }
+    remaining = next;
+  }
+  return remaining;
+};
+
+const matcherRanges = (
+  matcher: CharacterMatcher,
+): ReadonlyArray<CharacterRange> => {
+  if (matcher.kind === 'literal') {
+    return [[matcher.value, matcher.value]];
+  }
+  if (matcher.kind === 'non-slash') {
+    return NON_SLASH_RANGES;
+  }
+  return matcher.negated
+    ? subtractRanges(NON_SLASH_RANGES, matcher.ranges)
+    : intersectRanges(NON_SLASH_RANGES, matcher.ranges);
+};
+
+export const matchersIntersect = (
+  left: CharacterMatcher,
+  right: CharacterMatcher,
+): boolean =>
+  intersectRanges(matcherRanges(left), matcherRanges(right)).length > 0;
+
+export const parseCharacterClass = (
+  characters: ReadonlyArray<string>,
+  start: number,
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Ruby character classes require escape, negation, and range state in one parser.
+): { readonly end: number; readonly matcher: CharacterMatcher } | null => {
+  let cursor = start + 1;
+  const negated = characters[cursor] === '!' || characters[cursor] === '^';
+  if (negated) {
+    cursor += 1;
+  }
+  const values: Array<ClassValue> = [];
+  for (
+    ;
+    cursor < characters.length && characters[cursor] !== ']';
+    cursor += 1
+  ) {
+    let escaped = false;
+    if (characters[cursor] === '\\' && characters[cursor + 1] !== undefined) {
+      cursor += 1;
+      escaped = true;
+    }
+    values.push({
+      escaped,
+      value: characters[cursor]?.codePointAt(0) ?? 0,
+    });
+  }
+  if (characters[cursor] !== ']') {
+    return null;
+  }
+  const ranges: Array<CharacterRange> = [];
+  for (let index = 0; index < values.length; index += 1) {
+    const startValue = values[index]?.value ?? 0;
+    const separator = values[index + 1];
+    const endValue = values[index + 2]?.value ?? 0;
+    if (
+      index + 2 < values.length &&
+      separator?.value === HYPHEN &&
+      !separator.escaped
+    ) {
+      if (startValue <= endValue) {
+        ranges.push([startValue, endValue]);
+      } else {
+        ranges.push([startValue, startValue], [endValue, endValue]);
+      }
+      index += 2;
+    } else {
+      ranges.push([startValue, startValue]);
+    }
+  }
+  return { end: cursor, matcher: { kind: 'class', ranges, negated } };
+};

package/src/dependabot-directory-normalize.ts

@@ -0,0 +1,33 @@
+const applySegment = (
+  segments: Array<string>,
+  segment: string,
+  absolute: boolean,
+): void => {
+  if (segment !== '' && segment !== '.') {
+    if (segment !== '..') {
+      segments.push(segment);
+    } else if (segments.at(-1) !== undefined && segments.at(-1) !== '..') {
+      segments.pop();
+    } else if (!absolute) {
+      segments.push(segment);
+    }
+  }
+};
+
+export const normalizeDependabotDirectory = (directory: string): string => {
+  const absolute = directory.startsWith('/');
+  const segments: Array<string> = [];
+  for (const segment of directory.split('/')) {
+    applySegment(segments, segment, absolute);
+  }
+  let normalized = segments.join('/');
+  if (normalized === '') {
+    normalized = absolute ? '/' : '.';
+  }
+  return normalized.startsWith('/') ? normalized : `/${normalized}`;
+};
+
+export const isDependabotGlob = (directory: string): boolean =>
+  directory.includes('*') ||
+  directory.includes('?') ||
+  (directory.includes('[') && directory.includes(']'));

package/src/dependabot-directory-overlap.ts

@@ -0,0 +1,139 @@
+import {
+  type CharacterMatcher,
+  matchersIntersect,
+  parseCharacterClass,
+} from './dependabot-directory-character-class';
+
+type Edge = {
+  readonly from: number;
+  readonly to: number;
+  readonly matcher: CharacterMatcher | null;
+};
+
+type Automaton = {
+  readonly accept: number;
+  readonly edges: ReadonlyArray<Edge>;
+};
+
+const compileDirectory = (
+  directory: string,
+  supportsGlobs: boolean,
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Ruby glob tokens have distinct NFA transitions that are clearest in one ordered parser.
+): Automaton => {
+  const characters = [...directory];
+  const edges: Array<Edge> = [];
+  let current = 0;
+  let states = 1;
+  const append = (matcher: CharacterMatcher): void => {
+    const next = states;
+    states += 1;
+    edges.push({ from: current, to: next, matcher });
+    current = next;
+  };
+
+  for (let index = 0; index < characters.length; index += 1) {
+    const character = characters[index];
+    if (!supportsGlobs) {
+      append({ kind: 'literal', value: character?.codePointAt(0) ?? 0 });
+    } else if (character === '\\' && characters[index + 1] !== undefined) {
+      index += 1;
+      append({
+        kind: 'literal',
+        value: characters[index]?.codePointAt(0) ?? 0,
+      });
+    } else if (
+      character === '*' &&
+      characters[index + 1] === '*' &&
+      characters[index + 2] === '/' &&
+      (index === 0 || characters[index - 1] === '/')
+    ) {
+      const next = states;
+      const insideDirectory = states + 1;
+      states += 2;
+      edges.push(
+        { from: current, to: next, matcher: null },
+        { from: current, to: insideDirectory, matcher: { kind: 'non-slash' } },
+        {
+          from: insideDirectory,
+          to: insideDirectory,
+          matcher: { kind: 'non-slash' },
+        },
+        {
+          from: insideDirectory,
+          to: current,
+          matcher: { kind: 'literal', value: '/'.codePointAt(0) ?? 0 },
+        },
+      );
+      current = next;
+      index += 2;
+    } else if (character === '*') {
+      while (characters[index + 1] === '*') {
+        index += 1;
+      }
+      const next = states;
+      states += 1;
+      edges.push(
+        { from: current, to: next, matcher: null },
+        { from: current, to: current, matcher: { kind: 'non-slash' } },
+      );
+      current = next;
+    } else if (character === '?') {
+      append({ kind: 'non-slash' });
+    } else if (character === '[') {
+      const parsed = parseCharacterClass(characters, index);
+      if (parsed === null) {
+        append({ kind: 'literal', value: '['.codePointAt(0) ?? 0 });
+      } else {
+        append(parsed.matcher);
+        index = parsed.end;
+      }
+    } else {
+      append({ kind: 'literal', value: character?.codePointAt(0) ?? 0 });
+    }
+  }
+  return { accept: current, edges };
+};
+
+export const directoriesOverlap = (
+  leftDirectory: string,
+  leftSupportsGlobs: boolean,
+  rightDirectory: string,
+  rightSupportsGlobs: boolean,
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: The product walk must process both automata's epsilon and consuming transitions together.
+): boolean => {
+  const left = compileDirectory(leftDirectory, leftSupportsGlobs);
+  const right = compileDirectory(rightDirectory, rightSupportsGlobs);
+  const pending: Array<readonly [number, number]> = [[0, 0]];
+  const visited = new Set<string>();
+  for (const [leftState, rightState] of pending) {
+    const key = `${leftState}:${rightState}`;
+    if (!visited.has(key)) {
+      visited.add(key);
+      if (leftState === left.accept && rightState === right.accept) {
+        return true;
+      }
+      const leftEdges = left.edges.filter((edge) => edge.from === leftState);
+      const rightEdges = right.edges.filter((edge) => edge.from === rightState);
+      pending.push(
+        ...leftEdges
+          .filter((edge) => edge.matcher === null)
+          .map((edge) => [edge.to, rightState] as const),
+        ...rightEdges
+          .filter((edge) => edge.matcher === null)
+          .map((edge) => [leftState, edge.to] as const),
+      );
+      for (const leftEdge of leftEdges) {
+        for (const rightEdge of rightEdges) {
+          if (
+            leftEdge.matcher !== null &&
+            rightEdge.matcher !== null &&
+            matchersIntersect(leftEdge.matcher, rightEdge.matcher)
+          ) {
+            pending.push([leftEdge.to, rightEdge.to]);
+          }
+        }
+      }
+    }
+  }
+  return false;
+};

package/src/dependabot-update.ts

@@ -1,3 +1,8 @@
+import {
+  isDependabotGlob,
+  normalizeDependabotDirectory,
+} from './dependabot-directory-normalize';
+import { directoriesOverlap } from './dependabot-directory-overlap';
 import { isNonEmptyString, isRecord } from './github-settings-parse';
 
 export type UpdateBlock = Record<string, unknown>;
@@ -6,6 +11,8 @@ export type UpdateTarget = {
   readonly ecosystem: string;
   readonly targetBranch: string | null;
   readonly directories: ReadonlyArray<string>;
+  readonly normalizedDirectories: ReadonlyArray<string>;
+  readonly globDirectories: ReadonlySet<string>;
 };
 
 const listOfNonEmptyStrings = (
@@ -72,6 +79,7 @@ export const updateTarget = (
   block: UpdateBlock,
   label: string,
   problems: Array<string>,
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Target validation deliberately gathers every independent configuration problem.
 ): UpdateTarget | null => {
   const ecosystem = block['package-ecosystem'];
   if (!isNonEmptyString(ecosystem)) {
@@ -103,6 +111,9 @@ export const updateTarget = (
     ? [directory as string]
     : (directories as ReadonlyArray<string>);
   const normalized = [...new Set(rawDirectories)].sort();
+  const normalizedDirectories = [
+    ...new Set(normalized.map(normalizeDependabotDirectory)),
+  ].sort();
   if (
     !hasDirectory &&
     Array.isArray(directories) &&
@@ -120,6 +131,10 @@ export const updateTarget = (
     ecosystem,
     targetBranch: targetBranch ?? null,
     directories: normalized,
+    normalizedDirectories,
+    globDirectories: new Set(
+      hasDirectories ? normalizedDirectories.filter(isDependabotGlob) : [],
+    ),
   };
 };
 
@@ -135,9 +150,13 @@ export const sameUpdateTarget = (
   right: UpdateTarget,
 ): boolean =>
   sameUpdateScope(left, right) &&
-  left.directories.length === right.directories.length &&
-  left.directories.every(
-    (directory, index) => directory === right.directories[index],
+  left.normalizedDirectories.length === right.normalizedDirectories.length &&
+  left.normalizedDirectories.every(
+    (directory, index) => directory === right.normalizedDirectories[index],
+  ) &&
+  left.globDirectories.size === right.globDirectories.size &&
+  [...left.globDirectories].every((directory) =>
+    right.globDirectories.has(directory),
   );
 
 export const overlapsUpdateTarget = (
@@ -145,7 +164,16 @@ export const overlapsUpdateTarget = (
   right: UpdateTarget,
 ): boolean =>
   sameUpdateScope(left, right) &&
-  left.directories.some((directory) => right.directories.includes(directory));
+  left.normalizedDirectories.some((leftDirectory) =>
+    right.normalizedDirectories.some((rightDirectory) =>
+      directoriesOverlap(
+        leftDirectory,
+        left.globDirectories.has(leftDirectory),
+        rightDirectory,
+        right.globDirectories.has(rightDirectory),
+      ),
+    ),
+  );
 
 export const updateTargetDescription = (target: UpdateTarget): string => {
   const branch =

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}`,
       ];