elspais 0.11.2__py3-none-any.whl → 0.43.5__py3-none-any.whl

elspais/graph/parsers/heredocs.py

@@ -0,0 +1,225 @@
+"""Heredocs parser for embedded requirement definitions.
+
+This parser recognizes embedded requirement definitions in test files
+(Python triple-quoted strings, shell heredocs) and claims them as
+plain-text blocks, preventing the requirement parser from treating
+them as real requirements.
+
+If the text needs to be parsed later, it can be sent to the deserializer
+as that can process arbitrary blocks of text.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Iterator
+
+from elspais.graph.parsers import ParsedContent
+
+if TYPE_CHECKING:
+    from elspais.graph.parsers import ParseContext
+
+
+def _get_file_type(file_path: str) -> str:
+    """Determine file type from path.
+
+    Args:
+        file_path: Path to the file.
+
+    Returns:
+        File type: 'python', 'shell', or 'other'.
+    """
+    suffix = Path(file_path).suffix.lower()
+    name = Path(file_path).name.lower()
+
+    if suffix == ".py":
+        return "python"
+    elif suffix in (".sh", ".bash", ".zsh", ".ksh"):
+        return "shell"
+    elif name.endswith(".sh") or name.endswith(".bash"):
+        return "shell"
+    else:
+        return "other"
+
+
+class HeredocsParser:
+    """Parser for heredoc/multiline string blocks containing requirement patterns.
+
+    Priority: 10 (runs before requirement parser at 50)
+
+    Claims Python triple-quoted strings and shell heredocs that contain
+    REQ-xxx patterns, marking them as heredoc content type.
+    """
+
+    # Priority 10 - runs early to claim heredocs before requirement parser
+    priority: int = 10
+
+    # Pattern to detect requirement IDs
+    REQ_PATTERN = re.compile(r"REQ[-_][A-Za-z]?\d+", re.IGNORECASE)
+
+    # Python triple-quote start patterns
+    PYTHON_HEREDOC_START = re.compile(
+        r"^[a-zA-Z_][a-zA-Z0-9_]*\s*=\s*[fFrRbBuU]?"  # var = [prefix]
+        r'("""|\'\'\')',  # triple quote
+        re.MULTILINE,
+    )
+
+    # Shell heredoc start pattern: << 'EOF' or << "EOF" or << EOF
+    SHELL_HEREDOC_START = re.compile(
+        r"<<\s*['\"]?([A-Za-z_][A-Za-z0-9_]*)['\"]?",
+        re.MULTILINE,
+    )
+
+    def claim_and_parse(
+        self,
+        lines: list[tuple[int, str]],
+        context: ParseContext,
+    ) -> Iterator[ParsedContent]:
+        """Claim heredoc blocks containing requirement patterns.
+
+        Args:
+            lines: List of (line_number, content) tuples.
+            context: Parse context with file information.
+
+        Yields:
+            ParsedContent for each claimed heredoc block.
+        """
+        file_type = _get_file_type(context.file_path)
+
+        if file_type == "python":
+            yield from self._parse_python_heredocs(lines, context)
+        elif file_type == "shell":
+            yield from self._parse_shell_heredocs(lines, context)
+        # Skip markdown, spec files, etc.
+
+    def _parse_python_heredocs(
+        self,
+        lines: list[tuple[int, str]],
+        context: ParseContext,
+    ) -> Iterator[ParsedContent]:
+        """Parse Python triple-quoted strings containing REQ patterns.
+
+        Args:
+            lines: List of (line_number, content) tuples.
+            context: Parse context.
+
+        Yields:
+            ParsedContent for each heredoc block.
+        """
+        i = 0
+        while i < len(lines):
+            line_num, content = lines[i]
+
+            # Check for triple-quote start
+            match = self.PYTHON_HEREDOC_START.match(content)
+            if match:
+                quote_char = match.group(1)  # """ or '''
+
+                # Find the end of the heredoc
+                heredoc_lines = [content]
+                end_idx = i
+
+                # Check if it's a one-liner
+                rest = content[match.end() :]
+                if quote_char in rest:
+                    # Single line heredoc - check for REQ pattern
+                    if self.REQ_PATTERN.search(content):
+                        yield ParsedContent(
+                            content_type="heredoc",
+                            start_line=line_num,
+                            end_line=line_num,
+                            raw_text=content,
+                            parsed_data={"quote_style": quote_char},
+                        )
+                    i += 1
+                    continue
+
+                # Multi-line heredoc
+                for j in range(i + 1, len(lines)):
+                    end_line_num, end_content = lines[j]
+                    heredoc_lines.append(end_content)
+                    if quote_char in end_content:
+                        end_idx = j
+                        break
+                else:
+                    # No closing quote found - skip
+                    i += 1
+                    continue
+
+                # Check if heredoc contains REQ pattern
+                full_text = "\n".join(heredoc_lines)
+                if self.REQ_PATTERN.search(full_text):
+                    yield ParsedContent(
+                        content_type="heredoc",
+                        start_line=line_num,
+                        end_line=lines[end_idx][0],
+                        raw_text=full_text,
+                        parsed_data={"quote_style": quote_char},
+                    )
+                    i = end_idx + 1
+                    continue
+
+            i += 1
+
+    def _parse_shell_heredocs(
+        self,
+        lines: list[tuple[int, str]],
+        context: ParseContext,
+    ) -> Iterator[ParsedContent]:
+        """Parse shell-style heredocs containing REQ patterns.
+
+        Args:
+            lines: List of (line_number, content) tuples.
+            context: Parse context.
+
+        Yields:
+            ParsedContent for each heredoc block.
+        """
+        i = 0
+        while i < len(lines):
+            line_num, content = lines[i]
+
+            # Check for shell heredoc start
+            match = self.SHELL_HEREDOC_START.search(content)
+            if match:
+                delimiter = match.group(1)  # e.g., EOF, END
+
+                # Find the end delimiter
+                heredoc_lines = [content]
+                end_idx = i
+
+                for j in range(i + 1, len(lines)):
+                    end_line_num, end_content = lines[j]
+                    heredoc_lines.append(end_content)
+                    if end_content.strip() == delimiter:
+                        end_idx = j
+                        break
+                else:
+                    # No closing delimiter found - skip
+                    i += 1
+                    continue
+
+                # Check if heredoc contains REQ pattern
+                full_text = "\n".join(heredoc_lines)
+                if self.REQ_PATTERN.search(full_text):
+                    yield ParsedContent(
+                        content_type="heredoc",
+                        start_line=line_num,
+                        end_line=lines[end_idx][0],
+                        raw_text=full_text,
+                        parsed_data={"delimiter": delimiter},
+                    )
+                    i = end_idx + 1
+                    continue
+
+            i += 1
+
+
+def create_parser() -> HeredocsParser:
+    """Factory function to create a HeredocsParser.
+
+    Returns:
+        New HeredocsParser instance.
+    """
+    return HeredocsParser()

