@hatem427/code-guard-ci 1.0.0

package/config/angular.config.ts

@@ -0,0 +1,223 @@
+/**
+ * ============================================================================
+ * angular.config.ts — Angular-specific coding rules
+ * ============================================================================
+ *
+ * Registers rules that only apply to Angular projects:
+ *   - ngOnInit misuse
+ *   - Deprecated APIs (::ng-deep, CommonModule, ngClass, ngStyle)
+ *   - Function calls in templates
+ *   - RxJS best practices (async pipe, takeUntilDestroyed, signals)
+ */
+
+import { registerRules, Rule } from './guidelines.config';
+
+const angularRules: Rule[] = [
+  // ── Lifecycle ──────────────────────────────────────────────────────────
+
+  {
+    id: 'angular-no-ngoninit',
+    label: 'Avoid ngOnInit for simple initialization',
+    description:
+      'Prefer constructor injection and field initializers. Use ngOnInit only when you need DOM access or @Input values. Modern Angular recommends inject() + signals.',
+    severity: 'warning',
+    fileExtensions: ['ts'],
+    pattern: /ngOnInit\s*\(\s*\)/g,
+    applicableTo: ['angular'],
+    category: 'Angular Lifecycle',
+  },
+
+  // ── Deprecated APIs ────────────────────────────────────────────────────
+
+  {
+    id: 'angular-no-ng-deep',
+    label: 'No ::ng-deep',
+    description:
+      '::ng-deep is deprecated. Use :host, CSS custom properties, or component styling APIs instead.',
+    severity: 'error',
+    fileExtensions: ['css', 'scss', 'sass', 'less', 'ts'],
+    pattern: /::ng-deep/g,
+    applicableTo: ['angular'],
+    category: 'Angular Deprecated APIs',
+  },
+
+  {
+    id: 'angular-no-common-module',
+    label: 'No CommonModule import in standalone components',
+    description:
+      'Standalone components should import specific directives (NgIf, NgFor, etc.) instead of the entire CommonModule. Better yet, use @if/@for control flow.',
+    severity: 'warning',
+    fileExtensions: ['ts'],
+    pattern: /CommonModule/g,
+    applicableTo: ['angular'],
+    category: 'Angular Deprecated APIs',
+  },
+
+  {
+    id: 'angular-no-ngclass',
+    label: 'No [ngClass] — use [class] binding or Tailwind',
+    description:
+      'Prefer [class.name]="condition" binding or Tailwind dynamic classes over [ngClass]. It is cleaner and more performant.',
+    severity: 'warning',
+    fileExtensions: ['html', 'ts'],
+    pattern: /\[ngClass\]/g,
+    applicableTo: ['angular'],
+    category: 'Angular Deprecated APIs',
+  },
+
+  {
+    id: 'angular-no-ngstyle',
+    label: 'No [ngStyle] — use [style] binding or Tailwind',
+    description:
+      'Prefer [style.property]="value" binding or Tailwind utilities over [ngStyle].',
+    severity: 'warning',
+    fileExtensions: ['html', 'ts'],
+    pattern: /\[ngStyle\]/g,
+    applicableTo: ['angular'],
+    category: 'Angular Deprecated APIs',
+  },
+
+  // ── Template best practices ────────────────────────────────────────────
+
+  {
+    id: 'angular-no-function-in-template',
+    label: 'No function calls in templates',
+    description:
+      'Avoid calling functions in Angular templates — they run on every change detection cycle. Use pipes, computed signals, or memoized getters instead.',
+    severity: 'error',
+    fileExtensions: ['html'],
+    pattern: null,
+    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;
+
+      for (let i = 0; i < file.lines.length; i++) {
+        const line = file.lines[i];
+
+        // 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({
+              line: i + 1,
+              message: `Function call in interpolation: "${trimmed}". Use a pipe or signal instead.`,
+            });
+          }
+        }
+
+        // Check property bindings [prop]="func()"
+        propertyBindingRegex.lastIndex = 0;
+        if (propertyBindingRegex.test(line)) {
+          violations.push({
+            line: i + 1,
+            message: `Function call in property binding: "${line.trim()}". Use a signal or memoized getter.`,
+          });
+        }
+      }
+
+      return violations;
+    },
+    applicableTo: ['angular'],
+    category: 'Angular Templates',
+  },
+
+  // ── RxJS best practices ────────────────────────────────────────────────
+
+  {
+    id: 'angular-use-async-pipe',
+    label: 'Use async pipe or toSignal() instead of manual subscribe',
+    description:
+      'Manual .subscribe() in components leads to memory leaks. Use the async pipe in templates or convert to signals with toSignal().',
+    severity: 'warning',
+    fileExtensions: ['ts'],
+    pattern: /\.subscribe\s*\(/g,
+    applicableTo: ['angular'],
+    category: 'RxJS',
+  },
+
+  {
+    id: 'angular-use-takeuntildestroyed',
+    label: 'Use takeUntilDestroyed() for subscriptions',
+    description:
+      'If you must subscribe manually, use takeUntilDestroyed() from @angular/core/rxjs-interop to auto-unsubscribe.',
+    severity: 'warning',
+    fileExtensions: ['ts'],
+    pattern: null,
+    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') &&
+        !file.content.includes('@Injectable')
+      ) {
+        return [];
+      }
+
+      const hasSubscribe = /\.subscribe\s*\(/.test(file.content);
+      const hasTakeUntilDestroyed = file.content.includes('takeUntilDestroyed');
+      const hasAsyncPipe = file.content.includes('| async') || file.content.includes('toSignal');
+
+      if (hasSubscribe && !hasTakeUntilDestroyed && !hasAsyncPipe) {
+        violations.push({
+          line: null,
+          message:
+            'Manual .subscribe() found without takeUntilDestroyed(). Add pipe(takeUntilDestroyed()) or use async pipe / toSignal().',
+        });
+      }
+
+      return violations;
+    },
+    applicableTo: ['angular'],
+    category: 'RxJS',
+  },
+
+  {
+    id: 'angular-prefer-signals',
+    label: 'Consider using Angular Signals',
+    description:
+      'Angular 16+ supports Signals for reactive state. Consider using signal(), computed(), and effect() for simpler reactivity.',
+    severity: 'info',
+    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(');
+
+      if (hasBehaviorSubject && !hasSignal) {
+        return [
+          {
+            line: null,
+            message:
+              'BehaviorSubject detected. Consider migrating to Angular Signals (signal(), computed()) for simpler state management.',
+          },
+        ];
+      }
+
+      return [];
+    },
+    applicableTo: ['angular'],
+    category: 'Angular Signals',
+  },
+];
+
+// Register all Angular-specific rules
+registerRules('angular', angularRules);
+
+export { angularRules };

