Skip to content

Commit fc0562c

Browse files
author
DavidQ
committed
Consolidate shared utilities and remove duplicate engine utility implementations - PR 11.75
1 parent f20eade commit fc0562c

68 files changed

Lines changed: 261 additions & 69 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/dev/codex_commands.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
1-
# Codex Command
1+
# Codex Commands — PR 11.75
22

33
Model: GPT-5.4
44
Reasoning: high
55

6-
```text
7-
Run full workflow for PLAN_PR_LEVEL_11_74_UTILS_CONSOLIDATION_INVENTORY.
8-
9-
Create an analysis-only inventory comparing src/engine/utils/* and src/shared/utils/* at folder, file, export, and method level. Produce docs/dev/reports/utils_consolidation_inventory.md and docs/dev/reports/utils_consolidation_inventory.csv. Classify each export as shared-safe, engine-only, duplicate-move-to-shared, duplicate-keep-engine, or needs-review. Include a compact next-PR consolidation list. Do not move files, do not rewrite imports, do not add shims, and do not run the full sample suite.
6+
```powershell
7+
codex --model gpt-5.4 --reasoning high "Run PR 11.75 utils consolidation. Read docs/pr/PR_11_75_UTILS_CONSOLIDATION.md. Inventory src/engine/utils and src/shared/utils at file and exported-method level. Consolidate only true shared-safe duplicates into src/shared/utils, keep engine-bound utilities in src/engine/utils, update imports, remove duplicate implementation files only after imports are updated, and write reports under docs/dev/reports. Do not create wrappers, alias files, bridge exports, pass-through variables, or broad refactors. Run targeted syntax/import validation only."
108
```

‎docs/dev/commit_comment.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Inventory engine and shared utilities before common-utils consolidation - PR 11.74
1+
Consolidate shared utilities and remove duplicate engine utility implementations - PR 11.75

‎docs/dev/reports/PR_11_75_expected_report.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# PR 11.75 Expected Report
2+
3+
Codex must create or update a report with:
4+
5+
- Files scanned in `src/engine/utils/*`
6+
- Files scanned in `src/shared/utils/*`
7+
- Exported methods/classes/constants found
8+
- Duplicate or near-duplicate matches
9+
- Destination decision for each candidate
10+
- Import updates made
11+
- Files removed
12+
- Targeted validation commands and results
13+
14+
If a utility is ambiguous, keep it in place and document why.

‎docs/dev/reports/PR_11_75_utils_consolidation_report.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# PR 11.75 Utils Consolidation Report
2+
3+
## Scope Executed
4+
- Consolidated shared-safe engine math utilities into shared utils.
5+
- Updated imports to canonical shared path.
6+
- Removed duplicate engine utility source only after import updates.
7+
- No wrappers, alias files, bridge exports, pass-through variables, or broad refactors introduced.
8+
9+
## Inventory (File + Exported Method)
10+
- Engine utils files: 5
11+
- Shared utils files: 18
12+
- Inventory CSV: `docs/dev/reports/PR_11_75_utils_inventory.csv`
13+
14+
## Consolidation Decisions
15+
- Moved shared-safe utility implementation:
16+
- `clamp`, `distance`, `wrap`, `randomRange`
17+
- From deleted file: `src/engine/utils/math.js`
18+
- To canonical file: `src/shared/utils/mathUtils.js`
19+
- Kept engine-bound utilities in `src/engine/utils`:
20+
- `fuzzyMatchScore.js`
21+
- `geometry.js`
22+
- `invariant.js`
23+
- `normalizeCommandText.js`
24+
- Updated barrel export: `src/shared/utils/index.js` now exports shared math utils.
25+
- Updated engine barrel: removed math exports from `src/engine/utils/index.js`.
26+
27+
## Import Update Coverage
28+
- JS/MJS files updated in this PR: 62
29+
- In-scope source/sample/game/test files touched: 62
30+
- Canonical import path now used: `src/shared/utils/mathUtils.js`
31+
32+
## Targeted Validation
33+
1. Syntax checks: `node --check` run for all changed JS/MJS files (excluding deleted files)
34+
- Result: PASS (`node_check_passed=61`)
35+
2. Legacy path check for removed engine math utility path
36+
- Check: repository scan for `src/engine/utils/math.js` in JS/MJS imports
37+
- Result: PASS (`legacy_engine_math_path_refs=0`)
38+
3. Targeted import-resolution scan on changed JS/MJS files
39+
- Result: PASS for consolidation changes; one pre-existing unrelated unresolved import remains:
40+
- `samples/phase-13/1316/game/FakeLoopbackNetworkModel.js -> ../../shared/latencyModel.js`
41+
- This path issue was present outside the utils-consolidation scope and was not modified in this PR.
42+
4. Full sample suite
43+
- Skipped by instruction (targeted syntax/import validation only).
44+
45+
## Changed Files (Core)
46+
- `src/shared/utils/mathUtils.js` (new)
47+
- `src/shared/utils/index.js`
48+
- `src/engine/utils/index.js`
49+
- `src/engine/utils/math.js` (deleted)
50+
- Multiple import-only path updates across `src/`, `games/`, `samples/`, and `tests/`.

‎docs/dev/reports/PR_11_75_utils_inventory.csv‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
tree,file,exported_method
2+
engine,src/engine/utils/fuzzyMatchScore.js,fuzzyMatchScore
3+
engine,src/engine/utils/geometry.js,pointInRect
4+
engine,src/engine/utils/geometry.js,xyInRect
5+
engine,src/engine/utils/geometry.js,getCenteredRect
6+
engine,src/engine/utils/index.js,pointInRect
7+
engine,src/engine/utils/index.js,xyInRect
8+
engine,src/engine/utils/index.js,getCenteredRect
9+
engine,src/engine/utils/invariant.js,invariant
10+
engine,src/engine/utils/normalizeCommandText.js,normalizeCommandText
11+
shared,src/shared/utils/arrayUtils.js,ensureArray
12+
shared,src/shared/utils/arrayUtils.js,asArray
13+
shared,src/shared/utils/arrayUtils.js,asStringArray
14+
shared,src/shared/utils/createNoopDevConsoleIntegration.js,createNoopDevConsoleIntegration
15+
shared,src/shared/utils/debugConfigUtils.js,parseBooleanFlag
16+
shared,src/shared/utils/debugConfigUtils.js,normalizeDebugMode
17+
shared,src/shared/utils/debugConfigUtils.js,readStoredBoolean
18+
shared,src/shared/utils/debugConfigUtils.js,writeStoredBoolean
19+
shared,src/shared/utils/debugConfigUtils.js,isLocalDebugEnvironment
20+
shared,src/shared/utils/debugConfigUtils.js,resolveDebugConfig
21+
shared,src/shared/utils/directionUtils.js,oppositeCardinalDirection
22+
shared,src/shared/utils/highScoreUtils.js,sanitizeScore
23+
shared,src/shared/utils/highScoreUtils.js,sanitizeInitials
24+
shared,src/shared/utils/highScoreUtils.js,sanitizeRow
25+
shared,src/shared/utils/highScoreUtils.js,sortRows
26+
shared,src/shared/utils/idUtils.js,* from ../id/idUtils.js
27+
shared,src/shared/utils/index.js,ensureArray
28+
shared,src/shared/utils/index.js,asArray
29+
shared,src/shared/utils/index.js,asStringArray
30+
shared,src/shared/utils/index.js,safeTrim
31+
shared,src/shared/utils/index.js,toLowerSafe
32+
shared,src/shared/utils/index.js,stringCompare
33+
shared,src/shared/utils/index.js,trimSafe
34+
shared,src/shared/utils/index.js,sanitizeText
35+
shared,src/shared/utils/index.js,normalizeString
36+
shared,src/shared/utils/index.js,escapeHtml
37+
shared,src/shared/utils/index.js,createId
38+
shared,src/shared/utils/index.js,generateId
39+
shared,src/shared/utils/index.js,normalizeId
40+
shared,src/shared/utils/index.js,createStableId
41+
shared,src/shared/utils/index.js,isValidId
42+
shared,src/shared/utils/index.js,isFiniteNumber
43+
shared,src/shared/utils/index.js,toFiniteNumber
44+
shared,src/shared/utils/index.js,asFiniteNumber
45+
shared,src/shared/utils/index.js,asPositiveInteger
46+
shared,src/shared/utils/index.js,asPositiveNumber
47+
shared,src/shared/utils/index.js,isObject
48+
shared,src/shared/utils/index.js,isPlainObject
49+
shared,src/shared/utils/index.js,asObject
50+
shared,src/shared/utils/index.js,asObjectArray
51+
shared,src/shared/utils/index.js,cloneJson
52+
shared,src/shared/utils/index.js,stringifyValue
53+
shared,src/shared/utils/index.js,oppositeCardinalDirection
54+
shared,src/shared/utils/index.js,wrapTextByCharacterCount
55+
shared,src/shared/utils/index.js,clamp
56+
shared,src/shared/utils/index.js,distance
57+
shared,src/shared/utils/index.js,wrap
58+
shared,src/shared/utils/index.js,randomRange
59+
shared,src/shared/utils/initialsEntryUtils.js,codeToLetter
60+
shared,src/shared/utils/jsonUtils.js,cloneJson
61+
shared,src/shared/utils/mathUtils.js,clamp
62+
shared,src/shared/utils/mathUtils.js,distance
63+
shared,src/shared/utils/mathUtils.js,wrap
64+
shared,src/shared/utils/mathUtils.js,randomRange
65+
shared,src/shared/utils/networkDebugUtils.js,toNetworkSnapshot
66+
shared,src/shared/utils/networkDebugUtils.js,getCommandSnapshot
67+
shared,src/shared/utils/networkDebugUtils.js,commandLinesForTrace
68+
shared,src/shared/utils/networkDebugUtils.js,sanitizeText
69+
shared,src/shared/utils/networkDebugUtils.js,asNumber
70+
shared,src/shared/utils/numberUtils.js,* from ../number/numberUtils.js
71+
shared,src/shared/utils/objectUtils.js,isObject
72+
shared,src/shared/utils/objectUtils.js,isPlainObject
73+
shared,src/shared/utils/objectUtils.js,asObject
74+
shared,src/shared/utils/objectUtils.js,asArray
75+
shared,src/shared/utils/runtimeRegistryUtils.js,getRuntimeAndRegistry
76+
shared,src/shared/utils/snapshotCloneUtils.js,cloneSnapshot
77+
shared,src/shared/utils/stringUtils.js,* from ../string/stringHelpers.js
78+
shared,src/shared/utils/stringifyValueUtils.js,stringifyValue
79+
shared,src/shared/utils/textWrapUtils.js,wrapTextByCharacterCount

‎docs/pr/PR_11_75_UTILS_CONSOLIDATION.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# PR 11.75 — Utils Consolidation
2+
3+
## Purpose
4+
Consolidate duplicated utility code between `src/engine/utils/*` and `src/shared/utils/*` without introducing wrappers, aliases, pass-through shims, or broad refactors.
5+
6+
## Scope
7+
- Inventory both utility trees before moving code.
8+
- Move only shared-safe/pure utilities into `src/shared/utils/*`.
9+
- Keep engine-bound utilities in `src/engine/utils/*`.
10+
- Remove true duplicate engine utilities after imports are updated.
11+
- Update imports to the final canonical path.
12+
- Do not create bridge files, alias exports, or temporary compatibility layers.
13+
14+
## Shared vs Engine Rule
15+
`src/shared/utils/*` is for pure reusable utilities only:
16+
- no engine imports
17+
- no canvas dependency
18+
- no render loop dependency
19+
- no game state dependency
20+
- no sample-specific dependency
21+
- no hidden fallback/default data
22+
23+
`src/engine/utils/*` keeps utilities that depend on:
24+
- engine runtime
25+
- canvas/rendering
26+
- input systems
27+
- physics/game state
28+
- sample or tool loaders
29+
30+
## Required Codex Workflow
31+
1. List files under `src/engine/utils` and `src/shared/utils`.
32+
2. Identify exact duplicate or near-duplicate functions/classes/constants.
33+
3. For each duplicate, decide canonical location using the shared-vs-engine rule.
34+
4. Move shared-safe utilities to `src/shared/utils/*`.
35+
5. Remove duplicate source from `src/engine/utils/*` only after imports are updated.
36+
6. Update import paths across affected files.
37+
7. Run targeted syntax/import validation.
38+
8. Produce reports under `docs/dev/reports`.
39+
40+
## Non-goals
41+
- No broad cleanup outside utility consolidation.
42+
- No unrelated formatting.
43+
- No roadmap rewrite.
44+
- No standalone compatibility wrappers.
45+
- No mass refactor.
46+
47+
## Acceptance
48+
- Pure utilities live in `src/shared/utils/*`.
49+
- Engine-only utilities remain in `src/engine/utils/*`.
50+
- No duplicate utility implementation remains across both trees unless behavior differs and is documented.
51+
- No alias/pass-through files are introduced.
52+
- Targeted validation passes.

‎games/AITargetDummy/game/AITargetDummyController.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ AITargetDummyController.js
66
*/
77
import AITargetDummyConfig from './AITargetDummyConfig.js';
88
import AITargetDummyStateMachine from './AITargetDummyStateMachine.js';
9-
import { clamp } from '/src/engine/utils/math.js';
9+
import { clamp } from '/src/shared/utils/mathUtils.js';
1010
import { safeNormalize } from '../../../src/shared/math/vectorNormalizeUtils.js';
1111

