@syntopica/eslint-config 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) BusiRocket
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLIC_API.md

@@ -0,0 +1,47 @@
+# Public API (`@syntopica/eslint-config`)
+
+Semver applies to **export subpaths** listed below. Import paths not listed here
+are **private** and may change without a major bump.
+
+## Stable exports (semver)
+
+| Export subpath                                 | Purpose                                                           |
+| ---------------------------------------------- | ----------------------------------------------------------------- |
+| `@syntopica/eslint-config/base`                | Core JS/TS correctness, imports, promise, security, Prettier last |
+| `@syntopica/eslint-config/nextjs`              | Next.js App Router + React + frontend boundaries                  |
+| `@syntopica/eslint-config/vite-react`          | Vite + React + frontend boundaries                                |
+| `@syntopica/eslint-config/astro`               | Astro + TS + frontend boundaries                                  |
+| `@syntopica/eslint-config/node`                | Node globals + unicorn prefer-node-protocol                       |
+| `@syntopica/eslint-config/nestjs`              | Node preset + NestJS decorator-aware rule tweaks                  |
+| `@syntopica/eslint-config/code-quality`        | Sonar + code-policy structural rules                              |
+| `@syntopica/eslint-config/accessibility`       | jsx-a11y                                                          |
+| `@syntopica/eslint-config/tailwind`            | Tailwind CSS plugin                                               |
+| `@syntopica/eslint-config/frontend-boundaries` | `eslint-plugin-boundaries` layer map only                         |
+| `@syntopica/eslint-config/testing`             | Vitest + Testing Library rules for test files                     |
+
+Each entry resolves to **TypeScript source** (`*.ts`) published in the package.
+Consumers load flat config with **ESM** and a TypeScript-aware runner (for
+example `jiti` or your bundler) as shown in the package README.
+
+## Implementation detail
+
+Internal modules under `src/` that are not re-exported through the table above
+are **not** public API.
+
+## `publint`/`attw` findings that are expected, not defects
+
+`publish:check` (`publint --strict && attw --pack . --profile node16`) ignores
+two `attw` rules for this package: `cjs-resolves-to-esm` and
+`internal-resolution-error`. Both are consequences of the no-build design above,
+not resolution bugs:
+
+- **`cjs-resolves-to-esm`** — every export subpath resolves to raw `.ts` ESM
+  source; there is no CommonJS build to satisfy a `require()` caller. Consumers
+  load these configs with ESM and a TypeScript-aware runtime (`jiti`), never
+  `require`.
+- **`internal-resolution-error`** — subpaths such as `./nextjs` and `./astro`
+  import framework packages (`@next/eslint-plugin-next`, `eslint-plugin-astro`,
+  etc.) declared as **optional peer dependencies**. `attw`'s sandbox only
+  contains this package's own tarball, so it cannot see peers a real consumer
+  installs, and flags those imports as unresolved. This is the intended shape of
+  an optional peer, not a broken `exports` entry.

package/README.md

