@schilling.mark.a/software-methodology 1.0.0

package/clean-code/references/enterprise-patterns.md

@@ -0,0 +1,334 @@
+# Enterprise Patterns
+
+Patterns for structuring larger systems. These bridge the gap between domain logic and infrastructure concerns.
+
+---
+
+## Repository
+
+**When to use:**
+- You want to decouple domain logic from data access
+- You want your business logic to be testable without a real database
+- You want a consistent interface for querying and persisting domain objects
+
+**Smell that triggers it:**
+- SQL queries or ORM calls directly inside business logic classes
+- Changing the database requires changes in multiple business classes
+- Unit tests require a running database
+
+**Solution:**
+```
+// Interface defined by the DOMAIN — not by the database
+interface InvoiceRepository:
+  findById(id: string): Invoice | null
+  findByCustomer(customerId: string): Invoice[]
+  findUnpaid(): Invoice[]
+  save(invoice: Invoice): void
+  delete(id: string): void
+
+// Implementation lives in infrastructure layer
+class PostgresInvoiceRepository implements InvoiceRepository:
+  constructor(db: DatabaseConnection)
+
+  findById(id):
+    row = this.db.query("SELECT * FROM invoices WHERE id = $1", [id])
+    return this.mapToInvoice(row)
+
+  save(invoice):
+    if invoice.isNew():
+      this.db.query("INSERT INTO invoices ...", [...])
+    else:
+      this.db.query("UPDATE invoices SET ... WHERE id = $1", [...])
+
+// Business logic knows only the interface
+class InvoiceService:
+  constructor(repo: InvoiceRepository)
+
+  markOverdue():
+    unpaid = this.repo.findUnpaid()
+    unpaid.forEach(inv => inv.markOverdue())
+    unpaid.forEach(inv => this.repo.save(inv))
+
+// Test uses an in-memory implementation
+class InMemoryInvoiceRepository implements InvoiceRepository:
+  private store: Map<string, Invoice> = new Map()
+  findById(id): return this.store.get(id)
+  save(invoice): this.store.set(invoice.id, invoice)
+  // ... rest of interface
+```
+
+**Key insight:** The interface is owned by the domain layer. The implementation is owned by the infrastructure layer. Business logic never knows which database is behind the repository.
+
+---
+
+## Service Layer
+
+**When to use:**
+- You need a clear boundary between the application's business logic and its callers (UI, API, CLI)
+- Multiple entry points (REST API, GraphQL, CLI) need to perform the same business operations
+- You want to define the set of operations an application supports in one place
+
+**Smell that triggers it:**
+- Business logic living directly in controllers or route handlers
+- The same business operation duplicated across multiple entry points
+- No clear boundary between "what the application does" and "how it's invoked"
+
+**Solution:**
+```
+// Service layer defines application operations
+class InvoiceService:
+  constructor(repo: InvoiceRepository, taxEngine: TaxEngine, notifier: Notifier)
+
+  createInvoice(data: CreateInvoiceDTO): Invoice
+    customer = this.repo.findCustomer(data.customerId)
+    invoice = new Invoice(customer, data.lineItems)
+    invoice.applyTax(this.taxEngine.calculate(invoice))
+    this.repo.save(invoice)
+    this.notifier.send(invoice)
+    return invoice
+
+  payInvoice(invoiceId: string, paymentData: PaymentDTO): PaymentResult
+    invoice = this.repo.findById(invoiceId)
+    invoice.pay(paymentData)
+    this.repo.save(invoice)
+    return new PaymentResult(invoice)
+
+// REST controller — thin, delegates everything
+class InvoiceController:
+  constructor(service: InvoiceService)
+
+  POST /invoices:
+    return this.service.createInvoice(requestBody)
+
+  POST /invoices/:id/pay:
+    return this.service.payInvoice(params.id, requestBody)
+
+// CLI — same service, different entry point
+class InvoiceCLI:
+  constructor(service: InvoiceService)
+
+  handleCreateCommand(args):
+    invoice = this.service.createInvoice(parseArgs(args))
+    print(invoice.toString())
+```
+
+**Key insight:** The service layer is the single source of truth for what the application can do. Controllers and CLI handlers are thin wrappers that handle serialization and invocation — nothing else.
+
+---
+
+## Unit of Work
+
+**When to use:**
+- Multiple domain objects change as part of a single business operation
+- All changes must succeed or all must fail (transactional consistency)
+- You want to batch database writes rather than writing after every single change
+
+**Smell that triggers it:**
+- Multiple `repository.save()` calls in sequence — if the second fails, the first is already committed
+- Business logic that manually manages transactions
+
+**Solution:**
+```
+class UnitOfWork:
+  private dirty: DomainObject[] = []
+  private newObjects: DomainObject[] = []
+  private removedObjects: DomainObject[] = []
+
+  register(obj: DomainObject):
+    this.dirty.push(obj)
+
+  registerNew(obj: DomainObject):
+    this.newObjects.push(obj)
+
+  registerRemoved(obj: DomainObject):
+    this.removedObjects.push(obj)
+
+  commit(): void
+    transaction = db.beginTransaction()
+    try:
+      this.newObjects.forEach(obj => db.insert(obj))
+      this.dirty.forEach(obj => db.update(obj))
+      this.removedObjects.forEach(obj => db.delete(obj))
+      transaction.commit()
+    catch:
+      transaction.rollback()
+      throw
+
+// Service uses UoW for transactional consistency
+class InvoiceService:
+  constructor(uow: UnitOfWork, repo: InvoiceRepository)
+
+  processPayment(invoiceId, paymentData):
+    invoice = this.repo.findById(invoiceId)
+    payment = new Payment(paymentData)
+    invoice.pay(payment)
+
+    this.uow.register(invoice)         ← mark as changed
+    this.uow.registerNew(payment)      ← mark as new
+    this.uow.commit()                  ← single transaction: both or neither
+```
+
+**Key insight:** Business logic describes *what* changed. Unit of Work handles *when* and *how* it's persisted. If anything fails, nothing is committed.
+
+---
+
+## Specification
+
+**When to use:**
+- You have complex business rules that need to be combined, reused, or queried against
+- You need to express "does this object match these criteria?" as a composable object
+- The same selection logic is used in both validation and querying
+
+**Smell that triggers it:**
+- Long boolean expressions for filtering or validation
+- The same filtering logic duplicated in business rules and database queries
+- Complex conditions that are hard to name or reuse
+
+**Solution:**
+```
+interface Specification:
+  isSatisfiedBy(candidate): boolean
+  and(other: Specification): Specification
+  or(other: Specification): Specification
+  not(): Specification
+
+class UnpaidInvoiceSpec implements Specification:
+  isSatisfiedBy(invoice): return invoice.status == "unpaid"
+
+class OverdueDateSpec implements Specification:
+  constructor(referenceDate: Date)
+  isSatisfiedBy(invoice): return invoice.dueDate < this.referenceDate
+
+class MinimumAmountSpec implements Specification:
+  constructor(minAmount: Money)
+  isSatisfiedBy(invoice): return invoice.total() >= this.minAmount
+
+// Compose specifications
+overdueAndUnpaid = new UnpaidInvoiceSpec().and(new OverdueDateSpec(today))
+highValueOverdue = overdueAndUnpaid.and(new MinimumAmountSpec(Money(10000)))
+
+// Use in business logic
+invoices.filter(inv => highValueOverdue.isSatisfiedBy(inv))
+
+// Use in validation
+if not unpaidSpec.isSatisfiedBy(invoice):
+  throw Error("Invoice is not in unpaid state")
+```
+
+**Key insight:** Business rules become named, composable objects. "High-value overdue unpaid invoices" is expressed as composed specifications, not a deeply nested boolean expression.
+
+---
+
+## Value Object
+
+**When to use:**
+- An object represents a concept defined entirely by its attributes, not by identity
+- Two instances with the same attributes are considered equal
+- The object should be immutable once created
+
+**Smell that triggers it:**
+- Raw primitives (numbers, strings) representing domain concepts like money, email, coordinates
+- Repeated validation logic for the same concept scattered across the codebase
+- Equality checks on raw values that should carry meaning
+
+**Solution:**
+```
+class Money:
+  constructor(amount: number, currency: string)
+    if amount < 0: throw Error("Amount cannot be negative")
+    if not validCurrency(currency): throw Error("Invalid currency")
+    this.amount = amount
+    this.currency = currency
+    freeze(this)                    ← immutable
+
+  add(other: Money): Money
+    if this.currency != other.currency:
+      throw Error("Cannot add different currencies")
+    return new Money(this.amount + other.amount, this.currency)
+
+  multiply(factor: number): Money
+    return new Money(this.amount * factor, this.currency)
+
+  equals(other: Money): boolean
+    return this.amount == other.amount && this.currency == other.currency
+
+  toString(): string
+    return formatCurrency(this.amount, this.currency)   // "$1,000.00"
+
+class Email:
+  constructor(address: string)
+    if not isValidEmail(address): throw Error("Invalid email: " + address)
+    this.address = address.toLowerCase()
+    freeze(this)
+
+  equals(other: Email): boolean
+    return this.address == other.address
+
+// Usage — no raw primitives in domain logic
+class Invoice:
+  constructor(customer: Customer, total: Money)
+    this.customer = customer
+    this.total = total                // Money, not number
+
+  addLineItem(item: LineItem):
+    this.total = this.total.add(item.amount)   // Money.add, not +
+```
+
+**Key insight:** Value objects move validation to the point of creation. A `Money` object can never hold an invalid amount. A raw number can. Every domain concept that has validation rules and natural equality should be a value object.
+
+---
+
+## Domain Events
+
+**When to use:**
+- Something happened in the domain that other parts of the system should know about
+- You want to decouple the thing that happened from the reactions to it
+- You want an audit trail of what occurred in the domain
+
+**Smell that triggers it:**
+- A method that directly calls multiple other systems after completing its work
+- Business logic that knows about email, logging, or external APIs
+- No record of what happened in the domain over time
+
+**Solution:**
+```
+// Events are simple data objects — immutable records of what happened
+class InvoiceCreatedEvent:
+  constructor(invoiceId, customerId, amount, createdAt)
+  // No behavior — just data
+
+class InvoicePaidEvent:
+  constructor(invoiceId, transactionId, paidAt)
+
+// Domain object collects events, doesn't publish them
+class Invoice:
+  private events: DomainEvent[] = []
+
+  markPaid(transactionId):
+    this.status = "paid"
+    this.events.push(new InvoicePaidEvent(this.id, transactionId, now()))
+
+  getEvents(): DomainEvent[]
+    return this.events
+
+// Service publishes events AFTER the transaction commits
+class InvoiceService:
+  constructor(repo: InvoiceRepository, eventBus: EventBus)
+
+  payInvoice(invoiceId, paymentData):
+    invoice = this.repo.findById(invoiceId)
+    invoice.markPaid(paymentData.transactionId)
+    this.repo.save(invoice)
+    invoice.getEvents().forEach(e => this.eventBus.publish(e))
+
+// Handlers react to events — completely decoupled
+class EmailOnPaymentHandler:
+  handle(event: InvoicePaidEvent):
+    sendPaymentConfirmation(event.invoiceId)
+
+class AuditOnPaymentHandler:
+  handle(event: InvoicePaidEvent):
+    auditLog.record(event)
+```
+
+**Key insight:** The domain object doesn't know who's listening. It just records what happened. The event bus delivers events to handlers after the fact. New reaction = new handler, zero changes to the domain.

