Clean samples shared barrel and utility patterns - PR_26140_078-clean-samples-shared-barrel-and-utils

DavidQ · DavidQ · commit 8107dbec3a12 · 2026-05-21T14:34:39.000-04:00
diff --git a/docs/dev/reports/samples_shared_cleanup_report.md b/docs/dev/reports/samples_shared_cleanup_report.md
@@ -0,0 +1,40 @@
+# PR_26140_078 Samples Shared Cleanup Report
+
+## Scope
+- Removed sample-level pass-through utility files in `samples/shared`:
+  - `debugConfigUtils.js`
+  - `networkDebugUtils.js`
+  - `numberUtils.js`
+  - `snapshotCloneUtils.js`
+- Removed the sample-level `worldSystems.js` barrel.
+- Updated sample imports to direct canonical owners:
+  - shared debug config from `/src/shared/debug/config.js`
+  - shared network debug helpers from `/src/shared/debug/network.js`
+  - shared number helpers from `/src/shared/number/numbers.js`
+  - shared snapshot clone helper from `/src/shared/runtime/snapshotClone.js`
+  - world system classes/functions from `samples/shared/worldSystems/*`
+- Updated `tests/samples/SamplesProgramCombinedPass.test.mjs` so its canonical samples/shared list no longer expects removed pass-through files.
+- Kept sample entry `index.js` files intact.
+- No sample JSON files were changed.
+- No schema files were changed.
+- No replacement pass-through files or shims were created.
+
+## Validation Notes
+- The first focused `SamplesProgramCombinedPass` run exposed an existing UTF-8 BOM in `samples/metadata/samples.index.metadata.json`. Sample JSON was not modified; the test reader now tolerates a leading BOM so the affected sample/shared boundary test can run.
+
+## Validation Results
+- PASS: targeted syntax validation for all changed existing `.js` and `.mjs` files using `node --check`.
+- PASS: targeted import-resolution validation confirmed import targets exist for 22 changed JS/MJS files.
+- PASS: `rg -n "worldSystems\.js|debugConfigUtils\.js|networkDebugUtils\.js|numberUtils\.js|snapshotCloneUtils\.js" samples tests --glob "*.js" --glob "*.mjs" --glob "*.html" --glob "*.css" --glob "!tests/results/**"` returned no active references.
+- PASS: `rg -n "^export .* from" samples/shared --glob "*.js"` returned no remaining samples/shared barrel-style re-exports.
+- PASS: `node --input-type=module -e "const m = await import('./tests/samples/SamplesProgramCombinedPass.test.mjs'); await m.run(); console.log('PASS SamplesProgramCombinedPass');"`.
+- PASS: `npm run test:workspace-v2` passed 59 tests.
+- PASS: JSON change audit found no changed `.json` files.
+
+## Full Samples Smoke Test
+- Skipped. This PR changes sample import plumbing and sample shared helper ownership; targeted syntax/import validation plus `SamplesProgramCombinedPass` covered the affected sample/shared paths without broadly changing sample loader behavior.
+
+## Manual Validation Notes
+- Confirm code search finds no active references to the removed sample shared helper names.
+- Confirm the phase 13 world-system samples still import their world-system components from `samples/shared/worldSystems/*`.
+- Confirm sample JSON remains untouched.
diff --git a/samples/phase-12/1205/main.js b/samples/phase-12/1205/main.js
@@ -8,7 +8,7 @@ import Engine from '/src/engine/core/Engine.js';
 import InputService from '/src/engine/input/InputService.js';
 import { Theme } from '/src/engine/theme/Theme.js';
 import { ThemeTokens } from '/src/engine/theme/ThemeTokens.js';
-import { resolveDebugConfig } from '../../shared/debugConfigUtils.js';
+import { resolveDebugConfig } from '/src/shared/debug/config.js';
 import { createSampleGameDevConsoleIntegration } from '../../../tools/dev/devConsoleIntegration.js';
 import MultiSystemDemoScene from './MultiSystemDemoScene.js';
 
@@ -49,4 +49,3 @@ engine.start();
 // Keep explicit palette JSON discoverable by audit tooling.
 const SAMPLE_1205_PALETTE_PATH = './sample.1205.palette.json';
 void SAMPLE_1205_PALETTE_PATH;
