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

src/linters/magic_numbers/python_analyzer.py

@@ -0,0 +1,64 @@
+"""
+Purpose: Python AST analysis for finding numeric literal nodes
+
+Scope: Python magic number detection through AST traversal
+
+Overview: Provides PythonMagicNumberAnalyzer class that traverses Python AST to find all numeric
+    literal nodes (integers and floats). Uses ast.NodeVisitor pattern to walk the syntax tree and
+    collect Constant nodes containing numeric values along with their parent nodes and line numbers.
+    Returns structured data about each numeric literal including the AST node, parent node, numeric
+    value, and source location. This analyzer handles Python-specific AST structure and provides
+    the foundation for magic number detection by identifying all candidates before context filtering.
+
+Dependencies: ast module for AST parsing and node types, analyzers.ast_utils
+
+Exports: PythonMagicNumberAnalyzer class
+
+Interfaces: PythonMagicNumberAnalyzer.find_numeric_literals(tree) -> list[tuple],
+    returns list of (node, parent, value, line_number) tuples
+
+Implementation: AST NodeVisitor pattern with parent tracking, filters for numeric Constant nodes
+"""
+
+import ast
+from typing import Any
+
+from src.analyzers.ast_utils import build_parent_map
+
+
+class PythonMagicNumberAnalyzer(ast.NodeVisitor):
+    """Analyzes Python AST to find numeric literals."""
+
+    def __init__(self) -> None:
+        """Initialize the analyzer."""
+        self.numeric_literals: list[tuple[ast.Constant, ast.AST | None, Any, int]] = []
+        self.parent_map: dict[ast.AST, ast.AST] = {}
+
+    def find_numeric_literals(
+        self, tree: ast.AST
+    ) -> list[tuple[ast.Constant, ast.AST | None, Any, int]]:
+        """Find all numeric literals in the AST.
+
+        Args:
+            tree: The AST to analyze
+
+        Returns:
+            List of tuples (node, parent, value, line_number)
+        """
+        self.numeric_literals = []
+        self.parent_map = build_parent_map(tree)
+        self.visit(tree)
+        return self.numeric_literals
+
+    def visit_Constant(self, node: ast.Constant) -> None:
+        """Visit a Constant node and check if it's a numeric literal.
+
+        Args:
+            node: The Constant node to check
+        """
+        if isinstance(node.value, (int, float)):
+            parent = self.parent_map.get(node)
+            line_number = node.lineno if hasattr(node, "lineno") else 0
+            self.numeric_literals.append((node, parent, node.value, line_number))
+
+        self.generic_visit(node)

src/linters/magic_numbers/typescript_analyzer.py

