ailabs/puaros
1
0
Fork 0
mirror of https://github.com/samiyev/puaros.git synced 2025-12-27 23:06:54 +05:00
Code Issues Packages Projects Releases Wiki Activity

docs: add Anemic Model Detection documentation to WHY.md and RESEARCH_CITATIONS.md

Browse Source
This commit is contained in:
imfozilbek
2025-11-26 00:44:12 +05:00
parent a6b4c69b75
commit 656571860e
4 changed files with 546 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
README.md
View File

@@ -4,7 +4,7 @@ A TypeScript monorepo for code quality and analysis tools.
## Packages
- **[@puaros/guardian](./packages/guardian)** - Code quality guardian for vibe coders and enterprise teams. Detects hardcoded values, circular dependencies, and architecture violations. Perfect for AI-assisted development and enforcing Clean Architecture at scale.
- **[@puaros/guardian](./packages/guardian)** - Research-backed code quality guardian for vibe coders and enterprise teams. Detects hardcoded values, secrets, circular dependencies, architecture violations, and anemic domain models. Every rule is based on academic research, industry standards (OWASP, SonarQube), and authoritative books (Martin Fowler, Uncle Bob, Eric Evans). Perfect for AI-assisted development and enforcing Clean Architecture at scale.
## Prerequisites
@@ -147,6 +147,21 @@ The `@puaros/guardian` package is a code quality analyzer for both individual de
- **CLI Tool**: Command-line interface with `guardian` command
- **CI/CD Integration**: JSON/Markdown output for automation pipelines
### 📚 Research-Backed Rules
Guardian's detection rules are based on decades of software engineering research and industry best practices:
- **Academic Research**: MIT Course 6.031, ScienceDirect peer-reviewed studies (2020-2023), IEEE papers on Technical Debt
- **Industry Standards**: SonarQube (400,000+ organizations), Google/Airbnb/Microsoft style guides, OWASP security standards
- **Authoritative Books**:
- 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)
- **Security Standards**: OWASP Secrets Management, GitHub Secret Scanning (350+ patterns)
**Every rule links to research citations** - see [Why Guardian's Rules Matter](./packages/guardian/docs/WHY.md) and [Full Research Citations](./packages/guardian/docs/RESEARCH_CITATIONS.md) for complete academic papers, books, and expert references.
### Use Cases
**For Vibe Coders:**

22
packages/guardian/README.md
View File

@@ -79,7 +79,7 @@ Code quality guardian for vibe coders and enterprise teams - because AI writes f
- Supports multiple folder structures (domain/aggregates/*, domain/*, domain/entities/*)
- Filters allowed imports (value-objects, events, repositories, services)
- Critical severity for maintaining aggregate independence
- 📚 *Based on: Domain-Driven Design (Evans 2003), Implementing DDD (Vernon 2013)* → [Why?](./docs/WHY.md#aggregate-boundaries)
- 📚 *Based on: Domain-Driven Design (Evans 2003), Implementing DDD (Vernon 2013)* → [Why?](./docs/WHY.md#aggregate-boundary-validation)
🔐 **Secret Detection** ✨ NEW in v0.8.0
- Detects 350+ types of hardcoded secrets using industry-standard Secretlint
@@ -88,7 +88,25 @@ Code quality guardian for vibe coders and enterprise teams - because AI writes f
- Context-aware remediation suggestions for each secret type
- Prevents credentials from reaching version control
- Integrates seamlessly with existing detectors
- 📚 *Based on: OWASP Top 10, CWE-798 (Hardcoded Credentials), NIST Security Guidelines* → [Learn more](https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password)
- 📚 *Based on: OWASP Secrets Management, GitHub Secret Scanning (350+ patterns), security standards* → [Why?](./docs/WHY.md#secret-detection)
🩺 **Anemic Domain Model Detection** ✨ NEW in v0.9.0
- Detects entities with only getters/setters (data bags without behavior)
- Identifies public setters anti-pattern in domain entities
- Calculates methods-to-properties ratio for behavioral analysis
- Enforces rich domain models over anemic models
- Suggests moving business logic from services to entities
- Medium severity - architectural code smell
- 📚 *Based on: Martin Fowler's "Anemic Domain Model" (2003), DDD (Evans 2003), Transaction Script vs Domain Model patterns* → [Why?](./docs/WHY.md#anemic-domain-model-detection)
🎯 **Severity-Based Prioritization**
- Automatic sorting by severity: CRITICAL → HIGH → MEDIUM → LOW
- Filter by severity level: `--only-critical` or `--min-severity high`
- Focus on what matters most: secrets and circular dependencies first
- Visual severity indicators with color-coded labels (🔴🟠🟡🟢)
- Smart categorization based on impact to production
- Enables gradual technical debt reduction
- 📚 *Based on: SonarQube severity classification, IEEE/ScienceDirect research on Technical Debt prioritization* → [Why?](./docs/WHY.md#severity-based-prioritization)
🏗️ **Clean Architecture Enforcement**
- Built with DDD principles

314
packages/guardian/docs/RESEARCH_CITATIONS.md
View File

@@ -16,6 +16,10 @@ This document provides authoritative sources, academic papers, industry standard
8. [General Software Quality Standards](#8-general-software-quality-standards)
9. [Code Complexity Metrics](#9-code-complexity-metrics)
10. [Additional Authoritative Sources](#10-additional-authoritative-sources)
11. [Anemic Domain Model Detection](#11-anemic-domain-model-detection)
12. [Aggregate Boundary Validation (DDD Tactical Patterns)](#12-aggregate-boundary-validation-ddd-tactical-patterns)
13. [Secret Detection & Security](#13-secret-detection--security)
14. [Severity-Based Prioritization & Technical Debt](#14-severity-based-prioritization--technical-debt)
---
@@ -503,22 +507,318 @@ This document provides authoritative sources, academic papers, industry standard
---
## 11. Anemic Domain Model Detection
### Martin Fowler's Original Blog Post (2003)
**Blog Post: "Anemic Domain Model"** (November 25, 2003)
- Author: Martin Fowler
- Published: November 25, 2003
- Described as an anti-pattern related to domain driven design and application architecture
- Basic symptom: domain objects have hardly any behavior, making them little more than bags of getters and setters
- Reference: [Martin Fowler - Anemic Domain Model](https://martinfowler.com/bliki/AnemicDomainModel.html)
**Key Problems Identified:**
- "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, and these objects are connected with the rich relationships and structure that true domain models have"
- "The catch comes when you look at the behavior, and you realize that there is hardly any behavior on these objects"
- "This is contrary to the basic idea of object-oriented design; which is to combine data and process together"
**Why It's an Anti-pattern:**
- Fowler argues that anemic domain models incur all of the costs of a domain model, without yielding any of the benefits
- The logic that should be in a domain object is domain logic - validations, calculations, business rules
- Separating data from behavior violates core OOP principles
- Reference: [Wikipedia - Anemic Domain Model](https://en.wikipedia.org/wiki/Anemic_domain_model)
### Rich Domain Model vs Transaction Script
**Martin Fowler: Transaction Script Pattern**
- Transaction Script organizes business logic by procedures where each procedure handles a single request
- Good for simple logic with not-null checks and basic calculations
- Reference: [Martin Fowler - Transaction Script](https://martinfowler.com/eaaCatalog/transactionScript.html)
**When to Use Rich Domain Model:**
- If you have complicated and everchanging business rules involving validation, calculations, and derivations
- Object model handles complex domain logic better than procedural scripts
- Reference: [InformIT - Domain Logic Patterns](https://www.informit.com/articles/article.aspx?p=1398617&seqNum=2)
**Comparison:**
- Transaction Script is better for simple logic
- Domain Model is better when things get complicated with complex business rules
- You can refactor from Transaction Script to Domain Model, but it's a harder change
- Reference: [Medium - Transaction Script vs Domain Model](https://medium.com/@vibstudio_7040/transaction-script-active-record-and-domain-model-the-good-the-bad-and-the-ugly-c5b80a733305)
### Domain-Driven Design Context
**Eric Evans: Domain-Driven Design** (2003)
- Entities should have both identity and behavior
- Rich domain models place business logic within domain entities
- Anemic models violate DDD principles by separating data from behavior
- Reference: Already covered in Section 10 - [Domain-Driven Design Book](#domain-driven-design)
**Community Discussion:**
- Some argue anemic models can follow SOLID design principles
- However, consensus among DDD practitioners aligns with Fowler's anti-pattern view
- Reference: [Stack Overflow - Anemic Domain Model Anti-Pattern](https://stackoverflow.com/questions/6293981/concrete-examples-on-why-the-anemic-domain-model-is-considered-an-anti-pattern)
---
## 12. Aggregate Boundary Validation (DDD Tactical Patterns)
### Eric Evans: Domain-Driven Design (2003)
**Original Book Definition:**
- Aggregate: "A cluster of associated objects that we treat as a unit for the purpose of data changes"
- An aggregate defines a consistency boundary around one or more entities
- Exactly one entity in an aggregate is the root
- Reference: [Microsoft Learn - Tactical DDD](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/tactical-ddd)
**DDD Reference Document** (2015)
- Official Domain-Driven Design Reference by Eric Evans
- Contains comprehensive definitions of Aggregates and boundaries
- Reference: [Domain Language - DDD Reference PDF](https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf)
### Vaughn Vernon: Implementing Domain-Driven Design (2013)
**Chapter 10: Aggregates** (Page 347)
- Author: Vaughn Vernon
- Publisher: Addison-Wesley
- ISBN: 978-0321834577
- Available at: [Amazon - Implementing DDD](https://www.amazon.com/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577)
**Key Rules from the Chapter:**
- **Rule: Model True Invariants in Consistency Boundaries**
- **Rule: Design Small Aggregates**
- **Rule: Reference Other Aggregates by Identity**
- **Rule: Use Eventual Consistency Outside the Boundary**
**Effective Aggregate Design Series:**
- Three-part essay series by Vaughn Vernon
- Available as downloadable PDFs
- Licensed under Creative Commons Attribution-NoDerivs 3.0
- Reference: [Kalele - Effective Aggregate Design](https://kalele.io/effective-aggregate-design/)
**Appendix A: Aggregates and Event Sourcing:**
- Additional coverage of aggregate patterns
- Practical implementation guidance
- Reference: Available in the book
### Tactical DDD Patterns
**Microsoft Azure Architecture Center:**
- "Using tactical DDD to design microservices"
- Official Microsoft documentation on aggregate boundaries
- Comprehensive guide for microservices architecture
- Reference: [Microsoft Learn - Tactical DDD](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/tactical-ddd)
**SOCADK Design Practice Repository:**
- Summaries of artifacts, templates, and techniques for tactical DDD
- Practical examples of aggregate boundary enforcement
- Reference: [SOCADK - Tactical DDD](https://socadk.github.io/design-practice-repository/activities/DPR-TacticDDD.html)
### Why Aggregate Boundaries Matter
**Transactional Boundary:**
- What makes it an aggregate is the transactional boundary
- Changes to aggregate must be atomic
- Ensures consistency within the boundary
- Reference: [Medium - Mastering Aggregate Design](https://medium.com/ssense-tech/ddd-beyond-the-basics-mastering-aggregate-design-26591e218c8c)
**Cross-Aggregate References:**
- Aggregates should only reference other aggregates by ID, not direct entity references
- Prevents tight coupling between aggregates
- Maintains clear boundaries
- Reference: [Lev Gorodinski - Two Sides of DDD](http://gorodinski.com/blog/2013/03/11/the-two-sides-of-domain-driven-design/)
---
## 13. Secret Detection & Security
### OWASP Standards
**OWASP Secrets Management Cheat Sheet**
- Official OWASP best practices and guidelines for secrets management
- Comprehensive coverage of hardcoded credentials risks
- Reference: [OWASP - Secrets Management](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)
**OWASP DevSecOps Guideline**
- Section on Secrets Management (v-0.2)
- Integration with CI/CD pipelines
- Reference: [OWASP - DevSecOps Secrets](https://owasp.org/www-project-devsecops-guideline/latest/01a-Secrets-Management)
**OWASP Password Management: Hardcoded Password**
- Vulnerability documentation on hardcoded passwords
- "It is never a good idea to hardcode a password"
- Makes fixing the problem extremely difficult
- Reference: [OWASP - Hardcoded Password Vulnerability](https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password)
### Key Security Principles
**Don't Hardcode Secrets:**
- Secrets should not be hardcoded
- Should not be unencrypted
- Should not be stored in source code
- Reference: [OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)
**Centralized Management:**
- Growing need to centralize storage, provisioning, auditing, rotation, and management of secrets
- Control access and prevent secrets from leaking
- Use purpose-built tools for encryption-at-rest
- Reference: [OWASP SAMM - Secret Management](https://owaspsamm.org/model/implementation/secure-deployment/stream-b/)
**Prevention Tools:**
- Use pre-commit hooks to prevent secrets from entering codebase
- Automated scanning in CI/CD pipelines
- Reference: [GitHub OWASP Secrets Management](https://github.com/dominikdesmit/owasp-secrets-management)
### GitHub Secret Scanning
**Official GitHub Documentation:**
- About Secret Scanning: Automated detection of secrets in repositories
- Scans for patterns and heuristics matching known types of secrets
- Reference: [GitHub Docs - Secret Scanning](https://docs.github.com/code-security/secret-scanning/about-secret-scanning)
**How It Works:**
- Automatically scans repository contents for sensitive data (API keys, passwords, tokens)
- Scans commits, issues, and pull requests continuously
- Real-time alerts to repository administrators
- Reference: [GitHub Docs - Keeping Secrets Secure](https://docs.github.com/en/code-security/secret-scanning)
**AI-Powered Detection:**
- Copilot Secret Scanning uses large language models (LLMs)
- Identifies unstructured secrets (generic passwords) in source code
- Enhances detection beyond pattern matching
- Reference: [GitHub Docs - Copilot Secret Scanning](https://docs.github.com/en/code-security/secret-scanning/copilot-secret-scanning)
**Supported Patterns:**
- 350+ secret patterns detected
- AWS, GitHub, NPM, SSH, GCP, Slack, Basic Auth, JWT tokens
- Reference: [GitHub Docs - Supported Patterns](https://docs.github.com/en/code-security/secret-scanning/introduction/supported-secret-scanning-patterns)
### Mobile Security
**OWASP Mobile Security:**
- "Secrets security is the most important issue for mobile applications"
- Only safe way: keep secrets off the client side entirely
- Move sensitive information to backend
- Reference: [GitGuardian - OWASP Top 10 Mobile](https://blog.gitguardian.com/owasp-top-10-for-mobile-secrets/)
### Third-Party Tools
**GitGuardian:**
- Secrets security and non-human identity governance
- Enterprise-grade secret detection
- Reference: [GitGuardian Official Site](https://www.gitguardian.com/)
**Yelp detect-secrets:**
- Open-source enterprise-friendly secret detection
- Prevent secrets in code
- Reference: [GitHub - Yelp detect-secrets](https://github.com/Yelp/detect-secrets)
---
## 14. Severity-Based Prioritization & Technical Debt
### Academic Research on Technical Debt Prioritization
**Systematic Literature Review** (2020)
- Title: "A systematic literature review on Technical Debt prioritization"
- Analyzed 557 unique papers, included 44 primary studies
- Finding: "Technical Debt prioritization research is preliminary and there is no consensus on what the important factors are and how to measure them"
- Reference: [ScienceDirect - TD Prioritization](https://www.sciencedirect.com/science/article/pii/S016412122030220X)
**IEEE Conference Paper** (2021)
- Title: "Technical Debt Prioritization: Taxonomy, Methods Results, and Practical Characteristics"
- Systematic mapping review of 112 studies, resulting in 51 unique papers
- Classified methods in two-level taxonomy with 10 categories
- Reference: [IEEE Xplore - TD Prioritization](https://ieeexplore.ieee.org/document/9582595/)
**Identifying Severity of Technical Debt** (2023)
- Journal: Software Quality Journal
- Title: "Identifying the severity of technical debt issues based on semantic and structural information"
- Problem: "Existing studies mainly focus on detecting TD through source code or comments but usually ignore the severity degree of TD issues"
- Proposed approach combining semantic and structural information
- Reference: [Springer - TD Severity](https://link.springer.com/article/10.1007/s11219-023-09651-3)
### SonarQube Severity Classification
**Current Severity Levels** (SonarQube 10.2+)
- Severity levels: **info, low, medium, high, and blocker**
- Reference: [SonarQube Docs - Metrics Definition](https://docs.sonarsource.com/sonarqube-server/user-guide/code-metrics/metrics-definition)
**High/Blocker Severity:**
- An issue with significant probability of severe unintended consequences
- Should be fixed immediately
- Includes bugs leading to production crashes
- Security flaws allowing attackers to extract sensitive data or execute malicious code
- Reference: [SonarQube Docs - Metrics](https://docs.sonarsource.com/sonarqube-server/10.8/user-guide/code-metrics/metrics-definition)
**Medium Severity:**
- Quality flaw that can highly impact developer's productivity
- Uncovered code, duplicated blocks, unused parameters
- Reference: [SonarQube Documentation](https://docs.sonarsource.com/sonarqube-server/10.8/user-guide/code-metrics/metrics-definition)
**Low Severity:**
- Quality flaw with slight impact on developer productivity
- Lines too long, switch statements with few cases
- Reference: [SonarQube Documentation](https://docs.sonarsource.com/sonarqube-server/10.8/user-guide/code-metrics/metrics-definition)
**Info Severity:**
- No expected impact on application
- Informational purposes only
- Reference: [SonarQube Documentation](https://docs.sonarsource.com/sonarqube-server/10.8/user-guide/code-metrics/metrics-definition)
### Legacy SonarQube Classification (pre-10.2)
**Five Severity Levels:**
- **BLOCKER**: Bug with high probability to impact behavior in production (memory leak, unclosed JDBC connection)
- **CRITICAL**: Bug with low probability to impact production behavior OR security flaw (empty catch block, SQL injection)
- **MAJOR**: Quality flaw highly impacting developer productivity (uncovered code, duplicated blocks, unused parameters)
- **MINOR**: Quality flaw slightly impacting developer productivity (lines too long, switch statements < 3 cases)
- **INFO**: Informational only
- Reference: [SonarQube Community - Severity Categories](https://community.sonarsource.com/t/sonarqube-severity-categories/115287)
### Research on Impact and Effectiveness
**Empirical Study** (2020)
- Title: "Some SonarQube issues have a significant but small effect on faults and changes"
- Published in: ScienceDirect (Information and Software Technology)
- Large-scale empirical study on SonarQube issue impact
- Reference: [ScienceDirect - SonarQube Issues](https://www.sciencedirect.com/science/article/abs/pii/S0164121220301734)
**Machine Learning for Prioritization** (2024)
- Recent approaches: "Development teams could integrate models into CI/CD pipelines"
- Automatically flag potential TD issues during code reviews
- Prioritize based on severity
- Reference: [arXiv - Technical Debt Management](https://arxiv.org/html/2403.06484v1)
### Multiple-Case Study
**Aligning TD with Business Objectives** (2018)
- Title: "Aligning Technical Debt Prioritization with Business Objectives: A Multiple-Case Study"
- Demonstrates importance of priority-based technical debt management
- Reference: [ResearchGate - TD Business Alignment](https://www.researchgate.net/publication/328903587_Aligning_Technical_Debt_Prioritization_with_Business_Objectives_A_Multiple-Case_Study)
---
## Conclusion
The code quality detection rules implemented in Guardian are firmly grounded in:
1. **Academic Research**: Peer-reviewed papers on software maintainability, complexity metrics, and code quality
2. **Industry Standards**: ISO/IEC 25010, SonarQube rules, Google and Airbnb style guides
1. **Academic Research**: Peer-reviewed papers on software maintainability, complexity metrics, code quality, technical debt prioritization, and severity classification
2. **Industry Standards**: ISO/IEC 25010, SonarQube rules, OWASP security guidelines, Google and Airbnb style guides
3. **Authoritative Books**:
- Robert C. Martin's "Clean Architecture" (2017)
- Vaughn Vernon's "Implementing Domain-Driven Design" (2013)
- Eric Evans' "Domain-Driven Design" (2003)
- Martin Fowler's "Patterns of Enterprise Application Architecture" (2002)
- Martin Fowler's "Refactoring" (1999, 2018)
- Steve McConnell's "Code Complete" (1993, 2004)
4. **Expert Guidance**: Martin Fowler, Robert C. Martin (Uncle Bob), Eric Evans, Alistair Cockburn, Kent Beck
5. **Open Source Tools**: ArchUnit, SonarQube, ESLint - widely adopted in enterprise environments
4. **Expert Guidance**: Martin Fowler, Robert C. Martin (Uncle Bob), Eric Evans, Vaughn Vernon, Alistair Cockburn, Kent Beck
5. **Security Standards**: OWASP Secrets Management, GitHub Secret Scanning, GitGuardian best practices
6. **Open Source Tools**: ArchUnit, SonarQube, ESLint, Secretlint - widely adopted in enterprise environments
These rules represent decades of software engineering wisdom, empirical research, and battle-tested practices from the world's leading software organizations and thought leaders.
These rules represent decades of software engineering wisdom, empirical research, security best practices, and battle-tested practices from the world's leading software organizations and thought leaders.
---
@@ -545,8 +845,8 @@ These rules represent decades of software engineering wisdom, empirical research
---
**Document Version**: 1.0
**Last Updated**: 2025-11-24
**Document Version**: 1.1
**Last Updated**: 2025-11-26
**Questions or want to contribute research?**
- 📧 Email: fozilbek.samiyev@gmail.com
- 🐙 GitHub: https://github.com/samiyev/puaros/issues

207
packages/guardian/docs/WHY.md
View File

@@ -10,6 +10,10 @@ Guardian's detection rules are not invented - they're based on decades of softwa
- [Entity Exposure](#entity-exposure)
- [Repository Pattern](#repository-pattern)
- [Naming Conventions](#naming-conventions)
- [Anemic Domain Model Detection](#anemic-domain-model-detection)
- [Aggregate Boundary Validation](#aggregate-boundary-validation)
- [Secret Detection](#secret-detection)
- [Severity-Based Prioritization](#severity-based-prioritization)
- [Full Research Citations](#full-research-citations)
---
@@ -319,6 +323,192 @@ Consistent naming:
---
## 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](https://martinfowler.com/bliki/AnemicDomainModel.html)
**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](https://en.wikipedia.org/wiki/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](https://martinfowler.com/eaaCatalog/transactionScript.html)
**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](https://stackoverflow.com/questions/6293981/concrete-examples-on-why-the-anemic-domain-model-is-considered-an-anti-pattern)
[Read full research →](./RESEARCH_CITATIONS.md#11-anemic-domain-model-detection)
---
## 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](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/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](https://kalele.io/effective-aggregate-design/)
**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](https://medium.com/ssense-tech/ddd-beyond-the-basics-mastering-aggregate-design-26591e218c8c)
**Microsoft Azure Documentation:**
- Official guide for microservices architecture
- Comprehensive aggregate boundary patterns
- [Microsoft Learn - Tactical DDD](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/tactical-ddd)
[Read full research →](./RESEARCH_CITATIONS.md#12-aggregate-boundary-validation-ddd-tactical-patterns)
---
## 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](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)
- **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](https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password)
**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](https://docs.github.com/code-security/secret-scanning/about-secret-scanning)
**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](https://owaspsamm.org/model/implementation/secure-deployment/stream-b/)
**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](https://blog.gitguardian.com/owasp-top-10-for-mobile-secrets/)
[Read full research →](./RESEARCH_CITATIONS.md#13-secret-detection--security)
---
## 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](https://www.sciencedirect.com/science/article/pii/S016412122030220X)
- **IEEE Conference Paper (2021)**
- "Technical Debt Prioritization: Taxonomy, Methods Results"
- Reviewed 112 studies
- Classified methods in 10 categories
- [IEEE Xplore](https://ieeexplore.ieee.org/document/9582595/)
- **Software Quality Journal (2023)**
- "Identifying the severity of technical debt issues"
- Problem: Most studies ignore severity degree
- Proposed semantic + structural approach
- [Springer](https://link.springer.com/article/10.1007/s11219-023-09651-3)
**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](https://docs.sonarsource.com/sonarqube-server/user-guide/code-metrics/metrics-definition)
**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](https://arxiv.org/html/2403.06484v1)
**Business Alignment:**
- "Aligning Technical Debt Prioritization with Business Objectives" (2018)
- Multiple-case study demonstrating importance
- [ResearchGate](https://www.researchgate.net/publication/328903587_Aligning_Technical_Debt_Prioritization_with_Business_Objectives_A_Multiple-Case_Study)
[Read full research →](./RESEARCH_CITATIONS.md#14-severity-based-prioritization--technical-debt)
---
## Full Research Citations
For complete academic papers, books, and authoritative sources, see:
@@ -354,8 +544,9 @@ Guardian's rules align with international standards:
Guardian's rules are backed by:
✅ **5 Seminal Books** (1993-2017)
✅ **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)
@@ -363,9 +554,16 @@ Guardian's rules are backed by:
✅ **Academic Research** (1976-2024)
- MIT Course 6.031
- ScienceDirect peer-reviewed studies
- 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
@@ -373,10 +571,11 @@ Guardian's rules are backed by:
- 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
- Alistair Cockburn, Kent Beck, Thomas McCabe
- Vaughn Vernon, Alistair Cockburn, Kent Beck, Thomas McCabe
---
@@ -388,4 +587,4 @@ Guardian's rules are backed by:
---
*Last updated: 2025-11-24*
*Last updated: 2025-11-26*