Skip to content

Commit f20eade

Browse files
author
DavidQ
committed
Inventory engine and shared utilities before common-utils consolidation - PR 11.74
1 parent 8ecbbde commit f20eade

7 files changed

Lines changed: 208 additions & 4 deletions

‎docs/dev/codex_commands.md‎

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

33
Model: GPT-5.4
44
Reasoning: high
55

6-
```powershell
7-
codex --model gpt-5.4 --reasoning high "Run BUILD_PR for docs/pr/PR_11_72_WORKSPACE_MANAGER_TOOL_TILE_JSON_COUNTS.md. Implement only the scoped Workspace Manager tool tile sample-count fix. Derive Samples (##) from matching sample JSON files under samples/**. Palette Browser / Manager must count all palette JSON files and show the real count, not a stale/static number. Do not hardcode counts. Do not create fallback/default data. Produce the required evidence report and package the changed files into <project folder>/tmp/PR_11_72_WORKSPACE_MANAGER_TOOL_TILE_JSON_COUNTS.zip."
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.
810
```

‎docs/dev/commit_comment.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Derive Workspace Manager tool tile sample counts from matching sample JSON files - PR 11.72
1+
Inventory engine and shared utilities before common-utils consolidation - PR 11.74

‎docs/dev/reports/PR_11_74_expected_outputs.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# PR 11.74 Expected Outputs
2+
3+
Codex should create:
4+
5+
- `docs/dev/reports/utils_consolidation_inventory.md`
6+
- `docs/dev/reports/utils_consolidation_inventory.csv`
7+
8+
This PR is intentionally analysis-only so PR 11.75 can perform one focused consolidation pass without guessing.

