puaros/packages/guardian/docs/WHY.md

Why Guardian's Rules Matter

Guardian's detection rules are not invented - they're based on decades of software engineering research, industry standards, and expert opinion from leading authorities.

Quick Navigation:

• Hardcode Detection
• Circular Dependencies
• Clean Architecture
• Framework Leaks
• Entity Exposure
• Repository Pattern
• Naming Conventions
• Anemic Domain Model Detection
• Aggregate Boundary Validation
• Secret Detection
• Severity-Based Prioritization
• Full Research Citations

---

Hardcode Detection

Why it matters

Magic numbers and strings make code:

• ❌ Hard to maintain - Changing a value requires finding all occurrences
• ❌ Error-prone - Typos in repeated values cause bugs
• ❌ Difficult to understand - What does 3000 mean without context?
• ❌ Not ready for change - Configuration changes require code modifications

Who says so?

Academia:

• MIT Course 6.031: Software Construction

  "Magic numbers fail three key measures: Safe from bugs, Easy to understand, Ready for change"

  • Used in MIT's software engineering curriculum
  • Read the course material

Industry Standards:

• SonarQube Rule RSPEC-109: "Magic numbers should not be used"
  • Used by 400,000+ organizations worldwide
  • Identifies hardcoded values as code smells
  • View the rule

Research:

• 2022 ScienceDirect Study: "What do developers consider magic literals?"
  • Analyzed 24,000 literals from 3,500+ methods
  • Surveyed 26 professional developers
  • Read the paper

Historical Context:

• Anti-pattern dating back to 1960s COBOL/FORTRAN manuals
• One of the oldest rules of programming

Read full research →

---

Circular Dependencies

Why it matters

Circular dependencies create:

• ❌ Tight coupling - Components cannot evolve independently
• ❌ Testing difficulties - Impossible to test modules in isolation
• ❌ Maintenance nightmares - Changes cause ripple effects across codebase
• ❌ Build complexity - Compilation order becomes problematic

Who says so?

Expert Opinion:

• Martin Fowler: Enterprise architecture patterns expert

  "Putting abstract classes in supertype package is good way of breaking cycles in the dependency structure"

  • Recommends using abstraction to break cycles
  • Read on TechTarget

Real-world Solutions:

• Shopify Engineering: "Remove Circular Dependencies by Using Dependency Injection"
  • Demonstrates practical application of Repository Pattern
  • Production-proven solution from major tech company
  • Read the article

Impact Studies:

• Services become hardly maintainable and highly coupled
• Open the door to error-prone applications
• Components cannot be tested in isolation

Read full research →

---

Clean Architecture

Why it matters

Clean Architecture principles ensure:

• ✅ Independence - Business rules don't depend on frameworks
• ✅ Testability - Business logic can be tested without UI/DB
• ✅ Flexibility - Easy to swap frameworks and tools
• ✅ Maintainability - Clear boundaries and responsibilities

The Dependency Rule

Robert C. Martin's Core Principle:

"Source code dependencies can only point inwards. Nothing in an inner circle can know anything about something in an outer circle."

Layer Flow:

Domain (innermost) ← Application ← Infrastructure (outermost)

Who says so?

The Definitive Book:

• Robert C. Martin (Uncle Bob): "Clean Architecture" (2017)
  • Published by O'Reilly (Prentice Hall)
  • Based on SOLID principles and decades of experience
  • Get the book

Core Principles:

• SOLID Principles (2000): Foundation of Clean Architecture
  • Single Responsibility Principle
  • Open-Closed Principle
  • Liskov Substitution Principle
  • Interface Segregation Principle
  • Dependency Inversion Principle (critical for layer separation)
  • Learn SOLID

The Clean Architecture Blog:

• Original blog post by Uncle Bob (2012)
• Defines the concentric circles architecture
• Read the original

Read full research →

---

Framework Leaks

Why it matters

Framework dependencies in domain layer:

• ❌ Coupling to infrastructure - Business logic tied to technical details
• ❌ Testing difficulties - Cannot test without framework setup
• ❌ Framework lock-in - Migration becomes impossible
• ❌ Violates Clean Architecture - Breaks the Dependency Rule

Who says so?

Original Research:

• Alistair Cockburn (2005): "Hexagonal Architecture"
  • HaT Technical Report 2005.02

  "Create your application to work without either a UI or a database so you can run automated regression-tests against the application, work when the database becomes unavailable, and link applications together without any user involvement."

  • Original Ports & Adapters pattern
  • Read the original paper

