Skip to content

Commit bb1f6d4

Browse files
author
DavidQ
committed
Expand utils audit to report dead usage, duplicates, and folder placement mismatches - PR 11.81
1 parent 3e35a1f commit bb1f6d4

8 files changed

Lines changed: 249 additions & 4 deletions

‎docs/dev/codex_commands.md‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,26 @@
1-
# Codex Commands - PR 11.80
1+
# Codex Commands — PR 11.81
22

33
Model: GPT-5.4
44
Reasoning: high
55

6-
```powershell
7-
codex run --model gpt-5.4 --reasoning high -- "Implement PR 11.80 exactly as described in docs/pr/PLAN_PR_11_80_DEAD_UTILS_AUDIT.md and docs/pr/BUILD_PR_11_80_DEAD_UTILS_AUDIT.md. Add scripts/PS/audit-dead-utils.ps1 as report-only. Do not delete or move utility files. Run the new script once and save output notes in docs/dev/reports/dead_utils_audit_validation.md. Package the result as <project folder>/tmp/PR_11_80_DEAD_UTILS_AUDIT.zip."
6+
Run Codex with this task:
7+
8+
```text
9+
You are applying PR 11.81. Expand the utilities audit only. Do not delete, move, or rewrite implementation files.
10+
11+
Inspect src/shared/utils/** and any remaining src/engine/utils/**.
12+
13+
Create these reports:
14+
- docs/dev/reports/utils_dead_usage_audit.md
15+
- docs/dev/reports/utils_duplicate_exports_audit.md
16+
- docs/dev/reports/utils_folder_category_audit.md
17+
- docs/dev/reports/utils_audit_summary.csv
18+
19+
Report:
20+
1. unused utility files and unused named exports
21+
2. duplicate or near-duplicate exports across utility files
22+
3. folder-category mismatches, especially generic utilities still under src/engine/utils
23+
4. every remaining literal reference to src/engine/utils/ and /src/engine/utils/
24+
25+
Do not change implementation code. Do not create wrappers, aliases, or pass-through files. This PR is report-only.
826
```

‎docs/dev/commit_comment.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Add report-only dead utils audit after shared utils consolidation - PR 11.80
1+
Expand utils audit to report dead usage, duplicates, and folder placement mismatches - PR 11.81

‎docs/dev/reports/PR_11_81_EXPECTED_REPORTS.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# PR 11.81 Expected Reports
2+
3+
Codex must generate the following during execution:
4+
5+
- utils_dead_usage_audit.md
6+
- utils_duplicate_exports_audit.md
7+
- utils_folder_category_audit.md
8+
- utils_audit_summary.csv
9+
10+
This placeholder documents required deliverables only.

‎docs/dev/reports/utils_audit_summary.csv‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Category,Metric,Count,Notes
2+
DeadUsage,UtilityFilesScanned,22,"src/shared/utils and src/engine/utils"
3+
DeadUsage,PotentialUnusedUtilityFiles,0,"No import/path references found in source scan roots"
4+
DeadUsage,PotentialUnusedNamedExports,40,"No named/default import evidence found"
5+
Duplicates,DuplicateExportNames,21,"Same export name appears in multiple utility files"
6+
Category,EngineUtilsFilesRemaining,0,"Files still under src/engine/utils"
7+
References,RemainingLiteralEngineUtilsReferences,11,"Occurrences of src/engine/utils/ or /src/engine/utils/"

‎docs/dev/reports/utils_dead_usage_audit.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Utils Dead Usage Audit
2+
3+
Scanned utility files: 22
4+
Potentially unused utility files: 0
5+
Potentially unused named exports: 40
6+
7+
## Potentially Unused Utility Files
8+
- none
9+
10+
## Potentially Unused Named Exports
11+
- src/shared/utils/directionUtils.js :: `oppositeCardinalDirection` (function)
12+
- src/shared/utils/fuzzyMatchScore.js :: `fuzzyMatchScore` (named-list)
13+
- src/shared/utils/geometryUtils.js :: `getCenteredRect` (function)
14+
- src/shared/utils/geometryUtils.js :: `pointInRect` (function)
15+
- src/shared/utils/geometryUtils.js :: `xyInRect` (function)
16+
- src/shared/utils/index.js :: `asFiniteNumber` (named-list)
17+
- src/shared/utils/index.js :: `asObject` (named-list)
18+
- src/shared/utils/index.js :: `asObjectArray` (named-list)
19+
- src/shared/utils/index.js :: `asPositiveInteger` (named-list)
20+
- src/shared/utils/index.js :: `asPositiveNumber` (named-list)
21+
- src/shared/utils/index.js :: `clamp` (named-list)
22+
- src/shared/utils/index.js :: `cloneJson` (named-list)
23+
- src/shared/utils/index.js :: `distance` (named-list)
24+
- src/shared/utils/index.js :: `fuzzyMatchScore` (named-list)
25+
- src/shared/utils/index.js :: `generateId` (named-list)
26+
- src/shared/utils/index.js :: `getCenteredRect` (named-list)
27+
- src/shared/utils/index.js :: `invariant` (named-list)
28+
- src/shared/utils/index.js :: `isFiniteNumber` (named-list)
29+
- src/shared/utils/index.js :: `isObject` (named-list)
30+
- src/shared/utils/index.js :: `isPlainObject` (named-list)
31+
- src/shared/utils/index.js :: `normalizeCommandText` (named-list)
32+
- src/shared/utils/index.js :: `normalizeString` (named-list)
33+
- src/shared/utils/index.js :: `pointInRect` (named-list)
34+
- src/shared/utils/index.js :: `randomRange` (named-list)
35+
- src/shared/utils/index.js :: `safeTrim` (named-list)
36+
- src/shared/utils/index.js :: `stringCompare` (named-list)
37+
- src/shared/utils/index.js :: `stringifyValue` (named-list)
38+
- src/shared/utils/index.js :: `toFiniteNumber` (named-list)
39+
- src/shared/utils/index.js :: `toLowerSafe` (named-list)
40+
- src/shared/utils/index.js :: `trimSafe` (named-list)
41+
- src/shared/utils/index.js :: `wrap` (named-list)
42+
- src/shared/utils/index.js :: `xyInRect` (named-list)
43+
- src/shared/utils/networkDebugUtils.js :: `asNumber` (named-list)
44+
- src/shared/utils/networkDebugUtils.js :: `commandLinesForTrace` (function)
45+
- src/shared/utils/networkDebugUtils.js :: `getCommandSnapshot` (function)
46+
- src/shared/utils/networkDebugUtils.js :: `sanitizeText` (variable)
47+
- src/shared/utils/networkDebugUtils.js :: `toNetworkSnapshot` (function)
48+
- src/shared/utils/normalizeCommandTextUtils.js :: `normalizeCommandText` (named-list)
49+
- src/shared/utils/snapshotCloneUtils.js :: `cloneSnapshot` (function)
50+
- src/shared/utils/textWrapUtils.js :: `wrapTextByCharacterCount` (function)

‎docs/dev/reports/utils_duplicate_exports_audit.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Utils Duplicate Exports Audit
2+
3+
Duplicate export names across utility files: 21
4+
5+
## Duplicate / Near-Duplicate Export Names
6+
- `asArray` in:
7+
- src/shared/utils/arrayUtils.js
8+
- src/shared/utils/index.js
9+
- src/shared/utils/objectUtils.js
10+
- `asObject` in:
11+
- src/shared/utils/index.js
12+
- src/shared/utils/objectUtils.js
13+
- `asStringArray` in:
14+
- src/shared/utils/arrayUtils.js
15+
- src/shared/utils/index.js
16+
- `clamp` in:
17+
- src/shared/utils/index.js
18+
- src/shared/utils/mathUtils.js
19+
- `cloneJson` in:
20+
- src/shared/utils/index.js
21+
- src/shared/utils/jsonUtils.js
22+
- `distance` in:
23+
- src/shared/utils/index.js
24+
- src/shared/utils/mathUtils.js
25+
- `ensureArray` in:
26+
- src/shared/utils/arrayUtils.js
27+
- src/shared/utils/index.js
28+
- `fuzzyMatchScore` in:
29+
- src/shared/utils/fuzzyMatchScore.js
30+
- src/shared/utils/index.js
31+
- `getCenteredRect` in:
32+
- src/shared/utils/geometryUtils.js
33+
- src/shared/utils/index.js
34+
- `invariant` in:
35+
- src/shared/utils/index.js
36+
- src/shared/utils/invariantUtils.js
37+
- `isObject` in:
38+
- src/shared/utils/index.js
39+
- src/shared/utils/objectUtils.js
40+
- `isPlainObject` in:
41+
- src/shared/utils/index.js
42+
- src/shared/utils/objectUtils.js
43+
- `normalizeCommandText` in:
44+
- src/shared/utils/index.js
45+
- src/shared/utils/normalizeCommandTextUtils.js
46+
- `oppositeCardinalDirection` in:
47+
- src/shared/utils/directionUtils.js
48+
- src/shared/utils/index.js
49+
- `pointInRect` in:
50+
- src/shared/utils/geometryUtils.js
51+
- src/shared/utils/index.js
52+
- `randomRange` in:
53+
- src/shared/utils/index.js
54+
- src/shared/utils/mathUtils.js
55+
- `sanitizeText` in:
56+
- src/shared/utils/index.js
57+
- src/shared/utils/networkDebugUtils.js
58+
- `stringifyValue` in:
59+
- src/shared/utils/index.js
60+
- src/shared/utils/stringifyValueUtils.js
61+
- `wrap` in:
62+
- src/shared/utils/index.js
63+
- src/shared/utils/mathUtils.js
64+
- `wrapTextByCharacterCount` in:
65+
- src/shared/utils/index.js
66+
- src/shared/utils/textWrapUtils.js
67+
- `xyInRect` in:
68+
- src/shared/utils/geometryUtils.js
69+
- src/shared/utils/index.js

‎docs/dev/reports/utils_folder_category_audit.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Utils Folder Category Audit
2+
3+
Utility files under src/engine/utils: 0
4+
5+
## Folder-Category Mismatches
6+
- none
7+
8+
## Remaining Literal src/engine/utils References
9+
Total literal references found: 11
10+
- docs/dev/codex_commands.md:11 :: Inspect src/shared/utils/** and any remaining src/engine/utils/**.
11+
- docs/dev/codex_commands.md:23 :: 4. every remaining literal reference to src/engine/utils/ and /src/engine/utils/
12+
- docs/pr/BUILD_PR_11_80_DEAD_UTILS_AUDIT.md:40 :: Exit non-zero if any stale `src/engine/utils/` or `/src/engine/utils/` references remain.
13+
- docs/pr/PLAN_PR_11_80_DEAD_UTILS_AUDIT.md:8 :: - Scan `src/shared/utils/**` and any remaining `src/engine/utils/**` utility files.
14+
- docs/pr/PLAN_PR_11_80_DEAD_UTILS_AUDIT.md:10 :: - Detect stale references to `src/engine/utils/` and `/src/engine/utils/`.
15+
- docs/pr/PLAN_PR_11_80_DEAD_UTILS_AUDIT.md:24 :: - `-Ci` exits non-zero only when stale `src/engine/utils/` references remain, not merely because dead candidates exist.
16+
- docs/pr/PR_11_81_UTILS_AUDIT_EXPANSION.md:16 :: - any remaining `src/engine/utils/**`
17+
- docs/pr/PR_11_81_UTILS_AUDIT_EXPANSION.md:68 :: - Remaining `src/engine/utils/` references are listed.
18+
- scripts/PS/audit-dead-utils.ps1:108 :: "/src/engine/utils/$baseName",
19+
- scripts/PS/audit-dead-utils.ps1:109 :: "/src/engine/utils/$moduleName"
20+
- scripts/PS/audit-dead-utils.ps1:152 :: $stalePatterns = @('src/engine/utils/', '/src/engine/utils/')

‎docs/pr/PR_11_81_UTILS_AUDIT_EXPANSION.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# PR 11.81 — Utils Audit Expansion
2+
3+
## Purpose
4+
Expand the existing dead-utils audit so Codex reports three things in one pass:
5+
6+
1. unused utility files/exports
7+
2. duplicate or near-duplicate utility exports across utility folders
8+
3. folder-category placement mismatches
9+
10+
This is report-only. Do not delete, move, or rewrite implementation files in this PR.
11+
12+
## Scope
13+
Inspect:
14+
15+
- `src/shared/utils/**`
16+
- any remaining `src/engine/utils/**`
17+
- imports and references across the repo
18+
19+
## Required output
20+
Create:
21+
22+
- `docs/dev/reports/utils_dead_usage_audit.md`
23+
- `docs/dev/reports/utils_duplicate_exports_audit.md`
24+
- `docs/dev/reports/utils_folder_category_audit.md`
25+
- `docs/dev/reports/utils_audit_summary.csv`
26+
27+
## Classification rules
28+
29+
### shared/utils
30+
Allowed:
31+
32+
- pure helpers
33+
- validation helpers
34+
- math helpers
35+
- color helpers
36+
- string/path helpers
37+
- object/array helpers
38+
- no engine runtime dependency
39+
40+
Not allowed:
41+
42+
- canvas/render-loop logic
43+
- game-state coupling
44+
- physics runtime coupling
45+
- input runtime coupling
46+
- sample-specific behavior
47+
48+
### engine/utils
49+
Allowed only when utility is proven engine-runtime specific.
50+
51+
If generic, classify as `move-to-shared`.
52+
53+
## Duplicate rules
54+
Flag:
55+
56+
- same export name in multiple utility files
57+
- same or near-same implementation body
58+
- pass-through wrappers
59+
- alias utilities
60+
- re-export chains used only to preserve old paths
61+
62+
Do not fix them in this PR. Report exact recommended action.
63+
64+
## Acceptance
65+
66+
- Reports exist.
67+
- No implementation files changed.
68+
- Remaining `src/engine/utils/` references are listed.
69+
- Duplicate exports are listed.
70+
- Folder category mismatches are listed.
71+
- Next PR can perform actual cleanup from the reports.

0 commit comments

Comments
 (0)