@bcelep/capint 0.4.2 → 0.7.0

package/skills/dignified-python/references/advanced/exception-handling.md

@@ -0,0 +1,185 @@
+---
+description:
+  Detailed exception handling patterns including B904 chaining, third-party API compatibility, and
+  anti-patterns.
+---
+
+# Exception Handling Reference
+
+**Read when**: Writing try/except blocks, wrapping third-party APIs, seeing `from e` or `from None`
+
+---
+
+## When Exceptions ARE Acceptable
+
+Exceptions are ONLY acceptable at:
+
+1. **Error boundaries** (CLI/API level)
+2. **Third-party API compatibility** (when no alternative exists)
+3. **Adding context before re-raising**
+
+### 1. Error Boundaries
+
+```python
+# ACCEPTABLE: CLI command error boundary
+@click.command("create")
+@click.pass_obj
+def create(ctx: ErkContext, name: str) -> None:
+    """Create a worktree."""
+    try:
+        create_worktree(ctx, name)
+    except subprocess.CalledProcessError as e:
+        click.echo(f"Error: Git command failed: {e.stderr}", err=True)
+        raise SystemExit(1)
+```
+
+### 2. Third-Party API Compatibility
+
+```python
+# ACCEPTABLE: Third-party API forces exception handling
+def _get_bigquery_sample(sql_client, table_name):
+    """
+    BigQuery's TABLESAMPLE doesn't work on views.
+    There's no reliable way to determine a priori whether
+    a table supports TABLESAMPLE.
+    """
+    try:
+        return sql_client.run_query(f"SELECT * FROM {table_name} TABLESAMPLE...")
+    except Exception:
+        return sql_client.run_query(f"SELECT * FROM {table_name} ORDER BY RAND()...")
+```
+
+> **The test for "no alternative exists"**: Can you validate or check the condition BEFORE calling
+> the API? If yes (even using a different function/method), use LBYL. The exception only applies
+> when the API provides NO way to determine success a priori—you literally must attempt the
+> operation to know if it will work.
+
+### What Does NOT Qualify as Third-Party API Compatibility
+
+Standard library functions with known LBYL alternatives do NOT qualify:
+
+```python
+# WRONG: int() has LBYL alternative (str.isdigit)
+try:
+    port = int(user_input)
+except ValueError:
+    port = 80
+
+# CORRECT: Check before calling
+if user_input.lstrip('-+').isdigit():
+    port = int(user_input)
+else:
+    port = 80
+
+# WRONG: datetime.fromisoformat() can be validated first
+try:
+    dt = datetime.fromisoformat(timestamp_str)
+except ValueError:
+    dt = None
+
+# CORRECT: Validate format before parsing
+def _is_iso_format(s: str) -> bool:
+    return len(s) >= 10 and s[4] == "-" and s[7] == "-"
+
+if _is_iso_format(timestamp_str):
+    dt = datetime.fromisoformat(timestamp_str)
+else:
+    dt = None
+```
+
+### 3. Adding Context Before Re-raising
+
+```python
+# ACCEPTABLE: Adding context before re-raising
+try:
+    process_file(config_file)
+except yaml.YAMLError as e:
+    raise ValueError(f"Failed to parse config file {config_file}: {e}") from e
+```
+
+---
+
+## Exception Chaining (B904 Lint Compliance)
+
+**Ruff rule B904** requires explicit exception chaining when raising inside an `except` block. This
+prevents losing the original traceback.
+
+```python
+# CORRECT: Chain to preserve context
+try:
+    parse_config(path)
+except ValueError as e:
+    click.echo(json.dumps({"success": False, "error": str(e)}))
+    raise SystemExit(1) from e  # Preserves traceback
+
+# CORRECT: Explicitly break chain when intentional
+try:
+    fetch_from_cache(key)
+except KeyError:
+    # Original exception is not relevant to caller
+    raise ValueError(f"Unknown key: {key}") from None
+
+# WRONG: Missing exception chain (B904 violation)
+try:
+    parse_config(path)
+except ValueError:
+    raise SystemExit(1)  # Lint error: missing 'from e' or 'from None'
+
+# CORRECT: CLI error boundary with JSON output
+try:
+    result = some_operation()
+except RuntimeError as e:
+    click.echo(json.dumps({"success": False, "error": str(e)}))
+    raise SystemExit(0) from None  # Exception is in JSON, traceback irrelevant to CLI user
+```
+
+**When to use each:**
+
+- `from e` - Preserve original exception for debugging
+- `from None` - Intentionally suppress original (e.g., transforming exception type, CLI JSON output)
+
+---
+
+## Exception Anti-Patterns
+
+**Never swallow exceptions silently**
+
+Even at error boundaries, you must at least log/warn so issues can be diagnosed:
+
+```python
+# WRONG: Silent exception swallowing
+try:
+    risky_operation()
+except:
+    pass
+
+# WRONG: Silent swallowing even at error boundary
+try:
+    optional_feature()
+except Exception:
+    pass  # Silent - impossible to diagnose issues
+
+# CORRECT: Let exceptions bubble up (default)
+risky_operation()
+
+# CORRECT: At error boundaries, log the exception
+try:
+    optional_feature()
+except Exception as e:
+    logging.warning("Optional feature failed: %s", e)  # Diagnosable
+```
+
+**Never use silent fallback behavior**
+
+```python
+# WRONG: Silent fallback masks failure
+def process_text(text: str) -> dict:
+    try:
+        return llm_client.process(text)
+    except Exception:
+        return regex_parse_fallback(text)
+
+# CORRECT: Let error bubble to boundary
+def process_text(text: str) -> dict:
+    return llm_client.process(text)
+```

