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.
2025-12-27 23:06:54 +05:00 · 2025-11-24 02:54:39 +05:00
parent 9f97509b06
commit 03705b5264
96 changed files with 9520 additions and 0 deletions
--- a/packages/guardian/CHANGELOG.md
+++ b/packages/guardian/CHANGELOG.md
@@ -0,0 +1,233 @@
+# Changelog
+
+All notable changes to @puaros/guardian will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-11-24
+
+### Added
+
+**🎉 Initial Release of @puaros/guardian**
+
+Code quality guardian for vibe coders and enterprise teams - your AI coding companion that keeps code clean while you move fast.
+
+#### Core Features
+
+- ✨ **Hardcode Detection**
+  - Detects magic numbers (timeouts, ports, limits, retries, delays)
+  - Detects magic strings (URLs, connection strings, API endpoints, error messages)
+  - Smart context analysis to reduce false positives
+  - Automatic constant name suggestions based on context
+  - Location suggestions for extracted constants (domain/shared/infrastructure)
+  - Ignores allowed numbers: -1, 0, 1, 2, 10, 100, 1000
+  - Ignores console.log, imports, tests, and exported constants
+
+- 🔄 **Circular Dependency Detection**
+  - Detects import cycles in codebase (A → B → A, A → B → C → A, etc.)
+  - Shows complete dependency chain for each cycle
+  - CLI output with detailed cycle path and severity
+  - Supports detection of multiple independent cycles
+  - Handles complex graphs with both cyclic and acyclic parts
+
+- 📝 **Naming Convention Enforcement**
+  - Layer-based naming rules for Clean Architecture
+  - **Domain Layer:**
+    - Entities: PascalCase nouns (User.ts, Order.ts)
+    - Services: *Service suffix (UserService.ts)
+    - Repository interfaces: I*Repository prefix (IUserRepository.ts)
+    - Forbidden patterns: Dto, Controller, Request, Response
+  - **Application Layer:**
+    - Use cases: Verb + Noun in PascalCase (CreateUser.ts, UpdateProfile.ts)
+    - DTOs: *Dto, *Request, *Response suffixes
+    - Mappers: *Mapper suffix
+  - **Infrastructure Layer:**
+    - Controllers: *Controller suffix
+    - Repository implementations: *Repository suffix
+    - Services: *Service or *Adapter suffixes
+  - Smart exclusion system for base classes
+  - Support for 26 standard use case verbs
+
+- 🏗️ **Architecture Violations**
+  - Clean Architecture layer validation
+  - Dependency rules enforcement:
+    - Domain → can only import Shared
+    - Application → can import Domain, Shared
+    - Infrastructure → can import Domain, Application, Shared
+    - Shared → cannot import anything
+  - Layer detection from file paths
+  - Import statement analysis
+
+#### CLI Interface
+
+- 🛠️ **Command-line tool** (`guardian` command)
+  - `guardian check <path>` - analyze project
+  - `--exclude <dirs>` - exclude directories
+  - `--verbose` - detailed output
+  - `--no-hardcode` - skip hardcode detection
+  - `--no-architecture` - skip architecture checks
+  - `--version` - show version
+  - `--help` - show help
+
+#### Reporting & Metrics
+
+- 📊 **Comprehensive metrics**
+  - Total files analyzed
+  - Total functions count
+  - Total imports count
+  - Layer distribution statistics (domain/application/infrastructure/shared)
+  - Detailed violation reports with file:line:column
+  - Context snippets for each violation
+  - Smart suggestions for fixing issues
+
+#### Developer Experience
+
+- 🤖 **Built for AI-Assisted Development**
+  - Perfect companion for Claude, GPT, Copilot, Cursor
+  - Catches common AI code smells (hardcoded values, architecture violations)
+  - Educational error messages with fix suggestions
+  - Designed for vibe coding workflow: AI writes → Guardian reviews → AI fixes → Ship
+
+- 🏢 **Enterprise-Ready**
+  - Enforce architectural standards at scale
+  - CI/CD integration ready
+  - JSON/Markdown output for automation
+  - Security: catch hardcoded secrets before production
+  - Metrics export for dashboards
+
+#### Examples & Documentation
+
+- 📚 **Comprehensive examples** (36 files)
+  - **Good Architecture** (29 files): Complete DDD/Clean Architecture patterns
+    - Domain: Aggregates, Entities, Value Objects, Events, Services, Factories, Specifications
+    - Application: Use Cases, DTOs, Mappers
+    - Infrastructure: Repositories, Controllers
+  - **Bad Architecture** (7 files): Anti-patterns to avoid
+    - Hardcoded values, Circular dependencies, Framework leaks, Entity exposure, Naming violations
+  - All examples fully documented with explanations
+  - Can be used as templates for new projects
+
+#### Testing & Quality
+
+- ✅ **Comprehensive test suite**
+  - 159 tests across 6 test files
+  - All tests passing
+  - 80%+ code coverage on all metrics
+  - Test fixtures for various scenarios
+  - Integration and unit tests
+
+- 🧹 **Self-analyzing**
+  - Guardian passes its own checks with **0 violations**
+  - All constants extracted (no hardcoded values)
+  - Follows Clean Architecture
+  - No circular dependencies
+  - Proper naming conventions
+
+#### Technical Details
+
+**Architecture:**
+- Built with Clean Architecture principles
+- Domain-Driven Design (DDD) patterns
+- Layered architecture (Domain, Application, Infrastructure, Shared)
+- TypeScript with strict type checking
+- Tree-sitter based AST parsing
+
+**Dependencies:**
+- commander ^12.1.0 - CLI framework
+- simple-git ^3.30.0 - Git operations
+- tree-sitter ^0.21.1 - Abstract syntax tree parsing
+- tree-sitter-javascript ^0.23.0 - JavaScript parser
+- tree-sitter-typescript ^0.23.0 - TypeScript parser
+- uuid ^13.0.0 - UUID generation
+
+**Development:**
+- TypeScript 5.7.3
+- Vitest 4.0.10 for testing
+- Node.js >= 18.0.0 required
+- CommonJS output with full TypeScript declarations
+- Source maps included
+
+**Package:**
+- Size: ~58 KB compressed
+- Unpacked: ~239 KB
+- 172 files included
+- Public npm package (`@puaros/guardian`)
+- CLI binary: `guardian`
+
+### Documentation
+
+- 📖 **Comprehensive README** (25KB+)
+  - Quick start for vibe coders (30-second setup)
+  - Enterprise integration guides (CI/CD, pre-commit, metrics)
+  - Real-world examples and workflows
+  - API documentation
+  - FAQ for both vibe coders and enterprise teams
+  - Success stories and use cases
+
+- 🗺️ **Roadmap** - Future features and improvements
+- 📋 **Contributing guidelines**
+- 📝 **TODO list** - Technical debt tracking
+- 📄 **MIT License**
+
+### Notes
+
+- First public release on npm
+- Production-ready for both individual developers and enterprise teams
+- Perfect for AI-assisted development workflows
+- Enforces Clean Architecture at scale
+- Zero violations in own codebase (self-tested)
+
+---
+
+## Future Releases
+
+Planned features for upcoming versions:
+- Framework leaks detection (domain importing from infrastructure)
+- Entity exposure detection (domain entities in presentation layer)
+- Configuration file support (.guardianrc)
+- Custom rule definitions
+- Plugin system
+- Multi-language support
+- Watch mode
+- Auto-fix capabilities
+- Git integration (check only changed files)
+- Performance optimizations
+
+See [ROADMAP.md](./ROADMAP.md) for detailed feature roadmap.
+
+---
+
+## Version Guidelines
+
+### Semantic Versioning
+
+**MAJOR.MINOR.PATCH** (e.g., 1.2.3)
+
+- **MAJOR** - Incompatible API changes
+- **MINOR** - New features, backwards compatible
+- **PATCH** - Bug fixes, backwards compatible
+
+### Release Checklist
+
+Before releasing a new version:
+- [ ] Update CHANGELOG.md with all changes
+- [ ] Update version in package.json
+- [ ] Run `pnpm test` - all tests pass
+- [ ] Run `pnpm build` - clean build
+- [ ] Run `pnpm test:coverage` - coverage >= 80%
+- [ ] Update ROADMAP.md if needed
+- [ ] Update README.md if API changed
+- [ ] Create git tag: `git tag v0.1.0`
+- [ ] Push to GitHub: `git push origin main --tags`
+- [ ] Publish to npm: `npm publish`
+
+---
+
+**Links:**
+- [Official Website](https://puaros.ailabs.uz)
+- [GitHub Repository](https://github.com/samiyev/puaros)
+- [npm Package](https://www.npmjs.com/package/@puaros/guardian)
+- [Documentation](https://github.com/samiyev/puaros/packages/guardian#readme)
+- [Roadmap](./ROADMAP.md)
+- [Issues](https://github.com/samiyev/puaros/issues)