package/config/guidelines.config.ts

@@ -0,0 +1,229 @@
+/**
+ * ============================================================================
+ * guidelines.config.ts — Central guidelines configuration
+ * ============================================================================
+ *
+ * Defines the shape of a rule, severity levels, and the shared rule registry.
+ * Each project-type config (angular, react, nextjs) plugs into this registry.
+ */
+
+import { ProjectType } from '../scripts/utils/project-detector';
+
+// ── Severity ────────────────────────────────────────────────────────────────
+
+export type Severity = 'error' | 'warning' | 'info';
+
+// ── Rule definition ─────────────────────────────────────────────────────────
+
+export interface Rule {
+  /** Unique identifier — used in reports and inline suppressions */
+  id: string;
+
+  /** Human-readable label for logs and checklists */
+  label: string;
+
+  /** Detailed description of what the rule checks */
+  description: string;
+
+  /** Severity: 'error' blocks commit, 'warning' allows but logs, 'info' is advisory */
+  severity: Severity;
+
+  /**
+   * Which file extensions this rule applies to.
+   * Empty array = all files.
+   */
+  fileExtensions: string[];
+
+  /**
+   * Regex pattern to search for inside file content.
+   * If set, the rule engine will scan each line for this pattern.
+   * `null` means the rule uses a custom checker function instead.
+   */
+  pattern: RegExp | null;
+
+  /**
+   * Optional custom checker function for complex rules that cannot be
+   * expressed as a simple regex. Receives the file info and returns
+   * an array of violation objects.
+   */
+  customCheck?: (file: any) => Array<{ line: number | null; message: string }>;
+
+  /**
+   * Which project types this rule applies to.
+   * Empty array = all project types.
+   */
+  applicableTo: ProjectType[];
+
+  /** Category for grouping in the PR checklist */
+  category: string;
+}
+
+// ── Shared rules (framework-agnostic) ───────────────────────────────────────
+
+export const sharedRules: Rule[] = [
+  {
+    id: 'no-console-log',
+    label: 'No console.log',
+    description: 'Remove all console.log statements before committing. Use a proper logging service instead.',
+    severity: 'error',
+    fileExtensions: ['ts', 'tsx', 'js', 'jsx'],
+    pattern: /console\.log\s*\(/g,
+    applicableTo: [],
+    category: 'Code Quality',
+  },
+  {
+    id: 'no-any-type',
+    label: 'No `any` type',
+    description: 'Avoid using `any` type. Use proper typing, generics, or `unknown` instead.',
+    severity: 'error',
+    fileExtensions: ['ts', 'tsx'],
+    pattern: /:\s*any\b|<any>|as\s+any\b/g,
+    applicableTo: [],
+    category: 'TypeScript',
+  },
+  {
+    id: 'no-settimeout',
+    label: 'No setTimeout',
+    description: 'Avoid using setTimeout. Use RxJS timer(), delay(), or framework-specific alternatives.',
+    severity: 'warning',
+    fileExtensions: ['ts', 'tsx', 'js', 'jsx'],
+    pattern: /setTimeout\s*\(/g,
+    applicableTo: [],
+    category: 'Async Patterns',
+  },
+  {
+    id: 'max-component-lines',
+    label: 'Component size ≤ 400 lines',
+    description: 'Components should not exceed 400 lines. Split large components into smaller, focused ones.',
+    severity: 'error',
+    fileExtensions: ['ts', 'tsx', 'jsx'],
+    pattern: null,
+    customCheck: (file) => {
+      if (file.lineCount > 400) {
+        return [
+          {
+            line: null,
+            message: `File has ${file.lineCount} lines (max 400). Consider splitting into smaller components.`,
+          },
+        ];
+      }
+      return [];
+    },
+    applicableTo: [],
+    category: 'Architecture',
+  },
+  {
+    id: 'no-custom-css',
+    label: 'Use Tailwind instead of custom CSS',
+    description: 'Prefer Tailwind utility classes over writing custom CSS. Custom styles should be rare and justified.',
+    severity: 'warning',
+    fileExtensions: ['css', 'scss', 'sass', 'less'],
+    pattern: null,
+    customCheck: (file) => {
+      // Allow Tailwind config files and global resets
+      const allowedFiles = [
+        'tailwind.css',
+        'globals.css',
+        'global.css',
+        'styles.css',
+        'variables.css',
+        'reset.css',
+      ];
+      const basename = file.relativePath.split('/').pop() || '';
+      if (allowedFiles.includes(basename)) return [];
+
+      // Check for custom CSS declarations (property: value patterns)
+      const cssDeclarationRegex = /^\s*[a-z-]+\s*:\s*[^;]+;/gm;
+      const matches: Array<{ line: number | null; message: string }> = [];
+      const lines: string[] = file.lines;
+
+      for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        // Skip @apply (Tailwind), @import, @tailwind directives, comments, and CSS custom properties
+        if (
+          trimmed.startsWith('@apply') ||
+          trimmed.startsWith('@import') ||
+          trimmed.startsWith('@tailwind') ||
+          trimmed.startsWith('//') ||
+          trimmed.startsWith('/*') ||
+          trimmed.startsWith('*') ||
+          trimmed.startsWith('--') // CSS custom properties
+        ) {
+          continue;
+        }
+
+        cssDeclarationRegex.lastIndex = 0;
+        if (cssDeclarationRegex.test(lines[i])) {
+          matches.push({
+            line: i + 1,
+            message: `Custom CSS found: "${trimmed}". Prefer Tailwind utilities.`,
+          });
+        }
+      }
+
+      // Only report if there are a meaningful number of custom declarations
+      if (matches.length > 3) {
+        return [
+          {
+            line: null,
+            message: `File contains ${matches.length} custom CSS declarations. Consider using Tailwind utilities instead.`,
+          },
+        ];
+      }
+
+      return [];
+    },
+    applicableTo: [],
+    category: 'Styling',
+  },
+];
+
+// ── Rule registry (populated by project-specific configs) ───────────────────
+
+const ruleRegistry: Map<ProjectType, Rule[]> = new Map();
+
+/**
+ * Register rules for a specific project type.
+ * Called by angular.config.ts, react.config.ts, nextjs.config.ts.
+ */
+export function registerRules(projectType: ProjectType, rules: Rule[]): void {
+  const existing = ruleRegistry.get(projectType) || [];
+  ruleRegistry.set(projectType, [...existing, ...rules]);
+}
+
+/**
+ * Get all applicable rules for a detected project type.
+ * Merges shared rules with project-specific rules.
+ */
+export function getRulesForProject(projectType: ProjectType): Rule[] {
+  const projectRules = ruleRegistry.get(projectType) || [];
+
+  // Filter shared rules: include if applicableTo is empty (all) or includes this project type
+  const applicableShared = sharedRules.filter(
+    (r) => r.applicableTo.length === 0 || r.applicableTo.includes(projectType)
+  );
+
+  return [...applicableShared, ...projectRules];
+}
+
+/**
+ * Get ALL rules across all project types (used for PR checklist generation).
+ */
+export function getAllRules(): Rule[] {
+  const allProjectRules: Rule[] = [];
+  for (const rules of ruleRegistry.values()) {
+    allProjectRules.push(...rules);
+  }
+
+  // Deduplicate by rule id
+  const seen = new Set<string>();
+  const deduped: Rule[] = [];
+  for (const rule of [...sharedRules, ...allProjectRules]) {
+    if (!seen.has(rule.id)) {
+      seen.add(rule.id);
+      deduped.push(rule);
+    }
+  }
+
+  return deduped;
+}

package/config/nextjs.config.ts

@@ -0,0 +1,160 @@
+/**
+ * ============================================================================
+ * nextjs.config.ts — Next.js-specific coding rules
+ * ============================================================================
+ *
+ * Registers rules that only apply to Next.js projects:
+ *   - App Router patterns
+ *   - Server/Client component boundaries
+ *   - Image optimization
+ *   - API route conventions
+ *
+ * Note: Next.js projects also inherit React rules automatically
+ * because the React config registers rules for 'nextjs' too.
+ */
+
+import { registerRules, Rule } from './guidelines.config';
+
+const nextjsRules: Rule[] = [
+  // ── App Router ─────────────────────────────────────────────────────────
+
+  {
+    id: 'nextjs-use-client-directive',
+    label: 'Verify "use client" / "use server" directives',
+    description:
+      'Components using hooks, event handlers, or browser APIs must have "use client" at the top. Server components must not have it.',
+    severity: 'warning',
+    fileExtensions: ['tsx', 'jsx', 'ts', 'js'],
+    pattern: null,
+    customCheck: (file) => {
+      const violations: Array<{ line: number | null; message: string }> = [];
+
+      const hasUseClient = file.content.includes("'use client'") || file.content.includes('"use client"');
+      const hasHooks = /use(State|Effect|Context|Reducer|Callback|Memo|Ref)\s*\(/.test(file.content);
+      const hasEventHandlers = /on(Click|Change|Submit|KeyDown|KeyUp|Focus|Blur)\s*=/.test(file.content);
+
+      // If file uses hooks or event handlers but lacks "use client"
+      if ((hasHooks || hasEventHandlers) && !hasUseClient) {
+        // Only flag if this looks like a component file (not a utility/hook file)
+        const isComponent = /export\s+(default\s+)?function\s+[A-Z]/.test(file.content) ||
+                           /const\s+[A-Z]\w+\s*[:=]/.test(file.content);
+        if (isComponent) {
+          violations.push({
+            line: 1,
+            message: 'Component uses hooks/events but missing "use client" directive at the top.',
+          });
+        }
+      }
+
+      return violations;
+    },
+    applicableTo: ['nextjs'],
+    category: 'Next.js App Router',
+  },
+
+  // ── Image optimization ─────────────────────────────────────────────────
+
+  {
+    id: 'nextjs-use-image-component',
+    label: 'Use next/image instead of <img>',
+    description:
+      'Always use the Next.js <Image> component for automatic optimization, lazy loading, and proper sizing.',
+    severity: 'warning',
+    fileExtensions: ['tsx', 'jsx'],
+    pattern: /<img\s/g,
+    applicableTo: ['nextjs'],
+    category: 'Next.js Performance',
+  },
+
+  // ── Link component ────────────────────────────────────────────────────
+
+  {
+    id: 'nextjs-use-link-component',
+    label: 'Use next/link instead of <a>',
+    description:
+      'Use the Next.js <Link> component for client-side navigation. Avoid plain <a> tags for internal links.',
+    severity: 'warning',
+    fileExtensions: ['tsx', 'jsx'],
+    pattern: /<a\s+href\s*=\s*["']\/(?!\/)/g,
+    applicableTo: ['nextjs'],
+    category: 'Next.js Navigation',
+  },
+
+  // ── API routes ─────────────────────────────────────────────────────────
+
+  {
+    id: 'nextjs-api-error-handling',
+    label: 'API routes must have error handling',
+    description:
+      'All API route handlers (GET, POST, etc.) must wrap logic in try/catch and return proper error responses.',
+    severity: 'warning',
+    fileExtensions: ['ts', 'js'],
+    pattern: null,
+    customCheck: (file) => {
+      const violations: Array<{ line: number | null; message: string }> = [];
+
+      // Only check files in api/ or route.ts/route.js paths
+      if (
+        !file.relativePath.includes('/api/') &&
+        !file.relativePath.includes('route.ts') &&
+        !file.relativePath.includes('route.js')
+      ) {
+        return [];
+      }
+
+      const hasExportedHandler = /export\s+(async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH)/.test(file.content);
+      const hasTryCatch = file.content.includes('try {') || file.content.includes('try{');
+
+      if (hasExportedHandler && !hasTryCatch) {
+        violations.push({
+          line: null,
+          message: 'API route handler missing try/catch error handling. Wrap logic in try/catch.',
+        });
+      }
+
+      return violations;
+    },
+    applicableTo: ['nextjs'],
+    category: 'Next.js API Routes',
+  },
+
+  // ── Metadata ──────────────────────────────────────────────────────────
+
+  {
+    id: 'nextjs-page-metadata',
+    label: 'Pages should export metadata',
+    description:
+      'Page components should export a metadata object or generateMetadata function for SEO.',
+    severity: 'info',
+    fileExtensions: ['tsx', 'ts'],
+    pattern: null,
+    customCheck: (file) => {
+      const violations: Array<{ line: number | null; message: string }> = [];
+
+      // Only check page.tsx files
+      const basename = file.relativePath.split('/').pop() || '';
+      if (basename !== 'page.tsx' && basename !== 'page.ts') return [];
+
+      const hasMetadata =
+        file.content.includes('export const metadata') ||
+        file.content.includes('export function generateMetadata') ||
+        file.content.includes('export async function generateMetadata');
+
+      if (!hasMetadata) {
+        violations.push({
+          line: null,
+          message: 'Page is missing metadata export. Add `export const metadata` or `export function generateMetadata`.',
+        });
+      }
+
+      return violations;
+    },
+    applicableTo: ['nextjs'],
+    category: 'Next.js SEO',
+  },
+];
+
+// Register all Next.js-specific rules
+registerRules('nextjs', nextjsRules);
+
+export { nextjsRules };