Add dedicated section in help for AI coding assistants with:
- Step-by-step workflow (scan → fix → verify → expand)
- Recommended commands for each step
- Output format description for parsing
- Priority order guidance (CRITICAL → HIGH → MEDIUM → LOW)
This helps AI agents (Claude, Copilot, Cursor) immediately
understand how to use Guardian and take action.
Plan internal improvements before v0.8.0:
- v0.7.5: Refactor AnalyzeProject use-case (614 -> ~100 lines)
- v0.7.6: Refactor CLI module (470 -> ~100 lines)
- v0.7.7: Improve test coverage for domain files
- v0.7.8: Add E2E tests for pipeline and CLI
- v0.7.9: Refactor large detectors (optional)
Each release scoped to fit single session (~128K tokens).
Add TypeScript-aware filtering to HardcodeDetector to ignore legitimate
language constructs that are not actually hardcoded values.
Changes:
- Add detection and filtering of TypeScript type contexts:
* Union types (type Status = 'active' | 'inactive')
* Interface property types (interface { mode: 'development' })
* Type assertions (as 'read' | 'write')
* typeof checks (typeof x === 'string')
- Add Symbol() call detection for DI container tokens
- Add import() dynamic import detection
- Extend constants file patterns to include tokens.ts/tokens.js
- Add 13 new tests covering TypeScript type context filtering
Impact:
- Tested on real project (puaro/core): 985 → 633 issues (35.7% reduction)
- All 345 tests pass
- Zero new linting errors
Implement DDD aggregate boundary validation to detect and prevent direct
entity references across aggregate boundaries.
Features:
- Detect direct entity imports between aggregates
- Allow only ID or Value Object references
- Support multiple folder structures (domain/aggregates/*, domain/*, domain/entities/*)
- Filter allowed imports (value-objects, events, repositories, services)
- Critical severity level for violations
- 41 comprehensive tests with 92.55% coverage
- CLI output with detailed suggestions
- Examples of good and bad patterns
Breaking changes: None
Backwards compatible: Yes
- Added 11 new valid DDD repository method patterns
- Support for has*(), is*(), exists*(), clear*(), store*() methods
- Support for lifecycle methods: initialize(), close(), connect(), disconnect()
- Fixes issue where valid DDD patterns were flagged as violations
- Better alignment with real-world Domain-Driven Design practices
This reduces false positives in projects using cache repositories,
connection management, and domain-specific query methods.
Version: 0.6.3
- Added docs/WHY.md with user-friendly rule explanations and authoritative sources
- Added docs/RESEARCH_CITATIONS.md with 551 lines of academic and industry references
- Updated README.md with micro-citations under each feature
- Enhanced CLI help with 'BACKED BY RESEARCH' section
- Updated AI tools mentions across all docs (GitHub Copilot, Cursor, Windsurf, Claude, ChatGPT, Cline)
- Organized documentation structure: moved RESEARCH_CITATIONS.md to docs/
- Version bump: 0.6.1 -> 0.6.2
Research backing includes:
- Academia: MIT Course 6.031, ScienceDirect studies
- Books: Clean Architecture (Martin 2017), DDD (Evans 2003)
- Industry: Google, Microsoft, Airbnb style guides, SonarQube
- Experts: Martin Fowler, Robert C. Martin, Eric Evans, Alistair Cockburn
Improved guardian --help with comprehensive, actionable information:
- Add DETECTS section with quick fix instructions for all 8 violation types
- Add SEVERITY LEVELS explanation (CRITICAL → LOW)
- Add step-by-step WORKFLOW guide
- Add 7 practical EXAMPLES covering common use cases
- Add HOW TO FIX COMMON ISSUES reference section
Technical improvements:
- Extract all help text strings to CLI_HELP_TEXT constants
- Fix 17 hardcoded string violations
- Maintain Single Source of Truth principle
- Zero violations in Guardian's own codebase
The help system now provides complete context for autonomous AI agents
and clear guidance for human developers.
- Mark v0.6.0 as released
- Add comprehensive v0.6.0 section with all features
- Shift future versions (0.7.0 → 0.8.0, etc.)
- Update last modified date
- Add low-coverage files to technical debt (SourceFile, ProjectPath, RepositoryViolation, ValueObject)
- Update test statistics (10 test files, 292 tests, 90.63% coverage)
- Add v0.5.2 section with limit feature and ESLint cleanup
- Document all completed tasks from this release
- Add Entity Exposure Detection to features
- Add Dependency Direction Enforcement to features
- Add Repository Pattern Validation to features
- Update API documentation with all 8 violation types
- Add severity levels to all interfaces
- Document --limit option with examples
- Update ProjectMetrics interface
- Update test statistics (292 tests, 90.63% coverage)
- Remove unused SEVERITY_LEVELS import from AnalyzeProject.ts
- Prefix unused fileName variable with underscore in HardcodeDetector.ts
- Replace || with ?? for nullish coalescing
- Add --limit/-l option to limit detailed violation output
- Implement limit logic in displayGroupedViolations function
- Show warning when violations exceed limit
- Works with severity filters (--only-critical, --min-severity)
- Extract severity labels and headers to constants
- Improve CLI maintainability with SEVERITY_DISPLAY_LABELS and SEVERITY_SECTION_HEADERS
- Add CRITICAL/HIGH/MEDIUM/LOW severity levels to all violations
- Sort violations by severity automatically (most critical first)
- Add CLI flags: --min-severity and --only-critical
- Group violations by severity in CLI output with color-coded headers
- Update all violation interfaces to include severity field
- Maintain 90%+ test coverage with all tests passing
- Update CHANGELOG.md, ROADMAP.md, and package version to 0.5.2
Implement dependency direction detection to enforce Clean Architecture rules:
- Domain layer can only import from Domain and Shared
- Application layer can only import from Domain, Application, and Shared
- Infrastructure layer can import from all layers
- Shared layer can be imported by all layers
Added:
- IDependencyDirectionDetector interface in domain layer
- DependencyViolation value object with detailed suggestions and examples
- DependencyDirectionDetector implementation in infrastructure
- Integration with AnalyzeProject use case
- New DEPENDENCY_DIRECTION rule in constants
- 43 comprehensive tests covering all scenarios (100% passing)
- Good and bad examples in examples directory
Improvements:
- Optimized extractLayerFromImport method to reduce complexity
- Fixed indentation in DependencyGraph.ts
- Updated getExampleFix to avoid false positives in old detector
Test Results:
- All 261 tests passing
- Build successful
- Self-check: 0 architecture violations in src code
Implement entity exposure detection to prevent domain entities
from leaking to API responses. Detects when controllers/routes
return domain entities instead of DTOs.
Features:
- EntityExposure value object with detailed suggestions
- IEntityExposureDetector interface in domain layer
- EntityExposureDetector implementation in infrastructure
- Integration into AnalyzeProject use case
- CLI display with helpful suggestions
- 24 comprehensive unit tests (98% coverage)
- Examples for bad and good patterns
Detection scope:
- Infrastructure layer only (controllers, routes, handlers, resolvers, gateways)
- Identifies PascalCase entities without Dto/Request/Response suffixes
- Parses async methods with Promise<T> return types
- Provides step-by-step remediation suggestions
Test coverage:
- EntityExposureDetector: 98.07%
- Overall project: 90.6% statements, 83.97% branches
- 218 tests passing
BREAKING CHANGE: Version bump to 0.3.0
- Fix indentation in DependencyGraph.ts getMetrics return type
- Add ESLint disable comment for Guards class (utility class pattern)
- Clean up formatting across analyzer files
- Add UserWithFrameworks.ts example showing framework leaks in domain
- Add examples/bad/ directory with anti-pattern demonstrations
- Demonstrate common mistakes: Prisma in domain, Express types, etc.
- Add framework leak detector to AnalyzeProject use case
- Export FrameworkLeakDetector in public API
- Add FRAMEWORK_LEAK rule constant
- Include framework leak violations in analysis response
- Add IFrameworkLeakDetector interface in domain/services
- Add FrameworkLeak value object with framework type categorization
- Implement FrameworkLeakDetector with 250+ framework patterns across 12 categories
- Add comprehensive test suite (35 tests) for framework leak detection
- Support HTTP frameworks, ORMs, loggers, caches, message queues, etc.
- Detect framework imports in domain layer and suggest proper abstractions
Update README, CLAUDE.md, and CHANGELOG for guardian package.
Add guardian package documentation and remove core references.
Update repository URLs to samiyev/puaros and add official website link (puaros.ailabs.uz).
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.
Install required dependencies:
- simple-git for git operations
- tree-sitter and parsers for code parsing
- uuid for ID generation
- vitest for testing
- Remove deprecated @types/ioredis
Add test structure:
- Unit tests for BaseEntity
- Unit tests for Guards utility
- Test fixtures with code samples
- Integration and unit test directories
Add infrastructure implementations:
- BaseRepository with in-memory storage
- GitService for git operations using simple-git
- CodeParser for JS/TS parsing using tree-sitter
