From 5518676170ce4d233defb2f4e508175c76d162a2 Mon Sep 17 00:00:00 2001 From: tiennm99 Date: Sun, 30 Aug 2026 20:52:41 +0700 Subject: [PATCH] chore: session plan and agent memory Record structure refactor plan and quality-gates analysis for future reference. --- .../project-quality-gates-blind-spots.md | 6 +++ plans/260830-2023-structure-refactor/plan.md | 37 +++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 plans/260830-2023-structure-refactor/plan.md diff --git a/.claude/agent-memory/code-reviewer/project-quality-gates-blind-spots.md b/.claude/agent-memory/code-reviewer/project-quality-gates-blind-spots.md index 023f286..7d7192e 100644 --- a/.claude/agent-memory/code-reviewer/project-quality-gates-blind-spots.md +++ b/.claude/agent-memory/code-reviewer/project-quality-gates-blind-spots.md @@ -28,6 +28,12 @@ ten setter call sites surviving green). Lint currently emits 4 pre-existing `is_pano` field that is only a build-time filter (open the generated data and look at an actual record). +- `README.md` is outside the doc-update habit. Verified 2026-08-30: the six + `/docs/` files were rewritten for the region tree while README still described + "5 Vietnamese locations" incl. Da Lat/Duc Hoa as top-level, "In-memory + sessions" (they are Redis), and Node 18+ against `engines: >=24`. Check README + explicitly on any docs pass; it is never reached by editing `/docs/`. + **How to apply:** when a diff removes or renames state, props, helpers, or imports, grep the whole file. For any React change, state plainly in the report which criteria are runtime-only. For any doc change, verify each load-bearing diff --git a/plans/260830-2023-structure-refactor/plan.md b/plans/260830-2023-structure-refactor/plan.md new file mode 100644 index 0000000..3375303 --- /dev/null +++ b/plans/260830-2023-structure-refactor/plan.md @@ -0,0 +1,37 @@ +# Behavior-Preserving Structure Refactor + +Status: done (all 6 phases; @/ alias conversion skipped — vitest has no alias +config, conversion would break test imports for no functional gain) | Branch: +main | Source: structure review 2026-08-30 +Validated: eslint 0 errors/0 warnings, 258/258 tests, build:check green, +src/data diff empty. + +Contract: improve structure per review; zero behavior change (wire responses, +UI copy/classes, score thresholds, generated data all identical). Excluded as +behavior changes: new-game 200-status fix, new-game POST removal, result-copy +consolidation, Upstash pipelining, skip-race/error-state fixes. + +## Phases + +1. **Split `src/lib/game.js` by layer** — keep scoring (`SCORE_BANDS`, + `calculateScore`, `calculateDistance`, `formatDistance`); new + `src/lib/username.js` (localStorage, mirrors `theme.js`); presentation + helpers move to their single consumers. Thresholds/strings verbatim. +2. **Decompose `GameClient.js`** — extract `ResultMap.js`, + `RoundResultDialog.js`, `GuessMapPanel.js`; collapse 8 result fields into + one `result` object. Retry loop dies with the conditional container. +3. **Extract `LeaderboardModal.js`** from `page.js`; drop the + `exhaustive-deps` suppression via `useCallback`. +4. **Invert client-safety test** — walk from every `'use client'` file, + assert none reaches `data/panos`, `pano-index`, `data/boundaries`. + Server-only header added to boundaries generator (lands on next regen). +5. **Pipeline tooling** — `scripts/lib/paths.mjs` (import.meta.url-based), + `scripts/lib/barrel.mjs` (shared emitter + byte-identity test vs current + generated barrels), npm scripts `data:boundaries|panos|districts`. +6. **Mechanical** — lint → `eslint .` + ignores, fix 4 warnings, `@/` alias, + delete `tabs.jsx` + dead code + `allowScripts`, README refresh, docs drift. + +Validation per phase: `npm test`; final: lint + `npm run build:check` + +`git diff --stat src/data` (must be empty). + +Rollback: each phase is an independent commit-sized unit; revert file moves.