@davidvornholt/standards 0.5.0 → 0.7.0

package/README.md

@@ -7,14 +7,18 @@ bunx @davidvornholt/standards init
 standards sync
 standards check
 standards doctor
+standards structure
 standards github --check
 standards github --apply
 ```
 
 `github --check` compares the live GitHub repository (merge settings and rulesets) against the merged declaration in `.github/settings.json` + `.github/settings.local.json`; `github --apply` converges the live repository to exactly the declared state. `check` runs the same comparison whenever `.github/settings.json` is present.
 
+`structure` enforces the canonical monorepo structure contract: workspace scripts (`check-types`, `lint`, `lint:fix`, `test`), root gate scripts, filtered Turbo convenience aliases, internal `0.0.0`/`workspace:*` versioning, package `exports`, shared tsconfig inheritance, and browser a11y wiring. Only a workspace containing an explicit `*.a11y.ts` suite must provide a `test:a11y` script and direct `@axe-core/playwright` and `@playwright/test` dependencies. `check` includes `structure`, so these rules gate every consumer PR.
+
 ## Configuration
 
+- **`sync-standards.local.json`** (optional) — consumer-owned sync policy at the repo root, validated by `doctor`/`check` and every `init`/`sync` even when an explicit ref or local source makes its `"ref"` irrelevant. All fields optional; a missing file means the defaults. `"ref"` is a non-empty single-line string that pins a tag, branch, or full commit sha to sync from instead of `main` (an explicit `--ref` overrides it; a local-path `--from` source is used as-is and ignores only the validated pin). `"autoSync": false` is read by the standards-sync workflow, not the CLI, and skips the weekly scheduled run. Version 0.7.0 removes the legacy `STANDARDS_AUTO_SYNC` and `STANDARDS_SYNC_REF` variable behavior; consumers must upgrade the package and lockfile before adopting a policy file.
 - **`GH_TOKEN` / `GITHUB_TOKEN`** (optional) — GitHub API token for the `github` command and the GitHub portion of `check`. When neither is set, the token from the local `gh` CLI is used; with no token at all, reads still work on public repositories. `--apply` and private-repo reads need an authenticated token, and repo merge settings are only visible (and thus verifiable) to admin tokens — non-admin runs report them as unverifiable.
 
 See the standards repository README for the ownership model and adoption workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,9 @@
     "src/github-apply.ts",
     "src/github-commands.ts",
     "src/github-diff.ts",
-    "src/github-settings.ts"
+    "src/github-settings.ts",
+    "src/structure-check.ts",
+    "src/structure-workspace.ts"
   ],
   "scripts": {
     "lint": "biome check --error-on-warnings .",

package/src/cli.ts

@@ -26,7 +26,7 @@ import {
   dirname,
   isAbsolute,
   join,
-  normalize,
+  posix,
   relative,
   resolve,
   sep,
@@ -35,6 +35,8 @@ import process from 'node:process';
 import { CANONICAL_SETTINGS_FILE, LOCAL_SETTINGS_FILE } from './github-api';
 import { runGithubApply, runGithubCheck } from './github-commands';
 import { loadGithubSettings } from './github-settings';
+import { collectStructureProblems } from './structure-check';
+import { hasSafeCommand } from './structure-workspace';
 
 const { YAML: BunYaml } = await import('bun');
 
@@ -74,7 +76,14 @@ type Source = {
   readonly cleanup: () => void;
 };
 
-type Command = 'check' | 'doctor' | 'github' | 'help' | 'init' | 'sync';
+type Command =
+  | 'check'
+  | 'doctor'
+  | 'github'
+  | 'help'
+  | 'init'
+  | 'structure'
+  | 'sync';
 
 type CliOptions = {
   readonly command: Command | undefined;
@@ -91,7 +100,9 @@ const sha256 = (buf: Buffer): string =>
 const toPosix = (p: string): string => p.split(sep).join('/');
 
 const assertSafeRelativePath = (path: string, label: string): void => {
-  const normalized = normalize(path);
+  // POSIX semantics on every platform: managed paths are repository-relative
+  // POSIX paths, and win32 normalize would rewrite `/` to `\` and reject them.
+  const normalized = posix.normalize(path);
   if (
     path.length === 0 ||
     path === '.' ||
@@ -672,11 +683,19 @@ const inspectDependabot = (raw: string): ReadonlyArray<string> => {
 
 const inspectPackageJson = (packageRaw: string): ReadonlyArray<string> => {
   const problems: Array<string> = [];
-  const packageJson = JSON.parse(packageRaw) as Record<string, unknown>;
-  const scripts = packageJson.scripts as Record<string, unknown> | undefined;
-  const devDependencies = packageJson.devDependencies as
-    | Record<string, unknown>
-    | undefined;
+  let packageJson: unknown;
+  try {
+    packageJson = JSON.parse(packageRaw);
+  } catch {
+    return ['package.json must contain valid JSON'];
+  }
+  if (!isRecord(packageJson)) {
+    return ['package.json must contain a JSON object'];
+  }
+  const scripts = isRecord(packageJson.scripts) ? packageJson.scripts : {};
+  const devDependencies = isRecord(packageJson.devDependencies)
+    ? packageJson.devDependencies
+    : {};
   if (typeof devDependencies?.['@davidvornholt/standards'] !== 'string') {
     problems.push(
       'package.json must declare @davidvornholt/standards directly',
@@ -684,7 +703,10 @@ const inspectPackageJson = (packageRaw: string): ReadonlyArray<string> => {
   }
   for (const name of ['check', 'check:fix']) {
     const script = scripts?.[name];
-    if (typeof script !== 'string' || !script.includes('standards check')) {
+    if (
+      typeof script !== 'string' ||
+      !hasSafeCommand(script, 'standards check')
+    ) {
       problems.push(`package.json script "${name}" must run standards check`);
     }
   }
@@ -733,6 +755,8 @@ const runDoctor = async (consumer: string): Promise<boolean> => {
     );
   }
 
+  problems.push(...(await inspectPolicy(consumer)));
+
   if (problems.length > 0) {
     console.error(
       `standards doctor: ${problems.length} integration problem(s):`,
@@ -747,12 +771,13 @@ const runDoctor = async (consumer: string): Promise<boolean> => {
 const USAGE = `Usage: standards <command> [options]
 
 Commands:
