thailint 0.10.0__py3-none-any.whl → 0.12.0__py3-none-any.whl

src/linters/stringly_typed/python/comparison_tracker.py

@@ -0,0 +1,252 @@
+"""
+Purpose: Detect scattered string comparisons in Python AST
+
+Scope: Find equality/inequality comparisons with string literals across Python files
+
+Overview: Provides ComparisonTracker class that traverses Python AST to find scattered
+    string comparisons like `if env == "production"`. Tracks the variable name, compared
+    string value, and operator to enable cross-file aggregation. When a variable is compared
+    to multiple unique string values across files, it suggests the variable should be an enum.
+    Excludes common false positives like `__name__ == "__main__"` and type name checks.
+
+Dependencies: ast module for AST parsing, dataclasses for pattern structure
+
+Exports: ComparisonTracker class, ComparisonPattern dataclass
+
+Interfaces: ComparisonTracker.find_patterns(tree) -> list[ComparisonPattern]
+
+Implementation: AST NodeVisitor pattern with Compare node handling for string comparisons
+"""
+
+import ast
+from dataclasses import dataclass
+
+
+@dataclass
+class ComparisonPattern:
+    """Represents a string comparison found in Python code.
+
+    Captures information about a comparison like `if (env == "production")` to
+    enable cross-file analysis for detecting scattered string comparisons that
+    suggest missing enums.
+    """
+
+    variable_name: str
+    """Variable name being compared (e.g., 'env' or 'self.status')."""
+
+    compared_value: str
+    """The string literal value being compared to."""
+
+    operator: str
+    """The comparison operator ('==' or '!=')."""
+
+    line_number: int
+    """Line number where the comparison occurs (1-indexed)."""
+
+    column: int
+    """Column number where the comparison starts (0-indexed)."""
+
+
+# Excluded variable names that are common false positives
+_EXCLUDED_VARIABLES = frozenset(
+    {
+        "__name__",
+        "__class__.__name__",
+    }
+)
+
+# Excluded values that are common in legitimate comparisons
+_EXCLUDED_VALUES = frozenset(
+    {
+        "__main__",
+    }
+)
+
+
+class ComparisonTracker(ast.NodeVisitor):  # thailint: ignore[srp]
+    """Tracks scattered string comparisons in Python AST.
+
+    Finds patterns like `if env == "production"` and `if status != "deleted"` where
+    string literals are used for comparisons that could use enums instead.
+
+    Note: Method count exceeds SRP limit because AST traversal requires multiple helper
+    methods for extracting variable names, attribute names, and pattern filtering. All
+    methods support the single responsibility of tracking string comparisons.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the tracker."""
+        self.patterns: list[ComparisonPattern] = []
+
+    def find_patterns(self, tree: ast.AST) -> list[ComparisonPattern]:
+        """Find all string comparisons in the AST.
+
+        Args:
+            tree: The AST to analyze
+
+        Returns:
+            List of ComparisonPattern instances for each detected comparison
+        """
+        self.patterns = []
+        self.visit(tree)
+        return self.patterns
+
+    def visit_Compare(self, node: ast.Compare) -> None:  # pylint: disable=invalid-name
+        """Visit a Compare node to check for string comparisons.
+
+        Handles both `var == "string"` and `"string" == var` patterns.
+
+        Args:
+            node: The Compare node to analyze
+        """
+        self._check_comparison(node)
+        self.generic_visit(node)
+
+    def _check_comparison(self, node: ast.Compare) -> None:
+        """Check if comparison is a string comparison to track.
+
+        Args:
+            node: The Compare node to check
+        """
+        # Only handle simple binary comparisons
+        if len(node.ops) != 1 or len(node.comparators) != 1:
+            return
+
+        operator = node.ops[0]
+        if not isinstance(operator, (ast.Eq, ast.NotEq)):
+            return
+
+        op_str = "==" if isinstance(operator, ast.Eq) else "!="
+        left = node.left
+        right = node.comparators[0]
+
+        # Try both orientations: var == "string" and "string" == var
+        self._try_extract_pattern(left, right, op_str, node)
+        self._try_extract_pattern(right, left, op_str, node)
+
+    def _try_extract_pattern(
+        self,
+        var_side: ast.expr,
+        string_side: ast.expr,
+        operator: str,
+        node: ast.Compare,
+    ) -> None:
+        """Try to extract a pattern from a comparison.
+
+        Args:
+            var_side: The expression that might be a variable
+            string_side: The expression that might be a string literal
+            operator: The comparison operator
+            node: The original Compare node for location info
+        """
+        # Check if string_side is a string literal
+        if not isinstance(string_side, ast.Constant):
+            return
+        if not isinstance(string_side.value, str):
+            return
+
+        string_value = string_side.value
+
+        # Extract variable name
+        var_name = self._extract_variable_name(var_side)
+        if var_name is None:
+            return
+
+        # Check for excluded patterns
+        if self._should_exclude(var_name, string_value):
+            return
+
+        self._add_pattern(var_name, string_value, operator, node)
+
+    def _extract_variable_name(self, node: ast.expr) -> str | None:
+        """Extract variable name from an expression.
+
+        Handles simple names (var) and attribute access (obj.attr).
+
+        Args:
+            node: The expression to extract from
+
+        Returns:
+            Variable name string or None if not extractable
+        """
+        if isinstance(node, ast.Name):
+            return node.id
+        if isinstance(node, ast.Attribute):
+            return self._extract_attribute_name(node)
+        return None
+
+    def _extract_attribute_name(self, node: ast.Attribute) -> str | None:
+        """Extract attribute name from an attribute access.
+
+        Builds qualified names like 'obj.attr' or 'a.b.attr'.
+
+        Args:
+            node: The Attribute node
+
+        Returns:
+            Qualified attribute name or None if too complex
+        """
+        parts: list[str] = [node.attr]
+        current = node.value
+
+        # Limit depth to avoid overly complex names
+        max_depth = 3
+        depth = 0
+
+        while depth < max_depth:
+            if isinstance(current, ast.Name):
+                parts.append(current.id)
+                break
+            if isinstance(current, ast.Attribute):
+                parts.append(current.attr)
+                current = current.value
+                depth += 1
+            else:
+                # Complex expression, still return what we have
+                parts.append("_")
+                break
+
+        return ".".join(reversed(parts))
+
+    def _should_exclude(self, var_name: str, string_value: str) -> bool:
+        """Check if this comparison should be excluded.
+
+        Filters out common patterns that are not stringly-typed code:
+        - __name__ == "__main__"
+        - __class__.__name__ checks
+
+        Args:
+            var_name: The variable name
+            string_value: The string value
+
+        Returns:
+            True if the comparison should be excluded
+        """
+        if var_name in _EXCLUDED_VARIABLES:
+            return True
+        if string_value in _EXCLUDED_VALUES:
+            return True
+        # Also exclude if the full qualified name ends with __name__
+        if var_name.endswith("__name__"):
+            return True
+        return False
+
+    def _add_pattern(
+        self, var_name: str, string_value: str, operator: str, node: ast.Compare
+    ) -> None:
+        """Create and add a comparison pattern to results.
+
+        Args:
+            var_name: The variable name
+            string_value: The string value being compared
+            operator: The comparison operator
+            node: The Compare node for location info
+        """
+        pattern = ComparisonPattern(
+            variable_name=var_name,
+            compared_value=string_value,
+            operator=operator,
+            line_number=node.lineno,
+            column=node.col_offset,
+        )
+        self.patterns.append(pattern)

