@oleksandr.rudnychenko/sync_loop 0.2.5 → 0.3.2

package/dist/src/template/.agent-loop/patterns/code-patterns.md

@@ -0,0 +1,300 @@
+# Code Patterns (P1–P11)
+
+Reusable implementation patterns for layered application code.
+Referenced from [../patterns.md](../patterns.md).
+
+---
+
+## P1 · Port/Adapter
+
+Abstracts infrastructure behind protocol interfaces. Decouples domain logic from external systems.
+
+```python
+# Port (interface/protocol)
+class StoragePort(Protocol):
+    def search(
+        self,
+        collection: str,
+        query: str,
+        *,
+        filters: dict | None = None,
+        limit: int = 10,
+    ) -> list[Record]: ...
+
+# Adapter (concrete implementation)
+class DatabaseAdapter:
+    def __init__(self, client: DBClient) -> None:
+        self._client = client
+
+    def search(
+        self,
+        collection: str,
+        query: str,
+        *,
+        filters: dict | None = None,
+        limit: int = 10,
+    ) -> list[Record]:
+        # Implementation against real infrastructure
+        ...
+```
+
+**Key rules:**
+- Port lives in `libs/{component}/port.*`
+- Adapter lives in `libs/{component}/{impl}.*`
+- Services depend on port interfaces, not adapters directly
+
+---
+
+## P2 · Domain Module
+
+Each domain module follows a consistent multi-file layout:
+
+| File | Purpose |
+|------|---------|
+| `models.*` | Domain entities and value objects |
+| `services.*` | Business logic and orchestration |
+| `routes.*` | Transport endpoints |
+| `tasks.*` | Background tasks (if async processing needed) |
+
+```python
+# services.py — business logic only, no transport concerns
+class OrderService:
+    def __init__(self, repository: OrderRepository) -> None:
+        self._repository = repository
+
+    def process(self, *, order_id: str) -> ProcessResult:
+        order = self._repository.get(order_id)
+        # business logic here
+        return ProcessResult(order_id=order.id, status="completed")
+```
+
+---
+
+## P3 · Background Task Boundary
+
+Task handlers stay thin. Business logic always lives in services.
+
+```python
+# tasks.py — thin wrapper, delegates to service
+def process_order_task(runtime: TaskRuntime, order_id: str):
+    """Background task that delegates to service."""
+    service = runtime.order_service
+    service.update_status(order_id, status="processing")
+
+    try:
+        service.process(order_id=order_id)
+        service.update_status(order_id, status="completed")
+    except Exception as exc:
+        service.update_status(order_id, status="failed", error=str(exc))
+        raise
+```
+
+**Key rules:**
+- Tasks never contain business logic
+- Dependencies injected via runtime, not imported directly
+- Always update status on success and failure
+
+---
+
+## P4 · App Context / Composition Root
+
+Centralized dependency wiring, initialized once at startup:
+
+```python
+@dataclass
+class AppContext:
+    config: Config
+    session_factory: SessionFactory
+    services: ServiceRegistry
+    logger: Logger
+
+_context: AppContext | None = None
+
+def init_app_context(config: Config) -> AppContext:
+    global _context
+    if _context:
+        return _context
+    _context = AppContext(config=config, ...)
+    return _context
+
+def get_app_context() -> AppContext:
+    if _context is None:
+        return init_app_context(load_config())
+    return _context
+```
+
+---
+
+## P5 · Transport Route
+
+Routes only handle transport concerns; all logic delegated to services:
+
+```python
+router = APIRouter()
+
+def get_service() -> OrderService:
+    ctx = get_app_context()
+    return OrderService(ctx.repository)
+
+@router.post("/orders")
+def create_order(
+    data: CreateOrderRequest,
+    service: OrderService = Depends(get_service),
+) -> OrderResponse:
+    result = service.create(data)
+    return OrderResponse(id=result.id, status=result.status)
+```
+
+---
+
+## P6 · Typed Models
+
+Domain entities with explicit types and serialization:
+
+```python
+@dataclass(slots=True)
+class OrderItem:
+    product_id: str
+    quantity: int
+    unit_price: float
+    tags: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "product_id": self.product_id,
+            "quantity": self.quantity,
+            "unit_price": self.unit_price,
+            "tags": self.tags,
+        }
+```
+
+---
+
+## P7 · Collection/Enum Safety
+
+Replace magic strings with typed enums:
+
+```python
+class Collection(str, Enum):
+    ORDERS = "orders"
+    PRODUCTS = "products"
+    USERS = "users"
+
+# Usage: repository.query(Collection.ORDERS, ...)
+# NOT: repository.query("orders", ...)
+```
+
+---
+
+## P8 · Error Handling
+
+Layered exception hierarchy with boundary translation:
+
+```python
+# Domain exceptions
+class DomainError(Exception):
+    """Base error for domain."""
+
+class NotFoundError(DomainError):
+    """Resource not found."""
+
+class ValidationError(DomainError):
+    """Invalid input or state."""
+
+# Route-level translation
+@router.get("/orders/{order_id}")
+def get_order(order_id: str, service = Depends(get_service)):
+    try:
+        return service.get(order_id)
+    except NotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    except ValidationError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+```
+
+---
+
+## P9 · Type Hints Everywhere
+
+All code must have complete type annotations:
+
+```python
+# ✅ Good — fully typed
+def process(
+    order_id: str,
+    *,
+    callback: Callable[..., Awaitable[Response]] | None = None,
+) -> tuple[str, dict[str, Any]] | None:
+    ...
+
+# ❌ Bad — missing annotations
+def process(order_id, callback=None):
+    ...
+```
+
+**Common type aliases:**
+```python
+SessionFactory = Callable[[], Session]
+Filters = Mapping[str, Any]
+```
+
+---
+
+## P10 · Service Orchestration
+
+Services accept all dependencies via constructor — no hidden state:
+
+```python
+# Production code
+class AnalysisService:
+    def __init__(
+        self,
+        repository: Repository,
+        evaluator: EvaluationService,
+    ):
+        self._repository = repository
+        self._evaluator = evaluator
+
+# Test code — inject mocks
+service = AnalysisService(
+    repository=mock_repository,
+    evaluator=mock_evaluator,
+)
+```
+
+---
+
+## P11 · Config Isolation
+
+Centralized, environment-based configuration with startup validation:
+
+```python
+@dataclass
+class Config:
+    database_url: str
+    debug: bool = False
+    max_workers: int = 4
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        return cls(
+            database_url=os.environ["DATABASE_URL"],
+            debug=os.environ.get("DEBUG", "0") == "1",
+            max_workers=int(os.environ.get("MAX_WORKERS", "4")),
+        )
+```
+
+**Key rules:**
+- All config read from environment at startup
+- No scattered `os.environ` calls inside business logic
+- Test config overrides controlled via fixtures
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [../patterns.md](../patterns.md) | Pattern routing index |
+| [refactoring-workflow.md](refactoring-workflow.md) | Safe structural changes |
+| [testing-guide.md](testing-guide.md) | Verification strategy |

