crackerjack 0.18.2__py3-none-any.whl → 0.45.2__py3-none-any.whl

crackerjack/services/patterns/core.py

@@ -0,0 +1,212 @@
+"""Core pattern validation classes and utilities.
+
+This module contains the base classes and utilities for safely handling
+regex patterns with validation, caching, and performance monitoring.
+"""
+
+import re
+import signal
+import threading
+import time
+import typing as t
+from dataclasses import dataclass, field
+from re import Pattern
+
+MAX_INPUT_SIZE = 10 * 1024 * 1024
+MAX_ITERATIONS = 10
+PATTERN_CACHE_SIZE = 100
+
+
+class CompiledPatternCache:
+    _lock = threading.RLock()
+    _cache: dict[str, Pattern[str]] = {}
+    _max_size = PATTERN_CACHE_SIZE
+
+    @classmethod
+    def get_compiled_pattern(cls, pattern: str) -> Pattern[str]:
+        return cls.get_compiled_pattern_with_flags(pattern, pattern, 0)
+
+    @classmethod
+    def get_compiled_pattern_with_flags(
+        cls, cache_key: str, pattern: str, flags: int
+    ) -> Pattern[str]:
+        with cls._lock:
+            if cache_key in cls._cache:
+                return cls._cache[cache_key]
+
+            try:
+                compiled = re.compile(pattern, flags)
+            except re.error as e:
+                raise ValueError(f"Invalid regex pattern '{pattern}': {e}")
+
+            if len(cls._cache) >= cls._max_size:
+                oldest_key = next(iter(cls._cache))
+                del cls._cache[oldest_key]
+
+            cls._cache[cache_key] = compiled
+            return compiled
+
+    @classmethod
+    def clear_cache(cls) -> None:
+        with cls._lock:
+            cls._cache.clear()
+
+    @classmethod
+    def get_cache_stats(cls) -> dict[str, int | list[str]]:
+        with cls._lock:
+            return {
+                "size": len(cls._cache),
+                "max_size": cls._max_size,
+                "patterns": list[t.Any](cls._cache.keys()),
+            }
+
+
+def validate_pattern_safety(pattern: str) -> list[str]:
+    warnings = []
+
+    if ".*.*" in pattern:
+        warnings.append("Multiple .* constructs may cause performance issues")
+
+    if ".+.+" in pattern:
+        warnings.append("Multiple .+ constructs may cause performance issues")
+
+    nested_quantifiers = re.findall(r"[+*?]\??[+*?]", pattern)
+    if nested_quantifiers:
+        warnings.append(f"Nested quantifiers detected: {nested_quantifiers}")
+
+    if "|" in pattern and pattern.count("|") > 10:
+        warnings.append("Many alternations may cause performance issues")
+
+    return warnings
+
+
+@dataclass
+class ValidatedPattern:
+    name: str
+    pattern: str
+    replacement: str
+    test_cases: list[tuple[str, str]]
+    description: str = ""
+    global_replace: bool = False
+    flags: int = 0
+    _compiled_pattern: Pattern[str] | None = field(default=None, init=False)
+
+    def __post_init__(self) -> None:
+        self._validate()
+
+    def _validate(self) -> None:
+        try:
+            self._get_compiled_pattern()
+        except ValueError as e:
+            if "Invalid regex pattern" in str(e):
+                error_msg = str(e).replace(f"'{self.pattern}'", f"'{self.name}'")
+                raise ValueError(error_msg) from e
+            raise
+
+        if r"\g < " in self.replacement or r" >" in self.replacement:
+            raise ValueError(
+                f"Bad replacement syntax in '{self.name}': {self.replacement}. "
+                "Use \\g<1> not \\g<1>"  # REGEX OK: educational example
+            )
+
+        warnings = validate_pattern_safety(self.pattern)
+        if warnings:
+            pass
+
+        for input_text, expected in self.test_cases:
+            try:
+                count = 0 if self.global_replace else 1
+                result = self._apply_internal(input_text, count)
+                if result != expected:
+                    raise ValueError(
+                        f"Pattern '{self.name}' failed test case: "
+                        f"'{input_text}' -> '{result}' != expected '{expected}'"
+                    )
+            except re.error as e:
+                raise ValueError(f"Pattern '{self.name}' failed on '{input_text}': {e}")
+
+    def _get_compiled_pattern(self) -> Pattern[str]:
+        cache_key = f"{self.pattern}|flags: {self.flags}"
+        return CompiledPatternCache.get_compiled_pattern_with_flags(
+            cache_key, self.pattern, self.flags
+        )
+
+    def _apply_internal(self, text: str, count: int = 1) -> str:
+        if len(text) > MAX_INPUT_SIZE:
+            raise ValueError(
+                f"Input text too large: {len(text)} bytes > {MAX_INPUT_SIZE}"
+            )
+
+        return self._get_compiled_pattern().sub(self.replacement, text, count=count)
+
+    def apply(self, text: str) -> str:
+        count = 0 if self.global_replace else 1
+        return self._apply_internal(text, count)
+
+    def apply_iteratively(self, text: str, max_iterations: int = MAX_ITERATIONS) -> str:
+        if max_iterations <= 0:
+            raise ValueError("max_iterations must be positive")
+
+        result = text
+        for _ in range(max_iterations):
+            new_result = self.apply(result)
+            if new_result == result:
+                break
+            result = new_result
+        else:
+            pass
+
+        return result
+
+    def apply_with_timeout(self, text: str, timeout_seconds: float = 1.0) -> str:
+        def timeout_handler(signum: int, frame: t.Any) -> None:
+            raise TimeoutError(
+                f"Pattern '{self.name}' timed out after {timeout_seconds}s"
+            )
+
+        old_handler = signal.signal(signal.SIGALRM, timeout_handler)
+        signal.alarm(int(timeout_seconds))
+
+        try:
+            result = self.apply(text)
+        finally:
+            signal.alarm(0)
+            signal.signal(signal.SIGALRM, old_handler)
+
+        return result
+
+    def test(self, text: str) -> bool:
+        compiled = self._get_compiled_pattern()
+        return bool(compiled.search(text))
+
+    def search(self, text: str) -> re.Match[str] | None:
+        if len(text) > MAX_INPUT_SIZE:
+            raise ValueError(
+                f"Input text too large: {len(text)} bytes > {MAX_INPUT_SIZE}"
+            )
+        return self._get_compiled_pattern().search(text)
+
+    def findall(self, text: str) -> list[str]:
+        if len(text) > MAX_INPUT_SIZE:
+            raise ValueError(
+                f"Input text too large: {len(text)} bytes > {MAX_INPUT_SIZE}"
+            )
+        return self._get_compiled_pattern().findall(text)
+
+    def get_performance_stats(
+        self, text: str, iterations: int = 100
+    ) -> dict[str, float]:
+        times = []
+
+        for _ in range(iterations):
+            start = time.perf_counter()
+            self.apply(text)
+            end = time.perf_counter()
+            times.append(end - start)
+
+        return {
+            "mean_time": sum(times) / len(times),
+            "min_time": min(times),
+            "max_time": max(times),
+            "total_time": sum(times),
+        }

