@lvlup-sw/axiom 0.2.0

package/skills/critique/references/dependency-patterns.md

@@ -0,0 +1,319 @@
+# Dependency Patterns Reference
+
+Coupling metrics, dependency direction analysis, and circular dependency detection for architecture review.
+
+---
+
+## Healthy vs Unhealthy Dependency Patterns
+
+### Healthy: Inward-Pointing Dependencies
+
+Dependencies flow from outer layers (infrastructure, I/O, frameworks) toward inner layers (domain, core business logic). The core has no knowledge of the outer layers.
+
+```text
++-------------------------------------------------------+
+|                    Infrastructure                      |
+|   (HTTP, Database, Filesystem, External APIs)          |
+|                                                        |
+|   +-----------------------------------------------+   |
+|   |              Application Layer                |   |
+|   |   (Use Cases, Orchestration, Commands)        |   |
+|   |                                               |   |
+|   |   +---------------------------------------+   |   |
+|   |   |           Domain Core                 |   |   |
+|   |   |   (Entities, Value Objects, Rules)    |   |   |
+|   |   |                                       |   |   |
+|   |   |   * No imports from outer layers      |   |   |
+|   |   |   * Defines interfaces others impl    |   |   |
+|   |   +---------------------------------------+   |   |
+|   |                                               |   |
+|   +-----------------------------------------------+   |
+|                                                        |
++-------------------------------------------------------+
+
+  Dependency direction:  Infrastructure --> Application --> Domain
+  (arrows point INWARD)
+```
+
+**Characteristics of healthy patterns:**
+- Domain core has zero imports from infrastructure or framework code
+- Interfaces are defined in the domain, implemented in infrastructure
+- The composition root (entry point) is the only place that wires concrete implementations
+- Modules at the same layer communicate through well-defined interfaces
+
+### Unhealthy: Outward-Pointing Dependencies
+
+Domain or core modules import directly from infrastructure, creating tight coupling.
+
+```text
++-------------------------------------------------------+
+|                    Infrastructure                      |
+|   (HTTP, Database, Filesystem, External APIs)          |
+|                                                        |
+|   +-----------------------------------------------+   |
+|   |              Application Layer                |   |
+|   |                                               |   |
+|   |   +---------------------------------------+   |   |
+|   |   |           Domain Core                 |   |   |
+|   |   |                                       |   |   |
+|   |   |   import { Pool } from 'pg'      <---+---+---+----- VIOLATION
+|   |   |   import { S3 } from 'aws-sdk'   <---+---+---+----- VIOLATION
+|   |   |   import { readFile } from 'fs'  <---+---+---+----- VIOLATION
+|   |   |                                       |   |   |
+|   |   +---------------------------------------+   |   |
+|   |                                               |   |
+|   +-----------------------------------------------+   |
+|                                                        |
++-------------------------------------------------------+
+
+  Dependency direction: Domain --> Infrastructure
+  (arrows point OUTWARD = unhealthy)
+```
+
+**Symptoms of unhealthy patterns:**
+- Business logic modules import database drivers, HTTP clients, or framework packages
+- Changing an infrastructure library forces changes in domain code
+- Unit-testing domain logic requires mocking infrastructure dependencies
+- Module-level globals hold infrastructure state (lazy-init singletons)
+
+### Unhealthy: Peer-to-Peer Coupling
+
+Modules at the same layer bypass interfaces and depend on each other's internals.
+
+```text
+  Module A <---------> Module B
+     |                    |
+     +-------> Module C <-+
+                  |
+                  +-------> Module A   (circular!)
+
+  Every module knows about every other module's internals.
+  Changes propagate unpredictably.
+```
+
+---
+
+## Coupling Metrics
+
+### Afferent Coupling (Ca)
+
+**Definition:** The number of external modules that depend on (import from) a given module.
+
+**Interpretation:**
+- High Ca = many dependents = this module is heavily relied upon
+- Modules with high Ca should be very stable (changes break many consumers)
+- If a high-Ca module is also frequently changing, it is a fragility risk
+
+**How to measure:**
+```text
+For module M:
+  Ca(M) = count of unique modules that import from M
+```
+
+### Efferent Coupling (Ce)
+
+**Definition:** The number of external modules that a given module depends on (imports).
+
+**Interpretation:**
+- High Ce = many dependencies = this module is vulnerable to upstream changes
+- Modules with high Ce are hard to test in isolation
+- High Ce in a core module signals possible DIP violation
+
+**How to measure:**
+```text
+For module M:
+  Ce(M) = count of unique modules that M imports from
+```
+
+### Instability (I)
+
+**Definition:** `I = Ce / (Ca + Ce)` where 0 means maximally stable and 1 means maximally unstable.
+
+**Interpretation:**
+
+| I value | Meaning | Expectation |
+|---------|---------|-------------|
+| I = 0 | Maximally stable | Many dependents, no dependencies. Hard to change. Should be abstract. |
+| I = 1 | Maximally unstable | No dependents, many dependencies. Easy to change. Should be concrete. |
+| 0 < I < 1 | Mixed | Assess whether stability matches the module's role. |
+
+**The Stable Dependencies Principle:** Modules should depend only on modules that are more stable than themselves. An unstable module (I near 1) depending on another unstable module creates fragility chains.
+
+```text
+  STABLE (I=0.1) <---- UNSTABLE (I=0.8)     OK: unstable depends on stable
+  STABLE (I=0.1) ----> UNSTABLE (I=0.8)     BAD: stable depends on unstable
+```
+
+### Abstractness (A)
+
+**Definition:** `A = abstract_types / total_types` where 0 means fully concrete and 1 means fully abstract.
+
+**Interpretation:**
+- High abstractness = mostly interfaces, abstract classes, type definitions
+- Low abstractness = mostly concrete implementations
+
+### The Main Sequence
+
+The ideal relationship between abstractness (A) and instability (I) follows the "main sequence" diagonal:
+
+```text
+  A (Abstractness)
+  1 |  Zone of          .
+    |  Uselessness    .
+    |               .      Main Sequence
+    |             .          (A + I = 1)
+    |           .
+    |         .
+    |       .
+    |     .        Zone of
+    |   .            Pain
+    | .
+  0 +---+---+---+---+----> I (Instability)
+    0                   1
+```
+
+- **Zone of Pain (low A, low I):** Concrete and stable. Hard to change but heavily depended on. Database schemas, core utilities.
+- **Zone of Uselessness (high A, high I):** Abstract and unstable. Interfaces nobody implements. Dead abstractions.
+- **Main Sequence (A + I ~ 1):** Balanced. Stable modules are abstract; unstable modules are concrete.
+
+**Distance from Main Sequence:** `D = |A + I - 1|` — closer to 0 is better. Modules with D > 0.5 deserve investigation.
+
+---
+
+## Circular Dependency Detection
+
+### What Are Circular Dependencies?
+
+A circular dependency exists when module A depends on module B, and module B (directly or transitively) depends back on module A.
+
+### Types of Circular Dependencies
+
+**Direct cycles:**
+```text
+  A ----imports----> B
+  B ----imports----> A
+```
+
+**Transitive cycles:**
+```text
+  A ----imports----> B
+  B ----imports----> C
+  C ----imports----> A
+```
+
+**Barrel-file-mediated cycles:**
+```text
+  feature/index.ts re-exports from:
+    - feature/handler.ts
+    - feature/types.ts
+
+  feature/handler.ts imports from feature/index.ts
+    (to get types — but barrel re-exports handler too!)
+```
+
+### Detection Approach
+
+1. **Build the import graph:** Parse all source files, extract import/require statements, resolve to file paths
+2. **Run cycle detection:** Apply depth-first search (DFS) with back-edge detection on the import graph
+3. **Classify cycles:** Direct (2 modules), short transitive (3-4 modules), long transitive (5+ modules)
+4. **Assess severity:**
+   - Direct cycles involving core/domain modules: **HIGH**
+   - Barrel-file-mediated cycles: **MEDIUM** (often accidental, easy to fix)
+   - Transitive cycles in leaf modules: **LOW**
+
+### Remediation Strategies
+
+| Pattern | Fix |
+|---------|-----|
+| Direct A <-> B cycle | Extract shared types into a third module C, both A and B depend on C |
+| Barrel-file cycle | Use direct imports instead of barrel re-exports |
+| Transitive cycle through shared state | Introduce an event bus or mediator pattern |
+| Cycle caused by type imports only | Use `import type` (TypeScript) to break the runtime cycle |
+
+---
+
+## Layered Architecture Violations
+
+### What Constitutes a Layer
+
+A layered architecture organizes code into horizontal layers with strict dependency rules:
+
+```text
+  +-------------------------------------------------------+
+  | Infrastructure |              | Presentation          |
+  | (DB, FS, APIs) |              | (routes, controllers) |
+  +----------|-----+--------------+-----|------------------+
+             |                          |
+             v                          v
+  +-----------------------------------------------+
+  |              Application                      |
+  |   (use cases, orchestrators, commands)        |
+  +----------------------|------------------------+
+                         |
+                         v
+  +-----------------------------------------------+
+  |              Domain (core)                    |
+  |   (entities, value objects, domain services)  |
+  +-----------------------------------------------+
+
+  Arrows = dependency direction (pointing INWARD toward the core).
+  Infrastructure and Presentation both depend inward on Application/Domain.
+  Domain (core) NEVER imports from any outer layer.
+```
+
+### Common Layer Violations
+
+| Violation | Signal | Severity |
+|-----------|--------|----------|
+| Domain imports infrastructure | `import { query } from '../db'` in a domain file | **HIGH** |
+| Application imports presentation | Use case module imports an HTTP request type | **MEDIUM** |
+| Skip-layer dependency | Presentation directly calls infrastructure, bypassing application | **MEDIUM** |
+| Bidirectional layer dependency | Application imports domain AND domain imports application | **HIGH** |
+
+### How to Detect Layer Violations
+
+1. **Establish layer boundaries:** Map directories to layers (e.g., `src/domain/`, `src/infra/`, `src/app/`)
+2. **Build import graph with layer annotations:** Tag each module with its layer
+3. **Check direction:** For each import, verify the importing module's layer is the same or closer to the periphery than the imported module's layer
+4. **Flag violations:** Any import pointing outward (from a core layer to a peripheral layer) is a violation
+
+---
+
+## Dependency Inversion in Practice
+
+### When to Use Interfaces vs Direct Dependencies
+
+**Use an interface (abstraction boundary) when:**
+- The dependency crosses an architectural layer boundary (e.g., application -> infrastructure)
+- You need to swap implementations (testing, multi-environment, migration)
+- The dependency is volatile (external API, third-party library likely to change)
+- Multiple implementations exist or are planned (e.g., FileStorage: local, S3, GCS)
+
+**Use a direct dependency when:**
+- Both modules are in the same layer and same bounded context
+- The dependency is a stable, well-tested utility (e.g., a date library, a hash function)
+- The abstraction would be a 1:1 mirror of the concrete API (pointless indirection)
+- The module is a pure function or value object with no side effects
+
+### Practical Decision Flowchart
+
+```text
+  Does the dependency cross a layer boundary?
+       |                    |
+      YES                  NO
+       |                    |
+  Use interface        Is the dependency volatile?
+                            |              |
+                           YES            NO
+                            |              |
+                       Use interface   Direct dependency is fine
+```
+
+### Common Anti-Patterns
+
+| Anti-Pattern | Description | Fix |
+|-------------|-------------|-----|
+| Interface mirroring | Interface is an exact copy of one concrete class | Remove interface, use direct dependency |
+| God interface | One interface with 15+ methods for all possible operations | Split into role-specific interfaces (ISP) |
+| Premature abstraction | Interface created "just in case" with only one implementation | Remove until a second implementation materializes |
+| Leaky abstraction | Interface exposes implementation details (SQL in method names, HTTP status codes in domain interface) | Redesign interface using domain language |

