teddy-cli 0.1.0__py3-none-any.whl

teddy_executor/core/services/parser_metadata.py

@@ -0,0 +1,153 @@
+from typing import Any, List, Optional
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mistletoe.block_token import (
+        List as MdList,
+        ListItem as MdListItem,
+    )
+    from mistletoe.span_token import Link
+
+from teddy_executor.core.services.parser_infrastructure import (
+    EXPECTED_KV_PARTS,
+    get_child_text,
+    normalize_path,
+    normalize_link_target,
+    find_node_in_tree,
+)
+
+
+def _process_link_key(
+    item: "MdListItem", text: str, key_map: dict[str, str]
+) -> Optional[tuple[str, str]]:
+    """Helper to process a single link-based metadata key."""
+    from mistletoe.span_token import Link
+
+    for key_text, param_key in key_map.items():
+        if f"{key_text}:" in text:
+            link_node = find_node_in_tree(item, Link)
+            if link_node:
+                target = normalize_link_target(link_node.target)
+                return param_key, normalize_path(target)
+            parts = text.split(f"{key_text}:", 1)
+            if len(parts) == EXPECTED_KV_PARTS and parts[1].strip():
+                return param_key, normalize_path(parts[1].strip())
+    return None
+
+
+def _process_text_key(text: str, key_map: dict[str, str]) -> Optional[tuple[str, str]]:
+    """Helper to process a single text-based metadata key."""
+    # Strip markdown bolding for resilient key matching
+    clean_text = text.replace("**", "")
+    for key_text, param_key in key_map.items():
+        if f"{key_text}:" in clean_text:
+            # Use clean text for finding the colon and splitting
+            parts = clean_text.split(":", 1)
+            return param_key, parts[1].strip()
+    return None
+
+
+def parse_plan_metadata(metadata_list_node: "MdList") -> dict[str, str]:
+    """Parses top-level plan metadata list."""
+    metadata = {}
+    list_children = getattr(metadata_list_node, "children", [])
+    for item in list_children if list_children is not None else []:
+        text = get_child_text(item).strip()
+        if ":" in text:
+            key, value = text.split(":", 1)
+            metadata[key.strip("* ")] = value.strip()
+    return metadata
+
+
+def parse_action_metadata(
+    metadata_list: "MdList",
+    link_key_map: Optional[dict[str, str]] = None,
+    text_key_map: Optional[dict[str, str]] = None,
+) -> tuple[Optional[str], dict[str, Any]]:
+    """Parses metadata from a Markdown list."""
+    from mistletoe.block_token import ListItem as MdListItem
+
+    params: dict[str, Any] = {}
+    description: Optional[str] = None
+    if not metadata_list.children:
+        return description, params
+
+    _link_key_map = link_key_map or {}
+    _text_key_map = text_key_map or {}
+
+    for item in metadata_list.children:
+        if not isinstance(item, MdListItem):
+            continue
+        text = get_child_text(item)
+
+        if "Description:" in text:
+            description = text.split(":", 1)[1].strip()
+            continue
+
+        link_result = _process_link_key(item, text, _link_key_map)
+        if link_result:
+            params[link_result[0]] = link_result[1]
+            continue
+
+        text_result = _process_text_key(text, _text_key_map)
+        if text_result:
+            params[text_result[0]] = text_result[1]
+
+    return description, params
+
+
+def parse_env_from_metadata(metadata_list: "MdList") -> Optional[dict[str, str]]:
+    """Parses environment variables from a nested metadata list."""
+    from mistletoe.block_token import List as MdList
+
+    if not metadata_list.children:
+        return None
+
+    env_dict: dict[str, str] = {}
+    for item in metadata_list.children:
+        if "env:" in get_child_text(item).strip():
+            env_list = find_node_in_tree(item, MdList)
+            if env_list and env_list.children:
+                for env_item in env_list.children:
+                    env_text = get_child_text(env_item).strip()
+                    if ":" in env_text:
+                        key, value = [p.strip() for p in env_text.split(":", 1)]
+                        env_dict[key] = value.strip('"')
+    return env_dict if env_dict else None
+
+
+def _find_all_links(node) -> "List[Link]":
+    """Recursively finds all Link tokens in a node tree."""
+    from mistletoe.span_token import Link
+
+    links = []
+    if isinstance(node, Link):
+        links.append(node)
+    if hasattr(node, "children") and node.children:
+        for child in node.children:
+            links.extend(_find_all_links(child))
+    return links
+
+
+def parse_handoff_resources_from_list(metadata_list: "MdList") -> "List[str] | None":
+    """
+    Parses handoff resources from a metadata list item.
+    Supports both nested lists and simple multi-line links within the item.
+    Recognizes both legacy "Handoff Resources:" and new "Reference Files:".
+    """
+    resources = []
+    if not (metadata_list and metadata_list.children):
+        return None
+
+    for item in metadata_list.children:
+        item_text = get_child_text(item).strip()
+        if item_text.startswith("Handoff Resources:") or item_text.startswith(
+            "Reference Files:"
+        ):
+            # Find all links within this list item's entire sub-tree
+            links = _find_all_links(item)
+            for link in links:
+                target = normalize_link_target(link.target)
+                resources.append(normalize_path(target))
+
+    return resources if resources else None