crackerjack/services/patterns/documentation/__init__.py

@@ -0,0 +1,14 @@
+"""Documentation-related regex patterns.
+
+This package provides patterns for working with documentation elements including
+docstrings, markdown badges, links, comments, and code blocks.
+"""
+
+from .badges_markdown import PATTERNS as BADGES_MARKDOWN_PATTERNS
+from .comments_blocks import PATTERNS as COMMENTS_BLOCKS_PATTERNS
+from .docstrings import PATTERNS as DOCSTRINGS_PATTERNS
+
+# Merge all documentation patterns into a single registry
+PATTERNS = DOCSTRINGS_PATTERNS | BADGES_MARKDOWN_PATTERNS | COMMENTS_BLOCKS_PATTERNS
+
+__all__ = ["PATTERNS"]

crackerjack/services/patterns/documentation/badges_markdown.py

@@ -0,0 +1,96 @@
+"""Badge and markdown link parsing patterns.
+
+This module provides regex patterns for working with markdown syntax,
+particularly coverage badges and links in README files.
+"""
+
+import re
+
+from ..core import ValidatedPattern
+
+PATTERNS = {
+    "detect_coverage_badge": ValidatedPattern(
+        name="detect_coverage_badge",
+        pattern=r"!\[Coverage.*?\]\(.*?coverage.*?\)|!\[.*coverage.*?\]\(.*?shields\.io.*?coverage.*?\)|https://img\.shields\.io/badge/coverage-[\d\.]+%25-\w+",
+        replacement="",
+        description="Detect existing coverage badges in README content",
+        flags=re.IGNORECASE,
+        test_cases=[
+            ("![Coverage](https://example.com/coverage.svg)", ""),
+            (
+                "![Coverage Badge](https://shields.io/coverage-100%25-green)",
+                "",
+            ),
+            (
+                "https://img.shields.io/badge/coverage-95.5%25-brightgreen",
+                "",
+            ),
+            (
+                "![test coverage](https://img.shields.io/coverage/repo)",
+                "",
+            ),
+            ("Some text without badge", "Some text without badge"),
+        ],
+    ),
+    "extract_markdown_links": ValidatedPattern(
+        name="extract_markdown_links",
+        pattern=r"\[([^\]]+)\]\(([^)]+)\)",
+        replacement=r"\1 -> \2",
+        description="Extract markdown link text and URLs from [text](url) patterns",
+        test_cases=[
+            ("[Click here](http://example.com)", "Click here -> http://example.com"),
+            ("[GitHub](https://github.com)", "GitHub -> https://github.com"),
+            (
+                "[Documentation](./docs/README.md)",
+                "Documentation -> ./docs/README.md",
+            ),
+            ("No links here", "No links here"),
+        ],
+    ),
+    "update_coverage_badge_any": ValidatedPattern(
+        name="update_coverage_badge_any",
+        pattern=r"(!\[.*coverage.*?\]\()([^)]+)(\))",
+        replacement=r"\1NEW_BADGE_URL\3",
+        description="Update any coverage-related badge URL",
+        flags=re.IGNORECASE,
+        test_cases=[
+            ("![Coverage](old_url)", "![Coverage](NEW_BADGE_URL)"),
+            ("![coverage badge](old_url)", "![coverage badge](NEW_BADGE_URL)"),
+            ("![test coverage](url)", "![test coverage](NEW_BADGE_URL)"),
+            ("![Other Badge](url)", "![Other Badge](url)"),
+        ],
+    ),
+    "update_coverage_badge_url": ValidatedPattern(
+        name="update_coverage_badge_url",
+        pattern=r"(!\[Coverage.*?\]\()([^)]+)(\))",
+        replacement=r"\1NEW_BADGE_URL\3",
+        description="Update coverage badge URL in markdown links",
+        test_cases=[
+            ("![Coverage](old_url)", "![Coverage](NEW_BADGE_URL)"),
+            ("![Coverage Badge](old_badge_url)", "![Coverage Badge](NEW_BADGE_URL)"),
+            ("text ![Coverage](url) more", "text ![Coverage](NEW_BADGE_URL) more"),
+            ("no badge here", "no badge here"),
+        ],
+    ),
+    "update_shields_coverage_url": ValidatedPattern(
+        name="update_shields_coverage_url",
+        pattern=r"(https://img\.shields\.io/badge/coverage-[\d\.]+%25-\w+)",
+        replacement="NEW_BADGE_URL",
+        description="Update shields.io coverage badge URLs directly",
+        test_cases=[
+            (
+                "https://img.shields.io/badge/coverage-95.5%25-brightgreen",
+                "NEW_BADGE_URL",
+            ),
+            (
+                "https://img.shields.io/badge/coverage-100%25-success",
+                "NEW_BADGE_URL",
+            ),
+            (
+                "https://img.shields.io/badge/coverage-75.0%25-yellow",
+                "NEW_BADGE_URL",
+            ),
+            ("https://example.com/other-badge", "https://example.com/other-badge"),
+        ],
+    ),
+}

crackerjack/services/patterns/documentation/comments_blocks.py

@@ -0,0 +1,83 @@
+"""Comment and code block parsing patterns.
+
+This module provides regex patterns for working with code comments,
+TODO markers, and bash/command code blocks in documentation.
+"""
+
+import re
+
+from ..core import ValidatedPattern
+
+PATTERNS = {
+    "enhance_command_blocks": ValidatedPattern(
+        name="enhance_command_blocks",
+        pattern=r"```(?:bash|shell|sh)?\n([^`]+)\n```",
+        replacement=r"```bash\n\1\n```",
+        description="Enhance command blocks with proper bash syntax highlighting",
+        test_cases=[
+            ("```\npython -m test\n```", "```bash\npython -m test\n```"),
+            ("```bash\necho hello\n```", "```bash\necho hello\n```"),
+            ("```sh\nls -la\n```", "```bash\nls -la\n```"),
+            ("```shell\ncd /tmp\n```", "```bash\ncd /tmp\n```"),
+        ],
+    ),
+    "extract_bash_command_blocks": ValidatedPattern(
+        name="extract_bash_command_blocks",
+        pattern=r"```bash\n([^`]+)\n```",
+        replacement=r"\1",
+        description="Extract content from bash command blocks",
+        test_cases=[
+            ("```bash\necho hello\n```", "echo hello"),
+            ("```bash\npython -m test\n```", "python -m test"),
+            ("text\n```bash\nls -la\n```\nmore", "text\nls -la\nmore"),
+            ("```bash\nmulti\nline\ncommand\n```", "multi\nline\ncommand"),
+        ],
+    ),
+    "extract_step_numbers": ValidatedPattern(
+        name="extract_step_numbers",
+        pattern=r"^(\s*)(\d+)\.\s*(.+)$",
+        replacement=r"\1**Step \2**: \3",
+        description="Extract and enhance numbered steps in documentation",
+        flags=re.MULTILINE,
+        test_cases=[
+            ("1. First step", "**Step 1**: First step"),
+            ("  2. Indented step", "  **Step 2**: Indented step"),
+            ("10. Double digit step", "**Step 10**: Double digit step"),
+            ("normal text", "normal text"),
+        ],
+    ),
+    "preserved_comments": ValidatedPattern(
+        name="preserved_comments",
+        pattern=r"(#.*?(?: coding: | encoding: | type: | noqa | pragma).*)",
+        replacement=r"\1",
+        description="Match preserved code comments (encoding, type hints, etc.)",
+        test_cases=[
+            ("# coding: utf-8", "# coding: utf-8"),
+            ("# encoding: utf-8", "# encoding: utf-8"),
+            ("# type: ignore", "# type: ignore"),
+            ("# noqa: F401", "# noqa: F401"),
+            (
+                "x = 1  # type: int",
+                "x = 1  # type: int",
+            ),
+            (
+                "# pragma: no cover",
+                "# pragma: no cover",
+            ),
+            ("# regular comment", "# regular comment"),
+        ],
+    ),
+    "todo_pattern": ValidatedPattern(
+        name="todo_pattern",
+        pattern=r"(#.*?TODO.*)",
+        replacement=r"\1",
+        flags=re.IGNORECASE,
+        description="Match TODO comments for validation",
+        test_cases=[
+            ("# TODO: Fix this", "# TODO: Fix this"),
+            ("# todo: implement feature", "# todo: implement feature"),
+            ("# Todo: Update docs", "# Todo: Update docs"),
+            ("# FIXME: not a TODO", "# FIXME: not a TODO"),
+        ],
+    ),
+}

crackerjack/services/patterns/documentation/docstrings.py

@@ -0,0 +1,89 @@
+"""Docstring parsing and manipulation patterns.
+
+This module provides regex patterns for working with docstrings in various formats
+including triple-quoted strings, Google-style, and Sphinx-style documentation.
+"""
+
+import re
+
+from ..core import ValidatedPattern
+
+PATTERNS = {
+    "docstring_triple_double": ValidatedPattern(
+        name="docstring_triple_double",
+        pattern=r'^\s*""".*?"""\s*$',
+        replacement=r"",
+        flags=re.MULTILINE | re.DOTALL,
+        description="Remove triple-quoted docstrings with double quotes",
+        test_cases=[
+            (' """This is a docstring""" ', ""),
+            ('"""Module docstring"""', ""),
+            (' """\n Multi-line\n docstring\n """', ""),
+            (
+                'regular_code = "not a docstring"',
+                'regular_code = "not a docstring"',
+            ),
+        ],
+    ),
+    "docstring_triple_single": ValidatedPattern(
+        name="docstring_triple_single",
+        pattern=r"^\s*'''.*?'''\s*$",
+        replacement=r"",
+        flags=re.MULTILINE | re.DOTALL,
+        description="Remove triple-quoted docstrings with single quotes",
+        test_cases=[
+            (" '''This is a docstring''' ", ""),
+            ("'''Module docstring'''", ""),
+            (" '''\n Multi-line\n docstring\n '''", ""),
+            (
+                "regular_code = 'not a docstring'",
+                "regular_code = 'not a docstring'",
+            ),
+        ],
+    ),
+    "extract_docstring_returns": ValidatedPattern(
+        name="extract_docstring_returns",
+        pattern=r"(?:Returns?|Return):\s*(.+?)(?=\n\n|\n\w+:|\Z)",
+        replacement=r"\1",
+        description="Extract return descriptions from docstrings",
+        flags=re.MULTILINE | re.DOTALL,
+        test_cases=[
+            ("Returns: Simple value", "Simple value"),
+            ("Return: Another form", "Another form"),
+            ("Returns: Multi-line\n    description", "Multi-line\n    description"),
+            ("Returns: Simple value\n\nArgs:", "Simple value\n\nArgs:"),
+        ],
+    ),
+    "extract_google_docstring_params": ValidatedPattern(
+        name="extract_google_docstring_params",
+        pattern=r"^\s*(\w+)(?:\s*\([^)]+\))?\s*:\s*(.+)$",
+        replacement=r"\1: \2",
+        description="Extract parameter names and descriptions from Google-style docstrings",
+        flags=re.MULTILINE,
+        test_cases=[
+            ("name (str): Description here", "name: Description here"),
+            ("count (int): Number of items", "count: Number of items"),
+            (
+                "complex_param (Optional[Dict[str, Any]]): Complex type",
+                "complex_param: Complex type",
+            ),
+            ("simple: Simple desc", "simple: Simple desc"),
+        ],
+    ),
+    "extract_sphinx_docstring_params": ValidatedPattern(
+        name="extract_sphinx_docstring_params",
+        pattern=r":param\s+(\w+)\s*:\s*(.+)$",
+        replacement=r"\1: \2",
+        description="Extract parameter names and descriptions from Sphinx-style docstrings",
+        flags=re.MULTILINE,
+        test_cases=[
+            (":param name: Description here", "name: Description here"),
+            (":param count: Number of items", "count: Number of items"),
+            (":param my_var: Simple description", "my_var: Simple description"),
+            (
+                ":param complex_var: Multi-word description here",
+                "complex_var: Multi-word description here",
+            ),
+        ],
+    ),
+}