thailint 0.2.0__py3-none-any.whl → 0.15.3__py3-none-any.whl

src/linters/stateless_class/python_analyzer.py

@@ -0,0 +1,290 @@
+"""
+Purpose: Python AST analyzer for detecting stateless classes
+
+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.
+
+Dependencies: Python AST module
+
+Exports: analyze_code function, ClassInfo dataclass
+
+Interfaces: analyze_code(code) -> list[ClassInfo] returning detected stateless classes
+
+Implementation: AST visitor pattern with focused helper functions for different checks
+"""
+
+import ast
+from dataclasses import dataclass
+
+
+@dataclass
+class ClassInfo:
+    """Information about a detected stateless class."""
+
+    name: str
+    line: int
+    column: int
+
+
+def analyze_code(code: str, min_methods: int = 2) -> list[ClassInfo]:
+    """Analyze Python code for stateless classes.
+
+    Args:
+        code: Python source code
+        min_methods: Minimum methods required to flag class
+
+    Returns:
+        List of detected stateless class info
+    """
+    try:
+        tree = ast.parse(code)
+    except SyntaxError:
+        return []
+
+    return _find_stateless_classes(tree, min_methods)
+
+
+def _find_stateless_classes(tree: ast.Module, min_methods: int = 2) -> list[ClassInfo]:
+    """Find all stateless classes in AST.
+
+    Args:
+        tree: Parsed AST module
+        min_methods: Minimum methods required to flag class
+
+    Returns:
+        List of stateless class info
+    """
+    results = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef) and _is_stateless(node, min_methods):
+            results.append(ClassInfo(node.name, node.lineno, node.col_offset))
+    return results
+
+
+def _is_stateless(class_node: ast.ClassDef, min_methods: int = 2) -> bool:
+    """Check if class is stateless and should be functions.
+
+    Args:
+        class_node: AST ClassDef node
+        min_methods: Minimum methods required to flag class
+
+    Returns:
+        True if class is stateless violation
+    """
+    if _should_skip_class(class_node):
+        return False
+    return _count_methods(class_node) >= min_methods
+
+
+def _should_skip_class(class_node: ast.ClassDef) -> bool:
+    """Check if class should be skipped from analysis.
+
+    Args:
+        class_node: AST ClassDef node
+
+    Returns:
+        True if class should be skipped
+    """
+    return (
+        _has_constructor(class_node)
+        or _is_exception_case(class_node)
+        or _has_class_attributes(class_node)
+        or _has_instance_attributes(class_node)
+        or _has_base_classes(class_node)
+    )
+
+
+def _has_base_classes(class_node: ast.ClassDef) -> bool:
+    """Check if class inherits from non-trivial base classes.
+
+    Classes that inherit from other classes are using polymorphism/inheritance
+    and should not be flagged as stateless.
+
+    Args:
+        class_node: AST ClassDef node
+
+    Returns:
+        True if class has non-trivial base classes
+    """
+    if not class_node.bases:
+        return False
+
+    for base in class_node.bases:
+        base_name = _get_base_name(base)
+        # Skip trivial bases like object
+        if base_name and base_name not in ("object",):
+            return True
+
+    return False
+
+
+def _count_methods(class_node: ast.ClassDef) -> int:
+    """Count methods in class.
+
+    Args:
+        class_node: AST ClassDef node
+
+    Returns:
+        Number of methods
+    """
+    return sum(1 for item in class_node.body if isinstance(item, ast.FunctionDef))
+
+
+def _has_constructor(class_node: ast.ClassDef) -> bool:
+    """Check if class has __init__ or __new__ method.
+
+    Args:
+        class_node: AST ClassDef node
+
+    Returns:
+        True if class has constructor
+    """
+    constructor_names = ("__init__", "__new__")
+    return any(
+        isinstance(item, ast.FunctionDef) and item.name in constructor_names
+        for item in class_node.body
+    )
+
+
+def _is_exception_case(class_node: ast.ClassDef) -> bool:
+    """Check if class is an exception case (ABC, Protocol, or decorated).
+
+    Args:
+        class_node: AST ClassDef node
+
+    Returns:
+        True if class is ABC, Protocol, or decorated
+    """
+    if class_node.decorator_list:
+        return True
+    return _inherits_from_abc_or_protocol(class_node)
+
+
+def _inherits_from_abc_or_protocol(class_node: ast.ClassDef) -> bool:
+    """Check if class inherits from ABC or Protocol.
+
+    Args:
+        class_node: AST ClassDef node
+
+    Returns:
+        True if inherits from ABC or Protocol
+    """
+    return any(_get_base_name(base) in ("ABC", "Protocol") for base in class_node.bases)
+
+
+def _get_base_name(base: ast.expr) -> str:
+    """Extract name from base class expression.
+
+    Args:
+        base: AST expression for base class
+
+    Returns:
+        Base class name or empty string
+    """
+    if isinstance(base, ast.Name):
+        return base.id
+    if isinstance(base, ast.Attribute):
+        return base.attr
+    return ""
+
+
+def _has_class_attributes(class_node: ast.ClassDef) -> bool:
+    """Check if class has class-level attributes.
+
+    Args:
+        class_node: AST ClassDef node
+
+    Returns:
+        True if class has class attributes
+    """
+    return any(isinstance(item, (ast.Assign, ast.AnnAssign)) for item in class_node.body)
+
+
+def _has_instance_attributes(class_node: ast.ClassDef) -> bool:
+    """Check if methods assign to self.attr.
+
+    Args:
+        class_node: AST ClassDef node
+
+    Returns:
+        True if any method assigns to self
+    """
+    return any(
+        isinstance(item, ast.FunctionDef) and _method_has_self_assignment(item)
+        for item in class_node.body
+    )
+
+
+def _method_has_self_assignment(method: ast.FunctionDef) -> bool:
+    """Check if method assigns to self.attr.
+
+    Args:
+        method: AST FunctionDef node
+
+    Returns:
+        True if method assigns to self
+    """
+    return any(_is_self_attribute_assignment(node) for node in ast.walk(method))
+
+
+def _is_self_attribute_assignment(node: ast.AST) -> bool:
+    """Check if node is a self.attr assignment.
+
+    Args:
+        node: AST node to check
+
+    Returns:
+        True if node is self attribute assignment
+    """
+    if not isinstance(node, ast.Assign):
+        return False
+    return any(_is_self_attribute(t) for t in node.targets)
+
+
+def _is_self_attribute(node: ast.expr) -> bool:
+    """Check if node is a self.attr reference.
+
+    Args:
+        node: AST expression node
+
+    Returns:
+        True if node is self.attr
+    """
+    if not isinstance(node, ast.Attribute):
+        return False
+    if not isinstance(node.value, ast.Name):
+        return False
+    return node.value.id == "self"
+
+
+# Legacy class wrapper for backward compatibility with linter.py
+class StatelessClassAnalyzer:
+    """Analyzes Python code for stateless classes.
+
+    Note: This class is a thin wrapper around module-level functions
+    to maintain backward compatibility with existing code.
+    """
+
+    def __init__(self, min_methods: int = 2) -> None:
+        """Initialize the analyzer.
+
+        Args:
+            min_methods: Minimum methods required to flag class
+        """
+        self._min_methods = min_methods
+
+    def analyze(self, code: str) -> list[ClassInfo]:
+        """Analyze Python code for stateless classes.
+
+        Args:
+            code: Python source code
+
+        Returns:
+            List of detected stateless class info
+        """
+        return analyze_code(code, self._min_methods)

