@hatem427/code-guard-ci 1.0.0

package/scripts/generate-pr-checklist.ts

@@ -0,0 +1,285 @@
+/**
+ * ============================================================================
+ * generate-pr-checklist.ts — PR Checklist Generator
+ * ============================================================================
+ *
+ * Generates a Markdown checklist suitable for pasting into a GitHub PR
+ * description or comment. The checklist includes:
+ *   - All active coding rules (grouped by category)
+ *   - Feature doc verification
+ *   - Pre-commit check result summary
+ *
+ * Usage:
+ *   npm run generate-pr-checklist
+ *   npm run generate-pr-checklist -- --output=pr-checklist.md
+ *   npm run generate-pr-checklist -- --project=angular
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+
+import { detectProject, ProjectType } from './utils/project-detector';
+import { getRulesForProject, getAllRules, Rule, Severity } from '../config/guidelines.config';
+import { getCurrentBranch } from './utils/file-checker';
+import * as logger from './utils/logger';
+
+// ── Load all project-type configs (side-effect: registers rules) ────────────
+
+import '../config/angular.config';
+import '../config/react.config';
+import '../config/nextjs.config';
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+interface ChecklistOptions {
+  /** Override project type instead of auto-detecting */
+  project?: ProjectType;
+  /** Output file path (if not set, prints to stdout) */
+  output?: string;
+  /** Include all rules across all project types */
+  all?: boolean;
+}
+
+// ── Argument parsing ────────────────────────────────────────────────────────
+
+function parseArgs(): ChecklistOptions {
+  const args = process.argv.slice(2);
+  const opts: ChecklistOptions = {};
+
+  for (const arg of args) {
+    const [key, ...valueParts] = arg.replace(/^--/, '').split('=');
+    const value = valueParts.join('=').replace(/^["']|["']$/g, '');
+
+    switch (key) {
+      case 'project':
+        if (['angular', 'react', 'nextjs'].includes(value)) {
+          opts.project = value as ProjectType;
+        }
+        break;
+      case 'output':
+        opts.output = value;
+        break;
+      case 'all':
+        opts.all = value === 'true' || value === '';
+        break;
+    }
+  }
+
+  return opts;
+}
+
+// ── Checklist generation ────────────────────────────────────────────────────
+
+/**
+ * Get the severity emoji for display.
+ */
+function severityEmoji(severity: Severity): string {
+  switch (severity) {
+    case 'error':
+      return '🔴';
+    case 'warning':
+      return '🟡';
+    case 'info':
+      return '🔵';
+  }
+}
+
+/**
+ * Check if feature documentation exists for the current branch.
+ */
+function checkFeatureDocs(): { exists: boolean; featureName: string; docPath: string } {
+  const branch = getCurrentBranch();
+  const featureName = branch.replace(/^(feat|feature)\//, '');
+  const docPath = path.join('docs', 'features', `${featureName}.md`);
+
+  return {
+    exists: fs.existsSync(docPath),
+    featureName,
+    docPath,
+  };
+}
+
+/**
+ * Get the list of changed files for this PR (compared to main/master).
+ */
+function getChangedFiles(): string[] {
+  try {
+    // Try comparing with main first, then master
+    const baseBranch = (() => {
+      try {
+        execSync('git rev-parse --verify origin/main', { stdio: 'pipe' });
+        return 'origin/main';
+      } catch {
+        return 'origin/master';
+      }
+    })();
+
+    const output = execSync(`git diff --name-only ${baseBranch}...HEAD`, {
+      encoding: 'utf-8',
+    }).trim();
+
+    return output ? output.split('\n').filter(Boolean) : [];
+  } catch {
+    // Fallback: just get staged files
+    try {
+      return execSync('git diff --cached --name-only', { encoding: 'utf-8' })
+        .trim()
+        .split('\n')
+        .filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+}
+
+/**
+ * Generate the full PR checklist in Markdown format.
+ */
+function generateChecklist(rules: Rule[], projectLabel: string): string {
+  const branch = getCurrentBranch();
+  const changedFiles = getChangedFiles();
+  const featureDoc = checkFeatureDocs();
+  const isFeatureBranch = branch.startsWith('feat/') || branch.startsWith('feature/');
+  const today = new Date().toISOString().split('T')[0];
+
+  let md = '';
+
+  // ── Header ──────────────────────────────────────────────────────────────
+  md += `## 🛡️ Code Guardian — PR Checklist\n\n`;
+  md += `> Auto-generated on ${today} for **${projectLabel}** project\n`;
+  md += `> Branch: \`${branch}\` | Files changed: ${changedFiles.length}\n\n`;
+
+  // ── Changed files summary ─────────────────────────────────────────────
+  md += `### 📁 Changed Files (${changedFiles.length})\n\n`;
+  if (changedFiles.length > 0) {
+    md += `<details>\n<summary>Click to expand file list</summary>\n\n`;
+    for (const f of changedFiles) {
+      md += `- \`${f}\`\n`;
+    }
+    md += `\n</details>\n\n`;
+  } else {
+    md += `_No changed files detected._\n\n`;
+  }
+
+  // ── Coding rules checklist ────────────────────────────────────────────
+  md += `### ✅ Coding Rules Checklist\n\n`;
+
+  // Group rules by category
+  const byCategory = new Map<string, Rule[]>();
+  for (const rule of rules) {
+    const existing = byCategory.get(rule.category) || [];
+    existing.push(rule);
+    byCategory.set(rule.category, existing);
+  }
+
+  for (const [category, categoryRules] of byCategory) {
+    md += `**${category}**\n\n`;
+
+    for (const rule of categoryRules) {
+      const emoji = severityEmoji(rule.severity);
+      md += `- [ ] ${emoji} **${rule.label}** — ${rule.description}\n`;
+    }
+    md += `\n`;
+  }
+
+  // ── Feature docs section ──────────────────────────────────────────────
+  md += `### 📄 Documentation\n\n`;
+
+  if (isFeatureBranch) {
+    const docStatus = featureDoc.exists ? '✅' : '❌';
+    md += `- [${featureDoc.exists ? 'x' : ' '}] ${docStatus} Feature documentation exists at \`${featureDoc.docPath}\`\n`;
+
+    if (!featureDoc.exists) {
+      md += `  > ⚠️ **Action required**: Run \`npm run generate-doc -- --name="${featureDoc.featureName}" --type=ui\` to generate docs.\n`;
+    }
+  } else {
+    md += `- [x] ℹ️ Not a feature branch — docs not required.\n`;
+  }
+
+  md += `\n`;
+
+  // ── Pre-commit verification ───────────────────────────────────────────
+  md += `### 🔧 Pre-commit Checks\n\n`;
+  md += `- [ ] ✅ \`npm run precommit-check\` passes without errors\n`;
+  md += `- [ ] ✅ ESLint reports no errors\n`;
+  md += `- [ ] ✅ Prettier formatting is consistent\n`;
+  md += `- [ ] ✅ No console.log statements in committed code\n`;
+  md += `- [ ] ✅ All components ≤ 400 lines\n`;
+  md += `\n`;
+
+  // ── Additional review items ───────────────────────────────────────────
+  md += `### 🔍 Manual Review Points\n\n`;
+  md += `- [ ] Code has been self-reviewed\n`;
+  md += `- [ ] Naming conventions are followed\n`;
+  md += `- [ ] No hardcoded values or magic numbers\n`;
+  md += `- [ ] Error handling is in place\n`;
+  md += `- [ ] Edge cases are considered\n`;
+  md += `- [ ] Tests are updated/added for new functionality\n`;
+  md += `- [ ] No unnecessary comments or dead code\n`;
+  md += `\n`;
+
+  // ── Footer ────────────────────────────────────────────────────────────
+  md += `---\n`;
+  md += `_Generated by [Code Guardian](https://github.com/team/code-guardian) v1.0.0_\n`;
+
+  return md;
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+function main(): void {
+  logger.header('📋 Code Guardian — PR Checklist Generator');
+
+  const opts = parseArgs();
+
+  // Determine project type
+  let projectType: ProjectType;
+  let projectLabel: string;
+
+  if (opts.project) {
+    projectType = opts.project;
+    projectLabel = opts.project.charAt(0).toUpperCase() + opts.project.slice(1);
+    logger.info(`Using specified project type: ${projectLabel}`);
+  } else {
+    const detected = detectProject();
+    projectType = detected.type;
+    projectLabel = detected.label;
+    logger.info(`Detected project type: ${projectLabel}`);
+  }
+
+  // Get rules
+  const rules = opts.all ? getAllRules() : getRulesForProject(projectType);
+  logger.info(`Using ${rules.length} rule(s) for checklist.`);
+
+  // Generate the checklist
+  const checklist = generateChecklist(rules, projectLabel);
+
+  // Output
+  if (opts.output) {
+    const outputPath = path.resolve(opts.output);
+    fs.writeFileSync(outputPath, checklist, 'utf-8');
+    logger.success(`PR checklist written to: ${outputPath}`);
+  } else {
+    // Print to stdout
+    console.log('\n' + checklist);
+    logger.success('PR checklist generated. Copy the above into your PR description!');
+  }
+
+  // Also copy to clipboard if pbcopy/xclip is available
+  try {
+    if (process.platform === 'darwin') {
+      execSync('pbcopy', { input: checklist });
+      logger.dim('📋 Copied to clipboard (macOS)');
+    } else if (process.platform === 'linux') {
+      execSync('xclip -selection clipboard', { input: checklist });
+      logger.dim('📋 Copied to clipboard (Linux)');
+    }
+  } catch {
+    // Clipboard copy is a nice-to-have, not critical
+  }
+}
+
+// ── Execute ─────────────────────────────────────────────────────────────────
+
+main();

package/scripts/precommit-check.ts

@@ -0,0 +1,349 @@
+/**
+ * ============================================================================
+ * precommit-check.ts — Main pre-commit hook script
+ * ============================================================================
+ *
+ * Entrypoint for the `npm run precommit-check` command.
+ * This script:
+ *   1. Checks bypass conditions (commit message, env variable)
+ *   2. Detects the project type (Angular / React / NextJS)
+ *   3. Loads the appropriate rule configuration
+ *   4. Reads all staged files
+ *   5. Executes the rule engine
+ *   6. Runs ESLint and Prettier on staged files
+ *   7. Reports results and exits with code 1 if errors are found
+ *
+ * Usage:
+ *   npm run precommit-check
+ *   BYPASS_RULES=true npm run precommit-check   # skip all checks
+ */
+
+import { execSync } from 'child_process';
+import * as path from 'path';
+
+// ── Import utilities ────────────────────────────────────────────────────────
+
+import { detectProject, ProjectType } from './utils/project-detector';
+import { getStagedFiles, getCommitMessage, readStagedFiles } from './utils/file-checker';
+import { getRulesForProject } from '../config/guidelines.config';
+import { executeRules, printReport, RuleEngineReport } from './utils/rule-engine';
+import * as logger from './utils/logger';
+import { verifyBypassPassword, recordBypass } from './utils/bypass-manager';
+import * as readline from 'readline';
+
+// ── Load all project-type configs (side-effect: registers rules) ────────────
+
+import '../config/angular.config';
+import '../config/react.config';
+import '../config/nextjs.config';
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+/** The bypass flag that can appear in a commit message */
+const BYPASS_COMMIT_FLAG = '#bypass-rules';
+
+/** Environment variable to bypass all checks */
+const BYPASS_ENV_VAR = 'BYPASS_RULES';
+
+/** File extensions we care about for linting */
+const LINTABLE_EXTENSIONS = ['ts', 'tsx', 'js', 'jsx', 'html', 'css', 'scss'];
+
+/** File extensions for code guardian rule checks */
+const CHECKABLE_EXTENSIONS = ['ts', 'tsx', 'js', 'jsx', 'html', 'css', 'scss', 'sass', 'less'];
+
+// ── Bypass detection ────────────────────────────────────────────────────────
+
+/**
+ * Prompt user for input (password or reason)
+ */
+function promptUser(question: string, hidden: boolean = false): Promise<string> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    if (hidden) {
+      // Hide password input
+      const stdin = process.stdin as any;
+      stdin.setRawMode(true);
+      
+      let password = '';
+      process.stdout.write(question);
+      
+      stdin.on('data', (char: Buffer) => {
+        const str = char.toString('utf-8');
+        
+        if (str === '\n' || str === '\r' || str === '\u0004') {
+          stdin.setRawMode(false);
+          process.stdout.write('\n');
+          rl.close();
+          resolve(password);
+        } else if (str === '\u0003') {
+          // Ctrl+C
+          process.exit(1);
+        } else if (str === '\u007f' || str === '\b') {
+          // Backspace
+          if (password.length > 0) {
+            password = password.slice(0, -1);
+            process.stdout.write('\b \b');
+          }
+        } else {
+          password += str;
+          process.stdout.write('*');
+        }
+      });
+    } else {
+      rl.question(question, (answer) => {
+        rl.close();
+        resolve(answer);
+      });
+    }
+  });
+}
+
+/**
+ * Check if the pre-commit checks should be bypassed.
+ * Three methods:
+ *   1. Environment variable `BYPASS_RULES=true` (no password required)
+ *   2. Commit message contains `#bypass-rules` (requires password)
+ *   3. Interactive password prompt (if errors found)
+ */
+async function shouldBypass(commitMessage: string): Promise<{ bypassed: boolean; reason: string; method: 'commit-message' | 'env-variable' | 'password' }> {
+  // Check environment variable (for CI/CD - no password required)
+  if (process.env[BYPASS_ENV_VAR]?.toLowerCase() === 'true') {
+    // Allow custom reason via BYPASS_REASON environment variable
+    const customReason = process.env['BYPASS_REASON'];
+    const reason = customReason || 'Automated bypass via environment variable';
+    recordBypass(reason, commitMessage, 'env-variable');
+    return { bypassed: true, reason: `Environment variable ${BYPASS_ENV_VAR}=true`, method: 'env-variable' };
+  }
+
+  // Check commit message flag (requires password)
+  if (commitMessage.includes(BYPASS_COMMIT_FLAG)) {
+    logger.warn(`Bypass flag detected in commit message: "${BYPASS_COMMIT_FLAG}"`);
+    logger.info('Password required to bypass checks.');
+    
+    const password = await promptUser('🔐 Enter bypass password: ', true);
+    
+    if (verifyBypassPassword(password)) {
+      const reason = await promptUser('📝 Reason for bypass: ', false);
+      recordBypass(reason || 'No reason provided', commitMessage, 'commit-message');
+      return { bypassed: true, reason: `Commit message contains "${BYPASS_COMMIT_FLAG}" (authenticated)`, method: 'commit-message' };
+    } else {
+      logger.error('❌ Invalid password. Bypass denied.');
+      return { bypassed: false, reason: '', method: 'commit-message' };
+    }
+  }
+
+  return { bypassed: false, reason: '', method: 'commit-message' };
+}
+
+// ── ESLint runner ───────────────────────────────────────────────────────────
+
+/**
+ * Run ESLint on staged files. Returns true if linting passed.
+ */
+function runEslint(stagedFiles: string[]): boolean {
+  const lintableFiles = stagedFiles.filter((f) => {
+    const ext = path.extname(f).replace(/^\./, '');
+    return LINTABLE_EXTENSIONS.includes(ext);
+  });
+
+  if (lintableFiles.length === 0) {
+    logger.dim('No lintable files found — skipping ESLint.');
+    return true;
+  }
+
+  logger.info(`Running ESLint on ${lintableFiles.length} file(s)...`);
+
+  try {
+    const fileList = lintableFiles.join(' ');
+    execSync(`npx eslint ${fileList} --max-warnings 0`, {
+      stdio: 'inherit',
+      encoding: 'utf-8',
+    });
+    logger.success('ESLint passed.');
+    return true;
+  } catch {
+    logger.error('ESLint found issues. Fix them before committing.');
+    return false;
+  }
+}
+
+// ── Prettier runner ─────────────────────────────────────────────────────────
+
+/**
+ * Run Prettier on staged files in check mode. Returns true if formatting is OK.
+ * If formatting issues are found, runs Prettier --write and re-stages the files.
+ */
+function runPrettier(stagedFiles: string[]): boolean {
+  const formattableFiles = stagedFiles.filter((f) => {
+    const ext = path.extname(f).replace(/^\./, '');
+    return LINTABLE_EXTENSIONS.includes(ext);
+  });
+
+  if (formattableFiles.length === 0) {
+    logger.dim('No formattable files found — skipping Prettier.');
+    return true;
+  }
+
+  logger.info(`Running Prettier on ${formattableFiles.length} file(s)...`);
+
+  try {
+    const fileList = formattableFiles.join(' ');
+    execSync(`npx prettier --check ${fileList}`, {
+      stdio: 'pipe',
+      encoding: 'utf-8',
+    });
+    logger.success('Prettier check passed.');
+    return true;
+  } catch {
+    logger.warn('Prettier found formatting issues — auto-fixing...');
+
+    try {
+      const fileList = formattableFiles.join(' ');
+      execSync(`npx prettier --write ${fileList}`, {
+        stdio: 'inherit',
+        encoding: 'utf-8',
+      });
+
+      // Re-stage the auto-formatted files
+      execSync(`git add ${formattableFiles.join(' ')}`, {
+        stdio: 'inherit',
+        encoding: 'utf-8',
+      });
+
+      logger.success('Prettier auto-fixed and re-staged files.');
+      return true;
+    } catch {
+      logger.error('Prettier auto-fix failed.');
+      return false;
+    }
+  }
+}
+
+// ── Feature doc detection ───────────────────────────────────────────────────
+
+/**
+ * If the commit looks like a new feature (branch name contains "feat/" or
+ * "feature/"), remind the user to generate docs.
+ */
+function checkFeatureDocsReminder(): void {
+  try {
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf-8' }).trim();
+
+    if (branch.startsWith('feat/') || branch.startsWith('feature/')) {
+      const featureName = branch.replace(/^(feat|feature)\//, '');
+      const docPath = path.join('docs', 'features', `${featureName}.md`);
+
+      const fs = require('fs');
+      if (!fs.existsSync(docPath)) {
+        logger.warn(
+          `Feature branch detected: "${branch}"\n` +
+          `  📄 No feature doc found at ${docPath}\n` +
+          `  💡 Run: npm run generate-doc -- --name="${featureName}" --type=ui`
+        );
+      }
+    }
+  } catch {
+    // Silently ignore — not critical
+  }
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  logger.header('🛡️  Code Guardian — Pre-commit Check');
+
+  // Get commit message early
+  const commitMessage = getCommitMessage();
+
+  // Step 1: Check for bypass
+  const bypass = await shouldBypass(commitMessage);
+  if (bypass.bypassed) {
+    logger.warn(`Checks BYPASSED: ${bypass.reason}`);
+    logger.warn('⚠️  All rules skipped. Make sure this is intentional!');
+    process.exit(0);
+  }
+
+  // Step 2: Detect project type
+  const project = detectProject();
+  logger.info(`Detected project: ${project.label}`);
+
+  if (project.type === 'unknown') {
+    logger.warn(
+      'Could not detect project type. Only shared rules will be applied.\n' +
+      '  Hint: Make sure package.json has @angular/core, react, or next as a dependency.'
+    );
+  }
+
+  // Step 3: Get staged files
+  const stagedPaths = getStagedFiles();
+  if (stagedPaths.length === 0) {
+    logger.info('No staged files found — nothing to check.');
+    process.exit(0);
+  }
+
+  logger.info(`Found ${stagedPaths.length} staged file(s).`);
+
+  // Step 4: Read file contents
+  const files = readStagedFiles(CHECKABLE_EXTENSIONS);
+  if (files.length === 0) {
+    logger.info('No checkable files in staging — skipping rule engine.');
+  }
+
+  // Step 5: Load rules and execute
+  let report: RuleEngineReport = {
+    violations: [],
+    errorCount: 0,
+    warningCount: 0,
+    infoCount: 0,
+    filesChecked: 0,
+    rulesExecuted: 0,
+    bypassed: false,
+  };
+
+  if (files.length > 0) {
+    const rules = getRulesForProject(project.type);
+    logger.info(`Loaded ${rules.length} rule(s) for ${project.label}.`);
+
+    report = executeRules(files, rules, true);
+    printReport(report);
+  }
+
+  // Step 6: Run ESLint
+  const eslintPassed = runEslint(stagedPaths);
+
+  // Step 7: Run Prettier (auto-fix mode)
+  const prettierPassed = runPrettier(stagedPaths);
+
+  // Step 8: Check for feature docs
+  checkFeatureDocsReminder();
+
+  // Step 9: Final verdict
+  console.log('');
+  if (report.errorCount > 0 || !eslintPassed) {
+    logger.error('❌ Commit BLOCKED — fix the errors above and try again.');
+    logger.dim(`  To bypass: use "${BYPASS_COMMIT_FLAG}" in commit message or set ${BYPASS_ENV_VAR}=true`);
+    
+    // Exit immediately with error code - no interactive bypass in hook
+    // User must use #bypass-rules in commit message to bypass
+    process.exitCode = 1;
+    process.exit(1);
+  }
+
+  if (report.warningCount > 0 || !prettierPassed) {
+    logger.warn('⚠️  Commit allowed with warnings. Please address them soon.');
+  }
+
+  logger.success('✅ All checks passed — commit allowed!');
+  process.exit(0);
+}
+
+// ── Execute ─────────────────────────────────────────────────────────────────
+
+main().catch((err) => {
+  logger.error(`Unexpected error: ${err.message || err}`);
+  process.exit(1);
+});