devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/story/markdown_contracts.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import re
+import uuid
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .discovery import get_story_source_paths
+
+ALLOWED_PLANES = ["auth", "api", "ui", "integrations", "ops"]
+
+MANDATORY_CONTRACT_FORMATION_MODE_LINE = (
+    "CONTRACT FORMATION MODE: implementation is irrelevant; do not compare against current code/UI. "
+    "Define user-expected outcomes and test oracles only."
+)
+
+
+@dataclass(frozen=True)
+class PlaneOracle:
+    plane: str
+    oracle: str
+    anchor: str
+
+
+@dataclass(frozen=True)
+class StoryContract:
+    story_uuid: str
+    story_id: str
+    title: str
+    required_planes: list[str]
+    contract_formation_mode_line_present: bool
+    plane_oracles: list[PlaneOracle]
+    raw_text: str
+    source_path: str
+
+
+@dataclass(frozen=True)
+class ParsedStoryBlock:
+    """A story contract plus the approximate line where it started (for diagnostics)."""
+
+    contract: StoryContract
+    start_line: int
+
+
+_KEY_RE = re.compile(r"^(story_uuid|story_id|title|required_planes)\s*:\s*(.+?)\s*$")
+
+
+def _parse_required_planes(value: str) -> list[str]:
+    # Accept either bracket-list syntax: [auth, api] or comma-separated: auth, api
+    v = value.strip()
+    inner = v[1:-1].strip() if v.startswith("[") and v.endswith("]") else v
+    if not inner:
+        return []
+    parts = [p.strip().strip("\"'") for p in inner.split(",")]
+    return [p for p in parts if p]
+
+
+def _parse_plane_oracles(lines: list[str], *, start_index: int) -> tuple[list[PlaneOracle], int]:
+    # Parses a canonical list block:
+    # plane_oracles:
+    # - plane: auth
+    #   oracle: "..."
+    #   anchor: "..."
+    i = start_index
+    if i >= len(lines) or lines[i].strip() != "plane_oracles:":
+        return ([], start_index)
+    i += 1
+
+    oracles: list[PlaneOracle] = []
+    current: dict[str, str] = {}
+
+    def flush() -> None:
+        nonlocal current
+        if not current:
+            return
+        plane = current.get("plane", "").strip()
+        oracle = current.get("oracle", "").strip()
+        anchor = current.get("anchor", "").strip()
+        oracles.append(PlaneOracle(plane=plane, oracle=oracle, anchor=anchor))
+        current = {}
+
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.strip()
+        if stripped == "":
+            i += 1
+            continue
+
+        # stop if we hit the start of another story header
+        if stripped.startswith("story_uuid:"):
+            break
+
+        if stripped.startswith("-"):
+            flush()
+            # allow "- plane: auth" or "-plane: auth" (we'll normalize)
+            rest = stripped[1:].strip()
+            if rest and ":" in rest:
+                k, v = rest.split(":", 1)
+                current[k.strip()] = v.strip().strip("\"'")
+            i += 1
+            continue
+
+        if ":" in stripped:
+            k, v = stripped.split(":", 1)
+            k = k.strip()
+            v = v.strip().strip("\"'")
+            if k in {"plane", "oracle", "anchor"}:
+                current[k] = v
+            i += 1
+            continue
+
+        # Any other non-empty line ends the list block.
+        break
+
+    flush()
+    return (oracles, i)
+
+
+def parse_story_contracts_from_markdown(text: str, *, source_path: str) -> list[ParsedStoryBlock]:
+    lines = text.splitlines()
+
+    # Heuristic boundary: each story starts at a line that begins with story_uuid:
+    blocks: list[tuple[int, int]] = []
+    starts: list[int] = [idx for idx, line in enumerate(lines) if line.strip().startswith("story_uuid:")]
+    if not starts:
+        return []
+
+    for si, start in enumerate(starts):
+        end = starts[si + 1] if si + 1 < len(starts) else len(lines)
+        blocks.append((start, end))
+
+    parsed: list[ParsedStoryBlock] = []
+    for start, end in blocks:
+        block_lines = lines[start:end]
+        fields: dict[str, str] = {}
+        contract_mode_present = False
+
+        # First pass: parse key fields anywhere in the block (header generally near top).
+        for bl in block_lines:
+            if bl.strip() == MANDATORY_CONTRACT_FORMATION_MODE_LINE:
+                contract_mode_present = True
+            m = _KEY_RE.match(bl.strip())
+            if m:
+                fields[m.group(1)] = m.group(2).strip().strip("\"'")
+
+        required_planes = _parse_required_planes(fields.get("required_planes", ""))
+
+        # Parse plane_oracles list block (find first occurrence)
+        po: list[PlaneOracle] = []
+        for idx, bl in enumerate(block_lines):
+            if bl.strip() == "plane_oracles:":
+                po, _ = _parse_plane_oracles(block_lines, start_index=idx)
+                break
+
+        c = StoryContract(
+            story_uuid=fields.get("story_uuid", ""),
+            story_id=fields.get("story_id", ""),
+            title=fields.get("title", ""),
+            required_planes=required_planes,
+            contract_formation_mode_line_present=contract_mode_present,
+            plane_oracles=po,
+            raw_text="\n".join(block_lines).strip() + "\n",
+            source_path=source_path,
+        )
+        parsed.append(ParsedStoryBlock(contract=c, start_line=start + 1))
+
+    return parsed
+
+
+def iter_canonical_story_paths(repo_root: Path) -> Iterable[Path]:
+    yield from get_story_source_paths(repo_root)
+
+
+def _as_list(value: Any) -> list[str]:
+    if isinstance(value, str):
+        text = value.strip()
+        return [text] if text else []
+    if not isinstance(value, list):
+        return []
+    items: list[str] = []
+    for item in value:
+        text = str(item).strip()
+        if text:
+            items.append(text)
+    return items
+
+
+def _append_block(lines: list[str], heading: str, body_lines: list[str]) -> None:
+    lines.append(heading)
+    lines.extend(body_lines if body_lines else ["- TODO"])
+    lines.append("")
+
+
+def render_canonical_story_markdown(story: dict[str, Any]) -> str:
+    story_uuid = str(story.get("story_uuid") or "").strip()
+    story_id = str(story.get("story_id") or "").strip()
+    title = str(story.get("title") or story_id or "Untitled story").strip()
+    required_planes = _as_list(story.get("required_planes"))
+    contract_mode = str(story.get("contract_formation_mode") or MANDATORY_CONTRACT_FORMATION_MODE_LINE).strip()
+
+    evidence_anchors = _as_list(story.get("evidence_anchors"))
+    scope_items = _as_list(story.get("scope"))
+    if not scope_items:
+        if required_planes:
+            scope_items.append(f"Required planes: {', '.join(required_planes)}.")
+        primary_actor = story.get("primary_actor")
+        if isinstance(primary_actor, dict):
+            actor_label = str(primary_actor.get("label") or primary_actor.get("id") or "").strip()
+            if actor_label:
+                scope_items.append(f"Primary actor: {actor_label}.")
+        if evidence_anchors:
+            scope_items.extend(f"Evidence anchor: {anchor}" for anchor in evidence_anchors)
+        source_analysis_id = str(story.get("source_analysis_id") or "").strip()
+        if source_analysis_id:
+            scope_items.append(f"Source analysis id: {source_analysis_id}.")
+    out_of_scope = _as_list(story.get("out_of_scope") or story.get("non_goals")) or [
+        "Do not infer unsupported implementation details beyond the reconciled live story JSON."
+    ]
+
+    plane_oracles = []
+    for item in story.get("plane_oracles") or []:
+        if not isinstance(item, dict):
+            continue
+        plane = str(item.get("plane") or "").strip()
+        if not plane:
+            continue
+        plane_oracles.append(
+            {
+                "plane": plane,
+                "oracle": str(item.get("oracle") or f"{title}: user-observable outcome stays satisfied for the {plane} plane.").strip(),
+                "anchor": str(item.get("anchor") or (evidence_anchors[0] if evidence_anchors else f"story:{story_id}:{plane}")).strip(),
+            }
+        )
+    if not plane_oracles:
+        for plane in required_planes:
+            plane_oracles.append(
+                {
+                    "plane": plane,
+                    "oracle": f"{title}: user-observable outcome stays satisfied for the {plane} plane.",
+                    "anchor": evidence_anchors[0] if evidence_anchors else f"story:{story_id}:{plane}",
+                }
+            )
+
+    acceptance_criteria = _as_list(story.get("acceptance_criteria")) or [
+        f"{title}: satisfy the documented outcome across {', '.join(required_planes) if required_planes else 'the required'} plane coverage."
+    ]
+    contract_specs = _as_list(story.get("contract_test_spec"))
+    if not contract_specs:
+        contract_specs = [f"Given the story contract for {story_id or title}"]
+        for criterion in acceptance_criteria:
+            contract_specs.append(f"Then {criterion}")
+
+    intent_lines = [str(story.get("intent") or story.get("story_statement") or title).strip()]
+    user_value_text = str(story.get("user_value_statement") or story.get("user_value") or "").strip()
+    user_value_lines = user_value_text.splitlines() if user_value_text else ["User value is carried by the reconciled live story JSON."]
+
+    lines: list[str] = [
+        f"story_uuid: {story_uuid}",
+        f"story_id: {story_id}",
+        f"title: {title}",
+        f"required_planes: [{', '.join(required_planes)}]",
+        "",
+        contract_mode,
+        "",
+    ]
+    _append_block(lines, "## Intent", intent_lines)
+    _append_block(lines, "## User value", user_value_lines)
+    _append_block(lines, "## Scope", [f"- {item}" for item in scope_items])
+    _append_block(lines, "## Out of scope", [f"- {item}" for item in out_of_scope])
+
+    lines.append("plane_oracles:")
+    for oracle in plane_oracles:
+        lines.append(f"- plane: {oracle['plane']}")
+        lines.append(f"  oracle: \"{oracle['oracle']}\"")
+        lines.append(f"  anchor: \"{oracle['anchor']}\"")
+        lines.append("")
+
+    _append_block(
+        lines,
+        "## Acceptance criteria",
+        [f"{index}. {item}" for index, item in enumerate(acceptance_criteria, start=1)],
+    )
+    _append_block(
+        lines,
+        "## Contract test specs",
+        [f"{index}. {item}" for index, item in enumerate(contract_specs, start=1)],
+    )
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def is_uuid4(value: str) -> bool:
+    try:
+        u = uuid.UUID(value)
+    except Exception:
+        return False
+    return u.version == 4