@davidvornholt/standards 0.27.0 → 0.29.0

package/README.md

@@ -97,7 +97,15 @@ bun standards structure --profile source
 
 `doctor` checks project-owned integration points such as `biome.jsonc`, `AGENTS.local.md`, package scripts, sync policy, settings overlays, and Dependabot inputs.
 
-`structure` checks the exact Bun declaration, workspace scripts, internal dependency versions, package exports, TypeScript inheritance, accessibility wiring, and CI secret structure. The `source` profile records the few intentional differences in this repository itself.
+`structure` checks the exact Bun declaration, root and workspace scripts, internal dependency versions, package exports, TypeScript inheritance, accessibility wiring, and CI secret structure. The `source` profile records the few intentional differences in this repository itself.
+
+Starting with 0.29.0, Biome runs once from the repository root instead of once per workspace. The root `package.json` must declare `lint` running `biome check --error-on-warnings .` and `lint:fix` running `biome check --write --error-on-warnings .`, and any workspace that declares `lint` or `lint:fix` fails. To upgrade an existing repository:
+
+1. Install the new CLI with `bun add --dev --exact @davidvornholt/standards@0.29.0`.
+2. Run `bun standards sync` so the canonical `packages/typescript-config` and `packages/a11y-testing` drop their lint scripts. A repository that pins `ref` in `sync-standards.local.json` first moves it to `v0.29.0` or later.
+3. Add the root `lint` and `lint:fix` scripts and remove both scripts from every workspace `package.json`.
+4. In `turbo.json`, replace the `lint` and `lint:fix` tasks with `//#lint` (`"outputs": []`) and `//#lint:fix` (`"cache": false`, `"outputs": []`), and delete any `<package>#lint` overrides. Keep the default inputs for `//#lint`.
+5. Run `bun run lint:fix` and fix anything it still reports. The root run also checks root files that per-workspace runs never covered.
 
 ## dependabot
 
@@ -182,6 +190,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
@@ -236,7 +248,7 @@ Bootstrap credentials and singular tokens still owned by an active repository ar
 
 ### Prepare existing consumers for GitHub App client IDs
 
-`standards creds add github --dest ci:ci.broker_app` writes and verifies `app_id`, `client_id`, and `private_key` together. Run it in each existing consumer, mirror the new `client_id` key with a placeholder in its `secrets/ci.example.yaml`, and commit both files before adopting a workflow that resolves `broker_app.client_id` and passes `client-id` to `actions/create-github-app-token@v3`. The numeric `app_id` remains available while existing workflows are migrated. Do not remove it until every local and canonical caller has switched. Canonical workflows continue using `app-id` until consumer provisioning is complete.
+`standards creds add github --dest ci:ci.broker_app` writes and verifies `app_id`, `client_id`, and `private_key` together. The canonical Standards sync workflow passes `client-id` to `actions/create-github-app-token@v3` when `ci.broker_app.client_id` exists and falls back to the deprecated `app-id` when it does not. Provision `client_id` in each existing consumer before a future release drops that fallback: re-run `bun standards creds add github --dest ci:ci.broker_app`, or add the App's public client ID at `ci.broker_app.client_id` with `sops`. Mirror the new key with a placeholder in `secrets/ci.example.yaml` and commit both files. Keep the numeric `app_id` until every local and canonical caller has switched to `client-id`.
 
 ## screenshots
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -180,8 +180,6 @@
     "src/sops-action-callers.ts"
   ],
   "scripts": {
-    "lint": "biome check --error-on-warnings .",
-    "lint:fix": "biome check --write --error-on-warnings .",
     "check-types": "tsc --noEmit",
     "test": "bun test"
   },

package/src/cli.ts

@@ -389,11 +389,31 @@ type MirrorResult = {
   readonly stale: ReadonlyArray<string>;
 };
 
