thailint 0.1.5__py3-none-any.whl → 0.5.0__py3-none-any.whl

src/core/linter_utils.py

@@ -0,0 +1,168 @@
+"""
+Purpose: Shared utility functions for linter framework patterns
+
+Scope: Common config loading, metadata access, and context validation utilities for all linters
+
+Overview: Provides reusable helper functions to eliminate duplication across linter implementations.
+    Includes utilities for loading configuration from context metadata with language-specific overrides,
+    extracting metadata fields safely with type validation, and validating context state. Standardizes
+    common patterns used by srp, nesting, dry, and file_placement linters. Reduces boilerplate code
+    while maintaining type safety and proper error handling.
+
+Dependencies: BaseLintContext from src.core.base
+
+Exports: get_metadata, get_metadata_value, load_linter_config, has_file_content
+
+Interfaces: All functions take BaseLintContext and return typed values (dict, str, bool, Any)
+
+Implementation: Type-safe metadata access with fallbacks, generic config loading with language support
+"""
+
+from typing import Any, Protocol, TypeVar
+
+from src.core.base import BaseLintContext
+
+
+# Protocol for config classes that support from_dict
+class ConfigProtocol(Protocol):
+    """Protocol for configuration classes with from_dict class method."""
+
+    @classmethod
+    def from_dict(
+        cls, config_dict: dict[str, Any], language: str | None = None
+    ) -> "ConfigProtocol":
+        """Create config instance from dictionary."""
+
+
+# Type variable for config classes
+ConfigType = TypeVar("ConfigType", bound=ConfigProtocol)  # pylint: disable=invalid-name
+
+
+def get_metadata(context: BaseLintContext) -> dict[str, Any]:
+    """Get metadata dictionary from context with safe fallback.
+
+    Args:
+        context: Lint context containing optional metadata
+
+    Returns:
+        Metadata dictionary, or empty dict if not available
+    """
+    metadata = getattr(context, "metadata", None)
+    if metadata is None or not isinstance(metadata, dict):
+        return {}
+    return dict(metadata)  # Explicit cast to satisfy type checker
+
+
+def get_metadata_value(context: BaseLintContext, key: str, default: Any = None) -> Any:
+    """Get specific value from context metadata with safe fallback.
+
+    Args:
+        context: Lint context containing optional metadata
+        key: Metadata key to retrieve
+        default: Default value if key not found
+
+    Returns:
+        Metadata value or default
+    """
+    metadata = get_metadata(context)
+    return metadata.get(key, default)
+
+
+def get_language(context: BaseLintContext) -> str | None:
+    """Get language from context.
+
+    Args:
+        context: Lint context containing optional language
+
+    Returns:
+        Language string or None
+    """
+    return getattr(context, "language", None)
+
+
+def get_project_root(context: BaseLintContext) -> str | None:
+    """Get project root from context metadata.
+
+    Args:
+        context: Lint context containing optional metadata
+
+    Returns:
+        Project root path or None
+    """
+    metadata = get_metadata(context)
+    project_root = metadata.get("project_root")
+    return str(project_root) if project_root is not None else None
+
+
+def load_linter_config(
+    context: BaseLintContext,
+    config_key: str,
+    config_class: type[ConfigType],
+) -> ConfigType:
+    """Load linter configuration from context metadata with language-specific overrides.
+
+    Args:
+        context: Lint context containing metadata
+        config_key: Key to look up in metadata (e.g., "srp", "nesting", "dry")
+        config_class: Configuration class with from_dict() class method
+
+    Returns:
+        Configuration instance (uses default config if metadata unavailable)
+
+    Example:
+        config = load_linter_config(context, "srp", SRPConfig)
+    """
+    metadata = get_metadata(context)
+    config_dict = metadata.get(config_key, {})
+
+    if not isinstance(config_dict, dict):
+        return config_class()
+
+    # Get language for language-specific thresholds
+    language = get_language(context)
+
+    # Call from_dict with language if config class supports it
+    # This works for SRPConfig, NestingConfig, etc.
+    try:
+        result = config_class.from_dict(config_dict, language=language)
+        return result  # type: ignore[return-value]
+    except TypeError:
+        # Fallback for config classes that don't support language parameter
+        result_fallback = config_class.from_dict(config_dict)
+        return result_fallback  # type: ignore[return-value]
+
+
+def has_file_content(context: BaseLintContext) -> bool:
+    """Check if context has file content available.
+
+    Args:
+        context: Lint context to check
+
+    Returns:
+        True if file_content is not None
+    """
+    return context.file_content is not None
+
+
+def has_file_path(context: BaseLintContext) -> bool:
+    """Check if context has file path available.
+
+    Args:
+        context: Lint context to check
+
+    Returns:
+        True if file_path is not None
+    """
+    return context.file_path is not None
+
+
+def should_process_file(context: BaseLintContext) -> bool:
+    """Check if file should be processed (has both content and path).
+
+    Args:
+        context: Lint context to check
+
+    Returns:
+        True if file has both content and path available
+    """
+    return has_file_content(context) and has_file_path(context)

src/core/registry.py

