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

src/linters/file_header/violation_builder.py

@@ -0,0 +1,78 @@
+"""
+File: src/linters/file_header/violation_builder.py
+Purpose: Builds violation messages for file header linter
+Exports: ViolationBuilder class
+Depends: Violation type from core
+Implements: Message templates with context-specific details
+Related: linter.py for builder usage, atemporal_detector.py for temporal violations
+
+Overview:
+    Creates formatted violation messages for file header validation failures.
+    Handles missing fields, atemporal language, and other header issues with clear,
+    actionable messages. Provides consistent violation format across all validation types.
+
+Usage:
+    builder = ViolationBuilder("file-header.validation")
+    violation = builder.build_missing_field("Purpose", "test.py", 1)
+
+Notes: Follows standard violation format with rule_id, message, location, severity, suggestion
+"""
+
+from src.core.types import Severity, Violation
+
+
+class ViolationBuilder:
+    """Builds violation messages for file header issues."""
+
+    def __init__(self, rule_id: str):
+        """Initialize with rule ID.
+
+        Args:
+            rule_id: Rule identifier for violations
+        """
+        self.rule_id = rule_id
+
+    def build_missing_field(self, field_name: str, file_path: str, line: int = 1) -> Violation:
+        """Build violation for missing mandatory field.
+
+        Args:
+            field_name: Name of missing field
+            file_path: Path to file
+            line: Line number (default 1 for header)
+
+        Returns:
+            Violation object describing missing field
+        """
+        return Violation(
+            rule_id=self.rule_id,
+            message=f"Missing mandatory field: {field_name}",
+            file_path=file_path,
+            line=line,
+            column=1,
+            severity=Severity.ERROR,
+            suggestion=f"Add '{field_name}:' field to file header",
+        )
+
+    def build_atemporal_violation(
+        self, pattern: str, description: str, file_path: str, line: int
+    ) -> Violation:
+        """Build violation for temporal language.
+
+        Args:
+            pattern: Matched regex pattern
+            description: Description of temporal language
+            file_path: Path to file
+            line: Line number of violation
+
+        Returns:
+            Violation object describing temporal language issue
+        """
+        return Violation(
+            rule_id=self.rule_id,
+            message=f"Temporal language detected: {description}",
+            file_path=file_path,
+            line=line,
+            column=1,
+            severity=Severity.ERROR,
+            suggestion="Use present-tense factual descriptions without temporal references",
+        )

src/linters/file_placement/linter.py

@@ -75,9 +75,12 @@ class FilePlacementLinter:
         # Load and validate config
         if config_obj:
             # Handle both wrapped and unwrapped config formats
-            # Wrapped: {"file-placement": {...}}
+            # Wrapped: {"file-placement": {...}} or {"file_placement": {...}}
             # Unwrapped: {"directories": {...}, "global_deny": [...], ...}
-            self.config = config_obj.get("file-placement", config_obj)
+            # Try both hyphenated and underscored keys for backward compatibility
+            self.config = config_obj.get(
+                "file-placement", config_obj.get("file_placement", config_obj)
+            )
         elif config_file:
             self.config = self._components.config_loader.load_config_file(config_file)
         else:
@@ -279,7 +282,9 @@ class FilePlacementRule(BaseLintRule):  # thailint: ignore[srp.violation]
 
     @staticmethod
     def _get_wrapped_config(context: BaseLintContext) -> dict[str, Any] | None:
-        """Get config from wrapped format: {"file-placement": {...}}.
+        """Get config from wrapped format: {"file-placement": {...}} or {"file_placement": {...}}.
+
+        Supports both hyphenated and underscored keys for backward compatibility.
 
         Args:
             context: Lint context with metadata
