PR_26140_038-canonical-shared-utility-naming-final-pass

Author: DavidQ

docs/dev/reports/PR_26140_038-canonical-shared-utility-naming-final-pass_report.md

@@ -0,0 +1,43 @@
+# PR_26140_038 Canonical Shared Utility Naming Final Pass
+
+## Scope
+- Used PR_26140_037 as the prior delta.
+- Removed remaining cosmetic aliases from repo-owned touched code.
+- Kept behavior unchanged; no gameplay, runtime, schema, manifest, vendor, generated, archive, report snapshot, or tests/results artifact changes were made.
+
+## Changes
+- Replaced Playwright `workspaceV2CoverageReporter as coverageReporter` imports with direct `workspaceV2CoverageReporter` imports/usages in affected browser specs.
+- Replaced the `import * as fs from "node:fs/promises"` namespace import in `tests/core/BackgroundImageAndFullscreenBezel.test.mjs` with canonical named fs/promises imports.
+- Verified the prior cosmetic coverage reporter alias no longer appears in repo-owned Playwright specs.
+
+## Remaining Intentional Aliases
+- `tests/run-tests.mjs`: `run as run...` aliases remain because every test module exports the same `run` function name and the aggregate runner needs distinct callable names.
+- `src/engine/**/index.js` and `tools/shared/**/index.js`: `export { default as ... }` remains for public barrel APIs that expose default class/module exports under stable named exports.
+- `src/shared/index.js`: `export * as shared...` namespace exports remain as intentional top-level shared-family barrels.
+- `tests/core/EngineCoreBoundaryBaseline.test.mjs` and `tests/runtime/Phase19OverlayExpansionFramework.test.mjs`: namespace imports remain because these tests validate module/barrel surfaces as namespaces.
+- `tests/shared/SharedNumberStringIdCloseout.test.mjs` and `tests/shared/SharedFoundationCombinedPass.test.mjs`: `legacy...` aliases remain to compare legacy compatibility modules against canonical utilities.
+- `games/Asteroids/utils/math.js`: `wrap as sharedWrap` remains because the Asteroids local `wrap(value, max)` adapter preserves an existing two-argument gameplay API over the shared three-argument helper.
+
+## Validation
+- PASS: changed JavaScript/MJS files passed `node --check`.
+- INFO: `npm run build` is not defined in `package.json`.
+- PASS: `npm run build:manifest` completed; generated `docs/build/sample-manifest.json` was removed after validation.
+- PASS: `node tests\core\BackgroundImageAndFullscreenBezel.test.mjs`.
+- PASS: `node tests\games\AsteroidsValidation.test.mjs`.
+- PASS: `node tests\games\AsteroidsManifestScreenDimensions.test.mjs`.
+- PASS: `node tests\games\AsteroidsPresentation.test.mjs`.
+- PASS: `node tests\tools\ObjectVectorFinalRuntimeCleanup.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/games/GameIndexPreviewManifestResolution.spec.mjs --project=playwright --workers=1 --reporter=list`.
+- PASS: `npm run test:workspace-v2` (58 passed).
+- PASS: `git diff --check` returned no whitespace errors; Git reported line-ending normalization warnings only.
+- PASS: `rg -n "workspaceV2CoverageReporter\s+as\s+coverageReporter|\bcoverageReporter\b" tests/playwright -g "*.mjs"` returned no matches.
+- PASS: repo-owned alias scan found only the intentional categories documented above:
+  - `rg -n "^\s*import\b.*\bas\b|^\s*export\b.*\bas\b" games tools src tests -g "*.js" -g "*.mjs" -g "!**/node_modules/**" -g "!**/tests/results/**" -g "!docs/dev/reports/**" -g "!docs/archive/**" -g "!tools/Vector Map Editor/**" -g "!**/generated/**" -g "!**/vendor/**" -g "!**/*.min.js"`
+- PASS: changed-file guard found no modified node_modules, tests/results, docs/dev/reports snapshots, archived tools, generated bundles, vendor files, bundled files, or minified JS files.
+
+## Notes
+- Full samples smoke test was not run; this PR is limited to canonical naming cleanup and the requested targeted validations passed.

tests/core/BackgroundImageAndFullscreenBezel.test.mjs

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import os from "node:os";
 import path from "node:path";
-import * as fs from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import Engine from "../../src/engine/core/Engine.js";
 import backgroundImage from "../../src/engine/runtime/backgroundImage.js";
 import fullscreenBezel, {
@@ -747,38 +747,38 @@ function testMalformedAndExtremeStretchConfigValuesAreSafe() {
 }
 
 async function testBezelStretchConfigAutoCreate() {
-  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "bezel-stretch-config-"));
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "bezel-stretch-config-"));
   const configPath = "games/TestGame/assets/images/bezel.stretch.override.json";
 
   try {
     const config = await ensureBezelStretchConfigFile(configPath, {
       cwd: tempRoot,
-      fsModule: fs,
+      fsModule: { mkdir, readFile, writeFile },
       pathModule: path
     });
     assert.deepEqual(config, { uniformEdgeStretchPx: 0 });
 
     const absolutePath = path.resolve(tempRoot, configPath);
-    const saved = JSON.parse(await fs.readFile(absolutePath, "utf8"));
+    const saved = JSON.parse(await readFile(absolutePath, "utf8"));
     assert.deepEqual(saved, { uniformEdgeStretchPx: 0 });
 
     const existingContent = { uniformEdgeStretchPx: 12 };
-    await fs.writeFile(absolutePath, `${JSON.stringify(existingContent, null, 2)}\n`, "utf8");
+    await writeFile(absolutePath, `${JSON.stringify(existingContent, null, 2)}\n`, "utf8");
     const loadedExisting = await ensureBezelStretchConfigFile(configPath, {
       cwd: tempRoot,
-      fsModule: fs,
+      fsModule: { mkdir, readFile, writeFile },
       pathModule: path
     });
-    const savedAfterReload = JSON.parse(await fs.readFile(absolutePath, "utf8"));
+    const savedAfterReload = JSON.parse(await readFile(absolutePath, "utf8"));
     assert.deepEqual(loadedExisting, existingContent);
     assert.deepEqual(savedAfterReload, existingContent);
   } finally {
-    await fs.rm(tempRoot, { recursive: true, force: true });
+    await rm(tempRoot, { recursive: true, force: true });
   }
 }
 
 async function testBezelDetectionTriggersStretchConfigAutoCreate() {
-  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "bezel-detected-config-"));
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "bezel-detected-config-"));
   const documentRef = createDocumentStub("/games/_template/index.html");
   const host = createElement("div", documentRef);
   const canvas = createElement("canvas", documentRef);
@@ -796,7 +796,7 @@ async function testBezelDetectionTriggersStretchConfigAutoCreate() {
         providerCalls += 1;
         return ensureBezelStretchConfigFile(configPath, {
           cwd: tempRoot,
-          fsModule: fs,
+          fsModule: { mkdir, readFile, writeFile },
           pathModule: path
         });
       }
@@ -814,17 +814,17 @@ async function testBezelDetectionTriggersStretchConfigAutoCreate() {
     }
 
     const createdPath = path.resolve(tempRoot, "games/_template/assets/images/bezel.stretch.override.json");
-    const saved = JSON.parse(await fs.readFile(createdPath, "utf8"));
+    const saved = JSON.parse(await readFile(createdPath, "utf8"));
     assert.deepEqual(saved, { uniformEdgeStretchPx: 0 });
     assert.equal(bezel.getState().stretchConfigPath, "games/_template/assets/images/bezel.stretch.override.json");
     assert.equal(bezel.getState().stretchConfigInitialized, true);
   } finally {
-    await fs.rm(tempRoot, { recursive: true, force: true });
+    await rm(tempRoot, { recursive: true, force: true });
   }
 }
 
 async function testBezelDetectionDoesNotOverwriteExistingStretchConfig() {
-  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "bezel-detected-existing-config-"));
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "bezel-detected-existing-config-"));
   const documentRef = createDocumentStub("/games/_template/index.html");
   const host = createElement("div", documentRef);
   const canvas = createElement("canvas", documentRef);