package/dist/src/template/.agent-loop/patterns/refactoring-workflow.md

@@ -0,0 +1,114 @@
+# Refactoring Workflow (R1)
+
+Checklist and approach for moving files, changing imports, or restructuring modules.
+Referenced from [../patterns.md](../patterns.md).
+
+---
+
+## Refactoring Checklist
+
+```
+Phase 1: PLAN
+  ☐ Identify all files to move/rename/extract
+  ☐ Map old imports → new imports
+  ☐ Check for documentation references (README, docstrings, agent-loop specs)
+  ☐ Identify public interfaces that must remain stable
+
+Phase 2: EXECUTE
+  ☐ Move files
+  ☐ Update imports in moved files (internal references)
+  ☐ Update all caller imports (use grep to find every reference)
+  ☐ Update documentation examples if they contain import paths
+  ☐ Update .agent-loop/patterns.md structure section if layout changed
+
+Phase 3: VALIDATE (NON-NEGOTIABLE)
+  ☐ 1. Type check: run project type checker
+  ☐ 2. Run tests: execute test suite with fail-fast
+  ☐ 3. Check docs: grep for old import paths across all files
+  ☐ 4. Verify no orphaned imports (unused or broken)
+
+Phase 4: DOCUMENT
+  ☐ Update README structure section
+  ☐ Update architecture docs if needed
+  ☐ Create report in docs/reports/ if the refactor is major
+```
+
+---
+
+## Example: Moving a Module File
+
+```bash
+# 1. Move file
+mv src/modules/old_location/processor.py src/modules/new_location/processor.py
+
+# 2. Update imports inside the moved file (internal references)
+# e.g., relative imports that changed due to new directory depth
+
+# 3. Find ALL references to the old path
+grep -r "from src.modules.old_location.processor" .
+grep -r "import old_location.processor" .
+
+# 4. Update each reference found:
+#    - tests/unit/test_processor.py
+#    - src/modules/new_location/tasks.py
+#    - docs/architecture.md (if it mentions import paths)
+
+# 5. MANDATORY: Run validation
+# Type check → Tests → Grep for leftover old paths
+```
+
+**Why tests after docs?** Documentation often contains import examples. Tests verify imports actually work and catch typos in updated paths.
+
+---
+
+## Example: Extracting a Function to a New Module
+
+```bash
+# 1. Create the new module
+touch src/libs/parsing/helpers.py
+
+# 2. Move the function definition to the new file
+# Update its internal imports
+
+# 3. In the original file, replace the function body with an import:
+#    from src.libs.parsing.helpers import parse_response
+
+# 4. Find all OTHER callers of the original location
+grep -r "from src.modules.analysis.utils import parse_response" .
+
+# 5. Update all callers to use the new import path
+
+# 6. VALIDATE: type check + tests + grep for old path
+```
+
+---
+
+## Guardrails
+
+- **Prefer reversible steps** — move one file at a time, validate, then move next
+- **Never combine unrelated refactors** — one logical change per commit
+- **Do not hide breaking API changes** — if a public interface moved, update all consumers
+- **Never skip Phase 3** — validation is non-negotiable, even for "simple" moves
+- **Grep is your friend** — always search for the old path after moving; IDEs miss things
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Prevention |
+|---------|------------|
+| Circular imports after move | Map dependency graph before moving |
+| Tests pass but type checker fails | Always run type checker first |
+| Docs reference old paths | Grep docs/ and *.md files explicitly |
+| Forgot to update __init__.py re-exports | Check all `__init__.py` files in affected packages |
+| Moved too many files at once | Move one file → validate → repeat |
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [../validate-env.md](../validate-env.md) | Stage 1 gates (type check, tests) |
+| [../validate-n.md](../validate-n.md) | Stage 2 neighbor checks (boundary impact) |
+| [testing-guide.md](testing-guide.md) | Regression test strategy |