@@ -0,0 +1,106 @@
+# @syntopica/eslint-config
+
+Flat ESLint configuration for JavaScript and TypeScript projects: shared
+**base** rules plus optional layers for Next.js, Vite + React, Astro, Node,
+Tailwind, accessibility, and code-quality (including
+`eslint-plugin-code-policy`).
+
+- **Public API (semver):** see [PUBLIC_API.md](./PUBLIC_API.md).
+- **Platform decisions:**
+  [engineering-baseline/docs/platform-decisions.md](https://github.com/BusiRocket/engineering-baseline/blob/main/docs/platform-decisions.md).
+
+## Requirements
+
+- Node.js 20+
+- ESLint 9+ (flat config)
+- TypeScript 5.4+ for type-aware linting
+
+Install `eslint` and `typescript` in your project, plus every package listed for
+the subpaths you import - see [Stacks](#stacks).
+
+This package ships **TypeScript source**, so each subpath's `import` statements
+are resolved from your project, not from a build. Under pnpm's isolated
+`node_modules` that means a plugin must be a direct dependency of the consumer
+even when it is a `dependencies` entry here: a missing one fails `tsc --noEmit`
+with `Cannot find module '<plugin>'` before ESLint ever runs. Optional peers are
+listed in `package.json` under `peerDependencies` / `peerDependenciesMeta`.
+
+## Install
+
+```bash
+pnpm add -D @syntopica/eslint-config@^0.1.0 eslint typescript
+```
+
+Add peers for the stacks you use (React, Next.js, Astro, and so on). The
+**base** stack ships several dependencies bundled with this package;
+framework-specific plugins remain peers.
+
+## New project
+
+1. Add `@syntopica/eslint-config` and peers for your stack.
+2. Add `eslint.config.ts` (or `.mjs`) using `jiti` / `tsx` / Node 22+ TypeScript
+   support as needed.
+3. Follow
+   [docs/adoption/new-repo.md](https://github.com/BusiRocket/engineering-baseline/blob/main/docs/adoption/new-repo.md).
+
+Minimal `eslint.config.ts` (Node / library):
+
+```ts
+import { createBaseConfig } from '@syntopica/eslint-config/base'
+
+export default createBaseConfig({ tsconfigRootDir: import.meta.dirname })
+```
+
+Next.js App Router: import `createNextjsConfig` from
+`@syntopica/eslint-config/nextjs` and compose with `createBaseConfig` as in the
+the Next.js template in
+[engineering-baseline](https://github.com/BusiRocket/engineering-baseline/tree/main/templates/nextjs-app).
+
+## Existing project
+
+See
+[docs/adoption/existing-repo.md](https://github.com/BusiRocket/engineering-baseline/blob/main/docs/adoption/existing-repo.md)
+and
+[docs/migration.md](https://github.com/BusiRocket/engineering-baseline/blob/main/docs/migration.md).
+Migrate to flat config first, then layer `@syntopica/eslint-config`.
+
+## Stacks
+
+Install the packages in the right-hand column alongside the subpath you import.
+The list is transitive: `/code-quality` also pulls in what `/testing` needs, and
+`/nestjs` what `/node` needs.
+
+| Import subpath         | Use case                               | Install alongside                                                                                                                                                                                           |
+| ---------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/base`                | Core TS/JS, imports, promise, security | `@eslint/js`, `eslint-config-prettier`, `eslint-plugin-import`, `eslint-import-resolver-typescript`, `eslint-plugin-promise`, `eslint-plugin-security`, `eslint-plugin-unused-imports`, `typescript-eslint` |
+| `/nextjs`              | Next.js + React + boundaries           | `@next/eslint-plugin-next`, `eslint-plugin-react`, `eslint-plugin-react-hooks`, `eslint-plugin-boundaries`                                                                                                  |
+| `/vite-react`          | Vite + React + boundaries              | `eslint-plugin-react`, `eslint-plugin-react-hooks`, `eslint-plugin-react-refresh`, `eslint-plugin-boundaries`                                                                                               |
+| `/vite-vue`            | Vite + Vue                             | `eslint-plugin-vue`, `eslint-plugin-vuejs-accessibility`, `vue-eslint-parser`, `eslint-plugin-unused-imports`, `typescript-eslint`                                                                          |
+| `/astro`               | Astro                                  | `eslint-plugin-astro`, `typescript-eslint`, `eslint-plugin-boundaries`                                                                                                                                      |
+| `/node`                | Node libraries                         | `eslint-plugin-unicorn`, `globals`                                                                                                                                                                          |
+| `/nestjs`              | NestJS services                        | `eslint-plugin-unicorn`, `globals`                                                                                                                                                                          |
+| `/code-quality`        | Sonar + code-policy                    | `eslint-plugin-code-policy`, `eslint-plugin-sonarjs`, `eslint-plugin-testing-library`, `@vitest/eslint-plugin`                                                                                              |
+| `/testing`             | Vitest + Testing Library               | `@vitest/eslint-plugin`, `eslint-plugin-testing-library`                                                                                                                                                    |
+| `/accessibility`       | jsx-a11y                               | `eslint-plugin-jsx-a11y`                                                                                                                                                                                    |
+| `/tailwind`            | Tailwind plugin                        | `eslint-plugin-tailwindcss`                                                                                                                                                                                 |
+| `/frontend-boundaries` | Boundaries only                        | `eslint-plugin-boundaries`                                                                                                                                                                                  |
+
+`/code-quality` composes `/testing` unconditionally, so
+`eslint-plugin-testing-library` is required there even in a project with no
+tests.
+
+## CLI helper
+
+```bash
+pnpm dlx @syntopica/create-baseline@^0.1.0 --check
+```
+
+`--soft` prints install commands; `--hard` also requires `eslint.config.*` in
+the repo root.
+
+## Related
+
+- **Plugin (rules only):** `eslint-plugin-code-policy` — full baseline is
+  composed here, not in the plugin.
+- **Prettier / TS configs:** `@syntopica/prettier-config`,
+  `@syntopica/tsconfig`.

package/eslint.config.ts

@@ -0,0 +1,7 @@
+import { createBaseConfig } from './src/base.ts'
+import { createNodeConfig } from './src/node.ts'
+
+export default [
+  ...createBaseConfig({ tsconfigRootDir: import.meta.dirname }),
+  ...createNodeConfig(),
+]

package/package.json

@@ -0,0 +1,186 @@
+{
+  "name": "@syntopica/eslint-config",
+  "version": "0.8.0",
+  "private": false,
+  "packageManager": "pnpm@11.25.0",
+  "license": "MIT",
+  "description": "Shared ESLint configuration baseline",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BusiRocket/baseline.git",
+    "directory": "packages/eslint-config"
+  },
+  "homepage": "https://github.com/BusiRocket/baseline/tree/main/packages/eslint-config#readme",
+  "bugs": {
+    "url": "https://github.com/BusiRocket/baseline/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "src",
+    "eslint.config.ts",
+    "tsconfig.json",
+    "PUBLIC_API.md"
+  ],
+  "exports": {
+    "./base": "./src/base.ts",
+    "./nextjs": "./src/nextjs.ts",
+    "./astro": "./src/astro.ts",
+    "./vite-react": "./src/vite-react.ts",
+    "./vite-vue": "./src/vite-vue.ts",
+    "./node": "./src/node.ts",
+    "./nestjs": "./src/nestjs.ts",
+    "./code-quality": "./src/code-quality.ts",
+    "./accessibility": "./src/accessibility.ts",
+    "./tailwind": "./src/tailwind.ts",
+    "./frontend-boundaries": "./src/frontend-boundaries.ts",
+    "./testing": "./src/testing.ts",
+    "./data-files": "./src/data-files.ts"
+  },
+  "scripts": {
+    "fix": "pnpm run lint:fix",
+    "lint": "eslint src --max-warnings 0",
+    "lint:fix": "eslint src --fix",
+    "lint:suppress": "eslint src --suppress-all",
+    "lint:prune": "eslint src --prune-suppressions",
+    "type-check": "tsc --noEmit -p tsconfig.json",
+    "publish:check": "baseline-licenses && publint --strict && attw --pack . --profile node16 --ignore-rules cjs-resolves-to-esm internal-resolution-error"
+  },
+  "dependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-promise": "^7.3.0",
+    "eslint-plugin-security": "^4.0.1",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "typescript-eslint": "^8.68.0"
+  },
+  "peerDependencies": {
+    "@eslint/markdown": ">=8.0.0",
+    "@next/eslint-plugin-next": ">=15.0.0",
+    "@vitest/eslint-plugin": ">=1.0.0",
+    "eslint": ">=9.0.0",
+    "eslint-config-next": ">=15.0.0",
+    "eslint-plugin-astro": ">=0.34.0",
+    "eslint-plugin-boundaries": ">=7.0.0",
+    "eslint-plugin-code-policy": ">=0.4.0",
+    "eslint-plugin-jsonc": ">=3.0.0",
+    "eslint-plugin-jsx-a11y": ">=6.8.0",
+    "eslint-plugin-react": ">=7.37.0",
+    "eslint-plugin-react-hooks": ">=5.0.0",
+    "eslint-plugin-react-refresh": ">=0.4.0",
+    "eslint-plugin-regexp": ">=2.7.0",
+    "eslint-plugin-sonarjs": ">=3.0.0",
+    "eslint-plugin-tailwindcss": "^4.2.0",
+    "eslint-plugin-testing-library": ">=7.0.0",
+    "eslint-plugin-unicorn": ">=57.0.0",
+    "eslint-plugin-vue": ">=10.0.0",
+    "eslint-plugin-vuejs-accessibility": ">=2.4.0",
+    "eslint-plugin-yml": ">=3.0.0",
+    "globals": ">=15.0.0",
+    "typescript": ">=5.4.0",
+    "vue-eslint-parser": ">=10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@next/eslint-plugin-next": {
+      "optional": true
+    },
+    "@vitest/eslint-plugin": {
+      "optional": true
+    },
+    "eslint-config-next": {
+      "optional": true
+    },
+    "eslint-plugin-astro": {
+      "optional": true
+    },
+    "eslint-plugin-boundaries": {
+      "optional": true
+    },
+    "eslint-plugin-code-policy": {
+      "optional": true
+    },
+    "eslint-plugin-jsx-a11y": {
+      "optional": true
+    },
+    "eslint-plugin-react": {
+      "optional": true
+    },
+    "eslint-plugin-react-hooks": {
+      "optional": true
+    },
+    "eslint-plugin-react-refresh": {
+      "optional": true
+    },
+    "eslint-plugin-sonarjs": {
+      "optional": true
+    },
+    "eslint-plugin-tailwindcss": {
+      "optional": true
+    },
+    "eslint-plugin-testing-library": {
+      "optional": true
+    },
+    "eslint-plugin-unicorn": {
+      "optional": true
+    },
+    "eslint-plugin-vue": {
+      "optional": true
+    },
+    "eslint-plugin-vuejs-accessibility": {
+      "optional": true
+    },
+    "globals": {
+      "optional": true
+    },
+    "vue-eslint-parser": {
+      "optional": true
+    },
+    "@eslint/markdown": {
+      "optional": true
+    },
+    "eslint-plugin-jsonc": {
+      "optional": true
+    },
+    "eslint-plugin-yml": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@eslint/markdown": "^8.0.3",
+    "@next/eslint-plugin-next": "^16.3.3",
+    "@types/node": "^26.4.0",
+    "@vitest/eslint-plugin": "^1.6.27",
+    "eslint": "^10.9.1",
+    "eslint-plugin-astro": "^3.1.0",
+    "eslint-plugin-boundaries": "^7.2.0",
+    "eslint-plugin-code-policy": "workspace:*",
+    "eslint-plugin-jsonc": "^3.4.2",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.5",
+    "eslint-plugin-regexp": "^3.2.0",
+    "eslint-plugin-sonarjs": "^4.2.0",
+    "eslint-plugin-tailwindcss": "^4.4.0",
+    "eslint-plugin-testing-library": "^7.16.2",
+    "eslint-plugin-unicorn": "^74.0.0",
+    "eslint-plugin-vue": "^10.10.0",
+    "eslint-plugin-vuejs-accessibility": "^2.6.0",
+    "eslint-plugin-yml": "^3.8.1",
+    "globals": "^17.11.0",
+    "jiti": "^2.7.0",
+    "publint": "^0.3.24",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vue-eslint-parser": "^10.4.1"
+  }
+}

package/src/accessibility.ts

@@ -0,0 +1,26 @@
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const jsxA11y = require('eslint-plugin-jsx-a11y') as {
+  flatConfigs: { recommended: unknown; strict: unknown }
+}
+
+/**
+ * Accessibility rules for JSX-based projects (React, Next.js, Astro).
+ * Enforces WCAG compliance at lint time: alt text, ARIA roles,
+ * keyboard navigation, form labels, and more.
+ *
+ * `strict`, not `recommended`. The two differ on the rules that catch the
+ * failures a sighted mouse user never sees: a `role` on an element that
+ * already has one, an interactive handler on a `div` with no keyboard
+ * equivalent, a label that is adjacent to its control rather than associated
+ * with it. `recommended` relaxes exactly those to keep large existing
+ * codebases green, which is the wrong trade for a baseline whose templates
+ * start at zero findings.
+ *
+ * Static analysis is half the gate: it reads the source, not the rendered
+ * tree, so a violation composed at runtime is invisible to it. The templates
+ * pair this with an axe assertion over the rendered component.
+ *
+ * Spread this as the final layer (after framework config, before architecture):
+ *   ...createAccessibilityConfig()
+ */
+export const createAccessibilityConfig = () => [jsxA11y.flatConfigs.strict]

package/src/astro.ts

@@ -0,0 +1,62 @@
+import astroPlugin from 'eslint-plugin-astro'
+import { globalIgnores } from 'eslint/config'
+import tseslint from 'typescript-eslint'
+
+import { createFrontendBoundariesConfig } from './frontend-boundaries'
+
+export type AstroConfigOptions = {
+  tsconfigRootDir?: string
+}
+
+type FlatConfigLike = Record<string, unknown>
+const astroConfigs = astroPlugin.configs as unknown as Record<
+  string,
+  FlatConfigLike[]
+>
+const astroRecommended = astroConfigs['flat/recommended'] ?? []
+const astroA11yRecommended = astroConfigs['flat/jsx-a11y-recommended'] ?? []
+
+export const createAstroConfig = (options: AstroConfigOptions = {}) => {
+  const tsconfigRootDir = options.tsconfigRootDir ?? process.cwd()
+
+  return [
+    globalIgnores(['dist/**', '.astro/**', 'coverage/**']),
+    ...astroRecommended,
+    ...astroA11yRecommended,
+    {
+      files: ['**/*.astro'],
+      languageOptions: {
+        parserOptions: {
+          parser: tseslint.parser,
+          project: true,
+          tsconfigRootDir,
+          extraFileExtensions: ['.astro'],
+        },
+      },
+    },
+    {
+      files: ['**/*.{ts,tsx}'],
+      languageOptions: {
+        parserOptions: {
+          projectService: true,
+          tsconfigRootDir,
+        },
+      },
+      rules: {
+        '@typescript-eslint/no-confusing-void-expression': 'off',
+        '@typescript-eslint/unbound-method': 'off',
+        '@typescript-eslint/require-await': 'off',
+        '@typescript-eslint/no-misused-promises': [
+          'error',
+          { checksVoidReturn: false },
+        ],
+      },
+    },
+    {
+      files: ['**/*.d.ts'],
+      rules: { '@typescript-eslint/triple-slash-reference': 'off' },
+    },
+    // Same layered boundaries as Next.js / Vite React (components, services, hooks, …)
+    ...createFrontendBoundariesConfig(),
+  ]
+}