@hatem427/code-guard-ci 1.0.0

package/scripts/utils/code-analyzer.ts

@@ -0,0 +1,341 @@
+/**
+ * ============================================================================
+ * code-analyzer.ts — Automatic documentation from TypeScript/React code
+ * ============================================================================
+ *
+ * Analyzes TypeScript/React components and extracts:
+ *   - Component props and their types
+ *   - JSDoc comments
+ *   - Default values
+ *   - Event handlers
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { Project, SourceFile, InterfaceDeclaration, TypeAliasDeclaration, PropertySignature } from 'ts-morph';
+
+export interface PropInfo {
+  name: string;
+  type: string;
+  required: boolean;
+  defaultValue?: string;
+  description?: string;
+}
+
+export interface ComponentInfo {
+  name: string;
+  description?: string;
+  props: PropInfo[];
+  filePath: string;
+  isReactComponent: boolean;
+}
+
+/**
+ * Analyze a TypeScript/React component file
+ */
+export function analyzeComponent(filePath: string): ComponentInfo | null {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  const project = new Project({
+    compilerOptions: {
+      jsx: 1, // React JSX
+      target: 99, // ESNext
+      module: 99, // ESNext
+    },
+  });
+
+  const sourceFile = project.addSourceFileAtPath(filePath);
+  const fileName = path.basename(filePath, path.extname(filePath));
+  
+  // Try to find component name and props
+  const componentInfo = extractComponentInfo(sourceFile, fileName);
+  
+  if (!componentInfo) {
+    return null;
+  }
+
+  return {
+    name: componentInfo.name,
+    description: componentInfo.description,
+    props: componentInfo.props,
+    filePath,
+    isReactComponent: componentInfo.isReactComponent,
+  };
+}
+
+/**
+ * Extract component information from source file
+ */
+function extractComponentInfo(sourceFile: SourceFile, defaultName: string): ComponentInfo | null {
+  let componentName = toPascalCase(defaultName);
+  let props: PropInfo[] = [];
+  let description: string | undefined;
+  let isReactComponent = false;
+
+  // Look for React component (function or arrow function)
+  const functionDeclarations = sourceFile.getFunctions();
+  const variableStatements = sourceFile.getVariableStatements();
+
+  // Check function declarations
+  for (const func of functionDeclarations) {
+    const name = func.getName();
+    if (name && /^[A-Z]/.test(name)) {
+      componentName = name;
+      isReactComponent = true;
+      description = extractJsDocComment(func);
+      
+      // Extract props from parameters
+      const params = func.getParameters();
+      if (params.length > 0) {
+        const propsParam = params[0];
+        const typeNode = propsParam.getTypeNode();
+        if (typeNode) {
+          props = extractPropsFromType(sourceFile, typeNode.getText());
+        }
+      }
+      break;
+    }
+  }
+
+  // Check variable declarations (arrow functions)
+  if (!isReactComponent) {
+    for (const statement of variableStatements) {
+      const declarations = statement.getDeclarations();
+      for (const decl of declarations) {
+        const name = decl.getName();
+        if (/^[A-Z]/.test(name)) {
+          const initializer = decl.getInitializer();
+          if (initializer && (initializer.getKindName() === 'ArrowFunction' || initializer.getKindName() === 'FunctionExpression')) {
+            componentName = name;
+            isReactComponent = true;
+            description = extractJsDocComment(decl);
+            
+            // Extract props from arrow function parameters
+            const arrowFunc = initializer.asKind(218); // ArrowFunction kind
+            if (arrowFunc) {
+              const params = arrowFunc.getParameters();
+              if (params.length > 0) {
+                const propsParam = params[0];
+                const typeNode = propsParam.getTypeNode();
+                if (typeNode) {
+                  props = extractPropsFromType(sourceFile, typeNode.getText());
+                }
+              }
+            }
+            break;
+          }
+        }
+      }
+      if (isReactComponent) break;
+    }
+  }
+
+  // If still not found, look for props interface/type
+  if (props.length === 0) {
+    props = findPropsInterface(sourceFile, componentName);
+  }
+
+  return {
+    name: componentName,
+    description,
+    props,
+    isReactComponent,
+    filePath: sourceFile.getFilePath(),
+  };
+}
+
+/**
+ * Find props interface or type alias
+ */
+function findPropsInterface(sourceFile: SourceFile, componentName: string): PropInfo[] {
+  const possibleNames = [
+    `${componentName}Props`,
+    `I${componentName}Props`,
+    `${componentName}Properties`,
+  ];
+
+  // Check interfaces
+  for (const interfaceDecl of sourceFile.getInterfaces()) {
+    const name = interfaceDecl.getName();
+    if (possibleNames.includes(name) || name.toLowerCase().includes('props')) {
+      return extractPropsFromInterface(interfaceDecl);
+    }
+  }
+
+  // Check type aliases
+  for (const typeAlias of sourceFile.getTypeAliases()) {
+    const name = typeAlias.getName();
+    if (possibleNames.includes(name) || name.toLowerCase().includes('props')) {
+      return extractPropsFromTypeAlias(typeAlias);
+    }
+  }
+
+  return [];
+}
+
+/**
+ * Extract props from interface declaration
+ */
+function extractPropsFromInterface(interfaceDecl: InterfaceDeclaration): PropInfo[] {
+  const props: PropInfo[] = [];
+
+  for (const prop of interfaceDecl.getProperties()) {
+    props.push(extractPropInfo(prop));
+  }
+
+  return props;
+}
+
+/**
+ * Extract props from type alias
+ */
+function extractPropsFromTypeAlias(typeAlias: TypeAliasDeclaration): PropInfo[] {
+  const props: PropInfo[] = [];
+  const typeNode = typeAlias.getTypeNode();
+
+  if (typeNode && typeNode.getKindName() === 'TypeLiteral') {
+    const members = (typeNode as any).getMembers();
+    for (const member of members) {
+      if (member.getKindName() === 'PropertySignature') {
+        props.push(extractPropInfo(member));
+      }
+    }
+  }
+
+  return props;
+}
+
+/**
+ * Extract props from type reference string
+ */
+function extractPropsFromType(sourceFile: SourceFile, typeName: string): PropInfo[] {
+  // Remove generic brackets and get base type name
+  const baseType = typeName.replace(/<.*>/, '').trim();
+
+  // Find the interface or type
+  const interfaceDecl = sourceFile.getInterface(baseType);
+  if (interfaceDecl) {
+    return extractPropsFromInterface(interfaceDecl);
+  }
+
+  const typeAlias = sourceFile.getTypeAlias(baseType);
+  if (typeAlias) {
+    return extractPropsFromTypeAlias(typeAlias);
+  }
+
+  return [];
+}
+
+/**
+ * Extract individual prop information
+ */
+function extractPropInfo(prop: PropertySignature): PropInfo {
+  const name = prop.getName();
+  const type = prop.getType().getText();
+  const required = !prop.hasQuestionToken();
+  const description = extractJsDocComment(prop);
+
+  // Try to get default value
+  let defaultValue: string | undefined;
+  const initializer = prop.getInitializer();
+  if (initializer) {
+    defaultValue = initializer.getText();
+  }
+
+  return {
+    name,
+    type: simplifyType(type),
+    required,
+    defaultValue,
+    description,
+  };
+}
+
+/**
+ * Extract JSDoc comment
+ */
+function extractJsDocComment(node: any): string | undefined {
+  try {
+    if (typeof node.getJsDocs !== 'function') {
+      return undefined;
+    }
+    const jsDocs = node.getJsDocs();
+    if (jsDocs && jsDocs.length > 0) {
+      const comment = jsDocs[0].getDescription().trim();
+      return comment || undefined;
+    }
+  } catch (err) {
+    // Silently fail
+  }
+  return undefined;
+}
+
+/**
+ * Simplify complex type names for documentation
+ */
+function simplifyType(type: string): string {
+  // Remove 'import("...")' wrapper
+  type = type.replace(/import\([^)]+\)\./g, '');
+  
+  // Simplify React types
+  type = type.replace(/React\./g, '');
+  type = type.replace(/MouseEvent<.*?>/g, 'MouseEvent');
+  type = type.replace(/ChangeEvent<.*?>/g, 'ChangeEvent');
+  
+  // Shorten long union types
+  if (type.length > 50 && type.includes('|')) {
+    const parts = type.split('|');
+    if (parts.length > 3) {
+      return `${parts.slice(0, 3).join(' | ')} | ...`;
+    }
+  }
+  
+  return type;
+}
+
+/**
+ * Convert kebab-case or snake_case to PascalCase
+ */
+function toPascalCase(str: string): string {
+  return str
+    .split(/[-_]/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join('');
+}
+
+/**
+ * Search for component files in directory
+ */
+export function findComponentFile(componentName: string, searchDir: string = process.cwd()): string | null {
+  const possibleNames = [
+    componentName,
+    componentName.toLowerCase(),
+    componentName.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, ''),
+  ];
+
+  const possibleExtensions = ['.tsx', '.ts', '.jsx', '.js'];
+  const possibleDirs = [
+    'src/components',
+    'components',
+    'src',
+    '.',
+  ];
+
+  for (const dir of possibleDirs) {
+    const fullDir = path.join(searchDir, dir);
+    if (!fs.existsSync(fullDir)) continue;
+
+    for (const name of possibleNames) {
+      for (const ext of possibleExtensions) {
+        const filePath = path.join(fullDir, name + ext);
+        if (fs.existsSync(filePath)) {
+          return filePath;
+        }
+      }
+    }
+  }
+
+  return null;
+}