package/dist/src/template/.agent-loop/patterns/testing-guide.md

@@ -0,0 +1,258 @@
+# Testing Guide (R2)
+
+Comprehensive testing patterns for safe iteration and regression prevention.
+Referenced from [../patterns.md](../patterns.md).
+
+---
+
+## Test Organization
+
+```
+tests/
+├── conftest.py          # Shared fixtures, global setup
+├── factories.py         # Test data builders
+├── mocks.py             # Mock implementations for external deps
+├── api/                 # API/endpoint tests (HTTP client)
+├── integration/         # Multi-component workflow tests
+└── unit/                # Pure logic tests (no I/O)
+```
+
+---
+
+## Pattern 1: Fixture-Based Setup
+
+```python
+# Environment isolation — reset global state each test
+@pytest.fixture(autouse=True)
+def reset_context():
+    """Reset global state before each test."""
+    import app.context
+    app.context._context = None
+    yield
+    app.context._context = None
+
+# Test app configuration
+@pytest.fixture
+def test_app(monkeypatch: pytest.MonkeyPatch, tmp_path: Path):
+    """Configure app with test-safe environment."""
+    monkeypatch.setenv("APP_ENV", "testing")
+    monkeypatch.setenv("ENABLE_BACKGROUND_TASKS", "0")
+    yield create_app()
+
+# API client for endpoint tests
+@pytest.fixture
+def client(test_app):
+    return TestClient(test_app)
+```
+
+---
+
+## Pattern 2: Factory Pattern for Test Data
+
+```python
+class EntityFactory:
+    @staticmethod
+    def create(
+        id: str | None = None,
+        name: str = "Test Entity",
+        entity_type: str = "default",
+        **extras: Any,
+    ) -> dict[str, Any]:
+        return {
+            "id": id or str(uuid4()),
+            "name": name,
+            "metadata": {"type": entity_type, **extras},
+        }
+
+    @staticmethod
+    def with_full_analysis() -> dict[str, Any]:
+        """Semantic constructor for entity with all analysis fields populated."""
+        return EntityFactory.create(
+            name="Fully Analyzed Entity",
+            entity_type="analyzed",
+            score=85.0,
+            grade="B",
+        )
+```
+
+---
+
+## Pattern 3: Mock External Dependencies
+
+```python
+class MockExternalService:
+    """Mock for any external service boundary (LLM, API, storage)."""
+    def __init__(self, response: dict | str | None = None):
+        self.response = response or self._default_response()
+        self.calls: list[dict] = []
+
+    async def __call__(self, prompt: str, context: str, **kwargs):
+        self.calls.append({"prompt": prompt, "context": context})
+        return json.dumps(self.response), {}
+
+    @property
+    def call_count(self) -> int:
+        return len(self.calls)
+```
+
+Usage:
+```python
+@pytest.fixture
+def mock_service() -> MockExternalService:
+    return MockExternalService(response={"score": 85})
+
+def test_analysis_delegates_to_service(mock_service):
+    service = AnalysisService(external=mock_service)
+    result = service.analyze(...)
+    assert mock_service.call_count == 1
+```
+
+---
+
+## Pattern 4: Class-Based Test Organization
+
+```python
+class TestParseResponse:
+    def test_valid_json_response(self):
+        response = '{"entity_type": "analyzed", "score": 85}'
+        result = parse_response(response)
+        assert result.entity_type == EntityType.ANALYZED
+
+    def test_invalid_json_fallback(self):
+        result = parse_response("Not JSON")
+        assert result.entity_type == EntityType.UNKNOWN
+
+    def test_missing_fields_use_defaults(self):
+        result = parse_response('{"entity_type": "analyzed"}')
+        assert result.score == 0.0
+```
+
+---
+
+## Pattern 5: Parametrized Tests
+
+```python
+@pytest.mark.parametrize("score,expected_grade", [
+    (95, "A"), (90, "A"),
+    (89.9, "B"), (85, "B"), (80, "B"),
+    (79, "C"), (70, "C"),
+    (69, "D"), (60, "D"),
+    (59, "F"), (0, "F"),
+])
+def test_grade_thresholds(score: float, expected_grade: str):
+    assert compute_grade(score) == expected_grade
+```
+
+---
+
+## Pattern 6: Three-Layer Test Strategy
+
+```python
+# UNIT: Pure logic, no I/O
+def test_parse_response():
+    result = parse_response('{"entity_type": "analyzed"}')
+    assert result.entity_type == EntityType.ANALYZED
+
+# INTEGRATION: Multiple components, mocked external I/O
+def test_analysis_pipeline(mock_service, mock_repository):
+    service = AnalysisService(external=mock_service, repo=mock_repository)
+    report = service.analyze(entities=[...])
+    assert report.aggregate_score > 0
+
+# API: HTTP endpoint, full stack with test client
+def test_analyze_endpoint(client, mock_data):
+    response = client.post("/api/v1/analyze", json=mock_data)
+    assert response.status_code == 200
+    assert "score" in response.json()
+```
+
+---
+
+## Pattern 7: Assertion Patterns
+
+```python
+# ✅ Specific property checks
+assert report.task_id == "task-1"
+assert len(report.metrics) > 0
+assert "total_items" in [m.name for m in report.metrics]
+
+# ✅ Range/constraint checks
+assert 0 <= result.score <= 100
+assert result.entity_type in EntityType
+
+# ✅ Collection checks
+assert all(m.value >= 0 for m in report.metrics)
+assert any(r.entity_type == "analyzed" for r in results)
+
+# ❌ Vague — what is being verified?
+assert report
+assert result is not None
+```
+
+---
+
+## Pattern 8: Naming Convention
+
+Format: `test_<action>_<condition>_<outcome>`
+
+```
+test_returns_report                      # Basic happy path
+test_metrics_computed_correctly          # Specific behavior
+test_unknown_type_falls_back_to_default  # Edge case
+test_invalid_json_fallback               # Error handling
+test_missing_fields_use_defaults         # Default behavior
+test_empty_input_returns_empty_report    # Boundary condition
+```
+
+---
+
+## Test Metrics (Target)
+
+| Metric | Target |
+|--------|--------|
+| Pass Rate | 100% |
+| Unit proportion | ≥ 70% |
+| Integration proportion | ≤ 20% |
+| API proportion | ≤ 10% |
+
+---
+
+## Test Heuristics
+
+| Heuristic | Guideline |
+|-----------|-----------|
+| **Speed** | Unit < 10ms, Integration < 100ms, API < 1s |
+| **Isolation** | Each test independent, no shared mutable state |
+| **Coverage** | Critical paths and edge cases tested, not chasing 100% line coverage |
+| **Clarity** | Test name explains what behavior is being verified |
+| **Simplicity** | One logical assertion per test (multiple `assert` OK if testing one concept) |
+| **Structure** | Arrange → Act → Assert (AAA pattern) |
+| **Determinism** | No flaky tests — mock time, randomness, external systems |
+
+---
+
+## Validation Strategy
+
+1. **Changed symbols first** — run tests for files you changed
+2. **Adjacent modules second** — run tests for callers/consumers
+3. **Full suite last** — once local confidence is high, run everything
+
+```bash
+# Targeted
+pytest tests/unit/test_processor.py -x -v
+
+# Adjacent
+pytest tests/unit/ tests/integration/ -x -v -k "processor or analysis"
+
+# Full suite
+pytest tests/ -x -v
+```
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [../validate-env.md](../validate-env.md) | Gate orchestration (test gate details) |
+| [refactoring-workflow.md](refactoring-workflow.md) | Safe code movement (tests after each move) |