‎docs/dev/reports/utils_consolidation_inventory.csv‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
folder,file,export,export_kind,methods_in_file,imports,classification,notes
2+
engine/utils,src/engine/utils/fuzzyMatchScore.js,fuzzyMatchScore,named-export,fuzzyMatchScore,,shared-safe,
3+
engine/utils,src/engine/utils/geometry.js,pointInRect,function,,,shared-safe,
4+
engine/utils,src/engine/utils/geometry.js,xyInRect,function,,,shared-safe,
5+
engine/utils,src/engine/utils/geometry.js,getCenteredRect,function,,,shared-safe,
6+
engine/utils,src/engine/utils/index.js,(barrel-reexports),barrel,,,needs-review,Barrel file; consolidation sequencing should happen after direct utility moves.
7+
engine/utils,src/engine/utils/invariant.js,invariant,function,,,shared-safe,
8+
engine/utils,src/engine/utils/math.js,clamp,function,,,duplicate-move-to-shared,Generic clamp; duplicate local clamp exists in engine debug layout.
9+
engine/utils,src/engine/utils/math.js,distance,function,,,duplicate-move-to-shared,Distance helper duplicated by local implementations in network/AI modules.
10+
engine/utils,src/engine/utils/math.js,wrap,function,,,shared-safe,
11+
engine/utils,src/engine/utils/math.js,randomRange,function,,,shared-safe,
12+
engine/utils,src/engine/utils/normalizeCommandText.js,normalizeCommandText,named-export,normalizeCommandText,,needs-review,Hardcoded filler-token list may be command-domain specific.
13+
shared/utils,src/shared/utils/arrayUtils.js,ensureArray,function,,./stringUtils.js,shared-safe,
14+
shared/utils,src/shared/utils/arrayUtils.js,asArray,function,,./stringUtils.js,duplicate-keep-engine,Name overlap with object/3D debug utility asArray variants.
15+
shared/utils,src/shared/utils/arrayUtils.js,asStringArray,function,,./stringUtils.js,shared-safe,
16+
shared/utils,src/shared/utils/createNoopDevConsoleIntegration.js,createNoopDevConsoleIntegration,function,,,engine-only,
17+
shared/utils,src/shared/utils/debugConfigUtils.js,parseBooleanFlag,function,,./stringUtils.js,shared-safe,
18+
shared/utils,src/shared/utils/debugConfigUtils.js,normalizeDebugMode,function,,./stringUtils.js,shared-safe,
19+
shared/utils,src/shared/utils/debugConfigUtils.js,readStoredBoolean,function,,./stringUtils.js,needs-review,Touches localStorage/location query flags (browser environment concerns).
20+
shared/utils,src/shared/utils/debugConfigUtils.js,writeStoredBoolean,function,,./stringUtils.js,needs-review,Touches localStorage/location query flags (browser environment concerns).
21+
shared/utils,src/shared/utils/debugConfigUtils.js,isLocalDebugEnvironment,function,,./stringUtils.js,shared-safe,
22+
shared/utils,src/shared/utils/debugConfigUtils.js,resolveDebugConfig,function,,./stringUtils.js,needs-review,Touches localStorage/location query flags (browser environment concerns).
23+
shared/utils,src/shared/utils/directionUtils.js,oppositeCardinalDirection,function,,,shared-safe,
24+
shared/utils,src/shared/utils/highScoreUtils.js,sanitizeScore,function,,,shared-safe,
25+
shared/utils,src/shared/utils/highScoreUtils.js,sanitizeInitials,function,,,shared-safe,
26+
shared/utils,src/shared/utils/highScoreUtils.js,sanitizeRow,function,,,shared-safe,
27+
shared/utils,src/shared/utils/highScoreUtils.js,sortRows,function,,,shared-safe,
28+
shared/utils,src/shared/utils/idUtils.js,* from ../id/idUtils.js,re-export-star,,,needs-review,
29+
shared/utils,src/shared/utils/index.js,(barrel-reexports),barrel,,,needs-review,Barrel file; consolidation sequencing should happen after direct utility moves.
30+
shared/utils,src/shared/utils/initialsEntryUtils.js,codeToLetter,function,,,shared-safe,
31+
shared/utils,src/shared/utils/jsonUtils.js,cloneJson,function,,,duplicate-move-to-shared,Duplicate cloneJson exists in engine debug inspectors shared utils.
32+
shared/utils,src/shared/utils/networkDebugUtils.js,toNetworkSnapshot,function,toSafeKey,../math/numberNormalization.js|./objectUtils.js|./stringUtils.js,engine-only,Network-trace and command snapshot semantics are debug-runtime specific.
33+
shared/utils,src/shared/utils/networkDebugUtils.js,getCommandSnapshot,function,toSafeKey,../math/numberNormalization.js|./objectUtils.js|./stringUtils.js,engine-only,Network-trace and command snapshot semantics are debug-runtime specific.
34+
shared/utils,src/shared/utils/networkDebugUtils.js,commandLinesForTrace,function,toSafeKey,../math/numberNormalization.js|./objectUtils.js|./stringUtils.js,engine-only,Network-trace and command snapshot semantics are debug-runtime specific.
35+
shared/utils,src/shared/utils/networkDebugUtils.js,sanitizeText,const,toSafeKey,../math/numberNormalization.js|./objectUtils.js|./stringUtils.js,duplicate-keep-engine,Network-trace and command snapshot semantics are debug-runtime specific.
36+
shared/utils,src/shared/utils/networkDebugUtils.js,asNumber,re-export(../math/numberNormalization.js),toSafeKey,../math/numberNormalization.js|./objectUtils.js|./stringUtils.js,engine-only,Network-trace and command snapshot semantics are debug-runtime specific.
37+
shared/utils,src/shared/utils/numberUtils.js,* from ../number/numberUtils.js,re-export-star,,,needs-review,
38+
shared/utils,src/shared/utils/objectUtils.js,isObject,named-export,isObject|isPlainObject|asObject|asArray,./arrayUtils.js,shared-safe,
39+
shared/utils,src/shared/utils/objectUtils.js,isPlainObject,named-export,isObject|isPlainObject|asObject|asArray,./arrayUtils.js,duplicate-keep-engine,Similar helper names appear in engine debug/network modules.
40+
shared/utils,src/shared/utils/objectUtils.js,asObject,named-export,isObject|isPlainObject|asObject|asArray,./arrayUtils.js,duplicate-keep-engine,Similar helper names appear in engine debug/network modules.
41+
shared/utils,src/shared/utils/objectUtils.js,asArray,named-export,isObject|isPlainObject|asObject|asArray,./arrayUtils.js,duplicate-keep-engine,Similar helper names appear in engine debug/network modules.
42+
shared/utils,src/shared/utils/runtimeRegistryUtils.js,getRuntimeAndRegistry,function,,,engine-only,Depends on console runtime/panel registry contract.
43+
shared/utils,src/shared/utils/snapshotCloneUtils.js,cloneSnapshot,function,,,needs-review,
44+
shared/utils,src/shared/utils/stringUtils.js,* from ../string/stringHelpers.js,re-export-star,,,needs-review,
45+
shared/utils,src/shared/utils/stringifyValueUtils.js,stringifyValue,function,,,shared-safe,
46+
shared/utils,src/shared/utils/textWrapUtils.js,wrapTextByCharacterCount,function,,,shared-safe,