package/skills/dignified-python/references/advanced/interfaces.md

@@ -0,0 +1,183 @@
+---
+description: ABC vs Protocol decision guide, dependency injection patterns, and complete DI examples.
+---
+
+# Interface Design Reference
+
+**Read when**: Creating ABC/Protocol classes, writing @abstractmethod, designing gateway interfaces
+
+---
+
+## ABC vs Protocol: Choosing the Right Interface
+
+**ABCs (nominal typing)** and **Protocols (structural typing)** serve different purposes. Choose
+based on ownership and coupling needs.
+
+| Use Case                                  | Recommended | Why                                                  |
+| ----------------------------------------- | ----------- | ---------------------------------------------------- |
+| Internal interfaces you control           | ABC         | Explicit enforcement, runtime validation, code reuse |
+| Third-party library boundaries            | Protocol    | No inheritance required, loose coupling              |
+| Plugin systems with isinstance checks     | ABC         | Reliable runtime type validation                     |
+| Minimal interface contracts (1-2 methods) | Protocol    | Less boilerplate, focused contracts                  |
+
+**Default for erk internal code: ABC. Default for external library facades: Protocol.**
+
+---
+
+## ABC Interface Pattern
+
+```python
+# CORRECT: Use ABC for interfaces
+from abc import ABC, abstractmethod
+
+class Repository(ABC):
+    @abstractmethod
+    def save(self, entity: Entity) -> None:
+        """Save entity to storage."""
+        ...
+
+    @abstractmethod
+    def load(self, id: str) -> Entity:
+        """Load entity by ID."""
+        ...
+
+class PostgresRepository(Repository):
+    def save(self, entity: Entity) -> None:
+        # Implementation
+        pass
+
+    def load(self, id: str) -> Entity:
+        # Implementation
+        pass
+```
+
+---
+
+## Benefits of ABC (Internal Interfaces)
+
+1. **Explicit inheritance** - Clear class hierarchy, explicit opt-in
+2. **Runtime validation** - Errors at instantiation if abstract methods missing
+3. **Code reuse** - Can include concrete methods and shared logic
+4. **Reliable isinstance()** - Full signature checking at runtime
+
+---
+
+## Benefits of Protocol (External Boundaries)
+
+1. **No inheritance required** - Works with code you don't control
+2. **Loose coupling** - Implementations don't know about the protocol
+3. **Minimal contracts** - Define only the methods you need
+4. **Duck typing** - Aligns with Python's philosophy
+
+---
+
+## Complete DI Example
+
+```python
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+# Define the interface
+class DataStore(ABC):
+    @abstractmethod
+    def get(self, key: str) -> str | None:
+        """Retrieve value by key."""
+        ...
+
+    @abstractmethod
+    def set(self, key: str, value: str) -> None:
+        """Store value with key."""
+        ...
+
+# Real implementation
+class RedisStore(DataStore):
+    def get(self, key: str) -> str | None:
+        return self.client.get(key)
+
+    def set(self, key: str, value: str) -> None:
+        self.client.set(key, value)
+
+# Fake for testing
+class FakeStore(DataStore):
+    def __init__(self) -> None:
+        self._data: dict[str, str] = {}
+
+    def get(self, key: str) -> str | None:
+        if key not in self._data:
+            return None
+        return self._data[key]
+
+    def set(self, key: str, value: str) -> None:
+        self._data[key] = value
+
+# Business logic accepts interface
+@dataclass
+class Service:
+    store: DataStore  # Depends on abstraction
+
+    def process(self, item: str) -> None:
+        cached = self.store.get(item)
+        if cached is None:
+            result = expensive_computation(item)
+            self.store.set(item, result)
+        else:
+            result = cached
+        use_result(result)
+```
+
+---
+
+## When to Use Protocol
+
+**Protocols excel at defining interfaces for code you don't control:**
+
+```python
+# CORRECT: Protocol for third-party library facade
+from typing import Protocol
+
+class HttpClient(Protocol):
+    """Interface for HTTP operations - decouples from requests/httpx/aiohttp."""
+    def get(self, url: str) -> Response: ...
+    def post(self, url: str, data: dict) -> Response: ...
+
+# Any HTTP library that has these methods works - no inheritance needed
+def fetch_data(client: HttpClient, endpoint: str) -> dict:
+    response = client.get(endpoint)
+    return response.json()
+```
+
+**Protocols are also appropriate for minimal, focused interfaces:**
+
+```python
+# CORRECT: Protocol for structural typing with minimal interface
+from typing import Protocol
+
+class Closeable(Protocol):
+    def close(self) -> None: ...
+
+def cleanup_resources(resources: list[Closeable]) -> None:
+    for r in resources:
+        r.close()
+```
+
+---
+
+## Protocol Limitations
+
+1. **No runtime validation** - `@runtime_checkable` only checks method existence, not signatures
+2. **No code reuse** - Protocols shouldn't have method implementations
+3. **Weaker isinstance() checks** - ABCs provide more reliable runtime type checking
+
+---
+
+## Decision Checklist
+
+Before defining an interface (ABC or Protocol):
+
+- [ ] Do I own all implementations? -> Prefer ABC
+- [ ] Am I wrapping a third-party library? -> Prefer Protocol
+- [ ] Do I need runtime isinstance() validation? -> Use ABC
+- [ ] Is this a minimal interface (1-2 methods)? -> Protocol may be simpler
+- [ ] Do I need shared method implementations? -> Use ABC
+
+**Default for erk internal code: ABC. Default for external library facades: Protocol.**