package/scripts/utils/file-checker.ts

@@ -0,0 +1,253 @@
+/**
+ * ============================================================================
+ * file-checker.ts — Low-level file analysis utilities
+ * ============================================================================
+ *
+ * Provides helpers for reading staged files, counting lines, extracting
+ * template content, and running regex-based checks against source code.
+ * Used by the rule engine to apply individual lint rules.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface FileInfo {
+  /** Absolute path to the file */
+  absolutePath: string;
+  /** Path relative to repo root */
+  relativePath: string;
+  /** File extension without the leading dot (e.g. "ts", "tsx", "html") */
+  extension: string;
+  /** Full file content (UTF-8) */
+  content: string;
+  /** Individual lines (1-indexed access via lines[lineNumber - 1]) */
+  lines: string[];
+  /** Total line count */
+  lineCount: number;
+}
+
+export interface CheckMatch {
+  /** 1-based line number where the match was found */
+  line: number;
+  /** The content of the matched line (trimmed) */
+  text: string;
+  /** Column offset (0-based) within the line */
+  column: number;
+}
+
+// ── Git helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Returns the list of staged files (relative paths) using `git diff --cached`.
+ * Filters out deleted files (status "D") so we only check files that exist.
+ */
+export function getStagedFiles(): string[] {
+  try {
+    const output = execSync('git diff --cached --name-only --diff-filter=d', {
+      encoding: 'utf-8',
+    }).trim();
+
+    if (!output) return [];
+    return output.split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Returns the current commit message from `.git/COMMIT_EDITMSG`.
+ * Falls back to empty string if unavailable.
+ */
+export function getCommitMessage(): string {
+  try {
+    // During a pre-commit hook the message file may not exist yet.
+    // We also support reading from the HUSKY_GIT_PARAMS env.
+    const msgFile = path.join(process.cwd(), '.git', 'COMMIT_EDITMSG');
+    if (fs.existsSync(msgFile)) {
+      return fs.readFileSync(msgFile, 'utf-8').trim();
+    }
+
+    // Fallback: try getting the last commit message (for post-commit uses)
+    return execSync('git log -1 --pretty=%B 2>/dev/null', { encoding: 'utf-8' }).trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Returns the current branch name.
+ */
+export function getCurrentBranch(): string {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf-8' }).trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+// ── File reading ────────────────────────────────────────────────────────────
+
+/**
+ * Read a single file and return a structured `FileInfo` object.
+ */
+export function readFileInfo(relativePath: string): FileInfo | null {
+  const absolutePath = path.resolve(process.cwd(), relativePath);
+
+  if (!fs.existsSync(absolutePath)) return null;
+
+  try {
+    const content = fs.readFileSync(absolutePath, 'utf-8');
+    const lines = content.split('\n');
+
+    return {
+      absolutePath,
+      relativePath,
+      extension: path.extname(relativePath).replace(/^\./, ''),
+      content,
+      lines,
+      lineCount: lines.length,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read multiple staged files, filtering by allowed extensions.
+ */
+export function readStagedFiles(extensions?: string[]): FileInfo[] {
+  const staged = getStagedFiles();
+  const files: FileInfo[] = [];
+
+  for (const rel of staged) {
+    const ext = path.extname(rel).replace(/^\./, '');
+
+    // Skip files that don't match the allowed extensions
+    if (extensions && extensions.length > 0 && !extensions.includes(ext)) {
+      continue;
+    }
+
+    const info = readFileInfo(rel);
+    if (info) files.push(info);
+  }
+
+  return files;
+}
+
+// ── Content checks ──────────────────────────────────────────────────────────
+
+/**
+ * Search a file's content for all matches of the given regex.
+ * Returns an array of matches with line numbers and text.
+ */
+export function findMatches(file: FileInfo, pattern: RegExp): CheckMatch[] {
+  const matches: CheckMatch[] = [];
+
+  for (let i = 0; i < file.lines.length; i++) {
+    const line = file.lines[i];
+
+    // Skip lines that are comments
+    const trimmed = line.trim();
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) {
+      continue;
+    }
+
+    // Reset lastIndex for global regexps
+    pattern.lastIndex = 0;
+
+    const match = pattern.exec(line);
+    if (match) {
+      matches.push({
+        line: i + 1, // 1-based
+        text: trimmed,
+        column: match.index,
+      });
+    }
+  }
+
+  return matches;
+}
+
+/**
+ * Check if a file exceeds the maximum allowed line count.
+ */
+export function exceedsMaxLines(file: FileInfo, maxLines: number): boolean {
+  return file.lineCount > maxLines;
+}
+
+/**
+ * Extract Angular inline template content from a component file.
+ * Looks for `template: \`...\`` blocks.
+ */
+export function extractInlineTemplate(file: FileInfo): { content: string; startLine: number } | null {
+  const templateRegex = /template\s*:\s*`([\s\S]*?)`/;
+  const match = templateRegex.exec(file.content);
+
+  if (!match) return null;
+
+  // Find the line number where the template starts
+  const before = file.content.substring(0, match.index);
+  const startLine = before.split('\n').length;
+
+  return {
+    content: match[1],
+    startLine,
+  };
+}
+
+/**
+ * Extract content from Angular HTML template files.
+ * Returns the full file content for .html files associated with Angular components.
+ */
+export function extractExternalTemplate(file: FileInfo): string | null {
+  if (file.extension !== 'html') return null;
+  return file.content;
+}
+
+/**
+ * Check if a file has a specific inline suppression comment.
+ * Supports: // code-guardian-disable <rule-id>
+ */
+export function hasInlineSuppression(file: FileInfo, ruleId: string, lineNumber: number): boolean {
+  // Check the line itself
+  if (file.lines[lineNumber - 1]?.includes(`code-guardian-disable ${ruleId}`)) {
+    return true;
+  }
+
+  // Check the line above
+  if (lineNumber > 1 && file.lines[lineNumber - 2]?.includes(`code-guardian-disable ${ruleId}`)) {
+    return true;
+  }
+
+  // Check file-level suppression at the top of the file
+  const firstLines = file.lines.slice(0, 5).join('\n');
+  if (firstLines.includes(`code-guardian-disable-file ${ruleId}`)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Detect whether a file contains JSX/TSX content (React templates).
+ */
+export function isJsxFile(file: FileInfo): boolean {
+  return ['jsx', 'tsx'].includes(file.extension);
+}
+
+/**
+ * Detect whether a file is an Angular component.
+ */
+export function isAngularComponent(file: FileInfo): boolean {
+  return file.content.includes('@Component') && ['ts'].includes(file.extension);
+}
+
+/**
+ * Detect whether a file is a style file.
+ */
+export function isStyleFile(file: FileInfo): boolean {
+  return ['css', 'scss', 'sass', 'less'].includes(file.extension);
+}

package/scripts/utils/logger.ts

@@ -0,0 +1,88 @@
+/**
+ * ============================================================================
+ * logger.ts — Colored, structured console output for the Code Guardian toolkit
+ * ============================================================================
+ *
+ * Provides severity-based logging with ANSI color codes.
+ * No external dependency required (chalk is optional — we use raw ANSI here
+ * for zero-dep portability).
+ */
+
+// ── ANSI escape helpers ─────────────────────────────────────────────────────
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+
+const FG = {
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m',
+} as const;
+
+const BG = {
+  red: '\x1b[41m',
+  green: '\x1b[42m',
+  yellow: '\x1b[43m',
+} as const;
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/** Informational message — cyan prefix */
+export function info(msg: string): void {
+  console.log(`${FG.cyan}ℹ ${BOLD}[INFO]${RESET}${FG.cyan} ${msg}${RESET}`);
+}
+
+/** Success message — green prefix */
+export function success(msg: string): void {
+  console.log(`${FG.green}✔ ${BOLD}[PASS]${RESET}${FG.green} ${msg}${RESET}`);
+}
+
+/** Warning message — yellow prefix */
+export function warn(msg: string): void {
+  console.log(`${FG.yellow}⚠ ${BOLD}[WARN]${RESET}${FG.yellow} ${msg}${RESET}`);
+}
+
+/** Error message — red prefix */
+export function error(msg: string): void {
+  console.error(`${FG.red}✖ ${BOLD}[FAIL]${RESET}${FG.red} ${msg}${RESET}`);
+}
+
+/** Section header — bold magenta divider */
+export function header(title: string): void {
+  const line = '─'.repeat(60);
+  console.log(`\n${FG.magenta}${BOLD}${line}${RESET}`);
+  console.log(`${FG.magenta}${BOLD}  ${title}${RESET}`);
+  console.log(`${FG.magenta}${BOLD}${line}${RESET}\n`);
+}
+
+/** Dim helper text */
+export function dim(msg: string): void {
+  console.log(`${DIM}  ${msg}${RESET}`);
+}
+
+/** Print a violation detail line */
+export function violation(file: string, line: number | null, rule: string, message: string): void {
+  const loc = line !== null ? `:${line}` : '';
+  console.log(
+    `  ${FG.red}✖${RESET} ${FG.white}${file}${loc}${RESET} ${DIM}[${rule}]${RESET} ${FG.yellow}${message}${RESET}`
+  );
+}
+
+/** Print a summary banner */
+export function summary(errors: number, warnings: number): void {
+  console.log('');
+  if (errors === 0 && warnings === 0) {
+    console.log(`${BG.green}${FG.white}${BOLD}  ✔ ALL CHECKS PASSED  ${RESET}`);
+  } else if (errors === 0) {
+    console.log(`${BG.yellow}${FG.white}${BOLD}  ⚠ ${warnings} WARNING(S) — COMMIT ALLOWED  ${RESET}`);
+  } else {
+    console.log(`${BG.red}${FG.white}${BOLD}  ✖ ${errors} ERROR(S), ${warnings} WARNING(S) — COMMIT BLOCKED  ${RESET}`);
+  }
+  console.log('');
+}