src/linters/stringly_typed/__init__.py

@@ -0,0 +1,36 @@
+"""
+Purpose: Stringly-typed linter package exports
+
+Scope: Public API for stringly-typed linter module
+
+Overview: Provides the public interface for the stringly-typed linter package. Exports
+    StringlyTypedConfig for configuration and StringlyTypedRule for linting. The stringly-typed
+    linter detects code patterns where plain strings are used instead of proper enums or typed
+    alternatives, helping identify potential type safety improvements. Supports cross-file
+    detection to find repeated string patterns across the codebase. Includes IgnoreChecker
+    for inline ignore directive support.
+
+Dependencies: .config for StringlyTypedConfig, .linter for StringlyTypedRule,
+    .storage for StringlyTypedStorage, .ignore_checker for IgnoreChecker
+
+Exports: StringlyTypedConfig, StringlyTypedRule, StringlyTypedStorage, StoredPattern,
+    IgnoreChecker
+
+Interfaces: Configuration loading via StringlyTypedConfig.from_dict(),
+    StringlyTypedRule.check() and finalize() for linting, IgnoreChecker.filter_violations()
+
+Implementation: Module-level exports with __all__ definition
+"""
+
+from src.linters.stringly_typed.config import StringlyTypedConfig
+from src.linters.stringly_typed.ignore_checker import IgnoreChecker
+from src.linters.stringly_typed.linter import StringlyTypedRule
+from src.linters.stringly_typed.storage import StoredPattern, StringlyTypedStorage
+
+__all__ = [
+    "StringlyTypedConfig",
+    "IgnoreChecker",
+    "StringlyTypedRule",
+    "StringlyTypedStorage",
+    "StoredPattern",
+]