-
diff --git a/samples/phase-12/1208/ToolFormattedTilesParallaxScene.js b/samples/phase-12/1208/ToolFormattedTilesParallaxScene.js
@@ -12,7 +12,7 @@ import Camera2D from '/src/engine/camera/Camera2D.js';
 import { worldRectToScreen } from '/src/engine/camera/CameraSystem.js';
 import Tilemap from '/src/engine/tilemap/Tilemap.js';
 import { resolveRectVsTilemap } from '/src/engine/tilemap/TilemapCollision.js';
-import { isFiniteNumber } from '../../shared/numberUtils.js';
+import { isFiniteNumber } from '/src/shared/number/numbers.js';
 
 const theme = new Theme(ThemeTokens);
 const TILEMAP_PRESET_PATH = './sample.1208.tile-map-editor.json';
diff --git a/samples/phase-13/1303/AsteroidsWorldSystemsScene.js b/samples/phase-13/1303/AsteroidsWorldSystemsScene.js
@@ -8,8 +8,12 @@ import Scene from '/src/engine/scene/Scene.js';
 import { Theme } from '/src/engine/theme/Theme.js';
 import { ThemeTokens } from '/src/engine/theme/ThemeTokens.js';
 import { drawFrame, drawPanel } from '/src/engine/debug/DebugPanel.js';
-import { isFiniteNumber } from '../../shared/numberUtils.js';
-import { SpawnSystem, LifecycleSystem, WorldStateSystem, EventsSystem, distanceSq } from '/samples/shared/worldSystems.js';
+import { isFiniteNumber } from '/src/shared/number/numbers.js';
+import { SpawnSystem } from '/samples/shared/worldSystems/SpawnSystem.js';
+import { LifecycleSystem } from '/samples/shared/worldSystems/LifecycleSystem.js';
+import { WorldStateSystem } from '/samples/shared/worldSystems/WorldStateSystem.js';
+import { EventsSystem } from '/samples/shared/worldSystems/EventsSystem.js';
+import { distanceSq } from '/samples/shared/worldSystems/distanceSq.js';
 
 const theme = new Theme(ThemeTokens);
 const ASTEROID_MIN_SPEED = 20;
diff --git a/samples/phase-13/1309/SpaceInvadersWorldSystemsScene.js b/samples/phase-13/1309/SpaceInvadersWorldSystemsScene.js
@@ -8,7 +8,11 @@ import Scene from '/src/engine/scene/Scene.js';
 import { Theme } from '/src/engine/theme/Theme.js';
 import { ThemeTokens } from '/src/engine/theme/ThemeTokens.js';
 import { drawFrame, drawPanel } from '/src/engine/debug/DebugPanel.js';
-import { SpawnSystem, LifecycleSystem, WorldStateSystem, EventsSystem, distanceSq } from '/samples/shared/worldSystems.js';
+import { SpawnSystem } from '/samples/shared/worldSystems/SpawnSystem.js';
+import { LifecycleSystem } from '/samples/shared/worldSystems/LifecycleSystem.js';
+import { WorldStateSystem } from '/samples/shared/worldSystems/WorldStateSystem.js';
+import { EventsSystem } from '/samples/shared/worldSystems/EventsSystem.js';
+import { distanceSq } from '/samples/shared/worldSystems/distanceSq.js';
 
 const theme = new Theme(ThemeTokens);
 const INVADERS_VALIDATION_PRESETS = {
diff --git a/samples/phase-13/1313/PacmanLiteWorldSystemsScene.js b/samples/phase-13/1313/PacmanLiteWorldSystemsScene.js
@@ -8,7 +8,11 @@ import Scene from '/src/engine/scene/Scene.js';
 import { Theme } from '/src/engine/theme/Theme.js';
 import { ThemeTokens } from '/src/engine/theme/ThemeTokens.js';
 import { drawFrame, drawPanel } from '/src/engine/debug/DebugPanel.js';
-import { SpawnSystem, LifecycleSystem, WorldStateSystem, EventsSystem, distanceSq } from '/samples/shared/worldSystems.js';
+import { SpawnSystem } from '/samples/shared/worldSystems/SpawnSystem.js';
+import { LifecycleSystem } from '/samples/shared/worldSystems/LifecycleSystem.js';
+import { WorldStateSystem } from '/samples/shared/worldSystems/WorldStateSystem.js';
+import { EventsSystem } from '/samples/shared/worldSystems/EventsSystem.js';
+import { distanceSq } from '/samples/shared/worldSystems/distanceSq.js';
 
 const theme = new Theme(ThemeTokens);
 
diff --git a/samples/phase-13/1316/debug/networkSampleADebug.js b/samples/phase-13/1316/debug/networkSampleADebug.js
@@ -13,7 +13,7 @@ import {
   commandLinesForTrace,
   getCommandSnapshot,
   toNetworkSnapshot
-} from "../../../shared/networkDebugUtils.js";
+} from "/src/shared/debug/network.js";
 
 const NETWORK_SAMPLE_KEY = "networkSampleA";
 
