MeshiTrack/docs/lint_resolution_plan.md

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.