Extract high-confidence duplicate helpers into shared utility modules - PR_26139_030-shared-utils-duplicate-method-extraction

DavidQ · DavidQ · commit ef677f3d44ab · 2026-05-19T22:18:40.000-04:00
diff --git a/docs/dev/reports/PR_26139_030-shared-utils-duplicate-method-extraction_report.md b/docs/dev/reports/PR_26139_030-shared-utils-duplicate-method-extraction_report.md
@@ -0,0 +1,48 @@
+# PR_26139_030 Shared Utils Duplicate Method Extraction Report
+
+## Scope
+
+- Read `docs/dev/PROJECT_INSTRUCTIONS.md` and `tmp/dups.txt`.
+- Treated `tmp/dups.txt` as broad duplicate-input signal only; ignored vendor, bundled, Playwright/test-runner, generated, and unrelated tool noise.
+- Limited extraction to high-confidence helpers whose behavior matched current callers.
+
+## Changes
+
+- Added shared geometry helpers in `src/shared/utils/geometryUtils.js`:
+  - `normalizePoints`
+  - `centerPoints`
+  - `maxRadius`
+- Added exact JSON-clone helper `deepClone` in `src/shared/utils/jsonUtils.js`.
+  - Preserved existing `cloneJson` nullish behavior by delegating non-nullish values to `deepClone`.
+- Reused existing `asArray` from `src/shared/utils/arrayUtils.js`.
+- Reused existing `isRecord` / `isPlainObject` shared guards where local semantics matched.
+- Replaced duplicate local helpers in:
+  - Asteroids ship, bullet, UFO, ship debris, and asteroid profile geometry modules.
+  - Asteroids manifest object geometry loader.
+  - Shared Object Vector collision path.
+  - Collision Inspector V2 constants.
+  - Object Vector Studio V2 app/schema service.
+
+## Deliberate Non-Changes
+
+- Did not merge `src/engine/collision/objectVector.js` local `normalizePoints`; it preserves non-finite point entries via fallback conversion, while the extracted Asteroids helper filters non-finite points.
+- Did not normalize broad `sanitizeText`, `normalizeText`, `clamp`, or `toFiniteNumber` duplicates because `tmp/dups.txt` includes many unrelated or semantically different active/tool/vendor definitions.
+- Did not touch deprecated Vector Map Editor, Playwright internals, CodeMirror/bundled code, generated artifacts, or test-runner code.
+
+## Validation
+
+- PASS `npm run build:manifest`
+- PASS `node tests/games/AsteroidsValidation.test.mjs`
+- PASS `node tests/games/AsteroidsPresentation.test.mjs`
+- PASS `node tests/tools/ObjectVectorStudioV2DeleteCleanup.test.mjs`
+- PASS `npx playwright test tests/playwright/tools/AsteroidsGameSceneCleanup.spec.mjs --project=playwright --workers=1 --reporter=list`
+- PASS `npx playwright test tests/playwright/tools/ObjectVectorStudioV2FirstClassToolStarter.spec.mjs --project=playwright --workers=1 --reporter=list`
+- PASS `npx playwright test tests/playwright/tools/CollisionInspectorV2.spec.mjs --project=playwright --workers=1 --reporter=list`
+- PASS `npx playwright test tests/playwright/tools/AsteroidsGameSceneCleanup.spec.mjs tests/playwright/tools/ObjectVectorStudioV2FirstClassToolStarter.spec.mjs tests/playwright/tools/CollisionInspectorV2.spec.mjs --project=playwright --workers=1 --reporter=list`
+- PASS vendor/generated modification check: no `vendor`, bundled, minified, generated, Playwright-report, or test-results paths were modified.
+- Advisory Playwright V8 coverage refreshed in `docs/dev/reports/playwright_v8_coverage_report.txt` and `docs/dev/reports/coverage_changed_js_guardrail.txt`.
+
+## Notes
+
+- `npm run build:manifest` generated `docs/build/sample-manifest.json`; it was removed after validation because it is a generated build artifact outside this PR scope.
+- Full samples smoke test was skipped; this PR is a scoped helper extraction and requested targeted Asteroids/Object Vector/Collision Inspector validation instead.
diff --git a/dupes_called.txt b/dupes_called.txt
diff --git a/games/Asteroids/entities/Bullet.js b/games/Asteroids/entities/Bullet.js
@@ -6,15 +6,7 @@ Bullet.js
 */
 import { wrap } from '../utils/math.js';
 import { transformCollisionPoints } from '../../../src/engine/collision/index.js';