@@ -289,8 +294,12 @@ class FilePlacementRule(BaseLintRule):  # thailint: ignore[srp.violation]
         """
         if not hasattr(context, "metadata"):
             return None
+        # Try hyphenated format first (original format)
         if "file-placement" in context.metadata:
             return context.metadata["file-placement"]
+        # Try underscored format (normalized format)
+        if "file_placement" in context.metadata:
+            return context.metadata["file_placement"]
         return None
 
     @staticmethod
@@ -378,9 +387,11 @@ class FilePlacementRule(BaseLintRule):  # thailint: ignore[srp.violation]
         try:
             config = self._parse_layout_file(layout_path)
 
-            # Unwrap file-placement key if present
+            # Unwrap file-placement key if present (try both formats for backward compatibility)
             if "file-placement" in config:
                 return config["file-placement"]
+            if "file_placement" in config:
+                return config["file_placement"]
 
             return config
         except Exception:

src/linters/magic_numbers/__init__.py

@@ -0,0 +1,48 @@
+"""
+Purpose: Magic numbers linter package exports and convenience functions
+
+Scope: Public API for magic numbers linter module
+
+Overview: Provides the public interface for the magic numbers linter package. Exports main
+    MagicNumberRule class for use by the orchestrator and MagicNumberConfig for configuration.
+    Includes lint() convenience function that provides a simple API for running the magic numbers
+    linter on a file or directory without directly interacting with the orchestrator. This module
+    serves as the entry point for users of the magic numbers linter, hiding implementation details
+    and exposing only the essential components needed for linting operations.
+
+Dependencies: .linter for MagicNumberRule, .config for MagicNumberConfig
+
+Exports: MagicNumberRule class, MagicNumberConfig dataclass, lint() convenience function
+
+Interfaces: lint(path, config) -> list[Violation] for simple linting operations
+
+Implementation: Module-level exports with __all__ definition, convenience function wrapper
+"""
+
+from .config import MagicNumberConfig
+from .linter import MagicNumberRule
+
+__all__ = ["MagicNumberRule", "MagicNumberConfig", "lint"]
+
+
+def lint(file_path: str, config: dict | None = None) -> list:
+    """Convenience function for linting a file for magic numbers.
+
+    Args:
+        file_path: Path to the file to lint
+        config: Optional configuration dictionary
+
+    Returns:
+        List of violations found
+    """
+    from pathlib import Path
+
+    from src.orchestrator.core import FileLintContext
+
+    rule = MagicNumberRule()
+    context = FileLintContext(
+        path=Path(file_path),
+        lang="python",
+    )
+
+    return rule.check(context)

src/linters/magic_numbers/config.py

@@ -0,0 +1,82 @@
+"""
+Purpose: Configuration schema for magic numbers linter
+
+Scope: MagicNumberConfig dataclass with allowed_numbers and max_small_integer settings
+
+Overview: Defines configuration schema for magic numbers linter. Provides MagicNumberConfig dataclass
+    with allowed_numbers set (default includes common acceptable numbers like -1, 0, 1, 2, 3, 4, 5, 10, 100, 1000)
+    and max_small_integer threshold (default 10) for range() contexts. Supports per-file and per-directory
+    config overrides through from_dict class method. Validates that configuration values are appropriate
+    types. Integrates with orchestrator's configuration system to allow users to customize allowed numbers
+    via .thailint.yaml configuration files.
+
+Dependencies: dataclasses for class definition, typing for type hints
+
+Exports: MagicNumberConfig dataclass
+
+Interfaces: MagicNumberConfig(allowed_numbers: set, max_small_integer: int, enabled: bool),
+    from_dict class method for loading configuration from dictionary
+
+Implementation: Dataclass with validation and defaults, matches reference implementation patterns
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class MagicNumberConfig:
+    """Configuration for magic numbers linter."""
+
+    enabled: bool = True
+    allowed_numbers: set[int | float] = field(
+        default_factory=lambda: {-1, 0, 1, 2, 3, 4, 5, 10, 100, 1000}
+    )
+    max_small_integer: int = 10
+    ignore: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        """Validate configuration values."""
+        if self.max_small_integer <= 0:
+            raise ValueError(f"max_small_integer must be positive, got {self.max_small_integer}")
+
+    @classmethod
+    def from_dict(cls, config: dict[str, Any], language: str | None = None) -> "MagicNumberConfig":
+        """Load configuration from dictionary with language-specific overrides.
+
+        Args:
+            config: Dictionary containing configuration values
+            language: Programming language (python, typescript, javascript)
+                for language-specific settings
+
+        Returns:
+            MagicNumberConfig instance with values from dictionary
+        """
+        # Get language-specific config if available
+        if language and language in config:
+            lang_config = config[language]
+            allowed_numbers = set(
+                lang_config.get(
+                    "allowed_numbers",
+                    config.get("allowed_numbers", {-1, 0, 1, 2, 3, 4, 5, 10, 100, 1000}),
+                )
+            )
+            max_small_integer = lang_config.get(
+                "max_small_integer", config.get("max_small_integer", 10)
+            )
+        else:
+            allowed_numbers = set(
+                config.get("allowed_numbers", {-1, 0, 1, 2, 3, 4, 5, 10, 100, 1000})
+            )
+            max_small_integer = config.get("max_small_integer", 10)
+
+        ignore_patterns = config.get("ignore", [])
+        if not isinstance(ignore_patterns, list):
+            ignore_patterns = []
+
+        return cls(
+            enabled=config.get("enabled", True),
+            allowed_numbers=allowed_numbers,
+            max_small_integer=max_small_integer,
+            ignore=ignore_patterns,
+        )

src/linters/magic_numbers/context_analyzer.py

@@ -0,0 +1,247 @@
+"""
+Purpose: Analyzes contexts to determine if numeric literals are acceptable
+
+Scope: Context detection for magic number acceptable usage patterns
+
+Overview: Provides ContextAnalyzer class that determines whether a numeric literal is in an acceptable
+    context where it should not be flagged as a magic number. Detects acceptable contexts including
+    constant definitions (UPPERCASE names), small integers in range() or enumerate() calls, test files,
+    and configuration contexts. Uses AST node analysis to inspect parent nodes and determine the usage
+    pattern of numeric literals. Helps reduce false positives by distinguishing between legitimate
+    numeric literals and true magic numbers that should be extracted to constants. Method count (10)
+    exceeds SRP limit (8) because refactoring for A-grade complexity requires extracting helper methods.
+    Class maintains single responsibility of context analysis - all methods support this core purpose.
+
+Dependencies: ast module for AST node types, pathlib for Path handling
+
+Exports: ContextAnalyzer class
+
+Interfaces: ContextAnalyzer.is_acceptable_context(node, parent, file_path, config) -> bool,
+    various helper methods for specific context checks
+
+Implementation: AST parent node inspection, pattern matching for acceptable contexts, configurable
+    max_small_integer threshold for range detection
+"""
+
+import ast
+from pathlib import Path
+
+
+class ContextAnalyzer:  # thailint: ignore[srp]
+    """Analyzes contexts to determine if numeric literals are acceptable."""
+
+    def is_acceptable_context(
+        self,
+        node: ast.Constant,
+        parent: ast.AST | None,
+        file_path: Path | None,
+        config: dict,
+    ) -> bool:
+        """Check if a numeric literal is in an acceptable context.
+
+        Args:
+            node: The numeric constant node
+            parent: The parent node in the AST
+            file_path: Path to the file being analyzed
+            config: Configuration with allowed_numbers and max_small_integer
+
+        Returns:
+            True if the context is acceptable and should not be flagged
+        """
+        # File-level and definition checks
+        if self.is_test_file(file_path) or self.is_constant_definition(node, parent):
+            return True
+
+        # Usage pattern checks
+        return self._is_acceptable_usage_pattern(node, parent, config)
+
+    def _is_acceptable_usage_pattern(
+        self, node: ast.Constant, parent: ast.AST | None, config: dict
+    ) -> bool:
+        """Check if numeric literal is in acceptable usage pattern.
+
+        Args:
+            node: The numeric constant node
+            parent: The parent node in the AST
+            config: Configuration with max_small_integer threshold
+
+        Returns:
+            True if usage pattern is acceptable
+        """
+        if self.is_small_integer_in_range(node, parent, config):
+            return True
+
+        if self.is_small_integer_in_enumerate(node, parent, config):
+            return True
+
+        return self.is_string_repetition(node, parent)
+
+    def is_test_file(self, file_path: Path | None) -> bool:
+        """Check if the file is a test file.
+
+        Args:
+            file_path: Path to the file
+
+        Returns:
+            True if the file is a test file (matches test_*.py pattern)
+        """
+        if not file_path:
+            return False
+        return file_path.name.startswith("test_") or "_test.py" in file_path.name
+
+    def is_constant_definition(self, node: ast.Constant, parent: ast.AST | None) -> bool:
+        """Check if the number is part of an UPPERCASE constant definition.
+
+        Args:
+            node: The numeric constant node
+            parent: The parent node in the AST
+
+        Returns:
+            True if this is a constant definition
+        """
+        if not self._is_assignment_node(parent):
+            return False
+
+        # Type narrowing: parent is ast.Assign after the check above
+        assert isinstance(parent, ast.Assign)  # nosec B101
+        return self._has_constant_target(parent)
+
+    def _is_assignment_node(self, parent: ast.AST | None) -> bool:
+        """Check if parent is an assignment node."""
+        return parent is not None and isinstance(parent, ast.Assign)
+
+    def _has_constant_target(self, parent: ast.Assign) -> bool:
+        """Check if assignment has uppercase constant target."""
+        return any(
+            isinstance(target, ast.Name) and self._is_constant_name(target.id)
+            for target in parent.targets
+        )
+
+    def _is_constant_name(self, name: str) -> bool:
+        """Check if a name follows constant naming convention.
+
+        Args:
+            name: Variable name to check
+
+        Returns:
+            True if the name is UPPERCASE (constant convention)
+        """
+        return name.isupper() and len(name) > 1
+
+    def is_small_integer_in_range(
+        self, node: ast.Constant, parent: ast.AST | None, config: dict
+    ) -> bool:
+        """Check if this is a small integer used in range() call.
+
+        Args:
+            node: The numeric constant node
+            parent: The parent node in the AST
+            config: Configuration with max_small_integer threshold
+
+        Returns:
+            True if this is a small integer in range()
+        """
+        if not isinstance(node.value, int):
+            return False
+
+        max_small_int = config.get("max_small_integer", 10)
+        if not 0 <= node.value <= max_small_int:
+            return False
+
+        return self._is_in_range_call(parent)
+
+    def is_small_integer_in_enumerate(
+        self, node: ast.Constant, parent: ast.AST | None, config: dict
+    ) -> bool:
+        """Check if this is a small integer used in enumerate() call.
+
+        Args:
+            node: The numeric constant node
+            parent: The parent node in the AST
+            config: Configuration with max_small_integer threshold
+
+        Returns:
+            True if this is a small integer in enumerate()
+        """
+        if not isinstance(node.value, int):
+            return False
+
+        max_small_int = config.get("max_small_integer", 10)
+        if not 0 <= node.value <= max_small_int:
+            return False
+
+        return self._is_in_enumerate_call(parent)
+
+    def _is_in_range_call(self, parent: ast.AST | None) -> bool:
+        """Check if the parent is a range() call.
+
+        Args:
+            parent: The parent node
+
+        Returns:
+            True if parent is range() call
+        """
+        return (
+            isinstance(parent, ast.Call)
+            and isinstance(parent.func, ast.Name)
+            and parent.func.id == "range"
+        )
+
+    def _is_in_enumerate_call(self, parent: ast.AST | None) -> bool:
+        """Check if the parent is an enumerate() call.
+
+        Args:
+            parent: The parent node
+
+        Returns:
+            True if parent is enumerate() call
+        """
+        return (
+            isinstance(parent, ast.Call)
+            and isinstance(parent.func, ast.Name)
+            and parent.func.id == "enumerate"
+        )
+
+    def is_string_repetition(self, node: ast.Constant, parent: ast.AST | None) -> bool:
+        """Check if this number is used in string repetition (e.g., "-" * 40).
+
+        Args:
+            node: The numeric constant node
+            parent: The parent node in the AST
+
+        Returns:
+            True if this is a string repetition pattern
+        """
+        if not isinstance(node.value, int):
+            return False
+
+        if not isinstance(parent, ast.BinOp):
+            return False
+
+        if not isinstance(parent.op, ast.Mult):
+            return False
+
+        # Check if either operand is a string constant
+        return self._has_string_operand(parent)
+
+    def _has_string_operand(self, binop: ast.BinOp) -> bool:
+        """Check if binary operation has a string operand.
+
+        Args:
+            binop: Binary operation node
+
+        Returns:
+            True if either left or right operand is a string constant
+        """
+        return self._is_string_constant(binop.left) or self._is_string_constant(binop.right)
+
+    def _is_string_constant(self, node: ast.AST) -> bool:
+        """Check if a node is a string constant.
+
+        Args:
+            node: AST node to check
+
+        Returns:
+            True if node is a Constant with string value
+        """
+        return isinstance(node, ast.Constant) and isinstance(node.value, str)