docs: ESLint rules analysis and implementation roadmap

ESLINT_DECISION_TREE.md

@@ -0,0 +1,223 @@
+# ESLint Rules Decision Tree
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Start: Which ESLint rules should I implement?             │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+           ┌─────────────────────┐
+           │ How much time do    │
+           │ you have?           │
+           └─┬─────────┬─────────┘
+             │         │
+    ┌────────┘         └────────┐
+    │                           │
+    ▼                           ▼
+┌───────────┐          ┌────────────────┐
+│ 5 minutes │          │ 4 weeks        │
+└─────┬─────┘          └────────┬───────┘
+      │                         │
+      ▼                         ▼
+┌─────────────────────┐   ┌──────────────────────┐
+│ QUICK WINS          │   │ COMPREHENSIVE        │
+│                     │   │                      │
+│ 1. Security rules   │   │ Week 1: High Priority│
+│    (zero violations)│   │ - Security           │
+│                     │   │ - Type imports       │
+│ 2. Type imports     │   │ - Console rules      │
+│    (auto-fix)       │   │                      │
+│                     │   │ Week 2: Medium       │
+│ 3. prefer-const     │   │ - Import order       │
+│    (auto-fix)       │   │ - Node.js rules      │
+│                     │   │                      │
+│ ✅ Zero breaking    │   │ Week 3: Return types │
+│ ✅ 20-30% rules     │   │ - Function returns   │
+│ ✅ Done in 5 min    │   │   (start with warn)  │
+└─────────────────────┘   │                      │
+                          │ Week 4+: Low Priority│
+                          │ - Documentation      │
+                          │ - Comment quality    │
+                          │ - Test standards     │
+                          │                      │
+                          │ ✅ All 20 rules      │
+                          │ ✅ ~700 → <100 errors│
+                          └──────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│  Or: Pick specific categories you care about                │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+        ┌────────────┴────────────┐
+        │                         │
+        ▼                         ▼
+  ┌──────────┐            ┌──────────────┐
+  │ Priority?│            │  Goal?       │
+  └─┬───┬───┬┘            └─┬────┬───┬───┘
+    │   │   │               │    │   │
+  High Medium Low          Type Code Security
+    │   │   │              Safety Org
+    │   │   │               │    │   │
+    ▼   ▼   ▼               ▼    ▼   ▼
+
+HIGH PRIORITY               TYPE SAFETY
+├─ Security (PR #3)         ├─ consistent-type-imports (PR #2)
+├─ Type imports (PR #2)     ├─ explicit-function-return-type (PR #5)
+└─ Console rules (PR #1)    └─ no-non-null-assertion
+
+MEDIUM PRIORITY             CODE ORGANIZATION
+├─ Import order (PR #4)     ├─ import/order (PR #4)
+├─ Return types (PR #5)     ├─ import/no-default-export (PR #4)
+└─ Node.js rules (PR #6)    └─ Comment quality (PR #8)
+
+LOW PRIORITY                SECURITY
+├─ Modern JS (PR #7)        ├─ no-eval (PR #3)
+├─ Comments (PR #8)         ├─ no-implied-eval (PR #3)
+└─ Docs (PR #9)             └─ prefer-promise-reject-errors (PR #3)
+
+┌─────────────────────────────────────────────────────────────┐
+│  Implementation Checklist                                   │
+└─────────────────────────────────────────────────────────────┘
+
+Phase 1: Immediate (No Breaking Changes)
+┌─────────────────────────────────────────┐
+│ □ Add security baseline rules           │  ← 2 min
+│ □ Add modern JS rules (no-var, etc)     │  ← 1 min
+│ □ Verify zero violations                │  ← 1 min
+│ □ Commit                                 │  ← 1 min
+└─────────────────────────────────────────┘  = 5 min total
+
+Phase 2: Auto-fixable (Week 1)
+┌─────────────────────────────────────────┐
+│ □ Install eslint-plugin-unicorn         │  ← 1 min
+│ □ Enable consistent-type-imports        │  ← 2 min
+│ □ Run npm run lint -- --fix             │  ← 1 min
+│ □ Review changes                         │  ← 5 min
+│ □ Commit                                 │  ← 1 min
+└─────────────────────────────────────────┘  = 10 min total
+
+Phase 3: Import Organization (Week 2)
+┌─────────────────────────────────────────┐
+│ □ Install eslint-plugin-import          │  ← 1 min
+│ □ Configure import/order                │  ← 3 min
+│ □ Run npm run lint -- --fix             │  ← 1 min
+│ □ Review changes                         │  ← 10 min
+│ □ Test builds                            │  ← 2 min
+│ □ Commit                                 │  ← 1 min
+└─────────────────────────────────────────┘  = 18 min total
+
+Phase 4: Gradual Adoption (Week 3-4)
+┌─────────────────────────────────────────┐
+│ □ Add no-console with CLI exceptions    │  ← 5 min config
+│ □ Add explicit-return-type as "warn"    │  ← 2 min config
+│ □ Address violations gradually          │  ← Ongoing
+│ □ Upgrade to "error" when ready         │  ← Later
+└─────────────────────────────────────────┘
+
+Phase 5: Additional Tooling (Ongoing)
+┌─────────────────────────────────────────┐
+│ □ Install eslint-plugin-n               │
+│ □ Install eslint-plugin-jsdoc (warn)    │
+│ □ Install eslint-plugin-eslint-comments │
+│ □ Add test-specific rules               │
+└─────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│  Success Metrics                                            │
+└─────────────────────────────────────────────────────────────┘
+
+Current State:
+  Lint errors:        ~700 (mostly no-unsafe-*)
+  eslint-disable:     2 instances
+  Config:             ESLint 9.32 + typescript-eslint 8.38
+
+After Quick Wins (5 min):
+  New rules:          6-8 rules enabled
+  Violations:         0 (all zero-impact)
+  Rules coverage:     20-30%
+
+After Comprehensive (4 weeks):
+  New rules:          20 rules enabled
+  Target violations:  <100 errors
+  Rules coverage:     100%
+  Packages added:     6 optional plugins
+
+┌─────────────────────────────────────────────────────────────┐
+│  Rule Categories Quick Reference                            │
+└─────────────────────────────────────────────────────────────┘
+
+Security (PR #3) ⭐⭐⭐
+  no-eval, no-implied-eval, no-throw-literal
+  Impact: Low | Auto-fix: No | Breaking: No
+
+Type Safety (PR #2, #5) ⭐⭐⭐
+  consistent-type-imports, explicit-function-return-type
+  Impact: High | Auto-fix: Partial | Breaking: No
+
+Code Org (PR #4) ⭐⭐
+  import/order, import/no-default-export
+  Impact: Medium | Auto-fix: Yes | Breaking: No
+
+Console (PR #1) ⭐⭐
+  no-console (with CLI exceptions)
+  Impact: Medium | Auto-fix: No | Breaking: No
+
+Node.js (PR #6) ⭐⭐
+  n/no-deprecated-api, n/prefer-node-protocol
+  Impact: Low | Auto-fix: Partial | Breaking: No
+
+Modern JS (PR #7) ⭐
+  prefer-const, no-var, prefer-template
+  Impact: Low | Auto-fix: Yes | Breaking: No
+
+Comments (PR #8) ⭐
+  no-warning-comments, eslint-comments/*
+  Impact: Low | Auto-fix: Partial | Breaking: No
+
+Docs (PR #9) ⭐
+  jsdoc/require-jsdoc
+  Impact: High | Auto-fix: No | Breaking: No
+
+Tests (PR #10) ⭐
+  Test-specific overrides
+  Impact: Low | Auto-fix: No | Breaking: No
+
+┌─────────────────────────────────────────────────────────────┐
+│  When to Use Which Document                                 │
+└─────────────────────────────────────────────────────────────┘
+
+ESLINT_README.md
+  ├─ First-time reading
+  ├─ Need overview
+  └─ Choosing your path
+
+ESLINT_RECOMMENDATIONS.md
+  ├─ Understanding patterns
+  ├─ Deep analysis
+  └─ The "why" behind rules
+
+ESLINT_PR_PROPOSALS.md
+  ├─ Creating PRs
+  ├─ Copy-paste configs
+  └─ Step-by-step guides
+
+ESLINT_QUICKSTART.md
+  ├─ Just getting started
+  ├─ Need templates
+  └─ Quick reference
+
+┌─────────────────────────────────────────────────────────────┐
+│  Decision: Start Now!                                       │
+└─────────────────────────────────────────────────────────────┘
+
+  Choose your path above ↑
+
+  Then:
+  1. Open the appropriate document
+  2. Follow the steps
+  3. Commit changes
+  4. Ship it! 🚀
+
+  All paths lead to better code quality!
+```