diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 7dc946d..5204a80 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -21,8 +21,8 @@ Requirements for the consolidation milestone. Each maps to roadmap phases. ### Code Quality -- [ ] **QUAL-01**: Duplicated FTS5 JOIN pattern (5+ copies) is consolidated into a single SQLite VIEW (track_metadata or similar) -- [ ] **QUAL-02**: Event name constants are generated from Go source (backend/events/events.go) to TypeScript (frontend/src/events.ts) via codegen, wired into go generate and pre-commit hook +- [x] **QUAL-01**: Duplicated FTS5 JOIN pattern (5+ copies) is consolidated into a single SQLite VIEW (track_metadata or similar) +- [x] **QUAL-02**: Event name constants are generated from Go source (backend/events/events.go) to TypeScript (frontend/src/events.ts) via codegen, wired into go generate and pre-commit hook - [ ] **QUAL-03**: Queue batch lookups in persistence.go use sqlc.slice() instead of fmt.Sprintf placeholder construction where feasible - [ ] **QUAL-04**: Intentional hand-crafted SQL exceptions (batch INSERT, dynamic IN clauses) are documented with // SAFETY: comments explaining why they bypass sqlc @@ -98,8 +98,8 @@ Which phases cover which requirements. Updated during roadmap creation. | CORR-07 | Phase 2: Backend Correctness | Complete | | CORR-08 | Phase 2: Backend Correctness | Complete | | CORR-09 | Phase 2: Backend Correctness | Complete | -| QUAL-01 | Phase 6: SQL Consolidation & Code Quality | Pending | -| QUAL-02 | Phase 6: SQL Consolidation & Code Quality | Pending | +| QUAL-01 | Phase 6: SQL Consolidation & Code Quality | Complete | +| QUAL-02 | Phase 6: SQL Consolidation & Code Quality | Complete | | QUAL-03 | Phase 6: SQL Consolidation & Code Quality | Pending | | QUAL-04 | Phase 6: SQL Consolidation & Code Quality | Pending | | PERF-01 | Phase 7: Backend Performance | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b17f2fd..d6ea4d9 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -57,7 +57,7 @@ Plans: 4. Tests using `NewTestDB` pass with `-race` flag enabled **Plans:** 1 plan Plans: -- [ ] 03-01-PLAN.md — Extract shared applyPRAGMAs, add production PRAGMAs, and create NewTestDB helper +- [x] 03-01-PLAN.md — Extract shared applyPRAGMAs, add production PRAGMAs, and create NewTestDB helper ### Phase 4: Queue, Config & Player Tests **Goal:** The queue, config, and player packages have comprehensive unit tests that characterize current behavior and serve as a safety net for later refactoring @@ -70,8 +70,8 @@ Plans: 4. All tests in this phase pass with `-race` flag enabled **Plans:** 2 plans Plans: -- [ ] 04-01-PLAN.md — Queue package unit tests (core operations, navigation, persistence roundtrip) -- [ ] 04-02-PLAN.md — Config + Player tests (sub-config validators, load/save roundtrip, volume conversion, state mapping) +- [x] 04-01-PLAN.md — Queue package unit tests (core operations, navigation, persistence roundtrip) +- [x] 04-02-PLAN.md — Config + Player tests (sub-config validators, load/save roundtrip, volume conversion, state mapping) ### Phase 5: Database & Library Tests **Goal:** Database queries (especially FTS5 search) and library scan logic have unit tests that lock down current behavior before SQL consolidation and performance optimization @@ -84,8 +84,8 @@ Plans: 4. All tests in this phase pass with `-race` flag enabled **Plans:** 2 plans Plans: -- [ ] 05-01-PLAN.md — FTS5 search tests, pure helper tests, search index operations, migration verification -- [ ] 05-02-PLAN.md — Entity cache tests, library pure helpers, orphan cleanup tests +- [x] 05-01-PLAN.md — FTS5 search tests, pure helper tests, search index operations, migration verification +- [x] 05-02-PLAN.md — Entity cache tests, library pure helpers, orphan cleanup tests ### Phase 6: SQL Consolidation & Code Quality **Goal:** Duplicated SQL patterns are eliminated, event names are provably synchronized between Go and TypeScript, and intentional SQL exceptions are documented @@ -98,8 +98,8 @@ Plans: 4. Every hand-crafted SQL statement that intentionally bypasses sqlc has a `// SAFETY:` comment explaining why (batch INSERT, dynamic IN clauses, etc.) **Plans:** 3 plans Plans: -- [ ] 06-01-PLAN.md — Create track_metadata VIEW and consolidate search queries -- [ ] 06-02-PLAN.md — Event codegen tool (Go→TypeScript) and pre-commit hook wiring +- [x] 06-01-PLAN.md — Create track_metadata VIEW and consolidate search queries +- [x] 06-02-PLAN.md — Event codegen tool (Go→TypeScript) and pre-commit hook wiring - [ ] 06-03-PLAN.md — Migrate lookupChunk to sqlc.slice() and add SAFETY comments to all hand-crafted SQL ### Phase 7: Backend Performance @@ -129,13 +129,13 @@ Plans: |-------|----------------|--------|-----------| | 1. Concurrency Race Fixes | 1/1 | Complete | 2026-02-28 | | 2. Backend Correctness | 2/2 | Complete | 2026-03-03 | -| 3. Test Infrastructure | 0/1 | Planned | — | -| 4. Queue, Config & Player Tests | 0/2 | Planned | — | -| 5. Database & Library Tests | 0/2 | Planned | — | -| 6. SQL Consolidation & Code Quality | 0/3 | Planned | — | +| 3. Test Infrastructure | 1/1 | Complete | 2026-03-04 | +| 4. Queue, Config & Player Tests | 2/2 | Complete | 2026-03-04 | +| 5. Database & Library Tests | 2/2 | Complete | 2026-03-04 | +| 6. SQL Consolidation & Code Quality | 2/3 | In Progress | — | | 7. Backend Performance | 0/? | Not started | — | | 8. Frontend Performance & UX | 0/? | Not started | — | --- *Roadmap created: 2026-02-27* -*Last updated: 2026-03-02* +*Last updated: 2026-03-05* diff --git a/.planning/STATE.md b/.planning/STATE.md index 1871e36..ec63b71 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,13 +2,13 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone -status: completed -last_updated: "2026-03-04T21:49:00.903Z" +status: in-progress +last_updated: "2026-03-05T00:23:19Z" progress: - total_phases: 5 + total_phases: 8 completed_phases: 5 - total_plans: 8 - completed_plans: 8 + total_plans: 11 + completed_plans: 10 --- # YellowJacket — Consolidation Milestone State @@ -16,17 +16,17 @@ progress: ## Project Reference **Core value:** The music player works reliably and feels solid — every interaction is correct, responsive, and trustworthy. -**Current focus:** Phase 5 complete — 15 database search tests + 13 library scan tests all passing with -race. +**Current focus:** Phase 6 in progress — track_metadata VIEW + event codegen complete, 1 plan remaining (SAFETY comments). **Milestone:** Consolidation (correctness, performance, code quality, UX polish, test coverage) ## Current Position -**Phase:** 05-database-library-tests (complete) -**Plan:** 2/2 (complete) -**Status:** Milestone complete +**Phase:** 06-sql-consolidation-code-quality (in progress) +**Plan:** 2/3 (06-01, 06-02 complete) +**Status:** In progress ``` -Phase Progress: [#####...] 5/8 phases complete +Phase Progress: [######..] 6/8 phases — Phase 6: 2/3 plans complete ``` ## Performance Metrics @@ -48,6 +48,8 @@ Phase Progress: [#####...] 5/8 phases complete | 05-02 duration | 4 min | | Phase 05 P01 | 9 min | 2 tasks | 1 files | | Phase 05 P02 | 4 min | 2 tasks | 1 files | +| Phase 06 P01 | 2 min | 2 tasks | 4 files | +| Phase 06 P02 | 2 min | 2 tasks | 3 files | ## Accumulated Context @@ -72,6 +74,8 @@ Phase Progress: [#####...] 5/8 phases complete | Volume roundtrip ±1 tolerance | ToUserVolume uses int truncation not rounding, causing up to 1 unit drift | Phase 4 | | Direct Library construction in tests | Bypasses Config.Validate os.Stat; entity cache functions only need ctx + db | Phase 5 | | Contentless FTS5 DELETE limitation | DeleteSearchIndex errors on content='' tables; production logs warning, stale entries are harmless | Phase 5 | +| SQLite VIEW for JOIN dedup | track_metadata VIEW consolidates 5-table JOIN; migration2 keeps inline JOIN for upgrade path | Phase 6 | +| AST-based event codegen | Iterate f.Decls directly for deterministic declaration-order output; atomic writes via temp+rename | Phase 6 | ### TODOs @@ -82,7 +86,7 @@ Phase Progress: [#####...] 5/8 phases complete - [x] Execute Phase 2 Plan 02 (complete) - [x] Plan Phase 3 (complete) - [x] Execute Phase 3 Plan 01 (complete) -- [ ] Validate sqlc + SQLite VIEW + FTS5 compatibility during Phase 6 planning (research flag) +- [x] Validate sqlc + SQLite VIEW + FTS5 compatibility during Phase 6 planning (validated — sqlc generates TrackMetadatum model, all tests pass) - [x] Design queue test architecture during Phase 4 planning (complete) - [x] Determine library scan test fixture strategy during Phase 5 planning (complete — inline construction, setupTestLibrary helper) - [ ] Measure startup time with large library before Phase 7 lazy loading work @@ -114,21 +118,20 @@ None currently. ### Last Session -**Date:** 2026-03-04 -**What happened:** Executed Phase 5 Plan 01 — FTS5 search tests (pure helpers, search queries, index ops, migrations) -**Where we stopped:** Completed 05-01-PLAN.md (all 2 tasks, verification passed). Phase 5 fully complete. -**Next action:** `/gsd-plan-phase 6` to plan SQL consolidation +**Date:** 2026-03-05 +**What happened:** Executed Phase 6 Plan 02 — Go→TypeScript event codegen tool with go/ast, fixing LibraryConfigChanged gap +**Where we stopped:** Completed 06-02-PLAN.md (2 tasks, all verification passed). Phase 6 plan 2/3 done. +**Next action:** `/gsd-execute-phase 06` to continue with 06-03-PLAN.md ### Context for Next Session -- Phase 5 complete: TEST-03 (15 database tests) + TEST-06 (13 library tests) requirements delivered -- 84 tests total: 29 queue + 27 config/player + 15 database search + 13 library scan, all passing with `-race` -- Contentless FTS5 limitation documented — DELETE fails on content='' tables -- QueryContext rows must be closed before next ExecContext on single-connection SQLite -- `codegen-check` lefthook pre-commit hook hangs — use `LEFTHOOK=0` for commits -- Ready for Phase 6 (SQL consolidation) +- Event codegen tool at backend/events/cmd/genevents/main.go +- LibraryConfigChanged gap automatically fixed by codegen +- `go generate ./...` completes in ~1.8s, codegen-check hook works end-to-end +- `codegen-check` pre-commit hook no longer hangs — can use LEFTHOOK=1 for commits +- Phase 6: 2/3 plans complete, SAFETY comments plan remaining --- *State initialized: 2026-02-27* -Last activity: 2026-03-04 - Completed 05-01: FTS5 search tests (helpers, queries, index ops, migrations) -*Last updated: 2026-03-04* +Last activity: 2026-03-05 - Completed 06-02: Go→TypeScript event codegen with go/ast and pre-commit hook +*Last updated: 2026-03-05* diff --git a/.planning/phases/06-sql-consolidation-code-quality/06-01-SUMMARY.md b/.planning/phases/06-sql-consolidation-code-quality/06-01-SUMMARY.md new file mode 100644 index 0000000..b5b87bc --- /dev/null +++ b/.planning/phases/06-sql-consolidation-code-quality/06-01-SUMMARY.md @@ -0,0 +1,102 @@ +--- +phase: 06-sql-consolidation-code-quality +plan: 01 +subsystem: database +tags: [sqlite, view, fts5, sql-consolidation, sqlc] + +# Dependency graph +requires: + - phase: 05-database-library-tests + provides: "15 FTS5 search tests as safety net for VIEW consolidation" +provides: + - "track_metadata VIEW consolidating 5-table metadata JOIN" + - "Migration 4 for existing databases" + - "sqlc schema awareness of track_metadata VIEW" +affects: [07-performance-startup-optimization, 08-frontend-polish-accessibility] + +# Tech tracking +tech-stack: + added: [] + patterns: ["SQLite VIEW for JOIN deduplication", "migration-backed VIEW creation"] + +key-files: + created: + - "backend/database/sql/schemas/track_metadata_view.sql" + modified: + - "backend/database/database.go" + - "backend/database/search.go" + - "backend/database/sql/sqlcgen/models.go" + +key-decisions: + - "VIEW uses CREATE VIEW IF NOT EXISTS for idempotent schema application" + - "migration2 inline JOIN preserved — runs before migration 4 for upgrade path" + +patterns-established: + - "SQLite VIEW as single source of truth for complex multi-table JOINs" + +requirements-completed: [QUAL-01] + +# Metrics +duration: 2min +completed: 2026-03-05 +--- + +# Phase 6 Plan 1: SQL Consolidation — track_metadata VIEW Summary + +**Consolidated 4 duplicated 5-table FTS5 JOINs into a single `track_metadata` SQLite VIEW with migration 4 and sqlc schema awareness** + +## Performance + +- **Duration:** 2 min +- **Started:** 2026-03-05T00:20:53Z +- **Completed:** 2026-03-05T00:23:19Z +- **Tasks:** 2 +- **Files modified:** 4 + +## Accomplishments +- Created `track_metadata` VIEW consolidating the 5-table audio metadata JOIN pattern +- Added migration 4 to create the VIEW for existing databases (user_version 3→4) +- Replaced all 4 inline JOINs in search.go (SearchFTS, SearchFTSByFilename, SearchFTSTracks, RebuildSearchIndex) with VIEW references +- All 15 existing FTS5 search tests pass unchanged with `-race` +- Net reduction: 60 lines of duplicated SQL eliminated + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Create track_metadata VIEW schema and migration** - `9c7e5a9` (feat) +2. **Task 2: Consolidate search queries to use track_metadata VIEW** - `9159b40` (refactor) + +## Files Created/Modified +- `backend/database/sql/schemas/track_metadata_view.sql` - VIEW definition for sqlc schema awareness +- `backend/database/database.go` - Migration 4 (track_metadata VIEW creation for existing databases) +- `backend/database/search.go` - All 4 search functions now use `JOIN track_metadata` instead of inline JOINs +- `backend/database/sql/sqlcgen/models.go` - sqlc-generated TrackMetadatum model from VIEW + +## Decisions Made +- VIEW uses `CREATE VIEW IF NOT EXISTS` for idempotent schema application (safe for both fresh and migrated databases) +- migration2 inline JOIN intentionally preserved — it runs at user_version=1→2 before the VIEW exists at version=3→4 +- TrackMetadatum sqlc model generated automatically but not used in Go code yet (available for future sqlc queries against the VIEW) + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered +None + +## User Setup Required +None - no external service configuration required. + +## Next Phase Readiness +- VIEW consolidation complete, search.go has zero duplicated JOINs +- Ready for remaining Phase 6 plans (code quality improvements) +- Track metadata VIEW available for future sqlc queries + +## Self-Check: PASSED + +All created files exist on disk. All commit hashes verified in git log. + +--- +*Phase: 06-sql-consolidation-code-quality* +*Completed: 2026-03-05*