thailint 0.15.5__py3-none-any.whl → 0.15.6__py3-none-any.whl

src/core/cli_utils.py

@@ -143,6 +143,24 @@ def _load_json_config(config_file: Path) -> dict[str, Any]:
         return dict(result) if isinstance(result, dict) else {}
 
 
+def _sanitize_string(text: str) -> str:
+    """Remove or replace surrogate characters that can't be encoded to UTF-8.
+
+    Surrogate characters (U+D800-U+DFFF) appear when Python reads filesystem paths
+    or file content with invalid UTF-8 bytes using surrogateescape error handling.
+    These characters cannot be encoded to UTF-8 and cause UnicodeEncodeError.
+
+    Args:
+        text: String that may contain surrogate characters
+
+    Returns:
+        String with surrogates replaced by the Unicode replacement character
+    """
+    # Encode with surrogateescape to handle surrogates, then decode back
+    # This effectively replaces surrogates with a replacement representation
+    return text.encode("utf-8", errors="surrogateescape").decode("utf-8", errors="replace")
+
+
 def format_violations(violations: list, output_format: str) -> None:
     """Format and print violations to console.
 
@@ -168,10 +186,10 @@ def _output_json(violations: list) -> None:
         "violations": [
             {
                 "rule_id": v.rule_id,
-                "file_path": str(v.file_path),
+                "file_path": _sanitize_string(str(v.file_path)),
                 "line": v.line,
                 "column": v.column,
-                "message": v.message,
+                "message": _sanitize_string(v.message),
                 "severity": v.severity.name,
             }
             for v in violations
@@ -215,9 +233,11 @@ def _print_violation(v: Any) -> None:
     Args:
         v: Violation object with file_path, line, column, severity, rule_id, message
     """
-    location = f"{v.file_path}:{v.line}" if v.line else str(v.file_path)
+    file_path = _sanitize_string(str(v.file_path))
+    message = _sanitize_string(v.message)
+    location = f"{file_path}:{v.line}" if v.line else file_path
     if v.column:
         location += f":{v.column}"
     click.echo(f"  {location}")
-    click.echo(f"    [{v.severity.name}] {v.rule_id}: {v.message}")
+    click.echo(f"    [{v.severity.name}] {v.rule_id}: {message}")
     click.echo()

src/linters/magic_numbers/config.py

@@ -4,8 +4,9 @@ Purpose: Configuration schema for magic numbers linter
 Scope: MagicNumberConfig dataclass with allowed_numbers and max_small_integer settings
 
 Overview: Defines configuration schema for magic numbers linter. Provides MagicNumberConfig dataclass
-    with allowed_numbers set (default includes common acceptable numbers like -1, 0, 1, 2, 3, 4, 5, 10, 100, 1000)
-    and max_small_integer threshold (default 10) for range() contexts. Supports per-file and per-directory
+    with allowed_numbers set (default includes common acceptable numbers like -1, 0, 1, 2, 3, 4, 5, 10, 100, 1000
+    and standard ports like 80, 443, 22, 21, 8080, 8443, 3000, 5000) and max_small_integer threshold (default 10)
+    for range() contexts. Supports per-file and per-directory
     config overrides through from_dict class method. Validates that configuration values are appropriate
     types. Integrates with orchestrator's configuration system to allow users to customize allowed numbers
     via .thailint.yaml configuration files.
@@ -18,11 +19,41 @@ Interfaces: MagicNumberConfig(allowed_numbers: set, max_small_integer: int, enab
     from_dict class method for loading configuration from dictionary
 
 Implementation: Dataclass with validation and defaults, matches reference implementation patterns
+
+Suppressions:
+    - unnecessary-lambda: The lambda is required here because dataclass field default_factory
+        needs a callable, and DEFAULT_ALLOWED_NUMBERS.copy() is a method call, not a callable.
+        Using `default_factory=DEFAULT_ALLOWED_NUMBERS.copy` would call the method at class
+        definition time, not at instance creation time.
 """
 
 from dataclasses import dataclass, field
 from typing import Any
 
+# Default allowed numbers including common small integers and standard ports
+DEFAULT_ALLOWED_NUMBERS: set[int | float] = {
+    # Common small integers
+    -1,
+    0,
+    1,
+    2,
+    3,
+    4,
+    5,
+    10,
+    100,
+    1000,
+    # Standard ports
+    21,  # FTP
+    22,  # SSH
+    80,  # HTTP
+    443,  # HTTPS
+    3000,  # Common dev server (Node.js, Rails)
+    5000,  # Flask default
+    8080,  # Alternate HTTP
+    8443,  # Alternate HTTPS
+}
+
 
 @dataclass
 class MagicNumberConfig:
@@ -30,10 +61,11 @@ class MagicNumberConfig:
 
     enabled: bool = True
     allowed_numbers: set[int | float] = field(
-        default_factory=lambda: {-1, 0, 1, 2, 3, 4, 5, 10, 100, 1000}
+        default_factory=lambda: DEFAULT_ALLOWED_NUMBERS.copy()  # pylint: disable=unnecessary-lambda
     )
     max_small_integer: int = 10
     ignore: list[str] = field(default_factory=list)
+    exempt_definition_files: bool = True
 
     def __post_init__(self) -> None:
         """Validate configuration values."""
@@ -58,16 +90,14 @@ class MagicNumberConfig:
             allowed_numbers = set(
                 lang_config.get(
                     "allowed_numbers",
-                    config.get("allowed_numbers", {-1, 0, 1, 2, 3, 4, 5, 10, 100, 1000}),
+                    config.get("allowed_numbers", DEFAULT_ALLOWED_NUMBERS),
                 )
             )
             max_small_integer = lang_config.get(
                 "max_small_integer", config.get("max_small_integer", 10)
             )
         else:
-            allowed_numbers = set(
-                config.get("allowed_numbers", {-1, 0, 1, 2, 3, 4, 5, 10, 100, 1000})
-            )
+            allowed_numbers = set(config.get("allowed_numbers", DEFAULT_ALLOWED_NUMBERS))
             max_small_integer = config.get("max_small_integer", 10)
 
         ignore_patterns = config.get("ignore", [])
@@ -79,4 +109,5 @@ class MagicNumberConfig:
             allowed_numbers=allowed_numbers,
             max_small_integer=max_small_integer,
             ignore=ignore_patterns,
+            exempt_definition_files=config.get("exempt_definition_files", True),
         )

src/linters/magic_numbers/definition_detector.py

@@ -0,0 +1,226 @@
+"""
+Purpose: Detect constant definition files that should be exempt from magic number checking
+
+Scope: File-level detection of definition patterns (status codes, constants files)
+
+Overview: Provides functions to detect if a file is a constant definition file that should
+    be exempt from magic number violations. Definition files exist specifically to define
+    named constants and shouldn't be flagged. Detection is based on:
+    1. Filename patterns (*_codes.py, *_constants.py, constants.py)
+    2. Content patterns (dicts with 5+ int keys, 10+ UPPERCASE constant assignments)
+    Files matching these patterns contain legitimate constant definitions.
+
+Dependencies: ast module for parsing, pathlib for Path handling, re for pattern matching
+
+Exports: is_definition_file function
+
+Interfaces: is_definition_file(file_path, content) -> bool
+
+Implementation: Filename pattern matching and AST-based content analysis
+"""
+
+import ast
+import re
+from pathlib import Path
+
+# Threshold for number of UPPERCASE constants to consider a file as definition file
+MIN_UPPERCASE_CONSTANTS = 10
+
+# Threshold for number of int keys in a dict to consider it a definition pattern
+MIN_DICT_INT_KEYS = 5
+
+
+def is_definition_file(file_path: Path | str | None, content: str | None) -> bool:
+    """Check if file is a constant definition file that should be exempt.
+
+    Args:
+        file_path: Path to the file
+        content: File content
+
+    Returns:
+        True if file is a definition file that should be exempt
+    """
+    if _matches_definition_filename(file_path):
+        return True
+
+    if content and _has_definition_content_patterns(content):
+        return True
+
+    return False
+
+
+def _matches_definition_filename(file_path: Path | str | None) -> bool:
+    """Check if filename matches definition file patterns.
+
+    Patterns:
+    - *_codes.py (status_codes.py, error_codes.py, etc.)
+    - *_constants.py (app_constants.py, etc.)
+    - constants.py
+
+    Args:
+        file_path: Path to the file
+
+    Returns:
+        True if filename matches definition patterns
+    """
+    if not file_path:
+        return False
+
+    file_name = Path(file_path).name.lower()
+
+    # Check for *_codes.py pattern
+    if file_name.endswith("_codes.py"):
+        return True
+
+    # Check for constants.py or *_constants.py
+    if file_name == "constants.py" or file_name.endswith("_constants.py"):
+        return True
+
+    return False
+
+
+def _has_definition_content_patterns(content: str) -> bool:
+    """Check if content has definition file patterns.
+
+    Patterns:
+    - 10+ UPPERCASE constant assignments
+    - Dict with 5+ integer keys
+
+    Args:
+        content: File content
+
+    Returns:
+        True if content matches definition patterns
+    """
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return False
+
+    # Check for many UPPERCASE constants
+    if _count_uppercase_constants(tree) >= MIN_UPPERCASE_CONSTANTS:
+        return True
+
+    # Check for dicts with many int keys
+    if _has_dict_with_int_keys(tree):
+        return True
+
+    return False
+
+
+def _count_uppercase_constants(tree: ast.Module) -> int:
+    """Count UPPERCASE constant assignments at module level.
+
+    Args:
+        tree: Parsed AST module
+
+    Returns:
+        Number of UPPERCASE constant assignments
+    """
+    count = 0
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            count += _count_numeric_constant_targets(node)
+    return count
+
+
+def _count_numeric_constant_targets(assign_node: ast.Assign) -> int:
+    """Count UPPERCASE constant targets with numeric values in an assignment.
+
+    Args:
+        assign_node: AST Assign node
+
+    Returns:
+        Number of uppercase constant targets with numeric values
+    """
+    if not _is_numeric_constant(assign_node.value):
+        return 0
+    return sum(1 for t in assign_node.targets if _is_uppercase_name_target(t))
+
+
+def _is_numeric_constant(value: ast.expr) -> bool:
+    """Check if value is a numeric constant.
+
+    Args:
+        value: AST expression node
+
+    Returns:
+        True if value is a numeric constant
+    """
+    return isinstance(value, ast.Constant) and isinstance(value.value, (int, float))
+
+
+def _is_uppercase_name_target(target: ast.expr) -> bool:
+    """Check if target is an uppercase name.
+
+    Args:
+        target: AST expression node
+
+    Returns:
+        True if target is an uppercase Name node
+    """
+    return isinstance(target, ast.Name) and _is_constant_name(target.id)
+
+
+def _is_constant_name(name: str) -> bool:
+    """Check if name follows UPPERCASE constant convention.
+
+    Args:
+        name: Variable name
+
+    Returns:
+        True if name is UPPERCASE (with underscores allowed)
+    """
+    # Must be uppercase and contain at least 2 characters
+    if len(name) < 2:
+        return False
+    # Allow underscores but must have uppercase letters
+    return re.match(r"^[A-Z][A-Z0-9_]*$", name) is not None
+
+
+def _has_dict_with_int_keys(tree: ast.Module) -> bool:
+    """Check if module has a dict with many integer keys.
+
+    Args:
+        tree: Parsed AST module
+
+    Returns:
+        True if there's a dict with MIN_DICT_INT_KEYS+ int keys
+    """
+    return any(_has_enough_int_keys(node) for node in ast.walk(tree) if isinstance(node, ast.Dict))
+
+
+def _has_enough_int_keys(dict_node: ast.Dict) -> bool:
+    """Check if dict has enough integer keys to be a definition pattern.
+
+    Args:
+        dict_node: AST Dict node
+
+    Returns:
+        True if dict has MIN_DICT_INT_KEYS or more integer keys
+    """
+    return _count_int_keys(dict_node) >= MIN_DICT_INT_KEYS
+
+
+def _count_int_keys(dict_node: ast.Dict) -> int:
+    """Count integer keys in a dict.
+
+    Args:
+        dict_node: AST Dict node
+
+    Returns:
+        Number of integer constant keys
+    """
+    return sum(1 for key in dict_node.keys if _is_int_key(key))
+
+
+def _is_int_key(key: ast.expr | None) -> bool:
+    """Check if key is an integer constant.
+
+    Args:
+        key: AST expression node (or None for **dict unpacking)
+
+    Returns:
+        True if key is an integer constant
+    """
+    return isinstance(key, ast.Constant) and isinstance(key.value, int)

src/linters/magic_numbers/linter.py

@@ -40,6 +40,7 @@ from src.linter_config.ignore import get_ignore_parser
 
 from .config import MagicNumberConfig
 from .context_analyzer import is_acceptable_context
+from .definition_detector import is_definition_file
 from .python_analyzer import PythonMagicNumberAnalyzer
 from .typescript_analyzer import TypeScriptMagicNumberAnalyzer
 from .typescript_ignore_checker import TypeScriptIgnoreChecker
@@ -174,6 +175,12 @@ class MagicNumberRule(MultiLanguageLintRule):  # thailint: ignore[srp]
         if self._is_file_ignored(context, config):
             return []
 
+        # Check if file is a definition file (status_codes.py, constants.py, etc.)
+        if config.exempt_definition_files and is_definition_file(
+            context.file_path, context.file_content
+        ):
+            return []
+
         tree = self._parse_python_code(context.file_content)
         if tree is None:
             return []

src/linters/nesting/python_analyzer.py

@@ -5,10 +5,12 @@ Scope: Python code nesting depth analysis using ast module
 
 Overview: Analyzes Python code to calculate maximum nesting depth using AST traversal. Implements
     visitor pattern to walk AST, tracking current depth and maximum depth found. Increments depth
-    for If, For, While, With, AsyncWith, Try, ExceptHandler, Match, and match_case nodes. Starts
-    depth counting at 1 for function body, matching reference implementation behavior. Returns
-    maximum depth found and location information for violation reporting. Provides helper method
-    to find all function definitions in an AST tree for batch processing.
+    for If, For, While, With, AsyncWith, Try, ExceptHandler, Match, and match_case nodes. Correctly
+    handles elif chains by detecting when an If node is in elif position (sole child in parent's
+    orelse list) and not incrementing depth. Starts depth counting at 1 for function body, matching
+    reference implementation behavior. Returns maximum depth found and location information for
+    violation reporting. Provides helper method to find all function definitions in an AST tree
+    for batch processing.
 
 Dependencies: ast module for Python parsing
 
@@ -16,11 +18,37 @@ Exports: PythonNestingAnalyzer class with calculate_max_depth method
 
 Interfaces: calculate_max_depth(func_node: ast.FunctionDef) -> tuple[int, int], find_all_functions
 
-Implementation: AST visitor pattern with depth tracking, based on reference implementation algorithm
+Implementation: AST visitor pattern with depth tracking, elif detection via parent orelse inspection
 """
 
 import ast
 
+# Control structure types that increase nesting depth
+_CONTROL_STRUCTURES = (
+    ast.For,
+    ast.While,
+    ast.With,
+    ast.AsyncWith,
+    ast.Try,
+    ast.Match,
+    ast.match_case,
+)
+
+
+class _DepthTracker:
+    """Tracks maximum nesting depth during AST traversal."""
+
+    def __init__(self, default_line: int) -> None:
+        """Initialize tracker with default line number."""
+        self.max_depth = 0
+        self.max_depth_line = default_line
+
+    def record(self, node: ast.AST, depth: int, default_line: int) -> None:
+        """Record depth if it's the new maximum."""
+        if depth > self.max_depth:
+            self.max_depth = depth
+            self.max_depth_line = getattr(node, "lineno", default_line)
+
 
 class PythonNestingAnalyzer:
     """Calculates maximum nesting depth in Python functions."""
@@ -40,42 +68,12 @@ class PythonNestingAnalyzer:
         Returns:
             Tuple of (max_depth, line_number_of_max_depth)
         """
-        max_depth = 0
-        max_depth_line = func_node.lineno
-
-        def visit_node(node: ast.AST, current_depth: int = 0) -> None:
-            nonlocal max_depth, max_depth_line
-
-            if current_depth > max_depth:
-                max_depth = current_depth
-                max_depth_line = getattr(node, "lineno", func_node.lineno)
-
-            # Nodes that increase nesting depth
-            if isinstance(
-                node,
-                (
-                    ast.If,
-                    ast.For,
-                    ast.While,
-                    ast.With,
-                    ast.AsyncWith,
-                    ast.Try,
-                    ast.ExceptHandler,
-                    ast.Match,
-                    ast.match_case,
-                ),
-            ):
-                current_depth += 1
-
-            # Visit children
-            for child in ast.iter_child_nodes(node):
-                visit_node(child, current_depth)
-
-        # Start at depth 1 for function body (matching reference implementation)
+        tracker = _DepthTracker(func_node.lineno)
+
         for stmt in func_node.body:
-            visit_node(stmt, 1)
+            _visit_node(stmt, 0, tracker, func_node.lineno)
 
-        return max_depth, max_depth_line
+        return tracker.max_depth, tracker.max_depth_line
 
     def find_all_functions(self, tree: ast.AST) -> list[ast.FunctionDef | ast.AsyncFunctionDef]:
         """Find all function definitions in AST.
@@ -91,3 +89,68 @@ class PythonNestingAnalyzer:
             if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                 functions.append(node)
         return functions
+
+
+def _visit_node(
+    node: ast.AST,
+    current_depth: int,
+    tracker: _DepthTracker,
+    default_line: int,
+    is_elif: bool = False,
+) -> None:
+    """Visit AST node, tracking nesting depth for control structures only."""
+    if isinstance(node, ast.If):
+        _visit_if_node(node, current_depth, tracker, default_line, is_elif)
+    elif isinstance(node, _CONTROL_STRUCTURES):
+        _visit_control_structure(node, current_depth, tracker, default_line)
+    else:
+        _visit_children(node, current_depth, tracker, default_line)
+
+
+def _visit_if_node(
+    node: ast.If, current_depth: int, tracker: _DepthTracker, default_line: int, is_elif: bool
+) -> None:
+    """Visit If node with special elif handling."""
+    if not is_elif:
+        current_depth += 1
+        tracker.record(node, current_depth, default_line)
+
+    # Visit body
+    for child in node.body:
+        _visit_node(child, current_depth, tracker, default_line)
+
+    # Handle orelse - check for elif chain
+    if _is_elif_chain(node.orelse):
+        _visit_node(node.orelse[0], current_depth, tracker, default_line, is_elif=True)
+    else:
+        for child in node.orelse:
+            _visit_node(child, current_depth, tracker, default_line)
+
+
+def _visit_control_structure(
+    node: ast.AST, current_depth: int, tracker: _DepthTracker, default_line: int
+) -> None:
+    """Visit a control structure node that increases depth."""
+    current_depth += 1
+    tracker.record(node, current_depth, default_line)
+    _visit_children(node, current_depth, tracker, default_line)
+
+
+def _visit_children(
+    node: ast.AST, current_depth: int, tracker: _DepthTracker, default_line: int
+) -> None:
+    """Visit all children of a node without incrementing depth."""
+    for child in ast.iter_child_nodes(node):
+        _visit_node(child, current_depth, tracker, default_line)
+
+
+def _is_elif_chain(orelse: list[ast.stmt]) -> bool:
+    """Check if orelse list represents an elif (single If node).
+
+    Args:
+        orelse: The orelse list from an If node
+
+    Returns:
+        True if this is an elif (single If in orelse), False otherwise
+    """
+    return len(orelse) == 1 and isinstance(orelse[0], ast.If)

src/linters/stateless_class/config.py

@@ -30,6 +30,8 @@ class StatelessClassConfig:
     enabled: bool = True
     min_methods: int = 2
     ignore: list[str] = field(default_factory=list)
+    exempt_test_classes: bool = True
+    exempt_mixins: bool = True
 
     @classmethod
     def from_dict(
@@ -55,4 +57,6 @@ class StatelessClassConfig:
             enabled=config.get("enabled", True),
             min_methods=config.get("min_methods", 2),
             ignore=ignore_patterns,
+            exempt_test_classes=config.get("exempt_test_classes", True),
+            exempt_mixins=config.get("exempt_mixins", True),
         )

src/linters/stateless_class/linter.py

@@ -27,6 +27,8 @@ Suppressions:
         exceeds limit due to comprehensive 5-level ignore system support.
 """
 
+import ast
+from collections.abc import Callable
 from pathlib import Path
 
 from src.core.base import BaseLintContext, BaseLintRule
@@ -36,7 +38,13 @@ from src.linter_config.ignore import get_ignore_parser
 from src.linter_config.rule_matcher import rule_matches
 
 from .config import StatelessClassConfig
-from .python_analyzer import ClassInfo, StatelessClassAnalyzer
+from .python_analyzer import (
+    ClassInfo,
+    StatelessClassAnalyzer,
+    is_mixin_class,
+    is_test_class,
+    is_test_file,
+)
 
 
 class StatelessClassRule(BaseLintRule):  # thailint: ignore[srp,dry]
@@ -74,16 +82,41 @@ class StatelessClassRule(BaseLintRule):  # thailint: ignore[srp,dry]
             return []
 
         config = self._load_config(context)
-        if not config.enabled or self._should_skip_file(context, config):
+        if not config.enabled:
+            return []
+        if self._should_skip_file(context, config):
             return []
 
         # _should_analyze ensures file_content is set
         assert context.file_content is not None  # nosec B101
 
+        stateless_classes = self._find_stateless_classes(context, config)
+        return self._filter_ignored_violations(stateless_classes, context)
+
+    def _find_stateless_classes(
+        self, context: BaseLintContext, config: StatelessClassConfig
+    ) -> list[ClassInfo]:
+        """Find stateless classes and apply exemptions.
+
+        Args:
+            context: Lint context
+            config: Configuration
+
+        Returns:
+            List of stateless classes after applying exemptions
+        """
+        assert context.file_content is not None  # nosec B101
+
         analyzer = StatelessClassAnalyzer(min_methods=config.min_methods)
-        stateless_classes = analyzer.analyze(context.file_content)
+        classes = analyzer.analyze(context.file_content)
 
-        return self._filter_ignored_violations(stateless_classes, context)
+        if config.exempt_test_classes:
+            classes = self._filter_test_classes(classes, context)
+
+        if config.exempt_mixins:
+            classes = self._filter_mixin_classes(classes, context)
+
+        return classes
 
     def _should_skip_file(self, context: BaseLintContext, config: StatelessClassConfig) -> bool:
         """Check if file should be skipped due to ignore patterns or directives.
@@ -230,6 +263,85 @@ class StatelessClassRule(BaseLintRule):  # thailint: ignore[srp,dry]
         """
         return rule_matches(self.rule_id, rule_pattern)
 
+    def _parse_class_nodes(self, context: BaseLintContext) -> dict[str, ast.ClassDef] | None:
+        """Parse code and build map of class names to AST nodes.
+
+        Args:
+            context: Lint context
+
+        Returns:
+            Dict mapping class names to ClassDef nodes, or None if parsing fails
+        """
+        if not context.file_content:
+            return None
+        try:
+            tree = ast.parse(context.file_content)
+        except SyntaxError:
+            return None
+        return {node.name: node for node in ast.walk(tree) if isinstance(node, ast.ClassDef)}
+
+    def _filter_test_classes(
+        self, classes: list[ClassInfo], context: BaseLintContext
+    ) -> list[ClassInfo]:
+        """Filter out test classes from stateless class list.
+
+        Args:
+            classes: List of stateless classes found
+            context: Lint context
+
+        Returns:
+            List of classes with test classes removed
+        """
+        # If file is a test file, exempt all classes
+        if is_test_file(str(context.file_path) if context.file_path else None):
+            return []
+
+        class_nodes = self._parse_class_nodes(context)
+        if class_nodes is None:
+            return classes
+
+        return self._filter_by_predicate(classes, class_nodes, is_test_class)
+
+    def _filter_by_predicate(
+        self,
+        classes: list[ClassInfo],
+        class_nodes: dict[str, ast.ClassDef],
+        predicate: Callable[[ast.ClassDef], bool],
+    ) -> list[ClassInfo]:
+        """Filter classes based on a predicate function.
+
+        Args:
+            classes: List of class info to filter
+            class_nodes: Map of class names to AST nodes
+            predicate: Function that returns True for classes to exclude
+
+        Returns:
+            List of classes not matching the predicate
+        """
+        return [
+            info
+            for info in classes
+            if info.name not in class_nodes or not predicate(class_nodes[info.name])
+        ]
+
+    def _filter_mixin_classes(
+        self, classes: list[ClassInfo], context: BaseLintContext
+    ) -> list[ClassInfo]:
+        """Filter out mixin classes from stateless class list.
+
+        Args:
+            classes: List of stateless classes found
+            context: Lint context
+
+        Returns:
+            List of classes with mixin classes removed
+        """
+        class_nodes = self._parse_class_nodes(context)
+        if class_nodes is None:
+            return classes
+
+        return self._filter_by_predicate(classes, class_nodes, is_mixin_class)
+
     def _filter_ignored_violations(
         self, classes: list[ClassInfo], context: BaseLintContext
     ) -> list[Violation]:

src/linters/stateless_class/python_analyzer.py

@@ -6,14 +6,16 @@ Scope: AST-based analysis of Python class definitions for stateless patterns
 Overview: Analyzes Python source code using AST to detect classes that have no
     constructor (__init__ or __new__), no instance state (self.attr assignments),
     and 2+ methods - indicating they should be refactored to module-level functions.
-    Excludes legitimate patterns like ABC, Protocol, decorated classes, and classes
-    with class-level attributes.
+    Excludes legitimate patterns like ABC, Protocol, decorated classes, classes
+    with class-level attributes, test classes (Test* prefix or TestCase inheritance),
+    and mixin classes (name contains "Mixin").
 
 Dependencies: Python AST module
 
-Exports: analyze_code function, ClassInfo dataclass
+Exports: analyze_code function, ClassInfo dataclass, is_test_class function
 
-Interfaces: analyze_code(code) -> list[ClassInfo] returning detected stateless classes
+Interfaces: analyze_code(code) -> list[ClassInfo] returning detected stateless classes,
+    is_test_class(class_node) -> bool for test class detection
 
 Implementation: AST visitor pattern with focused helper functions for different checks
 """
@@ -262,6 +264,86 @@ def _is_self_attribute(node: ast.expr) -> bool:
     return node.value.id == "self"
 
 
+def is_test_class(class_node: ast.ClassDef) -> bool:
+    """Check if class is a test class that should be exempt.
+
+    Test classes are exempt because they commonly have multiple methods
+    without instance state (setup/teardown patterns, assertion methods).
+
+    Criteria:
+    - Class name starts with "Test"
+    - Class inherits from unittest.TestCase or TestCase
+
+    Args:
+        class_node: AST ClassDef node
+
+    Returns:
+        True if class is a test class
+    """
+    # Check class name
+    if class_node.name.startswith("Test"):
+        return True
+
+    # Check base classes for TestCase
+    for base in class_node.bases:
+        base_name = _get_base_name(base)
+        if base_name in ("TestCase", "unittest.TestCase"):
+            return True
+
+    return False
+
+
+def is_test_file(file_path: str | None) -> bool:
+    """Check if file is a test file based on path.
+
+    Args:
+        file_path: Path to the file
+
+    Returns:
+        True if file is in tests/ directory or named test_*.py
+    """
+    if not file_path:
+        return False
+
+    path_str = str(file_path)
+    return _is_in_tests_directory(path_str) or _has_test_filename(path_str)
+
+
+def _is_in_tests_directory(path_str: str) -> bool:
+    """Check if path is in a tests/ directory."""
+    return (
+        "/tests/" in path_str
+        or "\\tests\\" in path_str
+        or path_str.startswith("tests/")
+        or path_str.startswith("tests\\")
+    )
+
+
+def _has_test_filename(path_str: str) -> bool:
+    """Check if path has a test_*.py filename."""
+    file_name = path_str.rsplit("/", maxsplit=1)[-1].rsplit("\\", maxsplit=1)[-1]
+    return file_name.startswith("test_")
+
+
+def is_mixin_class(class_node: ast.ClassDef) -> bool:
+    """Check if class is a mixin class that should be exempt.
+
+    Mixin classes provide reusable methods intended to be combined with other
+    classes via multiple inheritance. They commonly have multiple methods without
+    instance state, which is an intentional pattern.
+
+    Criteria:
+    - Class name contains "Mixin" (case-insensitive)
+
+    Args:
+        class_node: AST ClassDef node
+
+    Returns:
+        True if class is a mixin class
+    """
+    return "mixin" in class_node.name.lower()
+
+
 # Legacy class wrapper for backward compatibility with linter.py
 class StatelessClassAnalyzer:
     """Analyzes Python code for stateless classes.

{thailint-0.15.5.dist-info → thailint-0.15.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thailint
-Version: 0.15.5
+Version: 0.15.6
 Summary: The AI Linter - Enterprise-grade linting and governance for AI-generated code across multiple languages
 License: MIT
 License-File: LICENSE

{thailint-0.15.5.dist-info → thailint-0.15.6.dist-info}/RECORD

@@ -23,7 +23,7 @@ src/cli_main.py,sha256=C0Ey7YNlG3ipqb3KsJZ8rL8PJ4ueVp_45IUirGidvHI,1618
 src/config.py,sha256=O3ixzsYekGjlggmIsawCU1bctOa0MyG2IczHpg3mGyw,12753
 src/core/__init__.py,sha256=5FtsDvhMt4SNRx3pbcGURrxn135XRbeRrjSUxiXwkNc,381
 src/core/base.py,sha256=u5A8geprlKnsJk4ShiLHTKXRekZUB4I6rPQWxgiFeto,8019
-src/core/cli_utils.py,sha256=ZdFSPrZ4WfpTMh-mc_Z3u5OYidE1YyPRKflMynPosa8,6552
+src/core/cli_utils.py,sha256=o7lWPSlic96lRyfcsmBf8S1ej25M1-wlclx8_Eup20g,7446
 src/core/config_parser.py,sha256=CRHV2-csxag6yQzx_4IYYz57QSUYjPkeSb0XvOyshRI,4272
 src/core/constants.py,sha256=PKtPDqk6k9VuOSgjq1FAdi2CTvlnhdXvLj91dNaMDTA,1584
 src/core/linter_utils.py,sha256=StnKFzJgSvLyao1S0LpTKhsXo8nOwpdKpxo7mXl5PIg,8594
@@ -141,9 +141,10 @@ src/linters/lbyl/pattern_detectors/string_validator_detector.py,sha256=GXXcsCfmp
 src/linters/lbyl/python_analyzer.py,sha256=auPrWFUEmFxtv1GB3exJzz7uX71gXqEUCHKO64UDR8w,8041
 src/linters/lbyl/violation_builder.py,sha256=6wVX9U7Jq1ONWcGuasvIwJE9mXHcT778p0OcPC0Wx7w,10296
 src/linters/magic_numbers/__init__.py,sha256=17dkCUf0uiYLvpOZF01VDojj92NzxXZMtRhrSBUzsdc,1689
-src/linters/magic_numbers/config.py,sha256=3zV6ZNezouBWUYy4kMw5PUlPNvIWXVwOxTz1moZfRoI,3270
+src/linters/magic_numbers/config.py,sha256=l18AO6XY6zkrX6_aumn3CZLpCsw185sfy5B_v2nY-OA,4233
 src/linters/magic_numbers/context_analyzer.py,sha256=EgDyxxjvEqyD3FX0Fnxj5RcOPyvyVs_rYFxj2HOxYdg,7309
-src/linters/magic_numbers/linter.py,sha256=CGo_35ujoCbNXbb0XI4KGCm5C9PCe_LzvXrgmvYN-I4,16736
+src/linters/magic_numbers/definition_detector.py,sha256=brENrT17ofYzZUpFjAq05DeG4DS2pKdWAWm4DyGTrDY,6156
+src/linters/magic_numbers/linter.py,sha256=JoguQjpWNt1Xp818HuzzCdTv9RqVKQoZXy6fFK8zk0o,17023
 src/linters/magic_numbers/python_analyzer.py,sha256=Ba-EODvAkUIOhqMFv86MxMlXqF20ngvgubiWN_U_IUk,2446
 src/linters/magic_numbers/typescript_analyzer.py,sha256=-2YPmNWXHJN8R2siV3pJk_3Baj-A9nnvQRpU35YBKgs,7519
 src/linters/magic_numbers/typescript_ignore_checker.py,sha256=9JWqtXd8KU_GCc_66KSZT2X7uQhNGpxE2ikOyjcLyao,2847
@@ -156,7 +157,7 @@ src/linters/method_property/violation_builder.py,sha256=A7SwZWlVG_7W5pJiHOvIroI2
 src/linters/nesting/__init__.py,sha256=tszmyCEQMpEwB5H84WcAUfRYDQl7jpsn04es5DtAHsM,3200
 src/linters/nesting/config.py,sha256=PfPA2wJn3i6HHXeM0qu6Qx-v1KJdRwlRkFOdpf7NhS8,2405
 src/linters/nesting/linter.py,sha256=bn5aPlxKZNw3T2LsOSfZUK_shkxcsdUS_LtFVsGJexk,6622
-src/linters/nesting/python_analyzer.py,sha256=__fs_NE9xA4NM1MDOHBGdrI0zICkTcgbVZtfT03cxF0,3230
+src/linters/nesting/python_analyzer.py,sha256=ZaZuFErwpyEG3G0O5LqYwWn7Kmae9mqB8GCSRHSkjmU,5344
 src/linters/nesting/typescript_analyzer.py,sha256=70TsjP3EJWiHJ1ncMaveFE0e9_HdukWZr9LM0_MDXr8,3639
 src/linters/nesting/typescript_function_extractor.py,sha256=dDB1otJnFMCo-Pj4mTr4gekKe7V4ArOAtX6gV0dBDc4,4494
 src/linters/nesting/violation_builder.py,sha256=WwgR_Q9pfPJOoVuNZQL4MU3-Wc6RX_GGL5Rc2-RVlbI,4829
@@ -186,9 +187,9 @@ src/linters/srp/typescript_analyzer.py,sha256=Wi0P_G1v5AnZYtMN3sNm1iHva84-8Kep2L
 src/linters/srp/typescript_metrics_calculator.py,sha256=cDaHlnzMgFSTd2Sn5-tldR2HS6P8GMv4Qptep6PJozw,4093
 src/linters/srp/violation_builder.py,sha256=jaIjVtRYWUTs1SVJVwd0FxCojo0DxhPzfhyfMKmAroM,3881
 src/linters/stateless_class/__init__.py,sha256=8ePpinmCD27PCz7ukwUWcNwo-ZgyvhOquns-U51MyiQ,1063
-src/linters/stateless_class/config.py,sha256=u8Jt_xygIkuxZx2o0Uw_XFatOh11QhC9aN8lB_vfnLk,1993
-src/linters/stateless_class/linter.py,sha256=Rm3fZfkyUOYeBodcLPUcMNKUHPuc5NgKOeDioGXyu_M,11338
-src/linters/stateless_class/python_analyzer.py,sha256=psEx2pG-eZJfK9ViX4YaNCLFEXEqUoViA3rc32o_sVQ,7623
+src/linters/stateless_class/config.py,sha256=nLowY3nGjvku-GSfPwzclCmVieRulyhaoTjTyWpElk4,2195
+src/linters/stateless_class/linter.py,sha256=G6ftfGqocCbAg24IWJgi2wk8Rld-cJu7OVRPdToZmqY,14783
+src/linters/stateless_class/python_analyzer.py,sha256=P7PJAoCw_1mJdyyqe7EN5ybkDB4FguuTvgTeyy2qgJs,10018
 src/linters/stringly_typed/__init__.py,sha256=6r4IIykZ6mm551KQpRTSDp418EFqJQbuzjSfLHcwyBc,1511
 src/linters/stringly_typed/config.py,sha256=-M7fwwr9axQsQcGtowVINC9Bh1cS1b2-KPxFb2GtL3M,7500
 src/linters/stringly_typed/context_filter.py,sha256=JohTFvXiHKfVzUowRbsDrY37QngJDmhFfoxyoTzKriY,11422
@@ -219,8 +220,8 @@ src/orchestrator/language_detector.py,sha256=ALt2BEZKXQM2dWr1ChF9lZVj83YF4Bl9xwr
 src/templates/thailint_config_template.yaml,sha256=57ZtLxnIoOHtR5Ejq3clb4nhY9J4n6h36XFb79ZZPlc,12020
 src/utils/__init__.py,sha256=NiBtKeQ09Y3kuUzeN4O1JNfUIYPQDS2AP1l5ODq-Dec,125
 src/utils/project_root.py,sha256=aaxUM-LQ1okrPClmZWPFd_D09W3V1ArgJiidEEp_eU8,6262
-thailint-0.15.5.dist-info/METADATA,sha256=eCz6fB_QjLHkSrbUvyQU8pGObNYH2ZezmBgagz7oYbA,7202
-thailint-0.15.5.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-thailint-0.15.5.dist-info/entry_points.txt,sha256=DNoGUlxpaMFqxQDgHp1yeGqohOjdFR-kH19uHYi3OUY,72
-thailint-0.15.5.dist-info/licenses/LICENSE,sha256=kxh1J0Sb62XvhNJ6MZsVNe8PqNVJ7LHRn_EWa-T3djw,1070
-thailint-0.15.5.dist-info/RECORD,,
+thailint-0.15.6.dist-info/METADATA,sha256=0ZW5TC2eyix3Bil_XocUFO4fcOCK037NB3d0CLvCdkI,7202
+thailint-0.15.6.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+thailint-0.15.6.dist-info/entry_points.txt,sha256=DNoGUlxpaMFqxQDgHp1yeGqohOjdFR-kH19uHYi3OUY,72
+thailint-0.15.6.dist-info/licenses/LICENSE,sha256=kxh1J0Sb62XvhNJ6MZsVNe8PqNVJ7LHRn_EWa-T3djw,1070
+thailint-0.15.6.dist-info/RECORD,,