-  init    Bootstrap a consumer repo: seed repo-owned files, mirror canonical files, write the lock
-  sync    Mirror canonical files from upstream and rewrite the lock
-  check   Verify canonical files, extension seams, and GitHub settings
-  doctor  Validate extension seams only
-  github  Compare (--check) or converge (--apply) live GitHub settings
-  help    Show this help
+  init       Bootstrap a consumer repo: seed repo-owned files, mirror canonical files, write the lock
+  sync       Mirror canonical files from upstream and rewrite the lock
+  check      Verify canonical files, extension seams, monorepo structure, and GitHub settings
+  doctor     Validate extension seams only
+  structure  Validate monorepo structure rules only
+  github     Compare (--check) or converge (--apply) live GitHub settings
+  help       Show this help
 
 Options:
   --dir <path>   Consumer directory to operate on (default: current directory)
@@ -769,6 +794,7 @@ const commandFromArg = (arg: string): Command => {
     arg === 'github' ||
     arg === 'help' ||
     arg === 'init' ||
+    arg === 'structure' ||
     arg === 'sync'
   ) {
     return arg;
@@ -861,18 +887,112 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
   };
 };
 
+// Canonical monorepo structure gate: workspace and root script shapes,
+// internal versioning, `exports`, tsconfig inheritance, and a11y wiring.
+const runStructure = async (consumer: string): Promise<boolean> => {
+  const problems = await collectStructureProblems(consumer);
+  if (problems.length > 0) {
+    console.error(
+      `standards structure: ${problems.length} monorepo structure problem(s):`,
+    );
+    console.error(problems.map((problem) => `  - ${problem}`).join('\n'));
+    return false;
+  }
+  console.log('standards structure: workspace layout matches the standards');
+  return true;
+};
+
 const runCheckCommand = async (consumer: string): Promise<boolean> => {
   const driftIsClean = await runCheck(consumer);
   const integrationIsValid = await runDoctor(consumer);
+  const structureIsValid = await runStructure(consumer);
   // The GitHub gate activates with the synced declaration and then fails
   // closed: once .github/settings.json exists, an unreachable API or an
   // unreadable origin is a failure, not a skip.
   const githubIsConverged = existsSync(join(consumer, CANONICAL_SETTINGS_FILE))
     ? await runGithubCheck(consumer)
     : true;
-  return driftIsClean && integrationIsValid && githubIsConverged;
+  return (
+    driftIsClean && integrationIsValid && structureIsValid && githubIsConverged
+  );
+};
+
+// Consumer-owned sync policy, checked in next to the canonical (read-only)
+// standards-sync workflow it configures — versioned and reviewable, unlike
+// repository Actions variables. All fields are optional; a missing file means
+// the defaults (track main, weekly auto-sync on).
+//   autoSync  false skips the scheduled workflow run; manual dispatch and
+//             local CLI runs are deliberate acts and always proceed.
+//   ref       tag, branch, or full commit sha to sync from instead of main.
+const POLICY_FILE = 'sync-standards.local.json';
+const LINE_BREAK = /[\r\n]/u;
+
+type Policy = {
+  readonly autoSync?: boolean;
+  readonly ref?: string;
 };
 
