invar-tools 1.7.1__py3-none-any.whl → 1.10.0__py3-none-any.whl

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:

invar/core/template_helpers.py

@@ -0,0 +1,32 @@
+"""
+Template transformation helpers.
+
+Core module: pure logic for template content transformations.
+"""
+
+from __future__ import annotations
+
+from deal import post
+
+
+@post(lambda result: "`" not in result or "\\`" in result)
+@post(lambda result: "${" not in result or "\\${" in result)
+def escape_for_js_template(content: str) -> str:
+    """
+    Escape content for JavaScript template literal.
+
+    Escapes backticks and ${} sequences that would be interpreted
+    by JavaScript template literals.
+
+    >>> escape_for_js_template("Hello `world`")
+    'Hello \\\\`world\\\\`'
+    >>> escape_for_js_template("Value: ${x}")
+    'Value: \\\\${x}'
+    >>> escape_for_js_template("Normal text")
+    'Normal text'
+    """
+    # Escape backticks
+    content = content.replace("`", "\\`")
+    # Escape ${} template expressions
+    content = content.replace("${", "\\${")
+    return content

invar/core/ts_parsers.py

@@ -0,0 +1,286 @@
+"""TypeScript tool output parsers (pure logic).
+
+This module contains pure parsing functions for TypeScript tool outputs.
+Part of LX-06 TypeScript tooling support.
+
+All functions are pure - they transform strings to structured data
+without any I/O operations.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Literal
+
+from deal import post, pre
+
+
+@dataclass(frozen=True)
+class TSViolation:
+    """A single TypeScript verification issue (immutable)."""
+
+    file: str
+    line: int | None
+    column: int | None
+    rule: str
+    message: str
+    severity: Literal["error", "warning", "info"]
+    source: Literal["tsc", "eslint", "vitest"]
+
+
+@pre(lambda line: "\n" not in line)  # Single line only
+@post(lambda result: result is None or result.source == "tsc")
+def parse_tsc_line(line: str) -> TSViolation | None:
+    """Parse a single tsc output line into a violation.
+
+    Args:
+        line: Raw tsc output line.
+
+    Returns:
+        Parsed violation or None if parsing fails.
+
+    Examples:
+        >>> v = parse_tsc_line("src/foo.ts(10,5): error TS2322: Type mismatch")
+        >>> v.file if v else None
+        'src/foo.ts'
+        >>> v.line if v else None
+        10
+        >>> v.rule if v else None
+        'TS2322'
+        >>> v.severity if v else None
+        'error'
+
+        >>> v = parse_tsc_line("src/bar.ts(1,1): warning TS6133: Unused var")
+        >>> v.severity if v else None
+        'warning'
+
+        >>> parse_tsc_line("random text") is None
+        True
+
+        >>> parse_tsc_line("") is None
+        True
+    """
+    # Pattern: file(line,col): severity TSxxxx: message
+    pattern = r"^(.+?)\((\d+),(\d+)\): (error|warning) (TS\d+): (.+)$"
+    match = re.match(pattern, line)
+
+    if not match:
+        return None
+
+    file_path, line_num, col, severity, code, message = match.groups()
+
+    return TSViolation(
+        file=file_path,
+        line=int(line_num),
+        column=int(col),
+        rule=code,
+        message=message,
+        severity="error" if severity == "error" else "warning",
+        source="tsc",
+    )
+
+
+@pre(lambda output: output is not None)  # Accepts any string including empty
+@post(lambda result: all(v.source == "tsc" for v in result))
+def parse_tsc_output(output: str) -> list[TSViolation]:
+    """Parse full tsc output into violations list.
+
+    Args:
+        output: Full tsc stdout output.
+
+    Returns:
+        List of parsed violations.
+
+    Examples:
+        >>> output = '''src/a.ts(1,1): error TS2322: Type A
+        ... src/b.ts(2,3): warning TS6133: Unused
+        ... Some other line'''
+        >>> violations = parse_tsc_output(output)
+        >>> len(violations)
+        2
+        >>> violations[0].file
+        'src/a.ts'
+
+        >>> parse_tsc_output("")
+        []
+    """
+    violations: list[TSViolation] = []
+    for line in output.splitlines():
+        if ": error TS" in line or ": warning TS" in line:
+            violation = parse_tsc_line(line)
+            if violation:
+                violations.append(violation)
+    return violations
+
+
+@pre(lambda output, base_path="": output is not None)  # Accepts any string including empty
+@post(lambda result: all(v.source == "eslint" for v in result))
+def parse_eslint_json(output: str, base_path: str = "") -> list[TSViolation]:
+    """Parse ESLint JSON output into violations list.
+
+    Args:
+        output: ESLint JSON stdout output.
+        base_path: Base path to make file paths relative (optional).
+
+    Returns:
+        List of parsed violations.
+
+    Examples:
+        >>> output = '''[{
+        ...   "filePath": "/project/src/foo.ts",
+        ...   "messages": [
+        ...     {"line": 10, "column": 5, "severity": 2,
+        ...      "ruleId": "no-unused-vars", "message": "Unused var"}
+        ...   ]
+        ... }]'''
+        >>> violations = parse_eslint_json(output, "/project")
+        >>> len(violations)
+        1
+        >>> violations[0].rule
+        'no-unused-vars'
+        >>> violations[0].severity
+        'error'
+
+        >>> parse_eslint_json("invalid json")
+        []
+
+        >>> parse_eslint_json("")
+        []
+    """
+    violations: list[TSViolation] = []
+
+    try:
+        eslint_output = json.loads(output)
+    except json.JSONDecodeError:
+        return violations
+
+    # ESLint output must be a list
+    if not isinstance(eslint_output, list):
+        return violations
+
+    for file_result in eslint_output:
+        # Each file result must be a dict
+        if not isinstance(file_result, dict):
+            continue
+
+        file_path = file_result.get("filePath", "")
+
+        # Make path relative if base_path provided
+        if base_path and isinstance(file_path, str) and file_path.startswith(base_path):
+            file_path = file_path[len(base_path) :].lstrip("/\\")
+
+        messages = file_result.get("messages", [])
+        if not isinstance(messages, list):
+            continue
+
+        for msg in messages:
+            if not isinstance(msg, dict):
+                continue
+            severity_num = msg.get("severity", 1)
+            violations.append(
+                TSViolation(
+                    file=str(file_path),
+                    line=msg.get("line"),
+                    column=msg.get("column"),
+                    rule=msg.get("ruleId") or "unknown",
+                    message=str(msg.get("message", "")),
+                    severity="error" if severity_num == 2 else "warning",
+                    source="eslint",
+                )
+            )
+
+    return violations
+
+
+@pre(lambda output, base_path="": output is not None)  # Accepts any string including empty
+@post(lambda result: all(v.source == "vitest" for v in result))
+def parse_vitest_json(output: str, base_path: str = "") -> list[TSViolation]:
+    """Parse Vitest JSON output into violations list.
+
+    Args:
+        output: Vitest JSON stdout output.
+        base_path: Base path to make file paths relative (optional).
+
+    Returns:
+        List of violations (test failures only).
+
+    Examples:
+        >>> output = '''{
+        ...   "testResults": [{
+        ...     "name": "/project/tests/foo.test.ts",
+        ...     "assertionResults": [
+        ...       {"status": "failed", "title": "should work"}
+        ...     ]
+        ...   }]
+        ... }'''
+        >>> violations = parse_vitest_json(output, "/project")
+        >>> len(violations)
+        1
+        >>> violations[0].rule
+        'test_failure'
+
+        >>> parse_vitest_json("invalid json")
+        []
+
+        >>> output_pass = '{"testResults": [{"name": "x", "assertionResults": [{"status": "passed", "title": "ok"}]}]}'
+        >>> parse_vitest_json(output_pass)
+        []
+    """
+    violations: list[TSViolation] = []
+
+    try:
+        vitest_output = json.loads(output)
+    except json.JSONDecodeError:
+        return violations
+
+    # Vitest output must be a dict with testResults
+    if not isinstance(vitest_output, dict):
+        return violations
+
+    test_results = vitest_output.get("testResults", [])
+    if not isinstance(test_results, list):
+        return violations
+
+    for test_file in test_results:
+        # Each test file must be a dict
+        if not isinstance(test_file, dict):
+            continue
+
+        file_path = test_file.get("name", "")
+
+        # Make path relative if base_path provided
+        if base_path and isinstance(file_path, str) and file_path.startswith(base_path):
+            file_path = file_path[len(base_path) :].lstrip("/\\")
+
+        assertion_results = test_file.get("assertionResults", [])
+        if not isinstance(assertion_results, list):
+            continue
+
+        for assertion in assertion_results:
+            if not isinstance(assertion, dict):
+                continue
+            if assertion.get("status") == "failed":
+                # Extract detailed failure message from failureMessages if available
+                title = str(assertion.get("title", "Test failed"))
+                failure_msgs = assertion.get("failureMessages", [])
+                if isinstance(failure_msgs, list) and failure_msgs:
+                    # Use first failure message, truncate if too long
+                    detail = str(failure_msgs[0])[:200]
+                    message = f"{title}: {detail}"
+                else:
+                    message = title
+                violations.append(
+                    TSViolation(
+                        file=str(file_path),
+                        line=None,
+                        column=None,
+                        rule="test_failure",
+                        message=message,
+                        severity="error",
+                        source="vitest",
+                    )
+                )
+
+    return violations