diff --git a/docs/AUDIT_PLATFORM.md b/docs/AUDIT_PLATFORM.md index 77c0829c..d1081840 100644 --- a/docs/AUDIT_PLATFORM.md +++ b/docs/AUDIT_PLATFORM.md @@ -12,12 +12,12 @@ Legend: ๐Ÿ”ด critical ยท ๐ŸŸ  high ยท ๐ŸŸก medium ยท ๐ŸŸข low ยท ## 0. Health snapshot -| Check | Result | Notes | -| ----------------- | ---------- | ------------------------------------------------------------------------------------------------------ | -| `pnpm install -r` | โœ… pass | 4 peer warnings โ€” `@azure/cosmos` wants `@azure/core-client@^1.10.0`. Cosmetic. | -| `pnpm typecheck` | โœ… pass | All TS sources compile (`tsc --noEmit`). | -| `pnpm test` | โœ… pass | ~2,200 tests across 18+ test suites, all green. | -| `pnpm lint` | ๐ŸŸก partial | After this audit's structural fixes: still 85 pre-existing errors in code, 96 warnings. See section P. | +| Check | Result | Notes | +| ----------------- | ------- | ----------------------------------------------------------------------------------------------- | +| `pnpm install -r` | โœ… pass | No warnings when `GITEA_NPM_TOKEN` is exported after sourcing `~/.zshrc`. | +| `pnpm typecheck` | โœ… pass | All TS sources compile (`tsc --noEmit`). | +| `pnpm test` | โœ… pass | ~2,200 tests across 18+ test suites; one cowork-service `EPIPE` flake cleared on focused rerun. | +| `pnpm lint` | โœ… pass | Workspace lint exits 0 with 0 errors. Remaining output is warnings only. See section W. | ## A. Lint pipeline blockers (fixed by this audit) @@ -39,43 +39,26 @@ Legend: ๐Ÿ”ด critical ยท ๐ŸŸ  high ยท ๐ŸŸก medium ยท ๐ŸŸข low ยท These all matter because `pnpm -r exec eslint` bails on the first package failure, so the 45-error design-tokens issue was hiding everything below it. -Now the pipeline runs to completion and **surfaces the real lint debt** (next -section). +Now the pipeline runs to completion and the current workspace has **0 lint +errors**. -## P. Pre-existing lint debt now visible +## P. Pre-existing lint debt cleared -After section A's structural unblocks the workspace-wide lint reports: +Current workspace-wide lint reports no errors: ``` -โœ– 181 problems (85 errors, 96 warnings) +0 errors ``` -Errors break down by rule (top 4): +The stale handoff note expected 85 pre-existing errors, but a live rerun on +2026-05-04 found none. No P-sweep package commits were needed in this session. -| Rule | Count | Notes | -| ----------------------------------- | ----: | ------------------------------------------------------------------ | -| `@typescript-eslint/no-unused-vars` | 67 | Mostly unused imports / unused destructured params in tests + code | -| `prefer-const` | 7 | `let` declarations never reassigned | -| `no-redeclare` | 7 | Likely identifiers shadowing globals / re-imports | -| `no-useless-escape` | 4 | Regex / string escapes that are no-ops | +## W. Pre-existing lint warnings -All of these are autofixable for the most part (`pnpm lint:fix`) **except** -where renaming an unused var changes a public API surface. They span multiple -packages I don't have working knowledge of (auth, llm, cosmos, billing-service, -tracker-service, growth-service, etc.). I'm not fixing them blind in this pass -โ€” each one is a one-liner but a wrong rename can break a downstream consumer. - -**Recommendation**: a follow-up sweep where the package owner runs -`pnpm --filter lint:fix`, eyeballs the diff, and commits per package. -Should be 6โ€“10 small commits. - -## W. Pre-existing lint warnings (96) - -Mostly `no-console` in CLI tools (`create-app`, `keyvault`, `sidecar-monitor`, -`generate.ts`, `roadmap/page.tsx`) and one `no-explicit-any` in `api-client`. -These are intentional in CLI scripts (we already disabled `no-console` for -`**/scripts/**` in this audit's eslint config change), and the rest are case-by- -case judgment calls. Not blocking. +Remaining lint output is warnings only, mostly `no-console` in CLI tools and +diagnostic scripts (`create-app`, `keyvault`, `sidecar-monitor`, `gen-module`, +`migrate-referrals`, `roadmap/page.tsx`) plus a few `no-explicit-any` warnings. +These are case-by-case judgment calls and not blocking. ## R. Repo-state observations (not fixed) @@ -83,15 +66,14 @@ case judgment calls. Not blocking. | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | :----------------: | | R1 | Working tree had 3 uncommitted edits when the audit started: `docker-compose.ecosystem.yml` (removes `nomgap-web` from Docker), `products/nomgap/product.json` (replaces flag set + adds containers), `services/platform-service/src/modules/flags/seed.ts` (+14 lines of flags). These look like an in-progress nomgap-on-Vercel migration. **Not touched** โ€” out of audit scope and missing context. | โ€” | โฌœ | | R2 | Local `main` was 17 commits behind `origin/main` at the start of the session. Backup branch `backup/main-20260504-062733` was taken from `origin/main` (the source of truth) โ€” local stale main was _not_ backed up. | ๐ŸŸข | โœ… (backup exists) | -| R3 | `.npmrc` references `${GITEA_NPM_TOKEN}` โ€” pnpm prints a noisy WARN if the env var is unset. Cosmetic; the install still resolves the public packages it can. | ๐ŸŸข | โฌœ | -| R4 | `pnpm install -r` reports 4 missing peer warnings for `@azure/core-client@^1.10.0`. Adding it as an explicit dep on the two services that use `@azure/cosmos` would silence the warning. | ๐ŸŸข | โฌœ | +| R3 | `.npmrc` references `${GITEA_NPM_TOKEN}`. On this machine `~/.zshrc` defines the token but does not export it, so use `source ~/.zshrc && export GITEA_NPM_TOKEN` before `pnpm`; this silences the WARN. | ๐ŸŸข | โœ… documented | +| R4 | Earlier `pnpm install -r` reported peer warnings for `@azure/core-client@^1.10.0`. A live rerun with the token exported reported no peer warnings. | ๐ŸŸข | โœ… verified | --- ## Ordering of fixes 1. **Section A** (this commit) โ€” structural unblocks so `pnpm lint` runs end-to-end again. -2. **Section P** โ€” per-package `lint:fix` sweeps owned by each package's - maintainer. Each package = one commit. ~6โ€“10 commits. -3. **Section W** โ€” case-by-case `no-console` review (defer; warnings only). -4. **Section R** โ€” chore-level housekeeping (peer deps, .npmrc). +2. **Section P** โ€” no current lint errors; no package sweeps needed. +3. **Section W** โ€” case-by-case warning review (defer; warnings only). +4. **Section R** โ€” housekeeping verified/documented. diff --git a/docs/CODEX_RESUME_PROMPT.md b/docs/CODEX_RESUME_PROMPT.md index 443977f0..18f416f2 100644 --- a/docs/CODEX_RESUME_PROMPT.md +++ b/docs/CODEX_RESUME_PROMPT.md @@ -14,9 +14,10 @@ file. You are resuming a tooling-backed audit of a 69-package pnpm workspace. A prior session already unblocked the lint pipeline, ran every gate, and -catalogued what's left. Your job is to clear the **85 pre-existing lint -errors** that are now visible โ€” one package at a time, with eyeball -review, no shortcuts. +catalogued what was left. A fresh rerun on 2026-05-04 shows the old +**85 pre-existing lint errors** are now stale: current workspace lint exits +0 with 0 errors. Do not start a P-sweep unless a fresh lint log shows new +errors. ### Step 0 โ€” Required reads (do this BEFORE writing any code) @@ -31,10 +32,10 @@ re-shipped to the trading repo), also skim: 3. `/Users/saravana/BytelystAI/trading/learning_ai_invt_trdg/docs/HANDOVER.md` -After reading, summarise in your own words: which audit items are โœ… done -(section A โ€” 13 items), which are โฌœ open (section P โ€” the 85 errors), -and which package you are about to attempt first. If your summary -disagrees with the audit doc tables, re-read. +After reading, summarise in your own words: which audit items are done +(section A โ€” 13 items), that section P is currently clear, and what optional +follow-up you are about to attempt. If your summary disagrees with the audit +doc tables, re-read. ### Step 1 โ€” Environment @@ -45,7 +46,8 @@ the install will fail on the private `@bytelyst/*` packages used by the mobile workspace and by transitive deps. ```bash -source ~/.zshrc # gets GITEA_NPM_TOKEN onto your shell +source ~/.zshrc +export GITEA_NPM_TOKEN # ~/.zshrc defines it on this machine but does not export it echo "$GITEA_NPM_TOKEN" | wc -c # must print 41 (40 chars + newline) ``` @@ -58,20 +60,16 @@ NOT --no-verify. Do NOT skip hooks. ```bash cd /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat source ~/.zshrc +export GITEA_NPM_TOKEN pnpm install -r --prefer-offline # โ†’ cache hit, finishes in seconds pnpm typecheck # โ†’ exit 0 (all 69 packages compile) -pnpm test # โ†’ ~2,200 tests pass -pnpm lint > /tmp/lint.log 2>&1 # baseline: exit 1, 85 errors - -# After your change: -pnpm lint > /tmp/lint-after.log 2>&1 -diff <(grep -c "errors" /tmp/lint.log) <(grep -c "errors" /tmp/lint-after.log) -# Error count MUST go DOWN, never up. +pnpm test # โ†’ ~2,200 tests pass; rerun focused package if a known flake appears +pnpm lint > /tmp/lint.log 2>&1 # current baseline: exit 0, 0 errors ``` -The 96 `no-console` warnings are intentional in CLI scripts and are NOT -your problem. Focus on errors. +Remaining lint output is warnings only. Treat warning cleanup as case-by-case +Section W work, not part of the completed P-sweep. ### Step 3 โ€” Working tree state at handover @@ -89,7 +87,8 @@ needs a clean lockfile, run install yourself and decide deliberately. ### Step 4 โ€” Priority queue: the P-sweep -The 85 errors break down by rule: +The P-sweep is currently complete. The stale 85-error handoff broke down by +rule as: | Rule | Count | Notes | | ----------------------------------- | ----: | -------------------------------------------------- | @@ -103,7 +102,8 @@ Recent upstream work made `^_`-prefix vars an official escape hatch `destructuredArrayIgnorePattern`). Use that โ€” don't delete identifiers that might be public API. -**Workflow per package** (one commit per package, no exceptions): +If a fresh lint log shows new errors, use this workflow per package (one commit +per package, no exceptions): ```bash # 1. Identify package owners by looking at the lint log @@ -148,16 +148,15 @@ inspection): 5. `dashboards/admin-web`, `dashboards/tracker-web`, `dashboards/ux-lab` 6. Everything remaining (one pass) -Target: 6โ€“10 small commits, lint error count 85 โ†’ 0. +Target for any future sweep: reduce the fresh lint error count to 0. ### Step 5 โ€” Secondary work (after P-sweep is done) -| # | Item | What | Effort | -| --- | ----- | ------------------------------------------------------------------------------------------------------------ | ------ | -| 1 | R3 | Silence the `.npmrc` `${GITEA_NPM_TOKEN}` WARN with a graceful fallback | 30 min | -| 2 | R4 | Add explicit `@azure/core-client@^1.10.0` to the two services using `@azure/cosmos` to silence peer warnings | 15 min | -| 3 | (new) | Decide whether to commit the regenerated `pnpm-lock.yaml` (review the diff) | 1 hr | -| 4 | (new) | Audit any package whose tests skip > 5% (look at `feedback-client`, `cowork-service`) โ€” investigate why | 1-2 hr | +| # | Item | What | Effort | +| --- | ----- | ------------------------------------------------------------------------------------------------------- | ------ | +| 1 | W | Review remaining lint warnings case-by-case | varies | +| 2 | (new) | Decide whether to commit the regenerated `pnpm-lock.yaml` (review the diff) | 1 hr | +| 3 | (new) | Audit any package whose tests skip > 5% (look at `feedback-client`, `cowork-service`) โ€” investigate why | 1-2 hr | ### Step 6 โ€” Commit conventions @@ -218,15 +217,14 @@ After each commit + push: Stop and ask the human, do not guess, when: -- An "unused" export is consumed by code outside this repo (trading repo +- A fresh lint log shows an "unused" export consumed by code outside this repo (trading repo vendors several packages โ€” check there before deleting). - A `lint:fix` autofix changes runtime behaviour (rare for the rules in scope, but possible with `no-useless-escape` if a regex is doing something subtle). - Tests start failing in a package whose code you didn't directly touch (transitive type breakage). -- You have cleared all 85 errors and want direction on Section R or - Section W. +- You have cleared any fresh lint errors and want direction on Section W. Otherwise: keep going. The point of this brief is so you don't have to ping the human every package. @@ -242,13 +240,8 @@ Paste this single block into Codex / Claude / Gemini: ``` Resume the platform audit on this machine. Read /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/CODEX_RESUME_PROMPT.md -in full first โ€” it contains your full brief, the P-sweep workflow, the -verification gates, and the commit conventions. Then walk the 85 lint -errors package-by-package: pick one, run `pnpm --filter exec -eslint . --ext .ts,.tsx --fix`, eyeball the diff, run gates, commit -(one package = one commit, subject `chore(P-sweep): ...`), push, tick -the audit doc, repeat. Source ~/.zshrc in every shell so -GITEA_NPM_TOKEN is available. Do not touch the nomgap WIP files. Do -not bulk-fix. After each push, tell me the package, commit hash, and -error-count delta in three sentences. +in full first. Source ~/.zshrc and export GITEA_NPM_TOKEN in every shell. +Run the verification gates, confirm lint still exits 0 with 0 errors, and do +not start a P-sweep unless a fresh lint log shows new errors. Do not touch the +nomgap WIP files or commit pnpm-lock.yaml as a side effect. ``` diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md index af2fca53..653f2f0b 100644 --- a/docs/HANDOVER.md +++ b/docs/HANDOVER.md @@ -9,24 +9,23 @@ ## TL;DR A tooling-backed audit was performed across all 69 workspace packages. -`pnpm install / typecheck / test` all pass cleanly. `pnpm lint` was failing -fast at one package (hiding everything downstream); a structural eslint -config fix + 13 mechanical lint fixes have made the lint pipeline run -end-to-end. **85 pre-existing lint errors are now visible** that nobody -had seen before โ€” they belong to package owners to clear with -`pnpm --filter lint:fix` followed by an eyeball review. +`pnpm install / typecheck / lint` pass cleanly on the current workspace. +`pnpm lint` was previously failing fast at one package, but a structural eslint +config fix + 13 mechanical lint fixes made the lint pipeline run end-to-end. +A fresh rerun on 2026-05-04 shows **0 lint errors**; the old 85-error P-sweep +handoff is stale. --- ## What's working right now -| Check | Result | Notes | -| ---------------------- | ------------------ | ---------------------------------------------------------------------------------- | -| `pnpm install -r` | โœ… pass | 4 cosmetic peer warnings (`@azure/core-client`) | -| `pnpm typecheck` | โœ… pass | All 69 packages compile | -| `pnpm test` | โœ… pass | ~2,200 tests across 18+ suites | -| `pnpm lint` (pipeline) | โœ… runs end-to-end | Was bailing fast; this audit unblocked it | -| `pnpm lint` (errors) | ๐ŸŸก 85 | All pre-existing, surfaced by the unblock โ€” see `docs/AUDIT_PLATFORM.md` section P | +| Check | Result | Notes | +| ---------------------- | ------------------ | ------------------------------------------------------------------- | +| `pnpm install -r` | โœ… pass | No warnings when `GITEA_NPM_TOKEN` is exported | +| `pnpm typecheck` | โœ… pass | All 69 packages compile | +| `pnpm test` | โœ… pass | ~2,200 tests; cowork-service `EPIPE` flake cleared on focused rerun | +| `pnpm lint` (pipeline) | โœ… runs end-to-end | Was bailing fast; this audit unblocked it | +| `pnpm lint` (errors) | โœ… 0 | Warnings only โ€” see `docs/AUDIT_PLATFORM.md` section W | --- @@ -34,13 +33,13 @@ had seen before โ€” they belong to package owners to clear with ### 1. The `.npmrc` token requirement -`.npmrc` references `${GITEA_NPM_TOKEN}`. **Without it exported**, `pnpm` -emits noisy WARNs and `pnpm install -r` fails on the mobile / vendored -`@bytelyst/*` private packages. Every developer needs to: +`.npmrc` references `${GITEA_NPM_TOKEN}`. On this machine, `~/.zshrc` defines +the variable but does not export it. Without export, `pnpm` emits noisy WARNs. +Every developer shell should run: ```bash -# Add to ~/.zshrc (or ~/.bashrc) -export GITEA_NPM_TOKEN= +source ~/.zshrc +export GITEA_NPM_TOKEN ``` The audit session's tooling runs all relied on this being sourced. @@ -64,37 +63,20 @@ without inspecting it** โ€” it likely upgraded transitive versions. `docs/AUDIT_PLATFORM.md` has the full breakdown: - **Section A** (โœ… done): 13 lint pipeline blockers fixed in `8f541c9`. -- **Section P** (open): 85 pre-existing lint errors surfaced. Top rules: - - 67 ร— `@typescript-eslint/no-unused-vars` - - 7 ร— `prefer-const` - - 7 ร— `no-redeclare` - - 4 ร— `no-useless-escape` -- **Section W** (low priority): 96 `no-console` warnings in CLI tools etc. -- **Section R** (housekeeping): 4 misc observations. +- **Section P** (โœ… clear): current workspace lint has 0 errors. +- **Section W** (low priority): warnings only, mostly `no-console` in CLI tools. +- **Section R** (housekeeping): token export and peer-warning observations are documented/verified. -**Note**: a recent upstream commit (in the rebased main since this audit -started) tightened the unused-vars rule with `varsIgnorePattern: '^_'`, -`caughtErrorsIgnorePattern: '^_'`, etc. โ€” meaning `_`-prefix is now an -official escape hatch for intentionally-unused names. This makes the -85-error sweep easier (just rename, don't delete). +**Note**: a recent upstream commit tightened the unused-vars rule with +`varsIgnorePattern: '^_'`, `caughtErrorsIgnorePattern: '^_'`, etc. โ€” meaning +`_`-prefix is now an official escape hatch for intentionally-unused names. --- ## Suggested next steps -1. **P sweep** โ€” package owners run `pnpm --filter lint:fix` per - package, eyeball the diff (the autofixer can technically remove unused - exports, which is breaking), commit. Target 6โ€“10 small commits. - Likely owners by error count: - - `services/platform-service` (probably the biggest chunk) - - `services/extraction-service`, `services/cowork-service` - - `packages/auth`, `packages/llm`, `packages/cosmos` - - `dashboards/admin-web`, `dashboards/tracker-web` -2. **R3** โ€” silence the `.npmrc` WARN with a graceful fallback (not - blocking; just noisy). -3. **R4** โ€” add explicit `@azure/core-client@^1.10.0` to the two services - that pull `@azure/cosmos` to silence peer warnings. -4. _(optional)_ commit the regenerated `pnpm-lock.yaml` once someone with +1. **Section W** โ€” optionally review warnings case-by-case. +2. _(optional)_ commit the regenerated `pnpm-lock.yaml` once someone with context can verify the upgrades it introduced. --- @@ -104,15 +86,16 @@ official escape hatch for intentionally-unused names. This makes the ```bash # Verify clean state before starting cd /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat -source ~/.zshrc # ensure GITEA_NPM_TOKEN is loaded +source ~/.zshrc +export GITEA_NPM_TOKEN # ensure pnpm can read the token git status # 4 unrelated WIP files expected (see ยง2 above) -git log --oneline -3 # top: 8f541c9 chore(audit): unblock workspace lint pipeline... +git log --oneline -3 # Run the gates pnpm install -r --prefer-offline # โ†’ done in seconds (cache hit) pnpm typecheck # โ†’ exit 0 -pnpm test # โ†’ ~2,200 pass -pnpm lint > /tmp/lint.log 2>&1 # โ†’ exit 1 with 85 errors (see AUDIT_PLATFORM.md ยงP) +pnpm test # โ†’ ~2,200 pass; rerun focused package if a known flake appears +pnpm lint > /tmp/lint.log 2>&1 # โ†’ exit 0, 0 errors ``` ---