🛡️ Code Guardian

<p align="center"> <strong>AI-Aware Code Protection for Modern Development</strong> </p> <p align="center"> <a href="#-features">Features</a> • <a href="#-quick-start">Quick Start</a> • <a href="#-real-world-examples">Examples</a> • <a href="#-documentation">Docs</a> • <a href="#-contributing">Contributing</a> </p> <p align="center"> <img src="https://img.shields.io/npm/v/@diullei/codeguardian/beta" alt="npm version" /> <img src="https://img.shields.io/badge/status-beta-yellow" alt="Status: Beta" /> <img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT" /> </p>

---

🎯 What is Code Guardian?

Code Guardian is a validation tool that helps you maintain code quality and architectural integrity, especially when working with AI coding assistants. It validates only what changed, making it perfect for CI/CD pipelines and pre-commit hooks.

The Problem: AI assistants are great at writing code, but they don't always follow your project's rules, patterns, or architectural decisions.

The Solution: Code Guardian acts as your automated code checker, ensuring that both human and AI-generated code adheres to your standards.

✨ Features

• 🚀 Lightning Fast - Validates only changed files, not your entire codebase
• 🤖 AI-Friendly - Clear error messages help AI assistants self-correct
• 🧩 Composable Rules - Build complex validations from simple primitives
• 🔍 AST-Aware - Search code structure with ast-grep integration
• 📦 Zero Config - Sensible defaults with full customization when needed
• 🛡️ Git-Native - Works seamlessly with branches, commits, and diffs
• 🚫 Smart Exclusions - Use .cg-ignore files to skip directories

🚀 Quick Start

Prerequisites

• Node.js 16 or higher
• Git repository
• ast-grep CLI (optional, for AST-based rules)

Installation

npm install -g @diullei/codeguardian@beta

# Or run directly without installing
npx @diullei/codeguardian@beta check

Your First Rule

Create a protect-auth.cg.yaml file in your project root:

# Protect critical authentication code
id: protect-auth
description: Authentication code requires manual review
rule:
    type: for_each
    select:
        type: select_files
        path_pattern: 'src/auth/**/*'
    assert:
        type: assert_property
        property_path: 'status'
        expected_value: 'unchanged'
        operator: '=='
        message: 'Authentication code cannot be modified without review'

Run validation:

codeguardian check

# ✅ All rules passed!

📚 Real-World Examples

🚨 Prevent AI Hallucinations

Stop AI from creating duplicate or alternative versions of files:

id: no-duplicate-files
description: Prevent AI from creating alternative file versions
rule:
    type: none_of
    rules:
        - type: for_each
          select:
              type: select_files
              path_pattern: '**/*_(improved|enhanced|copy|v2).*'
          assert:
              type: assert_match
              pattern: '.*'
              should_match: true
              message: 'Update the original file instead of creating duplicates'

🏛️ Enforce Clean Architecture

Keep your domain logic pure and framework-agnostic:

id: clean-architecture
description: Domain must not depend on infrastructure
rule:
    type: for_each
    select:
        type: select_files
        path_pattern: 'src/domain/**/*.ts'
    assert:
        type: none_of
        rules:
            - type: assert_match
              pattern: 'from.*infrastructure'
              message: 'Domain cannot import infrastructure'
            - type: assert_match
              pattern: 'import.*(express|axios|prisma)'
              message: 'Domain must remain framework-agnostic'

🔒 Security Patterns

Detect potential vulnerabilities using AST queries:

id: no-eval
description: Prevent dynamic code execution
rule:
    type: for_each
    select:
        type: select_files
        path_pattern: '**/*.{js,ts}'
        select_all: true # Check entire codebase
    assert:
        type: for_each
        select:
            type: select_ast_nodes
            query: 'eval($CODE)'
            language: 'javascript'
        assert:
            type: assert_match
            pattern: '.'
            should_match: false
            message: 'eval() is forbidden - security risk'

📊 Validate Build Metrics

Ensure build quality and performance:

id: bundle-size-limit
description: Keep bundle size under control
rule:
    type: for_each
    select:
        type: select_command_output
        command: 'du -k dist/bundle.js | cut -f1'
    assert:
        type: assert_property
        property_path: 'stdout'
        extract_pattern: '(\d+)'
        operator: '<='
        expected_value: 2000
        suggestion: 'Bundle exceeds 2MB - consider code splitting'

