@syntopica/eslint-config 0.8.0

package/src/nextjs.ts

@@ -0,0 +1,85 @@
+import nextPlugin from '@next/eslint-plugin-next'
+import reactHooks from 'eslint-plugin-react-hooks'
+import { globalIgnores } from 'eslint/config'
+
+import { createFrontendBoundariesConfig } from './frontend-boundaries'
+import { resolveReactVersion } from './react-version'
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const react = require('eslint-plugin-react') as {
+  configs: { flat: { recommended: unknown; 'jsx-runtime': unknown } }
+}
+
+export type NextjsConfigOptions = {
+  /**
+   * React version handed to `eslint-plugin-react`. Defaults to the version of
+   * the React installed beside the project, and only falls back to `'detect'`
+   * when that cannot be resolved - see `resolveReactVersion`.
+   */
+  reactVersion?: string
+  tsconfigRootDir?: string
+}
+
+// This preset registers @next/next, react and react-hooks itself and pulls only
+// Next's Core Web Vitals *rules* from @next/eslint-plugin-next. It does NOT spread
+// the full `eslint-config-next` flat config, because that package also registers
+// `import`, `jsx-a11y` and `@typescript-eslint` — plugins the layered baseline
+// (base + accessibility) already owns — which throws "Cannot redefine plugin".
+// `eslint-config-next` is kept as an optional peer dependency so standalone Next
+// projects that do not layer the full baseline can import it directly.
+const nextRules = {
+  ...nextPlugin.configs['core-web-vitals'].rules,
+}
+
+export const createNextjsConfig = (options: NextjsConfigOptions = {}) => {
+  return [
+    globalIgnores([
+      '.next/**',
+      'out/**',
+      'build/**',
+      'dist/**',
+      'coverage/**',
+      'next-env.d.ts',
+    ]),
+
+    // Core React correctness rules + automatic JSX transform (React 17+)
+    react.configs.flat.recommended,
+    react.configs.flat['jsx-runtime'],
+
+    // Unscoped on purpose: the two configs above carry no `files` key, so their
+    // rules can run on any linted file and each one would otherwise re-enter
+    // version detection.
+    {
+      settings: {
+        react: {
+          version: options.reactVersion ?? resolveReactVersion() ?? 'detect',
+        },
+      },
+    },
+
+    {
+      files: ['**/*.{js,jsx,ts,tsx}'],
+      plugins: {
+        '@next/next': nextPlugin,
+        'react-hooks': reactHooks,
+      },
+      rules: {
+        ...nextRules,
+        ...reactHooks.configs.recommended.rules,
+
+        // prevent {count && <Comp />} rendering "0" when count === 0
+        'react/jsx-no-leaked-render': 'error',
+        // avoid array index as list key (causes stale renders)
+        'react/no-array-index-key': 'warn',
+        // <MyComp></MyComp> → <MyComp /> (auto-fixable)
+        'react/self-closing-comp': 'warn',
+        // dangerouslySetInnerHTML opens XSS vectors
+        'react/no-danger': 'error',
+        // inline component definitions cause infinite re-mount loops
+        'react/no-unstable-nested-components': 'error',
+        // remove pointless <> wrappers
+        'react/jsx-no-useless-fragment': ['warn', { allowExpressions: true }],
+      },
+    },
+    ...createFrontendBoundariesConfig(),
+  ]
+}

package/src/node.ts

@@ -0,0 +1,28 @@
+import unicorn from 'eslint-plugin-unicorn'
+import globals from 'globals'
+
+export const createNodeConfig = () => [
+  {
+    // A CLI's stdout is its product, and a maintenance script's output is the
+    // reason it is run. `no-console` is an error everywhere else - a
+    // `console.log` in application code is a debugging statement that reached
+    // production - but forbidding it here would only produce a file of
+    // suppressions. Scoped by directory rather than by preset: a NestJS
+    // service composes this same config and its request handlers must not
+    // print to stdout.
+    files: ['**/bin/**/*.{ts,js,mjs,cjs}', '**/scripts/**/*.{ts,js,mjs,cjs}'],
+    rules: {
+      'no-console': 'off',
+    },
+  },
+  {
+    files: ['**/*.{ts,js,mjs,cjs}'],
+    languageOptions: {
+      globals: { ...globals.node },
+    },
+    plugins: { unicorn },
+    rules: {
+      'unicorn/prefer-node-protocol': 'error',
+    },
+  },
+]