package/skills/critique/references/solid-principles.md

@@ -0,0 +1,359 @@
+# SOLID Principles Reference
+
+Detection heuristics and severity guidance for agent-driven architectural assessment.
+
+---
+
+## S — Single Responsibility Principle (SRP)
+
+### Definition
+
+A module should have one, and only one, reason to change. Each class or module should encapsulate a single concern so that a change in one business requirement affects only one module.
+
+### Violation Signals
+
+1. A class or module handles both data persistence AND business logic
+2. A single file contains multiple unrelated public interfaces or exported functions
+3. The module name contains "And" or "Manager" or "Helper" (symptom of mixed concerns)
+4. More than 3 constructor/initialization parameters from different domains
+5. The module is modified in nearly every feature branch (high churn across unrelated features)
+
+### Severity Guide
+
+| Severity | When to assign |
+|----------|---------------|
+| **HIGH** | Module mixes I/O (network, filesystem, database) with core business rules. Changes to infrastructure force changes to domain logic. |
+| **MEDIUM** | Module handles 2-3 related but distinct concerns (e.g., validation + transformation). Concerns could be separated but aren't yet causing bugs. |
+| **LOW** | Module has a slightly broad scope but concerns are closely related. Separation would be premature. |
+
+### Code Examples
+
+**Violation:**
+```
+class OrderService {
+  validateOrder(order) { ... }        // business rule
+  calculateTotal(order) { ... }       // business rule
+  saveToDatabase(order) { ... }       // persistence
+  sendConfirmationEmail(order) { ... } // notification
+  generatePdfInvoice(order) { ... }   // rendering
+}
+```
+
+**Healthy alternative:**
+```
+class OrderValidator {
+  validate(order) { ... }
+}
+
+class OrderCalculator {
+  calculateTotal(order) { ... }
+}
+
+class OrderRepository {
+  save(order) { ... }
+}
+
+class OrderNotifier {
+  sendConfirmation(order) { ... }
+}
+```
+
+### Detection Heuristics
+
+- Count the number of distinct "domains" imported by a module (e.g., database, HTTP, email, file system). More than 2 suggests SRP violation.
+- Check if removing one public method would make half the imports unnecessary. If so, the method belongs elsewhere.
+- Look for methods that could be tested independently with completely different mock setups — they likely belong in different modules.
+
+---
+
+## O — Open/Closed Principle (OCP)
+
+### Definition
+
+Software entities should be open for extension but closed for modification. You should be able to add new behavior without changing existing, tested code.
+
+### Violation Signals
+
+1. Adding a new variant requires modifying an existing `switch` or `if/else` chain
+2. A function has a growing list of type-check branches (`if (type === "A") ... else if (type === "B") ...`)
+3. Feature additions consistently require editing the same core file
+4. Configuration objects grow new boolean flags for each new feature
+5. Functions accept a `type` or `kind` string and branch on its value
+
+### Severity Guide
+
+| Severity | When to assign |
+|----------|---------------|
+| **HIGH** | Every new feature requires modifying a critical-path module (e.g., event dispatcher, router). Risk of regression in existing behavior with each change. |
+| **MEDIUM** | A switch/case or if/else chain has 5+ branches and is growing. Extension is possible but requires touching stable code. |
+| **LOW** | A conditional has 2-3 branches in a non-critical path. The branching is manageable and unlikely to grow further. |
+
+### Code Examples
+
+**Violation:**
+```
+function calculateDiscount(customer) {
+  if (customer.type === "regular") {
+    return 0.05
+  } else if (customer.type === "premium") {
+    return 0.10
+  } else if (customer.type === "vip") {
+    return 0.20
+  }
+  // Adding a new customer type means editing this function
+}
+```
+
+**Healthy alternative:**
+```
+// Strategy pattern — new types are added without modifying existing code
+const discountStrategies = {
+  regular: () => 0.05,
+  premium: () => 0.10,
+  vip: () => 0.20,
+}
+
+function calculateDiscount(customer) {
+  const strategy = discountStrategies[customer.type]
+  return strategy ? strategy() : 0
+}
+// New types: just add an entry to the map
+```
+
+### Detection Heuristics
+
+- Search for `switch` statements on a `type` or `kind` field — count the branches. Five or more suggests OCP violation.
+- Check git history: if the same file is modified in >50% of feature branches, it may be closed to extension.
+- Look for "registry" or "map" patterns that could replace branching logic.
+
+---
+
+## L — Liskov Substitution Principle (LSP)
+
+### Definition
+
+Subtypes must be substitutable for their base types without altering the correctness of the program. If a function works with a base type, it must work identically with any derived type.
+
+### Violation Signals
+
+1. A subclass throws an exception for a method the base class supports
+2. A subclass overrides a method to do nothing (empty override or no-op)
+3. A function checks `instanceof` or the concrete type before calling a method
+4. A subclass narrows the accepted input range or widens the output range beyond the base contract
+5. Documentation says "do not call X on this subtype" — a direct substitutability violation
+
+### Severity Guide
+
+| Severity | When to assign |
+|----------|---------------|
+| **HIGH** | Substituting the subtype causes runtime errors, data corruption, or silently wrong results. Code contains `instanceof` guards to work around the violation. |
+| **MEDIUM** | Subtype behaves differently in edge cases that callers may not handle. No runtime error, but correctness depends on knowing the concrete type. |
+| **LOW** | Subtype overrides behavior in a benign way (e.g., logging or metrics) that does not affect correctness. |
+
+### Code Examples
+
+**Violation:**
+```
+class Bird {
+  fly() { return "flying" }
+}
+
+class Penguin extends Bird {
+  fly() { throw new Error("Penguins cannot fly") }
+  // Violates LSP: callers expecting Bird.fly() to work will crash
+}
+
+function makeBirdFly(bird) {
+  // Forced to add a type check — LSP violation symptom
+  if (bird instanceof Penguin) {
+    return bird.swim()
+  }
+  return bird.fly()
+}
+```
+
+**Healthy alternative:**
+```
+interface Movable {
+  move(): string
+}
+
+class Sparrow implements Movable {
+  move() { return "flying" }
+}
+
+class Penguin implements Movable {
+  move() { return "swimming" }
+}
+
+function makeAnimalMove(animal: Movable) {
+  return animal.move()  // Works for all implementations
+}
+```
+
+### Detection Heuristics
+
+- Search for `instanceof` checks in functions that accept a base type — this is the classic LSP smell.
+- Look for empty method overrides or methods that throw `NotImplementedError` / `UnsupportedOperationError`.
+- Check if any subclass method has a comment like "not applicable" or "unused".
+- Look for type narrowing (`as ConcreteType`) immediately after receiving a base-typed parameter.
+
+---
+
+## I — Interface Segregation Principle (ISP)
+
+### Definition
+
+No client should be forced to depend on methods it does not use. Interfaces should be small and focused so that implementing classes are not burdened with irrelevant obligations.
+
+### Violation Signals
+
+1. An interface has more than 7-8 methods (likely too broad)
+2. Implementing classes leave methods as no-ops or throw "not supported"
+3. A single interface is imported by clients that only use a subset of its methods
+4. Interface changes force updates in modules that don't use the changed method
+5. Parameters typed as a broad interface when only 1-2 properties are accessed
+
+### Severity Guide
+
+| Severity | When to assign |
+|----------|---------------|
+| **HIGH** | A broad interface forces implementors to provide dangerous no-op stubs for critical operations (e.g., `delete()` that silently does nothing). Clients may call methods that appear supported but aren't. |
+| **MEDIUM** | Interface is large (8+ methods) and implementors stub out 2-3 methods. No safety risk but increases maintenance burden. |
+| **LOW** | Interface is slightly broad but all implementors genuinely use most methods. Splitting would add complexity without clear benefit. |
+
+### Code Examples
+
+**Violation:**
+```
+interface Worker {
+  work(): void
+  eat(): void
+  sleep(): void
+  attendMeeting(): void
+  writeReport(): void
+}
+
+class Robot implements Worker {
+  work() { /* ... */ }
+  eat() { /* no-op — robots don't eat */ }
+  sleep() { /* no-op */ }
+  attendMeeting() { /* no-op */ }
+  writeReport() { /* ... */ }
+}
+```
+
+**Healthy alternative:**
+```
+interface Workable {
+  work(): void
+}
+
+interface Reportable {
+  writeReport(): void
+}
+
+interface HumanNeeds {
+  eat(): void
+  sleep(): void
+}
+
+class Robot implements Workable, Reportable {
+  work() { /* ... */ }
+  writeReport() { /* ... */ }
+}
+
+class HumanWorker implements Workable, Reportable, HumanNeeds {
+  work() { /* ... */ }
+  writeReport() { /* ... */ }
+  eat() { /* ... */ }
+  sleep() { /* ... */ }
+}
+```
+
+### Detection Heuristics
+
+- Count methods per interface. More than 7 is a signal worth investigating.
+- Search for empty method bodies or `throw new Error("Not implemented")` in classes implementing an interface.
+- Check if any implementation only uses <50% of the interface methods meaningfully.
+- Look for function parameters typed with a broad interface where only 1-2 fields/methods are accessed in the body.
+
+---
+
+## D — Dependency Inversion Principle (DIP)
+
+### Definition
+
+High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details — details should depend on abstractions.
+
+### Violation Signals
+
+1. A domain/business-logic module directly imports a database driver, HTTP client, or file system module
+2. Constructor creates its own dependencies instead of receiving them (no dependency injection)
+3. Module-level `import` of a concrete implementation where an interface/type would suffice
+4. A core module imports from an `infrastructure/`, `adapters/`, or `io/` directory
+5. Changing a database library requires editing business logic files
+
+### Severity Guide
+
+| Severity | When to assign |
+|----------|---------------|
+| **HIGH** | Core business logic directly instantiates or imports infrastructure (database, network, filesystem). Impossible to test without real infrastructure or heavy mocking. |
+| **MEDIUM** | A module depends on a concrete implementation but the dependency is injected (not self-created). The direction is wrong but testability is preserved. |
+| **LOW** | A utility module depends on a specific library for convenience. The dependency is isolated and easily swappable. |
+
+### Code Examples
+
+**Violation:**
+```
+// Domain module directly importing infrastructure
+import { Pool } from 'pg'
+import { S3Client } from '@aws-sdk/client-s3'
+
+class OrderService {
+  private db = new Pool({ connectionString: process.env.DB_URL })
+  private s3 = new S3Client({ region: 'us-east-1' })
+
+  async createOrder(data) {
+    // Business logic tightly coupled to Postgres and S3
+    await this.db.query('INSERT INTO orders ...', [data])
+    await this.s3.send(new PutObjectCommand({ ... }))
+  }
+}
+```
+
+**Healthy alternative:**
+```
+// Domain depends on abstractions
+interface OrderRepository {
+  save(order: Order): Promise<void>
+}
+
+interface FileStorage {
+  upload(key: string, data: Buffer): Promise<void>
+}
+
+class OrderService {
+  constructor(
+    private repo: OrderRepository,
+    private storage: FileStorage,
+  ) {}
+
+  async createOrder(data) {
+    const order = Order.create(data)
+    await this.repo.save(order)
+    await this.storage.upload(order.invoiceKey, order.toPdf())
+  }
+}
+
+// Infrastructure implements the abstractions
+class PostgresOrderRepository implements OrderRepository { ... }
+class S3FileStorage implements FileStorage { ... }
+```
+
+### Detection Heuristics
+
+- Check import paths in domain/core modules: do they import from `infrastructure/`, `adapters/`, `db/`, `io/`, or driver-specific packages?
+- Search for `new` keyword in domain modules creating infrastructure objects (database connections, HTTP clients, cache clients).
+- Look for `process.env` access in domain modules — environment configuration is an infrastructure concern.
+- Check if the composition root (entry point / DI container) is the only place where concrete implementations are wired to abstractions.