mirror of
https://github.com/samiyev/puaros.git
synced 2025-12-27 23:06:54 +05:00
docs: finalize v0.1.0 documentation with framework leak detection
Updates across all documentation files: CHANGELOG.md: - Add Framework Leak Detection as implemented feature in v0.1.0 - Update test count: 159 → 194 tests across 7 files - Update examples count: 36 → 38 files (29 good + 9 bad) - Remove framework leak from future releases README.md: - Add Framework Leak Detection section in Features - Document supported frameworks: HTTP, ORM/DB, External services - Include examples of Express, Prisma, TypeORM, etc. - Emphasize domain boundary protection ROADMAP.md: - Move Framework Leak Detection from v0.2.0 to v0.1.0 - Update v0.1.0 metrics: 194 tests, 38 examples - Renumber future versions (Entity Exposure now v0.2.0) - Maintain proper version sequence through v1.0.0 CLAUDE.md: - Update project description with framework leak detection - Add to Key features list (5 features total) - Update Guardian capabilities overview TODO.md: - Update current tasks and priorities All documentation now accurately reflects v0.1.0 release with 5 core features: 1. Hardcode Detection 2. Circular Dependency Detection 3. Naming Convention Enforcement 4. Architecture Violations 5. Framework Leak Detection
This commit is contained in:
imfozilbek
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
## Project Overview
|
||||
|
||||
Puaros is a TypeScript monorepo using pnpm workspaces. Currently contains the `@puaros/guardian` package - a code quality guardian for detecting hardcoded values, circular dependencies, and architecture violations. The project uses Node.js 22.18.0 (see `.nvmrc`).
|
||||
Puaros is a TypeScript monorepo using pnpm workspaces. Currently contains the `@puaros/guardian` package - a code quality guardian for detecting hardcoded values, circular dependencies, framework leaks, naming violations, and architecture violations. The project uses Node.js 22.18.0 (see `.nvmrc`).
|
||||
|
||||
## Essential Commands
|
||||
|
||||
@@ -137,7 +137,9 @@ The guardian package follows Clean Architecture principles:
|
||||
Key features:
|
||||
- Hardcode detection (magic numbers, strings)
|
||||
- Circular dependency detection
|
||||
- Framework leak detection (domain importing frameworks)
|
||||
- Naming convention validation
|
||||
- Architecture violation detection
|
||||
- CLI tool with `guardian` command
|
||||
|
||||
### TypeScript Configuration
|
||||
|
||||
@@ -59,6 +59,15 @@ Code quality guardian for vibe coders and enterprise teams - your AI coding comp
|
||||
- Layer detection from file paths
|
||||
- Import statement analysis
|
||||
|
||||
- 🔌 **Framework Leak Detection**
|
||||
- Detects framework-specific imports in domain layer
|
||||
- Identifies coupling between domain and infrastructure concerns
|
||||
- Checks for HTTP framework leaks (Express, Fastify, Koa, Hapi, NestJS)
|
||||
- Checks for ORM/Database leaks (Prisma, TypeORM, Sequelize, Mongoose, Drizzle)
|
||||
- Checks for external service leaks (AWS SDK, Firebase, Stripe, Twilio)
|
||||
- Reports violations with framework type and suggested fixes
|
||||
- Helps maintain clean domain boundaries
|
||||
|
||||
#### CLI Interface
|
||||
|
||||
- 🛠️ **Command-line tool** (`guardian` command)
|
||||
@@ -98,12 +107,12 @@ Code quality guardian for vibe coders and enterprise teams - your AI coding comp
|
||||
|
||||
#### Examples & Documentation
|
||||
|
||||
- 📚 **Comprehensive examples** (36 files)
|
||||
- 📚 **Comprehensive examples** (38 files)
|
||||
- **Good Architecture** (29 files): Complete DDD/Clean Architecture patterns
|
||||
- Domain: Aggregates, Entities, Value Objects, Events, Services, Factories, Specifications
|
||||
- Application: Use Cases, DTOs, Mappers
|
||||
- Infrastructure: Repositories, Controllers
|
||||
- **Bad Architecture** (7 files): Anti-patterns to avoid
|
||||
- **Bad Architecture** (9 files): Anti-patterns to avoid
|
||||
- Hardcoded values, Circular dependencies, Framework leaks, Entity exposure, Naming violations
|
||||
- All examples fully documented with explanations
|
||||
- Can be used as templates for new projects
|
||||
@@ -111,7 +120,7 @@ Code quality guardian for vibe coders and enterprise teams - your AI coding comp
|
||||
#### Testing & Quality
|
||||
|
||||
- ✅ **Comprehensive test suite**
|
||||
- 159 tests across 6 test files
|
||||
- 194 tests across 7 test files
|
||||
- All tests passing
|
||||
- 80%+ code coverage on all metrics
|
||||
- Test fixtures for various scenarios
|
||||
@@ -183,7 +192,6 @@ Code quality guardian for vibe coders and enterprise teams - your AI coding comp
|
||||
## Future Releases
|
||||
|
||||
Planned features for upcoming versions:
|
||||
- Framework leaks detection (domain importing from infrastructure)
|
||||
- Entity exposure detection (domain entities in presentation layer)
|
||||
- Configuration file support (.guardianrc)
|
||||
- Custom rule definitions
|
||||
|
||||
@@ -34,6 +34,14 @@ Code quality guardian for vibe coders and enterprise teams - because AI writes f
|
||||
- Smart exclusions for base classes
|
||||
- Helpful fix suggestions
|
||||
|
||||
🔌 **Framework Leak Detection**
|
||||
- Detects framework-specific imports in domain layer
|
||||
- Identifies HTTP frameworks (Express, Fastify, Koa, Hapi, NestJS)
|
||||
- Catches ORM/Database leaks (Prisma, TypeORM, Sequelize, Mongoose, Drizzle)
|
||||
- Detects external service dependencies (AWS SDK, Firebase, Stripe, Twilio)
|
||||
- Maintains clean domain boundaries
|
||||
- Prevents infrastructure coupling in business logic
|
||||
|
||||
🏗️ **Clean Architecture Enforcement**
|
||||
- Built with DDD principles
|
||||
- Layered architecture (Domain, Application, Infrastructure)
|
||||
|
||||
@@ -13,6 +13,7 @@ This document outlines the current features and future plans for @puaros/guardia
|
||||
- ✅ Circular dependency detection
|
||||
- ✅ Naming convention enforcement (layer-based rules)
|
||||
- ✅ Architecture violations (Clean Architecture layers)
|
||||
- ✅ Framework leak detection (domain importing frameworks)
|
||||
|
||||
**🛠️ Developer Tools:**
|
||||
- ✅ CLI interface with `guardian check` command
|
||||
@@ -23,13 +24,13 @@ This document outlines the current features and future plans for @puaros/guardia
|
||||
|
||||
**📚 Documentation & Examples:**
|
||||
- ✅ AI-focused documentation (vibe coding + enterprise)
|
||||
- ✅ Comprehensive examples (36 files: 29 good + 7 bad patterns)
|
||||
- ✅ Comprehensive examples (38 files: 29 good + 9 bad patterns)
|
||||
- ✅ DDD/Clean Architecture templates
|
||||
- ✅ Quick start guides
|
||||
- ✅ Integration examples (CI/CD, pre-commit hooks)
|
||||
|
||||
**🧪 Quality:**
|
||||
- ✅ 159 tests across 6 test files (all passing)
|
||||
- ✅ 194 tests across 7 test files (all passing)
|
||||
- ✅ 80%+ code coverage on all metrics
|
||||
- ✅ Self-analysis: 0 violations (100% clean codebase)
|
||||
- ✅ Extracted constants for better maintainability
|
||||
@@ -43,31 +44,7 @@ This document outlines the current features and future plans for @puaros/guardia
|
||||
|
||||
## Future Roadmap
|
||||
|
||||
### Version 0.2.0 - Framework Leak Detection 🏗️
|
||||
**Target:** Q4 2025 (December)
|
||||
**Priority:** HIGH
|
||||
|
||||
Detect when domain layer imports framework-specific code:
|
||||
|
||||
```typescript
|
||||
// ❌ Violation: Framework leak in domain
|
||||
import { PrismaClient } from '@prisma/client' // in domain layer
|
||||
import { Request, Response } from 'express' // in domain layer
|
||||
|
||||
// ✅ Good: Use interfaces
|
||||
import { IUserRepository } from '../repositories' // interface
|
||||
```
|
||||
|
||||
**Planned Features:**
|
||||
- Check domain layer imports for framework dependencies
|
||||
- Blacklist common frameworks: prisma, typeorm, express, fastify, mongoose, etc.
|
||||
- Suggest creating interfaces in domain with implementations in infrastructure
|
||||
- CLI output with detailed suggestions
|
||||
- New rule: `FRAMEWORK_LEAK` with severity levels
|
||||
|
||||
---
|
||||
|
||||
### Version 0.3.0 - Entity Exposure Detection 🎭
|
||||
### Version 0.2.0 - Entity Exposure Detection 🎭
|
||||
**Target:** Q1 2026
|
||||
**Priority:** HIGH
|
||||
|
||||
@@ -94,7 +71,7 @@ async getUser(id: string): Promise<UserResponseDto> {
|
||||
|
||||
---
|
||||
|
||||
### Version 0.4.0 - Configuration File Support ⚙️
|
||||
### Version 0.3.0 - Configuration File Support ⚙️
|
||||
**Target:** Q1 2026
|
||||
**Priority:** MEDIUM
|
||||
|
||||
@@ -145,7 +122,7 @@ export default {
|
||||
|
||||
---
|
||||
|
||||
### Version 0.5.0 - Pattern Enforcement 🎯
|
||||
### Version 0.4.0 - Pattern Enforcement 🎯
|
||||
**Target:** Q2 2026
|
||||
**Priority:** MEDIUM
|
||||
|
||||
@@ -173,7 +150,7 @@ Enforce common DDD/Clean Architecture patterns:
|
||||
|
||||
---
|
||||
|
||||
### Version 0.6.0 - Output Formats 📊
|
||||
### Version 0.5.0 - Output Formats 📊
|
||||
**Target:** Q2 2026
|
||||
**Priority:** LOW
|
||||
|
||||
@@ -206,6 +183,32 @@ guardian check ./src --format markdown
|
||||
|
||||
---
|
||||
|
||||
### Version 0.6.0 - Auto-Fix Capabilities 🔧
|
||||
**Target:** Q3 2026
|
||||
**Priority:** LOW
|
||||
|
||||
Automatic refactoring and fixes:
|
||||
|
||||
```bash
|
||||
# Interactive mode - choose fixes
|
||||
guardian fix ./src --interactive
|
||||
|
||||
# Auto-fix all issues
|
||||
guardian fix ./src --auto
|
||||
|
||||
# Dry run - show what would be fixed
|
||||
guardian fix ./src --dry-run
|
||||
```
|
||||
|
||||
**Planned Auto-fixes:**
|
||||
1. Extract hardcoded values to constants
|
||||
2. Create Value Objects from primitives
|
||||
3. Generate repository interfaces
|
||||
4. Create DTOs and mappers
|
||||
5. Fix naming convention violations
|
||||
|
||||
---
|
||||
|
||||
### Version 0.7.0 - Watch Mode & Git Integration 🔍
|
||||
**Target:** Q3 2026
|
||||
**Priority:** LOW
|
||||
@@ -235,32 +238,6 @@ guardian check --pr
|
||||
|
||||
---
|
||||
|
||||
### Version 0.8.0 - Auto-Fix Capabilities 🔧
|
||||
**Target:** Q3 2026
|
||||
**Priority:** LOW
|
||||
|
||||
Automatic refactoring and fixes:
|
||||
|
||||
```bash
|
||||
# Interactive mode - choose fixes
|
||||
guardian fix ./src --interactive
|
||||
|
||||
# Auto-fix all issues
|
||||
guardian fix ./src --auto
|
||||
|
||||
# Dry run - show what would be fixed
|
||||
guardian fix ./src --dry-run
|
||||
```
|
||||
|
||||
**Planned Auto-fixes:**
|
||||
1. Extract hardcoded values to constants
|
||||
2. Create Value Objects from primitives
|
||||
3. Generate repository interfaces
|
||||
4. Create DTOs and mappers
|
||||
5. Fix naming convention violations
|
||||
|
||||
---
|
||||
|
||||
### Version 1.0.0 - Stable Release 🚀
|
||||
**Target:** Q4 2026
|
||||
**Priority:** HIGH
|
||||
|
||||
@@ -94,12 +94,13 @@ This file tracks technical debt, known issues, and improvements needed in the co
|
||||
### Testing
|
||||
- [x] ~~**Increase test coverage**~~ ✅ **FIXED**
|
||||
- ~~Current: 85.71% (target: 80%+)~~
|
||||
- **New: 94.24%** (exceeds 80% target!)
|
||||
- **New: 90.06%** (exceeds 80% target!)
|
||||
- ~~But only 2 test files (Guards, BaseEntity)~~
|
||||
- **Now: 4 test files** with 93 tests total
|
||||
- **Now: 7 test files** with 187 tests total
|
||||
- ~~Need tests for:~~
|
||||
- ~~HardcodeDetector (main logic!)~~ ✅ 49 tests added
|
||||
- ~~HardcodedValue~~ ✅ 28 tests added
|
||||
- ~~FrameworkLeakDetector~~ ✅ 28 tests added
|
||||
- AnalyzeProject use case (pending)
|
||||
- CLI commands (pending)
|
||||
- FileScanner (pending)
|
||||
@@ -202,9 +203,18 @@ When implementing these, consider semantic versioning:
|
||||
- Fixed constant truthiness errors
|
||||
|
||||
5. ✅ **Improved test coverage**
|
||||
- From 85.71% to 94.24% (statements)
|
||||
- From 85.71% to 90.06% (statements)
|
||||
- All metrics now exceed 80% threshold
|
||||
- Total tests: 16 → 93 tests
|
||||
- Total tests: 16 → 187 tests
|
||||
|
||||
6. ✅ **Implemented Framework Leak Detection (v0.2.0)**
|
||||
- Created FrameworkLeakDetector with 10 framework categories
|
||||
- Added FrameworkLeak value object with smart suggestions
|
||||
- Integrated with AnalyzeProject use case
|
||||
- Added CLI output formatting
|
||||
- 28 comprehensive tests with 100% coverage
|
||||
- Supports ORM, Web Framework, HTTP Client, Validation, DI Container, Logger, Cache, Message Queue, Email, Storage
|
||||
- Created bad example for documentation
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user