@@ -0,0 +1,215 @@
+"""
+Purpose: TypeScript/JavaScript magic number detection using Tree-sitter AST analysis
+
+Scope: Tree-sitter based numeric literal detection for TypeScript and JavaScript code
+
+Overview: Analyzes TypeScript and JavaScript code to detect numeric literals that should be
+    extracted to named constants. Uses Tree-sitter parser to traverse TypeScript AST and
+    identify numeric literal nodes with their line numbers and values. Detects acceptable
+    contexts such as enum definitions and UPPERCASE constant declarations to avoid false
+    positives. Supports both TypeScript and JavaScript files with shared detection logic.
+    Handles TypeScript-specific syntax including enums, const assertions, readonly properties,
+    arrow functions, async functions, and class methods.
+
+Dependencies: TypeScriptBaseAnalyzer for tree-sitter parsing, tree-sitter Node type
+
+Exports: TypeScriptMagicNumberAnalyzer class with find_numeric_literals and context detection
+
+Interfaces: find_numeric_literals(root_node) -> list[tuple], is_enum_context(node),
+    is_constant_definition(node)
+
+Implementation: Tree-sitter node traversal with visitor pattern, context-aware filtering
+    for acceptable numeric literal locations
+
+Suppressions:
+    - srp: Analyzer implements tree-sitter traversal with context detection methods.
+        Methods support single responsibility of magic number detection in TypeScript.
+"""
+
+from src.analyzers.typescript_base import (
+    TREE_SITTER_AVAILABLE,
+    Node,
+    TypeScriptBaseAnalyzer,
+)
+
+
+class TypeScriptMagicNumberAnalyzer(TypeScriptBaseAnalyzer):  # thailint: ignore[srp]
+    """Analyzes TypeScript/JavaScript code for magic numbers using Tree-sitter.
+
+    Note: Method count (11) exceeds SRP limit (8) because refactoring for A-grade
+    complexity requires extracting helper methods. Class maintains single responsibility
+    of TypeScript magic number detection - all methods support this core purpose.
+    """
+
+    def find_numeric_literals(self, root_node: Node) -> list[tuple[Node, float | int, int]]:
+        """Find all numeric literal nodes in TypeScript/JavaScript AST.
+
+        Args:
+            root_node: Root tree-sitter node to search from
+
+        Returns:
+            List of (node, value, line_number) tuples for each numeric literal
+        """
+        if not TREE_SITTER_AVAILABLE or root_node is None:
+            return []
+
+        literals: list[tuple[Node, float | int, int]] = []
+        self._collect_numeric_literals(root_node, literals)
+        return literals
+
+    def _collect_numeric_literals(
+        self, node: Node, literals: list[tuple[Node, float | int, int]]
+    ) -> None:
+        """Recursively collect numeric literals from AST.
+
+        Args:
+            node: Current tree-sitter node
+            literals: List to accumulate found literals
+        """
+        if node.type == "number":
+            value = self._extract_numeric_value(node)
+            if value is not None:
+                line_number = node.start_point[0] + 1
+                literals.append((node, value, line_number))
+
+        for child in node.children:
+            self._collect_numeric_literals(child, literals)
+
+    def _extract_numeric_value(self, node: Node) -> float | int | None:
+        """Extract numeric value from number node.
+
+        Args:
+            node: Tree-sitter number node
+
+        Returns:
+            Numeric value (int or float) or None if parsing fails
+        """
+        text = self.extract_node_text(node)
+        try:
+            # Try int first
+            if "." not in text and "e" not in text.lower():
+                return int(text, 0)  # Handles hex, octal, binary
+            # Otherwise float
+            return float(text)
+        except (ValueError, TypeError):
+            return None
+
+    def is_enum_context(self, node: Node) -> bool:
+        """Check if numeric literal is in enum definition.
+
+        Args:
+            node: Numeric literal node
+
+        Returns:
+            True if node is within enum_declaration
+        """
+        if not TREE_SITTER_AVAILABLE:
+            return False
+
+        current = node.parent
+        while current is not None:
+            if current.type == "enum_declaration":
+                return True
+            current = current.parent
+        return False
+
+    def is_constant_definition(self, node: Node, source_code: str) -> bool:
+        """Check if numeric literal is in UPPERCASE constant definition.
+
+        Args:
+            node: Numeric literal node
+            source_code: Full source code to extract variable names
+
+        Returns:
+            True if assigned to UPPERCASE constant variable
+        """
+        if not TREE_SITTER_AVAILABLE:
+            return False
+
+        # Find the declaration parent
+        parent = self._find_declaration_parent(node)
+        if parent is None:
+            return False
+
+        # Check if identifier is UPPERCASE constant
+        return self._has_uppercase_identifier(parent)
+
+    def _find_declaration_parent(self, node: Node) -> Node | None:
+        """Find the declaration parent node.
+
+        Args:
+            node: Starting node
+
+        Returns:
+            Declaration parent or None
+        """
+        parent = node.parent
+        if self._is_declaration_type(parent):
+            return parent
+
+        # Try grandparent for nested cases
+        if parent is not None:
+            grandparent = parent.parent
+            if self._is_declaration_type(grandparent):
+                return grandparent
+
+        return None
+
+    def _is_declaration_type(self, node: Node | None) -> bool:
+        """Check if node is a declaration type."""
+        if node is None:
+            return False
+        return node.type in ("variable_declarator", "lexical_declaration", "pair")
+
+    def _has_uppercase_identifier(self, parent_node: Node) -> bool:
+        """Check if declaration has UPPERCASE identifier.
+
+        Args:
+            parent_node: Declaration parent node
+
+        Returns:
+            True if identifier is UPPERCASE
+        """
+        identifier_node = self._find_identifier_in_declaration(parent_node)
+        if identifier_node is None:
+            return False
+
+        identifier_text = self.extract_node_text(identifier_node)
+        return self._is_uppercase_constant(identifier_text)
+
+    def _find_identifier_in_declaration(self, node: Node) -> Node | None:
+        """Find identifier node in variable declaration.
+
+        Args:
+            node: Variable declarator or lexical declaration node
+
+        Returns:
+            Identifier node or None
+        """
+        # Walk children looking for identifier
+        for child in node.children:
+            if child.type in ("identifier", "property_identifier"):
+                return child
+            # Recursively check children
+            result = self._find_identifier_in_declaration(child)
+            if result is not None:
+                return result
+        return None
+
+    def _is_uppercase_constant(self, name: str) -> bool:
+        """Check if identifier is UPPERCASE constant style.
+
+        Args:
+            name: Identifier name
+
+        Returns:
+            True if name is UPPERCASE with optional underscores
+        """
+        if not name:
+            return False
+        # Must be at least one letter and all letters must be uppercase
+        # Allow underscores and numbers
+        letters_only = "".join(c for c in name if c.isalpha())
+        if not letters_only:
+            return False
+        return letters_only.isupper()

