@hatem427/code-guard-ci 2.2.9 → 3.0.0

package/config/angular.config.ts

@@ -18,6 +18,24 @@ import { registerRules, Rule } from './guidelines.config';
 const angularRules: Rule[] = [
   // ── NEW: Control Flow Syntax (Angular 17+) ────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: angular-use-new-control-flow
+  // ROLE: Enforce Angular 17+ @if/@for/@switch syntax
+  // PURPOSE: Prevents legacy *ngIf, *ngFor, *ngSwitch usage — the new
+  //          control flow is built-in, tree-shakeable, and has better
+  //          type narrowing than structural directives.
+  // EXAMPLE:
+  //   WRONG:
+  //     <div *ngIf="isVisible">
+  //       <li *ngFor="let item of items">{{ item }}</li>
+  //     </div>
+  //   RIGHT:
+  //     @if (isVisible) {
+  //       @for (item of items; track item.id) {
+  //         <li>{{ item }}</li>
+  //       }
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'angular-use-new-control-flow',
     label: 'Use @if, @for, @switch instead of *ngIf, *ngFor',
@@ -35,7 +53,7 @@ const angularRules: Rule[] = [
           violations.push({
             line: i + 1,
             message:
-              'Found structural directive. Use new Angular control flow syntax for better performance and readability.\n\nWhy: @if/@for are built-in Angular features with less overhead than directive matching.\n\n- <div *ngIf="isVisible">\n-   <li *ngFor="let item of items">{{ item }}</li>\n- </div>\n\n+ @if (isVisible) {\n+   @for (item of items; track item.id) {\n+     <li>{{ item }}</li>\n+   }\n+ }',
+              'Found structural directive. Use new Angular control flow syntax for better performance and readability.',
           });
         }
       }