src/linters/stringly_typed/config.py

@@ -0,0 +1,189 @@
+"""
+Purpose: Configuration dataclass for stringly-typed linter
+
+Scope: Define configurable options for stringly-typed pattern detection
+
+Overview: Provides StringlyTypedConfig for customizing linter behavior including minimum
+    occurrences required to flag patterns, enum value thresholds, cross-file detection
+    settings, and ignore patterns. The stringly-typed linter detects code patterns where
+    plain strings are used instead of proper enums or typed alternatives. Integrates with
+    the orchestrator's configuration system to allow users to customize detection via
+    .thailint.yaml configuration files. Follows the same configuration pattern as other
+    thai-lint linters.
+
+Dependencies: dataclasses, typing
+
+Exports: StringlyTypedConfig dataclass, default constants
+
+Interfaces: StringlyTypedConfig.from_dict() class method for configuration loading
+
+Implementation: Dataclass with sensible defaults, validation in __post_init__, and config
+    loading from dictionary with language-specific override support
+
+Suppressions:
+    - too-many-instance-attributes: Configuration dataclass with cohesive detection settings
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# Default thresholds
+DEFAULT_MIN_OCCURRENCES = 2
+DEFAULT_MIN_VALUES_FOR_ENUM = 2
+DEFAULT_MAX_VALUES_FOR_ENUM = 6
+
+# Default ignore patterns - test directories are excluded by default
+# because test fixtures commonly use string literals for mocking
+DEFAULT_IGNORE_PATTERNS: list[str] = [
+    "**/tests/**",
+    "**/test/**",
+    "**/*_test.py",
+    "**/*_test.ts",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "**/*.stories.ts",
+    "**/*.stories.tsx",
+    "**/conftest.py",
+    "**/fixtures/**",
+]
+
+
+@dataclass
+class StringlyTypedConfig:  # pylint: disable=too-many-instance-attributes
+    """Configuration for stringly-typed linter.
+
+    Note: Pylint too-many-instance-attributes disabled. This is a configuration
+    dataclass serving as a data container for related stringly-typed linter settings.
+    All 8 attributes are cohesively related (detection thresholds, filtering options,
+    cross-file settings, exclusion patterns). Splitting would reduce cohesion and make
+    configuration loading more complex without meaningful benefit. This follows the
+    established pattern in DRYConfig.
+    """
+
+    enabled: bool = True
+    """Whether the linter is enabled."""
+
+    min_occurrences: int = DEFAULT_MIN_OCCURRENCES
+    """Minimum number of cross-file occurrences required to flag a violation."""
+
+    min_values_for_enum: int = DEFAULT_MIN_VALUES_FOR_ENUM
+    """Minimum number of unique string values to suggest an enum."""
+
+    max_values_for_enum: int = DEFAULT_MAX_VALUES_FOR_ENUM
+    """Maximum number of unique string values to suggest an enum (above this, not enum-worthy)."""
+
+    require_cross_file: bool = True
+    """Whether to require cross-file occurrences to flag violations."""
+
+    ignore: list[str] = field(default_factory=list)
+    """File patterns to ignore. Defaults merged with test directories in from_dict."""
+
+    allowed_string_sets: list[list[str]] = field(default_factory=list)
+    """String sets that are allowed and should not be flagged."""
+
+    exclude_variables: list[str] = field(default_factory=list)
+    """Variable names to exclude from detection."""
+
+    def __post_init__(self) -> None:
+        """Validate configuration values."""
+        if self.min_occurrences < 1:
+            raise ValueError(f"min_occurrences must be at least 1, got {self.min_occurrences}")
+        if self.min_values_for_enum < 2:
+            raise ValueError(
+                f"min_values_for_enum must be at least 2, got {self.min_values_for_enum}"
+            )
+        if self.max_values_for_enum < self.min_values_for_enum:
+            raise ValueError(
+                f"max_values_for_enum ({self.max_values_for_enum}) must be >= "
+                f"min_values_for_enum ({self.min_values_for_enum})"
+            )
+
+    @classmethod
+    def from_dict(
+        cls, config: dict[str, Any], language: str | None = None
+    ) -> "StringlyTypedConfig":
+        """Load configuration from dictionary.
+
+        Args:
+            config: Dictionary containing configuration values
+            language: Programming language for language-specific overrides
+
+        Returns:
+            StringlyTypedConfig instance with values from dictionary
+        """
+        # Check for language-specific overrides first
+        if language and language in config:
+            lang_config = config[language]
+            return cls._from_merged_config(config, lang_config)
+
+        return cls._from_base_config(config)
+
+    @classmethod
+    def _from_base_config(cls, config: dict[str, Any]) -> "StringlyTypedConfig":
+        """Create config from base configuration dictionary.
+
+        Args:
+            config: Base configuration dictionary
+
+        Returns:
+            StringlyTypedConfig instance
+        """
+        # Merge user ignore patterns with defaults
+        user_ignore = config.get("ignore", [])
+        merged_ignore = DEFAULT_IGNORE_PATTERNS.copy() + user_ignore
+
+        return cls(
+            enabled=config.get("enabled", True),
+            min_occurrences=config.get("min_occurrences", DEFAULT_MIN_OCCURRENCES),
+            min_values_for_enum=config.get("min_values_for_enum", DEFAULT_MIN_VALUES_FOR_ENUM),
+            max_values_for_enum=config.get("max_values_for_enum", DEFAULT_MAX_VALUES_FOR_ENUM),
+            require_cross_file=config.get("require_cross_file", True),
+            ignore=merged_ignore,
+            allowed_string_sets=config.get("allowed_string_sets", []),
+            exclude_variables=config.get("exclude_variables", []),
+        )
+
+    @classmethod
+    def _from_merged_config(
+        cls, base_config: dict[str, Any], lang_config: dict[str, Any]
+    ) -> "StringlyTypedConfig":
+        """Create config with language-specific overrides merged.
+
+        Args:
+            base_config: Base configuration dictionary
+            lang_config: Language-specific configuration overrides
+
+        Returns:
+            StringlyTypedConfig instance with merged values
+        """
+        # Merge user ignore patterns with defaults
+        user_ignore = lang_config.get("ignore", base_config.get("ignore", []))
+        merged_ignore = DEFAULT_IGNORE_PATTERNS.copy() + user_ignore
+
+        return cls(
+            enabled=lang_config.get("enabled", base_config.get("enabled", True)),
+            min_occurrences=lang_config.get(
+                "min_occurrences",
+                base_config.get("min_occurrences", DEFAULT_MIN_OCCURRENCES),
+            ),
+            min_values_for_enum=lang_config.get(
+                "min_values_for_enum",
+                base_config.get("min_values_for_enum", DEFAULT_MIN_VALUES_FOR_ENUM),
+            ),
+            max_values_for_enum=lang_config.get(
+                "max_values_for_enum",
+                base_config.get("max_values_for_enum", DEFAULT_MAX_VALUES_FOR_ENUM),
+            ),
+            require_cross_file=lang_config.get(
+                "require_cross_file", base_config.get("require_cross_file", True)
+            ),
+            ignore=merged_ignore,
+            allowed_string_sets=lang_config.get(
+                "allowed_string_sets", base_config.get("allowed_string_sets", [])
+            ),
+            exclude_variables=lang_config.get(
+                "exclude_variables", base_config.get("exclude_variables", [])
+            ),
+        )