code quality

plans/systematic-plan.md

@@ -0,0 +1,303 @@
+Route Plan — small-to-big verification route (excluding apps/companion)
+Ground rules (why this route works)
+Never run broad npm test/all-suites early. We always scope by area and by config.
+Each phase has a single ownership boundary (core → adapters → api → website → tests → E2E).
+If something fails, stop and fix at the smallest scope, then re-run only that phase.
+Phase 0 — Baseline + failure artifacts
+Artifacts folder
+
+mkdir -p artifacts/verify
+export VERIFY_RUN_ID=$(date -u +%Y%m%dT%H%M%SZ)
+export VERIFY_OUT=artifacts/verify/$VERIFY_RUN_ID
+mkdir -p $VERIFY_OUT
+
+Standard failure capture format (use consistently)
+
+ESLint: JSON report
+TypeScript: plain text log
+Vitest: JSON report (when supported)
+Playwright: HTML report + traces/videos on failure (config-dependent)
+Note: root scripts exist for typechecking targets in package.json–package.json, but we will run per-area tsc directly to keep scope small.
+
+Phase 1 — Verify core/ in isolation
+1.1 Typecheck (core only)
+npx tsc --noEmit -p core/tsconfig.json 2>&1 | tee $VERIFY_OUT/core.tsc.log
+
+Exit criteria: tsc exits 0; no TypeScript errors.
+
+1.2 Lint (core only)
+npx eslint core --ext .ts,.tsx --max-warnings 0 -f json -o $VERIFY_OUT/core.eslint.json
+
+Exit criteria: ESLint exits 0; report contains 0 errors.
+
+1.3 Unit tests (core only; filtered)
+Vitest includes core by default via vitest.config.ts.
+
+npx vitest run --config vitest.config.ts core --reporter=default
+
+If you want machine-readable output:
+
+npx vitest run --config vitest.config.ts core --reporter=json --outputFile=$VERIFY_OUT/core.vitest.json
+
+Exit criteria: all tests under core/**/*.{test,spec}.* pass.
+
+Minimal subset strategy: pass core as the filter argument so Vitest only runs tests whose paths match core.
+
+Failure reporting for Code mode (copy/paste template)
+
+Command: (paste exact command)
+Failing file(s): (from output)
+First error: (topmost stack)
+Suspected layer: (domain/service/adapter)
+Repro scope: re-run with npx vitest run --config vitest.config.ts path/to/file.test.ts
+Phase 2 — Verify adapters/ in isolation
+2.1 Typecheck (adapters only)
+npx tsc --noEmit -p adapters/tsconfig.json 2>&1 | tee $VERIFY_OUT/adapters.tsc.log
+
+Exit criteria: tsc exits 0.
+
+2.2 Lint (adapters only)
+npx eslint adapters --ext .ts,.tsx --max-warnings 0 -f json -o $VERIFY_OUT/adapters.eslint.json
+
+Exit criteria: ESLint exits 0.
+
+2.3 Unit tests (adapters only; filtered)
+npx vitest run --config vitest.config.ts adapters --reporter=default
+
+Optional JSON:
+
+npx vitest run --config vitest.config.ts adapters --reporter=json --outputFile=$VERIFY_OUT/adapters.vitest.json
+
+Exit criteria: all tests under adapters/**/*.{test,spec}.* pass.
+
+Minimal subset strategy: pass adapters as Vitest filter.
+
+Phase 3 — Verify apps/api/ in isolation
+3.1 Typecheck (API only)
+npx tsc --noEmit -p apps/api/tsconfig.json 2>&1 | tee $VERIFY_OUT/api.tsc.log
+
+Exit criteria: tsc exits 0.
+
+3.2 Lint (API source only)
+Root lint script targets apps/api/src in package.json.
+
+npm run lint --silent
+# optional: also capture JSON
+npx eslint apps/api/src --ext .ts,.tsx --max-warnings 0 -f json -o $VERIFY_OUT/api.eslint.json
+
+Exit criteria: ESLint exits 0.
+
+3.3 API tests (Vitest, API config)
+Config: vitest.api.config.ts
+
+npm run api:test --silent
+# equivalent:
+# npx vitest run --config vitest.api.config.ts
+
+Optional JSON:
+
+npx vitest run --config vitest.api.config.ts --reporter=json --outputFile=$VERIFY_OUT/api.vitest.json
+
+Exit criteria: all tests matched by vitest.api.config.ts pass.
+
+3.4 API contract validation (smallest meaningful contract test)
+Script points at a single file in package.json.
+
+npm run test:api:contracts --silent
+
+Exit criteria: contract validation test passes.
+
+Minimal subset strategy
+
+Use the API-specific config so we never accidentally pick up website/core/adapters suites.
+Prefer the single-file contract validation script first.
+Phase 4 — Verify apps/website/ in isolation
+4.1 Website lint (workspace only)
+Workspace script in package.json.
+
+npm run website:lint --silent
+# optional JSON capture
+( cd apps/website && npx eslint . --ext .ts,.tsx --max-warnings 0 -f json -o ../../$VERIFY_OUT/website.eslint.json )
+
+Exit criteria: ESLint exits 0.
+
+4.2 Website type-check (workspace only)
+Workspace script in package.json.
+
+npm run website:type-check --silent 2>&1 | tee $VERIFY_OUT/website.tsc.log
+
+Exit criteria: TypeScript exits 0.
+
+4.3 Website unit/integration tests (Vitest website config)
+Config: vitest.website.config.ts
+
+npx vitest run --config vitest.website.config.ts --reporter=default
+
+Optional JSON:
+
+npx vitest run --config vitest.website.config.ts --reporter=json --outputFile=$VERIFY_OUT/website.vitest.json
+
+Exit criteria: all tests included by vitest.website.config.ts pass.
+
+Minimal subset strategy
+
+Use the website-specific config so we don’t drag in unrelated tests/integration/* suites.
+If only one failing file: re-run with npx vitest run --config vitest.website.config.ts path/to/failing.test.ts.
+Phase 5 — Verify tests/ (non-E2E suites)
+5.1 Typecheck test harness (tests only)
+Script exists in package.json.
+
+npm run test:types --silent 2>&1 | tee $VERIFY_OUT/tests.tsc.log
+
+Exit criteria: tsc exits 0.
+
+5.2 Unit tests (tests/unit only)
+Script exists in package.json.
+
+npm run test:unit --silent
+
+Optional scoped rerun:
+
+npx vitest run tests/unit --reporter=json --outputFile=$VERIFY_OUT/tests.unit.vitest.json
+
+Exit criteria: unit suite passes.
+
+5.3 Integration tests (tests/integration only)
+Script exists in package.json.
+
+npm run test:integration --silent
+
+Optional JSON:
+
+npx vitest run tests/integration --reporter=json --outputFile=$VERIFY_OUT/tests.integration.vitest.json
+
+Exit criteria: integration suite passes.
+
+5.4 Contract tests (targeted)
+Contract runner exists in package.json–package.json.
+
+npm run test:contracts --silent
+npm run test:contract:compatibility --silent
+
+Exit criteria: contract suite + compatibility checks pass.
+
+Phase 6 — Website integration via Playwright (auth/session/route guards)
+Config: playwright.website-integration.config.ts
+
+6.1 Bring up docker E2E environment (website + api + db)
+Scripts exist in package.json–package.json.
+
+npm run docker:e2e:up
+
+6.2 Run website integration tests
+npx playwright test -c playwright.website-integration.config.ts
+
+Artifacts:
+
+npx playwright show-report playwright-report || true
+
+Exit criteria: all Playwright tests pass with 0 retries (configs set retries 0 in playwright.website-integration.config.ts).
+
+6.3 Tear down
+npm run docker:e2e:down
+
+Phase 7 — API smoke via Playwright
+Config: playwright.api.config.ts
+
+7.1 Start docker E2E environment
+npm run docker:e2e:up
+
+7.2 Run API smoke suite (config-targeted)
+npx playwright test -c playwright.api.config.ts
+
+Exit criteria: all smoke tests pass; auth setup passes via playwright.api.config.ts.
+
+7.3 Tear down
+npm run docker:e2e:down
+
+Phase 8 — Full website page-render E2E (Docker)
+Config: playwright.website.config.ts
+
+8.1 Bring up docker E2E environment
+npm run docker:e2e:up
+
+8.2 Run containerized website E2E
+Root script exists in package.json.
+
+npm run smoke:website:docker --silent
+# equivalent:
+# npx playwright test -c playwright.website.config.ts
+
+Exit criteria
+
+all tests pass
+no console/runtime errors (the suite’s stated purpose in playwright.website.config.ts–playwright.website.config.ts)
+8.3 Tear down
+npm run docker:e2e:down
+
+Phase 9 — Placeholder E2E inventory + implementation plan (must be completed at the end)
+9.1 Identify placeholder tests (mechanical rule)
+Current placeholders are primarily *.spec.ts under tests/e2e/ containing TODO blocks (example: tests/e2e/media/avatar.spec.ts).
+
+Inventory command (produces a reviewable list):
+
+rg -n "TODO: Implement test|TODO: Implement authentication" tests/e2e > $VERIFY_OUT/e2e.placeholders.txt
+
+Exit criteria: inventory file exists and is reviewed; every placeholder file is accounted for.
+
+9.2 Decide runner + wiring (so these tests actually run)
+Observation: your active runners are:
+
+Vitest E2E for *.e2e.test.ts via vitest.e2e.config.ts
+Playwright for website/api via playwright.website.config.ts and playwright.api.config.ts
+The placeholder files are *.spec.ts and appear to be Playwright-style UI specs. To make them “working,” they must:
+
+have deterministic auth + data seeding, and
+be included by a Playwright config’s testDir/testMatch.
+Plan (small-to-big, no scope explosion):
+
+Create one shared Playwright fixture for auth + seed (driver/admin/sponsor), then reuse it.
+Enable one directory at a time (e.g., tests/e2e/onboarding/*), keeping the blast radius small.
+Promote stable subsets into CI only after they’re reliable locally.
+9.3 Implement placeholders without expanding scope prematurely
+Rules of engagement:
+
+First implement the lowest-dependency happy paths (navigation + render assertions), then add mutations (create/update/delete).
+Use stable selectors (data-testid) and avoid brittle text-only selectors.
+For each spec file: ensure every test(...) contains at least one real assertion and no TODO blocks.
+Per-directory implementation order (smallest external dependency first):
+
+tests/e2e/dashboard/* (mostly navigation + visibility)
+tests/e2e/onboarding/* (auth + wizard flows)
+tests/e2e/profile/*
+tests/e2e/leagues/*
+tests/e2e/teams/*
+tests/e2e/media/* (uploads last; requires fixtures and storage)
+9.4 Identify missing coverage/gaps against product expectations
+Alignment sources:
+
+Product expectations in docs/concept/CONCEPT.md and role-specific behavior in docs/concept/ADMINS.md, docs/concept/DRIVERS.md, docs/concept/TEAMS.md, docs/concept/RACING.md.
+Gap-finding method:
+
+Build a checklist of feature promises from those concept docs.
+Map each promise to at least one E2E spec file.
+If a promise has no spec file, add a single targeted E2E spec (do not add broad new suites).
+Exit criteria (hard):
+
+rg -n "TODO: Implement" tests/e2e returns 0 results.
+All placeholder-derived specs are included in a Playwright config and pass in the docker E2E environment.
+Phase 10 — Optional final aggregate (only after everything above is green)
+Only now is it acceptable to run broader aggregations:
+
+npm run verify in package.json (note: it currently runs lint + typecheck targets + unit + integration).
+Suggested tracking checklist (Orchestrator TODO)
+Use the checklist already captured in the orchestrator list, driven phase-by-phase:
+
+Run Phase 1 commands; fix failures in core/ only.
+Run Phase 2; fix failures in adapters/ only.
+Run Phase 3; fix failures in apps/api/ only.
+Run Phase 4; fix failures in apps/website/ only.
+Run Phase 5; fix failures under tests/ only.
+Run Phase 6–8; fix failures by the nearest boundary (website vs api).
+Run Phase 9 last; implement every placeholder spec until rg TODO is empty and suites pass.
+This route plan is complete and ready for execution in Code mode.