package/src/react-version.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+
+/**
+ * The React version installed next to the project being linted, or `undefined`
+ * when it cannot be resolved.
+ *
+ * `settings.react.version: 'detect'` makes `eslint-plugin-react` walk up from
+ * the linted file with its own resolver, and on ESLint 10 that walk crashes:
+ * `resolveBasedir` still calls `context.getFilename()`, removed in ESLint 10,
+ * so every file fails with `contextOrFilename.getFilename is not a function`
+ * before a single rule runs (eslint-plugin-react 7.37.5, the newest published).
+ * Handing the plugin a concrete version skips detection entirely.
+ *
+ * Resolution is from `process.cwd()` - where ESLint is invoked - and not from
+ * this package, so a consumer's own React is found rather than whichever copy
+ * a hoisted install placed beside the config.
+ */
+export const resolveReactVersion = (): string | undefined => {
+  try {
+    const manifestPath = createRequire(import.meta.url).resolve(
+      'react/package.json',
+      { paths: [process.cwd()] },
+    )
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- path comes from require.resolve, not from user input
+    const manifest: unknown = JSON.parse(readFileSync(manifestPath, 'utf8'))
+
+    return typeof manifest === 'object' &&
+      manifest !== null &&
+      'version' in manifest &&
+      typeof manifest.version === 'string'
+      ? manifest.version
+      : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/tailwind.ts

@@ -0,0 +1,64 @@
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const tailwindcss = require('eslint-plugin-tailwindcss') as {
+  // v4 stable exposes a single flat-config object (v4 beta had 'flat/recommended' as an array).
+  configs: { recommended: object }
+}
+
+/**
+ * Tailwind CSS lint rules.
+ * Enforces class ordering, detects contradicting classes (e.g. `flex block`),
+ * promotes shorthands (e.g. `pt-4 pb-4` → `py-4`).
+ *
+ * `cssConfigPath` is MANDATORY since eslint-plugin-tailwindcss v4 stable: the
+ * plugin resolves the design system from the Tailwind v4 CSS entry file (the
+ * one with `@import "tailwindcss"`), e.g. `./src/styles.css`.
+ *
+ * `no-custom-classname` is intentionally disabled: real apps routinely mix
+ * Tailwind utilities with their own CSS layer (BEM-style classes, component
+ * classes) and custom prefixes, which this rule cannot distinguish from typos.
+ * On those codebases it produces overwhelming false-positive noise with no
+ * reliable signal, so it is off by default. Re-enable per-project with an
+ * allowlist (`settings.tailwindcss.whitelist`) if a project is utility-only.
+ *
+ * `classnames-order` is intentionally disabled too: `prettier-plugin-tailwindcss`
+ * (shipped in `@syntopica/prettier-config/frontend`) is the class sorter of
+ * record and orders classes differently from this rule. A project running
+ * both `eslint --fix` and `prettier --write` would see each pass fight the
+ * other's ordering, so `lint` and `format:check` could never agree at the
+ * same time. Prettier owns class ordering; this rule stays off to avoid the
+ * conflict.
+ *
+ * Requires `tailwindcss` to be installed in the consuming project.
+ * Only add this to projects that use Tailwind CSS.
+ */
+export const createTailwindConfig = (options: { cssConfigPath: string }) => {
+  // eslint.config.ts is loaded by jiti at runtime, which does not type-check
+  // the call, so a missing option surfaces as a bare
+  // "Cannot read properties of undefined" thrown from inside ESLint with no
+  // hint about which factory asked for what. Say it plainly instead.
+  // The type says `options` is required, and for a TypeScript caller it is.
+  // At runtime it is whatever the config file passed, so the check is real.
+  const given = options as { cssConfigPath?: string } | undefined
+  if (!given?.cssConfigPath) {
+    throw new Error(
+      'createTailwindConfig requires { cssConfigPath }. ' +
+        'eslint-plugin-tailwindcss v4 resolves the design system from your ' +
+        'Tailwind CSS entry file - the one with `@import "tailwindcss"` - so ' +
+        "pass it: createTailwindConfig({ cssConfigPath: './src/styles.css' }).",
+    )
+  }
+
+  return [
+    tailwindcss.configs.recommended,
+    {
+      files: ['**/*.{js,jsx,ts,tsx,vue,astro,html}'],
+      settings: {
+        tailwindcss: { cssConfigPath: options.cssConfigPath },
+      },
+      rules: {
+        'tailwindcss/no-custom-classname': 'off',
+        'tailwindcss/classnames-order': 'off',
+      },
+    },
+  ]
+}

package/src/testing.ts

@@ -0,0 +1,35 @@
+import vitest from '@vitest/eslint-plugin'
+import testingLibrary from 'eslint-plugin-testing-library'
+
+/**
+ * Test-file rules. These catch what review misses in a green build: a
+ * committed `.only` silently skipping the rest of the suite, a test with no
+ * assertion, and Testing Library queries whose promises are never awaited.
+ *
+ * `eslint-plugin-vitest` is deprecated; `@vitest/eslint-plugin` is its
+ * maintained successor.
+ */
+export const createTestingConfig = () => [
+  {
+    files: [
+      '**/*.{test,spec}.{ts,tsx}',
+      '**/__tests__/**/*.{ts,tsx}',
+      '**/test/**/*.{ts,tsx}',
+    ],
+    plugins: { vitest, 'testing-library': testingLibrary },
+    rules: {
+      'vitest/no-focused-tests': ['error', { fixable: false }],
+      'vitest/no-disabled-tests': 'warn',
+      'vitest/no-identical-title': 'error',
+      'vitest/expect-expect': 'error',
+      'vitest/valid-expect': 'error',
+      'vitest/no-conditional-expect': 'error',
+      'testing-library/await-async-queries': 'error',
+      'testing-library/await-async-utils': 'error',
+      'testing-library/no-await-sync-queries': 'error',
+      'testing-library/no-container': 'error',
+      'testing-library/no-node-access': 'warn',
+      'testing-library/prefer-screen-queries': 'error',
+    },
+  },
+]

package/src/vite-react.ts

@@ -0,0 +1,64 @@
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+
+import { createFrontendBoundariesConfig } from './frontend-boundaries'
+import { resolveReactVersion } from './react-version'
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const react = require('eslint-plugin-react') as {
+  configs: { flat: { recommended: unknown; 'jsx-runtime': unknown } }
+}
+
+export type ViteReactConfigOptions = {
+  /**
+   * React version handed to `eslint-plugin-react`. Defaults to the version of
+   * the React installed beside the project, and only falls back to `'detect'`
+   * when that cannot be resolved - see `resolveReactVersion`.
+   */
+  reactVersion?: string
+}
+
+export const createViteReactConfig = (options: ViteReactConfigOptions = {}) => [
+  // Core React correctness rules + automatic JSX transform (React 17+)
+  react.configs.flat.recommended,
+  react.configs.flat['jsx-runtime'],
+  // Unscoped on purpose: the two configs above carry no `files` key, so their
+  // rules can run on any linted file and each one would otherwise re-enter
+  // version detection.
+  {
+    settings: {
+      react: {
+        version: options.reactVersion ?? resolveReactVersion() ?? 'detect',
+      },
+    },
+  },
+  {
+    files: ['**/*.{ts,tsx,js,jsx}'],
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      // hooks rules
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': [
+        'warn',
+        { allowConstantExport: true },
+      ],
+
+      // prevent {count && <Comp />} rendering "0" when count === 0
+      'react/jsx-no-leaked-render': 'error',
+      // avoid array index as list key (causes stale renders)
+      'react/no-array-index-key': 'warn',
+      // <MyComp></MyComp> → <MyComp /> (auto-fixable)
+      'react/self-closing-comp': 'warn',
+      // dangerouslySetInnerHTML opens XSS vectors
+      'react/no-danger': 'error',
+      // inline component definitions cause infinite re-mount loops
+      'react/no-unstable-nested-components': 'error',
+      // remove pointless <> wrappers
+      'react/jsx-no-useless-fragment': ['warn', { allowExpressions: true }],
+    },
+  },
+  // Same layered boundaries as Next.js (src/components, src/services, etc.)
+  ...createFrontendBoundariesConfig(),
+]

