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/application/use-cases/CreateUser.ts

@@ -0,0 +1,60 @@
+import { Email } from "../../domain/value-objects/Email"
+import { UserRegistrationService } from "../../domain/services/UserRegistrationService"
+import { UserMapper } from "../mappers/UserMapper"
+import { CreateUserRequest } from "../dtos/CreateUserRequest"
+import { UserResponseDto } from "../dtos/UserResponseDto"
+
+/**
+ * Use Case: CreateUser
+ *
+ * DDD Pattern: Application Service / Use Case
+ * - Orchestrates domain operations
+ * - Transaction boundary
+ * - Converts DTOs to domain
+ *
+ * SOLID Principles:
+ * - SRP: handles user creation workflow
+ * - DIP: depends on abstractions (UserRegistrationService)
+ * - OCP: can extend without modifying
+ *
+ * Clean Architecture:
+ * - Application layer
+ * - Uses domain services
+ * - Returns DTOs (not domain entities)
+ *
+ * Clean Code:
+ * - Verb+Noun naming: CreateUser
+ * - Single purpose
+ * - No business logic (delegated to domain)
+ */
+export class CreateUser {
+    constructor(private readonly userRegistrationService: UserRegistrationService) {}
+
+    public async execute(request: CreateUserRequest): Promise<UserResponseDto> {
+        this.validateRequest(request)
+
+        const email = Email.create(request.email)
+
+        const user = await this.userRegistrationService.registerUser(
+            email,
+            request.firstName,
+            request.lastName,
+        )
+
+        return UserMapper.toDto(user)
+    }
+
+    private validateRequest(request: CreateUserRequest): void {
+        if (!request.email?.trim()) {
+            throw new Error("Email is required")
+        }
+
+        if (!request.firstName?.trim()) {
+            throw new Error("First name is required")
+        }
+
+        if (!request.lastName?.trim()) {
+            throw new Error("Last name is required")
+        }
+    }
+}

packages/guardian/examples/good-architecture/application/use-cases/PlaceOrder.ts

@@ -0,0 +1,88 @@
+import { OrderFactory } from "../../domain/factories/OrderFactory"
+import { IOrderRepository } from "../../domain/repositories/IOrderRepository"
+import { UserId } from "../../domain/value-objects/UserId"
+import { Money } from "../../domain/value-objects/Money"
+import { OrderMapper } from "../mappers/OrderMapper"
+import { OrderResponseDto } from "../dtos/OrderResponseDto"
+
+/**
+ * Place Order Request
+ */
+export interface PlaceOrderRequest {
+    readonly userId: string
+    readonly items: Array<{
+        readonly productId: string
+        readonly productName: string
+        readonly price: number
+        readonly currency: string
+        readonly quantity: number
+    }>
+}
+
+/**
+ * Use Case: PlaceOrder
+ *
+ * Application Service:
+ * - Orchestrates order placement
+ * - Transaction boundary
+ * - Validation at system boundary
+ *
+ * Business Flow:
+ * 1. Validate request
+ * 2. Create order with items
+ * 3. Confirm order
+ * 4. Persist order
+ * 5. Return DTO
+ */
+export class PlaceOrder {
+    constructor(private readonly orderRepository: IOrderRepository) {}
+
+    public async execute(request: PlaceOrderRequest): Promise<OrderResponseDto> {
+        this.validateRequest(request)
+
+        const userId = UserId.create(request.userId)
+
+        const items = request.items.map((item) => ({
+            productId: item.productId,
+            productName: item.productName,
+            price: Money.create(item.price, item.currency),
+            quantity: item.quantity,
+        }))
+
+        const order = OrderFactory.createWithItems(userId, items)
+
+        order.confirm()
+
+        await this.orderRepository.save(order)
+
+        return OrderMapper.toDto(order)
+    }
+
+    private validateRequest(request: PlaceOrderRequest): void {
+        if (!request.userId?.trim()) {
+            throw new Error("User ID is required")
+        }
+
+        if (!request.items || request.items.length === 0) {
+            throw new Error("Order must have at least one item")
+        }
+
+        for (const item of request.items) {
+            if (!item.productId?.trim()) {
+                throw new Error("Product ID is required")
+            }
+
+            if (!item.productName?.trim()) {
+                throw new Error("Product name is required")
+            }
+
+            if (item.price <= 0) {
+                throw new Error("Price must be positive")
+            }
+
+            if (item.quantity <= 0) {
+                throw new Error("Quantity must be positive")
+            }
+        }
+    }
+}