refactor: introduce Primitive protocol to type the generic discovery and display functions

The Named protocol only captured `name`, leaving _discover_and_filter_enabled
(engine.py) and _print_primitives_section (cli.py) completely untyped. Evolve
it to Primitive with both `name` and `enabled`, and add full type annotations
to these two key generic functions so the shared primitive pattern is explicit
and IDE-verifiable.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

src/ralphify/_discovery.py

@@ -16,20 +16,23 @@
 from ralphify._frontmatter import PRIMITIVES_DIR, parse_frontmatter
 
 
-class Named(Protocol):
-    """Protocol for objects with a ``name`` attribute.
+class Primitive(Protocol):
+    """Protocol for the shared interface of all primitive types.
 
     All primitive dataclasses (:class:`~ralphify.checks.Check`,
     :class:`~ralphify.contexts.Context`, :class:`~ralphify.instructions.Instruction`,
     :class:`~ralphify.ralphs.Ralph`) satisfy this protocol, enabling type-safe
-    merging in :func:`merge_by_name`.
+    discovery, filtering, merging, and display.
     """
 
     @property
     def name(self) -> str: ...
 
+    @property
+    def enabled(self) -> bool: ...
+
 
-_N = TypeVar("_N", bound=Named)
+_P = TypeVar("_P", bound=Primitive)
 
 
 class PrimitiveEntry(NamedTuple):
@@ -100,12 +103,12 @@ def discover_local_primitives(
     return _scan_dir(base_dir / kind, marker)
 
 
-def merge_by_name(global_list: list[_N], local_list: list[_N]) -> list[_N]:
+def merge_by_name(global_list: list[_P], local_list: list[_P]) -> list[_P]:
     """Merge global and prompt-local primitives; local wins on name conflict.
 
     Used by the engine to overlay prompt-scoped primitives on top of
-    global ones.  Both lists must contain objects with a ``.name`` attribute
-    (see :class:`Named`).  Results are sorted alphabetically by name.
+    global ones.  Both lists must contain objects satisfying the
+    :class:`Primitive` protocol.  Results are sorted alphabetically by name.
     """
     by_name = {p.name: p for p in global_list}
     for p in local_list:

src/ralphify/cli.py

@@ -9,13 +9,16 @@
 import sys
 import tomllib
 import uuid
+from collections.abc import Callable
 from pathlib import Path
+from typing import TypeVar
 
 import typer
 from rich.console import Console
 
 from ralphify import __version__
 from ralphify._console_emitter import ConsoleEmitter
+from ralphify._discovery import Primitive
 from ralphify._frontmatter import CHECK_MARKER, CONFIG_FILENAME, CONTEXT_MARKER, INSTRUCTION_MARKER, PRIMITIVES_DIR, RALPH_MARKER
 from ralphify.checks import discover_checks
 from ralphify.contexts import discover_contexts
@@ -77,7 +80,10 @@ def resolve_command(self, ctx, args):
 ]
 
 
-def _print_primitives_section(label: str, items: list, detail_fn) -> None:
+_P = TypeVar("_P", bound=Primitive)
+
+
+def _print_primitives_section(label: str, items: list[_P], detail_fn: Callable[[_P], str]) -> None:
     """Print a status section for discovered primitives."""
     if items:
         rprint(f"\n[bold]{label}:[/bold]  {len(items)} found")

src/ralphify/engine.py

@@ -17,9 +17,10 @@
 import traceback
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, NamedTuple
+from collections.abc import Callable as _Callable
+from typing import Any, NamedTuple, TypeVar
 from ralphify._agent import execute_agent
-from ralphify._discovery import merge_by_name
+from ralphify._discovery import Primitive, merge_by_name
 from ralphify._events import Event, EventEmitter, EventType, NullEmitter
 from ralphify._output import format_duration
 from ralphify._run_types import RunConfig, RunState, RunStatus
@@ -66,7 +67,15 @@ def _resolve_prompt_dir(config: RunConfig) -> Path | None:
     return None
 
 
-def _discover_and_filter_enabled(root, prompt_dir, discover, discover_local):
+_P = TypeVar("_P", bound=Primitive)
+
+
+def _discover_and_filter_enabled(
+    root: Path,
+    prompt_dir: Path | None,
+    discover: _Callable[[Path], list[_P]],
+    discover_local: _Callable[[Path], list[_P]],
+) -> list[_P]:
     """Discover primitives, merge local overrides (if any), and return only enabled ones.
 
     Encapsulates the three-step pattern shared by all primitive types: