thailint 0.9.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

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

src/linters/stringly_typed/python/validation_detector.py

@@ -0,0 +1,186 @@
+"""
+Purpose: Detect membership validation patterns in Python AST
+
+Scope: Find 'x in ("a", "b")' and 'x not in (...)' patterns
+
+Overview: Provides MembershipValidationDetector class that traverses Python AST to find
+    membership validation patterns where strings are used instead of enums. Detects
+    Compare nodes with In/NotIn operators and string literal collections (tuple, set,
+    list). Returns structured MembershipPattern dataclass instances with string values,
+    operator type, location, and optional variable name. Filters out non-string
+    collections, single-element collections, and variable references.
+
+Dependencies: ast module for AST parsing, dataclasses for pattern structure,
+    variable_extractor for variable name extraction
+
+Exports: MembershipValidationDetector class, MembershipPattern dataclass
+
+Interfaces: MembershipValidationDetector.find_patterns(tree) -> list[MembershipPattern]
+
+Implementation: AST NodeVisitor pattern with Compare node handling for In/NotIn operators
+"""
+
+import ast
+from dataclasses import dataclass
+
+from .constants import MIN_VALUES_FOR_PATTERN
+from .variable_extractor import extract_variable_name
+
+
+@dataclass
+class MembershipPattern:
+    """Represents a detected membership validation pattern.
+
+    Captures the essential information about a stringly-typed membership check
+    including the string values being compared, the operator used, source location,
+    and the variable being tested if identifiable.
+    """
+
+    string_values: set[str]
+    """Set of string values in the membership test."""
+
+    operator: str
+    """Operator used: 'in' or 'not in'."""
+
+    line_number: int
+    """Line number where the pattern occurs (1-indexed)."""
+
+    column: int
+    """Column number where the pattern starts (0-indexed)."""
+
+    variable_name: str | None
+    """Variable name being tested, if identifiable from a simple expression."""
+
+
+class MembershipValidationDetector(ast.NodeVisitor):
+    """Detects membership validation patterns in Python AST.
+
+    Finds patterns like 'x in ("a", "b")' and 'x not in {"c", "d"}' where
+    strings are used for validation instead of proper enums.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the detector."""
+        self.patterns: list[MembershipPattern] = []
+
+    def find_patterns(self, tree: ast.AST) -> list[MembershipPattern]:
+        """Find all membership validation patterns in the AST.
+
+        Args:
+            tree: The AST to analyze
+
+        Returns:
+            List of MembershipPattern instances for each detected pattern
+        """
+        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 membership patterns.
+
+        Handles Compare nodes with In or NotIn operators where the
+        comparator is a literal collection of strings.
+
+        Args:
+            node: The Compare node to analyze
+        """
+        for op_index, operator in enumerate(node.ops):
+            self._check_membership_operator(node, operator, op_index)
+        self.generic_visit(node)
+
+    def _check_membership_operator(
+        self, node: ast.Compare, operator: ast.cmpop, op_index: int
+    ) -> None:
+        """Check if an operator forms a valid membership pattern.
+
+        Args:
+            node: The Compare node containing the operator
+            operator: The comparison operator to check
+            op_index: Index of the operator in the Compare node
+        """
+        if not isinstance(operator, (ast.In, ast.NotIn)):
+            return
+
+        comparator = node.comparators[op_index]
+        string_values = _extract_string_values(comparator)
+
+        if string_values is None or len(string_values) < MIN_VALUES_FOR_PATTERN:
+            return
+
+        self._add_pattern(node, operator, string_values)
+
+    def _add_pattern(self, node: ast.Compare, operator: ast.cmpop, string_values: set[str]) -> None:
+        """Create and add a membership pattern to results.
+
+        Args:
+            node: The Compare node containing the pattern
+            operator: The In or NotIn operator
+            string_values: Set of string values detected
+        """
+        operator_str = "in" if isinstance(operator, ast.In) else "not in"
+        variable_name = extract_variable_name(node.left)
+
+        pattern = MembershipPattern(
+            string_values=string_values,
+            operator=operator_str,
+            line_number=node.lineno,
+            column=node.col_offset,
+            variable_name=variable_name,
+        )
+        self.patterns.append(pattern)
+
+
+def _extract_string_values(node: ast.AST) -> set[str] | None:
+    """Extract string values from a collection literal.
+
+    Args:
+        node: AST node representing the collection
+
+    Returns:
+        Set of string values if all elements are strings, None otherwise
+    """
+    elements = _get_collection_elements(node)
+    if elements is None or len(elements) == 0:
+        return None
+
+    return _collect_string_constants(elements)
+
+
+def _get_collection_elements(node: ast.AST) -> list[ast.expr] | None:
+    """Get elements from a collection literal node.
+
+    Args:
+        node: AST node that may be a collection literal
+
+    Returns:
+        List of element nodes if node is a collection, None otherwise
+    """
+    if isinstance(node, ast.Tuple):
+        return list(node.elts)
+    if isinstance(node, ast.Set):
+        return list(node.elts)
+    if isinstance(node, ast.List):
+        return list(node.elts)
+    return None
+
+
+def _collect_string_constants(elements: list[ast.expr]) -> set[str] | None:
+    """Collect string constants from a list of AST expression nodes.
+
+    Args:
+        elements: List of expression nodes from a collection
+
+    Returns:
+        Set of string values if all elements are string constants, None otherwise
+    """
+    string_values: set[str] = set()
+
+    for element in elements:
+        if not isinstance(element, ast.Constant):
+            return None
+        if not isinstance(element.value, str):
+            return None
+        string_values.add(element.value)
+
+    return string_values

src/linters/stringly_typed/python/variable_extractor.py

@@ -0,0 +1,96 @@
+"""
+Purpose: Extract variable names from Python AST nodes
+
+Scope: AST node analysis for identifying variable names in expressions
+
+Overview: Provides functions to extract variable names from various Python AST expression
+    types including simple names, attribute access chains, and method calls. Handles
+    complex expressions by returning None when the variable cannot be simply identified.
+    Supports extraction from Name nodes, Attribute chains (e.g., self.status), and Call
+    nodes for method calls (e.g., x.lower()).
+
+Dependencies: ast module for AST node types
+
+Exports: extract_variable_name, extract_attribute_chain functions
+
+Interfaces: extract_variable_name(node) -> str | None for general extraction,
+    extract_attribute_chain(node) -> str for attribute chain extraction
+
+Implementation: Pattern matching on AST node types with recursive chain handling
+"""
+
+import ast
+
+
+def extract_variable_name(node: ast.AST) -> str | None:
+    """Extract variable name from an expression node.
+
+    Identifies the variable being used in an expression, handling
+    simple names, attribute access, and method calls.
+
+    Args:
+        node: AST node representing an expression
+
+    Returns:
+        Variable name if identifiable, None for complex expressions
+    """
+    if isinstance(node, ast.Name):
+        return node.id
+
+    if isinstance(node, ast.Attribute):
+        return extract_attribute_chain(node)
+
+    if isinstance(node, ast.Call):
+        return _extract_call_variable(node)
+
+    return None
+
+
+def extract_attribute_chain(node: ast.Attribute) -> str:
+    """Extract full attribute chain as string.
+
+    Builds a dotted string representation of attribute access,
+    e.g., 'self.status' or 'obj.attr.subattr'.
+
+    Args:
+        node: Attribute node to extract from
+
+    Returns:
+        String representation of attribute chain
+    """
+    parts: list[str] = [node.attr]
+    current = node.value
+
+    while isinstance(current, ast.Attribute):
+        parts.append(current.attr)
+        current = current.value
+
+    if isinstance(current, ast.Name):
+        parts.append(current.id)
+
+    parts.reverse()
+    return ".".join(parts)
+
+
+def _extract_call_variable(node: ast.Call) -> str | None:
+    """Extract variable from a method call expression.
+
+    For expressions like x.lower(), returns 'x'.
+    For complex calls like get_value().lower(), returns None.
+
+    Args:
+        node: Call node to extract from
+
+    Returns:
+        Variable name if identifiable, None otherwise
+    """
+    if not isinstance(node.func, ast.Attribute):
+        return None
+
+    value = node.func.value
+    if isinstance(value, ast.Name):
+        return value.id
+    if isinstance(value, ast.Attribute):
+        return extract_attribute_chain(value)
+
+    return None