docs(typescript): add comprehensive verification checklist for conversion plan

2026-02-18 16:38:13 -05:00
parent d709510a28
commit 364de1ee93
1 changed files with 781 additions and 0 deletions
@@ -0,0 +1,781 @@
+# TypeScript Conversion Plan Verification Checklist
+
+Use this checklist to comprehensively audit the TypeScript Conversion Plan in a single pass. Each item includes verification steps to confirm accuracy.
+
+---
+
+## 1. Type Definition Verification
+
+### 1.1 Verify All Types Match Actual API Responses
+
+**For each type definition in `web/src/types/api.d.ts` (planned):**
+
+- [ ] Locate the API endpoint in `internal/handlers/*.go`
+- [ ] Check what the endpoint **actually returns** (return statement)
+- [ ] Determine if it returns:
+  - Handler-defined struct (e.g., `handlers.BookInfo`)
+  - Database row (e.g., `database.SearchMediaItemsRow`)
+  - Map/slice of either
+- [ ] Find the source type definition:
+  - Handler structs: `internal/handlers/*.go`
+  - Database rows: `internal/database/queries.sql.go`
+- [ ] Verify all JSON tags match TypeScript interface fields (snake_case)
+- [ ] Map pgtype fields to TypeScript types:
+  - `pgtype.Text` → `string | undefined`
+  - `pgtype.UUID` → `string`
+  - `pgtype.Timestamp` → `string` (ISO datetime)
+  - `pgtype.Numeric` → `number` or `string`
+  - `pgtype.Bool` → `boolean`
+  - `[]string` → `string[]`
+
+**Common Pitfalls:**
+- Handler structs may be defined but unused (e.g., `search.go`'s `MediaItemSummary`)
+- Endpoints may return database rows directly, not handler structs
+- JSON tags may use snake_case while Go fields use PascalCase
+- Arrays vs single values (e.g., `author` string vs `authors` array)
+
+**Verification Commands:**
+```bash
+# Find endpoint implementation
+rg "func.*SearchMediaItems" internal/handlers/
+
+# Check return type
+rg -A 10 "func.*SearchMediaItems" internal/handlers/media.go | grep "return c.JSON"
+
+# Find type definition
+rg "type SearchMediaItemsRow struct" internal/database/queries.sql.go
+
+# Check JSON tags
+rg 'json:"' internal/database/queries.sql.go | grep "SearchMediaItemsRow"
+```
+
+### 1.2 Verify No Duplicate/Conflicting Type Definitions
+
+- [ ] No two TypeScript interfaces describe the same API response
+- [ ] No interface fields contradict actual JSON response
+- [ ] No unused handler structs are referenced in type comments
+- [ ] All inline types in `.ts` files could move to `types/api.d.ts`
+
+---
+
+## 2. API Contract Verification
+
+### 2.1 Verify All API Endpoints Referenced in Plan Exist
+
+**For each endpoint mentioned:**
+
+- [ ] Endpoint exists in `internal/handlers/*.go`
+- [ ] Route is registered in routing code
+- [ ] HTTP method matches (GET/POST/PUT/DELETE)
+- [ ] Response format matches plan's type definitions
+- [ ] Authentication requirements match plan assumptions
+
+**Check Commands:**
+```bash
+# Find endpoint definition
+rg "POST.*collections.*rules" internal/handlers/
+
+# Check route registration
+rg "collections.*rules" cmd/server/ or internal/router/
+```
+
+### 2.2 Verify Authentication Patterns
+
+- [ ] All API endpoints that require auth are documented
+- [ ] Token storage approach matches (`localStorage.getItem('token')`)
+- [ ] Auth header format consistent (`Bearer ${token}`)
+- [ ] 401 handling documented (token clearing, redirect)
+
+### 2.3 Verify Error Response Formats
+
+- [ ] Error responses use consistent structure (`{"error": "message"}`)
+- [ ] Toast integration documented for all error cases
+- [ ] Network error handling documented
+- [ ] Validation error handling documented (400 responses)
+
+---
+
+## 3. Cross-Reference Verification
+
+### 3.1 Template-Handler Type Sharing
+
+**For each template that imports handlers:**
+
+- [ ] Template imports `internal/handlers` package
+- [ ] Template uses handler types for SSR data (e.g., `handlers.BookInfo`)
+- [ ] TypeScript interfaces match the same handler JSON responses
+- [ ] No duplicate type definitions between handlers and templates
+- [ ] Template-only types are clearly marked (e.g., `PageData`, `UnsafeHTML`)
+
+**Verification:**
+```bash
+# Find templates importing handlers
+rg 'import.*handlers' templates/*.templ
+
+# Check handler type usage in templates
+rg 'handlers\.(CollectionData|BookInfo|UserProfile)' templates/*.templ
+```
+
+### 3.2 Existing TypeScript Module Patterns
+
+**Verify all existing `.ts` modules follow documented patterns:**
+
+- [ ] Procedural style (no classes, no `this`)
+- [ ] Functions exported to `window` object
+- [ ] No ES module imports/exports (browser globals)
+- [ ] Proper type annotations (`import type` for type-only imports)
+- [ ] Consistent error handling with toast integration
+
+**Check existing modules:**
+- `web/src/toast.ts`
+- `web/src/theme.ts`
+- `web/src/header.ts`
+- `web/src/device-management.ts`
+
+### 3.3 JavaScript to TypeScript Mapping
+
+**For each inline script in templates:**
+
+- [ ] Identify all `<script>` blocks in templates
+- [ ] Count total lines of inline JavaScript
+- [ ] Verify plan's line count estimates are accurate
+- [ ] Check for duplicate functionality (e.g., login.templ theme code vs theme.ts)
+- [ ] Verify no critical functionality is missed in conversion plan
+
+**Verification Commands:**
+```bash
+# Count script blocks
+rg '<script>' templates/*.templ | wc -l
+
+# Count inline JS lines
+rg '<script>' templates/*.templ -A 100 | grep -v '^--$' | wc -l
+
+# Find duplicate functions
+rg "function applyTheme" templates/*.templ web/src/*.ts
+```
+
+---
+
+## 4. Architecture Verification
+
+### 4.1 Verify Hybrid SSR Architecture Preserved
+
+**For each feature conversion:**
+
+- [ ] Initial page load uses SSR (Go templates with data)
+- [ ] TypeScript only handles CRUD operations (create, update, delete)
+- [ ] No new HTML endpoints needed (use existing `/api/*` endpoints)
+- [ ] Service layer remains source of truth
+- [ ] No handler duplication between SSR and API
+
+**Check:**
+```bash
+# Verify templates use handler data
+rg 'CollectionData\|BookInfo\|UserProfile' templates/*.templ
+
+# Verify API endpoints exist
+rg 'GET.*collections\|POST.*collections' internal/handlers/
+```
+
+### 4.2 Verify Progressive Enhancement
+
+**For each form/user flow:**
+
+- [ ] Form has `action` and `method` attributes
+- [ ] Form submits correctly without JavaScript (test in browser)
+- [ ] HTMX attributes enhance but don't replace standard behavior
+- [ ] Critical paths work without JS (login, create, update, delete)
+- [ ] TypeScript interception is optional enhancement, not requirement
+
+**Test Procedure:**
+1. Open DevTools → Disable JavaScript
+2. Navigate to page
+3. Verify form submits with full page reload
+4. Re-enable JavaScript
+5. Verify enhanced behavior works
+
+### 4.3 Verify No Backend Modifications for Frontend Tasks
+
+**For each TypeScript module:**
+
+- [ ] Only uses existing API endpoints
+- [ ] No new handler functions needed
+- [ ] No database schema changes needed
+- [ ] No migration files needed
+- [ ] All functionality achievable with current API
+
+**Red Flags:**
+- Plan mentions "need to add endpoint for..."
+- TypeScript code requires new backend structure
+- Data transformation needed in handler
+
+---
+
+## 5. Build & Deployment Verification
+
+### 5.1 Verify TypeScript Configuration
+
+- [ ] `tsconfig.json` exists and is correctly configured
+- [ ] `module: "none"` for browser globals
+- [ ] `outDir: "./web/static"` for flat output
+- [ ] `rootDir: "./web/src"` for source organization
+- [ ] `strict: true` for type safety
+- [ ] `.d.ts` files don't generate JS output
+- [ ] Source maps configured appropriately
+
+**Check:**
+```bash
+# Verify tsconfig.json
+cat tsconfig.json
+
+# Test compilation
+npm run build:ts
+
+# Check output
+ls -la web/static/*.js
+```
+
+### 5.2 Verify Build Scripts
+
+- [ ] `package.json` has correct build scripts
+- [ ] `npm run build:ts` compiles TypeScript
+- [ ] `npm run build:ts:watch` for development
+- [ ] No additional bundlers needed (webpack, vite, etc.)
+- [ ] Build output matches plan's expectations
+
+**Check:**
+```bash
+# Verify scripts
+cat package.json | grep -A 5 '"scripts"'
+
+# Test build
+npm run build:ts
+
+# Verify output structure
+ls -la web/static/
+```
+
+### 5.3 Verify Docker/Podman Integration
+
+- [ ] TypeScript compilation happens during Docker build
+- [ ] No local binary builds needed
+- [ `.gitignore` excludes `.js` files but includes `.ts` files
+- [ ] Production build includes minified CSS
+
+**Check:**
+```bash
+# Check Dockerfile
+rg "npm run build" Dockerfile
+
+# Check .gitignore
+rg "\.js$" .gitignore
+```
+
+---
+
+## 6. Phase Dependency Verification
+
+### 6.1 Verify Phase Ordering
+
+**For each phase:**
+
+- [ ] All dependencies are completed in previous phases
+- [ ] No circular dependencies between phases
+- [ ] Core utilities (Phase 2) before feature modules (Phases 3-5)
+- [ ] Standalone files (Phase 1) before inline conversion
+- [ ] Template cleanup (Phase 6) after all conversions complete
+
+**Check dependency graph:**
+```
+Phase 1 (search.js) → No dependencies ✓
+Phase 2 (utils) → No dependencies ✓
+Phase 3 (low complexity) → Needs Phase 2 ✓
+Phase 4 (medium complexity) → Needs Phase 2, 3 ✓
+Phase 5 (high complexity) → Needs Phase 4 ✓
+Phase 6 (cleanup) → Needs all phases ✓
+```
+
+### 6.2 Verify Phase Completeness
+
+**For each phase:**
+
+- [ ] All deliverables are listed
+- [ ] All files to create/delete/update are specified
+- [ ] Build verification steps are included
+- [ ] Testing steps are documented
+- [ ] Rollback strategy is mentioned
+
+### 6.3 Verify Timeline Estimates
+
+**For each phase:**
+
+- [ ] Effort estimates are realistic
+- [ ] Line counts match actual code
+- [ ] Total duration is achievable (16-21 days)
+- [ ] No phase exceeds 6 days (break down if needed)
+
+---
+
+## 7. Code Style Verification
+
+### 7.1 Verify Procedural Style Compliance
+
+**Check all proposed code examples:**
+
+- [ ] No classes used
+- [ ] No `this` references
+- [ ] No inheritance
+- [ ] Functions are standalone, not methods
+- [ ] State is in variables/parameters, not properties
+- [ ] Event delegation used where appropriate
+
+**Examples should follow:**
+```typescript
+// ✅ GOOD: Procedural
+function deleteRule(ruleId: string): void {
+    // implementation
+}
+window.deleteRule = deleteRule;
+
+// ❌ BAD: OOP
+class RuleManager {
+    deleteRule(ruleId: string): void {
+        // implementation
+    }
+}
+```
+
+### 7.2 Verify Event Handler Patterns
+
+**Check appropriate use of:**
+
+- [ ] `onclick` for simple static content
+- [ ] `data-action` + event delegation for dynamic content
+- [ ] Form interception for progressive enhancement
+- [ ] No over-engineering (not everything needs data-action)
+
+**Plan should include:**
+- When to use each pattern
+- Examples of each pattern
+- Rationale for pattern selection
+
+### 7.3 Verify TailwindCSS Usage
+
+- [ ] No custom CSS in TypeScript files
+- [ ] All styling uses Tailwind classes
+- [ ] No inline `style` attributes except for dynamic values
+- [ ] Theme variables used appropriately (`var(--bg-primary)`, etc.)
+
+---
+
+## 8. Documentation Verification
+
+### 8.1 Verify Type Definition Documentation
+
+**For each type in `web/src/types/api.d.ts`:**
+
+- [ ] Comment references source file (database or handler)
+- [ ] Comment includes line numbers or struct name
+- [ ] Fields have inline comments if purpose unclear
+- [ ] Complex types have usage examples
+
+**Example:**
+```typescript
+// Matches database.SearchMediaItemsRow from /api/media-items/search
+// Source: internal/database/queries.sql.go:SearchMediaItemsRow
+// Used in: search.ts
+export interface MediaItemSummary {
+    id: string;
+    title: string;
+    // ...
+}
+```
+
+### 8.2 Verify Code Example Accuracy
+
+**For each code example in plan:**
+
+- [ ] Code actually compiles/runs
+- [ ] Imports are correct for module system
+- [ ] Type annotations match actual types
+- [ ] Variable names match plan's conventions
+- [ ] No syntax errors
+
+**Test by:**
+- Copying example to actual `.ts` file
+- Running `npm run build:ts`
+- Checking for compilation errors
+
+### 8.3 Verify Template Examples
+
+**For each template example:**
+
+- [ ] Valid Go template syntax (`templ` not `html`)
+- [ ] Correct handler type references
+- [ ] Script tags use correct paths
+- [ ] No inline JavaScript (after conversion)
+- [ ] HTMX attributes are correct
+
+---
+
+## 9. Template Integration Verification
+
+### 9.1 Verify Template Cleanup Tasks
+
+**For each template mentioned in Phase 6:**
+
+- [ ] Current template file exists
+- [ ] Line numbers for duplicate code are accurate
+- [ ] Removal won't break functionality
+- [ ] Replacement TypeScript module exists
+- [ ] Script tag added to template `<head>`
+
+**Verify specific tasks:**
+- [ ] login.templ lines 62-88 (duplicate theme code)
+- [ ] Any other duplicate function calls
+- [ ] Any unused inline script blocks
+
+**Check:**
+```bash
+# Find duplicate theme code
+rg "function applyTheme" templates/login.templ web/src/theme.ts
+
+# Count script blocks per template
+rg '<script>' templates/login.templ -c
+```
+
+### 9.2 Verify SSR Data Preservation
+
+**For each template conversion:**
+
+- [ ] Initial data still rendered server-side
+- [ ] Template still uses handler types (e.g., `handlers.CollectionData`)
+- [ ] No client-side data fetching for initial load
+- [ ] TypeScript only enhances, doesn't replace SSR
+
+**Example check:**
+```go
+// ✅ CORRECT: Template receives data from handler
+templ Collections(collections []handlers.CollectionData)
+
+// ❌ WRONG: Template fetches data client-side
+// This would break progressive enhancement
+```
+
+---
+
+## 10. Progressive Enhancement Verification
+
+### 10.1 Verify Critical User Flows
+
+**For each critical flow (login, CRUD operations):**
+
+- [ ] Works without JavaScript (standard form submission)
+- [ ] Enhanced with JavaScript (AJAX, toasts, etc.)
+- [ ] No JavaScript required for basic functionality
+- [ ] Graceful degradation for mobile/slow connections
+
+**Test procedure:**
+1. Disable JavaScript in browser
+2. Attempt each critical flow
+3. Verify functionality works (with page reloads)
+4. Enable JavaScript
+5. Verify enhanced experience
+
+### 10.2 Verify HTMX Usage
+
+**For each HTMX form:**
+
+- [ ] Has `action` and `method` attributes (fallback)
+- [ ] HTMX attributes (`hx-post`, `hx-target`, etc.) enhance behavior
+- [ ] No TypeScript interception needed (HTMX handles it)
+- [ ] Works without JavaScript enabled
+
+**Check:**
+```bash
+# Find HTMX forms
+rg 'hx-post|hx-get' templates/*.templ
+
+# Verify standard attributes exist
+rg '<form' templates/*.templ -A 3 | grep "action="
+```
+
+### 10.3 Verify Error Handling
+
+**For error scenarios:**
+
+- [ ] Network errors show toast notification
+- [ ] 401 errors clear tokens and redirect
+- [ ] 404/500 errors display user-friendly messages
+- [ ] Validation errors (400) show field-specific feedback
+- [ ] No console errors in normal operation
+
+---
+
+## 11. Missing Information Detection
+
+### 11.1 Check for Unaddressed Template Scripts
+
+**For each template with `<script>` blocks:**
+
+- [ ] Script is mentioned in conversion plan
+- [ ] Conversion phase is specified
+- [ ] TypeScript module is planned
+- [ ] No inline JavaScript is overlooked
+
+**Find all scripts:**
+```bash
+# List all templates with scripts
+rg '<script>' templates/*.templ -l
+
+# Count scripts per template
+rg '<script>' templates/*.templ -c
+```
+
+### 11.2 Check for Missing API Endpoints
+
+**For each TypeScript operation mentioned:**
+
+- [ ] API endpoint exists
+- [ ] Endpoint is documented in plan
+- [ ] Type definition matches endpoint response
+- [ ] Authentication requirements are clear
+
+**Find all fetch calls:**
+```bash
+# Find fetch in plan
+rg "fetch\(" TYPESCRIPT_CONVERSION_PLAN.md | grep "/api/"
+```
+
+### 11.3 Check for Missing Build Steps
+
+**Verify plan includes:**
+
+- [ ] TypeScript compilation command
+- [ ] Watch mode command for development
+- [ ] Production build steps
+- [ ] Docker integration
+- [ ] Verification steps after build
+
+---
+
+## 12. Contradiction Detection
+
+### 12.1 Check for Internal Contradictions
+
+**Search for conflicting statements:**
+
+- [ ] Architecture described differently in different sections
+- [ ] Type definitions that contradict each other
+- [ ] Phase ordering that conflicts with dependencies
+- [ ] Code style examples that violate guidelines
+
+**Common contradictions:**
+- "No classes" but example shows class
+- "Use snake_case" but example uses camelCase
+- "Progressive enhancement required" but form lacks action attribute
+- "Don't modify backend" but plan suggests new endpoint
+
+### 12.2 Check for Contradictions with Codebase
+
+**Verify plan matches reality:**
+
+- [ ] Existing TypeScript files match plan's patterns
+- [ ] Build configuration matches plan's description
+- [ ] Template structure matches plan's assumptions
+- [ ] API endpoints match plan's documentation
+
+**Cross-check:**
+```bash
+# Verify existing TS patterns
+rg "class " web/src/*.ts
+# Should return nothing if plan is correct
+
+# Verify build config
+rg "module.*none" tsconfig.json
+# Should match plan
+```
+
+### 12.3 Check for Contradictions with Guidelines
+
+**Compare with PROJECT_GUIDELINES.md:**
+
+- [ ] No OOP in TypeScript (procedural only)
+- [ ] Use TailwindCSS (no custom CSS)
+- [ ] Progressive enhancement required
+- [ ] SSR for initial loads
+- [ ] Service layer as source of truth
+- [ ] No handler duplication
+
+---
+
+## 13. Realism Verification
+
+### 13.1 Verify Line Count Estimates
+
+**For each template/script mentioned:**
+
+- [ ] Count actual lines in file
+- [ ] Compare to plan's estimate
+- [ ] Estimate is within ±20% of actual
+
+**Count lines:**
+```bash
+# Count inline JS in template
+rg -A 1000 '<script>' templates/collection_rules.templ | wc -l
+
+# Count total template lines
+wc -l templates/*.templ
+```
+
+### 13.2 Verify Phase Duration Estimates
+
+**For each phase:**
+
+- [ ] Effort matches complexity (low = 1-2 days, medium = 3-4, high = 5-6)
+- [ ] Total lines to convert justify duration
+- [ ] Phase dependencies don't create bottlenecks
+- [ ] Parallel work is possible where stated
+
+### 13.3 Verify Technical Feasibility
+
+**Check for over-ambitious goals:**
+
+- [ ] No entirely new architecture proposed
+- [ ] No unproven technologies
+- [ ] No breaking changes to existing systems
+- [ ] Rollback is possible if conversion fails
+- [ ] Testing is feasible within timeline
+
+---
+
+## 14. Testing Verification
+
+### 14.1 Verify Testing Strategy
+
+**Plan should include:**
+
+- [ ] Unit testing approach (if applicable)
+- [ ] Integration testing approach
+- [ ] Manual testing checklist
+- [ ] Browser testing matrix
+- [ ] Progressive enhancement testing
+- [ ] Performance testing (bundle sizes)
+
+### 14.2 Verify Test Coverage
+
+**For each converted feature:**
+
+- [ ] Test steps are documented
+- [ ] Success criteria are defined
+- [ ] Edge cases are considered
+- [ ] Error cases are tested
+- [ ] Progressive enhancement is verified
+
+### 14.3 Verify Rollback Strategy
+
+**For each phase:**
+
+- [ ] Git branch strategy is defined
+- [ ] Quick rollback procedure is documented
+- [ ] Feature flags or gradual rollout possible
+- [ ] No destructive changes until verified
+
+---
+
+## 15. Success Criteria Verification
+
+### 15.1 Verify All Success Criteria are Measurable
+
+**For each success criterion:**
+
+- [ ] Can be verified with yes/no check
+- [ ] Has clear definition of "done"
+- [ ] Can be tested automatically or manually
+- [ ] Is realistic given timeline
+
+### 15.2 Verify Success Criteria Match Goals
+
+**Check criteria align with:**
+
+- [ ] TypeScript conversion (all JS converted)
+- [ ] Type safety (no `any` except legacy)
+- [ ] Architecture preservation (SSR, progressive enhancement)
+- [ ] Code quality (procedural style, no OOP)
+- [ ] Functionality (no regressions)
+
+### 15.3 Verify Success Criteria are Complete
+
+**Ensure criteria cover:**
+
+- [ ] Code conversion completeness
+- [ ] Type safety standards
+- [ ] Compilation/build success
+- [ ] Testing completion
+- [ ] Documentation updates
+- [ ] No regressions
+- [ ] Performance standards
+
+---
+
+## Summary Checklist
+
+Before approving the TypeScript conversion plan, verify:
+
+### Critical (Must Pass)
+- [ ] All type definitions match actual API responses (check database layer)
+- [ ] No unused handler structs referenced in type definitions
+- [ ] All API endpoints referenced actually exist
+- [ ] Progressive enhancement maintained for all critical flows
+- [ ] No backend modifications required for frontend tasks
+- [ ] Build configuration is correct and tested
+- [ ] Phase dependencies are acyclic and logical
+- [ ] All inline JavaScript is accounted for in conversion plan
+
+### Important (Should Pass)
+- [ ] Code style examples match documented guidelines
+- [ ] Template cleanup tasks have accurate line numbers
+- [ ] Timeline estimates are realistic
+- [ ] Testing strategy is comprehensive
+- [ ] Rollback strategy is clear
+- [ ] No internal contradictions in plan
+- [ ] No contradictions with codebase reality
+- [ ] No contradictions with PROJECT_GUIDELINES.md
+
+### Nice to Have
+- [ ] Documentation is clear and complete
+- [ ] Examples are accurate and helpful
+- [ ] Common pitfalls are documented
+- [ ] Verification commands are provided
+- [ ] Success criteria are measurable
+- [ ] Plan is easy to follow for implementers
+
+---
+
+## Usage Instructions
+
+1. **Before Starting Review:** Read the entire TYPESCRIPT_CONVERSION_PLAN.md
+2. **During Review:** Go through each section of this checklist systematically
+3. **For Each Item:** Run the provided verification commands
+4. **Document Findings:** Note any issues found with file/line references
+5. **Categorize Issues:** Mark as Critical, Important, or Nice to Have
+6. **Verify Fixes:** After fixing issues, re-run relevant checklist sections
+
+## Common Issues Found
+
+1. **Type Mismatches:** Handler structs defined but not used by endpoints
+2. **Missing Fields:** TypeScript interfaces missing fields that API returns
+3. **Wrong Field Types:** `string` vs `string[]`, `author` vs `authors`
+4. **Duplicate Code:** Inline JavaScript duplicating existing TypeScript
+5. **Overlooked Scripts:** `<script>` blocks not mentioned in plan
+6. **Missing Endpoints:** API references that don't exist
+7. **Broken Dependencies:** Phase B depends on Phase A, but ordered incorrectly
+8. **Contradictions:** Plan says one thing, examples show another
+9. **Unrealistic Estimates:** 500 lines of complex code in 1 day
+10. **Missing Testing:** No way to verify conversion worked
+
+---
+
+*Created: 2025-02-18*
+*Purpose: Comprehensive verification of TypeScript conversion plan*
+*Version: 1.0*