teddy_executor/core/services/parser_reporting.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+from typing import Any, List, TYPE_CHECKING
+from teddy_executor.core.domain.models.plan import Plan
+from teddy_executor.core.ports.inbound.plan_parser import InvalidPlanError
+from teddy_executor.core.services.parser_infrastructure import (
+    get_child_text,
+    H2_LEVEL,
+    H3_LEVEL,
+)
+
+if TYPE_CHECKING:
+    from mistletoe.block_token import Document
+from teddy_executor.core.utils.markdown import get_fence_for_content
+
+# Maximum length for AST node previews in error reports
+MAX_PREVIEW_LENGTH = 60
+
+
+def _get_node_preview(node: Any) -> str:
+    """Extracts a truncated first-line preview of a node's content."""
+    content = get_child_text(node).strip() if node else ""
+    first_line = content.splitlines()[0] if content else ""
+    if len(first_line) > MAX_PREVIEW_LENGTH:
+        return first_line[:MAX_PREVIEW_LENGTH].strip() + "..."
+    return first_line
+
+
+def _get_failure_cutoff_idx(
+    children: List[Any], mismatch_idx: int, offending_ids: set[int]
+) -> float:
+    """Determines the index after which nodes should be marked as unvalidated."""
+    failure_cutoff_idx = mismatch_idx if mismatch_idx != -1 else float("inf")
+    if offending_ids:
+        for i, node in enumerate(children):
+            if id(node) in offending_ids:
+                failure_cutoff_idx = min(failure_cutoff_idx, i)
+                break
+    return failure_cutoff_idx
+
+
+def _format_expected_structure() -> str:
+    """Returns the formatted 'Expected Document Structure' section."""
+    lines = [
+        "[000] Heading (Level 1)",
+        "[001] List (Metadata)",
+        "[002] Heading (Level 2: Rationale)",
+        "[003] Code Block (Rationale Content)",
+        "[004] Heading (Level 2: Action Plan) —or— Heading (Level 2: Message)",
+        "[005...] (If Action Plan) Heading (Level 3: Action Type) and (Action-specific AST nodes)",
+    ]
+    content = "\n".join(lines) + "\n"
+    fence = get_fence_for_content(content)
+    return f"### Expected Response Structure (MRP) \n{fence}text\n{content}{fence}\n"
+
+
+def format_node_name(node: Any) -> str:
+    """Formats the type name of a node with relevant metadata and content preview."""
+    from mistletoe.block_token import Heading, CodeFence, BlockCode
+
+    if node is None:
+        return "EOF"
+    name = type(node).__name__
+    if name in ("CodeFence", "BlockCode"):
+        name = "Code Block"
+
+    if isinstance(node, Heading):
+        name += f" (Level {node.level})"
+    elif isinstance(node, CodeFence):
+        delimiter = getattr(node, "delimiter", "```")
+        count = len(delimiter)
+        label = "tildes" if delimiter.startswith("~") else "backticks"
+        name += f" ({count} {label})"
+    elif isinstance(node, BlockCode):
+        name += " (indented)"
+
+    preview = _get_node_preview(node)
+    if preview:
+        name += f': "{preview}"'
+    return name
+
+
+def _render_ast_view(
+    doc: Document,
+    error_ids: set[int],
+    error_map: dict[int, str],
+    cutoff_idx: float = float("inf"),
+) -> str:
+    """
+    Core AST rendering logic with logical indentation. Returns raw text.
+    """
+    from mistletoe.block_token import Heading
+
+    indent_level = 0
+    lines = []
+
+    for i, node in enumerate(doc.children or []):
+        node_id = id(node)
+
+        # Logical children (indented siblings) of an action (H3)
+        if isinstance(node, Heading):
+            if node.level <= H2_LEVEL:
+                indent_level = 0
+            elif node.level == H3_LEVEL:
+                indent_level = 1
+
+        is_error = node_id in error_ids
+        is_unvalidated = i > cutoff_idx and not is_error
+
+        if is_error:
+            status = f"[✗] [{i:03d}]"
+        elif is_unvalidated:
+            status = f"[ ] [{i:03d}]"
+        else:
+            status = f"[✓] [{i:03d}]"
+
+        # Truncate error message for AST trace to keep it clean
+        raw_reason = error_map.get(node_id, "")
+        concise_reason = raw_reason.splitlines()[0] if raw_reason else ""
+        reason = f" (Error: {concise_reason})" if is_error else ""
+
+        # Heading 1-3 are never indented. Their contents/sub-headings are.
+        is_top_heading = isinstance(node, Heading) and node.level <= H3_LEVEL
+        display_indent = "  " * (0 if is_top_heading else indent_level)
+        n_name = format_node_name(node)
+        lines.append(f"{display_indent}{status} {n_name}{reason}")
+
+    return "\n".join(lines) + "\n"
+
+
+def format_hybrid_ast_view(
+    doc: Document,
+    errors: List[Any],  # List[ValidationError]
+) -> str:
+    """
+    Generates a hybrid AST visualization: surgical highlighting and logical indentation.
+    """
+    error_ids = {id(e.offending_node) for e in errors if e.offending_node}
+    error_map = {id(e.offending_node): e.message for e in errors if e.offending_node}
+    ast_text = _render_ast_view(doc, error_ids, error_map)
+
+    fence = get_fence_for_content(ast_text)
+    return f"### Plan AST with Highlighted Failures\n{fence}text\n{ast_text}{fence}\n"
+
+
+def get_action_type_from_node(plan: Plan, offending_node: Any) -> str:
+    """Walks back from a node to find its parent action type."""
+    from mistletoe.block_token import Heading
+
+    if not offending_node:
+        return "Unknown"
+
+    if not plan.source_doc:
+        return get_child_text(offending_node).strip().replace("`", "")
+
+    nodes = list(plan.source_doc.children or [])
+    target_idx = -1
+    for i, node in enumerate(nodes):
+        if id(node) == id(offending_node):
+            target_idx = i
+            break
+
+    if target_idx != -1:
+        for i in range(target_idx, -1, -1):
+            if isinstance(nodes[i], Heading) and nodes[i].level == H3_LEVEL:
+                return get_child_text(nodes[i]).strip().replace("`", "")
+
+    return get_child_text(offending_node).strip().replace("`", "")
+
+
+def validate_plan_structure(doc: Document, start_idx: int):
+    """Validates the structural schema of the top-level nodes."""
+    from mistletoe.block_token import (
+        BlockCode,
+        CodeFence,
+        Heading,
+        List as MdList,
+    )
+
+    doc_children = doc.children if doc.children is not None else []
+    children = list(doc_children)
+    expected_schema = [
+        (
+            "a List (Metadata) immediately following the title",
+            lambda n: isinstance(n, MdList),
+        ),
+        (
+            "a Level 2 Heading containing 'Rationale'",
+            lambda n: (
+                isinstance(n, Heading)
+                and n.level == H2_LEVEL
+                and "Rationale" in get_child_text(n)
+            ),
+        ),
+        (
+            "a CodeFence or BlockCode containing the rationale content",
+            lambda n: isinstance(n, (CodeFence, BlockCode)),
+        ),
+        (
+            "a Level 2 Heading containing 'Action Plan' or 'Message'",
+            lambda n: (
+                isinstance(n, Heading)
+                and n.level == H2_LEVEL
+                and any(
+                    term in get_child_text(n) for term in ["Action Plan", "Message"]
+                )
+            ),
+        ),
+    ]
+
+    offending_nodes = []
+    primary_mismatch = None
+
+    for i, (expected_desc, predicate) in enumerate(expected_schema):
+        target_idx = start_idx + 1 + i
+        actual_node = children[target_idx] if target_idx < len(children) else None
+
+        if not actual_node or not predicate(actual_node):
+            offending_nodes.append(actual_node)
+            if primary_mismatch is None:
+                primary_mismatch = (expected_desc, target_idx, actual_node)
+
+    if offending_nodes and primary_mismatch is not None:
+        expected_desc, target_idx, actual_node = primary_mismatch
+        error_msg = format_structural_mismatch_msg(
+            doc, expected_desc, target_idx, offending_nodes
+        )
+        raise InvalidPlanError(error_msg, offending_nodes=offending_nodes)
+
+
+def format_structural_mismatch_msg(
+    doc: Document,
+    expected: str,
+    mismatch_idx: int,
+    offending_nodes: List[Any],
+) -> str:
+    """Constructs a detailed structural validation error message."""
+    primary_node = offending_nodes[0] if offending_nodes else None
+    actual_name = format_node_name(primary_node)
+
+    is_direct = expected.startswith(("a ", "an ", "## ", "### ", "Heading", "List"))
+    error_header = f"Expected {expected}" if is_direct else expected
+
+    # If mismatch_idx is -1, this is a content error, not a structural schema mismatch
+    if mismatch_idx == -1:
+        msg = f"Plan content is invalid: {expected}.\n\n"
+    else:
+        msg = f"Plan structure is invalid. {error_header}, but found {actual_name}.\n\n"
+
+    msg += _format_expected_structure()
+    msg += "\n### Actual Response Structure\n"
+
+    children = list(doc.children) if doc.children else []
+    offending_ids = {id(node) for node in offending_nodes if node is not None}
+    error_map = {id_node: error_header for id_node in offending_ids}
+    if mismatch_idx != -1 and mismatch_idx < len(children):
+        error_ids_set = offending_ids | {id(children[mismatch_idx])}
+        error_map[id(children[mismatch_idx])] = error_header
+    else:
+        error_ids_set = offending_ids
+
+    cutoff = _get_failure_cutoff_idx(children, mismatch_idx, offending_ids)
+    ast_text = _render_ast_view(doc, error_ids_set, error_map, cutoff)
+    fence = get_fence_for_content(ast_text)
+    msg += f"{fence}text\n{ast_text}{fence}\n"
+
+    msg += "\n**Hint:** Parsing often fails due to improper Code Block Formatting.\n"
+    return msg

