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

elspais/{core → utilities}/hasher.py

@@ -1,7 +1,7 @@
-"""
-elspais.core.hasher - Hash calculation for requirement change detection.
+"""Hasher - Hash calculation for requirement change detection.
 
 Provides functions for calculating and verifying SHA-256 based content hashes.
+Ported from core/hasher.py.
 """
 
 import hashlib
@@ -10,20 +10,17 @@ from typing import Optional
 
 
 def clean_requirement_body(content: str, normalize_whitespace: bool = False) -> str:
-    """
-    Clean requirement body text for consistent hashing.
+    """Clean requirement body text for consistent hashing.
 
     Args:
         content: Raw requirement body text
         normalize_whitespace: If True, aggressively normalize whitespace.
-                             If False (default), only remove trailing blank lines
-                             (matches hht-diary tools behavior).
+                             If False (default), only remove trailing blank lines.
 
     Returns:
         Cleaned text suitable for hashing
     """
     if normalize_whitespace:
-        # Aggressive normalization mode
         lines = content.split("\n")
 
         # Remove leading blank lines
@@ -49,13 +46,10 @@ def clean_requirement_body(content: str, normalize_whitespace: bool = False) ->
 
         return "\n".join(result_lines)
     else:
-        # Default: hht-diary compatible mode (only remove trailing blank lines)
+        # Default: only remove trailing blank lines
         lines = content.split("\n")
-
-        # Remove trailing blank lines (matches hht-diary behavior)
         while lines and not lines[-1].strip():
             lines.pop()
-
         return "\n".join(lines)
 
 
@@ -65,23 +59,19 @@ def calculate_hash(
     algorithm: str = "sha256",
     normalize_whitespace: bool = False,
 ) -> str:
-    """
-    Calculate a content hash for change detection.
+    """Calculate a content hash for change detection.
 
     Args:
         content: Text content to hash
         length: Number of characters in the hash (default 8)
         algorithm: Hash algorithm to use (default "sha256")
         normalize_whitespace: If True, aggressively normalize whitespace.
