Skip to content

Commit 2b31fec

Browse files
author
DavidQ
committed
PR_03_02_SHARED_STRINGS_EXTRACTION
1 parent 23cc5da commit 2b31fec

11 files changed

Lines changed: 143 additions & 49 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -8,38 +8,38 @@ MODEL: GPT-5.4
88
REASONING: high
99

1010
COMMAND:
11-
Implement PR_03_01_SHARED_NUMBERS_NORMALIZATION.
11+
Implement PR_03_02_SHARED_STRINGS_EXTRACTION.
1212

1313
Goal:
14-
Consolidate duplicated numeric helpers onto the shared math layer with no behavior or API changes.
14+
Consolidate duplicated string helpers onto the shared layer with no behavior or API changes.
1515

1616
Target layer:
17-
- src/shared/math/
17+
- src/shared/utils/
1818

1919
Focus helpers:
20-
- asFiniteNumber
21-
- asPositiveInteger
22-
- toFiniteNumber
23-
- roundNumber
20+
- normalizeString
21+
- safeTrim
22+
- toLowerSafe
23+
- stringCompare
2424

2525
Required steps:
26-
1. Produce docs/dev/reports/number_usage_scan.txt for numeric helper duplicates and consumers in scope.
26+
1. Produce docs/dev/reports/string_usage_scan.txt for string helper duplicates and consumers in scope.
2727
2. Produce docs/dev/reports/extraction_map.txt with exact source -> shared target mapping.
28-
3. Standardize consumers in scope onto shared numeric helpers.
29-
4. Remove only obsolete duplicate numeric helper implementations within this PR scope.
28+
3. Standardize consumers in scope onto shared string helpers.
29+
4. Remove only obsolete duplicate string helper implementations within this PR scope.
3030
5. Keep changes surgical.
3131

3232
Rules:
33-
- numeric helpers only
34-
- no string/id/object helper extraction
33+
- string helpers only
34+
- no number/id/object helper extraction
3535
- no broad cleanup
3636
- no API changes
3737
- no behavior changes
3838

3939
Validation:
4040
- impacted imports resolve
41-
- duplicate numeric helpers in scope removed or redirected
41+
- duplicate string helpers in scope removed or redirected
4242
- impacted tests/smoke pass
4343

4444
Return ZIP:
45-
<project folder>/tmp/PR_03_01_SHARED_NUMBERS_NORMALIZATION.zip
45+
<project folder>/tmp/PR_03_02_SHARED_STRINGS_EXTRACTION.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
PR_03_01_SHARED_NUMBERS_NORMALIZATION
1+
PR_03_02_SHARED_STRINGS_EXTRACTION

‎docs/dev/reports/change_summary.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Shared numeric helper consolidation package focused on canonicalizing numeric normalization utilities under src/shared/math.
1+
Shared string helper consolidation package focused on canonicalizing string normalization utilities under src/shared/utils.

‎docs/dev/reports/extraction_map.txt‎

Lines changed: 24 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,24 @@
1-
EXTRACTION MAP
2-
Generated: 2026-04-13
3-
Command: PR_03_01_SHARED_NUMBERS_NORMALIZATION
4-
5-
Source -> Shared Target Mapping
6-
- src/shared/utils/numberUtils.js::toFiniteNumber -> src/shared/math/numberNormalization.js::toFiniteNumber
7-
- src/shared/utils/numberUtils.js::asFiniteNumber -> src/shared/math/numberNormalization.js::asFiniteNumber
8-
- src/shared/utils/numberUtils.js::asPositiveInteger -> src/shared/math/numberNormalization.js::asPositiveInteger
9-
- src/shared/math/numberNormalization.js::roundNumber remains canonical owner
10-
11-
Compatibility Redirects
12-
- src/shared/utils/numberUtils.js keeps export surface and redirects numeric helper ownership to shared/math.
13-
- samples/_shared/numberUtils.js routes core numeric helpers to shared/math and keeps non-target helpers from shared/utils.
1+
PR_03_02_SHARED_STRINGS_EXTRACTION - extraction map
2+
3+
Canonical shared targets:
4+
- src/shared/utils/stringUtils.js::safeTrim
5+
- src/shared/utils/stringUtils.js::toLowerSafe
6+
- src/shared/utils/stringUtils.js::stringCompare
7+
- src/shared/utils/stringUtils.js::normalizeString (existing canonical export retained)
8+
9+
Source -> shared mapping:
10+
1) src/shared/utils/debugConfigUtils.js
11+
- local sanitizeText(value) -> safeTrim(value)
12+
- sanitizeText(value).toLowerCase() callsites -> toLowerSafe(value)
13+
14+
2) src/shared/utils/networkDebugUtils.js
15+
- local sanitizeText(value) -> safeTrim(value)
16+
- exported sanitizeText symbol redirected as:
17+
export const sanitizeText = safeTrim;
18+
19+
Backward-compatibility mapping retained in shared layer:
20+
- trimSafe(value) -> safeTrim(value)
21+
- sanitizeText(value) -> safeTrim(value)
22+
- normalizeString(value) -> safeTrim(value)
23+
24+
No API or behavior changes introduced for existing public exports.

‎docs/dev/reports/string_usage_scan.txt‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
PR_03_02_SHARED_STRINGS_EXTRACTION - string helper usage scan
2+
3+
Focused helper scan (src/, samples/, tools/, games/, tests/):
4+
- normalizeString
5+
- Definition: src/shared/utils/stringUtils.js:9 (pre-change)
6+
- Consumer(s): tools/shared/vectorTemplateSampleGame.js (multiple)
7+
- safeTrim
8+
- No pre-existing definition or usage in scan scope
9+
- toLowerSafe
10+
- No pre-existing definition or usage in scan scope
11+
- stringCompare
12+
- No pre-existing definition or usage in scan scope
13+
14+
Duplicate helper implementations in scoped shared utils:
15+
- src/shared/utils/debugConfigUtils.js
16+
- local sanitizeText(value) => typeof string ? trim : ''
17+
- consumer sites: parseBooleanFlag, normalizeDebugMode, isLocalDebugEnvironment, resolveDebugConfig
18+
- src/shared/utils/networkDebugUtils.js
19+
- local sanitizeText(value) => typeof string ? trim : ''
20+
- consumer sites: toSafeKey + commandLinesForTrace optional sanitizer fallback
21+
22+
Consolidation scope applied:
23+
- Shared canonical string helpers consolidated in src/shared/utils/stringUtils.js
24+
- In-scope duplicate local sanitize helpers replaced by shared helper usage in:
25+
- src/shared/utils/debugConfigUtils.js
26+
- src/shared/utils/networkDebugUtils.js
27+
28+
Out of scope:
29+
- Engine-level and tools/sample local sanitizeText duplicates are intentionally unchanged in this PR.

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
[ ] number_usage_scan.txt generated
1+
[ ] string_usage_scan.txt generated
22
[ ] extraction_map.txt generated
3-
[ ] numeric helpers consolidated to src/shared/math
3+
[ ] string helpers consolidated to src/shared/utils
44
[ ] no API changes
55
[ ] no behavior changes
66
[ ] impacted imports resolve

‎docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@
117117
- [x] `src/shared/state`
118118
- [x] `games/_template/flow`
119119
- [ ] `samples/phase-01`
120-
- [ ] `samples/phase-13_network-concepts`
120+
- [ ] `samples/phase-13`
121121
- [x] `tools/shared`
122122

123123
### Recent Checkpoint Notes

