Architecture Decision Records
Architecture Decision Records
This project documents significant architectural decisions as ADRs. They are ordered by impact — from core architecture down to individual plugin choices.
Core Architecture
Fundamental decisions that define how this project works.
| # | Decision | Summary |
|---|---|---|
| ADR-0001 | Pre-built Configs | 16 ESLint + 8 OxLint permutations generated at build time |
| ADR-0002 | Code Generation | Emit real ES modules with imports instead of serializing config objects |
| ADR-0003 | Bitmask Hashing | Deterministic SHA-1 filenames from frozen bit positions |
Rule Philosophy
How rules are selected, configured, and organized.
| # | Decision | Summary |
|---|---|---|
| ADR-0004 | Curated Rules | Use presets as baselines, hand-pick every additional rule |
| ADR-0005 | Strict TypeScript | strictTypeChecked + projectService: true for maximum type safety |
| ADR-0006 | AI Mode | Dedicated ai: true flag for stricter rules on AI-generated code |
Integration Patterns
How configs, tools, and overrides fit together.
| # | Decision | Summary |
|---|---|---|
| ADR-0007 | File-Scoped Overrides | Six override blocks (tests, e2e, stories, configs, declarations, scripts) |
| ADR-0008 | Prettier Compatibility | eslint-config-prettier disables all formatting conflicts |
| ADR-0009 | OxLint Integration | @oxlint/migrate at build time, eslint-plugin-oxlint at runtime |
| ADR-0010 | OxLint over Biome | ESLint rule compatibility and Vite ecosystem alignment |
Plugin Decisions
Which plugins are included and why.
| # | Decision | Summary |
|---|---|---|
| ADR-0011 | Perfectionist | One plugin for all sorting (imports, exports, objects, interfaces) |
| ADR-0012 | Testing Plugins | Vitest, Playwright, Testing Library, Storybook — scoped by file pattern |
| ADR-0013 | CSpell | Spell checking for identifiers and comments (warn severity) |
| ADR-0014 | Rule-Helpers API | Five functions for post-load config customization |
Exclusion Decisions
Plugins and tools that were evaluated and intentionally not adopted.
| # | Decision | Summary |
|---|---|---|
| ADR-0015 | No eslint-plugin-promise | TypeScript + SonarJS already cover Promise patterns |
| ADR-0016 | No Framework Linting | No Next.js, Nuxt, Remix, or Tailwind plugins |
| ADR-0017 | @eslint-react Deferred | Superseded — re-evaluated and adopted in ADR-0019 |
| ADR-0018 | No @shopify/eslint-plugin | Only 2-3 useful rules out of 29 |
| ADR-0019 | Migration to @eslint-react | Replaces unmaintained eslint-plugin-react with modern engine |
| ADR-0020 | React Compat Plugin | Unified react/ namespace for OxLint-compatible legacy names |