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/src/api.ts

@@ -0,0 +1,90 @@
+import {
+    AnalyzeProject,
+    AnalyzeProjectRequest,
+    AnalyzeProjectResponse,
+} from "./application/use-cases/AnalyzeProject"
+import { IFileScanner } from "./domain/services/IFileScanner"
+import { ICodeParser } from "./domain/services/ICodeParser"
+import { IHardcodeDetector } from "./domain/services/IHardcodeDetector"
+import { INamingConventionDetector } from "./domain/services/INamingConventionDetector"
+import { FileScanner } from "./infrastructure/scanners/FileScanner"
+import { CodeParser } from "./infrastructure/parsers/CodeParser"
+import { HardcodeDetector } from "./infrastructure/analyzers/HardcodeDetector"
+import { NamingConventionDetector } from "./infrastructure/analyzers/NamingConventionDetector"
+import { ERROR_MESSAGES } from "./shared/constants"
+
+/**
+ * Analyzes a TypeScript/JavaScript project for code quality issues
+ *
+ * Detects hardcoded values (magic numbers and strings) and validates
+ * Clean Architecture layer dependencies.
+ *
+ * @param options - Configuration for the analysis
+ * @param options.rootDir - Root directory to analyze
+ * @param options.include - File patterns to include (optional)
+ * @param options.exclude - Directories to exclude (optional, defaults to node_modules, dist, build)
+ *
+ * @returns Analysis results including violations, metrics, and dependency graph
+ *
+ * @throws {Error} If analysis fails or project cannot be scanned
+ *
+ * @example
+ * ```typescript
+ * import { analyzeProject } from '@puaros/guardian'
+ *
+ * const result = await analyzeProject({
+ *     rootDir: './src',
+ *     exclude: ['node_modules', 'dist', 'test']
+ * })
+ *
+ * console.log(`Found ${result.hardcodeViolations.length} hardcoded values`)
+ * console.log(`Found ${result.violations.length} architecture violations`)
+ * console.log(`Analyzed ${result.metrics.totalFiles} files`)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Check for hardcoded values only
+ * const result = await analyzeProject({ rootDir: './src' })
+ *
+ * result.hardcodeViolations.forEach(violation => {
+ *     console.log(`${violation.file}:${violation.line}`)
+ *     console.log(`  Type: ${violation.type}`)
+ *     console.log(`  Value: ${violation.value}`)
+ *     console.log(`  Suggestion: ${violation.suggestion.constantName}`)
+ *     console.log(`  Location: ${violation.suggestion.location}`)
+ * })
+ * ```
+ */
+export async function analyzeProject(
+    options: AnalyzeProjectRequest,
+): Promise<AnalyzeProjectResponse> {
+    const fileScanner: IFileScanner = new FileScanner()
+    const codeParser: ICodeParser = new CodeParser()
+    const hardcodeDetector: IHardcodeDetector = new HardcodeDetector()
+    const namingConventionDetector: INamingConventionDetector = new NamingConventionDetector()
+    const useCase = new AnalyzeProject(
+        fileScanner,
+        codeParser,
+        hardcodeDetector,
+        namingConventionDetector,
+    )
+
+    const result = await useCase.execute(options)
+
+    if (!result.success || !result.data) {
+        throw new Error(result.error ?? ERROR_MESSAGES.FAILED_TO_ANALYZE)
+    }
+
+    return result.data
+}
+
+export type {
+    AnalyzeProjectRequest,
+    AnalyzeProjectResponse,
+    ArchitectureViolation,
+    HardcodeViolation,
+    CircularDependencyViolation,
+    NamingConventionViolation,
+    ProjectMetrics,
+} from "./application/use-cases/AnalyzeProject"