thailint 0.2.1__py3-none-any.whl → 0.3.1__py3-none-any.whl

src/linters/magic_numbers/python_analyzer.py

@@ -0,0 +1,76 @@
+"""
+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
+
+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
+
+
+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 = {}
+        self._build_parent_map(tree)
+        self.visit(tree)
+        return self.numeric_literals
+
+    def _build_parent_map(self, node: ast.AST, parent: ast.AST | None = None) -> None:
+        """Build a map of nodes to their parents.
+
+        Args:
+            node: Current AST node
+            parent: Parent of current node
+        """
+        if parent is not None:
+            self.parent_map[node] = parent
+
+        for child in ast.iter_child_nodes(node):
+            self._build_parent_map(child, node)
+
+    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,217 @@
+"""
+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
+"""
+
+from typing import Any
+
+from src.analyzers.typescript_base import TypeScriptBaseAnalyzer
+
+try:
+    from tree_sitter import Node
+
+    TREE_SITTER_AVAILABLE = True
+except ImportError:
+    TREE_SITTER_AVAILABLE = False
+    Node = Any  # type: ignore
+
+
+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/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/nesting/__init__.py

@@ -22,7 +22,7 @@ Implementation: Simple re-export pattern for package interface, convenience func
 from pathlib import Path
 from typing import Any
 
-from .config import NestingConfig
+from .config import DEFAULT_MAX_NESTING_DEPTH, NestingConfig
 from .linter import NestingDepthRule
 from .python_analyzer import PythonNestingAnalyzer
 from .typescript_analyzer import TypeScriptNestingAnalyzer
@@ -36,7 +36,11 @@ __all__ = [
 ]
 
 
-def lint(path: Path | str, config: dict[str, Any] | None = None, max_depth: int = 4) -> list:
+def lint(
+    path: Path | str,
+    config: dict[str, Any] | None = None,
+    max_depth: int = DEFAULT_MAX_NESTING_DEPTH,
+) -> list:
     """Lint a file or directory for nesting depth violations.
 
     Args:

src/linters/nesting/config.py

@@ -21,12 +21,15 @@ Implementation: Dataclass with validation and defaults, matches reference implem
 from dataclasses import dataclass
 from typing import Any
 
+# Default nesting threshold constant
+DEFAULT_MAX_NESTING_DEPTH = 4
+
 
 @dataclass
 class NestingConfig:
     """Configuration for nesting depth linter."""
 
-    max_nesting_depth: int = 4  # Default from reference implementation
+    max_nesting_depth: int = DEFAULT_MAX_NESTING_DEPTH  # Default from reference implementation
     enabled: bool = True
 
     def __post_init__(self) -> None:
@@ -49,10 +52,10 @@ class NestingConfig:
         if language and language in config:
             lang_config = config[language]
             max_nesting_depth = lang_config.get(
-                "max_nesting_depth", config.get("max_nesting_depth", 4)
+                "max_nesting_depth", config.get("max_nesting_depth", DEFAULT_MAX_NESTING_DEPTH)
             )
         else:
