refactor(layering): R84 requires each new unit test to be named for a module beside it

[thymikee]

Stacked on #3667 (test-kit single entry) on #3659 (R11 devDependencies) on #3645 (R83).

What

R84 test-colocation: every *.test.ts under root src/ and packages/<pkg>/src/ sits in the directory of a module (or in that directory's __tests__/) and is named <module>.test.ts or <module>-<aspect>.test.ts. It measures its offenders against the merge-base and keeps no baseline file, the same way R83 does: 202 unmatched tests at head against 202 at the merge-base. Growth fails; moving or renaming a test into place needs no edit (base entries are carried to head coordinates through renamedSince, so a rename is the same entry). Burn-down belongs to the package and root workers; this PR only lands the rule.

Conventions (stated in the rule's doc comment, so it needs no exemptions)

• Cross-module package tests (conformance drivers, package-surface tests) are named for the package entry: index-<aspect>.test.ts, beside index.ts. index is an ordinary module to the rule.
• Repo-level guards (tests that assert on Swift sources, manifests, docs or scripts) move to test/repo-guards/, under the exempt test/ tree, and run in unit-core.
• Exempt: test/, scripts/, package-local test/ trees. The rule reads only src/ and packages/*/src/, and not test-kit, whose sources are test support.
• A module is any production source file (isProductionSourceFile): fixtures and __tests__/ helpers never count as the module a test is named for.

Evidence

• test-colocation.test.ts: matched by module and by -aspect; unmatched for a different name, a glued suffix or a dotted suffix; __tests__ judged against the parent directory (and not against modules inside __tests__); index-<aspect> matched only with an index.ts beside it; fixtures never the module; test/, scripts/ and package test trees unmeasured; growth fails, a cleanup or unchanged set passes; the message names both conventions.
• Planted src/__tests__/planted-unmatched.test.ts in the real tree: check:layering named it under R84. Removed.
• The measurement runs through mergeBaseRatchets (LayeringRatchets.unmatchedTests); measureRatchets now takes the tracked tree ({ manifests, files }) that R83 and R84 share.
• Gates: pnpm check:quick, check:layering (384 node tests), check:fallow, check:gate-manifest, check:affected --run, repo-wide pnpm format.

🤖 Generated with Claude Code

[cubic-dev-ai]

All reported issues were addressed across 6 files

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

The code at bce7f7d has one problem to fix before merge. R84 sends authors to a test/repo-guards/ directory that no test project collects. The checks are still queued, with no failures so far. The diff only touches scripts/layering, so the Repo Guards and Lint & Format jobs through check:layering are the ones that apply. No conflicts.

The violation message in test-colocation.ts, the rule comment above it and the PR body all say repo-level guards belong in test/repo-guards/ and "run in unit-core". That directory does not exist at this commit, and the unit-core include in vitest.config.ts lists test/ files one by one with no test/repo-guards glob. No gate fails when a test file belongs to no vitest project. An author who follows the remedy moves a guard out of src/, and it then runs in no lane while check:layering, the unit suite and CI stay green. The burn-down will take this route for some of the 347 offenders. The rule should be that every location R84 names as a remedy is collected by a vitest project. Please add test/repo-guards/**/*.test.ts to the unit-core include and map it in check:affected, or drop that remedy from the message and comment until the PR that creates the directory lands. To validate, put a throwaway test in test/repo-guards/ and show that the unit suite runs it.

Not blocking, and fine to take or leave: no fixture-repo test covers a test that was unmatched at the base and then renamed (the carry-over through the base-to-head mapping and the re-sort in ratchet-reference.ts), and a case like the one at session-authority-overlay.test.ts:312 would pin it. IN_SCOPE and TEST_FILE in test-colocation.ts also re-spell predicates from tracked-sources.ts, so exporting those and reusing them would keep one source of truth.

The two open inline threads on the declaration-module regex and the unmatched-test sort are fixed at this commit. Please resolve the regex thread and the sort thread.

I read the code but did not run check:layering. So I could not confirm the 347 count, which the rule comment gives as 346, or the planted-test result. The rename carry-over is checked by reading only.

Before merge, a vitest project must collect test/repo-guards/, or the message must drop that remedy.

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.24 MB	5.24 MB	0 B
Package (unpacked)	5.24 MB	5.24 MB	0 B
Package (download)	1.57 MB	1.57 MB	-4 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	19.9 ms	18.1 ms	-1.8 ms
CLI --help	50.6 ms	51.3 ms	+0.7 ms

[thymikee]

The base was old: #3663 added the glob to unit-core before this stack was rebased onto it. On the current head (vitest.config.ts:138, inside the unit-core include list):

            'test/repo-guards/*.test.ts',

and pnpm vitest list --project unit-core lists them under [unit-core], e.g.

[unit-core] test/repo-guards/apple-runner-log-redaction.test.ts > commit-wait cadence logging goes through the typed value-free boundary
[unit-core] test/repo-guards/apple-runner-package-source.test.ts > package apple runner source strips unit-test blocks without mutating checkout source

To keep the remedy from rotting, test-colocation.test.ts now asserts that vitest.config.ts still collects test/repo-guards/*.test.ts, so removing the glob fails check:layering. The non-blocking points are taken too: R84 reuses SOURCE_TREE_ROOT from tracked-sources instead of re-spelling it, the carried merge-base entries go through a tested inHeadCoordinates helper (rename into a new lexical position, re-sorted), and the rule comment no longer hard-codes a count (the live number, 253 at the new merge-base, is in the check:layering output). Both inline threads you listed are resolved.

[thymikee]

The PR is ready. Both earlier threads from the review of bce7f7d are fixed at 56bbc2e: foo.d.ts is no longer indexed as foo in measureUnmatchedTests, and the sort in inHeadCoordinates is now pinned by a test.

Not blocking: the new test at https://github.com/callstack/agent-device/blob/56bbc2e/scripts/layering/test-colocation.test.ts#L151 matches the literal glob text in vitest.config.ts instead of asking vitest what it collects, and TEST_KIT_TREE and TEST_FILE in https://github.com/callstack/agent-device/blob/56bbc2e/scripts/layering/test-colocation.ts#L32 repeat parts of TEST_SUPPORT_PATH from tracked-sources.ts. You can take or leave both.

Both cubic-dev-ai threads are fixed at this head, so you can resolve them: the .d.ts indexing one (#3669 (comment)) and the inHeadCoordinates sort one (#3669 (comment)).

I did not run check:layering or vitest list. I checked that test/repo-guards is collected from the config text at 56bbc2e and from your quoted vitest list output. I also did not exercise a rename that git does not detect as a rename. renamedSince does not map it, so it shows as a new offender, which fits the rename-into-place design.

No conflicts. CI is still pending: every check is queued or was cancelled by a newer push, and none has failed. This diff only touches scripts/layering, so Repo Guards (check:layering) and unit-core are the jobs that matter. Both need to go green on 56bbc2e before merge.