codeguard

v2.0.0

Published

3 months ago

AI code reviewer that catches hallucinations and duplicates

0High
0Medium
0Low

code-review ai linter ast cli typescript javascript hallucination-detection duplicate-detection static-analysis code-quality

CodeGuard

AI code reviewer that catches hallucinations and duplicates in your codebase.

Features (Phase 1 MVP - COMPLETE ✅)

✅ Scan files for duplicate functions across entire codebase
✅ Detect hallucinated methods (React, Convex, and more)
✅ NPM package validation - validates against installed packages
✅ UI Library Detection - prevents custom styling when using component libraries
✅ Existing Code Detection - finds similar functionality already in your codebase
✅ Queue System - processes multiple file changes without dropping any
✅ Customizable Themes - 8 beautiful color schemes to choose from
✅ No Authentication Required - scan freely without sign-in
✅ Beautiful CLI with gradient banners and colored output
✅ TypeScript/JavaScript support via AST parsing
✅ Nested member expression detection (convex.db.delete())

Installation

npm install
npm run build
npm link

Now you can use codeguard from anywhere!

Usage

Scan a file

codeguard scan <file>

Example:

codeguard scan src/components/UserProfile.tsx
codeguard scan @file1.ts @file2.ts  # Multiple files with @ syntax

Watch mode (real-time scanning)

Auto Mode (default):

codeguard watch

Scans each file change immediately.

Manual Mode (reduces API calls):

codeguard watch --manual
# or
codeguard watch -m

Files changes are queued. Press SPACE to scan all changes at once. Perfect for reducing API calls when making many rapid changes!

Interactive command mode with slash commands

codeguard cmd
codeguard cmd --file src/app.ts  # Set context file

Initialize in a project

codeguard init

This creates a .codeguard.json config file.

Customize UI Theme

codeguard theme                 # View available themes
codeguard theme ocean           # Switch to ocean theme
codeguard theme cyberpunk       # Switch to cyberpunk theme

Available Themes:

default - Classic cyan and blue
ocean - Deep blue ocean vibes
forest - Natural green tones
sunset - Vibrant magenta and yellow
monochrome - Classic black and white
cyberpunk - Bright neon colors
dracula - Popular Dracula color scheme
nord - Arctic, north-bluish color palette

Your theme preference is saved to .codeguard.json and persists across sessions.

Slash Commands

CodeGuard includes powerful AI-powered slash commands for code analysis:

| Command | Aliases | Description | |---------|---------|-------------| | /help | /h, /? | Show available commands | | /explain <file> | /e | Explain code using AI | | /fix <file> | /f | Suggest fixes for code issues | | /review <file> | /r | Comprehensive code review | | /test <file> | /t | Generate test cases | | /refactor <file> | /rf | Get refactoring suggestions | | /docs <file> | /d | Generate documentation | | /security <file> | /sec | Security vulnerability scan | | /context <file> | /ctx | Set context file | | /exit | /quit, /q | Exit command mode |

Slash Commands Example

$ codeguard cmd --file src/app.ts
  > /explain
  # AI explains the code structure and logic

  > /fix
  # AI suggests specific fixes for detected issues

  > /test
  # AI generates comprehensive test cases

  > /security
  # AI performs security audit

  > /context src/utils.ts
  # Switch to different file

  > /review
  # Get full code review of src/utils.ts

Example Output

 ██████╗ ██████╗ ██████╗ ███████╗ ██████╗ ██╗   ██╗ █████╗ ██████╗ ██████╗ 
██╔════╝██╔═══██╗██╔══██╗██╔════╝██╔════╝ ██║   ██║██╔══██╗██╔══██╗██╔══██╗
██║     ██║   ██║██║  ██║█████╗  ██║  ███╗██║   ██║███████║██████╔╝██║  ██║
██║     ██║   ██║██║  ██║██╔══╝  ██║   ██║██║   ██║██╔══██║██╔══██╗██║  ██║
╚██████╗╚██████╔╝██████╔╝███████╗╚██████╔╝╚██████╔╝██║  ██║██║  ██║██████╔╝
 ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝ 
  AI-Powered Code Review • Catch hallucinations & duplicates

  ⚠️  DUPLICATES DETECTED
  Found 1 duplicate function(s)

  ╭─────────────────────────────────────────────
  │ ✗ validateEmail()
  │
  │ 📍 ./src/utils.ts:12
  │ 🔁 ./src/validators.ts:5
  ╰─────────────────────────────────────────────

  🚨 HALLUCINATIONS DETECTED
  Found 2 potential hallucination(s)

  ╭─────────────────────────────────────────────
  │ ✗ convex.db.delete() might not exist
  │
  │ 📍 ./src/api.ts:15
  │
  │ 💡 convex.db.delete() doesn't exist in convex. Valid methods: get, query, insert, patch, replace
  ╰─────────────────────────────────────────────

╭────────────────────────╮
│                        │
│   📊 SCAN COMPLETE     │
│                        │
│   Files scanned: 47    │
│   Issues found: 2      │
│                        │
│   ⚠️  Duplicates: 1    │
│   🚨 Hallucinations: 1 │
│                        │
╰────────────────────────╯

