@zgeoff/chex 0.0.9 → 0.0.11

package/README.md

@@ -57,6 +57,7 @@ The repo checks read the branch, the pushed commits and the repo's config:
 | `commits`          | a pushed commit whose message fails `@zgeoff/commitlint-config`                                                                | `--pushed-refs` |
 | `local-paths`      | a line a pushed commit adds that holds the home folder or the host name                                                        | `--pushed-refs` |
 | `test-timeouts`    | a `bun test` timeout above its lane's limit, in a script or a `bunfig.toml`                                                    | none            |
+| `test-layout`      | a test folder, file name or import outside [the test layout](../../docs/guides/test-layout.md)                                 | none            |
 | `workflows`        | nothing: it warns on each fault of the shared workflow lint, and passes                                                        | the paths       |
 | `dependency-gates` | a stale age-gate exclude, an override or an audit ignore that nothing needs, or a first-party package with no age-gate exclude | none            |
 | `uncommitted`      | a file the branch changes that holds a change the push does not send                                                           | none            |

package/lefthook.yml

@@ -13,6 +13,16 @@
 # repo's own install of chex, diet and rig, and fails when one is missing
 # rather than download a package of that name.
 
+# A pre-commit or a pre-push in a linked worktree exports GIT_DIR, which git
+# reads before a -C path, so a job command that runs git in a folder of its
+# own, such as a temp clone, would write to this repository instead. Each job
+# starts with clear-git-env, which unsets every variable git lists as local to
+# a repository; git then finds the repository from the job's folder. lefthook
+# expands a template in run only, so each files command that runs a program
+# unsets the same variables itself.
+templates:
+  clear-git-env: unset $(git rev-parse --local-env-vars);
+
 pre-commit:
   # Sequential, so typecheck reads the files the fixers before it rewrote.
   piped: true
@@ -20,7 +30,7 @@ pre-commit:
     # lefthook skips the job when no staged file matches the glob.
     - name: typecheck
       glob: '*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,json,jsonc}'
-      run: bun x --no-install diet -- bun run typecheck
+      run: '{clear-git-env} bun x --no-install diet -- bun run typecheck'
 
 pre-push:
   # Sequential, to bound memory on a small host or with parallel agents.
@@ -30,24 +40,30 @@ pre-push:
     # push when a file the branch changes or deletes holds a change that is
     # not committed, and names each such file.
     - name: uncommitted
-      run: bun x --no-install diet -- bun x --no-install chex uncommitted
+      run: '{clear-git-env} bun x --no-install diet -- bun x --no-install chex uncommitted'
     - name: format:check
-      run: bun x --no-install diet -- bun run format:check
+      run: '{clear-git-env} bun x --no-install diet -- bun run format:check'
     # Plain oxlint, without the unused-directive check: a directive for a
     # type-aware rule reads as unused in plain mode.
     - name: lint
-      files: bun node_modules/@zgeoff/chex/src/read-branch-files.ts
+      files:
+        unset $(git rev-parse --local-env-vars); bun
+        node_modules/@zgeoff/chex/src/read-branch-files.ts
       glob: '*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}'
       run:
-        bun x --no-install diet -- bun x --no-install oxlint --no-error-on-unmatched-pattern {files}
+        '{clear-git-env} bun x --no-install diet -- bun x --no-install oxlint
+        --no-error-on-unmatched-pattern {files}'
     # Each file check reads only the files the branch changes that match its
     # glob, so a file the branch leaves unchanged never fails a push. A check
     # whose program the machine lacks prints a notice and passes: CI installs
     # the program and runs the check on every pull request.
     - name: shell
-      files: bun node_modules/@zgeoff/chex/src/read-branch-files.ts
+      files:
+        unset $(git rev-parse --local-env-vars); bun
+        node_modules/@zgeoff/chex/src/read-branch-files.ts
       glob: '*.sh'
       run: |
+        {clear-git-env}
         for program in shellcheck shfmt; do
           if ! command -v "$program" > /dev/null; then
             echo "shell: skipped, because $program is not on the PATH; CI runs the check"
@@ -62,9 +78,11 @@ pre-push:
     # decides whether the job runs. The repo's check:docs script names the
     # checks it takes, such as chex prose length links.
     - name: docs
-      files: bun node_modules/@zgeoff/chex/src/read-branch-files.ts
+      files:
+        unset $(git rev-parse --local-env-vars); bun
+        node_modules/@zgeoff/chex/src/read-branch-files.ts
       glob: '*.md'