package/skills/dignified-python/references/advanced/typing-advanced.md

@@ -0,0 +1,158 @@
+---
+description: Advanced typing patterns including cast() with assertions, Literal types for programmatic strings.
+---
+
+# Advanced Typing Reference
+
+**Read when**: Using typing.cast(), creating Literal type aliases, narrowing types
+
+---
+
+## Using `typing.cast()`
+
+### Core Rule
+
+**ALWAYS verify `cast()` with a runtime assertion, unless there's a documented reason not to.**
+
+`typing.cast()` is a compile-time only construct—it tells the type checker to trust you but performs
+no runtime verification. If your assumption is wrong, you'll get silent misbehavior instead of a
+clear error.
+
+### Required Pattern
+
+```python
+from collections.abc import MutableMapping
+from typing import Any, cast
+
+# CORRECT: Runtime assertion before cast
+assert isinstance(doc, MutableMapping), f"Expected MutableMapping, got {type(doc)}"
+cast(dict[str, Any], doc)["key"] = value
+
+# CORRECT: Alternative with hasattr for duck typing
+assert hasattr(obj, '__setitem__'), f"Expected subscriptable, got {type(obj)}"
+cast(dict[str, Any], obj)["key"] = value
+```
+
+### Anti-Pattern
+
+```python
+# WRONG: Cast without runtime verification
+cast(dict[str, Any], doc)["key"] = value  # If doc isn't a dict-like, silent failure
+```
+
+### When to Skip Runtime Verification
+
+**Default: Always add the assertion when cost is trivial (O(1) checks like `in`, `isinstance`).**
+
+Skip the assertion only in these narrow cases:
+
+1. **Immediately after a type guard**: The check was just performed and would be redundant
+
+   ```python
+   if isinstance(value, str):
+       # No assertion needed - we just checked
+       result = cast(str, value).upper()
+   ```
+
+2. **Performance-critical hot path**: Add a comment explaining the measured overhead
+   ```python
+   # Skip assertion: called 10M times/sec, isinstance adds 15% overhead
+   # Type invariant maintained by _validate_input() at entry point
+   cast(int, cached_value)
+   ```
+
+**What is NOT a valid reason to skip:**
+
+- "Click validates the choice set" - Add assertion anyway; cost is trivial
+- "The library guarantees the type" - Add assertion anyway; defense in depth
+- "It's obvious from context" - Add assertion anyway; future readers benefit
+
+### Why This Matters
+
+- **Silent bugs are worse than loud bugs**: An assertion failure gives you a stack trace and clear
+  error message
+- **Documentation**: The assertion documents your assumption for future readers
+- **Defense in depth**: Third-party libraries can change behavior between versions
+
+---
+
+## Programmatically Significant Strings
+
+**Use `Literal` types for strings that have programmatic meaning.**
+
+When strings represent a fixed set of valid values (error codes, status values, command types),
+model them in the type system using `Literal`.
+
+### Why This Matters
+
+1. **Type safety** - Typos caught at type-check time, not runtime
+2. **IDE support** - Autocomplete shows valid options
+3. **Documentation** - Valid values are explicit in the code
+4. **Refactoring** - Rename operations work correctly
+
+### Naming Convention
+
+**Use kebab-case for all internal Literal string values:**
+
+```python
+# CORRECT: kebab-case for internal values
+IssueCode = Literal["orphan-state", "orphan-dir", "missing-branch"]
+ErrorType = Literal["not-found", "invalid-format", "timeout-exceeded"]
+```
+
+**Exception: When modeling external systems, match the external API's convention:**
+
+```python
+# CORRECT: Match GitHub API's UPPER_CASE
+PRState = Literal["OPEN", "MERGED", "CLOSED"]
+
+# CORRECT: Match GitHub Actions API's lowercase
+WorkflowStatus = Literal["completed", "in_progress", "queued"]
+```
+
+The rule is: kebab-case by default, external convention when modeling external APIs.
+
+### Pattern
+
+```python
+from dataclasses import dataclass
+from typing import Literal
+
+# CORRECT: Define a type alias for the valid values
+IssueCode = Literal["orphan-state", "orphan-dir", "missing-branch"]
+
+@dataclass(frozen=True)
+class Issue:
+    code: IssueCode
+    message: str
+
+def check_state() -> list[Issue]:
+    issues: list[Issue] = []
+    if problem_detected:
+        issues.append(Issue(code="orphan-state", message="description"))  # Type-checked!
+    return issues
+
+# WRONG: Bare strings without type constraint
+def check_state() -> list[tuple[str, str]]:
+    issues: list[tuple[str, str]] = []
+    issues.append(("orphen-state", "desc"))  # Typo goes unnoticed!
+    return issues
+```
+
+### When to Use Literal
+
+- Error/issue codes
+- Status values (pending, complete, failed)
+- Command types or action names
+- Configuration keys with fixed valid values
+- Any string that is compared programmatically
+
+### Decision Checklist
+
+Before using a bare `str` type, ask:
+
+- Is this string compared with `==` or `in` anywhere?
+- Is there a fixed set of valid values?
+- Would a typo in this string cause a bug?
+
+If any answer is "yes", use `Literal` instead.