1212
export default class AITargetDummyController {

‎games/AITargetDummy/game/AITargetDummyInputController.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ David Quesenberry
55
AITargetDummyInputController.js
66
*/
77
import { GamepadInputAdapter } from '/src/engine/input/index.js';
8-
import { clamp } from '/src/engine/utils/math.js';
8+
import { clamp } from '/src/shared/utils/mathUtils.js';
99

1010
export default class AITargetDummyInputController {
1111
constructor(input) {

‎games/AITargetDummy/game/AITargetDummyWorld.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ AITargetDummyWorld.js
66
*/
77
import AITargetDummyConfig from './AITargetDummyConfig.js';
88
import AITargetDummyController from './AITargetDummyController.js';
9-
import { clamp } from '/src/engine/utils/math.js';
9+
import { clamp } from '/src/shared/utils/mathUtils.js';
1010
import { safeNormalize } from '../../../src/shared/math/vectorNormalizeUtils.js';
1111

1212
const MAX_STEP_SECONDS = 1 / 120;

‎games/Asteroids/entities/Ufo.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ David Quesenberry
55
Ufo.js
66
*/
77
import Bullet from './Bullet.js';
8-
import { distance } from '../../../src/engine/utils/index.js';
8+
import { distance } from '../../../src/shared/utils/mathUtils.js';
99
import { transformPoints } from '../../../src/engine/rendering/index.js';
1010
import { randomRange } from '../utils/math.js';
1111

0 commit comments

Comments
 (0)