chore(lint): count-based lint ratchet — new violations block, existing debt baselined; CI lint now blocking (#3962) (#3989)

* chore(lint): WP1 config hygiene — kill 468 false-positive errors

Eliminate the ~468 ESLint config false-positives (346 parser errors +
122 no-undef fires on TS ambient globals) so the baseline captures only
genuine rule violations:

• Extend top-level ignores: docs/** (VitePress cache), examples/**,
  protobufs/** (submodule), public/**  →  kills 346 parser errors
• Add no-undef:'off' for all TS/JS files — standard typescript-eslint
  recommendation; tsc reports undefined identifiers, not ESLint
• Add project:false override for scripts/**/*.{js,mjs,cjs,ts},
  *.{js,mjs,cjs}, tests/**/*.{js,mjs,cjs} — utility files outside
  tsconfig.json now lint without the type-aware parser

After: 0 parser errors, 0 no-undef errors.
Part of remediation epic #3962 Task 1.4.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AphLfgUJWaFNAgU5UXdJ4n

* chore(lint): WP2 severity promotions + raw-fetch ban (#3962)

Promote three rules from warn→error (existing violations are frozen by
the count-based ratchet introduced in WP3; new occurrences are blocked):

• @typescript-eslint/no-explicit-any → 'error' (2,024 sites baselined)
• react-hooks/exhaustive-deps → 'error' (110 sites / 43 files baselined;
  do NOT auto-fix — missing deps in effect arrays can cause render loops)
• prefer-const → 'error' (34 sites — auto-fixed in the next commit)

Add a no-restricted-syntax block scoped to src/components/** and
src/pages/** banning bare fetch(), window.fetch(), and globalThis.fetch().
64 existing sites (25 component files, 3 page files) are frozen by the
ratchet baseline; they migrate to ApiService in Phase 5. Note: flat-config
array replacement means the SQL-ban selectors are not in this block —
components/pages never access the DB directly.

Part of remediation epic #3962 Task 1.4.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AphLfgUJWaFNAgU5UXdJ4n

* chore(lint): WP2 prefer-const auto-fix (let→const, 31 of 34 sites)

Run `eslint --fix --rule '{"prefer-const":"error"}' 'src/**/*.{ts,tsx}'`.
Every changed line is a bare let→const rename; no behavioral change.
3 residual sites (destructuring in RebootModal.tsx and apiTokenRoutes.ts)
could not be auto-fixed and are frozen by the lint ratchet baseline.

Part of remediation epic #3962 Task 1.4.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AphLfgUJWaFNAgU5UXdJ4n

* chore(lint): WP3 count-based ratchet + baseline (#3962)

Add scripts/lint-ratchet.mjs: a homegrown count-based per-file ESLint
ratchet. Semantics: for each file×rule, current > baseline → FAIL;
current < baseline → advisory only. Zero new npm dependencies.

Add scripts/lint-ratchet.test.mjs: 10 Vitest unit tests covering the
pure compare(), tally(), and sortObj() functions.

Add package.json scripts:
  lint:ci       → node scripts/lint-ratchet.mjs  (CI gate, blocking)
  lint:baseline → node scripts/lint-ratchet.mjs --update  (regenerate)

Add eslint-baseline.json (generated, NOT hand-edited):
  410 files · 2,515 violations frozen
  Top buckets: no-explicit-any 2,026 · no-unused-vars 175 ·
    exhaustive-deps 110 · no-restricted-syntax (fetch ban + SQL) 79 ·
    react-refresh 37 · prefer-const 3 (residual after auto-fix)
  Keys alphabetically sorted, 2-space indent, trailing newline.

npm run lint:ci exits 0 on HEAD (baseline matches current tree).

Part of remediation epic #3962 Task 1.4.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AphLfgUJWaFNAgU5UXdJ4n

* ci(lint): WP4 make lint blocking + document ratchet (#3962)

ci.yml: replace non-blocking 'npm run lint' (continue-on-error: true)
with blocking 'npm run lint:ci'. Existing violations are frozen by the
count-based baseline; only new regressions cause CI failures.

pr-tests.yml: replace 'npm run lint || true' with 'npm run lint:ci'.
Same semantics — blocking gate on new violations only.

CLAUDE.md: add ESLint ratchet subsection documenting:
- lint / lint:ci / lint:baseline commands and when to use each
- rules that are now errors (no-explicit-any, exhaustive-deps, prefer-const)
- raw fetch() ban in src/components/** and src/pages/**
- how to handle a legit new violation
- warning against baseline growth

Part of remediation epic #3962 Task 1.4.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AphLfgUJWaFNAgU5UXdJ4n

* chore(lint): detect fully-fixed files in ratchet advisory (#3962)

Add a second pass in compare() that scans baseline entries missing from
the current lint output (file became fully clean). Without this pass,
advisory messages only fire when a file still has *some* violation but
fewer than baseline — completely-fixed files were silently ignored.

Also add a Vitest unit test covering the fully-fixed-file advisory case.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AphLfgUJWaFNAgU5UXdJ4n

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: Yeraze

.github/workflows/ci.yml

@@ -69,9 +69,11 @@ jobs:
       - name: Install dependencies
         run: npm install --legacy-peer-deps
 
-      - name: Run linter
-        run: npm run lint
-        continue-on-error: true  # Pre-existing errors need cleanup before enforcing; tracked separately
+      - name: Run lint ratchet
+        # BLOCKING: fails only on new violations above the checked-in baseline.
+        # Existing debt is frozen in eslint-baseline.json and burns down over time.
+        # Regenerate baseline: npm run lint:baseline. Tracking: #3962 Task 1.4.
+        run: npm run lint:ci
 
       - name: Run type checking
         run: npm run typecheck

.github/workflows/pr-tests.yml

@@ -80,10 +80,13 @@ jobs:
           # Add prettier check when configured
           # npm run format:check
 
-      - name: Run linter
+      - name: Run lint ratchet
         run: |
-          echo "Running ESLint..."
-          npm run lint || true  # Don't fail for now
+          echo "Running ESLint ratchet..."
+          # BLOCKING: fails only on new violations above the checked-in baseline.
+          # Existing debt is frozen in eslint-baseline.json and burns down over time.
+          # Regenerate baseline: npm run lint:baseline. Tracking: #3962 Task 1.4.
+          npm run lint:ci
 
       - name: Type check
         run: |

CLAUDE.md

@@ -112,6 +112,21 @@ afterEach(() => harness.cleanup());
 - ESLint rule (`no-restricted-syntax` in `eslint.config.mjs`) forbids `this.db.prepare`, `this.db.exec`, `postgresPool.query`, `mysqlPool.query` outside `src/server/migrations/**` and test files.
 - Intentional exceptions must carry `// eslint-disable-next-line no-restricted-syntax -- <reason>`.
 
+### ESLint Ratchet (remediation #3962 Task 1.4)
+Three lint commands:
+- `npm run lint` — full ESLint report; noisy during burn-down (thousands of existing violations). For local exploration only.
+- `npm run lint:ci` — the **CI gate**. Runs `scripts/lint-ratchet.mjs`: fails only when a file's per-rule violation count exceeds the checked-in baseline (`eslint-baseline.json`). **This is what CI checks — it must exit 0.**
+- `npm run lint:baseline` — regenerate `eslint-baseline.json` from the current tree. Run **after intentionally fixing violations** (baseline shrinks). Never run it to paper over new ones — reviewers will flag a baseline that grows rule counts.
+
+**Rules now errors (existing violations frozen by baseline; burn them down, never up):**
+- `@typescript-eslint/no-explicit-any` — 2,026 sites baselined. Burn down in Phase 6.
+- `react-hooks/exhaustive-deps` — 110 sites. Do NOT auto-fix; missing deps can cause render loops. Fix per-site with behavior verification or a targeted `eslint-disable-next-line` with an issue-ref reason.
+- `prefer-const` — 3 residual sites (destructuring edge cases).
+
+**Raw `fetch()` banned in `src/components/**` and `src/pages/**`** — 64 existing sites frozen by baseline; they migrate to `ApiService` (`src/services/api.ts`) or a TanStack query hook in Phase 5. New components/pages must not use raw `fetch()`.
+
+**Adding a violation you can't avoid:** fix it, or add a targeted `// eslint-disable-next-line <rule> -- #<issue> <reason>`, or (last resort, with reviewer sign-off) `npm run lint:baseline`. Treat any PR that *grows* a rule count in the baseline as a red flag.
+
 ### Migration Registry
 Migrations use a centralized registry in `src/db/migrations.ts`. Each migration has functions for all three backends.