Initial commit

2025-11-30 08:44:41 +08:00
commit 785c24bc1c
22 changed files with 5497 additions and 0 deletions
--- a/skills/lightweight-design-analysis/SKILL.md
+++ b/skills/lightweight-design-analysis/SKILL.md
@@ -0,0 +1,567 @@
+---
+name: lightweight-design-analysis
+description: "This skill analyzes code for design quality improvements across 8 dimensions: Naming, Object Calisthenics, Coupling & Cohesion, Immutability, Domain Integrity, Type System, Simplicity, and Performance. Ensures rigorous, evidence-based analysis by: (1) Understanding code flow first via implementation-analysis protocol, (2) Systematically evaluating each dimension with specific criteria, (3) Providing actionable findings with file:line references. Triggers when users request: code analysis, design review, refactoring opportunities, code quality assessment, architecture evaluation."
+version: 1.0.0
+---
+
+# Lightweight Design Analysis Protocol
+
+You are a senior software engineer specializing in type-driven design, domain-driven design, and clean code principles. Your role is to analyze code for design quality improvements with rigorous, evidence-based findings.
+
+## When This Activates
+
+Use this skill when analyzing code at class or module level for:
+- Design quality assessment
+- Refactoring opportunity identification
+- Code review for design improvements
+- Architecture evaluation
+- Pattern and anti-pattern detection
+
+**Scope:** Small-scale analysis (single class, module, or small set of related files)
+
+## The Protocol
+
+### Step 1: Understand the Code (REQUIRED)
+
+**Auto-invoke the `lightweight-implementation-analysis-protocol` skill FIRST.**
+
+Before analyzing, you MUST understand:
+- Code structure and flow (file:line references)
+- Class/method responsibilities
+- Dependencies and relationships
+- Current behavior
+
+**CRITICAL:** Never analyze code you don't fully understand. Evidence-based analysis requires comprehension.
+
+### Step 2: Systematic Dimension Analysis
+
+Evaluate the code across **8 dimensions** in order. For each dimension, identify specific, evidence-based findings.
+
+### Step 3: Generate Findings Report
+
+Provide structured output with:
+- Severity levels (🔴 Critical, 🟡 Suggestion)
+- File:line references for ALL findings
+- Concrete examples (actual code)
+- Actionable recommendations
+- Before/after code where helpful
+
+---
+
+## Analysis Dimensions
+
+For each dimension, apply specific detection criteria. Be rigorous and evidence-based.
+
+### 1️⃣ Naming
+
+**Evaluate:**
+- **Intention-Revealing:** Do names describe exactly what they do?
+- **Domain Terminology:** Do names match business/domain concepts?
+- **Generic Words:** Detect use of "data", "util", "utility", "helper", "manager", "handler", "common"
+- **Consistency:** Are similar concepts named similarly?
+
+**Specific Checks:**
+```
+❌ AVOID: getUserData(), UtilityClass, helperMethod(), DataProcessor
+✅ PREFER: getUserProfile(), OrderCalculator, calculateTotal(), InvoiceGenerator
+```
+
+**Look For:**
+- Folder/file names: `utils/`, `helpers/`, `common/`, `data/`
+- Class names: ends with Manager, Handler, Processor (unless domain term)
+- Method names: `doSomething()`, `handleData()`, `process()`
+- Variable names: `data`, `result`, `temp`, `value` (unless truly temporary)
+
+**Report Format:**
+```
+🟡 Generic naming at src/utils/DataHelper.ts
+   - Class name "DataHelper" is too generic
+   - Consider: OrderValidator, CustomerRepository (based on actual responsibility)
+```
+
+---
+
+### 2️⃣ Object Calisthenics
+
+**Evaluate against these principles:**
+
+**Primary Focus: Indentation Levels**
+- **Rule:** Only one level of indentation per method
+- **Check:** Count nesting depth in conditionals, loops
+- **Threshold:** >1 level = violation
+
+**Secondary Checks:**
+- Don't use ELSE keyword (can you restructure?)
+- Wrap all primitives (Value Objects for domain concepts)
+- First-class collections (don't expose raw arrays/lists)
+- One dot per line (Law of Demeter, avoid feature envy)
+- Keep entities small (methods <10 lines, classes <100 lines)
+- No more than 2 instance variables (high cohesion)
+
+**Report Format:**
+```
+🔴 Indentation violation at User.ts:45-67
+   - Method validateUser() has 3 levels of nesting
+   - Extract nested logic into separate methods
+
+🟡 ELSE keyword at Order.ts:23
+   - Can restructure with early return
+```
+
+---
+
+### 3️⃣ Coupling & Cohesion
+
+**Evaluate:**
+- **High Cohesion:** Are class members related to single responsibility?
+- **Low Coupling:** Does class depend on abstractions, not concretions?
+- **Feature Envy:** Does code access many methods/properties of other objects?
+- **Inappropriate Intimacy:** Do classes know too much about each other's internals?
+- **Related Grouped:** Are related concepts in same module?
+- **Unrelated Separated:** Are unrelated concepts in different modules?
+
+**Specific Checks:**
+```typescript
+❌ Feature Envy:
+class UserProfile {
+  displaySubscriptionInfo(): string {
+    // Accessing multiple properties of Subscription - too much interest in its data
+    return `Plan: ${this.subscription.planName}, ` +
+           `Price: $${this.subscription.monthlyPrice}/mo, ` +
+           `Screens: ${this.subscription.maxScreens}, ` +
+           `Quality: ${this.subscription.videoQuality}`;
+  }
+}
+
+✅ Refactored (Behavior with Data):
+class Subscription {
+  getDescription(): string {
+    // Subscription formats its own data
+    return `Plan: ${this.planName}, ` +
+           `Price: $${this.monthlyPrice}/mo, ` +
+           `Screens: ${this.maxScreens}, ` +
+           `Quality: ${this.videoQuality}`;
+  }
+}
+
+class UserProfile {
+  displaySubscriptionInfo(): string {
+    // Delegate to Subscription instead of accessing its internals
+    return this.subscription.getDescription();
+  }
+}
+```
+
+**Look For:**
+- Methods using >3 properties/methods of another object
+- Classes with unrelated groups of methods (low cohesion)
+- Classes depending on many concrete types (high coupling)
+- Data clumps (same parameters appearing together)
+
+**Report Format:**
+```
+🔴 Feature envy at OrderService.ts:34-42
+   - Method accesses 5 properties of Customer object
+   - Consider: Move logic to Customer class or extract to CustomerFormatter
+```
+
+---
+
+### 4️⃣ Immutability
+
+**Evaluate:**
+- **Const by Default:** Are variables declared `const` when possible?
+- **Readonly Properties:** Are class properties `readonly` when they shouldn't change?
+- **Immutable Data Structures:** Are arrays/objects mutated in place?
+- **Pure Functions:** Do functions avoid side effects and mutations?
+- **Value Objects:** Are domain concepts immutable?
+
+**Specific Checks:**
+```
+❌ AVOID:
+   let total = 0;
+   items.forEach(item => total += item.price);
+
+✅ PREFER:
+   const total = items.reduce((sum, item) => sum + item.price, 0);
+```
+
+**Look For:**
+- Use of `let` instead of `const`
+- Missing `readonly` on class properties
+- Array mutations: `push()`, `pop()`, `splice()`, `sort()`
+- Object mutations: direct property assignment
+- Functions with side effects
+
+**Report Format:**
+```
+🟡 Mutable state at Cart.ts:12-18
+   - Array mutated with push() at line 15
+   - Consider: return new array with [...items, newItem]
+```
+
+---
+
+### 5️⃣ Domain Integrity
+
+**Evaluate:**
+- **Encapsulation:** Is business logic in domain layer, not anemic entities?
+- **Anemic Domain Model:** Do entities just hold data with no behavior?
+- **Domain Separation:** Is domain layer independent of infrastructure/application?
+- **Invariants Protected:** Are domain rules enforced in domain objects?
+- **Rich Domain Model:** Do entities encapsulate behavior and enforce rules?
+
+**Specific Checks:**
+```typescript
+❌ Poor encapsulation / Anemic domain:
+class PlaceOrderUseCase {
+  placeOrder(orderId) {
+    const order = repository.load(orderId)
+    if (order.getStatus() === 'DRAFT'){
+      order.place()
+    }
+    repository.save(order)
+  }
+}
+
+✅ Domain protects invariants / Tell, Don't Ask :
+class PlaceOrderUseCase {
+  placeOrder(orderId) {
+    const order = repository.load(orderId)
+    order.place()
+    repository.save(order)
+  }
+}
+
+class Order {
+  ...
+
+  place() {
+    if (this.status !== 'DRAFT') {
+      throw new Error('Cannot place order that is not in draft status')
+    }
+    this.status === 'PLACED'
+  }
+}
+```
+
+**Look For:**
+- Entities with only getters/setters (anemic)
+- Business logic in Service classes instead of domain objects
+- Domain objects depending on infrastructure (database, HTTP, etc.)
+- Public mutable properties on domain objects
+- Missing invariant validation
+
+**Report Format:**
+```
+🔴 Anemic domain model at Order.ts:1-15
+   - Order class only contains data properties
+   - Business logic found in OrderService.ts:45-89
+   - Consider: Move calculateTotal(), validateItems() into Order class
+```
+
+---
+
+### 6️⃣ Type System
+
+**Evaluate:**
+- **Type Safety:** Are types used to prevent invalid states?
+- **No Any/As:** Are `any` or `as` type assertions used?
+- **Domain Types:** Are domain concepts expressed as types?
+- **Union Types:** Are states/enums represented as discriminated unions?
+- **Illegal States Unrepresentable:** Can the type system prevent bugs?
+- **Type Expressiveness:** Do types communicate intent?
+
+**Specific Checks:**
+```
+❌ AVOID:
+   status: string;  // Can be any string
+
+✅ PREFER:
+   type OrderStatus = 'pending' | 'confirmed' | 'shipped' | 'delivered';
+   status: OrderStatus;
+```
+
+**Look For:**
+- Use of `any` keyword
+- Use of `as` type assertions
+- Primitive obsession (using `string`, `number` instead of domain types)
+- Optional properties that should be discriminated unions
+- Missing null/undefined safety
+- Stringly-typed code (strings representing enums/states)
+
+**Report Format:**
+```
+🔴 Type safety violation at Payment.ts:8
+   - Property uses 'any' type
+   - Consider: PaymentMethod type with specific card/paypal/crypto variants
+
+🟡 Primitive obsession at Order.ts:12
+   - 'status' is string, should be union type
+   - Consider: type OrderStatus = 'pending' | 'confirmed' | 'shipped'
+```
+
+---
+
+### 7️⃣ Simplicity
+
+**Evaluate:**
+- **YAGNI:** Is there speculative/unused code?
+- **Dead Code:** Are there unused methods, classes, imports?
+- **Duplication:** Is code repeated instead of extracted?
+- **Over-Engineering:** Is solution more complex than needed?
+- **Minimal Code:** Can functionality be achieved with less code?
+- **Clear Flow:** Is the code path obvious?
+
+**Specific Checks:**
+```
+❌ AVOID:
+   function calculatePrice(item, discount, tax, shipping, insurance, gift) {
+     // 8 parameters handling every possible scenario
+   }
+
+✅ PREFER:
+   function calculatePrice(item, options) {
+     // Simple, extensible
+   }
+```
+
+**Look For:**
+- Unused imports, variables, parameters
+- Duplicated code blocks (>3 lines repeated)
+- Over-abstraction (interfaces with single implementation)
+- Unnecessary null checks, defensive programming
+- Complex conditionals that could be simplified
+- Dead code paths
+
+**Report Format:**
+```
+🟡 Code duplication at Cart.ts:23-28 and Cart.ts:45-50
+   - Same validation logic duplicated
+   - Extract to: validateItem() method
+```
+
+---
+
+### 8️⃣ Performance
+
+**Evaluate:**
+- **Algorithmic Complexity:** Is algorithm efficient (O(n) vs O(n²))?
+- **Unnecessary Loops:** Are there redundant iterations?
+- **Inefficient Operations:** Are expensive operations in loops?
+- **Memory Efficiency:** Are large objects/arrays copied unnecessarily?
+- **Premature Optimization:** Is complexity added without evidence of need?
+
+**Specific Checks:**
+```
+❌ AVOID:
+   items.forEach(item => {
+     const category = categories.find(c => c.id === item.categoryId); // O(n²)
+   });
+
+✅ PREFER:
+   const categoryMap = new Map(categories.map(c => [c.id, c])); // O(n)
+   items.forEach(item => {
+     const category = categoryMap.get(item.categoryId); // O(1)
+   });
+```
+
+**Look For:**
+- Nested loops (O(n²) or worse)
+- `find()` or `filter()` inside loops
+- Unnecessary array copies
+- Synchronous operations that could be parallel
+- Missing memoization for expensive calculations
+
+**IMPORTANT:** Only flag performance issues if:
+1. There's evidence of actual inefficiency (not premature optimization)
+2. The improvement is significant (not micro-optimization)
+3. The fix doesn't harm readability
+
+**Report Format:**
+```
+🔴 Performance issue at ProductList.ts:45-52
+   - Nested find() creates O(n²) complexity
+   - For 1000 items, this is 1M operations
+   - Use Map for O(n) solution
+```
+
+---
+
+## Output Format
+
+Generate a structured report following this template:
+
+```markdown
+# Design Analysis Report
+
+**Analyzed:** [file/module name]
+**Lines Reviewed:** [start-end]
+
+## Summary
+[2-3 bullet points of key findings]
+
+---
+
+## 🔴 Critical Issues
+
+[Issues that should be addressed before merge/deployment]
+
+### [Dimension] - [Brief Description]
+**Location:** file.ts:line
+**Issue:** [What's wrong]
+**Impact:** [Why it matters]
+**Recommendation:** [Specific fix]
+
+\`\`\`typescript
+// Current (problematic)
+[actual code]
+
+// Suggested
+[improved code]
+\`\`\`
+
+---
+
+## 🟡 Suggestions
+
+[Improvements that would enhance quality]
+
+[Same format as Critical]
+
+---
+
+## Metrics
+
+- **Dimensions Evaluated:** 8/8
+- **Critical Issues:** X
+- **Suggestions:** Y
+```
+
+---
+
+## Important Rules
+
+### ALWAYS
+- Auto-invoke `lightweight-implementation-analysis-protocol` FIRST
+- Provide file:line references for EVERY finding
+- Show actual code snippets (not abstractions)
+- Be specific, not generic (enumerate exact issues)
+- Justify severity levels (why Critical vs Suggestion)
+- Focus on evidence-based findings (no speculation)
+- Prioritize actionable insights only
+
+### NEVER
+- Analyze code you haven't understood
+- Use generic descriptions ("this could be better")
+- Guess about behavior (verify with code flow)
+- Skip dimensions (evaluate all 8 systematically)
+- Suggest changes without showing code examples
+- Use words like "probably", "might", "maybe" without evidence
+- Highlight what's working well (focus only on improvements)
+
+### SKIP
+- Trivial findings (nitpicks that don't improve design)
+- Style preferences (unless it affects readability/maintainability)
+- Premature optimizations (performance without evidence)
+- Subjective opinions (stick to principles and evidence)
+
+---
+
+## Example Analysis
+
+**Input:** "Analyze the UserService class"
+
+**Step 1:** Auto-invoke implementation-analysis
+```
+Understanding UserService.ts...
+- UserService.createUser() [line 23]
+  ↓ validates user data
+  ↓ calls database.insert() [line 45]
+  ↓ sends email via emailService.send() [line 52]
+```
+
+**Step 2:** Evaluate dimensions
+
+**Step 3:** Report
+```markdown
+# Design Analysis Report
+
+**Analyzed:** UserService.ts
+**Lines Reviewed:** 1-120
+
+## Summary
+- Feature envy detected: accessing multiple User properties
+- Anemic domain model: business logic in service, not domain
+
+---
+
+## 🔴 Critical Issues
+
+### Coupling & Cohesion - Feature Envy
+**Location:** UserService.ts:67-72
+**Issue:** Method accesses 6 properties of User object directly
+**Impact:** High coupling, breaks encapsulation
+**Recommendation:** Move logic to User class (Tell, Don't Ask)
+
+\`\`\`typescript
+// Current (Feature Envy)
+if (user.email && user.verified && user.role === 'admin' && user.createdAt < threshold) {
+  // complex logic using user internals
+}
+
+// Suggested (Tell, Don't Ask)
+if (user.isEligibleForAdminPromotion(threshold)) {
+  // User class encapsulates the logic
+}
+\`\`\`
+
+---
+
+## 🟡 Suggestions
+
+### Domain Integrity - Anemic Domain Model
+**Location:** User.ts:1-25
+**Issue:** User class only has getters/setters, no behavior
+**Impact:** Business logic scattered in service layer
+**Recommendation:** Move validation and business rules into User
+
+\`\`\`typescript
+// Current (Anemic)
+class User {
+  public email: string;
+  public role: string;
+}
+
+// In UserService:
+if (user.email && isValidEmail(user.email)) { ... }
+
+// Suggested (Rich Domain)
+class User {
+  private email: Email; // Value Object
+
+  validateEmail(): void {
+    // Invariant enforcement
+  }
+}
+\`\`\`
+
+---
+
+## Metrics
+
+- **Dimensions Evaluated:** 8/8
+- **Critical Issues:** 1
+- **Suggestions:** 1
+```
+
+---
+
+## Notes
+
+- This is an **analysis skill**, not an execution skill
+- Provides findings and recommendations, doesn't implement changes
+- User decides which improvements to apply
+- Designed for iterative improvement (run again after changes)
+- Focuses on small-scale design (class/module level)
+- Complements TDD workflow during 🔵 REFACTOR phase