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

src/core/base.py

@@ -8,14 +8,17 @@ Overview: Establishes the contract that all linting plugins must follow through
     Defines BaseLintRule which all concrete linting rules inherit from, specifying required
     properties (rule_id, rule_name, description) and the check() method for violation detection.
     Provides BaseLintContext as the interface for accessing file information during analysis,
-    exposing file_path, file_content, and language properties. These abstractions enable the
-    rule registry to discover and instantiate rules dynamically without tight coupling, supporting
-    the extensible plugin system where new rules can be added by simply placing them in the
-    appropriate directory structure.
+    exposing file_path, file_content, and language properties. Includes MultiLanguageLintRule
+    intermediate class implementing template method pattern for language dispatch, eliminating
+    code duplication across multi-language linters (nesting, srp, magic_numbers). These
+    abstractions enable the rule registry to discover and instantiate rules dynamically without
+    tight coupling, supporting the extensible plugin system where new rules can be added by
+    simply placing them in the appropriate directory structure.
 
 Dependencies: abc for abstract base class support, pathlib for Path types, Violation from types
 
-Exports: BaseLintRule (abstract rule interface), BaseLintContext (abstract context interface)
+Exports: BaseLintRule (abstract rule interface), BaseLintContext (abstract context interface),
+    MultiLanguageLintRule (template method base for multi-language linters)
 
 Interfaces: BaseLintRule.check(context) -> list[Violation], BaseLintContext properties
     (file_path, file_content, language), all abstract methods must be implemented by subclasses
@@ -26,7 +29,9 @@ Implementation: ABC-based interface definitions with @abstractmethod decorators,
 
 from abc import ABC, abstractmethod
 from pathlib import Path
+from typing import Any
 
+from .constants import Language
 from .types import Violation
 
 
@@ -132,3 +137,88 @@ class BaseLintRule(ABC):
             List of violations found during finalization. Empty list by default.
         """
         return []
+
+
+class MultiLanguageLintRule(BaseLintRule):
+    """Base class for linting rules that support multiple programming languages.
+
+    Provides language dispatch pattern to eliminate code duplication across multi-language
+    linters. Subclasses implement language-specific checking methods rather than handling
+    dispatch logic themselves.
+
+    Subclasses must implement:
+    - _check_python(context, config) for Python language support
+    - _check_typescript(context, config) for TypeScript/JavaScript support
+    - _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.
+
+        Dispatches to language-specific checking methods based on context.language.
+        Handles common patterns like file content validation and config loading.
+
+        Args:
+            context: Lint context with file information
+
+        Returns:
+            List of violations found
+        """
+        from .linter_utils import has_file_content
+
+        if not has_file_content(context):
+            return []
+
+        config = self._load_config(context)
+        if not config.enabled:
+            return []
+
+        if context.language == Language.PYTHON:
+            return self._check_python(context, config)
+
+        if context.language in (Language.TYPESCRIPT, Language.JAVASCRIPT):
+            return self._check_typescript(context, config)
+
+        return []
+
+    @abstractmethod
+    def _load_config(self, context: BaseLintContext) -> Any:
+        """Load configuration from context.
+
+        Args:
+            context: Lint context
+
+        Returns:
+            Configuration object with at minimum an 'enabled' attribute
+        """
+        raise NotImplementedError("Subclasses must implement _load_config")
+
+    @abstractmethod
+    def _check_python(self, context: BaseLintContext, config: Any) -> list[Violation]:
+        """Check Python code for violations.
+
+        Args:
+            context: Lint context with Python file information
+            config: Loaded configuration
+
+        Returns:
+            List of violations found in Python code
+        """
+        raise NotImplementedError("Subclasses must implement _check_python")
+
+    @abstractmethod
+    def _check_typescript(self, context: BaseLintContext, config: Any) -> list[Violation]:
+        """Check TypeScript/JavaScript code for violations.
+
+        Args:
+            context: Lint context with TypeScript/JavaScript file information
+            config: Loaded configuration
+
+        Returns:
+            List of violations found in TypeScript/JavaScript code
+        """
+        raise NotImplementedError("Subclasses must implement _check_typescript")

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."""
@@ -72,28 +74,56 @@ def parse_json(file_obj: TextIO, path: Path) -> dict[str, Any]:
         raise ConfigParseError(f"Invalid JSON in {path}: {e}") from e
 
 
+def _normalize_config_keys(config: dict[str, Any]) -> dict[str, Any]:
+    """Normalize configuration keys from hyphens to underscores.
+
+    Converts top-level keys like "magic-numbers" to "magic_numbers" to match
+    internal linter expectations while maintaining backward compatibility with
+    both formats in config files.
+
+    Args:
+        config: Configuration dictionary with potentially hyphenated keys
+
+    Returns:
+        Configuration dictionary with normalized (underscored) keys
+    """
+    normalized = {}
+    for key, value in config.items():
+        # Replace hyphens with underscores in keys
+        normalized_key = key.replace("-", "_")
+        normalized[normalized_key] = value
+    return normalized
+
+
 def parse_config_file(path: Path, encoding: str = "utf-8") -> dict[str, Any]:
     """Parse configuration file based on extension.
 
     Supports .yaml, .yml, and .json formats. Automatically detects format
-    from file extension and uses appropriate parser.
+    from file extension and uses appropriate parser. Normalizes hyphenated
+    keys (e.g., "magic-numbers") to underscored keys (e.g., "magic_numbers")
+    for internal consistency.
 
     Args:
         path: Path to configuration file.
         encoding: File encoding (default: utf-8).
 
     Returns:
-        Parsed configuration dictionary.
+        Parsed configuration dictionary with normalized keys.
 
     Raises:
         ConfigParseError: If file format is unsupported or parsing fails.
     """
     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"]:
-            return parse_yaml(f, path)
-        return parse_json(f, path)
+        if suffix in CONFIG_EXTENSIONS:
+            config = parse_yaml(f, path)
+        else:
+            config = parse_json(f, path)
+
+    # Normalize keys from hyphens to underscores
+    return _normalize_config_keys(config)

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