Normalize shared folder layout by domain - PR_26140_063-normalize-shared-folder-layout

Author: DavidQ

docs/dev/reports/shared_folder_layout_normalization_report.md

@@ -0,0 +1,56 @@
+# PR_26140_063 Shared Folder Layout Normalization
+
+## Summary
+- Moved the remaining root-level shared helper modules into explicit domain folders under `src/shared/`.
+- Kept imports pointing directly at the canonical domain files instead of creating root-level compatibility shims.
+- Removed the object helper's cross-domain `asArray` re-export and split affected imports so array helpers come from `src/shared/array/arrays.js`.
+- Refreshed the shared extraction guard baseline after the canonical path moves.
+- Preserved behavior; this PR is layout/import normalization only.
+
+## Layout Decisions
+- Array helpers: `src/shared/array/arrays.js`.
+- Object helpers: `src/shared/object/objects.js`.
+- JSON clone helpers: `src/shared/json/clone.js`.
+- String helpers: `src/shared/string/strings.js`, `textWrap.js`, `commandText.js`, `fuzzyMatchScore.js`, and `stringifyValue.js`.
+- Math/spatial helpers: `src/shared/math/scalars.js`, `geometry.js`, `directions.js`, `vectorMath.js`, `vectorNormalize.js`, and `numberNormalization.js`.
+- Debug helpers: `src/shared/debug/config.js`, `network.js`, and `noopDevConsoleIntegration.js`.
+- Runtime helpers: `src/shared/runtime/registry.js` and `snapshotClone.js`.
+- Game-generic helpers: `src/shared/game/highScores.js` and `initialsEntry.js`.
+- Validation helper: `src/shared/validation/invariant.js`.
+
+## Guardrail Checks
+- Confirmed `src/shared/` root contains only the existing `index.js` namespace barrel.
+- Confirmed no active import/export statements reference `shared/utils/`.
+- Confirmed no active import/export statements reference the relocated dangling root shared files such as `shared/arrays.js`, `shared/objects.js`, `shared/json.js`, or `shared/strings.js`.
+- Confirmed no `../` export-from chains exist inside `src/shared/**/*.js`.
+- Confirmed no `Utils`/`utils` naming remains in `src/shared/**/*.js`.
+- No root shared compatibility re-export shims were created.
+- No sample JSON files were modified.
+
+## Validation
+- PASS: `node tools/dev/checkSharedExtractionGuard.mjs --update-baseline`.
+- PASS: `node tools/dev/checkSharedExtractionGuard.mjs`.
+- PASS: root shared file check confirmed only `src/shared/index.js` remains at root.
+- PASS: no active imports from `shared/utils` or relocated root shared files.
+- PASS: no `../` export-from chains in `src/shared`.
+- PASS: no `Utils`/`utils` naming in `src/shared/**/*.js`.
+- PASS: changed-file syntax validation for 135 JavaScript files.
+- PASS: changed-file import target validation for 135 JavaScript files.
+- PASS: `node tools/dev/checkSharedExtractionGuard.selftest.mjs`.
+- PASS: `node tests/shared/SharedFoundationCombinedPass.test.mjs`.
+- PASS: `node tests/shared/SharedNumberStringIdCloseout.test.mjs`.
+- PASS: `npm run test:workspace-v2` (59 passed).
+- PASS: `git diff --check`.
+
+## Coverage Guardrail
+- `npm run test:workspace-v2` regenerated advisory Playwright V8 coverage reports.
+- `docs/dev/reports/coverage_changed_js_guardrail.txt` lists changed runtime JavaScript files with covered entries where Workspace V2 exercised them and WARN details for files not collected by that Playwright run.
+- Coverage is advisory and missing changed runtime files are WARN, not FAIL, per project instructions.
+
+## Full Samples Smoke Test
+- Skipped as requested. This PR changes shared module layout/imports and is covered by targeted syntax/import checks plus Workspace V2; sample JSON remains out of scope.
+
+## Manual Validation
+- Open Workspace Manager V2 and select the repo.
+- Launch Object Vector Studio V2, Palette Manager V2, Asset Manager V2, and Asteroids from Workspace Manager V2.
+- Expected: tools and Asteroids launch without module resolution errors, and behavior matches the pre-layout-change state.

games/Asteroids/entities/Bullet.js

@@ -6,7 +6,7 @@ Bullet.js
 */
 import { wrap } from '/src/shared/math/scalars.js';
 import { transformCollisionPoints } from '/src/engine/collision/index.js';
