Skip to content

Commit 233e885

Browse files
ToolboxAidToolboxAid
committed
Finalize Playwright monolith cleanup architecture with targeted-lane ownership, wrapper consolidation, and deterministic routing enforcement - PR_26146_043-monolith-cleanup-final-architecture-closeout
1 parent ed71bf2 commit 233e885

36 files changed

Lines changed: 427 additions & 254 deletions

‎docs/dev/reports/dependency_gating_report.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Dependency Gating Report
22

3-
Generated: 2026-05-26T22:17:10.904Z
3+
Generated: 2026-05-26T22:55:37.501Z
44
Status: PASS
55

66
## Gate Order
@@ -17,8 +17,8 @@ Status: PASS
1717
| workspace-contract | No | SKIP | none | Workspace Manager V2 contract and lifecycle behavior | Lane was not selected, so dependency-gated runtime scheduling skipped it. |
1818
| tool-runtime | No | SKIP | none | First-class tool runtime behavior | Lane was not selected, so dependency-gated runtime scheduling skipped it. |
1919
| game-runtime | No | SKIP | none | Game-owned Playwright runtime behavior | Lane was not selected, so dependency-gated runtime scheduling skipped it. |
20-
| integration | Yes | PASS | none | Workspace, tool, game index, and manifest handoff behavior | Lane has no lane dependencies and is eligible after preflight and compilation pass. |
21-
| engine-src | No | SKIP | none | src/ engine and shared runtime capability behavior | Lane was not selected, so dependency-gated runtime scheduling skipped it. |
20+
| integration | No | SKIP | none | Workspace, tool, game index, and manifest handoff behavior | Lane was not selected, so dependency-gated runtime scheduling skipped it. |
21+
| engine-src | Yes | PASS | none | src/ engine and shared runtime capability behavior | Lane has no lane dependencies and is eligible after preflight and compilation pass. |
2222
| samples | No | SKIP | none | Affected samples lane, on request only | Lane was not selected, so dependency-gated runtime scheduling skipped it. |
2323

2424
## Dependency Failures Caught Pre-Runtime

‎docs/dev/reports/dependency_hydration_reuse_report.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Dependency Hydration Reuse Report
22

3-
Generated: 2026-05-26T22:17:10.905Z
3+
Generated: 2026-05-26T22:55:37.502Z
44
Status: PASS
55

66
## Summary
@@ -16,7 +16,7 @@ Prevented fixture ownership traversal: 0
1616

1717
| Lane | Status | Helpers | Fixtures | Imports | Dependency Hydration Hash | Reason |
1818
| --- | --- | --- | --- | --- | --- | --- |
19-
| integration | INVALIDATED | tests/helpers/playwrightRepoServer.mjs; tests/helpers/playwrightStorageIsolation.mjs; tests/helpers/playwrightV8CoverageReporter.mjs; tests/helpers/workspaceV2CoverageReporter.mjs | games/Pong/game.manifest.json | tests/helpers/playwrightRepoServer.mjs; tests/helpers/playwrightStorageIsolation.mjs; tests/helpers/playwrightV8CoverageReporter.mjs; tests/helpers/workspaceV2CoverageReporter.mjs | a26bcd0115fc4315 | Dependency hydration was refreshed after warm-start invalidation. |
19+
| engine-src | INVALIDATED | none | none | src/engine/assets/AssetLoaderSystem.js; src/engine/assets/AssetRegistry.js; src/engine/assets/ImageAssetLoader.js; src/engine/audio/AudioService.js; src/engine/camera/Camera2D.js; src/engine/camera/Camera3D.js; src/engine/camera/CameraSystem.js; src/engine/core/Engine.js; src/engine/core/FixedTicker.js; src/engine/core/FrameClock.js; src/engine/core/RuntimeMetrics.js; src/engine/events/EventBus.js; src/engine/input/ActionInputService.js; src/engine/input/GamepadHapticsService.js; src/engine/input/GamepadInputAdapter.js; src/engine/input/InputMap.js; src/engine/input/InputService.js; src/engine/input/KeyboardState.js; src/engine/input/MouseState.js; src/engine/physics/arcadeBody.js; src/engine/physics/collision3d.js; src/engine/physics/drag.js; src/engine/physics/integration3d.js; src/engine/physics/scene3d.js; src/engine/rendering/CanvasRenderer.js; src/engine/rendering/LayeredRenderSystem.js; src/engine/scene/Scene.js; src/engine/scene/SceneManager.js; src/engine/systems/MovementSystem.js; src/engine/systems/PhysicsSystem.js | e13166ce3ced2d3e | Dependency hydration was refreshed after warm-start invalidation. |
2020