How It Works

1. AST Parsing

Uses Babel to parse JavaScript/TypeScript files into an Abstract Syntax Tree, extracting:

Function declarations
Arrow functions
Class methods
Method calls (including nested like convex.db.delete())

2. Duplicate Detection

Scans your entire codebase to find functions with the same name across different files.

3. NPM Package Validation

Reads your package.json to get installed dependencies
Validates method calls against known package APIs
Currently supports: React, Convex, and common JS built-ins
Extensible to add custom package validation

4. Hallucination Detection

Catches common AI hallucinations like:

React.useHook() → Should use specific hooks
Array.remove() → Use splice() or filter()
convex.db.delete() → Use ctx.db.delete() in mutations
And more...

5. Existing Code Detection

Analyzes new functions and finds similar functionality already in your codebase:

Detection Methods:

Function name similarity using Levenshtein distance
Common operation prefixes (get, fetch, validate, format, etc.)
Keyword extraction from function bodies (API calls, validation, formatting, etc.)
Pattern matching for common operations

What It Finds:

High similarity - Functions you can directly reuse
Medium similarity - Functions with similar patterns worth checking
Low similarity - Related functionality that might have useful code

Example Output:

💡 EXISTING CODE DETECTED
Found 2 function(s) with similar existing code

1. validateUserEmail() at NewComponent.tsx:45
   ⚠️  Can reuse existing code:
   → validateEmail() in utils/validation.ts:23
     HIGH - similar function name, performs similar operations (validate, email)
   💡 Consider reusing 'validateEmail' from validation.ts:23 instead of creating 'validateUserEmail'

2. fetchUserData() at Dashboard.tsx:112
   Similar patterns found (might be useful):
   → getUserProfile() in api/users.ts:67
     both fetch similar data, shares some functionality (fetch, user)
   💡 Check 'getUserProfile' in users.ts:67 - it might have useful patterns for 'fetchUserData'

Why This Matters:

Prevents Code Duplication - Reuse instead of recreate
Maintains Consistency - Use existing patterns
Saves Time - Don't reinvent what exists
Easier Maintenance - Fewer places to update

6. Queue System for File Changes

When multiple files change rapidly (e.g., during git checkout or bulk edits):

Queues all changes instead of dropping them
Processes sequentially to avoid race conditions
Shows queue status in the output
Never misses a file even during rapid changes

Example:

⚡ CHANGE DETECTED [3 in queue]
Time: 10:30:45 AM
File: src/components/Button.tsx

# ... scan results ...

⏱  Scanned in 850ms (2 more in queue)
👀 Watching for changes...

7. UI Library Detection

Automatically detects UI component libraries and warns when you add custom styling that conflicts with their theming systems:

Supported Libraries:

Hero UI / NextUI
shadcn/ui
Material-UI (MUI)
Chakra UI
Ant Design
Mantine
DaisyUI

What It Detects:

Custom Tailwind colors using hex values: bg-[#ff0000]
Inline styles with custom colors: style={{ color: '#ff0000' }}
CSS rules with custom hex colors
Arbitrary Tailwind values that bypass theme tokens

Why This Matters: When using component libraries with theming systems, adding custom colors and styles:

Breaks consistency with the design system
Makes theme switching (dark mode, etc.) harder
Bypasses the library's built-in accessibility features
Creates maintenance issues when updating the theme

Example Output:

⚠️  UI LIBRARY STYLING ISSUES
Found 3 styling issue(s)

1. Component.tsx: Found 2 custom color(s) using Tailwind hex values. Use shadcn's theme tokens instead.
2. Button.tsx: Found 1 inline style(s) with custom colors. Use shadcn's theming system instead.
3. Card.tsx: Found 3 CSS rule(s) with custom hex colors. Use shadcn's theme configuration instead.

What's Hooked Up

✅ NPM Integration

Fetches package metadata from npm registry
Validates against installed package versions
Caches results for performance

🚧 Not Yet Hooked Up

GitHub API (for issue tracking)
Full TypeScript definitions parsing
Pattern learning from codebase
Auto-fix suggestions

What's Next (Phase 2)

GitHub Action integration
GitHub issues integration (learn anti-patterns from issues)
Pattern detection (how your team does auth, DB calls, etc.)
VS Code extension
Web dashboard
More package support

Development

# Install dependencies
npm install

# Build
npm run build

# Link globally
npm link

# Run
codeguard scan <file>

# Test
codeguard scan test/sample.ts
codeguard scan test/hallucination-test.ts

Architecture

src/
├── cli.ts                       # CLI entry point with commander
├── parser.ts                    # AST parsing with Babel
├── detector.ts                  # Duplicate function detection
├── hallucination.ts             # Hallucination checking logic
├── package-validator.ts         # NPM package validation
├── npm-registry.ts              # NPM registry API client
├── ui-library-detector.ts       # UI library detection & styling validation
├── existing-code-detector.ts    # Find similar existing functionality
├── watcher.ts                   # File watcher with queue system
└── output.ts                    # Fancy terminal output formatting

License

MIT