@hatem427/code-guard-ci 1.0.0

package/.husky/pre-commit

@@ -0,0 +1,27 @@
+#!/usr/bin/env sh
+# ============================================================================
+# Husky pre-commit hook
+# ============================================================================
+#
+# This hook runs automatically before every commit. It:
+#   1. Executes the Code Guardian pre-commit checks
+#   2. Blocks the commit if errors are found
+#
+# Bypass methods:
+#   - Add #bypass-rules to your commit message
+#   - Run: BYPASS_RULES=true git commit -m "message"
+#
+# To skip this hook entirely (git native):
+#   git commit --no-verify
+# ============================================================================
+
+. "$(dirname -- "$0")/_/husky.sh"
+
+echo "🛡️  Running Code Guardian pre-commit checks..."
+
+# Run the TypeScript pre-commit check script via npm
+npm run precommit-check
+
+# Exit with the same code as the check script
+# (0 = pass, 1 = blocked)
+exit $?

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,646 @@
+# 🛡️ Code Guardian
+
+> **Production-ready TypeScript tooling to enforce PR & coding guidelines for Angular, React, and Next.js projects.**
+
+Automatically enforce your team's coding standards with pre-commit hooks, feature documentation generation, and PR checklists.
+
+---
+
+## 🚀 Quick Start
+
+### Option 1: Install as NPM Package (Recommended)
+
+```bash
+# Install in your project
+npm install --save-dev @team/code-guardian
+
+# Or with yarn
+yarn add -D @team/code-guardian
+
+# Initialize in your project
+npx code-guardian init
+```
+
+### Option 2: Copy Files Directly
+
+```bash
+# Clone or copy this repository into your project
+cp -r code-guardian/* your-project/
+
+# Install dependencies
+cd your-project
+npm install
+
+# Setup Husky
+npm run prepare
+```
+
+---
+
+## 📦 What's Included
+
+- ✅ **Pre-commit hooks** - Automatic code quality checks before every commit
+- ✅ **19 comprehensive rules** - Code Quality (5) + Security (4) + Performance (3) + Accessibility (2) + Framework-specific (5+)
+- ✅ **Auto-fix capability** - Automatically fix common violations (console.log, any type, alt text, button type)
+- ✅ **ESLint & Prettier** - Auto-formatting and linting integration
+- ✅ **Feature docs generator** - Auto-generate documentation from templates or code analysis
+- ✅ **PR checklist generator** - Create comprehensive PR checklists
+- ✅ **Secure bypass logging** - All bypasses logged with tamper detection
+- ✅ **Admin-only deletion** - Protected log management with audit trail
+- ✅ **Auto-detection** - Automatically detects Angular, React, or Next.js
+
+---
+
+## 🧪 Testing in Your Project
+
+### Step 1: Create a Test Git Repository
+
+```bash
+# Navigate to your Angular/React/Next.js project
+cd /path/to/your-project
+
+# Initialize git if not already done
+git init
+
+# Make sure you have a package.json with framework dependencies
+# Example for Angular:
+npm install @angular/core @angular/common
+
+# Example for React:
+npm install react react-dom
+
+# Example for Next.js:
+npm install next react react-dom
+```
+
+### Step 2: Install Code Guardian
+
+```bash
+# Option A: Link local package (for development)
+cd /home/hatem/Documents/roles
+npm link
+
+cd /path/to/your-project
+npm link @team/code-guardian
+
+# Option B: Copy files directly
+cp -r /home/hatem/Documents/roles/* .
+
+# Install dependencies
+npm install
+
+# Add required scripts to package.json
+npm pkg set \
+  scripts.set-bypass-password="npx ts-node node_modules/@team/code-guardian/scripts/set-bypass-password.ts" \
+  scripts.set-admin-password="npx ts-node node_modules/@team/code-guardian/scripts/set-admin-password.ts" \
+  scripts.delete-bypass-logs="npx ts-node node_modules/@team/code-guardian/scripts/delete-bypass-logs.ts" \
+  scripts.view-bypass-log="npx ts-node node_modules/@team/code-guardian/scripts/view-bypass-log.ts" \
+  scripts.auto-fix="npx ts-node node_modules/@team/code-guardian/scripts/auto-fix.ts"
+```
+
+### Step 3: Test the Pre-commit Hook
+
+```bash
+# Create a test file with violations
+cat > src/test.component.ts << 'EOF'
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-test',
+  template: `<div>{{ getValue() }}</div>`
+})
+export class TestComponent {
+  name: any = 'test';  // ❌ Uses 'any'
+  
+  ngOnInit() {  // ⚠️ Uses ngOnInit
+    console.log('test');  // ❌ Uses console.log
+  }
+  
+  getValue() {  // ❌ Function in template
+    return this.name;
+  }
+}
+EOF
+
+# Stage the file
+git add src/test.component.ts
+
+# Try to commit (should be blocked)
+git commit -m "test commit"
+```
+
+**Expected output:**
+```
+🛡️  Running Code Guardian pre-commit checks...
+
+────────────────────────────────────────────────────────────
+  🛡️  Code Guardian — Pre-commit Check
+────────────────────────────────────────────────────────────
+
+ℹ [INFO] Detected project: Angular
+ℹ [INFO] Found 1 staged file(s).
+
+  📂 Code Quality
+  ✖ src/test.component.ts:12 [no-console-log] Remove all console.log...
+
+  📂 TypeScript
+  ✖ src/test.component.ts:9 [no-any-type] Avoid using `any` type...
+
+❌ Commit BLOCKED — fix the errors above and try again.
+```
+
+### Step 4: Test Bypass
+
+```bash
+# Bypass via commit message
+git commit -m "test commit #bypass-rules"
+
+# Or bypass via environment variable
+BYPASS_RULES=true git commit -m "test commit"
+```
+
+**Important**: All bypasses are automatically logged for security and audit purposes. See [Bypass Security](#-bypass-logging--security) below.
+
+### Step 5: Test Feature Doc Generator
+
+```bash
+# Generate a UI component doc
+npm run generate-doc -- --name="user-card" --type=ui
+
+# Check the generated file
+cat docs/features/user-card.md
+```
+
+### Step 6: Test PR Checklist Generator
+
+```bash
+# Generate checklist for current project
+npm run generate-pr-checklist
+
+# Generate for specific framework
+npm run generate-pr-checklist -- --project=angular
+
+# Save to file
+npm run generate-pr-checklist -- --output=checklist.md
+```
+
+---
+
+## 📚 Making it Reusable as NPM Package
+
+### Option A: Publish to NPM Registry
+
+#### 1. Update package.json
+
+```bash
+# Edit package.json - change these fields:
+{
+  "name": "@your-org/code-guardian",  // Change to your org
+  "version": "1.0.0",
+  "private": false,  // Make it public
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "code-guardian": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "config",
+    "scripts",
+    "templates",
+    ".husky"
+  ]
+}
+```
+
+#### 2. Build and Publish
+
+```bash
+# Build TypeScript
+npm run build
+
+# Login to NPM
+npm login
+
+# Publish
+npm publish --access public
+```
+
+#### 3. Use in Other Projects
+
+```bash
+# In any project
+npm install --save-dev @your-org/code-guardian
+
+# Run setup
+npx code-guardian init
+```
+
+### Option B: Use as Git Submodule (No Publishing)
+
+```bash
+# In your project
+git submodule add https://github.com/your-org/code-guardian.git tools/code-guardian
+
+# Link scripts in package.json
+{
+  "scripts": {
+    "precommit-check": "ts-node tools/code-guardian/scripts/precommit-check.ts",
+    "generate-doc": "ts-node tools/code-guardian/scripts/generate-doc.ts",
+    "generate-pr-checklist": "ts-node tools/code-guardian/scripts/generate-pr-checklist.ts"
+  }
+}
+
+# Setup Husky to use the submodule
+cp tools/code-guardian/.husky/pre-commit .husky/pre-commit
+```
+
+### Option C: Use as Local NPM Package (Best for Testing)
+
+```bash
+# In the code-guardian directory
+npm link
+
+# In your project directory
+npm link @team/code-guardian
+
+# Now you can use it like a normal package
+npx code-guardian init
+```
+
+---
+
+## 🔧 Configuration
+
+### Customizing Rules
+
+Edit the config files to add/remove/modify rules:
+
+```typescript
+// config/angular.config.ts
+const angularRules: Rule[] = [
+  {
+    id: 'my-custom-rule',
+    label: 'My Custom Rule',
+    description: 'Enforce my team standard',
+    severity: 'error',
+    fileExtensions: ['ts'],
+    pattern: /forbidden-pattern/g,
+    applicableTo: ['angular'],
+    category: 'Custom Rules',
+  },
+  // ... existing rules
+];
+```
+
+### Adding New Project Types
+
+```typescript
+// config/vue.config.ts
+import { registerRules, Rule } from './guidelines.config';
+
+const vueRules: Rule[] = [
+  {
+    id: 'vue-composition-api',
+    label: 'Use Composition API',
+    description: 'Prefer Composition API over Options API',
+    severity: 'warning',
+    fileExtensions: ['vue'],
+    pattern: /export default \{[\s\S]*data\(\)/g,
+    applicableTo: ['vue'],
+    category: 'Vue Best Practices',
+  },
+];
+
+registerRules('vue', vueRules);
+export { vueRules };
+```
+
+Then update `project-detector.ts`:
+
+```typescript
+export type ProjectType = 'angular' | 'react' | 'nextjs' | 'vue' | 'unknown';
+
+// In detectProject function:
+if (hasDep(pkg, 'vue')) {
+  return { type: 'vue', label: 'Vue.js', rootDir: dir, packageJson: pkg };
+}
+```
+
+### Inline Suppressions
+
+Suppress specific rules in your code:
+
+```typescript
+// Suppress for one line
+const data: any = {}; // code-guardian-disable no-any-type
+
+// Suppress for entire file (add at top)
+// code-guardian-disable-file no-console-log
+```
+
+---
+
+## 📋 Available Rules
+
+### 📂 Code Quality (All Projects)
+
+| Rule ID | Severity | Description |
+|---------|----------|-------------|
+| `no-console-log` | 🔴 Error | No console.log statements |
+| `no-any-type` | 🔴 Error | No `any` type usage |
+| `no-settimeout` | 🟡 Warning | Avoid setTimeout |
+| `max-component-lines` | 🔴 Error | Components ≤ 400 lines |
+| `no-custom-css` | 🟡 Warning | Prefer Tailwind over custom CSS |
+
+### 🔒 Security Rules (All Projects)
+
+| Rule ID | Severity | Description |
+|---------|----------|-------------|
+| `react-no-dangerously-set-html` | 🔴 Error | Prevents XSS attacks via dangerouslySetInnerHTML |
+| `no-eval` | 🔴 Error | No eval() - blocks code injection |
+| `no-hardcoded-credentials` | 🔴 Error | Detects API keys/passwords in code |
+| `require-https` | 🔴 Error | Enforces HTTPS URLs for API calls |
+
+### ⚡ Performance Rules (React/Next.js)
+
+| Rule ID | Severity | Description |
+|---------|----------|-------------|
+| `react-no-anonymous-functions-in-render` | 🔴 Error | Prevents unnecessary re-renders |
+| `react-missing-key-prop` | 🔴 Error | Ensures proper list rendering with keys |
+| `no-large-bundle-imports` | 🟡 Warning | Warns about large library imports |
+
+### ♿ Accessibility Rules (React/Next.js)
+
+| Rule ID | Severity | Description |
+|---------|----------|-------------|
+| `require-alt-text` | 🔴 Error | All images must have alt attributes |
+| `require-button-type` | 🔴 Error | Buttons need explicit type attribute |
+
+### Angular-Specific Rules
+
+| Rule ID | Severity | Description |
+|---------|----------|-------------|
+| `angular-no-ngoninit` | 🟡 Warning | Avoid ngOnInit for simple init |
+| `angular-no-ng-deep` | 🔴 Error | No ::ng-deep usage |
+| `angular-no-common-module` | 🟡 Warning | No CommonModule in standalone |
+| `angular-no-ngclass` | 🟡 Warning | Use [class] binding instead |
+| `angular-no-ngstyle` | 🟡 Warning | Use [style] binding instead |
+| `angular-no-function-in-template` | 🔴 Error | No function calls in templates |
+| `angular-use-async-pipe` | 🟡 Warning | Use async pipe over subscribe |
+| `angular-use-takeuntildestroyed` | 🟡 Warning | Use takeUntilDestroyed() |
+| `angular-prefer-signals` | 🔵 Info | Consider using Signals |
+
+### ⚛️ React Hooks & Components
+
+| Rule ID | Severity | Description |
+|---------|----------|-------------|
+| `react-no-useeffect-no-deps` | 🔴 Error | useEffect needs dependency array |
+| `react-no-inline-styles` | 🟡 Warning | No inline style objects |
+| `react-no-direct-dom` | 🔴 Error | No direct DOM manipulation |
+| `react-prefer-fc-typing` | 🔵 Info | Type props explicitly |
+| `react-no-prop-spreading` | 🔵 Info | Avoid prop spreading |
+
+### Next.js-Specific Rules
+
+| Rule ID | Severity | Description |
+|---------|----------|-------------|
+| `nextjs-use-client-directive` | 🟡 Warning | Verify "use client" directive |
+| `nextjs-use-image-component` | 🟡 Warning | Use next/image not <img> |
+| `nextjs-use-link-component` | 🟡 Warning | Use next/link not <a> |
+| `nextjs-api-error-handling` | 🟡 Warning | API routes need try/catch |
+| `nextjs-page-metadata` | 🔵 Info | Pages should export metadata |
+
+---
+
+## 🎯 NPM Scripts Reference
+
+```bash
+# Pre-commit check (runs automatically via Husky)
+npm run precommit-check
+
+# Auto-fix violations
+npm run auto-fix                    # Fix all violations
+npm run auto-fix -- --dry-run       # Preview fixes without changing files
+
+# Security & Bypass Management
+npm run set-bypass-password         # Set developer bypass password
+npm run set-admin-password          # Set admin password (log deletion)
+npm run view-bypass-log             # View all bypass attempts
+npm run delete-bypass-logs          # Delete bypass logs (requires admin password)
+
+# Generate feature documentation
+npm run generate-doc -- --name="feature-name" --type=ui
+npm run generate-doc -- --name="auth-api" --type=api
+npm run generate-doc -- --name="user-service" --type=service
+
+# Generate PR checklist
+npm run generate-pr-checklist
+npm run generate-pr-checklist -- --project=angular
+npm run generate-pr-checklist -- --output=checklist.md
+npm run generate-pr-checklist -- --all  # All rules across all frameworks
+
+# Build TypeScript
+npm run build
+
+# Lint and format
+npm run lint
+npm run format
+```
+
+---
+
+## � Bypass Logging & Security
+
+### Immutable Audit Logging
+
+Every bypass attempt is automatically logged with:
+- ✅ **Author identity** (name and email from git)
+- ✅ **Timestamp** (when bypass occurred)
+- ✅ **Reason** (commit message or reason provided)
+- ✅ **Affected files** (what was bypassed)
+- ✅ **Branch name** (where bypass happened)
+- ✅ **Commit hash** (linked to specific commit)
+- ✅ **Integrity checksum** (tamper detection)
+
+### Two-Level Security
+
+#### 1. Bypass Password (Developer Access)
+- Allows bypassing pre-commit checks when necessary
+- Share with authorized developers
+- Default: `bypass123` ⚠️ **CHANGE IMMEDIATELY**
+
+```bash
+# Set bypass password
+npm run set-bypass-password
+```
+
+#### 2. Admin Password (Restricted Access)
+- Required to delete bypass log entries
+- Share only with team leads and security officers
+- Default: `admin123` ⚠️ **CHANGE IMMEDIATELY**
+
+```bash
+# Set admin password
+npm run set-admin-password
+```
+
+### Viewing Bypass Logs
+
+```bash
+# View all bypass attempts
+npm run view-bypass-log
+
+# Filter by author
+npm run view-bypass-log -- --author="john@example.com"
+
+# View recent (last 7 days)
+npm run view-bypass-log -- --days=7
+```
+
+### Deleting Logs (Admin Only)
+
+```bash
+# Delete specific entry
+npm run delete-bypass-logs -- --id="entry-uuid"
+
+# Delete by author
+npm run delete-bypass-logs -- --author="john@example.com"
+
+# Delete before date
+npm run delete-bypass-logs -- --before="2024-01-01"
+```
+
+**Security Features:**
+- 🔒 Logs are immutable (read-only after creation)
+- 🔍 Tamper detection with checksums
+- 📦 Automatic archiving of deleted entries
+- 🚨 Alerts when log integrity fails
+- 📊 Complete audit trail maintained
+
+### File Security
+
+All sensitive files are stored in `.code-guardian/` and should **NEVER** be committed:
+
+```
+.code-guardian/
+├── bypass-log.json              # Main audit log (read-only)
+├── bypass-password.hash         # Bypass password
+├── admin-credentials.hash       # Admin password
+└── bypass-archive/              # Deleted/tampered logs
+    ├── deleted-entries-*.json
+    └── tampered-log-*.json
+```
+
+**📖 For complete security documentation, see [docs/BYPASS_SECURITY.md](docs/BYPASS_SECURITY.md)**
+
+---
+
+## �🔄 CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/pr-check.yml
+name: PR Checks
+
+on: [pull_request]
+
+jobs:
+  code-guardian:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Run Code Guardian
+        run: npm run precommit-check
+        env:
+          BYPASS_RULES: false
+      
+      - name: Generate PR Checklist
+        run: npm run generate-pr-checklist -- --output=checklist.md
+      
+      - name: Comment PR
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const fs = require('fs');
+            const checklist = fs.readFileSync('checklist.md', 'utf8');
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: checklist
+            });
+```
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add your rules/features
+4. Test thoroughly
+5. Submit a PR with documentation
+
+---
+
+## 📄 License
+
+MIT License - feel free to use in your projects!
+
+---
+
+## 🆘 Troubleshooting
+
+### "Command not found: code-guardian"
+
+```bash
+# Make sure you've installed dependencies
+npm install
+
+# Or if using as package
+npm link @team/code-guardian
+```
+
+### "Husky hook not running"
+
+```bash
+# Reinstall Husky
+rm -rf .husky
+npm run prepare
+chmod +x .husky/pre-commit
+```
+
+### "TypeScript errors"
+
+```bash
+# Check TypeScript compilation
+npx tsc --noEmit
+
+# Rebuild
+npm run build
+```
+
+### "Rules not detecting my framework"
+
+```bash
+# Check package.json has the right dependencies
+# Angular: @angular/core
+# React: react
+# Next.js: next
+
+# Or manually specify in scripts:
+npm run precommit-check -- --project=angular
+```
+
+---
+
+**Built with ❤️ for better code quality**