teddy_executor/core/services/plan_validator.py

@@ -0,0 +1,82 @@
+"""
+This module contains the implementation of the PlanValidator service.
+"""
+
+from typing import Dict, List, Optional, Sequence
+
+from teddy_executor.core.domain.models.plan import Plan
+from teddy_executor.core.ports.inbound.plan_validator import IPlanValidator
+from teddy_executor.core.services.validation_rules.helpers import (
+    IActionValidator,
+    ValidationError,
+)
+
+
+from teddy_executor.core.ports.outbound import IFileSystemManager
+
+
+class PlanValidator(IPlanValidator):
+    """
+    Implements IPlanValidator using a strategy pattern to run pre-flight checks.
+    """
+
+    def __init__(
+        self,
+        file_system_manager: IFileSystemManager,
+        validators: Optional[List[IActionValidator]] = None,
+    ):
+        self._file_system_manager = file_system_manager
+        self._validators = validators or []
+
+    def validate(
+        self, plan: Plan, context_paths: Optional[Dict[str, Sequence[str]]] = None
+    ) -> List[ValidationError]:
+        """
+        Validates a plan by dispatching each action to a specific validation method.
+
+        Returns:
+            A list of validation error objects. An empty list signifies success.
+        """
+        errors: List[ValidationError] = []
+        for action in plan.actions:
+            action_type_lower = action.type.lower()
+            action_errors: Optional[List[ValidationError]] = None
+
+            # Dispatch to injected action-specific validators
+            handled_by_injected = False
+            for validator in self._validators:
+                if validator.can_validate(action_type_lower):
+                    action_errors = validator.validate(
+                        action, context_paths=context_paths
+                    )
+                    handled_by_injected = True
+                    break
+
+            if handled_by_injected:
+                if action_errors:
+                    errors.extend(action_errors)
+            elif action_type_lower in [
+                "research",
+                "prompt",
+                "invoke",
+                "return",
+            ]:
+                # These actions have no validation rules currently
+                pass
+            elif action_type_lower == "message":
+                # MESSAGE under ## Action Plan is invalid; mutual exclusivity required
+                errors.append(
+                    ValidationError(
+                        message="MESSAGE action is not allowed under '## Action Plan'. "
+                        "Use '## Message' section instead. Mutual exclusivity is required.",
+                        file_path=None,
+                    )
+                )
+            else:
+                errors.append(
+                    ValidationError(
+                        message=f"Unknown action type: {action.type}",
+                        file_path=action.params.get("path"),
+                    )
+                )
+        return errors