diff --git a/samples/phase-13/1316/game/FakeLoopbackNetworkModel.js b/samples/phase-13/1316/game/FakeLoopbackNetworkModel.js
@@ -6,7 +6,7 @@ FakeLoopbackNetworkModel.js
 */
 
 import { clamp } from "../../../../src/shared/math/scalars.js";
-import { asPositiveNumber } from '../../../shared/numberUtils.js';
+import { asPositiveNumber } from '/src/shared/number/numbers.js';
 import { createLatencyModel } from "../../_shared/latencyModel.js";
 
 const MAX_TRACE_EVENTS = 80;
diff --git a/samples/phase-13/1316/game/NetworkSampleAScene.js b/samples/phase-13/1316/game/NetworkSampleAScene.js
@@ -7,7 +7,7 @@ NetworkSampleAScene.js
 import Scene from '/src/engine/scene/Scene.js';
 import FakeLoopbackNetworkModel from "./FakeLoopbackNetworkModel.js";
 import { clamp } from "/src/shared/math/scalars.js";
-import { asPositiveNumber } from "../../../shared/numberUtils.js";
+import { asPositiveNumber } from "/src/shared/number/numbers.js";
 
 const VIEW_WIDTH = 960;
 const VIEW_HEIGHT = 720;
diff --git a/samples/phase-13/1316/main.js b/samples/phase-13/1316/main.js
@@ -8,7 +8,7 @@ import Engine from "/src/engine/core/Engine.js";
 import InputService from "/src/engine/input/InputService.js";
 import { Theme } from "/src/engine/theme/Theme.js";
 import { ThemeTokens } from "/src/engine/theme/ThemeTokens.js";
-import { resolveDebugConfig } from "../../shared/debugConfigUtils.js";
+import { resolveDebugConfig } from "/src/shared/debug/config.js";
 import { createSampleGameDevConsoleIntegration } from "../../../tools/dev/devConsoleIntegration.js";
 import { createNetworkSampleADebugPlugin } from "./debug/networkSampleADebug.js";
 import NetworkSampleAScene from "./game/NetworkSampleAScene.js";
diff --git a/samples/phase-13/1316/server/networkSampleADashboardServer.mjs b/samples/phase-13/1316/server/networkSampleADashboardServer.mjs
@@ -9,7 +9,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import FakeLoopbackNetworkModel from "../game/FakeLoopbackNetworkModel.js";
-import { asPositiveInteger } from "../../../shared/numberUtils.js";
+import { asPositiveInteger } from "../../../../src/shared/number/numbers.js";
 
 const DEFAULT_HOST = "127.0.0.1";
 const DEFAULT_PORT = 4310;
diff --git a/samples/phase-13/1317/debug/networkSampleBDebug.js b/samples/phase-13/1317/debug/networkSampleBDebug.js
@@ -8,7 +8,7 @@ networkSampleBDebug.js
 import { createNetworkDebugPluginDefinition } from '/src/engine/debug/network/bootstrap/createNetworkDebugSurfaceIntegration.js';
 import { asArray } from "/src/shared/array/arrays.js";
 import { asObject } from "/src/shared/object/objects.js";
-import { asNumber, toNetworkSnapshot } from "../../../shared/networkDebugUtils.js";
+import { asNumber, toNetworkSnapshot } from "/src/shared/debug/network.js";
 
 const NETWORK_SAMPLE_KEY = "networkSampleB";
 
diff --git a/samples/phase-13/1317/game/FakeHostClientNetworkModel.js b/samples/phase-13/1317/game/FakeHostClientNetworkModel.js
@@ -6,7 +6,7 @@ FakeHostClientNetworkModel.js
 */
 import FakeLoopbackNetworkModel from "../../1316/game/FakeLoopbackNetworkModel.js";
 import { clamp } from "/src/shared/math/scalars.js";
-import { asPositiveNumber } from "../../../shared/numberUtils.js";
+import { asPositiveNumber } from "/src/shared/number/numbers.js";
 
 const MAX_TRACE_EVENTS = 120;
 
