# MeshiTrack ESLint Remediation & Clean-up Plan

This document establishes a highly structured, quantitative, and actionable plan to resolve the remaining **ESLint violations** across the MeshiTrack monorepo. Following the auto-formatting runs (which successfully wiped out all 279 Prettier warnings), we have mapped out all remaining violations into distinct, manageable categories.

---

## 📊 1. Quantitative Breakdown of Remaining Violations

| Rule ID | API Package Violations | Web Package Violations | Total Violations | Critical Remediation Category |
| :--- | :---: | :---: | :---: | :--- |
| **`@typescript-eslint/explicit-function-return-type`** | 165 | 50 | **215** | Stage 2: Return Boundary Annotations |
| **`@typescript-eslint/no-unsafe-member-access`** | 63 | 117 | **180** | Stage 3: Unsafe-`any` Remediation & Unknown Parsing |
| **`@typescript-eslint/naming-convention`** | 76 | 43 | **119** | Stage 1: Fine-tuning Rule Rules |
| **`@typescript-eslint/no-unsafe-assignment`** | 43 | 33 | **76** | Stage 3: Unsafe-`any` Remediation & Unknown Parsing |
| **`@typescript-eslint/no-explicit-any`** | 15 | 38 | **53** | Stage 3: Type-safe Mocking & unknown Shift |
| **`@typescript-eslint/no-unsafe-return`** / **`no-unsafe-call`** | 43 | 25 | **68** | Stage 3: Unsafe-`any` Remediation & Unknown Parsing |
| **`@typescript-eslint/no-floating-promises`** / **`no-misused-promises`** | 4 | 26 | **30** | Stage 4: Safe Asynchronous Execution |
| **`@typescript-eslint/member-ordering`** | 15 | 4 | **19** | Stage 5: Structural Class Ordering |
| **Others** (e.g. `unused-vars`, `prefer-const`) | 5 | 5 | **10** | Stage 6: Minor Cleanups |
| **Total Structural Errors** | **428** | **341** | **769** | |

---

## 📅 2. Stage-by-Stage Remediation Strategy

### 🛠️ Stage 1: Rule Refinement (Remediation: ~120 Errors Resolved)
Before refactoring active files, we fine-tune our rules to represent real-world Javascript/TypeScript practices:
1. **Allow `PascalCase` on variables**: We have already enabled `PascalCase` for variables in both packages, allowing React component functions (e.g. `const TopBar = ...`) and database model objects (e.g. `const UserModel = ...`) to parse correctly.
2. **Exclude dynamic API/Database keys**: We will configure `@typescript-eslint/naming-convention` to ignore property names containing leading/trailing underscores (like `_id` and `__v`) or specific HTTP headers in controllers.

---

### 📝 Stage 2: Explicit Boundary Return Types (Remediation: 215 Errors Resolved)
To prevent type-drift, we will add explicit return signatures to the codebase:
1. **Service and Repository Boundaries**: Add explicit return types to all public methods in all services (e.g., `Promise<ShoppingListDocument[]>`, `Promise<void>`).
2. **Fastify Route Handlers**: Specify return types or configure ESLint to allow implicit handler return values since Fastify structures routing objects automatically.

---

### 🛡️ Stage 3: Unsafe-`any` Eradication (Remediation: 377 Errors Resolved)
The largest source of logic leaks resides in un-typed values and `as any` casting:
1. **Shift to `unknown` for Boundary Payloads**: For Fastify dynamic requests (`request.body`, `request.params`) and Next.js dynamic states, specify types as `unknown` and parse them safely via **Zod schemas**.
2. **Standardize Test Suite Mocks**: Replace `as any` mock variables in unit tests with type-safe mock generators or `Partial<T>` objects (e.g. using `vi.mocked()` correctly).

---

### ⚡ Stage 4: Floating Promises & misuses (Remediation: 30 Errors Resolved)
1. **Await floating promises**: Add correct `await` statements to database connections and route registrations.
2. **Explicit Background Tasks**: Mark intentional background hooks (like event logs) with `void` (e.g. `void this.logEvent(...)`) to document intention.

---

### 🧱 Stage 5: Structural Class Member Ordering (Remediation: 19 Errors Resolved)
1. Organize the 19 classes failing the ordering rule to place fields at the top, followed by constructors, followed by public methods, followed by private methods.