elspais/graph/parsers/journey.py

@@ -0,0 +1,131 @@
+"""JourneyParser - Priority 60 parser for user journey blocks.
+
+Parses user journey specifications from markdown.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Iterator
+
+from elspais.graph.parsers import ParseContext, ParsedContent
+
+
+class JourneyParser:
+    """Parser for user journey blocks.
+
+    Priority: 60 (after requirements)
+
+    Parses user journeys in format:
+    - Header: ## JNY-xxx-NN: Title
+    - Actor/Goal fields
+    - Steps section
+    - End marker
+    """
+
+    priority = 60
+
+    # Journey ID pattern: JNY-{Descriptor}-{number}
+    HEADER_PATTERN = re.compile(r"^#*\s*(?P<id>JNY-[A-Za-z0-9-]+):\s*(?P<title>.+)$")
+    ACTOR_PATTERN = re.compile(r"\*\*Actor\*\*:\s*(?P<actor>.+?)(?:\n|$)")
+    GOAL_PATTERN = re.compile(r"\*\*Goal\*\*:\s*(?P<goal>.+?)(?:\n|$)")
+    END_MARKER_PATTERN = re.compile(r"^\*End\*\s+\*JNY-[^*]+\*", re.MULTILINE)
+
+    def claim_and_parse(
+        self,
+        lines: list[tuple[int, str]],
+        context: ParseContext,
+    ) -> Iterator[ParsedContent]:
+        """Claim and parse user journey blocks.
+
+        Args:
+            lines: List of (line_number, content) tuples.
+            context: Parsing context.
+
+        Yields:
+            ParsedContent for each journey block.
+        """
+        line_map = dict(lines)
+        line_numbers = sorted(line_map.keys())
+
+        if not line_numbers:
+            return
+
+        claimed: set[int] = set()
+        i = 0
+
+        while i < len(line_numbers):
+            ln = line_numbers[i]
+            if ln in claimed:
+                i += 1
+                continue
+
+            text = line_map[ln]
+
+            header_match = self.HEADER_PATTERN.match(text)
+            if header_match:
+                journey_id = header_match.group("id")
+                title = header_match.group("title").strip()
+                start_line = ln
+
+                # Find end of journey
+                journey_lines = [(ln, text)]
+                end_line = ln
+                j = i + 1
+
+                while j < len(line_numbers):
+                    next_ln = line_numbers[j]
+                    next_text = line_map[next_ln]
+                    journey_lines.append((next_ln, next_text))
+                    end_line = next_ln
+
+                    if self.END_MARKER_PATTERN.match(next_text):
+                        j += 1
+                        break
+
+                    # Next journey header
+                    if self.HEADER_PATTERN.match(next_text):
+                        journey_lines.pop()
+                        end_line = line_numbers[j - 1] if j > i + 1 else ln
+                        break
+
+                    j += 1
+
+                # Claim lines
+                for claim_ln, _ in journey_lines:
+                    claimed.add(claim_ln)
+
+                raw_text = "\n".join(t for _, t in journey_lines)
+                parsed_data = self._parse_journey(journey_id, title, raw_text)
+
+                yield ParsedContent(
+                    content_type="journey",
+                    start_line=start_line,
+                    end_line=end_line,
+                    raw_text=raw_text,
+                    parsed_data=parsed_data,
+                )
+
+                while i < len(line_numbers) and line_numbers[i] in claimed:
+                    i += 1
+            else:
+                i += 1
+
+    def _parse_journey(self, journey_id: str, title: str, text: str) -> dict[str, Any]:
+        """Parse journey fields from text block."""
+        data: dict[str, Any] = {
+            "id": journey_id,
+            "title": title,
+            "actor": None,
+            "goal": None,
+        }
+
+        actor_match = self.ACTOR_PATTERN.search(text)
+        if actor_match:
+            data["actor"] = actor_match.group("actor").strip()
+
+        goal_match = self.GOAL_PATTERN.search(text)
+        if goal_match:
+            data["goal"] = goal_match.group("goal").strip()
+
+        return data

elspais/graph/parsers/remainder.py

@@ -0,0 +1,79 @@
+"""RemainderParser - Priority 999 catch-all parser.
+
+Claims all remaining unclaimed lines after all other parsers have run.
+Groups contiguous lines into remainder blocks.
+"""
+
+from __future__ import annotations
+
+from typing import Iterator
+
+from elspais.graph.parsers import ParseContext, ParsedContent
+
+
+class RemainderParser:
+    """Parser for unclaimed remainder content.
+
+    Priority: 999 (lowest priority, runs last)
+
+    Claims all remaining lines that no other parser claimed, grouping
+    contiguous lines into blocks. This ensures every line in the file
+    is assigned to exactly one ParsedContent.
+    """
+
+    priority = 999
+
+    def claim_and_parse(
+        self,
+        lines: list[tuple[int, str]],
+        context: ParseContext,
+    ) -> Iterator[ParsedContent]:
+        """Claim all remaining lines as remainder blocks.
+
+        Groups contiguous lines (no gaps in line numbers) into single
+        remainder blocks.
+
+        Args:
+            lines: List of (line_number, content) tuples.
+            context: Parsing context.
+
+        Yields:
+            ParsedContent for each contiguous remainder block.
+        """
+        if not lines:
+            return
+
+        # Sort by line number
+        sorted_lines = sorted(lines, key=lambda x: x[0])
+
+        # Group contiguous lines
+        groups: list[list[tuple[int, str]]] = []
+        current_group: list[tuple[int, str]] = []
+
+        for ln, text in sorted_lines:
+            if not current_group:
+                current_group.append((ln, text))
+            elif ln == current_group[-1][0] + 1:
+                # Contiguous
+                current_group.append((ln, text))
+            else:
+                # Gap - start new group
+                groups.append(current_group)
+                current_group = [(ln, text)]
+
+        if current_group:
+            groups.append(current_group)
+
+        # Yield each group as a remainder block
+        for group in groups:
+            start_line = group[0][0]
+            end_line = group[-1][0]
+            raw_text = "\n".join(text for _, text in group)
+
+            yield ParsedContent(
+                content_type="remainder",
+                start_line=start_line,
+                end_line=end_line,
+                raw_text=raw_text,
+                parsed_data={},
+            )