+type MirrorCommand = 'init' | 'sync';
+
 type MirrorOptions = {
   readonly upstream: ReadonlyMap<string, ManagedEntry>;
   readonly consumer: string;
   readonly previous: Record<string, string>;
   readonly dryRun: boolean;
+  readonly command: MirrorCommand;
+};
+
+// A copy or zip tool that follows links turns a managed link into a directory of
+// copies. Those copies are not in the lock, so the run refuses; for a link the
+// message names what the path should be and the exact way back to it.
+const directoryCollision = (
+  rel: string,
+  entry: ManagedEntry,
+  unlocked: ReadonlyArray<string>,
+  command: MirrorCommand,
+): string => {
+  const holding = `${unlocked.length} path(s) this repository does not manage (${unlocked.slice(0, COLLISION_SAMPLE).join(', ')})`;
+  if (entry.kind !== 'symlink') {
+    return `${rel} is a directory holding ${holding}; move or delete them, then re-run`;
+  }
+  const canonical = posix.join(posix.dirname(rel), entry.target);
+  return `${rel} should be a symlink to the canonical ${canonical}, but it is a directory holding ${holding}; copy and zip tools that follow links can cause this. First move any of your own files out of ${rel}, then run \`rm -rf ${rel} && bun standards ${command}\``;
 };
 
 // Two things init/sync must settle before their first write: an escaping
