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

src/core/cli_utils.py

@@ -26,6 +26,8 @@ from typing import Any
 
 import click
 
+from src.core.constants import CONFIG_EXTENSIONS
+
 
 def common_linter_options(func: Callable) -> Callable:
     """Add common linter CLI options to command.
@@ -103,7 +105,7 @@ def _load_config_by_format(config_file: Path) -> dict[str, Any]:
     Returns:
         Loaded configuration dictionary
     """
-    if config_file.suffix in {".yaml", ".yml"}:
+    if config_file.suffix in CONFIG_EXTENSIONS:
         return _load_yaml_config(config_file)
     if config_file.suffix == ".json":
         return _load_json_config(config_file)
@@ -146,10 +148,12 @@ def format_violations(violations: list, output_format: str) -> None:
 
     Args:
         violations: List of violation objects with rule_id, file_path, line, column, message, severity
-        output_format: Output format ("text" or "json")
+        output_format: Output format ("text", "json", or "sarif")
     """
     if output_format == "json":
         _output_json(violations)
+    elif output_format == "sarif":
+        _output_sarif(violations)
     else:
         _output_text(violations)
 
@@ -177,6 +181,19 @@ def _output_json(violations: list) -> None:
     click.echo(json.dumps(output, indent=2))
 
 
+def _output_sarif(violations: list) -> None:
+    """Output violations in SARIF v2.1.0 format.
+
+    Args:
+        violations: List of violation objects
+    """
+    from src.formatters.sarif import SarifFormatter
+
+    formatter = SarifFormatter()
+    sarif_doc = formatter.format(violations)
+    click.echo(json.dumps(sarif_doc, indent=2))
+
+
 def _output_text(violations: list) -> None:
     """Output violations in human-readable text format.
 

src/core/config_parser.py

@@ -27,6 +27,8 @@ from typing import Any, TextIO
 
 import yaml
 
+from src.core.constants import CONFIG_EXTENSIONS
+
 
 class ConfigParseError(Exception):
     """Configuration file parsing errors."""
@@ -113,11 +115,12 @@ def parse_config_file(path: Path, encoding: str = "utf-8") -> dict[str, Any]:
     """
     suffix = path.suffix.lower()
 
-    if suffix not in [".yaml", ".yml", ".json"]:
+    valid_suffixes = (*CONFIG_EXTENSIONS, ".json")
+    if suffix not in valid_suffixes:
         raise ConfigParseError(f"Unsupported config format: {suffix}")
 
     with path.open(encoding=encoding) as f:
-        if suffix in [".yaml", ".yml"]:
+        if suffix in CONFIG_EXTENSIONS:
             config = parse_yaml(f, path)
         else:
             config = parse_json(f, path)

src/core/constants.py

@@ -0,0 +1,54 @@
+"""
+Purpose: Core constants and enums used across the thai-lint codebase
+
+Scope: Centralized definitions for language names, storage modes, config extensions
+
+Overview: Provides type-safe enums and constants for consistent stringly-typed patterns
+    across the codebase. Includes Language enum for programming language detection,
+    StorageMode for cache storage options, and CONFIG_EXTENSIONS for config file
+    discovery. Using enums ensures compile-time safety and IDE autocompletion.
+
+Dependencies: enum module
+
+Exports: Language enum, StorageMode enum, CONFIG_EXTENSIONS, IgnoreDirective enum,
+    HEADER_SCAN_LINES, MAX_ATTRIBUTE_CHAIN_DEPTH
+
+Interfaces: Use enum values instead of string literals throughout codebase
+
+Implementation: Standard Python enums with string values for compatibility
+"""
+
+from enum import Enum
+
+
+class Language(str, Enum):
+    """Supported programming languages for linting."""
+
+    PYTHON = "python"
+    TYPESCRIPT = "typescript"
+    JAVASCRIPT = "javascript"
+    MARKDOWN = "markdown"
+
+
+class StorageMode(str, Enum):
+    """Storage modes for DRY linter cache."""
+
+    MEMORY = "memory"
+    TEMPFILE = "tempfile"
+
+
+class IgnoreDirective(str, Enum):
+    """Inline ignore directive types."""
+
+    IGNORE = "ignore"
+    IGNORE_FILE = "ignore-file"
+
+
+# Valid config file extensions
+CONFIG_EXTENSIONS: tuple[str, str] = (".yaml", ".yml")
+
+# Number of lines to scan at file start for ignore directives and headers
+HEADER_SCAN_LINES: int = 10
+
+# Maximum depth for attribute chain traversal (e.g., obj.attr.attr2.attr3)
+MAX_ATTRIBUTE_CHAIN_DEPTH: int = 3

src/core/linter_utils.py

@@ -1,26 +1,48 @@
 """
 Purpose: Shared utility functions for linter framework patterns
 