-import { normalizePoints } from '/src/shared/geometry.js';
+import { normalizePoints } from '/src/shared/math/geometry.js';
 
 export default class Bullet {
   constructor(x, y, vx, vy, life = 1.1, { angle = 0, collisionPoints = [] } = {}) {

games/Asteroids/entities/Ship.js

@@ -6,7 +6,7 @@ Ship.js
 */
 import { wrap } from '/src/shared/math/scalars.js';
 import { transformCollisionPoints } from '/src/engine/collision/index.js';
-import { normalizePoints } from '/src/shared/geometry.js';
+import { normalizePoints } from '/src/shared/math/geometry.js';
 
 export default class Ship {
   constructor(x, y, { collisionPoints = [] } = {}) {

games/Asteroids/entities/Ufo.js

@@ -6,7 +6,7 @@ Ufo.js
 */
 import Bullet from './Bullet.js';
 import { distance, randomRange } from '/src/shared/math/scalars.js';
-import { normalizePoints } from '/src/shared/geometry.js';
+import { normalizePoints } from '/src/shared/math/geometry.js';
 import { transformCollisionPoints } from '/src/engine/collision/index.js';
 
 const UFO_PROFILES = {

games/Asteroids/game/asteroidObjectGeometry.js

@@ -2,8 +2,8 @@ import {
   ASTEROIDS_ASTEROID_SIZE_OBJECT_IDS,
 } from './asteroidsObjectGeometryManifest.js';
 import { getObjectVectorCollisionOutlinePoints } from '/src/engine/collision/index.js';
-import { asArray } from '/src/shared/arrays.js';
-import { centerPoints, maxRadius } from '/src/shared/geometry.js';
+import { asArray } from '/src/shared/array/arrays.js';
+import { centerPoints, maxRadius } from '/src/shared/math/geometry.js';
 
 const ASTEROID_SIZE_LABELS = Object.freeze({
   1: 'SML',

games/Asteroids/game/asteroidsObjectGeometryManifest.js

@@ -1,6 +1,6 @@
 import { getObjectVectorCollisionOutlinePoints } from '/src/engine/collision/index.js';
 import { isRecord } from '/src/shared/types/typeGuards.js';
-import { deepClone } from '/src/shared/json.js';
+import { deepClone } from '/src/shared/json/clone.js';
 
 const ASTEROIDS_OBJECT_VECTOR_TOOL_KEY = 'object-vector-studio-v2';
 const OBJECT_VECTOR_PAYLOAD_KEYS = new Set(['version', 'toolId', 'name', 'objects']);

games/Asteroids/index.js

@@ -6,8 +6,8 @@ import Engine from "/src/engine/core/Engine.js";
 import { InputService } from "/src/engine/input/index.js";
 import { ObjectVectorRuntimeAssetService } from "/src/engine/rendering/index.js";
 import { Theme, ThemeTokens } from "/src/engine/theme/index.js";
-import { resolveDebugConfig } from "/src/shared/debugConfig.js";
-import { createNoopDevConsoleIntegration } from "/src/shared/noopDevConsoleIntegration.js";
+import { resolveDebugConfig } from "/src/shared/debug/config.js";
+import { createNoopDevConsoleIntegration } from "/src/shared/debug/noopDevConsoleIntegration.js";
 import { asPositiveInteger } from "/src/shared/number/index.js";
 import AsteroidsGameScene from "./game/AsteroidsGameScene.js";
 import { loadAsteroidsObjectGeometryFromManifest } from "./game/asteroidsObjectGeometryManifest.js";

games/Asteroids/systems/AsteroidsHighScoreService.js

@@ -10,7 +10,7 @@ import {
   sanitizeInitials,
   sanitizeRow,
   sortRows,
-} from '/src/shared/highScores.js';
+} from '/src/shared/game/highScores.js';
 
 const DEFAULT_KEY = 'toolboxaid:games:asteroids:high-score-table';
 const DEFAULT_ROWS = [

games/Asteroids/systems/AsteroidsInitialsEntry.js

@@ -4,7 +4,7 @@ David Quesenberry
 03/25/2026
 AsteroidsInitialsEntry.js
 */
-import { codeToLetter } from '/src/shared/initialsEntry.js';
+import { codeToLetter } from '/src/shared/game/initialsEntry.js';
 
 const KEY_CODES = Array.from({ length: 26 }).map((_, index) => `Key${String.fromCharCode(65 + index)}`);
 

games/Asteroids/systems/ShipDebrisSystem.js

@@ -5,7 +5,7 @@ David Quesenberry
 ShipDebrisSystem.js
 */
 import { randomRange } from '/src/shared/math/scalars.js';
-import { normalizePoints } from '/src/shared/geometry.js';
+import { normalizePoints } from '/src/shared/math/geometry.js';
 
 function createShipSegments(points) {
   const normalized = normalizePoints(points);