Industry Adoption:

• Robert C. Martin: "Clean Architecture" (2017)

  "Frameworks are tools, not architectures"

  • Frameworks belong in outer layers only

• AWS Prescriptive Guidance: Documents hexagonal architecture patterns

• GitHub: Domain-Driven Hexagon: Comprehensive implementation guide

  • View the guide

Key Insight: The goal is to isolate the application's business logic from external resources like databases, message queues, HTTP frameworks, etc.

Read full research →

---

Entity Exposure

Why it matters

Exposing domain entities directly:

• ❌ Breaks encapsulation - Exposes internal domain structure
• ❌ Security risks - May leak sensitive data (passwords, tokens)
• ❌ Coupling - API tied to domain model changes
• ❌ Violates Single Responsibility - Entities serve two purposes

Use DTOs Instead

Data Transfer Object (DTO) Pattern:

• Transform domain entities into simple data structures
• Control exactly what data is exposed
• Decouple API contracts from domain model
• Separate concerns: domain logic vs. data transfer

Who says so?

The Definitive Source:

• Martin Fowler: "Patterns of Enterprise Application Architecture" (2002)
  • Defines the DTO pattern
  • Published by Addison-Wesley

  "An object that carries data between processes in order to reduce the number of method calls"

  • Read on martinfowler.com

Purpose:

• Originally designed to batch remote calls and reduce network overhead
• Modern use: Separate domain model from external representation
• Prevents "God objects" that do too much

Warning: LocalDTO Anti-pattern: Martin Fowler also warns about overusing DTOs in local contexts where they add unnecessary complexity.

Read full research →

---

Repository Pattern

Why it matters

Repository pattern provides:

• ✅ Abstraction - Domain doesn't know about persistence details
• ✅ Testability - Easy to mock data access in tests
• ✅ Centralized queries - Single place for data access logic
• ✅ Clean separation - Domain logic separate from data access

Common Violations

Guardian detects:

• ORM types leaking into repository interfaces
• Technical method names (findOne, save) instead of domain language
• Direct ORM/database usage in use cases
• new Repository() instantiation (should use DI)

Who says so?

The Definitive Source:

• Martin Fowler: Enterprise Application Architecture Catalog

  "Mediates between the domain and data mapping layers using a collection-like interface for accessing domain objects"

  • Part of the Domain Logic Patterns
  • Read on martinfowler.com

Key Benefits:

• Minimizes duplicate query logic
• Allows multiple repositories for different storage needs
• Domain layer doesn't know about SQL, MongoDB, or any specific technology

Additional Support:

• Microsoft Learn: Official documentation on Repository Pattern
• Eric Evans: Referenced in Domain-Driven Design book
• Listed as: Data Source Architectural Pattern

Real-world Example:

// ❌ Bad: ORM leak in interface
interface IUserRepository {
    findOne(query: PrismaWhereInput): Promise<User>
}

// ✅ Good: Domain language
interface IUserRepository {
    findByEmail(email: Email): Promise<User | null>
    findById(id: UserId): Promise<User | null>
}

Read full research →

---

Naming Conventions

Why it matters

Consistent naming:

• ✅ Readability - Code is self-documenting
• ✅ Predictability - Developers know what to expect
• ✅ Maintainability - Easier to navigate large codebases
• ✅ Team alignment - Everyone follows same patterns

Guardian's Conventions

Domain Layer:

• Entities: User.ts, Order.ts (PascalCase nouns)
• Services: UserService.ts (PascalCase + Service suffix)
• Repositories: IUserRepository.ts (I prefix for interfaces)

Application Layer:

• Use cases: CreateUser.ts, PlaceOrder.ts (Verb + Noun)
• DTOs: UserDto.ts, CreateUserRequest.ts (Dto/Request/Response suffix)
• Mappers: UserMapper.ts (Mapper suffix)

Infrastructure Layer:

• Controllers: UserController.ts (Controller suffix)
• Repositories: MongoUserRepository.ts (implementation name + Repository)

Who says so?

Industry Style Guides:

• Google Java Style Guide

  • PascalCase for classes
  • camelCase for methods and variables
  • Read the guide

• Airbnb JavaScript Style Guide

  • 145,000+ GitHub stars
  • Industry standard for JavaScript/TypeScript
  • Read the guide

• Microsoft .NET Guidelines

  • PascalCase for types and public members
  • Consistent across entire .NET ecosystem
  • Widely adopted in C# and TypeScript communities

Use Case Naming:

