invar-tools 1.8.0__py3-none-any.whl → 1.11.0__py3-none-any.whl

invar/core/models.py

@@ -1,3 +1,4 @@
+# @invar:allow file_size: LX-10 added layer types and functions, extraction planned
 """
 Pydantic models for Invar.
 
@@ -7,6 +8,7 @@ No I/O operations allowed.
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from enum import Enum
 from typing import Literal
 
@@ -31,6 +33,47 @@ class Severity(str, Enum):
     SUGGEST = "suggest"  # DX-61: Functional pattern suggestions
 
 
+class CodeLayer(str, Enum):
+    """Code layer for differentiated size limits (LX-10)."""
+
+    CORE = "core"
+    SHELL = "shell"
+    TESTS = "tests"
+    DEFAULT = "default"
+
+
+@dataclass(frozen=True)
+class LayerLimits:
+    """Size limits for a specific code layer (LX-10).
+
+    Examples:
+        >>> limits = LayerLimits(max_file_lines=500, max_function_lines=50)
+        >>> limits.max_file_lines
+        500
+        >>> limits.max_function_lines
+        50
+    """
+
+    max_file_lines: int
+    max_function_lines: int
+
+
+# LX-10: Hardcoded layer limits (no config needed)
+PYTHON_LAYER_LIMITS: dict[CodeLayer, LayerLimits] = {
+    CodeLayer.CORE: LayerLimits(500, 50),
+    CodeLayer.SHELL: LayerLimits(700, 100),
+    CodeLayer.TESTS: LayerLimits(1000, 200),
+    CodeLayer.DEFAULT: LayerLimits(600, 80),
+}
+
+TYPESCRIPT_LAYER_LIMITS: dict[CodeLayer, LayerLimits] = {
+    CodeLayer.CORE: LayerLimits(650, 65),
+    CodeLayer.SHELL: LayerLimits(910, 130),
+    CodeLayer.TESTS: LayerLimits(1300, 260),
+    CodeLayer.DEFAULT: LayerLimits(780, 104),
+}
+
+
 class Contract(BaseModel):
     """A contract (precondition or postcondition) on a function."""
 
@@ -72,6 +115,69 @@ class FileInfo(BaseModel):
     source: str = ""  # Original source code for advanced analysis
 
 
+# LX-10: Layer detection functions
+@pre(lambda file_info: file_info is not None and hasattr(file_info, "path"))
+@post(lambda result: result in CodeLayer)
+def get_layer(file_info: FileInfo) -> CodeLayer:
+    """
+    Determine code layer from FileInfo classification.
+
+    Uses existing is_core/is_shell fields. Tests detection via path.
+
+    Examples:
+        >>> get_layer(FileInfo(path="src/core/logic.py", lines=10, is_core=True))
+        <CodeLayer.CORE: 'core'>
+        >>> get_layer(FileInfo(path="src/shell/cli.py", lines=10, is_shell=True))
+        <CodeLayer.SHELL: 'shell'>
+        >>> get_layer(FileInfo(path="tests/test_foo.py", lines=10))
+        <CodeLayer.TESTS: 'tests'>
+        >>> get_layer(FileInfo(path="src/utils.py", lines=10))
+        <CodeLayer.DEFAULT: 'default'>
+        >>> # Edge: "test_" must be at filename start, not anywhere in path
+        >>> get_layer(FileInfo(path="src/contest_utils.py", lines=10))
+        <CodeLayer.DEFAULT: 'default'>
+        >>> get_layer(FileInfo(path="src/foo_test.py", lines=10))
+        <CodeLayer.TESTS: 'tests'>
+    """
+    # Tests: path-based (no is_tests field exists)
+    path_lower = file_info.path.replace("\\", "/").lower()
+    filename = path_lower.rsplit("/", 1)[-1]  # Extract filename
+    # Match: /tests/ dir, /test/ dir, test_*.py files, *_test.py files
+    if (
+        "/tests/" in path_lower
+        or "/test/" in path_lower
+        or filename.startswith("test_")
+        or filename.endswith("_test.py")
+    ):
+        return CodeLayer.TESTS
+
+    # Core/Shell: use existing classification
+    if file_info.is_core:
+        return CodeLayer.CORE
+    if file_info.is_shell:
+        return CodeLayer.SHELL
+
+    return CodeLayer.DEFAULT
+
+
+@pre(lambda layer, language="python": isinstance(layer, CodeLayer) and language in ("python", "typescript"))
+@post(lambda result: result.max_file_lines > 0 and result.max_function_lines > 0)
+def get_limits(layer: CodeLayer, language: str = "python") -> LayerLimits:
+    """
+    Get size limits for layer and language.
+
+    Examples:
+        >>> get_limits(CodeLayer.CORE).max_function_lines
+        50
+        >>> get_limits(CodeLayer.SHELL).max_function_lines
+        100
+        >>> get_limits(CodeLayer.CORE, "typescript").max_function_lines
+        65
+    """
+    limits = TYPESCRIPT_LAYER_LIMITS if language == "typescript" else PYTHON_LAYER_LIMITS
+    return limits[layer]
+
+
 class Violation(BaseModel):
     """A rule violation found by Guard."""
 

invar/core/patterns/detector.py

@@ -27,6 +27,7 @@ class PatternDetector(Protocol):
     Detectors analyze AST nodes and return suggestions with confidence levels.
     """
 