-      run: bun x --no-install diet -- bun run --silent check:docs
+      run: '{clear-git-env} bun x --no-install diet -- bun run --silent check:docs'
     # GitHub runs no workflow from a subfolder of .github/workflows, and
     # sync/workflow-callers holds the workflows that tools delivers. actionlint
     # 1.7.12 rejects the concurrency queue key that GitHub documents, until
@@ -72,11 +90,14 @@ pre-push:
     # The workflow lint runs after actionlint, even when actionlint is missing
     # or fails.
     - name: workflows
-      files: bun node_modules/@zgeoff/chex/src/read-branch-files.ts
+      files:
+        unset $(git rev-parse --local-env-vars); bun
+        node_modules/@zgeoff/chex/src/read-branch-files.ts
       glob:
         - '.github/workflows/*.{yml,yaml}'
         - 'sync/workflow-callers/*.{yml,yaml}'
       run: |
+        {clear-git-env}
         status=0
         if ! command -v actionlint > /dev/null; then
           echo "workflows: actionlint skipped, because it is not on the PATH; CI runs it"
@@ -98,26 +119,27 @@ pre-push:
     - name: commits
       files: echo package.json
       use_stdin: true
-      run: 'bun x --no-install diet -- bun x --no-install chex commits --pushed-refs # {files}'
+      run:
+        '{clear-git-env} bun x --no-install diet -- bun x --no-install chex commits --pushed-refs #
+        {files}'
     # package.json keeps this job from the same lefthook skip.
     - name: local-paths
       files: echo package.json
       use_stdin: true
-      run: 'bun x --no-install diet -- bun x --no-install chex local-paths --pushed-refs # {files}'
+      run:
+        '{clear-git-env} bun x --no-install diet -- bun x --no-install chex local-paths
+        --pushed-refs # {files}'
     - name: test-timeouts
-      run: bun x --no-install diet -- bun x --no-install chex test-timeouts
+      run: '{clear-git-env} bun x --no-install diet -- bun x --no-install chex test-timeouts'
     - name: dependency-gates
-      run: bun x --no-install diet -- bun x --no-install chex dependency-gates
+      run: '{clear-git-env} bun x --no-install diet -- bun x --no-install chex dependency-gates'
     - name: typecheck
-      run: bun x --no-install diet -- bun run typecheck
-    # A pre-push in a linked worktree exports GIT_DIR, and a test that runs git
-    # in a temp folder would inherit it and write to the real repository: a
-    # git init there sets core.bare=true. The tests run without git's
-    # repository variables. A bunfig.toml reaches the job too, because a change
-    # to it skips the related tests.
+      run: '{clear-git-env} bun x --no-install diet -- bun run typecheck'
+    # A bunfig.toml reaches the job too, because a change to it skips the
+    # related tests.
     - name: test
-      files: bun node_modules/@zgeoff/chex/src/read-branch-files.ts
+      files:
+        unset $(git rev-parse --local-env-vars); bun
+        node_modules/@zgeoff/chex/src/read-branch-files.ts
       glob: '*.{ts,tsx,toml}'
-      run:
-        env -u GIT_DIR -u GIT_WORK_TREE -u GIT_INDEX_FILE -u GIT_COMMON_DIR bun x --no-install diet
-        -- bun x --no-install rig related {files}
+      run: '{clear-git-env} bun x --no-install diet -- bun x --no-install rig related {files}'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/chex",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Run each shared docs and repo check as one subcommand, with the lefthook pre-push baseline that calls them",
   "keywords": [
     "checks",
@@ -20,9 +20,14 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
-    "lefthook.yml"
+    "lefthook.yml",
+    "!src/test-utils"
   ],
   "type": "module",
