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

invar/core/review_trigger.py

@@ -0,0 +1,298 @@
+"""
+Review trigger detection for DX-30 Visible Workflow and DX-31 Independent Adversarial Reviewer.
+
+DX-30: Contract quality ratio check (80% threshold)
+DX-31: Independent review triggers (escape count, coverage, security)
+
+Core module: pure logic, no I/O.
+"""
+
+from __future__ import annotations
+
+import re
+
+from deal import post, pre
+
+from invar.core.entry_points import count_escape_hatches
+from invar.core.models import FileInfo, RuleConfig, Severity, SymbolKind, Violation
+
+# DX-31: Security-sensitive path patterns that trigger review suggestion
+# Split into two groups to reduce false positives:
+
+# Patterns safe to match as substrings (authentication, cryptography are valid matches)
+SECURITY_SUBSTRING_PATTERNS: tuple[str, ...] = (
+    "auth",       # authentication, authorize, authority
+    "crypt",      # cryptography, encrypt, decrypt
+    "secret",
+    "password",
+    "credential",
+    "permission",
+)
+
+# Patterns that must be exact word matches (to avoid keyboard, tokenizer, accessory)
+SECURITY_WORD_PATTERNS: tuple[str, ...] = (
+    "token",      # not tokenizer
+    "key",        # not keyboard, monkey
+    "session",    # not obsession
+    "access",     # not accessory
+)
+
+
+@pre(lambda file_info: isinstance(file_info, FileInfo))
+@post(lambda result: isinstance(result, tuple) and len(result) == 3)
+def calculate_contract_ratio(file_info: FileInfo) -> tuple[float, int, int]:
+    """
+    Calculate contract coverage ratio for a file (DX-31).
+
+    Returns (ratio, total_functions, with_contracts).
+    Only counts public functions (not starting with _).
+
+    Examples:
+        >>> from invar.core.models import Contract, Symbol, SymbolKind
+        >>> # No functions
+        >>> empty = FileInfo(path="empty.py", lines=10)
+        >>> calculate_contract_ratio(empty)
+        (1.0, 0, 0)
+        >>> # 100% coverage
+        >>> c = Contract(kind="pre", expression="x > 0", line=1)
+        >>> sym = Symbol(name="calc", kind=SymbolKind.FUNCTION, line=1, end_line=5, contracts=[c])
+        >>> full = FileInfo(path="full.py", lines=10, symbols=[sym])
+        >>> calculate_contract_ratio(full)
+        (1.0, 1, 1)
+        >>> # 0% coverage
+        >>> sym_no = Symbol(name="calc", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> none = FileInfo(path="none.py", lines=10, symbols=[sym_no])
+        >>> calculate_contract_ratio(none)
+        (0.0, 1, 0)
+        >>> # Private functions ignored
+        >>> priv = Symbol(name="_helper", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> private_only = FileInfo(path="priv.py", lines=10, symbols=[priv])
+        >>> calculate_contract_ratio(private_only)
+        (1.0, 0, 0)
+    """
+    # Only check public functions (not starting with _)
+    # MINOR-9: This excludes dunder methods (__init__, __str__, etc.) which is intentional.
+    # Dunder methods are boilerplate; public API methods are the focus of contract coverage.
+    functions = [
+        s for s in file_info.symbols
+        if s.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD) and not s.name.startswith("_")
+    ]
+
+    if not functions:
+        return (1.0, 0, 0)
+
+    total = len(functions)
+    with_contracts = sum(1 for f in functions if f.contracts)
+    ratio = with_contracts / total
+
+    return (ratio, total, with_contracts)
+
+
+@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+def check_contract_quality_ratio(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
+    """
+    Check contract coverage ratio in Core files (DX-30).
+
+    WARNING if less than 80% of public functions have @pre or @post.
+    This encourages "Contract before Implement" workflow.
+
+    Examples:
+        >>> # Shell file - no check
+        >>> shell_info = FileInfo(path="shell/cli.py", lines=50, is_shell=True)
+        >>> check_contract_quality_ratio(shell_info, RuleConfig())
+        []
+        >>> # Core file with 100% coverage - pass
+        >>> from invar.core.models import Contract, Symbol
+        >>> c = Contract(kind="pre", expression="x > 0", line=1)
+        >>> sym = Symbol(name="calc", kind=SymbolKind.FUNCTION, line=1, end_line=5, contracts=[c])
+        >>> core_ok = FileInfo(path="core/calc.py", lines=50, symbols=[sym], is_core=True)
+        >>> check_contract_quality_ratio(core_ok, RuleConfig())
+        []
+        >>> # Core file with 0% coverage - warning
+        >>> sym_no = Symbol(name="calc", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> core_bad = FileInfo(path="core/calc.py", lines=50, symbols=[sym_no], is_core=True)
+        >>> vs = check_contract_quality_ratio(core_bad, RuleConfig())
+        >>> len(vs) == 1 and vs[0].rule == "contract_quality_ratio"
+        True
+    """
+    violations: list[Violation] = []
+
+    if not file_info.is_core:
+        return violations
+
+    ratio, total, with_contracts = calculate_contract_ratio(file_info)
+
+    if total == 0:
+        return violations
+
+    if ratio < 0.8:
+        pct = int(ratio * 100)
+        violations.append(
+            Violation(
+                rule="contract_quality_ratio",
+                severity=Severity.WARNING,
+                file=file_info.path,
+                line=None,
+                message=f"Contract coverage: {pct}% ({with_contracts}/{total}). Target: 80%+",
+                suggestion="Add @pre/@post to public functions. See INVAR.md 'Visible Workflow'",
+            )
+        )
+
+    return violations
+
+
+@pre(lambda path: isinstance(path, str))
+@post(lambda result: isinstance(result, bool))
+def is_security_sensitive(path: str) -> bool:
+    """
+    Check if path indicates security-sensitive code (DX-31).
+
+    Uses two-tier matching to reduce false positives:
+    - Substring matching for unambiguous patterns (auth, crypt, secret, etc.)
+    - Word-exact matching for ambiguous patterns (key, token, access, session)
+
+    Examples:
+        >>> # Substring patterns (auth, crypt, secret, password, credential, permission)
+        >>> is_security_sensitive("src/auth/login.py")
+        True
+        >>> is_security_sensitive("src/authentication.py")
+        True
+        >>> is_security_sensitive("src/core/crypto.py")
+        True
+        >>> is_security_sensitive("src/utils/helpers.py")
+        False
+
+        >>> # Word-exact patterns (token, key, session, access)
+        >>> is_security_sensitive("src/token_handler.py")
+        True
+        >>> is_security_sensitive("src/api_key.py")
+        True
+        >>> is_security_sensitive("src/access_control.py")
+        True
+
+        >>> # False positive prevention
+        >>> is_security_sensitive("src/tokenizer.py")
+        False
+        >>> is_security_sensitive("src/keyboard.py")
+        False
+        >>> is_security_sensitive("src/monkey.py")
+        False
+        >>> is_security_sensitive("src/accessory.py")
+        False
+        >>> is_security_sensitive("src/hockey.py")
+        False
+
+        >>> # Edge cases
+        >>> is_security_sensitive("")
+        False
+    """
+    if not path:
+        return False
+
+    path_lower = path.lower()
+
+    # Check substring patterns (safe, low false positive rate)
+    if any(pattern in path_lower for pattern in SECURITY_SUBSTRING_PATTERNS):
+        return True
+
+    # Check word-exact patterns (split path into words first)
+    words = re.split(r"[/_.\-\\]", path_lower)
+    return any(word in SECURITY_WORD_PATTERNS for word in words)
+
+
+@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+def check_review_suggested(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
+    """
+    Suggest independent review when conditions warrant (DX-31).
+
+    Triggers review suggestion for Core files when:
+    - escape_count >= 3: Multiple escape hatches indicate complexity
+    - contract_ratio < 50%: Low contract coverage needs review
+    - security-sensitive path: Security code needs extra scrutiny
+
+    Examples:
+        >>> from invar.core.models import Contract, Symbol, SymbolKind
+        >>> # Shell file - no check
+        >>> shell = FileInfo(path="shell/cli.py", lines=50, is_shell=True)
+        >>> check_review_suggested(shell, RuleConfig())
+        []
+        >>> # Core file with no triggers - pass
+        >>> c = Contract(kind="pre", expression="x > 0", line=1)
+        >>> sym = Symbol(name="calc", kind=SymbolKind.FUNCTION, line=1, end_line=5, contracts=[c])
+        >>> core_ok = FileInfo(path="core/calc.py", lines=50, symbols=[sym], is_core=True)
+        >>> check_review_suggested(core_ok, RuleConfig())
+        []
+        >>> # Security-sensitive path - warning
+        >>> auth = FileInfo(path="core/auth/login.py", lines=50, is_core=True, source="")
+        >>> vs = check_review_suggested(auth, RuleConfig())
+        >>> len(vs) == 1 and vs[0].rule == "review_suggested"
+        True
+        >>> # Low contract ratio - warning
+        >>> sym_no = Symbol(name="calc", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> low = FileInfo(path="core/calc.py", lines=50, symbols=[sym_no], is_core=True)
+        >>> vs = check_review_suggested(low, RuleConfig())
+        >>> len(vs) == 1 and "contract" in vs[0].message.lower()
+        True
+        >>> # Multiple escape hatches - warning
+        >>> source = '''
+        ... # @invar:allow rule1: reason1
+        ... # @invar:allow rule2: reason2
+        ... # @invar:allow rule3: reason3
+        ... '''
+        >>> escapes = FileInfo(path="core/complex.py", lines=50, is_core=True, source=source, symbols=[sym])
+        >>> vs = check_review_suggested(escapes, RuleConfig())
+        >>> len(vs) == 1 and "escape" in vs[0].message.lower()
+        True
+    """
+    violations: list[Violation] = []
+
+    # Only check Core files
+    if not file_info.is_core:
+        return violations
+
+    # Trigger 1: Security-sensitive path
+    if is_security_sensitive(file_info.path):
+        violations.append(
+            Violation(
+                rule="review_suggested",
+                severity=Severity.WARNING,
+                file=file_info.path,
+                line=None,
+                message=f"Security-sensitive file: {file_info.path}",
+                suggestion="Consider independent /review before task completion",
+            )
+        )
+        return violations  # Only one suggestion per file
+
+    # Trigger 2: Multiple escape hatches (>= 3)
+    source = file_info.source or ""
+    escape_count = count_escape_hatches(source)
+    if escape_count >= 3:
+        violations.append(
+            Violation(
+                rule="review_suggested",
+                severity=Severity.WARNING,
+                file=file_info.path,
+                line=None,
+                message=f"High escape hatch count: {escape_count} @invar:allow markers",
+                suggestion="Consider independent /review to validate escape justifications",
+            )
+        )
+        return violations  # Only one suggestion per file
+
+    # Trigger 3: Low contract ratio (< 50%)
+    ratio, total, _ = calculate_contract_ratio(file_info)
+    if total > 0 and ratio < 0.5:
+        pct = int(ratio * 100)
+        violations.append(
+            Violation(
+                rule="review_suggested",
+                severity=Severity.WARNING,
+                file=file_info.path,
+                line=None,
+                message=f"Low contract coverage: {pct}% (threshold: 50%)",
+                suggestion="Add contracts, or request independent /review to assess quality",
+            )
+        )
+
+    return violations

invar/core/rule_meta.py

@@ -142,11 +142,43 @@ RULE_META: dict[str, RuleMeta] = {
     # Shell rules
     "shell_result": RuleMeta(
         name="shell_result",
-        severity=Severity.WARNING,
+        severity=Severity.ERROR,  # DX-22: Architecture rule, must fix or explain
         category=RuleCategory.SHELL,
         detects="Shell function not returning Result[T, E]",
         cannot_detect=("Result usage correctness", "Error handling quality"),
-        hint="Wrap return value with Success() or return Failure()",
+        hint="Wrap with Success()/Failure(), or add: # @invar:allow shell_result: <reason>",
+    ),
+    "entry_point_too_thick": RuleMeta(
+        name="entry_point_too_thick",
+        severity=Severity.ERROR,  # DX-22: Architecture rule, must fix or explain
+        category=RuleCategory.SHELL,
+        detects="Entry point (Flask route, Typer command, etc.) exceeds max lines",
+        cannot_detect=("Whether complexity is unavoidable", "Framework constraints"),
+        hint="Move logic to Shell function, or add: # @invar:allow entry_point_too_thick: <reason>",
+    ),
+    "shell_pure_logic": RuleMeta(
+        name="shell_pure_logic",
+        severity=Severity.WARNING,
+        category=RuleCategory.SHELL,
+        detects="Shell function with no I/O operations (pure logic belongs in Core)",
+        cannot_detect=("Indirect I/O via method calls", "Framework-specific patterns"),
+        hint="Move to Core layer and add @pre/@post contracts, or add: # @shell_orchestration: <reason>",
+    ),
+    "shell_too_complex": RuleMeta(
+        name="shell_too_complex",
+        severity=Severity.INFO,
+        category=RuleCategory.SHELL,
+        detects="Shell function with excessive branching complexity",
+        cannot_detect=("Whether complexity is justified", "Domain-specific patterns"),
+        hint="Extract logic to Core, or add: # @shell_complexity: <reason>",
+    ),
+    "shell_complexity_debt": RuleMeta(
+        name="shell_complexity_debt",
+        severity=Severity.ERROR,
+        category=RuleCategory.SHELL,
+        detects="Project accumulated too many unaddressed complexity warnings (DX-22 Fix-or-Explain)",
+        cannot_detect=("Individual function justifications",),
+        hint="Address shell_too_complex warnings: refactor OR add @shell_complexity: markers",
     ),
     # Documentation rules
     "missing_doctest": RuleMeta(
@@ -157,6 +189,33 @@ RULE_META: dict[str, RuleMeta] = {
         cannot_detect=("Doctest quality", "Edge case coverage"),
         hint="Add >>> examples showing typical usage and edge cases",
     ),
+    # DX-28: Skip abuse prevention
+    "skip_without_reason": RuleMeta(
+        name="skip_without_reason",
+        severity=Severity.WARNING,
+        category=RuleCategory.CONTRACTS,
+        detects="@skip_property_test used without justification reason",
+        cannot_detect=("Whether the reason is valid", "Skip abuse patterns"),
+        hint='Add reason: @skip_property_test("category: explanation")',
+    ),
+    # DX-30: Contract coverage ratio
+    "contract_quality_ratio": RuleMeta(
+        name="contract_quality_ratio",
+        severity=Severity.WARNING,
+        category=RuleCategory.CONTRACTS,
+        detects="Core file with less than 80% contract coverage on public functions",
+        cannot_detect=("Contract quality", "Whether contracts are meaningful"),
+        hint="Add @pre/@post to public functions. Use Phase TodoList for complex tasks",
+    ),
+    # DX-31: Review suggestion trigger
+    "review_suggested": RuleMeta(
+        name="review_suggested",
+        severity=Severity.WARNING,
+        category=RuleCategory.DOCS,
+        detects="Conditions warranting independent code review (escape count, coverage, security)",
+        cannot_detect=("Whether review was performed", "Review quality"),
+        hint="Consider independent /review sub-agent before task completion",
+    ),
 }
 
 

invar/core/rules.py

@@ -12,11 +12,21 @@ from invar.core.contracts import (
     check_partial_contract,
     check_redundant_type_contracts,
     check_semantic_tautology,
+    check_skip_without_reason,  # DX-28
 )
+from invar.core.entry_points import 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.must_use import check_must_use
 from invar.core.purity import check_impure_calls, check_internal_imports
+from invar.core.review_trigger import (
+    check_contract_quality_ratio,  # DX-30
+    check_review_suggested,  # DX-31
+)
+from invar.core.shell_architecture import (
+    check_shell_pure_logic,
+    check_shell_too_complex,
+)
 from invar.core.suggestions import format_suggestion_for_violation
 from invar.core.utils import get_excluded_rules
 
@@ -105,8 +115,8 @@ def check_function_size(file_info: FileInfo, config: RuleConfig) -> list[Violati
     """
     Check if any function exceeds maximum line count.
 
-    When use_code_lines is True, uses code_lines (excluding docstring).
-    When exclude_doctest_lines is True, subtracts doctest lines from count.
+    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
@@ -121,26 +131,19 @@ def check_function_size(file_info: FileInfo, config: RuleConfig) -> list[Violati
     for symbol in file_info.symbols:
         if symbol.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD):
             total_lines = symbol.end_line - symbol.line + 1
-            # Calculate effective line count based on config
-            if config.use_code_lines and symbol.code_lines is not None:
+            # DX-22: Always use code_lines when available (excluding docstring)
+            if symbol.code_lines is not None:
                 func_lines = symbol.code_lines
                 line_type = "code lines"
             else:
                 func_lines = total_lines
                 line_type = "lines"
-            # Optionally exclude doctest lines
-            if config.exclude_doctest_lines and symbol.doctest_lines > 0:
+            # DX-22: Always exclude doctest lines from size calculation
+            if symbol.doctest_lines > 0:
                 func_lines -= symbol.doctest_lines
                 line_type = f"{line_type} (excl. doctest)"
 
             if func_lines > config.max_function_lines:
-                # P19: Show breakdown if doctest lines exist
-                if symbol.doctest_lines > 0 and not config.exclude_doctest_lines:
-                    code_only = total_lines - symbol.doctest_lines
-                    breakdown = f" ({code_only} code + {symbol.doctest_lines} doctest)"
-                    suggestion = f"Extract helper or set exclude_doctest_lines=true{breakdown}"
-                else:
-                    suggestion = "Extract helper functions"
                 violations.append(
                     Violation(
                         rule="function_size",
@@ -148,7 +151,7 @@ def check_function_size(file_info: FileInfo, config: RuleConfig) -> list[Violati
                         file=file_info.path,
                         line=symbol.line,
                         message=f"Function '{symbol.name}' has {func_lines} {line_type} (max: {config.max_function_lines})",
-                        suggestion=suggestion,
+                        suggestion="Extract helper functions",
                     )
                 )
 
@@ -294,7 +297,10 @@ def check_shell_result(file_info: FileInfo, config: RuleConfig) -> list[Violatio
     """
     Check that Shell functions with return values use Result[T, E].
 
-    Skips: functions returning None (CLI entry points).
+    Skips:
+    - Functions returning None (CLI entry points)
+    - Generators (Iterator/Generator/AsyncIterator/AsyncGenerator)
+    - Entry points (DX-23: framework callbacks like Flask routes, Typer commands)
 
     Examples:
         >>> from invar.core.models import FileInfo, Symbol, SymbolKind, RuleConfig
@@ -314,23 +320,75 @@ def check_shell_result(file_info: FileInfo, config: RuleConfig) -> list[Violatio
         # Skip functions with no return type or returning None
         if "-> None" in symbol.signature or "->" not in symbol.signature:
             continue
-        # Skip generators (Iterator/Generator) - acceptable exception per protocol
-        if "Iterator[" in symbol.signature or "Generator[" in symbol.signature:
+        # Skip generators (Iterator/Generator/AsyncIterator/AsyncGenerator) - acceptable per protocol
+        # MINOR-11: Added async variants
+        if any(
+            pattern in symbol.signature
+            for pattern in ("Iterator[", "Generator[", "AsyncIterator[", "AsyncGenerator[")
+        ):
+            continue
+        # DX-23: Skip entry points; DX-22: Skip if @invar:allow marker
+        if is_entry_point(symbol, file_info.source) or has_allow_marker(symbol, file_info.source, "shell_result"):
             continue
         if "Result[" not in symbol.signature:
             violations.append(
                 Violation(
                     rule="shell_result",
-                    severity=Severity.WARNING,
+                    severity=Severity.ERROR,  # DX-22: Architecture rule
                     file=file_info.path,
                     line=symbol.line,
                     message=f"Shell function '{symbol.name}' should return Result[T, E]",
-                    suggestion="Use Result[T, E] from returns library",
+                    suggestion="Use Result[T, E], or add: # @invar:allow shell_result: <reason>",
                 )
             )
     return violations
 
 
+@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+def check_entry_point_thin(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
+    """
+    Check that entry points are thin (DX-23).
+
+    Entry points should delegate to Shell functions and not contain
+    business logic. They serve as "monad runners" at framework boundaries.
+
+    Examples:
+        >>> from invar.core.models import FileInfo, Symbol, SymbolKind, RuleConfig
+        >>> sym = Symbol(name="index", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> source = '@app.route("/")\\ndef index(): pass'
+        >>> info = FileInfo(path="shell/web.py", lines=10, symbols=[sym], is_shell=True, source=source)
+        >>> check_entry_point_thin(info, RuleConfig())
+        []
+    """
+    violations: list[Violation] = []
+    if not file_info.is_shell:
+        return violations
+
+    max_lines = config.entry_max_lines
+
+    for symbol in file_info.symbols:
+        if symbol.kind != SymbolKind.FUNCTION:
+            continue
+
+        # Only check entry points; DX-22: Skip if @invar:allow marker
+        if not is_entry_point(symbol, file_info.source) or has_allow_marker(symbol, file_info.source, "entry_point_too_thick"):
+            continue
+        lines = get_symbol_lines(symbol)
+        if lines > max_lines:
+            violations.append(
+                Violation(
+                    rule="entry_point_too_thick",
+                    severity=Severity.ERROR,  # DX-22: Architecture rule
+                    file=file_info.path,
+                    line=symbol.line,
+                    message=f"Entry point '{symbol.name}' has {lines} lines (max: {max_lines})",
+                    suggestion="Move logic to Shell function, or add: # @invar:allow entry_point_too_thick: <reason>",
+                )
+            )
+
+    return violations
+
+
 @post(lambda result: len(result) > 0)
 def get_all_rules() -> list[RuleFunc]:
     """
@@ -347,6 +405,9 @@ def get_all_rules() -> list[RuleFunc]:
         check_contracts,
         check_doctests,
         check_shell_result,
+        check_entry_point_thin,  # DX-23
+        check_shell_pure_logic,  # DX-22
+        check_shell_too_complex,  # DX-22
         check_internal_imports,
         check_impure_calls,
         check_empty_contracts,
@@ -355,6 +416,9 @@ def get_all_rules() -> list[RuleFunc]:
         check_param_mismatch,
         check_partial_contract,
         check_must_use,
+        check_skip_without_reason,  # DX-28
+        check_contract_quality_ratio,  # DX-30
+        check_review_suggested,  # DX-31
     ]