Deep normalize shared method domains - PR_26140_064-deep-normalize-shared-method-domains

Author: DavidQ

docs/dev/reports/shared_method_domain_audit_report.md

@@ -0,0 +1,44 @@
+# PR_26140_064 Deep Normalize Shared Method Domains
+
+## Summary
+- Moved JSON read/write helpers from `src/shared/io/jsonIO.js` to `src/shared/json/jsonIO.js`.
+- Moved shared record/object normalization into `src/shared/object/objects.js`.
+- Moved shared array normalization into `src/shared/array/arrays.js` and record-array normalization into `src/shared/array/recordArrays.js`.
+- Moved `isRecord` consumers to the object domain and `isNonEmptyString` to the string domain.
+- Removed unused pass-through shared files for `src/shared/index.js`, `src/shared/io/index.js`, `src/shared/data/index.js`, `src/shared/data/normalization.js`, and `src/shared/types/index.js`.
+
+## Domain Audit Decisions
+- `safeJsonParse`, `safeJsonStringify`, `cloneJsonData`: JSON serialization/deserialization helpers; canonical file is now `src/shared/json/jsonIO.js`.
+- `normalizeRecord`: object/record coercion helper; canonical file is now `src/shared/object/objects.js`.
+- `normalizeArray`: array coercion helper; canonical file is now `src/shared/array/arrays.js`.
+- `normalizeRecordArray`: array-of-records helper; canonical file is now `src/shared/array/recordArrays.js`.
+- `isRecord`: object/record predicate; canonical file is now `src/shared/object/objects.js`.
+- `isNonEmptyString`: string predicate; canonical file is now `src/shared/string/strings.js`.
+- `isFunction` and `isBoolean`: retained in `src/shared/types/typeGuards.js` because they are primitive type predicates and not array/object/string/json methods.
+- Existing state, contract, debug, game, runtime, validation, math, number, id, and geometry methods were reviewed and left in their current domain folders where the file domain already matched the exported behavior.
+
+## Guardrail Checks
+- `src/shared/io/jsonIO.js` no longer exists.
+- `src/shared/data/normalization.js` no longer exists, so array methods do not remain there.
+- No active imports or references remain for moved `shared/io`, `shared/data`, root `shared/index`, or `types/index` paths outside excluded historical/report areas.
+- No root-level shared pass-through export file remains at `src/shared/index.js`.
+- No `../` export chains exist under `src/shared/**/*.js`.
+- No sample JSON files were modified.
+
+## Validation
+- PASS: targeted syntax validation for 14 changed JavaScript files, including untracked files.
+- PASS: targeted import-target validation for 14 changed JavaScript files, including untracked files.
+- PASS: `npm run test:workspace-v2` with 59 passed.
+- PASS: stale moved-path scan for active JavaScript.
+- PASS: `git diff --check` completed with only Git CRLF normalization warnings for existing files.
+
+## Coverage Guardrail
+- Playwright generated the existing advisory V8 coverage report. Missing/low coverage entries remain WARN-only per project instructions.
+
+## Full Samples Smoke Test
+- Skipped. This PR only changes shared import/domain placement and the requested validation covered syntax/import correctness plus Workspace V2 behavior.
+
+## Manual Validation
+1. Review `docs/dev/reports/codex_review.diff` for the shared domain moves and import updates.
+2. Confirm `src/shared/json/jsonIO.js`, `src/shared/object/objects.js`, and `src/shared/array/recordArrays.js` are the canonical locations for the moved methods.
+3. Confirm Workspace Manager V2 still launches and runs through the tested tool flows.

games/Asteroids/game/asteroidsObjectGeometryManifest.js

@@ -1,5 +1,5 @@
 import { getObjectVectorCollisionOutlinePoints } from '/src/engine/collision/index.js';
-import { isRecord } from '/src/shared/types/typeGuards.js';
+import { isRecord } from '/src/shared/object/objects.js';
 import { deepClone } from '/src/shared/json/clone.js';
 
 const ASTEROIDS_OBJECT_VECTOR_TOOL_KEY = 'object-vector-studio-v2';

samples/phase-17/shared/overlayGameplayRuntime.js

@@ -10,7 +10,7 @@ import {
   LEVEL17_OVERLAY_CYCLE_KEY,
 } from '/samples/phase-17/shared/overlayCycleInput.js';
 import { normalizeOverlayRuntimeExtensions } from '/samples/phase-17/shared/overlayRuntimeExtensionNormalization.js';
-import { cloneJsonData, safeJsonParse, safeJsonStringify } from '/src/shared/io/index.js';
+import { cloneJsonData, safeJsonParse, safeJsonStringify } from '/src/shared/json/jsonIO.js';
 import { asFiniteNumber } from '/src/shared/number/index.js';
 
 const overlayRuntimePreferenceMemoryStore = new Map();

src/engine/collision/objectVector.js

@@ -13,7 +13,7 @@ import {
   normalizeObjectVectorTransform,
   transformRuntimeOrientedPoints,
 } from '../rendering/OrientationTransform.js';
-import { isRecord } from '../../shared/types/typeGuards.js';
+import { isRecord } from '../../shared/object/objects.js';
 import { deepClone } from '../../shared/json/clone.js';
 import { asFiniteNumber } from '../../shared/number/index.js';
 

src/engine/rendering/ObjectVectorTransformService.js

@@ -1,4 +1,4 @@
-import { isRecord } from "../../shared/types/typeGuards.js";
+import { isRecord } from "../../shared/object/objects.js";
 import { asFiniteNumber } from "../../shared/number/index.js";
 
 const DEGREES_PER_RADIAN = 180 / Math.PI;

src/shared/array/arrays.js

@@ -4,6 +4,10 @@ export function ensureArray(value) {
   return Array.isArray(value) ? value : [];
 }
 
+export function normalizeArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
 export function asArray(value) {
   return ensureArray(value);
 }

src/shared/array/recordArrays.js

@@ -0,0 +1,6 @@
+import { normalizeArray } from "./arrays.js";
+import { normalizeRecord } from "../object/objects.js";
+
+export function normalizeRecordArray(value) {
+  return normalizeArray(value).map((entry) => normalizeRecord(entry));
+}