@davidvornholt/standards 0.28.0 → 0.29.1

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, the root lint tasks in `turbo.json`, 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.1`.
+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`. Starting with 0.29.1, `structure` fails until this step is done: Turbo runs the root lint scripts only through the `//#` tasks, so a leftover `lint` task makes `turbo run lint` pass without running Biome.
+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.1",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -173,6 +173,7 @@
     "src/structure-script.ts",
     "src/structure-secrets.ts",
     "src/structure-sops-envelope.ts",
+    "src/structure-turbo.ts",
     "src/structure-workspace.ts",
     "src/sync-policy.ts",
     "src/yaml-emit.ts",
@@ -180,8 +181,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(
@@ -1302,9 +1326,9 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
   };
 };
 
-// Canonical monorepo structure gate: workspace and root script shapes,
-// internal versioning, `exports`, tsconfig inheritance, a11y wiring,
-// and the undecrypted CI secrets contract
+// Canonical monorepo structure gate: workspace and root script shapes, the
+// root lint tasks in turbo.json, internal versioning, `exports`, tsconfig
+// inheritance, a11y wiring, and the undecrypted CI secrets contract
 // (SOPS shape mirroring plus the keys the synced workflows require).
 // The `source` profile instead pins the standards template repository's own
 // deliberate exceptions to the consumer contract.

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

@@ -13,10 +13,11 @@ import {
 } from './structure-profile';
 import { filteredTurboAliasProblem, hasSafeCommands } from './structure-script';
 import { collectCiSecretsProblems } from './structure-secrets';
+import { collectTurboLintProblems } from './structure-turbo';
 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 =
@@ -155,14 +156,17 @@ export const collectStructureProblems = async (
   consumer: string,
   profile: StructureProfile,
 ): Promise<ReadonlyArray<string>> => {
-  const [root, secretsProblems, callerProblems] = await Promise.all([
-    readJsonFile(join(consumer, 'package.json')),
-    collectCiSecretsProblems(consumer),
-    collectSopsActionCallerProblems(consumer),
-  ]);
+  const [root, turboProblems, secretsProblems, callerProblems] =
+    await Promise.all([
+      readJsonFile(join(consumer, 'package.json')),
+      collectTurboLintProblems(consumer),
+      collectCiSecretsProblems(consumer),
+      collectSopsActionCallerProblems(consumer),
+    ]);
   if (root === null) {
     return [
       'package.json must exist and contain a JSON object',
+      ...turboProblems,
       ...secretsProblems,
       ...callerProblems,
     ];
@@ -194,6 +198,7 @@ export const collectStructureProblems = async (
     ...missingPublishedCliProblems(profile, workspaces),
     ...collectBunVersionProblems(root),
     ...inspectRootScripts(root, profile, requireA11y),
+    ...turboProblems,
     ...inspections.flatMap((i) => [...i.problems]),
     ...secretsProblems,
     ...callerProblems,

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-turbo.ts

@@ -0,0 +1,89 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isRecord } from './github-settings-parse';
+
+// The root gate runs `turbo run lint` and `turbo run lint:fix`, and Turbo runs
+// a root package.json script only through a task registered as `//#<name>`.
+// A plain `lint` task targets workspace scripts, which no longer exist, so
+// Turbo runs nothing and the gate passes without linting. A cache hit also
+// skips Biome: narrowed `//#lint` inputs let CI replay main's cached pass after
+// a linted file changes, and a cached `//#lint:fix` replays instead of fixing.
+const ROOT_LINT_TASK = '//#lint';
+const ROOT_LINT_FIX_TASK = '//#lint:fix';
+const LINT_TASK_NAMES: ReadonlyArray<string> = ['lint', 'lint:fix'];
+const ROOT_PACKAGE = '//';
+
+const readTurboConfig = async (
+  consumer: string,
+): Promise<Record<string, unknown> | null> => {
+  const raw = await readFile(join(consumer, 'turbo.json'), 'utf8').catch(
+    () => null,
+  );
+  if (raw === null) {
+    return null;
+  }
+  try {
+    // Turbo accepts comments and trailing commas in turbo.json.
+    const parsed: unknown = globalThis.Bun.JSONC.parse(raw);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+
+// Matches `lint`, `lint:fix`, and `<package>#lint(:fix)` overrides, but not
+// the root `//#` tasks.
+const isWorkspaceLintTask = (key: string): boolean => {
+  const separator = key.lastIndexOf('#');
+  const owner = separator === -1 ? null : key.slice(0, separator);
+  return (
+    owner !== ROOT_PACKAGE && LINT_TASK_NAMES.includes(key.slice(separator + 1))
+  );
+};
+
+const rootLintProblems = (
+  tasks: Record<string, unknown>,
+): ReadonlyArray<string> => {
+  const { [ROOT_LINT_TASK]: lint, [ROOT_LINT_FIX_TASK]: lintFix } = tasks;
+  return [
+    ...(isRecord(lint)
+      ? []
+      : [
+          `turbo.json: define the root task "${ROOT_LINT_TASK}" as { "outputs": [] }; Turbo runs the root "lint" script only through that task, so without it turbo run lint never runs Biome`,
+        ]),
+    ...(isRecord(lint) && Object.hasOwn(lint, 'inputs')
+      ? [
+          `turbo.json: remove "inputs" from the root task "${ROOT_LINT_TASK}"; the default inputs cover every file Biome checks, and a narrower set replays a cached pass after a linted file changes`,
+        ]
+      : []),
+    ...(isRecord(lintFix)
+      ? []
+      : [
+          `turbo.json: define the root task "${ROOT_LINT_FIX_TASK}" as { "cache": false, "outputs": [] }; Turbo runs the root "lint:fix" script only through that task, so without it turbo run lint:fix never runs Biome`,
+        ]),
+    ...(isRecord(lintFix) && lintFix.cache !== false
+      ? [
+          `turbo.json: set "cache": false on the root task "${ROOT_LINT_FIX_TASK}"; a cache hit replays the previous output instead of running Biome's fixes`,
+        ]
+      : []),
+  ];
+};
+
+export const collectTurboLintProblems = async (
+  consumer: string,
+): Promise<ReadonlyArray<string>> => {
+  const config = await readTurboConfig(consumer);
+  if (config === null) {
+    return ['turbo.json must exist and contain a JSON object'];
+  }
+  const tasks = isRecord(config.tasks) ? config.tasks : {};
+  return [
+    ...rootLintProblems(tasks),
+    ...Object.keys(tasks)
+      .filter(isWorkspaceLintTask)
+      .map(
+        (key) =>
+          `turbo.json: remove task "${key}"; linting runs once at the repository root through the root tasks "${ROOT_LINT_TASK}" and "${ROOT_LINT_FIX_TASK}"`,
+      ),
+  ];
+};

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