2121
## Safeguards
2222

‎docs/dev/reports/execution_graph_reuse_report.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Execution Graph Reuse Report
22

3-
Generated: 2026-05-26T22:17:10.905Z
3+
Generated: 2026-05-26T22:55:37.502Z
44
Status: PASS
55

66
## Summary
@@ -16,7 +16,7 @@ Prevented targeted scheduling work: 0
1616

1717
| Lane | Status | Snapshot Status | Execution Graph Hash | Reason |
1818
| --- | --- | --- | --- | --- |
19-
| integration | INVALIDATED | INVALIDATED | 012d1831d3650992 | Lane snapshot is part of the selected targeted execution graph. |
19+
| engine-src | INVALIDATED | INVALIDATED | 390a3c57c1ad187d | Lane snapshot is part of the selected targeted execution graph. |
2020

2121
## Safeguards
2222

‎docs/dev/reports/failure_fingerprint_report.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Failure Fingerprint Report
22

3-
Generated: 2026-05-26T22:17:24.433Z
3+
Generated: 2026-05-26T22:55:38.503Z
44
Status: PASS
55

66
## Summary

‎docs/dev/reports/filesystem_scan_reduction_report.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,23 @@
11
# Filesystem Scan Reduction Report
22

3-
Generated: 2026-05-26T22:20:10.285Z
3+
Generated: 2026-05-26T22:54:12.028Z
44
Status: PASS
55

66
## Scan Enforcement
77

88
| Path | Status | Reason |
99
| --- | --- | --- |
10-
| tests/playwright | BROAD | Standalone structural audit intentionally enumerated all Playwright ownership buckets. |
11-
| tests/helpers | BROAD | Standalone structural audit intentionally checked all shared helper ownership. |
10+
| tests/playwright | PREVENTED | Targeted lanes supplied explicit spec files; global Playwright discovery was not used. |
11+
| tests/helpers | SCOPED | Helper discovery used the targeted import graph instead of enumerating every helper. |
12+
| games/ | SCOPED | Game fixture discovery used explicit manifest/path references from targeted files. |
13+
| tests/playwright/engine | SKIP | Unselected lane directory discovery was skipped. |
14+
| tests/playwright/games | SKIP | Unselected lane directory discovery was skipped. |
15+
| tests/playwright/integration | SKIP | Unselected lane directory discovery was skipped. |
16+
| tests/playwright/tools | SCOPED | Selected lane discovery was restricted to explicit target specs. |
1217

1318
## Runtime Savings Observations
1419

15-
- Standalone ownership validation used broad mode by design; targeted lane runner supplies scoped discovery inputs.
20+
- Scoped discovery prevented broad Playwright lane-directory enumeration for targeted execution.
1621
- Helper and fixture inputs are explicit, allowing the runner to cache the discovery map within one execution cycle.
1722
- Deterministic discovery-scope failures block Playwright launch instead of expanding into fallback lanes.
1823
- Full samples smoke remains outside targeted discovery unless samples scope is explicitly active.