package/src/vite-vue.ts

@@ -0,0 +1,88 @@
+import unusedImports from 'eslint-plugin-unused-imports'
+import tseslint from 'typescript-eslint'
+
+import { createFrontendBoundariesConfig } from './frontend-boundaries'
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const pluginVue = require('eslint-plugin-vue') as {
+  configs: Record<string, unknown[]>
+}
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vueA11y = require('eslint-plugin-vuejs-accessibility') as {
+  configs: Record<string, unknown[]>
+}
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vueParser = require('vue-eslint-parser') as {
+  parseForESLint: (...args: unknown[]) => unknown
+}
+
+export type ViteVueConfigOptions = {
+  tsconfigRootDir?: string
+}
+
+/**
+ * Vue 3 SFC linting layer for Vite apps.
+ *
+ * - eslint-plugin-vue `flat/recommended` (highest priority tier: essential +
+ *   strongly-recommended + recommended).
+ * - eslint-plugin-vuejs-accessibility `flat/recommended` (jsx-a11y does not lint
+ *   `.vue` SFCs, so Vue gets its own a11y layer here).
+ * - `.vue` files parsed by vue-eslint-parser with typescript-eslint as the
+ *   `<script lang="ts">` parser (type-aware via projectService).
+ * - Reuses the shared frontend import boundaries.
+ */
+export const createViteVueConfig = (options: ViteVueConfigOptions = {}) => {
+  const tsconfigRootDir = options.tsconfigRootDir ?? process.cwd()
+  const vueRecommended = pluginVue.configs['flat/recommended'] ?? []
+  const a11yRecommended = vueA11y.configs['flat/recommended'] ?? []
+
+  return [
+    ...vueRecommended,
+    ...a11yRecommended,
+    {
+      files: ['**/*.vue'],
+      languageOptions: {
+        parser: vueParser,
+        parserOptions: {
+          parser: tseslint.parser,
+          projectService: true,
+          tsconfigRootDir,
+          extraFileExtensions: ['.vue'],
+          ecmaVersion: 2024,
+          sourceType: 'module',
+        },
+      },
+      plugins: {
+        'unused-imports': unusedImports,
+      },
+      rules: {
+        // TypeScript (not core ESLint) resolves identifiers inside `<script
+        // setup lang="ts">`; core `no-undef` cannot see ambient/global types and
+        // would false-positive on them. typescript-eslint disables it for .ts
+        // for the same reason — mirror that for .vue SFCs.
+        'no-undef': 'off',
+        // Unused-binding handling consistent with the .ts layer: defer to
+        // unused-imports with the `_`-prefix escape hatch.
+        'no-unused-vars': 'off',
+        'unused-imports/no-unused-vars': [
+          'error',
+          {
+            args: 'after-used',
+            argsIgnorePattern: '^_',
+            varsIgnorePattern: '^_',
+            ignoreRestSiblings: true,
+          },
+        ],
+        // raw HTML binding is an XSS vector
+        'vue/no-v-html': 'error',
+        // force the type-based defineProps<...>() form
+        'vue/define-props-declaration': ['error', 'type-based'],
+        // refs must carry a type when it cannot be inferred
+        'vue/require-typed-ref': 'error',
+        // multi-word component names (root App is the conventional exception)
+        'vue/multi-word-component-names': ['error', { ignores: ['App'] }],
+      },
+    },
+    ...createFrontendBoundariesConfig(),
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024"],
+    "strict": true,
+    "noEmit": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src/**/*.ts", "eslint.config.ts"]
+}