bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(audit): add warning completion checklist

Browse Source 
Add a detailed checklist for finishing the post-P-sweep quality work, including warning taxonomy, package workstreams, gates, done criteria, remaining task areas, and progress tracking.
This commit is contained in:
Saravana Achu Mac 2026-05-04 15:36:16 -07:00
parent 6978ddb209
commit af893c23be
1 changed files with 317 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

317
docs/AUDIT_WARNING_COMPLETION_CHECKLIST.md Normal file
View File

@ -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 <workspace> build
pnpm --filter <workspace> test
pnpm --filter <workspace> 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 `<img>` 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 `<img>` 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 `<img>`.
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 `<img>`.
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. |