diff --git a/samples/phase-13/1317/game/NetworkSampleBScene.js b/samples/phase-13/1317/game/NetworkSampleBScene.js
@@ -6,7 +6,7 @@ NetworkSampleBScene.js
 */
 import Scene from '/src/engine/scene/Scene.js';
 import FakeHostClientNetworkModel from "./FakeHostClientNetworkModel.js";
-import { asPositiveNumber } from "../../../shared/numberUtils.js";
+import { asPositiveNumber } from "/src/shared/number/numbers.js";
 
 const VIEW_WIDTH = 960;
 const VIEW_HEIGHT = 720;
diff --git a/samples/phase-13/1317/main.js b/samples/phase-13/1317/main.js
@@ -8,7 +8,7 @@ import Engine from "/src/engine/core/Engine.js";
 import InputService from "/src/engine/input/InputService.js";
 import { Theme } from "/src/engine/theme/Theme.js";
 import { ThemeTokens } from "/src/engine/theme/ThemeTokens.js";
-import { resolveDebugConfig } from "../../shared/debugConfigUtils.js";
+import { resolveDebugConfig } from "/src/shared/debug/config.js";
 import { createSampleGameDevConsoleIntegration } from "../../../tools/dev/devConsoleIntegration.js";
 import { createNetworkSampleBDebugPlugin } from "./debug/networkSampleBDebug.js";
 import NetworkSampleBScene from "./game/NetworkSampleBScene.js";
diff --git a/samples/phase-13/1318/debug/networkSampleCDebug.js b/samples/phase-13/1318/debug/networkSampleCDebug.js
@@ -8,13 +8,13 @@ networkSampleCDebug.js
 import { createNetworkDebugPluginDefinition } from '/src/engine/debug/network/bootstrap/createNetworkDebugSurfaceIntegration.js';
 import { asArray } from "/src/shared/array/arrays.js";
 import { asObject } from "/src/shared/object/objects.js";
-import { isFiniteNumber } from "../../../shared/numberUtils.js";
+import { isFiniteNumber } from "/src/shared/number/numbers.js";
 import {
   asNumber,
   commandLinesForTrace,
   getCommandSnapshot,
   toNetworkSnapshot
-} from "../../../shared/networkDebugUtils.js";
+} from "/src/shared/debug/network.js";
 
 const NETWORK_SAMPLE_KEY = "networkSampleC";
 
diff --git a/samples/phase-13/1318/game/FakeDivergenceTraceNetworkModel.js b/samples/phase-13/1318/game/FakeDivergenceTraceNetworkModel.js
@@ -6,7 +6,7 @@ FakeDivergenceTraceNetworkModel.js
 */
 import ReconciliationLayerAdapter from "./ReconciliationLayerAdapter.js";
 import { clamp } from "/src/shared/math/scalars.js";
-import { asPositiveNumber, isFiniteNumber } from "../../../shared/numberUtils.js";
+import { asPositiveNumber, isFiniteNumber } from "/src/shared/number/numbers.js";
 
 const MAX_TRACE_EVENTS = 160;
 const MAX_TIMELINE_EVENTS = 80;
diff --git a/samples/phase-13/1318/game/NetworkSampleCScene.js b/samples/phase-13/1318/game/NetworkSampleCScene.js
@@ -6,7 +6,7 @@ NetworkSampleCScene.js
 */
 import Scene from '/src/engine/scene/Scene.js';
 import FakeDivergenceTraceNetworkModel from "./FakeDivergenceTraceNetworkModel.js";
-import { asPositiveNumber, isFiniteNumber } from "../../../shared/numberUtils.js";
+import { asPositiveNumber, isFiniteNumber } from "/src/shared/number/numbers.js";
 
 const VIEW_WIDTH = 960;
 const VIEW_HEIGHT = 720;
diff --git a/samples/phase-13/1318/game/ReconciliationLayerAdapter.js b/samples/phase-13/1318/game/ReconciliationLayerAdapter.js
@@ -5,8 +5,8 @@ David Quesenberry
 ReconciliationLayerAdapter.js
 */
 import StateTimelineBuffer from "./StateTimelineBuffer.js";