@@ -3,36 +3,24 @@ Purpose: Rule registry with automatic plugin discovery and registration
 
 Scope: Dynamic rule management and discovery across all linter plugin packages
 
-Overview: Implements the plugin discovery system that enables the extensible architecture by
-    automatically finding and registering linting rules from specified packages without requiring
-    explicit registration code. The RuleRegistry maintains a collection of discovered rules indexed
-    by rule_id, providing methods to register individual rules, retrieve rules by identifier, and
-    list all available rules. Auto-discovery works by scanning Python packages for classes that
-    inherit from BaseLintRule, filtering out abstract base classes, instantiating concrete rule
-    classes, and registering them for use by the orchestrator. This enables developers to add new
-    rules simply by creating a class in the appropriate package structure without modifying any
-    framework code. The registry handles import errors gracefully and supports both package-level
-    and module-level discovery patterns.
-
-Dependencies: importlib for dynamic module loading, inspect for class introspection,
-    pkgutil for package traversal, BaseLintRule for type checking
+Overview: Implements rule registry that maintains a collection of registered linting rules indexed
+    by rule_id. Provides methods to register individual rules, retrieve rules by identifier, list
+    all available rules, and discover rules from packages using the RuleDiscovery helper. Enables
+    the extensible plugin architecture by allowing rules to be added dynamically without framework
+    modifications. Validates rule uniqueness and handles registration errors gracefully.
+
+Dependencies: BaseLintRule, RuleDiscovery
 
 Exports: RuleRegistry class with register(), get(), list_all(), and discover_rules() methods
 
 Interfaces: register(rule: BaseLintRule) -> None, get(rule_id: str) -> BaseLintRule | None,
     list_all() -> list[BaseLintRule], discover_rules(package_path: str) -> int
 
-Implementation: Package scanning with pkgutil.iter_modules(), class introspection with inspect,
-    subclass detection for BaseLintRule, abstract class filtering, graceful error handling for
-    failed imports, duplicate rule_id validation
+Implementation: Dictionary-based registry with RuleDiscovery delegation, duplicate validation
 """
 
-import importlib
-import inspect
-import pkgutil
-from typing import Any
-
 from .base import BaseLintRule
+from .rule_discovery import RuleDiscovery
 
 
 class RuleRegistry:
@@ -45,6 +33,7 @@ class RuleRegistry:
     def __init__(self) -> None:
         """Initialize empty registry."""
         self._rules: dict[str, BaseLintRule] = {}
+        self._discovery = RuleDiscovery()
 
     def register(self, rule: BaseLintRule) -> None:
         """Register a new rule.
@@ -93,78 +82,14 @@ class RuleRegistry:
         Returns:
             Number of rules discovered and registered.
         """
-        try:
-            package = importlib.import_module(package_path)
-        except ImportError:
-            return 0
-
-        if not hasattr(package, "__path__"):
-            return self._discover_from_module(package_path)
-
-        return self._discover_from_package_modules(package_path, package)
-
-    def _discover_from_package_modules(self, package_path: str, package: Any) -> int:
-        """Discover rules from all modules in a package."""
-        discovered_count = 0
-        for _, module_name, _ in pkgutil.iter_modules(package.__path__):
-            full_module_name = f"{package_path}.{module_name}"
-            discovered_count += self._try_discover_from_module(full_module_name)
-        return discovered_count
-
-    def _try_discover_from_module(self, module_name: str) -> int:
-        """Try to discover rules from a module, return 0 on error."""
-        try:
-            return self._discover_from_module(module_name)
-        except (ImportError, AttributeError):
-            return 0
-
-    def _discover_from_module(self, module_path: str) -> int:
-        """Discover rules from a specific module.
-
-        Args:
-            module_path: Full module path to search.
+        discovered_rules = self._discovery.discover_from_package(package_path)
+        return sum(1 for rule in discovered_rules if self._try_register(rule))
 
