guardian-framework 0.1.0

package/templates/languages/python-patterns.md

@@ -0,0 +1,312 @@
+# Python Code Patterns
+
+> **Purpose:** Reusable Python patterns for Guardian projects.
+> **Generic:** Adapt for your framework (FastAPI, Django, etc.).
+
+---
+
+## Error Handling
+
+```python
+# Custom exception classes
+class ValidationError(Exception):
+    def __init__(self, message: str, field: str):
+        super().__init__(message)
+        self.field = field
+
+class ConfigError(Exception):
+    pass
+
+# Result type pattern (optional, for library code)
+from dataclasses import dataclass
+from typing import Generic, TypeVar, Union
+
+T = TypeVar('T')
+E = TypeVar('E')
+
+@dataclass
+class Ok(Generic[T]):
+    value: T
+    ok: bool = True
+
+@dataclass
+class Err(Generic[E]):
+    error: E
+    ok: bool = False
+
+Result = Union[Ok[T], Err[E]]
+
+def parse_config(input: str) -> Result[dict, ValidationError]:
+    try:
+        return Ok(json.loads(input))
+    except json.JSONDecodeError:
+        return Err(ValidationError("Invalid JSON", "config"))
+```
+
+---
+
+## Tracing / Logging
+
+```python
+import logging
+import structlog
+
+# Structured logging
+logger = structlog.get_logger()
+
+def process_request(user_id: str, request_id: str):
+    logger.info("Processing request", user_id=user_id, request_id=request_id)
+    try:
+        result = do_work()
+        logger.info("Request complete", result=result)
+    except Exception as e:
+        logger.error("Request failed", error=str(e), exc_info=True)
+        raise
+
+# Standard logging alternative
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    level=logging.INFO
+)
+```
+
+---
+
+## Cancellation / Cleanup
+
+```python
+import asyncio
+from contextlib import asynccontextmanager
+
+# Async cancellation
+async def long_running_task(cancel_event: asyncio.Event):
+    while not cancel_event.is_set():
+        await do_work()
+        await asyncio.sleep(1)
+
+# Context manager for cleanup
+@asynccontextmanager
+async def managed_resource():
+    resource = acquire_resource()
+    try:
+        yield resource
+    finally:
+        release_resource(resource)
+
+# Usage
+async def main():
+    cancel_event = asyncio.Event()
+    task = asyncio.create_task(long_running_task(cancel_event))
+
+    # Cancel after timeout
+    await asyncio.sleep(10)
+    cancel_event.set()
+    await task
+```
+
+---
+
+## Atomic Writes
+
+```python
+import os
+import tempfile
+
+def atomic_write(filepath: str, content: str):
+    # Write to temp file in same directory
+    dir_path = os.path.dirname(filepath)
+    with tempfile.NamedTemporaryFile(
+        mode='w',
+        dir=dir_path,
+        delete=False,
+        suffix='.tmp'
+    ) as tmp:
+        tmp.write(content)
+        tmp_path = tmp.name
+
+    # Atomic rename
+    os.replace(tmp_path, filepath)
+```
+
+---
+
+## Async Patterns
+
+```python
+import asyncio
+
+# Parallel execution
+async def parallel_tasks():
+    results = await asyncio.gather(
+        task_a(),
+        task_b(),
+        task_c()
+    )
+    return results
+
+# Concurrent limit
+async def concurrent_limit(tasks: list, limit: int):
+    semaphore = asyncio.Semaphore(limit)
+
+    async def bounded_task(task):
+        async with semaphore:
+            return await task()
+
+    return await asyncio.gather(*[bounded_task(t) for t in tasks])
+```
+
+---
+
+## Testing
+
+```python
+# pytest patterns
+import pytest
+
+def test_parse():
+    result = parse("input")
+    assert result.ok == True
+
+@pytest.mark.asyncio
+async def test_async_flow():
+    result = await run_flow()
+    assert result is not None
+
+# Mocking
+from unittest.mock import Mock, patch
+
+@patch('module.dependency')
+def test_with_mock(mock_dep):
+    mock_dep.return_value = "mocked"
+    result = use_dependency()
+    assert result == "expected"
+```
+
+---
+
+## Anti-Patterns (NEVER DO)
+
+```python
+# ❌ Bare except
+try:
+    do_work()
+except:  # BAD - catches everything including KeyboardInterrupt
+    pass
+
+# ✅ Specific exception
+try:
+    do_work()
+except ValueError as e:
+    logger.error("Validation failed", error=e)
+except Exception as e:
+    logger.error("Unexpected error", error=e)
+
+# ❌ Silent failures
+def bad():
+    result = risky_operation()
+    if not result:
+        return None  # BAD - no indication of failure
+
+# ✅ Explicit error handling
+def good():
+    result = risky_operation()
+    if not result.ok:
+        raise ValidationError(result.error)
+    return result.value
+
+# ❌ Global state
+config = {}  # BAD - mutable global
+
+# ✅ Encapsulated state
+class Config:
+    def __init__(self):
+        self._data = {}
+
+    def get(self, key):
+        return self._data.get(key)
+```
+
+---
+
+## Build Commands
+
+```bash
+# Install dependencies
+poetry install
+
+# Activate shell with project venv
+poetry shell
+
+# Run with poetry venv
+poetry run archguard
+
+# Test
+poetry run pytest
+
+# Test with coverage
+poetry run pytest --cov=.
+
+# Lint
+poetry run ruff check .
+
+# Format
+poetry run ruff format .
+
+# Type check
+poetry run mypy .
+
+# Security audit
+poetry run pip-audit
+
+# Build
+poetry build
+```
+
+---
+
+## Dependencies
+
+```toml
+# pyproject.toml — Poetry-based project
+[tool.poetry]
+name = "archguard"
+version = "0.1.0"
+description = "Engineering Change Intelligence Platform"
+authors = ["Arman <arman@example.com>"]
+readme = "README.md"
+package-mode = true
+
+[tool.poetry.dependencies]
+python = "^3.12"
+fastapi = "^0.115.0"
+uvicorn = "^0.32.0"
+pydantic = "^2.0.0"
+structlog = "^24.0.0"
+asyncpg = "^0.30.0"
+httpx = "^0.27.0"
+redis = "^5.0.0"
+celery = "^5.4.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pytest-asyncio = "^0.24.0"
+pytest-cov = "^6.0.0"
+ruff = "^0.8.0"
+mypy = "^1.0.0"
+pip-audit = "^2.0.0"
+
+[tool.poetry.scripts]
+archguard = "archguard.main:main"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+```