+const parsePolicy = (parsed: unknown): Policy => {
+  if (!isRecord(parsed)) {
+    throw new Error(`${POLICY_FILE} must be a JSON object`);
+  }
+  const unsupportedFields = Object.keys(parsed).filter(
+    (field) => field !== 'autoSync' && field !== 'ref',
+  );
+  if (unsupportedFields.length > 0) {
+    throw new Error(
+      `${POLICY_FILE} contains unsupported field(s): ${unsupportedFields.join(', ')}`,
+    );
+  }
+  if (parsed.autoSync !== undefined && typeof parsed.autoSync !== 'boolean') {
+    throw new Error(`${POLICY_FILE} "autoSync" must be a boolean`);
+  }
+  if (
+    parsed.ref !== undefined &&
+    (!isNonEmptyString(parsed.ref) || LINE_BREAK.test(parsed.ref))
+  ) {
+    throw new Error(
+      `${POLICY_FILE} "ref" must be a non-empty single-line string`,
+    );
+  }
+  return { autoSync: parsed.autoSync, ref: parsed.ref };
+};
+
+const readPolicy = async (consumer: string): Promise<Policy> => {
+  const raw = await readTextIfPresent(join(consumer, POLICY_FILE));
+  if (raw === null) {
+    return {};
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${POLICY_FILE} must contain valid JSON`, { cause: error });
+  }
+  return parsePolicy(parsed);
+};
+
+const inspectPolicy = async (
+  consumer: string,
+): Promise<ReadonlyArray<string>> => {
+  try {
+    await readPolicy(consumer);
+    return [];
+  } catch (error) {
+    return [error instanceof Error ? error.message : String(error)];
+  }
+};
+
+// Policy validation is unconditional once the file exists. Selection happens
+// afterward: explicit refs win for remote sources, while local paths are used
+// as-is and ignore only the already-validated policy ref.
+const selectedRef = (
+  src: string,
+  explicitRef: string | undefined,
+  policy: Policy,
+): string | undefined =>
+  existsSync(src) ? explicitRef : (explicitRef ?? policy.ref);
+
 const runInitCommand = async (
   consumer: string,
   from: string | undefined,
@@ -888,7 +1008,9 @@ const runInitCommand = async (
     process.exitCode = 1;
     return;
   }
-  const source = resolveSource(from ?? DEFAULT_UPSTREAM, ref);
+  const src = from ?? DEFAULT_UPSTREAM;
+  const policy = await readPolicy(consumer);
+  const source = resolveSource(src, selectedRef(src, ref, policy));
   try {
     const manifest = await loadManifest(
       join(source.dir, 'sync-standards.json'),
@@ -908,7 +1030,9 @@ const runSyncCommand = async (
   const consumerManifest = await loadManifest(
     join(consumer, 'sync-standards.json'),
   );
-  const source = resolveSource(from ?? consumerManifest.upstream, ref);
+  const src = from ?? consumerManifest.upstream;
+  const policy = await readPolicy(consumer);
+  const source = resolveSource(src, selectedRef(src, ref, policy));
   try {
     const manifest = await loadManifest(
       join(source.dir, 'sync-standards.json'),
@@ -919,6 +1043,24 @@ const runSyncCommand = async (
   }
 };
 
+// Commands whose success is reported through the exit code.
+const runGateCommand = (
+  command: 'check' | 'doctor' | 'github' | 'structure',
+  consumer: string,
+  apply: boolean,
+): Promise<boolean> => {
+  if (command === 'check') {
+    return runCheckCommand(consumer);
+  }
+  if (command === 'doctor') {
+    return runDoctor(consumer);
+  }
+  if (command === 'structure') {
+    return runStructure(consumer);
+  }
+  return apply ? runGithubApply(consumer) : runGithubCheck(consumer);
+};
+
 const main = async (): Promise<void> => {
   const { command, consumer, dryRun, from, ref, apply } = parseArgs(
     process.argv.slice(2),
@@ -936,30 +1078,6 @@ const main = async (): Promise<void> => {
     return;
   }
 
-  if (command === 'check') {
-    if (!(await runCheckCommand(consumer))) {
-      process.exitCode = 1;
-    }
-    return;
-  }
-
-  if (command === 'github') {
-    const converged = apply
-      ? await runGithubApply(consumer)
-      : await runGithubCheck(consumer);
-    if (!converged) {
-      process.exitCode = 1;
-    }
-    return;
-  }
-
-  if (command === 'doctor') {
-    if (!(await runDoctor(consumer))) {
-      process.exitCode = 1;
-    }
-    return;
-  }
-
   if (command === 'init') {
     await runInitCommand(consumer, from, ref);
     return;
@@ -967,6 +1085,11 @@ const main = async (): Promise<void> => {
 
   if (command === 'sync') {
     await runSyncCommand(consumer, from, ref, dryRun);
+    return;
+  }
+
+  if (!(await runGateCommand(command, consumer, apply))) {
+    process.exitCode = 1;
   }
 };
 

package/src/structure-check.ts

@@ -0,0 +1,198 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { isRecord } from './github-settings';
+import {
+  hasSafeCommand,
+  inspectWorkspace,
+  isSafeFilteredTurboAlias,
+  type Workspace,
+} from './structure-workspace';
+
+const ROOT_CHECK = 'turbo run lint check-types test build test:a11y';
+const ROOT_CHECK_FIX = 'turbo run lint:fix check-types test build test:a11y';
+const ROOT_A11Y = 'turbo run test:a11y';
+
+const ROOT_FIXED_SCRIPTS = new Set([
+  'standards',
+  'check',
+  'check:fix',
+  'test:a11y',
+]);
+const GLOB_SUFFIX = '/*';
+const WORKSPACES_REQUIREMENT =
+  'package.json: "workspaces" must be a non-empty array of literal paths or one-level "<dir>/*" patterns';
+
+const readJson = async (
+  path: string,
+): Promise<Record<string, unknown> | null> => {
+  const raw = await readFile(path, 'utf8').catch(() => null);
+  if (raw === null) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+type ResolvedPattern = {
+  readonly dirs: ReadonlyArray<string>;
+  readonly problem: string | null;
+};
+type WorkspacePatterns = {
+  readonly patterns: ReadonlyArray<string>;
+  readonly problems: ReadonlyArray<string>;
+};
+const isSafeWorkspacePath = (pattern: string): boolean =>
+  pattern.trim() !== '' &&
+  pattern === pattern.trim() &&
+  !isAbsolute(pattern) &&
+  !pattern.includes('\\') &&
+  pattern
+    .split('/')
+    .every((part) => part !== '' && part !== '.' && part !== '..');
+const workspacePatternsOf = (
+  root: Record<string, unknown>,
+): WorkspacePatterns => {
+  const { workspaces } = root;
+  if (!Array.isArray(workspaces) || workspaces.length === 0) {
+    return { patterns: [], problems: [WORKSPACES_REQUIREMENT] };
+  }
+  const patterns: Array<string> = [];
+  const problems: Array<string> = [];
+  workspaces.forEach((pattern, index) => {
+    if (typeof pattern !== 'string') {
+      problems.push(`package.json: workspaces[${index}] must be a string`);
+    } else if (isSafeWorkspacePath(pattern)) {
+      patterns.push(pattern);
+    } else {
+      problems.push(
+        `package.json: unsafe workspaces pattern "${pattern}"; use a relative path without "." or ".." segments`,
+      );
+    }
+  });
+  return { patterns, problems };
+};
+const resolvePattern = async (
+  consumer: string,
+  pattern: string,
+): Promise<ResolvedPattern> => {
+  if (
+    pattern.endsWith(GLOB_SUFFIX) &&
+    !pattern.slice(0, -GLOB_SUFFIX.length).includes('*')
+  ) {
+    const base = pattern.slice(0, -GLOB_SUFFIX.length);
+    const entries = await readdir(join(consumer, base), {
+      withFileTypes: true,
+    }).catch((error: unknown) =>
+      isRecord(error) && error.code === 'ENOENT' ? [] : null,
+    );
+    if (entries === null) {
+      return {
+        dirs: [],
+        problem: `package.json: cannot read workspace directory "${base}" declared by "${pattern}"`,
+      };
+    }
+    return {
+      dirs: entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => `${base}/${entry.name}`),
+      problem: null,
+    };
+  }
+  if (pattern.includes('*')) {
+    return {
+      dirs: [],
+      problem: `package.json: unsupported workspaces pattern "${pattern}"; use "<dir>/*" or a literal path`,
+    };
+  }
+  return { dirs: [pattern], problem: null };
+};
+type LoadedWorkspace = {
+  readonly workspace: Workspace | null;
+  readonly problem: string | null;
+};
+const loadWorkspace = async (
+  consumer: string,
+  rel: string,
+): Promise<LoadedWorkspace> => {
+  const path = join(consumer, rel, 'package.json');
+  if (!existsSync(path)) {
+    return { workspace: null, problem: null };
+  }
+  const manifest = await readJson(path);
+  if (manifest === null) {
+    return {
+      workspace: null,
+      problem: `${rel}: package.json must contain a JSON object`,
+    };
+  }
+  return {
+    workspace: { rel, dir: join(consumer, rel), manifest },
+    problem: null,
+  };
+};
+const inspectRootScripts = (
+  root: Record<string, unknown>,
+  requireA11y: boolean,
+): ReadonlyArray<string> => {
+  const scripts = isRecord(root.scripts) ? root.scripts : {};
+  const expectations: ReadonlyArray<readonly [string, string]> = [
+    ['check', ROOT_CHECK],
+    ['check:fix', ROOT_CHECK_FIX],
+    ...(requireA11y ? [['test:a11y', ROOT_A11Y] as const] : []),
+  ];
+  const gateProblems = expectations.flatMap(([name, fragment]) => {
+    const { [name]: script } = scripts;
+    return typeof script === 'string' && hasSafeCommand(script, fragment)
+      ? []
+      : [`package.json: root script "${name}" must run ${fragment}`];
+  });
+  const aliasProblems = Object.entries(scripts).flatMap(([name, script]) =>
+    ROOT_FIXED_SCRIPTS.has(name) ||
+    typeof script !== 'string' ||
+    isSafeFilteredTurboAlias(script)
+      ? []
+      : [
+          `package.json: root script "${name}" must delegate through Turbo with an explicit --filter`,
+        ],
+  );
+  return [...gateProblems, ...aliasProblems];
+};
+export const collectStructureProblems = async (
+  consumer: string,
+): Promise<ReadonlyArray<string>> => {
+  const root = await readJson(join(consumer, 'package.json'));
+  if (root === null) {
+    return ['package.json must exist and contain a JSON object'];
+  }
+  const declaration = workspacePatternsOf(root);
+  const resolved = await Promise.all(
+    declaration.patterns.map((pattern) => resolvePattern(consumer, pattern)),
+  );
+  const rels = [...new Set(resolved.flatMap((r) => r.dirs))].sort();
+  const loaded = await Promise.all(
+    rels.map((rel) => loadWorkspace(consumer, rel)),
+  );
+  const workspaces = loaded.flatMap((l) =>
+    l.workspace === null ? [] : [l.workspace],
+  );
+  const workspaceNames = new Set(
+    workspaces
+      .map((ws) => ws.manifest.name)
+      .filter((name): name is string => typeof name === 'string'),
+  );
+  const inspections = await Promise.all(
+    workspaces.map((ws) => inspectWorkspace(ws, workspaceNames)),
+  );
+  const requireA11y = inspections.some((i) => i.hasA11ySuite);
+  return [
+    ...declaration.problems,
+    ...resolved.flatMap((r) => (r.problem === null ? [] : [r.problem])),
+    ...loaded.flatMap((l) => (l.problem === null ? [] : [l.problem])),
+    ...inspectRootScripts(root, requireA11y),
+    ...inspections.flatMap((i) => [...i.problems]),
+  ];
+};

package/src/structure-workspace.ts

@@ -0,0 +1,200 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isRecord } from './github-settings';
+export type Workspace = {
+  readonly rel: string;
+  readonly dir: string;
+  readonly manifest: Record<string, unknown>;
+};
+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'],
+];
+const A11Y_DEPENDENCIES = ['@axe-core/playwright', '@playwright/test'] as const;
+const DEPENDENCY_FIELDS =
+  'dependencies devDependencies peerDependencies optionalDependencies'.split(
+    ' ',
+  );
+const SHARED_TSCONFIG_PACKAGE = '@davidvornholt/typescript-config';
+const SHARED_TSCONFIG_PATH =
+  /^@davidvornholt\/typescript-config\/(?:base|next|react-library)$/u;
+const UNSAFE_SCRIPT_SYNTAX = /[|;#"'`\r\n]/u;
+const SCRIPT_WHITESPACE = /\s+/u;
+const NON_EXECUTING_A11Y_OPTION =
+  /^(?:-h|-V|--(?:debug|help|last-failed|list|only-changed|ui|version))(?:=|$)/u;
+const NON_EXECUTING_TURBO_OPTION = /^(?:-h|-v|--(?:dry|help|version))(?:=|$)/u;
+const IGNORED_DIRS = new Set('.git,.next,.turbo,dist,node_modules'.split(','));
+const scriptOf = (
+  manifest: Record<string, unknown>,
+  name: string,
+): string | null => {
+  const scripts = isRecord(manifest.scripts) ? manifest.scripts : {};
+  const script = scripts[name];
+  return typeof script === 'string' ? script : null;
+};
+const safeCommands = (
+  script: string | null,
+): ReadonlyArray<ReadonlyArray<string>> | null => {
+  if (
+    script === null ||
+    script.trim() === '' ||
+    UNSAFE_SCRIPT_SYNTAX.test(script) ||
+    script.includes('$(')
+  ) {
+    return null;
+  }
+  const commands = script.split('&&').map((command) => command.trim());
+  return commands.some((command) => command === '' || command.includes('&'))
+    ? null
+    : commands.map((command) => command.split(SCRIPT_WHITESPACE));
+};
+export const hasSafeCommand = (
+  script: string | null,
+  expected: string,
+): boolean =>
+  safeCommands(script)?.some((tokens) => tokens.join(' ') === expected) ??
+  false;
+const hasSafeA11yCommand = (script: string | null): boolean =>
+  safeCommands(script)?.some(
+    (tokens) =>
+      tokens[0] === 'playwright' &&
+      tokens[1] === 'test' &&
+      tokens.slice(2).every((token) => !NON_EXECUTING_A11Y_OPTION.test(token)),
+  ) ?? false;
+export const isSafeFilteredTurboAlias = (script: string): boolean => {
+  const commands = safeCommands(script);
+  if (commands?.length !== 1) {
+    return false;
+  }
+  const [tokens] = commands;
+  const filterAt = tokens.findIndex(
+    (token) => token === '--filter' || token.startsWith('--filter='),
+  );
+  const filter = tokens[filterAt];
+  const filterValue =
+    filter === '--filter'
+      ? tokens[filterAt + 1]
+      : filter?.slice('--filter='.length);
+  return tokens[0] !== 'turbo' || tokens[1] !== 'run'
+    ? false
+    : tokens[2]?.startsWith('-') === false &&
+        !tokens.some((token) => NON_EXECUTING_TURBO_OPTION.test(token)) &&
+        filterValue !== undefined &&
+        filterValue !== '' &&
+        !filterValue.startsWith('-');
+};
+const containsA11ySuite = async (dir: string): Promise<boolean> => {
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  if (
+    entries.some((entry) => entry.isFile() && entry.name.endsWith('.a11y.ts'))
+  ) {
+    return true;
+  }
+  const nested = await Promise.all(
+    entries
+      .filter((entry) => entry.isDirectory() && !IGNORED_DIRS.has(entry.name))
+      .map((entry) => containsA11ySuite(join(dir, entry.name))),
+  );
+  return nested.includes(true);
+};
+const inspectScripts = (ws: Workspace): ReadonlyArray<string> =>
+  WORKSPACE_SCRIPTS.flatMap(([name, command]) =>
+    hasSafeCommand(scriptOf(ws.manifest, name), command)
+      ? []
+      : [`${ws.rel}: script "${name}" must run ${command}`],
+  );
+const declaredDependencies = (manifest: Record<string, unknown>) =>
+  DEPENDENCY_FIELDS.flatMap((field) => {
+    const deps = manifest[field];
+    return isRecord(deps) ? Object.entries(deps) : [];
+  });
+const inspectInternalDeps = (
+  ws: Workspace,
+  workspaceNames: ReadonlySet<string>,
+): ReadonlyArray<string> =>
+  declaredDependencies(ws.manifest).flatMap(([name, spec]) =>
+    workspaceNames.has(name) && spec !== 'workspace:*'
+      ? [`${ws.rel}: internal dependency "${name}" must use "workspace:*"`]
+      : [],
+  );
+const isSharedTsconfigPath = (value: unknown): value is string =>
+  typeof value === 'string' && SHARED_TSCONFIG_PATH.test(value);
+const extendsSharedTsconfig = (raw: string): boolean => {
+  let parsed: unknown;
+  try {
+    parsed = globalThis.Bun.JSONC.parse(raw);
+  } catch {
+    return false;
+  }
+  if (!isRecord(parsed)) {
+    return false;
+  }
+  const extensions = Array.isArray(parsed.extends)
+    ? parsed.extends
+    : [parsed.extends];
+  return (
+    extensions.every((value) => typeof value === 'string') &&
+    extensions.some(isSharedTsconfigPath)
+  );
+};
+const inspectTsconfig = async (
+  ws: Workspace,
+): Promise<ReadonlyArray<string>> => {
+  if (ws.manifest.name === SHARED_TSCONFIG_PACKAGE) {
+    return [];
+  }
+  const raw = await readFile(join(ws.dir, 'tsconfig.json'), 'utf8').catch(
+    () => null,
+  );
+  if (raw === null || !extendsSharedTsconfig(raw)) {
+    return [`${ws.rel}: tsconfig.json must extend ${SHARED_TSCONFIG_PACKAGE}`];
+  }
+  return [];
+};
+const inspectA11y = async (
+  ws: Workspace,
+): Promise<{ problems: ReadonlyArray<string>; hasSuite: boolean }> => {
+  const hasSuite = await containsA11ySuite(ws.dir);
+  if (!hasSuite) {
+    return { problems: [], hasSuite };
+  }
+  const declared = new Set(
+    declaredDependencies(ws.manifest).map(([name]) => name),
+  );
+  const problems = [
+    ...(hasSafeA11yCommand(scriptOf(ws.manifest, 'test:a11y'))
+      ? []
+      : [
+          `${ws.rel}: a *.a11y.ts suite requires a non-empty "test:a11y" script that runs playwright test`,
+        ]),
+    ...A11Y_DEPENDENCIES.filter((dep) => !declared.has(dep)).map(
+      (dep) =>
+        `${ws.rel}: a *.a11y.ts suite requires a direct dependency on ${dep}`,
+    ),
+  ];
+  return { problems, hasSuite };
+};
+export const inspectWorkspace = async (
+  ws: Workspace,
+  workspaceNames: ReadonlySet<string>,
+) => {
+  const [tsconfigProblems, a11y] = await Promise.all([
+    inspectTsconfig(ws),
+    inspectA11y(ws),
+  ]);
+  const problems = [
+    ...inspectScripts(ws),
+    ...(ws.manifest.version === '0.0.0'
+      ? []
+      : [`${ws.rel}: internal workspace version must be "0.0.0"`]),
+    ...inspectInternalDeps(ws, workspaceNames),
+    ...(ws.rel.startsWith('packages/') && ws.manifest.exports === undefined
+      ? [`${ws.rel}: package must define its public API with "exports"`]
+      : []),
+    ...tsconfigProblems,
+    ...a11y.problems,
+  ];
+  return { problems, hasA11ySuite: a11y.hasSuite };
+};