src/linters/magic_numbers/typescript_ignore_checker.py

@@ -0,0 +1,81 @@
+"""
+Purpose: TypeScript-specific ignore directive checking for magic numbers linter
+
+Scope: Ignore directive detection for TypeScript/JavaScript files
+
+Overview: Provides ignore directive checking functionality specifically for TypeScript and JavaScript
+    files in the magic numbers linter. Handles both thailint-style and noqa-style ignore comments
+    using TypeScript comment syntax (// instead of #). Extracted from linter.py to reduce file
+    size and improve modularity.
+
+Dependencies: IgnoreDirectiveParser from src.linter_config.ignore, Violation type, violation_utils
+
+Exports: TypeScriptIgnoreChecker class
+
+Interfaces: TypeScriptIgnoreChecker.should_ignore(violation, context) -> bool
+
+Implementation: Comment parsing with TypeScript-specific syntax handling, uses shared utilities
+"""
+
+from src.core.base import BaseLintContext
+from src.core.types import Violation
+from src.core.violation_utils import get_violation_line, has_typescript_noqa
+from src.linter_config.ignore import get_ignore_parser
+
+
+class TypeScriptIgnoreChecker:
+    """Checks for TypeScript-style ignore directives in magic numbers linter."""
+
+    def __init__(self) -> None:
+        """Initialize with standard ignore parser."""
+        self._ignore_parser = get_ignore_parser()
+
+    def should_ignore(self, violation: Violation, context: BaseLintContext) -> bool:
+        """Check if TypeScript violation should be ignored.
+
+        Args:
+            violation: Violation to check
+            context: Lint context
+
+        Returns:
+            True if should ignore
+        """
+        if self._ignore_parser.should_ignore_violation(violation, context.file_content or ""):
+            return True
+
+        return self._check_typescript_ignore(violation, context)
+
+    def _check_typescript_ignore(self, violation: Violation, context: BaseLintContext) -> bool:
+        """Check for TypeScript-style ignore directives.
+
+        Args:
+            violation: Violation to check
+            context: Lint context
+
+        Returns:
+            True if line has ignore directive
+        """
+        line_text = get_violation_line(violation, context)
+        if line_text is None:
+            return False
+
+        return self._has_typescript_ignore_directive(line_text)
+
+    def _has_typescript_ignore_directive(self, line_text: str) -> bool:
+        """Check if line has TypeScript-style ignore directive.
+
+        Args:
+            line_text: Line text to check
+
+        Returns:
+            True if has ignore directive
+        """
+        if "// thailint: ignore[magic-numbers]" in line_text:
+            return True
+
+        if "// thailint: ignore" in line_text:
+            after_ignore = line_text.split("// thailint: ignore")[1].split("//")[0]
+            if "[" not in after_ignore:
+                return True
+
+        return has_typescript_noqa(line_text)

src/linters/magic_numbers/violation_builder.py

