eslint-plugin-ai-rules 0.3.0 → 0.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 eslint-plugin-ai-rules
+Copyright (c) 2026 Lucas Souza
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -94,6 +94,7 @@ npx eslint --fix .
 - [Structure DSL](#structure-dsl)
 - [Limitations](#limitations)
 - [Rules](#rules)
+- [Disabling or changing rules](#disabling-or-changing-rules)
 - [What runs automatically](#what-runs-automatically)
 - [Recommended preset](#recommended-preset)
 - [Troubleshooting](#troubleshooting)
@@ -101,19 +102,19 @@ npx eslint --fix .
 - [Migrating from 0.2.x](#migrating-from-02x)
 - [Development](#development)
 - [Publishing](#publishing)
-- [Legacy](#legacy)
+- [Articles](#articles)
+- [Contributing](#contributing)
+- [Security](#security)
 
 ## 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:
+If you install the plugin and use `aiRules.configs.recommended` without configuring the project structure, `ai-rules/project-setup` reports 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.
+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.  ai-rules/project-setup
 ```
 
-The warning exists only to make sure the new structure rules are actually configured. It is printed once per process.
+The warning exists only to make sure the new structure rules are actually configured. It is reported once per process.
 
 It disappears when you provide a valid configuration:
 
@@ -123,7 +124,7 @@ It disappears when you provide a valid configuration:
 - a custom non-empty `structure`
 - a `relations` configuration
 
-A project containing only `rootFolder` and an empty `structure` is still considered unconfigured and will warn.
+A project containing only `rootFolder` and an empty `structure` is still considered unconfigured and will report.
 
 For CI or temporary runs, silence the warning without changing the config:
 
@@ -131,6 +132,16 @@ For CI or temporary runs, silence the warning without changing the config:
 AI_RULES_SILENT=1 npx eslint .
 ```
 
+You can also disable the rule or change its severity like any other ESLint rule:
+
+```ts
+{
+  rules: {
+    'ai-rules/project-setup': 'off',
+  },
+}
+```
+
 The warning is still recommended as a setup check, so prefer `preset: 'other'` for projects that intentionally do not use structure validation.
 
 ## Features
@@ -167,6 +178,7 @@ interface IProjectDefinition {
   preset?: 'frontend' | 'backend' | 'other'
   structure?: IProjectStructure
   relations?: IRelationsConfig
+  rules?: Linter.RulesRecord
 }
 ```
 
@@ -178,6 +190,7 @@ interface IProjectDefinition {
 - `preset` provides a base structure.
 - `structure` is merged on top of the preset.
 - `relations` enables architecture dependency policies with `eslint-plugin-boundaries`.
+- `rules` overrides rule severities and options for that project using the standard ESLint rule format.
 - `preset: 'other'` disables structure validation unless a custom `structure` is provided.
 
 `aiRules.configs.projects([...])` generates one flat config per project. Each config:
@@ -186,9 +199,10 @@ interface IProjectDefinition {
 - sets `settings['ai-rules'].project`;
 - enables `ai-rules/project-structure`;
 - adds `ignores` from `ignoredPaths`;
-- includes the recommended rules;
+- includes the recommended rules, overridable by `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`.
+- when `relations` is present, registers `boundaries` and enables `boundaries/dependencies`;
+- applies `rules` last, so a project can disable or change any rule.
 
 ## Examples
 
@@ -422,7 +436,7 @@ structure: {
 
 ```ts
 structure: {
-  ignoredPaths: ['dist/**', 'coverage/**', 'src/services/generated/**'],
+  ignoredPaths: ['dist/**', 'coverage/**', 'src/shared/services/generated/**'],
 }
 ```
 
@@ -579,6 +593,8 @@ These violations are intentional and should be fixed during migration.
 
 ### Frontend preset relations
 
+All global frontend layers live under `src/shared` (for example `src/shared/components`). Page-local layers remain under `src/pages/*`.
+
 | Layer | Can import | Same layer |
 |-------|------------|------------|
 | components | components, hooks, contexts, services, generated, utils, helpers, constants, env | yes |
@@ -731,32 +747,36 @@ Custom relation message:
 │   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
+│   ├── shared/
+│   │   ├── components/
+│   │   │   ├── *.tsx
+│   │   │   └── ui/*.{ts,tsx}
+│   │   ├── constants/*.ts
 │   │   ├── contexts/*.tsx
+│   │   ├── env/index.ts
 │   │   ├── helpers/*.ts
-│   │   └── tabs/<tab-kebab>/
-│   │       ├── *.tsx
-│   │       └── <section-kebab>/
-│   │           ├── *.tsx, *.ts
-│   │           ├── components/*.tsx
-│   │           └── contents/
-│   │               ├── *.tsx
-│   │               └── components/*.tsx
-│   ├── services/generated/** (ignored)
-│   ├── services/utils/*.ts
-│   └── utils/*.ts
+│   │   ├── hooks/*.ts
+│   │   ├── services/
+│   │   │   ├── generated/** (ignored)
+│   │   │   └── utils/*.ts
+│   │   └── utils/*.ts
+│   └── pages/
+│       ├── *.tsx
+│       └── <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
 ├── e2e/
 │   ├── .auth/** (ignored)
 │   ├── fixtures/*
@@ -955,12 +975,12 @@ Validates the configured hierarchy, folder names and file names.
 
 ### `ai-rules/project-setup`
 
-Prints the configuration warning described above.
+Reports the configuration warning described above as a regular ESLint diagnostic.
 
 - Type: `suggestion`
 - Enabled as `warn` in `recommended`
-- Does not report lint messages
-- Warns once per process
+- Reports once per process
+- Respects the configured severity (`off`, `warn`, `error`)
 - Suppressed by `preset: 'other'`, `frontend`, `backend` or a non-empty custom structure
 
 ### `ai-rules/filename-pascal-case`
@@ -1032,20 +1052,82 @@ The plugin also configures the `import-x` resolver with:
 extensions: ['.ts', '.tsx', '.d.ts', '.js', '.jsx']
 ```
 
-Override any bundled rule after the preset:
+## Disabling or changing rules
+
+Every rule is controlled through the standard ESLint `rules` object. Any entry accepts `'off'`, `'warn'`, `'error'`, or `['error', options]`.
+
+### Option 1: override after the generated config
+
+Flat config is evaluated in order, so a config placed after `projects()` or `recommended` wins:
 
 ```ts
 export default defineConfig([
-  ...aiRules.configs.projects([{ rootFolder: '.', preset: 'frontend' }]),
+  ...tseslint.configs.recommended,
+  ...aiRules.configs.projects([
+    { rootFolder: '.', preset: 'frontend' },
+  ]),
   {
     rules: {
-      '@stylistic/semi': ['error', 'always'],
+      'ai-rules/sort-imports': 'off',
+      'ai-rules/project-structure': 'warn',
+      'ai-rules/filename-pascal-case': 'error',
+      '@stylistic/semi': ['warn', 'always'],
       'import-x/no-default-export': 'off',
+      'boundaries/dependencies': 'off',
+    },
+  },
+])
+```
+
+To apply an override only to part of the repository, use `files`:
+
+```ts
+{
+  files: ['scripts/**/*', '*.config.*'],
+  rules: {
+    'ai-rules/filename-pascal-case': 'off',
+  },
+}
+```
+
+### Option 2: per-project `rules`
+
+When using `projects()`, pass `rules` in the project definition. These rules are applied after the recommended rules, the preset rules and the automatic structure/relations rules:
+
+```ts
+aiRules.configs.projects([
+  {
+    rootFolder: 'apps/api',
+    preset: 'backend',
+    rules: {
+      'ai-rules/sort-imports': 'off',
+      'ai-rules/project-structure': 'warn',
+      '@stylistic/semi': ['warn', 'always'],
+      'boundaries/dependencies': 'off',
     },
   },
 ])
 ```
 
+Precedence inside `projects()` is:
+
+1. `recommended` rules
+2. automatic `project-structure`, `filename-pascal-case` and `boundaries/dependencies` rules
+3. `preset.rules`
+4. project `rules`
+5. any flat config placed after `projects()` in the ESLint config array
+
+The `rules` option uses the same shape as ESLint, including options arrays:
+
+```ts
+rules: {
+  'ai-rules/filename-pascal-case': [
+    'error',
+    { ignore: ['\\.config\\.'], ignoreMiddleExtensions: false },
+  ],
+}
+```
+
 ## What runs automatically
 
 | You use | What is enabled |
@@ -1101,6 +1183,16 @@ Or explicitly opt out:
 
 A project with only `rootFolder` and an empty `structure` still warns.
 
+If you intentionally do not want this check, disable the rule:
+
+```ts
+{
+  rules: {
+    'ai-rules/project-setup': 'off',
+  },
+}
+```
+
 For temporary runs or CI, use:
 
 ```bash
@@ -1204,34 +1296,36 @@ If you intentionally do not want structure validation:
 ## Development
 
 ```bash
-git clone <repo>
+git clone https://github.com/lvsouza/eslint-ai-guard.git
 cd eslint-ai-guard
-npm install
-
-npm run typecheck      # tsc --noEmit
-npm test               # node:test against dist
-npm run lint           # eslint .
-npm run lint -- --fix
-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
+corepack enable
+yarn install --frozen-lockfile
+
+yarn typecheck      # tsc --noEmit
+yarn test           # node:test against dist
+yarn test:watch     # node:test in watch mode
+yarn lint           # eslint .
+yarn lint --fix
+yarn build          # tsup -> ESM + CJS + declarations
+yarn dev            # tsup --watch
+yarn verify         # typecheck + test + lint + pack
+yarn test:coverage  # c8 coverage with thresholds
+yarn test:consumer  # install packed tarball in a temp project
+yarn test:package   # publint + arethetypeswrong
+yarn test:release   # full validation before release
+npm pack --dry-run  # verify published files
 ```
 
-`test:consumer` and `test:package` are release checks and are not part of `verify`. They may use the network.
+`test:consumer` and `test:package` are release checks and are not part of `verify`. They may use the network. `test:release` runs the complete validation: `verify`, coverage, consumer and package checks.
 
 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_VERSION=9.22.0 yarn test:consumer
+ESLINT_VERSION='^10.0.0' yarn test:consumer
 ```
 
-CI runs `verify`, coverage and consumer checks on Node 20, 22 and 24.
+The full validation runs in `.github/workflows/release.yml` on version tags: `verify` on Node 20, 22 and 24, coverage and package checks on Node 24, and consumer tests on Node 20/24 with ESLint 9.22 and 10. Pull requests keep dependency review and CodeQL.
 
 ### Project structure
 
@@ -1254,13 +1348,9 @@ eslint-ai-guard/
 │   │   ├── validateRelations.ts
 │   │   ├── validateStructure.ts
 │   │   └── presets/
-│   │       ├── frontend.ts
-│   │       ├── backend.ts
-│   │       ├── other.ts
-│   │       ├── helpers.ts
-│   │       └── index.ts
 │   ├── utils/
 │   └── rules/
+│       ├── constants.ts
 │       ├── FilenamePascalCase.ts
 │       ├── NoMultilineImports.ts
 │       ├── ProjectSetup.ts
@@ -1270,11 +1360,18 @@ eslint-ai-guard/
 ├── test/
 ├── scripts/
 │   └── TestConsumer.mjs
+├── docs/
 ├── .github/
-│   └── workflows/
-│       └── ci.yml
-├── eslint/
+│   ├── workflows/
+│   │   ├── codeql.yml
+│   │   ├── dependency-review.yml
+│   │   └── release.yml
+│   ├── ISSUE_TEMPLATE/
+│   └── dependabot.yml
 ├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── SECURITY.md
+├── CODE_OF_CONDUCT.md
 ├── eslint.config.mjs
 ├── tsconfig.json
 ├── tsup.config.ts
@@ -1284,28 +1381,53 @@ eslint-ai-guard/
 
 ### Adding a new rule
 
-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`.
+1. Create `src/rules/MyRule.ts` in PascalCase.
+2. Add the rule name to `src/rules/constants.ts`.
+3. Export it from `src/rules/index.ts`.
+4. Register it in `src/plugin.ts`.
+5. Add it to `src/configs/recommended.ts` if it should be enabled by default.
+6. Provide `meta.docs.description`, `meta.docs.url`, `meta.docs.recommended`, `meta.schema` and `meta.messages`.
+7. Add `meta.defaultOptions` when the rule accepts options.
+8. Add tests in `test/`.
+9. Run `yarn verify`.
 
 ## Publishing
 
+Releases are driven by a version tag. The workflow validates that the tag matches `package.json`, runs all checks, publishes to npm with provenance and creates a GitHub release.
+
+1. Update `version` in `package.json`.
+2. Update `CHANGELOG.md`.
+3. Run `yarn test:release`.
+4. Commit and push the changes.
+5. Create and push a tag:
+
 ```bash
-npm run verify
-npm run test:coverage
-npm run test:release
-npm version patch|minor|major
-npm publish --access public
+git tag v0.4.0
+git push origin v0.4.0
 ```
 
-`prepublishOnly` runs `verify` and refuses to publish with any uncommitted, staged or untracked changes.
+The release workflow requires the `NPM_TOKEN` repository secret. Provenance also requires `id-token: write`, which is already configured in `.github/workflows/release.yml`.
+
+The workflow runs all checks before publishing. If any check fails, the publish job is skipped. Fix the problem, delete the tag and recreate it before pushing again:
+
+```bash
+git tag -d v0.4.0
+git push origin :refs/tags/v0.4.0
+```
+
+`prepack` runs `yarn build` automatically, so published packages always contain a fresh `dist`. The plugin version is injected from `package.json` during the build, so you do not need to edit `src/plugin.ts`.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing and rule-authoring guidelines. All participants are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for supported versions and private vulnerability reporting.
 
-## Legacy
+## Articles
 
-`eslint/` keeps the three original rule implementations before packaging. Source of truth is `src/rules/`.
+- [How I forced AI to follow the project standard with ESLint](docs/tabnews-eslint-plugin-ai-rules.md)
 
 ## License