-            max_nesting_depth = config.get("max_nesting_depth", 4)
+            max_nesting_depth = config.get("max_nesting_depth", DEFAULT_MAX_NESTING_DEPTH)
 
         return cls(
             max_nesting_depth=max_nesting_depth,

src/linters/nesting/linter.py

@@ -21,8 +21,8 @@ Implementation: Composition pattern with helper classes, AST-based analysis with
 import ast
 from typing import Any
 
-from src.core.base import BaseLintContext, BaseLintRule
-from src.core.linter_utils import has_file_content, load_linter_config
+from src.core.base import BaseLintContext, MultiLanguageLintRule
+from src.core.linter_utils import load_linter_config
 from src.core.types import Violation
 from src.linter_config.ignore import IgnoreDirectiveParser
 
@@ -32,7 +32,7 @@ from .typescript_analyzer import TypeScriptNestingAnalyzer
 from .violation_builder import NestingViolationBuilder
 
 
-class NestingDepthRule(BaseLintRule):
+class NestingDepthRule(MultiLanguageLintRule):
     """Detects excessive nesting depth in functions."""
 
     def __init__(self) -> None:
@@ -55,27 +55,16 @@ class NestingDepthRule(BaseLintRule):
         """Description of what this rule checks."""
         return "Functions should not have excessive nesting depth for better readability"
 
-    def check(self, context: BaseLintContext) -> list[Violation]:
-        """Check for excessive nesting depth violations.
+    def _load_config(self, context: BaseLintContext) -> NestingConfig:
+        """Load configuration from context.
 
         Args:
-            context: Lint context with file information
+            context: Lint context
 
         Returns:
-            List of violations found
+            NestingConfig instance
         """
-        if not has_file_content(context):
-            return []
-
-        config = load_linter_config(context, "nesting", NestingConfig)
-        if not config.enabled:
-            return []
-
-        if context.language == "python":
-            return self._check_python(context, config)
-        if context.language in ("typescript", "javascript"):
-            return self._check_typescript(context, config)
-        return []
+        return load_linter_config(context, "nesting", NestingConfig)
 
     def _process_python_functions(
         self, functions: list, analyzer: Any, config: NestingConfig, context: BaseLintContext

src/linters/srp/__init__.py

@@ -22,7 +22,7 @@ Implementation: Simple re-export pattern for package interface, convenience func
 from pathlib import Path
 from typing import Any
 
-from .config import SRPConfig
+from .config import DEFAULT_MAX_LOC_PER_CLASS, DEFAULT_MAX_METHODS_PER_CLASS, SRPConfig
 from .linter import SRPRule
 from .python_analyzer import PythonSRPAnalyzer
 from .typescript_analyzer import TypeScriptSRPAnalyzer
@@ -39,8 +39,8 @@ __all__ = [
 def lint(
     path: Path | str,
     config: dict[str, Any] | None = None,
-    max_methods: int = 7,
-    max_loc: int = 200,
+    max_methods: int = DEFAULT_MAX_METHODS_PER_CLASS,
+    max_loc: int = DEFAULT_MAX_LOC_PER_CLASS,
 ) -> list:
     """Lint a file or directory for SRP violations.
 

src/linters/srp/config.py

@@ -23,13 +23,17 @@ Implementation: Dataclass with validation and defaults, heuristic-based SRP dete
 from dataclasses import dataclass, field
 from typing import Any
 
+# Default SRP threshold constants
+DEFAULT_MAX_METHODS_PER_CLASS = 7
+DEFAULT_MAX_LOC_PER_CLASS = 200
+
 
 @dataclass
 class SRPConfig:
     """Configuration for SRP linter."""
 
-    max_methods: int = 7  # Maximum methods per class
-    max_loc: int = 200  # Maximum lines of code per class
+    max_methods: int = DEFAULT_MAX_METHODS_PER_CLASS  # Maximum methods per class
+    max_loc: int = DEFAULT_MAX_LOC_PER_CLASS  # Maximum lines of code per class
     enabled: bool = True
     check_keywords: bool = True
     keywords: list[str] = field(
@@ -58,11 +62,13 @@ class SRPConfig:
         # Get language-specific config if available
         if language and language in config:
             lang_config = config[language]
-            max_methods = lang_config.get("max_methods", config.get("max_methods", 7))
-            max_loc = lang_config.get("max_loc", config.get("max_loc", 200))
+            max_methods = lang_config.get(
+                "max_methods", config.get("max_methods", DEFAULT_MAX_METHODS_PER_CLASS)
+            )
+            max_loc = lang_config.get("max_loc", config.get("max_loc", DEFAULT_MAX_LOC_PER_CLASS))
         else:
-            max_methods = config.get("max_methods", 7)
-            max_loc = config.get("max_loc", 200)
+            max_methods = config.get("max_methods", DEFAULT_MAX_METHODS_PER_CLASS)
+            max_loc = config.get("max_loc", DEFAULT_MAX_LOC_PER_CLASS)
 
         return cls(
             max_methods=max_methods,

src/linters/srp/linter.py

@@ -18,8 +18,8 @@ Interfaces: SRPRule.check(context) -> list[Violation], properties for rule metad
 Implementation: Composition pattern with helper classes, heuristic-based SRP analysis
 """
 
-from src.core.base import BaseLintContext, BaseLintRule
-from src.core.linter_utils import has_file_content, load_linter_config
+from src.core.base import BaseLintContext, MultiLanguageLintRule
+from src.core.linter_utils import load_linter_config
 from src.core.types import Violation
 from src.linter_config.ignore import IgnoreDirectiveParser
 
@@ -29,7 +29,7 @@ from .metrics_evaluator import evaluate_metrics
 from .violation_builder import ViolationBuilder
 
 
-class SRPRule(BaseLintRule):
+class SRPRule(MultiLanguageLintRule):
     """Detects Single Responsibility Principle violations in classes."""
 
     def __init__(self) -> None:
@@ -54,7 +54,9 @@ class SRPRule(BaseLintRule):
         return "Classes should have a single, well-defined responsibility"
 
     def check(self, context: BaseLintContext) -> list[Violation]:
-        """Check for SRP violations.
+        """Check for SRP violations with custom ignore pattern handling.
+
+        Overrides parent to add file-level ignore pattern checking before dispatch.
 
         Args:
             context: Lint context with file information
@@ -62,39 +64,33 @@ class SRPRule(BaseLintRule):
         Returns:
             List of violations found
         """
-        if not self._should_check_file(context):
-            return []
+        from src.core.linter_utils import has_file_content
 
-        config = load_linter_config(context, "srp", SRPConfig)
-        if not self._is_linter_enabled(context, config):
+        if not has_file_content(context):
             return []
 
-        return self._check_by_language(context, config)
-
-    def _should_check_file(self, context: BaseLintContext) -> bool:
-        """Check if file has content to analyze.
-
-        Args:
-            context: Lint context
+        config = self._load_config(context)
+        if not self._should_process_file(context, config):
+            return []
 
-        Returns:
-            True if file should be checked
-        """
-        return has_file_content(context)
+        # Standard language dispatch
+        return self._dispatch_by_language(context, config)
 
-    def _is_linter_enabled(self, context: BaseLintContext, config: SRPConfig) -> bool:
-        """Check if linter is enabled and file is not ignored.
+    def _should_process_file(self, context: BaseLintContext, config: SRPConfig) -> bool:
+        """Check if file should be processed.
 
         Args:
             context: Lint context
             config: SRP configuration
 
         Returns:
-            True if linter should run on this file
+            True if file should be processed
         """
-        return config.enabled and not self._is_file_ignored(context, config)
+        if not config.enabled:
+            return False
+        return not self._is_file_ignored(context, config)
 
-    def _check_by_language(self, context: BaseLintContext, config: SRPConfig) -> list[Violation]:
+    def _dispatch_by_language(self, context: BaseLintContext, config: SRPConfig) -> list[Violation]:
         """Dispatch to language-specific checker.
 
         Args:
@@ -106,10 +102,23 @@ class SRPRule(BaseLintRule):
         """
         if context.language == "python":
             return self._check_python(context, config)
+
         if context.language in ("typescript", "javascript"):
             return self._check_typescript(context, config)
+
         return []
 
+    def _load_config(self, context: BaseLintContext) -> SRPConfig:
+        """Load configuration from context.
+
+        Args:
+            context: Lint context
+
+        Returns:
+            SRPConfig instance
+        """
+        return load_linter_config(context, "srp", SRPConfig)
+
     def _is_file_ignored(self, context: BaseLintContext, config: SRPConfig) -> bool:
         """Check if file matches ignore patterns.