@syntopica/eslint-config 0.8.0

package/src/base.ts

@@ -0,0 +1,252 @@
+import js from '@eslint/js'
+import prettier from 'eslint-config-prettier'
+import importPlugin from 'eslint-plugin-import'
+import unusedImports from 'eslint-plugin-unused-imports'
+import { globalIgnores } from 'eslint/config'
+import tseslint from 'typescript-eslint'
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const promisePlugin = require('eslint-plugin-promise') as Record<
+  string,
+  unknown
+>
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const regexp = require('eslint-plugin-regexp') as {
+  configs: {
+    'flat/recommended': {
+      plugins: Record<string, unknown>
+      rules: Record<string, unknown>
+    }
+  }
+}
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const security = require('eslint-plugin-security') as {
+  configs: {
+    recommended: {
+      plugins: Record<string, unknown>
+      rules: Record<string, unknown>
+    }
+  }
+}
+
+export type SharedConfigOptions = {
+  tsconfigRootDir?: string
+}
+
+// Root-level config files (eslint.config.ts, knip.config.ts, and any other
+// *.config.{ts,mjs,js}) sit outside a template tsconfig's `include: ["src"]`,
+// so the project service rejects them with "was not found by the project
+// service" the moment lefthook lints a staged file that touches one.
+// Reused below for both `allowDefaultProject` (so these globs get linted at
+// all) and `disableTypeChecked` (so they get linted with rules that don't
+// need real type information - see the comment at that block for why).
+const DEFAULT_PROJECT_FILE_GLOBS = [
+  '*.config.ts',
+  '*.config.mjs',
+  '*.config.js',
+  'eslint.config.ts',
+  'knip.config.ts',
+]
+
+export const createBaseConfig = (options: SharedConfigOptions = {}) => {
+  const tsconfigRootDir = options.tsconfigRootDir ?? process.cwd()
+
+  return [
+    globalIgnores([
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/build/**',
+      '**/coverage/**',
+      // Stryker's mutant sandbox: a copy of src with instrumentation woven
+      // through it. Linting it reports the instrumentation, not the code.
+      '**/.stryker-tmp/**',
+      '**/.next/**',
+      '**/.astro/**',
+      '**/.lighthouseci/**',
+      '**/out/**',
+      // Test fixtures are inputs, not code: a rule that reads the filesystem
+      // needs deliberately malformed sample files on disk, and linting them
+      // reports the very violations they exist to reproduce.
+      '**/tests/fixtures/**',
+      '**/__fixtures__/**',
+    ]),
+    // Scoped to JavaScript and TypeScript. Unscoped, ESLint's core
+    // recommendations apply to every file a config touches, including the
+    // Markdown, JSON and YAML that `data-files` adds - where a core rule that
+    // reaches for `sourceCode.getAllComments()` throws rather than reporting,
+    // taking the whole lint run down with a stack trace.
+    { ...js.configs.recommended, files: ['**/*.{js,jsx,ts,tsx,mjs,cjs}'] },
+    ...tseslint.configs.strictTypeChecked.map((config) => ({
+      ...config,
+      files: ['**/*.{ts,tsx}'],
+    })),
+    {
+      files: ['**/*.{ts,tsx}'],
+      languageOptions: {
+        parser: tseslint.parser,
+        ecmaVersion: 2024,
+        sourceType: 'module',
+        parserOptions: {
+          // allowDefaultProject lints DEFAULT_PROJECT_FILE_GLOBS with the
+          // default compiler options instead of a real tsconfig project.
+          // Entries must not contain `**` and are capped at 8 matched files
+          // by typescript-eslint - both satisfied by these root-level globs.
+          projectService: {
+            allowDefaultProject: DEFAULT_PROJECT_FILE_GLOBS,
+          },
+          tsconfigRootDir,
+        },
+      },
+      rules: {
+        '@typescript-eslint/no-explicit-any': 'error',
+        '@typescript-eslint/no-non-null-assertion': 'error',
+        '@typescript-eslint/no-floating-promises': 'error',
+        '@typescript-eslint/no-misused-promises': 'error',
+        '@typescript-eslint/consistent-type-imports': [
+          'error',
+          { prefer: 'type-imports', fixStyle: 'separate-type-imports' },
+        ],
+        '@typescript-eslint/switch-exhaustiveness-check': 'error',
+        // Prefer `type` over `interface` — consistent with the types-in-own-file convention
+        '@typescript-eslint/consistent-type-definitions': ['error', 'type'],
+        // Class properties that are never reassigned should be readonly
+        '@typescript-eslint/prefer-readonly': 'error',
+        // A function that returns a promise on one path and a value on
+        // another is awaited correctly by accident. Marking it `async`
+        // makes both paths a promise, which is what every caller assumes.
+        '@typescript-eslint/promise-function-async': 'error',
+        'no-unused-vars': 'off',
+      },
+    },
+    {
+      // The default compiler options behind allowDefaultProject don't carry
+      // the real tsconfig's module resolution and lib settings, so ordinary
+      // imports here (even Node builtins like `node:path`) come back as
+      // unresolved "error" types rather than their real types. Every rule
+      // above that needs real type information (no-floating-promises,
+      // no-misused-promises, switch-exhaustiveness-check, prefer-readonly,
+      // and the strictTypeChecked rules from the block above this one) would
+      // otherwise misfire on every import in these files. disableTypeChecked
+      // only turns off rules that require type information; the purely
+      // syntactic ones (no-explicit-any, consistent-type-imports, ...) still
+      // apply.
+      files: DEFAULT_PROJECT_FILE_GLOBS,
+      ...tseslint.configs.disableTypeChecked,
+    },
+    {
+      files: ['**/*.{js,jsx,ts,tsx,mjs,cjs}'],
+      plugins: {
+        import: importPlugin,
+        'unused-imports': unusedImports,
+      },
+      settings: {
+        'import/resolver': { typescript: true },
+        // eslint-plugin-import defaults to ['.js', '.mjs', '.cjs'] for its
+        // own cross-file export-map resolution (separate from the parser
+        // ESLint itself uses). Without .ts/.tsx/.jsx listed here, every rule
+        // that needs that resolution -- import/no-cycle included -- silently
+        // treats every non-JS file as unresolvable and reports nothing.
+        // Mirrors the `files` glob on this config block.
+        'import/extensions': ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx'],
+      },
+      rules: {
+        // Neither is in eslint:recommended, and neither is in
+        // strictTypeChecked: `==` against anything but null is a coercion
+        // nobody wrote on purpose, and a console.log is a debugging statement
+        // that reached production. `warn` and `error` stay allowed - they are
+        // the ones that are meant to ship.
+        eqeqeq: ['error', 'smart'],
+        'no-console': ['error', { allow: ['warn', 'error'] }],
+        'import/first': 'error',
+        'import/newline-after-import': 'error',
+        'import/no-duplicates': 'error',
+        'import/no-self-import': 'error',
+        // No maxDepth: shallow caps miss exactly the long cycles that tangle
+        // large codebases. `allowUnsafeDynamicCyclicDependency` stays off.
+        'import/no-cycle': ['error', { ignoreExternal: true }],
+        'unused-imports/no-unused-imports': 'error',
+        '@typescript-eslint/no-unused-vars': 'off',
+        'unused-imports/no-unused-vars': [
+          'error',
+          {
+            args: 'after-used',
+            argsIgnorePattern: '^_',
+            varsIgnorePattern: '^_',
+            ignoreRestSiblings: true,
+          },
+        ],
+      },
+    },
+    // ── Promise best practices ──────────────────────────────────────────────
+    // (no-floating-promises in TS block already covers unhandled Promises)
+    {
+      files: ['**/*.{js,jsx,ts,tsx,mjs,cjs}'],
+      plugins: { promise: promisePlugin },
+      rules: {
+        // prefer async/await over .then() chaining
+        'promise/prefer-await-to-then': 'warn',
+        // prefer async/await over callback patterns
+        'promise/prefer-await-to-callbacks': 'warn',
+        // no Promise inside .then() / .catch() (Promise hell)
+        'promise/no-nesting': 'error',
+        // no return Promise.resolve(x) inside .then() — redundant
+        'promise/no-return-wrap': 'error',
+        // resolve/reject param naming convention
+        'promise/param-names': 'error',
+      },
+    },
+    // ── Regular expressions ─────────────────────────────────────────────────
+    // `security/detect-non-literal-regexp` below only notices that a pattern
+    // came from a variable. This reads the pattern itself: catastrophic
+    // backtracking (ReDoS) written as a literal, an always-true assertion, a
+    // character class that does not match what it looks like, a useless flag.
+    // A real security class, statically decidable, and with a low enough
+    // false-positive rate that the recommended set is adopted as-is.
+    {
+      files: ['**/*.{js,jsx,ts,tsx,mjs,cjs}'],
+      plugins: {
+        regexp: regexp.configs['flat/recommended'].plugins['regexp'],
+      },
+      rules: { ...regexp.configs['flat/recommended'].rules },
+    },
+    // ── Security best practices ─────────────────────────────────────────────
+    {
+      files: ['**/*.{js,jsx,ts,tsx,mjs,cjs}'],
+      plugins: { security: security.configs.recommended.plugins['security'] },
+      rules: {
+        // eval() with a variable — always dangerous
+        'security/detect-eval-with-expression': 'error',
+        // non-literal RegExp — potential ReDoS
+        'security/detect-non-literal-regexp': 'warn',
+        // fs calls with non-literal paths — potential path traversal
+        'security/detect-non-literal-fs-filename': 'warn',
+        // timing-attack-prone equality checks (passwords, tokens)
+        'security/detect-possible-timing-attacks': 'warn',
+        // Math.random() for security purposes
+        'security/detect-pseudoRandomBytes': 'error',
+        // detect-object-injection intentionally OFF — too many false positives
+        // with normal bracket-notation array/object access
+      },
+    },
+    // ── dependency-cruiser's CommonJS config ────────────────────────────────
+    // Every repo adopting the baseline's quality gates writes a
+    // `.dependency-cruiser.cjs`: the tool loads CommonJS only, while the
+    // shared factory is TypeScript, so the file is CJS in an otherwise ESM
+    // project and reaches the factory through jiti. Without this it fails on
+    // `__filename`/`require`/`module` as undefined globals. The matching
+    // rule relaxation lives in the code-policy rule itself, so no order of
+    // config composition can defeat it.
+    {
+      files: ['**/.dependency-cruiser.cjs'],
+      languageOptions: {
+        globals: {
+          __filename: 'readonly',
+          __dirname: 'readonly',
+          module: 'writable',
+          require: 'readonly',
+        },
+      },
+    },
+    prettier,
+  ]
+}

package/src/code-quality-sonar.ts

@@ -0,0 +1,27 @@
+import sonarjs from 'eslint-plugin-sonarjs'
+
+/** Duplication and smell rules from eslint-plugin-sonarjs. Composed by code-quality. */
+export const createCodeQualitySonarConfig = () => [
+  {
+    files: ['**/*.{ts,tsx,js,jsx}'],
+    plugins: { sonarjs },
+    rules: {
+      'sonarjs/no-identical-functions': 'error',
+      'sonarjs/no-duplicated-branches': 'error',
+      'sonarjs/no-duplicate-string': ['warn', { threshold: 4 }],
+      // Cyclomatic `complexity` counts branches; this counts how hard the
+      // branching is to hold in your head, so nesting costs more than a flat
+      // sequence of guards. The two disagree in the direction that matters:
+      // a function with ten early returns is easy and scores 10 on
+      // cyclomatic, while three nested loops with a condition each is hard
+      // and scores 4. 15 is SonarSource's own default.
+      // `error`, not `warn`, and the difference is not severity: every lint
+      // script runs with --max-warnings 0, so a warning fails the build
+      // anyway. ESLint's bulk suppressions only apply to errors, and existing
+      // debt has to be expressible as `eslint-suppressions.json` - a file
+      // review can see and `lint:prune` can shrink - rather than as a raised
+      // threshold nobody ever lowers again.
+      'sonarjs/cognitive-complexity': ['error', 15],
+    },
+  },
+]

package/src/code-quality.ts

@@ -0,0 +1,119 @@
+/**
+ * Structural enforcement: atomic files, no inline types, view/hook split, import policy.
+ * Complexity + size: max-lines (100 hard cap), max-lines-per-function, cyclomatic complexity.
+ *
+ * Full rationale: docs/standards/code-quality.md and
+ * docs/standards/typescript-frontend-architecture.md
+ */
+
+import codePolicy from 'eslint-plugin-code-policy'
+
+import { createCodeQualitySonarConfig } from './code-quality-sonar'
+import { createTestingConfig } from './testing'
+
+export const createCodeQualityConfig = () => [
+  codePolicy.configs.recommended,
+  {
+    files: ['**/*.{ts,tsx,js,jsx}'],
+    rules: {
+      'max-lines': [
+        'error',
+        { max: 100, skipBlankLines: true, skipComments: true },
+      ],
+      'max-lines-per-function': [
+        'warn',
+        { max: 50, skipBlankLines: true, skipComments: true, IIFEs: true },
+      ],
+      complexity: ['warn', { max: 10 }],
+      'max-depth': ['warn', { max: 4 }],
+      'max-params': ['warn', { max: 4 }],
+    },
+  },
+  ...createCodeQualitySonarConfig(),
+  ...createTestingConfig(),
+  // Tooling and framework entrypoints are allowed to exceed the default file budget.
+  {
+    files: [
+      '**/*.config.{ts,js,mjs,cjs}',
+      '**/eslint.config.*',
+      '**/*.setup.{ts,tsx}',
+      '**/next-env.d.ts',
+      '**/vitest.config.*',
+      '**/playwright.config.*',
+    ],
+    rules: {
+      'max-lines': 'off',
+      'max-lines-per-function': 'off',
+    },
+  },
+  {
+    // Globs match createTestingConfig()'s: a helper under `tests/` or `test/`
+    // that is not itself named `*.test.ts` is still test scaffolding and must
+    // be judged by the same policy, not by the production one.
+    files: [
+      '**/*.{test,spec}.{ts,tsx}',
+      '**/__tests__/**/*.{ts,tsx}',
+      '**/tests/**/*.{ts,tsx}',
+      '**/test/**/*.{ts,tsx}',
+    ],
+    rules: {
+      // Tests get a real budget, not an exemption. 200 is deliberately looser
+      // than production's 100 - a test file carries arrange scaffolding its
+      // subject does not - but it is still a budget: past 200 lines a test
+      // file is covering more than one behaviour and should be split by
+      // behaviour, which is also what makes a failure easy to locate.
+      'max-lines': [
+        'error',
+        { max: 200, skipBlankLines: true, skipComments: true },
+      ],
+      // Off, not relaxed. In a test file the longest "function" is the
+      // top-level `describe` callback, so this rule measures the wrapper
+      // rather than any real complexity: 20 trivial `it` cases already report
+      // a 62-line arrow. Leaving it on would contradict the 200-line budget
+      // above and push authors to split `describe` blocks for no reason.
+      // File size is governed by max-lines; per-case size by review.
+      'max-lines-per-function': 'off',
+      // Placement stays enforced: it costs no extra code and it is what keeps
+      // a shared fixture findable. Detection is camelCase-prefix based
+      // (`useX`, `formatX`, `mapX`, ...), so a test colocated with its
+      // subject inherits the subject's folder and passes; what this actually
+      // forbids is the `tests/utils/` + `tests/helpers/` junk drawer.
+      'code-policy/file-kind-placement': 'error',
+      // Test files legitimately colocate inline fixture types, builders, and
+      // local helpers next to the cases that use them; the atomic-file/one-unit
+      // discipline targets production architecture, not test scaffolding.
+      // Enforcing these three would mean writing twice the code for the same
+      // tests - every local builder would have to be exported or extracted.
+      'code-policy/no-inline-types-in-runtime-files': 'off',
+      'code-policy/no-hidden-top-level-declarations': 'off',
+      'code-policy/one-primary-unit': 'off',
+    },
+  },
+  // Next.js App Router special files often coordinate wiring and metadata.
+  {
+    files: [
+      '**/app/**/page.tsx',
+      '**/app/**/layout.tsx',
+      '**/app/**/loading.tsx',
+      '**/app/**/error.tsx',
+      '**/app/**/not-found.tsx',
+      '**/app/**/route.ts',
+      '**/app/**/template.tsx',
+      '**/app/**/default.tsx',
+      '**/src/app/**/page.tsx',
+      '**/src/app/**/layout.tsx',
+      '**/src/app/**/loading.tsx',
+      '**/src/app/**/error.tsx',
+      '**/src/app/**/not-found.tsx',
+      '**/src/app/**/route.ts',
+      '**/src/app/**/template.tsx',
+      '**/src/app/**/default.tsx',
+    ],
+    rules: {
+      'max-lines': [
+        'warn',
+        { max: 120, skipBlankLines: true, skipComments: true },
+      ],
+    },
+  },
+]

package/src/data-files.ts

@@ -0,0 +1,71 @@
+import markdown from '@eslint/markdown'
+import jsonc from 'eslint-plugin-jsonc'
+import yml from 'eslint-plugin-yml'
+
+/**
+ * Correctness rules for the files that are not TypeScript.
+ *
+ * Prettier already makes JSON, YAML and Markdown *consistent*. Nothing made
+ * them *correct*: a duplicate key in a JSON config silently wins or loses
+ * depending on the parser, a YAML value that reads as a boolean because it is
+ * spelled `no`, a Markdown link that points at a heading that was renamed.
+ * None of that is a formatting question and none of it was caught anywhere in
+ * the estate.
+ *
+ * Formatting rules are deliberately absent from all three sets - Prettier owns
+ * layout, and a lint rule that disagrees with it produces a fight no one wins.
+ *
+ * Composed separately from `base` rather than added to it: these need their
+ * own parsers, and a project that has no YAML should not pay for one.
+ */
+export const createDataFilesConfig = () => [
+  ...jsonc.configs['flat/recommended-with-json'].map((config) => ({
+    ...config,
+    files: ['**/*.json'],
+  })),
+  ...jsonc.configs['flat/recommended-with-jsonc'].map((config) => ({
+    ...config,
+    files: ['**/*.jsonc', '**/tsconfig*.json', '**/.vscode/*.json'],
+  })),
+  {
+    // JSON with comments, by TypeScript's own definition: `tsconfig.json` is
+    // JSONC, and the block above sets the right parser for it but does not
+    // undo the `no-comments` the plain-JSON set turned on for `**/*.json`.
+    files: ['**/*.jsonc', '**/tsconfig*.json', '**/.vscode/*.json'],
+    rules: { 'jsonc/no-comments': 'off' },
+  },
+  ...yml.configs['flat/recommended'].map((config) => ({
+    ...config,
+    files: ['**/*.{yml,yaml}'],
+  })),
+  {
+    files: ['**/*.{yml,yaml}'],
+    rules: {
+      // `no`, `off`, `yes` and `on` are booleans in YAML 1.1 and strings in
+      // 1.2, and which one a reader gets depends on the parser. GitHub Actions
+      // reads `on:` as a key, Docker Compose does not. Quote the ambiguous
+      // ones and the question stops existing.
+      'yml/no-irregular-whitespace': 'error',
+      'yml/require-string-key': 'error',
+    },
+  },
+  ...markdown.configs.recommended.map((config) => ({
+    ...config,
+    files: ['**/*.md'],
+  })),
+  {
+    files: ['**/*.md'],
+    rules: {
+      // A heading level that jumps from 2 to 4 breaks every table of contents
+      // and every screen reader's outline. Both rules are structural, not
+      // stylistic, which is why they are on and the rest of the set is not.
+      'markdown/heading-increment': 'error',
+      'markdown/no-empty-links': 'error',
+      // Off: this repository's TODO files use `- [ ]` and `- [x]` task
+      // checkboxes, which the rule reads as shortcut reference links to
+      // undefined labels. Every hit is one of those, so the rule is pure
+      // noise here rather than wrong in general.
+      'markdown/no-missing-label-refs': 'off',
+    },
+  },
+]

package/src/eslint-config-next.d.ts

@@ -0,0 +1,2 @@
+declare module 'eslint-config-next/core-web-vitals'
+declare module 'eslint-config-next/typescript'

package/src/frontend-boundaries.ts

@@ -0,0 +1,92 @@
+import boundaries from 'eslint-plugin-boundaries'
+
+/**
+ * Layered import boundaries for frontend apps (Next.js App Router, Vite React,
+ * Vite Vue, Astro with React islands).
+ *
+ * Intent:
+ * - `components/**` stays UI-oriented: may import shared code, not service internals directly.
+ * - `hooks`, `composables`, `types`, `utils`, `const`, `lib`, `store` are shared ownership layers.
+ * - `services/**` holds integrations; may import shared utilities/types, not `components`.
+ * - Root/shared code may call into `services` so hooks can orchestrate providers without
+ *   leaking SDK details into TSX.
+ *
+ * @see docs/standards/typescript-frontend-architecture.md
+ *
+ * Migration note (eslint-plugin-boundaries v7):
+ * - Element patterns are folder prefixes with `partialMatch: false` (anchored at the
+ *   project root); this replaces v6's `mode: "full"` + `<pattern>/**\/*` full-path globs.
+ * - The per-rule option is `policies` (renamed from `rules` in v7).
+ * - Selectors use the entity model: `{ from: { element: { types } } }` and
+ *   `{ allow: { to: { element: { types: { anyOf } } } } }`.
+ */
+export const createFrontendBoundariesConfig = () => [
+  {
+    files: ['**/*.{js,jsx,ts,tsx,vue,mjs,cjs}'],
+    plugins: { boundaries },
+    settings: {
+      // Ensure TypeScript path aliases (e.g. @/*) resolve correctly for all file
+      // types including .vue and .astro, which are not covered by the base config's
+      // import/resolver setting (that only applies to .ts/.tsx/.js etc.).
+      'import/resolver': { typescript: true },
+      'boundaries/elements': [
+        // app layer
+        { type: 'app', pattern: ['app', 'src/app'], partialMatch: false },
+        // components layer
+        {
+          type: 'components',
+          pattern: ['components', 'src/components'],
+          partialMatch: false,
+        },
+        // shared layer: hooks, composables, types, lib, utils, const, constants, store, stores
+        {
+          type: 'shared',
+          pattern: [
+            'hooks',
+            'src/hooks',
+            'composables',
+            'src/composables',
+            'types',
+            'src/types',
+            'lib',
+            'src/lib',
+            'utils',
+            'src/utils',
+            'const',
+            'src/const',
+            'constants',
+            'src/constants',
+            'store',
+            'src/store',
+            'stores',
+            'src/stores',
+          ],
+          partialMatch: false,
+        },
+        // services layer: services, actions
+        {
+          type: 'services',
+          pattern: ['services', 'src/services', 'actions', 'src/actions'],
+          partialMatch: false,
+        },
+      ],
+    },
+    rules: {
+      'boundaries/dependencies': [
+        'error',
+        {
+          default: 'disallow',
+          policies: Object.entries({
+            app: ['app', 'components', 'shared', 'services'],
+            components: ['components', 'shared'],
+            shared: ['shared', 'services'],
+            services: ['services', 'shared'],
+          }).map(([from, to]) => ({
+            from: { element: { types: from } },
+            allow: { to: { element: { types: { anyOf: to } } } },
+          })),
+        },
+      ],
+    },
+  },
+]

package/src/nestjs.ts

@@ -0,0 +1,25 @@
+import { createNodeConfig } from './node'
+
+// NestJS service layer. Compose it like the other framework presets:
+//   createBaseConfig() + createNestjsConfig() + createCodeQualityConfig()
+// It builds on the node preset (Node globals + prefer-node-protocol) and only
+// adds the decorator-aware rule tweaks NestJS needs on top of the strict base.
+export const createNestjsConfig = () => [
+  ...createNodeConfig(),
+  {
+    files: ['**/*.ts'],
+    rules: {
+      // @Module(), @Injectable() and friends are intentionally empty classes
+      // whose only job is to carry a decorator; the strict base flags these as
+      // extraneous, so allow classes that exist solely to be decorated.
+      '@typescript-eslint/no-extraneous-class': [
+        'error',
+        { allowWithDecorator: true },
+      ],
+      // NestJS DI reads constructor parameter types at runtime via
+      // emitDecoratorMetadata. Forcing type-only imports would erase those
+      // class references and break injection, so keep value imports here.
+      '@typescript-eslint/consistent-type-imports': 'off',
+    },
+  },
+]