@liberfi.io/eslint-config 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @liberfi.io/eslint-config
 
+## 0.1.18
+
+### Patch Changes
+
+- publish
+
+## 0.1.17
+
+### Patch Changes
+
+- publish
+
 ## 0.1.16
 
 ### Patch Changes

package/DESIGN-REVIEW.md

@@ -0,0 +1,68 @@
+# Design Review — `@liberfi.io/eslint-config`
+
+## Summary
+
+The `@liberfi.io/eslint-config` package centralises ESLint configuration for the entire monorepo using the modern flat config format. It integrates typescript-eslint, React, React Hooks, React Refresh, Prettier, Stylistic, and monorepo-cop into a single shareable config. The architecture is sound — one config consumed at the root level — but the implementation suffers from unused dependencies, duplicate rules, dead commented-out code, and a phantom tailwind rule reference. These issues add noise and could cause confusion or silent errors.
+
+## What's Done Well
+
+1. **Centralised, root-level config** — The config is consumed only at the root via `eslint.config.mjs`, so individual packages don't need their own ESLint setup. This is the cleanest pattern for monorepo linting.
+2. **Modern flat config** — Uses `defineConfig` and flat config arrays instead of the legacy `.eslintrc` format, aligning with ESLint v9+ direction.
+3. **Good plugin selection** — Covers the key areas: TypeScript type checking (`typescript-eslint`), React best practices (`eslint-plugin-react`, `react-hooks`, `react-refresh`), code style (`@stylistic`, `prettier`), and monorepo hygiene (`monorepo-cop`).
+4. **Sensible severity levels** — Most rules are set to `"warn"` rather than `"error"`, keeping the developer experience unblocking while still surfacing issues.
+5. **Prettier integration** — `eslint-config-prettier` is applied last, correctly disabling formatting rules that conflict with Prettier.
+6. **Monorepo boundary enforcement** — `monorepo-cop/no-relative-import-outside-package` at `"error"` level prevents cross-package relative imports.
+
+## Areas for Improvement
+
+1. **Unused dependencies in `package.json`** — Three packages are declared as dependencies but never imported in `index.mjs`: `@eslint/js`, `eslint-config-eslint`, `eslint-config-turbo`, and `eslint-plugin-import`. These inflate install time and create confusion about what's actually used. **Recommendation**: Remove all four from `dependencies`. If they're kept for future use, move them to comments in `package.json` or a TODO file.
+
+2. **Duplicate rules in the same block** — The following rules appear twice in the `rules` object, with the second declaration silently overriding the first:
+   - `@typescript-eslint/no-unused-vars` (both `"warn"`)
+   - `@typescript-eslint/ban-ts-comment` (`"warn"` then `"off"`)
+   - `@typescript-eslint/no-empty-object-type` (both `"warn"`)
+
+   The `ban-ts-comment` duplication is particularly problematic: it's set to `"warn"` then overridden to `"off"`, making the intent unclear. **Recommendation**: Remove the duplicates; keep only the intended final value for each rule.
+
+3. **Phantom `tailwindcss/no-custom-classname` rule** — This rule references the tailwind plugin, which is commented out. Depending on ESLint's handling, this either silently does nothing or throws an error when the plugin namespace isn't registered. **Recommendation**: Remove the rule. Re-add it when Tailwind v4 support lands.
+
+4. **Excessive commented-out code** — Large blocks of dead code (import plugin config, turbo config, tailwind config, `__dirname` setup) make the file hard to read. **Recommendation**: Remove commented-out blocks. Preserve intent via short TODO comments (one line each) and link to relevant issues if needed.
+
+5. **`eslint.config.fix.mjs` has dead tailwind comments** — The root `eslint.config.fix.mjs` contains a large commented-out block for tailwind rules. Same issue as above. **Recommendation**: Clean up in the same pass.
+
+6. **`apps/storybook` references non-existent `eslint-config-custom`** — `apps/storybook/eslint.config.js` imports from `eslint-config-custom`, which doesn't exist in the workspace. This is likely a leftover from a rename. **Recommendation**: Update it to import from `@liberfi.io/eslint-config`, or remove the file if storybook should use the root config.
+
+7. **No README.md** — No documentation on what rules are enabled, how to consume the config, or design rationale. **Recommendation**: Add a README per the project's package-readme standards.
+
+8. **Config is not parameterisable** — The exported config is a static array; consumers cannot customise it (e.g., add project-specific ignores or rule overrides) without spreading and modifying. **Recommendation**: Consider exporting a function that accepts options (e.g., `{ tailwind: boolean, strict: boolean }`) for flexibility, or document the spread-and-override pattern in the README.
+
+9. **`react-hooks/rules-of-hooks` set to `"warn"` instead of `"error"`** — Violating the rules of hooks causes runtime bugs, not style issues. This should almost always be `"error"`. **Recommendation**: Change to `"error"`.
+
+## Best Practices Checklist
+
+| Practice                     | Status                                               |
+| ---------------------------- | ---------------------------------------------------- |
+| Decoupling & boundaries      | Yes — single shared config at root                   |
+| Single responsibility        | Yes — only provides ESLint config                    |
+| Inversion of control         | Could improve — static config, not parameterisable   |
+| DRY / single source of truth | Could improve — duplicate rules, dead code           |
+| Dependency hygiene           | No — 4 unused dependencies declared                  |
+| API design                   | Could improve — no customisation API, no docs        |
+| State & side effects         | N/A                                                  |
+| Presentational vs container  | N/A                                                  |
+| Type safety                  | N/A                                                  |
+| Testability                  | N/A                                                  |
+| Error handling & feedback    | Could improve — phantom rule may cause silent errors |
+| Documentation                | No — missing README                                  |
+| Accessibility                | N/A                                                  |
+| Performance & bundle         | Could improve — unused deps increase install time    |
+
+## Review History
+
+| Date       | Summary                                                                                                                                                                                                                 |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 2026-03-04 | Initial design review. Identified unused dependencies (4), duplicate rules (3), phantom tailwind rule, excessive dead code, missing README, non-parameterisable config, and storybook referencing non-existent package. |
+
+## Conclusion
+
+The package successfully centralises ESLint configuration for the monorepo with a modern flat config approach and a well-chosen plugin set. The primary issues are hygiene-related: unused dependencies, duplicate rules, and dead commented-out code that obscure the actual configuration. Cleaning these up, adding a README, and fixing the phantom tailwind rule reference would significantly improve maintainability. The `react-hooks/rules-of-hooks` severity should be raised to `"error"` to prevent runtime bugs.

