eslint-plugin-ai-rules 0.3.1 → 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
 
@@ -961,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`
@@ -1038,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 |
@@ -1107,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
@@ -1210,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
 
@@ -1260,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
@@ -1276,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
@@ -1290,31 +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
 
-1. Change `version` in `package.json`.
-2. Optionally run `yarn build` to check the build and generated version.
-3. Run `npm publish`.
+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:
 
-`prepack` runs `yarn build` automatically, so `npm publish` always packs a fresh `dist`. The plugin version is injected from `package.json` during the build, so you do not need to edit `src/plugin.ts`.
+```bash
+git tag v0.4.0
+git push origin v0.4.0
+```
 
-For an extra check before publishing:
+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
-yarn verify
-npm pack --dry-run
+git tag -d v0.4.0
+git push origin :refs/tags/v0.4.0
 ```
 
-## Legacy
+`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.
+
+## 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
 

package/dist/index.cjs

@@ -49,22 +49,50 @@ var import_eslint_plugin_import_x = require("eslint-plugin-import-x");
 var import_eslint_plugin = __toESM(require("@stylistic/eslint-plugin"), 1);
 var import_typescript_eslint = __toESM(require("typescript-eslint"), 1);
 
+// src/rules/constants.ts
+var RULE_NAMES = {
+  filenamePascalCase: "filename-pascal-case",
+  noMultilineImports: "no-multiline-imports",
+  projectSetup: "project-setup",
+  projectStructure: "project-structure",
+  sortImports: "sort-imports"
+};
+var RULE_IDS = {
+  filenamePascalCase: `ai-rules/${RULE_NAMES.filenamePascalCase}`,
+  noMultilineImports: `ai-rules/${RULE_NAMES.noMultilineImports}`,
+  projectSetup: `ai-rules/${RULE_NAMES.projectSetup}`,
+  projectStructure: `ai-rules/${RULE_NAMES.projectStructure}`,
+  sortImports: `ai-rules/${RULE_NAMES.sortImports}`
+};
+
 // src/rules/FilenamePascalCase.ts
 var import_node_path = __toESM(require("path"), 1);
 var filenamePascalCase = {
   meta: {
     type: "suggestion",
-    docs: { description: "Enforce PascalCase for file names" },
+    docs: {
+      description: "Enforce PascalCase for file names",
+      recommended: true,
+      url: "https://github.com/lvsouza/eslint-ai-guard/blob/main/README.md#ai-rulesfilename-pascal-case"
+    },
     schema: [
       {
         type: "object",
         properties: {
-          ignore: { type: "array", items: { type: "string" } },
-          ignoreMiddleExtensions: { type: "boolean" }
+          ignore: {
+            type: "array",
+            items: { type: "string" },
+            description: "Regex strings matched against the file name and relative path."
+          },
+          ignoreMiddleExtensions: {
+            type: "boolean",
+            description: "Allow middle extensions such as .test in file names."
+          }
         },
         additionalProperties: false
       }
     ],
+    defaultOptions: [{ ignore: [], ignoreMiddleExtensions: true }],
     messages: {
       invalid: 'File name "{{basename}}" must be in PascalCase. Rename to "{{expected}}".'
     }
@@ -122,10 +150,12 @@ var filenamePascalCase = {
 var noMultilineImports = {
   meta: {
     type: "layout",
-    fixable: "code",
     docs: {
-      description: "Disallow multiline imports"
+      description: "Disallow multiline imports",
+      recommended: true,
+      url: "https://github.com/lvsouza/eslint-ai-guard/blob/main/README.md#ai-rulesno-multiline-imports"
     },
+    fixable: "code",
     schema: [],
     messages: {
       multilineImport: "Imports must be written on a single line."
@@ -387,7 +417,9 @@ var projectStructure = {
   meta: {
     type: "problem",
     docs: {
-      description: "Enforce the configured project folder and file structure"
+      description: "Enforce the configured project folder and file structure",
+      recommended: false,
+      url: "https://github.com/lvsouza/eslint-ai-guard/blob/main/README.md#ai-rulesproject-structure"
     },
     schema: [],
     messages: {
@@ -461,7 +493,7 @@ function hasStructureRules(structure) {
 }
 
 // src/rules/ProjectSetup.ts
-var hasWarned = false;
+var hasReported = false;
 function isConfiguredProject(project) {
   if (project.relations) return true;
   if (project.preset === "frontend" || project.preset === "backend" || project.preset === "other") {
@@ -469,36 +501,38 @@ function isConfiguredProject(project) {
   }
   return Boolean(project.structure && hasStructureRules(project.structure));
 }
-function warnOnce() {
-  if (hasWarned) return;
+function shouldReportOnce() {
+  if (hasReported) return false;
   if (process.env.AI_RULES_SILENT === "1" || process.env.AI_RULES_SILENT === "true") {
-    return;
+    return false;
   }
-  hasWarned = true;
-  console.warn(
-    [
-      "[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."
-    ].join("\n")
-  );
+  hasReported = true;
+  return true;
 }
 var projectSetup = {
   meta: {
     type: "suggestion",
     docs: {
-      description: "Warn when the project structure validation is not configured"
+      description: "Require project structure validation to be configured",
+      recommended: true,
+      url: "https://github.com/lvsouza/eslint-ai-guard/blob/main/README.md#ai-rulesproject-setup"
     },
     schema: [],
-    messages: {}
+    messages: {
+      notConfigured: '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.'
+    }
   },
   create(context) {
     return {
-      Program() {
+      Program(node) {
         const settings = context.settings["ai-rules"];
         const projects2 = settings?.projects ?? (settings?.project ? [settings.project] : []);
         if (projects2.some(isConfiguredProject)) return;
-        warnOnce();
+        if (!shouldReportOnce()) return;
+        context.report({
+          node,
+          messageId: "notConfigured"
+        });
       }
     };
   }
@@ -509,12 +543,14 @@ var sortImports = {
   meta: {
     type: "layout",
     docs: {
-      description: "Sort imports by group and line length descending, collapsing multiline imports"
+      description: "Enforce sorted imports by group and line length descending, collapsing multiline imports",
+      recommended: true,
+      url: "https://github.com/lvsouza/eslint-ai-guard/blob/main/README.md#ai-rulessort-imports"
     },
     fixable: "code",
     schema: [],
     messages: {
-      sortRequired: "As importa\xE7\xF5es devem estar ordenadas por grupo e tamanho da linha, ocupando uma \xFAnica linha."
+      sortRequired: "Imports must be sorted by group and line length, each on a single line."
     }
   },
   create(context) {
@@ -632,14 +668,14 @@ function getSortedContent(content) {
 var plugin = {
   meta: {
     name: "eslint-plugin-ai-rules",
-    version: "0.3.1"
+    version: "0.4.0"
   },
   rules: {
-    "filename-pascal-case": filenamePascalCase,
-    "no-multiline-imports": noMultilineImports,
-    "project-setup": projectSetup,
-    "project-structure": projectStructure,
-    "sort-imports": sortImports
+    [RULE_NAMES.filenamePascalCase]: filenamePascalCase,
+    [RULE_NAMES.noMultilineImports]: noMultilineImports,
+    [RULE_NAMES.projectSetup]: projectSetup,
+    [RULE_NAMES.projectStructure]: projectStructure,
+    [RULE_NAMES.sortImports]: sortImports
   }
 };
 
@@ -660,10 +696,10 @@ var recommended = [
       ]
     },
     rules: {
-      "ai-rules/sort-imports": "error",
-      "ai-rules/no-multiline-imports": "error",
-      "ai-rules/filename-pascal-case": "error",
-      "ai-rules/project-setup": "warn",
+      [RULE_IDS.sortImports]: "error",
+      [RULE_IDS.noMultilineImports]: "error",
+      [RULE_IDS.filenamePascalCase]: "error",
+      [RULE_IDS.projectSetup]: "warn",
       "max-len": "off",
       "import-x/no-duplicates": "error",
       "import-x/no-default-export": "off",
@@ -1880,6 +1916,11 @@ function validateDefinition(definition, index) {
       });
     }
   }
+  if (definition.rules !== void 0 && (typeof definition.rules !== "object" || definition.rules === null || Array.isArray(definition.rules))) {
+    throw new Error(
+      `Invalid project at index ${index}: rules must be an object.`
+    );
+  }
 }
 function resolveStructure(definition, preset) {
   return mergeStructure(preset?.structure, definition.structure);
@@ -1934,15 +1975,16 @@ function projects(definitions) {
     ]));
     const rules = {
       ...baseConfig.rules,
-      ...preset?.rules ?? {},
-      "ai-rules/project-structure": structureEnabled ? "error" : "off",
-      "ai-rules/filename-pascal-case": structureEnabled ? "off" : baseConfig.rules?.["ai-rules/filename-pascal-case"] ?? "error",
+      [RULE_IDS.projectStructure]: structureEnabled ? "error" : "off",
+      [RULE_IDS.filenamePascalCase]: structureEnabled ? "off" : baseConfig.rules?.[RULE_IDS.filenamePascalCase] ?? "error",
       ...relations ? {
         "boundaries/dependencies": [
           "error",
           buildRelationsRuleOptions(relations)
         ]
-      } : {}
+      } : {},
+      ...preset?.rules ?? {},
+      ...definition.rules ?? {}
     };
     return {
       ...baseConfig,