@niko464/eslint-config 0.0.1 → 0.1.0

package/README.md

@@ -1,3 +1,59 @@
 # @niko464/eslint-config
 
-Placeholder until v0.1. Plan: [Niko464/conventions#2](https://github.com/Niko464/conventions/issues/2).
+Shared ESLint flat-config blocks for Niko464's TypeScript projects. Each export is an array of config objects. Spread the ones a project needs into its own `eslint.config.*`.
+
+| Block    | For                              | What it turns on                                                                                                                                                                                           |
+| -------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `base`   | every TypeScript project         | `@niko464/no-comments`, and `linterOptions.noInlineConfig: true`, so no `eslint-disable` or inline rule comment has any effect                                                                             |
+| `react`  | React projects                   | `@niko464/no-effect-hooks`: bans `useEffect`, `useLayoutEffect` and `useInsertionEffect` from `react`, however they are imported                                                                           |
+| `shadcn` | Tailwind v4 + shadcn/ui projects | [`@shadcn/lint`](https://github.com/shadcn-ui/lint) with all six rules as errors: `no-restyle`, `no-raw-colors`, `no-arbitrary-values`, `no-inline-styles`, `no-unknown-classes`, `require-static-classes` |
+
+`@niko464/no-comments` reports every `//`, `/* */` and `/** */` comment except the tool directives: the shebang, `/// <reference`, `@ts-expect-error` and `prettier-ignore`. It has no autofix: what a comment says belongs in a name, a type, a test, `docs/` or an ADR, and only a person or an agent can move it there.
+
+`@niko464/no-effect-hooks` leaves `useEffectEvent`, `useSyncExternalStore` and ref callbacks allowed. Its error names the replacements: `useMountEffect`, `useEventListener` or `useInterval` from `@niko464/react-kit`, a `key`, a ref callback, deriving the value during render, or Motion for animation. A case none of these covers becomes a new hook in `@niko464/react-kit`, through a PR.
+
+## Install
+
+```bash
+pnpm add -D @niko464/eslint-config eslint typescript-eslint
+```
+
+ESLint 9.30 or later is required, and `@typescript-eslint/parser` 8.40 or later (it comes with `typescript-eslint`).
+
+## Use
+
+```js
+import { base, react, shadcn } from '@niko464/eslint-config';
+import tseslint from 'typescript-eslint';
+
+export default [...tseslint.configs.recommended, ...base, ...react, ...shadcn];
+```
+
+A project without React spreads only `base`. A project without Tailwind or shadcn/ui leaves out `shadcn`.
+
+### In a monorepo
+
+`defineConfig`'s `extends` scopes a block to part of the repo:
+
+```js
+import js from '@eslint/js';
+import { base, react, shadcn } from '@niko464/eslint-config';
+import { defineConfig } from 'eslint/config';
+import tseslint from 'typescript-eslint';
+
+export default defineConfig(
+  { ignores: ['dist/'] },
+  js.configs.recommended,
+  tseslint.configs.recommended,
+  {
+    files: ['apps/api/**/*.ts'],
+    rules: { 'no-restricted-imports': ['error', { patterns: ['@prisma/client'] }] },
+  },
+  base,
+  { files: ['apps/web/**/*.{ts,tsx}'], extends: [react, shadcn] },
+  { files: ['apps/web/components/ui/**'], rules: { 'shadcn/no-restyle': 'off' } },
+);
+```
+
+- The bans have their own rule IDs, so a project's own `no-restricted-imports` or `no-restricted-syntax` sits next to them without replacing them.
+- With inline config off, every exception lives in `eslint.config.*` as a `files`-scoped block, where review sees it.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { Linter } from 'eslint';
+export declare const base: Linter.Config[];
+export declare const react: Linter.Config[];
+export declare const shadcn: Linter.Config[];

package/dist/index.js

@@ -0,0 +1,42 @@
+import { plugin as shadcnPlugin } from '@shadcn/lint';
+import tsParser from '@typescript-eslint/parser';
+import { noComments } from "./no-comments.js";
+import { noEffectHooks } from "./no-effect-hooks.js";
+const plugin = {
+    meta: { name: '@niko464/eslint-config' },
+    rules: { 'no-comments': noComments, 'no-effect-hooks': noEffectHooks },
+};
+export const base = [
+    {
+        name: '@niko464/base',
+        plugins: { '@niko464': plugin },
+        linterOptions: { noInlineConfig: true },
+        rules: { '@niko464/no-comments': 'error' },
+    },
+];
+export const react = [
+    {
+        name: '@niko464/react',
+        plugins: { '@niko464': plugin },
+        rules: { '@niko464/no-effect-hooks': 'error' },
+    },
+];
+export const shadcn = [
+    {
+        name: '@niko464/shadcn',
+        files: ['**/*.{js,jsx,ts,tsx}'],
+        languageOptions: {
+            parser: tsParser,
+            parserOptions: { ecmaFeatures: { jsx: true } },
+        },
+        plugins: { shadcn: shadcnPlugin },
+        rules: {
+            'shadcn/no-restyle': 'error',
+            'shadcn/no-raw-colors': 'error',
+            'shadcn/no-arbitrary-values': 'error',
+            'shadcn/no-inline-styles': 'error',
+            'shadcn/no-unknown-classes': 'error',
+            'shadcn/require-static-classes': 'error',
+        },
+    },
+];

package/dist/no-comments.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from 'eslint';
+export declare const noComments: Rule.RuleModule;

package/dist/no-comments.js

@@ -0,0 +1,25 @@
+const TOOL_DIRECTIVES = [/^\s*@ts-expect-error(?:\s|:|$)/, /^\s*prettier-ignore\s*$/];
+const TRIPLE_SLASH_REFERENCE = /^\/\s*<reference\s/;
+const isToolDirective = (comment) => comment.type === 'Shebang' ||
+    (comment.type === 'Line' && TRIPLE_SLASH_REFERENCE.test(comment.value)) ||
+    TOOL_DIRECTIVES.some((pattern) => pattern.test(comment.value));
+export const noComments = {
+    meta: {
+        type: 'problem',
+        schema: [],
+        messages: {
+            comment: 'Comments are banned. Move what this comment says into a name, a type or a test, and put a "why" worth keeping in docs/ or an ADR.',
+        },
+    },
+    create(context) {
+        return {
+            Program() {
+                for (const comment of context.sourceCode.getAllComments()) {
+                    if (!isToolDirective(comment) && comment.loc) {
+                        context.report({ loc: comment.loc, messageId: 'comment' });
+                    }
+                }
+            },
+        };
+    },
+};

package/dist/no-effect-hooks.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from 'eslint';
+export declare const noEffectHooks: Rule.RuleModule;

package/dist/no-effect-hooks.js

@@ -0,0 +1,63 @@
+const EFFECT_HOOKS = new Set(['useEffect', 'useLayoutEffect', 'useInsertionEffect']);
+const keyName = (key, computed) => {
+    if (key.type === 'Literal')
+        return String(key.value);
+    if (key.type === 'Identifier' && !computed)
+        return key.name;
+    return null;
+};
+export const noEffectHooks = {
+    meta: {
+        type: 'problem',
+        schema: [],
+        messages: {
+            effect: '{{name}} is banned. Use useMountEffect, useEventListener or useInterval from @niko464/react-kit, a key, a ref callback, deriving the value during render, or Motion for animation. A case none of these covers becomes a new hook in @niko464/react-kit, through a PR.',
+        },
+    },
+    create(context) {
+        const reportIfEffect = (node, name) => {
+            if (name !== null && EFFECT_HOOKS.has(name)) {
+                context.report({ node, messageId: 'effect', data: { name } });
+            }
+        };
+        const reportNamespaceUse = (reference) => {
+            const identifier = reference.identifier;
+            const parent = identifier.parent;
+            if (parent?.type === 'MemberExpression' && parent.object === identifier) {
+                reportIfEffect(parent, keyName(parent.property, parent.computed));
+            }
+            if (parent?.type === 'VariableDeclarator' &&
+                parent.init === identifier &&
+                parent.id.type === 'ObjectPattern') {
+                for (const property of parent.id.properties) {
+                    if (property.type === 'Property') {
+                        reportIfEffect(property, keyName(property.key, property.computed));
+                    }
+                }
+            }
+        };
+        return {
+            ImportDeclaration(node) {
+                if (node.source.value !== 'react')
+                    return;
+                for (const specifier of node.specifiers) {
+                    const imported = specifier.type === 'ImportSpecifier' ? keyName(specifier.imported, false) : 'default';
+                    if (imported !== 'default') {
+                        reportIfEffect(specifier, imported);
+                        continue;
+                    }
+                    for (const variable of context.sourceCode.getDeclaredVariables(specifier)) {
+                        variable.references.forEach(reportNamespaceUse);
+                    }
+                }
+            },
+            ExportNamedDeclaration(node) {
+                if (node.source?.value !== 'react')
+                    return;
+                for (const specifier of node.specifiers) {
+                    reportIfEffect(specifier, keyName(specifier.local, false));
+                }
+            },
+        };
+    },
+};

package/package.json

@@ -1,7 +1,40 @@
 {
   "name": "@niko464/eslint-config",
-  "version": "0.0.1",
-  "description": "Placeholder until v0.1: see https://github.com/Niko464/conventions/issues/2",
-  "repository": { "type": "git", "url": "git+https://github.com/Niko464/conventions.git", "directory": "packages/eslint-config" },
-  "license": "MIT"
-}
+  "version": "0.1.0",
+  "description": "Shared ESLint flat-config blocks: a comment ban, an effect-hook ban and @shadcn/lint",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Niko464/conventions.git",
+    "directory": "packages/eslint-config"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "dependencies": {
+    "@shadcn/lint": "0.2.0"
+  },
+  "peerDependencies": {
+    "@typescript-eslint/parser": ">=8.40.0",
+    "eslint": "^9.30.0 || ^10.0.0"
+  },
+  "devDependencies": {
+    "@types/estree": "1.0.9",
+    "@typescript-eslint/parser": "8.71.1",
+    "eslint": "10.12.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  }
+}