thailint 0.8.0__tar.gz → 0.9.0__tar.gz

{thailint-0.8.0 → thailint-0.9.0}/CHANGELOG.md

@@ -26,6 +26,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Stateless Class Linter** - Detect Python classes without state that should be module-level functions
+  - AST-based detection of classes without `__init__`/`__new__` constructors
+  - Detects classes without instance state (`self.attr` assignments)
+  - Excludes ABC, Protocol, and decorated classes (legitimate patterns)
+  - Excludes classes with class-level attributes
+  - Minimum 2 methods required to flag (avoids false positives on simple wrappers)
+  - CLI command: `thailint stateless-class src/`
+  - JSON and SARIF output formats
+  - Configuration via `.thailint.yaml` with `min_methods` and `ignore` options
+  - Self-dogfooded: 23 violations in thai-lint codebase were fixed
+  - 28 tests (15 detector + 13 CLI) with 100% pass rate
+  - Documentation: `docs/stateless-class-linter.md`
+
 - **Project Root Detection System** - Three-level precedence system for accurate configuration and ignore pattern resolution
   - `--project-root` CLI option for explicit project root specification (highest priority)
   - Automatic project root inference from `--config` path (config's parent directory becomes project root)

{thailint-0.8.0 → thailint-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thailint
-Version: 0.8.0
+Version: 0.9.0
 Summary: The AI Linter - Enterprise-grade linting and governance for AI-generated code across multiple languages
 License: MIT
 License-File: LICENSE
@@ -37,7 +37,7 @@ 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/)
+[![Tests](https://img.shields.io/badge/tests-728%2F728%20passing-brightgreen.svg)](tests/)
 [![Coverage](https://img.shields.io/badge/coverage-87%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)
@@ -104,6 +104,12 @@ thailint complements your existing linting stack by catching the patterns AI too
   - 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
@@ -1017,6 +1023,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.
@@ -1306,6 +1414,8 @@ 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
+- **[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

{thailint-0.8.0 → thailint-0.9.0}/README.md

@@ -2,7 +2,7 @@
 
 [![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/)
+[![Tests](https://img.shields.io/badge/tests-728%2F728%20passing-brightgreen.svg)](tests/)
 [![Coverage](https://img.shields.io/badge/coverage-87%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)
@@ -69,6 +69,12 @@ thailint complements your existing linting stack by catching the patterns AI too
   - 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
@@ -982,6 +988,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.
@@ -1271,6 +1379,8 @@ 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
+- **[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

{thailint-0.8.0 → thailint-0.9.0}/pyproject.toml

@@ -17,7 +17,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "thailint"
-version = "0.8.0"
+version = "0.9.0"
 description = "The AI Linter - Enterprise-grade linting and governance for AI-generated code across multiple languages"
 authors = ["Steve Jackson"]
 license = "MIT"

{thailint-0.8.0 → thailint-0.9.0}/src/cli.py

@@ -1895,5 +1895,120 @@ def _execute_method_property_lint(  # pylint: disable=too-many-arguments,too-man
     sys.exit(1 if method_property_violations else 0)
 
 
+# =============================================================================
+# Stateless Class Linter Command
+# =============================================================================
+
+
+def _setup_stateless_class_orchestrator(
+    path_objs: list[Path], config_file: str | None, verbose: bool, project_root: Path | None = None
+):
+    """Set up orchestrator for stateless-class command."""
+    from src.orchestrator.core import Orchestrator
+    from src.utils.project_root import get_project_root
+
+    if project_root is None:
+        first_path = path_objs[0] if path_objs else Path.cwd()
+        search_start = first_path if first_path.is_dir() else first_path.parent
+        project_root = get_project_root(search_start)
+
+    orchestrator = Orchestrator(project_root=project_root)
+
+    if config_file:
+        _load_config_file(orchestrator, config_file, verbose)
+
+    return orchestrator
+
+
+def _run_stateless_class_lint(orchestrator, path_objs: list[Path], recursive: bool):
+    """Execute stateless-class lint on files or directories."""
+    all_violations = _execute_linting_on_paths(orchestrator, path_objs, recursive)
+    return [v for v in all_violations if "stateless-class" in v.rule_id]
+
+
+@cli.command("stateless-class")
+@click.argument("paths", nargs=-1, type=click.Path())
+@click.option("--config", "-c", "config_file", type=click.Path(), help="Path to config file")
+@format_option
+@click.option("--recursive/--no-recursive", default=True, help="Scan directories recursively")
+@click.pass_context
+def stateless_class(
+    ctx,
+    paths: tuple[str, ...],
+    config_file: str | None,
+    format: str,
+    recursive: bool,
+):
+    """Check for stateless classes that should be module functions.
+
+    Detects Python classes that have no constructor (__init__), no instance
+    state, and 2+ methods - indicating they should be refactored to module-level
+    functions instead of using a class as a namespace.
+
+    PATHS: Files or directories to lint (defaults to current directory if none provided)
+
+    Examples:
+
+        \b
+        # Check current directory (all files recursively)
+        thai-lint stateless-class
+
+        \b
+        # Check specific directory
+        thai-lint stateless-class src/
+
+        \b
+        # Check single file
+        thai-lint stateless-class src/utils.py
+
+        \b
+        # Check multiple files
+        thai-lint stateless-class src/utils.py src/helpers.py
+
+        \b
+        # Get JSON output
+        thai-lint stateless-class --format json .
+
+        \b
+        # Get SARIF output for CI/CD integration
+        thai-lint stateless-class --format sarif src/
+
+        \b
+        # Use custom config file
+        thai-lint stateless-class --config .thailint.yaml src/
+    """
+    verbose = ctx.obj.get("verbose", False)
+    project_root = _get_project_root_from_context(ctx)
+
+    if not paths:
+        paths = (".",)
+
+    path_objs = [Path(p) for p in paths]
+
+    try:
+        _execute_stateless_class_lint(
+            path_objs, config_file, format, recursive, verbose, project_root
+        )
+    except Exception as e:
+        _handle_linting_error(e, verbose)
+
+
+def _execute_stateless_class_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    path_objs, config_file, format, recursive, verbose, project_root=None
+):
+    """Execute stateless-class lint."""
+    _validate_paths_exist(path_objs)
+    orchestrator = _setup_stateless_class_orchestrator(
+        path_objs, config_file, verbose, project_root
+    )
+    stateless_class_violations = _run_stateless_class_lint(orchestrator, path_objs, recursive)
+
+    if verbose:
+        logger.info(f"Found {len(stateless_class_violations)} stateless-class violation(s)")
+
+    format_violations(stateless_class_violations, format)
+    sys.exit(1 if stateless_class_violations else 0)
+
+
 if __name__ == "__main__":
     cli()

{thailint-0.8.0 → thailint-0.9.0}/src/core/base.py

@@ -151,6 +151,10 @@ class MultiLanguageLintRule(BaseLintRule):
     - _load_config(context) for configuration loading
     """
 
+    def __init__(self) -> None:
+        """Initialize the multi-language lint rule."""
+        pass  # Base class for multi-language linters
+
     def check(self, context: BaseLintContext) -> list[Violation]:
         """Check for violations with automatic language dispatch.
 

thailint-0.9.0/src/core/rule_discovery.py

@@ -0,0 +1,158 @@
+"""
+Purpose: Automatic rule discovery for plugin-based linter architecture
+
+Scope: Discovers and validates linting rules from Python packages
+
+Overview: Provides automatic rule discovery functionality for the linter framework. Scans Python
+    packages for classes inheriting from BaseLintRule, filters out abstract base classes, validates
+    rule classes, and attempts instantiation. Handles import errors gracefully to support partial
+    package installations. Enables plugin architecture by discovering rules without explicit registration.
+
+Dependencies: importlib, inspect, pkgutil, BaseLintRule
+
+Exports: discover_from_package function, RuleDiscovery class (compat)
+
+Interfaces: discover_from_package(package_path) -> list[BaseLintRule]
+
+Implementation: Package traversal with pkgutil, class introspection with inspect, error handling
+"""
+
+import importlib
+import inspect
+import pkgutil
+from typing import Any
+
+from .base import BaseLintRule
+
+
+def discover_from_package(package_path: str) -> list[BaseLintRule]:
+    """Discover rules from a package and its modules.
+
+    Args:
+        package_path: Python package path (e.g., 'src.linters')
+
+    Returns:
+        List of discovered rule instances
+    """
+    try:
+        package = importlib.import_module(package_path)
+    except ImportError:
+        return []
+
+    if not hasattr(package, "__path__"):
+        return _discover_from_module(package_path)
+
+    return _discover_from_package_modules(package_path, package)
+
+
+def _discover_from_package_modules(package_path: str, package: Any) -> list[BaseLintRule]:
+    """Discover rules from all modules in a package.
+
+    Args:
+        package_path: Package path
+        package: Imported package object
+
+    Returns:
+        List of discovered rules
+    """
+    rules = []
+    for _, module_name, _ in pkgutil.iter_modules(package.__path__):
+        full_module_name = f"{package_path}.{module_name}"
+        module_rules = _try_discover_from_module(full_module_name)
+        rules.extend(module_rules)
+    return rules
+
+
+def _try_discover_from_module(module_name: str) -> list[BaseLintRule]:
+    """Try to discover rules from a module, return empty list on error.
+
+    Args:
+        module_name: Full module name
+
+    Returns:
+        List of discovered rules (empty on error)
+    """
+    try:
+        return _discover_from_module(module_name)
+    except (ImportError, AttributeError):
+        return []
+
+
+def _discover_from_module(module_path: str) -> list[BaseLintRule]:
+    """Discover rules from a specific module.
+
+    Args:
+        module_path: Full module path to search
+
+    Returns:
+        List of discovered rule instances
+    """
+    try:
+        module = importlib.import_module(module_path)
+    except (ImportError, AttributeError):
+        return []
+
+    rules = []
+    for _name, obj in inspect.getmembers(module):
+        if not _is_rule_class(obj):
+            continue
+        rule_instance = _try_instantiate_rule(obj)
+        if rule_instance:
+            rules.append(rule_instance)
+    return rules
+
+
+def _try_instantiate_rule(rule_class: type[BaseLintRule]) -> BaseLintRule | None:
+    """Try to instantiate a rule class.
+
+    Args:
+        rule_class: Rule class to instantiate
+
+    Returns:
+        Rule instance or None on error
+    """
+    try:
+        return rule_class()
+    except (TypeError, AttributeError):
+        return None
+
+
+def _is_rule_class(obj: Any) -> bool:
+    """Check if an object is a valid rule class.
+
+    Args:
+        obj: Object to check
+
+    Returns:
+        True if obj is a concrete BaseLintRule subclass
+    """
+    return (
+        inspect.isclass(obj)
+        and issubclass(obj, BaseLintRule)
+        and obj is not BaseLintRule
+        and not inspect.isabstract(obj)
+    )
+
+
+# Legacy class wrapper for backward compatibility
+class RuleDiscovery:
+    """Discovers linting rules from Python packages.
+
+    Note: This class is a thin wrapper around module-level functions
+    for backward compatibility.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the discovery service."""
+        pass  # No state needed
+
+    def discover_from_package(self, package_path: str) -> list[BaseLintRule]:
+        """Discover rules from a package and its modules.
+
+        Args:
+            package_path: Python package path (e.g., 'src.linters')
+
+        Returns:
+            List of discovered rule instances
+        """
+        return discover_from_package(package_path)