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

elspais/graph/mutations.py

@@ -0,0 +1,161 @@
+"""Mutation types for TraceGraph operations.
+
+This module provides dataclasses for tracking graph mutations,
+broken references, and other graph state changes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Iterator
+from uuid import uuid4
+
+
+@dataclass(frozen=True)
+class BrokenReference:
+    """A reference to a non-existent target node.
+
+    Captured during graph build when a link cannot be resolved.
+
+    Attributes:
+        source_id: ID of the node containing the reference.
+        target_id: ID that was referenced but doesn't exist.
+        edge_kind: Type of relationship ("implements", "refines", "validates").
+    """
+
+    source_id: str
+    target_id: str
+    edge_kind: str
+
+    def __str__(self) -> str:
+        """Human-readable representation."""
+        return f"{self.source_id} --[{self.edge_kind}]--> {self.target_id} (missing)"
+
+
+@dataclass
+class MutationEntry:
+    """Single mutation operation record.
+
+    Records a mutation for auditing and undo support. The before_state
+    contains enough information to reverse the operation.
+
+    Attributes:
+        id: Unique mutation ID (UUID4).
+        timestamp: When the mutation occurred.
+        operation: Operation type (e.g., "rename_node", "add_edge").
+        target_id: Primary target of the mutation.
+        before_state: State before mutation (for undo).
+        after_state: State after mutation.
+        affects_hash: Whether this mutation affects content hash.
+    """
+
+    operation: str
+    target_id: str
+    before_state: dict[str, Any]
+    after_state: dict[str, Any]
+    affects_hash: bool = False
+    id: str = field(default_factory=lambda: uuid4().hex)
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    def __str__(self) -> str:
+        """Human-readable representation."""
+        return f"[{self.id[:8]}] {self.operation}({self.target_id})"
+
+
+class MutationLog:
+    """Append-only mutation history.
+
+    Provides auditing and undo capabilities for graph mutations.
+    Entries are stored in chronological order.
+
+    Example:
+        >>> log = MutationLog()
+        >>> entry = MutationEntry(
+        ...     operation="rename_node",
+        ...     target_id="REQ-p00001",
+        ...     before_state={"id": "REQ-p00001"},
+        ...     after_state={"id": "REQ-p00002"},
+        ... )
+        >>> log.append(entry)
+        >>> list(log.iter_entries())
+        [MutationEntry(...)]
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty mutation log."""
+        self._entries: list[MutationEntry] = []
+
+    def append(self, entry: MutationEntry) -> None:
+        """Append a mutation entry to the log.
+
+        Args:
+            entry: The mutation record to append.
+        """
+        self._entries.append(entry)
+
+    def iter_entries(self) -> Iterator[MutationEntry]:
+        """Iterate over all entries in chronological order.
+
+        Yields:
+            MutationEntry instances in order of occurrence.
+        """
+        yield from self._entries
+
+    def __len__(self) -> int:
+        """Return the number of entries in the log."""
+        return len(self._entries)
+
+    def last(self) -> MutationEntry | None:
+        """Return the most recent entry, or None if empty."""
+        return self._entries[-1] if self._entries else None
+
+    def find_by_id(self, mutation_id: str) -> MutationEntry | None:
+        """Find an entry by its mutation ID.
+
+        Args:
+            mutation_id: The UUID of the mutation to find.
+
+        Returns:
+            The matching MutationEntry, or None if not found.
+        """
+        for entry in self._entries:
+            if entry.id == mutation_id:
+                return entry
+        return None
+
+    def entries_since(self, mutation_id: str) -> list[MutationEntry]:
+        """Get all entries since (and including) a specific mutation.
+
+        Useful for batch undo operations.
+
+        Args:
+            mutation_id: The UUID to start from.
+
+        Returns:
+            List of entries from the specified mutation to the most recent.
+
+        Raises:
+            ValueError: If the mutation_id is not found.
+        """
+        for i, entry in enumerate(self._entries):
+            if entry.id == mutation_id:
+                return list(self._entries[i:])
+        raise ValueError(f"Mutation {mutation_id} not found in log")
+
+    def pop(self) -> MutationEntry | None:
+        """Remove and return the most recent entry.
+
+        Used internally for undo operations. Does not log the removal.
+
+        Returns:
+            The removed entry, or None if log is empty.
+        """
+        return self._entries.pop() if self._entries else None
+
+    def clear(self) -> None:
+        """Clear all entries from the log."""
+        self._entries.clear()
+
+
+__all__ = ["BrokenReference", "MutationEntry", "MutationLog"]

elspais/graph/parsers/__init__.py

@@ -0,0 +1,156 @@
+"""MDparser - Line-claiming parser system.
+
+This module provides the infrastructure for parsing markdown spec files
+using a priority-based line-claiming system. Parsers are registered with
+priorities, and lines are claimed in priority order.
+
+Exports:
+- LineClaimingParser: Protocol for parser implementations
+- ParseContext: Context passed to parsers
+- ParsedContent: Result of parsing a claimed region
+- ParserRegistry: Manages parser registration and orchestration
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterator, Protocol, runtime_checkable
+
+
+@dataclass
+class ParseContext:
+    """Context passed to parsers during parsing.
+
+    Attributes:
+        file_path: Path to the file being parsed (relative to repo root).
+        config: Configuration dictionary for pattern matching, etc.
+    """
+
+    file_path: str
+    config: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ParsedContent:
+    """Result of parsing a claimed region.
+
+    Represents a contiguous block of lines claimed by a parser,
+    with the parsed content and metadata.
+
+    Attributes:
+        content_type: Type of content (e.g., "requirement", "comment").
+        start_line: First line number (1-indexed).
+        end_line: Last line number (1-indexed, inclusive).
+        raw_text: Original text of the claimed lines.
+        parsed_data: Structured data extracted by the parser.
+    """
+
+    content_type: str
+    start_line: int
+    end_line: int
+    raw_text: str
+    parsed_data: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def line_count(self) -> int:
+        """Number of lines in this content block."""
+        return self.end_line - self.start_line + 1
+
+
+@runtime_checkable
+class LineClaimingParser(Protocol):
+    """Protocol for line-claiming parsers.
+
+    Parsers claim lines in priority order (lower = earlier). Each parser
+    receives only the unclaimed lines and yields ParsedContent for any
+    lines it claims.
+    """
+
+    @property
+    def priority(self) -> int:
+        """Priority for this parser (lower = earlier)."""
+        ...
+
+    def claim_and_parse(
+        self,
+        lines: list[tuple[int, str]],
+        context: ParseContext,
+    ) -> Iterator[ParsedContent]:
+        """Claim and parse lines.
+
+        Args:
+            lines: List of (line_number, content) tuples for unclaimed lines.
+            context: Parsing context with file info and config.
+
+        Yields:
+            ParsedContent for each claimed region.
+        """
+        ...
+
+
+class ParserRegistry:
+    """Registry for managing line-claiming parsers.
+
+    Parsers are registered and then called in priority order during parsing.
+    Each parser only sees lines not yet claimed by earlier parsers.
+    """
+
+    def __init__(self) -> None:
+        self.parsers: list[LineClaimingParser] = []
+
+    def register(self, parser: LineClaimingParser) -> None:
+        """Register a parser.
+
+        Args:
+            parser: A parser implementing LineClaimingParser protocol.
+        """
+        self.parsers.append(parser)
+
+    def get_ordered(self) -> list[LineClaimingParser]:
+        """Get parsers sorted by priority (ascending).
+
+        Returns:
+            List of parsers in priority order.
+        """
+        return sorted(self.parsers, key=lambda p: p.priority)
+
+    def parse_all(
+        self,
+        lines: list[tuple[int, str]],
+        context: ParseContext,
+    ) -> Iterator[ParsedContent]:
+        """Parse lines using all registered parsers in priority order.
+
+        Each parser receives only the lines not claimed by earlier parsers.
+
+        Args:
+            lines: List of (line_number, content) tuples.
+            context: Parsing context.
+
+        Yields:
+            ParsedContent from all parsers.
+        """
+        # Track which line numbers have been claimed
+        claimed_lines: set[int] = set()
+
+        for parser in self.get_ordered():
+            # Filter to only unclaimed lines
+            unclaimed = [(ln, text) for ln, text in lines if ln not in claimed_lines]
+
+            if not unclaimed:
+                break
+
+            # Let parser claim and parse
+            for content in parser.claim_and_parse(unclaimed, context):
+                # Mark lines as claimed
+                for ln in range(content.start_line, content.end_line + 1):
+                    claimed_lines.add(ln)
+                yield content
+
+
+__all__ = [
+    "LineClaimingParser",
+    "ParseContext",
+    "ParsedContent",
+    "ParserRegistry",
+]

