puaros/packages/guardian/ROADMAP.md

Guardian Roadmap 🗺️

This document outlines the current features and future plans for @puaros/guardian.

Current Version: 0.1.0 ✅ RELEASED

Released: 2025-11-24

Features Included in 0.1.0

✨ Core Detection:

• ✅ Hardcode detection (magic numbers, magic strings)
• ✅ Circular dependency detection
• ✅ Naming convention enforcement (layer-based rules)
• ✅ Architecture violations (Clean Architecture layers)
• ✅ Framework leak detection (domain importing frameworks)

🛠️ Developer Tools:

• ✅ CLI interface with guardian check command
• ✅ Smart constant name suggestions
• ✅ Layer distribution analysis
• ✅ Detailed violation reports with file:line:column
• ✅ Context snippets for each issue

📚 Documentation & Examples:

• ✅ AI-focused documentation (vibe coding + enterprise)
• ✅ Comprehensive examples (38 files: 29 good + 9 bad patterns)
• ✅ DDD/Clean Architecture templates
• ✅ Quick start guides
• ✅ Integration examples (CI/CD, pre-commit hooks)

🧪 Quality:

• ✅ 194 tests across 7 test files (all passing)
• ✅ 80%+ code coverage on all metrics
• ✅ Self-analysis: 0 violations (100% clean codebase)
• ✅ Extracted constants for better maintainability

🎯 Built For:

• ✅ Vibe coders using AI assistants (Claude, GPT, Copilot, Cursor)
• ✅ Enterprise teams enforcing architectural standards
• ✅ Code review automation

---

Future Roadmap

Version 0.2.0 - Entity Exposure Detection 🎭

Target: Q1 2026 Priority: HIGH

Prevent domain entities from leaking to API responses:

// ❌ Bad: Domain entity exposed!
async getUser(id: string): Promise<User> {
    return this.userService.findById(id)
}

// ✅ Good: Use DTOs and Mappers
async getUser(id: string): Promise<UserResponseDto> {
    const user = await this.userService.findById(id)
    return UserMapper.toDto(user)
}

Planned Features:

• Analyze return types in controllers/routes
• Check if returned type is from domain/entities
• Suggest using DTOs and Mappers
• Examples of proper DTO usage

---

Version 0.3.0 - Configuration File Support ⚙️

Target: Q1 2026 Priority: MEDIUM

Add support for configuration file .guardianrc:

// guardian.config.js or .guardianrc.js
export default {
    rules: {
        'hardcode/magic-numbers': 'error',
        'hardcode/magic-strings': 'warn',
        'architecture/layer-violation': 'error',
        'architecture/framework-leak': 'error',
        'architecture/entity-exposure': 'error',
        'circular-dependency': 'error',
        'naming-convention': 'warn',
    },

    exclude: [
        '**/*.test.ts',
        '**/*.spec.ts',
        'scripts/',
        'migrations/',
    ],

    layers: {
        domain: 'src/domain',
        application: 'src/application',
        infrastructure: 'src/infrastructure',
        shared: 'src/shared',
    },

    // Ignore specific violations
    ignore: {
        'hardcode/magic-numbers': {
            'config/constants.ts': [3000, 8080],  // Allow specific values
        },
    },
}

Planned Features:

• Configuration file support (.guardianrc, .guardianrc.js, guardian.config.js)
• Rule-level severity configuration (error, warn, off)
• Custom layer path mappings
• Per-file ignore patterns
• Extends support (base configs)

---

Version 0.4.0 - Pattern Enforcement 🎯

Target: Q2 2026 Priority: MEDIUM

Enforce common DDD/Clean Architecture patterns:

Repository Pattern:

• Repository interfaces must be in domain
• Repository implementations must be in infrastructure
• No DB-specific code in interfaces

Dependency Injection:

• Detect new ConcreteClass() in use cases
• Enforce constructor injection
• Detect service locator anti-pattern

Primitive Obsession:

• Detect primitives where Value Objects should be used
• Common candidates: email, phone, money, percentage, URL
• Suggest creating Value Objects

God Classes:

• Classes with > N methods (configurable)
• Classes with > M lines (configurable)
• Suggest splitting into smaller classes

