Skip to content

Commit 1970ee0

Browse files
author
DavidQ
committed
Add guardrails against internal barrel exports - PR_26140_079-add-internal-barrel-guardrails
1 parent 8107dbe commit 1970ee0

4 files changed

Lines changed: 569 additions & 0 deletions

File tree

‎docs/dev/reports/internal_barrel_guardrails_report.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# PR_26140_079 Internal Barrel Guardrails Report
2+
3+
## Scope
4+
- Added `tools/dev/checkInternalBarrelGuard.mjs`.
5+
- Added `tools/dev/checkInternalBarrelGuard.baseline.json`.
6+
- Added `npm run check:internal-barrel-guard`.
7+
- No schema files were changed.
8+
- No sample JSON files were changed.
9+
- No runtime files were removed.
10+
11+
## Blocked Patterns
12+
- New internal pass-through files under `src/**`, `samples/shared/**`, or `tools/**` whose meaningful source is only `export ... from` re-exports.
13+
- New imports or export-from statements that target internal `/index.js` barrel files.
14+
15+
## Allowed Patterns
16+
- Existing legacy barrel debt listed in `tools/dev/checkInternalBarrelGuard.baseline.json`.
17+
- Game entrypoints such as `games/*/index.js`.
18+
- Sample entrypoints such as `samples/phase-*/****/index.js`.
19+
- Tool/browser entrypoints under `tools/**/index.js` when the target is an actual launch file and not a pass-through barrel.
20+
21+
## Ignored Paths
22+
- `node_modules/**`
23+
- `.git/**`
24+
- `tmp/**`
25+
- `docs/archive/**`
26+
- `docs/dev/reports/**`
27+
- `tests/results/**`
28+
- minified JavaScript files
29+
30+
## Current Baseline
31+
- Existing baseline violations: 35
32+
- Baseline is intentionally used so this PR blocks new barrel regressions without expanding scope into unrelated runtime cleanup.
33+
34+
## Validation
35+
- PASS: `node --check tools/dev/checkInternalBarrelGuard.mjs`
36+
- PASS: `node -e "const fs=require('fs'); JSON.parse(fs.readFileSync('package.json','utf8')); JSON.parse(fs.readFileSync('tools/dev/checkInternalBarrelGuard.baseline.json','utf8')); console.log('PASS JSON parse package and baseline');"`
37+
- PASS: `npm run check:internal-barrel-guard`
38+
- PASS: `npm run test:workspace-v2` passed 59 tests.
39+
- PASS: schema/sample JSON audit found no changed schema files and no changed sample JSON files.
40+
41+
## Full Samples Smoke Test
42+
- Skipped. This PR adds a repository validation guard and package script only; it does not change sample loader behavior.
43+
44+
## Manual Validation Notes
45+
- Run `npm run check:internal-barrel-guard`.
46+
- Expected pass behavior: current repo passes with `new_violations=0`.
47+
- Expected fail behavior: adding a new internal pass-through barrel or importing a new internal `/index.js` barrel reports `INTERNAL_BARREL_GUARD_FAILED`.

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
"check:phase24-closeout-guard": "node tools/dev/checkPhase24CloseoutExecutionGuard.mjs",
1212
"check:style-system-guard": "node tools/dev/checkStyleSystemGuard.mjs",
1313
"check:intentional-alias-ledger": "node tools/dev/checkIntentionalAliasLedgerGuard.mjs",
14+
"check:internal-barrel-guard": "node tools/dev/checkInternalBarrelGuard.mjs",
1415
"check:games-template-contract": "node ./scripts/validate-games-template-contract.mjs",
1516
"codex:review-artifacts": "node ./scripts/write-codex-review-artifacts.mjs",
1617
"test:asset-manager-v2": "playwright test tests/playwright/tools/AssetManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list",

