mirror of
https://github.com/samiyev/puaros.git
synced 2025-12-27 23:06:54 +05:00
Compare commits
7 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
1663d191ee | ||
|
|
7b4cb60f13 | ||
|
|
33d763c41b | ||
|
|
3cd97c6197 | ||
|
|
8dd445995d | ||
|
|
c75738ba51 | ||
|
|
83b5dccee4 |
@@ -5,6 +5,159 @@ All notable changes to @samiyev/guardian will be documented in this file.
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [0.7.4] - 2025-11-25
|
||||
|
||||
### Fixed
|
||||
|
||||
- 🐛 **TypeScript-aware hardcode detection** - dramatically reduces false positives by 35.7%:
|
||||
- Ignore strings in TypeScript union types (`type Status = 'active' | 'inactive'`)
|
||||
- Ignore strings in interface property types (`interface { mode: 'development' | 'production' }`)
|
||||
- Ignore strings in type assertions (`as 'read' | 'write'`)
|
||||
- Ignore strings in typeof checks (`typeof x === 'string'`)
|
||||
- Ignore strings in Symbol() calls for DI tokens (`Symbol('LOGGER')`)
|
||||
- Ignore strings in dynamic import() calls (`import('../../module.js')`)
|
||||
- Exclude tokens.ts/tokens.js files completely (DI container files)
|
||||
- Tested on real-world TypeScript project: 985 → 633 issues (352 false positives eliminated)
|
||||
- ✅ **Added 13 new tests** for TypeScript type context filtering
|
||||
|
||||
## [0.7.3] - 2025-11-25
|
||||
|
||||
### Fixed
|
||||
|
||||
- 🐛 **False positive: repository importing its own aggregate:**
|
||||
- Added `isInternalBoundedContextImport()` method to detect internal imports
|
||||
- Imports like `../aggregates/Entity` from `repositories/Repo` are now allowed
|
||||
- This correctly allows `ICodeProjectRepository` to import `CodeProject` from the same bounded context
|
||||
- Cross-aggregate imports (with multiple `../..`) are still detected as violations
|
||||
|
||||
## [0.7.2] - 2025-11-25
|
||||
|
||||
### Fixed
|
||||
|
||||
- 🐛 **False positive: `errors` folder detected as aggregate:**
|
||||
- Added `errors` and `exceptions` to `DDD_FOLDER_NAMES` constants
|
||||
- Added to `nonAggregateFolderNames` — these folders are no longer detected as aggregates
|
||||
- Added to `allowedFolderNames` — imports from `errors`/`exceptions` folders are allowed across aggregates
|
||||
- Fixes issue where `domain/code-analysis/errors/` was incorrectly identified as a separate aggregate named "errors"
|
||||
|
||||
## [0.7.1] - 2025-11-25
|
||||
|
||||
### Fixed
|
||||
|
||||
- 🐛 **Aggregate Boundary Detection for relative paths:**
|
||||
- Fixed regex pattern to support paths starting with `domain/` (without leading `/`)
|
||||
- Now correctly detects violations in projects scanned from parent directories
|
||||
|
||||
- 🐛 **Reduced false positives in Repository Pattern detection:**
|
||||
- Removed `findAll`, `exists`, `count` from ORM technical methods blacklist
|
||||
- These are now correctly recognized as valid domain method names
|
||||
- Added `exists`, `count`, `countBy[A-Z]` to domain method patterns
|
||||
|
||||
- 🐛 **Non-aggregate folder exclusions:**
|
||||
- Added exclusions for standard DDD folders: `constants`, `shared`, `factories`, `ports`, `interfaces`
|
||||
- Prevents false positives when domain layer has shared utilities
|
||||
|
||||
### Changed
|
||||
|
||||
- ♻️ **Extracted magic strings to constants:**
|
||||
- DDD folder names (`entities`, `aggregates`, `value-objects`, etc.) moved to `DDD_FOLDER_NAMES`
|
||||
- Repository method suggestions moved to `REPOSITORY_METHOD_SUGGESTIONS`
|
||||
- Fallback suggestions moved to `REPOSITORY_FALLBACK_SUGGESTIONS`
|
||||
|
||||
### Added
|
||||
|
||||
- 📁 **Aggregate boundary test examples:**
|
||||
- Added `examples/aggregate-boundary/domain/` with Order, User, Product aggregates
|
||||
- Demonstrates cross-aggregate entity reference violations
|
||||
|
||||
## [0.7.0] - 2025-11-25
|
||||
|
||||
### Added
|
||||
|
||||
**🔒 Aggregate Boundary Validation**
|
||||
|
||||
New DDD feature to enforce aggregate boundaries and prevent tight coupling between aggregates.
|
||||
|
||||
- ✅ **Aggregate Boundary Detector:**
|
||||
- Detects direct entity references across aggregate boundaries
|
||||
- Validates that aggregates reference each other only by ID or Value Objects
|
||||
- Supports multiple folder structure patterns:
|
||||
- `domain/aggregates/order/Order.ts`
|
||||
- `domain/order/Order.ts`
|
||||
- `domain/entities/order/Order.ts`
|
||||
|
||||
- ✅ **Smart Import Analysis:**
|
||||
- Parses ES6 imports and CommonJS require statements
|
||||
- Identifies entity imports from other aggregates
|
||||
- Allows imports from value-objects, events, services, specifications folders
|
||||
|
||||
- ✅ **Actionable Suggestions:**
|
||||
- Reference by ID instead of entity
|
||||
- Use Value Objects to store needed data from other aggregates
|
||||
- Maintain aggregate independence
|
||||
|
||||
- ✅ **CLI Integration:**
|
||||
- `--architecture` flag includes aggregate boundary checks
|
||||
- CRITICAL severity for violations
|
||||
- Detailed violation messages with file:line references
|
||||
|
||||
- ✅ **Test Coverage:**
|
||||
- 41 new tests for aggregate boundary detection
|
||||
- 333 total tests passing (100% pass rate)
|
||||
- Examples in `examples/aggregate-boundary/`
|
||||
|
||||
### Technical
|
||||
|
||||
- New `AggregateBoundaryDetector` in infrastructure layer
|
||||
- New `AggregateBoundaryViolation` value object in domain layer
|
||||
- New `IAggregateBoundaryDetector` interface for dependency inversion
|
||||
- Integrated into `AnalyzeProject` use case
|
||||
|
||||
## [0.6.4] - 2025-11-24
|
||||
|
||||
### Added
|
||||
|
||||
**🎯 Smart Context-Aware Suggestions for Repository Method Names**
|
||||
|
||||
Guardian now provides intelligent, context-specific suggestions when it detects non-domain method names in repositories.
|
||||
|
||||
- ✅ **Intelligent method name analysis:**
|
||||
- `queryUsers()` → Suggests: `search`, `findBy[Property]`
|
||||
- `selectById()` → Suggests: `findBy[Property]`, `get[Entity]`
|
||||
- `insertUser()` → Suggests: `create`, `add[Entity]`, `store[Entity]`
|
||||
- `updateRecord()` → Suggests: `update`, `modify[Entity]`
|
||||
- `upsertUser()` → Suggests: `save`, `store[Entity]`
|
||||
- `removeUser()` → Suggests: `delete`, `removeBy[Property]`
|
||||
- `fetchUserData()` → Suggests: `findBy[Property]`, `get[Entity]`
|
||||
- And more technical patterns detected automatically!
|
||||
|
||||
- 🎯 **Impact:**
|
||||
- Developers get actionable, relevant suggestions instead of generic examples
|
||||
- Faster refactoring with specific naming alternatives
|
||||
- Better learning experience for developers new to DDD
|
||||
|
||||
### Fixed
|
||||
|
||||
- ✅ **Expanded domain method patterns support:**
|
||||
- `find*()` methods - e.g., `findNodes()`, `findNodeById()`, `findSimilar()`
|
||||
- `saveAll()` - batch save operations
|
||||
- `deleteBy*()` methods - e.g., `deleteByPath()`, `deleteById()`
|
||||
- `deleteAll()` - clear all entities
|
||||
- `add*()` methods - e.g., `addRelationship()`, `addItem()`
|
||||
- `initializeCollection()` - collection initialization
|
||||
|
||||
- 🐛 **Removed `findAll` from technical methods blacklist:**
|
||||
- `findAll()` is now correctly recognized as a standard domain method
|
||||
- Reduced false positives for repositories using this common pattern
|
||||
|
||||
### Technical
|
||||
|
||||
- Added `suggestDomainMethodName()` method in `RepositoryPatternDetector.ts` with keyword-based suggestion mapping
|
||||
- Updated `getNonDomainMethodSuggestion()` in `RepositoryViolation.ts` to extract and use smart suggestions
|
||||
- Refactored suggestion logic to reduce cyclomatic complexity (22 → 9)
|
||||
- Enhanced `domainMethodPatterns` with 9 additional patterns
|
||||
- All 333 tests passing
|
||||
|
||||
## [0.6.3] - 2025-11-24
|
||||
|
||||
### Fixed
|
||||
|
||||
895
packages/guardian/COMPARISON.md
Normal file
895
packages/guardian/COMPARISON.md
Normal file
@@ -0,0 +1,895 @@
|
||||
# Guardian vs Competitors: Comprehensive Comparison 🔍
|
||||
|
||||
**Last Updated:** 2025-01-24
|
||||
|
||||
This document provides an in-depth comparison of Guardian against major competitors in the static analysis and architecture enforcement space.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 TL;DR - When to Use Each Tool
|
||||
|
||||
| Your Need | Recommended Tool | Why |
|
||||
|-----------|------------------|-----|
|
||||
| **TypeScript + AI coding + DDD** | ✅ **Guardian** | Only tool built for AI-assisted DDD development |
|
||||
| **Multi-language + Security** | SonarQube | 35+ languages, deep security scanning |
|
||||
| **Dependency visualization** | dependency-cruiser + Guardian | Best visualization + architecture rules |
|
||||
| **Java architecture** | ArchUnit | Java-specific with unit test integration |
|
||||
| **TypeScript complexity metrics** | FTA + Guardian | Fast metrics + architecture enforcement |
|
||||
| **Python architecture** | import-linter + Guardian (future) | Python layer enforcement |
|
||||
|
||||
---
|
||||
|
||||
## 📊 Feature Comparison Matrix
|
||||
|
||||
### Core Capabilities
|
||||
|
||||
| Feature | Guardian | SonarQube | dependency-cruiser | ArchUnit | FTA | ESLint |
|
||||
|---------|----------|-----------|-------------------|----------|-----|--------|
|
||||
| **Languages** | JS/TS | 35+ | JS/TS/Vue | Java | TS/JS | JS/TS |
|
||||
| **Setup Complexity** | ⚡ Simple | 🐌 Complex | ⚡ Simple | ⚙️ Medium | ⚡ Simple | ⚡ Simple |
|
||||
| **Price** | 🆓 Free | 💰 Freemium | 🆓 Free | 🆓 Free | 🆓 Free | 🆓 Free |
|
||||
| **GitHub Stars** | - | - | 6.2k | 3.1k | - | 24k+ |
|
||||
|
||||
### Detection Capabilities
|
||||
|
||||
| Feature | Guardian | SonarQube | dependency-cruiser | ArchUnit | FTA | ESLint |
|
||||
|---------|----------|-----------|-------------------|----------|-----|--------|
|
||||
| **Hardcode Detection** | ✅✅ (with AI tips) | ⚠️ (secrets only) | ❌ | ❌ | ❌ | ❌ |
|
||||
| **Circular Dependencies** | ✅ | ✅ | ✅✅ (visual) | ✅ | ❌ | ✅ |
|
||||
| **Architecture Layers** | ✅✅ (DDD/Clean) | ⚠️ (generic) | ✅ (via rules) | ✅✅ | ❌ | ⚠️ |
|
||||
| **Framework Leak** | ✅✅ UNIQUE | ❌ | ⚠️ (via rules) | ⚠️ | ❌ | ❌ |
|
||||
| **Entity Exposure** | ✅✅ UNIQUE | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||
| **Naming Conventions** | ✅ (DDD-specific) | ✅ (generic) | ❌ | ✅ | ❌ | ✅ |
|
||||
| **Repository Pattern** | ✅✅ UNIQUE | ❌ | ❌ | ⚠️ | ❌ | ❌ |
|
||||
| **Dependency Direction** | ✅✅ | ❌ | ✅ (via rules) | ✅ | ❌ | ❌ |
|
||||
| **Security (SAST)** | ❌ | ✅✅ | ❌ | ❌ | ❌ | ⚠️ |
|
||||
| **Dependency Risks (SCA)** | ❌ | ✅✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| **Complexity Metrics** | ❌ | ✅ | ❌ | ❌ | ✅✅ | ⚠️ |
|
||||
| **Code Duplication** | ❌ | ✅✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
|
||||
### Developer Experience
|
||||
|
||||
| Feature | Guardian | SonarQube | dependency-cruiser | ArchUnit | FTA | ESLint |
|
||||
|---------|----------|-----------|-------------------|----------|-----|--------|
|
||||
| **CLI** | ✅ | ✅ | ✅ | ❌ (lib) | ✅ | ✅ |
|
||||
| **Configuration** | ✅ (v0.6+) | ✅✅ | ✅ | ✅ | ⚠️ | ✅✅ |
|
||||
| **Visualization** | ✅ (v0.7+) | ✅✅ (dashboard) | ✅✅ (graphs) | ❌ | ⚠️ | ❌ |
|
||||
| **Auto-Fix** | ✅✅ (v0.9+) UNIQUE | ❌ | ❌ | ❌ | ❌ | ✅ |
|
||||
| **AI Workflow** | ✅✅ UNIQUE | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||
| **CI/CD Integration** | ✅ (v0.8+) | ✅✅ | ✅ | ✅ | ⚠️ | ✅✅ |
|
||||
| **IDE Extensions** | 🔜 (v1.0+) | ✅ | ❌ | ❌ | ⚠️ | ✅✅ |
|
||||
| **Metrics Dashboard** | ✅ (v0.10+) | ✅✅ | ⚠️ | ❌ | ✅ | ❌ |
|
||||
|
||||
**Legend:**
|
||||
- ✅✅ = Excellent support
|
||||
- ✅ = Good support
|
||||
- ⚠️ = Limited/partial support
|
||||
- ❌ = Not available
|
||||
- 🔜 = Planned/Coming soon
|
||||
|
||||
---
|
||||
|
||||
## 🔥 Guardian's Unique Advantages
|
||||
|
||||
Guardian has **7 unique features** that no competitor offers:
|
||||
|
||||
### 1. ✨ Hardcode Detection with AI Suggestions
|
||||
|
||||
**Guardian:**
|
||||
```typescript
|
||||
// Detected:
|
||||
app.listen(3000)
|
||||
|
||||
// Suggestion:
|
||||
💡 Extract to: DEFAULT_PORT
|
||||
📁 Location: infrastructure/config/constants.ts
|
||||
🤖 AI Prompt: "Extract port 3000 to DEFAULT_PORT constant in config"
|
||||
```
|
||||
|
||||
**Competitors:**
|
||||
- SonarQube: Only detects hardcoded secrets (API keys), not magic numbers
|
||||
- Others: No hardcode detection at all
|
||||
|
||||
### 2. 🔌 Framework Leak Detection
|
||||
|
||||
**Guardian:**
|
||||
```typescript
|
||||
// domain/entities/User.ts
|
||||
import { Request } from 'express' // ❌ VIOLATION!
|
||||
|
||||
// Detected: Framework leak in domain layer
|
||||
// Suggestion: Use dependency injection via interfaces
|
||||
```
|
||||
|
||||
**Competitors:**
|
||||
- ArchUnit: Can check via custom rules (not built-in)
|
||||
- Others: Not available
|
||||
|
||||
### 3. 🎭 Entity Exposure Detection
|
||||
|
||||
**Guardian:**
|
||||
```typescript
|
||||
// ❌ Bad: Domain entity exposed
|
||||
async getUser(): Promise<User> { }
|
||||
|
||||
// ✅ Good: Use DTOs
|
||||
async getUser(): Promise<UserDto> { }
|
||||
|
||||
// Guardian detects this automatically!
|
||||
```
|
||||
|
||||
**Competitors:**
|
||||
- None have this built-in
|
||||
|
||||
### 4. 📚 Repository Pattern Validation
|
||||
|
||||
**Guardian:**
|
||||
```typescript
|
||||
// Detects ORM types in domain interfaces:
|
||||
interface IUserRepository {
|
||||
findOne(query: { where: ... }) // ❌ Prisma-specific!
|
||||
}
|
||||
|
||||
// Detects concrete repos in use cases:
|
||||
constructor(private prisma: PrismaClient) {} // ❌ VIOLATION!
|
||||
```
|
||||
|
||||
**Competitors:**
|
||||
- None validate repository pattern
|
||||
|
||||
### 5. 🤖 AI-First Workflow
|
||||
|
||||
**Guardian:**
|
||||
```bash
|
||||
# Generate AI-friendly fix prompt
|
||||
guardian check ./src --format ai-prompt > fix.txt
|
||||
|
||||
# Feed to Claude/GPT:
|
||||
"Fix these Guardian violations: $(cat fix.txt)"
|
||||
|
||||
# AI fixes → Run Guardian again → Ship it!
|
||||
```
|
||||
|
||||
**Competitors:**
|
||||
- Generic output, not optimized for AI assistants
|
||||
|
||||
### 6. 🛠️ Auto-Fix for Architecture (v0.9+)
|
||||
|
||||
**Guardian:**
|
||||
```bash
|
||||
# Automatically extract hardcodes to constants
|
||||
guardian fix ./src --auto
|
||||
|
||||
# Rename files to match conventions
|
||||
guardian fix naming ./src --auto
|
||||
|
||||
# Interactive mode
|
||||
guardian fix ./src --interactive
|
||||
```
|
||||
|
||||
**Competitors:**
|
||||
- ESLint has `--fix` but only for syntax
|
||||
- None fix architecture violations
|
||||
|
||||
### 7. 🎯 DDD Pattern Detection (30+)
|
||||
|
||||
**Guardian Roadmap:**
|
||||
- Aggregate boundaries
|
||||
- Anemic domain model
|
||||
- Domain events
|
||||
- Value Object immutability
|
||||
- CQRS violations
|
||||
- Saga pattern
|
||||
- Ubiquitous language
|
||||
- And 23+ more DDD patterns!
|
||||
|
||||
**Competitors:**
|
||||
- Generic architecture checks only
|
||||
- No DDD-specific patterns
|
||||
|
||||
---
|
||||
|
||||
## 📈 Detailed Tool Comparisons
|
||||
|
||||
## vs SonarQube
|
||||
|
||||
### When SonarQube Wins
|
||||
|
||||
✅ **Multi-language projects**
|
||||
```
|
||||
Java + Python + TypeScript → Use SonarQube
|
||||
TypeScript only → Consider Guardian
|
||||
```
|
||||
|
||||
✅ **Security-critical applications**
|
||||
```
|
||||
SonarQube: SAST, SCA, OWASP Top 10, CVE detection
|
||||
Guardian: Architecture only (security coming later)
|
||||
```
|
||||
|
||||
✅ **Large enterprise with compliance**
|
||||
```
|
||||
SonarQube: Compliance reports, audit trails, enterprise support
|
||||
Guardian: Lightweight, developer-focused
|
||||
```
|
||||
|
||||
✅ **Existing SonarQube investment**
|
||||
```
|
||||
Already using SonarQube? Add Guardian for DDD-specific checks
|
||||
```
|
||||
|
||||
### When Guardian Wins
|
||||
|
||||
✅ **TypeScript + AI coding workflow**
|
||||
```typescript
|
||||
// AI generates code → Guardian checks → AI fixes → Ship
|
||||
// 10x faster than manual review
|
||||
```
|
||||
|
||||
✅ **Clean Architecture / DDD enforcement**
|
||||
```typescript
|
||||
// Guardian understands DDD out-of-the-box
|
||||
// SonarQube requires custom rules
|
||||
```
|
||||
|
||||
✅ **Fast setup (< 5 minutes)**
|
||||
```bash
|
||||
npm install -g @samiyev/guardian
|
||||
guardian check ./src
|
||||
# Done! (vs hours of SonarQube setup)
|
||||
```
|
||||
|
||||
✅ **Hardcode detection with context**
|
||||
```typescript
|
||||
// Guardian knows the difference between:
|
||||
const port = 3000 // ❌ Should be constant
|
||||
const increment = 1 // ✅ Allowed (semantic)
|
||||
```
|
||||
|
||||
### Side-by-Side Example
|
||||
|
||||
**Scenario:** Detect hardcoded port in Express app
|
||||
|
||||
```typescript
|
||||
// src/server.ts
|
||||
app.listen(3000)
|
||||
```
|
||||
|
||||
**SonarQube:**
|
||||
```
|
||||
❌ No violation (not a secret)
|
||||
```
|
||||
|
||||
**Guardian:**
|
||||
```
|
||||
✅ Hardcode detected:
|
||||
Type: magic-number
|
||||
Value: 3000
|
||||
💡 Suggested: DEFAULT_PORT
|
||||
📁 Location: infrastructure/config/constants.ts
|
||||
🤖 AI Fix: "Extract 3000 to DEFAULT_PORT constant"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## vs dependency-cruiser
|
||||
|
||||
### When dependency-cruiser Wins
|
||||
|
||||
✅ **Visualization priority**
|
||||
```bash
|
||||
# Best-in-class dependency graphs
|
||||
depcruise src --output-type dot | dot -T svg > graph.svg
|
||||
```
|
||||
|
||||
✅ **Custom dependency rules**
|
||||
```javascript
|
||||
// Highly flexible rule system
|
||||
forbidden: [
|
||||
{
|
||||
from: { path: '^src/domain' },
|
||||
to: { path: '^src/infrastructure' }
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
✅ **Multi-framework support**
|
||||
```
|
||||
JS, TS, Vue, Svelte, JSX, CoffeeScript
|
||||
```
|
||||
|
||||
### When Guardian Wins
|
||||
|
||||
✅ **DDD/Clean Architecture out-of-the-box**
|
||||
```typescript
|
||||
// Guardian knows these patterns:
|
||||
// - Domain/Application/Infrastructure layers
|
||||
// - Entity exposure
|
||||
// - Repository pattern
|
||||
// - Framework leaks
|
||||
|
||||
// dependency-cruiser: Write custom rules for each
|
||||
```
|
||||
|
||||
✅ **Hardcode detection**
|
||||
```typescript
|
||||
// Guardian finds:
|
||||
setTimeout(() => {}, 5000) // Magic number
|
||||
const url = "http://..." // Magic string
|
||||
|
||||
// dependency-cruiser: Doesn't check this
|
||||
```
|
||||
|
||||
✅ **AI workflow integration**
|
||||
```bash
|
||||
guardian check ./src --format ai-prompt
|
||||
# Optimized for Claude/GPT
|
||||
|
||||
depcruise src
|
||||
# Generic output
|
||||
```
|
||||
|
||||
### Complementary Usage
|
||||
|
||||
**Best approach:** Use both!
|
||||
|
||||
```bash
|
||||
# Guardian for architecture + hardcode
|
||||
guardian check ./src
|
||||
|
||||
# dependency-cruiser for visualization
|
||||
depcruise src --output-type svg > architecture.svg
|
||||
```
|
||||
|
||||
**Coming in Guardian v0.7.0:**
|
||||
```bash
|
||||
# Guardian will have built-in visualization!
|
||||
guardian visualize ./src --output architecture.svg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## vs ArchUnit (Java)
|
||||
|
||||
### When ArchUnit Wins
|
||||
|
||||
✅ **Java projects**
|
||||
```java
|
||||
// ArchUnit is built for Java
|
||||
@ArchTest
|
||||
void domainShouldNotDependOnInfrastructure(JavaClasses classes) {
|
||||
noClasses().that().resideInPackage("..domain..")
|
||||
.should().dependOnClassesThat().resideInPackage("..infrastructure..")
|
||||
.check(classes);
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Test-based architecture validation**
|
||||
```java
|
||||
// Architecture rules = unit tests
|
||||
// Runs in your CI with other tests
|
||||
```
|
||||
|
||||
✅ **Mature Java ecosystem**
|
||||
```
|
||||
Spring Boot, Hibernate, JPA patterns
|
||||
Built-in rules for layered/onion architecture
|
||||
```
|
||||
|
||||
### When Guardian Wins
|
||||
|
||||
✅ **TypeScript/JavaScript projects**
|
||||
```typescript
|
||||
// Guardian is built for TypeScript
|
||||
// ArchUnit doesn't support TS
|
||||
```
|
||||
|
||||
✅ **AI coding workflow**
|
||||
```bash
|
||||
# Guardian → AI → Fix → Ship
|
||||
# ArchUnit is test-based (slower feedback)
|
||||
```
|
||||
|
||||
✅ **Zero-config DDD**
|
||||
```bash
|
||||
guardian check ./src
|
||||
# Works immediately with DDD structure
|
||||
|
||||
# ArchUnit requires writing tests for each rule
|
||||
```
|
||||
|
||||
### Philosophical Difference
|
||||
|
||||
**ArchUnit:**
|
||||
```java
|
||||
// Architecture = Tests
|
||||
// You write explicit tests for each rule
|
||||
```
|
||||
|
||||
**Guardian:**
|
||||
```bash
|
||||
# Architecture = Linter
|
||||
# Pre-configured DDD rules out-of-the-box
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## vs FTA (Fast TypeScript Analyzer)
|
||||
|
||||
### When FTA Wins
|
||||
|
||||
✅ **Complexity metrics focus**
|
||||
```bash
|
||||
# FTA provides:
|
||||
# - Cyclomatic complexity
|
||||
# - Halstead metrics
|
||||
# - Line counts
|
||||
# - Technical debt estimation
|
||||
```
|
||||
|
||||
✅ **Performance (Rust-based)**
|
||||
```
|
||||
FTA: 1600 files/second
|
||||
Guardian: ~500 files/second (Node.js)
|
||||
```
|
||||
|
||||
✅ **Simplicity**
|
||||
```bash
|
||||
# FTA does one thing well: metrics
|
||||
fta src/
|
||||
```
|
||||
|
||||
### When Guardian Wins
|
||||
|
||||
✅ **Architecture enforcement**
|
||||
```typescript
|
||||
// Guardian checks:
|
||||
// - Layer violations
|
||||
// - Framework leaks
|
||||
// - Circular dependencies
|
||||
// - Repository pattern
|
||||
|
||||
// FTA: Only measures complexity, no architecture checks
|
||||
```
|
||||
|
||||
✅ **Hardcode detection**
|
||||
```typescript
|
||||
// Guardian finds magic numbers/strings
|
||||
// FTA doesn't check this
|
||||
```
|
||||
|
||||
✅ **AI workflow**
|
||||
```bash
|
||||
# Guardian provides actionable suggestions
|
||||
# FTA provides metrics only
|
||||
```
|
||||
|
||||
### Complementary Usage
|
||||
|
||||
**Best approach:** Use both!
|
||||
|
||||
```bash
|
||||
# Guardian for architecture
|
||||
guardian check ./src
|
||||
|
||||
# FTA for complexity metrics
|
||||
fta src/ --threshold complexity:15
|
||||
```
|
||||
|
||||
**Coming in Guardian v0.10.0:**
|
||||
```bash
|
||||
# Guardian will include complexity metrics!
|
||||
guardian metrics ./src --include-complexity
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## vs ESLint + Plugins
|
||||
|
||||
### When ESLint Wins
|
||||
|
||||
✅ **General code quality**
|
||||
```javascript
|
||||
// Best for:
|
||||
// - Code style
|
||||
// - Common bugs
|
||||
// - TypeScript errors
|
||||
// - React/Vue specific rules
|
||||
```
|
||||
|
||||
✅ **Huge ecosystem**
|
||||
```bash
|
||||
# 10,000+ plugins
|
||||
eslint-plugin-react
|
||||
eslint-plugin-vue
|
||||
eslint-plugin-security
|
||||
# ...and many more
|
||||
```
|
||||
|
||||
✅ **Auto-fix for syntax**
|
||||
```bash
|
||||
eslint --fix
|
||||
# Fixes semicolons, quotes, formatting, etc.
|
||||
```
|
||||
|
||||
### When Guardian Wins
|
||||
|
||||
✅ **Architecture enforcement**
|
||||
```typescript
|
||||
// ESLint doesn't understand:
|
||||
// - Clean Architecture layers
|
||||
// - DDD patterns
|
||||
// - Framework leaks
|
||||
// - Entity exposure
|
||||
|
||||
// Guardian does!
|
||||
```
|
||||
|
||||
✅ **Hardcode detection with context**
|
||||
```typescript
|
||||
// ESLint plugins check patterns
|
||||
// Guardian understands semantic context
|
||||
```
|
||||
|
||||
✅ **AI workflow integration**
|
||||
```bash
|
||||
# Guardian optimized for AI assistants
|
||||
# ESLint generic output
|
||||
```
|
||||
|
||||
### Complementary Usage
|
||||
|
||||
**Best approach:** Use both!
|
||||
|
||||
```bash
|
||||
# ESLint for code quality
|
||||
eslint src/
|
||||
|
||||
# Guardian for architecture
|
||||
guardian check ./src
|
||||
```
|
||||
|
||||
**Many teams run both in CI:**
|
||||
```yaml
|
||||
# .github/workflows/quality.yml
|
||||
- name: ESLint
|
||||
run: npm run lint
|
||||
|
||||
- name: Guardian
|
||||
run: guardian check ./src --fail-on error
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## vs import-linter (Python)
|
||||
|
||||
### When import-linter Wins
|
||||
|
||||
✅ **Python projects**
|
||||
```ini
|
||||
# .importlinter
|
||||
[importlinter]
|
||||
root_package = myproject
|
||||
|
||||
[importlinter:contract:1]
|
||||
name = Layers contract
|
||||
type = layers
|
||||
layers =
|
||||
myproject.domain
|
||||
myproject.application
|
||||
myproject.infrastructure
|
||||
```
|
||||
|
||||
✅ **Mature Python ecosystem**
|
||||
```python
|
||||
# Django, Flask, FastAPI integration
|
||||
```
|
||||
|
||||
### When Guardian Wins
|
||||
|
||||
✅ **TypeScript/JavaScript**
|
||||
```typescript
|
||||
// Guardian is for TS/JS
|
||||
// import-linter is Python-only
|
||||
```
|
||||
|
||||
✅ **More than import checking**
|
||||
```typescript
|
||||
// Guardian checks:
|
||||
// - Hardcode
|
||||
// - Entity exposure
|
||||
// - Repository pattern
|
||||
// - Framework leaks
|
||||
|
||||
// import-linter: Only imports
|
||||
```
|
||||
|
||||
### Future Integration
|
||||
|
||||
**Guardian v2.0+ (Planned):**
|
||||
```bash
|
||||
# Multi-language support coming
|
||||
guardian check ./python-src --language python
|
||||
guardian check ./ts-src --language typescript
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💰 Cost Comparison
|
||||
|
||||
| Tool | Free Tier | Paid Plans | Enterprise |
|
||||
|------|-----------|------------|------------|
|
||||
| **Guardian** | ✅ MIT License (100% free) | - | - |
|
||||
| **SonarQube** | ✅ Community Edition | Developer: $150/yr | Custom pricing |
|
||||
| **dependency-cruiser** | ✅ MIT License | - | - |
|
||||
| **ArchUnit** | ✅ Apache 2.0 | - | - |
|
||||
| **FTA** | ✅ Open Source | - | - |
|
||||
| **ESLint** | ✅ MIT License | - | - |
|
||||
|
||||
**Guardian will always be free and open-source (MIT License)**
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Setup Time Comparison
|
||||
|
||||
| Tool | Setup Time | Configuration Required |
|
||||
|------|------------|------------------------|
|
||||
| **Guardian** | ⚡ 2 minutes | ❌ Zero-config (DDD) |
|
||||
| **SonarQube** | 🐌 2-4 hours | ✅ Extensive setup |
|
||||
| **dependency-cruiser** | ⚡ 5 minutes | ⚠️ Rules configuration |
|
||||
| **ArchUnit** | ⚙️ 30 minutes | ✅ Write test rules |
|
||||
| **FTA** | ⚡ 1 minute | ❌ Zero-config |
|
||||
| **ESLint** | ⚡ 10 minutes | ⚠️ Plugin configuration |
|
||||
|
||||
**Guardian Setup:**
|
||||
```bash
|
||||
# 1. Install (30 seconds)
|
||||
npm install -g @samiyev/guardian
|
||||
|
||||
# 2. Run (90 seconds)
|
||||
cd your-project
|
||||
guardian check ./src
|
||||
|
||||
# Done! 🎉
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Real-World Performance
|
||||
|
||||
### Analysis Speed (1000 TypeScript files)
|
||||
|
||||
| Tool | Time | Notes |
|
||||
|------|------|-------|
|
||||
| **FTA** | ~0.6s | ⚡ Fastest (Rust) |
|
||||
| **Guardian** | ~2s | Fast (Node.js, tree-sitter) |
|
||||
| **dependency-cruiser** | ~3s | Fast |
|
||||
| **ESLint** | ~5s | Depends on rules |
|
||||
| **SonarQube** | ~15s | Slower (comprehensive) |
|
||||
|
||||
### Memory Usage
|
||||
|
||||
| Tool | RAM | Notes |
|
||||
|------|-----|-------|
|
||||
| **Guardian** | ~150MB | Efficient |
|
||||
| **FTA** | ~50MB | Minimal (Rust) |
|
||||
| **dependency-cruiser** | ~200MB | Moderate |
|
||||
| **ESLint** | ~300MB | Varies by plugins |
|
||||
| **SonarQube** | ~2GB | Heavy (server) |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Use Case Recommendations
|
||||
|
||||
### Scenario 1: TypeScript Startup Using AI Coding
|
||||
|
||||
**Best Stack:**
|
||||
```bash
|
||||
✅ Guardian (architecture + hardcode)
|
||||
✅ ESLint (code quality)
|
||||
✅ Prettier (formatting)
|
||||
```
|
||||
|
||||
**Why:**
|
||||
- Fast setup
|
||||
- AI workflow integration
|
||||
- Zero-config DDD
|
||||
- Catches AI mistakes (hardcode)
|
||||
|
||||
### Scenario 2: Enterprise Multi-Language
|
||||
|
||||
**Best Stack:**
|
||||
```bash
|
||||
✅ SonarQube (security + multi-language)
|
||||
✅ Guardian (TypeScript DDD specialization)
|
||||
✅ ArchUnit (Java architecture)
|
||||
```
|
||||
|
||||
**Why:**
|
||||
- Comprehensive coverage
|
||||
- Security scanning
|
||||
- Language-specific depth
|
||||
|
||||
### Scenario 3: Clean Architecture Refactoring
|
||||
|
||||
**Best Stack:**
|
||||
```bash
|
||||
✅ Guardian (architecture enforcement)
|
||||
✅ dependency-cruiser (visualization)
|
||||
✅ Guardian v0.9+ (auto-fix)
|
||||
```
|
||||
|
||||
**Why:**
|
||||
- Visualize current state
|
||||
- Detect violations
|
||||
- Auto-fix issues
|
||||
|
||||
### Scenario 4: Python + TypeScript Monorepo
|
||||
|
||||
**Best Stack:**
|
||||
```bash
|
||||
✅ Guardian (TypeScript)
|
||||
✅ import-linter (Python)
|
||||
✅ SonarQube (security, both languages)
|
||||
```
|
||||
|
||||
**Why:**
|
||||
- Language-specific depth
|
||||
- Unified security scanning
|
||||
|
||||
---
|
||||
|
||||
## 🏆 Winner by Category
|
||||
|
||||
| Category | Winner | Runner-up |
|
||||
|----------|--------|-----------|
|
||||
| **TypeScript Architecture** | 🥇 Guardian | dependency-cruiser |
|
||||
| **Multi-Language** | 🥇 SonarQube | - |
|
||||
| **Visualization** | 🥇 dependency-cruiser | SonarQube |
|
||||
| **AI Workflow** | 🥇 Guardian | - (no competitor) |
|
||||
| **Security** | 🥇 SonarQube | - |
|
||||
| **Hardcode Detection** | 🥇 Guardian | - (no competitor) |
|
||||
| **DDD Patterns** | 🥇 Guardian | ArchUnit (Java) |
|
||||
| **Auto-Fix** | 🥇 ESLint (syntax) | Guardian v0.9+ (architecture) |
|
||||
| **Complexity Metrics** | 🥇 FTA | SonarQube |
|
||||
| **Setup Speed** | 🥇 FTA | Guardian |
|
||||
|
||||
---
|
||||
|
||||
## 🔮 Future Roadmap Comparison
|
||||
|
||||
### Guardian v1.0.0 (Q4 2026)
|
||||
- ✅ Configuration & presets (v0.6)
|
||||
- ✅ Visualization (v0.7)
|
||||
- ✅ CI/CD kit (v0.8)
|
||||
- ✅ Auto-fix (v0.9) **UNIQUE!**
|
||||
- ✅ Metrics dashboard (v0.10)
|
||||
- ✅ 30+ DDD patterns (v0.11-v0.32)
|
||||
- ✅ VS Code extension
|
||||
- ✅ JetBrains plugin
|
||||
|
||||
### Competitors
|
||||
- **SonarQube**: Incremental improvements, AI-powered fixes (experimental)
|
||||
- **dependency-cruiser**: Stable, no major changes planned
|
||||
- **ArchUnit**: Java focus, incremental improvements
|
||||
- **FTA**: Adding more metrics
|
||||
- **ESLint**: Flat config, performance improvements
|
||||
|
||||
**Guardian's Advantage:** Only tool actively expanding DDD/architecture detection
|
||||
|
||||
---
|
||||
|
||||
## 💡 Migration Guides
|
||||
|
||||
### From SonarQube to Guardian
|
||||
|
||||
**When to migrate:**
|
||||
- TypeScript-only project
|
||||
- Want faster iteration
|
||||
- Need DDD-specific checks
|
||||
- Don't need multi-language/security
|
||||
|
||||
**How to migrate:**
|
||||
```bash
|
||||
# Keep SonarQube for security
|
||||
# Add Guardian for architecture
|
||||
npm install -g @samiyev/guardian
|
||||
guardian check ./src
|
||||
|
||||
# CI/CD: Run both
|
||||
# SonarQube (security) → Guardian (architecture)
|
||||
```
|
||||
|
||||
### From ESLint-only to ESLint + Guardian
|
||||
|
||||
**Why add Guardian:**
|
||||
```typescript
|
||||
// ESLint checks syntax
|
||||
// Guardian checks architecture
|
||||
```
|
||||
|
||||
**How to add:**
|
||||
```bash
|
||||
# Keep ESLint
|
||||
npm run lint
|
||||
|
||||
# Add Guardian
|
||||
guardian check ./src
|
||||
|
||||
# Both in CI:
|
||||
npm run lint && guardian check ./src
|
||||
```
|
||||
|
||||
### From dependency-cruiser to Guardian
|
||||
|
||||
**Why migrate:**
|
||||
- Need more than circular deps
|
||||
- Want hardcode detection
|
||||
- Need DDD patterns
|
||||
- Want auto-fix (v0.9+)
|
||||
|
||||
**How to migrate:**
|
||||
```bash
|
||||
# Replace:
|
||||
depcruise src --config .dependency-cruiser.js
|
||||
|
||||
# With:
|
||||
guardian check ./src
|
||||
|
||||
# Or keep both:
|
||||
# dependency-cruiser → visualization
|
||||
# Guardian → architecture + hardcode
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
### Guardian
|
||||
- [GitHub Repository](https://github.com/samiyev/puaros)
|
||||
- [Documentation](https://puaros.ailabs.uz)
|
||||
- [npm Package](https://www.npmjs.com/package/@samiyev/guardian)
|
||||
|
||||
### Competitors
|
||||
- [SonarQube](https://www.sonarsource.com/products/sonarqube/)
|
||||
- [dependency-cruiser](https://github.com/sverweij/dependency-cruiser)
|
||||
- [ArchUnit](https://www.archunit.org/)
|
||||
- [FTA](https://ftaproject.dev/)
|
||||
- [import-linter](https://import-linter.readthedocs.io/)
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Community & Support
|
||||
|
||||
| Tool | Community | Support |
|
||||
|------|-----------|---------|
|
||||
| **Guardian** | GitHub Issues | Community (planned: Discord) |
|
||||
| **SonarQube** | Community Forum | Commercial support available |
|
||||
| **dependency-cruiser** | GitHub Issues | Community |
|
||||
| **ArchUnit** | GitHub Issues | Community |
|
||||
| **ESLint** | Discord, Twitter | Community |
|
||||
|
||||
---
|
||||
|
||||
**Guardian's Position in the Market:**
|
||||
|
||||
> **"The AI-First Architecture Guardian for TypeScript teams practicing DDD/Clean Architecture"**
|
||||
|
||||
**Guardian is NOT:**
|
||||
- ❌ A replacement for SonarQube's security scanning
|
||||
- ❌ A replacement for ESLint's code quality checks
|
||||
- ❌ A multi-language tool (yet)
|
||||
|
||||
**Guardian IS:**
|
||||
- ✅ The best tool for TypeScript DDD/Clean Architecture
|
||||
- ✅ The only tool optimized for AI-assisted coding
|
||||
- ✅ The only tool with intelligent hardcode detection
|
||||
- ✅ The only tool with auto-fix for architecture (v0.9+)
|
||||
|
||||
---
|
||||
|
||||
**Questions? Feedback?**
|
||||
|
||||
- 📧 Email: fozilbek.samiyev@gmail.com
|
||||
- 🐙 GitHub: https://github.com/samiyev/puaros/issues
|
||||
- 🌐 Website: https://puaros.ailabs.uz
|
||||
323
packages/guardian/COMPETITIVE_ANALYSIS_SUMMARY.md
Normal file
323
packages/guardian/COMPETITIVE_ANALYSIS_SUMMARY.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# Competitive Analysis & Roadmap - Summary
|
||||
|
||||
**Date:** 2025-01-24
|
||||
**Prepared for:** Puaros Guardian
|
||||
**Documents Created:**
|
||||
1. ROADMAP_NEW.md - Updated roadmap with reprioritized features
|
||||
2. COMPARISON.md - Comprehensive competitor comparison
|
||||
3. docs/v0.6.0-CONFIGURATION-SPEC.md - Configuration feature specification
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Executive Summary
|
||||
|
||||
Guardian has **5 unique features** that no competitor offers, positioning it as the **only tool built for AI-assisted DDD/Clean Architecture development**. However, to achieve enterprise adoption, we need to first match competitors' baseline features (configuration, visualization, CI/CD, metrics).
|
||||
|
||||
### Current Position (v0.5.1)
|
||||
|
||||
**Strengths:**
|
||||
- ✅ Hardcode detection with AI suggestions (UNIQUE)
|
||||
- ✅ Framework leak detection (UNIQUE)
|
||||
- ✅ Entity exposure detection (UNIQUE)
|
||||
- ✅ Repository pattern validation (UNIQUE)
|
||||
- ✅ DDD-specific naming conventions (UNIQUE)
|
||||
|
||||
**Gaps:**
|
||||
- ❌ No configuration file support
|
||||
- ❌ No visualization/graphs
|
||||
- ❌ No ready-to-use CI/CD templates
|
||||
- ❌ No metrics/quality score
|
||||
- ❌ No auto-fix capabilities
|
||||
|
||||
---
|
||||
|
||||
## 📊 Competitive Landscape
|
||||
|
||||
### Main Competitors
|
||||
|
||||
| Tool | Strength | Weakness | Market Position |
|
||||
|------|----------|----------|-----------------|
|
||||
| **SonarQube** | Multi-language + Security | Complex setup, expensive | Enterprise leader |
|
||||
| **dependency-cruiser** | Best visualization | No hardcode/DDD | Dependency specialist |
|
||||
| **ArchUnit** | Java architecture | Java-only | Java ecosystem |
|
||||
| **FTA** | Fast metrics (Rust) | No architecture checks | Metrics tool |
|
||||
| **ESLint** | Huge ecosystem | No architecture | Code quality standard |
|
||||
|
||||
### Guardian's Unique Position
|
||||
|
||||
> **"The AI-First Architecture Guardian for TypeScript teams practicing DDD/Clean Architecture"**
|
||||
|
||||
**Market Gap Filled:**
|
||||
- No tool optimizes for AI-assisted coding workflow
|
||||
- No tool deeply understands DDD patterns (except ArchUnit for Java)
|
||||
- No tool combines hardcode detection + architecture enforcement
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Strategic Roadmap
|
||||
|
||||
### Phase 1: Market Parity (v0.6-v0.10) - Q1-Q2 2026
|
||||
|
||||
**Goal:** Match competitors' baseline features
|
||||
|
||||
| Version | Feature | Why Critical | Competitor |
|
||||
|---------|---------|--------------|------------|
|
||||
| v0.6.0 | Configuration & Presets | All competitors have this | ESLint, SonarQube |
|
||||
| v0.7.0 | Visualization | dependency-cruiser's main advantage | dependency-cruiser |
|
||||
| v0.8.0 | CI/CD Integration Kit | Enterprise requirement | SonarQube |
|
||||
| v0.9.0 | **Auto-Fix (UNIQUE!)** | Game-changer, no one has this | None |
|
||||
| v0.10.0 | Metrics & Quality Score | Enterprise adoption | SonarQube |
|
||||
|
||||
**After v0.10.0:** Guardian competes with SonarQube/dependency-cruiser on features
|
||||
|
||||
### Phase 2: DDD Specialization (v0.11-v0.32) - Q3-Q4 2026
|
||||
|
||||
**Goal:** Deepen DDD/Clean Architecture expertise
|
||||
|
||||
30+ DDD pattern detectors:
|
||||
- Aggregate boundaries
|
||||
- Anemic domain model
|
||||
- Domain events
|
||||
- Value Object immutability
|
||||
- CQRS validation
|
||||
- Saga pattern
|
||||
- Anti-Corruption Layer
|
||||
- Ubiquitous Language
|
||||
- And 22+ more...
|
||||
|
||||
**After Phase 2:** Guardian = THE tool for DDD/Clean Architecture
|
||||
|
||||
### Phase 3: Enterprise Ecosystem (v1.0+) - Q4 2026+
|
||||
|
||||
**Goal:** Full enterprise platform
|
||||
|
||||
- VS Code extension
|
||||
- JetBrains plugin
|
||||
- Web dashboard
|
||||
- Team analytics
|
||||
- Multi-language support (Python, C#, Java)
|
||||
|
||||
---
|
||||
|
||||
## 🔥 Critical Changes to Current Roadmap
|
||||
|
||||
### Old Roadmap Issues
|
||||
|
||||
❌ **v0.6.0 was "Aggregate Boundaries"** → Too early for DDD-specific features
|
||||
❌ **v0.12.0 was "Configuration"** → Way too late! Critical feature postponed
|
||||
❌ **Missing:** Visualization, CI/CD, Auto-fix, Metrics
|
||||
❌ **Too many consecutive DDD features** → Need market parity first
|
||||
|
||||
### New Roadmap Priorities
|
||||
|
||||
✅ **v0.6.0 = Configuration (MOVED UP)** → Critical for adoption
|
||||
✅ **v0.7.0 = Visualization (NEW)** → Compete with dependency-cruiser
|
||||
✅ **v0.8.0 = CI/CD Kit (NEW)** → Enterprise requirement
|
||||
✅ **v0.9.0 = Auto-Fix (NEW, UNIQUE!)** → Game-changing differentiator
|
||||
✅ **v0.10.0 = Metrics (NEW)** → Compete with SonarQube
|
||||
✅ **v0.11+ = DDD Features** → After market parity
|
||||
|
||||
---
|
||||
|
||||
## 💡 Key Recommendations
|
||||
|
||||
### Immediate Actions (Next 2 Weeks)
|
||||
|
||||
1. **Review & Approve New Roadmap**
|
||||
- Read ROADMAP_NEW.md
|
||||
- Approve priority changes
|
||||
- Create GitHub milestones
|
||||
|
||||
2. **Start v0.6.0 Configuration**
|
||||
- Read v0.6.0-CONFIGURATION-SPEC.md
|
||||
- Create implementation tasks
|
||||
- Start Phase 1 development
|
||||
|
||||
3. **Update Documentation**
|
||||
- Update main README.md with comparison table
|
||||
- Add "Guardian vs Competitors" section
|
||||
- Link to COMPARISON.md
|
||||
|
||||
### Next 3 Months (Q1 2026)
|
||||
|
||||
4. **Complete v0.6.0 (Configuration)**
|
||||
- 8-week timeline
|
||||
- Beta test with community
|
||||
- Stable release
|
||||
|
||||
5. **Start v0.7.0 (Visualization)**
|
||||
- Design graph system
|
||||
- Choose visualization library
|
||||
- Prototype SVG/Mermaid output
|
||||
|
||||
6. **Marketing & Positioning**
|
||||
- Create comparison blog post
|
||||
- Submit to Product Hunt
|
||||
- Share on Reddit/HackerNews
|
||||
|
||||
### Next 6 Months (Q1-Q2 2026)
|
||||
|
||||
7. **Complete Market Parity (v0.6-v0.10)**
|
||||
- Configuration ✅
|
||||
- Visualization ✅
|
||||
- CI/CD Integration ✅
|
||||
- Auto-Fix ✅ (UNIQUE!)
|
||||
- Metrics ✅
|
||||
|
||||
8. **Community Growth**
|
||||
- 1000+ GitHub stars
|
||||
- 100+ weekly npm installs
|
||||
- 10+ enterprise adopters
|
||||
|
||||
---
|
||||
|
||||
## 📈 Success Metrics
|
||||
|
||||
### v0.10.0 (Market Parity Achieved) - June 2026
|
||||
|
||||
**Feature Parity:**
|
||||
- ✅ Configuration support (compete with ESLint)
|
||||
- ✅ Visualization (compete with dependency-cruiser)
|
||||
- ✅ CI/CD integration (compete with SonarQube)
|
||||
- ✅ Auto-fix (UNIQUE! Game-changer)
|
||||
- ✅ Metrics dashboard (compete with SonarQube)
|
||||
|
||||
**Adoption Metrics:**
|
||||
- 1,000+ GitHub stars
|
||||
- 100+ weekly npm installs
|
||||
- 50+ projects with guardian.config.js
|
||||
- 10+ enterprise teams
|
||||
|
||||
### v1.0.0 (Enterprise Ready) - December 2026
|
||||
|
||||
**Feature Completeness:**
|
||||
- ✅ All baseline features
|
||||
- ✅ 30+ DDD pattern detectors
|
||||
- ✅ IDE extensions (VS Code, JetBrains)
|
||||
- ✅ Web dashboard
|
||||
- ✅ Team analytics
|
||||
|
||||
**Market Position:**
|
||||
- #1 tool for TypeScript DDD/Clean Architecture
|
||||
- Top 3 in static analysis for TypeScript
|
||||
- Known in enterprise as "the AI code reviewer"
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Positioning Strategy
|
||||
|
||||
### Target Segments
|
||||
|
||||
1. **Primary:** TypeScript developers using AI coding assistants (GitHub Copilot, Cursor, Windsurf, Claude, ChatGPT, Cline)
|
||||
2. **Secondary:** Teams implementing DDD/Clean Architecture
|
||||
3. **Tertiary:** Startups/scale-ups needing fast quality enforcement
|
||||
|
||||
### Messaging
|
||||
|
||||
**Tagline:** "The AI-First Architecture Guardian"
|
||||
|
||||
**Key Messages:**
|
||||
- "Catches the #1 AI mistake: hardcoded values everywhere"
|
||||
- "Enforces Clean Architecture that AI often ignores"
|
||||
- "Closes the AI feedback loop for cleaner code"
|
||||
- "The only tool with auto-fix for architecture" (v0.9+)
|
||||
|
||||
### Differentiation
|
||||
|
||||
**Guardian ≠ SonarQube:** We're specialized for TypeScript DDD, not multi-language security
|
||||
**Guardian ≠ dependency-cruiser:** We detect patterns, not just dependencies
|
||||
**Guardian ≠ ESLint:** We enforce architecture, not syntax
|
||||
|
||||
**Guardian = ESLint for architecture + AI code reviewer**
|
||||
|
||||
---
|
||||
|
||||
## 📚 Document Guide
|
||||
|
||||
### ROADMAP_NEW.md
|
||||
|
||||
**Purpose:** Complete technical roadmap with reprioritized features
|
||||
**Audience:** Development team, contributors
|
||||
**Key Sections:**
|
||||
- Current state analysis
|
||||
- Phase 1: Market Parity (v0.6-v0.10)
|
||||
- Phase 2: DDD Specialization (v0.11-v0.32)
|
||||
- Phase 3: Enterprise Ecosystem (v1.0+)
|
||||
|
||||
### COMPARISON.md
|
||||
|
||||
**Purpose:** Marketing-focused comparison with all competitors
|
||||
**Audience:** Users, potential adopters, marketing
|
||||
**Key Sections:**
|
||||
- Feature comparison matrix
|
||||
- Detailed tool comparisons
|
||||
- When to use each tool
|
||||
- Use case recommendations
|
||||
- Winner by category
|
||||
|
||||
### v0.6.0-CONFIGURATION-SPEC.md
|
||||
|
||||
**Purpose:** Technical specification for Configuration feature
|
||||
**Audience:** Development team
|
||||
**Key Sections:**
|
||||
- Configuration file format
|
||||
- Preset system design
|
||||
- Rule configuration
|
||||
- Implementation plan (8 weeks)
|
||||
- Testing strategy
|
||||
|
||||
---
|
||||
|
||||
## 🎬 Next Steps
|
||||
|
||||
### Week 1-2: Planning & Kickoff
|
||||
|
||||
- [ ] Review all three documents
|
||||
- [ ] Approve new roadmap priorities
|
||||
- [ ] Create GitHub milestones for v0.6.0-v0.10.0
|
||||
- [ ] Create implementation issues for v0.6.0
|
||||
- [ ] Update main README.md with comparison table
|
||||
|
||||
### Week 3-10: v0.6.0 Development
|
||||
|
||||
- [ ] Phase 1: Core Configuration (Week 3-4)
|
||||
- [ ] Phase 2: Rule Configuration (Week 4-5)
|
||||
- [ ] Phase 3: Preset System (Week 5-6)
|
||||
- [ ] Phase 4: Ignore Patterns (Week 6-7)
|
||||
- [ ] Phase 5: CLI Integration (Week 7-8)
|
||||
- [ ] Phase 6: Documentation (Week 8-9)
|
||||
- [ ] Phase 7: Beta & Release (Week 9-10)
|
||||
|
||||
### Post-v0.6.0
|
||||
|
||||
- [ ] Start v0.7.0 (Visualization) planning
|
||||
- [ ] Marketing push (blog, Product Hunt, etc.)
|
||||
- [ ] Community feedback gathering
|
||||
|
||||
---
|
||||
|
||||
## ❓ Questions?
|
||||
|
||||
**For technical questions:**
|
||||
- Email: fozilbek.samiyev@gmail.com
|
||||
- GitHub Issues: https://github.com/samiyev/puaros/issues
|
||||
|
||||
**For strategic decisions:**
|
||||
- Review sessions: Schedule with team
|
||||
- Roadmap adjustments: Create GitHub discussion
|
||||
|
||||
---
|
||||
|
||||
## 📝 Changelog
|
||||
|
||||
**2025-01-24:** Initial competitive analysis and roadmap revision
|
||||
- Created comprehensive competitor comparison
|
||||
- Reprioritized roadmap (Configuration moved to v0.6.0)
|
||||
- Added market parity phase (v0.6-v0.10)
|
||||
- Designed v0.6.0 Configuration specification
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ Analysis complete, ready for implementation
|
||||
|
||||
**Confidence Level:** HIGH - Analysis based on thorough competitor research and market positioning
|
||||
@@ -72,6 +72,15 @@ Code quality guardian for vibe coders and enterprise teams - because AI writes f
|
||||
- Prevents "new Repository()" anti-pattern
|
||||
- 📚 *Based on: Martin Fowler's Repository Pattern, DDD (Evans 2003)* → [Why?](./docs/WHY.md#repository-pattern)
|
||||
|
||||
🔒 **Aggregate Boundary Validation** ✨ NEW
|
||||
- Detects direct entity references across DDD aggregates
|
||||
- Enforces reference-by-ID or Value Object pattern
|
||||
- Prevents tight coupling between aggregates
|
||||
- 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)
|
||||
|
||||
🏗️ **Clean Architecture Enforcement**
|
||||
- Built with DDD principles
|
||||
- Layered architecture (Domain, Application, Infrastructure)
|
||||
|
||||
@@ -256,11 +256,10 @@ Internal refactoring to eliminate hardcoded values and improve maintainability:
|
||||
|
||||
---
|
||||
|
||||
## Future Roadmap
|
||||
## Version 0.7.0 - Aggregate Boundary Validation 🔒 ✅ RELEASED
|
||||
|
||||
### Version 0.6.0 - Aggregate Boundary Validation 🔒
|
||||
**Target:** Q1 2026
|
||||
**Priority:** MEDIUM
|
||||
**Released:** 2025-11-24
|
||||
**Priority:** CRITICAL
|
||||
|
||||
Validate aggregate boundaries in DDD:
|
||||
|
||||
@@ -286,12 +285,19 @@ class Order {
|
||||
}
|
||||
```
|
||||
|
||||
**Planned Features:**
|
||||
- Detect entity references across aggregates
|
||||
- Allow only ID or Value Object references
|
||||
- Detect circular dependencies between aggregates
|
||||
- Validate aggregate root access patterns
|
||||
- Support for aggregate folder structure
|
||||
**Implemented Features:**
|
||||
- ✅ Detect entity references across aggregates
|
||||
- ✅ Allow only ID or Value Object references from other aggregates
|
||||
- ✅ Filter allowed imports (value-objects, events, repositories, services)
|
||||
- ✅ Support for multiple aggregate folder structures (domain/aggregates/name, domain/name, domain/entities/name)
|
||||
- ✅ 41 comprehensive tests with 100% pass rate
|
||||
- ✅ Examples of good and bad patterns
|
||||
- ✅ CLI output with 🔒 icon and detailed violation info
|
||||
- ✅ Critical severity level for aggregate boundary violations
|
||||
|
||||
---
|
||||
|
||||
## Future Roadmap
|
||||
|
||||
---
|
||||
|
||||
|
||||
906
packages/guardian/ROADMAP_NEW.md
Normal file
906
packages/guardian/ROADMAP_NEW.md
Normal file
@@ -0,0 +1,906 @@
|
||||
# Guardian Roadmap 🗺️
|
||||
|
||||
**Last Updated:** 2025-01-24
|
||||
**Current Version:** 0.5.1
|
||||
|
||||
This document outlines the current features and strategic roadmap for @puaros/guardian, prioritized based on market competition analysis and enterprise adoption requirements.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Current State (v0.5.1) ✅
|
||||
|
||||
### ✨ Unique Competitive Advantages
|
||||
|
||||
Guardian currently has **5 unique features** that competitors don't offer:
|
||||
|
||||
| Feature | Status | Competitors |
|
||||
|---------|--------|-------------|
|
||||
| **Hardcode Detection + AI Suggestions** | ✅ Released | ❌ None |
|
||||
| **Framework Leak Detection** | ✅ Released | ❌ None |
|
||||
| **Entity Exposure Detection** | ✅ Released (v0.3.0) | ❌ None |
|
||||
| **Dependency Direction Enforcement** | ✅ Released (v0.4.0) | ⚠️ dependency-cruiser (via rules) |
|
||||
| **Repository Pattern Validation** | ✅ Released (v0.5.0) | ❌ None |
|
||||
|
||||
### 🛠️ Core Features (v0.1.0-v0.5.0)
|
||||
|
||||
**Detection Capabilities:**
|
||||
- ✅ Hardcode detection (magic numbers, magic strings) with smart suggestions
|
||||
- ✅ Circular dependency detection
|
||||
- ✅ Naming convention enforcement (DDD layer-based rules)
|
||||
- ✅ Clean Architecture layer violations
|
||||
- ✅ Framework leak detection (domain importing frameworks)
|
||||
- ✅ Entity exposure in API responses (v0.3.0)
|
||||
- ✅ Dependency direction validation (v0.4.0)
|
||||
- ✅ Repository pattern validation (v0.5.0)
|
||||
|
||||
**Developer Experience:**
|
||||
- ✅ 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
|
||||
|
||||
**Quality & Testing:**
|
||||
- ✅ 194 tests across 7 test files (all passing)
|
||||
- ✅ 80%+ code coverage on all metrics
|
||||
- ✅ Self-analysis: 0 violations (100% clean codebase)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Strategic Roadmap Overview
|
||||
|
||||
### Phase 1: Market Parity (v0.6-v0.10) - Q1-Q2 2026
|
||||
**Goal:** Match competitors' baseline features to enable enterprise adoption
|
||||
|
||||
- Configuration & Presets
|
||||
- Visualization & Dependency Graphs
|
||||
- CI/CD Integration Kit
|
||||
- Auto-Fix & Code Generation (UNIQUE!)
|
||||
- Metrics & Quality Score
|
||||
|
||||
### Phase 2: DDD Specialization (v0.11-v0.27) - Q3-Q4 2026
|
||||
**Goal:** Deepen DDD/Clean Architecture expertise
|
||||
|
||||
- Advanced DDD pattern detection (25+ features)
|
||||
- Aggregate boundaries, Domain Events, Value Objects
|
||||
- CQRS, Saga Pattern, Anti-Corruption Layer
|
||||
- Ubiquitous Language validation
|
||||
|
||||
### Phase 3: Enterprise Ecosystem (v1.0+) - Q4 2026+
|
||||
**Goal:** Full-featured enterprise platform
|
||||
|
||||
- VS Code extension
|
||||
- JetBrains plugin
|
||||
- Web dashboard
|
||||
- Team analytics
|
||||
- Multi-language support
|
||||
|
||||
---
|
||||
|
||||
## 📅 Detailed Roadmap
|
||||
|
||||
## Version 0.6.0 - Configuration & Presets ⚙️
|
||||
**Target:** Q1 2026 (January-February)
|
||||
**Priority:** 🔥 CRITICAL
|
||||
|
||||
> **Why Critical:** All competitors (SonarQube, ESLint, dependency-cruiser) have configuration. Without this, Guardian cannot be customized for different teams/projects.
|
||||
|
||||
### Features
|
||||
|
||||
#### 1. Configuration File Support
|
||||
|
||||
```javascript
|
||||
// guardian.config.js (primary)
|
||||
export default {
|
||||
// Zero-config presets
|
||||
preset: 'clean-architecture', // or 'ddd', 'hexagonal', 'onion'
|
||||
|
||||
// Rule configuration
|
||||
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',
|
||||
'dependency-direction': 'error',
|
||||
'repository-pattern': 'error',
|
||||
},
|
||||
|
||||
// Custom layer paths
|
||||
layers: {
|
||||
domain: 'src/core/domain',
|
||||
application: 'src/core/application',
|
||||
infrastructure: 'src/adapters',
|
||||
shared: 'src/shared',
|
||||
},
|
||||
|
||||
// Exclusions
|
||||
exclude: [
|
||||
'**/*.test.ts',
|
||||
'**/*.spec.ts',
|
||||
'scripts/',
|
||||
'migrations/',
|
||||
'node_modules/',
|
||||
],
|
||||
|
||||
// Per-rule ignores
|
||||
ignore: {
|
||||
'hardcode/magic-numbers': {
|
||||
'src/config/constants.ts': [3000, 8080],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Built-in Presets
|
||||
|
||||
```javascript
|
||||
// Preset: clean-architecture (default)
|
||||
preset: 'clean-architecture'
|
||||
// Enables: layer-violation, dependency-direction, naming-convention
|
||||
|
||||
// Preset: ddd
|
||||
preset: 'ddd'
|
||||
// Enables all DDD patterns: aggregates, value-objects, domain-events
|
||||
|
||||
// Preset: hexagonal (Ports & Adapters)
|
||||
preset: 'hexagonal'
|
||||
// Validates port/adapter separation
|
||||
|
||||
// Preset: minimal (for prototyping)
|
||||
preset: 'minimal'
|
||||
// Only critical rules: hardcode, circular-deps
|
||||
```
|
||||
|
||||
#### 3. Framework-Specific Presets
|
||||
|
||||
```javascript
|
||||
// NestJS
|
||||
preset: 'nestjs-clean-architecture'
|
||||
|
||||
// Express
|
||||
preset: 'express-clean-architecture'
|
||||
|
||||
// Next.js
|
||||
preset: 'nextjs-clean-architecture'
|
||||
```
|
||||
|
||||
#### 4. Configuration Discovery
|
||||
|
||||
Support multiple config file formats:
|
||||
- `guardian.config.js` (ES modules)
|
||||
- `guardian.config.cjs` (CommonJS)
|
||||
- `.guardianrc` (JSON)
|
||||
- `.guardianrc.json`
|
||||
- `package.json` (`guardian` field)
|
||||
|
||||
#### 5. CLI Override
|
||||
|
||||
```bash
|
||||
# Override config from CLI
|
||||
guardian check ./src --rule hardcode/magic-numbers=off
|
||||
|
||||
# Use specific config file
|
||||
guardian check ./src --config custom-config.js
|
||||
|
||||
# Generate config
|
||||
guardian init --preset clean-architecture
|
||||
```
|
||||
|
||||
### Implementation Tasks
|
||||
- [ ] Create config parser and validator
|
||||
- [ ] Implement preset system
|
||||
- [ ] Add config discovery logic
|
||||
- [ ] Update AnalyzeProject use case to accept config
|
||||
- [ ] CLI integration for config override
|
||||
- [ ] Add `guardian init` command
|
||||
- [ ] Documentation and examples
|
||||
- [ ] Tests (config parsing, presets, overrides)
|
||||
|
||||
---
|
||||
|
||||
## Version 0.7.0 - Visualization & Dependency Graphs 🎨
|
||||
**Target:** Q1 2026 (March)
|
||||
**Priority:** 🔥 HIGH
|
||||
|
||||
> **Why High:** dependency-cruiser's main advantage is visualization. Guardian needs this to compete.
|
||||
|
||||
### Features
|
||||
|
||||
#### 1. Dependency Graph Visualization
|
||||
|
||||
```bash
|
||||
# Generate SVG graph
|
||||
guardian visualize ./src --output architecture.svg
|
||||
|
||||
# Interactive HTML
|
||||
guardian visualize ./src --format html --output report.html
|
||||
|
||||
# Mermaid diagram for docs
|
||||
guardian graph ./src --format mermaid > ARCHITECTURE.md
|
||||
|
||||
# ASCII tree for terminal
|
||||
guardian visualize ./src --format ascii
|
||||
```
|
||||
|
||||
#### 2. Layer Dependency Diagram
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
I[Infrastructure Layer] --> A[Application Layer]
|
||||
I --> D[Domain Layer]
|
||||
A --> D
|
||||
D --> S[Shared]
|
||||
A --> S
|
||||
I --> S
|
||||
|
||||
style D fill:#4CAF50
|
||||
style A fill:#2196F3
|
||||
style I fill:#FF9800
|
||||
style S fill:#9E9E9E
|
||||
```
|
||||
|
||||
#### 3. Violation Highlighting
|
||||
|
||||
Visualize violations on graph:
|
||||
- 🔴 Circular dependencies (red arrows)
|
||||
- ⚠️ Framework leaks (yellow highlights)
|
||||
- 🚫 Wrong dependency direction (dashed red arrows)
|
||||
- ✅ Correct dependencies (green arrows)
|
||||
|
||||
#### 4. Metrics Overlay
|
||||
|
||||
```bash
|
||||
guardian visualize ./src --show-metrics
|
||||
|
||||
# Shows on each node:
|
||||
# - File count per layer
|
||||
# - Hardcode violations count
|
||||
# - Complexity score
|
||||
```
|
||||
|
||||
#### 5. Export Formats
|
||||
|
||||
- SVG (for docs/website)
|
||||
- PNG (for presentations)
|
||||
- HTML (interactive, zoomable)
|
||||
- Mermaid (for markdown docs)
|
||||
- DOT (Graphviz format)
|
||||
- JSON (for custom processing)
|
||||
|
||||
### Implementation Tasks
|
||||
- [ ] Implement graph generation engine
|
||||
- [ ] Add SVG/PNG renderer
|
||||
- [ ] Create Mermaid diagram generator
|
||||
- [ ] Build HTML interactive viewer
|
||||
- [ ] Add violation highlighting
|
||||
- [ ] Metrics overlay system
|
||||
- [ ] CLI commands (`visualize`, `graph`)
|
||||
- [ ] Documentation and examples
|
||||
- [ ] Tests (graph generation, formats)
|
||||
|
||||
---
|
||||
|
||||
## Version 0.8.0 - CI/CD Integration Kit 🚀
|
||||
**Target:** Q2 2026 (April)
|
||||
**Priority:** 🔥 HIGH
|
||||
|
||||
> **Why High:** Enterprise requires CI/CD integration. SonarQube succeeds because of this.
|
||||
|
||||
### Features
|
||||
|
||||
#### 1. GitHub Actions
|
||||
|
||||
```yaml
|
||||
# .github/workflows/guardian.yml (ready-to-use template)
|
||||
name: Guardian Quality Check
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
guardian:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-node@v3
|
||||
|
||||
- name: Guardian Analysis
|
||||
uses: puaros/guardian-action@v1
|
||||
with:
|
||||
path: './src'
|
||||
fail-on: 'error'
|
||||
report-format: 'markdown'
|
||||
|
||||
- name: Comment PR
|
||||
uses: actions/github-script@v6
|
||||
if: github.event_name == 'pull_request'
|
||||
with:
|
||||
script: |
|
||||
// Auto-comment violations on PR
|
||||
```
|
||||
|
||||
#### 2. GitLab CI Template
|
||||
|
||||
```yaml
|
||||
# .gitlab-ci.yml
|
||||
include:
|
||||
- template: Guardian.gitlab-ci.yml
|
||||
|
||||
guardian_check:
|
||||
stage: test
|
||||
extends: .guardian
|
||||
variables:
|
||||
GUARDIAN_FAIL_ON: "error"
|
||||
GUARDIAN_FORMAT: "markdown"
|
||||
```
|
||||
|
||||
#### 3. Quality Gate
|
||||
|
||||
```bash
|
||||
# Fail build on violations
|
||||
guardian check ./src --fail-on error
|
||||
guardian check ./src --fail-on warning
|
||||
|
||||
# Threshold-based
|
||||
guardian check ./src --max-violations 10
|
||||
guardian check ./src --max-hardcode 5
|
||||
```
|
||||
|
||||
#### 4. PR Auto-Comments
|
||||
|
||||
Automatically comment on PRs with:
|
||||
- Summary of violations
|
||||
- Comparison with base branch
|
||||
- Quality score change
|
||||
- Actionable suggestions
|
||||
|
||||
```markdown
|
||||
## 🛡️ Guardian Report
|
||||
|
||||
**Quality Score:** 87/100 (⬆️ +3 from main)
|
||||
|
||||
### Violations Found: 5
|
||||
|
||||
#### 🔴 Critical (2)
|
||||
- `src/api/server.ts:15` - Hardcoded port 3000
|
||||
- `src/domain/User.ts:10` - Framework leak (Express)
|
||||
|
||||
#### ⚠️ Warnings (3)
|
||||
- `src/services/UserService.ts` - Naming convention
|
||||
- ...
|
||||
|
||||
[View Full Report](link)
|
||||
```
|
||||
|
||||
#### 5. Pre-commit Hook
|
||||
|
||||
```bash
|
||||
# Install via npx
|
||||
npx guardian install-hooks
|
||||
|
||||
# Creates .husky/pre-commit
|
||||
#!/bin/sh
|
||||
guardian check --staged --fail-on error
|
||||
```
|
||||
|
||||
#### 6. Status Checks
|
||||
|
||||
Integrate with GitHub/GitLab status checks:
|
||||
- ✅ No violations
|
||||
- ⚠️ Warnings only
|
||||
- ❌ Errors found
|
||||
|
||||
### Implementation Tasks
|
||||
- [ ] Create GitHub Action
|
||||
- [ ] Create GitLab CI template
|
||||
- [ ] Implement quality gate logic
|
||||
- [ ] Build PR comment generator
|
||||
- [ ] Pre-commit hook installer
|
||||
- [ ] Status check integration
|
||||
- [ ] Bitbucket Pipelines support
|
||||
- [ ] Documentation and examples
|
||||
- [ ] Tests (CI/CD scenarios)
|
||||
|
||||
---
|
||||
|
||||
## Version 0.9.0 - Auto-Fix & Code Generation 🤖
|
||||
**Target:** Q2 2026 (May)
|
||||
**Priority:** 🚀 GAME-CHANGER (UNIQUE!)
|
||||
|
||||
> **Why Game-Changer:** No competitor has intelligent auto-fix for architecture. This makes Guardian unique!
|
||||
|
||||
### Features
|
||||
|
||||
#### 1. Auto-Fix Hardcode
|
||||
|
||||
```bash
|
||||
# Fix all hardcode violations automatically
|
||||
guardian fix ./src --auto
|
||||
|
||||
# Preview changes
|
||||
guardian fix ./src --dry-run
|
||||
|
||||
# Fix specific types
|
||||
guardian fix ./src --type hardcode
|
||||
guardian fix ./src --type naming
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
const timeout = 5000
|
||||
app.listen(3000)
|
||||
|
||||
// After (auto-generated constants.ts)
|
||||
export const DEFAULT_TIMEOUT_MS = 5000
|
||||
export const DEFAULT_PORT = 3000
|
||||
|
||||
// After (fixed code)
|
||||
import { DEFAULT_TIMEOUT_MS, DEFAULT_PORT } from './constants'
|
||||
const timeout = DEFAULT_TIMEOUT_MS
|
||||
app.listen(DEFAULT_PORT)
|
||||
```
|
||||
|
||||
#### 2. Generate Constants File
|
||||
|
||||
```bash
|
||||
# Extract all hardcodes to constants
|
||||
guardian generate constants ./src --output src/config/constants.ts
|
||||
|
||||
# Generated file:
|
||||
// src/config/constants.ts
|
||||
export const DEFAULT_TIMEOUT_MS = 5000
|
||||
export const DEFAULT_PORT = 3000
|
||||
export const MAX_RETRIES = 3
|
||||
export const API_BASE_URL = 'http://localhost:8080'
|
||||
```
|
||||
|
||||
#### 3. Fix Naming Violations
|
||||
|
||||
```bash
|
||||
# Rename files to match conventions
|
||||
guardian fix naming ./src --auto
|
||||
|
||||
# Before: src/application/use-cases/user.ts
|
||||
# After: src/application/use-cases/CreateUser.ts
|
||||
```
|
||||
|
||||
#### 4. AI-Friendly Fix Prompts
|
||||
|
||||
```bash
|
||||
# Generate prompt for AI assistant
|
||||
guardian check ./src --format ai-prompt > fix-prompt.txt
|
||||
|
||||
# Output (optimized for Claude/GPT):
|
||||
"""
|
||||
Fix the following Guardian violations:
|
||||
|
||||
1. HARDCODE (src/api/server.ts:15)
|
||||
- Replace: app.listen(3000)
|
||||
- With: Extract 3000 to DEFAULT_PORT constant
|
||||
- Location: Create src/config/constants.ts
|
||||
|
||||
2. FRAMEWORK_LEAK (src/domain/User.ts:5)
|
||||
- Remove: import { Request } from 'express'
|
||||
- Reason: Domain layer cannot import frameworks
|
||||
- Suggestion: Use dependency injection via interfaces
|
||||
|
||||
[Complete fix suggestions...]
|
||||
"""
|
||||
|
||||
# Then feed to Claude:
|
||||
# cat fix-prompt.txt | pbcopy
|
||||
# Paste into Claude: "Fix these Guardian violations"
|
||||
```
|
||||
|
||||
#### 5. Interactive Fix Mode
|
||||
|
||||
```bash
|
||||
# Interactive fix selection
|
||||
guardian fix ./src --interactive
|
||||
|
||||
# Prompts:
|
||||
# ? Fix hardcode in server.ts:15 (3000)? (Y/n)
|
||||
# ? Suggested constant name: DEFAULT_PORT
|
||||
# [Edit name] [Skip] [Fix All]
|
||||
```
|
||||
|
||||
#### 6. Refactoring Commands
|
||||
|
||||
```bash
|
||||
# Break circular dependency
|
||||
guardian refactor circular ./src/services/UserService.ts
|
||||
# Suggests: Extract shared interface
|
||||
|
||||
# Fix layer violation
|
||||
guardian refactor layer ./src/domain/entities/User.ts
|
||||
# Suggests: Move framework imports to infrastructure
|
||||
```
|
||||
|
||||
### Implementation Tasks
|
||||
- [ ] Implement auto-fix engine (AST transformation)
|
||||
- [ ] Constants extractor and generator
|
||||
- [ ] File renaming system
|
||||
- [ ] AI prompt generator
|
||||
- [ ] Interactive fix mode
|
||||
- [ ] Refactoring suggestions
|
||||
- [ ] Safe rollback mechanism
|
||||
- [ ] Documentation and examples
|
||||
- [ ] Tests (fix scenarios, edge cases)
|
||||
|
||||
---
|
||||
|
||||
## Version 0.10.0 - Metrics & Quality Score 📊
|
||||
**Target:** Q2 2026 (June)
|
||||
**Priority:** 🔥 HIGH
|
||||
|
||||
> **Why High:** Enterprise needs metrics to justify investment. SonarQube's dashboard is a major selling point.
|
||||
|
||||
### Features
|
||||
|
||||
#### 1. Quality Score (0-100)
|
||||
|
||||
```bash
|
||||
guardian score ./src
|
||||
|
||||
# Output:
|
||||
# 🛡️ Guardian Quality Score: 87/100 (Good)
|
||||
#
|
||||
# Category Breakdown:
|
||||
# ✅ Architecture: 95/100 (Excellent)
|
||||
# ⚠️ Hardcode: 78/100 (Needs Improvement)
|
||||
# ✅ Naming: 92/100 (Excellent)
|
||||
# ✅ Dependencies: 89/100 (Good)
|
||||
```
|
||||
|
||||
**Score Calculation:**
|
||||
- Architecture violations: -5 per error
|
||||
- Hardcode violations: -1 per occurrence
|
||||
- Circular dependencies: -10 per cycle
|
||||
- Naming violations: -2 per error
|
||||
|
||||
#### 2. Metrics Dashboard (JSON/HTML)
|
||||
|
||||
```bash
|
||||
# Export metrics
|
||||
guardian metrics ./src --format json > metrics.json
|
||||
guardian metrics ./src --format html > dashboard.html
|
||||
|
||||
# Metrics included:
|
||||
{
|
||||
"qualityScore": 87,
|
||||
"violations": {
|
||||
"hardcode": 12,
|
||||
"circular": 0,
|
||||
"architecture": 2,
|
||||
"naming": 5
|
||||
},
|
||||
"metrics": {
|
||||
"totalFiles": 45,
|
||||
"totalLOC": 3500,
|
||||
"hardcodePerKLOC": 3.4,
|
||||
"averageFilesPerLayer": 11.25
|
||||
},
|
||||
"trends": {
|
||||
"scoreChange": "+5",
|
||||
"violationsChange": "-8"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Trend Analysis
|
||||
|
||||
```bash
|
||||
# Compare with main branch
|
||||
guardian metrics ./src --compare-with main
|
||||
|
||||
# Output:
|
||||
# Quality Score: 87/100 (⬆️ +3 from main)
|
||||
#
|
||||
# Changes:
|
||||
# ✅ Hardcode violations: 12 (⬇️ -5)
|
||||
# ⚠️ Naming violations: 5 (⬆️ +2)
|
||||
# ✅ Circular deps: 0 (⬇️ -1)
|
||||
```
|
||||
|
||||
#### 4. Historical Tracking
|
||||
|
||||
```bash
|
||||
# Store metrics history
|
||||
guardian metrics ./src --save
|
||||
|
||||
# View trends
|
||||
guardian trends --last 30d
|
||||
|
||||
# Output: ASCII graph showing quality score over time
|
||||
```
|
||||
|
||||
#### 5. Export for Dashboards
|
||||
|
||||
```bash
|
||||
# Prometheus format
|
||||
guardian metrics ./src --format prometheus
|
||||
|
||||
# Grafana JSON
|
||||
guardian metrics ./src --format grafana
|
||||
|
||||
# CSV for Excel
|
||||
guardian metrics ./src --format csv
|
||||
```
|
||||
|
||||
#### 6. Badge Generation
|
||||
|
||||
```bash
|
||||
# Generate badge for README
|
||||
guardian badge ./src --output badge.svg
|
||||
|
||||
# Markdown badge
|
||||
|
||||
```
|
||||
|
||||
### Implementation Tasks
|
||||
- [ ] Quality score calculation algorithm
|
||||
- [ ] Metrics collection system
|
||||
- [ ] Trend analysis engine
|
||||
- [ ] JSON/HTML/Prometheus exporters
|
||||
- [ ] Historical data storage
|
||||
- [ ] Badge generator
|
||||
- [ ] CLI commands (`score`, `metrics`, `trends`, `badge`)
|
||||
- [ ] Documentation and examples
|
||||
- [ ] Tests (metrics calculation, exports)
|
||||
|
||||
---
|
||||
|
||||
## Version 0.11.0+ - DDD Specialization 🏗️
|
||||
**Target:** Q3-Q4 2026
|
||||
**Priority:** MEDIUM (After Market Parity)
|
||||
|
||||
Now we can focus on Guardian's unique DDD/Clean Architecture specialization:
|
||||
|
||||
### v0.11.0 - Aggregate Boundary Validation 🔒
|
||||
- Detect entity references across aggregates
|
||||
- Enforce ID-only references between aggregates
|
||||
- Validate aggregate root access patterns
|
||||
|
||||
### v0.12.0 - Anemic Domain Model Detection 🩺
|
||||
- Detect entities with only getters/setters
|
||||
- Count methods vs properties ratio
|
||||
- Suggest moving logic from services to entities
|
||||
|
||||
### v0.13.0 - Domain Event Validation 📢
|
||||
- Validate event publishing pattern
|
||||
- Check events inherit from DomainEvent base
|
||||
- Detect direct infrastructure calls from entities
|
||||
|
||||
### v0.14.0 - Value Object Immutability 🔐
|
||||
- Ensure Value Objects have readonly fields
|
||||
- Detect public setters
|
||||
- Verify equals() method exists
|
||||
|
||||
### v0.15.0 - Use Case Single Responsibility 🎯
|
||||
- Check Use Case has single public method (execute)
|
||||
- Detect multiple responsibilities
|
||||
- Suggest splitting large Use Cases
|
||||
|
||||
### v0.16.0 - Interface Segregation 🔌
|
||||
- Count methods per interface (> 10 = warning)
|
||||
- Check method cohesion
|
||||
- Suggest interface splitting
|
||||
|
||||
### v0.17.0 - Port-Adapter Pattern 🔌
|
||||
- Check Ports (interfaces) are in application/domain
|
||||
- Verify Adapters are in infrastructure
|
||||
- Detect external library imports in use cases
|
||||
|
||||
### v0.18.0 - Command Query Separation (CQRS) 📝
|
||||
- Detect methods that both change state and return data
|
||||
- Check Use Case names for CQS violations
|
||||
- Validate Command Use Cases return void
|
||||
|
||||
### v0.19.0 - Factory Pattern Validation 🏭
|
||||
- Detect complex logic in entity constructors
|
||||
- Check for `new Entity()` calls in use cases
|
||||
- Suggest extracting construction to Factory
|
||||
|
||||
### v0.20.0 - Specification Pattern Detection 🔍
|
||||
- Detect complex business rules in use cases
|
||||
- Validate Specification classes in domain
|
||||
- Suggest extracting rules to Specifications
|
||||
|
||||
### v0.21.0 - Layered Service Anti-pattern ⚠️
|
||||
- Detect service methods operating on single entity
|
||||
- Validate entities have behavior methods
|
||||
- Suggest moving service methods to entities
|
||||
|
||||
### v0.22.0 - Bounded Context Leak Detection 🚧
|
||||
- Detect entity imports across contexts
|
||||
- Validate only ID references between contexts
|
||||
- Verify event-based integration
|
||||
|
||||
### v0.23.0 - Transaction Script Detection 📜
|
||||
- Detect procedural logic in use cases
|
||||
- Check use case length (> 30-50 lines = warning)
|
||||
- Suggest moving logic to domain entities
|
||||
|
||||
### v0.24.0 - Persistence Ignorance 💾
|
||||
- Detect ORM decorators in domain entities
|
||||
- Check for ORM library imports in domain
|
||||
- Suggest persistence ignorance pattern
|
||||
|
||||
### v0.25.0 - Null Object Pattern Detection 🎭
|
||||
- Count null checks in use cases
|
||||
- Suggest Null Object pattern
|
||||
- Detect repositories returning null vs Null Object
|
||||
|
||||
### v0.26.0 - Primitive Obsession Detection 🔢
|
||||
- Detect methods with > 3 primitive parameters
|
||||
- Check for common Value Object candidates
|
||||
- Suggest creating Value Objects
|
||||
|
||||
### v0.27.0 - Service Locator Anti-pattern 🔍
|
||||
- Detect global ServiceLocator/Registry classes
|
||||
- Validate constructor injection
|
||||
- Suggest DI container usage
|
||||
|
||||
### v0.28.0 - Double Dispatch Pattern 🎯
|
||||
- Detect frequent instanceof or type checking
|
||||
- Check for long if-else/switch by type
|
||||
- Suggest Visitor pattern
|
||||
|
||||
### v0.29.0 - Entity Identity Validation 🆔
|
||||
- Detect public mutable ID fields
|
||||
- Validate ID is Value Object
|
||||
- Check for equals() method implementation
|
||||
|
||||
### v0.30.0 - Saga Pattern Detection 🔄
|
||||
- Detect multiple external calls without compensation
|
||||
- Validate compensating transactions
|
||||
- Suggest Saga pattern for distributed operations
|
||||
|
||||
### v0.31.0 - Anti-Corruption Layer Detection 🛡️
|
||||
- Detect direct legacy library imports
|
||||
- Check for domain adaptation to external APIs
|
||||
- Validate translator/adapter layer exists
|
||||
|
||||
### v0.32.0 - Ubiquitous Language Validation 📖
|
||||
**Priority: HIGH**
|
||||
- Detect synonyms for same concepts (User/Customer/Client)
|
||||
- Check inconsistent verbs (Create/Register/SignUp)
|
||||
- Require Ubiquitous Language glossary
|
||||
|
||||
---
|
||||
|
||||
## Version 1.0.0 - Stable Release 🚀
|
||||
**Target:** Q4 2026 (December)
|
||||
**Priority:** 🔥 CRITICAL
|
||||
|
||||
Production-ready stable release with ecosystem:
|
||||
|
||||
### Core Features
|
||||
- ✅ All detection features stabilized
|
||||
- ✅ Configuration & presets
|
||||
- ✅ Visualization & graphs
|
||||
- ✅ CI/CD integration
|
||||
- ✅ Auto-fix & code generation
|
||||
- ✅ Metrics & quality score
|
||||
- ✅ 30+ DDD pattern detectors
|
||||
|
||||
### Ecosystem
|
||||
|
||||
#### VS Code Extension
|
||||
- Real-time detection as you type
|
||||
- Inline suggestions and quick fixes
|
||||
- Problem panel integration
|
||||
- Code actions for auto-fix
|
||||
|
||||
#### JetBrains Plugin
|
||||
- IntelliJ IDEA, WebStorm support
|
||||
- Inspection integration
|
||||
- Quick fixes
|
||||
|
||||
#### Web Dashboard
|
||||
- Team quality metrics
|
||||
- Historical trends
|
||||
- Per-developer analytics
|
||||
- Project comparison
|
||||
|
||||
#### GitHub Integration
|
||||
- GitHub App
|
||||
- Code scanning integration
|
||||
- Dependency insights
|
||||
- Security alerts for architecture violations
|
||||
|
||||
---
|
||||
|
||||
## 💡 Future Ideas (Post-1.0.0)
|
||||
|
||||
### Multi-Language Support
|
||||
- Python (Django/Flask + DDD)
|
||||
- C# (.NET + Clean Architecture)
|
||||
- Java (Spring Boot + DDD)
|
||||
- Go (Clean Architecture)
|
||||
|
||||
### AI-Powered Features
|
||||
- LLM-based fix suggestions
|
||||
- AI generates code for complex refactorings
|
||||
- Claude/GPT API integration
|
||||
- Natural language architecture queries
|
||||
|
||||
### Team Analytics
|
||||
- Per-developer quality metrics
|
||||
- Team quality trends dashboard
|
||||
- Technical debt tracking
|
||||
- Leaderboards (gamification)
|
||||
|
||||
### Security Features
|
||||
- Secrets detection (API keys, passwords)
|
||||
- SQL injection pattern detection
|
||||
- XSS vulnerability patterns
|
||||
- Dependency vulnerability scanning
|
||||
|
||||
### Code Quality Metrics
|
||||
- Maintainability index
|
||||
- Technical debt estimation
|
||||
- Code duplication detection
|
||||
- Complexity trends
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Criteria
|
||||
|
||||
### v0.10.0 (Market Parity Achieved)
|
||||
- ✅ Configuration support (compete with ESLint)
|
||||
- ✅ Visualization (compete with dependency-cruiser)
|
||||
- ✅ CI/CD integration (compete with SonarQube)
|
||||
- ✅ Auto-fix (UNIQUE! Game-changer)
|
||||
- ✅ Metrics dashboard (compete with SonarQube)
|
||||
|
||||
### v1.0.0 (Enterprise Ready)
|
||||
- ✅ 1000+ GitHub stars
|
||||
- ✅ 100+ npm installs/week
|
||||
- ✅ 10+ enterprise adopters
|
||||
- ✅ 99%+ test coverage
|
||||
- ✅ Complete documentation
|
||||
- ✅ IDE extensions available
|
||||
|
||||
---
|
||||
|
||||
## 📊 Competitive Positioning
|
||||
|
||||
| Feature | Guardian v1.0 | SonarQube | dependency-cruiser | ArchUnit | FTA |
|
||||
|---------|---------------|-----------|-------------------|----------|-----|
|
||||
| TypeScript Focus | ✅✅ | ⚠️ | ✅✅ | ❌ | ✅✅ |
|
||||
| Hardcode + AI Tips | ✅✅ UNIQUE | ⚠️ | ❌ | ❌ | ❌ |
|
||||
| Architecture (DDD) | ✅✅ UNIQUE | ⚠️ | ⚠️ | ✅ | ❌ |
|
||||
| Visualization | ✅ | ✅ | ✅✅ | ❌ | ⚠️ |
|
||||
| Auto-Fix | ✅✅ UNIQUE | ❌ | ❌ | ❌ | ❌ |
|
||||
| Configuration | ✅ | ✅✅ | ✅ | ✅ | ⚠️ |
|
||||
| CI/CD | ✅ | ✅✅ | ✅ | ✅ | ⚠️ |
|
||||
| Metrics | ✅ | ✅✅ | ⚠️ | ❌ | ✅✅ |
|
||||
| Security (SAST) | ❌ | ✅✅ | ❌ | ❌ | ❌ |
|
||||
| Multi-language | ❌ | ✅✅ | ⚠️ | ⚠️ | ❌ |
|
||||
|
||||
**Guardian's Position:** The AI-First Architecture Guardian for TypeScript/DDD teams
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Want to help build Guardian? Check out:
|
||||
- [GitHub Issues](https://github.com/samiyev/puaros/issues)
|
||||
- [CONTRIBUTING.md](../../CONTRIBUTING.md)
|
||||
- [Discord Community](#) (coming soon)
|
||||
|
||||
---
|
||||
|
||||
## 📈 Versioning
|
||||
|
||||
Guardian follows [Semantic Versioning](https://semver.org/):
|
||||
- **MAJOR** (1.0.0) - Breaking changes
|
||||
- **MINOR** (0.x.0) - New features, backwards compatible
|
||||
- **PATCH** (0.x.y) - Bug fixes
|
||||
|
||||
Until 1.0.0, minor versions may include breaking changes as we iterate on the API.
|
||||
1176
packages/guardian/docs/v0.6.0-CONFIGURATION-SPEC.md
Normal file
1176
packages/guardian/docs/v0.6.0-CONFIGURATION-SPEC.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,40 @@
|
||||
/**
|
||||
* ❌ BAD EXAMPLE: Direct Entity Reference Across Aggregates
|
||||
*
|
||||
* Violation: Order aggregate directly imports and uses User entity from User aggregate
|
||||
*
|
||||
* Problems:
|
||||
* 1. Creates tight coupling between aggregates
|
||||
* 2. Changes to User entity affect Order aggregate
|
||||
* 3. Violates aggregate boundary principles in DDD
|
||||
* 4. Makes aggregates not independently modifiable
|
||||
*/
|
||||
|
||||
import { User } from "../user/User"
|
||||
import { Product } from "../product/Product"
|
||||
|
||||
export class Order {
|
||||
private id: string
|
||||
private user: User
|
||||
private product: Product
|
||||
private quantity: number
|
||||
|
||||
constructor(id: string, user: User, product: Product, quantity: number) {
|
||||
this.id = id
|
||||
this.user = user
|
||||
this.product = product
|
||||
this.quantity = quantity
|
||||
}
|
||||
|
||||
getUserEmail(): string {
|
||||
return this.user.email
|
||||
}
|
||||
|
||||
getProductPrice(): number {
|
||||
return this.product.price
|
||||
}
|
||||
|
||||
calculateTotal(): number {
|
||||
return this.product.price * this.quantity
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,16 @@
|
||||
import { User } from "../user/User"
|
||||
import { Product } from "../product/Product"
|
||||
|
||||
export class Order {
|
||||
private id: string
|
||||
private user: User
|
||||
private product: Product
|
||||
private quantity: number
|
||||
|
||||
constructor(id: string, user: User, product: Product, quantity: number) {
|
||||
this.id = id
|
||||
this.user = user
|
||||
this.product = product
|
||||
this.quantity = quantity
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,7 @@
|
||||
export class Product {
|
||||
public price: number
|
||||
|
||||
constructor(price: number) {
|
||||
this.price = price
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,7 @@
|
||||
export class User {
|
||||
public email: string
|
||||
|
||||
constructor(email: string) {
|
||||
this.email = email
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
/**
|
||||
* ✅ GOOD EXAMPLE: Reference by ID
|
||||
*
|
||||
* Best Practice: Order aggregate references other aggregates only by their IDs
|
||||
*
|
||||
* Benefits:
|
||||
* 1. Loose coupling between aggregates
|
||||
* 2. Each aggregate can be modified independently
|
||||
* 3. Follows DDD aggregate boundary principles
|
||||
* 4. Clear separation of concerns
|
||||
*/
|
||||
|
||||
import { UserId } from "../user/value-objects/UserId"
|
||||
import { ProductId } from "../product/value-objects/ProductId"
|
||||
|
||||
export class Order {
|
||||
private id: string
|
||||
private userId: UserId
|
||||
private productId: ProductId
|
||||
private quantity: number
|
||||
|
||||
constructor(id: string, userId: UserId, productId: ProductId, quantity: number) {
|
||||
this.id = id
|
||||
this.userId = userId
|
||||
this.productId = productId
|
||||
this.quantity = quantity
|
||||
}
|
||||
|
||||
getUserId(): UserId {
|
||||
return this.userId
|
||||
}
|
||||
|
||||
getProductId(): ProductId {
|
||||
return this.productId
|
||||
}
|
||||
|
||||
getQuantity(): number {
|
||||
return this.quantity
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,61 @@
|
||||
/**
|
||||
* ✅ GOOD EXAMPLE: Using Value Objects for Needed Data
|
||||
*
|
||||
* Best Practice: When Order needs specific data from other aggregates,
|
||||
* use Value Objects to store that data (denormalization)
|
||||
*
|
||||
* Benefits:
|
||||
* 1. Order aggregate has all data it needs
|
||||
* 2. No runtime dependency on other aggregates
|
||||
* 3. Better performance (no joins needed)
|
||||
* 4. Clear contract through Value Objects
|
||||
*/
|
||||
|
||||
import { UserId } from "../user/value-objects/UserId"
|
||||
import { ProductId } from "../product/value-objects/ProductId"
|
||||
|
||||
export class CustomerInfo {
|
||||
constructor(
|
||||
readonly customerId: UserId,
|
||||
readonly customerName: string,
|
||||
readonly customerEmail: string,
|
||||
) {}
|
||||
}
|
||||
|
||||
export class ProductInfo {
|
||||
constructor(
|
||||
readonly productId: ProductId,
|
||||
readonly productName: string,
|
||||
readonly productPrice: number,
|
||||
) {}
|
||||
}
|
||||
|
||||
export class Order {
|
||||
private id: string
|
||||
private customer: CustomerInfo
|
||||
private product: ProductInfo
|
||||
private quantity: number
|
||||
|
||||
constructor(id: string, customer: CustomerInfo, product: ProductInfo, quantity: number) {
|
||||
this.id = id
|
||||
this.customer = customer
|
||||
this.product = product
|
||||
this.quantity = quantity
|
||||
}
|
||||
|
||||
getCustomerEmail(): string {
|
||||
return this.customer.customerEmail
|
||||
}
|
||||
|
||||
calculateTotal(): number {
|
||||
return this.product.productPrice * this.quantity
|
||||
}
|
||||
|
||||
getCustomerInfo(): CustomerInfo {
|
||||
return this.customer
|
||||
}
|
||||
|
||||
getProductInfo(): ProductInfo {
|
||||
return this.product
|
||||
}
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@samiyev/guardian",
|
||||
"version": "0.6.3",
|
||||
"version": "0.7.3",
|
||||
"description": "Research-backed code quality guardian for AI-assisted development. Detects hardcodes, circular deps, framework leaks, entity exposure, and 8 architecture violations. Enforces Clean Architecture/DDD principles. Works with GitHub Copilot, Cursor, Windsurf, Claude, ChatGPT, Cline, and any AI coding tool.",
|
||||
"keywords": [
|
||||
"puaros",
|
||||
|
||||
@@ -11,6 +11,7 @@ import { IFrameworkLeakDetector } from "./domain/services/IFrameworkLeakDetector
|
||||
import { IEntityExposureDetector } from "./domain/services/IEntityExposureDetector"
|
||||
import { IDependencyDirectionDetector } from "./domain/services/IDependencyDirectionDetector"
|
||||
import { IRepositoryPatternDetector } from "./domain/services/RepositoryPatternDetectorService"
|
||||
import { IAggregateBoundaryDetector } from "./domain/services/IAggregateBoundaryDetector"
|
||||
import { FileScanner } from "./infrastructure/scanners/FileScanner"
|
||||
import { CodeParser } from "./infrastructure/parsers/CodeParser"
|
||||
import { HardcodeDetector } from "./infrastructure/analyzers/HardcodeDetector"
|
||||
@@ -19,6 +20,7 @@ import { FrameworkLeakDetector } from "./infrastructure/analyzers/FrameworkLeakD
|
||||
import { EntityExposureDetector } from "./infrastructure/analyzers/EntityExposureDetector"
|
||||
import { DependencyDirectionDetector } from "./infrastructure/analyzers/DependencyDirectionDetector"
|
||||
import { RepositoryPatternDetector } from "./infrastructure/analyzers/RepositoryPatternDetector"
|
||||
import { AggregateBoundaryDetector } from "./infrastructure/analyzers/AggregateBoundaryDetector"
|
||||
import { ERROR_MESSAGES } from "./shared/constants"
|
||||
|
||||
/**
|
||||
@@ -76,6 +78,7 @@ export async function analyzeProject(
|
||||
const dependencyDirectionDetector: IDependencyDirectionDetector =
|
||||
new DependencyDirectionDetector()
|
||||
const repositoryPatternDetector: IRepositoryPatternDetector = new RepositoryPatternDetector()
|
||||
const aggregateBoundaryDetector: IAggregateBoundaryDetector = new AggregateBoundaryDetector()
|
||||
const useCase = new AnalyzeProject(
|
||||
fileScanner,
|
||||
codeParser,
|
||||
@@ -85,6 +88,7 @@ export async function analyzeProject(
|
||||
entityExposureDetector,
|
||||
dependencyDirectionDetector,
|
||||
repositoryPatternDetector,
|
||||
aggregateBoundaryDetector,
|
||||
)
|
||||
|
||||
const result = await useCase.execute(options)
|
||||
@@ -107,5 +111,6 @@ export type {
|
||||
EntityExposureViolation,
|
||||
DependencyDirectionViolation,
|
||||
RepositoryPatternViolation,
|
||||
AggregateBoundaryViolation,
|
||||
ProjectMetrics,
|
||||
} from "./application/use-cases/AnalyzeProject"
|
||||
|
||||
@@ -8,6 +8,7 @@ import { IFrameworkLeakDetector } from "../../domain/services/IFrameworkLeakDete
|
||||
import { IEntityExposureDetector } from "../../domain/services/IEntityExposureDetector"
|
||||
import { IDependencyDirectionDetector } from "../../domain/services/IDependencyDirectionDetector"
|
||||
import { IRepositoryPatternDetector } from "../../domain/services/RepositoryPatternDetectorService"
|
||||
import { IAggregateBoundaryDetector } from "../../domain/services/IAggregateBoundaryDetector"
|
||||
import { SourceFile } from "../../domain/entities/SourceFile"
|
||||
import { DependencyGraph } from "../../domain/entities/DependencyGraph"
|
||||
import { ProjectPath } from "../../domain/value-objects/ProjectPath"
|
||||
@@ -41,6 +42,7 @@ export interface AnalyzeProjectResponse {
|
||||
entityExposureViolations: EntityExposureViolation[]
|
||||
dependencyDirectionViolations: DependencyDirectionViolation[]
|
||||
repositoryPatternViolations: RepositoryPatternViolation[]
|
||||
aggregateBoundaryViolations: AggregateBoundaryViolation[]
|
||||
metrics: ProjectMetrics
|
||||
}
|
||||
|
||||
@@ -149,6 +151,19 @@ export interface RepositoryPatternViolation {
|
||||
severity: SeverityLevel
|
||||
}
|
||||
|
||||
export interface AggregateBoundaryViolation {
|
||||
rule: typeof RULES.AGGREGATE_BOUNDARY
|
||||
fromAggregate: string
|
||||
toAggregate: string
|
||||
entityName: string
|
||||
importPath: string
|
||||
file: string
|
||||
line?: number
|
||||
message: string
|
||||
suggestion: string
|
||||
severity: SeverityLevel
|
||||
}
|
||||
|
||||
export interface ProjectMetrics {
|
||||
totalFiles: number
|
||||
totalFunctions: number
|
||||
@@ -172,6 +187,7 @@ export class AnalyzeProject extends UseCase<
|
||||
private readonly entityExposureDetector: IEntityExposureDetector,
|
||||
private readonly dependencyDirectionDetector: IDependencyDirectionDetector,
|
||||
private readonly repositoryPatternDetector: IRepositoryPatternDetector,
|
||||
private readonly aggregateBoundaryDetector: IAggregateBoundaryDetector,
|
||||
) {
|
||||
super()
|
||||
}
|
||||
@@ -234,6 +250,9 @@ export class AnalyzeProject extends UseCase<
|
||||
const repositoryPatternViolations = this.sortBySeverity(
|
||||
this.detectRepositoryPatternViolations(sourceFiles),
|
||||
)
|
||||
const aggregateBoundaryViolations = this.sortBySeverity(
|
||||
this.detectAggregateBoundaryViolations(sourceFiles),
|
||||
)
|
||||
const metrics = this.calculateMetrics(sourceFiles, totalFunctions, dependencyGraph)
|
||||
|
||||
return ResponseDto.ok({
|
||||
@@ -247,6 +266,7 @@ export class AnalyzeProject extends UseCase<
|
||||
entityExposureViolations,
|
||||
dependencyDirectionViolations,
|
||||
repositoryPatternViolations,
|
||||
aggregateBoundaryViolations,
|
||||
metrics,
|
||||
})
|
||||
} catch (error) {
|
||||
@@ -532,6 +552,37 @@ export class AnalyzeProject extends UseCase<
|
||||
return violations
|
||||
}
|
||||
|
||||
private detectAggregateBoundaryViolations(
|
||||
sourceFiles: SourceFile[],
|
||||
): AggregateBoundaryViolation[] {
|
||||
const violations: AggregateBoundaryViolation[] = []
|
||||
|
||||
for (const file of sourceFiles) {
|
||||
const boundaryViolations = this.aggregateBoundaryDetector.detectViolations(
|
||||
file.content,
|
||||
file.path.relative,
|
||||
file.layer,
|
||||
)
|
||||
|
||||
for (const violation of boundaryViolations) {
|
||||
violations.push({
|
||||
rule: RULES.AGGREGATE_BOUNDARY,
|
||||
fromAggregate: violation.fromAggregate,
|
||||
toAggregate: violation.toAggregate,
|
||||
entityName: violation.entityName,
|
||||
importPath: violation.importPath,
|
||||
file: file.path.relative,
|
||||
line: violation.line,
|
||||
message: violation.getMessage(),
|
||||
suggestion: violation.getSuggestion(),
|
||||
severity: VIOLATION_SEVERITY_MAP.AGGREGATE_BOUNDARY,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
return violations
|
||||
}
|
||||
|
||||
private calculateMetrics(
|
||||
sourceFiles: SourceFile[],
|
||||
totalFunctions: number,
|
||||
|
||||
@@ -155,6 +155,7 @@ program
|
||||
entityExposureViolations,
|
||||
dependencyDirectionViolations,
|
||||
repositoryPatternViolations,
|
||||
aggregateBoundaryViolations,
|
||||
} = result
|
||||
|
||||
const minSeverity: SeverityLevel | undefined = options.onlyCritical
|
||||
@@ -185,6 +186,10 @@ program
|
||||
repositoryPatternViolations,
|
||||
minSeverity,
|
||||
)
|
||||
aggregateBoundaryViolations = filterBySeverity(
|
||||
aggregateBoundaryViolations,
|
||||
minSeverity,
|
||||
)
|
||||
|
||||
if (options.onlyCritical) {
|
||||
console.log("\n🔴 Filtering: Showing only CRITICAL severity issues\n")
|
||||
@@ -374,6 +379,35 @@ program
|
||||
)
|
||||
}
|
||||
|
||||
// Aggregate boundary violations
|
||||
if (options.architecture && aggregateBoundaryViolations.length > 0) {
|
||||
console.log(
|
||||
`\n🔒 Found ${String(aggregateBoundaryViolations.length)} aggregate boundary violation(s)`,
|
||||
)
|
||||
|
||||
displayGroupedViolations(
|
||||
aggregateBoundaryViolations,
|
||||
(ab, index) => {
|
||||
const location = ab.line ? `${ab.file}:${String(ab.line)}` : ab.file
|
||||
console.log(`${String(index + 1)}. ${location}`)
|
||||
console.log(` Severity: ${SEVERITY_LABELS[ab.severity]}`)
|
||||
console.log(` From Aggregate: ${ab.fromAggregate}`)
|
||||
console.log(` To Aggregate: ${ab.toAggregate}`)
|
||||
console.log(` Entity: ${ab.entityName}`)
|
||||
console.log(` Import: ${ab.importPath}`)
|
||||
console.log(` ${ab.message}`)
|
||||
console.log(" 💡 Suggestion:")
|
||||
ab.suggestion.split("\n").forEach((line) => {
|
||||
if (line.trim()) {
|
||||
console.log(` ${line}`)
|
||||
}
|
||||
})
|
||||
console.log("")
|
||||
},
|
||||
limit,
|
||||
)
|
||||
}
|
||||
|
||||
// Hardcode violations
|
||||
if (options.hardcode && hardcodeViolations.length > 0) {
|
||||
console.log(
|
||||
@@ -407,7 +441,8 @@ program
|
||||
frameworkLeakViolations.length +
|
||||
entityExposureViolations.length +
|
||||
dependencyDirectionViolations.length +
|
||||
repositoryPatternViolations.length
|
||||
repositoryPatternViolations.length +
|
||||
aggregateBoundaryViolations.length
|
||||
|
||||
if (totalIssues === 0) {
|
||||
console.log(CLI_MESSAGES.NO_ISSUES)
|
||||
|
||||
@@ -48,3 +48,15 @@ export const REPOSITORY_PATTERN_MESSAGES = {
|
||||
SUGGESTION_DELETE: "remove or delete",
|
||||
SUGGESTION_QUERY: "find or search",
|
||||
}
|
||||
|
||||
export const REPOSITORY_FALLBACK_SUGGESTIONS = {
|
||||
DEFAULT: "findById() or findByEmail()",
|
||||
}
|
||||
|
||||
export const AGGREGATE_VIOLATION_MESSAGES = {
|
||||
USE_ID_REFERENCE: "1. Reference other aggregates by ID (UserId, OrderId) instead of entity",
|
||||
USE_VALUE_OBJECT:
|
||||
"2. Use Value Objects to store needed data from other aggregates (CustomerInfo, ProductSummary)",
|
||||
AVOID_DIRECT_REFERENCE: "3. Avoid direct entity references to maintain aggregate independence",
|
||||
MAINTAIN_INDEPENDENCE: "4. Each aggregate should be independently modifiable and deployable",
|
||||
}
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
import { AggregateBoundaryViolation } from "../value-objects/AggregateBoundaryViolation"
|
||||
|
||||
/**
|
||||
* Interface for detecting aggregate boundary violations in DDD
|
||||
*
|
||||
* Aggregate boundary violations occur when an entity from one aggregate
|
||||
* directly references an entity from another aggregate. In DDD, aggregates
|
||||
* should reference each other only by ID or Value Objects to maintain
|
||||
* loose coupling and independence.
|
||||
*/
|
||||
export interface IAggregateBoundaryDetector {
|
||||
/**
|
||||
* Detects aggregate boundary violations in the given code
|
||||
*
|
||||
* Analyzes import statements to identify direct entity references
|
||||
* across aggregate boundaries.
|
||||
*
|
||||
* @param code - Source code to analyze
|
||||
* @param filePath - Path to the file being analyzed
|
||||
* @param layer - The architectural layer of the file (should be 'domain')
|
||||
* @returns Array of detected aggregate boundary violations
|
||||
*/
|
||||
detectViolations(
|
||||
code: string,
|
||||
filePath: string,
|
||||
layer: string | undefined,
|
||||
): AggregateBoundaryViolation[]
|
||||
|
||||
/**
|
||||
* Checks if a file path belongs to an aggregate
|
||||
*
|
||||
* @param filePath - The file path to check
|
||||
* @returns The aggregate name if found, undefined otherwise
|
||||
*/
|
||||
extractAggregateFromPath(filePath: string): string | undefined
|
||||
|
||||
/**
|
||||
* Checks if an import path references an entity from another aggregate
|
||||
*
|
||||
* @param importPath - The import path to analyze
|
||||
* @param currentAggregate - The aggregate of the current file
|
||||
* @returns True if the import crosses aggregate boundaries inappropriately
|
||||
*/
|
||||
isAggregateBoundaryViolation(importPath: string, currentAggregate: string): boolean
|
||||
}
|
||||
@@ -0,0 +1,137 @@
|
||||
import { ValueObject } from "./ValueObject"
|
||||
import { AGGREGATE_VIOLATION_MESSAGES } from "../constants/Messages"
|
||||
|
||||
interface AggregateBoundaryViolationProps {
|
||||
readonly fromAggregate: string
|
||||
readonly toAggregate: string
|
||||
readonly entityName: string
|
||||
readonly importPath: string
|
||||
readonly filePath: string
|
||||
readonly line?: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Represents an aggregate boundary violation in the codebase
|
||||
*
|
||||
* Aggregate boundary violations occur when an entity from one aggregate
|
||||
* directly references an entity from another aggregate, violating DDD principles:
|
||||
* - Aggregates should reference each other only by ID or Value Objects
|
||||
* - Direct entity references create tight coupling between aggregates
|
||||
* - Changes to one aggregate should not require changes to another
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // Bad: Direct entity reference across aggregates
|
||||
* const violation = AggregateBoundaryViolation.create(
|
||||
* 'order',
|
||||
* 'user',
|
||||
* 'User',
|
||||
* '../user/User',
|
||||
* 'src/domain/aggregates/order/Order.ts',
|
||||
* 5
|
||||
* )
|
||||
*
|
||||
* console.log(violation.getMessage())
|
||||
* // "Order aggregate should not directly reference User entity from User aggregate"
|
||||
* ```
|
||||
*/
|
||||
export class AggregateBoundaryViolation extends ValueObject<AggregateBoundaryViolationProps> {
|
||||
private constructor(props: AggregateBoundaryViolationProps) {
|
||||
super(props)
|
||||
}
|
||||
|
||||
public static create(
|
||||
fromAggregate: string,
|
||||
toAggregate: string,
|
||||
entityName: string,
|
||||
importPath: string,
|
||||
filePath: string,
|
||||
line?: number,
|
||||
): AggregateBoundaryViolation {
|
||||
return new AggregateBoundaryViolation({
|
||||
fromAggregate,
|
||||
toAggregate,
|
||||
entityName,
|
||||
importPath,
|
||||
filePath,
|
||||
line,
|
||||
})
|
||||
}
|
||||
|
||||
public get fromAggregate(): string {
|
||||
return this.props.fromAggregate
|
||||
}
|
||||
|
||||
public get toAggregate(): string {
|
||||
return this.props.toAggregate
|
||||
}
|
||||
|
||||
public get entityName(): string {
|
||||
return this.props.entityName
|
||||
}
|
||||
|
||||
public get importPath(): string {
|
||||
return this.props.importPath
|
||||
}
|
||||
|
||||
public get filePath(): string {
|
||||
return this.props.filePath
|
||||
}
|
||||
|
||||
public get line(): number | undefined {
|
||||
return this.props.line
|
||||
}
|
||||
|
||||
public getMessage(): string {
|
||||
return `${this.capitalizeFirst(this.props.fromAggregate)} aggregate should not directly reference ${this.props.entityName} entity from ${this.capitalizeFirst(this.props.toAggregate)} aggregate`
|
||||
}
|
||||
|
||||
public getSuggestion(): string {
|
||||
const suggestions: string[] = [
|
||||
AGGREGATE_VIOLATION_MESSAGES.USE_ID_REFERENCE,
|
||||
AGGREGATE_VIOLATION_MESSAGES.USE_VALUE_OBJECT,
|
||||
AGGREGATE_VIOLATION_MESSAGES.AVOID_DIRECT_REFERENCE,
|
||||
AGGREGATE_VIOLATION_MESSAGES.MAINTAIN_INDEPENDENCE,
|
||||
]
|
||||
|
||||
return suggestions.join("\n")
|
||||
}
|
||||
|
||||
public getExampleFix(): string {
|
||||
return `
|
||||
// ❌ Bad: Direct entity reference across aggregates
|
||||
// domain/aggregates/order/Order.ts
|
||||
import { User } from '../user/User'
|
||||
|
||||
class Order {
|
||||
constructor(private user: User) {}
|
||||
}
|
||||
|
||||
// ✅ Good: Reference by ID
|
||||
// domain/aggregates/order/Order.ts
|
||||
import { UserId } from '../user/value-objects/UserId'
|
||||
|
||||
class Order {
|
||||
constructor(private userId: UserId) {}
|
||||
}
|
||||
|
||||
// ✅ Good: Use Value Object for needed data
|
||||
// domain/aggregates/order/value-objects/CustomerInfo.ts
|
||||
class CustomerInfo {
|
||||
constructor(
|
||||
readonly customerId: string,
|
||||
readonly customerName: string,
|
||||
readonly customerEmail: string
|
||||
) {}
|
||||
}
|
||||
|
||||
// domain/aggregates/order/Order.ts
|
||||
class Order {
|
||||
constructor(private customerInfo: CustomerInfo) {}
|
||||
}`
|
||||
}
|
||||
|
||||
private capitalizeFirst(str: string): string {
|
||||
return str.charAt(0).toUpperCase() + str.slice(1)
|
||||
}
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
import { ValueObject } from "./ValueObject"
|
||||
import { REPOSITORY_VIOLATION_TYPES } from "../../shared/constants/rules"
|
||||
import { REPOSITORY_PATTERN_MESSAGES } from "../constants/Messages"
|
||||
import { REPOSITORY_FALLBACK_SUGGESTIONS, REPOSITORY_PATTERN_MESSAGES } from "../constants/Messages"
|
||||
|
||||
interface RepositoryViolationProps {
|
||||
readonly violationType:
|
||||
@@ -177,6 +177,9 @@ export class RepositoryViolation extends ValueObject<RepositoryViolationProps> {
|
||||
}
|
||||
|
||||
private getNonDomainMethodSuggestion(): string {
|
||||
const detailsMatch = /Consider: (.+)$/.exec(this.props.details)
|
||||
const smartSuggestion = detailsMatch ? detailsMatch[1] : null
|
||||
|
||||
const technicalToDomain = {
|
||||
findOne: REPOSITORY_PATTERN_MESSAGES.SUGGESTION_FINDONE,
|
||||
findMany: REPOSITORY_PATTERN_MESSAGES.SUGGESTION_FINDMANY,
|
||||
@@ -186,8 +189,10 @@ export class RepositoryViolation extends ValueObject<RepositoryViolationProps> {
|
||||
query: REPOSITORY_PATTERN_MESSAGES.SUGGESTION_QUERY,
|
||||
}
|
||||
|
||||
const suggestion =
|
||||
const fallbackSuggestion =
|
||||
technicalToDomain[this.props.methodName as keyof typeof technicalToDomain]
|
||||
const finalSuggestion =
|
||||
smartSuggestion || fallbackSuggestion || REPOSITORY_FALLBACK_SUGGESTIONS.DEFAULT
|
||||
|
||||
return [
|
||||
REPOSITORY_PATTERN_MESSAGES.STEP_RENAME_METHOD,
|
||||
@@ -196,7 +201,7 @@ export class RepositoryViolation extends ValueObject<RepositoryViolationProps> {
|
||||
"",
|
||||
REPOSITORY_PATTERN_MESSAGES.EXAMPLE_PREFIX,
|
||||
`❌ Bad: ${this.props.methodName || "findOne"}()`,
|
||||
`✅ Good: ${suggestion || "findById() or findByEmail()"}`,
|
||||
`✅ Good: ${finalSuggestion}`,
|
||||
].join("\n")
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,381 @@
|
||||
import { IAggregateBoundaryDetector } from "../../domain/services/IAggregateBoundaryDetector"
|
||||
import { AggregateBoundaryViolation } from "../../domain/value-objects/AggregateBoundaryViolation"
|
||||
import { LAYERS } from "../../shared/constants/rules"
|
||||
import { IMPORT_PATTERNS } from "../constants/paths"
|
||||
import { DDD_FOLDER_NAMES } from "../constants/detectorPatterns"
|
||||
|
||||
/**
|
||||
* Detects aggregate boundary violations in Domain-Driven Design
|
||||
*
|
||||
* This detector enforces DDD aggregate rules:
|
||||
* - Aggregates should reference each other only by ID or Value Objects
|
||||
* - Direct entity references across aggregates create tight coupling
|
||||
* - Each aggregate should be independently modifiable
|
||||
*
|
||||
* Folder structure patterns detected:
|
||||
* - domain/aggregates/order/Order.ts
|
||||
* - domain/order/Order.ts (aggregate name from parent folder)
|
||||
* - domain/entities/order/Order.ts
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const detector = new AggregateBoundaryDetector()
|
||||
*
|
||||
* // Detect violations in order aggregate
|
||||
* const code = `
|
||||
* import { User } from '../user/User'
|
||||
* import { UserId } from '../user/value-objects/UserId'
|
||||
* `
|
||||
* const violations = detector.detectViolations(
|
||||
* code,
|
||||
* 'src/domain/aggregates/order/Order.ts',
|
||||
* 'domain'
|
||||
* )
|
||||
*
|
||||
* // violations will contain 1 violation for direct User entity import
|
||||
* // but not for UserId (value object is allowed)
|
||||
* console.log(violations.length) // 1
|
||||
* ```
|
||||
*/
|
||||
export class AggregateBoundaryDetector implements IAggregateBoundaryDetector {
|
||||
private readonly entityFolderNames = new Set<string>([
|
||||
DDD_FOLDER_NAMES.ENTITIES,
|
||||
DDD_FOLDER_NAMES.AGGREGATES,
|
||||
])
|
||||
private readonly valueObjectFolderNames = new Set<string>([
|
||||
DDD_FOLDER_NAMES.VALUE_OBJECTS,
|
||||
DDD_FOLDER_NAMES.VO,
|
||||
])
|
||||
private readonly allowedFolderNames = new Set<string>([
|
||||
DDD_FOLDER_NAMES.VALUE_OBJECTS,
|
||||
DDD_FOLDER_NAMES.VO,
|
||||
DDD_FOLDER_NAMES.EVENTS,
|
||||
DDD_FOLDER_NAMES.DOMAIN_EVENTS,
|
||||
DDD_FOLDER_NAMES.REPOSITORIES,
|
||||
DDD_FOLDER_NAMES.SERVICES,
|
||||
DDD_FOLDER_NAMES.SPECIFICATIONS,
|
||||
DDD_FOLDER_NAMES.ERRORS,
|
||||
DDD_FOLDER_NAMES.EXCEPTIONS,
|
||||
])
|
||||
private readonly nonAggregateFolderNames = new Set<string>([
|
||||
DDD_FOLDER_NAMES.VALUE_OBJECTS,
|
||||
DDD_FOLDER_NAMES.VO,
|
||||
DDD_FOLDER_NAMES.EVENTS,
|
||||
DDD_FOLDER_NAMES.DOMAIN_EVENTS,
|
||||
DDD_FOLDER_NAMES.REPOSITORIES,
|
||||
DDD_FOLDER_NAMES.SERVICES,
|
||||
DDD_FOLDER_NAMES.SPECIFICATIONS,
|
||||
DDD_FOLDER_NAMES.ENTITIES,
|
||||
DDD_FOLDER_NAMES.CONSTANTS,
|
||||
DDD_FOLDER_NAMES.SHARED,
|
||||
DDD_FOLDER_NAMES.FACTORIES,
|
||||
DDD_FOLDER_NAMES.PORTS,
|
||||
DDD_FOLDER_NAMES.INTERFACES,
|
||||
DDD_FOLDER_NAMES.ERRORS,
|
||||
DDD_FOLDER_NAMES.EXCEPTIONS,
|
||||
])
|
||||
|
||||
/**
|
||||
* Detects aggregate boundary violations in the given code
|
||||
*
|
||||
* Analyzes import statements to identify direct entity references
|
||||
* across aggregate boundaries in the domain layer.
|
||||
*
|
||||
* @param code - Source code to analyze
|
||||
* @param filePath - Path to the file being analyzed
|
||||
* @param layer - The architectural layer of the file (should be 'domain')
|
||||
* @returns Array of detected aggregate boundary violations
|
||||
*/
|
||||
public detectViolations(
|
||||
code: string,
|
||||
filePath: string,
|
||||
layer: string | undefined,
|
||||
): AggregateBoundaryViolation[] {
|
||||
if (layer !== LAYERS.DOMAIN) {
|
||||
return []
|
||||
}
|
||||
|
||||
const currentAggregate = this.extractAggregateFromPath(filePath)
|
||||
if (!currentAggregate) {
|
||||
return []
|
||||
}
|
||||
|
||||
const violations: AggregateBoundaryViolation[] = []
|
||||
const lines = code.split("\n")
|
||||
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i]
|
||||
const lineNumber = i + 1
|
||||
|
||||
const imports = this.extractImports(line)
|
||||
for (const importPath of imports) {
|
||||
if (this.isAggregateBoundaryViolation(importPath, currentAggregate)) {
|
||||
const targetAggregate = this.extractAggregateFromImport(importPath)
|
||||
const entityName = this.extractEntityName(importPath)
|
||||
|
||||
if (targetAggregate && entityName) {
|
||||
violations.push(
|
||||
AggregateBoundaryViolation.create(
|
||||
currentAggregate,
|
||||
targetAggregate,
|
||||
entityName,
|
||||
importPath,
|
||||
filePath,
|
||||
lineNumber,
|
||||
),
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return violations
|
||||
}
|
||||
|
||||
/**
|
||||
* Checks if a file path belongs to an aggregate
|
||||
*
|
||||
* Extracts aggregate name from paths like:
|
||||
* - domain/aggregates/order/Order.ts → 'order'
|
||||
* - domain/order/Order.ts → 'order'
|
||||
* - domain/entities/order/Order.ts → 'order'
|
||||
*
|
||||
* @param filePath - The file path to check
|
||||
* @returns The aggregate name if found, undefined otherwise
|
||||
*/
|
||||
public extractAggregateFromPath(filePath: string): string | undefined {
|
||||
const normalizedPath = filePath.toLowerCase().replace(/\\/g, "/")
|
||||
|
||||
const domainMatch = /(?:^|\/)(domain)\//.exec(normalizedPath)
|
||||
if (!domainMatch) {
|
||||
return undefined
|
||||
}
|
||||
|
||||
const domainEndIndex = domainMatch.index + domainMatch[0].length
|
||||
const pathAfterDomain = normalizedPath.substring(domainEndIndex)
|
||||
const segments = pathAfterDomain.split("/").filter(Boolean)
|
||||
|
||||
if (segments.length < 2) {
|
||||
return undefined
|
||||
}
|
||||
|
||||
if (this.entityFolderNames.has(segments[0])) {
|
||||
if (segments.length < 3) {
|
||||
return undefined
|
||||
}
|
||||
const aggregate = segments[1]
|
||||
if (this.nonAggregateFolderNames.has(aggregate)) {
|
||||
return undefined
|
||||
}
|
||||
return aggregate
|
||||
}
|
||||
|
||||
const aggregate = segments[0]
|
||||
if (this.nonAggregateFolderNames.has(aggregate)) {
|
||||
return undefined
|
||||
}
|
||||
return aggregate
|
||||
}
|
||||
|
||||
/**
|
||||
* Checks if an import path references an entity from another aggregate
|
||||
*
|
||||
* @param importPath - The import path to analyze
|
||||
* @param currentAggregate - The aggregate of the current file
|
||||
* @returns True if the import crosses aggregate boundaries inappropriately
|
||||
*/
|
||||
public isAggregateBoundaryViolation(importPath: string, currentAggregate: string): boolean {
|
||||
const normalizedPath = importPath.replace(IMPORT_PATTERNS.QUOTE, "").toLowerCase()
|
||||
|
||||
if (!normalizedPath.includes("/")) {
|
||||
return false
|
||||
}
|
||||
|
||||
if (!normalizedPath.startsWith(".") && !normalizedPath.startsWith("/")) {
|
||||
return false
|
||||
}
|
||||
|
||||
// Check if import stays within the same bounded context
|
||||
if (this.isInternalBoundedContextImport(normalizedPath)) {
|
||||
return false
|
||||
}
|
||||
|
||||
const targetAggregate = this.extractAggregateFromImport(normalizedPath)
|
||||
if (!targetAggregate || targetAggregate === currentAggregate) {
|
||||
return false
|
||||
}
|
||||
|
||||
if (this.isAllowedImport(normalizedPath)) {
|
||||
return false
|
||||
}
|
||||
|
||||
return this.seemsLikeEntityImport(normalizedPath)
|
||||
}
|
||||
|
||||
/**
|
||||
* Checks if the import is internal to the same bounded context
|
||||
*
|
||||
* An import like "../aggregates/Entity" from "repositories/Repo" stays within
|
||||
* the same bounded context (one level up goes to the bounded context root).
|
||||
*
|
||||
* An import like "../../other-context/Entity" crosses bounded context boundaries.
|
||||
*/
|
||||
private isInternalBoundedContextImport(normalizedPath: string): boolean {
|
||||
const parts = normalizedPath.split("/")
|
||||
const dotDotCount = parts.filter((p) => p === "..").length
|
||||
|
||||
/*
|
||||
* If only one ".." and path goes into aggregates/entities folder,
|
||||
* it's likely an internal import within the same bounded context
|
||||
*/
|
||||
if (dotDotCount === 1) {
|
||||
const nonDotParts = parts.filter((p) => p !== ".." && p !== ".")
|
||||
if (nonDotParts.length >= 1) {
|
||||
const firstFolder = nonDotParts[0]
|
||||
// Importing from aggregates/entities within same bounded context is allowed
|
||||
if (this.entityFolderNames.has(firstFolder)) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return false
|
||||
}
|
||||
|
||||
/**
|
||||
* Checks if the import path is from an allowed folder (value-objects, events, etc.)
|
||||
*/
|
||||
private isAllowedImport(normalizedPath: string): boolean {
|
||||
for (const folderName of this.allowedFolderNames) {
|
||||
if (normalizedPath.includes(`/${folderName}/`)) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
/**
|
||||
* Checks if the import seems to be an entity (not a value object, event, etc.)
|
||||
*
|
||||
* Note: normalizedPath is already lowercased, so we check if the first character
|
||||
* is a letter (indicating it was likely PascalCase originally)
|
||||
*/
|
||||
private seemsLikeEntityImport(normalizedPath: string): boolean {
|
||||
const pathParts = normalizedPath.split("/")
|
||||
const lastPart = pathParts[pathParts.length - 1]
|
||||
|
||||
if (!lastPart) {
|
||||
return false
|
||||
}
|
||||
|
||||
const filename = lastPart.replace(/\.(ts|js)$/, "")
|
||||
|
||||
if (filename.length > 0 && /^[a-z][a-z]/.exec(filename)) {
|
||||
return true
|
||||
}
|
||||
|
||||
return false
|
||||
}
|
||||
|
||||
/**
|
||||
* Extracts the aggregate name from an import path
|
||||
*
|
||||
* Handles both absolute and relative paths:
|
||||
* - ../user/User → user
|
||||
* - ../../domain/user/User → user
|
||||
* - ../user/value-objects/UserId → user (but filtered as value object)
|
||||
*/
|
||||
private extractAggregateFromImport(importPath: string): string | undefined {
|
||||
const normalizedPath = importPath.replace(IMPORT_PATTERNS.QUOTE, "").toLowerCase()
|
||||
|
||||
const segments = normalizedPath.split("/").filter((seg) => seg !== ".." && seg !== ".")
|
||||
|
||||
if (segments.length === 0) {
|
||||
return undefined
|
||||
}
|
||||
|
||||
for (let i = 0; i < segments.length; i++) {
|
||||
if (
|
||||
segments[i] === DDD_FOLDER_NAMES.DOMAIN ||
|
||||
segments[i] === DDD_FOLDER_NAMES.AGGREGATES
|
||||
) {
|
||||
if (i + 1 < segments.length) {
|
||||
if (
|
||||
this.entityFolderNames.has(segments[i + 1]) ||
|
||||
segments[i + 1] === DDD_FOLDER_NAMES.AGGREGATES
|
||||
) {
|
||||
if (i + 2 < segments.length) {
|
||||
return segments[i + 2]
|
||||
}
|
||||
} else {
|
||||
return segments[i + 1]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (segments.length >= 2) {
|
||||
const secondLastSegment = segments[segments.length - 2]
|
||||
|
||||
if (
|
||||
!this.entityFolderNames.has(secondLastSegment) &&
|
||||
!this.valueObjectFolderNames.has(secondLastSegment) &&
|
||||
!this.allowedFolderNames.has(secondLastSegment) &&
|
||||
secondLastSegment !== DDD_FOLDER_NAMES.DOMAIN
|
||||
) {
|
||||
return secondLastSegment
|
||||
}
|
||||
}
|
||||
|
||||
if (segments.length === 1) {
|
||||
return undefined
|
||||
}
|
||||
|
||||
return undefined
|
||||
}
|
||||
|
||||
/**
|
||||
* Extracts the entity name from an import path
|
||||
*/
|
||||
private extractEntityName(importPath: string): string | undefined {
|
||||
const normalizedPath = importPath.replace(IMPORT_PATTERNS.QUOTE, "")
|
||||
const segments = normalizedPath.split("/")
|
||||
const lastSegment = segments[segments.length - 1]
|
||||
|
||||
if (lastSegment) {
|
||||
return lastSegment.replace(/\.(ts|js)$/, "")
|
||||
}
|
||||
|
||||
return undefined
|
||||
}
|
||||
|
||||
/**
|
||||
* Extracts import paths from a line of code
|
||||
*
|
||||
* Handles various import statement formats:
|
||||
* - import { X } from 'path'
|
||||
* - import X from 'path'
|
||||
* - import * as X from 'path'
|
||||
* - const X = require('path')
|
||||
*
|
||||
* @param line - A line of code to analyze
|
||||
* @returns Array of import paths found in the line
|
||||
*/
|
||||
private extractImports(line: string): string[] {
|
||||
const imports: string[] = []
|
||||
|
||||
let match = IMPORT_PATTERNS.ES_IMPORT.exec(line)
|
||||
while (match) {
|
||||
imports.push(match[1])
|
||||
match = IMPORT_PATTERNS.ES_IMPORT.exec(line)
|
||||
}
|
||||
|
||||
match = IMPORT_PATTERNS.REQUIRE.exec(line)
|
||||
while (match) {
|
||||
imports.push(match[1])
|
||||
match = IMPORT_PATTERNS.REQUIRE.exec(line)
|
||||
}
|
||||
|
||||
return imports
|
||||
}
|
||||
}
|
||||
@@ -26,6 +26,19 @@ export class HardcodeDetector implements IHardcodeDetector {
|
||||
|
||||
private readonly ALLOWED_STRING_PATTERNS = [/^[a-z]$/i, /^\/$/, /^\\$/, /^\s+$/, /^,$/, /^\.$/]
|
||||
|
||||
/**
|
||||
* Patterns to detect TypeScript type contexts where strings should be ignored
|
||||
*/
|
||||
private readonly TYPE_CONTEXT_PATTERNS = [
|
||||
/^\s*type\s+\w+\s*=/i, // type Foo = ...
|
||||
/^\s*interface\s+\w+/i, // interface Foo { ... }
|
||||
/^\s*\w+\s*:\s*['"`]/, // property: 'value' (in type or interface)
|
||||
/\s+as\s+['"`]/, // ... as 'type'
|
||||
/Record<.*,\s*import\(/, // Record with import type
|
||||
/typeof\s+\w+\s*===\s*['"`]/, // typeof x === 'string'
|
||||
/['"`]\s*===\s*typeof\s+\w+/, // 'string' === typeof x
|
||||
]
|
||||
|
||||
/**
|
||||
* Detects all hardcoded values (both numbers and strings) in the given code
|
||||
*
|
||||
@@ -43,14 +56,15 @@ export class HardcodeDetector implements IHardcodeDetector {
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a file is a constants definition file
|
||||
* Check if a file is a constants definition file or DI tokens file
|
||||
*/
|
||||
private isConstantsFile(filePath: string): boolean {
|
||||
const _fileName = filePath.split("/").pop() ?? ""
|
||||
const constantsPatterns = [
|
||||
/^constants?\.(ts|js)$/i,
|
||||
/constants?\/.*\.(ts|js)$/i,
|
||||
/\/(constants|config|settings|defaults)\.ts$/i,
|
||||
/\/(constants|config|settings|defaults|tokens)\.ts$/i,
|
||||
/\/di\/tokens\.(ts|js)$/i,
|
||||
]
|
||||
return constantsPatterns.some((pattern) => pattern.test(filePath))
|
||||
}
|
||||
@@ -341,6 +355,18 @@ export class HardcodeDetector implements IHardcodeDetector {
|
||||
return false
|
||||
}
|
||||
|
||||
if (this.isInTypeContext(line)) {
|
||||
return false
|
||||
}
|
||||
|
||||
if (this.isInSymbolCall(line, value)) {
|
||||
return false
|
||||
}
|
||||
|
||||
if (this.isInImportCall(line, value)) {
|
||||
return false
|
||||
}
|
||||
|
||||
if (value.includes(DETECTION_KEYWORDS.HTTP) || value.includes(DETECTION_KEYWORDS.API)) {
|
||||
return true
|
||||
}
|
||||
@@ -388,4 +414,46 @@ export class HardcodeDetector implements IHardcodeDetector {
|
||||
const end = Math.min(line.length, index + 30)
|
||||
return line.substring(start, end)
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a line is in a TypeScript type definition context
|
||||
* Examples:
|
||||
* - type Foo = 'a' | 'b'
|
||||
* - interface Bar { prop: 'value' }
|
||||
* - Record<X, import('path')>
|
||||
* - ... as 'type'
|
||||
*/
|
||||
private isInTypeContext(line: string): boolean {
|
||||
const trimmedLine = line.trim()
|
||||
|
||||
if (this.TYPE_CONTEXT_PATTERNS.some((pattern) => pattern.test(trimmedLine))) {
|
||||
return true
|
||||
}
|
||||
|
||||
if (trimmedLine.includes("|") && /['"`][^'"`]+['"`]\s*\|/.test(trimmedLine)) {
|
||||
return true
|
||||
}
|
||||
|
||||
return false
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a string is inside a Symbol() call
|
||||
* Example: Symbol('TOKEN_NAME')
|
||||
*/
|
||||
private isInSymbolCall(line: string, stringValue: string): boolean {
|
||||
const symbolPattern = new RegExp(
|
||||
`Symbol\\s*\\(\\s*['"\`]${stringValue.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}['"\`]\\s*\\)`,
|
||||
)
|
||||
return symbolPattern.test(line)
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a string is inside an import() call
|
||||
* Example: import('../../path/to/module.js')
|
||||
*/
|
||||
private isInImportCall(line: string, stringValue: string): boolean {
|
||||
const importPattern = /import\s*\(\s*['"`][^'"`]+['"`]\s*\)/
|
||||
return importPattern.test(line) && line.includes(stringValue)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -3,6 +3,7 @@ import { RepositoryViolation } from "../../domain/value-objects/RepositoryViolat
|
||||
import { LAYERS, REPOSITORY_VIOLATION_TYPES } from "../../shared/constants/rules"
|
||||
import { ORM_QUERY_METHODS } from "../constants/orm-methods"
|
||||
import { REPOSITORY_PATTERN_MESSAGES } from "../../domain/constants/Messages"
|
||||
import { REPOSITORY_METHOD_SUGGESTIONS } from "../constants/detectorPatterns"
|
||||
|
||||
/**
|
||||
* Detects Repository Pattern violations in the codebase
|
||||
@@ -68,27 +69,39 @@ export class RepositoryPatternDetector implements IRepositoryPatternDetector {
|
||||
|
||||
private readonly domainMethodPatterns = [
|
||||
/^findBy[A-Z]/,
|
||||
/^findAll/,
|
||||
/^findAll$/,
|
||||
/^find[A-Z]/,
|
||||
/^save$/,
|
||||
/^saveAll$/,
|
||||
/^create$/,
|
||||
/^update$/,
|
||||
/^delete$/,
|
||||
/^deleteBy[A-Z]/,
|
||||
/^deleteAll$/,
|
||||
/^remove$/,
|
||||
/^removeBy[A-Z]/,
|
||||
/^removeAll$/,
|
||||
/^add$/,
|
||||
/^add[A-Z]/,
|
||||
/^get[A-Z]/,
|
||||
/^getAll$/,
|
||||
/^search/,
|
||||
/^list/,
|
||||
/^has[A-Z]/,
|
||||
/^is[A-Z]/,
|
||||
/^exists$/,
|
||||
/^exists[A-Z]/,
|
||||
/^existsBy[A-Z]/,
|
||||
/^clear[A-Z]/,
|
||||
/^clearAll$/,
|
||||
/^store[A-Z]/,
|
||||
/^initialize$/,
|
||||
/^initializeCollection$/,
|
||||
/^close$/,
|
||||
/^connect$/,
|
||||
/^disconnect$/,
|
||||
/^count$/,
|
||||
/^countBy[A-Z]/,
|
||||
]
|
||||
|
||||
private readonly concreteRepositoryPatterns = [
|
||||
@@ -237,6 +250,73 @@ export class RepositoryPatternDetector implements IRepositoryPatternDetector {
|
||||
return violations
|
||||
}
|
||||
|
||||
/**
|
||||
* Suggests better domain method names based on the original method name
|
||||
*/
|
||||
private suggestDomainMethodName(methodName: string): string {
|
||||
const lowerName = methodName.toLowerCase()
|
||||
const suggestions: string[] = []
|
||||
|
||||
const suggestionMap: Record<string, string[]> = {
|
||||
query: [
|
||||
REPOSITORY_METHOD_SUGGESTIONS.SEARCH,
|
||||
REPOSITORY_METHOD_SUGGESTIONS.FIND_BY_PROPERTY,
|
||||
],
|
||||
select: [
|
||||
REPOSITORY_METHOD_SUGGESTIONS.FIND_BY_PROPERTY,
|
||||
REPOSITORY_METHOD_SUGGESTIONS.GET_ENTITY,
|
||||
],
|
||||
insert: [
|
||||
REPOSITORY_METHOD_SUGGESTIONS.CREATE,
|
||||
REPOSITORY_METHOD_SUGGESTIONS.ADD_ENTITY,
|
||||
REPOSITORY_METHOD_SUGGESTIONS.STORE_ENTITY,
|
||||
],
|
||||
update: [
|
||||
REPOSITORY_METHOD_SUGGESTIONS.UPDATE,
|
||||
REPOSITORY_METHOD_SUGGESTIONS.MODIFY_ENTITY,
|
||||
],
|
||||
upsert: [
|
||||
REPOSITORY_METHOD_SUGGESTIONS.SAVE,
|
||||
REPOSITORY_METHOD_SUGGESTIONS.STORE_ENTITY,
|
||||
],
|
||||
remove: [
|
||||
REPOSITORY_METHOD_SUGGESTIONS.DELETE,
|
||||
REPOSITORY_METHOD_SUGGESTIONS.REMOVE_BY_PROPERTY,
|
||||
],
|
||||
fetch: [
|
||||
REPOSITORY_METHOD_SUGGESTIONS.FIND_BY_PROPERTY,
|
||||
REPOSITORY_METHOD_SUGGESTIONS.GET_ENTITY,
|
||||
],
|
||||
retrieve: [
|
||||
REPOSITORY_METHOD_SUGGESTIONS.FIND_BY_PROPERTY,
|
||||
REPOSITORY_METHOD_SUGGESTIONS.GET_ENTITY,
|
||||
],
|
||||
load: [
|
||||
REPOSITORY_METHOD_SUGGESTIONS.FIND_BY_PROPERTY,
|
||||
REPOSITORY_METHOD_SUGGESTIONS.GET_ENTITY,
|
||||
],
|
||||
}
|
||||
|
||||
for (const [keyword, keywords] of Object.entries(suggestionMap)) {
|
||||
if (lowerName.includes(keyword)) {
|
||||
suggestions.push(...keywords)
|
||||
}
|
||||
}
|
||||
|
||||
if (lowerName.includes("get") && lowerName.includes("all")) {
|
||||
suggestions.push(
|
||||
REPOSITORY_METHOD_SUGGESTIONS.FIND_ALL,
|
||||
REPOSITORY_METHOD_SUGGESTIONS.LIST_ALL,
|
||||
)
|
||||
}
|
||||
|
||||
if (suggestions.length === 0) {
|
||||
return REPOSITORY_METHOD_SUGGESTIONS.DEFAULT_SUGGESTION
|
||||
}
|
||||
|
||||
return `Consider: ${suggestions.slice(0, 3).join(", ")}`
|
||||
}
|
||||
|
||||
/**
|
||||
* Detects non-domain method names in repository interfaces
|
||||
*/
|
||||
@@ -258,13 +338,14 @@ export class RepositoryPatternDetector implements IRepositoryPatternDetector {
|
||||
const methodName = methodMatch[1]
|
||||
|
||||
if (!this.isDomainMethodName(methodName) && !line.trim().startsWith("//")) {
|
||||
const suggestion = this.suggestDomainMethodName(methodName)
|
||||
violations.push(
|
||||
RepositoryViolation.create(
|
||||
REPOSITORY_VIOLATION_TYPES.NON_DOMAIN_METHOD_NAME,
|
||||
filePath,
|
||||
layer || LAYERS.DOMAIN,
|
||||
lineNumber,
|
||||
`Method '${methodName}' uses technical name instead of domain language`,
|
||||
`Method '${methodName}' uses technical name instead of domain language. ${suggestion}`,
|
||||
undefined,
|
||||
undefined,
|
||||
methodName,
|
||||
|
||||
@@ -64,3 +64,47 @@ export const NAMING_ERROR_MESSAGES = {
|
||||
USE_VERB_NOUN: "Use verb + noun in PascalCase (e.g., CreateUser.ts, UpdateProfile.ts)",
|
||||
USE_CASE_START_VERB: "Use cases should start with a verb",
|
||||
} as const
|
||||
|
||||
/**
|
||||
* DDD folder names for aggregate boundary detection
|
||||
*/
|
||||
export const DDD_FOLDER_NAMES = {
|
||||
ENTITIES: "entities",
|
||||
AGGREGATES: "aggregates",
|
||||
VALUE_OBJECTS: "value-objects",
|
||||
VO: "vo",
|
||||
EVENTS: "events",
|
||||
DOMAIN_EVENTS: "domain-events",
|
||||
REPOSITORIES: "repositories",
|
||||
SERVICES: "services",
|
||||
SPECIFICATIONS: "specifications",
|
||||
DOMAIN: "domain",
|
||||
CONSTANTS: "constants",
|
||||
SHARED: "shared",
|
||||
FACTORIES: "factories",
|
||||
PORTS: "ports",
|
||||
INTERFACES: "interfaces",
|
||||
ERRORS: "errors",
|
||||
EXCEPTIONS: "exceptions",
|
||||
} as const
|
||||
|
||||
/**
|
||||
* Repository method suggestions for domain language
|
||||
*/
|
||||
export const REPOSITORY_METHOD_SUGGESTIONS = {
|
||||
SEARCH: "search",
|
||||
FIND_BY_PROPERTY: "findBy[Property]",
|
||||
GET_ENTITY: "get[Entity]",
|
||||
CREATE: "create",
|
||||
ADD_ENTITY: "add[Entity]",
|
||||
STORE_ENTITY: "store[Entity]",
|
||||
UPDATE: "update",
|
||||
MODIFY_ENTITY: "modify[Entity]",
|
||||
SAVE: "save",
|
||||
DELETE: "delete",
|
||||
REMOVE_BY_PROPERTY: "removeBy[Property]",
|
||||
FIND_ALL: "findAll",
|
||||
LIST_ALL: "listAll",
|
||||
DEFAULT_SUGGESTION:
|
||||
"Use domain-specific names like: findBy[Property], save, create, delete, update, add[Entity]",
|
||||
} as const
|
||||
|
||||
@@ -2,7 +2,6 @@ export const ORM_QUERY_METHODS = [
|
||||
"findOne",
|
||||
"findMany",
|
||||
"findFirst",
|
||||
"findAll",
|
||||
"findAndCountAll",
|
||||
"insert",
|
||||
"insertMany",
|
||||
@@ -17,8 +16,6 @@ export const ORM_QUERY_METHODS = [
|
||||
"run",
|
||||
"exec",
|
||||
"aggregate",
|
||||
"count",
|
||||
"exists",
|
||||
] as const
|
||||
|
||||
export type OrmQueryMethod = (typeof ORM_QUERY_METHODS)[number]
|
||||
|
||||
@@ -88,6 +88,7 @@ export const SEVERITY_ORDER: Record<SeverityLevel, number> = {
|
||||
export const VIOLATION_SEVERITY_MAP = {
|
||||
CIRCULAR_DEPENDENCY: SEVERITY_LEVELS.CRITICAL,
|
||||
REPOSITORY_PATTERN: SEVERITY_LEVELS.CRITICAL,
|
||||
AGGREGATE_BOUNDARY: SEVERITY_LEVELS.CRITICAL,
|
||||
DEPENDENCY_DIRECTION: SEVERITY_LEVELS.HIGH,
|
||||
FRAMEWORK_LEAK: SEVERITY_LEVELS.HIGH,
|
||||
ENTITY_EXPOSURE: SEVERITY_LEVELS.HIGH,
|
||||
|
||||
@@ -10,6 +10,7 @@ export const RULES = {
|
||||
ENTITY_EXPOSURE: "entity-exposure",
|
||||
DEPENDENCY_DIRECTION: "dependency-direction",
|
||||
REPOSITORY_PATTERN: "repository-pattern",
|
||||
AGGREGATE_BOUNDARY: "aggregate-boundary",
|
||||
} as const
|
||||
|
||||
/**
|
||||
|
||||
538
packages/guardian/tests/AggregateBoundaryDetector.test.ts
Normal file
538
packages/guardian/tests/AggregateBoundaryDetector.test.ts
Normal file
@@ -0,0 +1,538 @@
|
||||
import { describe, it, expect } from "vitest"
|
||||
import { AggregateBoundaryDetector } from "../src/infrastructure/analyzers/AggregateBoundaryDetector"
|
||||
import { LAYERS } from "../src/shared/constants/rules"
|
||||
|
||||
describe("AggregateBoundaryDetector", () => {
|
||||
const detector = new AggregateBoundaryDetector()
|
||||
|
||||
describe("extractAggregateFromPath", () => {
|
||||
it("should extract aggregate from domain/aggregates/name path", () => {
|
||||
expect(detector.extractAggregateFromPath("src/domain/aggregates/order/Order.ts")).toBe(
|
||||
"order",
|
||||
)
|
||||
expect(detector.extractAggregateFromPath("src/domain/aggregates/user/User.ts")).toBe(
|
||||
"user",
|
||||
)
|
||||
expect(
|
||||
detector.extractAggregateFromPath("src/domain/aggregates/product/Product.ts"),
|
||||
).toBe("product")
|
||||
})
|
||||
|
||||
it("should extract aggregate from domain/name path", () => {
|
||||
expect(detector.extractAggregateFromPath("src/domain/order/Order.ts")).toBe("order")
|
||||
expect(detector.extractAggregateFromPath("src/domain/user/User.ts")).toBe("user")
|
||||
expect(detector.extractAggregateFromPath("src/domain/cart/ShoppingCart.ts")).toBe(
|
||||
"cart",
|
||||
)
|
||||
})
|
||||
|
||||
it("should extract aggregate from domain/entities/name path", () => {
|
||||
expect(detector.extractAggregateFromPath("src/domain/entities/order/Order.ts")).toBe(
|
||||
"order",
|
||||
)
|
||||
expect(detector.extractAggregateFromPath("src/domain/entities/user/User.ts")).toBe(
|
||||
"user",
|
||||
)
|
||||
})
|
||||
|
||||
it("should return undefined for non-domain paths", () => {
|
||||
expect(
|
||||
detector.extractAggregateFromPath("src/application/use-cases/CreateUser.ts"),
|
||||
).toBeUndefined()
|
||||
expect(
|
||||
detector.extractAggregateFromPath(
|
||||
"src/infrastructure/repositories/UserRepository.ts",
|
||||
),
|
||||
).toBeUndefined()
|
||||
expect(detector.extractAggregateFromPath("src/shared/types/Result.ts")).toBeUndefined()
|
||||
})
|
||||
|
||||
it("should return undefined for paths without aggregate structure", () => {
|
||||
expect(detector.extractAggregateFromPath("src/domain/User.ts")).toBeUndefined()
|
||||
expect(detector.extractAggregateFromPath("src/User.ts")).toBeUndefined()
|
||||
})
|
||||
|
||||
it("should handle Windows-style paths", () => {
|
||||
expect(
|
||||
detector.extractAggregateFromPath("src\\domain\\aggregates\\order\\Order.ts"),
|
||||
).toBe("order")
|
||||
expect(detector.extractAggregateFromPath("src\\domain\\user\\User.ts")).toBe("user")
|
||||
})
|
||||
})
|
||||
|
||||
describe("isAggregateBoundaryViolation", () => {
|
||||
it("should detect direct entity import from another aggregate", () => {
|
||||
expect(detector.isAggregateBoundaryViolation("../user/User", "order")).toBe(true)
|
||||
expect(detector.isAggregateBoundaryViolation("../../user/User", "order")).toBe(true)
|
||||
expect(
|
||||
detector.isAggregateBoundaryViolation("../../../domain/user/User", "order"),
|
||||
).toBe(true)
|
||||
})
|
||||
|
||||
it("should NOT detect import from same aggregate", () => {
|
||||
expect(detector.isAggregateBoundaryViolation("../order/Order", "order")).toBe(false)
|
||||
expect(detector.isAggregateBoundaryViolation("./OrderItem", "order")).toBe(false)
|
||||
})
|
||||
|
||||
it("should NOT detect value object imports", () => {
|
||||
expect(
|
||||
detector.isAggregateBoundaryViolation("../user/value-objects/UserId", "order"),
|
||||
).toBe(false)
|
||||
expect(detector.isAggregateBoundaryViolation("../user/vo/Email", "order")).toBe(false)
|
||||
})
|
||||
|
||||
it("should NOT detect event imports", () => {
|
||||
expect(
|
||||
detector.isAggregateBoundaryViolation("../user/events/UserCreatedEvent", "order"),
|
||||
).toBe(false)
|
||||
expect(
|
||||
detector.isAggregateBoundaryViolation(
|
||||
"../user/domain-events/UserRegisteredEvent",
|
||||
"order",
|
||||
),
|
||||
).toBe(false)
|
||||
})
|
||||
|
||||
it("should NOT detect repository interface imports", () => {
|
||||
expect(
|
||||
detector.isAggregateBoundaryViolation(
|
||||
"../user/repositories/IUserRepository",
|
||||
"order",
|
||||
),
|
||||
).toBe(false)
|
||||
})
|
||||
|
||||
it("should NOT detect service imports", () => {
|
||||
expect(
|
||||
detector.isAggregateBoundaryViolation("../user/services/UserService", "order"),
|
||||
).toBe(false)
|
||||
})
|
||||
|
||||
it("should NOT detect external package imports", () => {
|
||||
expect(detector.isAggregateBoundaryViolation("express", "order")).toBe(false)
|
||||
expect(detector.isAggregateBoundaryViolation("@nestjs/common", "order")).toBe(false)
|
||||
})
|
||||
|
||||
it("should NOT detect imports without path separator", () => {
|
||||
expect(detector.isAggregateBoundaryViolation("User", "order")).toBe(false)
|
||||
})
|
||||
})
|
||||
|
||||
describe("detectViolations", () => {
|
||||
describe("Domain layer aggregate boundary violations", () => {
|
||||
it("should detect direct entity import from another aggregate", () => {
|
||||
const code = `
|
||||
import { User } from '../user/User'
|
||||
|
||||
export class Order {
|
||||
constructor(private user: User) {}
|
||||
}`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(1)
|
||||
expect(violations[0].fromAggregate).toBe("order")
|
||||
expect(violations[0].toAggregate).toBe("user")
|
||||
expect(violations[0].entityName).toBe("User")
|
||||
expect(violations[0].importPath).toBe("../user/User")
|
||||
expect(violations[0].line).toBe(2)
|
||||
})
|
||||
|
||||
it("should detect multiple entity imports from different aggregates", () => {
|
||||
const code = `
|
||||
import { User } from '../user/User'
|
||||
import { Product } from '../product/Product'
|
||||
import { Category } from '../catalog/Category'
|
||||
|
||||
export class Order {
|
||||
constructor(
|
||||
private user: User,
|
||||
private product: Product,
|
||||
private category: Category
|
||||
) {}
|
||||
}`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(3)
|
||||
expect(violations[0].entityName).toBe("User")
|
||||
expect(violations[1].entityName).toBe("Product")
|
||||
expect(violations[2].entityName).toBe("Category")
|
||||
})
|
||||
|
||||
it("should NOT detect value object imports", () => {
|
||||
const code = `
|
||||
import { UserId } from '../user/value-objects/UserId'
|
||||
import { ProductId } from '../product/value-objects/ProductId'
|
||||
|
||||
export class Order {
|
||||
constructor(
|
||||
private userId: UserId,
|
||||
private productId: ProductId
|
||||
) {}
|
||||
}`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should NOT detect event imports", () => {
|
||||
const code = `
|
||||
import { UserCreatedEvent } from '../user/events/UserCreatedEvent'
|
||||
import { ProductAddedEvent } from '../product/domain-events/ProductAddedEvent'
|
||||
|
||||
export class Order {
|
||||
handle(event: UserCreatedEvent): void {}
|
||||
}`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should NOT detect repository interface imports", () => {
|
||||
const code = `
|
||||
import { IUserRepository } from '../user/repositories/IUserRepository'
|
||||
|
||||
export class OrderService {
|
||||
constructor(private userRepo: IUserRepository) {}
|
||||
}`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/OrderService.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should NOT detect imports from same aggregate", () => {
|
||||
const code = `
|
||||
import { OrderItem } from './OrderItem'
|
||||
import { OrderStatus } from './value-objects/OrderStatus'
|
||||
|
||||
export class Order {
|
||||
constructor(
|
||||
private items: OrderItem[],
|
||||
private status: OrderStatus
|
||||
) {}
|
||||
}`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(0)
|
||||
})
|
||||
})
|
||||
|
||||
describe("Non-domain layers", () => {
|
||||
it("should return empty array for application layer", () => {
|
||||
const code = `
|
||||
import { User } from '../../domain/aggregates/user/User'
|
||||
import { Order } from '../../domain/aggregates/order/Order'
|
||||
|
||||
export class CreateOrder {
|
||||
constructor() {}
|
||||
}`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/application/use-cases/CreateOrder.ts",
|
||||
LAYERS.APPLICATION,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should return empty array for infrastructure layer", () => {
|
||||
const code = `
|
||||
import { User } from '../../domain/aggregates/user/User'
|
||||
|
||||
export class UserController {
|
||||
constructor() {}
|
||||
}`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/infrastructure/controllers/UserController.ts",
|
||||
LAYERS.INFRASTRUCTURE,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should return empty array for undefined layer", () => {
|
||||
const code = `import { User } from '../user/User'`
|
||||
const violations = detector.detectViolations(code, "src/utils/helper.ts", undefined)
|
||||
|
||||
expect(violations).toHaveLength(0)
|
||||
})
|
||||
})
|
||||
|
||||
describe("Import statement formats", () => {
|
||||
it("should detect violations in named imports", () => {
|
||||
const code = `import { User, UserProfile } from '../user/User'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(1)
|
||||
})
|
||||
|
||||
it("should detect violations in default imports", () => {
|
||||
const code = `import User from '../user/User'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(1)
|
||||
})
|
||||
|
||||
it("should detect violations in namespace imports", () => {
|
||||
const code = `import * as UserAggregate from '../user/User'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(1)
|
||||
})
|
||||
|
||||
it("should detect violations in require statements", () => {
|
||||
const code = `const User = require('../user/User')`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(1)
|
||||
})
|
||||
})
|
||||
|
||||
describe("Different path structures", () => {
|
||||
it("should detect violations in domain/aggregates/name structure", () => {
|
||||
const code = `import { User } from '../user/User'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(1)
|
||||
expect(violations[0].fromAggregate).toBe("order")
|
||||
expect(violations[0].toAggregate).toBe("user")
|
||||
})
|
||||
|
||||
it("should detect violations in domain/name structure", () => {
|
||||
const code = `import { User } from '../user/User'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(1)
|
||||
expect(violations[0].fromAggregate).toBe("order")
|
||||
expect(violations[0].toAggregate).toBe("user")
|
||||
})
|
||||
|
||||
it("should detect violations in domain/entities/name structure", () => {
|
||||
const code = `import { User } from '../../user/User'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/entities/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(1)
|
||||
expect(violations[0].fromAggregate).toBe("order")
|
||||
expect(violations[0].toAggregate).toBe("user")
|
||||
})
|
||||
})
|
||||
|
||||
describe("Edge cases", () => {
|
||||
it("should handle empty code", () => {
|
||||
const violations = detector.detectViolations(
|
||||
"",
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should handle code with no imports", () => {
|
||||
const code = `
|
||||
export class Order {
|
||||
constructor(private id: string) {}
|
||||
}`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should handle file without aggregate in path", () => {
|
||||
const code = `import { User } from '../user/User'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should handle comments in imports", () => {
|
||||
const code = `
|
||||
// This is a comment
|
||||
import { User } from '../user/User' // Bad import
|
||||
`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(1)
|
||||
})
|
||||
})
|
||||
|
||||
describe("getMessage", () => {
|
||||
it("should return correct violation message", () => {
|
||||
const code = `import { User } from '../user/User'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations[0].getMessage()).toBe(
|
||||
"Order aggregate should not directly reference User entity from User aggregate",
|
||||
)
|
||||
})
|
||||
|
||||
it("should capitalize aggregate names in message", () => {
|
||||
const code = `import { Product } from '../product/Product'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/cart/ShoppingCart.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations[0].getMessage()).toContain("Cart aggregate")
|
||||
expect(violations[0].getMessage()).toContain("Product aggregate")
|
||||
})
|
||||
})
|
||||
|
||||
describe("getSuggestion", () => {
|
||||
it("should return suggestions for fixing aggregate boundary violations", () => {
|
||||
const code = `import { User } from '../user/User'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
const suggestion = violations[0].getSuggestion()
|
||||
expect(suggestion).toContain("Reference other aggregates by ID")
|
||||
expect(suggestion).toContain("Use Value Objects")
|
||||
expect(suggestion).toContain("Avoid direct entity references")
|
||||
expect(suggestion).toContain("independently modifiable")
|
||||
})
|
||||
})
|
||||
|
||||
describe("getExampleFix", () => {
|
||||
it("should return example fix for aggregate boundary violation", () => {
|
||||
const code = `import { User } from '../user/User'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
const example = violations[0].getExampleFix()
|
||||
expect(example).toContain("// ❌ Bad")
|
||||
expect(example).toContain("// ✅ Good")
|
||||
expect(example).toContain("UserId")
|
||||
expect(example).toContain("CustomerInfo")
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
describe("Complex scenarios", () => {
|
||||
it("should detect mixed valid and invalid imports", () => {
|
||||
const code = `
|
||||
import { User } from '../user/User' // VIOLATION
|
||||
import { UserId } from '../user/value-objects/UserId' // OK
|
||||
import { Product } from '../product/Product' // VIOLATION
|
||||
import { ProductId } from '../product/value-objects/ProductId' // OK
|
||||
import { OrderItem } from './OrderItem' // OK - same aggregate
|
||||
|
||||
export class Order {
|
||||
constructor(
|
||||
private user: User,
|
||||
private userId: UserId,
|
||||
private product: Product,
|
||||
private productId: ProductId,
|
||||
private items: OrderItem[]
|
||||
) {}
|
||||
}`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(2)
|
||||
expect(violations[0].entityName).toBe("User")
|
||||
expect(violations[1].entityName).toBe("Product")
|
||||
})
|
||||
|
||||
it("should handle deeply nested import paths", () => {
|
||||
const code = `import { User } from '../../../domain/aggregates/user/entities/User'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(1)
|
||||
expect(violations[0].entityName).toBe("User")
|
||||
})
|
||||
|
||||
it("should detect violations with .ts extension in import", () => {
|
||||
const code = `import { User } from '../user/User.ts'`
|
||||
const violations = detector.detectViolations(
|
||||
code,
|
||||
"src/domain/aggregates/order/Order.ts",
|
||||
LAYERS.DOMAIN,
|
||||
)
|
||||
|
||||
expect(violations).toHaveLength(1)
|
||||
expect(violations[0].entityName).toBe("User")
|
||||
})
|
||||
})
|
||||
})
|
||||
@@ -468,4 +468,102 @@ const b = 2`
|
||||
expect(result[0].context).toContain("5000")
|
||||
})
|
||||
})
|
||||
|
||||
describe("TypeScript type contexts (false positive reduction)", () => {
|
||||
it("should NOT detect strings in union types", () => {
|
||||
const code = `type Status = 'active' | 'inactive' | 'pending'`
|
||||
const result = detector.detectMagicStrings(code, "test.ts")
|
||||
|
||||
expect(result).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should NOT detect strings in interface property types", () => {
|
||||
const code = `interface Config { mode: 'development' | 'production' }`
|
||||
const result = detector.detectMagicStrings(code, "test.ts")
|
||||
|
||||
expect(result).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should NOT detect strings in type aliases", () => {
|
||||
const code = `type Theme = 'light' | 'dark'`
|
||||
const result = detector.detectMagicStrings(code, "test.ts")
|
||||
|
||||
expect(result).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should NOT detect strings in type assertions", () => {
|
||||
const code = `const mode = getMode() as 'read' | 'write'`
|
||||
const result = detector.detectMagicStrings(code, "test.ts")
|
||||
|
||||
expect(result).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should NOT detect strings in Symbol() calls", () => {
|
||||
const code = `const TOKEN = Symbol('MY_TOKEN')`
|
||||
const result = detector.detectMagicStrings(code, "test.ts")
|
||||
|
||||
expect(result).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should NOT detect strings in multiple Symbol() calls", () => {
|
||||
const code = `
|
||||
export const LOGGER = Symbol('LOGGER')
|
||||
export const DATABASE = Symbol('DATABASE')
|
||||
export const CACHE = Symbol('CACHE')
|
||||
`
|
||||
const result = detector.detectMagicStrings(code, "test.ts")
|
||||
|
||||
expect(result).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should NOT detect strings in import() calls", () => {
|
||||
const code = `const module = import('../../path/to/module.js')`
|
||||
const result = detector.detectMagicStrings(code, "test.ts")
|
||||
|
||||
expect(result).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should NOT detect strings in typeof checks", () => {
|
||||
const code = `if (typeof x === 'string') { }`
|
||||
const result = detector.detectMagicStrings(code, "test.ts")
|
||||
|
||||
expect(result).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should NOT detect strings in reverse typeof checks", () => {
|
||||
const code = `if ('number' === typeof count) { }`
|
||||
const result = detector.detectMagicStrings(code, "test.ts")
|
||||
|
||||
expect(result).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should skip tokens.ts files completely", () => {
|
||||
const code = `
|
||||
export const LOGGER = Symbol('LOGGER')
|
||||
export const DATABASE = Symbol('DATABASE')
|
||||
const url = "http://localhost:8080"
|
||||
`
|
||||
const result = detector.detectAll(code, "src/di/tokens.ts")
|
||||
|
||||
expect(result).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should skip tokens.js files completely", () => {
|
||||
const code = `const TOKEN = Symbol('TOKEN')`
|
||||
const result = detector.detectAll(code, "src/di/tokens.js")
|
||||
|
||||
expect(result).toHaveLength(0)
|
||||
})
|
||||
|
||||
it("should detect real magic strings even with type contexts nearby", () => {
|
||||
const code = `
|
||||
type Mode = 'read' | 'write'
|
||||
const apiKey = "secret-key-12345"
|
||||
`
|
||||
const result = detector.detectMagicStrings(code, "test.ts")
|
||||
|
||||
expect(result.length).toBeGreaterThan(0)
|
||||
expect(result.some((r) => r.value === "secret-key-12345")).toBe(true)
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
Reference in New Issue
Block a user