feat(guardian): add guardian package - code quality analyzer

Add @puaros/guardian package v0.1.0 - code quality guardian for vibe coders and enterprise teams.

Features:
- Hardcode detection (magic numbers, magic strings)
- Circular dependency detection
- Naming convention enforcement (Clean Architecture)
- Architecture violation detection
- CLI tool with comprehensive reporting
- 159 tests with 80%+ coverage
- Smart suggestions for fixes
- Built for AI-assisted development

Built with Clean Architecture and DDD principles.
Works with Claude, GPT, Copilot, Cursor, and any AI coding assistant.

packages/guardian/examples/good-architecture/domain/services/PricingService.ts

@@ -0,0 +1,80 @@
+import { Order } from "../aggregates/Order"
+import { Money } from "../value-objects/Money"
+
+/**
+ * Domain Service: PricingService
+ *
+ * DDD Pattern: Domain Service
+ * - Encapsulates pricing business logic
+ * - Pure business logic (no infrastructure)
+ * - Can be used by multiple aggregates
+ *
+ * Business Rules:
+ * - Discounts based on order total
+ * - Free shipping threshold
+ * - Tax calculation
+ *
+ * Clean Code:
+ * - No magic numbers: constants for thresholds
+ * - Clear method names
+ * - Single Responsibility
+ */
+export class PricingService {
+    private static readonly DISCOUNT_THRESHOLD = Money.create(100, "USD")
+    private static readonly DISCOUNT_PERCENTAGE = 0.1
+    private static readonly FREE_SHIPPING_THRESHOLD = Money.create(50, "USD")
+    private static readonly SHIPPING_COST = Money.create(10, "USD")
+    private static readonly TAX_RATE = 0.2
+
+    /**
+     * Calculate discount for order
+     *
+     * Business Rule: 10% discount for orders over $100
+     */
+    public calculateDiscount(order: Order): Money {
+        const total = order.calculateTotal()
+
+        if (total.isGreaterThan(PricingService.DISCOUNT_THRESHOLD)) {
+            return total.multiply(PricingService.DISCOUNT_PERCENTAGE)
+        }
+
+        return Money.zero(total.currency)
+    }
+
+    /**
+     * Calculate shipping cost
+     *
+     * Business Rule: Free shipping for orders over $50
+     */
+    public calculateShippingCost(order: Order): Money {
+        const total = order.calculateTotal()
+
+        if (total.isGreaterThan(PricingService.FREE_SHIPPING_THRESHOLD)) {
+            return Money.zero(total.currency)
+        }
+
+        return PricingService.SHIPPING_COST
+    }
+
+    /**
+     * Calculate tax
+     *
+     * Business Rule: 20% tax on order total
+     */
+    public calculateTax(order: Order): Money {
+        const total = order.calculateTotal()
+        return total.multiply(PricingService.TAX_RATE)
+    }
+
+    /**
+     * Calculate final total with all costs
+     */
+    public calculateFinalTotal(order: Order): Money {
+        const subtotal = order.calculateTotal()
+        const discount = this.calculateDiscount(order)
+        const shipping = this.calculateShippingCost(order)
+        const tax = this.calculateTax(order)
+
+        return subtotal.subtract(discount).add(shipping).add(tax)
+    }
+}

packages/guardian/examples/good-architecture/domain/services/UserRegistrationService.ts

@@ -0,0 +1,63 @@
+import { User } from "../aggregates/User"
+import { Email } from "../value-objects/Email"
+import { IUserRepository } from "../repositories/IUserRepository"
+
+/**
+ * Domain Service: UserRegistrationService
+ *
+ * DDD Pattern: Domain Service
+ * - Encapsulates business logic that doesn't belong to a single entity
+ * - Coordinates multiple aggregates
+ * - Stateless
+ *
+ * When to use Domain Service:
+ * - Business logic spans multiple aggregates
+ * - Operation doesn't naturally fit in any entity
+ * - Need to check uniqueness (requires repository)
+ *
+ * SOLID Principles:
+ * - SRP: handles user registration logic
+ * - DIP: depends on IUserRepository abstraction
+ * - ISP: focused interface
+ *
+ * Clean Code:
+ * - Meaningful name: clearly registration logic
+ * - Small method: does one thing
+ * - No magic strings: clear error messages
+ */
+export class UserRegistrationService {
+    constructor(private readonly userRepository: IUserRepository) {}
+
+    /**
+     * Business Operation: Register new user
+     *
+     * Business Rules:
+     * - Email must be unique
+     * - User must have valid data
+     * - Registration creates active user
+     *
+     * @throws Error if email already exists
+     * @throws Error if user data is invalid
+     */
+    public async registerUser(email: Email, firstName: string, lastName: string): Promise<User> {
+        const existingUser = await this.userRepository.findByEmail(email)
+
+        if (existingUser) {
+            throw new Error(`User with email ${email.value} already exists`)
+        }
+
+        const user = User.create(email, firstName, lastName)
+
+        await this.userRepository.save(user)
+
+        return user
+    }
+
+    /**
+     * Business Query: Check if email is available
+     */
+    public async isEmailAvailable(email: Email): boolean {
+        const existingUser = await this.userRepository.findByEmail(email)
+        return !existingUser
+    }
+}