elspais/graph/parsers/code.py

@@ -0,0 +1,213 @@
+"""CodeParser - Priority 70 parser for code references.
+
+Parses code comments containing requirement references.
+Uses the shared reference_config infrastructure for configurable patterns.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Iterator
+
+from elspais.graph.parsers import ParseContext, ParsedContent
+from elspais.graph.parsers.config_helpers import is_empty_comment
+from elspais.utilities.reference_config import (
+    ReferenceConfig,
+    ReferenceResolver,
+    build_block_header_pattern,
+    build_block_ref_pattern,
+    build_comment_pattern,
+)
+
+if TYPE_CHECKING:
+    from elspais.utilities.patterns import PatternConfig
+
+
+class CodeParser:
+    """Parser for code reference comments.
+
+    Priority: 70 (after requirements and journeys)
+
+    Recognizes comments like:
+    - # Implements: REQ-xxx
+    - # Validates: REQ-xxx
+    - // Implements: REQ-xxx (for JS/TS)
+    - // IMPLEMENTS REQUIREMENTS: (multiline block header)
+    - //   REQ-xxx: Description (multiline block item)
+
+    Uses configurable patterns from ReferenceConfig for:
+    - Comment styles (# // -- etc.)
+    - Keywords (Implements, Validates, Tests, etc.)
+    - Separator characters (- _ etc.)
+    """
+
+    priority = 70
+
+    def __init__(
+        self,
+        pattern_config: PatternConfig | None = None,
+        reference_resolver: ReferenceResolver | None = None,
+    ) -> None:
+        """Initialize CodeParser with optional configuration.
+
+        Args:
+            pattern_config: Configuration for ID structure. If None, uses defaults.
+            reference_resolver: Resolver for file-specific reference config. If None,
+                               uses default ReferenceConfig.
+        """
+        self._pattern_config = pattern_config
+        self._reference_resolver = reference_resolver
+
+    def _get_pattern_config(self, context: ParseContext) -> PatternConfig:
+        """Get pattern config from context or instance.
+
+        Args:
+            context: Parse context that may contain pattern config.
+
+        Returns:
+            PatternConfig to use for parsing.
+        """
+        # Try instance config first
+        if self._pattern_config is not None:
+            return self._pattern_config
+
+        # Try context config
+        if "pattern_config" in context.config:
+            return context.config["pattern_config"]
+
+        # Fall back to creating a default
+        from elspais.utilities.patterns import PatternConfig
+
+        return PatternConfig.from_dict(
+            {
+                "prefix": "REQ",
+                "types": {
+                    "prd": {"id": "p", "name": "PRD"},
+                    "ops": {"id": "o", "name": "OPS"},
+                    "dev": {"id": "d", "name": "DEV"},
+                },
+                "id_format": {"style": "numeric", "digits": 5},
+            }
+        )
+
+    def _get_reference_config(
+        self, context: ParseContext, pattern_config: PatternConfig
+    ) -> ReferenceConfig:
+        """Get reference config for the current file.
+
+        Args:
+            context: Parse context with file path.
+            pattern_config: Pattern config (unused but available for consistency).
+
+        Returns:
+            ReferenceConfig for this file.
+        """
+        if self._reference_resolver is not None:
+            file_path = Path(context.file_path)
+            repo_root = Path(context.config.get("repo_root", "."))
+            return self._reference_resolver.resolve(file_path, repo_root)
+
+        # Try context config
+        if "reference_resolver" in context.config:
+            resolver: ReferenceResolver = context.config["reference_resolver"]
+            file_path = Path(context.file_path)
+            repo_root = Path(context.config.get("repo_root", "."))
+            return resolver.resolve(file_path, repo_root)
+
+        # Fall back to default config
+        return ReferenceConfig()
+
+    def claim_and_parse(
+        self,
+        lines: list[tuple[int, str]],
+        context: ParseContext,
+    ) -> Iterator[ParsedContent]:
+        """Claim and parse code reference comments.
+
+        Args:
+            lines: List of (line_number, content) tuples.
+            context: Parsing context.
+
+        Yields:
+            ParsedContent for each code reference.
+        """
+        # Get configs for this file
+        pattern_config = self._get_pattern_config(context)
+        ref_config = self._get_reference_config(context, pattern_config)
+
+        # Build patterns dynamically based on config
+        implements_pattern = build_comment_pattern(pattern_config, ref_config, "implements")
+        validates_pattern = build_comment_pattern(pattern_config, ref_config, "validates")
+        block_header_pattern = build_block_header_pattern(ref_config, "implements")
+        block_ref_pattern = build_block_ref_pattern(pattern_config, ref_config)
+
+        i = 0
+        while i < len(lines):
+            ln, text = lines[i]
+
+            # Check for single-line patterns first
+            impl_match = implements_pattern.search(text)
+            val_match = validates_pattern.search(text)
+
+            if impl_match or val_match:
+                parsed_data: dict[str, Any] = {
+                    "implements": [],
+                    "validates": [],
+                }
+
+                if impl_match:
+                    refs = [r.strip() for r in impl_match.group("refs").split(",")]
+                    parsed_data["implements"] = refs
+
+                if val_match:
+                    refs = [r.strip() for r in val_match.group("refs").split(",")]
+                    parsed_data["validates"] = refs
+
+                yield ParsedContent(
+                    content_type="code_ref",
+                    start_line=ln,
+                    end_line=ln,
+                    raw_text=text,
+                    parsed_data=parsed_data,
+                )
+                i += 1
+                continue
+
+            # Check for multiline block header: // IMPLEMENTS REQUIREMENTS:
+            if block_header_pattern.search(text):
+                refs: list[str] = []
+                start_ln = ln
+                end_ln = ln
+                raw_lines = [text]
+                i += 1
+
+                # Collect REQ references from subsequent comment lines
+                while i < len(lines):
+                    next_ln, next_text = lines[i]
+                    ref_match = block_ref_pattern.match(next_text)
+                    if ref_match:
+                        refs.append(ref_match.group("ref"))
+                        end_ln = next_ln
+                        raw_lines.append(next_text)
+                        i += 1
+                    elif is_empty_comment(next_text, ref_config.comment_styles):
+                        # Empty comment line, skip
+                        i += 1
+                    else:
+                        # Non-comment line or different content, stop
+                        break
+
+                if refs:
+                    yield ParsedContent(
+                        content_type="code_ref",
+                        start_line=start_ln,
+                        end_line=end_ln,
+                        raw_text="\n".join(raw_lines),
+                        parsed_data={
+                            "implements": refs,
+                            "validates": [],
+                        },
+                    )
+                continue
+
+            i += 1

elspais/graph/parsers/comments.py

@@ -0,0 +1,112 @@
+"""CommentsParser - Priority 0 parser for HTML comment blocks.
+
+Claims HTML comments (single-line and multi-line) before any other parser
+can process them. This prevents comment content from being interpreted
+as requirements or other content types.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterator
+
+from elspais.graph.parsers import ParseContext, ParsedContent
+
+
+class CommentsParser:
+    """Parser for HTML comment blocks.
+
+    Priority: 0 (highest priority, runs first)
+
+    Handles:
+    - Single-line comments: <!-- comment -->
+    - Multi-line comments: <!-- ... -->
+    """
+
+    priority = 0
+
+    # Pattern for single-line comment
+    SINGLE_LINE_PATTERN = re.compile(r"<!--.*-->")
+
+    # Pattern for comment start
+    COMMENT_START = re.compile(r"<!--")
+
+    # Pattern for comment end
+    COMMENT_END = re.compile(r"-->")
+
+    def claim_and_parse(
+        self,
+        lines: list[tuple[int, str]],
+        context: ParseContext,
+    ) -> Iterator[ParsedContent]:
+        """Claim and parse HTML comment blocks.
+
+        Args:
+            lines: List of (line_number, content) tuples.
+            context: Parsing context.
+
+        Yields:
+            ParsedContent for each comment block.
+        """
+        # Build a dict for quick line lookup
+        line_map = dict(lines)
+        line_numbers = sorted(line_map.keys())
+
+        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]
+
+            # Check for single-line comment
+            if self.SINGLE_LINE_PATTERN.search(text):
+                claimed.add(ln)
+                yield ParsedContent(
+                    content_type="comment",
+                    start_line=ln,
+                    end_line=ln,
+                    raw_text=text,
+                    parsed_data={"comment_type": "single_line"},
+                )
+                i += 1
+                continue
+
+            # Check for multi-line comment start
+            if self.COMMENT_START.search(text) and not self.COMMENT_END.search(text):
+                # Find the closing -->
+                start_ln = ln
+                end_ln = None
+                collected_lines = [text]
+
+                for j in range(i + 1, len(line_numbers)):
+                    next_ln = line_numbers[j]
+                    # Only consider contiguous lines
+                    if next_ln != line_numbers[j - 1] + 1:
+                        # Gap in line numbers, can't be same comment
+                        break
+                    next_text = line_map[next_ln]
+                    collected_lines.append(next_text)
+                    if self.COMMENT_END.search(next_text):
+                        end_ln = next_ln
+                        break
+
+                if end_ln is not None:
+                    # Found closing, claim all lines
+                    for claim_ln in range(start_ln, end_ln + 1):
+                        if claim_ln in line_map:
+                            claimed.add(claim_ln)
+
+                    yield ParsedContent(
+                        content_type="comment",
+                        start_line=start_ln,
+                        end_line=end_ln,
+                        raw_text="\n".join(collected_lines),
+                        parsed_data={"comment_type": "multi_line"},
+                    )
+
+            i += 1

elspais/graph/parsers/config_helpers.py

@@ -0,0 +1,29 @@
+"""Shared helper functions for parsers."""
+
+from __future__ import annotations
+
+
+def is_empty_comment(text: str, comment_styles: list[str]) -> bool:
+    """Check if a line is an empty comment.
+
+    An empty comment is a line that starts with a comment marker but has
+    no meaningful content after it. This includes decorative comment lines
+    like "# ----" or "// ======".
+
+    Args:
+        text: Line text to check.
+        comment_styles: List of comment style markers (e.g., ["#", "//"]).
+
+    Returns:
+        True if line is an empty comment.
+    """
+    stripped = text.strip()
+    for style in comment_styles:
+        if stripped.startswith(style):
+            # Remove the comment marker and check if remainder is empty
+            remainder = stripped[len(style) :].strip()
+            # Also handle trailing comment markers (for decorative comments)
+            remainder = remainder.rstrip("#/-").strip()
+            if not remainder:
+                return True
+    return False