refactor: decompose parse_frontmatter into focused helpers to flatten nesting

Extract _extract_frontmatter_block (delimiter scanning) and _parse_kv_lines
(key-value parsing) from parse_frontmatter, reducing max nesting from 7 to 3
levels. Type coercion is now data-driven via _FIELD_COERCIONS dict — adding
a new typed field is a one-line dict entry instead of an elif branch.

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

Author: 2 people

CLAUDE.md

@@ -41,7 +41,7 @@ Tests are in `tests/` with one file per module. Docs are in `docs/` using MkDocs
 ## Traps
 
 - Primitive marker filenames (`CHECK.md`, `CONTEXT.md`, `INSTRUCTION.md`, `PROMPT.md`) are defined as constants in `_frontmatter.py` (`CHECK_MARKER`, `CONTEXT_MARKER`, etc.). All modules import from there — change the constant to rename everywhere.
-- `timeout` and `enabled` frontmatter fields have special type coercion in `_frontmatter.py:parse_frontmatter()`. New typed fields need coercion logic added there.
+- `timeout` and `enabled` frontmatter fields have special type coercion via `_FIELD_COERCIONS` in `_frontmatter.py`. To add a new typed field, add an entry to that dict.
 - Both contexts and instructions share `resolver.py:resolve_placeholders()`. Changes affect both.
 - Output is truncated to 5000 chars in `_output.py`. This is intentional.
 - Commands in frontmatter run via `shlex.split()` — no shell features (pipes, redirections, `&&`). Scripts (`run.*`) are the escape hatch.

src/ralphify/_frontmatter.py

@@ -21,6 +21,49 @@
 PROMPT_MARKER = "PROMPT.md"
 
 
+# Type coercion for known frontmatter fields.
+# To add a new typed field, add an entry here — no other changes needed.
+_FIELD_COERCIONS: dict[str, object] = {
+    "timeout": int,
+    "enabled": lambda v: v.lower() in ("true", "yes", "1"),
+}
+
+
+def _parse_kv_lines(lines: list[str]) -> dict:
+    """Parse flat ``key: value`` lines with type coercion for known fields."""
+    result: dict = {}
+    for line in lines:
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        key = key.strip()
+        value = value.strip()
+        coerce = _FIELD_COERCIONS.get(key)
+        result[key] = coerce(value) if coerce else value
+    return result
+
+
+def _extract_frontmatter_block(text: str) -> tuple[list[str], str]:
+    """Split text into frontmatter lines and body at ``---`` delimiters.
+
+    Returns ``([], text)`` when no valid frontmatter block is found.
+    """
+    lines = text.split("\n")
+    start = None
+    for i, line in enumerate(lines):
+        if line.strip() == "---":
+            if start is None:
+                start = i
+            else:
+                fm_lines = lines[start + 1 : i]
+                body = "\n".join(lines[i + 1 :]).strip()
+                return fm_lines, body
+    return [], text
+
+
 def parse_frontmatter(text: str) -> tuple[dict, str]:
     """Parse a markdown file with optional YAML-like frontmatter.
 
@@ -31,39 +74,11 @@ def parse_frontmatter(text: str) -> tuple[dict, str]:
 
     Returns ``(frontmatter_dict, body_text)``.
     """
-    frontmatter: dict = {}
-    body = text
-
-    stripped = text.strip()
-    if stripped.startswith("---"):
-        lines = text.split("\n")
-        # Find the opening ---
-        start = None
-        for i, line in enumerate(lines):
-            if line.strip() == "---":
-                if start is None:
-                    start = i
-                else:
-                    # Found closing ---
-                    fm_lines = lines[start + 1 : i]
-                    body = "\n".join(lines[i + 1 :]).strip()
-                    for fm_line in fm_lines:
-                        fm_line = fm_line.strip()
-                        if not fm_line or fm_line.startswith("#"):
-                            continue
-                        if ":" not in fm_line:
-                            continue
-                        key, _, value = fm_line.partition(":")
-                        key = key.strip()
-                        value = value.strip()
-                        # Type coercion
-                        if key == "timeout":
-                            frontmatter[key] = int(value)
-                        elif key == "enabled":
-                            frontmatter[key] = value.lower() in ("true", "yes", "1")
-                        else:
-                            frontmatter[key] = value
-                    break
+    if text.strip().startswith("---"):
+        fm_lines, body = _extract_frontmatter_block(text)
+        frontmatter = _parse_kv_lines(fm_lines)
+    else:
+        frontmatter, body = {}, text
 
     body = re.sub(r"<!--.*?-->", "", body, flags=re.DOTALL).strip()
     return frontmatter, body