@davidvornholt/standards 0.27.0 → 0.28.0

package/README.md

@@ -182,6 +182,10 @@ bun standards github --apply
 
 The command merges `.github/settings.json` with `.github/settings.local.json`, then compares or converges repository settings, declared rulesets, and canonical labels. Undeclared live labels are left alone. Undeclared repository-owned rulesets are removed by `--apply`.
 
+Starting with 0.28.0, every declared ruleset must explicitly state `target`, `enforcement`, and `bypass_actors`; branch and tag rulesets must also state `conditions.ref_name.include` and `conditions.ref_name.exclude`. Use `"bypass_actors": []` when nobody may bypass. Incomplete declarations fail before GitHub is contacted, with an error naming each missing field. Add the intended values to existing local rulesets before upgrading; no defaults or warning period apply.
+
+Push rulesets apply to every push and must omit `conditions`, as described in [GitHub's push-ruleset documentation](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets#push-rulesets).
+
 `--apply` needs admin authentication and rechecks the API response instead of treating an accepted request as success. A repository whose plan cannot enforce rulesets may declare `"rulesetEnforcement": "unavailable-on-plan"` in the local settings file.
 
 ## creds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {

package/src/github-bypass-actors.ts

@@ -2,7 +2,7 @@
 // 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';
+import { BYPASS_ACTORS_KEY } from './github-settings-parse';
 
 // 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

package/src/github-ruleset-diff.ts

@@ -3,9 +3,11 @@
 // 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';
+import {
+  BYPASS_ACTORS_KEY,
+  isRecord,
+  rulesetComparedKeys,
+} from './github-settings-parse';
 
 // 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;
@@ -21,13 +23,6 @@ export type RulesetDiff = {
   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>>,
@@ -99,15 +94,13 @@ export const diffRuleset = (
   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])}`,
-        );
-      }
+  for (const key of rulesetComparedKeys(declared.target)) {
+    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));

package/src/github-ruleset-visibility.ts

@@ -8,10 +8,8 @@ import {
   ADMIN_VISIBILITY_ADVICE,
   unverifiableProblem,
 } from './github-command-shared';
-import {
-  BYPASS_ACTORS_KEY,
-  type UnverifiableRulesetField,
-} from './github-ruleset-diff';
+import type { UnverifiableRulesetField } from './github-ruleset-diff';
+import { BYPASS_ACTORS_KEY } from './github-settings-parse';
 
 const SCOPE = 'ruleset field(s)';
 

package/src/github-settings-parse.ts

@@ -45,6 +45,89 @@ export const isNamedRuleset = (
 ): value is Readonly<Record<string, unknown>> & { readonly name: string } =>
   isRecord(value) && typeof value.name === 'string' && value.name.length > 0;
 
+export const BYPASS_ACTORS_KEY = 'bypass_actors';
+const RULESET_COMPARED_KEYS = [
+  'target',
+  'enforcement',
+  'conditions',
+  BYPASS_ACTORS_KEY,
+] as const;
+
+// Push rules cover every push to the repository and have no ref-name scope.
+// The parser and comparison share the same field contract.
+export const rulesetComparedKeys = (target: unknown) =>
+  target === 'push'
+    ? RULESET_COMPARED_KEYS.filter((key) => key !== 'conditions')
+    : RULESET_COMPARED_KEYS;
+
+const isStringList = (value: unknown): value is ReadonlyArray<string> =>
+  Array.isArray(value) && value.every((item) => typeof item === 'string');
+
+const isOneOf = (value: unknown, choices: ReadonlyArray<string>): boolean =>
+  typeof value === 'string' && choices.includes(value);
+
+const rulesetConditionsProblem = (
+  ruleset: Readonly<Record<string, unknown>>,
+  prefix: string,
+): string | null => {
+  if (ruleset.conditions === undefined) {
+    return null;
+  }
+  if (ruleset.target === 'push') {
+    return `${prefix} must omit "conditions" for target "push", which applies to every push`;
+  }
+  const refName = isRecord(ruleset.conditions)
+    ? ruleset.conditions.ref_name
+    : undefined;
+  return isRecord(refName) &&
+    isStringList(refName.include) &&
+    isStringList(refName.exclude)
+    ? null
+    : `${prefix} "conditions" must declare "ref_name.include" and "ref_name.exclude" as arrays of strings`;
+};
+
+const rulesetFieldProblems = (
+  ruleset: Readonly<Record<string, unknown>>,
+  label: string,
+): ReadonlyArray<string> => {
+  const problems: Array<string> = [];
+  const prefix = `${label} ruleset "${String(ruleset.name)}"`;
+  for (const key of rulesetComparedKeys(ruleset.target)) {
+    if (ruleset[key] === undefined) {
+      const advice =
+        key === BYPASS_ACTORS_KEY ? '; use [] if nobody may bypass' : '';
+      problems.push(`${prefix} must declare "${key}"${advice}`);
+    }
+  }
+  if (
+    ruleset.target !== undefined &&
+    !isOneOf(ruleset.target, ['branch', 'tag', 'push'])
+  ) {
+    problems.push(`${prefix} "target" must be "branch", "tag", or "push"`);
+  }
+  if (
+    ruleset.enforcement !== undefined &&
+    !isOneOf(ruleset.enforcement, ['active', 'disabled', 'evaluate'])
+  ) {
+    problems.push(
+      `${prefix} "enforcement" must be "active", "disabled", or "evaluate"`,
+    );
+  }
+  if (
+    ruleset[BYPASS_ACTORS_KEY] !== undefined &&
+    !Array.isArray(ruleset[BYPASS_ACTORS_KEY])
+  ) {
+    problems.push(
+      `${prefix} "${BYPASS_ACTORS_KEY}" must be an array; use [] if nobody may bypass`,
+    );
+  }
+  const conditionsProblem = rulesetConditionsProblem(ruleset, prefix);
+  if (conditionsProblem !== null) {
+    problems.push(conditionsProblem);
+  }
+  return problems;
+};
+
 const LABEL_COLOR = /^[0-9a-f]{6}$/u;
 const LABEL_DECLARATION_KEY_COUNT = 3;
 
@@ -98,6 +181,9 @@ const rulesetListProblems = (
     } else {
       names.add(ruleset.name);
     }
+    if (isNamedRuleset(ruleset)) {
+      problems.push(...rulesetFieldProblems(ruleset, label));
+    }
   }
   return problems;
 };