-
-function normalizePoints(points) {
-  return Array.isArray(points)
-    ? points.map((point) => ({
-      x: Number(point?.x ?? 0),
-      y: Number(point?.y ?? 0),
-    })).filter((point) => Number.isFinite(point.x) && Number.isFinite(point.y))
-    : [];
-}
+import { normalizePoints } from '../../../src/shared/utils/geometryUtils.js';
 
 export default class Bullet {
   constructor(x, y, vx, vy, life = 1.1, { angle = 0, collisionPoints = [] } = {}) {
diff --git a/games/Asteroids/entities/Ship.js b/games/Asteroids/entities/Ship.js
@@ -6,15 +6,7 @@ Ship.js
 */
 import { wrap } from '../utils/math.js';
 import { transformCollisionPoints } from '../../../src/engine/collision/index.js';
-
-function normalizePoints(points) {
-  return Array.isArray(points)
-    ? points.map((point) => ({
-      x: Number(point?.x ?? 0),
-      y: Number(point?.y ?? 0),
-    })).filter((point) => Number.isFinite(point.x) && Number.isFinite(point.y))
-    : [];
-}
+import { normalizePoints } from '../../../src/shared/utils/geometryUtils.js';
 
 export default class Ship {
   constructor(x, y, { collisionPoints = [] } = {}) {
diff --git a/games/Asteroids/entities/Ufo.js b/games/Asteroids/entities/Ufo.js
@@ -6,6 +6,7 @@ Ufo.js
 */
 import Bullet from './Bullet.js';
 import { distance } from '../../../src/shared/utils/mathUtils.js';
+import { normalizePoints } from '../../../src/shared/utils/geometryUtils.js';
 import { transformCollisionPoints } from '../../../src/engine/collision/index.js';
 import { randomRange } from '../utils/math.js';
 
@@ -26,15 +27,6 @@ const UFO_PROFILES = {
   },
 };
 
-function normalizePoints(points) {
-  return Array.isArray(points)
-    ? points.map((point) => ({
-      x: Number(point?.x ?? 0),
-      y: Number(point?.y ?? 0),
-    })).filter((point) => Number.isFinite(point.x) && Number.isFinite(point.y))
-    : [];
-}
-
 export default class Ufo {
   constructor(bounds, type = 'large', level = 1, rng = Math.random, { bulletCollisionPoints = [], collisionPoints = [] } = {}) {
     this.bounds = bounds;
diff --git a/games/Asteroids/game/asteroidObjectGeometry.js b/games/Asteroids/game/asteroidObjectGeometry.js
@@ -2,38 +2,15 @@ import {
   ASTEROIDS_ASTEROID_SIZE_OBJECT_IDS,
 } from './asteroidsObjectGeometryManifest.js';
 import { getObjectVectorCollisionOutlinePoints } from '../../../src/engine/collision/index.js';
+import { asArray } from '../../../src/shared/utils/arrayUtils.js';
+import { centerPoints, maxRadius } from '../../../src/shared/utils/geometryUtils.js';
 
 const ASTEROID_SIZE_LABELS = Object.freeze({
   1: 'SML',
   2: 'MED',
   3: 'LRG',
 });
 
-function asArray(value) {
-  return Array.isArray(value) ? value : [];
-}
-
-function centerPoints(points) {
-  if (!points.length) {
-    return [];
-  }
-  const xs = points.map(({ x }) => x);
-  const ys = points.map(({ y }) => y);
-  const centerX = (Math.min(...xs) + Math.max(...xs)) / 2;
-  const centerY = (Math.min(...ys) + Math.max(...ys)) / 2;
-  return points.map(({ x, y }) => ({
-    x: x - centerX,
-    y: y - centerY,
-  }));
-}
-
-function maxRadius(points) {
-  if (!points.length) {
-    return 0;
-  }
-  return Math.max(...points.map(({ x, y }) => Math.sqrt(x * x + y * y)));
-}
-
 function logProfileFailure(logger, message, details = {}) {
   if (!logger) {
     return;
diff --git a/games/Asteroids/game/asteroidsObjectGeometryManifest.js b/games/Asteroids/game/asteroidsObjectGeometryManifest.js
@@ -1,4 +1,6 @@
 import { getObjectVectorCollisionOutlinePoints } from '../../../src/engine/collision/index.js';
+import { isRecord } from '../../../src/shared/types/typeGuards.js';
+import { deepClone as clone } from '../../../src/shared/utils/jsonUtils.js';
 
 const ASTEROIDS_OBJECT_VECTOR_TOOL_KEY = 'object-vector-studio-v2';
 const OBJECT_VECTOR_PAYLOAD_KEYS = new Set(['version', 'toolId', 'name', 'objects']);
@@ -34,14 +36,6 @@ export const ASTEROIDS_UFO_TYPE_OBJECT_IDS = Object.freeze({
   small: ASTEROIDS_OBJECT_GEOMETRY_IDS.ufoSmall,
 });
 
-function isRecord(value) {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
-
-function clone(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-
 function normalizeString(value) {
   return String(value || '').trim();
 }
diff --git a/games/Asteroids/systems/ShipDebrisSystem.js b/games/Asteroids/systems/ShipDebrisSystem.js
@@ -5,15 +5,7 @@ David Quesenberry
 ShipDebrisSystem.js
 */
 import { randomRange } from '../utils/math.js';
-
-function normalizePoints(points) {
-  return Array.isArray(points)
-    ? points.map((point) => ({
-      x: Number(point?.x ?? 0),
-      y: Number(point?.y ?? 0),
-    })).filter((point) => Number.isFinite(point.x) && Number.isFinite(point.y))
-    : [];
-}
+import { normalizePoints } from '../../../src/shared/utils/geometryUtils.js';
 
 function createShipSegments(points) {
   const normalized = normalizePoints(points);
diff --git a/scripts/PS/find-duplicate-methods/dupes_called.ps1 b/scripts/PS/find-duplicate-methods/dupes_called.ps1
@@ -10,18 +10,22 @@
 # Get the root path (3 levels up)
 $rootPath = Resolve-Path "$PSScriptRoot\..\..\..\"
 
-Get-ChildItem -Path $rootPath -Recurse -Filter *.js | 
-    Select-String -Pattern "function\s+[a-zA-Z0-9_]*\(", "[a-zA-Z0-9_]*\s*=\s*function", "[a-zA-Z0-9_]*:\s*function" |
-    Group-Object Line | 
-    Where-Object { $_.Count -gt 1 } | 
+Get-ChildItem -Path $rootPath -Recurse -Filter *.js -File |
+    Where-Object {
+        $_.FullName -notmatch '\\node_modules\\'
+    } |
+    Select-String `
+        -Pattern "function\s+[a-zA-Z0-9_]*\(", "[a-zA-Z0-9_]*\s*=\s*function", "[a-zA-Z0-9_]*:\s*function" |
+    Group-Object Line |
+    Where-Object { $_.Count -gt 1 } |
     ForEach-Object {
         "($($_.Count)) Duplicate line: $($_.Name.Trim())"
-        
+
         $_.Group | ForEach-Object {
             # Replace the absolute root path with a single backslash
             $relativePath = $_.Path -replace [regex]::Escape($rootPath), ""
             "   -> Line $($_.LineNumber): \$relativePath"
         }
-        "" 
-    }
 
+        ""
+    }
diff --git a/src/engine/collision/objectVector.js b/src/engine/collision/objectVector.js
@@ -13,6 +13,8 @@ import {
   normalizeObjectVectorTransform,
   transformRuntimeOrientedPoints,
 } from '../rendering/OrientationTransform.js';
+import { isRecord } from '../../shared/types/typeGuards.js';
+import { deepClone as clone } from '../../shared/utils/jsonUtils.js';
 
 export const OBJECT_VECTOR_COLLISION_ENGINE_PATH = 'src/engine/collision/objectVector.js';
 export const OBJECT_VECTOR_COLLISION_MODES = Object.freeze(['bounds', 'vector', 'pixel-sprite', 'hybrid']);
@@ -30,14 +32,6 @@ const MODE_ALIASES = Object.freeze({
 const POLYGON_SAMPLE_COUNT = 28;
 const DEFAULT_MASK_CELL_SIZE = 4;
 
-function isRecord(value) {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
-
-function clone(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-
 function numberValue(value, fallback = 0) {
   const parsed = Number(value);
   return Number.isNaN(parsed) || Math.abs(parsed) === Infinity ? fallback : parsed;
diff --git a/src/shared/utils/geometryUtils.js b/src/shared/utils/geometryUtils.js
@@ -27,3 +27,33 @@ export function getCenteredRect(containerRect, width, height, verticalBias = 0.5
     h: height
   };
 }
+
+export function normalizePoints(points) {
+  return Array.isArray(points)
+    ? points.map((point) => ({
+      x: Number(point?.x ?? 0),
+      y: Number(point?.y ?? 0),
+    })).filter((point) => Number.isFinite(point.x) && Number.isFinite(point.y))
+    : [];
+}
+
+export function centerPoints(points) {
+  if (!points.length) {
+    return [];
+  }
+  const xs = points.map(({ x }) => x);
+  const ys = points.map(({ y }) => y);
+  const centerX = (Math.min(...xs) + Math.max(...xs)) / 2;
+  const centerY = (Math.min(...ys) + Math.max(...ys)) / 2;
+  return points.map(({ x, y }) => ({
+    x: x - centerX,
+    y: y - centerY,
+  }));
+}
+
+export function maxRadius(points) {
+  if (!points.length) {
+    return 0;
+  }
+  return Math.max(...points.map(({ x, y }) => Math.sqrt(x * x + y * y)));
+}
diff --git a/src/shared/utils/index.js b/src/shared/utils/index.js
@@ -23,12 +23,12 @@ export {
 } from "../id/index.js";
 export { isFiniteNumber, toFiniteNumber, asFiniteNumber, asPositiveInteger, asPositiveNumber } from "../number/index.js";
 export { isObject, isPlainObject, asObject, asArray as asObjectArray } from "./objectUtils.js";
-export { cloneJson } from "./jsonUtils.js";
+export { cloneJson, deepClone } from "./jsonUtils.js";
 export { stringifyValue } from "./stringifyValueUtils.js";
 export { oppositeCardinalDirection } from "./directionUtils.js";
 export { wrapTextByCharacterCount } from "./textWrapUtils.js";
 export { clamp, distance, wrap, randomRange } from "./mathUtils.js";
-export { pointInRect, xyInRect, getCenteredRect } from "./geometryUtils.js";
+export { pointInRect, xyInRect, getCenteredRect, normalizePoints, centerPoints, maxRadius } from "./geometryUtils.js";
 export { invariant } from "./invariantUtils.js";
 export { normalizeCommandText } from "./normalizeCommandTextUtils.js";
 export { fuzzyMatchScore } from "./fuzzyMatchScore.js";
diff --git a/src/shared/utils/jsonUtils.js b/src/shared/utils/jsonUtils.js
@@ -1,3 +1,7 @@
 export function cloneJson(value) {
-  return value == null ? value : JSON.parse(JSON.stringify(value));
-}
+  return value == null ? value : deepClone(value);
+}
+
+export function deepClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
diff --git a/tools/collision-inspector-v2/js/constants.js b/tools/collision-inspector-v2/js/constants.js
@@ -1,12 +1,10 @@
+export { deepClone as clone } from "../../../src/shared/utils/jsonUtils.js";
+
 export const OBJECT_LABELS = Object.freeze({
   a: "Object A",
   b: "Object B"
 });
 
-export function clone(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-
 export function labelForObject(object) {
   return `${object?.name || "Object"} (${object?.id || "unknown"})`;
 }
diff --git a/tools/object-vector-studio-v2/js/ToolStarterApp.js b/tools/object-vector-studio-v2/js/ToolStarterApp.js
@@ -11,6 +11,7 @@ import {
   transformObjectVectorShapePoint,
   ObjectVectorRuntimeAssetService
 } from "../../../src/engine/rendering/index.js";
+import { isPlainObject } from "../../../src/shared/utils/objectUtils.js";
 
 const WORKSPACE_TOOL_SESSION_KEY = "workspace.tools.object-vector-studio-v2";
 const WORKSPACE_PALETTE_SESSION_KEY = "workspace.tools.palette-manager-v2";
@@ -310,10 +311,6 @@ function payloadGameSlugFromName(name) {
   return slug || "game";
 }
 
-function isPlainObject(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
 function sortedShapes(object) {
   return [...(object?.shapes || [])].sort((left, right) => left.order - right.order);
 }
diff --git a/tools/object-vector-studio-v2/js/services/ObjectVectorStudioV2SchemaService.js b/tools/object-vector-studio-v2/js/services/ObjectVectorStudioV2SchemaService.js
@@ -1,12 +1,7 @@
-const SCHEMA_URL = new URL("../../../schemas/tools/object-vector-studio-v2.schema.json", import.meta.url);
-
-function isPlainObject(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
+import { isPlainObject } from "../../../../src/shared/utils/objectUtils.js";
+import { deepClone as clone } from "../../../../src/shared/utils/jsonUtils.js";
 
-function clone(value) {
-  return JSON.parse(JSON.stringify(value));
-}
+const SCHEMA_URL = new URL("../../../schemas/tools/object-vector-studio-v2.schema.json", import.meta.url);
 
 function isObjectIdentityId(value) {
   return /^object\.[a-z0-9-]+\.[a-z0-9][a-z0-9-]*$/.test(String(value || ""));
