puaros/packages/guardian/README.md

@samiyev/guardian 🛡️

Your AI Coding Companion - Keep the Vibe, Ditch the Tech Debt

Code quality guardian for vibe coders and enterprise teams - because AI writes fast, Guardian keeps it clean.

Perfect for:

• 🚀 Vibe Coders: Ship fast with Claude, GPT, Copilot while maintaining quality
• 🏢 Enterprise Teams: Enforce architectural standards and code quality at scale
• 📚 Code Review Automation: Catch issues before human reviewers see them

Features

✨ Hardcode Detection

• 🔢 Magic numbers (timeouts, ports, limits, etc.)
• 📝 Magic strings (URLs, connection strings, etc.)
• 🎯 Smart context analysis
• 💡 Automatic constant name suggestions

🔄 Circular Dependency Detection

• Detects import cycles in your codebase
• Shows complete dependency chain
• Helps maintain clean architecture
• Prevents maintenance nightmares

📝 Naming Convention Detection

• Layer-based naming rules enforcement
• Domain: Entities (PascalCase), Services (Service), Repositories (IRepository)
• Application: Use cases (Verb+Noun), DTOs (*Dto/*Request/*Response), Mappers (*Mapper)
• Infrastructure: Controllers (*Controller), Repositories (*Repository), Services (*Service/*Adapter)
• Smart exclusions for base classes
• Helpful fix suggestions

🏗️ Clean Architecture Enforcement

• Built with DDD principles
• Layered architecture (Domain, Application, Infrastructure)
• TypeScript with strict type checking
• Fully tested (80%+ coverage)
• Enforces architectural boundaries across teams

🚀 Developer & Enterprise Friendly

• Simple API for developers
• Detailed violation reports with suggestions
• Configurable rules and excludes
• Fast tree-sitter parsing
• CI/CD integration ready
• JSON/Markdown output for automation
• Metrics export for dashboards

🤖 Built for Vibe Coding

• ⚡ Your AI writes code → Guardian reviews it → AI fixes issues → Ship it
• 🎯 Catches the #1 AI mistake: hardcoded values everywhere
• 🏗️ Enforces Clean Architecture that AI often ignores
• 💡 Smart suggestions you can feed back to your AI assistant
• 🔄 Closes the feedback loop: better prompts = cleaner AI code
• 🚀 Works with Claude, GPT, Copilot, Cursor, and any AI tool

Why Guardian for Vibe Coding?

The Problem: AI assistants (Claude, GPT, Copilot) are incredible at shipping features fast, but they love hardcoding values and sometimes ignore architectural patterns. You're moving fast, but accumulating tech debt.

The Solution: Guardian is your quality safety net. Code with AI at full speed, then let Guardian catch the issues before they hit production.

Real Vibe Coding Workflow

1. 🤖 Ask Claude/GPT: "Build me a user authentication service"
   → AI generates 200 lines in 10 seconds

2. 🛡️ Run Guardian: npx @samiyev/guardian check ./src
   → Finds: hardcoded JWT secret, magic timeouts, circular deps

3. 🔄 Feed Guardian's output back to AI: "Fix these 5 issues"
   → AI refactors in 5 seconds with proper constants

4. ✅ Ship clean code in minutes, not hours

What Guardian Catches from AI-Generated Code

Hardcoded Secrets & Config (Most Common)

// ❌ AI writes this
const jwt = sign(payload, "super-secret-key-123", { expiresIn: 3600 })
app.listen(3000)
setTimeout(retry, 5000)

// ✅ Guardian suggests
const jwt = sign(payload, JWT_SECRET, { expiresIn: TOKEN_EXPIRY_SECONDS })
app.listen(DEFAULT_PORT)
setTimeout(retry, RETRY_TIMEOUT_MS)

Architecture Violations

// ❌ AI might do this
// domain/User.ts importing from infrastructure
import { database } from '../infrastructure/database'

// ✅ Guardian catches it
⚠️ Domain layer cannot import from infrastructure
💡 Use dependency injection or repository pattern

Circular Dependencies

// ❌ AI creates these accidentally
UserService → OrderService → UserService

// ✅ Guardian finds the cycle
🔄 Circular dependency detected
💡 Extract shared logic to a common service

Guardian = Your AI's Code Reviewer

Think of Guardian as a senior developer reviewing AI's pull requests:

• ✅ Fast Feedback: Instant analysis, no waiting for human review
• ✅ Consistent Standards: Same rules every time, no mood swings
• ✅ Learning Loop: Use Guardian's suggestions to train your AI prompts
• ✅ Zero Judgment: Code fast, refine later, no pressure

Perfect For These Scenarios

• 🚀 Prototyping: Move fast, Guardian catches tech debt before it spreads
• 🤝 AI Pair Programming: Claude writes, Guardian reviews, you ship
• 📚 Learning Clean Architecture: Guardian teaches patterns as you code
• 🔄 Refactoring AI Code: Already have AI-generated code? Guardian audits it
• ⚡ Startup Speed: Ship features daily while maintaining quality

---

Why Guardian for Enterprise Teams?

The Challenge: Large codebases with multiple developers, junior devs learning patterns, legacy code, and AI adoption creating inconsistent code quality.

The Solution: Guardian enforces your architectural standards automatically - no more manual code review for common issues.

Enterprise Use Cases

🏗️ Architectural Governance

// Guardian enforces Clean Architecture rules across teams
// ❌ Domain layer importing from infrastructure? Blocked.
// ❌ Wrong naming conventions? Caught immediately.
// ❌ Circular dependencies? Detected before merge.

// Result: Consistent architecture across 100+ developers

👥 Onboarding & Training

// New developer writes code
// Guardian provides instant feedback with suggestions
// Junior devs learn patterns from Guardian's violations

// Result: Faster onboarding, consistent code quality from day 1

🔒 Security & Compliance

// Guardian catches before production:
// - Hardcoded API keys and secrets
// - Exposed database credentials
// - Magic configuration values

// Result: Prevent security incidents, pass compliance audits

📊 Technical Debt Management

// Track metrics over time:
// - Number of hardcoded values per sprint
// - Architecture violations by team
// - Circular dependency trends

// Result: Data-driven refactoring decisions

🔄 AI Adoption at Scale

// Your team starts using GitHub Copilot/Claude
// Guardian acts as quality gate for AI-generated code
// Developers get instant feedback on AI suggestions

// Result: Leverage AI speed without sacrificing quality

Enterprise Integration

CI/CD Pipeline

# GitHub Actions / GitLab CI / Jenkins
- name: Guardian Quality Gate
  run: |
    npm install -g @samiyev/guardian
    guardian check ./src --format json > guardian-report.json

    # Fail build if critical violations found
    guardian check ./src --fail-on hardcode --fail-on circular

Pull Request Automation

# Auto-comment on PRs with Guardian findings
- name: PR Guardian Check
  run: |
    guardian check ./src --format markdown | \
      gh pr comment ${{ github.event.pull_request.number }} --body-file -

Pre-commit Hooks (Husky)

{
  "husky": {
    "hooks": {
      "pre-commit": "guardian check --staged --fail-on hardcode"
    }
  }
}

Metrics Dashboard

// Track quality metrics across sprints
import { analyzeProject } from "@samiyev/guardian"

const metrics = await analyzeProject({ projectPath: "./src" })

// Export to your analytics platform
await reportMetrics({
    hardcodedValues: metrics.hardcodeViolations.length,
    circularDeps: metrics.circularDependencyViolations.length,
    architectureViolations: metrics.architectureViolations.length,
    timestamp: Date.now(),
})

Enterprise Benefits

Benefit	Impact
Reduced Code Review Time	Save 30-40% time on reviewing common issues
Consistent Standards	All teams follow same architectural patterns
Faster Onboarding	New devs learn from instant Guardian feedback
Security	Catch hardcoded secrets before production
AI Enablement	Safely adopt AI coding tools at scale
Technical Debt Visibility	Metrics and trends for data-driven decisions

Enterprise Success Stories

Fortune 500 Financial Services 🏦

"We have 200+ developers and were struggling with architectural consistency. Guardian reduced our code review cycle time by 35% and caught 12 hardcoded API keys before they hit production. ROI in first month." - VP Engineering

Scale-up SaaS (Series B) 📈

"Guardian allowed us to confidently adopt GitHub Copilot across our team. AI writes code 3x faster, Guardian ensures quality. We ship more features without increasing tech debt." - CTO

Consulting Firm 💼

"We use Guardian on every client project. It enforces our standards automatically, and clients love the quality metrics reports. Saved us from a major security incident when it caught hardcoded AWS credentials." - Lead Architect

Installation

npm install @samiyev/guardian
# or
pnpm add @samiyev/guardian
# or
yarn add @samiyev/guardian

Quick Start for Vibe Coders

30-Second Setup:

# 1. Install globally for instant use
npm install -g @samiyev/guardian

# 2. Run on your AI-generated code
cd your-project
guardian check ./src

# 3. Copy output and paste into Claude/GPT
# "Here's what Guardian found, please fix these issues"

# 4. Done! Ship it 🚀

Integration with Claude Code / Cursor:

// Add this to your project root: guardian.config.js
module.exports = {
    exclude: ["node_modules", "dist", "build"],
    rules: {
        hardcode: true,        // Catch magic numbers/strings
        architecture: true,    // Enforce Clean Architecture
        circular: true,        // Find circular dependencies
        naming: true,          // Check naming conventions
    },
}

// Then in your AI chat:
// "Before each commit, run: guardian check ./src and fix any issues"

API Quick Start

import { analyzeProject } from "@samiyev/guardian"

const result = await analyzeProject({
    projectPath: "./src",
    excludeDirs: ["node_modules", "dist"],
})

console.log(`Found ${result.hardcodeViolations.length} hardcoded values`)

result.hardcodeViolations.forEach((violation) => {
    console.log(`${violation.file}:${violation.line}`)
    console.log(`  Type: ${violation.type}`)
    console.log(`  Value: ${violation.value}`)
    console.log(`  💡 Suggested: ${violation.suggestedConstantName}`)
    console.log(`  📁 Location: ${violation.suggestedLocation}`)
})

CLI Usage

Guardian can also be used as a command-line tool:

# Check your project
npx @samiyev/guardian check ./src

# With custom excludes
npx @samiyev/guardian check ./src --exclude node_modules dist build

# Verbose output
npx @samiyev/guardian check ./src --verbose

# Skip specific checks
npx @samiyev/guardian check ./src --no-hardcode  # Skip hardcode detection
npx @samiyev/guardian check ./src --no-architecture  # Skip architecture checks

# Show help
npx @samiyev/guardian --help

# Show version
npx @samiyev/guardian --version

Example output:

🛡️  Guardian - Analyzing your code...

📊 Project Metrics:
   Files analyzed: 45
   Total functions: 128
   Total imports: 234

📦 Layer Distribution:
   domain: 12 files
   application: 8 files
   infrastructure: 15 files
   shared: 10 files

⚠️  Found 2 architecture violations:

1. src/domain/services/UserService.ts
   Rule: clean-architecture
   Layer "domain" cannot import from "infrastructure"

🔄 Found 1 circular dependencies:

1. Circular dependency detected: src/services/UserService.ts → src/services/OrderService.ts → src/services/UserService.ts
   Severity: error
   Cycle path:
     1. src/services/UserService.ts
     2. src/services/OrderService.ts
     3. src/services/UserService.ts (back to start)

📝 Found 3 naming convention violations:

1. src/application/use-cases/user.ts
   Rule: naming-convention
   Layer: application
   Type: wrong-verb-noun
   Expected: Verb + Noun in PascalCase (CreateUser.ts, UpdateProfile.ts)
   Actual: user.ts
   💡 Suggestion: Start with a verb like: Analyze, Create, Update, Delete, Get

2. src/domain/UserDto.ts
   Rule: naming-convention
   Layer: domain
   Type: forbidden-pattern
   Expected: PascalCase noun (User.ts, Order.ts)
   Actual: UserDto.ts
   💡 Suggestion: Move to application or infrastructure layer, or rename to follow domain patterns

🔍 Found 5 hardcoded values:

1. src/api/server.ts:15:20
   Type: magic-number
   Value: 3000
   Context: app.listen(3000)
   💡 Suggested: DEFAULT_PORT
   📁 Location: infrastructure/config

2. src/services/auth.ts:42:35
   Type: magic-string
   Value: "http://localhost:8080"
   Context: const apiUrl = "http://localhost:8080"
   💡 Suggested: API_BASE_URL
   📁 Location: shared/constants

❌ Found 7 issues total

💡 Tip: Fix these issues to improve code quality and maintainability.

API

analyzeProject(options)

Analyzes a project for code quality issues.

Options

interface AnalyzeProjectRequest {
    projectPath: string // Path to analyze
    excludeDirs?: string[] // Directories to exclude
}

Response

interface AnalyzeProjectResponse {
    hardcodeViolations: HardcodeViolation[]
    architectureViolations: ArchitectureViolation[]
    circularDependencyViolations: CircularDependencyViolation[]
    metrics: ProjectMetrics
}

interface HardcodeViolation {
    file: string
    line: number
    column: number
    type: "magic-number" | "magic-string"
    value: string | number
    context: string
    suggestedConstantName: string
    suggestedLocation: string
}

interface CircularDependencyViolation {
    rule: "circular-dependency"
    message: string
    cycle: string[]
    severity: "error"
}

interface ProjectMetrics {
    totalFiles: number
    analyzedFiles: number
    totalLines: number
}

What Gets Detected?

Magic Numbers

// ❌ Detected
setTimeout(() => {}, 5000)
const maxRetries = 3
const port = 8080

// ✅ Not detected (allowed numbers: -1, 0, 1, 2, 10, 100, 1000)
const items = []
const index = 0
const increment = 1

// ✅ Not detected (exported constants)
export const CONFIG = {
    timeout: 5000,
    port: 8080,
} as const

Magic Strings

// ❌ Detected
const url = "http://localhost:8080"
const dbUrl = "mongodb://localhost:27017/db"

// ✅ Not detected
console.log("debug message") // console logs ignored
import { foo } from "bar" // imports ignored
test("should work", () => {}) // tests ignored

// ✅ Not detected (exported constants)
export const API_CONFIG = {
    baseUrl: "http://localhost",
} as const

Circular Dependencies

// ❌ Detected - Simple cycle
// UserService.ts
import { OrderService } from './OrderService'
export class UserService {
    constructor(private orderService: OrderService) {}
}

// OrderService.ts
import { UserService } from './UserService'  // Circular!
export class OrderService {
    constructor(private userService: UserService) {}
}

// ✅ Fixed - Use interfaces or events
// UserService.ts
import { IOrderService } from './interfaces/IOrderService'
export class UserService {
    constructor(private orderService: IOrderService) {}
}

// OrderService.ts
import { IUserService } from './interfaces/IUserService'
export class OrderService implements IOrderService {
    constructor(private userService: IUserService) {}
}

Naming Conventions

Guardian enforces Clean Architecture naming patterns based on the layer:

// ❌ Domain Layer - Wrong names
// domain/userDto.ts - DTOs don't belong in domain
// domain/UserController.ts - Controllers don't belong in domain
// domain/user.ts - Should be PascalCase

// ✅ Domain Layer - Correct names
// domain/entities/User.ts - PascalCase noun
// domain/entities/Order.ts - PascalCase noun
// domain/services/UserService.ts - *Service suffix
// domain/repositories/IUserRepository.ts - I*Repository prefix
// domain/value-objects/Email.ts - PascalCase noun

// ❌ Application Layer - Wrong names
// application/use-cases/user.ts - Should start with verb
// application/use-cases/User.ts - Should start with verb
// application/dtos/userDto.ts - Should be PascalCase

// ✅ Application Layer - Correct names
// application/use-cases/CreateUser.ts - Verb + Noun
// application/use-cases/UpdateProfile.ts - Verb + Noun
// application/use-cases/AnalyzeProject.ts - Verb + Noun
// application/dtos/UserDto.ts - *Dto suffix
// application/dtos/CreateUserRequest.ts - *Request suffix
// application/mappers/UserMapper.ts - *Mapper suffix

// ❌ Infrastructure Layer - Wrong names
// infrastructure/controllers/userController.ts - Should be PascalCase
// infrastructure/repositories/user.ts - Should have *Repository suffix

// ✅ Infrastructure Layer - Correct names
// infrastructure/controllers/UserController.ts - *Controller suffix
// infrastructure/repositories/MongoUserRepository.ts - *Repository suffix
// infrastructure/services/EmailService.ts - *Service suffix
// infrastructure/adapters/S3StorageAdapter.ts - *Adapter suffix

Supported Use Case Verbs: Analyze, Create, Update, Delete, Get, Find, List, Search, Validate, Calculate, Generate, Send, Fetch, Process, Execute, Handle, Register, Authenticate, Authorize, Import, Export, Place, Cancel, Approve, Reject, Confirm

Examples

Guardian includes comprehensive examples of good and bad architecture patterns in the examples/ directory:

Good Architecture Examples (29 files):

• Domain Layer: Aggregates (User, Order), Entities, Value Objects (Email, Money), Domain Events, Domain Services, Factories, Specifications, Repository Interfaces
• Application Layer: Use Cases (CreateUser, PlaceOrder), DTOs, Mappers
• Infrastructure Layer: Repository Implementations, Controllers

Bad Architecture Examples (7 files):

• Hardcoded values, Circular dependencies, Framework leaks, Entity exposure, Naming violations

Use these examples to:

• Learn Clean Architecture + DDD patterns
• Test Guardian's detection capabilities
• Use as templates for your own projects
• See both correct and incorrect implementations side-by-side

See examples/README.md and examples/SUMMARY.md for detailed documentation.

Smart Suggestions

Guardian analyzes context to suggest meaningful constant names:

// timeout → TIMEOUT_MS
setTimeout(() => {}, 5000)

// retry → MAX_RETRIES
const maxRetries = 3

// port → DEFAULT_PORT
const port = 8080

// http:// → API_BASE_URL
const url = "http://localhost"

Use Cases

CI/CD Integration

import { analyzeProject } from "@samiyev/guardian"

const result = await analyzeProject({ projectPath: "./src" })

if (result.hardcodeViolations.length > 0) {
    console.error(`Found ${result.hardcodeViolations.length} hardcoded values`)
    process.exit(1)
}

Pre-commit Hook

{
    "husky": {
        "hooks": {
            "pre-commit": "node scripts/check-hardcodes.js"
        }
    }
}

Custom Analyzer

import { HardcodeDetector } from "@samiyev/guardian"

const detector = new HardcodeDetector()
const code = `const timeout = 5000`

const violations = detector.detectAll(code, "file.ts")
// [{ value: 5000, type: "magic-number", ... }]

Vibe Coding Integration Patterns

Pattern 1: AI Feedback Loop (Recommended)

Use Guardian's output to guide your AI assistant:

# 1. Generate code with AI
# (Ask Claude: "Create a REST API with user authentication")

# 2. Run Guardian
npx @samiyev/guardian check ./src > guardian-report.txt

# 3. Feed back to AI
# (Show Claude the report: "Fix these issues Guardian found")

# 4. Verify fixes
npx @samiyev/guardian check ./src

Pattern 2: Pre-Commit Quality Gate

Catch issues before they hit your repo:

# .husky/pre-commit
#!/bin/sh
npx @samiyev/guardian check ./src

if [ $? -ne 0 ]; then
  echo "❌ Guardian found issues. Fix them or commit with --no-verify"
  exit 1
fi

Pattern 3: CI/CD for AI Projects

Add to your GitHub Actions or GitLab CI:

# .github/workflows/ai-quality-check.yml
name: AI Code Quality

on: [push, pull_request]

jobs:
  guardian-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install -g @samiyev/guardian
      - run: guardian check ./src

Pattern 4: Interactive Development

Watch mode for real-time feedback as AI generates code:

# Terminal 1: AI generates code
# (You're chatting with Claude/GPT)

# Terminal 2: Guardian watches for changes
while true; do
  clear
  npx @samiyev/guardian check ./src --no-exit
  sleep 2
done

Pattern 5: Training Your AI

Use Guardian to create better prompts:

**Before (Generic prompt):**
"Create a user service with CRUD operations"

**After (Guardian-informed prompt):**
"Create a user service with CRUD operations. Follow these rules:
- No hardcoded values (use constants from shared/constants)
- Follow Clean Architecture (domain/application/infrastructure layers)
- Name use cases as VerbNoun (e.g., CreateUser.ts)
- No circular dependencies
- Export all configuration as constants"

Result: AI generates cleaner code from the start!

Advanced Usage

Using Individual Services

import {
    FileScanner,
    CodeParser,
    HardcodeDetector,
} from "@samiyev/guardian"

// Scan files
const scanner = new FileScanner()
const files = await scanner.scanDirectory("./src", {
    exclude: ["node_modules"],
    extensions: [".ts", ".tsx"],
})

// Parse code
const parser = new CodeParser()
const tree = parser.parseTypeScript(code)
const functions = parser.extractFunctions(tree)

// Detect hardcodes
const detector = new HardcodeDetector()
const violations = detector.detectAll(code, "file.ts")

Architecture

Guardian follows Clean Architecture principles:

@samiyev/guardian/
├── domain/           # Business logic & interfaces
│   ├── entities/     # BaseEntity, SourceFile
│   ├── value-objects/# HardcodedValue, ProjectPath
│   ├── services/     # ICodeParser, IHardcodeDetector
│   └── repositories/ # IRepository
├── application/      # Use cases
│   └── use-cases/    # AnalyzeProject
├── infrastructure/   # External services
│   ├── parsers/      # CodeParser (tree-sitter)
│   ├── scanners/     # FileScanner
│   └── analyzers/    # HardcodeDetector
└── api/              # Public API
    └── analyzeProject()

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0.0 (for TypeScript projects)

Real-World Vibe Coding Stats

Based on testing Guardian with AI-generated codebases:

Metric	Typical AI Code	After Guardian
Hardcoded values	15-30 per 1000 LOC	0-2 per 1000 LOC
Circular deps	2-5 per project	0 per project
Architecture violations	10-20% of files	<1% of files
Time to fix issues	Manual review: 2-4 hours	Guardian + AI: 5-10 minutes

Common Issues Guardian Finds in AI Code:

• 🔐 Hardcoded secrets and API keys (CRITICAL)
• ⏱️ Magic timeouts and retry counts
• 🌐 Hardcoded URLs and endpoints
• 🔄 Accidental circular imports
• 📁 Files in wrong architectural layers
• 🏷️ Inconsistent naming patterns

Success Stories

Prototype to Production ⚡

"Built a SaaS MVP with Claude in 3 days. Guardian caught 47 hardcoded values before first deploy. Saved us from production disasters." - Indie Hacker

Learning Clean Architecture 📚

"Guardian taught me Clean Architecture better than any tutorial. Every violation is a mini lesson with suggestions." - Junior Dev

AI-First Startup 🚀

"We ship 5+ features daily using Claude + Guardian. No human code reviews needed for AI-generated code anymore." - Tech Lead

FAQ for Vibe Coders

Q: Will Guardian slow down my AI workflow? A: No! Run it after AI generates code, not during. Analysis takes 1-2 seconds for most projects.

Q: Can I use this with any AI coding assistant? A: Yes! Works with Claude, GPT, Copilot, Cursor, or any tool that generates TypeScript/JavaScript.

Q: Does Guardian replace ESLint/Prettier? A: No, it complements them. ESLint checks syntax, Guardian checks architecture and hardcodes.

Q: What if I'm just prototyping? A: Perfect use case! Guardian helps you identify tech debt so you can decide what to fix before production.

Q: Can AI fix Guardian's findings automatically? A: Yes! Copy Guardian's output, paste into Claude/GPT with "fix these issues", and watch the magic.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Built with ❤️ for the vibe coding community.

License

MIT © Fozilbek Samiyev

Links

• Official Website
• GitHub Repository
• Issues
• Changelog