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

src/linters/stateless_class/python_analyzer.py

@@ -0,0 +1,299 @@
+"""
+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__")
+    for item in class_node.body:
+        if isinstance(item, ast.FunctionDef) and item.name in constructor_names:
+            return True
+    return False
+
+
+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
+    """
+    for base in class_node.bases:
+        if _get_base_name(base) in ("ABC", "Protocol"):
+            return True
+    return False
+
+
+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
+    """
+    for item in class_node.body:
+        if isinstance(item, (ast.Assign, ast.AnnAssign)):
+            return True
+    return False
+
+
+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
+    """
+    for item in class_node.body:
+        if isinstance(item, ast.FunctionDef) and _method_has_self_assignment(item):
+            return True
+    return False
+
+
+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
+    """
+    for node in ast.walk(method):
+        if _is_self_attribute_assignment(node):
+            return True
+    return False
+
+
+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)

{thailint-0.8.0.dist-info → thailint-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thailint
-Version: 0.8.0
+Version: 0.10.0
 Summary: The AI Linter - Enterprise-grade linting and governance for AI-generated code across multiple languages
 License: MIT
 License-File: LICENSE
@@ -37,8 +37,8 @@ Description-Content-Type: text/markdown
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-682%2F682%20passing-brightgreen.svg)](tests/)
-[![Coverage](https://img.shields.io/badge/coverage-87%25-brightgreen.svg)](htmlcov/)
+[![Tests](https://img.shields.io/badge/tests-795%2F795%20passing-brightgreen.svg)](tests/)
+[![Coverage](https://img.shields.io/badge/coverage-88%25-brightgreen.svg)](htmlcov/)
 [![Documentation Status](https://readthedocs.org/projects/thai-lint/badge/?version=latest)](https://thai-lint.readthedocs.io/en/latest/?badge=latest)
 [![SARIF 2.1.0](https://img.shields.io/badge/SARIF-2.1.0-orange.svg)](docs/sarif-output.md)
 
@@ -98,12 +98,24 @@ thailint complements your existing linting stack by catching the patterns AI too
   - Configurable thresholds (lines, tokens, occurrences)
   - Language-specific detection (Python, TypeScript, JavaScript)
   - False positive filtering (keyword args, imports)
+- **Collection Pipeline Linting** - Detect for loops with embedded filtering
+  - Based on Martin Fowler's "Replace Loop with Pipeline" refactoring
+  - Detects if/continue patterns that should use generator expressions
+  - Generates refactoring suggestions with generator syntax
+  - Configurable threshold (min_continues)
+  - Python support with AST analysis
 - **Method Property Linting** - Detect methods that should be @property decorators
   - Python AST-based detection
   - get_* prefix detection (Java-style getters)
   - Simple computed value detection
   - Action verb exclusion (to_*, finalize, serialize)
   - Test file detection
+- **Stateless Class Linting** - Detect classes that should be module-level functions
+  - Python AST-based detection
+  - No constructor (__init__ or __new__) detection
+  - No instance state (self.attr) detection
+  - Excludes ABC, Protocol, and decorated classes
+  - Helpful refactoring suggestions
 - **Pluggable Architecture** - Easy to extend with custom linters
 - **Multi-Language Support** - Python, TypeScript, JavaScript, and more
 - **Flexible Configuration** - YAML/JSON configs with pattern matching
@@ -735,6 +747,109 @@ Built-in filters automatically exclude common non-duplication patterns:
 
 See [DRY Linter Guide](https://thai-lint.readthedocs.io/en/latest/dry-linter/) for comprehensive documentation, storage modes, and refactoring patterns.
 
+## Collection Pipeline Linter
+
+### Overview
+
+The collection-pipeline linter detects for loops with embedded filtering (if/continue patterns) that should be refactored to use generator expressions or other collection pipelines. Based on Martin Fowler's "Replace Loop with Pipeline" refactoring pattern.
+
+### The Anti-Pattern
+
+```python
+# Anti-pattern: Embedded filtering in loop body
+for file_path in dir_path.glob(pattern):
+    if not file_path.is_file():
+        continue
+    if ignore_parser.is_ignored(file_path):
+        continue
+    violations.extend(lint_file(file_path))
+```
+
+### The Solution
+
+```python
+# Collection pipeline: Filtering separated from processing
+valid_files = (
+    f for f in dir_path.glob(pattern)
+    if f.is_file() and not ignore_parser.is_ignored(f)
+)
+for file_path in valid_files:
+    violations.extend(lint_file(file_path))
+```
+
+### Quick Start
+
+```bash
+# Check current directory
+thailint pipeline .
+
+# Check specific directory
+thailint pipeline src/
+
+# Only flag patterns with 2+ filter conditions
+thailint pipeline --min-continues 2 src/
+
+# JSON output
+thailint pipeline --format json src/
+```
+
+### Configuration
+
+```yaml
+# .thailint.yaml
+collection-pipeline:
+  enabled: true
+  min_continues: 1  # Minimum if/continue patterns to flag
+  ignore:
+    - "tests/**"
+    - "**/legacy/**"
+```
+
+### Example Violation
+
+**Detected Pattern:**
+```python
+def process_files(paths):
+    for path in paths:
+        if not path.is_file():
+            continue
+        analyze(path)
+```
+
+**Violation Message:**
+```
+src/processor.py:3 - For loop over 'paths' has embedded filtering.
+  Consider using a generator expression:
+  for path in (path for path in paths if path.is_file()):
+```
+
+**Refactored Code:**
+```python
+def process_files(paths):
+    valid_paths = (p for p in paths if p.is_file())
+    for path in valid_paths:
+        analyze(path)
+```
+
+### Why This Matters
+
+- **Separation of concerns**: Filtering logic is separate from processing logic
+- **Readability**: Intent is clear at a glance
+- **Testability**: Filtering can be tested independently
+- **Based on**: Martin Fowler's "Replace Loop with Pipeline" refactoring
+
+### Ignoring Violations
+
+```python
+# Line-level ignore
+for item in items:  # thailint: ignore[collection-pipeline]
+    if not item.valid:
+        continue
+    process(item)
+```
+
+See [Collection Pipeline Linter Guide](docs/collection-pipeline-linter.md) for comprehensive documentation and refactoring patterns.
+
 ## Magic Numbers Linter
 
 ### Overview
@@ -1017,6 +1132,108 @@ Overview: Created 2024-01-15.  # thailint: ignore[file-header]
 
 See **[How to Ignore Violations](https://thai-lint.readthedocs.io/en/latest/how-to-ignore-violations/)** and **[File Header Linter Guide](https://thai-lint.readthedocs.io/en/latest/file-header-linter/)** for complete documentation.
 
+## Stateless Class Linter
+
+### Overview
+
+The stateless class linter detects Python classes that have no state (no constructor, no instance attributes) and should be refactored to module-level functions. This is a common anti-pattern in AI-generated code.
+
+### What Are Stateless Classes?
+
+Stateless classes are classes that:
+- Have no `__init__` or `__new__` method
+- Have no instance attributes (`self.attr` assignments)
+- Have 2+ methods (grouped functionality without state)
+
+```python
+# Bad - Stateless class (no state, just grouped functions)
+class TokenHasher:
+    def hash_token(self, token: str) -> str:
+        return hashlib.sha256(token.encode()).hexdigest()
+
+    def verify_token(self, token: str, hash_value: str) -> bool:
+        return self.hash_token(token) == hash_value
+
+# Good - Module-level functions
+def hash_token(token: str) -> str:
+    return hashlib.sha256(token.encode()).hexdigest()
+
+def verify_token(token: str, hash_value: str) -> bool:
+    return hash_token(token) == hash_value
+```
+
+### Quick Start
+
+```bash
+# Check stateless classes in current directory
+thailint stateless-class .
+
+# Check specific directory
+thailint stateless-class src/
+
+# Get JSON output
+thailint stateless-class --format json src/
+```
+
+### Configuration
+
+Add to `.thailint.yaml`:
+
+```yaml
+stateless-class:
+  enabled: true
+  min_methods: 2  # Minimum methods to flag
+```
+
+### Example Violation
+
+**Code with stateless class:**
+```python
+class StringUtils:
+    def capitalize_words(self, text: str) -> str:
+        return ' '.join(w.capitalize() for w in text.split())
+
+    def reverse_words(self, text: str) -> str:
+        return ' '.join(reversed(text.split()))
+```
+
+**Violation message:**
+```
+src/utils.py:1 - Class 'StringUtils' has no state and should be refactored to module-level functions
+```
+
+**Refactored code:**
+```python
+def capitalize_words(text: str) -> str:
+    return ' '.join(w.capitalize() for w in text.split())
+
+def reverse_words(text: str) -> str:
+    return ' '.join(reversed(text.split()))
+```
+
+### Exclusion Rules
+
+The linter does NOT flag classes that:
+- Have `__init__` or `__new__` constructors
+- Have instance attributes (`self.attr = value`)
+- Have class-level attributes
+- Inherit from ABC or Protocol
+- Have any decorator (`@dataclass`, `@register`, etc.)
+- Have 0-1 methods
+
+### Ignoring Violations
+
+```python
+# Line-level ignore
+class TokenHasher:  # thailint: ignore[stateless-class] - Legacy API
+    def hash(self, token): ...
+
+# File-level ignore
+# thailint: ignore-file[stateless-class]
+```
+
+See **[How to Ignore Violations](https://thai-lint.readthedocs.io/en/latest/how-to-ignore-violations/)** and **[Stateless Class Linter Guide](https://thai-lint.readthedocs.io/en/latest/stateless-class-linter/)** for complete documentation.
+
 ## Pre-commit Hooks
 
 Automate code quality checks before every commit and push with pre-commit hooks.
@@ -1243,6 +1460,9 @@ docker run --rm -v $(pwd):/data washad/thailint:latest nesting /data/src/file1.p
 # Lint specific subdirectory
 docker run --rm -v $(pwd):/data washad/thailint:latest nesting /data/src
 
+# Collection pipeline linter
+docker run --rm -v $(pwd):/data washad/thailint:latest pipeline /data/src
+
 # With custom config
 docker run --rm -v $(pwd):/data \
     washad/thailint:latest nesting --config /data/.thailint.yaml /data
@@ -1306,6 +1526,9 @@ docker run --rm -v /path/to/workspace:/workspace \
 - **[Nesting Depth Linter](https://thai-lint.readthedocs.io/en/latest/nesting-linter/)** - Nesting depth analysis guide
 - **[SRP Linter](https://thai-lint.readthedocs.io/en/latest/srp-linter/)** - Single Responsibility Principle guide
 - **[DRY Linter](https://thai-lint.readthedocs.io/en/latest/dry-linter/)** - Duplicate code detection guide
+- **[Collection Pipeline Linter](https://thai-lint.readthedocs.io/en/latest/collection-pipeline-linter/)** - Loop filtering refactoring guide
+- **[Method Property Linter](https://thai-lint.readthedocs.io/en/latest/method-property-linter/)** - Method-to-property conversion guide
+- **[Stateless Class Linter](https://thai-lint.readthedocs.io/en/latest/stateless-class-linter/)** - Stateless class detection guide
 - **[Pre-commit Hooks](https://thai-lint.readthedocs.io/en/latest/pre-commit-hooks/)** - Automated quality checks
 - **[SARIF Output Guide](docs/sarif-output.md)** - SARIF format for GitHub Code Scanning and CI/CD
 - **[Publishing Guide](https://thai-lint.readthedocs.io/en/latest/releasing/)** - Release and publishing workflow