src/linters/stringly_typed/python/condition_extractor.py

@@ -0,0 +1,131 @@
+"""
+Purpose: Extract string comparisons from Python condition expressions
+
+Scope: Parse BoolOp and Compare nodes to extract string equality patterns
+
+Overview: Provides functions to extract string comparisons from condition expressions
+    in Python AST. Handles simple comparisons, or-combined, and and-combined
+    conditions. Updates a collector object with extracted variable names and
+    string values. Separated from main detector to reduce complexity.
+
+Dependencies: ast module, variable_extractor
+
+Exports: extract_from_condition, is_simple_string_equality, get_string_constant
+
+Interfaces: Functions for extracting string comparisons from AST nodes
+
+Implementation: Recursive traversal of BoolOp nodes with Compare extraction
+"""
+
+import ast
+
+from .variable_extractor import extract_variable_name
+
+
+def extract_from_condition(
+    test: ast.expr,
+    collector: object,
+) -> None:
+    """Extract string comparisons from a condition expression.
+
+    Handles simple comparisons, or-combined, and and-combined comparisons.
+
+    Args:
+        test: The test expression from an if/elif
+        collector: Collector to accumulate results into (must have variable_name
+                  and string_values attributes)
+    """
+    if isinstance(test, ast.BoolOp):
+        _extract_from_bool_op(test, collector)
+    elif isinstance(test, ast.Compare):
+        _extract_from_compare(test, collector)
+
+
+def _extract_from_bool_op(node: ast.BoolOp, collector: object) -> None:
+    """Extract from BoolOp (And/Or combined comparisons).
+
+    Args:
+        node: BoolOp node
+        collector: Collector to accumulate results into
+    """
+    for value in node.values:
+        _handle_bool_op_value(value, collector)
+
+
+def _handle_bool_op_value(value: ast.expr, collector: object) -> None:
+    """Handle a single value from a BoolOp node.
+
+    Args:
+        value: Expression value from BoolOp
+        collector: Collector to accumulate results into
+    """
+    if isinstance(value, ast.Compare):
+        _extract_from_compare(value, collector)
+    elif isinstance(value, ast.BoolOp):
+        _extract_from_bool_op(value, collector)
+
+
+def _extract_from_compare(node: ast.Compare, collector: object) -> None:
+    """Extract string value from a Compare node with Eq/NotEq.
+
+    Args:
+        node: Compare node to analyze
+        collector: Collector to accumulate results into
+    """
+    if not _is_simple_equality(node):
+        return
+
+    string_value = _get_string_constant(node)
+    if string_value is None:
+        return
+
+    var_name = extract_variable_name(node.left)
+    _update_collector(collector, var_name, string_value)
+
+
+def _is_simple_equality(node: ast.Compare) -> bool:
+    """Check if Compare is a simple equality with one operator.
+
+    Args:
+        node: Compare node to check
+
+    Returns:
+        True if it's a simple x == y or x != y comparison
+    """
+    if len(node.ops) != 1:
+        return False
+    return isinstance(node.ops[0], (ast.Eq, ast.NotEq))
+
+
+def _get_string_constant(node: ast.Compare) -> str | None:
+    """Get string constant from the right side of comparison.
+
+    Args:
+        node: Compare node to extract from
+
+    Returns:
+        String value if comparator is a string constant, None otherwise
+    """
+    comparator = node.comparators[0]
+    if isinstance(comparator, ast.Constant) and isinstance(comparator.value, str):
+        return comparator.value
+    return None
+
+
+def _update_collector(
+    collector: object,
+    var_name: str | None,
+    string_value: str,
+) -> None:
+    """Update collector with extracted variable and value.
+
+    Args:
+        collector: Collector to update
+        var_name: Variable name from comparison
+        string_value: String value from comparison
+    """
+    if collector.variable_name is None:  # type: ignore[attr-defined]
+        collector.variable_name = var_name  # type: ignore[attr-defined]
+    # Only add if same variable (or no variable tracking)
+    if collector.variable_name == var_name or var_name is None:  # type: ignore[attr-defined]
+        collector.string_values.add(string_value)  # type: ignore[attr-defined]