• TM Forum Standard: Verb + Noun pattern for operations
  • Actions start with verbs: Create, Update, Delete, Get, Process
  • Clear intent from filename
  • Examples: ProcessOrder.ts, ValidateInput.ts

General Principle:

• Wikipedia: Naming Convention (Programming)
  • "Classes are nouns, methods are verbs"
  • Widely accepted across languages and paradigms

Read full research →

---

Anemic Domain Model Detection

Why it matters

Anemic domain models violate core OOP principles:

• ❌ No behavior - Entities become data bags with only getters/setters
• ❌ Logic in services - Business logic scattered across service layers
• ❌ Violates OOP - Separates data from behavior
• ❌ Higher complexity - Loses benefits of domain modeling

Who says so?

Martin Fowler's Original Anti-Pattern:

• Blog Post: "Anemic Domain Model" (November 25, 2003)

  "The basic symptom of an Anemic Domain Model is that at first blush it looks like the real thing. There are objects, many named after the nouns in the domain space... The catch comes when you look at the behavior, and you realize that there is hardly any behavior on these objects."

  • Published over 20 years ago, still relevant today
  • Read Fowler's post

Why It's an Anti-pattern:

"This is contrary to the basic idea of object-oriented design; which is to combine data and process together."

• Incurs all costs of domain model without any benefits
• Logic should be in domain objects: validations, calculations, business rules
• Wikipedia - Anemic Domain Model

Rich Domain Model vs Transaction Script:

• Transaction Script: Good for simple logic (Fowler, 2002)
• Rich Domain Model: Better for complex, ever-changing business rules
• Can refactor from Transaction Script to Domain Model, but it's harder than starting right
• Martin Fowler - Transaction Script

Domain-Driven Design Context:

• Eric Evans (2003): Entities should have both identity AND behavior
• Anemic models violate DDD by separating data from behavior
• Stack Overflow discussion

Read full research →

---

Aggregate Boundary Validation

Why it matters

Proper aggregate boundaries ensure:

• ✅ Consistency - Atomic changes within boundaries
• ✅ Low coupling - Aggregates are loosely connected
• ✅ Clear transactions - One aggregate = one transaction
• ✅ Maintainability - Boundaries prevent complexity spread

The Rules

Vaughn Vernon's Four Rules (2013):

1. Model True Invariants in Consistency Boundaries
2. Design Small Aggregates
3. Reference Other Aggregates by Identity
4. Use Eventual Consistency Outside the Boundary

Who says so?

Eric Evans: Domain-Driven Design (2003)

• Original Definition:

  "A cluster of associated objects that we treat as a unit for the purpose of data changes"

• An aggregate defines a consistency boundary
• Exactly one entity is the aggregate root
• Microsoft Learn - Tactical DDD

Vaughn Vernon: Implementing Domain-Driven Design (2013)

• Chapter 10: Aggregates (Page 347)
• ISBN: 978-0321834577
• Comprehensive rules for aggregate design
• Three-part essay series: "Effective Aggregate Design"
• Available at Kalele

Why Boundaries Matter:

• Transactional Boundary: Changes must be atomic
• Reference by ID: No direct entity references across aggregates
• Prevents tight coupling: Maintains clear boundaries
• Medium - Mastering Aggregate Design

Microsoft Azure Documentation:

• Official guide for microservices architecture
• Comprehensive aggregate boundary patterns
• Microsoft Learn - Tactical DDD

Read full research →

---

Secret Detection

Why it matters

Hardcoded secrets create critical security risks:

• 🔴 Data breaches - Exposed credentials lead to unauthorized access
• 🔴 Production incidents - Leaked tokens cause service disruptions
• 🔴 Compliance violations - GDPR, PCI-DSS, SOC 2 requirements
• 🔴 Impossible to rotate - Secrets in code are difficult to change

Who says so?

OWASP Security Standards:

• OWASP Secrets Management Cheat Sheet

  "Secrets should not be hardcoded, should not be unencrypted, and should not be stored in source code."

  • Official best practices from OWASP Foundation
  • Read the cheat sheet

• OWASP Hardcoded Password Vulnerability

  "It is never a good idea to hardcode a password, as it allows all of the project's developers to view the password and makes fixing the problem extremely difficult."

  • OWASP Documentation

GitHub Secret Scanning:

• Official GitHub Documentation
  • Automatically scans 350+ secret patterns
  • Detects AWS, GitHub, NPM, SSH, GCP, Slack tokens
  • AI-powered detection with Copilot Secret Scanning
  • GitHub Docs