@@ -0,0 +1,98 @@
+"""
+Purpose: Builds Violation objects for magic number detection
+
+Scope: Violation message construction for magic numbers linter
+
+Overview: Provides ViolationBuilder class that creates Violation objects for magic number detections.
+    Generates helpful, descriptive messages suggesting constant extraction for numeric literals.
+    Constructs complete Violation instances with rule_id, file_path, line number, column, message,
+    and suggestions. Formats messages to mention the specific numeric value and encourage using
+    named constants for better code maintainability and readability. Provides consistent violation
+    structure across all magic number detections.
+
+Dependencies: src.core.types for Violation dataclass, pathlib for Path handling, ast for node types
+
+Exports: ViolationBuilder class
+
+Interfaces: ViolationBuilder.create_violation(node, value, line, file_path) -> Violation,
+    builds complete Violation object with all required fields
+
+Implementation: Message template with value interpolation, structured violation construction
+"""
+
+import ast
+from pathlib import Path
+
+from src.core.types import Violation
+
+
+class ViolationBuilder:
+    """Builds violations for magic number detections."""
+
+    def __init__(self, rule_id: str) -> None:
+        """Initialize the violation builder.
+
+        Args:
+            rule_id: The rule ID to use in violations
+        """
+        self.rule_id = rule_id
+
+    def create_violation(
+        self,
+        node: ast.Constant,
+        value: int | float,
+        line: int,
+        file_path: Path | None,
+    ) -> Violation:
+        """Create a violation for a magic number.
+
+        Args:
+            node: The AST node containing the magic number
+            value: The numeric value
+            line: Line number where the violation occurs
+            file_path: Path to the file
+
+        Returns:
+            Violation object with details about the magic number
+        """
+        message = f"Magic number {value} should be a named constant"
+
+        suggestion = f"Extract {value} to a named constant (e.g., CONSTANT_NAME = {value})"
+
+        return Violation(
+            rule_id=self.rule_id,
+            file_path=str(file_path) if file_path else "",
+            line=line,
+            column=node.col_offset if hasattr(node, "col_offset") else 0,
+            message=message,
+            suggestion=suggestion,
+        )
+
+    def create_typescript_violation(
+        self,
+        value: int | float,
+        line: int,
+        file_path: Path | None,
+    ) -> Violation:
+        """Create a violation for a TypeScript magic number.
+
+        Args:
+            value: The numeric value
+            line: Line number where the violation occurs
+            file_path: Path to the file
+
+        Returns:
+            Violation object with details about the magic number
+        """
+        message = f"Magic number {value} should be a named constant"
+
+        suggestion = f"Extract {value} to a named constant (e.g., const CONSTANT_NAME = {value})"
+
+        return Violation(
+            rule_id=self.rule_id,
+            file_path=str(file_path) if file_path else "",
+            line=line,
+            column=0,  # Tree-sitter nodes don't have easy column access
+            message=message,
+            suggestion=suggestion,
+        )

src/linters/method_property/__init__.py

@@ -0,0 +1,49 @@
+"""
+Purpose: Package exports for method-should-be-property linter
+
+Scope: Method property linter public API
+
+Overview: Exports the MethodPropertyRule class and MethodPropertyConfig dataclass for use by
+    the orchestrator and external consumers. Provides a convenience lint() function for
+    standalone usage of the linter.
+
+Dependencies: MethodPropertyRule from linter module, MethodPropertyConfig from config module
+
+Exports: MethodPropertyRule, MethodPropertyConfig, lint function
+
+Interfaces: lint(file_path, content, config) -> list[Violation] convenience function
+
+Implementation: Simple re-exports from submodules with optional convenience wrapper
+"""
+
+from .config import MethodPropertyConfig
+from .linter import MethodPropertyRule
+
+__all__ = ["MethodPropertyRule", "MethodPropertyConfig", "lint"]
+
+
+def lint(
+    file_path: str,
+    content: str,
+    config: dict | None = None,
+) -> list:
+    """Lint a file for method-should-be-property violations.
+
+    Args:
+        file_path: Path to the file being linted
+        content: Content of the file
+        config: Optional configuration dictionary
+
+    Returns:
+        List of Violation objects
+    """
+    from unittest.mock import Mock
+
+    rule = MethodPropertyRule()
+    context = Mock()
+    context.file_path = file_path
+    context.file_content = content
+    context.language = "python"
+    context.config = config
+
+    return rule.check(context)

src/linters/method_property/config.py

