@davidvornholt/standards 0.28.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
 
@@ -240,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.28.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/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];