package/templates/languages/rust-patterns.md

@@ -0,0 +1,232 @@
+# Rust Code Patterns
+
+> **Purpose:** Reusable Rust patterns for Guardian projects.
+> **Source:** Extracted from Rigorix framework.
+
+---
+
+## Error Handling
+
+```rust
+// Use thiserror for all errors (never anyhow in library code)
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum MyError {
+    #[error("IO error: {0}")]
+    Io(#[from] std::io::Error),
+
+    #[error("Parse error at line {line}: {message}")]
+    Parse { line: usize, message: String },
+
+    #[error("Invalid configuration: {0}")]
+    Config(String),
+}
+
+// Automatic conversion with #[from]
+fn read_file(path: &str) -> Result<String, MyError> {
+    std::fs::read_to_string(path)?; // Auto-converts io::Error → MyError
+    Ok(content)
+}
+```
+
+---
+
+## Tracing / Logging
+
+```rust
+use tracing::{instrument, info, warn, error};
+
+// Add #[instrument] to public functions
+#[instrument(skip(non_debug_param), fields(user_id = %user_id))]
+pub async fn process_request(user_id: Uuid, non_debug_param: Vec<u8>) -> Result<()> {
+    info!("Processing request");
+    // ...
+    warn!("Something unusual happened");
+    // ...
+}
+```
+
+---
+
+## Cancellation / Cleanup
+
+```rust
+use tokio_util::sync::CancellationToken;
+
+pub async fn long_running_task(cancel_token: CancellationToken) -> Result<()> {
+    loop {
+        // Check cancellation in loops
+        if cancel_token.is_cancelled() {
+            info!("Task cancelled, cleaning up");
+            break;
+        }
+
+        // Do work
+        do_work()?;
+
+        // Sleep with cancellation awareness
+        tokio::select! {
+            _ = tokio::time::sleep(Duration::from_secs(1)) => {},
+            _ = cancel_token.cancelled() => break,
+        }
+    }
+    Ok(())
+}
+```
+
+---
+
+## Atomic Writes
+
+```rust
+use std::fs;
+use std::path::Path;
+
+// Write-rename pattern for atomic file persistence
+pub fn atomic_write(path: &Path, content: &str) -> std::io::Result<()> {
+    let temp_path = path.with_extension("tmp");
+
+    // Write to temp file
+    fs::write(&temp_path, content)?;
+
+    // Atomic rename (on POSIX systems)
+    fs::rename(&temp_path, path)?;
+
+    Ok(())
+}
+```
+
+---
+
+## Async Patterns
+
+```rust
+// Use tokio for async runtime
+use tokio::sync::{Mutex, RwLock};
+
+// RwLock for read-heavy workloads
+pub struct Cache {
+    data: RwLock<HashMap<String, Data>>,
+}
+
+// Mutex for write-heavy or complex state
+pub struct StateMachine {
+    state: Mutex<State>,
+}
+
+// Prefer async-friendly types
+// ✅ Use tokio::fs instead of std::fs in async context
+// ❌ Never block in async context (no std::fs::read_to_string)
+```
+
+---
+
+## Testing
+
+```rust
+// Unit tests inline
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_parse() {
+        let result = parse("input");
+        assert!(result.is_ok());
+    }
+}
+
+// Integration tests in tests/ directory
+// tests/integration_test.rs
+use rigorix::*;
+
+#[tokio::test]
+async fn test_full_flow() {
+    let result = run_flow();
+    assert!(result.is_ok());
+}
+```
+
+---
+
+## Anti-Patterns (NEVER DO)
+
+```rust
+// ❌ Using anyhow in library code
+use anyhow::Result;  // BAD
+
+// ✅ Use thiserror for library errors
+use thiserror::Error;  // GOOD
+
+// ❌ Blocking in async context
+async fn bad() {
+    let data = std::fs::read_to_string("file");  // BAD - blocks
+}
+
+// ✅ Use async-friendly APIs
+async fn good() {
+    let data = tokio::fs::read_to_string("file").await;  // GOOD
+}
+
+// ❌ Unbounded channels
+let (tx, rx) = mpsc::unbounded_channel();  // BAD
+
+// ✅ Bounded channels with backpressure
+let (tx, rx) = mpsc::channel(100);  // GOOD
+
+// ❌ unwrap() in production code
+let value = result.unwrap();  // BAD
+
+// ✅ Proper error handling
+let value = result?;  // GOOD
+// Or with context
+let value = result.map_err(|e| MyError::Context(e))?;
+```
+
+---
+
+## Build Commands
+
+```bash
+# Build
+cargo build
+
+# Build release
+cargo build --release
+
+# Test
+cargo test --all
+
+# Test specific
+cargo test --test integration_test
+
+# Lint
+cargo clippy -- -D warnings
+
+# Format
+cargo fmt --check
+
+# Security audit
+cargo audit
+
+# Coverage
+cargo tarpaulin --out Html
+```
+
+---
+
+## Dependencies
+
+```toml
+# Cargo.toml standard deps
+[dependencies]
+tokio = { version = "1", features = ["full"] }
+thiserror = "1"
+tracing = "0.1"
+tracing-subscriber = "0.3"
+serde = { version = "1", features = ["derive"] }
+
+[dev-dependencies]
+tokio-test = "0.4"
+```