-import { asFiniteNumber, asPositiveInteger, isFiniteNumber } from "../../../shared/numberUtils.js";
-import { cloneSnapshot } from "../../../shared/snapshotCloneUtils.js";
+import { asFiniteNumber, asPositiveInteger, isFiniteNumber } from "/src/shared/number/numbers.js";
+import { cloneSnapshot } from "/src/shared/runtime/snapshotClone.js";
 
 const APPROVED_PUBLIC_EVENT_TYPES = new Set([
   "worldState.transition.applied",
diff --git a/samples/phase-13/1318/game/StateTimelineBuffer.js b/samples/phase-13/1318/game/StateTimelineBuffer.js
@@ -5,8 +5,8 @@ David Quesenberry
 StateTimelineBuffer.js
 */
 
-import { asPositiveInteger, isFiniteNumber } from "../../../shared/numberUtils.js";
-import { cloneSnapshot } from "../../../shared/snapshotCloneUtils.js";
+import { asPositiveInteger, isFiniteNumber } from "/src/shared/number/numbers.js";
+import { cloneSnapshot } from "/src/shared/runtime/snapshotClone.js";
 
 function normalizeFrameId(frameId) {
   const numeric = Number(frameId);
diff --git a/samples/phase-13/1318/main.js b/samples/phase-13/1318/main.js
@@ -8,7 +8,7 @@ import Engine from "/src/engine/core/Engine.js";
 import InputService from "/src/engine/input/InputService.js";
 import { Theme } from "/src/engine/theme/Theme.js";
 import { ThemeTokens } from "/src/engine/theme/ThemeTokens.js";
-import { resolveDebugConfig } from "../../shared/debugConfigUtils.js";
+import { resolveDebugConfig } from "/src/shared/debug/config.js";
 import { createSampleGameDevConsoleIntegration } from "../../../tools/dev/devConsoleIntegration.js";
 import { createNetworkSampleCDebugPlugin } from "./debug/networkSampleCDebug.js";
 import NetworkSampleCScene from "./game/NetworkSampleCScene.js";
diff --git a/samples/shared/debugConfigUtils.js b/samples/shared/debugConfigUtils.js
diff --git a/samples/shared/networkDebugUtils.js b/samples/shared/networkDebugUtils.js
diff --git a/samples/shared/numberUtils.js b/samples/shared/numberUtils.js
diff --git a/samples/shared/sampleDetailPageEnhancement.js b/samples/shared/sampleDetailPageEnhancement.js
@@ -1,4 +1,4 @@
-import { isFiniteNumber } from './numberUtils.js';
+import { isFiniteNumber } from '../../src/shared/number/numbers.js';
 import { getToolRegistry } from '/tools/toolRegistry.js';
 
 const METADATA_URL = '/samples/metadata/samples.index.metadata.json';
diff --git a/samples/shared/snapshotCloneUtils.js b/samples/shared/snapshotCloneUtils.js
diff --git a/samples/shared/worldSystems.js b/samples/shared/worldSystems.js
diff --git a/tests/samples/SamplesProgramCombinedPass.test.mjs b/tests/samples/SamplesProgramCombinedPass.test.mjs
@@ -16,7 +16,8 @@ const METADATA_ROOT = path.join(SAMPLES_ROOT, "metadata");
 const VALIDATION_ARTIFACTS_ROOT = path.join(REPO_ROOT, "tests", "validation");
 
 function readJson(filePath) {
-  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  const text = fs.readFileSync(filePath, "utf8");
+  return JSON.parse(text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text);
 }
 
 function getExpectedPhases() {
@@ -62,16 +63,11 @@ function assertPhaseGrouping() {
 function assertSamplesSharedBoundary() {
   const canonicalSharedFiles = [
     "README.md",
-    "debugConfigUtils.js",
     "lateSampleBootstrap.js",
-    "networkDebugUtils.js",
-    "numberUtils.js",
     "platformerHelpers.js",
     "sampleBaseLayout.css",
     "sampleDetailPageEnhancement.js",
-    "snapshotCloneUtils.js",
     "worldGameStateSystem.js",
-    "worldSystems.js",
   ];
 
   for (const fileName of canonicalSharedFiles) {
@@ -82,13 +78,9 @@ function assertSamplesSharedBoundary() {
   const compatibilityShimsDir = path.join(SAMPLES_ROOT, "_shared");
   if (fs.existsSync(compatibilityShimsDir)) {
     const compatibilityShims = [
-      "debugConfigUtils.js",
       "lateSampleBootstrap.js",
-      "networkDebugUtils.js",
-      "numberUtils.js",
       "platformerHelpers.js",
       "sampleDetailPageEnhancement.js",
-      "snapshotCloneUtils.js",
     ];
     for (const fileName of compatibilityShims) {
       const shimPath = path.join(compatibilityShimsDir, fileName);