‎docs/dev/reports/final_monolith_cleanup_report.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# PR_26146_043 Final Monolith Cleanup Report
2+
3+
Generated: 2026-05-26
4+
Status: PASS
5+
6+
## Source Of Truth
7+
8+
This closeout uses these reports as the source of truth:
9+
- `docs/dev/reports/monolithic_test_code_audit.md`
10+
- `docs/dev/reports/monolithic_test_split_candidates.md`
11+
- `docs/dev/reports/monolith_split_execution_report.md`
12+
- `docs/dev/reports/remaining_monoliths_report.md`
13+
14+
No sample JSON was modified.
15+
16+
## Removed Obsolete Wrappers
17+
18+
| Removed wrapper | Replacement | Reason |
19+
| --- | --- | --- |
20+
| `npm run test:asset-manager-v2` | `npm run test:lane:tool-runtime` | The direct Playwright shortcut bypassed the targeted runner, zero-browser preflight, manifest validation, warm-start reuse, and lane ownership checks. The covered Asset Manager assertions remain in the tool-runtime lane. |
21+
| `npm run test:preview-generator-v2` | `npm run test:lane:tool-runtime` | The direct Playwright shortcut became obsolete after Preview Generator, Palette Manager, and Tool Template coverage were split into focused tool-runtime specs. |
22+
23+
## Removed Fallback Paths
24+
25+
| Area | Before | After |
26+
| --- | --- | --- |
27+
| Lane manifest inputs | A lane with no `discoveryTargets` could fall back to command-derived targets. | `laneDiscoveryTargets()` now returns only explicitly declared lane targets. |
28+
| Engine/src lane | Node test inputs were inferred from the command list. | Engine/src test inputs are declared in `discoveryTargets`. |
29+
| Samples lane | Sample test inputs were inferred from the command list when the lane was selected. | Samples test inputs are declared in `discoveryTargets`, while runtime remains gated by `--include-samples`. |
30+
| Runner preflight | Command targets were validated for existence and lane path only. | Runner preflight now also fails if any command target is missing from the lane manifest target list. |
31+
32+
## Preserved Intentional Wrappers
33+
34+
| Preserved wrapper | Reason |
35+
| --- | --- |
36+
| `npm run test:workspace-v2` | Compatibility entry that routes through `workspace-contract`; it no longer launches Playwright directly. |
37+
| `npm run test:lane:*` | Authoritative targeted lane entry points. |
38+
| `npm run test:lanes` | Safe no-lane mode; no runtime lanes execute without an explicit lane or `--all`. |
39+
| `npm run test:lanes:preflight` and `npm run test:playwright:zero-browser` | Zero-browser preflight entry points. |
40+
| `npm run test:audit:locations` and `npm run test:playwright:structure` | Explicit static broad audits; zero-browser only. |
41+
| `npm run test:lane:samples` | Explicit samples lane wrapper; still requires `--include-samples` and is not full samples smoke. |
42+
43+
## Final Routing Architecture
44+
45+
Targeted lanes are the authoritative default. Package test routing now has no direct `playwright test` shortcuts outside `test:lane:*`; browser-backed PR validation goes through `scripts/run-targeted-test-lanes.mjs`.
46+
47+
Static broad discovery remains available only through explicit zero-browser audit commands. Runtime broad execution remains explicit/on-request only through opt-in commands such as `--all`, the isolated broad integration spec file, or the existing runtime smoke commands.
48+
49+
Deterministic setup failures stop before browser/runtime startup through lane registration, runner preflight, scoped discovery, manifest input validation, warm-start validation, snapshot validation, lane compilation, and dependency gating.
50+
51+
## Preserved Broad/Expensive Tests
52+
53+
| Test or command | Status | Reason |
54+
| --- | --- | --- |
55+
| `tests/playwright/integration/GameIndexPreviewManifestBroadScan.spec.mjs` | Preserved, explicit/on-request | All-game thumbnail coverage is isolated from the targeted integration lane. |
56+
| `npm run test:launch-smoke` | Preserved, explicit/on-request | Runtime launch smoke remains outside targeted Playwright lanes. |
57+
| `npm run test:launch-smoke:games` | Preserved, explicit/on-request | Broad game runtime launch smoke remains intentional. |
58+
| `npm run test:workspace-manager:games` | Preserved, explicit/on-request | Workspace/game runtime command remains outside default targeted validation. |
59+
| `npm run test:manifest-payload:games` | Preserved, explicit/on-request | Game manifest payload validation remains explicit. |
60+
| `npm run test:sample-standalone:data-flow` | Preserved, explicit/on-request | Sample-related runtime validation remains outside default samples/full smoke. |
61+
62+
## Before And After
63+
64+
| Area | Before | After |
65+
| --- | --- | --- |
66+
| Tool shortcuts | Two direct Playwright scripts bypassed the lane runner. | Tool runtime coverage is reached through `test:lane:tool-runtime`. |
67+
| Manifest source of truth | Some non-Playwright lanes could infer manifest tests from command arguments. | Every lane target used for validation is explicitly declared. |
68+
| Broad fallback | Command-derived target fallback could mask an incomplete lane manifest. | Incomplete manifests fail deterministically before runtime. |
69+
| Direct Playwright routing | Package scripts still exposed direct single-spec Playwright shortcuts. | No direct Playwright test scripts remain outside targeted lane scripts. |
70+
71+
## Accepted Technical Debt
72+
73+
| Item | Reason retained |
74+
| --- | --- |
75+
| `tests/playwright/tools/WorkspaceManagerV2.spec.mjs` | Still a large physical file, but it is isolated to the `workspace-contract` lane and was not touched by this cleanup. |
76+
| `scripts/run-targeted-test-lanes.mjs` | Still physically monolithic; this closeout removed fallback routing behavior without performing a broader runner module split. |
77+
| `scripts/audit-playwright-test-locations.mjs` | Broad static audit remains intentional and zero-browser. |
78+
| `tests/playwright/tools/CollisionInspectorV2.spec.mjs` | Retained as a targeted tool-runtime fixture pending any future ownership-specific split. |