-Scope: Common config loading, metadata access, and context validation utilities for all linters
+Scope: Common config loading, metadata access, context validation, and AST parsing utilities
 
 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.
+    extracting metadata fields safely with type validation, validating context state, and parsing
+    Python AST with syntax error handling. Standardizes common patterns used by srp, nesting, dry,
+    performance, and file_placement linters. Reduces boilerplate code while maintaining type safety
+    and proper error handling.
 
-Dependencies: BaseLintContext from src.core.base
+Dependencies: BaseLintContext from src.core.base, ast for Python parsing
 
-Exports: get_metadata, get_metadata_value, load_linter_config, has_file_content
+Exports: get_metadata, get_metadata_value, load_linter_config, has_file_content, parse_python_ast,
+    with_parsed_python
 
 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
+
+Suppressions:
+    - invalid-name: T type variable follows Python generic naming convention
+    - type:ignore[return-value]: Generic config factory with runtime type checking
+    - unnecessary-ellipsis: Protocol method bodies use ellipsis per PEP 544
+    - B101: Assert used to narrow type after parse_python_ast returns non-None tree
 """
 
+import ast
+from collections.abc import Callable
 from typing import Any, Protocol, TypeVar
 
 from src.core.base import BaseLintContext
+from src.core.types import Violation
+
+
+# Protocol for violation builders that support syntax error handling
+class SyntaxErrorViolationBuilder(Protocol):
+    """Protocol for violation builders that can create syntax error violations."""
+
+    def create_syntax_error_violation(
+        self, error: SyntaxError, context: BaseLintContext
+    ) -> Violation:
+        """Create a violation for a syntax error."""
+        ...  # pylint: disable=unnecessary-ellipsis
 
 
 # Protocol for config classes that support from_dict
@@ -166,3 +188,70 @@ def should_process_file(context: BaseLintContext) -> bool:
         True if file has both content and path available
     """
     return has_file_content(context) and has_file_path(context)
+
+
+def parse_python_ast(
+    context: BaseLintContext,
+    violation_builder: SyntaxErrorViolationBuilder,
+) -> tuple[ast.Module | None, list[Violation]]:
+    """Parse Python AST from context, handling syntax errors gracefully.
+
+    Provides a standard pattern for Python linters to parse AST and handle
+    syntax errors by returning a violation instead of crashing.
+
+    Args:
+        context: Lint context containing file content
+        violation_builder: Builder to create syntax error violations
+
+    Returns:
+        Tuple of (ast_tree, violations):
+        - On success: (ast.Module, [])
+        - On syntax error: (None, [syntax_error_violation])
+
+    Example:
+        tree, errors = parse_python_ast(context, self._violation_builder)
+        if errors:
+            return errors
+        # ... use tree for analysis
+    """
+    try:
+        tree = ast.parse(context.file_content or "")
+        return tree, []
+    except SyntaxError as e:
+        violation = violation_builder.create_syntax_error_violation(e, context)
+        return None, [violation]
+
+
+def with_parsed_python(
+    context: BaseLintContext,
+    violation_builder: SyntaxErrorViolationBuilder,
+    on_success: Callable[[ast.Module], list[Violation]],
+) -> list[Violation]:
+    """Parse Python and call on_success with the AST, or return parse errors.
+
+    Eliminates the repeated parse-check-assert pattern across Python linters.
+    On parse success, calls on_success with a guaranteed non-None AST tree.
+    On parse failure, returns syntax error violations.
+
+    Args:
+        context: Lint context containing file content
+        violation_builder: Builder to create syntax error violations
+        on_success: Callback receiving the parsed AST tree, returns violations
+
+    Returns:
+        Violations from on_success callback, or syntax error violations
+
+    Example:
+        def _check_python(self, context, config):
+            return with_parsed_python(
+                context,
+                self._violation_builder,
+                lambda tree: self._analyze_tree(tree, config, context),
+            )
+    """
+    tree, errors = parse_python_ast(context, violation_builder)
+    if errors:
+        return errors
+    # tree is guaranteed non-None when errors is empty (parse_python_ast contract)
+    assert tree is not None  # nosec B101
+    return on_success(tree)