‎docs/dev/reports/utils_consolidation_inventory.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Utils Consolidation Inventory (Plan PR 11.74)
2+
3+
## Scope
4+
- Compared `src/engine/utils/*` and `src/shared/utils/*` at folder, file, export, and method level.
5+
- Analysis-only: no file moves, no import rewrites, no shims.
6+
7+
## Folder Summary
8+
- Engine utils files: 6
9+
- Shared utils files: 17
10+
- Engine utils exports inventoried: 10
11+
- Shared utils exports inventoried: 33
12+
- Total exports inventoried (excluding barrel rows): 43
13+
14+
## Classification Totals
15+
- shared-safe: 21
16+
- engine-only: 6
17+
- duplicate-move-to-shared: 3
18+
- duplicate-keep-engine: 5
19+
- needs-review: 10
20+
21+
## File-Level Notes
22+
- `src/engine/utils/index.js` and `src/shared/utils/index.js` are barrel files; they should be consolidated after direct utility ownership is finalized.
23+
- Engine math helpers (`clamp`, `distance`) are generic but currently duplicated by local helpers in other engine modules.
24+
- `runtimeRegistryUtils` and `networkDebugUtils` are currently in shared utils but depend on runtime/debug contracts, so they are flagged as `engine-only` for destination planning.
25+
26+
## Export Inventory
27+
| Folder | File | Export | Kind | Methods In File | Classification | Notes |
28+
|---|---|---|---|---|---|---|
29+
| engine/utils | src/engine/utils/fuzzyMatchScore.js | fuzzyMatchScore | named-export | fuzzyMatchScore | shared-safe | - |
30+
| engine/utils | src/engine/utils/geometry.js | pointInRect | function | - | shared-safe | - |
31+
| engine/utils | src/engine/utils/geometry.js | xyInRect | function | - | shared-safe | - |
32+
| engine/utils | src/engine/utils/geometry.js | getCenteredRect | function | - | shared-safe | - |
33+
| engine/utils | src/engine/utils/index.js | (barrel-reexports) | barrel | - | needs-review | Barrel file; consolidation sequencing should happen after direct utility moves. |
34+
| engine/utils | src/engine/utils/invariant.js | invariant | function | - | shared-safe | - |
35+
| engine/utils | src/engine/utils/math.js | clamp | function | - | duplicate-move-to-shared | Generic clamp; duplicate local clamp exists in engine debug layout. |
36+
| engine/utils | src/engine/utils/math.js | distance | function | - | duplicate-move-to-shared | Distance helper duplicated by local implementations in network/AI modules. |
37+
| engine/utils | src/engine/utils/math.js | wrap | function | - | shared-safe | - |
38+
| engine/utils | src/engine/utils/math.js | randomRange | function | - | shared-safe | - |
39+
| engine/utils | src/engine/utils/normalizeCommandText.js | normalizeCommandText | named-export | normalizeCommandText | needs-review | Hardcoded filler-token list may be command-domain specific. |
40+
| shared/utils | src/shared/utils/arrayUtils.js | ensureArray | function | - | shared-safe | - |
41+
| shared/utils | src/shared/utils/arrayUtils.js | asArray | function | - | duplicate-keep-engine | Name overlap with object/3D debug utility asArray variants. |
42+
| shared/utils | src/shared/utils/arrayUtils.js | asStringArray | function | - | shared-safe | - |
43+
| shared/utils | src/shared/utils/createNoopDevConsoleIntegration.js | createNoopDevConsoleIntegration | function | - | engine-only | - |
44+
| shared/utils | src/shared/utils/debugConfigUtils.js | parseBooleanFlag | function | - | shared-safe | - |
45+
| shared/utils | src/shared/utils/debugConfigUtils.js | normalizeDebugMode | function | - | shared-safe | - |
46+
| shared/utils | src/shared/utils/debugConfigUtils.js | readStoredBoolean | function | - | needs-review | Touches localStorage/location query flags (browser environment concerns). |
47+
| shared/utils | src/shared/utils/debugConfigUtils.js | writeStoredBoolean | function | - | needs-review | Touches localStorage/location query flags (browser environment concerns). |
48+
| shared/utils | src/shared/utils/debugConfigUtils.js | isLocalDebugEnvironment | function | - | shared-safe | - |
49+
| shared/utils | src/shared/utils/debugConfigUtils.js | resolveDebugConfig | function | - | needs-review | Touches localStorage/location query flags (browser environment concerns). |
50+
| shared/utils | src/shared/utils/directionUtils.js | oppositeCardinalDirection | function | - | shared-safe | - |
51+
| shared/utils | src/shared/utils/highScoreUtils.js | sanitizeScore | function | - | shared-safe | - |
52+
| shared/utils | src/shared/utils/highScoreUtils.js | sanitizeInitials | function | - | shared-safe | - |
53+
| shared/utils | src/shared/utils/highScoreUtils.js | sanitizeRow | function | - | shared-safe | - |
54+
| shared/utils | src/shared/utils/highScoreUtils.js | sortRows | function | - | shared-safe | - |
55+
| shared/utils | src/shared/utils/idUtils.js | * from ../id/idUtils.js | re-export-star | - | needs-review | - |
56+
| shared/utils | src/shared/utils/index.js | (barrel-reexports) | barrel | - | needs-review | Barrel file; consolidation sequencing should happen after direct utility moves. |
57+
| shared/utils | src/shared/utils/initialsEntryUtils.js | codeToLetter | function | - | shared-safe | - |
58+
| shared/utils | src/shared/utils/jsonUtils.js | cloneJson | function | - | duplicate-move-to-shared | Duplicate cloneJson exists in engine debug inspectors shared utils. |
59+
| shared/utils | src/shared/utils/networkDebugUtils.js | toNetworkSnapshot | function | toSafeKey | engine-only | Network-trace and command snapshot semantics are debug-runtime specific. |
60+
| shared/utils | src/shared/utils/networkDebugUtils.js | getCommandSnapshot | function | toSafeKey | engine-only | Network-trace and command snapshot semantics are debug-runtime specific. |
61+
| shared/utils | src/shared/utils/networkDebugUtils.js | commandLinesForTrace | function | toSafeKey | engine-only | Network-trace and command snapshot semantics are debug-runtime specific. |
62+
| shared/utils | src/shared/utils/networkDebugUtils.js | sanitizeText | const | toSafeKey | duplicate-keep-engine | Network-trace and command snapshot semantics are debug-runtime specific. |
63+
| shared/utils | src/shared/utils/networkDebugUtils.js | asNumber | re-export(../math/numberNormalization.js) | toSafeKey | engine-only | Network-trace and command snapshot semantics are debug-runtime specific. |
64+
| shared/utils | src/shared/utils/numberUtils.js | * from ../number/numberUtils.js | re-export-star | - | needs-review | - |
65+
| shared/utils | src/shared/utils/objectUtils.js | isObject | named-export | isObject|isPlainObject|asObject|asArray | shared-safe | - |
66+
| shared/utils | src/shared/utils/objectUtils.js | isPlainObject | named-export | isObject|isPlainObject|asObject|asArray | duplicate-keep-engine | Similar helper names appear in engine debug/network modules. |
67+
| shared/utils | src/shared/utils/objectUtils.js | asObject | named-export | isObject|isPlainObject|asObject|asArray | duplicate-keep-engine | Similar helper names appear in engine debug/network modules. |
68+
| shared/utils | src/shared/utils/objectUtils.js | asArray | named-export | isObject|isPlainObject|asObject|asArray | duplicate-keep-engine | Similar helper names appear in engine debug/network modules. |
69+
| shared/utils | src/shared/utils/runtimeRegistryUtils.js | getRuntimeAndRegistry | function | - | engine-only | Depends on console runtime/panel registry contract. |
70+
| shared/utils | src/shared/utils/snapshotCloneUtils.js | cloneSnapshot | function | - | needs-review | - |
71+
| shared/utils | src/shared/utils/stringUtils.js | * from ../string/stringHelpers.js | re-export-star | - | needs-review | - |
72+
| shared/utils | src/shared/utils/stringifyValueUtils.js | stringifyValue | function | - | shared-safe | - |
73+
| shared/utils | src/shared/utils/textWrapUtils.js | wrapTextByCharacterCount | function | - | shared-safe | - |
74+
75+
## Compact Next-PR Consolidation List
76+
1. Move `clamp` and `distance` to `src/shared/math` (or `src/shared/utils`) and replace local duplicate implementations in engine debug/network/AI modules.
77+
2. Consolidate `cloneJson` to a single shared export and remove engine debug duplicate helper.
78+
3. Consolidate `asObject` / `asArray` / `isPlainObject` usage onto shared/object utils in debug + network modules.
79+
4. Re-scope `runtimeRegistryUtils` and `networkDebugUtils` into engine/debug namespace (or split generic portions into shared and keep runtime-bound functions engine-only).
80+
5. Review `normalizeCommandText` domain coupling; either move to shared/string command helpers or keep engine-local with explicit ownership note.
81+
6. After direct-function moves, reduce barrel complexity in `src/shared/utils/index.js` and `src/engine/utils/index.js`.
82+
83+
## Guardrail Confirmation
84+
- No runtime behavior changes.
85+
- No file moves.
86+
- No import rewrites.
87+
- Full sample suite not run (analysis-only scope).