‎docs/dev/reports/final_testing_architecture_report.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# PR_26146_043 Final Testing Architecture Report
2+
3+
Generated: 2026-05-26
4+
Status: PASS
5+
6+
## Final Lane Ownership Model
7+
8+
| Lane | Ownership | Authoritative scope |
9+
| --- | --- | --- |
10+
| `workspace-contract` | Workspace contract | Workspace Manager V2 launch, manifest handoff, toolState open/save, invalid payload handling, and lifecycle contracts. It is isolated from `tool-runtime` scheduling. |
11+
| `tool-runtime` | Tools | First-class tool runtime behavior for Asset Manager, Preview Generator, Collision Inspector, Palette Manager, and Tool Template. |
12+
| `game-runtime` | Games | Explicit game-owned Playwright behavior, currently Asteroids runtime and asset/visual checks. |
13+
| `engine-src` | Engine | Node tests for reusable engine, input, render, asset, and audio runtime modules. |
14+
| `integration` | Integration | Cross-surface handoffs such as game index manifest preview resolution and tools index registration. |
15+
| `samples` | Samples | Explicit samples lane only; not full samples smoke. |
16+
17+
Workspace contract assertions stay isolated from tool runtime assertions by lane routing: `tool-runtime` no longer reaches `WorkspaceManagerV2.spec.mjs`, and `workspace-contract` remains selected only by `--lane workspace-contract`, `test:lane:workspace-contract`, or the compatibility `test:workspace-v2` wrapper.
18+
19+
## Operational Architecture
20+
21+
| Principle | Final state |
22+
| --- | --- |
23+
| Targeted lanes are authoritative default | `npm run test:lanes` has safe no-lane mode; runtime starts only for explicit lanes or `--all`. |
24+
| Broad Workspace/full samples are explicit/on-request only | Workspace compatibility routes to `workspace-contract`; samples require the samples lane wrapper and `--include-samples`; full samples smoke was not run. |
25+
| Deterministic failures stop before runtime | Lane registration, runner preflight, scoped discovery, manifest input validation, warm-start validation, snapshot validation, lane compilation, and dependency gating precede runtime scheduling. |
26+
| Manifest/snapshot reuse remains authoritative | Selected affected lanes regenerate/reuse persistent manifests, warm starts, and lane snapshots before runtime. |
27+
| Zero-browser preflight remains authoritative | Zero-browser preflight ran first and passed before targeted lanes were launched. |
28+
| Broad discovery fallback is prohibited | Lane manifests now use only explicit `discoveryTargets`; command targets missing from those targets fail preflight. |
29+
30+
## Accepted Routing Layers
31+
32+
| Layer | Status | Notes |
33+
| --- | --- | --- |
34+
| `package.json` lane scripts | Accepted | `test:lane:*` scripts route through `scripts/run-targeted-test-lanes.mjs`. |
35+
| `test:workspace-v2` | Accepted compatibility wrapper | Preserved because existing workflows use it; it routes to `workspace-contract`. |
36+
| Static structure/audit scripts | Accepted explicit broad zero-browser layer | Preserved because they inspect broad Playwright structure without browser startup. |
37+
| Direct Playwright package scripts | Removed | The obsolete Asset Manager and Preview Generator shortcuts were removed. |
38+
| Runner lane manifest validation | Accepted authoritative layer | Explicit targets, manifests, warm starts, and snapshots define lane inputs. |
39+
40+
## Remaining Intentionally Expensive Tests
41+
42+
| Test or command | Owner | Execution policy |
43+
| --- | --- | --- |
44+
| `tests/playwright/tools/WorkspaceManagerV2.spec.mjs` | Workspace contract | Run only through `workspace-contract` selection. |
45+
| `tests/playwright/integration/GameIndexPreviewManifestBroadScan.spec.mjs` | Integration broad scan | Explicit/on-request only; outside targeted integration defaults. |
46+
| `npm run test:launch-smoke` | Runtime smoke | Explicit/on-request only. |
47+
| `npm run test:launch-smoke:games` | Game runtime smoke | Explicit/on-request only. |
48+
| `npm run test:workspace-manager:games` | Workspace/game runtime | Explicit/on-request only. |
49+
| `npm run test:manifest-payload:games` | Game manifest payload | Explicit/on-request only. |
50+
| `npm run test:sample-standalone:data-flow` | Samples/runtime | Explicit/on-request only. |
51+
| `npm run test:lane:samples` | Samples | Explicit samples lane only; not full samples smoke. |
52+
53+
## Remaining Accepted Technical Debt
54+
55+
| Item | Accepted debt |
56+
| --- | --- |
57+
| `tests/playwright/tools/WorkspaceManagerV2.spec.mjs` | Physical file remains large and under `tests/playwright/tools`; lane routing keeps it isolated from tool-runtime until a dedicated Workspace spec relocation/split is approved. |
58+
| `scripts/run-targeted-test-lanes.mjs` | Runner still owns many responsibilities physically; this PR only removed obsolete routing and fallback behavior. |
59+
| `scripts/audit-playwright-test-locations.mjs` | Static audit remains broad by design and zero-browser. |
60+
| `tests/helpers/playwrightV8CoverageReporter.mjs` | Coverage collection/reporting remains shared until more consumers justify splitting it. |
61+
| `tests/helpers/runtimeSceneLoaderHotReload.helpers.mjs` | Helper ownership remains future cleanup scope. |
62+
| `tests/playwright/tools/CollisionInspectorV2.spec.mjs` | Retained as current tool-runtime coverage with explicit game fixtures. |
63+
64+
## Before And After Cleanup Observations
65+
66+
| Area | Before | After |
67+
| --- | --- | --- |
68+
| Package runtime entry points | Direct tool Playwright shortcuts existed outside lane preflight. | Browser-backed tool validation enters through `tool-runtime`. |
69+
| Lane manifests | Engine/samples targets could be inferred from command args. | Engine/samples targets are explicit manifest inputs. |
70+
| Discovery fallback | Missing `discoveryTargets` could be hidden by command-target fallback. | Missing target declarations fail before runtime. |
71+
| Tool/Workspace isolation | Tool lane already skipped Workspace spec, but direct tool scripts still bypassed runner safeguards. | Tool runtime uses the lane runner only; Workspace remains a separate compatibility-routed lane. |

‎docs/dev/reports/incremental_validation_report.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Incremental Validation Report
22

3-
Generated: 2026-05-26T22:17:10.906Z
3+
Generated: 2026-05-26T22:55:37.503Z
44
Status: PASS
55

66
## Reuse Summary
@@ -18,7 +18,7 @@ Prevented fixture resolution passes: 0
1818

1919
| Lane | Decision | Invalidated By | Runtime Savings Observation |
2020
| --- | --- | --- | --- |
21-
| integration | INVALIDATED | Persistent manifest input hash changed for integration.; Persistent manifest hash changed for integration. | Manifest was regenerated or skipped; no reuse savings for this lane. |
21+
| engine-src | INVALIDATED | Persistent manifest lane definition hash changed for engine-src. | Manifest was regenerated or skipped; no reuse savings for this lane. |
2222

2323
## Invalidation Rules
2424

0 commit comments

Comments
 (0)