diff --git a/docs/AUDIT_WARNING_COMPLETION_CHECKLIST.md b/docs/AUDIT_WARNING_COMPLETION_CHECKLIST.md new file mode 100644 index 00000000..6b95c1ad --- /dev/null +++ b/docs/AUDIT_WARNING_COMPLETION_CHECKLIST.md @@ -0,0 +1,317 @@ +# Platform Warning + Quality Completion Checklist + +Date started: 2026-05-04 +Scope: `learning_ai_common_plat` +Status: active + +This document tracks the work after the platform lint-error sweep reached +zero errors. It is intentionally broader than lint warnings: the goal is to +move the common platform toward a high-quality, low-noise, easy-to-maintain +baseline without hiding intentional diagnostics or changing product behavior +by accident. + +## Current Baseline + +As of the latest local sweep: + +| Gate | Current state | Notes | +| ---------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `pnpm install -r --prefer-offline` | Pass | Run with `source ~/.zshrc && export GITEA_NPM_TOKEN`. | +| `pnpm typecheck` | Pass | All workspace TypeScript compiles. | +| `pnpm test` | Pass with known load sensitivity | Full suite passes; isolated reruns cleared prior transient platform/cowork timeouts. | +| `pnpm lint` | Pass | `0` errors. Latest summarized warning count: `189` warnings. | +| Known untouched WIP | Present | Do not touch `docker-compose.ecosystem.yml`, `products/nomgap/product.json`, `services/platform-service/src/modules/flags/seed.ts`, or incidental `pnpm-lock.yaml` churn unless explicitly assigned. | + +Recent warning-cleanup commits: + +| Commit | Area | Result | +| --------- | --------------------------- | ----------------------------------------- | +| `4690072` | `@bytelyst/api-client` | Removed `any` from header merging. | +| `afe7d88` | `@bytelyst/monitoring` | Typed fetch test mocks. | +| `b6da94d` | `@bytelyst/tracker-web` | Typed tracker proxy test request helper. | +| `9625999` | `@lysnrai/platform-service` | Removed stale eslint-disable comments. | +| `6978ddb` | `@lysnrai/cowork-service` | Typed test doubles for IPC/Fastify mocks. | + +## Operating Rules + +- Keep `pnpm lint` at `0` errors at all times. +- Prefer one coherent area per commit: one package, one dashboard, or one + lint-policy change. +- Do not bulk-apply `eslint --fix` across the workspace. +- Do not change user/product behavior to satisfy a warning unless the behavior + is clearly wrong and covered by tests. +- Do not replace intentional CLI `console.*` calls with awkward logger plumbing + just to make the counter go down. +- For Fastify service runtime code, prefer `req.log` or `app.log` over + `console.*`. +- For CLI scripts and code generators, either keep `console.*` with an explicit + lint policy or refactor only when there is a real logging requirement. +- For React hook dependency warnings, inspect data flow first. Blindly adding + dependencies can create fetch loops. +- For `any`, prefer local structural types, Zod inference, `unknown` narrowing, + or test-only helper types. +- Every commit should include verification in the body when practical. + +## Standard Gates + +Use these before and after meaningful changes: + +```bash +cd /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat +source ~/.zshrc +export GITEA_NPM_TOKEN + +pnpm install -r --prefer-offline +pnpm typecheck +pnpm test +pnpm lint > /tmp/lint.log 2>&1 +``` + +For small scoped changes, run the package gates first: + +```bash +pnpm --filter build +pnpm --filter test +pnpm --filter exec eslint . --ext .ts,.tsx +``` + +Then run at least workspace lint before committing. Run the full test suite +when the package is shared, service-facing, or behavior-sensitive. + +## Done Definition + +This workstream is complete when: + +- Workspace lint still exits `0`. +- Remaining warnings are either eliminated or explicitly documented as + intentional with a narrow ESLint policy. +- No production service code uses raw `console.*` unless documented as + intentional and safe. +- No `@typescript-eslint/no-explicit-any` warnings remain in production code. +- Any remaining test-only `any` has a clear justification or is replaced by a + structural test helper. +- React hook warnings in dashboards have been reviewed for correctness, not + merely silenced. +- Next/Image warnings are either fixed or documented as intentional for the + specific asset flow. +- Known transient test behavior is documented with reproduction notes and an + owner. +- `docs/AUDIT_PLATFORM.md` and `docs/HANDOVER.md` stay aligned with the live + gates. + +## Workstreams + +### W1. Lint Policy + Warning Taxonomy + +Goal: distinguish intentional warning classes from real quality issues. + +- [ ] Capture a fresh warning inventory: + `pnpm lint > /tmp/lint-warning-inventory.log 2>&1`. +- [ ] Split warnings into buckets: + `console`, `no-explicit-any`, `no-unused-vars`, `react-hooks/exhaustive-deps`, + `@next/next/no-img-element`, Node module warnings, stale disables. +- [ ] Decide the policy for CLI/codegen `console.*`. +- [ ] Decide whether `**/scripts/**/*.ts` should receive a targeted + `no-console: off` override. +- [ ] Decide whether generator packages like `packages/create-app` should be + treated as CLI output surfaces. +- [ ] Document the policy in `docs/AUDIT_PLATFORM.md` or this file. +- [ ] Add a narrow ESLint override only after policy is agreed. +- [ ] Verify the override does not hide service runtime `console.*` calls. + +### W2. Admin Web React Warnings + +Goal: remove obvious dashboard warnings and review hook warnings safely. + +- [ ] `dashboards/admin-web/src/app/(dashboard)/experiments/[id]/page.tsx`: + remove or use unused `Download`. +- [ ] Same file: review `fetchExperimentData` dependency warning. +- [ ] Same file: remove, rename, or use unused `experiment` argument. +- [ ] `dashboards/admin-web/src/app/(dashboard)/experiments/page.tsx`: + remove, render, or rename unused `error`. +- [ ] `dashboards/admin-web/src/app/(dashboard)/feedback/page.tsx`: + remove unused `useRouter`. +- [ ] Same file: review `fetchFeedback` dependency warning. +- [ ] Same file: rename unused caught `err` values to `_err` or handle them. +- [ ] Same file: review `` use and migrate to `next/image` if safe. +- [ ] `dashboards/admin-web/src/app/(dashboard)/predictive/at-risk/page.tsx`: + remove or use unused `ArrowRight`. +- [ ] Same file: review `loadProfile` dependency warning. +- [ ] Same file: review `loadUsers` dependency warning. +- [ ] `dashboards/admin-web/src/app/(dashboard)/predictive/campaigns/page.tsx`: + remove unused `Tabs`, `TabsContent`, `TabsList`, `TabsTrigger`. +- [ ] Same file: review `loadStats` dependency warning. +- [ ] Same file: review `loadCampaigns` dependency warning. +- [ ] `dashboards/admin-web/src/app/(dashboard)/settings/security/page.tsx`: + review `` use and migrate to `next/image` if safe. +- [ ] `dashboards/admin-web/src/app/(dashboard)/surveys/[id]/page.tsx`: + review `loadSurvey` dependency warning. +- [ ] `dashboards/admin-web/src/app/(dashboard)/surveys/page.tsx`: + review `loadSurveys` dependency warning. +- [ ] Run `pnpm --filter @bytelyst/admin-web typecheck`. +- [ ] Run `pnpm --filter @bytelyst/admin-web test`. +- [ ] Run `pnpm --filter @bytelyst/admin-web exec eslint . --ext .ts,.tsx`. +- [ ] Consider an in-browser smoke pass for affected dashboard screens. + +### W3. Platform Service Runtime Console Usage + +Goal: replace service runtime `console.*` with structured logging or document +why the call is not runtime service code. + +- [ ] `services/platform-service/src/lib/push-notifications.ts`: replace + `console.*` with injected logger, app logger, or returned diagnostic state. +- [ ] Add tests or assertions for push notification error paths if behavior + changes. +- [ ] `services/platform-service/src/modules/ai-diagnostics/embedding-client.ts`: + replace or inject logger for current `console.*` calls. +- [ ] `services/platform-service/src/modules/ai-diagnostics/llm-analyzer.ts`: + replace or inject logger for current `console.*` call. +- [ ] `services/platform-service/src/modules/diagnostics/auto-triggers.ts`: + replace runtime `console.*`. +- [ ] `services/platform-service/src/modules/diagnostics/repository.ts`: + replace runtime `console.*`. +- [ ] Confirm replacements preserve useful error context and do not swallow + failures. +- [ ] Run `pnpm --filter @lysnrai/platform-service build`. +- [ ] Run targeted tests for changed modules. +- [ ] Run `pnpm --filter @lysnrai/platform-service test` when practical. +- [ ] Run scoped platform-service ESLint. + +### W4. Platform Predictive Analytics Typing + +Goal: remove production `any`s from +`services/platform-service/src/modules/predictive-analytics/campaign-engine.ts`. + +- [ ] Read `campaign-engine.ts` end-to-end before editing. +- [ ] Identify the domain shapes behind the 5 `any` uses. +- [ ] Prefer local interfaces or Zod-inferred types over broad casts. +- [ ] Add or update tests for campaign generation branches touched by types. +- [ ] Avoid changing campaign selection/scoring behavior unless a bug is found. +- [ ] Run predictive analytics tests. +- [ ] Run platform-service build/test/lint gates. + +### W5. Platform Scripts + Codegen + +Goal: make script warnings intentional and policy-backed. + +- [ ] `services/platform-service/scripts/gen-module.ts`: decide whether this is + CLI/codegen and should be covered by `no-console: off`. +- [ ] If not exempted, replace print calls with a small script logger wrapper. +- [ ] `services/platform-service/scripts/migrate-referrals.ts`: decide whether + this migration script should be covered by CLI policy. +- [ ] Type the remaining `any` at `migrate-referrals.ts`. +- [ ] Preserve dry-run/live migration output readability. +- [ ] Run script typecheck/build coverage via package build or `tsx` dry-run + where safe. + +### W6. Shared Package Console Warnings + +Goal: decide package-by-package whether console output is intentional API +behavior, CLI output, or noise. + +- [ ] `packages/broadcast-client/src/deep-link.ts`: review console usage. +- [ ] `packages/config/src/keyvault.ts`: review console usage. +- [ ] `packages/create-app/src/generators/agents-md.ts`: classify as + generator/CLI. +- [ ] `packages/create-app/src/generators/api-routes.ts`: classify as + generator/CLI. +- [ ] `packages/design-tokens/scripts/generate.ts`: classify as script output. +- [ ] `packages/diagnostics-client/src/client.ts`: document console capture as + intentional or add narrow inline disables. +- [ ] `services/monitoring/health-check.ts`: classify as CLI health-check. +- [ ] `services/extraction-service/src/modules/extract/sidecar-monitor.ts`: + review whether console is service runtime or local monitor output. +- [ ] Add tests only when behavior is changed, not for pure lint policy. + +### W7. Tracker Web Remaining Warnings + +Goal: finish tracker warnings without hiding real runtime errors. + +- [ ] `dashboards/tracker-web/src/app/roadmap/page.tsx`: replace or route + `console.error` calls through an app logger if available. +- [ ] Decide whether client-side console errors are acceptable for public + roadmap actions. +- [ ] Add `"type": "module"` to `dashboards/tracker-web/package.json` only if + it is safe for Next/Vitest/Husky scripts. +- [ ] Alternatively rename/configure `eslint.config.js` to avoid Node's module + type warning. +- [ ] Run tracker-web typecheck/test/lint after any package.json or config + change. + +### W8. Lockfile + Repo State + +Goal: resolve or document the large lockfile diff without mixing it into +quality commits. + +- [ ] Inspect `pnpm-lock.yaml` diff independently. +- [ ] Determine whether the lockfile was regenerated from current package + manifests or includes unintended dependency movement. +- [ ] Decide: commit lockfile, restore lockfile, or preserve as separate WIP. +- [ ] If committing, use a dedicated commit with a dependency-focused message. +- [ ] Do not include nomgap WIP files in the lockfile decision. +- [ ] Re-run install/typecheck/test/lint after lockfile action. + +### W9. Known Test Flakes + Load Sensitivity + +Goal: make the suite reliable enough for repeated audit gates. + +- [ ] Document the cowork-service `ipc-bridge.test.ts` transient `EPIPE` + observed during full-suite parallel runs. +- [ ] Document the platform-service `server.test.ts` timeout observed while + typecheck/lint ran in parallel. +- [ ] Reproduce each in isolation before changing tests. +- [ ] If reproducible, fix the underlying test lifecycle or timeout source. +- [ ] Avoid simply increasing timeouts without understanding the cause. +- [ ] Add notes to `docs/HANDOVER.md` if these remain known environment + sensitivities. + +### W10. Documentation + Handoff Hygiene + +Goal: keep future agents aligned with the true baseline. + +- [ ] Update `docs/AUDIT_PLATFORM.md` after each meaningful warning-policy + milestone. +- [ ] Update `docs/HANDOVER.md` when the current gate story changes. +- [ ] Keep `docs/CODEX_RESUME_PROMPT.md` aligned with the latest workflow. +- [ ] Record warning counts after each batch in this checklist. +- [ ] Include commit hashes in this checklist for major completed batches. +- [ ] Keep "do not touch nomgap WIP" instructions visible until those files are + resolved by their owner. + +## Suggested Next 25 Concrete Tasks + +1. Remove unused imports/vars in admin experiments detail. +2. Review and fix `fetchExperimentData` dependencies. +3. Remove unused `error` state in admin experiments list or render it. +4. Remove unused `useRouter` in admin feedback. +5. Rename or handle unused caught errors in admin feedback. +6. Review and fix `fetchFeedback` dependencies. +7. Replace/justify feedback ``. +8. Remove unused `ArrowRight` in predictive at-risk. +9. Review predictive at-risk `loadProfile` dependencies. +10. Review predictive at-risk `loadUsers` dependencies. +11. Remove unused `Tabs*` imports in predictive campaigns. +12. Review predictive campaigns `loadStats` dependencies. +13. Review predictive campaigns `loadCampaigns` dependencies. +14. Replace/justify security settings ``. +15. Review survey detail `loadSurvey` dependencies. +16. Review survey list `loadSurveys` dependencies. +17. Type the 5 predictive analytics `campaign-engine.ts` `any`s. +18. Replace platform push notification `console.*` calls. +19. Replace AI diagnostics embedding-client `console.*` calls. +20. Replace AI diagnostics analyzer `console.*` call. +21. Replace diagnostics auto-trigger/repository `console.*` calls. +22. Decide and implement CLI/script `console.*` lint policy. +23. Type the remaining `migrate-referrals.ts` `any`. +24. Resolve tracker-web ESLint module type warning. +25. Decide the fate of `pnpm-lock.yaml` in a dedicated change. + +## Progress Log + +| Date | Commit | Change | Warning impact | +| ---------- | --------- | ---------------------------------------------- | ------------------------------------------ | +| 2026-05-04 | `4690072` | Typed `@bytelyst/api-client` header merging. | Removed 1 `no-explicit-any` warning. | +| 2026-05-04 | `afe7d88` | Typed `@bytelyst/monitoring` fetch test mocks. | Removed 6 `no-explicit-any` warnings. | +| 2026-05-04 | `b6da94d` | Typed tracker-web proxy test request helper. | Removed 1 `no-explicit-any` warning. | +| 2026-05-04 | `9625999` | Removed stale platform-service lint disables. | Removed 2 stale-disable warnings. | +| 2026-05-04 | `6978ddb` | Typed cowork-service test doubles. | Removed cowork-service test `any` cluster. |