diff --git a/TYPESCRIPT_CONVERSION_VERIFICATION_CHECKLIST.md b/TYPESCRIPT_CONVERSION_VERIFICATION_CHECKLIST.md new file mode 100644 index 0000000..30df244 --- /dev/null +++ b/TYPESCRIPT_CONVERSION_VERIFICATION_CHECKLIST.md @@ -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 `