src/core/python_lint_rule.py

@@ -0,0 +1,101 @@
+"""
+Purpose: Base class for Python-only linters with common boilerplate
+
+Scope: Shared infrastructure for Python-only lint rules
+
+Overview: Provides PythonOnlyLintRule abstract base class that handles common boilerplate
+    for Python-only linters. Subclasses implement the abstract properties and analysis
+    method while the base class handles language checking, config loading, and enabled
+    checking. This eliminates duplicate code across Python-only linters like CQS and LBYL.
+
+Dependencies: BaseLintRule, BaseLintContext, Language, load_linter_config, has_file_content
+
+Exports: PythonOnlyLintRule
+
+Interfaces: Subclasses implement _config_key, _config_class, _analyze, and rule metadata
+
+Implementation: Template method pattern for Python linter boilerplate
+"""
+
+from abc import abstractmethod
+from typing import Any, Generic
+
+from .base import BaseLintContext, BaseLintRule
+from .constants import Language
+from .linter_utils import ConfigType, has_file_content, load_linter_config
+from .types import Violation
+
+
+class PythonOnlyLintRule(BaseLintRule, Generic[ConfigType]):
+    """Base class for Python-only linters with common boilerplate.
+
+    Handles language checking, config loading, and enabled checking.
+    Subclasses provide the config key, config class, and analysis logic.
+    """
+
+    def __init__(self, config: ConfigType | None = None) -> None:
+        """Initialize with optional config override.
+
+        Args:
+            config: Optional configuration override for testing
+        """
+        self._config_override = config
+
+    @property
+    @abstractmethod
+    def _config_key(self) -> str:
+        """Configuration key in metadata (e.g., 'cqs', 'lbyl')."""
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def _config_class(self) -> type[ConfigType]:
+        """Configuration class type."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def _analyze(self, code: str, file_path: str, config: ConfigType) -> list[Violation]:
+        """Perform linter-specific analysis.
+
+        Args:
+            code: Python source code
+            file_path: Path to the file
+            config: Loaded configuration
+
+        Returns:
+            List of violations found
+        """
+        raise NotImplementedError
+
+    def check(self, context: BaseLintContext) -> list[Violation]:
+        """Check for violations in the given context.
+
+        Args:
+            context: The lint context containing file information.
+
+        Returns:
+            List of violations found.
+        """
+        if not self._should_analyze(context):
+            return []
+
+        config = self._get_config(context)
+        if not self._is_enabled(config):
+            return []
+
+        file_path = str(context.file_path) if context.file_path else "unknown"
+        return self._analyze(context.file_content or "", file_path, config)
+
+    def _should_analyze(self, context: BaseLintContext) -> bool:
+        """Check if context should be analyzed."""
+        return context.language == Language.PYTHON and has_file_content(context)
+
+    def _get_config(self, context: BaseLintContext) -> ConfigType:
+        """Get configuration, using override if provided."""
+        if self._config_override is not None:
+            return self._config_override
+        return load_linter_config(context, self._config_key, self._config_class)
+
+    def _is_enabled(self, config: Any) -> bool:
+        """Check if linter is enabled in config."""
+        return getattr(config, "enabled", True)

src/core/registry.py

@@ -6,7 +6,7 @@ Scope: Dynamic rule management and discovery across all linter plugin packages
 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
+    the extensible plugin architecture by allowing dynamic rule registration without framework
     modifications. Validates rule uniqueness and handles registration errors gracefully.
 
 Dependencies: BaseLintRule, RuleDiscovery

src/core/rule_discovery.py

@@ -10,7 +10,7 @@ Overview: Provides automatic rule discovery functionality for the linter framewo
 
 Dependencies: importlib, inspect, pkgutil, BaseLintRule
 
-Exports: RuleDiscovery
+Exports: discover_from_package function, RuleDiscovery class (compat)
 
 Interfaces: discover_from_package(package_path) -> list[BaseLintRule]
 
@@ -19,114 +19,177 @@ Implementation: Package traversal with pkgutil, class introspection with inspect
 
 import importlib
 import inspect
+import logging
 import pkgutil
+from types import ModuleType
 from typing import Any
 
 from .base import BaseLintRule
 
+logger = logging.getLogger(__name__)
 
-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.
+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')
+    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 []
+    Returns:
+        List of discovered rule instances
+    """
+    try:
+        package = importlib.import_module(package_path)
+    except ImportError as e:
+        logger.debug("Failed to import package %s: %s", package_path, e)
+        return []
 