+  "exports": {
+    "./test-utils/*": "./src/test-utils/*.ts",
+    "./*": "./*"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -31,10 +36,14 @@
   },
   "dependencies": {
     "@zgeoff/std": "0.3.2",
+    "oxc-parser": "0.156.0",
     "ts-pattern": "5.9.2"
   },
   "devDependencies": {
     "@types/bun": "1.4.4",
+    "@zgeoff/rig": "0.0.6",
+    "@zgeoff/std": "0.3.2",
+    "@zgeoff/testing": "0.1.0",
     "tiny-invariant": "1.3.3",
     "tsrs": "0.18.0-ts7.1.0-dev.20260929",
     "typescript": "7.0.2"

package/src/check-names.ts

@@ -6,6 +6,7 @@ export const checkNames = [
   'commits',
   'local-paths',
   'test-timeouts',
+  'test-layout',
   'workflows',
   'dependency-gates',
   'uncommitted',

package/src/cli.ts

@@ -8,6 +8,7 @@ import { runChex } from './run-chex.ts';
 import { runCommitsCommand } from './run-commits-check.ts';
 import { runInit } from './run-init.ts';
 import { runLocalPathsCommand } from './run-local-paths-check.ts';
+import { runTestLayoutCommand } from './run-test-layout-check.ts';
 import { runTestTimeoutsCommand } from './run-test-timeouts-check.ts';
 import { runUncommittedCommand } from './run-uncommitted-check.ts';
 import { runWorkflowsCommand } from './run-workflows-check.ts';
@@ -21,6 +22,7 @@ process.exitCode = await runChex(process.argv.slice(2), {
       commits: runCommitsCommand,
       'local-paths': runLocalPathsCommand,
       'test-timeouts': runTestTimeoutsCommand,
+      'test-layout': runTestLayoutCommand,
       workflows: runWorkflowsCommand,
       'dependency-gates': runDependencyGatesCommand,
       uncommitted: runUncommittedCommand,

package/src/run-test-layout-check.ts

@@ -0,0 +1,119 @@
+import { join } from 'node:path';
+import { runProgram } from './run-program.ts';
+import { collectLaneSuffixes } from './test-layout/collect-lane-suffixes.ts';
+import { collectTestLayoutFaults } from './test-layout/collect-test-layout-faults.ts';
+import { collectWorkspaceRoots } from './test-layout/collect-workspace-roots.ts';
+import type { OxcParserModule } from './test-layout/oxc-parser-module.ts';
+import { parseWorkspacePatterns } from './test-layout/parse-workspace-patterns.ts';
+import { readOxcParser } from './test-layout/read-oxc-parser.ts';
+
+export interface TestLayoutCheckOptions {
+  readonly readTrackedPaths: () => Promise<readonly string[]>;
+
+  // Reads a tracked file by its path relative to the repo root.
+  readonly readText: (path: string) => Promise<string>;
+
+  // The default export of the rig.config.ts at the repo root.
+  readonly readRigConfig: () => Promise<unknown>;
+
+  readonly readParser: () => Promise<OxcParserModule>;
+
+  readonly writeOutput: (text: string) => void;
+
+  readonly writeError: (text: string) => void;
+}
+
+const sourcePattern = /\.(?:[cm]?[jt]s|[jt]sx)$/u;
+
+// Returns the exit code: 0 for a tree with no layout fault, 1 with a fault, and 2 when the check
+// cannot run.
+export async function runTestLayoutCheck(options: TestLayoutCheckOptions): Promise<number> {
+  let faults: string[];
+
+  try {
+    const trackedPaths = await options.readTrackedPaths();
+
+    const tracked = new Set(trackedPaths);
+
+    const manifestText = tracked.has('package.json')
+      ? await options.readText('package.json')
+      : '{}';
+
+    const manifest: unknown = JSON.parse(manifestText);
+    const workspaces = parseWorkspacePatterns(manifest);
+
+    const oxlintConfigText = tracked.has('.oxlintrc.json')
+      ? await options.readText('.oxlintrc.json')
+      : null;
+
+    const rigConfig = tracked.has('rig.config.ts') ? await options.readRigConfig() : null;
+
+    const sources = await Promise.all(
+      trackedPaths
+        .filter((path) => sourcePattern.test(path))
+        .map(async (path) => ({ path, text: await options.readText(path) })),
+    );
+
+    const parser = await options.readParser();
+
+    faults = collectTestLayoutFaults(
+      parser,
+      {
+        trackedPaths,
+        workspaces:
+          workspaces.kind === 'single'
+            ? []
+            : collectWorkspaceRoots(trackedPaths, workspaces.patterns),
+        isWorkspaceRepo: workspaces.kind === 'workspaces',
+        laneSuffixes: collectLaneSuffixes(oxlintConfigText, rigConfig),
+      },
+      sources,
+    );
+  } catch (error) {
+    options.writeError(`test-layout: ${error instanceof Error ? error.message : String(error)}\n`);
+
+    return 2;
+  }
+
+  for (const fault of faults) {
+    options.writeOutput(`${fault}\n`);
+  }
+
+  return faults.length === 0 ? 0 : 1;
+}
+
+export function runTestLayoutCommand(): Promise<number> {
+  const cwd = process.cwd();
+
+  return runTestLayoutCheck({
+    readTrackedPaths: () => {
+      const listing = runProgram(['git', 'ls-files', '-z'], { cwd, env: process.env });
+
+      if (listing.exitCode !== 0) {
+        return Promise.reject(new Error(`git ls-files failed: ${listing.stderr.trim()}`));
+      }
+
+      return Promise.resolve(listing.stdout.split('\0').filter((path) => path !== ''));
+    },
+    readText: (path) => Bun.file(join(cwd, path)).text(),
+    readRigConfig: async () => {
+      const loaded: unknown = await import(join(cwd, 'rig.config.ts'));
+
+      const defaultExport: unknown =
+        typeof loaded === 'object' && loaded !== null ? Reflect.get(loaded, 'default') : null;
+
+      return defaultExport;
+    },
+    readParser: readOxcParser,
+    writeOutput: (text) => {
+      process.stdout.write(text);
+    },
+    writeError: (text) => {
+      process.stderr.write(text);
+    },
+  });
+}
+
+if (import.meta.main) {
+  process.exitCode = await runTestLayoutCommand();
+}

package/src/test-layout/collect-folder-faults.ts

@@ -0,0 +1,141 @@
+import { posix } from 'node:path';
+import type { TestLayout } from './types.ts';
+
+// The faults of where folders sit: test folders, root folders of a workspace repo, helpers outside
+// src/, integration folders, and the subfolders of e2e/, bench/ and evals/.
+export function collectFolderFaults(layout: TestLayout): string[] {
+  return [
+    ...collectRootFolderFaults(layout),
+    ...collectIntegrationFaults(layout.trackedPaths),
+    ...collectTestFolderFaults(layout.trackedPaths),
+    ...collectHelperFolderFaults(layout),
+    ...collectSubfolderFaults(layout),
+  ];
+}
+
+const rootFolders = ['e2e', 'evals', 'bench'] as const;
+
+function collectRootFolderFaults(layout: TestLayout): string[] {
+  const example = pickExampleWorkspace(layout.workspaces);
+
+  const faults = rootFolders
+    .filter((folder) => layout.isWorkspaceRepo && hasFolder(layout.trackedPaths, folder))
+    .map(
+      (folder) =>
+        `${folder}/ sits at the repo root; move each file into the workspace it tests, such as ${example}/${folder}/`,
+    );
+
+  if (hasFolder(layout.trackedPaths, 'test-utils')) {
+    const target = layout.isWorkspaceRepo
+      ? `the workspace it tests, such as ${example}/src/test-utils/`
+      : 'src/test-utils/';
+
+    faults.push(`test-utils/ sits at the repo root; move each file into ${target}`);
+  }
+
+  return faults;
+}
+
+function pickExampleWorkspace(workspaces: readonly string[]): string {
+  const [first] = workspaces;
+  const parent = first === undefined ? '.' : posix.dirname(first);
+
+  return parent === '.' ? 'packages/<name>' : `${parent}/<name>`;
+}
+
+function hasFolder(trackedPaths: readonly string[], folder: string): boolean {
+  return trackedPaths.some((path) => path.startsWith(`${folder}/`));
+}
+
+function collectIntegrationFaults(trackedPaths: readonly string[]): string[] {
+  return collectFolderPaths(trackedPaths)
+    .filter((folder) => posix.basename(folder) === 'integration')
+    .map(
+      (folder) =>
+        `${folder}/ holds tests; move each one beside the module it tests, in the package that wires together the packages it imports`,
+    );
+}
+
+// Every folder that holds a tracked path, each once, in order.
+function collectFolderPaths(trackedPaths: readonly string[]): string[] {
+  const folders = new Set<string>();
+
+  for (const path of trackedPaths) {
+    const segments = path.split('/').slice(0, -1);
+
+    for (let length = 1; length <= segments.length; length += 1) {
+      folders.add(segments.slice(0, length).join('/'));
+    }
+  }
+
+  return [...folders].toSorted();
+}
+
+const testFolderNames = new Set(['test', 'tests', '__tests__']);
+
+function collectTestFolderFaults(trackedPaths: readonly string[]): string[] {
+  return collectFolderPaths(trackedPaths)
+    .filter((folder) => testFolderNames.has(posix.basename(folder)))
+    .map(
+      (folder) =>
+        `${folder}/ is a test folder; move its tests beside the modules they test, its end-to-end tests into the package's e2e/, and its helpers into src/test-utils/`,
+    );
+}
+
+function collectHelperFolderFaults(layout: TestLayout): string[] {
+  return layout.workspaces
+    .filter((root) => layout.trackedPaths.some((path) => path.startsWith(`${root}/test-utils/`)))
+    .map(
+      (root) =>
+        `${root}/test-utils/ holds test helpers outside src/; move each file into ${root}/src/test-utils/`,
+    );
+}
+
+// An e2e/, bench/ or evals/ folder counts in a folder that holds a package.json, and at the root of
+// a single-package repo.
+function collectSubfolderFaults(layout: TestLayout): string[] {
+  const tracked = new Set(layout.trackedPaths);
+
+  const isPackageFolder = (parent: string): boolean =>
+    parent === '' ? !layout.isWorkspaceRepo : tracked.has(posix.join(parent, 'package.json'));
+
+  const faults = new Set<string>();
+
+  for (const path of layout.trackedPaths) {
+    const segments = path.split('/');
+
+    for (const [index, name] of segments.entries()) {
+      const parent = segments.slice(0, index).join('/');
+      const rest = segments.slice(index + 1);
+      const folder = posix.join(parent, name);
+
+      if (!isPackageFolder(parent)) {
+        continue;
+      }
+
+      const [first, second] = rest;
+
+      if (name === 'e2e' && second !== undefined && first !== 'fixtures') {
+        faults.add(
+          `${folder}/${first}/ is a subfolder of ${folder}/; keep the tests flat in ${folder}/, with fixtures in ${folder}/fixtures/ and helpers in src/test-utils/`,
+        );
+      }
+
+      if (name === 'bench' && second !== undefined) {
+        faults.add(
+          `${folder}/${first}/ is a subfolder of ${folder}/; keep the bench files flat in ${folder}/, with helpers in src/test-utils/`,
+        );
+      }
+
+      const [suite, subfolder, inner] = rest;
+
+      if (name === 'evals' && suite !== undefined && inner !== undefined) {
+        faults.add(
+          `${folder}/${suite}/${subfolder}/ is a subfolder of ${folder}/${suite}/; keep that suite's files flat in ${folder}/${suite}/, with helpers in src/test-utils/`,
+        );
+      }
+    }
+  }
+
+  return [...faults].toSorted();
+}

package/src/test-layout/collect-import-faults.ts

@@ -0,0 +1,122 @@
+import { dirname, join, normalize } from 'node:path';
+import { collectImportSpecifiers } from './collect-import-specifiers.ts';
+import type { OxcParserModule } from './oxc-parser-module.ts';
+import type { SourceFile, TestLayout } from './types.ts';
+
+const sourcePattern = /\.(?:[cm]?[jt]s|[jt]sx)$/u;
+
+// The faults of imports: a relative import of another workspace's helper, and production code that
+// imports a helper.
+export function collectImportFaults(
+  oxc: OxcParserModule,
+  layout: TestLayout,
+  sources: readonly SourceFile[],
+): string[] {
+  return sources
+    .filter((source) => sourcePattern.test(source.path))
+    .flatMap((source) => {
+      const parsed = oxc.parseSync(source.path, source.text);
+      const [parseError] = parsed.errors;
+
+      if (parseError !== undefined) {
+        return [
+          `${source.path} does not parse, so the layout check cannot read its imports: ${parseError.message}`,
+        ];
+      }
+
+      return collectImportSpecifiers(oxc, parsed.program).flatMap((specifier) =>
+        collectSpecifierFaults(layout, source.path, specifier),
+      );
+    });
+}
+
+const packageHelperPattern = /^@[^/]+\/[^/]+\/test-utils(?:\/|$)/u;
+
+function collectSpecifierFaults(layout: TestLayout, importer: string, specifier: string): string[] {
+  const isRelative = specifier.startsWith('./') || specifier.startsWith('../');
+  const target = isRelative ? normalize(join(dirname(importer), specifier)) : specifier;
+  const isHelper = isRelative ? isHelperPath(layout, target) : packageHelperPattern.test(specifier);
+
+  if (isHelper && isProductionCode(layout, importer)) {
+    return [
+      `${importer} imports ${target}, a test helper, from production code; import test helpers only from tests and other test helpers`,
+    ];
+  }
+
+  if (!isRelative || !isHelper) {
+    return [];
+  }
+
+  const targetRoot = getWorkspaceRoot(layout, target);
+
+  if (targetRoot === getWorkspaceRoot(layout, importer)) {
+    return [];
+  }
+
+  const fix = layout.workspaces.includes(targetRoot)
+    ? "import it by the package's name, with the package as a workspace:* dev dependency"
+    : "copy the helper into the importer's own test-utils/";
+
+  return [`${importer} imports ${target}, a test helper of ${targetRoot}; ${fix}`];
+}
+
+function isHelperPath(layout: TestLayout, path: string): boolean {
+  const folder = getHelperFolder(layout, getWorkspaceRoot(layout, path));
+
+  return path === folder || path.startsWith(`${folder}/`);
+}
+
+function getHelperFolder(layout: TestLayout, root: string): string {
+  if (layout.workspaces.includes(root)) {
+    return `${root}/src/test-utils`;
+  }
+
+  if (root === '') {
+    return layout.isWorkspaceRepo ? 'test-utils' : 'src/test-utils';
+  }
+
+  return `${root}/test-utils`;
+}
+
+// A path belongs to its workspace, to the single package of a repo with no workspaces, or else to
+// the top-level folder it sits in, such as scripts/.
+function getWorkspaceRoot(layout: TestLayout, path: string): string {
+  const workspace = layout.workspaces.find((root) => path.startsWith(`${root}/`));
+
+  if (workspace !== undefined) {
+    return workspace;
+  }
+
+  const segments = path.split('/');
+
+  if (!layout.isWorkspaceRepo || segments.length === 1) {
+    return '';
+  }
+
+  return segments[0] ?? '';
+}
+
+const packageTestFolders = new Set(['e2e', 'evals', 'bench', 'test-utils']);
+
+function isProductionCode(layout: TestLayout, path: string): boolean {
+  const root = getWorkspaceRoot(layout, path);
+
+  if ((root === '' && layout.isWorkspaceRepo) || isHelperPath(layout, path)) {
+    return false;
+  }
+
+  if (/\.(?:test|bench)\.[^/]+$/u.test(path)) {
+    return false;
+  }
+
+  const isPackage = layout.workspaces.includes(root) || (root === '' && !layout.isWorkspaceRepo);
+
+  if (!isPackage) {
+    return true;
+  }
+
+  const relativePath = root === '' ? path : path.slice(root.length + 1);
+  const [folder] = relativePath.split('/');
+
+  return !packageTestFolders.has(folder ?? '');
+}

package/src/test-layout/collect-import-specifiers.ts

@@ -0,0 +1,55 @@
+import type { Expression, Program, StringLiteral } from 'oxc-parser';
+import type { OxcParserModule } from './oxc-parser-module.ts';
+
+export function collectImportSpecifiers(oxc: OxcParserModule, program: Program): string[] {
+  const specifiers: string[] = [];
+
+  const addLiteral = (node: Expression | StringLiteral | null | undefined): void => {
+    if (node?.type === 'Literal' && typeof node.value === 'string') {
+      specifiers.push(node.value);
+    }
+
+    const [onlyPart] =
+      node?.type === 'TemplateLiteral' && node.expressions.length === 0 ? node.quasis : [];
+
+    if (typeof onlyPart?.value.cooked === 'string') {
+      specifiers.push(onlyPart.value.cooked);
+    }
+  };
+
+  const visitor = new oxc.Visitor({
+    ImportDeclaration: (node) => {
+      addLiteral(node.source);
+    },
+    ExportNamedDeclaration: (node) => {
+      addLiteral(node.source);
+    },
+    ExportAllDeclaration: (node) => {
+      addLiteral(node.source);
+    },
+    ImportExpression: (node) => {
+      addLiteral(node.source);
+    },
+    TSImportType: (node) => {
+      addLiteral(node.source);
+    },
+    TSExternalModuleReference: (node) => {
+      addLiteral(node.expression);
+    },
+    CallExpression: (node) => {
+      const [first] = node.arguments;
+
+      if (
+        node.callee.type === 'Identifier' &&
+        node.callee.name === 'require' &&
+        first?.type !== 'SpreadElement'
+      ) {
+        addLiteral(first);
+      }
+    },
+  });
+
+  visitor.visit(program);
+
+  return specifiers;
+}

package/src/test-layout/collect-lane-suffixes.ts

@@ -0,0 +1,54 @@
+import { parseLaneLimits } from '../parse-lane-limits.ts';
+
+// The suffixes that a test file name may carry before `.test.ts`. A lane of the resolved
+// rig.config.ts has exactly the suffix it gives, and a lane only the oxlint config names has
+// `.<lane>`. The e2e lane selects by folder, so it has none.
+export function collectLaneSuffixes(
+  oxlintConfigText: string | null,
+  rigConfig: unknown,
+): readonly string[] {
+  const resolved = collectResolvedSuffixes(rigConfig);
+  const names = [...parseLaneLimits(oxlintConfigText).keys()].filter((name) => name !== 'e2e');
+
+  const fromNames = names.flatMap((name): string[] => {
+    const suffix = resolved.has(name) ? resolved.get(name) : `.${name}`;
+
+    return typeof suffix === 'string' ? [suffix] : [];
+  });
+
+  const fromConfig = [...resolved.values()].filter((suffix): suffix is string => suffix !== null);
+
+  return [...new Set([...fromNames, ...fromConfig])].toSorted();
+}
+
+// The suffix of each lane of the resolved rig.config.ts, by lane name; null for a lane without one.
+function collectResolvedSuffixes(rigConfig: unknown): Map<string, string | null> {
+  const lanes: unknown =
+    typeof rigConfig === 'object' && rigConfig !== null
+      ? Reflect.get(rigConfig, 'lanes')
+      : undefined;
+
+  const suffixes = new Map<string, string | null>();
+
+  if (!Array.isArray(lanes)) {
+    return suffixes;
+  }
+
+  for (const entry of lanes) {
+    const lane: unknown = entry;
+
+    if (typeof lane !== 'object' || lane === null) {
+      continue;
+    }
+
+    const name: unknown = Reflect.get(lane, 'name');
+    const suffix: unknown = Reflect.get(lane, 'suffix');
+    const laneSuffix = typeof suffix === 'string' ? suffix : null;
+
+    if (typeof name === 'string') {
+      suffixes.set(name, laneSuffix);
+    }
+  }
+
+  return suffixes;
+}

package/src/test-layout/collect-name-faults.ts

@@ -0,0 +1,96 @@
+import { posix } from 'node:path';
+import type { TestLayout } from './types.ts';
+
+const testSuffix = '.test.ts';
+
+// The faults of how test files are named: an e2e file's prefix, a module test with no module, and
+// a lane suffix that no lane declares.
+export function collectNameFaults(layout: TestLayout): string[] {
+  const namesByFolder = Map.groupBy(layout.trackedPaths, (path) => posix.dirname(path));
+  const faults: string[] = [];
+
+  for (const path of layout.trackedPaths) {
+    if (path.endsWith(testSuffix)) {
+      const siblings = namesByFolder.get(posix.dirname(path)) ?? [];
+
+      faults.push(
+        ...collectE2ENameFaults(path, layout),
+        ...collectModuleTestFaults(path, layout, siblings),
+      );
+    }
+  }
+
+  return faults;
+}
+
+const e2ePrefixes = [
+  'start-',
+  'stop-',
+  'recover-',
+  'cli-',
+  'build-',
+  'runtime-',
+  'enforce-',
+  'compat-',
+  'journey-',
+] as const;
+
+function collectE2ENameFaults(path: string, layout: TestLayout): string[] {
+  const folder = posix.dirname(path);
+  const parent = posix.dirname(folder);
+
+  const isE2EFolder =
+    posix.basename(folder) === 'e2e' &&
+    (parent === '.'
+      ? !layout.isWorkspaceRepo
+      : layout.trackedPaths.includes(posix.join(parent, 'package.json')));
+
+  const name = posix.basename(path);
+
+  if (!isE2EFolder || e2ePrefixes.some((prefix) => name.startsWith(prefix))) {
+    return [];
+  }
+
+  return [
+    `${path} doesn't start with an e2e prefix; rename it to start with ${e2ePrefixes.slice(0, -1).join(', ')} or ${e2ePrefixes.at(-1)}`,
+  ];
+}
+
+// A test in a src/ folder sits beside the module it tests: `<base>.test.ts` beside `<base>.<ext>`,
+// and `<base>.<word>.test.ts` beside `<base>.<ext>` when the word is a lane suffix, or beside
+// `<base>.<word>.<ext>` when it is part of a module's name.
+function collectModuleTestFaults(
+  path: string,
+  layout: TestLayout,
+  siblings: readonly string[],
+): string[] {
+  const stem = posix.basename(path).slice(0, -testSuffix.length);
+  const dotIndex = stem.lastIndexOf('.');
+  const base = dotIndex === -1 ? stem : stem.slice(0, dotIndex);
+  const word = dotIndex === -1 ? null : stem.slice(dotIndex + 1);
+  const names = siblings.map((sibling) => posix.basename(sibling));
+
+  const hasModule = (prefix: string): boolean =>
+    names.some(
+      (name) => name.startsWith(`${prefix}.`) && !name.slice(prefix.length + 1).includes('.'),
+    );
+
+  const isInSrc = posix.dirname(path).split('/').includes('src');
+  const isLaneTest = word !== null && layout.laneSuffixes.includes(`.${word}`);
+
+  if (word !== null && !isLaneTest) {
+    return hasModule(`${base}.${word}`)
+      ? []
+      : [
+          `${path} uses the suffix .${word}, which no lane in rig.config.ts declares, and ${base}.${word}.<ext> isn't beside it; declare the lane in rig.config.ts lanes, or rename the test after the module it tests`,
+        ];
+  }
+
+  if (isInSrc && !hasModule(base)) {
+    return [
+      `${path} has no ${base}.<ext> beside it; move the test next to the module it tests, or rename it after that module`,
+    ];
+  }
+
+  return [];
+}

package/src/test-layout/collect-test-layout-faults.ts

@@ -0,0 +1,17 @@
+import { collectFolderFaults } from './collect-folder-faults.ts';
+import { collectImportFaults } from './collect-import-faults.ts';
+import { collectNameFaults } from './collect-name-faults.ts';
+import type { OxcParserModule } from './oxc-parser-module.ts';
+import type { SourceFile, TestLayout } from './types.ts';
+
+export function collectTestLayoutFaults(
+  oxc: OxcParserModule,
+  layout: TestLayout,
+  sources: readonly SourceFile[],
+): string[] {
+  return [
+    ...collectFolderFaults(layout),
+    ...collectNameFaults(layout),
+    ...collectImportFaults(oxc, layout, sources),
+  ];
+}

package/src/test-layout/collect-workspace-roots.ts

@@ -0,0 +1,24 @@
+import { posix } from 'node:path';
+
+// Resolves the patterns of the root package.json `workspaces` field against the folders that hold
+// a tracked package.json. A pattern that starts with `!` leaves its folders out.
+export function collectWorkspaceRoots(
+  trackedPaths: readonly string[],
+  patterns: readonly string[],
+): string[] {
+  const included = patterns.filter((pattern) => !pattern.startsWith('!'));
+
+  const excluded = patterns
+    .filter((pattern) => pattern.startsWith('!'))
+    .map((pattern) => pattern.slice(1));
+
+  return trackedPaths
+    .filter((path) => posix.basename(path) === 'package.json' && path !== 'package.json')
+    .map((path) => posix.dirname(path))
+    .filter(
+      (folder) =>
+        included.some((pattern) => new Bun.Glob(pattern).match(folder)) &&
+        !excluded.some((pattern) => new Bun.Glob(pattern).match(folder)),
+    )
+    .toSorted();
+}

package/src/test-layout/oxc-parser-module.ts

@@ -0,0 +1,7 @@
+import type { Visitor, parseSync } from 'oxc-parser';
+
+export interface OxcParserModule {
+  readonly Visitor: typeof Visitor;
+
+  readonly parseSync: typeof parseSync;
+}

package/src/test-layout/parse-workspace-patterns.ts

@@ -0,0 +1,27 @@
+export type ParsedWorkspaces =
+  | { readonly kind: 'single' }
+  | { readonly kind: 'workspaces'; readonly patterns: readonly string[] };
+
+// A root package.json declares workspaces as a list, or as an object with a `packages` list.
+export function parseWorkspacePatterns(manifest: unknown): ParsedWorkspaces {
+  const workspaces: unknown =
+    typeof manifest === 'object' && manifest !== null
+      ? Reflect.get(manifest, 'workspaces')
+      : undefined;
+
+  if (workspaces === undefined) {
+    return { kind: 'single' };
+  }
+
+  const list: unknown =
+    typeof workspaces === 'object' && workspaces !== null && !Array.isArray(workspaces)
+      ? Reflect.get(workspaces, 'packages')
+      : workspaces;
+
+  return {
+    kind: 'workspaces',
+    patterns: Array.isArray(list)
+      ? list.filter((pattern): pattern is string => typeof pattern === 'string')
+      : [],
+  };
+}

package/src/test-layout/read-oxc-parser.ts

@@ -0,0 +1,23 @@
+import type { OxcParserModule } from './oxc-parser-module.ts';
+
+// The module name is built at run time, so the step bundle that CI downloads leaves oxc-parser out:
+// its native binding fails at import time on a runner with no node_modules, which would break every
+// check in the bundle. Only this check needs the parser, and it runs from an install.
+export async function readOxcParser(): Promise<OxcParserModule> {
+  const loaded: unknown = await import(['oxc', 'parser'].join('-'));
+
+  if (!isOxcParserModule(loaded)) {
+    throw new Error('oxc-parser exports no parseSync and no Visitor');
+  }
+
+  return loaded;
+}
+
+function isOxcParserModule(value: unknown): value is OxcParserModule {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'parseSync') === 'function' &&
+    typeof Reflect.get(value, 'Visitor') === 'function'
+  );
+}

package/src/test-layout/types.ts

@@ -0,0 +1,19 @@
+export interface SourceFile {
+  readonly path: string;
+
+  readonly text: string;
+}
+
+export interface TestLayout {
+  // Every path git tracks.
+  readonly trackedPaths: readonly string[];
+
+  // The workspace folders of the root package.json, relative to the repo root.
+  readonly workspaces: readonly string[];
+
+  // Whether the root package.json declares `workspaces`. A repo without the field is one package.
+  readonly isWorkspaceRepo: boolean;
+
+  // The suffixes that lanes use, each with its dot, such as `.browser`.
+  readonly laneSuffixes: readonly string[];
+}