@@ -836,16 +836,16 @@ async function testBezelDetectionDoesNotOverwriteExistingStretchConfig() {
   try {
     const expectedConfig = { uniformEdgeStretchPx: 14 };
     const configPath = path.resolve(tempRoot, "games/_template/assets/images/bezel.stretch.override.json");
-    await fs.mkdir(path.dirname(configPath), { recursive: true });
-    await fs.writeFile(configPath, `${JSON.stringify(expectedConfig, null, 2)}\n`, "utf8");
+    await mkdir(path.dirname(configPath), { recursive: true });
+    await writeFile(configPath, `${JSON.stringify(expectedConfig, null, 2)}\n`, "utf8");
 
     const bezel = new fullscreenBezel({
       canvas,
       documentRef,
       stretchConfigProvider(runtimeConfigPath) {
         return ensureBezelStretchConfigFile(runtimeConfigPath, {
           cwd: tempRoot,
-          fsModule: fs,
+          fsModule: { mkdir, readFile, writeFile },
           pathModule: path
         });
       }
@@ -858,37 +858,37 @@ async function testBezelDetectionDoesNotOverwriteExistingStretchConfig() {
       await bezel.stretchConfigPromise;
     }
 
-    const savedAfterStartup = JSON.parse(await fs.readFile(configPath, "utf8"));
+    const savedAfterStartup = JSON.parse(await readFile(configPath, "utf8"));
     assert.deepEqual(savedAfterStartup, expectedConfig);
     assert.equal(bezel.getState().uniformEdgeStretchPx, expectedConfig.uniformEdgeStretchPx);
   } finally {
-    await fs.rm(tempRoot, { recursive: true, force: true });
+    await rm(tempRoot, { recursive: true, force: true });
   }
 }
 
 async function testMalformedStretchConfigFileFallsBackWithoutOverwrite() {
-  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "bezel-malformed-config-"));
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "bezel-malformed-config-"));
   const configPath = path.resolve(tempRoot, "games/TestGame/assets/images/bezel.stretch.override.json");
   try {
-    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await mkdir(path.dirname(configPath), { recursive: true });
     const malformedContent = "{not-valid-json";
-    await fs.writeFile(configPath, malformedContent, "utf8");
+    await writeFile(configPath, malformedContent, "utf8");
 
     const loaded = await ensureBezelStretchConfigFile("games/TestGame/assets/images/bezel.stretch.override.json", {
       cwd: tempRoot,
-      fsModule: fs,
+      fsModule: { mkdir, readFile, writeFile },
       pathModule: path
     });
-    const savedAfterLoad = await fs.readFile(configPath, "utf8");
+    const savedAfterLoad = await readFile(configPath, "utf8");
     assert.deepEqual(loaded, { uniformEdgeStretchPx: 0 });
     assert.equal(savedAfterLoad, malformedContent);
   } finally {
-    await fs.rm(tempRoot, { recursive: true, force: true });
+    await rm(tempRoot, { recursive: true, force: true });
   }
 }
 
 async function testSampleGameBezelDetectionCreatesStretchConfig() {
-  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "bezel-detected-spaceinvaders-config-"));
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "bezel-detected-spaceinvaders-config-"));
   const documentRef = createDocumentStub("/games/SpaceInvaders/index.html");
   const host = createElement("div", documentRef);
   const canvas = createElement("canvas", documentRef);
@@ -904,7 +904,7 @@ async function testSampleGameBezelDetectionCreatesStretchConfig() {
       stretchConfigProvider(configPath) {
         return ensureBezelStretchConfigFile(configPath, {
           cwd: tempRoot,
-          fsModule: fs,
+          fsModule: { mkdir, readFile, writeFile },
           pathModule: path
         });
       }
@@ -919,11 +919,11 @@ async function testSampleGameBezelDetectionCreatesStretchConfig() {
     }
 
     const createdPath = path.resolve(tempRoot, "games/SpaceInvaders/assets/images/bezel.stretch.override.json");
-    const saved = JSON.parse(await fs.readFile(createdPath, "utf8"));
+    const saved = JSON.parse(await readFile(createdPath, "utf8"));
     assert.deepEqual(saved, { uniformEdgeStretchPx: 0 });
     assert.equal(bezel.getState().stretchConfigPath, "games/SpaceInvaders/assets/images/bezel.stretch.override.json");
   } finally {
-    await fs.rm(tempRoot, { recursive: true, force: true });
+    await rm(tempRoot, { recursive: true, force: true });
   }
 }
 

tests/playwright/games/GameIndexPreviewManifestResolution.spec.mjs