🤖 AI Task Validation

Verify AI completed the requested task correctly:

id: verify-feature-implementation
description: Ensure JWT auth was properly implemented
rule:
    type: for_each
    select:
        type: select_files
        path_pattern: 'src/auth/jwt.ts'
        select_all: true # Check current state
    assert:
        type: all_of
        rules:
            - type: assert_match
              pattern: 'jwt\.verify'
              message: 'JWT verification must be implemented'
            - type: assert_match
              pattern: 'RS256|ES256'
              message: 'Must use secure signing algorithm'

🎮 Usage

Validation Modes

# Default: Check only changed files (fast CI/CD)
codeguardian check

# Check everything including untracked files
codeguardian check --mode=all

# Pre-commit: Check only staged files
codeguardian check --mode=staged

Protection Levels

🛡️ Absolute Protection (select_all: true)

For critical rules that must ALWAYS pass:

# No package manager conflicts
type: for_each
select:
    type: select_files
    path_pattern: 'yarn.lock'
    select_all: true # Always check, regardless of changes
assert:
    type: assert_match
    pattern: '.*'
    should_match: false
    message: 'Project uses npm, not yarn'

📈 Progressive Protection (default)

For incremental improvements on changed code:

# Enforce naming on NEW files only
type: for_each
select:
    type: select_files
    path_pattern: '**/*.ts'
    status: ['added']
assert:
    type: assert_match
    pattern: '^[A-Z][a-zA-Z]+\.ts$'
    message: 'New files must use PascalCase'

🤝 AI Integration Workflow

When using AI coding assistants:

# 1. Include in your AI prompt:
"Run 'codeguardian check' after implementing features to ensure
architectural compliance. Fix any violations before completing."

# 2. AI-friendly output helps self-correction:
> codeguardian check
[FAIL] Domain cannot import infrastructure
  File: src/domain/user.ts:5
  Violation: import { PrismaClient } from '@prisma/client'
  Suggestion: Use repository interface instead

Claude Code Integration

Code Guardian provides seamless integration with Claude Code hooks for automatic validation. With the --claude-code-hook flag, violations trigger Claude to automatically fix issues before proceeding.

📖 See the complete Claude Code integration guide →

🧩 Rule Composition

Code Guardian uses simple primitives that compose into powerful rules:

• Selectors find what to check (files, lines, AST nodes)
• Assertions validate conditions (patterns, counts, properties)
• Combinators apply logic (for_each, all_of, any_of, none_of)

📖 Documentation

• Technical Guide - Detailed rule documentation
• Claude Code Integration - Automatic validation with Claude Code hooks
• Cheat Sheet - Complete syntax reference with examples
• Examples - Real-world rule configurations

Generate Rules with AI

Use our comprehensive cheat sheet to create custom rules:

Using the Code Guardian cheat sheet (https://raw.githubusercontent.com/diullei/codeguardian/refs/heads/main/Cheat_Sheet.md), create rules that:
- Prevent console.log in production
- Ensure all async functions have try-catch
- Block direct database access in controllers

For more sophisticated AI integration, check out our Claude command definitions that provide detailed prompts for rule creation and violation fixing.

🛠️ CLI Reference

codeguardian check [options]

Options:
  -c, --config   Rule files or pattern        [auto-discovers .cg.yaml]
  -e, --exclude  Exclude patterns             [array]
  -r, --repo     Repository path              [disables auto-discovery]
  -C             Change to directory first    [like git -C]
  -b, --base     Base branch                  [default: auto-detected]
  --head         Head branch/commit           [default: "HEAD"]
  -m, --mode     Validation scope             [diff|all|staged] [default: "diff"]
  -f, --format   Output format                [console|json] [default: "console"]
  --skip-missing-ast-grep  Skip AST rules if ast-grep not installed
  --claude-code-hook       Claude Code hook mode (exit 2 on errors, silent on success)

Repository Auto-Discovery

Code Guardian automatically finds your Git repository root when run from any subdirectory:

# Auto-discovers repository root from current directory
codeguardian check

# Change to directory first, then auto-discover
codeguardian check -C /path/to/project/src

# Use explicit repository path (no auto-discovery)
codeguardian check --repo /path/to/repo

🗺️ Project Status

⚠️ Beta Release: Code Guardian is under development. APIs may change between versions.

Current Features

• ✅ Core validati