+    # @invar:allow missing_doctest: Abstract property - no executable implementation
     @property
     @abstractmethod
     @post(lambda result: result in PatternID)
@@ -34,6 +35,7 @@ class PatternDetector(Protocol):
         """Unique identifier for this pattern."""
         ...
 
+    # @invar:allow missing_doctest: Abstract property - no executable implementation
     @property
     @abstractmethod
     @post(lambda result: result in Priority)
@@ -41,6 +43,7 @@ class PatternDetector(Protocol):
         """Priority tier (P0 or P1)."""
         ...
 
+    # @invar:allow missing_doctest: Abstract property - no executable implementation
     @property
     @abstractmethod
     @post(lambda result: len(result) > 0)
@@ -48,6 +51,7 @@ class PatternDetector(Protocol):
         """Human-readable description of the pattern."""
         ...
 
+    # @invar:allow missing_doctest: Abstract method - no executable implementation
     @abstractmethod
     @post(lambda result: all(isinstance(s, PatternSuggestion) for s in result))
     def detect(self, tree: ast.AST, file_path: str) -> list[PatternSuggestion]:
@@ -140,7 +144,8 @@ class BaseDetector:
             return f"{left} | {right}"
         else:
             # Python 3.9+ always has ast.unparse (project requires 3.11+)
-            return ast.unparse(annotation)
+            result = ast.unparse(annotation)
+            return result if result else "<unknown>"
 
     @pre(lambda self, params, type_name: len(type_name) > 0)
     @post(lambda result: result >= 0)

invar/core/patterns/p0_exhaustive.py

@@ -51,19 +51,31 @@ class ExhaustiveMatchDetector(BaseDetector):
     @property
     @post(lambda result: result == PatternID.EXHAUSTIVE)
     def pattern_id(self) -> PatternID:
-        """Unique identifier for this pattern."""
+        """Unique identifier for this pattern.
+
+        >>> ExhaustiveMatchDetector().pattern_id
+        <PatternID.EXHAUSTIVE: 'exhaustive'>
+        """
         return PatternID.EXHAUSTIVE
 
     @property
     @post(lambda result: result == Priority.P0)
     def priority(self) -> Priority:
-        """Priority tier."""
+        """Priority tier.
+
+        >>> ExhaustiveMatchDetector().priority
+        <Priority.P0: 'P0'>
+        """
         return Priority.P0
 
     @property
     @post(lambda result: len(result) > 0)
     def description(self) -> str:
-        """Human-readable description."""
+        """Human-readable description.
+
+        >>> len(ExhaustiveMatchDetector().description) > 0
+        True
+        """
         return "Use assert_never for exhaustive enum matching"
 
     @post(lambda result: all(isinstance(s, PatternSuggestion) for s in result))

invar/core/patterns/p0_literal.py

@@ -48,19 +48,31 @@ class LiteralDetector(BaseDetector):
     @property
     @post(lambda result: result == PatternID.LITERAL)
     def pattern_id(self) -> PatternID:
-        """Unique identifier for this pattern."""
+        """Unique identifier for this pattern.
+
+        >>> LiteralDetector().pattern_id
+        <PatternID.LITERAL: 'literal'>
+        """
         return PatternID.LITERAL
 
     @property
     @post(lambda result: result == Priority.P0)
     def priority(self) -> Priority:
-        """Priority tier."""
+        """Priority tier.
+
+        >>> LiteralDetector().priority
+        <Priority.P0: 'P0'>
+        """
         return Priority.P0
 
     @property
     @post(lambda result: len(result) > 0)
     def description(self) -> str:
-        """Human-readable description."""
+        """Human-readable description.
+
+        >>> len(LiteralDetector().description) > 0
+        True
+        """
         return "Use Literal type for finite value sets"
 
     @post(lambda result: all(isinstance(s, PatternSuggestion) for s in result))

invar/core/patterns/p0_newtype.py

@@ -50,19 +50,31 @@ class NewTypeDetector(BaseDetector):
     @property
     @post(lambda result: result == PatternID.NEWTYPE)
     def pattern_id(self) -> PatternID:
-        """Unique identifier for this pattern."""
+        """Unique identifier for this pattern.
+
+        >>> NewTypeDetector().pattern_id
+        <PatternID.NEWTYPE: 'newtype'>
+        """
         return PatternID.NEWTYPE
 
     @property
     @post(lambda result: result == Priority.P0)
     def priority(self) -> Priority:
-        """Priority tier."""
+        """Priority tier.
+
+        >>> NewTypeDetector().priority
+        <Priority.P0: 'P0'>
+        """
         return Priority.P0
 
     @property
     @post(lambda result: len(result) > 0)
     def description(self) -> str:
-        """Human-readable description."""
+        """Human-readable description.
+
+        >>> len(NewTypeDetector().description) > 0
+        True
+        """
         return "Use NewType for semantic clarity with multiple same-type parameters"
 
     @post(lambda result: all(isinstance(s, PatternSuggestion) for s in result))

invar/core/patterns/p0_nonempty.py

@@ -47,19 +47,31 @@ class NonEmptyDetector(BaseDetector):
     @property
     @post(lambda result: result == PatternID.NONEMPTY)
     def pattern_id(self) -> PatternID:
-        """Unique identifier for this pattern."""
+        """Unique identifier for this pattern.
+
+        >>> NonEmptyDetector().pattern_id
+        <PatternID.NONEMPTY: 'nonempty'>
+        """
         return PatternID.NONEMPTY
 
     @property
     @post(lambda result: result == Priority.P0)
     def priority(self) -> Priority:
-        """Priority tier."""
+        """Priority tier.
+
+        >>> NonEmptyDetector().priority
+        <Priority.P0: 'P0'>
+        """
         return Priority.P0
 
     @property
     @post(lambda result: len(result) > 0)
     def description(self) -> str:
-        """Human-readable description."""
+        """Human-readable description.
+
+        >>> len(NonEmptyDetector().description) > 0
+        True
+        """
         return "Use NonEmpty type for compile-time non-empty guarantees"
 
     @post(lambda result: all(isinstance(s, PatternSuggestion) for s in result))

invar/core/patterns/p0_validation.py

@@ -55,19 +55,31 @@ class ValidationDetector(BaseDetector):
     @property
     @post(lambda result: result == PatternID.VALIDATION)
     def pattern_id(self) -> PatternID:
-        """Unique identifier for this pattern."""
+        """Unique identifier for this pattern.
+
+        >>> ValidationDetector().pattern_id
+        <PatternID.VALIDATION: 'validation'>
+        """
         return PatternID.VALIDATION
 
     @property
     @post(lambda result: result == Priority.P0)
     def priority(self) -> Priority:
-        """Priority tier."""
+        """Priority tier.
+
+        >>> ValidationDetector().priority
+        <Priority.P0: 'P0'>
+        """
         return Priority.P0
 
     @property
     @post(lambda result: len(result) > 0)
     def description(self) -> str:
-        """Human-readable description."""
+        """Human-readable description.
+
+        >>> len(ValidationDetector().description) > 0
+        True
+        """
         return "Use error accumulation instead of fail-fast validation"
 
     @post(lambda result: all(isinstance(s, PatternSuggestion) for s in result))

