@hatem427/code-guard-ci 1.0.0

package/scripts/utils/project-detector.ts

@@ -0,0 +1,115 @@
+/**
+ * ============================================================================
+ * project-detector.ts — Automatically detect the frontend framework in use
+ * ============================================================================
+ *
+ * Inspects the project's package.json and file system to determine whether the
+ * current repository uses Angular, React, NextJS, or an unknown framework.
+ * This drives which set of coding rules should be enforced.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// ── Supported project types ─────────────────────────────────────────────────
+
+export type ProjectType = 'angular' | 'react' | 'nextjs' | 'unknown';
+
+export interface DetectionResult {
+  /** Which framework was detected */
+  type: ProjectType;
+  /** Human-readable label for logging */
+  label: string;
+  /** Root directory of the project */
+  rootDir: string;
+  /** package.json contents (parsed) */
+  packageJson: Record<string, any>;
+}
+
+// ── Detection logic ─────────────────────────────────────────────────────────
+
+/**
+ * Read the nearest package.json starting from `startDir` and walking up.
+ * Returns the parsed contents and the directory that contained it.
+ */
+function findPackageJson(startDir: string): { dir: string; pkg: Record<string, any> } | null {
+  let current = path.resolve(startDir);
+
+  while (true) {
+    const candidate = path.join(current, 'package.json');
+    if (fs.existsSync(candidate)) {
+      try {
+        const content = fs.readFileSync(candidate, 'utf-8');
+        return { dir: current, pkg: JSON.parse(content) };
+      } catch {
+        // Malformed JSON — keep walking
+      }
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) break; // reached filesystem root
+    current = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Check whether a dependency name exists in `dependencies` or
+ * `devDependencies` of the given package.json object.
+ */
+function hasDep(pkg: Record<string, any>, name: string): boolean {
+  return !!(pkg.dependencies?.[name] || pkg.devDependencies?.[name]);
+}
+
+/**
+ * Detect the project type based on the nearest package.json.
+ *
+ * Priority order (first match wins):
+ *   1. NextJS  — has `next` as a dependency
+ *   2. Angular — has `@angular/core` as a dependency
+ *   3. React   — has `react` as a dependency
+ *   4. Unknown — none of the above
+ *
+ * NextJS is checked first because it also pulls in React, so we want
+ * the more specific framework to win.
+ */
+export function detectProject(startDir: string = process.cwd()): DetectionResult {
+  const result = findPackageJson(startDir);
+
+  if (!result) {
+    return {
+      type: 'unknown',
+      label: 'Unknown Project',
+      rootDir: startDir,
+      packageJson: {},
+    };
+  }
+
+  const { dir, pkg } = result;
+
+  // NextJS check (must come before React — NextJS depends on React)
+  if (hasDep(pkg, 'next')) {
+    return { type: 'nextjs', label: 'Next.js', rootDir: dir, packageJson: pkg };
+  }
+
+  // Angular check
+  if (hasDep(pkg, '@angular/core')) {
+    return { type: 'angular', label: 'Angular', rootDir: dir, packageJson: pkg };
+  }
+
+  // React check
+  if (hasDep(pkg, 'react')) {
+    return { type: 'react', label: 'React', rootDir: dir, packageJson: pkg };
+  }
+
+  // Fallback — additional heuristics
+  if (fs.existsSync(path.join(dir, 'angular.json'))) {
+    return { type: 'angular', label: 'Angular (heuristic)', rootDir: dir, packageJson: pkg };
+  }
+  if (fs.existsSync(path.join(dir, 'next.config.js')) || fs.existsSync(path.join(dir, 'next.config.mjs'))) {
+    return { type: 'nextjs', label: 'Next.js (heuristic)', rootDir: dir, packageJson: pkg };
+  }
+
+  return { type: 'unknown', label: 'Unknown Project', rootDir: dir, packageJson: pkg };
+}

package/scripts/utils/rule-engine.ts

@@ -0,0 +1,186 @@
+/**
+ * ============================================================================
+ * rule-engine.ts — Orchestrates rule execution against a set of files
+ * ============================================================================
+ *
+ * The rule engine is the core processor. It takes a list of files and a list
+ * of rules, then runs each rule against each applicable file. Results are
+ * collected into a structured report.
+ */
+
+import { Rule, Severity } from '../../config/guidelines.config';
+import { FileInfo, findMatches, hasInlineSuppression } from './file-checker';
+import * as logger from './logger';
+
+// ── Result types ────────────────────────────────────────────────────────────
+
+export interface Violation {
+  /** The file where the violation was found */
+  file: string;
+  /** 1-based line number (null for file-level violations) */
+  line: number | null;
+  /** The rule that was violated */
+  ruleId: string;
+  /** Human-readable label */
+  ruleLabel: string;
+  /** Description of the violation */
+  message: string;
+  /** How severe is this? */
+  severity: Severity;
+  /** Category for grouping */
+  category: string;
+}
+
+export interface RuleEngineReport {
+  /** All violations found */
+  violations: Violation[];
+  /** Total number of error-severity violations */
+  errorCount: number;
+  /** Total number of warning-severity violations */
+  warningCount: number;
+  /** Total number of info-severity violations */
+  infoCount: number;
+  /** How many files were checked */
+  filesChecked: number;
+  /** How many rules were executed */
+  rulesExecuted: number;
+  /** Was the check bypassed? */
+  bypassed: boolean;
+}
+
+// ── Engine ──────────────────────────────────────────────────────────────────
+
+/**
+ * Run all `rules` against all `files` and collect a report.
+ *
+ * @param files  - The list of files to check (usually staged files).
+ * @param rules  - The list of rules to apply.
+ * @param verbose - If true, logs each rule as it runs.
+ * @returns A structured report of all findings.
+ */
+export function executeRules(
+  files: FileInfo[],
+  rules: Rule[],
+  verbose: boolean = false
+): RuleEngineReport {
+  const violations: Violation[] = [];
+  let rulesExecuted = 0;
+
+  for (const rule of rules) {
+    rulesExecuted++;
+
+    if (verbose) {
+      logger.dim(`Running rule: ${rule.id} — ${rule.label}`);
+    }
+
+    for (const file of files) {
+      // ── Extension filter ──────────────────────────────────────────────
+      if (
+        rule.fileExtensions.length > 0 &&
+        !rule.fileExtensions.includes(file.extension)
+      ) {
+        continue;
+      }
+
+      // ── Regex-based check ─────────────────────────────────────────────
+      if (rule.pattern) {
+        const matches = findMatches(file, rule.pattern);
+
+        for (const match of matches) {
+          // Check for inline suppression
+          if (hasInlineSuppression(file, rule.id, match.line)) {
+            continue;
+          }
+
+          violations.push({
+            file: file.relativePath,
+            line: match.line,
+            ruleId: rule.id,
+            ruleLabel: rule.label,
+            message: `${rule.description} (found: "${match.text.substring(0, 80)}")`,
+            severity: rule.severity,
+            category: rule.category,
+          });
+        }
+      }
+
+      // ── Custom check ──────────────────────────────────────────────────
+      if (rule.customCheck) {
+        const customViolations = rule.customCheck(file);
+
+        for (const cv of customViolations) {
+          // Check for inline suppression (if there's a line number)
+          if (cv.line && hasInlineSuppression(file, rule.id, cv.line)) {
+            continue;
+          }
+
+          violations.push({
+            file: file.relativePath,
+            line: cv.line,
+            ruleId: rule.id,
+            ruleLabel: rule.label,
+            message: cv.message,
+            severity: rule.severity,
+            category: rule.category,
+          });
+        }
+      }
+    }
+  }
+
+  // ── Count by severity ─────────────────────────────────────────────────
+
+  const errorCount = violations.filter((v) => v.severity === 'error').length;
+  const warningCount = violations.filter((v) => v.severity === 'warning').length;
+  const infoCount = violations.filter((v) => v.severity === 'info').length;
+
+  return {
+    violations,
+    errorCount,
+    warningCount,
+    infoCount,
+    filesChecked: files.length,
+    rulesExecuted,
+    bypassed: false,
+  };
+}
+
+/**
+ * Display a pretty-printed report in the terminal.
+ */
+export function printReport(report: RuleEngineReport): void {
+  if (report.bypassed) {
+    logger.warn('Rules bypassed — skipping checks.');
+    return;
+  }
+
+  logger.header(`Code Guardian Report — ${report.filesChecked} file(s), ${report.rulesExecuted} rule(s)`);
+
+  if (report.violations.length === 0) {
+    logger.success('No violations found!');
+    logger.summary(0, 0);
+    return;
+  }
+
+  // Group violations by category
+  const byCategory = new Map<string, Violation[]>();
+  for (const v of report.violations) {
+    const existing = byCategory.get(v.category) || [];
+    existing.push(v);
+    byCategory.set(v.category, existing);
+  }
+
+  for (const [category, items] of byCategory) {
+    console.log(`\n  📂 ${category}`);
+
+    for (const v of items) {
+      logger.violation(v.file, v.line, v.ruleId, v.message);
+    }
+  }
+
+  logger.summary(report.errorCount, report.warningCount);
+
+  if (report.infoCount > 0) {
+    logger.info(`${report.infoCount} informational notice(s) — consider addressing them.`);
+  }
+}

package/scripts/view-bypass-log.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env ts-node
+/**
+ * ============================================================================
+ * view-bypass-log.ts — View bypass audit log
+ * ============================================================================
+ *
+ * Usage:
+ *   npm run view-bypass-log
+ *   npm run view-bypass-log -- --author="john@example.com"
+ *   npm run view-bypass-log -- --days=7
+ */
+
+import { generateBypassReport, getBypassesByAuthor, getRecentBypasses } from './utils/bypass-manager';
+import * as logger from './utils/logger';
+
+function parseArgs(): { author?: string; days?: number } {
+  const args = process.argv.slice(2);
+  const opts: { author?: string; days?: number } = {};
+
+  for (const arg of args) {
+    const [key, ...valueParts] = arg.replace(/^--/, '').split('=');
+    const value = valueParts.join('=').replace(/^["']|["']$/g, '');
+
+    switch (key) {
+      case 'author':
+        opts.author = value;
+        break;
+      case 'days':
+        opts.days = parseInt(value, 10);
+        break;
+    }
+  }
+
+  return opts;
+}
+
+function main() {
+  logger.header('📊 Code Guardian — Bypass Audit Log');
+
+  const opts = parseArgs();
+
+  if (opts.author) {
+    logger.info(`Filtering by author: ${opts.author}`);
+    const entries = getBypassesByAuthor(opts.author);
+
+    if (entries.length === 0) {
+      logger.info(`No bypass entries found for ${opts.author}`);
+      return;
+    }
+
+    console.log(`\nFound ${entries.length} bypass(es) by ${opts.author}:\n`);
+    for (const entry of entries) {
+      const date = new Date(entry.timestamp).toLocaleString();
+      console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+      console.log(`📅 ${date}`);
+      console.log(`📝 Reason: ${entry.reason}`);
+      console.log(`🌿 Branch: ${entry.branch}`);
+      console.log(`📁 Files: ${entry.files.length} file(s)`);
+      console.log(`🔑 Method: ${entry.method}`);
+      if (entry.commitHash) {
+        console.log(`🔗 Commit: ${entry.commitHash}`);
+      }
+      console.log('');
+    }
+  } else if (opts.days) {
+    logger.info(`Showing bypasses from last ${opts.days} day(s)`);
+    const entries = getRecentBypasses(opts.days);
+
+    if (entries.length === 0) {
+      logger.info(`No bypass entries found in the last ${opts.days} day(s)`);
+      return;
+    }
+
+    console.log(`\nFound ${entries.length} bypass(es) in the last ${opts.days} day(s):\n`);
+    for (const entry of entries) {
+      const date = new Date(entry.timestamp).toLocaleString();
+      console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+      console.log(`👤 ${entry.author} <${entry.email}>`);
+      console.log(`📅 ${date}`);
+      console.log(`📝 Reason: ${entry.reason}`);
+      console.log(`🌿 Branch: ${entry.branch}`);
+      console.log(`🔑 Method: ${entry.method}`);
+      console.log('');
+    }
+  } else {
+    // Show full report
+    const report = generateBypassReport();
+    console.log(report);
+  }
+}
+
+main();

package/templates/feature-doc-api.md

@@ -0,0 +1,101 @@
+# {{FEATURE_TITLE}} — API
+
+> **Type**: API Endpoint / Route  
+> **Created**: {{DATE}}  
+> **Author**: {{AUTHOR}}  
+> **Status**: 🚧 Draft
+
+---
+
+## 📝 Description
+
+{{DESCRIPTION}}
+
+## 🌐 Endpoint
+
+| Method | Path                    | Auth Required |
+| ------ | ----------------------- | ------------- |
+| `GET`  | `/api/{{FEATURE_NAME}}` | ✅ Yes        |
+| `POST` | `/api/{{FEATURE_NAME}}` | ✅ Yes        |
+| _TODO_ | _TODO_                  | _TODO_        |
+
+## 📥 Request
+
+### Headers
+
+| Header          | Value              | Required |
+| --------------- | ------------------ | -------- |
+| `Authorization` | `Bearer <token>`   | Yes      |
+| `Content-Type`  | `application/json` | Yes      |
+
+### Query Parameters (GET)
+
+| Param    | Type     | Default | Description       |
+| -------- | -------- | ------- | ----------------- |
+| `page`   | `number` | `1`     | Page number       |
+| `limit`  | `number` | `20`    | Items per page    |
+| `search` | `string` | `""`    | Search query      |
+| _TODO_   | _TODO_   | _TODO_  | _Add more params_ |
+
+### Request Body (POST/PUT)
+
+```typescript
+interface {{FEATURE_TITLE}}Request {
+  // TODO: Define request body
+  name: string;
+  description?: string;
+}
+```
+
+### Example Request
+
+```bash
+curl -X POST /api/{{FEATURE_NAME}} \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "example"}'
+```
+
+## 📤 Response
+
+### Success Response (200)
+
+```typescript
+interface {{FEATURE_TITLE}}Response {
+  success: boolean;
+  data: {
+    id: string;
+    // TODO: Define response shape
+  };
+  meta?: {
+    total: number;
+    page: number;
+    limit: number;
+  };
+}
+```
+
+### Error Responses
+
+| Status | Code               | Description              |
+| ------ | ------------------ | ------------------------ |
+| `400`  | `VALIDATION_ERROR` | Invalid request body     |
+| `401`  | `UNAUTHORIZED`     | Missing or invalid token |
+| `404`  | `NOT_FOUND`        | Resource not found       |
+| `500`  | `INTERNAL_ERROR`   | Server error             |
+
+## 🔒 Authorization
+
+- Requires authenticated user
+- Role-based access: _TODO: define roles_
+- Rate limiting: _TODO: define limits_
+
+## 📝 Notes
+
+- _TODO: Add implementation notes_
+- _TODO: Add links to related endpoints_
+- _TODO: Add caching strategy if applicable_
+
+---
+
+_Generated by Code Guardian — {{DOC_TYPE}} template_

package/templates/feature-doc-service.md

@@ -0,0 +1,113 @@
+# {{FEATURE_TITLE}} — Service
+
+> **Type**: Service / Business Logic  
+> **Created**: {{DATE}}  
+> **Author**: {{AUTHOR}}  
+> **Status**: 🚧 Draft
+
+---
+
+## 📝 Description
+
+{{DESCRIPTION}}
+
+## 🏗️ Architecture
+
+### Location
+
+```
+src/
+├── services/
+│   └── {{FEATURE_NAME}}/
+│       ├── {{FEATURE_NAME}}.service.ts    # Main service
+│       ├── {{FEATURE_NAME}}.types.ts      # TypeScript interfaces
+│       ├── {{FEATURE_NAME}}.utils.ts      # Helper functions
+│       └── {{FEATURE_NAME}}.spec.ts       # Unit tests
+```
+
+### Dependency Graph
+
+```
+{{FEATURE_TITLE}}Service
+├── HttpClient / fetch
+├── AuthService (injection)
+├── LoggingService (injection)
+└── ConfigService (injection)
+```
+
+## 🚀 Usage
+
+### Angular (Injectable)
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class {{FEATURE_TITLE}}Service {
+  private readonly http = inject(HttpClient);
+
+  getAll(): Observable<{{FEATURE_TITLE}}[]> {
+    return this.http.get<{{FEATURE_TITLE}}[]>('/api/{{FEATURE_NAME}}');
+  }
+}
+```
+
+### React / Next.js (Hook or Module)
+
+```typescript
+export function use{{FEATURE_TITLE}}() {
+  const [data, setData] = useState<{{FEATURE_TITLE}}[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/{{FEATURE_NAME}}')
+      .then(res => res.json())
+      .then(setData)
+      .finally(() => setLoading(false));
+  }, []);
+
+  return { data, loading };
+}
+```
+
+## 📥 Inputs / Parameters
+
+| Method      | Params              | Return Type                 | Description         |
+| ----------- | ------------------- | --------------------------- | ------------------- |
+| `getAll()`  | `filters?: Filters` | `Observable<T[]>` / `T[]`   | Fetch all records   |
+| `getById()` | `id: string`        | `Observable<T>` / `T`       | Fetch single record |
+| `create()`  | `data: CreateDTO`   | `Observable<T>` / `T`       | Create new record   |
+| `update()`  | `id, data: Partial` | `Observable<T>` / `T`       | Update existing     |
+| `delete()`  | `id: string`        | `Observable<void>` / `void` | Delete record       |
+
+## 📤 Outputs / Events
+
+| Event       | Payload  | Description                     |
+| ----------- | -------- | ------------------------------- |
+| `onCreated` | `T`      | Emitted after successful create |
+| `onUpdated` | `T`      | Emitted after successful update |
+| `onDeleted` | `string` | Emitted after successful delete |
+| `onError`   | `Error`  | Emitted on any error            |
+
+## 🧪 Testing
+
+```typescript
+describe("{{FEATURE_TITLE}}Service", () => {
+  it("should fetch all records", async () => {
+    // TODO: Add test implementation
+  });
+
+  it("should handle errors gracefully", async () => {
+    // TODO: Add error handling tests
+  });
+});
+```
+
+## 📝 Notes
+
+- _TODO: Add state management considerations_
+- _TODO: Add caching strategy_
+- _TODO: Add retry/error-handling approach_
+- _TODO: Add performance considerations_
+
+---
+
+_Generated by Code Guardian — {{DOC_TYPE}} template_

package/templates/feature-doc-ui.md

@@ -0,0 +1,91 @@
+# {{FEATURE_TITLE}}
+
+> **Type**: UI Component  
+> **Created**: {{DATE}}  
+> **Author**: {{AUTHOR}}  
+> **Status**: 🚧 Draft
+
+---
+
+## 📝 Description
+
+{{DESCRIPTION}}
+
+## 🖼️ Visual Reference
+
+<!-- Add screenshots or Figma links here -->
+
+_TODO: Add screenshots_
+
+## 🚀 Usage
+
+### Basic Usage
+
+```html
+<!-- Angular -->
+<app-{{FEATURE_NAME}}></app-{{FEATURE_NAME}}>
+
+<!-- React / Next.js -->
+<{{FEATURE_TITLE}} />
+```
+
+### With Options
+
+```html
+<!-- Angular -->
+<app-{{FEATURE_NAME}}
+  [variant]="'primary'"
+  [size]="'md'"
+  (action)="onAction($event)"
+>
+</app-{{FEATURE_NAME}}>
+
+<!-- React / Next.js -->
+<{{FEATURE_TITLE}} variant="primary" size="md" onAction={handleAction} />
+```
+
+## 📥 Inputs / Props
+
+| Name       | Type      | Default     | Description                        |
+| ---------- | --------- | ----------- | ---------------------------------- |
+| `variant`  | `string`  | `'default'` | Visual variant: primary, secondary |
+| `size`     | `string`  | `'md'`      | Size: sm, md, lg                   |
+| `disabled` | `boolean` | `false`     | Whether the component is disabled  |
+| _TODO_     | _TODO_    | _TODO_      | _Add more inputs as needed_        |
+
+## 📤 Outputs / Events
+
+| Name     | Payload | Description                     |
+| -------- | ------- | ------------------------------- |
+| `action` | `Event` | Emitted when the user interacts |
+| _TODO_   | _TODO_  | _Add more outputs as needed_    |
+
+## 🎨 Styling
+
+- Uses **Tailwind CSS** utility classes
+- Supports dark mode via `dark:` variants
+- Responsive breakpoints: `sm`, `md`, `lg`, `xl`
+
+### CSS Custom Properties
+
+```css
+/* Override defaults in parent context */
+--{{FEATURE_NAME}}-bg: theme('colors.white');
+--{{FEATURE_NAME}}-border: theme('colors.gray.200');
+```
+
+## ♿ Accessibility
+
+- [ ] Keyboard navigable
+- [ ] Screen reader compatible (aria labels)
+- [ ] Focus indicators visible
+- [ ] Color contrast meets WCAG AA
+
+## 📝 Notes
+
+- _TODO: Add implementation notes, caveats, or known limitations._
+- _TODO: Add links to related components or documentation._
+
+---
+
+_Generated by Code Guardian — {{DOC_TYPE}} template_