invar-tools 1.4.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

invar/__init__.py

@@ -8,7 +8,13 @@ This package provides development tools (guard, map, sig).
 For runtime contracts only, use invar-runtime instead.
 """
 
-__version__ = "1.0.0"
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("invar-tools")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0.dev"  # Development mode fallback
+
 __protocol_version__ = "5.0"  # Protocol/spec version (separate from package version)
 
 # Re-export from invar-runtime for backwards compatibility

invar/core/entry_points.py

@@ -100,30 +100,30 @@ def count_escape_hatches(source: str) -> int:
     return len(extract_escape_hatches(source))
 
 
-@post(lambda result: all(len(t) == 2 for t in result))  # Returns (rule, reason) tuples
-def extract_escape_hatches(source: str) -> list[tuple[str, str]]:
+@post(lambda result: all(len(t) == 3 for t in result))  # Returns (rule, reason, line) tuples
+def extract_escape_hatches(source: str) -> list[tuple[str, str, int]]:
     """
-    Extract @invar:allow markers with their reasons (DX-33 Option E).
+    Extract @invar:allow markers with their reasons and line numbers (DX-33, DX-66).
 
     Uses tokenize to only match real comments, not strings/docstrings.
-    Returns list of (rule, reason) tuples for cross-file analysis.
+    Returns list of (rule, reason, line) tuples for cross-file analysis.
 
     Examples:
         >>> extract_escape_hatches("")
         []
         >>> extract_escape_hatches("# @invar:allow shell_result: API boundary")
-        [('shell_result', 'API boundary')]
+        [('shell_result', 'API boundary', 1)]
         >>> source = '''
         ... # @invar:allow rule1: same reason
         ... # @invar:allow rule2: different reason
         ... '''
         >>> extract_escape_hatches(source)