‎docs/pr/PR_03_02_SHARED_STRINGS_EXTRACTION.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# PR_03_02_SHARED_STRINGS_EXTRACTION
2+
3+
## Purpose
4+
Normalize duplicated string helper usage into the shared layer.
5+
6+
## Scope
7+
- string helper consolidation only
8+
- no behavior changes
9+
- no API changes
10+
- no non-string helper extraction
11+
12+
## Target Layer
13+
- src/shared/utils/
14+
15+
## Required Work
16+
1. Inventory active string helpers duplicated across the repo within this PR scope.
17+
2. Build an exact extraction map for string helpers moving to or standardizing on `src/shared/utils/`.
18+
3. Consolidate existing consumers onto shared string helpers.
19+
4. Remove only the duplicated local string helper implementations made obsolete by this consolidation.
20+
5. Keep changes surgical and execution-backed.
21+
22+
## Candidate Focus
23+
- normalizeString
24+
- safeTrim
25+
- toLowerSafe
26+
- stringCompare
27+
28+
## Constraints
29+
- no broad repo scan beyond string-helper consumers needed for this PR
30+
- no number/id/object helper work in this PR
31+
- no engine logic refactors
32+
- no sample/game/tool behavior changes
33+
- preserve public contracts
34+
35+
## Deliverables
36+
- docs/dev/reports/string_usage_scan.txt
37+
- docs/dev/reports/extraction_map.txt
38+
- docs/dev/reports/validation_checklist.txt
39+
40+
## Validation
41+
- shared string helpers are canonical for this PR scope
42+
- consumers in scope resolve to shared string helpers
43+
- no duplicate string helper remains in moved scope
44+
- tests/smoke in impacted scope pass
45+
46+
## Output
47+
<project folder>/tmp/PR_03_02_SHARED_STRINGS_EXTRACTION.zip

‎src/shared/utils/debugConfigUtils.js‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,10 @@
1+
import { safeTrim, toLowerSafe } from './stringUtils.js';
12
const BUILD_DEBUG_MODE = 'prod';
23
const BUILD_DEBUG_ENABLED = false;
34
const DEBUG_STATE_STORAGE_KEY = 'toolbox.sample.asteroids.debug.enabled';
45

5-
function sanitizeText(value) {
6-
return typeof value === 'string' ? value.trim() : '';
7-
}
8-
96
export function parseBooleanFlag(value, fallback) {
10-
const normalized = sanitizeText(value).toLowerCase();
7+
const normalized = toLowerSafe(value);
118
if (!normalized) {
129
return fallback;
1310
}
@@ -21,7 +18,7 @@ export function parseBooleanFlag(value, fallback) {
2118
}
2219

2320
export function normalizeDebugMode(value, fallback = 'prod') {
24-
const normalized = sanitizeText(value).toLowerCase();
21+
const normalized = toLowerSafe(value);
2522
if (normalized === 'dev' || normalized === 'qa' || normalized === 'prod') {
2623
return normalized;
2724
}
@@ -61,8 +58,8 @@ export function writeStoredBoolean(key, value) {
6158
}
6259

6360
export function isLocalDebugEnvironment(documentRef) {
64-
const protocol = sanitizeText(documentRef?.location?.protocol) || sanitizeText(globalThis?.location?.protocol);
65-
const hostname = sanitizeText(documentRef?.location?.hostname) || sanitizeText(globalThis?.location?.hostname);
61+
const protocol = safeTrim(documentRef?.location?.protocol) || safeTrim(globalThis?.location?.protocol);
62+
const hostname = safeTrim(documentRef?.location?.hostname) || safeTrim(globalThis?.location?.hostname);
6663

6764
if (protocol === 'file:') {
6865
return true;
@@ -72,7 +69,7 @@ export function isLocalDebugEnvironment(documentRef) {
7269
}
7370

7471
export function resolveDebugConfig(documentRef) {
75-
const search = sanitizeText(documentRef?.location?.search) || sanitizeText(globalThis?.location?.search);
72+
const search = safeTrim(documentRef?.location?.search) || safeTrim(globalThis?.location?.search);
7673
const searchParams = new URLSearchParams(search);
7774
const queryMode = searchParams.get('debugMode');
7875
const queryEnabled = searchParams.get('debug');

‎src/shared/utils/networkDebugUtils.js‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,13 @@
11
import { asNumber } from "../math/numberNormalization.js";
22
import { asObject, asArray } from "./objectUtils.js";
3-
4-
function sanitizeText(value) {
5-
return typeof value === "string" ? value.trim() : "";
6-
}
3+
import { safeTrim } from "./stringUtils.js";
74

85
function toSafeKey(value) {
9-
return sanitizeText(value);
6+
return safeTrim(value);
107
}
118

129
export { asNumber };
10+
export const sanitizeText = safeTrim;
1311

1412
export function toNetworkSnapshot(snapshot) {
1513
const sampleKey = arguments[1];

0 commit comments

Comments
 (0)