-        Returns:
-            Number of rules discovered from this module.
-        """
+    def _try_register(self, rule: BaseLintRule) -> bool:
+        """Try to register a rule, return True if successful."""
         try:
-            module = importlib.import_module(module_path)
-        except (ImportError, AttributeError):
-            return 0
-
-        return self._register_rules_from_module(module)
-
-    def _register_rules_from_module(self, module: Any) -> int:
-        """Register all rule classes from a module."""
-        discovered_count = 0
-        for _name, obj in inspect.getmembers(module):
-            if not self._is_rule_class(obj):
-                continue
-            if self._try_register_rule_class(obj):
-                discovered_count += 1
-        return discovered_count
-
-    def _try_register_rule_class(self, rule_class: Any) -> bool:
-        """Try to instantiate and register a rule class."""
-        try:
-            rule_instance = rule_class()
-            self.register(rule_instance)
+            self.register(rule)
             return True
-        except (TypeError, AttributeError, ValueError):
+        except ValueError:
+            # Rule already registered, skip
             return False
-
-    def _is_rule_class(self, 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  # Don't instantiate the base class
-            and not inspect.isabstract(obj)  # Don't instantiate abstract classes
-        )

src/core/rule_discovery.py

@@ -0,0 +1,132 @@
+"""
+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: RuleDiscovery
+
+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
+
+
+class RuleDiscovery:
+    """Discovers linting rules from Python packages."""
+
+    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
+        """
+        try:
+            package = importlib.import_module(package_path)
+        except ImportError:
+            return []
+
+        if not hasattr(package, "__path__"):
+            return self._discover_from_module(package_path)
+
+        return self._discover_from_package_modules(package_path, package)
+
+    def _discover_from_package_modules(self, 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 = self._try_discover_from_module(full_module_name)
+            rules.extend(module_rules)
+        return rules
+
+    def _try_discover_from_module(self, 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 self._discover_from_module(module_name)
+        except (ImportError, AttributeError):
+            return []
+
+    def _discover_from_module(self, 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 self._is_rule_class(obj):
+                continue
+            rule_instance = self._try_instantiate_rule(obj)
+            if rule_instance:
+                rules.append(rule_instance)
+        return rules
+
+    def _try_instantiate_rule(self, 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(self, 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)
+        )

src/core/violation_builder.py

@@ -0,0 +1,122 @@
+"""
+Purpose: Base violation builder class for consistent violation creation across all linters
+
+Scope: Core violation building functionality used by all linter violation builders
+
+Overview: Provides base classes and data structures for violation creation across all linters.
+    Defines ViolationInfo dataclass containing all required and optional violation fields,
+    and BaseViolationBuilder class with common build() method. Eliminates duplicate violation
+    construction patterns across file_placement, nesting, and srp linters. Ensures consistent
+    violation creation with proper defaults for column and severity fields. Linter-specific
+    builders extend this base class to inherit common construction logic while maintaining
+    their domain-specific message generation and suggestion logic.
+
+Dependencies: dataclasses, src.core.types (Violation, Severity)
+
+Exports: ViolationInfo dataclass, BaseViolationBuilder class
+
+Interfaces: ViolationInfo(rule_id, file_path, line, message, column, severity),
+    BaseViolationBuilder.build(info: ViolationInfo) -> Violation
+
+Implementation: Uses dataclass for type-safe violation info, base class provides build()
+    method that constructs Violation objects with proper defaults
+"""
+
+from dataclasses import dataclass
+
+from src.core.types import Severity, Violation
+
+
+@dataclass
+class ViolationInfo:
+    """Information needed to build a violation.
+
+    Attributes:
+        rule_id: Identifier for the rule that was violated
+        file_path: Path to the file containing the violation
+        line: Line number where violation occurs (1-indexed)
+        message: Description of the violation
+        column: Column number where violation occurs (0-indexed, default=1)
+        severity: Severity level of the violation (default=ERROR)
+        suggestion: Optional suggestion for fixing the violation
+    """
+
+    rule_id: str
+    file_path: str
+    line: int
+    message: str
+    column: int = 1
+    severity: Severity = Severity.ERROR
+    suggestion: str | None = None
+
+
+class BaseViolationBuilder:
+    """Base class for building violations with consistent structure.
+
+    Provides common build() method for creating Violation objects from ViolationInfo.
+    Linter-specific builders extend this class to add their domain-specific violation
+    creation methods while inheriting the common construction logic.
+    """
+
+    def build(self, info: ViolationInfo) -> Violation:
+        """Build a Violation from ViolationInfo.
+
+        Args:
+            info: ViolationInfo containing all violation details
+
+        Returns:
+            Violation object with all fields populated
+        """
+        return Violation(
+            rule_id=info.rule_id,
+            file_path=info.file_path,
+            line=info.line,
+            column=info.column,
+            message=info.message,
+            severity=info.severity,
+            suggestion=info.suggestion,
+        )
+
+    def build_from_params(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+        self,
+        rule_id: str,
+        file_path: str,
+        line: int,
+        message: str,
+        column: int = 1,
+        severity: Severity = Severity.ERROR,
+        suggestion: str | None = None,
+    ) -> Violation:
+        """Build a Violation directly from parameters.
+
+        Note: Pylint too-many-arguments disabled. This convenience method mirrors the
+        ViolationInfo dataclass fields (7 parameters, 3 with defaults). The alternative
+        would require every caller to create ViolationInfo objects manually, reducing
+        readability. This is a standard builder pattern where all parameters are
+        inherently related (Violation fields).
+
+        This is a convenience method that combines ViolationInfo creation and build()
+        to reduce duplication in violation builder methods.
+
+        Args:
+            rule_id: Identifier for the rule that was violated
+            file_path: Path to the file containing the violation
+            line: Line number where violation occurs (1-indexed)
+            message: Description of the violation
+            column: Column number where violation occurs (0-indexed, default=1)
+            severity: Severity level of the violation (default=ERROR)
+            suggestion: Optional suggestion for fixing the violation
+
+        Returns:
+            Violation object with all fields populated
+        """
+        info = ViolationInfo(
+            rule_id=rule_id,
+            file_path=file_path,
+            line=line,
+            message=message,
+            column=column,
+            severity=severity,
+            suggestion=suggestion,
+        )
+        return self.build(info)