package/skills/dignified-python/references/checklists.md

@@ -0,0 +1,134 @@
+---
+description: All decision checklists consolidated for final review before committing Python changes.
+---
+
+# Decision Checklists Reference
+
+**Read when**: Final review before committing Python code, need quick lookup of requirements
+
+---
+
+## Before Writing `try/except`
+
+- [ ] Is this at an error boundary? (CLI/API level)
+- [ ] Can I check the condition proactively? (LBYL)
+- [ ] Am I adding meaningful context, or just hiding?
+- [ ] Is third-party API forcing me to use exceptions? (No LBYL check exists—not even format
+      validation)
+- [ ] Have I encapsulated the violation?
+- [ ] Am I catching specific exceptions, not broad?
+- [ ] If catching at error boundary, am I logging/warning? (Never silently swallow)
+
+**Default: Let exceptions bubble up**
+
+---
+
+## Before Path Operations
+
+- [ ] Did I check `.exists()` before `.resolve()`?
+- [ ] Did I check `.exists()` before `.is_relative_to()`?
+- [ ] Am I using `pathlib.Path`, not `os.path`?
+- [ ] Did I specify `encoding="utf-8"`?
+
+---
+
+## Before Using `typing.cast()`
+
+- [ ] Have I added a runtime assertion to verify the cast?
+- [ ] Is the assertion cost trivial (O(1))? If yes, always add it.
+- [ ] If skipping, is it because I just performed an isinstance check (redundant)?
+- [ ] If skipping for performance, have I documented the measured overhead?
+
+**Default: Always add runtime assertion before cast when cost is trivial**
+
+---
+
+## Before Defining an Interface (ABC or Protocol)
+
+- [ ] Do I own all implementations? -> Prefer ABC
+- [ ] Am I wrapping a third-party library? -> Prefer Protocol
+- [ ] Do I need runtime isinstance() validation? -> Use ABC
+- [ ] Is this a minimal interface (1-2 methods)? -> Protocol may be simpler
+- [ ] Do I need shared method implementations? -> Use ABC
+
+**Default for erk internal code: ABC. Default for external library facades: Protocol.**
+
+---
+
+## Before Preserving Backwards Compatibility
+
+- [ ] Did the user explicitly request it?
+- [ ] Is this a public API with external consumers?
+- [ ] Have I documented why it's needed?
+- [ ] Is migration cost prohibitively high?
+
+**Default: Break the API and migrate callsites immediately**
+
+---
+
+## Before Inline Imports
+
+- [ ] Is this to break a circular dependency?
+- [ ] Is this for TYPE_CHECKING?
+- [ ] Is this for conditional features?
+- [ ] If for startup time: Have I MEASURED the import cost?
+- [ ] If for startup time: Is the cost significant (>100ms)?
+- [ ] If for startup time: Have I documented the measured cost in a comment?
+- [ ] Have I documented why the inline import is needed?
+
+**Default: Module-level imports**
+
+---
+
+## Before Importing/Re-Exporting Symbols
+
+- [ ] Is there already a canonical location for this symbol?
+- [ ] Am I creating a second import path for the same symbol?
+- [ ] If this is a shim module, am I importing only what's needed for this module's purpose?
+- [ ] Have I avoided `__all__` exports?
+
+**Default: Import from canonical location, never re-export**
+
+---
+
+## Before Declaring a Local Variable
+
+- [ ] Is this variable used more than once?
+- [ ] Is this variable used close to where it's declared?
+- [ ] Would inlining the computation hurt readability?
+- [ ] Am I extracting object fields into locals that are only used once?
+
+**Default: Inline single-use computations at the call site; access object attributes directly**
+
+---
+
+## Before Adding a Default Parameter Value
+
+- [ ] Do 95%+ of callers actually want this default?
+- [ ] Would forgetting to pass this parameter cause a subtle bug?
+- [ ] Is there a safer design that makes the choice explicit?
+- [ ] If the default is never overridden anywhere, should this parameter exist at all?
+
+**Default: Require explicit values; eliminate unused defaults**
+
+---
+
+## Before Adding a Function with 5+ Parameters
+
+- [ ] Have I added `*` after the first (or ctx) parameter?
+- [ ] Is only `self`/`ctx` positional?
+- [ ] Is this an ABC/Protocol method? (exempt from rule)
+- [ ] If using ThreadPoolExecutor.submit(), am I using a lambda wrapper?
+
+**Default: All parameters after the first should be keyword-only**
+
+---
+
+## Before Writing Module-Level Code
+
+- [ ] Does this involve any computation (even `Path()` construction)?
+- [ ] Does this involve I/O (file, network, environment)?
+- [ ] Could this fail or raise exceptions?
+- [ ] Would tests need to mock this value?
+
+If any answer is "yes", wrap in a `@cache`-decorated function instead.