@@ -408,10 +428,11 @@ const mirrorPreconditionProblems = async (
   consumer: string,
   upstream: ReadonlyMap<string, ManagedEntry>,
   previous: Record<string, string>,
+  command: MirrorCommand,
 ): Promise<ReadonlyArray<string>> => {
   const locked = new Set(Object.keys(previous));
   const collisions = await Promise.all(
-    [...upstream.keys()].map(async (rel) => {
+    [...upstream].map(async ([rel, entry]) => {
       const ancestor = await interposedAncestor(consumer, rel, upstream);
       if (ancestor !== null) {
         return `${rel} is below the ${ancestor.kind} ${ancestor.rel}; refusing to write through an existing file or symlink ancestor; move it aside before syncing this payload`;
@@ -423,7 +444,7 @@ const mirrorPreconditionProblems = async (
       const unlocked = await unlockedPathsUnder(consumer, rel, locked);
       return unlocked.length === 0
         ? null
-        : `${rel} is a directory holding ${unlocked.length} path(s) this repository does not manage (${unlocked.slice(0, COLLISION_SAMPLE).join(', ')}); move or delete them, then re-run`;
+        : directoryCollision(rel, entry, unlocked, command);
     }),
   );
   return [
@@ -545,12 +566,13 @@ const mirror = async ({
   consumer,
   previous,
   dryRun,
+  command,
 }: MirrorOptions): Promise<MirrorResult> => {
   for (const rel of Object.keys(previous)) {
     assertSafeRelativePath(rel, 'sync-standards.lock file');
   }
   assertNoProblems(
-    await mirrorPreconditionProblems(consumer, upstream, previous),
+    await mirrorPreconditionProblems(consumer, upstream, previous, command),
     'cannot mirror canonical files',
   );
   const next: Record<string, string> = {};
@@ -682,7 +704,7 @@ const runInit = async (
   assertNoProblems(
     [
       ...symlinkTargetProblems(seeds),
-      ...(await mirrorPreconditionProblems(consumer, upstream, {})),
+      ...(await mirrorPreconditionProblems(consumer, upstream, {}, 'init')),
     ],
     'cannot initialize from this source',
   );
@@ -712,6 +734,7 @@ const runInit = async (
     consumer,
     previous: {},
     dryRun: false,
+    command: 'init',
   });
   reportMirror(result, false);
   await applyProspectiveDependabot(consumer, prospectiveDependabot, false);
@@ -745,6 +768,7 @@ const runSync = async (
     consumer,
     previous: lock?.files ?? {},
     dryRun,
+    command: 'sync',
   });
   reportMirror(result, dryRun);
   const generated = await applyProspectiveDependabot(

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

package/src/poller-config.ts

@@ -14,7 +14,6 @@ const CONFIG_KEYS: ReadonlySet<string> = new Set([
   'repos',
   'model',
   'reasoningEffort',
-  // biome-ignore lint/security/noSecrets: a config key name, not a credential.
   'maxJobsPerTick',
   'staleClaimHours',
   'runTimeoutMinutes',
@@ -167,7 +166,6 @@ export const parsePollerConfig = (
     ),
     maxJobsPerTick: parsePositiveInteger(
       raw.maxJobsPerTick,
-      // biome-ignore lint/security/noSecrets: a config key name, not a credential.
       'maxJobsPerTick',
       DEFAULT_MAX_JOBS_PER_TICK,
       problems,

package/src/poller-github-pulls.ts

@@ -175,7 +175,6 @@ export const markPullRequestReady = async (
 ): Promise<void> => {
   const response = await request(token, 'POST', '/graphql', {
     query:
-      // biome-ignore lint/security/noSecrets: a GraphQL mutation string, not a credential.
       'mutation($id: ID!) { markPullRequestReadyForReview(input: {pullRequestId: $id}) { pullRequest { isDraft } } }',
     variables: { id: pullRequestNodeId },
   });

package/src/poller-outcome.ts

@@ -19,8 +19,12 @@ const hasExactKeys = (
   value: Readonly<Record<string, unknown>>,
   expected: ReadonlyArray<string>,
 ): boolean => {
-  const actual = Object.keys(value).sort();
-  const sortedExpected = [...expected].sort();
+  const actual = Object.keys(value).sort((left, right) =>
+    left.localeCompare(right),
+  );
+  const sortedExpected = [...expected].sort((left, right) =>
+    left.localeCompare(right),
+  );
   return (
     actual.length === sortedExpected.length &&
     actual.every((key, index) => key === sortedExpected[index])

package/src/poller-review-plan-parse.ts

@@ -22,8 +22,10 @@ const hasExactKeys = (
   value: Readonly<Record<string, unknown>>,
   keys: ReadonlyArray<string>,
 ): boolean => {
-  const actual = Object.keys(value).sort();
-  const expected = [...keys].sort();
+  const actual = Object.keys(value).sort((left, right) =>
+    left.localeCompare(right),
+  );
+  const expected = [...keys].sort((left, right) => left.localeCompare(right));
   return (
     actual.length === expected.length &&
     actual.every((key, index) => key === expected[index])

package/src/poller-review-thread-write.ts

@@ -2,7 +2,6 @@ import { apiError, HTTP_OK, request } from './github-api';
 import { isRecord } from './github-settings-parse';
 
 const REPLY_MUTATION =
-  // biome-ignore lint/security/noSecrets: a GraphQL mutation string, not a credential.
   'mutation($id: ID!, $body: String!) { addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $id, body: $body }) { comment { id } } }';
 
 const RESOLVE_MUTATION =

package/src/structure-check.ts

@@ -16,7 +16,7 @@ import { collectCiSecretsProblems } from './structure-secrets';
 import { inspectWorkspace, type Workspace } from './structure-workspace';
 
 const ROOT_FIXED_SCRIPTS = new Set(
-  'standards,check,check:fix,test:a11y'.split(','),
+  'standards,check,check:fix,lint,lint:fix,test:a11y'.split(','),
 );
 const GLOB_SUFFIX = '/*';
 const WORKSPACES_REQUIREMENT =

package/src/structure-profile.ts

@@ -13,6 +13,8 @@ const CONSUMER_CHECK =
 const CONSUMER_CHECK_FIX =
   'turbo run lint:fix check-types test build test:a11y --output-logs=errors-only';
 const ROOT_A11Y = 'turbo run test:a11y';
+const ROOT_LINT = 'biome check --error-on-warnings .';
+const ROOT_LINT_FIX = 'biome check --write --error-on-warnings .';
 
 export const PUBLISHED_CLI_WORKSPACE = 'packages/standards-cli';
 const PUBLISHED_CLI_PACKAGE = '@davidvornholt/standards';
@@ -51,6 +53,14 @@ const SOURCE_ROOT_EXPECTATIONS: ReadonlyArray<RootScriptExpectation> = [
   },
 ];
 
+// Biome runs once over the whole repository from the root. With the project
+// domain on, every invocation loads the entire repository, so one root run
+// replaces a full project load per workspace and also covers root files.
+const ROOT_LINT_EXPECTATIONS: ReadonlyArray<RootScriptExpectation> = [
+  { name: 'lint', commands: [ROOT_LINT], exact: true },
+  { name: 'lint:fix', commands: [ROOT_LINT_FIX], exact: true },
+];
+
 export const rootScriptExpectations = (
   profile: StructureProfile,
   requireA11y: boolean,
@@ -61,6 +71,7 @@ export const rootScriptExpectations = (
         { name: 'check', commands: [CONSUMER_CHECK], exact: false },
         { name: 'check:fix', commands: [CONSUMER_CHECK_FIX], exact: false },
       ]),
+  ...ROOT_LINT_EXPECTATIONS,
   ...(requireA11y
     ? [{ name: 'test:a11y', commands: [ROOT_A11Y], exact: false }]
     : []),

package/src/structure-workspace.ts

@@ -13,10 +13,12 @@ export type Workspace = {
 };
 const WORKSPACE_SCRIPTS: ReadonlyArray<readonly [string, string]> = [
   ['check-types', 'tsc --noEmit'],
-  ['lint', 'biome check --error-on-warnings .'],
-  ['lint:fix', 'biome check --write --error-on-warnings .'],
   ['test', 'bun test'],
 ];
+// Biome lints the whole repository once from the root "lint" scripts, and
+// Turbo runs only that root task. A workspace copy would be a stale second
+// entry point, so declaring one fails instead of being silently ignored.
+const ROOT_ONLY_SCRIPTS = ['lint', 'lint:fix'] as const;
 const A11Y_DEPENDENCIES = ['@axe-core/playwright', '@playwright/test'] as const;
 const DEPENDENCY_FIELDS =
   'dependencies devDependencies peerDependencies optionalDependencies'.split(
@@ -57,8 +59,9 @@ const containsA11ySuite = async (dir: string): Promise<boolean> => {
   );
   return nested.includes(true);
 };
-const inspectScripts = (ws: Workspace): ReadonlyArray<string> =>
-  WORKSPACE_SCRIPTS.flatMap(([name, command]) => {
+const inspectScripts = (ws: Workspace): ReadonlyArray<string> => {
+  const scripts = isRecord(ws.manifest.scripts) ? ws.manifest.scripts : {};
+  const required = WORKSPACE_SCRIPTS.flatMap(([name, command]) => {
     const script = scriptOf(ws.manifest, name);
     const accepted =
       hasSafeCommand(script, command) ||
@@ -67,6 +70,14 @@ const inspectScripts = (ws: Workspace): ReadonlyArray<string> =>
       name === 'test' ? 'bun test or bun test --isolate' : command;
     return accepted ? [] : [`${ws.rel}: script "${name}" must run ${expected}`];
   });
+  const rootOnly = ROOT_ONLY_SCRIPTS.filter((name) =>
+    Object.hasOwn(scripts, name),
+  ).map(
+    (name) =>
+      `${ws.rel}: remove script "${name}"; linting runs once at the repository root through the root "lint" and "lint:fix" scripts`,
+  );
+  return [...required, ...rootOnly];
+};
 const declaredDependencies = (manifest: Record<string, unknown>) =>
   DEPENDENCY_FIELDS.flatMap((field) => {
     const deps = manifest[field];