-        [('rule1', 'same reason'), ('rule2', 'different reason')]
+        [('rule1', 'same reason', 2), ('rule2', 'different reason', 3)]
         >>> # DX-33 Option C: Strings containing the pattern should NOT match
         >>> extract_escape_hatches('suggestion = "# @invar:allow rule: reason"')
         []
     """
-    results: list[tuple[str, str]] = []
+    results: list[tuple[str, str, int]] = []
     try:
         # Use iterator-based readline to avoid io.StringIO (forbidden in Core)
         lines = iter(source.splitlines(keepends=True))
@@ -132,10 +132,12 @@ def extract_escape_hatches(source: str) -> list[tuple[str, str]]:
             if tok.type == tokenize.COMMENT:
                 match = INVAR_ALLOW_PATTERN.search(tok.string)
                 if match:
-                    results.append((match.group(1), match.group(2)))
+                    # DX-66: tok.start[0] is the 1-based line number
+                    results.append((match.group(1), match.group(2), tok.start[0]))
     except Exception:
-        # Fall back to regex if tokenization fails (invalid syntax, non-printable chars, etc.)
-        return INVAR_ALLOW_PATTERN.findall(source)
+        # Fall back to regex if tokenization fails - can't get line numbers
+        # Return line 0 to indicate unknown position
+        return [(r, reason, 0) for r, reason in INVAR_ALLOW_PATTERN.findall(source)]
     return results
 
 

invar/core/formatter.py

@@ -235,7 +235,7 @@ def format_guard_agent(report: GuardReport, combined_status: str | None = None)
     status = combined_status if combined_status else ("passed" if report.passed else "failed")
     static_passed = report.errors == 0
 
-    return {
+    result = {
         "status": status,
         # DX-26: Separate static results from combined status
         "static": {
@@ -252,6 +252,26 @@ def format_guard_agent(report: GuardReport, combined_status: str | None = None)
         },
         "fixes": [_violation_to_fix(v) for v in report.violations],
     }
+    # DX-61: Add suggests count if any pattern suggestions exist
+    if report.suggests > 0:
+        result["static"]["suggests"] = report.suggests
+        result["summary"]["suggests"] = report.suggests
+    # DX-66: Add escape hatch summary if any exist
+    if report.escape_hatches.count > 0:
+        result["escape_hatches"] = {
+            "count": report.escape_hatches.count,
+            "by_rule": report.escape_hatches.by_rule,
+            "details": [
+                {
+                    "file": d.file,
+                    "line": d.line,
+                    "rule": d.rule,
+                    "reason": d.reason,
+                }
+                for d in report.escape_hatches.details
+            ],
+        }
+    return result
 
 
 @post(lambda result: "file" in result and "rule" in result and "severity" in result)

invar/core/models.py

@@ -28,6 +28,7 @@ class Severity(str, Enum):
     ERROR = "error"
     WARNING = "warning"
     INFO = "info"  # Phase 7: For informational issues like redundant type contracts
+    SUGGEST = "suggest"  # DX-61: Functional pattern suggestions
 
 
 class Contract(BaseModel):
@@ -82,6 +83,89 @@ class Violation(BaseModel):
     suggestion: str | None = None
 
 
+class EscapeHatchDetail(BaseModel):
+    """
+    Detail of a single escape hatch (@invar:allow) marker (DX-66).
+
+    Examples:
+        >>> d = EscapeHatchDetail(file="test.py", line=10, rule="shell_result", reason="API")
+        >>> d.line
+        10
+        >>> # line=0 is valid (fallback when line number unknown)
+        >>> d0 = EscapeHatchDetail(file="test.py", line=0, rule="test", reason="fallback")
+        >>> d0.line
+        0
+    """
+
+    file: str
+    line: int = Field(ge=0)  # 0 = fallback when line number unknown
+    rule: str
+    reason: str
+
+
+class EscapeHatchSummary(BaseModel):
+    """
+    Summary of escape hatches in the codebase (DX-66).
+
+    Provides visibility into @invar:allow usage for tracking technical debt.
+
+    Examples:
+        >>> summary = EscapeHatchSummary()
+        >>> summary.count
+        0
+        >>> summary.by_rule
+        {}
+        >>> detail = EscapeHatchDetail(file="test.py", line=10, rule="shell_result", reason="API boundary")
+        >>> summary.add(detail)
+        >>> summary.count
+        1
+        >>> summary.by_rule
+        {'shell_result': 1}
+    """
+
+    details: list[EscapeHatchDetail] = Field(default_factory=list)
+
+    @property
+    @post(lambda result: result >= 0)
+    def count(self) -> int:
+        """
+        Total number of escape hatches.
+
+        Examples:
+            >>> EscapeHatchSummary().count
+            0
+        """
+        return len(self.details)
+
+    @property
+    @post(lambda result: all(v >= 0 for v in result.values()))
+    def by_rule(self) -> dict[str, int]:
+        """
+        Count of escape hatches grouped by rule.
+
+        Examples:
+            >>> EscapeHatchSummary().by_rule
+            {}
+        """
+        counts: dict[str, int] = {}
+        for detail in self.details:
+            counts[detail.rule] = counts.get(detail.rule, 0) + 1
+        return counts
+
+    @pre(lambda self, detail: bool(detail.rule) and bool(detail.file))
+    def add(self, detail: EscapeHatchDetail) -> None:
+        """
+        Add an escape hatch detail to the summary.
+
+        Examples:
+            >>> s = EscapeHatchSummary()
+            >>> s.add(EscapeHatchDetail(file="t.py", line=1, rule="r", reason="x"))
+            >>> s.count
+            1
+        """
+        self.details.append(detail)
+
+
 class GuardReport(BaseModel):
     """Complete Guard report for a project."""
 
@@ -90,9 +174,12 @@ class GuardReport(BaseModel):
     errors: int = 0
     warnings: int = 0
     infos: int = 0  # Phase 7: Track INFO-level issues
+    suggests: int = 0  # DX-61: Track SUGGEST-level pattern suggestions
     # P24: Contract coverage statistics (Core files only)
     core_functions_total: int = 0
     core_functions_with_contracts: int = 0
+    # DX-66: Escape hatch visibility
+    escape_hatches: EscapeHatchSummary = Field(default_factory=EscapeHatchSummary)
 
     @pre(lambda self, violation: violation.rule and violation.severity)  # Valid violation
     def add_violation(self, violation: Violation) -> None:
@@ -106,12 +193,18 @@ class GuardReport(BaseModel):
             >>> report.add_violation(v)
             >>> report.errors
             1
+            >>> v2 = Violation(rule="pattern", severity=Severity.SUGGEST, file="x.py", message="sug")
+            >>> report.add_violation(v2)
+            >>> report.suggests
+            1
         """
         self.violations.append(violation)
         if violation.severity == Severity.ERROR:
             self.errors += 1
         elif violation.severity == Severity.WARNING:
             self.warnings += 1
+        elif violation.severity == Severity.SUGGEST:
+            self.suggests += 1
         else:
             self.infos += 1
 
@@ -263,6 +356,11 @@ class RuleConfig(BaseModel):
     timeout_crosshair: int = Field(default=300, ge=1, le=1800)  # Symbolic verification total
     timeout_crosshair_per_condition: int = Field(default=30, ge=1, le=300)  # Per-contract limit
 
+    # DX-61: Pattern detection configuration
+    pattern_min_confidence: str = Field(default="medium")  # low, medium, high
+    pattern_priorities: list[str] = Field(default_factory=lambda: ["P0"])  # P0, P1
+    pattern_exclude: list[str] = Field(default_factory=list)  # Pattern IDs to exclude
+
 
 # Phase 4: Perception models
 

invar/core/patterns/__init__.py

@@ -0,0 +1,53 @@
+"""
+Functional Pattern Detection (DX-61).
+
+This module provides pattern detection for suggesting functional programming
+improvements in Python code. Guard integrates with this module to provide
+SUGGEST-level feedback when it detects opportunities for patterns like:
+
+P0 (Core Patterns):
+    - NewType: Semantic clarity for multiple same-type parameters
+    - Validation: Error accumulation instead of fail-fast
+    - NonEmpty: Compile-time non-empty guarantees
+    - Literal: Type-safe finite value sets
+    - ExhaustiveMatch: assert_never for enum matching
+
+P1 (Extended Patterns - future):
+    - SmartConstructor: Validation at construction time
+    - StructuredError: Typed errors for programmatic handling
+
+Usage:
+    >>> from invar.core.patterns import detect_patterns
+    >>> source = "def f(a: str, b: str, c: str): pass"
+    >>> result = detect_patterns("test.py", source)
+    >>> result.has_suggestions
+    True
+
+See .invar/examples/functional.py for pattern examples.
+"""
+
+from invar.core.patterns.registry import (
+    PatternRegistry,
+    detect_patterns,
+    get_registry,
+)
+from invar.core.patterns.types import (
+    Confidence,
+    DetectionResult,
+    Location,
+    PatternID,
+    PatternSuggestion,
+    Priority,
+)
+
+__all__ = [
+    "Confidence",
+    "DetectionResult",
+    "Location",
+    "PatternID",
+    "PatternRegistry",
+    "PatternSuggestion",
+    "Priority",
+    "detect_patterns",
+    "get_registry",
+]

invar/core/patterns/detector.py

@@ -0,0 +1,249 @@
+"""
+Pattern Detector Protocol (DX-61).
+
+Base protocol for all pattern detectors.
+"""
+
+import ast
+from abc import abstractmethod
+from typing import Protocol
+
+from deal import post, pre
+
+from invar.core.patterns.types import (
+    Confidence,
+    Location,
+    PatternID,
+    PatternSuggestion,
+    Priority,
+)
+
+
+class PatternDetector(Protocol):
+    """
+    Protocol for pattern detectors.
+
+    Each detector identifies opportunities for a specific functional pattern.
+    Detectors analyze AST nodes and return suggestions with confidence levels.
+    """
+
+    @property
+    @abstractmethod
+    @post(lambda result: result in PatternID)
+    def pattern_id(self) -> PatternID:
+        """Unique identifier for this pattern."""
+        ...
+
+    @property
+    @abstractmethod
+    @post(lambda result: result in Priority)
+    def priority(self) -> Priority:
+        """Priority tier (P0 or P1)."""
+        ...
+
+    @property
+    @abstractmethod
+    @post(lambda result: len(result) > 0)
+    def description(self) -> str:
+        """Human-readable description of the pattern."""
+        ...
+
+    @abstractmethod
+    @post(lambda result: all(isinstance(s, PatternSuggestion) for s in result))
+    def detect(self, tree: ast.AST, file_path: str) -> list[PatternSuggestion]:
+        """
+        Analyze AST and return pattern suggestions.
+
+        Args:
+            tree: Parsed AST of the source file
+            file_path: Path to the source file (for location reporting)
+
+        Returns:
+            List of pattern suggestions found in the file
+        """
+        ...
+
+
+class BaseDetector:
+    """
+    Base class with common detection utilities.
+
+    Provides helper methods for AST analysis that can be reused
+    across different pattern detectors.
+    """
+
+    @post(lambda result: all(isinstance(name, str) and name for name, _ in result))
+    def get_function_params(self, node: ast.FunctionDef) -> list[tuple[str, str | None]]:
+        """
+        Extract parameter names and type annotations from a function.
+
+        >>> import ast
+        >>> code = "def f(a: str, b: int, c): pass"
+        >>> tree = ast.parse(code)
+        >>> func = tree.body[0]
+        >>> detector = BaseDetector()
+        >>> params = detector.get_function_params(func)
+        >>> params[0]
+        ('a', 'str')
+        >>> params[1]
+        ('b', 'int')
+        >>> params[2]
+        ('c', None)
+        """
+        params = []
+        for arg in node.args.args:
+            name = arg.arg
+            type_hint = None
+            if arg.annotation:
+                type_hint = self._annotation_to_str(arg.annotation)
+            params.append((name, type_hint))
+        return params
+
+    @post(lambda result: isinstance(result, str) and len(result) > 0)
+    def _annotation_to_str(self, annotation: ast.expr) -> str:
+        """
+        Convert an annotation AST node to string.
+
+        >>> import ast
+        >>> detector = BaseDetector()
+        >>> detector._annotation_to_str(ast.Name(id="str"))
+        'str'
+        >>> detector._annotation_to_str(ast.Constant(value="str"))
+        'str'
+        """
+        if isinstance(annotation, ast.Name):
+            return annotation.id
+        elif isinstance(annotation, ast.Constant):
+            return str(annotation.value)
+        elif isinstance(annotation, ast.Subscript):
+            # Handle generics like list[str]
+            base = self._annotation_to_str(annotation.value)
+            if isinstance(annotation.slice, ast.Tuple):
+                args = ", ".join(self._annotation_to_str(e) for e in annotation.slice.elts)
+            else:
+                args = self._annotation_to_str(annotation.slice)
+            return f"{base}[{args}]"
+        elif isinstance(annotation, ast.Attribute):
+            # Handle qualified names like typing.List
+            parts = []
+            node = annotation
+            while isinstance(node, ast.Attribute):
+                parts.append(node.attr)
+                node = node.value
+            if isinstance(node, ast.Name):
+                parts.append(node.id)
+            return ".".join(reversed(parts))
+        elif isinstance(annotation, ast.BinOp) and isinstance(annotation.op, ast.BitOr):
+            # Handle X | Y union syntax
+            left = self._annotation_to_str(annotation.left)
+            right = self._annotation_to_str(annotation.right)
+            return f"{left} | {right}"
+        else:
+            # Python 3.9+ always has ast.unparse (project requires 3.11+)
+            return ast.unparse(annotation)
+
+    @pre(lambda self, params, type_name: len(type_name) > 0)
+    @post(lambda result: result >= 0)
+    def count_type_occurrences(
+        self, params: list[tuple[str, str | None]], type_name: str
+    ) -> int:
+        """
+        Count how many parameters have a specific type.
+
+        >>> detector = BaseDetector()
+        >>> params = [("a", "str"), ("b", "str"), ("c", "int")]
+        >>> detector.count_type_occurrences(params, "str")
+        2
+        """
+        return sum(1 for _, t in params if t == type_name)
+
+    @post(lambda result: isinstance(result, bool))
+    def has_match_statement(self, node: ast.FunctionDef) -> bool:
+        """
+        Check if function contains a match statement.
+
+        >>> import ast
+        >>> code = '''
+        ... def f(x):
+        ...     match x:
+        ...         case 1: pass
+        ... '''
+        >>> tree = ast.parse(code)
+        >>> func = tree.body[0]
+        >>> detector = BaseDetector()
+        >>> detector.has_match_statement(func)
+        True
+        """
+        return any(isinstance(child, ast.Match) for child in ast.walk(node))
+
+    @post(lambda result: all(isinstance(c, str) for c in result))
+    def get_enum_cases(self, match_node: ast.Match) -> list[str]:
+        """
+        Extract case patterns from a match statement.
+
+        >>> import ast
+        >>> code = '''
+        ... match status:
+        ...     case Status.A: pass
+        ...     case Status.B: pass
+        ... '''
+        >>> tree = ast.parse(code)
+        >>> match = tree.body[0]
+        >>> detector = BaseDetector()
+        >>> cases = detector.get_enum_cases(match)
+        >>> "Status.A" in cases
+        True
+        """
+        cases = []
+        for case in match_node.cases:
+            pattern = case.pattern
+            if isinstance(pattern, ast.MatchValue):
+                cases.append(ast.unparse(pattern.value) if hasattr(ast, "unparse") else str(pattern.value))
+            elif isinstance(pattern, ast.MatchAs) and pattern.pattern is None:
+                cases.append("_")  # Wildcard
+        return cases
+
+    @pre(lambda self, pattern_id, priority, file_path, line, message, current_code, suggested_pattern, confidence, reference_pattern: line > 0)
+    @post(lambda result: result.reference_file == ".invar/examples/functional.py")
+    def make_suggestion(
+        self,
+        pattern_id: PatternID,
+        priority: Priority,
+        file_path: str,
+        line: int,
+        message: str,
+        current_code: str,
+        suggested_pattern: str,
+        confidence: Confidence,
+        reference_pattern: str,
+    ) -> PatternSuggestion:
+        """
+        Create a pattern suggestion with standard reference file.
+
+        >>> from invar.core.patterns.types import PatternID, Priority, Confidence
+        >>> detector = BaseDetector()
+        >>> suggestion = detector.make_suggestion(
+        ...     pattern_id=PatternID.NEWTYPE,
+        ...     priority=Priority.P0,
+        ...     file_path="test.py",
+        ...     line=10,
+        ...     message="Test message",
+        ...     current_code="def f(): pass",
+        ...     suggested_pattern="NewType",
+        ...     confidence=Confidence.HIGH,
+        ...     reference_pattern="Pattern 1: NewType",
+        ... )
+        >>> suggestion.reference_file
+        '.invar/examples/functional.py'
+        """
+        return PatternSuggestion(
+            pattern_id=pattern_id,
+            location=Location(file=file_path, line=line),
+            message=message,
+            confidence=confidence,
+            priority=priority,
+            current_code=current_code,
+            suggested_pattern=suggested_pattern,
+            reference_file=".invar/examples/functional.py",
+            reference_pattern=reference_pattern,
+        )