src/linters/stringly_typed/python/conditional_detector.py

@@ -0,0 +1,176 @@
+"""
+Purpose: Detect equality chain patterns in Python AST
+
+Scope: Find 'if x == "a" elif x == "b"', or-combined, and match statement patterns
+
+Overview: Provides ConditionalPatternDetector class that traverses Python AST to find
+    equality chain patterns where strings are used instead of enums. Detects single
+    equality comparisons with string constants, aggregates values from if/elif chains,
+    handles or-combined comparisons, and supports Python 3.10+ match statements.
+    Returns structured EqualityChainPattern dataclass instances with aggregated
+    string values, pattern type, location, and optional variable name.
+
+Dependencies: ast module for AST parsing, dataclasses for pattern structure,
+    condition_extractor for comparison extraction, match_analyzer for match statements
+
+Exports: ConditionalPatternDetector class, EqualityChainPattern dataclass
+
+Interfaces: ConditionalPatternDetector.find_patterns(tree) -> list[EqualityChainPattern]
+
+Implementation: AST NodeVisitor pattern with If node chain traversal and Match statement handling
+"""
+
+import ast
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .condition_extractor import extract_from_condition
+from .constants import MIN_VALUES_FOR_PATTERN
+from .match_analyzer import analyze_match_statement
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+@dataclass
+class EqualityChainPattern:
+    """Represents a detected equality chain pattern.
+
+    Captures information about stringly-typed equality checks including aggregated
+    string values from chains, pattern type, source location, and variable name.
+    """
+
+    string_values: set[str]
+    """Set of string values aggregated from the equality chain."""
+
+    pattern_type: str
+    """Type of pattern: 'equality_chain', 'or_combined', or 'match_statement'."""
+
+    line_number: int
+    """Line number where the pattern starts (1-indexed)."""
+
+    column: int
+    """Column number where the pattern starts (0-indexed)."""
+
+    variable_name: str | None
+    """Variable name being compared, if identifiable from a simple expression."""
+
+
+@dataclass
+class _ChainCollector:
+    """Internal collector for aggregating values from if/elif chains."""
+
+    variable_name: str | None = None
+    string_values: set[str] = field(default_factory=set)
+    line_number: int = 0
+    column: int = 0
+
+
+class ConditionalPatternDetector(ast.NodeVisitor):
+    """Detects equality chain patterns in Python AST.
+
+    Finds patterns like 'if x == "a" elif x == "b"', or-combined comparisons,
+    and match statements where strings are used instead of proper enums.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the detector."""
+        self.patterns: list[EqualityChainPattern] = []
+        self._processed_if_nodes: set[int] = set()
+
+    def find_patterns(self, tree: ast.AST) -> list[EqualityChainPattern]:
+        """Find all equality chain patterns in the AST.
+
+        Args:
+            tree: The AST to analyze
+
+        Returns:
+            List of EqualityChainPattern instances for each detected pattern
+        """
+        self.patterns = []
+        self._processed_if_nodes = set()
+        self.visit(tree)
+        return self.patterns
+
+    def visit_If(self, node: ast.If) -> None:  # pylint: disable=invalid-name
+        """Visit an If node to check for equality chain patterns.
+
+        Args:
+            node: The If node to analyze
+        """
+        if id(node) not in self._processed_if_nodes:
+            self._analyze_if_chain(node)
+        self.generic_visit(node)
+
+    def visit_Match(self, node: ast.Match) -> None:  # pylint: disable=invalid-name
+        """Visit a Match node to check for string case patterns.
+
+        Args:
+            node: The Match node to analyze
+        """
+        pattern = analyze_match_statement(node, EqualityChainPattern)
+        if pattern is not None:
+            self.patterns.append(pattern)  # type: ignore[arg-type]
+        self.generic_visit(node)
+
+    def _analyze_if_chain(self, node: ast.If) -> None:
+        """Analyze an if/elif chain for equality patterns.
+
+        Args:
+            node: The starting If node of the chain
+        """
+        collector = _ChainCollector(line_number=node.lineno, column=node.col_offset)
+
+        for if_node in self._iter_if_chain(node):
+            self._processed_if_nodes.add(id(if_node))
+            extract_from_condition(if_node.test, collector)
+
+        self._emit_pattern_if_valid(collector)
+
+    def _iter_if_chain(self, node: ast.If) -> "Iterator[ast.If]":
+        """Iterate through an if/elif chain.
+
+        Args:
+            node: Starting If node
+
+        Yields:
+            Each If node in the chain including elif branches
+        """
+        yield node
+        current: ast.If | None = node
+
+        while current is not None:
+            current = self._get_next_elif(current)
+            if current is not None:
+                yield current
+
+    def _get_next_elif(self, node: ast.If) -> ast.If | None:
+        """Get the next elif node in a chain.
+
+        Args:
+            node: Current If node
+
+        Returns:
+            Next elif If node, or None if no elif exists
+        """
+        if len(node.orelse) == 1 and isinstance(node.orelse[0], ast.If):
+            return node.orelse[0]
+        return None
+
+    def _emit_pattern_if_valid(self, collector: _ChainCollector) -> None:
+        """Emit a pattern if collector has sufficient values.
+
+        Args:
+            collector: Collector with aggregated values
+        """
+        if len(collector.string_values) < MIN_VALUES_FOR_PATTERN:
+            return
+
+        pattern = EqualityChainPattern(
+            string_values=collector.string_values,
+            pattern_type="equality_chain",
+            line_number=collector.line_number,
+            column=collector.column,
+            variable_name=collector.variable_name,
+        )
+        self.patterns.append(pattern)