-        if not hasattr(package, "__path__"):
-            return self._discover_from_module(package_path)
+    if not hasattr(package, "__path__"):
+        return _discover_from_module(package_path)
 
-        return self._discover_from_package_modules(package_path, package)
+    return _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
+def _discover_from_package_modules(package_path: str, package: Any) -> list[BaseLintRule]:
+    """Discover rules from all modules in a package.
 
-        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
+    Args:
+        package_path: Package path
+        package: Imported package object
 
-    def _try_discover_from_module(self, module_name: str) -> list[BaseLintRule]:
-        """Try to discover rules from a module, return empty list on error.
+    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
 
-        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 _try_discover_from_module(module_name: str) -> list[BaseLintRule]:
+    """Try to discover rules from a module, return empty list on error.
 
-    def _discover_from_module(self, module_path: str) -> list[BaseLintRule]:
-        """Discover rules from a specific module.
+    Args:
+        module_name: Full module name
 
-        Args:
-            module_path: Full module path to search
+    Returns:
+        List of discovered rules (empty on error)
+    """
+    try:
+        return _discover_from_module(module_name)
+    except (ImportError, AttributeError):
+        return []
 
-        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
+def _discover_from_module(module_path: str) -> list[BaseLintRule]:
+    """Discover rules from a specific module.
 
-        Returns:
-            Rule instance or None on error
-        """
-        try:
-            return rule_class()
-        except (TypeError, AttributeError):
-            return None
+    Args:
+        module_path: Full module path to search
+
+    Returns:
+        List of discovered rule instances
+    """
+    module = _try_import_module(module_path)
+    if module is None:
+        return []
+    return _extract_rules_from_module(module)
+
+
+def _try_import_module(module_path: str) -> ModuleType | None:
+    """Try to import a module, returning None on failure.
+
+    Args:
+        module_path: Full module path to import
+
+    Returns:
+        Module object or None if import fails
+    """
+    try:
+        return importlib.import_module(module_path)
+    except (ImportError, AttributeError):
+        return None
 
-    def _is_rule_class(self, obj: Any) -> bool:
-        """Check if an object is a valid rule class.
+
+def _extract_rules_from_module(module: ModuleType) -> list[BaseLintRule]:
+    """Extract rule instances from a module.
+
+    Args:
+        module: Imported module to scan
+
+    Returns:
+        List of discovered rule instances
+    """
+    rule_classes = [obj for _name, obj in inspect.getmembers(module) if _is_rule_class(obj)]
+    return _instantiate_rules(rule_classes)
+
+
+def _instantiate_rules(rule_classes: list[type[BaseLintRule]]) -> list[BaseLintRule]:
+    """Instantiate a list of rule classes.
+
+    Args:
+        rule_classes: List of rule classes to instantiate
+
+    Returns:
+        List of successfully instantiated rules
+    """
+    instances = (_try_instantiate_rule(cls) for cls in rule_classes)
+    return [inst for inst in instances if inst is not None]
+
+
+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:
-            obj: Object to check
+            package_path: Python package path (e.g., 'src.linters')
 
         Returns:
-            True if obj is a concrete BaseLintRule subclass
+            List of discovered rule instances
         """
-        return (
-            inspect.isclass(obj)
-            and issubclass(obj, BaseLintRule)
-            and obj is not BaseLintRule
-            and not inspect.isabstract(obj)
-        )
+        return discover_from_package(package_path)

src/core/types.py

@@ -81,3 +81,16 @@ class Violation:
             "severity": self.severity.value,
             "suggestion": self.suggestion,
         }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Violation":
+        """Reconstruct Violation from dictionary (for parallel processing)."""
+        return cls(
+            rule_id=data["rule_id"],
+            file_path=data["file_path"],
+            line=data["line"],
+            column=data["column"],
+            message=data["message"],
+            severity=Severity(data["severity"]),
+            suggestion=data.get("suggestion"),
+        )