Remove unnecessary import aliasing and use canonical shared utility names - PR_26140_036-remove-import-alias-confusion

Author: DavidQ

docs/dev/reports/PR_26140_036-remove-import-alias-confusion_report.md

@@ -0,0 +1,61 @@
+# PR_26140_036 Remove Import Alias Confusion Report
+
+## Scope
+- Removed unnecessary cosmetic `as` aliases from active repo-owned import statements.
+- Kept behavior unchanged by switching call sites to the canonical exported names.
+- Left export aliases alone where they are public compatibility bridges.
+- Did not touch vendor, generated, archive, `tests/results`, or report snapshot files.
+
+## Implementation Summary
+- Replaced `deepClone as clone` imports with canonical `deepClone` in Object Vector runtime/collision code, network/session/transport helpers, Asset Manager V2, Text to Speech V2, Workspace Manager V2, and Object Vector Studio V2 schema service code.
+- Replaced numeric/text/object helper aliases with canonical imports, including `asFinite`, `asNumber`, `asArray`, `asObject`, `normalizeText`, `isPlainObject`, and `getPromotionState`.
+- Removed wrapper-only import aliasing in `src/shared/utils/objectUtils.js` and `src/engine/debug/inspectors/shared/inspectorUtils.js` while preserving their existing exports.
+- Replaced Pacman AI's local `reverseDirection` import alias with direct `oppositeCardinalDirection` usage.
+
+## Remaining Import Alias
+Search command:
+
+`rg -n "^\\s*import\\b.*\\bas\\b" games tools src -g "*.js" -g "*.mjs" -g "!**/node_modules/**" -g "!**/tests/results/**" -g "!docs/dev/reports/**" -g "!docs/archive/**"`
+
+Remaining intentional import alias:
+
+- `games/Asteroids/utils/math.js:7` keeps `import { wrap as sharedWrap } ...` because this file exports the public Asteroids helper `wrap(value, max)` as a compatibility adapter over shared `wrap(value, min, max)`. Removing this import alias would require renaming the local public export or introducing another indirection, which is outside the PR's behavior-preserving scope.
+
+Intentional export aliases left in place:
+
+- `games/Pacman/game/PacmanFullAINavigator.js` keeps `export { oppositeCardinalDirection as opposite }` as a public compatibility bridge; the PR scope allows export aliases where intentional.
+
+## Validation
+- INFO: `npm run build` is not defined in this repo (`Missing script: "build"`).
+- PASS: `npm run build:manifest`.
+- PASS: `node tests/games/AsteroidsValidation.test.mjs`.
+- PASS: `node tests/games/AsteroidsManifestScreenDimensions.test.mjs`.
+- PASS: `node tests/games/AsteroidsPresentation.test.mjs`.
+- PASS: `node tests/games/AsteroidsVectorTransforms.test.mjs`.
+- PASS: `node tests/tools/ObjectVectorFinalRuntimeCleanup.test.mjs`.
+- PASS: `node tests/tools/ObjectVectorStudioV2DeleteCleanup.test.mjs`.
+- PASS: `npm run test:workspace-v2` (58 passed).
+- PASS: `npx playwright test tests/playwright/tools/ObjectVectorStudioV2FirstClassToolStarter.spec.mjs --project=playwright --workers=1 --reporter=list` (4 passed).
+- PASS: `npx playwright test tests/playwright/tools/CollisionInspectorV2.spec.mjs --project=playwright --workers=1 --reporter=list` (4 passed).
+- PASS: `npx playwright test tests/playwright/tools/AsteroidsGameSceneCleanup.spec.mjs --project=playwright --workers=1 --reporter=list` (1 passed).
+- PASS: `npx playwright test tests/playwright/games/GameIndexPreviewManifestResolution.spec.mjs --project=playwright --workers=1 --reporter=list` (4 passed, added because `games/index.render.js` import naming changed).
+- PASS: changed-file syntax sanity via `node --check` for every changed `.js`/`.mjs` file.
+- PASS: remaining import alias search, with only the documented Asteroids `wrap` bridge left.
+- PASS: vendor/generated/archive/report snapshot modification check found no matching changed paths.
+- PASS: `git diff --check` (CRLF normalization warnings only; no whitespace errors).
+
+## Playwright Impact
+Playwright impacted: Yes. Active runtime/tool JavaScript import names changed across Workspace Manager V2, Object Vector Studio V2, Collision Inspector V2, Asteroids runtime paths, and games index rendering. Expected pass behavior is unchanged launch/load/render/collision/navigation behavior. Expected fail behavior would be module import errors, page errors, failed tool launch, or broken manifest-driven render/collision paths; none appeared in validation.
+
+## Coverage
+- Advisory Playwright V8 coverage artifacts were refreshed at `docs/dev/reports/playwright_v8_coverage_report.txt` and `docs/dev/reports/coverage_changed_js_guardrail.txt`.
+- Missing changed runtime JS coverage is reported as WARN per project rules, not FAIL.
+
+## Full Samples Smoke
+Skipped. This PR is a scoped import-name cleanup with targeted Workspace Manager, Asteroids, Object Vector Studio V2, Collision Inspector V2, and games-index validation; it does not broadly change the sample loader/framework.
+
+## Manual Validation Notes
+1. Open Workspace Manager V2, select the repo, and confirm games and tools populate.
+2. Launch Object Vector Studio V2 and Collision Inspector V2 from Workspace Manager V2.
+3. Launch Asteroids and confirm normal gameplay smoke behavior.
+4. Open `games/index.html` and confirm game cards/previews still render.

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 as clone } from '../../../src/shared/utils/jsonUtils.js';
+import { deepClone } 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']);
@@ -112,7 +112,7 @@ export function loadAsteroidsObjectGeometryFromManifest(manifest, {
   const objects = Array.isArray(objectVectorPayload?.objects)
     ? objectVectorPayload.objects
       .filter((object) => isRecord(object) && normalizeString(object.id))
-      .map((object) => clone(object))
+      .map((object) => deepClone(object))
     : [];
   const objectsById = new Map(objects.map((object) => [object.id, object]));
   ASTEROIDS_REQUIRED_MANIFEST_GEOMETRY_IDS.forEach((id) => {
@@ -141,7 +141,7 @@ export function loadAsteroidsObjectGeometryFromManifest(manifest, {
   const objectGeometry = {
     objects,
     objectsById,
-    payload: clone(objectVectorPayload),
+    payload: deepClone(objectVectorPayload),
     sourceLabel,
   };
   logValidation(logger, 'OK', `Asteroids Object Vector manifest geometry loaded from ${sourceLabel}: ${objects.length} objects.`, {

games/Pacman/game/PacmanFullAINavigator.js

@@ -4,7 +4,7 @@ David Quesenberry
 03/25/2026
 PacmanFullAINavigator.js
 */
-import { oppositeCardinalDirection as reverseDirection } from '/src/shared/utils/index.js';
+import { oppositeCardinalDirection } from '/src/shared/utils/index.js';
 
 const DIRS = Object.freeze({
   left: { x: -1, y: 0 },
@@ -23,7 +23,7 @@ function getLegalDirections(grid, tileX, tileY) {
 function chooseDirectionTowardTarget(grid, tileX, tileY, currentDirection, targetTile, tieBreakOrder) {
   const legal = getLegalDirections(grid, tileX, tileY);
   if (!legal.length) return null;
-  const blockedReverse = reverseDirection(currentDirection);
+  const blockedReverse = oppositeCardinalDirection(currentDirection);
   const candidates = legal.filter((d) => d !== blockedReverse);
   const valid = candidates.length ? candidates : legal;
 

games/index.render.js

@@ -1,7 +1,7 @@
 import { asArray } from '../src/shared/utils/arrayUtils.js';
 import { getToolRegistry } from "../tools/toolRegistry.js";
 import { resolveGamePreviewMap } from "./shared/gameManifestPreviewResolver.js";
-import { normalizeText as normalize, normalizeToken } from "../src/shared/string/index.js";
+import { normalizeText, normalizeToken } from "../src/shared/string/index.js";
 import { launchWithExternalToolWorkspaceReset, resolveGameWorkspaceLaunchHref } from "../tools/shared/toolLaunchSSoT.js";
 
 const METADATA_PATH = "./metadata/games.index.metadata.json";
@@ -12,7 +12,7 @@ function normalizeTag(value) {
 }
 
 function isThemeEngineClass(value) {
-  const normalized = normalize(value).replace(/\\/g, "/");
+  const normalized = normalizeText(value).replace(/\\/g, "/");
   if (!normalized) {
     return false;
   }
@@ -21,16 +21,16 @@ function isThemeEngineClass(value) {
 }
 
 function toEngineClassName(value) {
-  const normalized = normalize(value).replace(/\\/g, "/");
+  const normalized = normalizeText(value).replace(/\\/g, "/");
   if (!normalized) {
     return "";
   }
   const leaf = normalized.split("/").pop() || "";
-  return normalize(leaf);
+  return normalizeText(leaf);
 }
 
 function levelSortKey(level) {
-  const value = normalize(level);
+  const value = normalizeText(level);
   const numericMatch = value.match(/Level\s+(\d+)/i);
   if (numericMatch) {
     return { bucket: 0, order: Number(numericMatch[1]), label: value };
@@ -63,7 +63,7 @@ function escapeHtml(value) {
 }
 
 function normalizeGameHref(value) {
-  const href = normalize(value).replace(/\\/g, "/");
+  const href = normalizeText(value).replace(/\\/g, "/");
   if (!href || href.includes("..") || !href.startsWith("/games/")) {
     return "";
   }
@@ -104,7 +104,7 @@ function readPinnedSet() {
     if (!Array.isArray(parsed)) {
       return new Set();
     }
-    return new Set(parsed.map((entry) => normalize(entry)).filter(Boolean));
+    return new Set(parsed.map((entry) => normalizeText(entry)).filter(Boolean));
   } catch {
     return new Set();
   }
@@ -117,16 +117,16 @@ function writePinnedSet(pinnedSet) {
 function buildRows(metadata, pinnedSet, toolLabelMap, previewMap) {
   const rows = asArray(metadata?.games)
     .map((game) => {
-      const id = normalize(game?.id);
-      const title = normalize(game?.title) || id;
-      const level = normalize(game?.level) || "Unassigned";
+      const id = normalizeText(game?.id);
+      const title = normalizeText(game?.title) || id;
+      const level = normalizeText(game?.level) || "Unassigned";
       if (!id || !title) {
         return null;
       }
-      const classValues = [...new Set(asArray(game?.classValues).map((value) => normalize(value)).filter(Boolean))]
+      const classValues = [...new Set(asArray(game?.classValues).map((value) => normalizeText(value)).filter(Boolean))]
         .sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }));
       const engineClasses = [...new Set(asArray(game?.engineClassesUsed)
-        .map((value) => normalize(value))
+        .map((value) => normalizeText(value))
         .filter(Boolean)
         .filter((value) => !isThemeEngineClass(value)))]
         .sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }));
@@ -145,15 +145,15 @@ function buildRows(metadata, pinnedSet, toolLabelMap, previewMap) {
       return {
         id,
         title,
-        description: normalize(game?.description) || "No description available.",
+        description: normalizeText(game?.description) || "No description available.",
         level,
-        status: normalize(game?.status) || "planned",
+        status: normalizeText(game?.status) || "planned",
         classValues,
         engineClasses,
         engineClassNames,
         toolTokens,
         tags,
-        preview: normalize(previewMap.get(id)),
+        preview: normalizeText(previewMap.get(id)),
         href,
         workspaceHref: workspaceLaunch.href,
         workspaceLaunchError: workspaceLaunch.error,
@@ -356,7 +356,7 @@ export async function initGamesIndex() {
   const toolLabelMap = new Map(
     toolRegistry
       .filter((tool) => tool.id !== "workspace-manager")
-      .map((tool) => [normalizeToken(tool.id), normalize(tool.displayName) || normalize(tool.name) || normalize(tool.id)])
+      .map((tool) => [normalizeToken(tool.id), normalizeText(tool.displayName) || normalizeText(tool.name) || normalizeText(tool.id)])
       .filter((entry) => entry[0] && entry[1])
   );
   let pinnedSet = readPinnedSet();
@@ -376,11 +376,11 @@ export async function initGamesIndex() {
   const apply = () => {
     model = buildRows(metadata, pinnedSet, toolLabelMap, previewMap);
     const state = {
-      level: normalize(levelSelect.value),
-      classValue: normalize(classSelect.value),
+      level: normalizeText(levelSelect.value),
+      classValue: normalizeText(classSelect.value),
       toolId: normalizeToken(toolSelect.value),
-      tag: normalize(tagSelect.value),
-      query: normalize(searchInput.value)
+      tag: normalizeText(tagSelect.value),
+      query: normalizeText(searchInput.value)
     };
     render(container, statusNode, model.rows, state);
     renderPinned(pinnedContainer, model.rows.filter((row) => row.pinned));
@@ -398,7 +398,7 @@ export async function initGamesIndex() {
     if (!(launchLink instanceof HTMLAnchorElement)) {
       return;
     }
-    const workspaceHref = normalize(launchLink.dataset.workspaceLaunchHref);
+    const workspaceHref = normalizeText(launchLink.dataset.workspaceLaunchHref);
     if (!workspaceHref) {
       return;
     }
@@ -411,7 +411,7 @@ export async function initGamesIndex() {
     if (!(target instanceof HTMLInputElement) || target.type !== "checkbox") {
       return;
     }
-    const gameId = normalize(target.dataset.gamePin);
+    const gameId = normalizeText(target.dataset.gamePin);
     if (!gameId) {
       return;
     }

src/advanced/promotion/createPromotionGate.js

@@ -7,7 +7,7 @@ createPromotionGate.js
 
 import { asFiniteNumber, asPositiveInteger } from '../../shared/math/numberNormalization.js';
 import { isPlainObject } from '../../shared/utils/objectUtils.js';
-import { getPromotionState as getPromotionPublicState } from '../../shared/state/index.js';
+import { getPromotionState } from '../../shared/state/index.js';
 
 function normalizeCriteriaMap(input, requiredCriteria = []) {
   const normalized = {};
@@ -244,7 +244,7 @@ function createPromotionGate(options = {}) {
     evaluate,
     getMetrics,
     getState() {
-      return getPromotionPublicState({
+      return getPromotionState({
         promoted,
         stableFrames,
         stabilityWindowFrames,

src/advanced/state/createWorldGameStateSystem.js

@@ -18,7 +18,7 @@ import {
   createTransitionAppliedEvent,
   createTransitionRejectedEvent
 } from './events.js';
-import { getPromotionState as getPromotionPublicState } from '../../shared/state/index.js';
+import { getPromotionState } from '../../shared/state/index.js';
 import { asFiniteNumber, asPositiveInteger } from '../../shared/math/numberNormalization.js';
 import { isPlainObject } from '../../shared/utils/objectUtils.js';
 import {
@@ -232,7 +232,7 @@ function createInlinePromotionGate({
     evaluate,
     getMetrics,
     getState() {
-      return getPromotionPublicState({
+      return getPromotionState({
         promoted,
         stableFrames,
         stabilityWindowFrames: windowFrames,

src/advanced/state/utils.js

@@ -5,13 +5,13 @@ David Quesenberry
 utils.js
 */
 
-import { isPlainObject as isPlainRecord } from '../../shared/utils/objectUtils.js';
+import { isPlainObject } from '../../shared/utils/objectUtils.js';
 
 function cloneDeep(value) {
   if (Array.isArray(value)) {
     return value.map((entry) => cloneDeep(entry));
   }
-  if (isPlainRecord(value)) {
+  if (isPlainObject(value)) {
     const out = {};
     const keys = Object.keys(value);
     for (let i = 0; i < keys.length; i += 1) {
@@ -40,8 +40,8 @@ function mergeDeep(baseValue, patchValue) {
   if (Array.isArray(patchValue)) {
     return patchValue.map((entry) => cloneDeep(entry));
   }
-  if (isPlainRecord(patchValue)) {
-    const baseObject = isPlainRecord(baseValue) ? baseValue : {};
+  if (isPlainObject(patchValue)) {
+    const baseObject = isPlainObject(baseValue) ? baseValue : {};
     const out = {};
     const baseKeys = Object.keys(baseObject);
     for (let i = 0; i < baseKeys.length; i += 1) {

src/engine/collision/objectVector.js

@@ -14,7 +14,7 @@ import {
   transformRuntimeOrientedPoints,
 } from '../rendering/OrientationTransform.js';
 import { isRecord } from '../../shared/types/typeGuards.js';
-import { deepClone as clone } from '../../shared/utils/jsonUtils.js';
+import { deepClone } from '../../shared/utils/jsonUtils.js';
 import { asFiniteNumber } from '../../shared/number/index.js';
 
 export const OBJECT_VECTOR_COLLISION_ENGINE_PATH = 'src/engine/collision/objectVector.js';
@@ -84,7 +84,7 @@ export function getObjectVectorOrigin(object) {
 }
 
 function effectiveShapeForFrame(shape, frame, shapeIndex) {
-  const effective = clone(shape);
+  const effective = deepClone(shape);
   const override = Array.isArray(frame?.shapeOverrides)
     ? frame.shapeOverrides.find((entry) => entry.shapeIndex === shapeIndex)
     : null;

src/engine/debug/inspectors/shared/inspectorUtils.js

@@ -5,10 +5,10 @@ David Quesenberry
 inspectorUtils.js
 */
 
-import { asArray as ensureArray } from "../../../../shared/utils/objectUtils.js";
+import { asArray, asObject } from "../../../../shared/utils/objectUtils.js";
 export { asNonNegativeInteger, asPositiveInteger, toFiniteNumber } from "../../../../shared/math/numberNormalization.js";
 export { sanitizeText } from "../../../../shared/utils/stringUtils.js";
-export { asArray, asObject } from "../../../../shared/utils/objectUtils.js";
+export { asArray, asObject };
 
 export function cloneJson(value) {
   if (typeof structuredClone === "function") {
@@ -18,7 +18,7 @@ export function cloneJson(value) {
 }
 
 export function boundedPush(buffer, item, max) {
-  const safeBuffer = ensureArray(buffer);
+  const safeBuffer = asArray(buffer);
   safeBuffer.push(item);
   if (safeBuffer.length > max) {
     safeBuffer.splice(0, safeBuffer.length - max);

src/engine/debug/network/shared/networkDebugUtils.js

@@ -5,8 +5,8 @@ David Quesenberry
 networkDebugUtils.js
 */
 
-import { asNumber as toNumber } from "../../../../shared/math/numberNormalization.js";
-import { asArray as toArray } from "../../../../shared/utils/objectUtils.js";
+import { asNumber } from "../../../../shared/math/numberNormalization.js";
+import { asArray } from "../../../../shared/utils/objectUtils.js";
 
 export { asObject, asArray } from "../../../../shared/utils/objectUtils.js";
 export { asNumber } from "../../../../shared/math/numberNormalization.js";
@@ -32,15 +32,15 @@ export function asBoolean(value, fallback = false) {
 }
 
 export function toNonNegativeInteger(value, fallback = 0) {
-  const numeric = Math.floor(toNumber(value, fallback));
+  const numeric = Math.floor(asNumber(value, fallback));
   if (!Number.isFinite(numeric) || numeric < 0) {
-    return Math.max(0, Math.floor(toNumber(fallback, 0)));
+    return Math.max(0, Math.floor(asNumber(fallback, 0)));
   }
   return numeric;
 }
 
 export function shallowCloneArray(values) {
-  return toArray(values).map((value) => {
+  return asArray(values).map((value) => {
     if (value !== null && typeof value === "object") {
       return { ...value };
     }