invar-tools 1.0.0__py3-none-any.whl

invar/core/lambda_helpers.py

@@ -0,0 +1,190 @@
+"""Lambda expression parsing helpers for contract analysis. No I/O operations."""
+
+from __future__ import annotations
+
+import ast
+import re
+
+from deal import post, pre
+
+
+@post(lambda result: result is None or isinstance(result, ast.Lambda))
+def find_lambda(tree: ast.Expression) -> ast.Lambda | None:
+    """Find the lambda node in an expression tree.
+
+    Examples:
+        >>> tree = ast.parse("lambda x: x > 0", mode="eval")
+        >>> find_lambda(tree) is not None
+        True
+        >>> tree = ast.parse("x + y", mode="eval")
+        >>> find_lambda(tree) is None
+        True
+    """
+    return next((n for n in ast.walk(tree) if isinstance(n, ast.Lambda)), None)
+
+
+@post(lambda result: isinstance(result, dict))
+def extract_annotations(signature: str) -> dict[str, str]:
+    """Extract parameter type annotations from signature.
+
+    Examples:
+        >>> extract_annotations("(x: int, y: str) -> bool")
+        {'x': 'int', 'y': 'str'}
+        >>> extract_annotations("(items: list[int]) -> None")
+        {'items': 'list[int]'}
+        >>> extract_annotations("(x, y)")
+        {}
+    """
+    if not signature or not signature.startswith("("):
+        return {}
+    annotations = {}
+    match = re.match(r"\(([^)]*)\)", signature)
+    if not match:
+        return annotations
+    for param in match.group(1).split(","):
+        param = param.strip()
+        if ": " in param:
+            name, type_hint = param.split(": ", 1)
+            if "=" in type_hint:
+                type_hint = type_hint.split("=")[0].strip()
+            annotations[name.strip()] = type_hint.strip()
+    return annotations
+
+
+@pre(lambda expression: isinstance(expression, str))
+@post(lambda result: result is None or isinstance(result, list))
+def extract_lambda_params(expression: str) -> list[str] | None:
+    """Extract parameter names from a lambda expression.
+
+    Examples:
+        >>> extract_lambda_params("lambda x, y: x > 0")
+        ['x', 'y']
+        >>> extract_lambda_params("lambda: True")
+        []
+        >>> extract_lambda_params("not a lambda") is None
+        True
+    """
+    if not expression.strip() or "lambda" not in expression:
+        return None
+    try:
+        tree = ast.parse(expression, mode="eval")
+        lambda_node = find_lambda(tree)
+        return [arg.arg for arg in lambda_node.args.args] if lambda_node else None
+    except (SyntaxError, TypeError, ValueError):
+        return None
+
+
+@post(lambda result: result is None or isinstance(result, list))
+def extract_func_param_names(signature: str) -> list[str] | None:
+    """Extract parameter names from a function signature (handles nested brackets).
+
+    Examples:
+        >>> extract_func_param_names("(x: int, y: int) -> int")
+        ['x', 'y']
+        >>> extract_func_param_names("(items: dict[str, int]) -> None")
+        ['items']
+        >>> extract_func_param_names("() -> bool")
+        []
+    """
+    if not signature or not signature.startswith("("):
+        return None
+    match = re.match(r"\(([^)]*)\)", signature)
+    if not match:
+        return None
+    content = match.group(1).strip()
+    if not content:
+        return []
+    # Split by comma, but respect brackets (for dict[K, V], tuple[A, B], etc.)
+    params = []
+    current = ""
+    depth = 0
+    for char in content:
+        if char in "([{":
+            depth += 1
+        elif char in ")]}":
+            depth -= 1
+        elif char == "," and depth == 0:
+            if current.strip():
+                params.append(current.strip().split(":")[0].split("=")[0].strip())
+            current = ""
+            continue
+        current += char
+    if current.strip():
+        params.append(current.strip().split(":")[0].split("=")[0].strip())
+    return params
+
+
+@post(lambda result: isinstance(result, set))
+def extract_used_names(node: ast.expr) -> set[str]:
+    """Extract all variable names used in an expression (Load context).
+
+    Examples:
+        >>> tree = ast.parse("x + y", mode="eval")
+        >>> sorted(extract_used_names(tree.body))
+        ['x', 'y']
+        >>> tree = ast.parse("len(items) > 0", mode="eval")
+        >>> sorted(extract_used_names(tree.body))
+        ['items', 'len']
+    """
+    names: set[str] = set()
+    for child in ast.walk(node):
+        if isinstance(child, ast.Name) and isinstance(child.ctx, ast.Load):
+            names.add(child.id)
+    return names
+
+
+# DX-01: Helper to generate lambda fix templates
+
+
+@post(lambda result: isinstance(result, str))
+def generate_lambda_fix(signature: str) -> str:
+    """
+    Generate a lambda fix template from function signature.
+
+    DX-01: Provides copy-pastable fix for param_mismatch errors.
+
+    Examples:
+        >>> generate_lambda_fix("(x: int, y: str) -> bool")
+        '@pre(lambda x, y: <condition>)'
+        >>> generate_lambda_fix("(x: int, y: int = 10) -> int")
+        '@pre(lambda x, y=10: <condition>)'
+        >>> generate_lambda_fix("(items: list[int], n: int = 5, reverse: bool = False) -> list")
+        '@pre(lambda items, n=5, reverse=False: <condition>)'
+        >>> generate_lambda_fix("() -> bool")
+        '@pre(lambda: <condition>)'
+        >>> generate_lambda_fix("")
+        '@pre(lambda: <condition>)'
+    """
+    if not signature or signature == "()" or not signature.startswith("("):
+        return "@pre(lambda: <condition>)"
+
+    match = re.match(r"\(([^)]*)\)", signature)
+    if not match:
+        return "@pre(lambda: <condition>)"
+
+    param_parts: list[str] = []
+    for param in match.group(1).split(","):
+        param = param.strip()
+        if not param:
+            continue
+
+        # Extract name and default value
+        if ": " in param:
+            name_part, type_part = param.split(": ", 1)
+            name = name_part.strip()
+            # Check for default value
+            if "=" in type_part:
+                default = type_part.split("=", 1)[1].strip()
+                param_parts.append(f"{name}={default}")
+            else:
+                param_parts.append(name)
+        elif "=" in param:
+            name, default = param.split("=", 1)
+            param_parts.append(f"{name.strip()}={default.strip()}")
+        else:
+            param_parts.append(param)
+
+    if not param_parts:
+        return "@pre(lambda: <condition>)"
+    params_str = ", ".join(param_parts)
+    return f"@pre(lambda {params_str}: <condition>)"

invar/core/models.py

@@ -0,0 +1,289 @@
+"""
+Pydantic models for Invar.
+
+Core models are pure data structures with validation.
+No I/O operations allowed.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Literal
+
+from deal import pre
+from pydantic import BaseModel, Field
+
+
+class SymbolKind(str, Enum):
+    """Kind of symbol extracted from Python code."""
+
+    FUNCTION = "function"
+    CLASS = "class"
+    METHOD = "method"
+
+
+class Severity(str, Enum):
+    """Severity level for violations."""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"  # Phase 7: For informational issues like redundant type contracts
+
+
+class Contract(BaseModel):
+    """A contract (precondition or postcondition) on a function."""
+
+    kind: Literal["pre", "post"]
+    expression: str
+    line: int
+
+
+class Symbol(BaseModel):
+    """A symbol extracted from Python source code."""
+
+    name: str
+    kind: SymbolKind
+    line: int
+    end_line: int
+    signature: str = ""
+    docstring: str | None = None
+    contracts: list[Contract] = Field(default_factory=list)
+    has_doctest: bool = False
+    # Phase 3: Guard Enhancement
+    internal_imports: list[str] = Field(default_factory=list)
+    impure_calls: list[str] = Field(default_factory=list)
+    code_lines: int | None = None  # Lines excluding docstring/comments
+    # Phase 6: Verification Completeness
+    doctest_lines: int = 0  # Number of lines that are doctest examples
+    # Phase 11 P25: For extraction analysis
+    function_calls: list[str] = Field(default_factory=list)  # Functions called within this function
+
+
+class FileInfo(BaseModel):
+    """Information about a Python file."""
+
+    path: str
+    lines: int
+    symbols: list[Symbol] = Field(default_factory=list)
+    imports: list[str] = Field(default_factory=list)
+    is_core: bool = False
+    is_shell: bool = False
+    source: str = ""  # Original source code for advanced analysis
+
+
+class Violation(BaseModel):
+    """A rule violation found by Guard."""
+
+    rule: str
+    severity: Severity
+    file: str
+    line: int | None = None
+    message: str
+    suggestion: str | None = None
+
+
+class GuardReport(BaseModel):
+    """Complete Guard report for a project."""
+
+    files_checked: int
+    violations: list[Violation] = Field(default_factory=list)
+    errors: int = 0
+    warnings: int = 0
+    infos: int = 0  # Phase 7: Track INFO-level issues
+    # P24: Contract coverage statistics (Core files only)
+    core_functions_total: int = 0
+    core_functions_with_contracts: int = 0
+
+    @pre(lambda self, violation: isinstance(violation, Violation))
+    def add_violation(self, violation: Violation) -> None:
+        """
+        Add a violation and update counts.
+
+        Examples:
+            >>> from invar.core.models import Violation, Severity, GuardReport
+            >>> report = GuardReport(files_checked=1)
+            >>> v = Violation(rule="test", severity=Severity.ERROR, file="x.py", message="err")
+            >>> report.add_violation(v)
+            >>> report.errors
+            1
+        """
+        self.violations.append(violation)
+        if violation.severity == Severity.ERROR:
+            self.errors += 1
+        elif violation.severity == Severity.WARNING:
+            self.warnings += 1
+        else:
+            self.infos += 1
+
+    @pre(lambda self, total, with_contracts: total >= 0 and with_contracts >= 0)
+    def update_coverage(self, total: int, with_contracts: int) -> None:
+        """
+        Update contract coverage statistics (P24).
+
+        Examples:
+            >>> from invar.core.models import GuardReport
+            >>> report = GuardReport(files_checked=1)
+            >>> report.update_coverage(10, 8)
+            >>> report.core_functions_total
+            10
+            >>> report.core_functions_with_contracts
+            8
+        """
+        self.core_functions_total += total
+        self.core_functions_with_contracts += with_contracts
+
+    @property
+    @pre(lambda self: isinstance(self, GuardReport))
+    def contract_coverage_pct(self) -> int:
+        """
+        Get contract coverage percentage (P24).
+
+        Examples:
+            >>> from invar.core.models import GuardReport
+            >>> report = GuardReport(files_checked=1)
+            >>> report.update_coverage(10, 8)
+            >>> report.contract_coverage_pct
+            80
+        """
+        if self.core_functions_total == 0:
+            return 100
+        return int(self.core_functions_with_contracts / self.core_functions_total * 100)
+
+    @property
+    @pre(lambda self: isinstance(self, GuardReport))
+    def contract_issue_counts(self) -> dict[str, int]:
+        """
+        Count contract quality issues by type (P24).
+
+        Examples:
+            >>> from invar.core.models import GuardReport, Violation, Severity
+            >>> report = GuardReport(files_checked=1)
+            >>> v1 = Violation(rule="empty_contract", severity=Severity.WARNING, file="x.py", message="m")
+            >>> v2 = Violation(rule="semantic_tautology", severity=Severity.WARNING, file="x.py", message="m")
+            >>> report.add_violation(v1)
+            >>> report.add_violation(v2)
+            >>> report.contract_issue_counts
+            {'tautology': 1, 'empty': 1, 'partial': 0, 'type_only': 0}
+        """
+        counts = {"tautology": 0, "empty": 0, "partial": 0, "type_only": 0}
+        for v in self.violations:
+            if v.rule == "semantic_tautology":
+                counts["tautology"] += 1
+            elif v.rule == "empty_contract":
+                counts["empty"] += 1
+            elif v.rule == "partial_contract":
+                counts["partial"] += 1
+            elif v.rule == "redundant_type_contract":
+                counts["type_only"] += 1
+        return counts
+
+    @property
+    @pre(lambda self: isinstance(self, GuardReport))
+    def passed(self) -> bool:
+        """
+        Check if guard passed (no errors).
+
+        Examples:
+            >>> from invar.core.models import GuardReport
+            >>> report = GuardReport(files_checked=1)
+            >>> report.passed
+            True
+        """
+        return self.errors == 0
+
+
+class RuleExclusion(BaseModel):
+    """
+    A rule exclusion pattern for specific files.
+
+    Examples:
+        >>> excl = RuleExclusion(pattern="**/generated/**", rules=["*"])
+        >>> excl.pattern
+        '**/generated/**'
+        >>> excl.rules
+        ['*']
+    """
+
+    pattern: str  # Glob pattern (fnmatch style with ** support)
+    rules: list[str]  # Rule names to exclude, or ["*"] for all
+
+
+class RuleConfig(BaseModel):
+    """
+    Configuration for rule checking.
+
+    Examples:
+        >>> config = RuleConfig()
+        >>> config.max_file_lines  # Phase 9 P1: Raised from 300
+        500
+        >>> config.strict_pure  # Phase 9 P12: Default ON for agents
+        True
+    """
+
+    max_file_lines: int = 500  # Phase 9 P1: Raised from 300 for less friction
+    max_function_lines: int = 50
+    forbidden_imports: tuple[str, ...] = (
+        "os",
+        "sys",
+        "socket",
+        "requests",
+        "urllib",
+        "subprocess",
+        "shutil",
+        "io",
+        "pathlib",
+    )
+    require_contracts: bool = True
+    require_doctests: bool = True
+    strict_pure: bool = True  # Phase 9 P12: Default ON for agent-native
+    use_code_lines: bool = False
+    exclude_doctest_lines: bool = False
+    # Phase 9 P1: Rule exclusions for specific file patterns
+    rule_exclusions: list[RuleExclusion] = Field(default_factory=list)
+    # Phase 9 P2: Per-rule severity overrides (off, info, warning, error)
+    severity_overrides: dict[str, str] = Field(
+        default_factory=lambda: {
+            "redundant_type_contract": "off",  # Expected behavior when forcing contracts
+        }
+    )
+    # Phase 9 P8: File size warning threshold (0 to disable, 0.8 = warn at 80%)
+    size_warning_threshold: float = 0.8
+    # B4: User-declared purity (override heuristics)
+    purity_pure: list[str] = Field(default_factory=list)  # Known pure functions
+    purity_impure: list[str] = Field(default_factory=list)  # Known impure functions
+
+
+# Phase 4: Perception models
+
+
+class SymbolRefs(BaseModel):
+    """
+    A symbol with its cross-file reference count.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind, SymbolRefs
+        >>> sym = Symbol(name="foo", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> sr = SymbolRefs(symbol=sym, file_path="core/calc.py", ref_count=10)
+        >>> sr.ref_count
+        10
+    """
+
+    symbol: Symbol
+    file_path: str
+    ref_count: int = 0
+
+
+class PerceptionMap(BaseModel):
+    """
+    Complete perception map for a project.
+
+    Examples:
+        >>> pm = PerceptionMap(project_root="/test", total_files=5, total_symbols=20)
+        >>> pm.total_files
+        5
+    """
+
+    project_root: str
+    total_files: int
+    total_symbols: int
+    symbols: list[SymbolRefs] = Field(default_factory=list)

invar/core/must_use.py

@@ -0,0 +1,172 @@
+"""
+Must-use return value detection.
+
+Core module: detects ignored return values of @must_use functions.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from deal import post, pre
+
+from invar.core.models import FileInfo, RuleConfig, Severity, Violation
+
+
+@pre(lambda source: isinstance(source, str) and len(source) > 0)
+def find_must_use_functions(source: str) -> dict[str, str]:
+    """
+    Find all functions decorated with @must_use in source code.
+
+    Returns a dict mapping function name to the must_use reason.
+
+    >>> code = '''
+    ... from invar import must_use
+    ... @must_use("Handle the error")
+    ... def validate(): pass
+    ... '''
+    >>> find_must_use_functions(code)
+    {'validate': 'Handle the error'}
+
+    >>> code = '''
+    ... @must_use()
+    ... def check(): pass
+    ... '''
+    >>> find_must_use_functions(code)
+    {'check': 'Return value must be used'}
+
+    >>> find_must_use_functions("def foo(): pass")
+    {}
+    """
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, TypeError, ValueError):
+        return {}
+
+    must_use_funcs: dict[str, str] = {}
+
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+
+        for decorator in node.decorator_list:
+            reason = _extract_must_use_reason(decorator)
+            if reason is not None:
+                must_use_funcs[node.name] = reason
+                break
+
+    return must_use_funcs
+
+
+@post(lambda result: result is None or isinstance(result, str))
+def _extract_must_use_reason(decorator: ast.expr) -> str | None:
+    """Extract reason from @must_use decorator, or None if not a must_use."""
+    # Case 1: @must_use("reason")
+    if isinstance(decorator, ast.Call):
+        func = decorator.func
+        if isinstance(func, ast.Name) and func.id == "must_use":
+            if decorator.args and isinstance(decorator.args[0], ast.Constant):
+                return str(decorator.args[0].value)
+            return "Return value must be used"
+        if isinstance(func, ast.Attribute) and func.attr == "must_use":
+            if decorator.args and isinstance(decorator.args[0], ast.Constant):
+                return str(decorator.args[0].value)
+            return "Return value must be used"
+
+    # Case 2: @must_use (no parens - though our API requires parens)
+    if isinstance(decorator, ast.Name) and decorator.id == "must_use":
+        return "Return value must be used"
+
+    return None
+
+
+@pre(lambda source, must_use_funcs: isinstance(source, str) and len(source) > 0 and isinstance(must_use_funcs, set))
+def find_ignored_calls(source: str, must_use_funcs: set[str]) -> list[tuple[str, int]]:
+    """
+    Find calls to must_use functions whose return values are ignored.
+
+    Returns list of (function_name, line_number) tuples.
+
+    >>> code = '''
+    ... validate(data)
+    ... result = check(x)
+    ... '''
+    >>> find_ignored_calls(code, {"validate", "check"})
+    [('validate', 2)]
+
+    >>> code = '''
+    ... if validate(x):
+    ...     pass
+    ... '''
+    >>> find_ignored_calls(code, {"validate"})
+    []
+    """
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, TypeError, ValueError):
+        return []
+
+    ignored: list[tuple[str, int]] = []
+
+    for node in ast.walk(tree):
+        # Look for expression statements (standalone calls)
+        if not isinstance(node, ast.Expr):
+            continue
+
+        call = node.value
+        if not isinstance(call, ast.Call):
+            continue
+
+        func_name = _get_call_name(call)
+        if func_name and func_name in must_use_funcs:
+            ignored.append((func_name, node.lineno))
+
+    return ignored
+
+
+@pre(lambda call: isinstance(call, ast.Call) and hasattr(call, 'func'))
+@post(lambda result: result is None or isinstance(result, str))
+def _get_call_name(call: ast.Call) -> str | None:
+    """Extract function name from a Call node."""
+    func = call.func
+    if isinstance(func, ast.Name):
+        return func.id
+    if isinstance(func, ast.Attribute):
+        return func.attr
+    return None
+
+
+@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+def check_must_use(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
+    """
+    Check for ignored return values of @must_use functions.
+
+    Examples:
+        >>> from invar.core.models import FileInfo, RuleConfig
+        >>> code = '''
+        ... from invar import must_use
+        ... @must_use("Error must be handled")
+        ... def validate(x): return x
+        ... validate(1)
+        ... '''
+        >>> info = FileInfo(path="test.py", lines=5, symbols=[], is_core=True, source=code)
+        >>> len(check_must_use(info, RuleConfig()))
+        1
+    """
+    violations: list[Violation] = []
+    source = file_info.source
+    if not source:
+        return violations
+
+    must_use_funcs = find_must_use_functions(source)
+    if not must_use_funcs:
+        return violations
+
+    for func_name, line in find_ignored_calls(source, set(must_use_funcs.keys())):
+        reason = must_use_funcs.get(func_name, "Return value must be used")
+        violations.append(Violation(
+            rule="must_use_ignored", severity=Severity.WARNING, file=file_info.path,
+            line=line, message=f"Return value of '{func_name}()' ignored",
+            suggestion=f"Hint: {reason}",
+        ))
+    return violations