@@ -2,15 +2,15 @@ import { expect, test } from "@playwright/test";
 import path from "node:path";
 import { readdir, readFile } from "node:fs/promises";
 import { startRepoServer } from "../../helpers/playwrightRepoServer.mjs";
-import { workspaceV2CoverageReporter as coverageReporter } from "../../helpers/workspaceV2CoverageReporter.mjs";
+import { workspaceV2CoverageReporter } from "../../helpers/workspaceV2CoverageReporter.mjs";
 
 const GAMES_DIR = "games";
 const PONG_MANIFEST_PATH = "games/Pong/game.manifest.json";
 const PONG_PREVIEW_PATH = "/games/Pong/assets/images/preview1.svg";
 const PONG_OLD_PREVIEW_PATH = "/games/Pong/assets/images/preview.svg";
 
 test.afterAll(async () => {
-  await coverageReporter.writeReport();
+  await workspaceV2CoverageReporter.writeReport();
 });
 
 async function readPongManifest() {
@@ -110,7 +110,7 @@ test("games index resolves every game thumbnail from manifest preview roles", as
     }
   });
 
-  await coverageReporter.start(page);
+  await workspaceV2CoverageReporter.start(page);
   try {
     await page.goto(`${server.baseUrl}/games/index.html`, { waitUntil: "networkidle" });
     for (const [gameId, previewPath] of previewPaths) {
@@ -124,7 +124,7 @@ test("games index resolves every game thumbnail from manifest preview roles", as
     expect(imageNotFoundResponses).toEqual([]);
     expect(pageErrors).toEqual([]);
   } finally {
-    await coverageReporter.stop(page);
+    await workspaceV2CoverageReporter.stop(page);
     await server.close();
   }
 });
@@ -137,7 +137,7 @@ test("games index resolves Pong thumbnail from manifest preview role", async ({
     pageErrors.push(error.message);
   });
 
-  await coverageReporter.start(page);
+  await workspaceV2CoverageReporter.start(page);
   try {
     await page.goto(`${server.baseUrl}/games/index.html`, { waitUntil: "networkidle" });
     const pongCard = page.locator('[data-game-id="Pong"]').first();
@@ -150,7 +150,7 @@ test("games index resolves Pong thumbnail from manifest preview role", async ({
     expect(requests.imageNotFoundResponses).not.toContain(PONG_OLD_PREVIEW_PATH);
     expect(pageErrors).toEqual([]);
   } finally {
-    await coverageReporter.stop(page);
+    await workspaceV2CoverageReporter.stop(page);
     await server.close();
   }
 });
@@ -163,7 +163,7 @@ test("Pong page resolves thumbnail from manifest preview role", async ({ page })
     pageErrors.push(error.message);
   });
 
-  await coverageReporter.start(page);
+  await workspaceV2CoverageReporter.start(page);
   try {
     await page.goto(`${server.baseUrl}/games/Pong/index.html`, { waitUntil: "networkidle" });
     const previewImage = page.locator("#pong-preview-thumbnail");
@@ -175,7 +175,7 @@ test("Pong page resolves thumbnail from manifest preview role", async ({ page })
     expect(requests.imageNotFoundResponses).not.toContain(PONG_OLD_PREVIEW_PATH);
     expect(pageErrors).toEqual([]);
   } finally {
-    await coverageReporter.stop(page);
+    await workspaceV2CoverageReporter.stop(page);
     await server.close();
   }
 });
@@ -196,7 +196,7 @@ test("Pong page keeps safe placeholder when preview role is absent", async ({ pa
     });
   });
 
-  await coverageReporter.start(page);
+  await workspaceV2CoverageReporter.start(page);
   try {
     await page.goto(`${server.baseUrl}/games/Pong/index.html`, { waitUntil: "networkidle" });
     await expect(page.locator("#pong-preview-placeholder")).toBeVisible();
@@ -208,7 +208,7 @@ test("Pong page keeps safe placeholder when preview role is absent", async ({ pa
     expect(requests.imageNotFoundResponses).not.toContain(PONG_OLD_PREVIEW_PATH);
     expect(pageErrors).toEqual([]);
   } finally {
-    await coverageReporter.stop(page);
+    await workspaceV2CoverageReporter.stop(page);
     await server.close();
   }
 });