@hatem427/code-guard-ci 2.2.8 → 3.0.0

package/dist/scripts/config-generators/eslint-generator.js

@@ -149,25 +149,245 @@ ${configs.join(',\n\n')},
 }
 function buildNxCustomRules(project) {
     const rules = [];
-    // ── Code Quality ──────────────────────────────────────────────────────
-    rules.push(`      // ── Code Quality ──────────────────────────────────────────────`, `      'no-console': ['warn', { allow: ['warn', 'error', 'info'] }],`, `      'no-debugger': 'error',`, `      'no-alert': 'error',`, `      'no-eval': 'error',`, `      'no-implied-eval': 'error',`, `      'no-new-func': 'error',`, `      'prefer-const': 'error',`, `      'no-var': 'error',`, `      'eqeqeq': ['error', 'always'],`, `      'curly': ['error', 'all'],`, `      'no-throw-literal': 'error',`, `      'prefer-template': 'warn',`, `      'no-useless-concat': 'warn',`);
-    // ── Import ordering ──────────────────────────────────────────────────
-    rules.push(``, `      // ── Import Ordering ──────────────────────────────────────────`, `      'import/order': ['error', {`, `        groups: [`, `          'builtin',`, `          'external',`, `          'internal',`, `          ['parent', 'sibling'],`, `          'index',`, `          'type',`, `        ],`, `        pathGroups: [`, `          { pattern: '@/**', group: 'internal', position: 'before' },`, `        ],`, `        pathGroupsExcludedImportTypes: ['type'],`, `        'newlines-between': 'always',`, `        alphabetize: { order: 'asc', caseInsensitive: true },`, `      }],`, `      'import/no-duplicates': 'error',`, `      'import/no-unresolved': 'off',`);
-    // ── TypeScript overrides (Nx flat/typescript already sets defaults) ────
+    // ═══════════════════════════════════════════════════════════════════════
+    // CODE QUALITY RULES
+    // These rules catch common bugs, security holes, and bad practices
+    // that slip through code review. They run on every save/commit.
+    // ═══════════════════════════════════════════════════════════════════════
+    rules.push(`      // ── Code Quality ──────────────────────────────────────────────`, 
+    // ─────────────────────────────────────────
+    // RULE: no-console
+    // WHY: console.log left in production code clutters browser devtools,
+    //      can leak sensitive data, and slows down rendering in loops.
+    //      We allow warn/error/info for legitimate logging.
+    // HOW: Flags console.log() and console.debug() but allows
+    //      console.warn(), console.error(), console.info().
+    // ─────────────────────────────────────────
+    `      'no-console': ['warn', { allow: ['warn', 'error', 'info'] }],`, 
+    // ─────────────────────────────────────────
+    // RULE: no-debugger
+    // WHY: debugger statements pause execution in the browser. If shipped
+    //      to production, they freeze the app for end users.
+    // HOW: Errors on any `debugger;` statement in the codebase.
+    // ─────────────────────────────────────────
+    `      'no-debugger': 'error',`, 
+    // ─────────────────────────────────────────
+    // RULE: no-alert
+    // WHY: alert(), confirm(), prompt() block the main thread and create
+    //      an ugly UX. Use toast notifications or modal components instead.
+    // HOW: Errors on any call to alert(), confirm(), or prompt().
+    // ─────────────────────────────────────────
+    `      'no-alert': 'error',`, 
+    // ─────────────────────────────────────────
+    // RULE: no-eval
+    // WHY: eval() executes arbitrary strings as code — the #1 XSS vector.
+    //      Attackers can inject malicious code through user input.
+    // HOW: Errors on any eval() call in the codebase.
+    // ─────────────────────────────────────────
+    `      'no-eval': 'error',`, 
+    // ─────────────────────────────────────────
+    // RULE: no-implied-eval
+    // WHY: setTimeout("code", delay) and setInterval("code", delay) are
+    //      hidden eval() calls with the same security risks.
+    // HOW: Errors on setTimeout/setInterval/execScript with string args.
+    // ─────────────────────────────────────────
+    `      'no-implied-eval': 'error',`, 
+    // ─────────────────────────────────────────
+    // RULE: no-new-func
+    // WHY: new Function("a", "b", "return a + b") is another form of
+    //      eval() that creates functions from strings — same XSS risk.
+    // HOW: Errors on any `new Function(...)` expression.
+    // ─────────────────────────────────────────
+    `      'no-new-func': 'error',`, 
+    // ─────────────────────────────────────────
+    // RULE: prefer-const
+    // WHY: Variables that are never reassigned should use `const` to
+    //      signal intent. Prevents accidental reassignment bugs.
+    // HOW: Errors when `let` is used but the variable is never reassigned.
+    //   WRONG: let name = 'John';  (never reassigned)
+    //   RIGHT: const name = 'John';
+    // ─────────────────────────────────────────
+    `      'prefer-const': 'error',`, 
+    // ─────────────────────────────────────────
+    // RULE: no-var
+    // WHY: `var` has function scope (not block scope), is hoisted, and
+    //      causes subtle bugs. `let` and `const` are block-scoped and safer.
+    // HOW: Errors on any `var` declaration.
+    //   WRONG: var count = 0;
+    //   RIGHT: let count = 0;  OR  const count = 0;
+    // ─────────────────────────────────────────
+    `      'no-var': 'error',`, 
+    // ─────────────────────────────────────────
+    // RULE: eqeqeq
+    // WHY: `==` performs type coercion (e.g., 0 == '' is true, null == undefined
+    //      is true). `===` compares value AND type — no surprises.
+    // HOW: Errors on `==` and `!=`, requires `===` and `!==`.
+    //   WRONG: if (count == '0')   → true (coercion!)
+    //   RIGHT: if (count === 0)    → type-safe comparison
+    // ─────────────────────────────────────────
+    `      'eqeqeq': ['error', 'always'],`, 
+    // ─────────────────────────────────────────
+    // RULE: curly
+    // WHY: Omitting braces in if/else/for/while causes bugs when adding
+    //      new lines — the new line runs OUTSIDE the block unconditionally.
+    // HOW: Requires { } braces for ALL control flow statements.
+    //   WRONG: if (done) return;
+    //   RIGHT: if (done) { return; }
+    // ─────────────────────────────────────────
+    `      'curly': ['error', 'all'],`, 
+    // ─────────────────────────────────────────
+    // RULE: no-throw-literal
+    // WHY: throw 'error' loses the stack trace. throw new Error('message')
+    //      captures the full call stack for debugging.
+    // HOW: Errors when throwing strings, numbers, or other non-Error objects.
+    //   WRONG: throw 'Something went wrong';
+    //   RIGHT: throw new Error('Something went wrong');
+    // ─────────────────────────────────────────
+    `      'no-throw-literal': 'error',`, 
+    // ─────────────────────────────────────────
+    // RULE: prefer-template
+    // WHY: Template literals (`Hello ${name}`) are more readable than
+    //      string concatenation ('Hello ' + name) and support multiline.
+    // HOW: Warns on string concatenation that could use template literals.
+    //   WRONG: 'Hello ' + name + ', welcome!'
+    //   RIGHT: `Hello ${name}, welcome!`
+    // ─────────────────────────────────────────
+    `      'prefer-template': 'warn',`, 
+    // ─────────────────────────────────────────
+    // RULE: no-useless-concat
+    // WHY: 'a' + 'b' can just be 'ab'. Useless concatenation adds noise
+    //      and suggests the developer forgot to add a variable.
+    // HOW: Warns on concatenation of two string literals.
+    //   WRONG: const path = '/api/' + 'users';
+    //   RIGHT: const path = '/api/users';
+    // ─────────────────────────────────────────
+    `      'no-useless-concat': 'warn',`);
+    // ═══════════════════════════════════════════════════════════════════════
+    // IMPORT ORDERING RULES
+    // Consistent import order makes files scannable at a glance.
+    // Groups: Node builtins → npm packages → workspace → parent → sibling → types
+    // ═══════════════════════════════════════════════════════════════════════
+    rules.push(``, `      // ── Import Ordering ──────────────────────────────────────────`, 
+    // ─────────────────────────────────────────
+    // RULE: import/order
+    // WHY: Without enforced ordering, imports become a random mess that's
+    //      hard to scan. Grouping by source type (builtin → external →
+    //      internal → relative → type) makes dependencies clear.
+    // HOW: Auto-sorts imports into groups with blank lines between them.
+    //      Alphabetizes within each group. @/ paths are treated as internal.
+    //   WRONG:
+    //     import { UserService } from '../services/user';
+    //     import { Component } from '@angular/core';
+    //     import * as fs from 'fs';
+    //   RIGHT:
+    //     import * as fs from 'fs';                        // builtin
+    //
+    //     import { Component } from '@angular/core';       // external
+    //
+    //     import { UserService } from '../services/user';  // parent
+    // ─────────────────────────────────────────
+    `      'import/order': ['error', {`, `        groups: [`, `          'builtin',`, `          'external',`, `          'internal',`, `          ['parent', 'sibling'],`, `          'index',`, `          'type',`, `        ],`, `        pathGroups: [`, `          { pattern: '@/**', group: 'internal', position: 'before' },`, `        ],`, `        pathGroupsExcludedImportTypes: ['type'],`, `        'newlines-between': 'always',`, `        alphabetize: { order: 'asc', caseInsensitive: true },`, `      }],`, 
+    // ─────────────────────────────────────────
+    // RULE: import/no-duplicates
+    // WHY: Importing from the same module twice wastes space and causes
+    //      confusion. Merge them into a single import statement.
+    // HOW: Errors when two import statements reference the same module.
+    //   WRONG:
+    //     import { signal } from '@angular/core';
+    //     import { computed } from '@angular/core';
+    //   RIGHT:
+    //     import { signal, computed } from '@angular/core';
+    // ─────────────────────────────────────────
+    `      'import/no-duplicates': 'error',`, 
+    // ─────────────────────────────────────────
+    // RULE: import/no-unresolved — OFF
+    // WHY: TypeScript already validates imports at compile time. Enabling
+    //      this ESLint rule causes false positives with path aliases
+    //      (@/...) and monorepo workspace references.
+    // ─────────────────────────────────────────
+    `      'import/no-unresolved': 'off',`);
+    // ═══════════════════════════════════════════════════════════════════════
+    // TYPESCRIPT RULES
+    // These supplement TypeScript's built-in type checking with style and
+    // safety rules that tsc doesn't enforce (e.g., no `any`, unused vars).
+    // ═══════════════════════════════════════════════════════════════════════
     if (project.usesTypeScript) {
-        rules.push(``, `      // ── TypeScript ─────────────────────────────────────────────`, `      '@typescript-eslint/no-explicit-any': 'error',`, `      '@typescript-eslint/no-unused-vars': ['error', {`, `        argsIgnorePattern: '^_',`, `        varsIgnorePattern: '^_',`, `      }],`, `      '@typescript-eslint/explicit-function-return-type': 'off',`, `      '@typescript-eslint/no-non-null-assertion': 'warn',`, `      '@typescript-eslint/consistent-type-imports': ['error', {`, `        prefer: 'type-imports',`, `      }],`);
+        rules.push(``, `      // ── TypeScript ─────────────────────────────────────────────`, 
+        // ─────────────────────────────────────────
+        // RULE: @typescript-eslint/no-explicit-any
+        // WHY: `any` disables ALL type checking — it defeats the purpose of
+        //      TypeScript. It hides bugs, breaks autocomplete, and makes
+        //      refactoring impossible. Use `unknown` if the type is truly unknown.
+        // HOW: Errors on any explicit `any` type annotation.
+        //   WRONG: function parse(data: any) { ... }
+        //   RIGHT: function parse(data: unknown) { ... }
+        //   RIGHT: function parse(data: Record<string, string>) { ... }
+        // ─────────────────────────────────────────
+        `      '@typescript-eslint/no-explicit-any': 'warn',`, 
+        // ─────────────────────────────────────────
+        // RULE: @typescript-eslint/no-unused-vars
+        // WHY: Unused variables are dead code — they clutter the file and
+        //      confuse readers. Variables prefixed with _ are intentionally
+        //      ignored (e.g., _event in callbacks, _unused in destructuring).
+        // HOW: Errors on unused variables/args. Ignores names starting with _.
+        //   WRONG: const result = getData();  (result never used)
+        //   RIGHT: const _result = getData();  (intentionally unused)
+        //   RIGHT: getData();  (no binding at all)
+        // ─────────────────────────────────────────
+        `      '@typescript-eslint/no-unused-vars': ['error', {`, `        argsIgnorePattern: '^_',`, `        varsIgnorePattern: '^_',`, `      }],`, 
+        // ─────────────────────────────────────────
+        // RULE: @typescript-eslint/explicit-function-return-type — OFF
+        // WHY: TypeScript infers return types automatically in most cases.
+        //      Forcing explicit return types adds noise without benefit.
+        //      We rely on TypeScript's inference and strict mode instead.
+        // ─────────────────────────────────────────
+        `      '@typescript-eslint/explicit-function-return-type': 'off',`, 
+        // ─────────────────────────────────────────
+        // RULE: @typescript-eslint/no-non-null-assertion
+        // WHY: The `!` operator (e.g., user!.name) tells TypeScript "trust me,
+        //      this is not null" — but it's lying. If it IS null, you get a
+        //      runtime crash. Use optional chaining (?.) or proper null checks.
+        // HOW: Warns on any `!` non-null assertion.
+        //   WRONG: const name = user!.name;
+        //   RIGHT: const name = user?.name ?? 'Unknown';
+        // ─────────────────────────────────────────
+        `      '@typescript-eslint/no-non-null-assertion': 'warn',`, 
+        // ─────────────────────────────────────────
+        // RULE: @typescript-eslint/consistent-type-imports
+        // WHY: `import type { User }` is erased at compile time — it adds
+        //      ZERO bytes to the bundle. Regular `import { User }` may keep
+        //      the module in the bundle even if only the type is used.
+        // HOW: Errors when a type-only import uses the regular import syntax.
+        //   WRONG: import { User } from './models';  (User is only a type)
+        //   RIGHT: import type { User } from './models';
+        // ─────────────────────────────────────────
+        `      '@typescript-eslint/consistent-type-imports': ['error', {`, `        prefer: 'type-imports',`, `      }],`);
     }
     return rules.join('\n');
 }
 function buildNxFrameworkConfig(project) {
     switch (project.type) {
         case 'angular':
+            // ═══════════════════════════════════════════════════════════════════
+            // ANGULAR-SPECIFIC NX RULES
+            // These rules enforce Angular coding conventions on top of Nx's
+            // built-in Angular ESLint configs (which include template linting).
+            // ═══════════════════════════════════════════════════════════════════
             return `  // Angular-specific Nx configs
   ...nx.configs['flat/angular'],
   ...nx.configs['flat/angular-template'],
   {
     files: ['**/*.ts'],
     rules: {
+      // ─────────────────────────────────────────
+      // RULE: @angular-eslint/directive-selector
+      // WHY: Directives MUST use a consistent prefix (e.g., 'app') to avoid
+      //      naming collisions with third-party libraries and native HTML.
+      //      camelCase is the Angular convention for attribute selectors.
+      // HOW: Errors if a directive selector doesn't start with 'app'.
+      //   WRONG: @Directive({ selector: '[highlight]' })
+      //   RIGHT: @Directive({ selector: '[appHighlight]' })
+      // ─────────────────────────────────────────
       '@angular-eslint/directive-selector': [
         'error',
         {
@@ -176,6 +396,15 @@ function buildNxFrameworkConfig(project) {
           style: 'camelCase',
         },
       ],
+      // ─────────────────────────────────────────
+      // RULE: @angular-eslint/component-selector
+      // WHY: Components MUST use a consistent prefix (e.g., 'app-') to avoid
+      //      collisions with HTML elements and third-party components.
+      //      kebab-case is required for custom element names (Web Components spec).
+      // HOW: Errors if a component selector doesn't start with 'app-'.
+      //   WRONG: @Component({ selector: 'user-card' })
+      //   RIGHT: @Component({ selector: 'app-user-card' })
+      // ─────────────────────────────────────────
       '@angular-eslint/component-selector': [
         'error',
         {
@@ -184,6 +413,12 @@ function buildNxFrameworkConfig(project) {
           style: 'kebab-case',
         },
       ],
+      // ─────────────────────────────────────────
+      // RULE: @angular-eslint/prefer-standalone — OFF
+      // WHY: We turned this off because our Angular constitution already
+      //      enforces standalone components through Code Guardian's custom
+      //      rules (angular-standalone-components). No need to double-enforce.
+      // ─────────────────────────────────────────
       '@angular-eslint/prefer-standalone': 'off',
     },
   },
@@ -192,34 +427,144 @@ function buildNxFrameworkConfig(project) {
     rules: {},
   }`;
         case 'react':
+            // ═══════════════════════════════════════════════════════════════════
+            // REACT-SPECIFIC NX RULES
+            // These rules enforce React best practices, accessibility, and hook
+            // rules on top of Nx's built-in React ESLint configs.
+            // ═══════════════════════════════════════════════════════════════════
             return `  // React-specific Nx configs
   ...nx.configs['flat/react'],
   {
     files: ['**/*.tsx', '**/*.jsx'],
     rules: {
+      // ─────────────────────────────────────────
+      // RULE: react/react-in-jsx-scope — OFF
+      // WHY: React 17+ has automatic JSX runtime — you no longer need
+      //      \`import React from 'react'\` at the top of every JSX file.
+      //      This rule was important for React 16 but is now obsolete.
+      // ─────────────────────────────────────────
       'react/react-in-jsx-scope': 'off',
+
+      // ─────────────────────────────────────────
+      // RULE: react/prop-types — OFF
+      // WHY: We use TypeScript interfaces for prop validation, which is
+      //      stricter than React PropTypes. PropTypes only validate at
+      //      runtime; TypeScript catches errors at compile time.
+      // ─────────────────────────────────────────
       'react/prop-types': 'off',
+
+      // ─────────────────────────────────────────
+      // RULE: react/no-danger
+      // WHY: dangerouslySetInnerHTML injects raw HTML — if the content
+      //      comes from user input, it's an XSS vulnerability. Every
+      //      usage must be reviewed and sanitized (e.g., DOMPurify).
+      // HOW: Errors on any use of dangerouslySetInnerHTML.
+      //   WRONG: <div dangerouslySetInnerHTML={{ __html: userContent }} />
+      //   RIGHT: <div>{sanitize(userContent)}</div>
+      // ─────────────────────────────────────────
       'react/no-danger': 'error',
+
+      // ─────────────────────────────────────────
+      // RULE: react/no-array-index-key
+      // WHY: Using array index as key causes React to reuse wrong DOM nodes
+      //      when items are reordered, deleted, or inserted — leading to
+      //      stale state, wrong animations, and visual glitches.
+      // HOW: Warns when .map((item, index) => <X key={index} />) is used.
+      //   WRONG: items.map((item, i) => <Card key={i} ... />)
+      //   RIGHT: items.map(item => <Card key={item.id} ... />)
+      // ─────────────────────────────────────────
       'react/no-array-index-key': 'warn',
+
+      // ─────────────────────────────────────────
+      // RULE: react/self-closing-comp
+      // WHY: Components without children should self-close for cleaner JSX.
+      //      It reduces visual noise and makes the template scannable.
+      // HOW: Errors on non-self-closing tags that have no children.
+      //   WRONG: <UserAvatar></UserAvatar>
+      //   RIGHT: <UserAvatar />
+      // ─────────────────────────────────────────
       'react/self-closing-comp': 'error',
+
+      // ─────────────────────────────────────────
+      // RULE: react/jsx-no-target-blank
+      // WHY: <a target="_blank"> without rel="noopener noreferrer" allows
+      //      the opened page to access window.opener — a security risk
+      //      (reverse tabnabbing attack).
+      // HOW: Errors on target="_blank" without rel="noopener noreferrer".
+      //   WRONG: <a href="..." target="_blank">Link</a>
+      //   RIGHT: <a href="..." target="_blank" rel="noopener noreferrer">Link</a>
+      // ─────────────────────────────────────────
       'react/jsx-no-target-blank': 'error',
+
+      // ─────────────────────────────────────────
+      // RULE: react-hooks/rules-of-hooks
+      // WHY: Hooks MUST be called at the top level (not inside conditions,
+      //      loops, or nested functions). React uses call order to match
+      //      hooks to state — conditional calls break this mapping.
+      // HOW: Errors if hooks are called inside if/for/while or nested funcs.
+      //   WRONG: if (isLoggedIn) { const [user] = useState(null); }
+      //   RIGHT: const [user] = useState(null); // Always at top level
+      // ─────────────────────────────────────────
       'react-hooks/rules-of-hooks': 'error',
+
+      // ─────────────────────────────────────────
+      // RULE: react-hooks/exhaustive-deps
+      // WHY: Missing dependencies in useEffect/useMemo/useCallback cause
+      //      stale closures — the hook reads outdated values. This is the
+      //      #1 source of "why doesn't my effect re-run?" bugs.
+      // HOW: Warns when a dependency is used inside the hook but missing
+      //      from the dependency array.
+      //   WRONG: useEffect(() => fetchUser(userId), []);  // missing userId
+      //   RIGHT: useEffect(() => fetchUser(userId), [userId]);
+      // ─────────────────────────────────────────
       'react-hooks/exhaustive-deps': 'warn',
+
+      // ─────────────────────────────────────────
+      // RULE: jsx-a11y/alt-text
+      // WHY: Images without alt text are invisible to screen readers.
+      //      Alt text describes the image for blind users and shows as
+      //      fallback when images fail to load.
+      // HOW: Errors on <img> without alt prop.
+      //   WRONG: <img src="/logo.png" />
+      //   RIGHT: <img src="/logo.png" alt="Company logo" />
+      // ─────────────────────────────────────────
       'jsx-a11y/alt-text': 'error',
+
+      // ─────────────────────────────────────────
+      // RULE: jsx-a11y/anchor-is-valid
+      // WHY: <a> tags without href (or with href="#") are not focusable by
+      //      keyboard and don't announce as links to screen readers.
+      //      Use <button> for actions, <Link> for navigation.
+      // HOW: Errors on <a> without valid href.
+      //   WRONG: <a onClick={handleClick}>Click me</a>
+      //   RIGHT: <button onClick={handleClick}>Click me</button>
+      // ─────────────────────────────────────────
       'jsx-a11y/anchor-is-valid': 'error',
     },
   }`;
         case 'nextjs':
+            // ═══════════════════════════════════════════════════════════════════
+            // NEXT.JS-SPECIFIC NX RULES
+            // Next.js inherits React rules. We only include the subset that
+            // applies to Next.js (e.g., no-array-index-key is less critical
+            // since Server Components don't have the same reorder issues).
+            // ═══════════════════════════════════════════════════════════════════
             return `  // Next.js + React Nx configs
   ...nx.configs['flat/react'],
   {
     files: ['**/*.tsx', '**/*.jsx'],
     rules: {
+      // react/react-in-jsx-scope — OFF: React 17+ automatic JSX runtime
       'react/react-in-jsx-scope': 'off',
+      // react/prop-types — OFF: TypeScript handles prop validation
       'react/prop-types': 'off',
+      // react/no-danger — ERROR: Prevents XSS via dangerouslySetInnerHTML
       'react/no-danger': 'error',
+      // react-hooks/rules-of-hooks — ERROR: Hooks must follow call order rules
       'react-hooks/rules-of-hooks': 'error',
+      // react-hooks/exhaustive-deps — WARN: Catch missing hook dependencies
       'react-hooks/exhaustive-deps': 'warn',
+      // jsx-a11y/alt-text — ERROR: All images must have alt text for accessibility
       'jsx-a11y/alt-text': 'error',
     },
   }`;
@@ -344,17 +689,78 @@ function getFilePatterns(project) {
 function buildMainConfigBlock(project, filePatterns) {
     const plugins = [`import: importPlugin`];
     const rules = [];
-    // ── Code Quality ─────────────────────────────────────────────────────
-    rules.push(`      // ── Code Quality ──────────────────────────────────────────────`, `      'no-console': ['warn', { allow: ['warn', 'error', 'info'] }],`, `      'no-debugger': 'error',`, `      'no-alert': 'error',`, `      'no-eval': 'error',`, `      'no-implied-eval': 'error',`, `      'no-new-func': 'error',`, `      'prefer-const': 'error',`, `      'no-var': 'error',`, `      'eqeqeq': ['error', 'always'],`, `      'curly': ['error', 'all'],`, `      'no-throw-literal': 'error',`, `      'prefer-template': 'warn',`, `      'no-useless-concat': 'warn',`);
-    // ── Import ordering ──────────────────────────────────────────────────
-    rules.push(``, `      // ── Import Ordering ──────────────────────────────────────────`, `      'import/order': ['error', {`, `        groups: [`, `          'builtin',`, `          'external',`, `          'internal',`, `          ['parent', 'sibling'],`, `          'index',`, `          'type',`, `        ],`, `        pathGroups: [`, `          { pattern: '@/**', group: 'internal', position: 'before' },`, `        ],`, `        pathGroupsExcludedImportTypes: ['type'],`, `        'newlines-between': 'always',`, `        alphabetize: { order: 'asc', caseInsensitive: true },`, `      }],`, `      'import/no-duplicates': 'error',`, `      'import/no-unresolved': 'off',`);
-    // ── TypeScript rules ──────────────────────────────────────────────────
+    // ═══════════════════════════════════════════════════════════════════════
+    // CODE QUALITY RULES (standalone projects)
+    // Same rules as Nx — see buildNxCustomRules() for full documentation.
+    // ═══════════════════════════════════════════════════════════════════════
+    rules.push(`      // ── Code Quality ──────────────────────────────────────────────`, 
+    // no-console: Allow warn/error/info, block log/debug in production
+    `      'no-console': ['warn', { allow: ['warn', 'error', 'info'] }],`, 
+    // no-debugger: Never ship debugger statements to production
+    `      'no-debugger': 'error',`, 
+    // no-alert: Use proper UI components instead of browser dialogs
+    `      'no-alert': 'error',`, 
+    // no-eval: Block eval() — the #1 XSS attack vector
+    `      'no-eval': 'error',`, 
+    // no-implied-eval: Block setTimeout("string") — hidden eval()
+    `      'no-implied-eval': 'error',`, 
+    // no-new-func: Block new Function("string") — another eval() variant
+    `      'no-new-func': 'error',`, 
+    // prefer-const: Use const when variable is never reassigned
+    `      'prefer-const': 'error',`, 
+    // no-var: Block var — use let/const for block scoping
+    `      'no-var': 'error',`, 
+    // eqeqeq: Require === instead of == to prevent type coercion bugs
+    `      'eqeqeq': ['error', 'always'],`, 
+    // curly: Require braces on all control flow to prevent scope bugs
+    `      'curly': ['error', 'all'],`, 
+    // no-throw-literal: throw Error objects, not strings (preserves stack trace)
+    `      'no-throw-literal': 'error',`, 
+    // prefer-template: Use template literals over string concatenation
+    `      'prefer-template': 'warn',`, 
+    // no-useless-concat: Don't concatenate two string literals needlessly
+    `      'no-useless-concat': 'warn',`);
+    // ═══════════════════════════════════════════════════════════════════════
+    // IMPORT ORDERING (standalone projects)
+    // Same ordering as Nx — see buildNxCustomRules() for full documentation.
+    // ═══════════════════════════════════════════════════════════════════════
+    rules.push(``, `      // ── Import Ordering ──────────────────────────────────────────`, 
+    // import/order: Enforce grouped, alphabetized imports with newlines
+    `      'import/order': ['error', {`, `        groups: [`, `          'builtin',`, `          'external',`, `          'internal',`, `          ['parent', 'sibling'],`, `          'index',`, `          'type',`, `        ],`, `        pathGroups: [`, `          { pattern: '@/**', group: 'internal', position: 'before' },`, `        ],`, `        pathGroupsExcludedImportTypes: ['type'],`, `        'newlines-between': 'always',`, `        alphabetize: { order: 'asc', caseInsensitive: true },`, `      }],`, 
+    // import/no-duplicates: Merge imports from the same module
+    `      'import/no-duplicates': 'error',`, 
+    // import/no-unresolved — OFF: TypeScript handles module resolution
+    `      'import/no-unresolved': 'off',`);
+    // ═══════════════════════════════════════════════════════════════════════
+    // TYPESCRIPT RULES (standalone projects)
+    // Same rules as Nx — see buildNxCustomRules() for full documentation.
+    // ═══════════════════════════════════════════════════════════════════════
     if (project.usesTypeScript) {
-        rules.push(``, `      // ── TypeScript ─────────────────────────────────────────────`, `      '@typescript-eslint/no-explicit-any': 'error',`, `      '@typescript-eslint/no-unused-vars': ['error', {`, `        argsIgnorePattern: '^_',`, `        varsIgnorePattern: '^_',`, `      }],`, `      '@typescript-eslint/explicit-function-return-type': 'off',`, `      '@typescript-eslint/no-non-null-assertion': 'warn',`, `      '@typescript-eslint/consistent-type-imports': ['error', {`, `        prefer: 'type-imports',`, `      }],`);
+        rules.push(``, `      // ── TypeScript ─────────────────────────────────────────────`, 
+        // no-explicit-any: Ban `any` — use unknown, generics, or proper types
+        `      '@typescript-eslint/no-explicit-any': 'error',`, 
+        // no-unused-vars: Remove dead variables, _ prefix = intentionally unused
+        `      '@typescript-eslint/no-unused-vars': ['error', {`, `        argsIgnorePattern: '^_',`, `        varsIgnorePattern: '^_',`, `      }],`, 
+        // explicit-function-return-type — OFF: TypeScript infers return types
+        `      '@typescript-eslint/explicit-function-return-type': 'off',`, 
+        // no-non-null-assertion: Warn on ! — use ?. or null checks instead
+        `      '@typescript-eslint/no-non-null-assertion': 'warn',`, 
+        // consistent-type-imports: Use `import type` for type-only imports (zero bundle cost)
+        `      '@typescript-eslint/consistent-type-imports': ['error', {`, `        prefer: 'type-imports',`, `      }],`);
     }
     // ── Node.js specific ──────────────────────────────────────────────────
     if (project.type === 'node') {
-        rules.push(``, `      // ── Node.js ────────────────────────────────────────────────`, `      'no-process-exit': 'warn',`);
+        rules.push(``, `      // ── Node.js ────────────────────────────────────────────────`, 
+        // ─────────────────────────────────────────
+        // RULE: no-process-exit
+        // WHY: process.exit() kills the process immediately without running
+        //      cleanup handlers (graceful shutdown, DB disconnect, file flush).
+        //      Use proper error handling and let the process exit naturally.
+        // HOW: Warns on any process.exit() call.
+        //   WRONG: process.exit(1);
+        //   RIGHT: throw new Error('Fatal error'); // Let error handler manage exit
+        // ─────────────────────────────────────────
+        `      'no-process-exit': 'warn',`);
     }
     // ── Language options ──────────────────────────────────────────────────
     const globalsEntries = [];
@@ -395,6 +801,11 @@ ${rules.join('\n')}
 function buildFrameworkConfig(project) {
     switch (project.type) {
         case 'react':
+            // ═══════════════════════════════════════════════════════════════════
+            // REACT STANDALONE RULES
+            // Full React, Hooks, and Accessibility rules for non-Nx projects.
+            // See buildNxFrameworkConfig() for detailed per-rule documentation.
+            // ═══════════════════════════════════════════════════════════════════
             return `  // React-specific rules
   {
     files: ['**/*.{tsx,jsx}'],
@@ -407,19 +818,34 @@ function buildFrameworkConfig(project) {
       react: { version: 'detect' },
     },
     rules: {
+      // react/react-in-jsx-scope — OFF: React 17+ automatic JSX runtime
       'react/react-in-jsx-scope': 'off',
+      // react/prop-types — OFF: TypeScript handles prop type validation
       'react/prop-types': 'off',
+      // react/no-danger — ERROR: Block dangerouslySetInnerHTML (XSS risk)
       'react/no-danger': 'error',
+      // react/no-array-index-key — WARN: Array index as key causes reorder bugs
       'react/no-array-index-key': 'warn',
+      // react/self-closing-comp — ERROR: <Component /> not <Component></Component>
       'react/self-closing-comp': 'error',
+      // react/jsx-no-target-blank — ERROR: Prevent reverse tabnabbing attack
       'react/jsx-no-target-blank': 'error',
+      // react-hooks/rules-of-hooks — ERROR: Hooks must follow call order rules
       'react-hooks/rules-of-hooks': 'error',
+      // react-hooks/exhaustive-deps — WARN: Catch missing hook dependencies
       'react-hooks/exhaustive-deps': 'warn',
+      // jsx-a11y/alt-text — ERROR: All images must have alt text
       'jsx-a11y/alt-text': 'error',
+      // jsx-a11y/anchor-is-valid — ERROR: <a> must have valid href or use <button>
       'jsx-a11y/anchor-is-valid': 'error',
     },
   }`;
         case 'nextjs':
+            // ═══════════════════════════════════════════════════════════════════
+            // NEXT.JS STANDALONE RULES
+            // React rules + Next.js plugin (image optimization, link component,
+            // Google Font loading, script optimization).
+            // ═══════════════════════════════════════════════════════════════════
             return `  // Next.js + React rules
   {
     files: ['**/*.{tsx,jsx}'],
@@ -433,27 +859,63 @@ function buildFrameworkConfig(project) {
       react: { version: 'detect' },
     },
     rules: {
+      // react/react-in-jsx-scope — OFF: React 17+ automatic JSX runtime
       'react/react-in-jsx-scope': 'off',
+      // react/prop-types — OFF: TypeScript handles prop type validation
       'react/prop-types': 'off',
+      // react/no-danger — ERROR: Block dangerouslySetInnerHTML (XSS risk)
       'react/no-danger': 'error',
+      // react-hooks/rules-of-hooks — ERROR: Hooks must follow call order rules
       'react-hooks/rules-of-hooks': 'error',
+      // react-hooks/exhaustive-deps — WARN: Catch missing hook dependencies
       'react-hooks/exhaustive-deps': 'warn',
+      // jsx-a11y/alt-text — ERROR: All images must have alt text
       'jsx-a11y/alt-text': 'error',
+      // Next.js recommended: Use <Image>, <Link>, <Script> components
       ...nextPlugin.configs.recommended.rules,
+      // Core Web Vitals: Enforce performance best practices
       ...nextPlugin.configs['core-web-vitals'].rules,
     },
   }`;
         case 'angular':
+            // ═══════════════════════════════════════════════════════════════════
+            // ANGULAR STANDALONE RULES
+            // Minimal Angular-specific rules — most enforcement is done by
+            // @angular-eslint (configured separately) and Code Guardian's
+            // custom rules in angular.config.ts.
+            // ═══════════════════════════════════════════════════════════════════
             return `  // Angular-specific rules
   {
     files: ['**/*.ts'],
     rules: {
+      // ─────────────────────────────────────────
+      // RULE: @typescript-eslint/no-empty-function
+      // WHY: Empty functions are usually forgotten implementations or
+      //      dead code. If intentionally empty (e.g., noop callback),
+      //      add a comment explaining why.
+      // HOW: Warns on empty function bodies.
+      //   WRONG: ngOnInit() {}
+      //   RIGHT: ngOnInit() { /* Intentionally empty — inputs are static */ }
+      // ─────────────────────────────────────────
       '@typescript-eslint/no-empty-function': 'warn',
+
+      // ─────────────────────────────────────────
+      // RULE: @typescript-eslint/member-ordering
+      // WHY: Consistent class member ordering makes large Angular classes
+      //      scannable. Convention: static → injected → signals/inputs →
+      //      lifecycle → public methods → private methods.
+      // HOW: Warns when class members are in unexpected order.
+      // ─────────────────────────────────────────
       '@typescript-eslint/member-ordering': 'warn',
     },
   }`;
         case 'vue':
         case 'nuxt':
+            // ═══════════════════════════════════════════════════════════════════
+            // VUE / NUXT RULES
+            // Vue ESLint plugin handles template linting, component naming,
+            // and Vue-specific patterns.
+            // ═══════════════════════════════════════════════════════════════════
             return `  // Vue-specific rules
   ...vuePlugin.configs['flat/recommended'],
   {
@@ -465,13 +927,55 @@ function buildFrameworkConfig(project) {
       },` : ''}
     },
     rules: {
+      // ─────────────────────────────────────────
+      // RULE: vue/multi-word-component-names
+      // WHY: Single-word component names can conflict with current or
+      //      future HTML element names (e.g., <Header>, <Footer>).
+      //      Multi-word names (e.g., <AppHeader>) prevent collisions.
+      // HOW: Warns on single-word component names.
+      //   WRONG: export default { name: 'Header' }
+      //   RIGHT: export default { name: 'AppHeader' }
+      // ─────────────────────────────────────────
       'vue/multi-word-component-names': 'warn',
+
+      // ─────────────────────────────────────────
+      // RULE: vue/no-v-html
+      // WHY: v-html injects raw HTML — same XSS risk as React's
+      //      dangerouslySetInnerHTML. All content must be sanitized.
+      // HOW: Errors on any v-html directive usage.
+      //   WRONG: <div v-html="userContent" />
+      //   RIGHT: <div>{{ sanitizedContent }}</div>
+      // ─────────────────────────────────────────
       'vue/no-v-html': 'error',
+
+      // ─────────────────────────────────────────
+      // RULE: vue/require-default-prop
+      // WHY: Props without defaults cause undefined values when the
+      //      parent doesn't pass the prop. Defaults ensure components
+      //      always have valid data to render.
+      // HOW: Warns on props without a default value.
+      //   WRONG: props: { count: { type: Number } }
+      //   RIGHT: props: { count: { type: Number, default: 0 } }
+      // ─────────────────────────────────────────
       'vue/require-default-prop': 'warn',
+
+      // ─────────────────────────────────────────
+      // RULE: vue/component-name-in-template-casing
+      // WHY: PascalCase component names in templates distinguish custom
+      //      components from native HTML elements (e.g., <UserCard> vs
+      //      <div>). This is the Vue style guide recommended convention.
+      // HOW: Errors on non-PascalCase component usage in templates.
+      //   WRONG: <user-card />
+      //   RIGHT: <UserCard />
+      // ─────────────────────────────────────────
       'vue/component-name-in-template-casing': ['error', 'PascalCase'],
     },
   }`;
         case 'svelte':
+            // ═══════════════════════════════════════════════════════════════════
+            // SVELTE RULES
+            // Uses the official eslint-plugin-svelte with recommended defaults.
+            // ═══════════════════════════════════════════════════════════════════
             return `  // Svelte-specific rules
   ...sveltePlugin.configs['flat/recommended']`;
         default: