@cci-petri/validation-agent

Validation Agent

A TypeScript CLI tool that reviews git diffs against cursor rules using Claude Code SDK.

Features

• 🔍 Review git commits or unstaged changes against cursor rules
• 📋 Auto-detects and combines ALL cursor rules from .cursorrules or .cursor/rules/*.mdc
• 🤖 Uses Claude Code SDK with file system access for intelligent rule analysis
• 📊 Provides detailed violations with confidence scores, rule sources, and line numbers
• 🔗 Can analyze imported files for comprehensive rule compliance checking
• ⚡ Shows only changed lines (git diff -U0) for focused analysis
• 🚀 Compare feature branches against main/master for CI/CD pipelines
• 📈 Summary table showing pass/fail status and violation counts per file
• 🚫 Auto-excludes generated files (lock files, dist/, node_modules/, etc.)
• 🎬 Real-time streaming with progress indicators during analysis
• 🎯 Focuses on added code only - ignores removed code and cursor rules files
• ❌ Exits with error code 1 when violations found (perfect for CI/CD pipelines)
• 🎯 Strictly enforces only your defined cursor rules (no made-up rules)

Installation

From npm (Recommended)

# Install globally
npm install -g @cci-petri/validation-agent

# Or use with npx (no installation required)
npx @cci-petri/validation-agent rule-review --help

From Source

• Clone and install dependencies:

git clone [e-mail]:circleci-petri/validation-agent.git
cd validation-agent
npm install

• Set up environment variables:

cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

• Build the project:

npm run build

Usage

Basic Commands

# Review latest commit against auto-detected rules
rule-review rule-review

# Review specific file in latest commit
rule-review rule-review --file src/index.ts

# Review unstaged changes
rule-review rule-review --commit unstaged

# Use custom rules file
rule-review rule-review --rules .cursor/rules/typescript.mdc

# Combine options: review specific file in unstaged changes
rule-review rule-review -f src/utils/git.ts -c unstaged

# Review specific commit by hash
rule-review rule-review -c abc1234

# Review with custom rules and specific file
rule-review rule-review -r my-rules.md -f src/index.ts

CI/CD & Branch Comparison

# Compare current feature branch against main (typical CI/CD usage)
rule-review rule-review -b main

# Compare feature branch against master
rule-review rule-review -b master

# Compare specific commit against main
rule-review rule-review -c HEAD -b main

# Compare feature branch against develop
rule-review rule-review -b develop

# Review specific file changes from feature branch vs main
rule-review rule-review -f src/index.ts -b main

Using with npx

# No installation required - run directly
npx @cci-petri/validation-agent rule-review

# Review unstaged changes
npx @cci-petri/validation-agent rule-review -c unstaged

# Review specific file
npx @cci-petri/validation-agent rule-review -f src/index.ts

Command Line Options

Flag	Long Form	Argument	Description
-f	--file	<file>	Specific file to review (filters diff to single file)
-c	--commit	<commit>	Git commit/reference to review (default: HEAD)
-r	--rules	<rules>	Custom path to cursor rules file
-b	--base-branch	<branch>	NEW: Base branch to compare against (e.g., main, master)
-h	--help	-	Display help information
-V	--version	-	Display version number

Special Commit Values

• HEAD (default) - Review the latest commit
• unstaged - Review uncommitted changes in working directory
• <commit-hash> - Review specific commit by hash
• <branch-name> - Review latest commit on specified branch

Understanding -c vs -b Flags

-c (commit): Specifies which commit to analyze -b (base-branch): Specifies what to compare against

Examples:

• rule-review rule-review -c HEAD → Compare HEAD~1 to HEAD (single commit)
• rule-review rule-review -b main → Compare main...HEAD (feature branch changes)
• rule-review rule-review -c HEAD -b main → Compare main...HEAD (same as above)
• rule-review rule-review -c abc123 -b main → Compare main...abc123

For CI/CD: Use -b main to review all changes in your feature branch.

Cursor Rules Detection

The tool automatically detects and combines cursor rules from:

• .cursorrules (traditional format)
• .cursor/rules/*.mdc (new Cursor IDE format - ALL .mdc files are loaded and combined)
• Custom path via -r option

When multiple .mdc files exist in .cursor/rules/, they are all loaded and combined with clear section headers showing which rule comes from which file.

Auto-Excluded Files

The tool automatically excludes these files from analysis:

• Lock files: yarn.lock, package-lock.json, pnpm-lock.yaml, Cargo.lock, etc.
• Generated files: .min.js, .min.css, dist/, build/, node_modules/*
• Cursor rules files: .cursorrules, .cursor/rules/*.mdc
• Other: Gemfile.lock, composer.lock, poetry.lock, Pipfile.lock, go.sum

Analysis Focus

The tool focuses on added code only:

• ✅ Analyzes lines starting with + in git diff (newly added code)
• ❌ Ignores lines starting with - in git diff (removed code)
• 🎯 Only reports violations in code being added to the codebase

Environment Variables

Required:

• ANTHROPIC_API_KEY - Your Anthropic API key

Optional:

• CLAUDE_MODEL - Claude model to use (default: claude-sonnet-4-20250514)
• ANTHROPIC_BASE_URL - API base URL (default: https://api.anthropic.com)

Development

# Run in development mode
npm run dev

# Build TypeScript
npm run build

# Run built version
npm start

Example Output

🔍 Starting rule review...
📋 Loaded rules from: .cursor/rules/ (3 files: general.mdc, typescript.mdc, react-hooks.mdc)

=== CURSOR RULES LOADED ===
Rules length: 2456 characters
Rule files: general.mdc, typescript.mdc, react-hooks.mdc

📄 Analyzing changes from main to HEAD
📊 Found 2 file(s) with changes

🔎 Analyzing 1/2: src/components/Button.tsx

🤖 Claude is analyzing...
📝 Analysis in progress...
🔍 Checking for rule violations...
💡 Generating suggestions...
📋 Preparing summary...
✅ Analysis complete!

📋 Results for src/components/Button.tsx:
❌ Rule Violations:
   1. Rule: No useState in components
      Rule Source: react-hooks.mdc
      Reason: Component uses useState hook directly
      Confidence: 9/10
      File: src/components/Button.tsx:15
      Code: const [state, setState] = useState();

💡 Suggestions:
   1. Move state logic to a custom hook
   2. Use useReducer for complex state management

📝 Summary: Component violates React hooks usage patterns defined in cursor rules
🔍 Imported files checked: src/hooks/useCustomHook.ts

🔎 Analyzing 2/2: src/utils/helpers.ts

🤖 Claude is analyzing...
📝 Analysis in progress...
✅ Analysis complete!

📋 Results for src/utils/helpers.ts:
✅ No issues found

📊 SUMMARY TABLE
┌─────────────────────────────────────────────────────────────────┬────────┬────────────┐
│ File                                                            │ Status │ Violations │
├─────────────────────────────────────────────────────────────────┼────────┼────────────┤
│ src/components/Button.tsx                                       │ ❌ FAIL │          1 │
│ src/utils/helpers.ts                                            │ ✅ PASS │          0 │
└─────────────────────────────────────────────────────────────────┴────────┴────────────┘

📈 Overall: 1 passed, 1 failed, 1 total violations

❌ Rule review completed with 1 violation(s) found!

CI/CD Integration

The tool exits with code 1 when violations are found, making it perfect for CI/CD pipelines:

# Compare feature branch against main (recommended for CI/CD)
npx @cci-petri/validation-agent rule-review -b main

# GitHub Actions example
npx @cci-petri/validation-agent rule-review -b main
# Job will fail if violations are found

# GitLab CI example
npx @cci-petri/validation-agent rule-review -b master

# For specific commits
npx @cci-petri/validation-agent rule-review -c $GITHUB_SHA -b main

Help Output

$ rule-review rule-review --help
Usage: rule-review rule-review [options]

Review git diffs against cursor rules

Options:
  -f, --file <file>          Specific file to review
  -c, --commit <commit>      Specific commit to review (default: HEAD)
  -r, --rules <rules>        Path to cursor rules file (default: .cursorrules)
  -b, --base-branch <branch> Base branch to compare against (e.g., main, master)
  -h, --help                 display help for command