invar/core/patterns/registry.py

@@ -53,7 +53,11 @@ class PatternRegistry:
     @property
     @post(lambda result: len(result) > 0)
     def detectors(self) -> list[PatternDetector]:
-        """Get all registered detectors."""
+        """Get all registered detectors.
+
+        >>> len(PatternRegistry().detectors) >= 5
+        True
+        """
         return self._detectors
 
     @post(lambda result: result is not None)

invar/core/patterns/types.py

@@ -149,7 +149,11 @@ class DetectionResult:
     @property
     @post(lambda result: isinstance(result, bool))
     def has_suggestions(self) -> bool:
-        """Check if any suggestions were found."""
+        """Check if any suggestions were found.
+
+        >>> DetectionResult(file="test.py", suggestions=[], patterns_checked=[]).has_suggestions
+        False
+        """
         return len(self.suggestions) > 0
 
     @pre(lambda self, min_confidence: min_confidence in Confidence)

invar/core/property_gen.py

@@ -368,6 +368,7 @@ def _skip_result(name: str, reason: str) -> PropertyTestResult:
 _SKIP_PATTERNS = (
     "Nothing", "NoSuchExample", "filter_too_much", "Could not resolve",
     "validation error", "missing", "positional argument", "Unable to satisfy",
+    "has no attribute 'check'",  # invar_runtime contracts, not deal contracts
 )
 
 
@@ -377,6 +378,9 @@ def _handle_test_exception(
     err_str: str, func_name: str, max_examples: int
 ) -> PropertyTestResult:
     """Handle exception from property test, returning skip or failure result."""
+    # Check for invar_runtime contracts (deal.cases requires deal contracts)
+    if "has no attribute 'check'" in err_str:
+        return _skip_result(func_name, "Skipped: uses invar_runtime (deal.cases requires deal contracts)")
     if any(p in err_str for p in _SKIP_PATTERNS):
         return _skip_result(func_name, "Skipped: untestable types")
     seed = _extract_hypothesis_seed(err_str)

invar/core/rules.py

@@ -1,10 +1,11 @@
+# @invar:allow file_size: LX-10 added doctests, consider extraction later
 """Rule engine for Guard. Rules check FileInfo and produce Violations. No I/O."""
 
 from __future__ import annotations
 
 from collections.abc import Callable
 
