@martinffx/atelier 2.0.0 → 3.0.1

package/skills/python-architecture/references/functional-core.md

@@ -1,337 +0,0 @@
-# Functional Core / Imperative Shell
-
-The functional core pattern separates pure business logic from side effects, creating highly testable and maintainable code.
-
-## Core Concept
-
-**Functional Core:**
-- Pure functions with no side effects
-- Deterministic: same input always produces same output
-- No IO operations (database, HTTP, files, time, random)
-- Easy to test (no mocks needed)
-- Business logic and domain rules
-
-**Imperative Shell:**
-- Thin layer handling all side effects
-- Coordinates external dependencies
-- Calls functional core for decisions
-- Hard to test (but simple enough to not need testing)
-
-## Pattern Structure
-
-```
-┌─────────────────────────────────┐
-│     Imperative Shell            │
-│  (HTTP, Database, Files, Time)  │
-│                                 │
-│  ┌───────────────────────────┐  │
-│  │   Functional Core         │  │
-│  │   (Pure Business Logic)   │  │
-│  │   - Calculations          │  │
-│  │   - Decisions             │  │
-│  │   - Transformations       │  │
-│  └───────────────────────────┘  │
-│                                 │
-└─────────────────────────────────┘
-```
-
-## Examples
-
-### ❌ Bad: Mixed Concerns
-
-```python
-import requests
-from datetime import datetime
-from database import save_order
-
-def process_order(order_id: str) -> None:
-    """Everything mixed together - hard to test"""
-    # IO
-    response = requests.get(f"/api/orders/{order_id}")
-    order_data = response.json()
-
-    # Business logic
-    if order_data["total"] > 100:
-        discount = 0.1
-    else:
-        discount = 0
-
-    # More IO
-    order_data["discount"] = discount
-    order_data["processed_at"] = datetime.now().isoformat()
-
-    # More IO
-    save_order(order_data)
-```
-
-**Problems:**
-- Can't test business logic without HTTP, database, time
-- Hard to verify discount calculation
-- Slow tests (real IO)
-- Unpredictable (depends on current time)
-
-### ✅ Good: Separated Concerns
-
-```python
-# ===== Functional Core (pure functions) =====
-from decimal import Decimal
-from dataclasses import dataclass
-from datetime import datetime
-
-@dataclass
-class OrderData:
-    total: Decimal
-    discount: Decimal
-    processed_at: datetime
-
-def calculate_discount(total: Decimal) -> Decimal:
-    """Pure function - no side effects"""
-    if total > 100:
-        return Decimal("0.1")
-    return Decimal("0")
-
-def apply_discount(order: OrderData, discount: Decimal, processed_at: datetime) -> OrderData:
-    """Pure function - returns new data"""
-    return OrderData(
-        total=order.total * (1 - discount),
-        discount=discount,
-        processed_at=processed_at
-    )
-
-# ===== Imperative Shell (IO coordination) =====
-import requests
-from database import save_order
-
-def process_order(order_id: str) -> None:
-    """Thin shell - just coordinates IO"""
-    # IO: fetch data
-    response = requests.get(f"/api/orders/{order_id}")
-    order_data = response.json()
-
-    # Convert to domain model
-    order = OrderData(
-        total=Decimal(order_data["total"]),
-        discount=Decimal("0"),
-        processed_at=datetime.now()  # IO: current time
-    )
-
-    # Pure: calculate discount
-    discount = calculate_discount(order.total)
-
-    # Pure: apply discount
-    processed_order = apply_discount(order, discount, datetime.now())
-
-    # IO: save result
-    save_order({
-        "total": float(processed_order.total),
-        "discount": float(processed_order.discount),
-        "processed_at": processed_order.processed_at.isoformat()
-    })
-```
-
-**Benefits:**
-- Test `calculate_discount` with no mocks
-- Test `apply_discount` with deterministic inputs
-- Shell is simple enough to not need tests
-- Fast tests (no real IO)
-- Predictable behavior
-
-## Testing Pure Functions
-
-```python
-import pytest
-from decimal import Decimal
-
-def test_discount_for_large_order():
-    """No mocks needed!"""
-    result = calculate_discount(Decimal("150"))
-    assert result == Decimal("0.1")
-
-def test_no_discount_for_small_order():
-    """No setup, no teardown"""
-    result = calculate_discount(Decimal("50"))
-    assert result == Decimal("0")
-
-def test_apply_discount():
-    """Deterministic test"""
-    order = OrderData(
-        total=Decimal("100"),
-        discount=Decimal("0"),
-        processed_at=datetime(2024, 1, 1)
-    )
-
-    result = apply_discount(
-        order,
-        Decimal("0.1"),
-        datetime(2024, 1, 2)
-    )
-
-    assert result.total == Decimal("90")
-    assert result.discount == Decimal("0.1")
-    assert result.processed_at == datetime(2024, 1, 2)
-```
-
-## Identifying Side Effects
-
-Ask these questions:
-1. **Does it perform IO?** (Database, HTTP, files, logging)
-2. **Does it depend on current time?** (datetime.now(), time.time())
-3. **Does it use randomness?** (random.random(), uuid.uuid4())
-4. **Does it mutate state?** (list.append(), dict.update())
-5. **Does it depend on global state?** (environment variables, config)
-
-If yes to any → **Imperative Shell**
-If no to all → **Functional Core**
-
-## Pushing Side Effects to the Edges
-
-### ❌ Bad: Side effects in the middle
-
-```python
-def calculate_price(product_id: str) -> Decimal:
-    """Pure function name, but has hidden IO"""
-    product = db.get_product(product_id)  # Hidden side effect!
-    return product.price * Decimal("1.1")
-```
-
-### ✅ Good: Accept data as parameter
-
-```python
-def calculate_price(product: Product) -> Decimal:
-    """Truly pure - takes data, returns result"""
-    return product.price * Decimal("1.1")
-
-def get_calculated_price(product_id: str) -> Decimal:
-    """Shell function - name reflects IO"""
-    product = db.get_product(product_id)  # IO is explicit
-    return calculate_price(product)  # Delegates to pure function
-```
-
-## Handling Time as a Side Effect
-
-### ❌ Bad: Hidden time dependency
-
-```python
-def is_expired(user: User) -> bool:
-    """Not pure - depends on current time"""
-    return user.expires_at < datetime.now()
-```
-
-### ✅ Good: Pass time as parameter
-
-```python
-def is_expired(user: User, current_time: datetime) -> bool:
-    """Pure - time is explicit parameter"""
-    return user.expires_at < current_time
-
-def check_user_expiration(user: User) -> bool:
-    """Shell - provides current time"""
-    return is_expired(user, datetime.now())
-```
-
-## Advanced: Decision/Effect Separation
-
-For complex workflows, separate decisions from effects:
-
-```python
-from dataclasses import dataclass
-from enum import Enum
-
-class Effect(Enum):
-    SEND_EMAIL = "send_email"
-    CHARGE_CARD = "charge_card"
-    CREATE_ORDER = "create_order"
-
-@dataclass
-class Decision:
-    """Pure data describing what to do"""
-    effects: list[Effect]
-    order_data: dict
-
-def decide_order_workflow(cart: Cart, user: User, payment: Payment) -> Decision:
-    """Pure function - returns description of effects"""
-    effects = []
-
-    if user.requires_verification:
-        effects.append(Effect.SEND_EMAIL)
-
-    if payment.amount > 0:
-        effects.append(Effect.CHARGE_CARD)
-
-    effects.append(Effect.CREATE_ORDER)
-
-    return Decision(
-        effects=effects,
-        order_data={"cart": cart, "user": user, "payment": payment}
-    )
-
-def execute_order_workflow(cart: Cart, user: User, payment: Payment) -> None:
-    """Shell - executes the effects"""
-    decision = decide_order_workflow(cart, user, payment)
-
-    for effect in decision.effects:
-        if effect == Effect.SEND_EMAIL:
-            email_service.send_verification(user.email)
-        elif effect == Effect.CHARGE_CARD:
-            payment_service.charge(payment.token, payment.amount)
-        elif effect == Effect.CREATE_ORDER:
-            order_service.create(decision.order_data)
-```
-
-**Benefits:**
-- Test decisions without executing effects
-- Retry-safe (decisions are pure)
-- Effects can be logged, audited, replayed
-
-## Guidelines
-
-1. **Start with pure functions**: Write business logic first without IO
-2. **Name functions honestly**: `get_user()` implies IO, `calculate_discount()` implies pure
-3. **Minimize shell thickness**: Keep imperative shell as thin as possible
-4. **Test the core**: Focus tests on functional core (business logic)
-5. **Accept data, don't fetch it**: Pure functions take parameters, don't call repositories
-6. **Return new data**: Don't mutate, return new values
-7. **Make time explicit**: Pass datetime as parameter instead of calling `datetime.now()`
-
-## When to Break the Rules
-
-**Logging**: Acceptable side effect in functional core if:
-- Non-invasive (doesn't change behavior)
-- Can be disabled/stubbed in tests
-- Doesn't affect return value
-
-```python
-import logging
-
-logger = logging.getLogger(__name__)
-
-def calculate_discount(total: Decimal) -> Decimal:
-    """Logging is acceptable side effect"""
-    if total > 100:
-        logger.debug(f"Applying discount to order total: {total}")
-        return Decimal("0.1")
-    return Decimal("0")
-```
-
-**Caching**: Acceptable mutation if:
-- Implementation detail (doesn't affect observable behavior)
-- Transparent to callers
-- Doesn't break determinism
-
-```python
-from functools import lru_cache
-
-@lru_cache(maxsize=128)
-def fibonacci(n: int) -> int:
-    """Pure function with internal caching"""
-    if n < 2:
-        return n
-    return fibonacci(n - 1) + fibonacci(n - 2)
-```
-
-## Summary
-
-- **Functional Core**: Pure functions, business logic, easy to test
-- **Imperative Shell**: IO coordination, thin layer, simple
-- **Benefits**: Testability, reliability, maintainability
-- **Key insight**: Most bugs are in business logic, not IO - make that testable

package/skills/python-build-tools/SKILL.md

@@ -1,153 +0,0 @@
----
-name: python-build-tools
-description: Python project tooling with uv, mise, ruff, basedpyright, and pytest. Use when setting up pyproject.toml, running builds, typechecking, configuring tests, linting, formatting, or managing Python environments.
-user-invocable: false
----
-
-# Python Build Tools
-
-Modern Python development tooling using uv, mise, ruff, basedpyright, and pytest.
-
-## Quick Start
-
-### Minimal pyproject.toml
-
-```toml
-[project]
-name = "my-project"
-version = "0.1.0"
-requires-python = ">=3.12"
-dependencies = ["fastapi", "pydantic"]
-
-[project.optional-dependencies]
-dev = ["pytest>=8.0.0", "ruff>=0.8.0", "basedpyright>=1.0.0"]
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.ruff]
-target-version = "py312"
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "N", "UP", "RUF"]
-
-[tool.basedpyright]
-typeCheckingMode = "strict"
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-```
-
-### Setup Project
-
-```bash
-uv init my-project && cd my-project
-uv sync
-uv add fastapi pydantic
-uv add --dev pytest ruff basedpyright
-```
-
-## Tool Overview
-
-| Tool | Purpose | Replaces |
-|------|---------|----------|
-| **uv** | Package management | pip, virtualenv |
-| **mise** | Version & tasks | pyenv, asdf |
-| **ruff** | Lint & format | black, isort, flake8 |
-| **basedpyright** | Type checking | mypy |
-| **pytest** | Testing | unittest |
-
-## Common Commands
-
-### Lint and Format
-
-```bash
-uv run ruff check --fix .
-uv run ruff format .
-```
-
-### Type Check
-
-```bash
-uv run basedpyright
-uv run basedpyright src/main.py
-```
-
-### Test
-
-```bash
-uv run pytest
-uv run pytest --cov=src --cov-report=html
-```
-
-### Manage Dependencies
-
-```bash
-uv add fastapi
-uv add --dev pytest
-uv lock --upgrade
-uv tree
-```
-
-## Mise Configuration
-
-Create `.mise.toml` for consistent development:
-
-```toml
-[tools]
-python = "3.12"
-
-[tasks.lint]
-run = "uv run ruff check --fix ."
-
-[tasks.format]
-run = "uv run ruff format ."
-
-[tasks.typecheck]
-run = "uv run basedpyright"
-
-[tasks.test]
-run = "uv run pytest"
-
-[tasks.check]
-depends = ["lint", "format", "typecheck", "test"]
-```
-
-Usage:
-
-```bash
-mise install
-mise run check
-```
-
-## Type Hints Example
-
-```python
-from decimal import Decimal
-from typing import Optional
-
-def calculate_discount(
-    total: Decimal,
-    rate: Optional[Decimal] = None
-) -> Decimal:
-    if rate is None:
-        rate = Decimal("0.1")
-    return total * rate
-```
-
-## Best Practices
-
-1. Use uv for all package management (faster, reliable)
-2. Pin Python version with mise
-3. Configure tools in pyproject.toml
-4. Enable strict type checking
-5. Run checks before commit
-
-## References
-
-For detailed configuration and advanced patterns:
-
-- **[references/uv.md](references/uv.md)** - Workspaces, scripts, dependency management
-- **[references/ruff.md](references/ruff.md)** - Rules, per-file ignores, pre-commit integration
-- **[references/basedpyright.md](references/basedpyright.md)** - Type patterns, generics, protocols