docs: ESLint rules analysis and implementation roadmap

[Copilot]

Analyzed codebase patterns and created actionable ESLint enhancement plan. Identified 9 notable patterns (custom error handling, minimal suppressions, strict assertions) and recommended 20 rules across 10 implementation PRs.

Documents

ESLINT_README.md

Navigation hub with 3 implementation paths (5min quick wins → 4 week comprehensive)

ESLINT_RECOMMENDATIONS.md

Deep analysis: current state (~700 errors), 9 patterns, 20 rules with rationale and priority rankings

ESLINT_PR_PROPOSALS.md

10 PR specifications with copy-paste configs, migration paths, testing strategies

ESLINT_QUICKSTART.md

Templates and commands for immediate implementation

ESLINT_DECISION_TREE.md

Visual guide for choosing implementation approach

Key Patterns

• Custom UsageError with fix suggestions
• Only 2 eslint-disable instances across ~75 TS files
• Already follows node: protocol imports
• Clean CLI/library separation for console usage

Recommendations Summary

Priority	Rules	Impact	Auto-fix
High	8	Security baseline, type imports, console rules	50%
Medium	7	Import order, return types, Node.js practices	60%
Low	5	Docs, comments, tests	20%

Quick wins (5min): Security + type imports = 20-30% coverage, zero breaking changes

Packages: 6 optional plugins (eslint-plugin-{import,n,unicorn,eslint-comments,jsdoc})

Example: Type Import Consistency (PR #2)

// eslint.config.js
{
  rules: {
    "@typescript-eslint/consistent-type-imports": ["error", {
      prefer: "type-imports",
      fixMergeTypeImports: true
    }]
  }
}

// Before
import { EventEmitter } from "node:events";
import { PlatformName, Platform } from "./types.js";

// After (auto-fixed)
import { EventEmitter } from "node:events";
import type { PlatformName, Platform } from "./types.js";

Target: ~700 errors → <100, no breaking changes, 50%+ auto-fixable

Original prompt

identify exciting patterns and suggest eslint rules to install / enable in separate PRs.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.