---

Version 0.5.0 - Output Formats 📊

Target: Q2 2026 Priority: LOW

Multiple output format support for better integration:

# JSON for CI/CD integrations
guardian check ./src --format json

# HTML report for dashboards
guardian check ./src --format html --output report.html

# JUnit XML for CI systems
guardian check ./src --format junit

# SARIF for GitHub Code Scanning
guardian check ./src --format sarif

# Markdown for PR comments
guardian check ./src --format markdown

Planned Features:

• JSON output format
• HTML report generation
• JUnit XML format
• SARIF format (GitHub Code Scanning)
• Markdown format (for PR comments)
• Custom templates support

---

Version 0.6.0 - Auto-Fix Capabilities 🔧

Target: Q3 2026 Priority: LOW

Automatic refactoring and fixes:

# Interactive mode - choose fixes
guardian fix ./src --interactive

# Auto-fix all issues
guardian fix ./src --auto

# Dry run - show what would be fixed
guardian fix ./src --dry-run

Planned Auto-fixes:

1. Extract hardcoded values to constants
2. Create Value Objects from primitives
3. Generate repository interfaces
4. Create DTOs and mappers
5. Fix naming convention violations

---

Version 0.7.0 - Watch Mode & Git Integration 🔍

Target: Q3 2026 Priority: LOW

Real-time feedback and git integration:

# Watch mode - analyze on file changes
guardian watch ./src

# Only check changed files (git diff)
guardian check --git-diff

# Check files staged for commit
guardian check --staged

# Check files in PR
guardian check --pr

Planned Features:

• Watch mode for real-time analysis
• Git integration (check only changed files)
• Staged files checking
• PR file checking
• Pre-commit hook helper

---

Version 1.0.0 - Stable Release 🚀

Target: Q4 2026 Priority: HIGH

Production-ready stable release:

Features:

• All detectors stabilized and tested
• Comprehensive documentation
• Performance optimizations
• Enterprise-grade reliability
• Breaking change stability commitment

Ecosystem:

• VS Code extension
• GitHub Action
• GitLab CI template
• Integration guides for major CI/CD platforms
• Metrics dashboard

---

Future Ideas 💡

AI Assistant Specific Features

• Detect over-engineering patterns (too many abstraction layers)
• Detect unimplemented code (TODO comments, placeholder methods)
• Naming consistency analysis (mixed conventions)
• Boundary validation detection

Security Features

• Secrets detection (API keys, passwords, tokens)
• SQL injection pattern detection
• XSS vulnerability patterns
• Dependency vulnerability scanning

Code Quality Metrics

• Code quality score (0-100)
• Maintainability index
• Technical debt estimation
• Trend analysis over time
• Compare metrics across commits

Code Duplication

• Copy-paste detection
• Similar code block detection
• Suggest extracting common logic
• Duplicate constant detection

IDE Extensions

• VS Code Extension:

  • Real-time detection as you type
  • Inline suggestions
  • Quick fixes
  • Code actions
  • Problem panel integration

• JetBrains Plugin:

  • IntelliJ IDEA, WebStorm support
  • Inspection integration
  • Quick fixes

Platform Integrations

• GitHub:

  • GitHub Action
  • PR comments
  • Code scanning integration
  • Status checks
  • Trends dashboard

• GitLab:

  • GitLab CI template
  • Merge request comments
  • Security scanning integration

• Bitbucket:

  • Pipelines integration
  • PR decorators

---

How to Contribute

Have an idea? Want to implement a feature?

1. Check existing GitHub Issues
2. Create a new issue with label enhancement
3. Discuss the approach with maintainers
4. Submit a Pull Request

We welcome contributions! See CONTRIBUTING.md for guidelines.

---

Versioning

Guardian follows Semantic Versioning:

• MAJOR (1.0.0) - Breaking changes
• MINOR (0.1.0) - New features, backwards compatible
• PATCH (0.0.1) - Bug fixes, backwards compatible

Until we reach 1.0.0, minor version bumps (0.x.0) may include breaking changes as we iterate on the API.

---

Last Updated: 2025-11-24 Current Version: 0.1.0