-                             If False (default), only remove trailing blank lines.
 
     Returns:
         Hexadecimal hash string of specified length
     """
-    # Clean the content first
     cleaned = clean_requirement_body(content, normalize_whitespace=normalize_whitespace)
 
-    # Calculate hash
     if algorithm == "sha256":
         hash_obj = hashlib.sha256(cleaned.encode("utf-8"))
     elif algorithm == "sha1":
@@ -91,7 +81,6 @@ def calculate_hash(
     else:
         raise ValueError(f"Unsupported hash algorithm: {algorithm}")
 
-    # Return first `length` characters of hex digest
     return hash_obj.hexdigest()[:length]
 
 
@@ -102,8 +91,7 @@ def verify_hash(
     algorithm: str = "sha256",
     normalize_whitespace: bool = False,
 ) -> bool:
-    """
-    Verify that content matches an expected hash.
+    """Verify that content matches an expected hash.
 
     Args:
         content: Text content to verify
@@ -111,7 +99,6 @@ def verify_hash(
         length: Hash length used (default 8)
         algorithm: Hash algorithm used (default "sha256")
         normalize_whitespace: If True, aggressively normalize whitespace.
-                             If False (default), only remove trailing blank lines.
 
     Returns:
         True if hash matches, False otherwise
@@ -126,8 +113,7 @@ def verify_hash(
 
 
 def extract_hash_from_footer(footer_text: str) -> Optional[str]:
-    """
-    Extract hash value from requirement footer line.
+    """Extract hash value from requirement footer line.
 
     Looks for pattern: **Hash**: XXXXXXXX
 

elspais/utilities/md_renderer.py

@@ -0,0 +1,189 @@
+"""Markdown-to-ANSI renderer for terminal documentation display.
+
+Renders markdown files with ANSI color codes for terminal display.
+Supports headings, code blocks, bold text, inline code, and command hints.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+
+class MarkdownRenderer:
+    """Renders markdown content to ANSI-colored terminal output."""
+
+    # ANSI escape codes
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    CYAN = "\033[36m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    RESET = "\033[0m"
+
+    def __init__(self, use_color: bool = True) -> None:
+        """Initialize renderer with color settings.
+
+        Args:
+            use_color: Whether to emit ANSI color codes.
+        """
+        self.use_color = use_color
+
+    def _c(self, code: str) -> str:
+        """Return ANSI code if colors enabled, else empty string."""
+        return code if self.use_color else ""
+
+    def render(self, markdown: str) -> str:
+        """Render markdown content to ANSI-colored output.
+
+        Args:
+            markdown: Raw markdown text.
+
+        Returns:
+            Formatted text with ANSI codes (if colors enabled).
+        """
+        lines = markdown.split("\n")
+        output_lines: list[str] = []
+        in_code_block = False
+        code_lines: list[str] = []
+
+        for line in lines:
+            # Handle code block boundaries
+            if line.strip().startswith("```"):
+                if in_code_block:
+                    # End code block - emit collected lines
+                    output_lines.extend(self._render_code_block(code_lines))
+                    code_lines = []
+                    in_code_block = False
+                else:
+                    # Start code block
+                    in_code_block = True
+                continue
+
+            if in_code_block:
+                code_lines.append(line)
+                continue
+
+            # Process regular lines
+            output_lines.append(self._render_line(line))
+
+        # Handle unclosed code block
+        if code_lines:
+            output_lines.extend(self._render_code_block(code_lines))
+
+        return "\n".join(output_lines)
+
+    def _render_code_block(self, lines: list[str]) -> list[str]:
+        """Render a fenced code block with dim formatting."""
+        result = []
+        for line in lines:
+            # Indent code blocks by 2 spaces and dim them
+            result.append(f"  {self._c(self.DIM)}{line}{self._c(self.RESET)}")
+        return result
+
+    def _render_line(self, line: str) -> str:
+        """Render a single line of markdown."""
+        stripped = line.strip()
+
+        # Level 1 heading: # Title -> boxed heading
+        if stripped.startswith("# ") and not stripped.startswith("## "):
+            title = stripped[2:].strip()
+            return self._render_heading(title)
+
+        # Level 2 heading: ## Subheading -> green with underline
+        if stripped.startswith("## "):
+            title = stripped[3:].strip()
+            return self._render_subheading(title)
+
+        # Level 3+ headings: just bold
+        if stripped.startswith("### "):
+            title = stripped[4:].strip()
+            return f"\n{self._c(self.BOLD)}{title}{self._c(self.RESET)}\n"
+
+        # Regular line - apply inline formatting
+        return self._render_inline(line)
+
+    def _render_heading(self, title: str) -> str:
+        """Render a level-1 heading with box borders."""
+        border = "═" * 60
+        return (
+            f"\n{self._c(self.BOLD)}{self._c(self.CYAN)}{border}{self._c(self.RESET)}\n"
+            f"{self._c(self.BOLD)}{title}{self._c(self.RESET)}\n"
+            f"{self._c(self.BOLD)}{self._c(self.CYAN)}{border}{self._c(self.RESET)}\n"
+        )
+
+    def _render_subheading(self, title: str) -> str:
+        """Render a level-2 heading with underline."""
+        underline = "─" * 40
+        return (
+            f"\n{self._c(self.BOLD)}{self._c(self.GREEN)}{title}{self._c(self.RESET)}\n"
+            f"{self._c(self.DIM)}{underline}{self._c(self.RESET)}\n"
+        )
+
+    def _render_inline(self, text: str) -> str:
+        """Apply inline markdown formatting to text.
+
+        Handles:
+        - **bold** -> BOLD
+        - `code` -> CYAN
+        - $ command -> GREEN $ prefix with dim comment
+        """
+        result = text
+
+        # Handle command lines: "$ command  # comment"
+        # Match lines that have "$ " near the start (possibly indented)
+        cmd_match = re.match(r"^(\s*)(\$)\s+(.*)$", result)
+        if cmd_match:
+            indent, dollar, rest = cmd_match.groups()
+            # Split command from comment
+            if "  #" in rest or "\t#" in rest:
+                # Find the comment part
+                comment_match = re.search(r"(\s{2,}#.*)$", rest)
+                if comment_match:
+                    comment = comment_match.group(1)
+                    cmd_part = rest[: comment_match.start()]
+                    result = (
+                        f"{indent}{self._c(self.GREEN)}{dollar}{self._c(self.RESET)} "
+                        f"{cmd_part}{self._c(self.DIM)}{comment}{self._c(self.RESET)}"
+                    )
+                else:
+                    result = f"{indent}{self._c(self.GREEN)}{dollar}{self._c(self.RESET)} {rest}"
+            else:
+                result = f"{indent}{self._c(self.GREEN)}{dollar}{self._c(self.RESET)} {rest}"
+            return result
+
+        # Bold: **text** -> BOLD text RESET
+        result = re.sub(
+            r"\*\*([^*]+)\*\*",
+            lambda m: f"{self._c(self.BOLD)}{m.group(1)}{self._c(self.RESET)}",
+            result,
+        )
+
+        # Inline code: `text` -> CYAN text RESET
+        result = re.sub(
+            r"`([^`]+)`",
+            lambda m: f"{self._c(self.CYAN)}{m.group(1)}{self._c(self.RESET)}",
+            result,
+        )
+
+        return result
+
+
+def render_markdown(markdown: str, use_color: bool | None = None) -> str:
+    """Convenience function to render markdown to ANSI.
+
+    Args:
+        markdown: Raw markdown text.
+        use_color: Whether to use ANSI colors. If None, auto-detect TTY.
+
+    Returns:
+        Formatted text suitable for terminal output.
+    """
+    if use_color is None:
+        use_color = sys.stdout.isatty()
+    renderer = MarkdownRenderer(use_color=use_color)
+    return renderer.render(markdown)

elspais/{core → utilities}/patterns.py

@@ -1,24 +1,34 @@
-"""
-elspais.core.patterns - Configurable requirement ID pattern matching.
+"""Patterns - Configurable requirement ID pattern matching.
 
 Supports multiple ID formats:
 - HHT style: REQ-p00001, REQ-CAL-d00001
 - Type-prefix style: PRD-00001, OPS-00001, DEV-00001
 - Jira style: PROJ-123
 - Named: REQ-UserAuth
+
+Ported from core/patterns.py.
 """
 
 import re
 from dataclasses import dataclass
 from typing import Any, Dict, List, Optional
 
-from elspais.core.models import ParsedRequirement
+
+@dataclass
+class ParsedRequirement:
+    """Result of parsing a requirement ID string."""
+
+    full_id: str
+    prefix: str
+    associated: Optional[str]
+    type_code: str
+    number: str
+    assertion: Optional[str] = None
 
 
 @dataclass
 class PatternConfig:
-    """
-    Configuration for requirement ID patterns.
+    """Configuration for requirement ID patterns.
 
     Attributes:
         id_template: Template string with tokens {prefix}, {associated}, {type}, {id}
@@ -89,7 +99,6 @@ class PatternConfig:
         if max_count is not None:
             return int(max_count)
 
-        # Default max based on style
         if style == "uppercase":
             return 26
         elif style == "numeric":
@@ -102,13 +111,10 @@ class PatternConfig:
 
 
 class PatternValidator:
-    """
-    Validates and parses requirement IDs against configured patterns.
-    """
+    """Validates and parses requirement IDs against configured patterns."""
 
     def __init__(self, config: PatternConfig):
-        """
-        Initialize pattern validator.
+        """Initialize pattern validator.
 
         Args:
             config: Pattern configuration
@@ -116,16 +122,10 @@ class PatternValidator:
         self.config = config
         self._regex = self._build_regex()
         self._regex_with_assertion = self._build_regex(include_assertion=True)
-        self._assertion_label_regex = re.compile(
-            f"^{self.config.get_assertion_label_pattern()}$"
-        )
+        self._assertion_label_regex = re.compile(f"^{self.config.get_assertion_label_pattern()}$")
 
     def _build_regex(self, include_assertion: bool = False) -> re.Pattern:
-        """Build regex pattern from configuration.
-
-        Args:
-            include_assertion: If True, include optional assertion suffix pattern
-        """
+        """Build regex pattern from configuration."""
         template = self.config.id_template
 
         # Build type alternatives
@@ -167,11 +167,9 @@ class PatternValidator:
             associated_pattern = "(?P<associated>)"
 
         # Build full regex from template
-        # Replace tokens with regex groups
         pattern = template
         pattern = pattern.replace("{prefix}", f"(?P<prefix>{re.escape(self.config.prefix)})")
 
-        # Handle associated - it's optional
         if "{associated}" in pattern:
             pattern = pattern.replace("{associated}", f"(?:{associated_pattern})?")
         else:
@@ -184,7 +182,6 @@ class PatternValidator:
 
         pattern = pattern.replace("{id}", f"(?P<id>{id_pattern})")
 
-        # Optionally add assertion suffix pattern
         if include_assertion:
             assertion_pattern = self.config.get_assertion_label_pattern()
             pattern = f"{pattern}(?:-(?P<assertion>{assertion_pattern}))?"
@@ -192,11 +189,10 @@ class PatternValidator:
         return re.compile(f"^{pattern}$")
 
     def parse(self, id_string: str, allow_assertion: bool = False) -> Optional[ParsedRequirement]:
-        """
-        Parse a requirement ID string into components.
+        """Parse a requirement ID string into components.
 
         Args:
-            id_string: The requirement ID to parse (e.g., "REQ-p00001" or "REQ-p00001-A")
+            id_string: The requirement ID to parse
             allow_assertion: If True, allow and parse assertion suffix
 
         Returns:
@@ -218,8 +214,7 @@ class PatternValidator:
         )
 
     def is_valid(self, id_string: str, allow_assertion: bool = False) -> bool:
-        """
-        Check if an ID string is valid.
+        """Check if an ID string is valid.
 
         Args:
             id_string: The requirement ID to validate
@@ -231,11 +226,10 @@ class PatternValidator:
         return self.parse(id_string, allow_assertion=allow_assertion) is not None
 
     def is_valid_assertion_label(self, label: str) -> bool:
-        """
-        Check if an assertion label is valid.
+        """Check if an assertion label is valid.
 
         Args:
-            label: The assertion label to validate (e.g., "A", "01")
+            label: The assertion label to validate
 
         Returns:
             True if valid, False otherwise
@@ -243,8 +237,7 @@ class PatternValidator:
         return self._assertion_label_regex.match(label) is not None
 
     def format_assertion_label(self, index: int) -> str:
-        """
-        Format an assertion label from a zero-based index.
+        """Format an assertion label from a zero-based index.
 
         Args:
             index: Zero-based index (0 = A or 00, 1 = B or 01, etc.)
@@ -279,11 +272,10 @@ class PatternValidator:
             return chr(ord("A") + index)
 
     def parse_assertion_label_index(self, label: str) -> int:
-        """
-        Parse an assertion label to get its zero-based index.
+        """Parse an assertion label to get its zero-based index.
 
         Args:
-            label: The assertion label (e.g., "A", "01", "B")
+            label: The assertion label
 
         Returns:
             Zero-based index
@@ -306,14 +298,11 @@ class PatternValidator:
 
         raise ValueError(f"Cannot parse assertion label: {label}")
 
-    def format(
-        self, type_code: str, number: int, associated: Optional[str] = None
-    ) -> str:
-        """
-        Format a requirement ID from components.
+    def format(self, type_code: str, number: int, associated: Optional[str] = None) -> str:
+        """Format a requirement ID from components.
 
         Args:
-            type_code: The requirement type code (e.g., "p")
+            type_code: The requirement type code
             number: The requirement number
             associated: Optional associated repo code
 
@@ -323,7 +312,6 @@ class PatternValidator:
         template = self.config.id_template
         id_format = self.config.id_format
 
-        # Format number
         style = id_format.get("style", "numeric")
         if style == "numeric":
             digits = int(id_format.get("digits", 5))
@@ -335,11 +323,9 @@ class PatternValidator:
         else:
             formatted_number = str(number)
 
-        # Build result
         result = template
         result = result.replace("{prefix}", self.config.prefix)
 
-        # Handle associated
         if associated and "{associated}" in result:
             associated_config = self.config.associated or {}
             sep = associated_config.get("separator", "-")
@@ -353,14 +339,7 @@ class PatternValidator:
         return result
 
     def extract_implements_ids(self, implements_str: str) -> List[str]:
-        """
-        Extract requirement IDs from an Implements field value.
-
-        Handles formats like:
-        - "p00001"
-        - "p00001, o00002"
-        - "REQ-p00001, REQ-o00002"
-        - "CAL-p00001"
+        """Extract requirement IDs from an Implements field value.
 
         Args:
             implements_str: The Implements field value
@@ -371,20 +350,42 @@ class PatternValidator:
         if not implements_str:
             return []
 
-        # Split by comma
         parts = [p.strip() for p in implements_str.split(",")]
         result = []
 
         for part in parts:
             if not part:
                 continue
-
-            # Check if it's a full ID
             if self.is_valid(part):
                 result.append(part)
             else:
-                # It might be a shortened ID like "p00001" or "CAL-p00001"
-                # Just keep the raw value for later resolution
                 result.append(part)
 
         return result
+
+
+def normalize_req_id(
+    req_id: str,
+    prefix_or_validator: str | PatternValidator = "REQ",
+) -> str:
+    """Normalize ID to canonical format.
+
+    Examples:
+        'd00027' -> 'REQ-d00027'
+        'REQ-d00027' -> 'REQ-d00027'
+
+    Args:
+        req_id: The requirement ID to normalize
+        prefix_or_validator: Either a prefix string or a PatternValidator instance
+
+    Returns:
+        Normalized ID with prefix
+    """
+    if isinstance(prefix_or_validator, PatternValidator):
+        prefix = prefix_or_validator.config.prefix
+    else:
+        prefix = prefix_or_validator
+
+    if req_id.startswith(f"{prefix}-"):
+        return req_id
+    return f"{prefix}-{req_id}"