package/clean-code/references/solid.md

@@ -0,0 +1,230 @@
+# SOLID Principles
+
+## Single Responsibility Principle (SRP)
+
+**Rule:** A class has exactly one reason to change.
+
+**Smell that triggers it:**
+- Class has methods that serve different concerns
+- Changing one feature requires editing this class even though the feature has nothing to do with the class's core purpose
+- Class name is vague or uses "and" (e.g., `InvoiceManager`)
+
+**Before:**
+```
+class Invoice:
+  calculateTotal()      ← business logic
+  formatAsPDF()         ← presentation
+  sendByEmail()         ← communication
+  saveToDatabase()      ← persistence
+```
+
+**After:**
+```
+class Invoice:            ← owns business logic only
+  calculateTotal()
+
+class InvoicePDFRenderer: ← owns presentation
+  render(invoice)
+
+class InvoiceNotifier:    ← owns communication
+  send(invoice)
+
+class InvoiceRepository:  ← owns persistence
+  save(invoice)
+```
+
+**Key insight:** "Reason to change" means a business requirement change. If marketing changes the PDF layout, only `InvoicePDFRenderer` changes. If tax rules change, only `Invoice` changes.
+
+---
+
+## Open/Closed Principle (OCP)
+
+**Rule:** Open for extension, closed for modification.
+
+**Smell that triggers it:**
+- Adding a new variant requires editing existing code
+- if/else or switch statements that grow with each new requirement
+- A method that checks "what type of thing am I dealing with?"
+
+**Before:**
+```
+class TaxCalculator:
+  calculate(invoice):
+    if invoice.region == "US":
+      return invoice.total * 0.08
+    if invoice.region == "UK":
+      return invoice.total * 0.20
+    if invoice.region == "CA":       ← every new region edits this class
+      return invoice.total * 0.05
+```
+
+**After:**
+```
+interface TaxRule:
+  calculate(invoice): Money
+
+class UStaxRule implements TaxRule:
+  calculate(invoice): return invoice.total * 0.08
+
+class UKTaxRule implements TaxRule:
+  calculate(invoice): return invoice.total * 0.20
+
+class TaxCalculator:
+  constructor(rule: TaxRule)         ← new region = new class, no edits
+  calculate(invoice): return this.rule.calculate(invoice)
+```
+
+**Key insight:** New behavior is added by writing new code (new class), not by editing existing code. The `TaxCalculator` never changes again.
+
+---
+
+## Liskov Substitution Principle (LSP)
+
+**Rule:** A subtype must be usable anywhere its base type is expected, without changing behavior.
+
+**Smell that triggers it:**
+- A subclass overrides a method and throws an exception or returns nothing
+- Code that checks `if (thing instanceof SpecificSubclass)` before acting
+- A subclass that weakens a precondition or strengthens a postcondition
+
+**Before:**
+```
+class Shape:
+  area(): number
+
+class Circle extends Shape:
+  area(): return π * r²
+
+class Square extends Shape:
+  area(): return side²
+
+class ReadOnlySquare extends Square:
+  setSize(): throw Error("Cannot modify")  ← violates LSP
+```
+
+**After:**
+```
+interface Shape:
+  area(): number                  ← read-only contract
+
+class Circle implements Shape:
+  area(): return π * r²
+
+class Square implements Shape:
+  area(): return side²
+
+class MutableSquare extends Square:
+  setSize(s): this.side = s       ← mutation is opt-in, not broken inheritance
+```
+
+**Key insight:** If a subclass has to break the parent's contract to work correctly, the hierarchy is wrong. Flatten it or use composition.
+
+---
+
+## Interface Segregation Principle (ISP)
+
+**Rule:** Clients should not be forced to depend on methods they do not use.
+
+**Smell that triggers it:**
+- A class implements an interface but leaves methods empty or throwing
+- An interface with many methods, most of which any given consumer ignores
+- "Fat interface" that accumulates methods over time
+
+**Before:**
+```
+interface Repository:
+  findById(id)
+  findAll()
+  save(entity)
+  delete(entity)
+  bulkImport(entities)      ← only used by one import service
+  generateReport()          ← only used by reporting
+```
+
+**After:**
+```
+interface Reader:
+  findById(id)
+  findAll()
+
+interface Writer:
+  save(entity)
+  delete(entity)
+
+interface BulkImporter:
+  bulkImport(entities)
+
+class InvoiceRepository implements Reader, Writer, BulkImporter:
+  // ... implements all
+
+class InvoiceService:
+  constructor(reader: Reader, writer: Writer)   ← only sees what it needs
+```
+
+**Key insight:** Each consumer declares the interface it needs. The concrete class implements all of them. Consumers are decoupled from each other.
+
+---
+
+## Dependency Inversion Principle (DIP)
+
+**Rule:** High-level modules depend on abstractions. Low-level modules also depend on abstractions. Abstractions do not depend on details.
+
+**Smell that triggers it:**
+- A business logic class directly instantiates or imports infrastructure (database, HTTP client, file system)
+- Changing a data store requires editing business logic
+- Unit tests require a real database or network call
+
+**Before:**
+```
+class InvoiceService:
+  constructor():
+    this.db = new PostgresDatabase()       ← concrete dependency
+    this.emailer = new SMTPEmailer()       ← concrete dependency
+
+  createInvoice(data):
+    invoice = new Invoice(data)
+    this.db.save(invoice)                  ← can't test without Postgres
+    this.emailer.send(invoice)             ← can't test without SMTP
+```
+
+**After:**
+```
+interface InvoiceRepository:               ← abstraction
+  save(invoice)
+
+interface Notifier:                        ← abstraction
+  send(invoice)
+
+class InvoiceService:
+  constructor(repo: InvoiceRepository, notifier: Notifier)  ← depends on abstractions
+    this.repo = repo
+    this.notifier = notifier
+
+  createInvoice(data):
+    invoice = new Invoice(data)
+    this.repo.save(invoice)
+    this.notifier.send(invoice)
+
+// Production wiring:
+service = new InvoiceService(new PostgresInvoiceRepository(), new SMTPNotifier())
+
+// Test wiring:
+service = new InvoiceService(mockRepository, mockNotifier)   ← no real infra needed
+```
+
+**Key insight:** The business logic (`InvoiceService`) never knows about Postgres or SMTP. It knows only the contracts it needs. This is the foundation that makes unit testing fast and isolated.
+
+---
+
+## Applying SOLID in Practice
+
+**Priority order when multiple principles apply:**
+1. DIP first — if you can't inject dependencies, nothing else matters for testability
+2. SRP — identify the single responsibility before extracting
+3. OCP — once responsibilities are clear, make extension points
+4. ISP — split interfaces when consumers only need subsets
+5. LSP — verify inheritance hierarchies don't break contracts
+
+**During GREEN:** Only apply DIP if the current test literally cannot pass without it (e.g., test needs to inject a mock). Everything else waits for REFACTOR.
+
+**During REFACTOR:** Walk through the list above. Apply only what the current code requires. Rule of Three applies — don't extract until the second occurrence.