package/README.md

@@ -0,0 +1,102 @@
+# @liberfi.io/eslint-config
+
+Shared ESLint configuration for the Liberfi React SDK monorepo. Provides a single flat config that covers TypeScript, React, code style, and monorepo boundary enforcement, consumed at the root level so individual packages need no ESLint setup.
+
+## Design Philosophy
+
+- **Centralised, root-level config** — One config at the monorepo root; packages inherit it without duplicating setup.
+- **Modern flat config** — Uses ESLint v9+ `defineConfig` and flat config arrays, no legacy `.eslintrc`.
+- **Warnings over errors** — Most rules are `"warn"` to keep the DX unblocking while still surfacing issues; only critical rules (monorepo boundaries) are `"error"`.
+- **Prettier-last** — `eslint-config-prettier` is applied last to disable formatting rules that conflict with Prettier.
+
+## Installation
+
+This is a workspace-internal package. It is already included as a root-level dev dependency:
+
+```bash
+pnpm add -D @liberfi.io/eslint-config --workspace
+```
+
+### Peer Dependencies
+
+The consuming project must have `eslint` installed (v9+).
+
+## API Reference
+
+### Default Export
+
+The package exports a flat config array via `index.mjs`:
+
+```javascript
+import customEslintConfig from "@liberfi.io/eslint-config";
+```
+
+**Type:** `FlatConfig[]` — an array of ESLint flat config objects ready to pass to `defineConfig`.
+
+### Included Plugins & Configs
+
+| Plugin / Config               | Purpose                                          |
+| ----------------------------- | ------------------------------------------------ |
+| `typescript-eslint`           | TypeScript-aware linting (recommended preset)    |
+| `eslint-plugin-react`         | React best practices (recommended + jsx-runtime) |
+| `eslint-plugin-react-hooks`   | Rules of Hooks enforcement                       |
+| `eslint-plugin-react-refresh` | React Refresh / HMR compatibility                |
+| `@stylistic/eslint-plugin`    | Code style rules                                 |
+| `eslint-plugin-monorepo-cop`  | Prevents cross-package relative imports          |
+| `eslint-config-prettier`      | Disables rules that conflict with Prettier       |
+| `globals`                     | Browser globals                                  |
+
+### Key Rules
+
+| Rule                                              | Severity | Notes                                     |
+| ------------------------------------------------- | -------- | ----------------------------------------- |
+| `no-console`                                      | warn     | Allows `console.warn` and `console.error` |
+| `@typescript-eslint/no-explicit-any`              | warn     |                                           |
+| `@typescript-eslint/no-unused-vars`               | warn     |                                           |
+| `@typescript-eslint/no-namespace`                 | off      |                                           |
+| `@typescript-eslint/ban-ts-comment`               | off      |                                           |
+| `react/prop-types`                                | off      | TypeScript handles prop validation        |
+| `react-hooks/rules-of-hooks`                      | warn     |                                           |
+| `monorepo-cop/no-relative-import-outside-package` | error    | Enforces package boundaries               |
+| `react-refresh/only-export-components`            | off      |                                           |
+
+### Global Ignores
+
+The config ignores: `build/`, `dist/`, `node_modules/`, `public/`, `__test__/`, `storybook-static/`, `*.js`, `*.cjs`, `*.d.ts`.
+
+## Usage Examples
+
+### Root `eslint.config.mjs`
+
+```javascript
+import { defineConfig } from "eslint/config";
+import customEslintConfig from "@liberfi.io/eslint-config";
+
+export default defineConfig(customEslintConfig);
+```
+
+### With additional project-specific overrides
+
+```javascript
+import { defineConfig } from "eslint/config";
+import customEslintConfig from "@liberfi.io/eslint-config";
+
+export default defineConfig([
+  ...customEslintConfig,
+  {
+    rules: {
+      "no-console": "error",
+    },
+  },
+]);
+```
+
+## Future Improvements
+
+- Remove unused dependencies (`@eslint/js`, `eslint-config-eslint`, `eslint-config-turbo`, `eslint-plugin-import`).
+- Remove duplicate rule declarations in `index.mjs`.
+- Remove phantom `tailwindcss/no-custom-classname` rule (plugin is not active).
+- Clean up commented-out code blocks.
+- Add Tailwind CSS v4 plugin support when available.
+- Consider exporting a configurable function instead of a static array for consumer flexibility.
+- Raise `react-hooks/rules-of-hooks` to `"error"` (violations cause runtime bugs).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liberfi.io/eslint-config",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "main": "index.mjs",
   "module": "index.mjs",
   "license": "MIT",