@davidvornholt/standards 0.4.0 → 0.6.0

package/README.md

@@ -7,12 +7,15 @@ 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
 
 - **`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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.4.0",
+  "version": "0.6.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,13 +76,21 @@ 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;
   readonly consumer: string;
   readonly dryRun: boolean;
   readonly from: string | undefined;
+  readonly ref: string | undefined;
   readonly apply: boolean;
 };
 
@@ -90,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 === '.' ||
@@ -163,9 +175,15 @@ const writeLock = async (dir: string, lock: Lock): Promise<void> => {
 
 // Fetch the template into a working directory. Accepts a local path (used to
 // prove the engine before the public repo exists and in tests), a github:
-// shorthand, or any git URL.
-const resolveSource = (src: string): Source => {
+// shorthand, or any git URL. Remote sources default to `main`; `ref` pins a
+// tag, branch, or full commit sha instead (`git fetch` accepts all three).
+const resolveSource = (src: string, ref: string | undefined): Source => {
   if (existsSync(src)) {
+    if (ref !== undefined) {
+      throw new Error(
+        `--ref requires a git URL source; a local path is used as-is: ${src}`,
+      );
+    }
     let sha = 'local';
     try {
       sha = execFileSync('git', ['-C', src, 'rev-parse', 'HEAD'], {
@@ -180,18 +198,34 @@ const resolveSource = (src: string): Source => {
   const url = src.startsWith(GITHUB_PREFIX)
     ? `https://github.com/${src.slice(GITHUB_PREFIX.length)}.git`
     : src;
+  const target = ref ?? 'main';
   const dir = mkdtempSync(join(tmpdir(), 'standards-'));
-  execFileSync('git', ['clone', '--depth', '1', '--branch', 'main', url, dir], {
-    stdio: 'ignore',
-  });
+  const cleanup = (): void => rmSync(dir, { recursive: true, force: true });
+  try {
+    // init + fetch instead of `clone --branch` so a full commit sha works as a
+    // ref, not only tags and branches (GitHub serves reachable sha fetches).
+    execFileSync('git', ['init', '--quiet', dir], { stdio: 'ignore' });
+    execFileSync(
+      'git',
+      ['-C', dir, 'fetch', '--quiet', '--depth', '1', '--', url, target],
+      { stdio: 'ignore' },
+    );
+    execFileSync(
+      'git',
+      ['-C', dir, 'checkout', '--quiet', '--detach', 'FETCH_HEAD'],
+      { stdio: 'ignore' },
+    );
+  } catch (error) {
+    cleanup();
+    throw new Error(
+      `Cannot fetch "${target}" from ${url}; expected a tag, branch, or full commit sha reachable on the remote`,
+      { cause: error },
+    );
+  }
   const sha = execFileSync('git', ['-C', dir, 'rev-parse', 'HEAD'], {
     encoding: 'utf8',
   }).trim();
-  return {
-    dir,
-    sha,
-    cleanup: () => rmSync(dir, { recursive: true, force: true }),
-  };
+  return { dir, sha, cleanup };
 };
 
 // Recursively collect files under `abs`, keyed by their POSIX path relative to