‎docs/pr/BUILD_PR_LEVEL_11_74_UTILS_CONSOLIDATION_INVENTORY.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# BUILD_PR_LEVEL_11_74_UTILS_CONSOLIDATION_INVENTORY
2+
3+
## Codex Task
4+
Create an analysis-only inventory for the two utility trees:
5+
6+
- `src/engine/utils/*`
7+
- `src/shared/utils/*`
8+
9+
## Steps
10+
1. Recursively list files under both folders.
11+
2. For each JavaScript/TypeScript file, identify exported functions, classes, constants, and default exports.
12+
3. For each export, identify likely dependencies by scanning imports and obvious runtime references.
13+
4. Compare names and implementation similarity across both trees.
14+
5. Classify each item as:
15+
- `shared-safe`
16+
- `engine-only`
17+
- `duplicate-move-to-shared`
18+
- `duplicate-keep-engine`
19+
- `needs-review`
20+
6. Write reports:
21+
- `docs/dev/reports/utils_consolidation_inventory.md`
22+
- `docs/dev/reports/utils_consolidation_inventory.csv`
23+
7. Add a compact follow-on section listing the exact files/exports recommended for the next consolidation PR.
24+
25+
## Hard Rules
26+
- Do not move files.
27+
- Do not edit imports.
28+
- Do not add alias/pass-through shims.
29+
- Do not create `engine -> shared -> engine` dependency cycles.
30+
- Do not change runtime code except optional report-generation helper scripts if needed.
31+
- Keep output evidence-based.
32+
33+
## Testing
34+
Run targeted syntax/format checks only if report-generation scripts are added.
35+
Do not run the full sample suite.
36+
37+
## Expected Result
38+
A short, actionable inventory that lets the next PR consolidate confirmed common utilities into `src/shared/utils/*` in one pass.

