puaros/packages/guardian/CHANGELOG.md

Changelog

All notable changes to @puaros/guardian will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[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 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
• GitHub Repository
• npm Package
• Documentation
• Roadmap
• Issues