Skip to content

Commit 3e35a1f

Browse files
author
DavidQ
committed
Add report-only dead utils audit after shared utils consolidation - PR 11.80
1 parent 0212631 commit 3e35a1f

8 files changed

Lines changed: 388 additions & 5 deletions

File tree

‎docs/dev/codex_commands.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# Codex command - PR 11.78
1+
# Codex Commands - PR 11.80
22

33
Model: GPT-5.4
4-
Reasoning: medium
4+
Reasoning: high
55

6-
```text
7-
Run BUILD_PR_LEVEL_11_78_ENGINE_UTILS_REFERENCE_CLOSURE. Rewrite every remaining literal reference from src/engine/utils/ to src/shared/utils/, including leading-slash forms. Do not create aliases or shims. Fail the PR if any runtime/source references remain after verification.
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."
88
```

‎docs/dev/commit_comment.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Rewrite remaining engine utils references to shared utils - PR 11.78
1+
Add report-only dead utils audit after shared utils consolidation - PR 11.80

‎docs/dev/reports/dead_utils_audit.csv‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
"Kind","Path","Reason","ReferenceCount","Recommendation"
2+
"PotentialDeadUtility","src\shared\utils\directionUtils.js","No matching reference patterns found in src/samples/tools/games JS or repo HTML/JSON scan.","0","AuditAndConfirmBeforeDelete"
3+
"PotentialDeadUtility","src\shared\utils\fuzzyMatchScore.js","No matching reference patterns found in src/samples/tools/games JS or repo HTML/JSON scan.","0","AuditAndConfirmBeforeDelete"
4+
"PotentialDeadUtility","src\shared\utils\geometryUtils.js","No matching reference patterns found in src/samples/tools/games JS or repo HTML/JSON scan.","0","AuditAndConfirmBeforeDelete"
5+
"PotentialDeadUtility","src\shared\utils\idUtils.js","No matching reference patterns found in src/samples/tools/games JS or repo HTML/JSON scan.","0","AuditAndConfirmBeforeDelete"
6+
"PotentialDeadUtility","src\shared\utils\normalizeCommandTextUtils.js","No matching reference patterns found in src/samples/tools/games JS or repo HTML/JSON scan.","0","AuditAndConfirmBeforeDelete"
7+
"PotentialDeadUtility","src\shared\utils\textWrapUtils.js","No matching reference patterns found in src/samples/tools/games JS or repo HTML/JSON scan.","0","AuditAndConfirmBeforeDelete"
8+
"UtilityFile","src\shared\utils\arrayUtils.js","Reference pattern matched in configured scan roots.","5","Keep"
9+
"UtilityFile","src\shared\utils\createNoopDevConsoleIntegration.js","Reference pattern matched in configured scan roots.","2","Keep"
10+
"UtilityFile","src\shared\utils\debugConfigUtils.js","Reference pattern matched in configured scan roots.","3","Keep"
11+
"UtilityFile","src\shared\utils\directionUtils.js","No matching shared/engine utils path references found in configured scan roots.","0","ReviewForRemoval"
12+
"UtilityFile","src\shared\utils\fuzzyMatchScore.js","No matching shared/engine utils path references found in configured scan roots.","0","ReviewForRemoval"
13+
"UtilityFile","src\shared\utils\geometryUtils.js","No matching shared/engine utils path references found in configured scan roots.","0","ReviewForRemoval"
14+
"UtilityFile","src\shared\utils\highScoreUtils.js","Reference pattern matched in configured scan roots.","4","Keep"
15+
"UtilityFile","src\shared\utils\idUtils.js","No matching shared/engine utils path references found in configured scan roots.","0","ReviewForRemoval"
16+
"UtilityFile","src\shared\utils\index.js","Reference pattern matched in configured scan roots.","12","Keep"
17+
"UtilityFile","src\shared\utils\initialsEntryUtils.js","Reference pattern matched in configured scan roots.","3","Keep"
18+
"UtilityFile","src\shared\utils\invariantUtils.js","Reference pattern matched in configured scan roots.","3","Keep"
19+
"UtilityFile","src\shared\utils\jsonUtils.js","Reference pattern matched in configured scan roots.","29","Keep"
20+
"UtilityFile","src\shared\utils\mathUtils.js","Reference pattern matched in configured scan roots.","58","Keep"
21+
"UtilityFile","src\shared\utils\networkDebugUtils.js","Reference pattern matched in configured scan roots.","2","Keep"
22+
"UtilityFile","src\shared\utils\normalizeCommandTextUtils.js","No matching shared/engine utils path references found in configured scan roots.","0","ReviewForRemoval"
23+
"UtilityFile","src\shared\utils\numberUtils.js","Reference pattern matched in configured scan roots.","1","Keep"
24+
"UtilityFile","src\shared\utils\objectUtils.js","Reference pattern matched in configured scan roots.","22","Keep"
25+
"UtilityFile","src\shared\utils\runtimeRegistryUtils.js","Reference pattern matched in configured scan roots.","3","Keep"
26+
"UtilityFile","src\shared\utils\snapshotCloneUtils.js","Reference pattern matched in configured scan roots.","1","Keep"
27+
"UtilityFile","src\shared\utils\stringifyValueUtils.js","Reference pattern matched in configured scan roots.","2","Keep"
28+
"UtilityFile","src\shared\utils\stringUtils.js","Reference pattern matched in configured scan roots.","11","Keep"
29+
"UtilityFile","src\shared\utils\textWrapUtils.js","No matching shared/engine utils path references found in configured scan roots.","0","ReviewForRemoval"