@@ -474,15 +508,6 @@ const runCheck = async (consumer: string): Promise<boolean> => {
 const readTextIfPresent = async (path: string): Promise<string | null> =>
   existsSync(path) ? readFile(path, 'utf8') : null;
 
-const hasStandardsImport = (justfile: string): boolean =>
-  justfile.split('\n').some((line) => {
-    const trimmed = line.trim();
-    return (
-      trimmed === "import 'standards.just'" ||
-      trimmed === 'import "standards.just"'
-    );
-  });
-
 const DEPENDABOT_BASELINE_ECOSYSTEMS = ['bun', 'github-actions'] as const;
 const DEPENDABOT_SCHEDULE_INTERVALS = new Set([
   'daily',
@@ -658,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',
@@ -670,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`);
     }
   }
@@ -679,11 +715,6 @@ const inspectPackageJson = (packageRaw: string): ReadonlyArray<string> => {
 
 const runDoctor = async (consumer: string): Promise<boolean> => {
   const problems: Array<string> = [];
-  const justfile = await readTextIfPresent(join(consumer, 'justfile'));
-  if (justfile === null || !hasStandardsImport(justfile)) {
-    problems.push("justfile must import 'standards.just'");
-  }
-
   const biome = await readTextIfPresent(join(consumer, 'biome.jsonc'));
   if (biome === null || !biome.includes('"./biome.base.jsonc"')) {
     problems.push('biome.jsonc must extend "./biome.base.jsonc"');
@@ -738,16 +769,18 @@ 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)
   --from <src>   Upstream override for init/sync (GitHub repo or local path)
+  --ref <ref>    Upstream tag, branch, or full commit sha for init/sync (remote Git/GitHub sources only; default: main)
   --dry-run      Preview a sync without writing anything
   --check        With github: compare live settings to the declaration (default)
   --apply        With github: converge the live repository (needs admin auth)`;
@@ -759,6 +792,7 @@ const commandFromArg = (arg: string): Command => {
     arg === 'github' ||
     arg === 'help' ||
     arg === 'init' ||
+    arg === 'structure' ||
     arg === 'sync'
   ) {
     return arg;
@@ -791,6 +825,7 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
   let consumer = process.cwd();
   let dryRun = false;
   let from: string | undefined;
+  let ref: string | undefined;
   let checkFlag = false;
   let apply = false;
 
@@ -814,6 +849,10 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
         from = nextOptionValue(argv, index);
         index += 1;
         break;
+      case '--ref':
+        ref = nextOptionValue(argv, index);
+        index += 1;
+        break;
       case '--help':
       case '-h':
         command = setCommand(command, 'help');
@@ -832,31 +871,54 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
   if (apply && checkFlag) {
     throw new Error('github accepts exactly one of --check or --apply');
   }
+  if (ref !== undefined && command !== 'init' && command !== 'sync') {
+    throw new Error('--ref is only valid with the init and sync commands');
+  }
 
   return {
     command,
     consumer: resolve(consumer),
     dryRun,
     from,
+    ref,
     apply,
   };
 };
 
+// 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
+  );
 };
 
 const runInitCommand = async (
   consumer: string,
   from: string | undefined,
+  ref: string | undefined,
 ): Promise<void> => {
   // Refuse before cloning upstream: re-initializing skips the lock, so it
   // would silently overwrite local canonical edits and orphan files that
@@ -868,7 +930,7 @@ const runInitCommand = async (
     process.exitCode = 1;
     return;
   }
-  const source = resolveSource(from ?? DEFAULT_UPSTREAM);
+  const source = resolveSource(from ?? DEFAULT_UPSTREAM, ref);
   try {
     const manifest = await loadManifest(
       join(source.dir, 'sync-standards.json'),
@@ -882,12 +944,13 @@ const runInitCommand = async (
 const runSyncCommand = async (
   consumer: string,
   from: string | undefined,
+  ref: string | undefined,
   dryRun: boolean,
 ): Promise<void> => {
   const consumerManifest = await loadManifest(
     join(consumer, 'sync-standards.json'),
   );
-  const source = resolveSource(from ?? consumerManifest.upstream);
+  const source = resolveSource(from ?? consumerManifest.upstream, ref);
   try {
     const manifest = await loadManifest(
       join(source.dir, 'sync-standards.json'),
@@ -898,8 +961,26 @@ 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, apply } = parseArgs(
+  const { command, consumer, dryRun, from, ref, apply } = parseArgs(
     process.argv.slice(2),
   );
 
@@ -915,37 +996,18 @@ 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;
-    }
+  if (command === 'init') {
+    await runInitCommand(consumer, from, ref);
     return;
   }
 
-  if (command === 'init') {
-    await runInitCommand(consumer, from);
+  if (command === 'sync') {
+    await runSyncCommand(consumer, from, ref, dryRun);
     return;
   }
 
-  if (command === 'sync') {
-    await runSyncCommand(consumer, from, dryRun);
+  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 };
+};