@davidvornholt/standards 0.9.0 → 0.10.1

package/src/github-api.ts

@@ -111,6 +111,53 @@ export const loadDeclared = async (
   );
 };
 
+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;

package/src/github-apply.ts

@@ -11,8 +11,11 @@ import {
   request,
 } from './github-api';
 import { diffRepositorySettings, diffRuleset } from './github-diff';
-import type { GithubSettings } from './github-settings-parse';
+import { type GithubSettings, isRecord } from './github-settings-parse';
 
+// GitHub answers a PATCH containing a plan-unavailable setting with HTTP 200
+// and the old value, so the response body — the updated repository — is
+// diffed again instead of trusting the status code.
 export const applyRepositorySettings = async (
   token: string,
   repo: string,
@@ -24,9 +27,22 @@ export const applyRepositorySettings = async (
     return [];
   }
   const patched = await request(token, 'PATCH', `/repos/${repo}`, repository);
-  if (patched.status !== HTTP_OK) {
+  if (patched.status !== HTTP_OK || !isRecord(patched.body)) {
     throw new Error(apiError('updating repository settings', patched));
   }
+  const persisted = diffRepositorySettings(repository, patched.body);
+  const ignored = [
+    ...persisted.drifted,
+    ...persisted.unverifiable.map(
+      (key) =>
+        `repository setting "${key}" is missing from the update response`,
+    ),
+  ];
+  if (ignored.length > 0) {
+    throw new Error(
+      `GitHub returned HTTP 200 but ignored part of the update: ${ignored.join('; ')}. A silently ignored setting is usually unavailable on this GitHub plan; if this plan cannot protect branches, declare the ruleset-enforcement opt-out instead`,
+    );
+  }
   return ['updated repository merge settings'];
 };
 
@@ -37,8 +53,8 @@ export const applySummary = (
 ): string => {
   if (rulesetsSkipped) {
     return actions.length === 0
-      ? `standards github: repository settings already converged for ${repo}; rulesets skipped`
-      : `standards github: repository settings apply complete for ${repo}; rulesets skipped`;
+      ? `standards github: enforceable settings already converged for ${repo}; plan-gated settings skipped`
+      : `standards github: enforceable settings apply complete for ${repo}; plan-gated settings skipped`;
   }
   return actions.length === 0
     ? 'standards github: already converged; no changes'

package/src/github-command-shared.ts

@@ -1,11 +1,45 @@
-import type { GithubSettings } from './github-settings-parse';
+import {
+  ENFORCEMENT_OPT_OUT,
+  type GithubSettings,
+} from './github-settings-parse';
+
+// Repository settings that only function alongside branch protection, which
+// the ruleset-enforcement opt-out declares unavailable on the plan. GitHub
+// answers a PATCH for them with HTTP 200 and silently keeps the old value, so
+// they must be skipped, never applied-and-trusted.
+export const PLAN_GATED_REPOSITORY_KEYS: ReadonlySet<string> = new Set([
+  'allow_auto_merge',
+]);
+
+export const enforceableRepositorySettings = (
+  declared: GithubSettings,
+): Readonly<Record<string, unknown>> =>
+  declared.rulesetEnforcement === ENFORCEMENT_OPT_OUT
+    ? Object.fromEntries(
+        Object.entries(declared.repository).filter(
+          ([key]) => !PLAN_GATED_REPOSITORY_KEYS.has(key),
+        ),
+      )
+    : declared.repository;
 
 export const optOutEligibilityProblem = (
   repo: string,
   declared: GithubSettings,
   liveRepository: Readonly<Record<string, unknown>>,
 ): string | null =>
-  declared.rulesetEnforcement === 'unavailable-on-plan' &&
+  declared.rulesetEnforcement === ENFORCEMENT_OPT_OUT &&
   liveRepository.private !== true
     ? `.github/settings.local.json "rulesetEnforcement" may only be declared for a private repository; ${repo} is public`
     : null;
+
+// 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.
+export const unverifiableProblem = (
+  scope: string,
+  items: ReadonlyArray<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`,
+      ];

package/src/github-commands.ts

@@ -1,11 +1,10 @@
 // `standards github --check` verifies the live GitHub repository against the
-// declared settings and fails closed on any drift or API error. `standards
-// github --apply` converges the live repository; it needs an admin token, so
-// it runs locally rather than in CI.
+// declared settings and fails closed on any drift, API error, or declared
+// state the token cannot see. `standards github --apply` converges the live
+// repository; it needs an admin token, so it runs locally rather than in CI.
 
 import {
   apiError,
-  fetchLiveRulesets,
   HTTP_OK,
   loadDeclared,
   request,
@@ -17,14 +16,17 @@ import {
   applyRulesets,
   applySummary,
 } from './github-apply';
-import { optOutEligibilityProblem } from './github-command-shared';
-import { diffRepositorySettings, diffRulesets } from './github-diff';
-import { type GithubSettings, isRecord } from './github-settings-parse';
+import {
+  enforceableRepositorySettings,
+  optOutEligibilityProblem,
+} from './github-command-shared';
+import { collectLiveDrift } from './github-live-drift';
+import { isRecord } from './github-settings-parse';
 
 // Printed on every check and apply while the opt-out is declared: the skip
 // must stay louder than the comfort of a green gate.
 const UNENFORCEABLE_NOTICE =
-  'standards github: rulesets are declared unenforceable on this GitHub plan (.github/settings.local.json "rulesetEnforcement"); the default branch is NOT protected. After upgrading the plan, remove the declaration, then run `bun standards github --apply`.';
+  'standards github: rulesets are declared unenforceable on this GitHub plan (.github/settings.local.json "rulesetEnforcement"); the default branch is NOT protected, and plan-gated repository settings ("allow_auto_merge") are skipped. After upgrading the plan, remove the declaration, then run `bun standards github --apply`.';
 
 const reportProblems = (problems: ReadonlyArray<string>): void => {
   console.error(
@@ -33,74 +35,6 @@ const reportProblems = (problems: ReadonlyArray<string>): void => {
   console.error(problems.map((problem) => `  - ${problem}`).join('\n'));
 };
 
-const repositoryDrift = async (
-  token: string | null,
-  repo: string,
-  declared: GithubSettings,
-): Promise<ReadonlyArray<string>> => {
-  const repoResponse = await request(token, 'GET', `/repos/${repo}`);
-  if (repoResponse.status !== HTTP_OK || !isRecord(repoResponse.body)) {
-    return [apiError(`reading repository ${repo}`, repoResponse)];
-  }
-  const eligibilityProblem = optOutEligibilityProblem(
-    repo,
-    declared,
-    repoResponse.body,
-  );
-  if (eligibilityProblem !== null) {
-    return [eligibilityProblem];
-  }
-  const diff = diffRepositorySettings(declared.repository, repoResponse.body);
-  if (diff.unverifiable.length > 0) {
-    console.log(
-      `standards github: repository setting(s) not visible to this token, verify with admin auth: ${diff.unverifiable.join(', ')}`,
-    );
-  }
-  return diff.drifted;
-};
-
-const rulesetDrift = async (
-  token: string | null,
-  repo: string,
-  declared: GithubSettings,
-): Promise<ReadonlyArray<string>> => {
-  if (declared.rulesetEnforcement === 'unavailable-on-plan') {
-    return [];
-  }
-  const live = await fetchLiveRulesets(token, repo);
-  if (live.rulesets === null) {
-    return [live.problem ?? 'unable to read rulesets'];
-  }
-  const diff = diffRulesets(declared.rulesets, live.rulesets);
-  if (diff.unverifiable.length > 0) {
-    console.log(
-      `standards github: ruleset field(s) not visible to this token, verify with admin auth: ${diff.unverifiable.join('; ')}`,
-    );
-  }
-  return diff.drifted;
-};
-
-const collectLiveDrift = async (
-  consumer: string,
-  declared: GithubSettings,
-): Promise<ReadonlyArray<string>> => {
-  const repo = resolveGithubRepo(consumer);
-  if (repo === null) {
-    return ['cannot determine the GitHub repository from the origin remote'];
-  }
-  const token = resolveToken();
-  try {
-    return [
-      ...(await repositoryDrift(token, repo, declared)),
-      ...(await rulesetDrift(token, repo, declared)),
-    ];
-  } catch (error) {
-    return [
-      `GitHub API unreachable: ${error instanceof Error ? error.message : String(error)}`,
-    ];
-  }
-};
-
 export const runGithubCheck = async (consumer: string): Promise<boolean> => {
   const declared = await loadDeclared(consumer);
   if (declared.merged?.rulesetEnforcement === 'unavailable-on-plan') {
@@ -119,7 +53,7 @@ export const runGithubCheck = async (consumer: string): Promise<boolean> => {
   }
   console.log(
     declared.merged?.rulesetEnforcement === 'unavailable-on-plan'
-      ? 'standards github: live repository settings match the declared configuration (rulesets skipped)'
+      ? 'standards github: live repository settings match the declared configuration (plan-gated settings skipped)'
       : 'standards github: live GitHub settings match the declared configuration',
   );
   return true;
@@ -165,7 +99,7 @@ export const runGithubApply = async (consumer: string): Promise<boolean> => {
       ...(await applyRepositorySettings(
         token,
         repo,
-        declared.merged.repository,
+        enforceableRepositorySettings(declared.merged),
         repoResponse.body,
       )),
     ];

package/src/github-diff.ts

@@ -89,8 +89,8 @@ const diffRules = (
 // 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 a non-admin CI token does not fail the gate
-// on state it cannot see.
+// 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>>,
@@ -150,9 +150,9 @@ export const diffRulesets = (
 };
 
 // Repo merge settings are only visible to admin tokens; report invisible keys
-// as unverifiable instead of drifted so a non-admin CI token does not fail the
-// gate, while still surfacing that only a local admin check gives full
-// coverage.
+// as unverifiable instead of drifted so callers fail the gate with a
+// missing-visibility message that names the token fix, not a bogus value
+// mismatch.
 export const diffRepositorySettings = (
   declared: Readonly<Record<string, unknown>>,
   live: Readonly<Record<string, unknown>>,

package/src/github-live-drift.ts

@@ -0,0 +1,99 @@
+// Drift collection for `standards github --check`: compares the live GitHub
+// repository against the merged declaration and fails closed on state the
+// token cannot see. Command wiring lives in github-commands.ts.
+
+import {
+  apiError,
+  fetchLiveRulesets,
+  fetchMergeSettingsViaGraphql,
+  HTTP_OK,
+  request,
+  resolveGithubRepo,
+  resolveToken,
+} from './github-api';
+import {
+  enforceableRepositorySettings,
+  optOutEligibilityProblem,
+  unverifiableProblem,
+} from './github-command-shared';
+import { diffRepositorySettings, diffRulesets } from './github-diff';
+import { type GithubSettings, isRecord } from './github-settings-parse';
+
+const repositoryDrift = async (
+  token: string | null,
+  repo: string,
+  declared: GithubSettings,
+): Promise<ReadonlyArray<string>> => {
+  const repoResponse = await request(token, 'GET', `/repos/${repo}`);
+  if (repoResponse.status !== HTTP_OK || !isRecord(repoResponse.body)) {
+    return [apiError(`reading repository ${repo}`, repoResponse)];
+  }
+  const eligibilityProblem = optOutEligibilityProblem(
+    repo,
+    declared,
+    repoResponse.body,
+  );
+  if (eligibilityProblem !== null) {
+    return [eligibilityProblem];
+  }
+  const declaredRepository = enforceableRepositorySettings(declared);
+  const diff = diffRepositorySettings(declaredRepository, repoResponse.body);
+  if (diff.unverifiable.length === 0) {
+    return diff.drifted;
+  }
+  // REST hides merge settings from read-only tokens; retry the invisible
+  // keys over GraphQL before failing the gate.
+  const fallback = await fetchMergeSettingsViaGraphql(
+    token,
+    repo,
+    diff.unverifiable,
+  );
+  const rediff = diffRepositorySettings(declaredRepository, {
+    ...repoResponse.body,
+    ...fallback,
+  });
+  return [
+    ...rediff.drifted,
+    ...unverifiableProblem('repository setting(s)', rediff.unverifiable),
+  ];
+};
+
+const rulesetDrift = async (
+  token: string | null,
+  repo: string,
+  declared: GithubSettings,
+): Promise<ReadonlyArray<string>> => {
+  if (declared.rulesetEnforcement === 'unavailable-on-plan') {
+    return [];
+  }
+  const live = await fetchLiveRulesets(token, repo);
+  if (live.rulesets === null) {
+    return [live.problem ?? 'unable to read rulesets'];
+  }
+  const diff = diffRulesets(declared.rulesets, live.rulesets);
+  return [
+    ...diff.drifted,
+    ...unverifiableProblem('ruleset field(s)', diff.unverifiable),
+  ];
+};
+
+export const collectLiveDrift = async (
+  consumer: string,
+  declared: GithubSettings,
+): Promise<ReadonlyArray<string>> => {
+  const repo = resolveGithubRepo(consumer);
+  if (repo === null) {
+    return ['cannot determine the GitHub repository from the origin remote'];
+  }
+  const token = resolveToken();
+  try {
+    return [
+      ...(await repositoryDrift(token, repo, declared)),
+      ...(await rulesetDrift(token, repo, declared)),
+    ];
+  } catch (error) {
+    return [
+      `GitHub API unreachable: ${error instanceof Error ? error.message : String(error)}`,
+    ];
+  }
+};

package/src/github-settings-parse.ts

@@ -25,6 +25,9 @@ export type ParsedGithubSettings = {
 export const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
 
+export const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.length > 0;
+
 export const isNamedRuleset = (
   value: unknown,
 ): value is Readonly<Record<string, unknown>> & { readonly name: string } =>

package/src/structure-profile.ts

@@ -30,6 +30,7 @@ const SOURCE_ROOT_EXPECTATIONS: ReadonlyArray<RootScriptExpectation> = [
     name: 'check',
     commands: [
       `${SOURCE_CLI} structure --profile source`,
+      `${SOURCE_CLI} dependabot --check`,
       `${SOURCE_CLI} github --check`,
       'turbo run lint check-types test',
     ],
@@ -39,6 +40,7 @@ const SOURCE_ROOT_EXPECTATIONS: ReadonlyArray<RootScriptExpectation> = [
     name: 'check:fix',
     commands: [
       `${SOURCE_CLI} structure --profile source`,
+      `${SOURCE_CLI} dependabot --write`,
       `${SOURCE_CLI} github --check`,
       'turbo run lint:fix check-types test',
     ],

package/src/yaml-emit.ts

@@ -0,0 +1,67 @@
+// Deterministic block-style YAML for JSON-shaped data. Bun ships a YAML
+// serializer, but it emits flow style, and generated files must stay readable
+// in consumer diffs. Like cli.ts, this module is zero-dependency so `bunx` can
+// execute the published package.
+
+import { isRecord } from './github-settings-parse';
+
+const isScalar = (value: unknown): boolean =>
+  value === null ||
+  typeof value === 'string' ||
+  typeof value === 'number' ||
+  typeof value === 'boolean';
+
+const BARE_KEY = /^[A-Za-z0-9_-]+$/u;
+
+const emitKey = (key: string): string =>
+  BARE_KEY.test(key) ? key : JSON.stringify(key);
+
+// Strings are always double-quoted; JSON string syntax is valid YAML.
+const emitScalar = (value: unknown): string =>
+  typeof value === 'string' ? JSON.stringify(value) : String(value);
+
+const emitEntry = (
+  key: string,
+  value: unknown,
+  indent: string,
+): Array<string> => {
+  if (isScalar(value)) {
+    return [`${indent}${key}: ${emitScalar(value)}`];
+  }
+  if (Array.isArray(value)) {
+    return value.length === 0
+      ? [`${indent}${key}: []`]
+      : [
+          `${indent}${key}:`,
+          ...value.flatMap((item) => emitItem(item, `${indent}  `)),
+        ];
+  }
+  if (isRecord(value)) {
+    return Object.keys(value).length === 0
+      ? [`${indent}${key}: {}`]
+      : [`${indent}${key}:`, ...emitEntries(value, `${indent}  `)];
+  }
+  throw new Error(`Unsupported YAML value under key "${key}"`);
+};
+
+const emitEntries = (
+  record: Record<string, unknown>,
+  indent: string,
+): Array<string> =>
+  Object.entries(record).flatMap(([key, value]) =>
+    emitEntry(emitKey(key), value, indent),
+  );
+
+const emitItem = (item: unknown, indent: string): Array<string> => {
+  if (isScalar(item)) {
+    return [`${indent}- ${emitScalar(item)}`];
+  }
+  if (isRecord(item) && Object.keys(item).length > 0) {
+    const lines = emitEntries(item, `${indent}  `);
+    return [`${indent}- ${(lines[0] ?? '').trimStart()}`, ...lines.slice(1)];
+  }
+  throw new Error('Unsupported YAML sequence item');
+};
+
+export const emitYamlDocument = (document: Record<string, unknown>): string =>
+  `${emitEntries(document, '').join('\n')}\n`;

package/src/yaml-parse.ts

@@ -0,0 +1,25 @@
+import { parseDocument } from 'yaml';
+
+export const parseYaml = (
+  raw: string,
+  label: string,
+): { readonly value: unknown; readonly problem: string | null } => {
+  try {
+    const unmergedDocument = parseDocument(raw, {
+      merge: false,
+      uniqueKeys: true,
+    });
+    if (unmergedDocument.errors.length === 0) {
+      const document = parseDocument(raw, { merge: true, uniqueKeys: true });
+      if (document.errors.length === 0) {
+        return { value: document.toJS() as unknown, problem: null };
+      }
+    }
+  } catch {
+    // The caller reports one stable configuration error for parser failures.
+  }
+  return {
+    value: null,
+    problem: `${label} must contain valid YAML with unique mapping keys`,
+  };
+};