Key Security Principles:

• Centralized Management: Use purpose-built secret management tools
• Prevention Tools: Pre-commit hooks to prevent secrets entering codebase
• Encryption at Rest: Never store secrets in plaintext
• OWASP SAMM - Secret Management

Mobile Security:

• OWASP: "Secrets security is the most important issue for mobile applications"
• Only safe way: keep secrets off the client side entirely
• GitGuardian - OWASP Top 10 Mobile

Read full research →

---

Severity-Based Prioritization

Why it matters

Severity classification enables:

• ✅ Focus on critical issues - Fix what matters most first
• ✅ Reduced technical debt - Prioritize based on impact
• ✅ Better CI/CD integration - Fail builds on critical issues only
• ✅ Team efficiency - Don't waste time on low-impact issues

Who says so?

Academic Research:

• Systematic Literature Review (2020)

  • Title: "A systematic literature review on Technical Debt prioritization"
  • Analyzed 557 papers, included 44 primary studies
  • Finding: Need for consensus on severity factors
  • ScienceDirect

• IEEE Conference Paper (2021)

  • "Technical Debt Prioritization: Taxonomy, Methods Results"
  • Reviewed 112 studies
  • Classified methods in 10 categories
  • IEEE Xplore

• Software Quality Journal (2023)

  • "Identifying the severity of technical debt issues"
  • Problem: Most studies ignore severity degree
  • Proposed semantic + structural approach
  • Springer

SonarQube Industry Standard:

• Current Classification (10.2+):
  • Blocker/High: Severe unintended consequences, fix immediately
  • Medium: Impacts developer productivity
  • Low: Slight impact on productivity
  • Info: No expected impact
  • SonarQube Docs

Real-World Impact:

• Development teams integrate models into CI/CD pipelines
• Automatically flag potential TD issues during code reviews
• Prioritize based on severity
• arXiv - Technical Debt Management

Business Alignment:

• "Aligning Technical Debt Prioritization with Business Objectives" (2018)
• Multiple-case study demonstrating importance
• ResearchGate

Read full research →

---

Full Research Citations

For complete academic papers, books, and authoritative sources, see:

📚 RESEARCH_CITATIONS.md

This document contains:

• 50+ authoritative references
• Academic papers with DOI/URLs
• Book citations with authors and publication years
• Industry standards from Google, Microsoft, AWS
• Expert blogs from Martin Fowler, Uncle Bob, Kent Beck
• Historical context dating back to 1960s

---

Quality Standards

Guardian's rules align with international standards:

ISO/IEC 25010:2011 (Software Quality Standard)

• Eight quality characteristics including Maintainability
• Sub-characteristics: Modularity, Reusability, Analysability, Modifiability, Testability
• Learn more

SQuaRE Framework:

• System and Software Quality Requirements and Evaluation
• Used throughout software development lifecycle

---

Summary: Why Trust Guardian?

Guardian's rules are backed by:

✅ 6 Seminal Books (1993-2017)

• Clean Architecture (Robert C. Martin, 2017)
• Implementing Domain-Driven Design (Vaughn Vernon, 2013)
• Domain-Driven Design (Eric Evans, 2003)
• Patterns of Enterprise Application Architecture (Martin Fowler, 2002)
• Refactoring (Martin Fowler, 1999)
• Code Complete (Steve McConnell, 1993)

✅ Academic Research (1976-2024)

• MIT Course 6.031
• ScienceDirect peer-reviewed studies (2020-2023)
• IEEE Conference papers on Technical Debt
• Software Quality Journal (2023)
• Cyclomatic Complexity (Thomas McCabe, 1976)

✅ Security Standards

• OWASP Secrets Management Cheat Sheet
• GitHub Secret Scanning (350+ patterns)
• OWASP Top 10 for Mobile

✅ International Standards

• ISO/IEC 25010:2011

✅ Industry Giants

• Google, Microsoft, Airbnb style guides
• SonarQube (400,000+ organizations)
• AWS documentation
• GitHub security practices

✅ Thought Leaders

• Martin Fowler, Robert C. Martin (Uncle Bob), Eric Evans
• Vaughn Vernon, Alistair Cockburn, Kent Beck, Thomas McCabe

---

Questions or want to contribute research?

• 📧 Email: fozilbek.samiyev@gmail.com
• 🐙 GitHub: https://github.com/samiyev/puaros/issues
• 📚 Full citations: RESEARCH_CITATIONS.md

---

Last updated: 2025-11-26