@@ -0,0 +1,138 @@
+"""
+Purpose: Configuration schema for method-should-be-property linter
+
+Scope: Method property linter configuration for Python files
+
+Overview: Defines configuration schema for method-should-be-property linter. Provides
+    MethodPropertyConfig dataclass with enabled flag, max_body_statements threshold (default 3)
+    for determining when a method body is too complex to be a property candidate, and ignore
+    patterns list for excluding specific files or directories. Includes configurable action verb
+    exclusions (prefixes and names) with sensible defaults that can be extended or overridden.
+    Supports per-file and per-directory config overrides through from_dict class method.
+    Integrates with orchestrator's configuration system via .thailint.yaml.
+
+Dependencies: dataclasses module for configuration structure, typing module for type hints
+
+Exports: MethodPropertyConfig dataclass, DEFAULT_EXCLUDE_PREFIXES, DEFAULT_EXCLUDE_NAMES
+
+Interfaces: from_dict(config, language) -> MethodPropertyConfig for configuration loading
+
+Implementation: Dataclass with defaults matching Pythonic conventions and common use cases
+
+Suppressions:
+    - dry: MethodPropertyConfig includes extensive exclusion lists that share patterns with
+        other config classes. Lists are maintained separately for clear documentation.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# Default action verb prefixes - methods starting with these are excluded
+# These represent actions/transformations, not property access
+DEFAULT_EXCLUDE_PREFIXES: tuple[str, ...] = (
+    "to_",  # Transformation: to_dict, to_json, to_string
+    "dump_",  # Serialization: dump_to_json, dump_to_apigw
+    "generate_",  # Factory: generate_report, generate_html
+    "create_",  # Factory: create_instance, create_config
+    "build_",  # Construction: build_query, build_html
+    "make_",  # Factory: make_request, make_connection
+    "render_",  # Output: render_template, render_html
+    "compute_",  # Calculation: compute_hash, compute_total
+    "calculate_",  # Calculation: calculate_sum, calculate_average
+)
+
+# Default action verb names - exact method names that are excluded
+# These are lifecycle hooks, display actions, and resource operations
+DEFAULT_EXCLUDE_NAMES: frozenset[str] = frozenset(
+    {
+        "finalize",  # Lifecycle hook
+        "serialize",  # Transformation
+        "dump",  # Serialization
+        "validate",  # Validation action
+        "show",  # Display action
+        "display",  # Display action
+        "print",  # Output action
+        "refresh",  # Update action
+        "reset",  # State action
+        "clear",  # State action
+        "close",  # Resource action
+        "open",  # Resource action
+        "save",  # Persistence action
+        "load",  # Persistence action
+        "execute",  # Action
+        "run",  # Action
+    }
+)
+
+
+def _load_list_config(
+    config: dict[str, Any], key: str, override_key: str, default: tuple[str, ...]
+) -> tuple[str, ...]:
+    """Load a list config with extend/override semantics."""
+    if override_key in config and isinstance(config[override_key], list):
+        return tuple(config[override_key])
+    if key in config and isinstance(config[key], list):
+        return default + tuple(config[key])
+    return default
+
+
+def _load_set_config(
+    config: dict[str, Any], key: str, override_key: str, default: frozenset[str]
+) -> frozenset[str]:
+    """Load a set config with extend/override semantics."""
+    if override_key in config and isinstance(config[override_key], list):
+        return frozenset(config[override_key])
+    if key in config and isinstance(config[key], list):
+        return default | frozenset(config[key])
+    return default
+
+
+@dataclass
+class MethodPropertyConfig:  # thailint: ignore[dry]
+    """Configuration for method-should-be-property linter."""
+
+    enabled: bool = True
+    max_body_statements: int = 3
+    ignore: list[str] = field(default_factory=list)
+    ignore_methods: list[str] = field(default_factory=list)
+
+    # Action verb exclusions (extend defaults or override)
+    exclude_prefixes: tuple[str, ...] = DEFAULT_EXCLUDE_PREFIXES
+    exclude_names: frozenset[str] = DEFAULT_EXCLUDE_NAMES
+
+    @classmethod
+    def from_dict(
+        cls, config: dict[str, Any] | None, language: str | None = None
+    ) -> "MethodPropertyConfig":
+        """Load configuration from dictionary.
+
+        Args:
+            config: Dictionary containing configuration values, or None
+            language: Programming language (unused, for interface compatibility)
+
+        Returns:
+            MethodPropertyConfig instance with values from dictionary
+        """
+        if config is None:
+            return cls()
+
+        ignore_patterns = config.get("ignore", [])
+        if not isinstance(ignore_patterns, list):
+            ignore_patterns = []
+
+        ignore_methods = config.get("ignore_methods", [])
+        if not isinstance(ignore_methods, list):
+            ignore_methods = []
+
+        return cls(
+            enabled=config.get("enabled", True),
+            max_body_statements=config.get("max_body_statements", 3),
+            ignore=ignore_patterns,
+            ignore_methods=ignore_methods,
+            exclude_prefixes=_load_list_config(
+                config, "exclude_prefixes", "exclude_prefixes_override", DEFAULT_EXCLUDE_PREFIXES
+            ),
+            exclude_names=_load_set_config(
+                config, "exclude_names", "exclude_names_override", DEFAULT_EXCLUDE_NAMES
+            ),
+        )