invar-tools 1.0.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

invar/core/strategies.py

@@ -26,7 +26,7 @@ class StrategyHint:
     constraints: dict[str, Any] = field(default_factory=dict)
     description: str = ""
 
-    @post(lambda result: isinstance(result, dict))
+    @post(lambda result: all(isinstance(k, str) for k in result))  # Keys are strings
     def to_hypothesis_args(self) -> dict[str, Any]:
         """Convert constraints to Hypothesis strategy arguments.
 
@@ -44,8 +44,7 @@ class StrategyHint:
 _NUMBER_PATTERN = re.compile(r"^-?[0-9]+\.?[0-9]*(?:e[+-]?[0-9]+)?$", re.IGNORECASE)
 
 
-@pre(lambda s: isinstance(s, str) and _NUMBER_PATTERN.match(s.strip()))
-@post(lambda result: isinstance(result, (int, float)))
+@pre(lambda s: _NUMBER_PATTERN.match(s.strip()))  # Valid number format
 def _parse_number(s: str) -> int | float:
     """Parse a number string to int or float.
 
@@ -141,11 +140,8 @@ PATTERNS: list[tuple[str, Callable[[re.Match, str], dict[str, Any] | None]]] = [
 ]
 
 
-@pre(
-    lambda pre_source, param_name, param_type=None: isinstance(pre_source, str)
-    and isinstance(param_name, str)
-)
-@post(lambda result: isinstance(result, StrategyHint))
+@pre(lambda pre_source, param_name, param_type=None: len(param_name) > 0)  # Param must be named
+@post(lambda result: isinstance(result.constraints, dict))  # Returns valid hint
 def infer_from_lambda(
     pre_source: str,
     param_name: str,
@@ -197,10 +193,8 @@ def infer_from_lambda(
     )
 
 
-@pre(
-    lambda pre_sources, param_name, param_type=None: isinstance(pre_sources, list)
-    and isinstance(param_name, str)
-)
+@pre(lambda pre_sources, param_name, param_type=None: len(param_name) > 0)  # Param must be named
+@post(lambda result: isinstance(result.constraints, dict))  # Returns valid hint
 def infer_from_multiple(
     pre_sources: list[str],
     param_name: str,
@@ -232,8 +226,7 @@ def infer_from_multiple(
     )
 
 
-@pre(lambda hint: isinstance(hint, StrategyHint))
-@post(lambda result: isinstance(result, str))
+@post(lambda result: ":" in result)  # Format is "name: strategy"
 def format_strategy_hint(hint: StrategyHint) -> str:
     """
     Format a strategy hint as a human-readable string.

invar/core/suggestions.py

@@ -32,6 +32,76 @@ CONSTRAINT_PATTERNS: dict[str, list[str]] = {
     "Optional": ["{name} is not None", "{name}"],
 }
 
+# Return-type-aware @post patterns for redundant_type_contract suggestions
+RETURN_TYPE_POST_PATTERNS: dict[str, str] = {
+    "list[Violation]": '@post(lambda result: all(v.rule == "RULE_NAME" for v in result))',
+    "list": '@post(lambda result: all(<predicate> for item in result))',
+    "dict": "@post(lambda result: all(isinstance(k, <type>) for k in result))",
+    "set": "@post(lambda result: all(<predicate> for item in result))",
+    "int": "@post(lambda result: result >= 0)",
+    "float": "@post(lambda result: result >= 0.0)",
+    "str": "@post(lambda result: len(result) > 0)",
+    "bool": "@post(lambda result: <semantic_predicate>)",
+    "None": "",  # No meaningful @post for None return
+}
+
+
+@post(lambda result: result is None or isinstance(result, str))
+def extract_return_type(signature: str) -> str | None:
+    """Extract return type from function signature.
+
+    Examples:
+        >>> extract_return_type("(x: int) -> list[Violation]")
+        'list[Violation]'
+        >>> extract_return_type("(x: int) -> int")
+        'int'
+        >>> extract_return_type("(x: int) -> None")
+        'None'
+        >>> extract_return_type("(x: int)")
+        >>> extract_return_type("()")
+    """
+    if not signature or "->" not in signature:
+        return None
+    match = re.search(r"->\s*(.+)$", signature)
+    if match:
+        return match.group(1).strip()
+    return None
+
+
+@pre(lambda return_type: return_type is None or isinstance(return_type, str))
+@post(lambda result: isinstance(result, str))
+def generate_post_suggestion(return_type: str | None) -> str:
+    """Generate @post suggestion based on return type.
+
+    Examples:
+        >>> generate_post_suggestion("list[Violation]")
+        '@post(lambda result: all(v.rule == "RULE_NAME" for v in result))'
+        >>> generate_post_suggestion("int")
+        '@post(lambda result: result >= 0)'
+        >>> generate_post_suggestion("bool")
+        '@post(lambda result: <semantic_predicate>)'
+        >>> generate_post_suggestion("CustomType")
+        '@post(lambda result: <condition>)'
+        >>> generate_post_suggestion(None)
+        '@post(lambda result: <condition>)'
+    """
+    if not return_type:
+        return "@post(lambda result: <condition>)"
+
+    # Exact match
+    if return_type in RETURN_TYPE_POST_PATTERNS:
+        pattern = RETURN_TYPE_POST_PATTERNS[return_type]
+        return pattern if pattern else "@post(lambda result: <condition>)"
+
+    # Generic match (list[X], dict[K,V], etc.)
+    base_match = re.match(r"^(list|dict|set)\[", return_type)
+    if base_match:
+        base = base_match.group(1)
+        if base in RETURN_TYPE_POST_PATTERNS:
+            return RETURN_TYPE_POST_PATTERNS[base]
+
+    return "@post(lambda result: <condition>)"
+
 
 @pre(lambda signature: signature.startswith("(") or signature == "")
 def generate_contract_suggestion(signature: str) -> str:
@@ -65,6 +135,8 @@ def generate_contract_suggestion(signature: str) -> str:
     for name, type_hint in params:
         if not name:  # Skip empty names from malformed signatures
             continue
+        if name in ("self", "cls"):  # Skip method receiver parameters
+            continue
         param_names.append(name)
         if not type_hint:
             continue
@@ -86,6 +158,10 @@ def _extract_params(signature: str) -> list[tuple[str, str | None]]:
     """
     Extract parameters and their types from a signature.
 
+    MINOR-2 Limitation: Uses naive comma splitting which breaks for complex types
+    like Callable[[int, str], bool] where commas appear inside nested brackets.
+    This is acceptable since suggestions are advisory, not strict validation.
+
     Examples:
         >>> _extract_params("(x: int, y: str) -> bool")
         [('x', 'int'), ('y', 'str')]
@@ -284,6 +360,7 @@ def format_suggestion_for_violation(symbol: Symbol, violation_type: str) -> str:
     Phase 9.2 P4: Generate lambda skeletons when no type-based suggestion available.
     P7: Added semantic_tautology support.
     P27: Show pattern alternatives (Guard provides options, Agent decides).
+    DX-XX: Return-type-aware @post suggestions for redundant_type_contract.
 
     Examples:
         >>> from invar.core.models import Symbol, SymbolKind
@@ -300,6 +377,12 @@ def format_suggestion_for_violation(symbol: Symbol, violation_type: str) -> str:
         >>> msg2 = format_suggestion_for_violation(sym2, "missing_contract")
         >>> "@pre(lambda data, config: <condition>)" in msg2
         True
+        >>> # Return-type-aware @post for redundant_type_contract
+        >>> sym3 = Symbol(name="check", kind=SymbolKind.FUNCTION, line=1, end_line=5,
+        ...     signature="(x: int) -> list[Violation]")
+        >>> msg3 = format_suggestion_for_violation(sym3, "redundant_type_contract")
+        >>> 'all(v.rule ==' in msg3
+        True
     """
     if symbol.kind not in (SymbolKind.FUNCTION, SymbolKind.METHOD):
         return ""
@@ -316,6 +399,15 @@ def format_suggestion_for_violation(symbol: Symbol, violation_type: str) -> str:
     patterns = generate_pattern_options(sig)
     suggestion = generate_contract_suggestion(sig)
 
+    # For redundant_type_contract, include return-type-aware @post suggestion
+    if violation_type == "redundant_type_contract":
+        return_type = extract_return_type(sig)
+        post_suggestion = generate_post_suggestion(return_type)
+        if suggestion:
+            full_suggestion = f"{suggestion}\n  or {post_suggestion}"
+            return _format_with_patterns(suggestion_prefix, full_suggestion, patterns)
+        return f"{skeleton_prefix}{post_suggestion}"
+
     if suggestion:
         return _format_with_patterns(suggestion_prefix, suggestion, patterns)
 

invar/core/sync_helpers.py

@@ -0,0 +1,238 @@
+"""
+DX-56: Pure sync helper functions.
+
+Core module: Pure logic for template sync operations.
+No I/O - only data transformation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from deal import post, pre
+
+if TYPE_CHECKING:
+    from invar.core.template_parser import ParsedFile
+
+
+# =============================================================================
+# Data Types
+# =============================================================================
+
+
+@dataclass
+class SyncConfig:
+    """Configuration for template sync operation.
+
+    Examples:
+        >>> config = SyncConfig()
+        >>> config.syntax
+        'cli'
+        >>> config.inject_project_additions
+        False
+
+        >>> config = SyncConfig(syntax="mcp", force=True)
+        >>> config.syntax
+        'mcp'
+        >>> config.force
+        True
+
+        >>> config = SyncConfig(skip_patterns=[".claude/skills/*"])
+        >>> config.skip_patterns
+        ['.claude/skills/*']
+    """
+
+    syntax: str = "cli"  # "cli" or "mcp"
+    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
+
+
+@dataclass
+class SyncReport:
+    """Result of sync operation.
+
+    Examples:
+        >>> report = SyncReport()
+        >>> report.created
+        []
+        >>> len(report.updated)
+        0
+
+        >>> report = SyncReport(created=["INVAR.md"], updated=["CLAUDE.md"])
+        >>> report.created
+        ['INVAR.md']
+    """
+
+    created: list[str] = field(default_factory=list)
+    updated: list[str] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+# =============================================================================
+# Manifest Helpers
+# =============================================================================
+
+
+@pre(lambda path, patterns: len(path) > 0 and isinstance(patterns, list))
+@post(lambda result: isinstance(result, bool))
+def should_skip_file(path: str, patterns: list[str]) -> bool:
+    """Check if path should be skipped based on skip patterns.
+
+    Examples:
+        >>> should_skip_file(".claude/skills/develop/SKILL.md", [".claude/skills/*"])
+        True
+        >>> should_skip_file("CLAUDE.md", [".claude/skills/*"])
+        False
+        >>> should_skip_file("INVAR.md", [])
+        False
+    """
+    return any(matches_glob_pattern(path, pattern) for pattern in patterns)
+
+
+@pre(lambda path, pattern: len(path) > 0 and len(pattern) > 0)
+@post(lambda result: isinstance(result, bool))
+def matches_glob_pattern(path: str, pattern: str) -> bool:
+    """Check if path matches a simple glob pattern with *.
+
+    Examples:
+        >>> matches_glob_pattern(".claude/skills/develop/SKILL.md", ".claude/skills/*/SKILL.md")
+        True
+        >>> matches_glob_pattern(".claude/skills/review/SKILL.md", ".claude/skills/*/SKILL.md")
+        True
+        >>> matches_glob_pattern("CLAUDE.md", ".claude/skills/*/SKILL.md")
+        False
+        >>> matches_glob_pattern("INVAR.md", "INVAR.md")
+        True
+    """
+    if "*" not in pattern:
+        return path == pattern
+
+    parts = pattern.split("*")
+    if len(parts) != 2:
+        return False
+
+    prefix, suffix = parts
+    return path.startswith(prefix) and path.endswith(suffix)
+
+
+@pre(lambda manifest: "templates" in manifest or "sync" in manifest)
+@post(lambda result: isinstance(result, tuple) and len(result) == 3)
+def get_sync_file_lists(
+    manifest: dict,
+) -> tuple[list[tuple[str, str]], list[tuple[str, str]], list[str]]:
+    """Extract file lists from manifest for sync operations.
+
+    Returns:
+        Tuple of (fully_managed, region_managed, create_only) file lists.
+        - fully_managed: List of (dest, src) tuples for full overwrite
+        - region_managed: List of (dest, src) tuples for region-based updates
+        - create_only: List of destination paths created once
+
+    Examples:
+        >>> manifest = {
+        ...     "sync": {
+        ...         "fully_managed": ["INVAR.md"],
+        ...         "region_managed": ["CLAUDE.md"],
+        ...         "create_only": [".invar/context.md"],
+        ...     },
+        ...     "templates": {
+        ...         "INVAR.md": {"src": "protocol/INVAR.md", "type": "copy"},
+        ...         "CLAUDE.md": {"src": "config/CLAUDE.md.jinja", "type": "jinja"},
+        ...     }
+        ... }
+        >>> fm, rm, co = get_sync_file_lists(manifest)
+        >>> len(fm)
+        1
+        >>> fm[0][0]
+        'INVAR.md'
+    """
+    sync_config = manifest.get("sync", {})
+    templates = manifest.get("templates", {})
+
+    fully_managed = []
+    for dest in sync_config.get("fully_managed", []):
+        if dest in templates:
+            fully_managed.append((dest, templates[dest].get("src", "")))
+
+    region_managed = []
+    for dest in sync_config.get("region_managed", []):
+        if dest in templates:
+            region_managed.append((dest, templates[dest].get("src", "")))
+        elif "*" in dest:
+            # Handle glob patterns like ".claude/skills/*/SKILL.md"
+            for template_dest, template_config in templates.items():
+                if matches_glob_pattern(template_dest, dest):
+                    region_managed.append((template_dest, template_config.get("src", "")))
+
+    create_only = sync_config.get("create_only", [])
+
+    return fully_managed, region_managed, create_only
+
+
+@pre(lambda manifest, file_path: "regions" in manifest and len(file_path) > 0)
+def get_region_config(manifest: dict, file_path: str) -> dict[str, dict] | None:
+    """Get region configuration for a file from manifest.
+
+    Examples:
+        >>> manifest = {
+        ...     "regions": {
+        ...         "CLAUDE.md": {
+        ...             "managed": {"action": "overwrite"},
+        ...             "user": {"action": "preserve"},
+        ...         }
+        ...     }
+        ... }
+        >>> config = get_region_config(manifest, "CLAUDE.md")
+        >>> config["managed"]["action"]
+        'overwrite'
+        >>> get_region_config(manifest, "unknown.md") is None
+        True
+    """
+    regions = manifest.get("regions", {})
+
+    # Direct match
+    if file_path in regions:
+        return regions[file_path]
+
+    # Glob pattern match
+    for pattern, config in regions.items():
+        if matches_glob_pattern(file_path, pattern):
+            return config
+
+    return None
+
+
+@pre(lambda parsed: hasattr(parsed, "regions"))
+def detect_region_scheme(parsed: ParsedFile) -> tuple[str, str] | None:
+    """Detect the region scheme from parsed file.
+
+    Returns (primary_region, user_region) or None if no known scheme.
+
+    Examples:
+        >>> from invar.core.template_parser import ParsedFile, Region
+        >>> p = ParsedFile(regions={"managed": Region("managed", 0, 10, "")})
+        >>> detect_region_scheme(p)
+        ('managed', 'user')
+        >>> p2 = ParsedFile(regions={"skill": Region("skill", 0, 10, "")})
+        >>> detect_region_scheme(p2)
+        ('skill', 'extensions')
+        >>> p3 = ParsedFile(regions={})
+        >>> detect_region_scheme(p3) is None
+        True
+    """
+    # Known schemes
+    schemes = {
+        "managed": ("managed", "user"),
+        "skill": ("skill", "extensions"),
+    }
+
+    for primary, scheme in schemes.items():
+        if primary in parsed.regions:
+            return scheme
+
+    return None

invar/core/tautology.py

@@ -24,6 +24,11 @@ def is_semantic_tautology(expression: str) -> tuple[bool, str]:
     - x or True (always true due to True)
     - True and x (simplifies but starts with True)
 
+    DX-38 Tier 1: Also detects obvious violations:
+    - lambda x: True (no constraint)
+    - lambda x: False (contradiction)
+    - lambda: ... (no parameters - doesn't validate function inputs)
+
     Examples:
         >>> is_semantic_tautology("lambda x: x == x")
         (True, 'x == x is always True')
@@ -35,6 +40,16 @@ def is_semantic_tautology(expression: str) -> tuple[bool, str]:
         (False, '')
         >>> is_semantic_tautology("lambda x: x or True")
         (True, 'expression contains unconditional True')
+        >>> is_semantic_tautology("lambda x: True")
+        (True, 'contract always returns True (no constraint)')
+        >>> is_semantic_tautology("lambda x: False")
+        (True, 'contract always returns False (contradiction - will always fail)')
+        >>> is_semantic_tautology("lambda: len([1,2]) > 0")
+        (True, "contract has no parameters (doesn't validate function inputs)")
+        >>> is_semantic_tautology("lambda result: result or not result")
+        (True, "'result or not result' is always True (tautology)")
+        >>> is_semantic_tautology("lambda x: x and not x")
+        (True, "'x and not x' is always False (contradiction)")
     """
     if not expression.strip():
         return (False, "")
@@ -43,63 +58,114 @@ def is_semantic_tautology(expression: str) -> tuple[bool, str]:
         lambda_node = find_lambda(tree)
         if lambda_node is None:
             return (False, "")
+
+        # DX-38 Tier 1: Check for no-parameter lambda
+        args = lambda_node.args
+        if not args.args and not args.posonlyargs and not args.kwonlyargs and not args.vararg and not args.kwarg:
+            return (True, "contract has no parameters (doesn't validate function inputs)")
+
         return _check_tautology_patterns(lambda_node.body)
     except (SyntaxError, TypeError, ValueError):
         return (False, "")
 
 
-@post(lambda result: isinstance(result, tuple) and len(result) == 2)
-def _check_tautology_patterns(node: ast.expr) -> tuple[bool, str]:
-    """Check for common tautology patterns in AST node."""
-    # Identity comparison pattern (e.g., x == x)
-    if (
-        isinstance(node, ast.Compare)
-        and len(node.ops) == 1
-        and isinstance(node.ops[0], (ast.Eq, ast.Is))
-    ):
-        left = ast.unparse(node.left)
-        right = ast.unparse(node.comparators[0])
+@pre(lambda node: isinstance(node, ast.expr))
+def _check_literal_patterns(node: ast.expr) -> tuple[bool, str] | None:
+    """Check for literal True/False patterns."""
+    if isinstance(node, ast.Constant) and node.value is True:
+        return (True, "contract always returns True (no constraint)")
+    if isinstance(node, ast.Constant) and node.value is False:
+        return (True, "contract always returns False (contradiction - will always fail)")
+    return None
+
+
+@pre(lambda node: isinstance(node, ast.expr))
+def _check_comparison_patterns(node: ast.expr) -> tuple[bool, str] | None:
+    """Check for identity and len >= 0 patterns."""
+    if not isinstance(node, ast.Compare) or len(node.ops) != 1:
+        return None
+    # Identity comparison pattern
+    if isinstance(node.ops[0], (ast.Eq, ast.Is)):
+        left, right = ast.unparse(node.left), ast.unparse(node.comparators[0])
         if left == right:
             return (True, f"{left} == {right} is always True")
-
-    # Length non-negative pattern (e.g., len(x) >= 0)
-    if isinstance(node, ast.Compare) and len(node.ops) == 1 and len(node.comparators) == 1:
-        left = node.left
-        op = node.ops[0]
-        right = node.comparators[0]
-        if (
-            isinstance(left, ast.Call)
-            and isinstance(left.func, ast.Name)
-            and left.func.id == "len"
-            and isinstance(op, ast.GtE)
-            and isinstance(right, ast.Constant)
-            and right.value == 0
-        ):
+    # Length non-negative pattern
+    if len(node.comparators) == 1:
+        left, op, right = node.left, node.ops[0], node.comparators[0]
+        if (isinstance(left, ast.Call) and isinstance(left.func, ast.Name) and
+            left.func.id == "len" and isinstance(op, ast.GtE) and
+            isinstance(right, ast.Constant) and right.value == 0):
             arg = ast.unparse(left.args[0]) if left.args else "x"
             return (True, f"len({arg}) >= 0 is always True for any sequence")
+    return None
+
 
-    # isinstance with object pattern (always True)
-    if (
-        isinstance(node, ast.Call)
-        and isinstance(node.func, ast.Name)
-        and node.func.id == "isinstance"
-        and len(node.args) == 2
-    ):
+@pre(lambda node: isinstance(node, ast.expr))
+def _check_isinstance_object(node: ast.expr) -> tuple[bool, str] | None:
+    """Check for isinstance(x, object) pattern."""
+    if (isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and
+        node.func.id == "isinstance" and len(node.args) == 2):
         type_arg = node.args[1]
         if isinstance(type_arg, ast.Name) and type_arg.id == "object":
-            arg = ast.unparse(node.args[0])
-            return (True, f"isinstance({arg}, object) is always True")
+            return (True, f"isinstance({ast.unparse(node.args[0])}, object) is always True")
+    return None
 
-    # Pattern: x or True, True or x (always true)
-    if isinstance(node, ast.BoolOp) and isinstance(node.op, ast.Or):
+
+@pre(lambda node: isinstance(node, ast.expr))
+def _check_boolop_patterns(node: ast.expr) -> tuple[bool, str] | None:
+    """Check for boolean operation patterns: x or True, x or not x, x and not x."""
+    if not isinstance(node, ast.BoolOp):
+        return None
+    if isinstance(node.op, ast.Or):
+        # x or True
         for val in node.values:
             if isinstance(val, ast.Constant) and val.value is True:
                 return (True, "expression contains unconditional True")
+        # Complement tautology pattern
+        values_unparsed = {ast.unparse(v): v for v in node.values}
+        for val in node.values:
+            if isinstance(val, ast.UnaryOp) and isinstance(val.op, ast.Not):
+                negated = ast.unparse(val.operand)
+                if negated in values_unparsed:
+                    return (True, f"'{negated} or not {negated}' is always True (tautology)")
+    if isinstance(node.op, ast.And):
+        # Complement contradiction pattern
+        values_unparsed = {ast.unparse(v): v for v in node.values}
+        for val in node.values:
+            if isinstance(val, ast.UnaryOp) and isinstance(val.op, ast.Not):
+                negated = ast.unparse(val.operand)
+                if negated in values_unparsed:
+                    return (True, f"'{negated} and not {negated}' is always False (contradiction)")
+    return None
+
+
+@pre(lambda node: isinstance(node, ast.expr) and hasattr(node, '__class__'))
+@post(lambda result: isinstance(result, tuple) and len(result) == 2)
+def _check_tautology_patterns(node: ast.expr) -> tuple[bool, str]:
+    """Check for common tautology patterns in AST node.
 
+    DX-38 Tier 1: Detects obvious violations:
+    - Literal True (always passes, no constraint)
+    - Literal False (always fails, contradiction)
+    - x == x, len(x) >= 0, isinstance(x, object), x or True
+    - x or not x (tautology), x and not x (contradiction)
+
+    Examples:
+        >>> import ast
+        >>> _check_tautology_patterns(ast.Constant(value=True))
+        (True, 'contract always returns True (no constraint)')
+        >>> _check_tautology_patterns(ast.Constant(value=False))
+        (True, 'contract always returns False (contradiction - will always fail)')
+    """
+    for checker in [_check_literal_patterns, _check_comparison_patterns,
+                    _check_isinstance_object, _check_boolop_patterns]:
+        result = checker(node)
+        if result:
+            return result
     return (False, "")
 
 
-@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+@pre(lambda file_info, config: len(file_info.path) > 0)
 def check_semantic_tautology(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     """Check for semantic tautology contracts. Core files only.