Skip to content

Commit 63fd297

Browse files
committed
refactor(layering): R11 keeps every relative package escape, compiled or not
Maintainer review on #3289: `if (compiled) continue;` retired more than tsc replaces. Planted the reviewer's exact case: packages/host-kit/src/r11-planted-sibling-tunnel.ts import { AppError } from '../../kernel/src/errors.ts'; pnpm exec tsc -b packages/host-kit --force -> exit 0, no diagnostics The reference redirects kernel's sources to their dist-types .d.ts, so nothing outside host-kit's rootDir is emitted and neither TS6059 nor TS6307 fires - the #3279 proof held only for the ROOT escape (TS2307 there, no project redirects it). The sibling tunnel breaks runtime identity instead: Node loads kernel once by path and once by specifier, so two AppError classes coexist and instanceof fails - invisible to any compiler. The escape branch returns for every package source; only the RESOLUTION branches (unknown package, un-exported subpath) stay compiler-owned. checkPackageInternalSites gains the requested compiled=true sibling-tunnel test, mutation-proven: re-adding the skip turns it, the escape test, and the quote-form test red. The non-blocking items are taken, both true: project-references.test.ts now asserts the root include list (pinning the help-conformance divergence the predicate's doc block promises) and the per-package include:[src]/no-exclude shape insideCompiledSources' regexes assume - mutation: adding an exclude to xml or a second scripts entry to root goes red - and check.ts's R11 summary line states the corrected split.
1 parent f75da8b commit 63fd297

4 files changed

Lines changed: 99 additions & 23 deletions

File tree

‎scripts/layering/check.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,9 @@
3232
// - Across the DAEMON MODULARITY MIGRATION: R7 ownership pressure and external
3333
// daemon request/session-state importers only shrink, R9 zone membership cannot grow or absorb
3434
// engine files, and planned logical modules start with zero forbidden/internal imports (R10).
35-
// - Over the WORKSPACE PACKAGES: every workspace specifier declared, no relative tunnelling
36-
// into a package's src, and the full specifier sweep for the scripts/ files the type graph
35+
// - Over the WORKSPACE PACKAGES: every workspace specifier declared, no relative path
36+
// leaving its package dir (compiled or not — a planted sibling tunnel tsc -b accepted,
37+
// #3289 review), and the full specifier sweep for the scripts/ files the type graph
3738
// omits — resolution itself (unknown package, un-exported subpath) is TS2307 under tsc -b
3839
// for compiled sources (#3279) (R11).
3940
// - Over PLATFORM PACKAGE COMPOSITION: six private metadata façades meet at the exact root

‎scripts/layering/package-boundaries.test.ts‎

Lines changed: 35 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -230,22 +230,48 @@ test('double-quoted and re-export routes into packages are not invisible to R11'
230230
'packages/kernel/src/errors.ts',
231231
'export * from "../../../src/utils/exec.ts";',
232232
);
233-
// The escape is compiler-owned for compiled sources; scripts/ and package harness files that
234-
// sit outside the type graph keep the R11 branch (#3279).
235-
assert.equal(checkPackageInternalSites(kernel, packageEscape, ALL, true).length, 0);
233+
// The escape is R11's own for EVERY package source, compiled or not (#3289 maintainer
234+
// review): the compiled-only skip was retired with a planted proof, below.
235+
assert.equal(checkPackageInternalSites(kernel, packageEscape, ALL, true).length, 1);
236236
assert.equal(checkPackageInternalSites(kernel, packageEscape, ALL, false).length, 1);
237237
});
238238

239239
// This `src/utils` path is another in-memory arbitrary parser fixture, not a live repository path.
240-
test('a package file importing root src is compiler-owned once tsc -b sees it', () => {
241-
// #3279: composite `rootDir` rejects a package->root relative escape with TS6059 + TS6307
242-
// (planted proof in the PR). R11 keeps the branch only for package files the graph omits.
243-
const sites = specifierSites(
240+
test('a package relative escape is R11-owned, compiled or not', () => {
241+
// #3289 maintainer review restored this branch after a planted `tsc -b` run showed the
242+
// compiler covers NEITHER package escape for a REFERENCED sibling:
243+
// packages/host-kit/src/r11-planted-sibling-tunnel.ts
244+
// import { AppError } from '../../kernel/src/errors.ts';
245+
// pnpm exec tsc -b packages/host-kit --force -> exit 0, no diagnostics
246+
// The reference redirects kernel's sources to their dist-types .d.ts, so nothing outside
247+
// host-kit's rootDir is emitted and TS6059/TS6307 never fire; the earlier PR-#3279 proof
248+
// (TS6059+TS6307) only held for the ROOT escape, where no project redirects. What both
249+
// tunnels break instead is runtime identity: Node instantiates the tunnelled module once
250+
// by path and once by specifier, so two AppError classes coexist and instanceof fails —
251+
// invisible to any compiler, so R11 holds it for compiled files too.
252+
const rootEscape = specifierSites(
244253
'packages/kernel/src/errors.ts',
245254
"import { helper } from '../../../src/utils/exec.ts';",
246255
);
247-
assert.deepEqual(checkPackageInternalSites(kernel, sites, ALL, true), []);
248-
assert.deepEqual(rules(checkPackageInternalSites(kernel, sites, ALL, false)), [
256+
assert.deepEqual(rules(checkPackageInternalSites(kernel, rootEscape, ALL, true)), [
257+
'R11 package-boundaries',
258+
]);
259+
assert.match(
260+
checkPackageInternalSites(kernel, rootEscape, ALL, true)[0]!.message,
261+
/escapes packages\/kernel/,
262+
);
263+
264+
// The exact reviewer case: compiled=true with a sibling-relative specifier.
265+
const siblingTunnel = specifierSites(
266+
'packages/kernel/src/errors.ts',
267+
"import { thing } from '../../xml/src/index.ts';",
268+
);
269+
assert.deepEqual(rules(checkPackageInternalSites(kernel, siblingTunnel, ALL, true)), [
270+
'R11 package-boundaries',
271+
]);
272+
273+
// Uncompiled package files keep the same branch (they never reach the compiler at all).
274+
assert.deepEqual(rules(checkPackageInternalSites(kernel, rootEscape, ALL, false)), [
249275
'R11 package-boundaries',
250276
]);
251277
});

‎scripts/layering/package-boundaries.ts‎

Lines changed: 22 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -152,14 +152,18 @@ function specifierPackageName(specifier: string): string | undefined {
152152
* `--experimental-strip-types`, not a tsconfig program), the `packages/maestro/test/`
153153
* conformance harness, and package build configs — reaches packages through import sites the
154154
* compiler never parses, so R11 stays the only owner of every boundary claim about those
155-
* routes (#3279).
155+
* routes (#3279). Only the RESOLUTION branches (unknown package, un-exported subpath) are
156+
* split this way; the relative-escape branch fires regardless — a planted sibling tunnel
157+
* `tsc -b` accepted, see `checkPackageInternalSites`.
156158
*
157159
* One documented divergence: the root program also includes
158160
* `scripts/help-conformance-command-validator.ts`, which this predicate classifies as
159161
* uncompiled. That is fail-closed — R11 keeps its full branch set (unknown package,
160-
* exports-map) for the file on top of what tsc enforces — never fail-open. The divergence is
161-
* pinned in `project-references.test.ts`, so a second scripts entry joining the root program
162-
* must be recorded there rather than silently widening the exception.
162+
* exports-map) for the file on top of what tsc enforces — never fail-open. The divergence
163+
* and the exact root include list are pinned in `project-references.test.ts`, and the
164+
* per-package `include: ["src"]` / no-`exclude` shape this predicate's regexes assume is
165+
* pinned there too, so widening any project's file set must be recorded there rather than
166+
* silently diverging from this predicate.
163167
*/
164168
export function insideCompiledSources(file: string): boolean {
165169
return /^packages\/[^/]+\/src\//.test(file) || /^src\//.test(file) || /^test\//.test(file);
@@ -169,11 +173,17 @@ export function insideCompiledSources(file: string): boolean {
169173
* Rules for files INSIDE a package. An undeclared sibling import is R11's alone: pnpm links
170174
* every workspace package under the root `node_modules`, so the import resolves, compiles, and
171175
* runs in this repo even when the manifest never declares it — and a published bundle
172-
* externalizes against that declaration. The relative escape past the package dir and every
173-
* resolution failure (unknown package, subpath the exports map does not name) are owned by the
174-
* compiler for compiled files: composite `rootDir` fails the escape with TS6059 + TS6307 and
175-
* NodeNext resolution fails the specifier with TS2307. Both are proven in #3279; uncompiled
176-
* files never reach either check, so for them R11 holds every branch.
176+
* externalizes against that declaration. The relative escape past the package dir is R11's
177+
* too, compiled or not: a planted `pnpm exec tsc -b packages/host-kit --force` with
178+
* `import { AppError } from '../../kernel/src/errors.ts'` in `host-kit/src/` **exits 0** —
179+
* the redirect to kernel's `dist-types` keeps every emitted file under host-kit's `rootDir`,
180+
* so neither TS6059 nor TS6307 fires (the root-escape tunnel DOES fail: TS2307, since `../..
181+
* /../kernel/...` lands outside every include and no package owns `kernel` at that depth).
182+
* What the sibling tunnel breaks is runtime identity — Node loads kernel once by path and
183+
* once by specifier, so two AppError classes coexist and `instanceof` silently fails. That
184+
* is invisible to any compiler. The remaining resolution failures (unknown package,
185+
* subpath the exports map does not name) are owned by NodeNext for compiled files with
186+
* TS2307; uncompiled files never reach either check, so for them R11 holds every branch.
177187
*/
178188
export function checkPackageInternalSites(
179189
pkg: WorkspacePackage,
@@ -184,7 +194,6 @@ export function checkPackageInternalSites(
184194
const violations: PackageBoundaryViolation[] = [];
185195
for (const site of sites) {
186196
if (site.specifier.startsWith('.')) {
187-
if (compiled) continue;
188197
const resolved = path.posix.normalize(
189198
path.posix.join(path.posix.dirname(site.file), site.specifier),
190199
);
@@ -194,8 +203,9 @@ export function checkPackageInternalSites(
194203
file: site.file,
195204
line: site.line,
196205
message:
197-
`'${site.specifier}' escapes ${pkg.dir}/ — a workspace package may not reach root ` +
198-
`code. Depend on another package's specifier, or move the shared code below this package.`,
206+
`'${site.specifier}' escapes ${pkg.dir}/ — a workspace package may not reach ` +
207+
`outside its own directory. Import a sibling through its specifier (Node would ` +
208+
`load the tunnelled module twice), or move the shared code below ${pkg.dir}.`,
199209
});
200210
}
201211
continue;

‎scripts/layering/project-references.test.ts‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ const repoRoot = path.resolve(import.meta.dirname, '../..');
1818
function readTsconfig(relativePath: string): {
1919
references?: { path: string }[];
2020
extends?: string;
21+
include?: string[];
22+
exclude?: string[];
2123
compilerOptions?: Record<string, unknown>;
2224
} {
2325
const source = fs.readFileSync(path.join(repoRoot, relativePath), 'utf8');
@@ -55,6 +57,43 @@ test('root and examples/sdk reference exactly the workspace package set', () =>
5557
assert.deepEqual(referencedPackageDirs('examples/sdk/tsconfig.json', 'examples/sdk'), expected);
5658
});
5759

60+
test('the compiled-set predicate is licensed by the tsconfig include/exclude shape it mirrors', () => {
61+
// `insideCompiledSources` (package-boundaries.ts) hard-codes the three include shapes the
62+
// tsc -b graph compiles: `packages/*/src`, root `src`, root `test`. That regex is honest
63+
// only while no project widens its file set behind it, so the shape is pinned here (the
64+
// file that already reads the tsconfigs), and the R11 side keeps its pin in
65+
// package-boundaries.test.ts (the #3279 walk-region test). A package tsconfig that gains
66+
// an `exclude`, or an include beyond `src` (plus replay-port's shared `global.d.ts`
67+
// sibling), or a root file added to the root include beyond src/test, must update the
68+
// predicate or fail here — the same "views cannot drift" rule as the reference lists.
69+
assert.deepEqual(readTsconfig('tsconfig.json').include, [
70+
'src',
71+
'test',
72+
'scripts/help-conformance-command-validator.ts',
73+
'packages/command-registry/src/global.d.ts',
74+
]);
75+
for (const pkg of readWorkspacePackages(repoRoot)) {
76+
const config = readTsconfig(`${pkg.dir}/tsconfig.json`);
77+
assert.equal(config.exclude, undefined, `${pkg.dir}/tsconfig.json must not declare exclude`);
78+
assert.deepEqual(
79+
(config.include ?? ['**/*']).filter((entry) => !entry.endsWith('global.d.ts')),
80+
['src'],
81+
`${pkg.dir}/tsconfig.json must keep including exactly src/`,
82+
);
83+
}
84+
});
85+
86+
test('the one scripts file in the root program is the divergence insideCompiledSources records', () => {
87+
// The predicate classifies scripts/help-conformance-command-validator.ts as UNCOMPILED
88+
// (fail-closed: R11 keeps its full branch set there) even though the root include names
89+
// it. This is the assertion the predicate's doc block points at: the divergence is
90+
// recorded here, and a second scripts file joining the root program must be recorded
91+
// next to this one rather than silently widening the exception.
92+
const rootInclude = readTsconfig('tsconfig.json').include ?? [];
93+
const scriptsEntries = rootInclude.filter((entry) => entry.startsWith('scripts/'));
94+
assert.deepEqual(scriptsEntries, ['scripts/help-conformance-command-validator.ts']);
95+
});
96+
5897
test('the root manifest declares every workspace package as a workspace dependency', () => {
5998
const manifest = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')) as {
6099
dependencies?: Record<string, string>;

0 commit comments

Comments
 (0)