‎tools/dev/checkInternalBarrelGuard.baseline.json‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
{
2+
"generatedAt": "2026-05-21T18:39:09.261Z",
3+
"violations": [
4+
{
5+
"file": "samples/phase-01/0116/ECSMovementSystemScene.js",
6+
"line": 11,
7+
"type": "internal-index-import",
8+
"detail": "Import targets internal index barrel /src/engine/components/index.js (src/engine/components/index.js)."
9+
},
10+
{
11+
"file": "samples/phase-01/0117/ECSInputSystemScene.js",
12+
"line": 11,
13+
"type": "internal-index-import",
14+
"detail": "Import targets internal index barrel /src/engine/components/index.js (src/engine/components/index.js)."
15+
},
16+
{
17+
"file": "samples/phase-01/0118/ECSCollisionSystemScene.js",
18+
"line": 11,
19+
"type": "internal-index-import",
20+
"detail": "Import targets internal index barrel /src/engine/components/index.js (src/engine/components/index.js)."
21+
},
22+
{
23+
"file": "samples/phase-01/0120/ECSSceneWorldScene.js",
24+
"line": 11,
25+
"type": "internal-index-import",
26+
"detail": "Import targets internal index barrel /src/engine/components/index.js (src/engine/components/index.js)."
27+
},
28+
{
29+
"file": "samples/phase-01/0121/UIOverlayScene.js",
30+
"line": 11,
31+
"type": "internal-index-import",
32+
"detail": "Import targets internal index barrel /src/engine/components/index.js (src/engine/components/index.js)."
33+
},
34+
{
35+
"file": "samples/phase-01/0122/EntityLifecycleScene.js",
36+
"line": 11,
37+
"type": "internal-index-import",
38+
"detail": "Import targets internal index barrel /src/engine/components/index.js (src/engine/components/index.js)."
39+
},
40+
{
41+
"file": "samples/phase-01/0123/DebugStatsScene.js",
42+
"line": 11,
43+
"type": "internal-index-import",
44+
"detail": "Import targets internal index barrel /src/engine/components/index.js (src/engine/components/index.js)."
45+
},
46+
{
47+
"file": "samples/phase-01/0124/DataDrivenWorldScene.js",
48+
"line": 11,
49+
"type": "internal-index-import",
50+
"detail": "Import targets internal index barrel /src/engine/components/index.js (src/engine/components/index.js)."
51+
},
52+
{
53+
"file": "samples/phase-02/0216/PrefabSystemScene.js",
54+
"line": 11,
55+
"type": "internal-index-import",
56+
"detail": "Import targets internal index barrel /src/engine/prefabs/index.js (src/engine/prefabs/index.js)."
57+
},
58+
{
59+
"file": "samples/phase-02/0218/PolishedPlayableSliceScene.js",
60+
"line": 21,
61+
"type": "internal-index-import",
62+
"detail": "Import targets internal index barrel /src/engine/prefabs/index.js (src/engine/prefabs/index.js)."
63+
},
64+
{
65+
"file": "samples/phase-05/0501/CombatHitboxesScene.js",
66+
"line": 11,
67+
"type": "internal-index-import",
68+
"detail": "Import targets internal index barrel /src/engine/combat/index.js (src/engine/combat/index.js)."
69+
},
70+
{
71+
"file": "samples/phase-05/0502/AttackTimingWindowsScene.js",
72+
"line": 11,
73+
"type": "internal-index-import",
74+
"detail": "Import targets internal index barrel /src/engine/combat/index.js (src/engine/combat/index.js)."
75+
},
76+
{
77+
"file": "samples/phase-05/0503/DamageInvulnerabilityScene.js",
78+
"line": 11,
79+
"type": "internal-index-import",
80+
"detail": "Import targets internal index barrel /src/engine/combat/index.js (src/engine/combat/index.js)."
81+
},
82+
{
83+
"file": "samples/phase-05/0504/KnockbackResponseScene.js",
84+
"line": 11,
85+
"type": "internal-index-import",
86+
"detail": "Import targets internal index barrel /src/engine/combat/index.js (src/engine/combat/index.js)."
87+
},
88+
{
89+
"file": "samples/phase-05/0505/HealthDeathStateScene.js",
90+
"line": 11,
91+
"type": "internal-index-import",
92+
"detail": "Import targets internal index barrel /src/engine/combat/index.js (src/engine/combat/index.js)."
93+
},
94+
{
95+
"file": "samples/phase-05/0506/CombatDebugOverlayScene.js",
96+
"line": 12,
97+
"type": "internal-index-import",
98+
"detail": "Import targets internal index barrel /src/engine/combat/index.js (src/engine/combat/index.js)."
99+
},
100+
{
101+
"file": "src/engine/combat/index.js",
102+
"type": "pass-through-export-barrel",
103+
"detail": "Internal pass-through files using `export ... from` are disallowed."
104+
},
105+
{
106+
"file": "src/engine/debug/CombatDebugOverlay.js",
107+
"line": 8,
108+
"type": "internal-index-import",
109+
"detail": "Import targets internal index barrel ../combat/index.js (src/engine/combat/index.js)."
110+
},
111+
{
112+
"file": "src/engine/debug/standard/threeD/legacySummarySurface.js",
113+
"type": "pass-through-export-barrel",
114+
"detail": "Internal pass-through files using `export ... from` are disallowed."
115+
},
116+
{
117+
"file": "src/engine/ecs/World.js",
118+
"line": 7,
119+
"type": "internal-index-import",
120+
"detail": "Import targets internal index barrel ../components/index.js (src/engine/components/index.js)."
121+
},
122+
{
123+
"file": "src/engine/prefabs/index.js",
124+
"type": "pass-through-export-barrel",
125+
"detail": "Internal pass-through files using `export ... from` are disallowed."
126+
},
127+
{
128+
"file": "src/shared/state/contracts.js",
129+
"type": "pass-through-export-barrel",
130+
"detail": "Internal pass-through files using `export ... from` are disallowed."
131+
},
132+
{
133+
"file": "src/shared/state/publicSelectors.js",
134+
"type": "pass-through-export-barrel",
135+
"detail": "Internal pass-through files using `export ... from` are disallowed."
136+
},
137+
{
138+
"file": "tests/combat/Combat.test.mjs",
139+
"line": 8,
140+
"type": "internal-index-import",
141+
"detail": "Import targets internal index barrel ../../src/engine/combat/index.js (src/engine/combat/index.js)."
142+
},
143+
{
144+
"file": "tests/shared/GetStateVariantClassification.test.mjs",
145+
"line": 11,
146+
"type": "internal-index-import",
147+
"detail": "Import targets internal index barrel ../../src/shared/state/index.js (src/shared/state/index.js)."
148+
},
149+
{
150+
"file": "tests/shared/SharedFoundationCombinedPass.test.mjs",
151+
"line": 29,
152+
"type": "internal-index-import",
153+
"detail": "Import targets internal index barrel ../../src/shared/data/index.js (src/shared/data/index.js)."
154+
},
155+
{
156+
"file": "tests/shared/SharedFoundationCombinedPass.test.mjs",
157+
"line": 17,
158+
"type": "internal-index-import",
159+
"detail": "Import targets internal index barrel ../../src/shared/id/index.js (src/shared/id/index.js)."
160+
},
161+
{
162+
"file": "tests/shared/SharedFoundationCombinedPass.test.mjs",
163+
"line": 30,
164+
"type": "internal-index-import",
165+
"detail": "Import targets internal index barrel ../../src/shared/io/index.js (src/shared/io/index.js)."
166+
},
167+
{
168+
"file": "tests/shared/SharedFoundationCombinedPass.test.mjs",
169+
"line": 23,
170+
"type": "internal-index-import",
171+
"detail": "Import targets internal index barrel ../../src/shared/math/index.js (src/shared/math/index.js)."
172+
},
173+
{
174+
"file": "tests/shared/SharedFoundationCombinedPass.test.mjs",
175+
"line": 32,
176+
"type": "internal-index-import",
177+
"detail": "Import targets internal index barrel ../../src/shared/state/index.js (src/shared/state/index.js)."
178+
},
179+
{
180+
"file": "tests/shared/SharedFoundationCombinedPass.test.mjs",
181+
"line": 31,
182+
"type": "internal-index-import",
183+
"detail": "Import targets internal index barrel ../../src/shared/types/index.js (src/shared/types/index.js)."
184+
},
185+
{
186+
"file": "tests/shared/SharedNumberStringIdCloseout.test.mjs",
187+
"line": 8,
188+
"type": "internal-index-import",
189+
"detail": "Import targets internal index barrel ../../src/shared/id/index.js (src/shared/id/index.js)."
190+
},
191+
{
192+
"file": "tests/shared/SharedNumberStringIdCloseout.test.mjs",
193+
"line": 13,
194+
"type": "internal-index-import",
195+
"detail": "Import targets internal index barrel ../../src/shared/number/index.js (src/shared/number/index.js)."
196+
},
197+
{
198+
"file": "tests/shared/SharedNumberStringIdCloseout.test.mjs",
199+
"line": 3,
200+
"type": "internal-index-import",
201+
"detail": "Import targets internal index barrel ../../src/shared/string/index.js (src/shared/string/index.js)."
202+
},
203+
{
204+
"file": "tools/shared/stringUtils.js",
205+
"type": "pass-through-export-barrel",
206+
"detail": "Internal pass-through files using `export ... from` are disallowed."
207+
}
208+
]
209+
}

0 commit comments

Comments
 (0)