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

invar/core/rules.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from collections.abc import Callable
 
-from deal import post, pre
+from deal import post
 
 from invar.core.contracts import (
     check_empty_contracts,
@@ -12,11 +12,16 @@ from invar.core.contracts import (
     check_partial_contract,
     check_redundant_type_contracts,
     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.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.postcondition_scope import check_postcondition_scope
 from invar.core.purity import check_impure_calls, check_internal_imports
+from invar.core.review_trigger import check_contract_quality_ratio, check_review_suggested
+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
 
@@ -48,7 +53,6 @@ def _build_size_suggestion(base: str, extraction_hint: str, func_hint: str) -> s
     return f"{base}{func_hint}" if func_hint else base
 
 
-@pre(lambda file_info: isinstance(file_info, FileInfo))
 @post(lambda result: isinstance(result, str))
 def _get_func_hint(file_info: FileInfo) -> str:
     """Get top 5 largest functions as hint string."""
@@ -59,7 +63,7 @@ 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, config: isinstance(file_info, FileInfo))
+@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.
@@ -100,13 +104,13 @@ def check_file_size(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     return violations
 
 
-@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+@post(lambda result: all(v.rule == "function_size" for v in result))
 def check_function_size(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     """
     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 +125,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,14 +145,14 @@ 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",
                     )
                 )
 
     return violations
 
 
-@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+@post(lambda result: all(v.rule == "forbidden_import" for v in result))
 def check_forbidden_imports(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     """
     Check for forbidden imports in Core files.
@@ -199,7 +196,7 @@ def check_forbidden_imports(file_info: FileInfo, config: RuleConfig) -> list[Vio
     return violations
 
 
-@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+@post(lambda result: all(v.rule == "missing_contract" for v in result))
 def check_contracts(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     """
     Check that public Core functions have contracts.
@@ -220,9 +217,13 @@ def check_contracts(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     if not file_info.is_core or not config.require_contracts:
         return violations
 
+    source = file_info.source or ""
     for symbol in file_info.symbols:
         # Check all functions and methods - agent needs contracts everywhere
         if symbol.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD) and not symbol.contracts:
+            # DX-22: Skip if @invar:allow marker present
+            if has_allow_marker(symbol, source, "missing_contract"):
+                continue
             kind_name = "Method" if symbol.kind == SymbolKind.METHOD else "Function"
             suggestion = format_suggestion_for_violation(symbol, "missing_contract")
             violations.append(
@@ -239,7 +240,7 @@ def check_contracts(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     return violations
 
 
-@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+@post(lambda result: all(v.rule == "missing_doctest" for v in result))
 def check_doctests(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     """
     Check that contracted functions have doctest examples.
@@ -289,12 +290,15 @@ def check_doctests(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     return violations
 
 
-@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+@post(lambda result: all(v.rule == "shell_result" for v in result))
 def check_shell_result(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     """
     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 +318,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
 
 
+@post(lambda result: all(v.rule == "entry_point_too_thick" for v in result))
+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 +403,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,
@@ -354,7 +413,11 @@ def get_all_rules() -> list[RuleFunc]:
         check_redundant_type_contracts,
         check_param_mismatch,
         check_partial_contract,
+        check_postcondition_scope,
         check_must_use,
+        check_skip_without_reason,  # DX-28
+        check_contract_quality_ratio,  # DX-30
+        check_review_suggested,  # DX-31
     ]
 
 
@@ -398,7 +461,7 @@ def _apply_severity_override(v: Violation, overrides: dict[str, str]) -> Violati
     )
 
 
-@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+@post(lambda result: all(v.rule and v.file for v in result) if result else True)
 def check_all_rules(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     """
     Run all rules against a file and collect violations.

invar/core/shell_analysis.py

@@ -0,0 +1,247 @@
+"""
+Shell source analysis helpers for DX-22.
+
+Helper functions for analyzing Shell layer code:
+- I/O operation detection
+- Marker pattern detection
+- Branch counting
+- Symbol source extraction
+
+Core module: pure logic, no I/O.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import TYPE_CHECKING
+
+from deal import post, pre
+
+if TYPE_CHECKING:
+    from invar.core.models import Symbol
+
+# I/O indicators that mark a function as legitimately in Shell
+IO_INDICATORS: frozenset[str] = frozenset([
+    # File operations
+    ".read(",
+    ".write(",
+    ".read_text(",
+    ".write_text(",
+    ".read_bytes(",
+    ".write_bytes(",
+    "open(",
+    "Path(",
+    ".exists()",
+    ".is_file()",
+    ".is_dir()",
+    ".rglob(",
+    ".glob(",
+    ".iterdir(",
+    ".mkdir(",
+    ".unlink(",
+    "shutil.",
+    "tempfile.",
+    # Process operations
+    "subprocess.",
+    "os.system(",
+    "os.popen(",
+    "os.getenv(",
+    "os.environ",
+    # Terminal/System
+    "sys.stdout",
+    "sys.stderr",
+    "sys.stdin",
+    ".isatty()",
+    # Module loading
+    "importlib.",
+    "exec_module(",
+    # Network operations
+    "requests.",
+    "aiohttp.",
+    "httpx.",
+    "urllib.",
+    # Console output
+    "print(",
+    "console.",
+    "Console(",
+    "typer.",
+    "click.",
+    "rich.",
+    # Result wrapping (Shell's primary job)
+    "Success(",
+    "Failure(",
+    "Result[",
+    # Database
+    "cursor.",
+    "connection.",
+    "session.",
+    # Logging
+    "logger.",
+    "logging.",
+    # Serialization (often to files)
+    "json.dump(",
+    "json.load(",
+    "toml.load(",
+    "yaml.load(",
+])
+
+# Marker pattern to exempt functions from complexity check
+COMPLEXITY_MARKER_PATTERN = re.compile(r"#\s*@shell_complexity\s*:")
+
+# Marker pattern to exempt functions from pure logic check (for orchestration functions)
+ORCHESTRATION_MARKER_PATTERN = re.compile(r"#\s*@shell_orchestration\s*:")
+
+
+# @invar:allow missing_contract: Boolean predicate, empty string is valid input
+def has_io_operations(source: str) -> bool:
+    """
+    Check if source code contains I/O operations.
+
+    Examples:
+        >>> has_io_operations("x = Success(value)")
+        True
+        >>> has_io_operations("return x + y")
+        False
+        >>> has_io_operations("path.read_text()")
+        True
+        >>> has_io_operations("print('hello')")
+        True
+    """
+    return any(indicator in source for indicator in IO_INDICATORS)
+
+
+@pre(lambda symbol, source: symbol is not None)  # Symbol must exist
+def has_orchestration_marker(symbol: Symbol, source: str) -> bool:
+    """
+    Check if symbol has @shell_orchestration marker comment.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="run_phase", kind=SymbolKind.FUNCTION, line=3, end_line=10)
+        >>> source = '''
+        ... # @shell_orchestration: Coordinates shell modules
+        ... def run_phase():
+        ...     pass
+        ... '''
+        >>> has_orchestration_marker(sym, source)
+        True
+
+        >>> sym2 = Symbol(name="calc", kind=SymbolKind.FUNCTION, line=1, end_line=3)
+        >>> has_orchestration_marker(sym2, "def calc(): pass")
+        False
+    """
+    lines = source.splitlines()
+    if not lines:
+        return False
+
+    start_line = max(0, symbol.line - 4)
+    end_line = symbol.line
+
+    context_lines = lines[start_line:end_line]
+    context = "\n".join(context_lines)
+
+    return bool(ORCHESTRATION_MARKER_PATTERN.search(context))
+
+
+@pre(lambda symbol, source: symbol is not None)  # Symbol must exist
+def has_complexity_marker(symbol: Symbol, source: str) -> bool:
+    """
+    Check if symbol has @shell_complexity marker comment.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="load", kind=SymbolKind.FUNCTION, line=3, end_line=10)
+        >>> source = '''
+        ... # @shell_complexity: Config cascade with fallbacks
+        ... def load():
+        ...     pass
+        ... '''
+        >>> has_complexity_marker(sym, source)
+        True
+
+        >>> sym2 = Symbol(name="simple", kind=SymbolKind.FUNCTION, line=1, end_line=3)
+        >>> has_complexity_marker(sym2, "def simple(): pass")
+        False
+    """
+    lines = source.splitlines()
+    if not lines:
+        return False
+
+    # Look at lines before the function definition
+    start_line = max(0, symbol.line - 4)
+    end_line = symbol.line
+
+    context_lines = lines[start_line:end_line]
+    context = "\n".join(context_lines)
+
+    return bool(COMPLEXITY_MARKER_PATTERN.search(context))
+
+
+@post(lambda result: result >= 0)  # Branch count is non-negative
+def count_branches(source: str) -> int:
+    """
+    Count the number of branches in source code.
+
+    Counts: if, elif, except, for, while, match case, ternary
+
+    Examples:
+        >>> count_branches("if x: pass")
+        1
+        >>> count_branches("if x: pass\\nelif y: pass")
+        2
+        >>> count_branches("for x in y: pass")
+        1
+        >>> count_branches("x = a if b else c")
+        1
+        >>> count_branches("pass")
+        0
+        >>> count_branches("")
+        0
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return 0
+
+    count = 0
+    for node in ast.walk(tree):
+        if isinstance(node, ast.If):
+            # ast.walk visits all If nodes including elifs
+            count += 1
+        elif isinstance(node, ast.For | ast.While | ast.ExceptHandler):
+            count += 1
+        elif isinstance(node, ast.Match):
+            # Count match cases
+            count += len(node.cases)
+        elif isinstance(node, ast.IfExp):
+            # Ternary expression
+            count += 1
+
+    return count
+
+
+@pre(lambda symbol, file_source: symbol is not None)  # Symbol must exist
+def get_symbol_source(symbol: Symbol, file_source: str) -> str:
+    """
+    Extract the source code for a specific symbol.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="foo", kind=SymbolKind.FUNCTION, line=2, end_line=4)
+        >>> source = '''# comment
+        ... def foo():
+        ...     return 1
+        ... '''
+        >>> 'def foo' in get_symbol_source(sym, source)
+        True
+    """
+    lines = file_source.splitlines()
+    if not lines:
+        return ""
+
+    # Line numbers are 1-indexed
+    start = max(0, symbol.line - 1)
+    end = min(len(lines), symbol.end_line)
+
+    return "\n".join(lines[start:end])

invar/core/shell_architecture.py

@@ -0,0 +1,171 @@
+"""
+Shell architecture rules for DX-22.
+
+Detects architectural issues in Shell layer:
+- shell_pure_logic: Pure logic that belongs in Core
+- shell_too_complex: Excessive branching complexity
+- shell_complexity_debt: Accumulated complexity warnings
+
+Core module: pure logic, no I/O.
+"""
+
+from __future__ import annotations
+
+from deal import post, pre
+
+from invar.core.entry_points import get_symbol_lines, is_entry_point
+from invar.core.models import FileInfo, RuleConfig, Severity, SymbolKind, Violation
+from invar.core.shell_analysis import (
+    count_branches,
+    get_symbol_source,
+    has_complexity_marker,
+    has_io_operations,
+    has_orchestration_marker,
+)
+
+
+@post(lambda result: all(v.rule == "shell_pure_logic" for v in result))
+def check_shell_pure_logic(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
+    """
+    Check that Shell functions contain I/O operations (DX-22).
+
+    Pure logic belongs in Core where it can be tested with contracts.
+    Functions > 5 lines without I/O indicators are flagged as WARNING.
+
+    Examples:
+        >>> from invar.core.models import FileInfo, Symbol, SymbolKind, RuleConfig
+        >>> sym = Symbol(name="calc", kind=SymbolKind.FUNCTION, line=1, end_line=10)
+        >>> source = "def calc(x, y):\\n    return x + y"
+        >>> info = FileInfo(path="shell/util.py", lines=10, symbols=[sym], is_shell=True, source=source)
+        >>> violations = check_shell_pure_logic(info, RuleConfig())
+        >>> len(violations) >= 0  # May or may not flag based on line count
+        True
+    """
+    violations: list[Violation] = []
+    if not file_info.is_shell:
+        return violations
+
+    for symbol in file_info.symbols:
+        if symbol.kind != SymbolKind.FUNCTION:
+            continue
+
+        # Skip small functions (wrappers are fine)
+        lines = get_symbol_lines(symbol)
+        if lines <= 5:
+            continue
+
+        # Skip entry points (they're handled by DX-23)
+        if is_entry_point(symbol, file_info.source):
+            continue
+
+        # Skip if marked with @shell_orchestration (coordinates other shell modules)
+        if has_orchestration_marker(symbol, file_info.source):
+            continue
+
+        # Get symbol source and check for I/O
+        symbol_source = get_symbol_source(symbol, file_info.source)
+        if not has_io_operations(symbol_source):
+            violations.append(
+                Violation(
+                    rule="shell_pure_logic",
+                    severity=Severity.WARNING,
+                    file=file_info.path,
+                    line=symbol.line,
+                    message=f"Shell function '{symbol.name}' has no I/O operations - pure logic belongs in Core",
+                    suggestion="Move to src/*/core/ and add @pre/@post contracts, or add: # @shell_orchestration: <reason>",
+                )
+            )
+
+    return violations
+
+
+@post(lambda result: all(v.rule == "shell_too_complex" for v in result))
+def check_shell_too_complex(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
+    """
+    Check that Shell functions don't have excessive branching (DX-22).
+
+    Complex logic should be in Core where it can be tested.
+    Functions exceeding shell_max_branches are flagged as INFO.
+
+    Use @shell_complexity marker to exempt justified complexity.
+
+    Examples:
+        >>> from invar.core.models import FileInfo, Symbol, SymbolKind, RuleConfig
+        >>> sym = Symbol(name="process", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> source = "def process(x):\\n    return x"
+        >>> info = FileInfo(path="shell/cli.py", lines=5, symbols=[sym], is_shell=True, source=source)
+        >>> check_shell_too_complex(info, RuleConfig())
+        []
+    """
+    violations: list[Violation] = []
+    if not file_info.is_shell:
+        return violations
+
+    max_branches = config.shell_max_branches
+
+    for symbol in file_info.symbols:
+        if symbol.kind != SymbolKind.FUNCTION:
+            continue
+
+        # Skip if marked with @shell_complexity
+        if has_complexity_marker(symbol, file_info.source):
+            continue
+
+        # Skip entry points
+        if is_entry_point(symbol, file_info.source):
+            continue
+
+        # Count branches in symbol source
+        symbol_source = get_symbol_source(symbol, file_info.source)
+        branches = count_branches(symbol_source)
+
+        if branches > max_branches:
+            violations.append(
+                Violation(
+                    rule="shell_too_complex",
+                    severity=Severity.INFO,
+                    file=file_info.path,
+                    line=symbol.line,
+                    message=f"Shell function '{symbol.name}' has {branches} branches (max: {max_branches})",
+                    suggestion="Extract logic to Core, or add: # @shell_complexity: <reason>",
+                )
+            )
+
+    return violations
+
+
+@pre(lambda violations, limit: isinstance(violations, list) and limit > 0)
+@post(lambda result: isinstance(result, list))
+def check_complexity_debt(violations: list[Violation], limit: int = 5) -> list[Violation]:
+    """
+    Check project-level complexity debt (DX-22 Fix-or-Explain).
+
+    When the project has too many unaddressed shell_too_complex warnings,
+    escalate to ERROR to force resolution.
+
+    Examples:
+        >>> from invar.core.models import Violation, Severity
+        >>> v1 = Violation(rule="shell_too_complex", severity=Severity.INFO, file="a.py", message="m")
+        >>> v2 = Violation(rule="shell_too_complex", severity=Severity.INFO, file="b.py", message="m")
+        >>> check_complexity_debt([v1, v2], limit=5)
+        []
+        >>> many = [Violation(rule="shell_too_complex", severity=Severity.INFO, file=f"{i}.py", message="m") for i in range(6)]
+        >>> result = check_complexity_debt(many, limit=5)
+        >>> len(result)
+        1
+        >>> result[0].severity == Severity.ERROR
+        True
+    """
+    unaddressed = [v for v in violations if v.rule == "shell_too_complex"]
+    if len(unaddressed) >= limit:
+        return [
+            Violation(
+                rule="shell_complexity_debt",
+                severity=Severity.ERROR,
+                file="<project>",
+                line=None,
+                message=f"Project has {len(unaddressed)} unaddressed complexity warnings (limit: {limit})",
+                suggestion="You must address these before proceeding:\n1. Refactor to reduce branches, OR\n2. Add @shell_complexity: markers with justification",
+            )
+        ]
+    return []