src/linters/stringly_typed/python/constants.py

@@ -0,0 +1,21 @@
+"""
+Purpose: Shared constants for stringly-typed Python detection
+
+Scope: Common configuration values used across Python pattern detectors
+
+Overview: Provides shared constants used by MembershipValidationDetector,
+    ConditionalPatternDetector, and other Python detection components.
+    Centralizes configuration values to ensure consistency and avoid
+    duplication across detector implementations.
+
+Dependencies: None
+
+Exports: MIN_VALUES_FOR_PATTERN constant
+
+Interfaces: Constants only, no function interfaces
+
+Implementation: Simple module-level constant definitions
+"""
+
+# Minimum number of string values to consider as enum candidate
+MIN_VALUES_FOR_PATTERN = 2

src/linters/stringly_typed/python/match_analyzer.py

@@ -0,0 +1,88 @@
+"""
+Purpose: Analyze Python match statements for stringly-typed patterns
+
+Scope: Extract string values from match statement cases
+
+Overview: Provides MatchStatementAnalyzer class that analyzes Python 3.10+ match
+    statements to detect stringly-typed patterns. Extracts string values from
+    case patterns and returns structured results. Separated from main detector
+    to maintain single responsibility and reduce class complexity.
+
+Dependencies: ast module, constants module, variable_extractor
+
+Exports: MatchStatementAnalyzer class
+
+Interfaces: MatchStatementAnalyzer.analyze(node) -> EqualityChainPattern | None
+
+Implementation: AST pattern matching for MatchValue nodes with string constants
+"""
+
+import ast
+
+from .constants import MIN_VALUES_FOR_PATTERN
+from .variable_extractor import extract_variable_name
+
+
+def analyze_match_statement(
+    node: ast.Match,
+    pattern_class: type,
+) -> object | None:
+    """Analyze a match statement for string case patterns.
+
+    Args:
+        node: Match statement node to analyze
+        pattern_class: The EqualityChainPattern class to use for results
+
+    Returns:
+        Pattern instance if valid match found, None otherwise
+    """
+    string_values = _collect_string_cases(node.cases)
+
+    if len(string_values) < MIN_VALUES_FOR_PATTERN:
+        return None
+
+    var_name = extract_variable_name(node.subject)
+    return pattern_class(
+        string_values=string_values,
+        pattern_type="match_statement",
+        line_number=node.lineno,
+        column=node.col_offset,
+        variable_name=var_name,
+    )
+
+
+def _collect_string_cases(cases: list[ast.match_case]) -> set[str]:
+    """Collect string values from match cases.
+
+    Args:
+        cases: List of match_case nodes
+
+    Returns:
+        Set of string values from MatchValue patterns
+    """
+    string_values: set[str] = set()
+
+    for case in cases:
+        value = _extract_case_string_value(case.pattern)
+        if value is not None:
+            string_values.add(value)
+
+    return string_values
+
+
+def _extract_case_string_value(pattern: ast.pattern) -> str | None:
+    """Extract string value from a case pattern.
+
+    Args:
+        pattern: Match case pattern node
+
+    Returns:
+        String value if pattern is a MatchValue with string, None otherwise
+    """
+    if not isinstance(pattern, ast.MatchValue):
+        return None
+    if not isinstance(pattern.value, ast.Constant):
+        return None
+    if not isinstance(pattern.value.value, str):
+        return None
+    return pattern.value.value