‎docs/pr/PLAN_PR_LEVEL_11_74_UTILS_CONSOLIDATION_INVENTORY.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# PLAN_PR_LEVEL_11_74_UTILS_CONSOLIDATION_INVENTORY
2+
3+
## Purpose
4+
Inventory `src/engine/utils/*` and `src/shared/utils/*` at the folder, file, export, and method level so consolidation can happen in the next PR without stretching the work across many rounds.
5+
6+
## Scope
7+
- Compare `src/engine/utils/*` and `src/shared/utils/*`.
8+
- Identify duplicate and near-duplicate utilities.
9+
- Classify each utility as `shared-safe`, `engine-only`, or `needs-review`.
10+
- Produce reports only.
11+
- Do not move files in this PR.
12+
- Do not rewrite imports in this PR.
13+
14+
## Destination Rule
15+
- `src/shared/utils/*`: generic utilities with no engine, renderer, sample, game-state, canvas, loader, or Workspace Manager dependency.
16+
- `src/engine/utils/*`: utilities that depend on engine lifecycle, render/update loops, sample runtime, asset loading, canvas/game state, or engine-specific contracts.
17+
18+
## Acceptance
19+
- Inventory report exists.
20+
- CSV report exists.
21+
- Follow-on consolidation plan exists and is limited to confirmed duplicates/shared-safe utilities.
22+
- No code movement.
23+
- No runtime behavior change.

0 commit comments

Comments
 (0)