@@ -45,6 +63,21 @@ const angularRules: Rule[] = [
     category: 'Template Syntax',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-use-let-syntax
+  // ROLE: Recommend Angular 17+ @let template variables
+  // PURPOSE: Simplifies complex template expressions by extracting them
+  //          into named variables, improving readability and avoiding
+  //          repeated evaluation.
+  // EXAMPLE:
+  //   WRONG:
+  //     {{ user?.profile?.name ? user.profile.name : 'Guest' }}
+  //     {{ user?.profile?.name ? user.profile.name : 'Guest' }}
+  //   RIGHT:
+  //     @let displayName = user?.profile?.name ?? 'Guest';
+  //     {{ displayName }}
+  //     {{ displayName }}
+  // ─────────────────────────────────────────
   {
     id: 'angular-use-let-syntax',
     label: 'Use @let for template variables',
@@ -71,6 +104,30 @@ const angularRules: Rule[] = [
 
   // ── Lifecycle ──────────────────────────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: angular-no-ngoninit
+  // ROLE: Enforce modern Angular initialization patterns
+  // PURPOSE: ngOnInit was needed when constructor injection was the norm.
+  //          With inject() + signals, field initializers and effect()
+  //          cover most use cases without lifecycle hooks.
+  // EXAMPLE:
+  //   WRONG:
+  //     export class UserComponent implements OnInit {
+  //       private userService = inject(UserService);
+  //       user: User | null = null;
+  //       ngOnInit() {
+  //         this.user = this.userService.getUser();
+  //       }
+  //     }
+  //   RIGHT:
+  //     export class UserComponent {
+  //       private userService = inject(UserService);
+  //       user = signal<User | null>(null);
+  //       constructor() {
+  //         effect(() => this.user.set(this.userService.getUser()));
+  //       }
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'angular-no-ngoninit',
     label: 'Avoid ngOnInit for simple initialization',
@@ -85,6 +142,20 @@ const angularRules: Rule[] = [
 
   // ── Deprecated APIs ────────────────────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: angular-no-ng-deep
+  // ROLE: Block deprecated view encapsulation piercing
+  // PURPOSE: ::ng-deep breaks component encapsulation and is officially
+  //          deprecated. It leads to unpredictable style leakage and
+  //          makes refactoring dangerous.
+  // EXAMPLE:
+  //   WRONG:
+  //     :host ::ng-deep .mat-card { background: red; }
+  //   RIGHT:
+  //     :host { --card-bg: red; }
+  //     /* In child component CSS: */
+  //     .mat-card { background: var(--card-bg); }
+  // ─────────────────────────────────────────
   {
     id: 'angular-no-ng-deep',
     label: 'No ::ng-deep',
@@ -97,6 +168,25 @@ const angularRules: Rule[] = [
     category: 'Angular Deprecated APIs',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-no-common-module
+  // ROLE: Enforce tree-shakeable standalone imports
+  // PURPOSE: CommonModule imports NgIf, NgFor, NgClass, AsyncPipe, and
+  //          30+ other directives/pipes. Standalone components should
+  //          import ONLY what they use — or better, use @if/@for.
+  // EXAMPLE:
+  //   WRONG:
+  //     @Component({
+  //       standalone: true,
+  //       imports: [CommonModule],
+  //     })
+  //   RIGHT:
+  //     @Component({
+  //       standalone: true,
+  //       imports: [NgClass, NgTemplateOutlet],
+  //     })
+  //     // Or even better — use @if/@for and import nothing
+  // ─────────────────────────────────────────
   {
     id: 'angular-no-common-module',
     label: 'No CommonModule import in standalone components',
@@ -109,6 +199,20 @@ const angularRules: Rule[] = [
     category: 'Angular Deprecated APIs',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-no-ngclass
+  // ROLE: Enforce modern class binding patterns
+  // PURPOSE: [ngClass] requires importing NgClass and has complex object
+  //          syntax. [class.name] binding is simpler, and Tailwind
+  //          pseudo-classes (disabled:, hover:) are even cleaner.
+  // EXAMPLE:
+  //   WRONG:
+  //     <button [ngClass]="{ 'btn-active': isActive, 'btn-disabled': isDisabled }">
+  //   RIGHT:
+  //     <button [class.btn-active]="isActive()" [class.btn-disabled]="isDisabled()">
+  //     <!-- Or with Tailwind: -->
+  //     <button class="not-disabled:bg-blue-500 disabled:bg-gray-300">
+  // ─────────────────────────────────────────
   {
     id: 'angular-no-ngclass',
     label: 'No [ngClass] — use [class] binding or Tailwind',
@@ -121,6 +225,20 @@ const angularRules: Rule[] = [
     category: 'Angular Deprecated APIs',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-no-ngstyle
+  // ROLE: Enforce modern style binding patterns
+  // PURPOSE: [ngStyle] is verbose and requires importing NgStyle.
+  //          Direct [style.prop] binding or Tailwind utilities are
+  //          simpler and more performant.
+  // EXAMPLE:
+  //   WRONG:
+  //     <div [ngStyle]="{ 'background-color': bgColor, 'font-size': fontSize + 'px' }">
+  //   RIGHT:
+  //     <div [style.background-color]="bgColor" [style.font-size.rem]="fontSize">
+  //     <!-- Or with Tailwind: -->
+  //     <div class="bg-primary text-base">
+  // ─────────────────────────────────────────
   {
     id: 'angular-no-ngstyle',
     label: 'No [ngStyle] — use [style] binding or Tailwind',
@@ -135,6 +253,22 @@ const angularRules: Rule[] = [
 
   // ── Template best practices ────────────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: angular-no-function-in-template
+  // ROLE: Block function calls in template bindings
+  // PURPOSE: Functions in templates execute on EVERY change detection
+  //          cycle, causing severe performance degradation. Signals and
+  //          computed() are memoized and only re-evaluate when deps change.
+  // EXAMPLE:
+  //   WRONG:
+  //     <span>{{ getFullName() }}</span>
+  //     <div [class.active]="isItemActive(item)">
+  //   RIGHT:
+  //     fullName = computed(() => this.firstName() + ' ' + this.lastName());
+  //     <span>{{ fullName() }}</span>
+  //     <!-- Or use a pipe: -->
+  //     <span>{{ user | fullName }}</span>
+  // ─────────────────────────────────────────
   {
     id: 'angular-no-function-in-template',
     label: 'No function calls in templates',
@@ -146,16 +280,6 @@ const angularRules: Rule[] = [
     customCheck: (file) => {
       const violations: Array<{ line: number | null; message: string }> = [];
 
-      /**
-       * Regex explanation:
-       * Match patterns like {{ someFunc() }} or (click)="handler()" but EXCLUDE:
-       *   - Event handlers: (click)="...", (submit)="...", on*="..." 
-       *   - Known safe pipes: | async, | date, | json, etc.
-       *   - Structural directives: *ngIf, *ngFor, @if, @for
-       *
-       * We look for interpolation bindings {{ expr() }} and property bindings [prop]="expr()"
-       * that contain function calls which are NOT event bindings.
-       */
       const interpolationRegex = /\{\{[^}]*\w+\s*\([^)]*\)[^}]*\}\}/g;
       const propertyBindingRegex = /\[(?!click|submit|keyup|keydown|change|input|focus|blur)\w+\]\s*=\s*"[^"]*\w+\s*\([^)]*\)[^"]*"/g;
 
@@ -165,7 +289,6 @@ const angularRules: Rule[] = [
         // Check interpolation bindings {{ func() }}
         interpolationRegex.lastIndex = 0;
         if (interpolationRegex.test(line)) {
-          // Exclude pipe usages like {{ value | pipeName }}
           const trimmed = line.trim();
           if (!trimmed.includes(' | ')) {
             violations.push({
@@ -193,6 +316,24 @@ const angularRules: Rule[] = [
 
   // ── RxJS best practices ────────────────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: angular-use-async-pipe
+  // ROLE: Prevent manual subscription memory leaks
+  // PURPOSE: Manual .subscribe() in components is the #1 cause of memory
+  //          leaks in Angular apps. The async pipe or toSignal()
+  //          auto-unsubscribes when the component is destroyed.
+  // EXAMPLE:
+  //   WRONG:
+  //     ngOnInit() {
+  //       this.userService.getUser().subscribe(user => this.user = user);
+  //     }
+  //   RIGHT:
+  //     user$ = this.userService.getUser();
+  //     <!-- In template: -->
+  //     {{ user$ | async }}
+  //     <!-- Or convert to signal: -->
+  //     user = toSignal(this.userService.getUser());
+  // ─────────────────────────────────────────
   {
     id: 'angular-use-async-pipe',
     label: 'Use async pipe or toSignal() instead of manual subscribe',
@@ -205,6 +346,26 @@ const angularRules: Rule[] = [
     category: 'RxJS',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-use-takeuntildestroyed
+  // ROLE: Enforce subscription cleanup in Angular classes
+  // PURPOSE: If subscribe() is unavoidable, takeUntilDestroyed() from
+  //          @angular/core/rxjs-interop handles cleanup automatically
+  //          tied to the component's DestroyRef lifecycle.
+  // EXAMPLE:
+  //   WRONG:
+  //     ngOnInit() {
+  //       this.data$.subscribe(d => this.process(d));
+  //     }
+  //     // Memory leak — never unsubscribes!
+  //   RIGHT:
+  //     private destroyRef = inject(DestroyRef);
+  //     ngOnInit() {
+  //       this.data$.pipe(
+  //         takeUntilDestroyed(this.destroyRef)
+  //       ).subscribe(d => this.process(d));
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'angular-use-takeuntildestroyed',
     label: 'Use takeUntilDestroyed() for subscriptions',
@@ -216,7 +377,6 @@ const angularRules: Rule[] = [
     customCheck: (file) => {
       const violations: Array<{ line: number | null; message: string }> = [];
 
-      // Only check Angular component/directive/service files
       if (
         !file.content.includes('@Component') &&
         !file.content.includes('@Directive') &&
@@ -243,6 +403,20 @@ const angularRules: Rule[] = [
     category: 'RxJS',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-prefer-signals
+  // ROLE: Recommend migration from BehaviorSubject to Signals
+  // PURPOSE: Angular Signals (signal(), computed(), effect()) are simpler,
+  //          synchronous, and deeply integrated with change detection.
+  //          BehaviorSubject is async and requires subscription management.
+  // EXAMPLE:
+  //   WRONG:
+  //     count$ = new BehaviorSubject<number>(0);
+  //     increment() { this.count$.next(this.count$.value + 1); }
+  //   RIGHT:
+  //     count = signal(0);
+  //     increment() { this.count.update(v => v + 1); }
+  // ─────────────────────────────────────────
   {
     id: 'angular-prefer-signals',
     label: 'Consider using Angular Signals',
@@ -252,7 +426,6 @@ const angularRules: Rule[] = [
     fileExtensions: ['ts'],
     pattern: null,
     customCheck: (file) => {
-      // Only flag if the component uses BehaviorSubject but no signals
       const hasBehaviorSubject = file.content.includes('BehaviorSubject');
       const hasSignal = file.content.includes('signal(') || file.content.includes('computed(');
 
@@ -272,6 +445,28 @@ const angularRules: Rule[] = [
     category: 'Angular Signals',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-prefer-inject
+  // ROLE: Enforce inject() function over constructor DI
+  // PURPOSE: inject() enables dependency injection at field declaration
+  //          level, works with standalone components, and doesn't require
+  //          constructor parameter boilerplate.
+  // EXAMPLE:
+  //   WRONG:
+  //     export class UserComponent {
+  //       constructor(
+  //         private userService: UserService,
+  //         private router: Router,
+  //         private http: HttpClient
+  //       ) {}
+  //     }
+  //   RIGHT:
+  //     export class UserComponent {
+  //       private userService = inject(UserService);
+  //       private router = inject(Router);
+  //       private http = inject(HttpClient);
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'angular-prefer-inject',
     label: 'Use inject() instead of constructor injection',
@@ -283,7 +478,6 @@ const angularRules: Rule[] = [
     customCheck: (file) => {
       const violations: Array<{ line: number | null; message: string }> = [];
       
-      // Only check Angular component/directive/service files
       if (
         !file.content.includes('@Component') &&
         !file.content.includes('@Directive') &&
@@ -292,12 +486,9 @@ const angularRules: Rule[] = [
         return [];
       }
 
-      // Check for constructor with dependency injection parameters
-      // Matches: constructor(private service: Type) or constructor(public readonly http: HttpClient)
       const constructorPattern = /constructor\s*\(\s*(?:private|public|protected|readonly|\s)+\w+\s*:\s*\w+/;
       
       if (constructorPattern.test(file.content)) {
-        // Find the line number
         for (let i = 0; i < file.lines.length; i++) {
           if (constructorPattern.test(file.lines[i])) {
             violations.push({
@@ -318,6 +509,22 @@ const angularRules: Rule[] = [
 
   // ── NEW: Signals & Signal-based Features (Angular 16+, essential in v21) ────
 
+  // ─────────────────────────────────────────
+  // RULE: angular-use-signals
+  // ROLE: Enforce Signal-based reactive state
+  // PURPOSE: Signals are the future of Angular reactivity. They are
+  //          synchronous, automatically tracked by change detection,
+  //          and eliminate the need for most RxJS subscriptions.
+  // EXAMPLE:
+  //   WRONG:
+  //     import { BehaviorSubject } from 'rxjs';
+  //     counter = new BehaviorSubject(0);
+  //     counter.next(counter.value + 1);
+  //   RIGHT:
+  //     import { signal } from '@angular/core';
+  //     counter = signal(0);
+  //     counter.update(val => val + 1);
+  // ─────────────────────────────────────────
   {
     id: 'angular-use-signals',
     label: 'Use Signals for reactive state',
@@ -329,7 +536,6 @@ const angularRules: Rule[] = [
     customCheck: (file) => {
       const violations: Array<{ line: number | null; message: string }> = [];
       
-      // Only check component/service files
       if (
         !file.content.includes('@Component') &&
         !file.content.includes('@Injectable') &&
@@ -338,7 +544,6 @@ const angularRules: Rule[] = [
         return [];
       }
 
-      // Flag BehaviorSubject usage without signal migration
       const hasBehaviorSubject = /BehaviorSubject|Subject/.test(file.content);
       const hasSignal = /signal\(|computed\(|effect\(/.test(file.content);
       const hasRxJS = /rxjs|Observable<|\.pipe\(/.test(file.content);
@@ -357,6 +562,22 @@ const angularRules: Rule[] = [
     category: 'Angular Signals',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-use-computed
+  // ROLE: Enforce computed() for derived state
+  // PURPOSE: computed() is memoized and only recalculates when its
+  //          signal dependencies change. Getters re-evaluate on every
+  //          change detection cycle.
+  // EXAMPLE:
+  //   WRONG:
+  //     get totalPrice(): number {
+  //       return this.items.reduce((sum, item) => sum + item.price, 0);
+  //     }
+  //   RIGHT:
+  //     totalPrice = computed(() =>
+  //       this.items().reduce((sum, item) => sum + item.price, 0)
+  //     );
+  // ─────────────────────────────────────────
   {
     id: 'angular-use-computed',
     label: 'Use computed() for derived state',
@@ -368,12 +589,11 @@ const angularRules: Rule[] = [
     customCheck: (file) => {
       const violations: Array<{ line: number | null; message: string }> = [];
       
-      // Flag getters in component classes that could be computed signals
       if (/get\s+\w+\s*\(\s*\).*\{[\s\S]*?return.*signal|this\.\w+\(\)/.test(file.content)) {
         violations.push({
           line: null,
           message:
-            'Found getter function. Use computed() from signals for automatic memoization and better performance.\n\nWhy: computed() caches results and only recalculates when dependencies change.\n\n- get totalPrice() {\n-   return this.items.reduce((sum, item) => sum + item.price, 0);\n- }\n\n+ import { computed } from "@angular/core";\n+ totalPrice = computed(() => \n+   this.items().reduce((sum, item) => sum + item.price, 0)\n+ );',
+            'Found getter function. Use computed() from signals for automatic memoization and better performance.',
         });
       }
       return violations;
@@ -382,6 +602,22 @@ const angularRules: Rule[] = [
     category: 'Angular Signals',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-use-effect
+  // ROLE: Enforce effect() for signal-driven side effects
+  // PURPOSE: effect() automatically tracks signal dependencies and
+  //          re-runs when they change, replacing ngOnInit-based
+  //          subscription patterns with declarative reactivity.
+  // EXAMPLE:
+  //   WRONG:
+  //     ngOnInit() {
+  //       this.data$.subscribe(data => this.processData(data));
+  //     }
+  //   RIGHT:
+  //     constructor() {
+  //       effect(() => this.processData(this.data()));
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'angular-use-effect',
     label: 'Use effect() for side effects instead of ngOnInit',
@@ -393,12 +629,11 @@ const angularRules: Rule[] = [
     customCheck: (file) => {
       const violations: Array<{ line: number | null; message: string }> = [];
       
-      // Flag ngOnInit with subscriptions or side effects
       if (/ngOnInit\s*\(\)[\s\S]*?\{[\s\S]*?(?:subscribe|addEventListener|setTimeout)/.test(file.content)) {
         violations.push({
           line: null,
           message:
-            'Found ngOnInit with side effects. Use effect() from signals for cleaner dependency tracking.\n\nWhy: effect() automatically tracks signal dependencies and runs when they change, without lifecycle timing issues.\n\n- ngOnInit() {\n-   this.data$.subscribe(data => this.processData(data));\n- }\n\n+ import { effect } from "@angular/core";\n+ constructor() {\n+   effect(() => this.processData(this.data()));\n+ }',
+            'Found ngOnInit with side effects. Use effect() from signals for cleaner dependency tracking.',
         });
       }
       return violations;
@@ -407,6 +642,22 @@ const angularRules: Rule[] = [
     category: 'Angular Signals',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-use-input-output-functions
+  // ROLE: Enforce signal-based input/output API
+  // PURPOSE: input(), output(), and model() functions provide better
+  //          null-safety, type inference, and signal integration than
+  //          @Input/@Output decorators.
+  // EXAMPLE:
+  //   WRONG:
+  //     @Input() title: string = '';
+  //     @Output() clicked = new EventEmitter<void>();
+  //   RIGHT:
+  //     title = input<string>('');
+  //     clicked = output<void>();
+  //     // Two-way binding:
+  //     name = model<string>('');
+  // ─────────────────────────────────────────
   {
     id: 'angular-use-input-output-functions',
     label: 'Use input(), output(), model() functions',
@@ -419,6 +670,22 @@ const angularRules: Rule[] = [
     category: 'Angular Components',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-signal-based-viewchild
+  // ROLE: Recommend signal-based queries
+  // PURPOSE: viewChild() and viewChildren() return signals, eliminating
+  //          the need for AfterViewInit lifecycle hooks and providing
+  //          automatic change detection integration.
+  // EXAMPLE:
+  //   WRONG:
+  //     @ViewChild('myInput') myInput!: ElementRef;
+  //     ngAfterViewInit() { this.myInput.nativeElement.focus(); }
+  //   RIGHT:
+  //     myInput = viewChild<ElementRef>('myInput');
+  //     constructor() {
+  //       afterNextRender(() => this.myInput()?.nativeElement.focus());
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'angular-signal-based-viewchild',
     label: 'Use signal-based @ViewChild where applicable',
@@ -433,6 +700,22 @@ const angularRules: Rule[] = [
 
   // ── NEW: Zoneless Change Detection (Angular 18+, recommended in v21) ───
 
+  // ─────────────────────────────────────────
+  // RULE: angular-consider-zoneless
+  // ROLE: Recommend zoneless change detection
+  // PURPOSE: Zone.js patches every async API (setTimeout, Promise, XHR)
+  //          adding ~100KB to the bundle. Signals make Zone.js optional
+  //          since they notify Angular directly of changes.
+  // EXAMPLE:
+  //   WRONG:
+  //     // app.config.ts (with Zone.js)
+  //     provideZoneChangeDetection({ eventCoalescing: true })
+  //   RIGHT:
+  //     // app.config.ts (zoneless)
+  //     provideExperimentalZonelessChangeDetection()
+  //     // angular.json
+  //     "polyfills": []  // remove zone.js
+  // ─────────────────────────────────────────
   {
     id: 'angular-consider-zoneless',
     label: 'Consider zoneless change detection',
@@ -445,10 +728,27 @@ const angularRules: Rule[] = [
     category: 'Performance',
   },
 
-  // ── NEW: Server-Side Rendering (Angular 17+) ──────────────────────────
-
   // ── Performance Rules ──────────────────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: angular-onpush-change-detection
+  // ROLE: Recommend OnPush change detection strategy
+  // PURPOSE: Default change detection runs on EVERY browser event.
+  //          OnPush only checks when @Input references change or signals
+  //          update, dramatically reducing unnecessary checks.
+  // EXAMPLE:
+  //   WRONG:
+  //     @Component({
+  //       selector: 'app-user-card',
+  //       templateUrl: './user-card.component.html',
+  //     })
+  //   RIGHT:
+  //     @Component({
+  //       selector: 'app-user-card',
+  //       templateUrl: './user-card.component.html',
+  //       changeDetection: ChangeDetectionStrategy.OnPush,
+  //     })
+  // ─────────────────────────────────────────
   {
     id: 'angular-onpush-change-detection',
     label: 'Consider OnPush change detection',
@@ -461,6 +761,21 @@ const angularRules: Rule[] = [
     category: 'Performance',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-trackby-for-loops
+  // ROLE: Enforce proper DOM identity tracking in loops
+  // PURPOSE: Without track, Angular destroys and recreates ALL DOM nodes
+  //          on every list change. track item.id lets Angular reuse
+  //          existing DOM nodes, improving performance 10-100x for lists.
+  // EXAMPLE:
+  //   WRONG:
+  //     <li *ngFor="let item of items">{{ item.name }}</li>
+  //     @for (item of items) { <li>{{ item.name }}</li> }
+  //   RIGHT:
+  //     @for (item of items; track item.id) {
+  //       <li>{{ item.name }}</li>
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'angular-trackby-for-loops',
     label: 'Use trackBy with *ngFor or proper @for iteration',
@@ -473,6 +788,20 @@ const angularRules: Rule[] = [
     category: 'Performance',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-no-unused-imports
+  // ROLE: Flag unnecessary RxJS imports when Signals are available
+  // PURPOSE: Importing Observable/Subject when Signals could be used
+  //          adds unnecessary bundle weight and cognitive overhead.
+  //          Prefer signals for simple reactive state.
+  // EXAMPLE:
+  //   WRONG:
+  //     import { Observable, BehaviorSubject } from 'rxjs';
+  //     data$ = new BehaviorSubject<string[]>([]);
+  //   RIGHT:
+  //     import { signal } from '@angular/core';
+  //     data = signal<string[]>([]);
+  // ─────────────────────────────────────────
   {
     id: 'angular-no-unused-imports',
     label: 'Avoid importing RxJS operators not used',
@@ -487,6 +816,26 @@ const angularRules: Rule[] = [
 
   // ── NEW: Server-Side Rendering Hydration (Angular 17+) ────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: angular-ssr-hydration
+  // ROLE: Block direct DOM access in SSR-compatible components
+  // PURPOSE: document.*, window.*, localStorage do not exist on the
+  //          server. Direct usage crashes SSR pre-rendering. Always
+  //          guard with isPlatformBrowser() or use afterNextRender().
+  // EXAMPLE:
+  //   WRONG:
+  //     ngOnInit() {
+  //       const token = localStorage.getItem('token');
+  //       document.title = 'My App';
+  //     }
+  //   RIGHT:
+  //     constructor() {
+  //       afterNextRender(() => {
+  //         const token = localStorage.getItem('token');
+  //         document.title = 'My App';
+  //       });
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'angular-ssr-hydration',
     label: 'Ensure SSR hydration compatibility',
@@ -499,6 +848,25 @@ const angularRules: Rule[] = [
     category: 'Server-Side Rendering',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-ssr-safe-initialization
+  // ROLE: Enforce browser API guards for SSR safety
+  // PURPOSE: Browser-only code (navigator, localStorage, window) must
+  //          be wrapped in platform guards to prevent server crashes
+  //          during pre-rendering.
+  // EXAMPLE:
+  //   WRONG:
+  //     const lang = navigator.language;
+  //     window.scrollTo(0, 0);
+  //   RIGHT:
+  //     private platformId = inject(PLATFORM_ID);
+  //     constructor() {
+  //       if (isPlatformBrowser(this.platformId)) {
+  //         const lang = navigator.language;
+  //         window.scrollTo(0, 0);
+  //       }
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'angular-ssr-safe-initialization',
     label: 'Guard browser-only APIs in SSR',
@@ -526,6 +894,23 @@ const angularRules: Rule[] = [
     category: 'Server-Side Rendering',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-lazy-load-modules
+  // ROLE: Enforce lazy loading for route modules
+  // PURPOSE: Eagerly loading all routes increases the initial bundle
+  //          size and slows Time-to-Interactive. Lazy loading defers
+  //          feature code until the user navigates to it.
+  // EXAMPLE:
+  //   WRONG:
+  //     import { UsersComponent } from './users/users.component';
+  //     { path: 'users', component: UsersComponent }
+  //   RIGHT:
+  //     {
+  //       path: 'users',
+  //       loadComponent: () => import('./users/users.component')
+  //         .then(m => m.UsersComponent)
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'angular-lazy-load-modules',
     label: 'Use lazy loading for routes',
@@ -533,13 +918,34 @@ const angularRules: Rule[] = [
       'Lazy load feature modules in routing to reduce initial bundle size and improve load time.',
     severity: 'info',
     fileExtensions: ['ts'],
-    pattern: /loadChildren:\s*\(\)\s*=>\s*import\(['"]\.['"]\)/g,
+    pattern: /loadChildren:\s*\(\)\s*=>\s*import\(/g,
     applicableTo: ['angular'],
     category: 'Performance',
   },
 
   // ── Best Practices ─────────────────────────────────────────────────────
 
+  // ─────────────────────────────────────────
+  // RULE: angular-standalone-components
+  // ROLE: Enforce standalone component architecture
+  // PURPOSE: NgModules add indirection and make dependency tracking hard.
+  //          Standalone components declare their own imports, are
+  //          tree-shakeable, and are the recommended Angular architecture.
+  // EXAMPLE:
+  //   WRONG:
+  //     @NgModule({
+  //       declarations: [UserComponent],
+  //       imports: [CommonModule],
+  //     })
+  //     export class UserModule {}
+  //   RIGHT:
+  //     @Component({
+  //       standalone: true,
+  //       imports: [NgClass],
+  //       selector: 'app-user',
+  //     })
+  //     export class UserComponent {}
+  // ─────────────────────────────────────────
   {
     id: 'angular-standalone-components',
     label: 'Prefer standalone components',
@@ -552,6 +958,24 @@ const angularRules: Rule[] = [
     category: 'Best Practices',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-strict-templates
+  // ROLE: Enforce strict template type checking
+  // PURPOSE: Without strictTemplates, Angular templates are essentially
+  //          untyped — typos in property names, wrong types, and missing
+  //          fields are silently ignored at compile time.
+  // EXAMPLE:
+  //   WRONG (tsconfig.json):
+  //     "angularCompilerOptions": {
+  //       "strictTemplates": false
+  //     }
+  //   RIGHT (tsconfig.json):
+  //     "angularCompilerOptions": {
+  //       "strictTemplates": true,
+  //       "strictInjectionParameters": true,
+  //       "strictInputAccessModifiers": true
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'angular-strict-templates',
     label: 'Enable strict template checking',
@@ -564,6 +988,23 @@ const angularRules: Rule[] = [
     category: 'TypeScript',
   },
 
+  // ─────────────────────────────────────────
+  // RULE: angular-defer-for-lazy
+  // ROLE: Recommend @defer for template-level lazy loading
+  // PURPOSE: @defer blocks let you lazy-load sections of a template
+  //          (heavy charts, tables, modals) without component-level
+  //          code splitting. Triggers include viewport, interaction, etc.
+  // EXAMPLE:
+  //   WRONG:
+  //     <app-heavy-chart [data]="chartData()"></app-heavy-chart>
+  //     <!-- Always loaded, even if below the fold -->
+  //   RIGHT:
+  //     @defer (on viewport) {
+  //       <app-heavy-chart [data]="chartData()"></app-heavy-chart>
+  //     } @placeholder {
+  //       <div class="h-64 animate-pulse bg-gray-200"></div>
+  //     }
+  // ─────────────────────────────────────────
   {
     id: 'angular-defer-for-lazy',
     label: 'Use @defer for lazy views',