-from deal import post
+from deal import post, pre
 
 from invar.core.contracts import (
     check_empty_contracts,
@@ -14,9 +15,22 @@ from invar.core.contracts import (
     check_semantic_tautology,
     check_skip_without_reason,
 )
-from invar.core.entry_points import get_symbol_lines, has_allow_marker, is_entry_point
+from invar.core.entry_points import (
+    extract_escape_hatches,
+    get_symbol_lines,
+    has_allow_marker,
+    is_entry_point,
+)
 from invar.core.extraction import format_extraction_hint
-from invar.core.models import FileInfo, RuleConfig, Severity, SymbolKind, Violation
+from invar.core.models import (
+    FileInfo,
+    RuleConfig,
+    Severity,
+    SymbolKind,
+    Violation,
+    get_layer,
+    get_limits,
+)
 from invar.core.must_use import check_must_use
 from invar.core.postcondition_scope import check_postcondition_scope
 from invar.core.purity import check_impure_calls, check_internal_imports
@@ -63,11 +77,33 @@ def _get_func_hint(file_info: FileInfo) -> str:
     return f" Functions: {', '.join(f'{n}({sz}L)' for n, sz in funcs)}" if funcs else ""
 
 
+@pre(lambda file_info, rule: file_info is not None and len(rule) > 0)
+@post(lambda result: isinstance(result, bool))
+def _has_file_escape(file_info: FileInfo, rule: str) -> bool:
+    """Check if file has escape hatch for given rule.
+
+    Examples:
+        >>> info = FileInfo(path="test.py", lines=10, source="# @invar:allow file_size: reason")
+        >>> _has_file_escape(info, "file_size")
+        True
+        >>> _has_file_escape(info, "other_rule")
+        False
+        >>> # Edge: empty source returns False
+        >>> _has_file_escape(FileInfo(path="x.py", lines=1), "any")
+        False
+    """
+    if not file_info.source:
+        return False
+    escapes = extract_escape_hatches(file_info.source)
+    return any(r == rule for r, _, _ in escapes)
+
+
 @post(lambda result: all(v.rule in ("file_size", "file_size_warning") for v in result))
 def check_file_size(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     """
     Check if file exceeds maximum line count or warning threshold.
 
+    LX-10: Uses layer-based limits (Core/Shell/Tests/Default).
     P18: Shows function groups in size warnings to help agents decide what to extract.
     P25: Shows extractable groups with dependencies for warnings.
 
@@ -75,30 +111,43 @@ def check_file_size(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
         >>> from invar.core.models import FileInfo, RuleConfig
         >>> check_file_size(FileInfo(path="ok.py", lines=100), RuleConfig())
         []
-        >>> len(check_file_size(FileInfo(path="big.py", lines=600), RuleConfig()))
+        >>> # Default layer: 600 lines max, error at 650
+        >>> len(check_file_size(FileInfo(path="big.py", lines=650), RuleConfig()))
+        1
+        >>> # Shell layer: 700 lines max, no error at 650
+        >>> vs = check_file_size(FileInfo(path="shell/cli.py", lines=550, is_shell=True), RuleConfig())
+        >>> any(v.rule == "file_size" for v in vs)
+        False
+        >>> # Core layer: 500 lines max (strict)
+        >>> len(check_file_size(FileInfo(path="core/calc.py", lines=550, is_core=True), RuleConfig()))
         1
-        >>> # P8: Warning at 80% threshold (400 lines when max is 500)
-        >>> vs = check_file_size(FileInfo(path="growing.py", lines=420), RuleConfig())
-        >>> len(vs) == 1 and vs[0].rule == "file_size_warning"
-        True
     """
+    # Check for escape hatch
+    if _has_file_escape(file_info, "file_size"):
+        return []
+
     violations: list[Violation] = []
     func_hint = _get_func_hint(file_info)
     extraction_hint = format_extraction_hint(file_info)
 
-    if file_info.lines > config.max_file_lines:
+    # LX-10: Get layer-based limits
+    layer = get_layer(file_info)
+    limits = get_limits(layer)
+    max_lines = limits.max_file_lines
+
+    if file_info.lines > max_lines:
         violations.append(Violation(
             rule="file_size", severity=Severity.ERROR, file=file_info.path, line=None,
-            message=f"File has {file_info.lines} lines (max: {config.max_file_lines})",
+            message=f"File has {file_info.lines} lines (max: {max_lines} for {layer.value})",
             suggestion=_build_size_suggestion("Split into smaller modules.", extraction_hint, func_hint),
         ))
     elif config.size_warning_threshold > 0:
-        threshold = int(config.max_file_lines * config.size_warning_threshold)
+        threshold = int(max_lines * config.size_warning_threshold)
         if file_info.lines >= threshold:
-            pct = int(file_info.lines / config.max_file_lines * 100)
+            pct = int(file_info.lines / max_lines * 100)
             violations.append(Violation(
                 rule="file_size_warning", severity=Severity.WARNING, file=file_info.path, line=None,
-                message=f"File has {file_info.lines} lines ({pct}% of {config.max_file_lines} limit)",
+                message=f"File has {file_info.lines} lines ({pct}% of {max_lines} limit)",
                 suggestion=_build_size_suggestion("Consider splitting before reaching limit.", extraction_hint, func_hint),
             ))
     return violations
@@ -109,21 +158,38 @@ def check_function_size(file_info: FileInfo, config: RuleConfig) -> list[Violati
     """
     Check if any function exceeds maximum line count.
 
+    LX-10: Uses layer-based limits (Core/Shell/Tests/Default).
     DX-22: Always uses code_lines (excluding docstring) and excludes doctest lines.
-    These behaviors were previously optional but are now the default.
 
     Examples:
         >>> from invar.core.models import FileInfo, Symbol, SymbolKind
         >>> sym = Symbol(name="foo", kind=SymbolKind.FUNCTION, line=1, end_line=10)
         >>> info = FileInfo(path="test.py", lines=20, symbols=[sym])
-        >>> cfg = RuleConfig(max_function_lines=50)
-        >>> check_function_size(info, cfg)
+        >>> check_function_size(info, RuleConfig())
+        []
+        >>> # Shell layer: 100 lines max (more lenient)
+        >>> sym2 = Symbol(name="cli", kind=SymbolKind.FUNCTION, line=1, end_line=80)
+        >>> info2 = FileInfo(path="shell/cli.py", lines=100, symbols=[sym2], is_shell=True)
+        >>> check_function_size(info2, RuleConfig())
         []
+        >>> # Core layer: 50 lines max (strict)
+        >>> sym3 = Symbol(name="calc", kind=SymbolKind.FUNCTION, line=1, end_line=60)
+        >>> info3 = FileInfo(path="core/calc.py", lines=100, symbols=[sym3], is_core=True)
+        >>> len(check_function_size(info3, RuleConfig()))
+        1
     """
     violations: list[Violation] = []
 
+    # LX-10: Get layer-based limits
+    layer = get_layer(file_info)
+    limits = get_limits(layer)
+    max_func_lines = limits.max_function_lines
+
     for symbol in file_info.symbols:
         if symbol.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD):
+            # LX-10: Check for escape hatch on individual functions
+            if has_allow_marker(symbol, file_info.source, "function_size"):
+                continue
             total_lines = symbol.end_line - symbol.line + 1
             # DX-22: Always use code_lines when available (excluding docstring)
             if symbol.code_lines is not None:
@@ -137,14 +203,14 @@ def check_function_size(file_info: FileInfo, config: RuleConfig) -> list[Violati
                 func_lines -= symbol.doctest_lines
                 line_type = f"{line_type} (excl. doctest)"
 
-            if func_lines > config.max_function_lines:
+            if func_lines > max_func_lines:
                 violations.append(
                     Violation(
                         rule="function_size",
                         severity=Severity.WARNING,
                         file=file_info.path,
                         line=symbol.line,
-                        message=f"Function '{symbol.name}' has {func_lines} {line_type} (max: {config.max_function_lines})",
+                        message=f"Function '{symbol.name}' has {func_lines} {line_type} (max: {max_func_lines} for {layer.value})",
                         suggestion="Extract helper functions",
                     )
                 )

invar/core/sync_helpers.py

@@ -21,6 +21,10 @@ if TYPE_CHECKING:
 # =============================================================================
 
 
+# LX-05: Valid language values for template rendering
+VALID_LANGUAGES = frozenset({"python", "typescript"})
+
+
 @dataclass
 class SyncConfig:
     """Configuration for template sync operation.
@@ -29,12 +33,16 @@ class SyncConfig:
         >>> config = SyncConfig()
         >>> config.syntax
         'cli'
+        >>> config.language
+        'python'
         >>> config.inject_project_additions
         False
 
-        >>> config = SyncConfig(syntax="mcp", force=True)
+        >>> config = SyncConfig(syntax="mcp", language="typescript", force=True)
         >>> config.syntax
         'mcp'
+        >>> config.language
+        'typescript'
         >>> config.force
         True
 
@@ -44,12 +52,30 @@ class SyncConfig:
     """
 
     syntax: str = "cli"  # "cli" or "mcp"
+    language: str = "python"  # "python" or "typescript" (LX-05)
     inject_project_additions: bool = False
     force: bool = False
     check: bool = False  # Preview only
     reset: bool = False  # Discard user content
     skip_patterns: list[str] = field(default_factory=list)  # Glob patterns to skip
 
+    @post(lambda result: result is None)  # Void method, validates or raises
+    def __post_init__(self) -> None:
+        """Validate configuration values.
+
+        Examples:
+            >>> SyncConfig(language="python")  # Valid
+            SyncConfig(syntax='cli', language='python', inject_project_additions=False, force=False, check=False, reset=False, skip_patterns=[])
+
+            >>> SyncConfig(language="rust")  # doctest: +IGNORE_EXCEPTION_DETAIL
+            Traceback (most recent call last):
+            ValueError: Invalid language 'rust'. Must be one of: python, typescript
+        """
+        if self.language not in VALID_LANGUAGES:
+            valid = ", ".join(sorted(VALID_LANGUAGES))
+            msg = f"Invalid language '{self.language}'. Must be one of: {valid}"
+            raise ValueError(msg)
+
 
 @dataclass
 class SyncReport: