eslint-plugin-ai-rules 0.2.1 → 0.3.0

package/README.md

@@ -2,61 +2,212 @@
 
 [![npm version](https://img.shields.io/npm/v/eslint-plugin-ai-rules)](https://www.npmjs.com/package/eslint-plugin-ai-rules)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
-[![eslint ^9](https://img.shields.io/badge/eslint-%5E9-4B32C3)](https://eslint.org)
+[![node >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)
+[![eslint 9.22+ / 10](https://img.shields.io/badge/eslint-%5E9.22%20%7C%7C%20%5E10-4B32C3)](https://eslint.org)
 
-Flat-config only ESLint plugin that bundles useful rules for AI-generated code. Ships a `recommended` preset with all rules enabled as `error` — zero config for consumers.
+Flat-config-only ESLint plugin for AI-generated code. It catches filename/import drift and enforces a project structure you declare, with ready-to-use `frontend` and `backend` presets.
 
-> **ESLint 9+ only.** Uses flat config (`eslint.config.{ts,js}`) and `eslint/config` `defineConfig`. No legacy `.eslintrc` support.
+> **ESLint 9.22+ or 10 only.** Uses flat config (`eslint.config.{js,mjs,ts}`). No legacy `.eslintrc` support.
 
-## Features
+## Start here
 
-- **AI Rules rules** — catches typical AI drift: wrong filename casing, unsorted/multiline imports
-- **Bundled preset** — `aiRules.configs.recommended` enables custom + `import-x`, `@stylistic`, `typescript-eslint` rules out of the box
-- **Autofix** — `sort-imports` and `no-multiline-imports` are `fixable: code` (`eslint --fix`)
-- **Dual build** — `dist/index.js` (ESM) + `dist/index.cjs` (CJS) via `tsup`, single-file bundle, `type: module`
+| If your project is... | Use |
+|-----------------------|-----|
+| Frontend only | `preset: 'frontend'` |
+| Backend only | `preset: 'backend'` |
+| Frontend + backend in one repo | two projects with different `rootFolder` |
+| Neither frontend nor backend | `preset: 'other'` |
+| Layered architecture | `relations` (controller → useCase → repository) |
 
-## Requirements
+Before installing, check:
 
-- Node `>=18` (`package.json` `engines`)
-- ESLint `^9.0.0` (peer) — flat config only
-- TypeScript `>=5.0.0` (peer)
+- Node.js `>= 20`
+- ESLint `^9.22.0` or `^10.0.0`
+- TypeScript `>= 5.0.0 < 6.1.0`
+- `typescript-eslint` configured as parser
+- `tsconfig.json` if you use aliases like `@/*`
+- `eslint-import-resolver-typescript` installed for TS alias resolution
 
-`@eslint/js`, `eslint-plugin-import-x`, `@stylistic/eslint-plugin`, `typescript-eslint`, `globals` are already `dependencies` — you don't need to install them.
+## Quick start
 
-## Installation
+Install:
 
 ```bash
-# npm
-npm i -D eslint-plugin-ai-rules eslint typescript
+npm i -D eslint-plugin-ai-rules eslint typescript typescript-eslint eslint-import-resolver-typescript
+```
 
-# yarn
-yarn add -D eslint-plugin-ai-rules eslint typescript
+Configure the project structure and let the plugin apply its recommended rules:
 
-# pnpm
-pnpm add -D eslint-plugin-ai-rules eslint typescript
+```ts
+import { defineConfig } from 'eslint/config'
+import aiRules from 'eslint-plugin-ai-rules'
+import tseslint from 'typescript-eslint'
 
-# bun
-bun add -d eslint-plugin-ai-rules eslint typescript
+export default defineConfig([
+  ...tseslint.configs.recommended,
+  ...aiRules.configs.projects([
+    { rootFolder: '.', preset: 'frontend' },
+  ]),
+])
 ```
 
-## Quick Start
+Monorepo with frontend and backend:
 
-### `eslint.config.ts` (recommended) — you define `files`
+```ts
+export default defineConfig([
+  ...tseslint.configs.recommended,
+  ...aiRules.configs.projects([
+    { rootFolder: 'apps/web', preset: 'frontend' },
+    { rootFolder: 'apps/api', preset: 'backend' },
+  ]),
+])
+```
 
-`recommended` is file-agnostic (only `plugins` + `settings` + `rules`) and does **not** configure a parser. Pair it with `typescript-eslint` (or `@typescript-eslint/parser`) and define `files`:
+Project that is neither frontend nor backend:
 
 ```ts
+export default defineConfig([
+  ...tseslint.configs.recommended,
+  ...aiRules.configs.projects([
+    { rootFolder: '.', preset: 'other' },
+  ]),
+])
+```
+
+Run:
+
+```bash
+npx eslint .
+npx eslint --fix .
+```
+
+## Contents
+
+- [Configuration warning](#configuration-warning)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Project structure](#project-structure)
+- [Examples](#examples)
+- [Architecture relations](#architecture-relations)
+- [Expected diagnostics](#expected-diagnostics)
+- [Preset reference](#preset-reference)
+- [Structure DSL](#structure-dsl)
+- [Limitations](#limitations)
+- [Rules](#rules)
+- [What runs automatically](#what-runs-automatically)
+- [Recommended preset](#recommended-preset)
+- [Troubleshooting](#troubleshooting)
+- [Common mistakes](#common-mistakes)
+- [Migrating from 0.2.x](#migrating-from-02x)
+- [Development](#development)
+- [Publishing](#publishing)
+- [Legacy](#legacy)
+
+## Configuration warning
+
+If you install the plugin and use `aiRules.configs.recommended` without configuring the project structure, the plugin prints a warning the first time it lints a file:
+
+```text
+[eslint-plugin-ai-rules] Project structure validation is not configured.
+Configure it with aiRules.configs.projects([{ rootFolder: '.', preset: 'frontend' | 'backend' }]).
+If this project is not a frontend/backend, use preset: 'other' to disable this warning.
+```
+
+The warning exists only to make sure the new structure rules are actually configured. It is printed once per process.
+
+It disappears when you provide a valid configuration:
+
+- `preset: 'frontend'`
+- `preset: 'backend'`
+- `preset: 'other'`
+- a custom non-empty `structure`
+- a `relations` configuration
+
+A project containing only `rootFolder` and an empty `structure` is still considered unconfigured and will warn.
+
+For CI or temporary runs, silence the warning without changing the config:
+
+```bash
+AI_RULES_SILENT=1 npx eslint .
+```
+
+The warning is still recommended as a setup check, so prefer `preset: 'other'` for projects that intentionally do not use structure validation.
+
+## Features
+
+- **Project structure validation** — folder hierarchy, dynamic folders, folder/file casing, prefixes, suffixes and regex patterns.
+- **Frontend/backend presets** — ready-to-use structures and architecture relations based on real projects.
+- **Custom structure** — declare exactly how your project must be organized.
+- **Architecture relations** — enforce which layers can import which other layers, including global vs page-local scope.
+- **Monorepo friendly** — one `rootFolder` per project, including nested roots.
+- **Autofix** — `sort-imports` and `no-multiline-imports` are fixable.
+- **Bundled rules** — ships with useful `import-x`, `@stylistic`, `boundaries` and `@typescript-eslint` rules.
+- **ESM + CJS** — `dist/index.js` and `dist/index.cjs`, with correct type declarations for both.
+
+## Requirements
+
+| Tool | Version |
+|------|---------|
+| Node.js | `>= 20` |
+| ESLint | `^9.22.0 || ^10.0.0` |
+| TypeScript | `>= 5.0.0 < 6.1.0` |
+| ESLint resolver | `eslint-import-resolver-typescript` `^4.4.5` |
+
+Runtime dependencies are `@stylistic/eslint-plugin`, `eslint-plugin-import-x`, `eslint-plugin-boundaries` and `typescript-eslint`.
+
+`eslint-import-resolver-typescript` is a peer dependency used by `relations` to resolve TS aliases. npm installs peers automatically; with Yarn 1 or pnpm, install it explicitly.
+
+## Project structure
+
+Each project definition has this shape:
+
+```ts
+interface IProjectDefinition {
+  rootFolder: string
+  preset?: 'frontend' | 'backend' | 'other'
+  structure?: IProjectStructure
+  relations?: IRelationsConfig
+}
+```
+
+- `rootFolder` is the project root, usually the folder containing `package.json`.
+- `rootFolder` is relative to the current working directory.
+- Absolute paths inside the current working directory are also accepted.
+- Nested roots are supported; the most specific root wins.
+- Duplicate roots are rejected.
+- `preset` provides a base structure.
+- `structure` is merged on top of the preset.
+- `relations` enables architecture dependency policies with `eslint-plugin-boundaries`.
+- `preset: 'other'` disables structure validation unless a custom `structure` is provided.
+
+`aiRules.configs.projects([...])` generates one flat config per project. Each config:
+
+- scopes `files` to the project root;
+- sets `settings['ai-rules'].project`;
+- enables `ai-rules/project-structure`;
+- adds `ignores` from `ignoredPaths`;
+- includes the recommended rules;
+- disables `ai-rules/filename-pascal-case`, because file naming is handled by `project-structure`;
+- when `relations` is present, registers `boundaries` and enables `boundaries/dependencies`.
+
+## Examples
+
+### Frontend only
+
+```ts
+import { defineConfig } from 'eslint/config'
 import aiRules from 'eslint-plugin-ai-rules'
 import tseslint from 'typescript-eslint'
 
-export default [
+export default defineConfig([
   ...tseslint.configs.recommended,
-  { files: ['**/*.{ts,tsx}'], ...aiRules.configs.recommended[0] },
-]
+  ...aiRules.configs.projects([
+    { rootFolder: '.', preset: 'frontend' },
+  ]),
+])
 ```
 
-Alternative with `defineConfig` (ESLint >= 9.22):
+### Frontend and backend in the same repository
 
 ```ts
 import { defineConfig } from 'eslint/config'
@@ -65,125 +216,762 @@ import tseslint from 'typescript-eslint'
 
 export default defineConfig([
   ...tseslint.configs.recommended,
-  { files: ['**/*.{ts,tsx}'], extends: aiRules.configs.recommended },
+  ...aiRules.configs.projects([
+    { rootFolder: 'packages/web', preset: 'frontend' },
+    { rootFolder: 'packages/api', preset: 'backend' },
+  ]),
 ])
 ```
 
-### `eslint.config.js` / `eslint.config.mjs`
+### Backend with preset (copy-paste)
 
-```js
+```ts
+import { defineConfig } from 'eslint/config'
 import aiRules from 'eslint-plugin-ai-rules'
 import tseslint from 'typescript-eslint'
 
-export default [
+export default defineConfig([
   ...tseslint.configs.recommended,
-  { files: ['**/*.{js,ts,tsx}'], ...aiRules.configs.recommended[0] },
-]
+  ...aiRules.configs.projects([
+    {
+      rootFolder: '.',
+      preset: 'backend',
+    },
+  ]),
+])
 ```
 
-### With overrides
+The backend preset includes strict architecture relations. With this config:
 
 ```ts
-import aiRules from 'eslint-plugin-ai-rules'
-import { defineConfig } from 'eslint/config'
+// src/http/controllers/ListProducts.ts
+import { listProducts } from '@/use-case/product/List' // allowed
+import { productRepository } from '@/repositories/ProductRepository' // blocked
+```
+
+To override a preset relation, declare only the layer/rule you want to change:
 
+```ts
+relations: {
+  rules: [
+    { from: 'service', allow: ['generated', 'env'], allowSameLayer: false },
+  ],
+}
+```
+
+### Opting out with `other`
+
+```ts
 export default defineConfig([
-  { files: ['**/*.{ts,tsx}'], ...aiRules.configs.recommended[0] },
-  {
-    // turn off filename check for tests or generated code
-    files: ['**/*.test.{ts,tsx}', '**/*.spec.{ts,tsx}', 'scripts/**/*'],
-    rules: {
-      'ai-rules/filename-pascal-case': 'off',
+  ...tseslint.configs.recommended,
+  ...aiRules.configs.projects([
+    { rootFolder: '.', preset: 'other' },
+  ]),
+])
+```
+
+### Custom structure
+
+```ts
+export default defineConfig([
+  ...tseslint.configs.recommended,
+  ...aiRules.configs.projects([
+    {
+      rootFolder: 'apps/api',
+      preset: 'backend',
+      structure: {
+        folders: {
+          src: {
+            folders: {
+              'use-case': {
+                folders: {
+                  '[feature]': {
+                    files: [
+                      {
+                        case: 'PascalCase',
+                        suffix: 'UseCase',
+                        extensions: ['.ts'],
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  ]),
+])
+```
+
+### Use case with a suffix
+
+```ts
+structure: {
+  folders: {
+    src: {
+      folders: {
+        'use-case': {
+          folders: {
+            '[feature]': {
+              files: [
+                {
+                  case: 'PascalCase',
+                  suffix: 'UseCase',
+                  extensions: ['.ts'],
+                },
+              ],
+            },
+          },
+        },
+      },
     },
   },
-  {
-    // or disable a bundled rule
-    rules: {
-      '@stylistic/semi': 'off',
+}
+```
+
+### Controller with a suffix
+
+```ts
+structure: {
+  folders: {
+    src: {
+      folders: {
+        http: {
+          folders: {
+            controllers: {
+              folders: {
+                '[feature]': {
+                  files: [
+                    {
+                      case: 'PascalCase',
+                      suffix: 'Controller',
+                      extensions: ['.ts'],
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        },
+      },
     },
   },
-])
+}
 ```
 
-Run:
+### Dynamic folder with prefix, suffix and regex
 
-```bash
-npx eslint .
-npx eslint --fix .   # autofix for sort-imports / no-multiline-imports
+```ts
+structure: {
+  folders: {
+    '[module]': {
+      name: {
+        prefix: 'feature-',
+        suffix: '-module',
+        pattern: '^feature-[a-z-]+-module$',
+      },
+      files: ['index.ts'],
+    },
+  },
+}
 ```
 
-## Configuration
+Valid: `feature-users-module/index.ts`.
 
-### `recommended` preset
+Invalid: `users-module/index.ts`, `feature-users/index.ts`, `feature-Users-module/index.ts`.
 
-`src/configs/recommended.ts` exports `defineConfig([...])` with **only** `plugins` + `settings` + `rules` (file-agnostic) — you define `files`/`ignores`/`languageOptions`:
+### Adding files to a preset
 
-- `plugins: { '@stylistic': stylistic, 'import-x': importX, 'ai-rules': plugin }`
-- `settings: { 'import-x/resolver-next': ... }` with `extensions: ['.ts','.tsx','.d.ts','.js','.jsx']`
-- Rules (all `error` unless noted):
+```ts
+structure: {
+  folders: {
+    src: {
+      additionalFiles: [
+        { case: 'PascalCase', suffix: 'Service', extensions: ['.ts'] },
+      ],
+    },
+  },
+}
+```
 
-| Rule | Default | Notes |
-|------|---------|-------|
-| `ai-rules/filename-pascal-case` | `error` | File-agnostic: checks every file ESLint lints. See below |
-| `ai-rules/sort-imports` | `error` | Groups + length desc, collapses multiline |
-| `ai-rules/no-multiline-imports` | `error` | Single-line imports |
-| `import-x/no-duplicates` | `error` |  |
-| `import-x/no-default-export` | `off` |  |
-| `max-len` | `off` |  |
-| `@stylistic/semi` | `['error','never']` | No semicolons |
-| `@typescript-eslint/consistent-type-imports` | `['error',{prefer:'type-imports'}]` |  |
-| `@typescript-eslint/no-unused-vars` | `['error',{argsIgnorePattern:'^_',varsIgnorePattern:'^_'}]` |  |
-| `@typescript-eslint/naming-convention` | `['error', {interface:'PascalCase' prefix I}, {typeAlias:'PascalCase' prefix T}]` | Disable per-project for `**/*.d.ts` via your own override if needed |
+### Replacing preset files
 
-`recommended` has no `files`/`ignores` — add them in your `eslint.config.*` (see Quick Start). This repo's `eslint.config.mjs` adds `globalIgnores`, `files: ['**/*.{ts,tsx}']` with `extends: [js.configs.recommended, tseslint.configs.recommended]` + `globals.browser` locally.
+```ts
+structure: {
+  folders: {
+    src: {
+      files: ['index.ts'],
+    },
+  },
+}
+```
+
+### Ignoring a preset subtree
+
+```ts
+structure: {
+  folders: {
+    e2e: { ignore: true },
+  },
+}
+```
+
+### Ignoring paths globally
+
+```ts
+structure: {
+  ignoredPaths: ['dist/**', 'coverage/**', 'src/services/generated/**'],
+}
+```
 
-### Custom setup (without `recommended`)
+### Manual settings without the factory
+
+Advanced users can configure the rule directly:
 
 ```ts
 import { plugin } from 'eslint-plugin-ai-rules'
-import { defineConfig } from 'eslint/config'
 
-export default defineConfig([
+export default [
   {
-    files: ['**/*.{ts,tsx}'],
+    files: ['src/**/*.ts'],
     plugins: { 'ai-rules': plugin },
+    settings: {
+      'ai-rules': {
+        project: {
+          rootFolder: '.',
+          preset: 'other',
+          structure: {
+            folders: {
+              src: {
+                files: [{ case: 'PascalCase', extensions: ['.ts'] }],
+              },
+            },
+          },
+        },
+      },
+    },
     rules: {
-      'ai-rules/sort-imports': 'error',
-      'ai-rules/no-multiline-imports': 'warn',
-      'ai-rules/filename-pascal-case': 'off',
+      'ai-rules/project-structure': 'error',
     },
   },
+]
+```
+
+Multiple projects can be passed directly through `settings['ai-rules'].projects`. The rule chooses the most specific root for each file.
+
+## Architecture relations
+
+`relations` enforces which layers can import which other layers. It complements `structure`: `structure` validates paths and names, `relations` validates import direction.
+
+```ts
+interface IRelationsRule {
+  from: string
+  allow?: string[]
+  deny?: string[]
+  allowSameLayer?: boolean
+  allowTypeImports?: boolean
+  message?: string
+}
+
+interface IRelationsScope {
+  capture: string
+  layers: string[]
+}
+
+interface IRelationsConfig {
+  layers: Record<string, string | string[]>
+  rules: IRelationsRule[]
+  allowTypeImports?: boolean
+  scope?: IRelationsScope
+}
+```
+
+Example for a backend:
+
+```ts
+export default defineConfig([
+  ...tseslint.configs.recommended,
+  ...aiRules.configs.projects([
+    {
+      rootFolder: 'apps/backend',
+      preset: 'other',
+      relations: {
+        layers: {
+          controller: 'src/http/controllers',
+          useCase: 'src/use-case',
+          repository: 'src/repositories',
+          service: 'src/services',
+          helper: 'src/helpers',
+        },
+        rules: [
+          { from: 'controller', allow: ['useCase', 'helper'] },
+          { from: 'useCase', allow: ['repository', 'service', 'helper'] },
+          { from: 'repository', allow: ['helper'] },
+          { from: 'service', allow: ['repository', 'helper'] },
+          { from: 'helper', allow: [] },
+        ],
+      },
+    },
+  ]),
 ])
 ```
 
-You can also import rules individually:
+Semantics:
+
+- Layers are folder paths relative to `rootFolder`.
+- `allow` means the layer can import only the listed layers.
+- `deny` means the layer cannot import the listed layers.
+- `allow` and `deny` are mutually exclusive per rule.
+- `allowSameLayer` defaults to `true`. Set it to `false` to block imports within the same layer.
+- External packages and Node core modules are allowed automatically.
+- Local files that do not match any layer are ignored by default.
+- Only one rule per `from` layer is allowed.
+- `scope` allows comparing a captured value, such as the current page, to restrict local imports to the same page.
+
+Presets already include relation rules. You only need to declare `relations` when you want to add or override layers and rules:
 
 ```ts
-import { filenamePascalCase, sortImports, noMultilineImports } from 'eslint-plugin-ai-rules'
+aiRules.configs.projects([
+  {
+    rootFolder: 'apps/backend',
+    preset: 'backend',
+    relations: {
+      rules: [
+        { from: 'service', allow: ['generated', 'env'], allowSameLayer: false },
+      ],
+    },
+  },
+])
 ```
 
-## Rules
+The preset backend is strict: controllers only use use-cases plus infrastructure, use-cases cannot access database/helpers directly, repositories cannot import repositories, and services cannot import services. Structural exceptions exist for `generated` and `database/schema`. Service subfolders are generic modules with their own scope.
 
-Brief overview. See source in `src/rules/` for full logic.
+The preset frontend uses global layers plus page-local scope. Global layers cannot import page-local files. Page-local files can import global layers and files from the same page only.
 
-### `ai-rules/filename-pascal-case`
+### Backend preset relations
+
+| Layer | Can import | Same layer |
+|-------|------------|------------|
+| controller | useCase, http, generated, helper, env | no |
+| http | useCase, helper, generated | no |
+| useCase | repository, service, serviceModule, generated | yes |
+| repository | database, databaseSchema | no |
+| service | generated, env | no |
+| generated | — | yes |
+| serviceModule | generated, env | yes, within the same module |
+| database | databaseSchema, env | no |
+| databaseSchema | — | yes |
+| helper | — | no |
+| env | — | no |
+| types | — | no |
+
+`generated` and `databaseSchema` are structural exceptions because they contain internal files that import each other. Any `src/services/<service-kebab>/` folder is a generic service module: files inside the same module can import each other, different modules cannot.
+
+The strict backend preset will report existing violations such as:
+
+- use-cases importing `database` or `helpers`;
+- services importing other services;
+- repositories importing other repositories, including `Setup`.
+
+These violations are intentional and should be fixed during migration.
+
+### Frontend preset relations
+
+| Layer | Can import | Same layer |
+|-------|------------|------------|
+| components | components, hooks, contexts, services, generated, utils, helpers, constants, env | yes |
+| hooks | hooks, contexts, services, generated, utils, helpers, constants, env | yes |
+| contexts | services, generated, utils, helpers, constants, env | no |
+| services | generated, utils, helpers, constants, env | no |
+| generated | — | yes |
+| utils | helpers, constants, env | no |
+| helpers | utils, constants, env | no |
+| constants | — | no |
+| env | — | no |
+| page | globals + same-page locals | yes (same page) |
+| pageComponent | globals + same-page locals (including page main) | yes |
+| pageHook | hooks/contexts/services/generated/utils/helpers/constants/env + same-page local hooks/services/contexts/helpers | yes |
+| pageService | services, generated, utils, helpers, constants, env + same-page pageHelper | no |
+| pageContext | contexts, services, generated, utils, helpers, constants, env + same-page pageService/pageHelper | no |
+| pageHelper | helpers, utils, constants, env | no |
+
+Local layers can import global layers. Global layers cannot import page-local layers. `pageHook` cannot import `pageComponent`.
+
+`utils` and `helpers` can import each other. If this creates undesirable cycles, remove one direction.
+
+### Same-layer and page scope
+
+```ts
+relations: {
+  layers: {
+    pageComponent: 'src/pages/*/components',
+    pageHook: 'src/pages/*/hooks',
+    page: 'src/pages/*',
+  },
+  scope: {
+    capture: 'page',
+    layers: ['pageComponent', 'pageHook', 'page'],
+  },
+  rules: [
+    {
+      from: 'pageComponent',
+      allow: ['pageHook'],
+      allowSameLayer: true,
+    },
+  ],
+}
+```
+
+A file from `src/pages/orders` can import another file from `src/pages/orders`, but not from `src/pages/users`.
+
+### Type-only imports
+
+Type-only imports follow the same restrictions by default:
+
+```ts
+import type { TUser } from '@/repositories/UserRepository' // blocked
+```
+
+Allow them globally:
+
+```ts
+relations: {
+  allowTypeImports: true,
+  layers: { /* ... */ },
+  rules: [/* ... */],
+}
+```
+
+Or for a specific layer:
+
+```ts
+{
+  from: 'controller',
+  allow: ['useCase'],
+  allowTypeImports: true,
+}
+```
+
+### Deny rules and messages
+
+```ts
+relations: {
+  layers: {
+    controller: 'src/http/controllers',
+    repository: 'src/repositories',
+  },
+  rules: [
+    {
+      from: 'controller',
+      deny: ['repository'],
+      message: 'Controllers must use use-cases instead of repositories.',
+    },
+  ],
+}
+```
+
+### Aliases and TypeScript
 
-Enforces `PascalCase` for file names. The rule is file-agnostic: it validates every file ESLint decides to lint, following the flat-config `files`/`ignores` defined in the consumer's config (same pattern as other filename rules).
+When the project root has a `tsconfig.json`, the generated config uses `eslint-import-resolver-typescript`, so aliases such as `@/repositories/UserRepository` are resolved automatically.
 
-- **Type:** `suggestion`, no autofix, `messageId: invalid`
-- **Ignores:** `index.{ts,tsx,js,jsx}`, `*.d.ts`, `*.css`, dotfiles
-- **Checks:** `path.basename` from `getPhysicalFilename()` / `context.filename`, `^[A-Z][a-zA-Z0-9]*$`, `kebab/snake -> PascalCase` conversion
-- **Options:**
-  - `ignore` — array of regex strings matched against the basename and the path relative to `cwd` (same idea as `unicorn/filename-case`). Use it for tool-mandated names like `*.config.*`, tests/specs, generated or vendored code.
-  - `ignoreMiddleExtensions` — `boolean`, default `true`. When `true`, only the base name before the first dot is validated, so `ValidationRanges.test.ts` is valid and `my-component.test.ts` is renamed to `MyComponent.test.ts`. When `false`, every dot-separated segment must be PascalCase, so `ValidationRanges.test.ts` is renamed to `ValidationRanges.Test.ts` (same idea as `unicorn/filename-case`).
+Make sure the resolver is installed at the project level:
+
+```bash
+npm i -D eslint-import-resolver-typescript
+```
+
+For JS projects without `tsconfig.json`, the Node resolver is used.
+
+`relations` uses `eslint-plugin-boundaries` under the hood and enables `boundaries/dependencies`.
+
+## Expected diagnostics
+
+Configuration warning:
+
+```text
+[eslint-plugin-ai-rules] Project structure validation is not configured.
+Configure it with aiRules.configs.projects([{ rootFolder: '.', preset: 'frontend' | 'backend' }]).
+If this project is not a frontend/backend, use preset: 'other' to disable this warning.
+```
+
+Structure violation:
+
+```text
+src/pages/MyFeature/Dashboard.tsx
+  error  Folder "MyFeature" inside "src/pages" must match kebab-case.  ai-rules/project-structure
+```
+
+Relation violation:
+
+```text
+src/http/controllers/ListProducts.ts
+  error  Dependencies to elements of type "repository" are not allowed in elements of type "controller".  boundaries/dependencies
+```
+
+Custom relation message:
+
+```ts
+{
+  from: 'controller',
+  deny: ['repository'],
+  message: 'Controllers must use use-cases instead of repositories.',
+}
+```
+
+## Preset reference
+
+### Frontend
+
+```text
+<root>/
+├── root files: package.json, lockfiles, *.config.{js,mjs,cjs,ts},
+│   tsconfig*.json, .env*, Dockerfile, entrypoint.sh, nginx.conf,
+│   index.html, AGENTS.md, README.md, LICENSE
+├── src/
+│   ├── App.tsx, AppRoutes.tsx, main.tsx, index.css, vite-env.d.ts
+│   ├── components/*.tsx
+│   ├── components/ui/*.{ts,tsx}
+│   ├── constants/*.ts
+│   ├── contexts/*.tsx
+│   ├── env/index.ts
+│   ├── helpers/*.ts
+│   ├── hooks/*.ts
+│   ├── pages/*.tsx
+│   ├── pages/<feature-kebab>/
+│   │   ├── *.tsx, helpers.ts, schema.ts, types.ts
+│   │   ├── components/*.tsx
+│   │   ├── hooks/*.ts
+│   │   ├── services/*.ts
+│   │   ├── contexts/*.tsx
+│   │   ├── helpers/*.ts
+│   │   └── tabs/<tab-kebab>/
+│   │       ├── *.tsx
+│   │       └── <section-kebab>/
+│   │           ├── *.tsx, *.ts
+│   │           ├── components/*.tsx
+│   │           └── contents/
+│   │               ├── *.tsx
+│   │               └── components/*.tsx
+│   ├── services/generated/** (ignored)
+│   ├── services/utils/*.ts
+│   └── utils/*.ts
+├── e2e/
+│   ├── .auth/** (ignored)
+│   ├── fixtures/*
+│   ├── pages/*.ts
+│   ├── specs/*.spec.ts
+│   └── support/*.ts
+│       └── api/*.ts
+├── scripts/*.ts
+├── scripts/types/** (ignored)
+├── public/** (ignored)
+└── .github/**, .vscode/** (ignored)
+```
+
+### Backend
+
+```text
+<root>/
+├── root files: package.json, lockfiles, *.config.{js,mjs,cjs,ts},
+│   tsconfig*.json, .env*, Dockerfile, .dockerignore,
+│   AGENTS.md, README.md, LICENSE
+├── src/
+│   ├── index.ts, Server.ts, Schemas.ts
+│   ├── env/index.ts
+│   ├── helpers/*.ts
+│   ├── @types/*.d.ts
+│   ├── database/
+│   │   ├── Connection.ts
+│   │   ├── schema/index.ts, *.ts
+│   │   ├── seeds/index.ts
+│   │   └── migrations/** (ignored)
+│   ├── repositories/Setup.ts, *.ts
+│   ├── http/
+│   │   ├── Routes.ts
+│   │   ├── controllers/Health.ts
+│   │   ├── controllers/<feature-kebab>/
+│   │   │   ├── *.ts
+│   │   │   └── <resource-kebab>/*.ts
+│   │   ├── hooks/*.ts
+│   │   └── types/*.d.ts
+│   ├── services/*.ts
+│   ├── services/<service-kebab>/index.ts, *.ts
+│   ├── services/generated/** (ignored)
+│   └── use-case/
+│       ├── Errors.ts
+│       └── <feature-kebab>/
+│           ├── *.ts
+│           └── <resource-kebab>/*.ts
+├── test/*.test.ts, GlobalSetup.ts, Setup.ts, ProvidedContext.d.ts
+├── test/Helpers/*.ts
+├── docs/** (ignored)
+├── scripts/*.ts
+├── uploads/** (ignored)
+└── .github/**, .vscode/** (ignored)
+```
+
+### Other
+
+`preset: 'other'` has an empty structure. It disables validation and suppresses the configuration warning. If you provide a `structure`, it validates exactly what you declared.
+
+## Structure DSL
 
 ```ts
-// my-component.ts         ❌  Rename to "MyComponent.ts"
-// ValidationRanges.test.ts  ✅ (ignoreMiddleExtensions: true, default)
-// ValidationRanges.test.ts  ❌  Rename to "ValidationRanges.Test.ts" (ignoreMiddleExtensions: false)
-// MyComponent.ts          ✅
+type TProjectPreset = 'frontend' | 'backend' | 'other'
+
+type TNameCase = 'PascalCase' | 'camelCase' | 'kebab-case' | 'snake_case'
+
+interface INameRule {
+  case?: TNameCase
+  prefix?: string
+  suffix?: string
+  pattern?: string
+}
+
+type TFileRule =
+  | string
+  | ({ extensions: string[] } & INameRule)
+
+interface IStructureNode {
+  name?: INameRule
+  files?: TFileRule[]
+  additionalFiles?: TFileRule[]
+  folders?: Record<string, IStructureNode>
+  ignore?: boolean
+}
+
+interface IProjectStructure extends IStructureNode {
+  ignoredPaths?: string[]
+}
 ```
 
+### Folder keys
+
+Literal keys match exactly:
+
+```ts
+folders: {
+  components: { files: ['*.tsx'] },
+}
+```
+
+Dynamic keys use brackets:
+
+```ts
+folders: {
+  '[feature]': {
+    name: { case: 'kebab-case' },
+    files: ['*.tsx'],
+  },
+}
+```
+
+- Only one dynamic folder is allowed per level.
+- `name` applies to dynamic folders.
+- A static folder key cannot have a `name` rule.
+- A dynamic folder without `name` accepts any folder name.
+
+### File rules
+
+Strings match exact names or globs:
+
+```ts
+files: [
+  'index.ts',
+  '*.spec.ts',
+  '*.config.{js,mjs,cjs,ts}',
+]
+```
+
+Supported glob syntax: `*`, `**`, `?` and `{a,b}`.
+
+Object rules require `extensions` and validate the base name:
+
+```ts
+files: [
+  {
+    extensions: ['.ts', '.tsx'],
+    case: 'PascalCase',
+  },
+  {
+    extensions: ['.ts'],
+    case: 'PascalCase',
+    suffix: 'UseCase',
+  },
+  {
+    extensions: ['.ts'],
+    case: 'PascalCase',
+    prefix: 'Use',
+  },
+  {
+    extensions: ['.ts'],
+    pattern: '^(Create|Read|Update|Delete|List)[A-Z][A-Za-z0-9]*$',
+  },
+]
+```
+
+- `extensions` also supports compound extensions: `.d.ts`, `.test.mjs`, `.spec.ts`.
+- `case`, `prefix`, `suffix` and `pattern` apply to the base name after removing the extension.
+- A file is valid when it matches at least one rule completely.
+
+### Merge behavior
+
+| Field | Behavior |
+|-------|----------|
+| `folders` | recursive merge by key; new keys are added |
+| `files` | replaces the preset files at that node |
+| `additionalFiles` | appends to the preset files |
+| `name` | fields override the preset |
+| `ignore` | overrides the preset |
+| `ignoredPaths` | union of preset and custom paths |
+
+## Limitations
+
+- Structure validation only runs for files ESLint actually lints.
+- Required empty folders are not detected.
+- Glob matching supports `*`, `**`, `?` and `{a,b}` only.
+- Nested roots are supported, but duplicate roots are rejected.
+- Relation layers must point to folders, not individual files.
+- Scoped layers must use patterns with a wildcard, such as `src/pages/*`.
+- TypeScript aliases in `relations` require the project `tsconfig.json`.
+- Type-only imports follow the same restrictions by default.
+- The backend preset is strict and will flag existing imports that violate AGENTS.md.
+- The frontend preset allows `utils` and `helpers` to import each other, which can create cycles.
+- ESLint versions below 9.22 are not supported.
+
+## Rules
+
+### `ai-rules/project-structure`
+
+Validates the configured hierarchy, folder names and file names.
+
+- Type: `problem`
+- No autofix
+- Reads `settings['ai-rules'].project` or `settings['ai-rules'].projects`
+- Messages: `folderNotAllowed`, `folderNameMismatch`, `fileNotAllowed`, `fileNameMismatch`
+- Ignores files outside the project root, `ignoredPaths` and `ignore: true` subtrees
+
+### `ai-rules/project-setup`
+
+Prints the configuration warning described above.
+
+- Type: `suggestion`
+- Enabled as `warn` in `recommended`
+- Does not report lint messages
+- Warns once per process
+- Suppressed by `preset: 'other'`, `frontend`, `backend` or a non-empty custom structure
+
+### `ai-rules/filename-pascal-case`
+
+Enforces PascalCase for file names.
+
+- Ignores `index.{ts,tsx,js,jsx}`, `*.d.ts`, `*.css` and dotfiles.
+- Options:
+  - `ignore`: regex strings matched against the basename and relative path.
+  - `ignoreMiddleExtensions`: defaults to `true`, so `ValidationRanges.test.ts` is valid.
+
 ```ts
 'ai-rules/filename-pascal-case': [
   'error',
@@ -194,86 +982,224 @@ Enforces `PascalCase` for file names. The rule is file-agnostic: it validates ev
 ]
 ```
 
-To scope or disable it, use your own config (as this repo does in `eslint.config.mjs`):
+`projects()` disables this rule because `project-structure` enforces file names.
+
+### `ai-rules/no-multiline-imports`
+
+Disallows multiline import declarations. Fixable.
 
 ```ts
-import { defineConfig } from 'eslint/config'
-import { recommended } from './src/configs/recommended'
+// before
+import {
+  b,
+  a,
+} from 'lodash'
+
+// after --fix
+import { b, a } from 'lodash'
+```
+
+### `ai-rules/sort-imports`
+
+Sorts imports by group and line length descending, collapsing multiline imports. Fixable.
+
+Groups:
+
+1. Directives (`'use client'`, `'use server'`, `'use strict'`)
+2. External packages (`react` first, then by line length desc)
+3. Internal imports (`.`, `@/`)
+4. Re-exports
+
+## Bundled rules from other plugins
+
+`recommended` also registers and applies these rules. They existed before project structure support and remain part of the default setup.
 
+| Rule | Default | Purpose |
+|------|---------|---------|
+| `import-x/no-duplicates` | `error` | Prevent importing the same module twice |
+| `import-x/no-default-export` | `off` | Default exports are allowed |
+| `max-len` | `off` | No line length limit |
+| `@stylistic/semi` | `['error', 'never']` | No semicolons |
+| `@typescript-eslint/consistent-type-imports` | `['error', { prefer: 'type-imports' }]` | Prefer `import type` |
+| `@typescript-eslint/no-unused-vars` | `['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }]` | Ignore unused values prefixed with `_` |
+| `@typescript-eslint/naming-convention` | interfaces `I` prefix, type aliases `T` prefix | Enforce `IUser` and `TUser` style |
+
+When `relations` is configured, `projects()` also registers `eslint-plugin-boundaries` and enables `boundaries/dependencies` with the generated layer policies.
+
+The plugin also configures the `import-x` resolver with:
+
+```ts
+extensions: ['.ts', '.tsx', '.d.ts', '.js', '.jsx']
+```
+
+Override any bundled rule after the preset:
+
+```ts
 export default defineConfig([
-  ...recommended,
-  { files: ['src/**/*'], rules: { 'ai-rules/filename-pascal-case': 'off' } },
+  ...aiRules.configs.projects([{ rootFolder: '.', preset: 'frontend' }]),
+  {
+    rules: {
+      '@stylistic/semi': ['error', 'always'],
+      'import-x/no-default-export': 'off',
+    },
+  },
 ])
 ```
 
-### `ai-rules/no-multiline-imports`
+## What runs automatically
+
+| You use | What is enabled |
+|---------|-----------------|
+| `aiRules.configs.recommended` | bundled rules + configuration warning |
+| `aiRules.configs.projects([...])` | recommended rules + `project-structure` |
+| `projects([...])` with `preset: 'frontend' \| 'backend'` | preset structure + preset relations |
+| `projects([...])` with `structure` | structure validation |
+| `projects([...])` with `relations` | `boundaries/dependencies` |
+| `projects([...])` with both | structure + relations |
+
+`projects()` does **not** configure the TypeScript parser. Pair it with `typescript-eslint` as shown in the examples.
+
+## Recommended preset
+
+`aiRules.configs.recommended` is file-agnostic. It provides:
+
+- plugins: `@stylistic`, `import-x`, `@typescript-eslint`, `ai-rules`
+- `settings['import-x/resolver-next']`
+- the rule set documented above
+
+It does **not** configure:
+
+- `files`
+- `ignores`
+- parser
+- language options
+- globals
+
+Pair it with `typescript-eslint` or `@typescript-eslint/parser` and define `files` in your config. `aiRules.configs.projects([...])` already does the file scoping for you.
+
+If you want the recommended rules without project structure validation, use `projects([{ rootFolder: '.', preset: 'other' }])`.
 
-Disallows multiline `ImportDeclaration`.
+## Troubleshooting
+
+### The configuration warning keeps appearing
 
-- **Type:** `layout`, `fixable: code`, `messageId: multilineImport`
-- **Fix:** collapses `{`, `}`, `,` and whitespace to single line: `import { b, a } from 'lodash'`
+Use a valid project configuration:
 
 ```ts
-// ❌
-import {
-  b,
-  a
-} from 'lodash'
+...aiRules.configs.projects([
+  { rootFolder: '.', preset: 'frontend' },
+])
+```
 
-// ✅ after --fix
-import { b, a } from 'lodash'
+Or explicitly opt out:
+
+```ts
+...aiRules.configs.projects([
+  { rootFolder: '.', preset: 'other' },
+])
 ```
 
-Note: `ai-rules/sort-imports` also collapses multiline; both fixers may run, but `sort-imports` handles the full `Program` sort.
+A project with only `rootFolder` and an empty `structure` still warns.
 
-### `ai-rules/sort-imports`
+For temporary runs or CI, use:
+
+```bash
+AI_RULES_SILENT=1 npx eslint .
+```
+
+### `project-structure` is not running
+
+Make sure you are using `aiRules.configs.projects([...])` or manually setting `settings['ai-rules'].project` and enabling `ai-rules/project-structure`.
 
-Sorts imports by group and line-length descending, collapsing multiline imports.
+### Type-aware rule error
 
-- **Type:** `layout`, `fixable: code` (`Program` fixer), `messageId: sortRequired`
-- **Groups (in order, each separated by one blank line):**
-  1. Directives (`'use client'`, `'use server'`, `'use strict'`)
-  2. External (`react` first, then other externals sorted by `line.length` desc → `localeCompare`)
-  3. Internal (`.`, `@/` sorted same)
-  4. Re-exports (`export { ... } from`, `export * from` sorted same)
-- **Rest:** code after imports, joined with `\n\n\n` (two blank lines between imports and code)
-- **Directives:** preserved at top while `canAcceptDirectives` is true
+`@typescript-eslint/consistent-type-imports` needs the TypeScript parser. Pair the plugin with:
 
 ```ts
-// ❌ before --fix
-import { local } from './local'
-import { a } from 'lodash'
-import React from 'react'
+...tseslint.configs.recommended
+```
+
+### Missing `dist` before lint
 
-// ✅ after --fix
-import React from 'react'
-import { a } from 'lodash'
+This repository imports the local build from `dist`. Consumers should import the published package:
 
-import { local } from './local'
+```ts
+import aiRules from 'eslint-plugin-ai-rules'
 ```
 
-Supports side-effect `import 'polyfill'`, `import type`, `export * from`, `export { ... } from`.
+### File ignored because outside of base path
 
-## TypeScript
+Run ESLint from the project root, or configure the correct `basePath`.
 
-Plugin itself uses `module: ESNext` + `moduleResolution: bundler` (`tsconfig.json`) and **no `.js` extensions** in source imports (e.g., `from './plugin'`). Output is bundled to single `dist/index.js` via `tsup`, so consumers don't need to handle internal paths. For your project, any TS config works; the preset sets `languageOptions.globals: globals.browser` and `import-x/resolver-next`.
+### Flat config only
 
-## Troubleshooting
+This plugin exports flat config arrays. It does not support legacy `.eslintrc`.
 
-**Missing `dist` before lint (repo uses `eslint.config.mjs` → `dist`)**
+### Filename rule too strict
+
+Use the `ignore` option or disable `ai-rules/filename-pascal-case` for tool-mandated files:
+
+```ts
+{
+  files: ['*.config.*', 'scripts/**/*'],
+  rules: {
+    'ai-rules/filename-pascal-case': 'off',
+  },
+}
 ```
-Error: Cannot find module './dist/index.js'
+
+## Common mistakes
+
+### Using `recommended` without `projects()`
+
+You get the configuration warning and no project structure validation. Use `projects([...])` or explicitly opt out with `preset: 'other'`.
+
+### Forgetting the TypeScript parser
+
+`aiRules.configs.recommended` does not configure `languageOptions.parser`. Pair it with `tseslint.configs.recommended` or a parser.
+
+### Aliases are not enforced in relations
+
+Make sure the project has `tsconfig.json` with `paths`, and install `eslint-import-resolver-typescript`.
+
+### A relation layer does not match
+
+Layers must point to folders, not files:
+
+```ts
+layers: {
+  controller: 'src/http/controllers', // correct
+  // controller: 'src/http/controllers/*.ts', // avoid
+}
 ```
-Fix: `npm run build` first. This repo's `eslint.config.mjs` imports from `dist` (no `jiti`), so `prelint` runs `build` automatically (`package.json` `prelint`).
 
-**File ignored because outside of base path**
-You passed an absolute path outside the config's `basePath`. Run `npx eslint .` from project root or use `npx eslint --no-config-lookup -c ./eslint.config.js ./src/file.ts` with correct cwd.
+### Type-only imports are blocked
+
+That is the default. Set `allowTypeImports: true` globally or per rule.
+
+### An external package or unknown file is not blocked
+
+`relations` only checks known local layers. External packages, Node core modules, same-layer imports and files outside any layer are allowed.
+
+### Duplicate or overlapping roots
+
+Nested roots are supported, but duplicate roots are rejected. Use the most specific configuration for each project.
+
+## Migrating from 0.2.x
+
+1. Replace `aiRules.configs.recommended` with `aiRules.configs.projects([...])`.
+2. Choose a preset: `frontend`, `backend`, or `other`.
+3. Set `rootFolder` to the folder containing `package.json`.
+4. Add `relations` if you want layer boundaries.
+5. Keep pairing with `typescript-eslint`.
 
-**Flat config only**
-This plugin exports flat config arrays. It does not support legacy `.eslintrc`. Use `eslint.config.{js,ts}`.
+If you intentionally do not want structure validation:
 
-**Filename rule too strict for tests/configs**
-The rule checks every linted file. Test/spec files with a PascalCase base (e.g. `ValidationRanges.test.ts`) pass by default via `ignoreMiddleExtensions: true`. For tool-mandated names like `*.config.*`, generated or vendored code, pass the `ignore` option (`{ ignore: ['\\.config\\.', '^generated/'] }`) or disable `ai-rules/filename-pascal-case` for those files via an override (see Quick Start).
+```ts
+...aiRules.configs.projects([
+  { rootFolder: '.', preset: 'other' },
+])
+```
 
 ## Development
 
@@ -282,60 +1208,104 @@ git clone <repo>
 cd eslint-ai-guard
 npm install
 
-npm run typecheck  # tsc --noEmit
-npm test           # node:test + dist build
-npm run lint       # eslint .
+npm run typecheck      # tsc --noEmit
+npm test               # node:test against dist
+npm run lint           # eslint .
 npm run lint -- --fix
-npm run build      # tsup -> dist/index.js + dist/index.cjs + dist/index.d.ts
-npm run dev        # tsup --watch
-npm run verify     # typecheck + test + lint + pack
-npm pack --dry-run # verify files: dist only
+npm run build          # tsup -> ESM + CJS + declarations
+npm run dev            # tsup --watch
+npm run verify         # typecheck + test + lint + pack
+npm run test:coverage  # c8 coverage with thresholds
+npm run test:consumer  # install packed tarball in a temp project
+npm run test:package   # publint + arethetypeswrong
+npm run test:release   # consumer + package checks
+npm pack --dry-run     # verify published files
 ```
 
-### Project structure
+`test:consumer` and `test:package` are release checks and are not part of `verify`. They may use the network.
+
+The consumer smoke test covers structure validation, relations with aliases and type-only imports, warning/suppression, ESM and CJS. It accepts `ESLINT_VERSION`:
 
+```bash
+ESLINT_VERSION=9.22.0 npm run test:consumer
+ESLINT_VERSION='^10.0.0' npm run test:consumer
 ```
-eslint-ai-guard/  # package: eslint-plugin-ai-rules
+
+CI runs `verify`, coverage and consumer checks on Node 20, 22 and 24.
+
+### Project structure
+
+```text
+eslint-ai-guard/
 ├── src/
-│   ├── index.ts              # re-exports plugin + recommended
-│   ├── plugin.ts             # plugin.meta + rules
+│   ├── index.ts
+│   ├── plugin.ts
 │   ├── configs/
-│   │   ├── recommended.ts    # flat-config preset (bundled rules)
+│   │   ├── recommended.ts
+│   │   ├── projects.ts
 │   │   └── index.ts
+│   ├── types/
+│   │   └── structure.ts
+│   ├── structures/
+│   │   ├── buildRelationsConfig.ts
+│   │   ├── hasStructureRules.ts
+│   │   ├── mergeRelations.ts
+│   │   ├── mergeStructure.ts
+│   │   ├── validateRelations.ts
+│   │   ├── validateStructure.ts
+│   │   └── presets/
+│   │       ├── frontend.ts
+│   │       ├── backend.ts
+│   │       ├── other.ts
+│   │       ├── helpers.ts
+│   │       └── index.ts
+│   ├── utils/
 │   └── rules/
 │       ├── FilenamePascalCase.ts
 │       ├── NoMultilineImports.ts
-│       ├── SortImports.ts    # also exports getSortedContent
+│       ├── ProjectSetup.ts
+│       ├── ProjectStructure.ts
+│       ├── SortImports.ts
 │       └── index.ts
-├── test/                     # node:test suites (run against dist)
-├── eslint/                   # deprecated original implementations
-├── eslint.config.mjs         # dogfooding: ...aiRules.configs.recommended from dist
-├── tsconfig.json             # ESNext/bundler, no .js extensions
-├── tsup.config.ts            # entry src/index.ts, format cjs+esm, dts, splitting:false
-├── package.json              # type module, exports ., files [dist]
-└── dist/                     # build output (gitignored)
+├── test/
+├── scripts/
+│   └── TestConsumer.mjs
+├── .github/
+│   └── workflows/
+│       └── ci.yml
+├── eslint/
+├── CHANGELOG.md
+├── eslint.config.mjs
+├── tsconfig.json
+├── tsup.config.ts
+├── package.json
+└── dist/
 ```
 
 ### Adding a new rule
 
-1. Create `src/rules/MyRule.ts` (`Rule.RuleModule`, `meta.messages`, `fixable` if needed)
-2. Export it from `src/rules/index.ts`
-3. Register in `src/plugin.ts` (`rules: { 'my-rule': myRule }`)
-4. Enable in `src/configs/recommended.ts` (`'ai-rules/my-rule': 'error'`)
-5. Add a `RuleTester` case in `test/` (add a fixture if needed)
-6. `npm run verify`
+1. Create `src/rules/MyRule.ts`.
+2. Export it from `src/rules/index.ts`.
+3. Register it in `src/plugin.ts`.
+4. Add it to `src/configs/recommended.ts` if it should be enabled by default.
+5. Add tests in `test/`.
+6. Run `npm run verify`.
 
-### Publishing
+## Publishing
 
 ```bash
+npm run verify
+npm run test:coverage
+npm run test:release
 npm version patch|minor|major
-npm publish --access public  # prepublishOnly runs verify (typecheck+test+lint+pack)
-# or manually: npm run verify && npm publish --access public
+npm publish --access public
 ```
 
+`prepublishOnly` runs `verify` and refuses to publish with any uncommitted, staged or untracked changes.
+
 ## Legacy
 
-`eslint/` keeps the three original rule files before packaging (deprecated). Source of truth is now `src/rules/`.
+`eslint/` keeps the three original rule implementations before packaging. Source of truth is `src/rules/`.
 
 ## License