‎docs/dev/reports/dead_utils_audit_validation.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# PR 11.80 Dead Utils Audit Validation
2+
3+
## Command run
4+
- `./scripts/PS/audit-dead-utils.ps1`
5+
6+
## Console output
7+
```text
8+
Dead utils audit complete.
9+
Utility files scanned: 22
10+
Potential dead utility files: 6
11+
Remaining engine-utils path references: 0
12+
Report: docs/dev/reports/dead_utils_audit.csv
13+
```
14+
15+
## Notes
16+
- Script executed once from repo root.
17+
- This PR is report-only; no utility files were moved or deleted.

‎docs/pr/BUILD_PR_11_80_DEAD_UTILS_AUDIT.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# BUILD_PR_11_80_DEAD_UTILS_AUDIT
2+
3+
## Codex task
4+
Add a new script:
5+
6+
`scripts/PS/audit-dead-utils.ps1`
7+
8+
## Required behavior
9+
10+
Run from repo root:
11+
12+
```powershell
13+
.\scripts\PS\audit-dead-utils.ps1
14+
```
15+
16+
Default output must be counts-first:
17+
18+
```text
19+
Dead utils audit complete.
20+
Utility files scanned: X
21+
Potential dead utility files: X
22+
Remaining engine-utils path references: X
23+
Report: docs/dev/reports/dead_utils_audit.csv
24+
```
25+
26+
With details:
27+
28+
```powershell
29+
.\scripts\PS\audit-dead-utils.ps1 -Details
30+
```
31+
32+
Print candidate paths and stale reference paths after the summary.
33+
34+
With CI:
35+
36+
```powershell
37+
.\scripts\PS\audit-dead-utils.ps1 -Ci
38+
```
39+
40+
Exit non-zero if any stale `src/engine/utils/` or `/src/engine/utils/` references remain.
41+
Do not fail CI for potential dead candidates yet; this PR is report-only for dead-code decisions.
42+
43+
## Scan rules
44+
45+
Utility roots:
46+
47+
- `src/shared/utils`
48+
- `src/engine/utils` if it still exists
49+
50+
Source search roots/files:
51+
52+
- `src/**/*.js`
53+
- `samples/**/*.js`
54+
- `tools/**/*.js`
55+
- `games/**/*.js`
56+
- `*.html`, `**/*.html`
57+
- `**/*.json`
58+
59+
Exclude:
60+
61+
- `.git`
62+
- `node_modules`
63+
- `docs/dev/reports`
64+
- `tmp`
65+
- generated ZIP/extract folders
66+
67+
For each utility file:
68+
69+
1. Determine basename, for example `invariant.js`.
70+
2. Determine extensionless module name, for example `invariant`.
71+
3. Search for import/path references containing:
72+
- `shared/utils/<basename>`
73+
- `shared/utils/<moduleName>`
74+
- `/src/shared/utils/<basename>`
75+
- `/src/shared/utils/<moduleName>`
76+
- old engine equivalents for reporting only
77+
4. Record candidate when no references are found outside the utility file itself.
78+
79+
## CSV columns
80+
81+
Write:
82+
83+
- `Kind`
84+
- `Path`
85+
- `Reason`
86+
- `ReferenceCount`
87+
- `Recommendation`
88+
89+
Kinds:
90+
91+
- `PotentialDeadUtility`
92+
- `RemainingEngineUtilsReference`
93+
- `UtilityFile`
94+
95+
## Guardrails
96+
97+
- No deletes.
98+
- No runtime import rewrites in this PR.
99+
- No wrappers/shims.
100+
- Keep script executable PowerShell only; no markdown/prose text inside the `.ps1` body except comments.

‎docs/pr/PLAN_PR_11_80_DEAD_UTILS_AUDIT.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# PLAN_PR_11_80_DEAD_UTILS_AUDIT
2+
3+
## Purpose
4+
Create a focused dead-utils audit after the engine/shared utils consolidation work.
5+
6+
## Scope
7+
- Add a report-only PowerShell audit script.
8+
- Scan `src/shared/utils/**` and any remaining `src/engine/utils/**` utility files.
9+
- Detect utility files that appear unreferenced by source, samples, tools, games, tests, HTML, and manifests.
10+
- Detect stale references to `src/engine/utils/` and `/src/engine/utils/`.
11+
- Emit counts-first console output and a CSV report.
12+
13+
## Non-goals
14+
- Do not delete utility files.
15+
- Do not move files.
16+
- Do not add alias, wrapper, or compatibility shim files.
17+
- Do not change runtime code unless needed to add the audit script to repo docs/scripts.
18+
19+
## Acceptance
20+
- Script runs from repo root.
21+
- Report is written to `docs/dev/reports/dead_utils_audit.csv`.
22+
- Console prints summary counts.
23+
- `-Details` dumps candidate paths.
24+
- `-Ci` exits non-zero only when stale `src/engine/utils/` references remain, not merely because dead candidates exist.

‎games/bouncing-ball/assets/images/background.png‎

2.17 MB
Loading

0 commit comments

Comments
 (0)