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

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)

src/linters/magic_numbers/linter.py

@@ -0,0 +1,452 @@
+"""
+Purpose: Main magic numbers linter rule implementation
+
+Scope: MagicNumberRule class implementing BaseLintRule interface
+
+Overview: Implements magic numbers linter rule following BaseLintRule interface. Orchestrates
+    configuration loading, Python AST analysis, context detection, and violation building through
+    focused helper classes. Detects numeric literals that should be extracted to named constants.
+    Supports configurable allowed_numbers set and max_small_integer threshold. Handles ignore
+    directives for suppressing specific violations. Main rule class acts as coordinator for magic
+    number checking workflow across Python code files. Method count (17) exceeds SRP limit (8)
+    because refactoring for A-grade complexity requires extracting helper methods. Class maintains
+    single responsibility of magic number detection - all methods support this core purpose.
+
+Dependencies: BaseLintRule, BaseLintContext, PythonMagicNumberAnalyzer, ContextAnalyzer,
+    ViolationBuilder, MagicNumberConfig, IgnoreDirectiveParser
+
+Exports: MagicNumberRule class
+
+Interfaces: MagicNumberRule.check(context) -> list[Violation], properties for rule metadata
+
+Implementation: Composition pattern with helper classes, AST-based analysis with configurable
+    allowed numbers and context detection
+"""
+
+import ast
+
+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
+
+from .config import MagicNumberConfig
+from .context_analyzer import ContextAnalyzer
+from .python_analyzer import PythonMagicNumberAnalyzer
+from .typescript_analyzer import TypeScriptMagicNumberAnalyzer
+from .violation_builder import ViolationBuilder
+
+
+class MagicNumberRule(MultiLanguageLintRule):  # thailint: ignore[srp]
+    """Detects magic numbers that should be replaced with named constants."""
+
+    def __init__(self) -> None:
+        """Initialize the magic numbers rule."""
+        self._ignore_parser = IgnoreDirectiveParser()
+        self._violation_builder = ViolationBuilder(self.rule_id)
+        self._context_analyzer = ContextAnalyzer()
+
+    @property
+    def rule_id(self) -> str:
+        """Unique identifier for this rule."""
+        return "magic-numbers.numeric-literal"
+
+    @property
+    def rule_name(self) -> str:
+        """Human-readable name for this rule."""
+        return "Magic Numbers"
+
+    @property
+    def description(self) -> str:
+        """Description of what this rule checks."""
+        return "Numeric literals should be replaced with named constants for better maintainability"
+
+    def _load_config(self, context: BaseLintContext) -> MagicNumberConfig:
+        """Load configuration from context.
+
+        Args:
+            context: Lint context
+
+        Returns:
+            MagicNumberConfig instance
+        """
+        # Try test-style config first
+        test_config = self._try_load_test_config(context)
+        if test_config is not None:
+            return test_config
+
+        # Try production config
+        prod_config = self._try_load_production_config(context)
+        if prod_config is not None:
+            return prod_config
+
+        # Use defaults
+        return MagicNumberConfig()
+
+    def _try_load_test_config(self, context: BaseLintContext) -> MagicNumberConfig | None:
+        """Try to load test-style configuration."""
+        if not hasattr(context, "config"):
+            return None
+        config_attr = context.config
+        if config_attr is None or not isinstance(config_attr, dict):
+            return None
+        return MagicNumberConfig.from_dict(config_attr, context.language)
+
+    def _try_load_production_config(self, context: BaseLintContext) -> MagicNumberConfig | None:
+        """Try to load production configuration."""
+        if not hasattr(context, "metadata") or not isinstance(context.metadata, dict):
+            return None
+        return load_linter_config(context, "magic_numbers", MagicNumberConfig)
+
+    def _check_python(self, context: BaseLintContext, config: MagicNumberConfig) -> list[Violation]:
+        """Check Python code for magic number violations.
+
+        Args:
+            context: Lint context with Python file information
+            config: Magic numbers configuration
+
+        Returns:
+            List of violations found in Python code
+        """
+        tree = self._parse_python_code(context.file_content)
+        if tree is None:
+            return []
+
+        numeric_literals = self._find_numeric_literals(tree)
+        return self._collect_violations(numeric_literals, context, config)
+
+    def _parse_python_code(self, code: str | None) -> ast.AST | None:
+        """Parse Python code into AST."""
+        try:
+            return ast.parse(code or "")
+        except SyntaxError:
+            return None
+
+    def _find_numeric_literals(self, tree: ast.AST) -> list:
+        """Find all numeric literals in AST."""
+        analyzer = PythonMagicNumberAnalyzer()
+        return analyzer.find_numeric_literals(tree)
+
+    def _collect_violations(
+        self, numeric_literals: list, context: BaseLintContext, config: MagicNumberConfig
+    ) -> list[Violation]:
+        """Collect violations from numeric literals."""
+        violations = []
+        for literal_info in numeric_literals:
+            violation = self._try_create_violation(literal_info, context, config)
+            if violation is not None:
+                violations.append(violation)
+        return violations
+
+    def _try_create_violation(
+        self, literal_info: tuple, context: BaseLintContext, config: MagicNumberConfig
+    ) -> Violation | None:
+        """Try to create a violation for a numeric literal.
+
+        Args:
+            literal_info: Tuple of (node, parent, value, line_number)
+            context: Lint context
+            config: Configuration
+        """
+        node, parent, value, line_number = literal_info
+        if not self._should_flag_number(value, (node, parent), config, context):
+            return None
+
+        violation = self._violation_builder.create_violation(
+            node, value, line_number, context.file_path
+        )
+        if self._should_ignore(violation, context):
+            return None
+
+        return violation
+
+    def _should_flag_number(
+        self,
+        value: int | float,
+        node_info: tuple[ast.Constant, ast.AST | None],
+        config: MagicNumberConfig,
+        context: BaseLintContext,
+    ) -> bool:
+        """Determine if a number should be flagged as a magic number.
+
+        Args:
+            value: The numeric value
+            node_info: Tuple of (node, parent) AST nodes
+            config: Configuration
+            context: Lint context
+
+        Returns:
+            True if the number should be flagged
+        """
+        if value in config.allowed_numbers:
+            return False
+
+        node, parent = node_info
+        config_dict = {
+            "max_small_integer": config.max_small_integer,
+            "allowed_numbers": config.allowed_numbers,
+        }
+
+        if self._context_analyzer.is_acceptable_context(
+            node, parent, context.file_path, config_dict
+        ):
+            return False
+
+        return True
+
+    def _should_ignore(self, violation: Violation, context: BaseLintContext) -> bool:
+        """Check if violation should be ignored based on inline directives.
+
+        Args:
+            violation: Violation to check
+            context: Lint context with file content
+
+        Returns:
+            True if violation should be ignored
+        """
+        # Check using standard ignore parser
+        if self._ignore_parser.should_ignore_violation(violation, context.file_content or ""):
+            return True
+
+        # Workaround for generic ignore directives
+        return self._check_generic_ignore(violation, context)
+
+    def _check_generic_ignore(self, violation: Violation, context: BaseLintContext) -> bool:
+        """Check for generic ignore directives (workaround for parser limitation).
+
+        Args:
+            violation: Violation to check
+            context: Lint context
+
+        Returns:
+            True if line has generic ignore directive
+        """
+        line_text = self._get_violation_line(violation, context)
+        if line_text is None:
+            return False
+
+        return self._has_generic_ignore_directive(line_text)
+
+    def _get_violation_line(self, violation: Violation, context: BaseLintContext) -> str | None:
+        """Get the line text for a violation."""
+        if not context.file_content:
+            return None
+
+        lines = context.file_content.splitlines()
+        if violation.line <= 0 or violation.line > len(lines):
+            return None
+
+        return lines[violation.line - 1].lower()
+
+    def _has_generic_ignore_directive(self, line_text: str) -> bool:
+        """Check if line has generic ignore directive."""
+        if self._has_generic_thailint_ignore(line_text):
+            return True
+        return self._has_noqa_directive(line_text)
+
+    def _has_generic_thailint_ignore(self, line_text: str) -> bool:
+        """Check for generic thailint: ignore (no brackets)."""
+        if "# thailint: ignore" not in line_text:
+            return False
+        after_ignore = line_text.split("# thailint: ignore")[1].split("#")[0]
+        return "[" not in after_ignore
+
+    def _has_noqa_directive(self, line_text: str) -> bool:
+        """Check for noqa-style comments."""
+        return "# noqa" in line_text
+
+    def _check_typescript(
+        self, context: BaseLintContext, config: MagicNumberConfig
+    ) -> list[Violation]:
+        """Check TypeScript/JavaScript code for magic number violations.
+
+        Args:
+            context: Lint context with TypeScript/JavaScript file information
+            config: Magic numbers configuration
+
+        Returns:
+            List of violations found in TypeScript/JavaScript code
+        """
+        analyzer = TypeScriptMagicNumberAnalyzer()
+        root_node = analyzer.parse_typescript(context.file_content or "")
+        if root_node is None:
+            return []
+
+        numeric_literals = analyzer.find_numeric_literals(root_node)
+        return self._collect_typescript_violations(numeric_literals, context, config, analyzer)
+
+    def _collect_typescript_violations(
+        self,
+        numeric_literals: list,
+        context: BaseLintContext,
+        config: MagicNumberConfig,
+        analyzer: TypeScriptMagicNumberAnalyzer,
+    ) -> list[Violation]:
+        """Collect violations from TypeScript numeric literals.
+
+        Args:
+            numeric_literals: List of (node, value, line_number) tuples
+            context: Lint context
+            config: Configuration
+            analyzer: TypeScript analyzer instance
+
+        Returns:
+            List of violations
+        """
+        violations = []
+        for node, value, line_number in numeric_literals:
+            violation = self._try_create_typescript_violation(
+                node, value, line_number, context, config, analyzer
+            )
+            if violation is not None:
+                violations.append(violation)
+        return violations
+
+    def _try_create_typescript_violation(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+        self,
+        node: object,
+        value: float | int,
+        line_number: int,
+        context: BaseLintContext,
+        config: MagicNumberConfig,
+        analyzer: TypeScriptMagicNumberAnalyzer,
+    ) -> Violation | None:
+        """Try to create a violation for a TypeScript numeric literal.
+
+        Args:
+            node: Tree-sitter node
+            value: Numeric value
+            line_number: Line number of literal
+            context: Lint context
+            config: Configuration
+            analyzer: TypeScript analyzer
+
+        Returns:
+            Violation or None if should not flag
+        """
+        if not self._should_flag_typescript_number(node, value, context, config, analyzer):
+            return None
+
+        violation = self._violation_builder.create_typescript_violation(
+            value, line_number, context.file_path
+        )
+        if self._should_ignore_typescript(violation, context):
+            return None
+
+        return violation
+
+    def _should_flag_typescript_number(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+        self,
+        node: object,
+        value: float | int,
+        context: BaseLintContext,
+        config: MagicNumberConfig,
+        analyzer: TypeScriptMagicNumberAnalyzer,
+    ) -> bool:
+        """Determine if a TypeScript number should be flagged.
+
+        Args:
+            node: Tree-sitter node
+            value: Numeric value
+            context: Lint context
+            config: Configuration
+            analyzer: TypeScript analyzer
+
+        Returns:
+            True if should flag as magic number
+        """
+        # Early return for allowed contexts
+        if self._is_typescript_allowed_context(value, context, config):
+            return False
+
+        # Check TypeScript-specific contexts
+        return not self._is_typescript_special_context(node, analyzer, context)
+
+    def _is_typescript_allowed_context(
+        self, value: float | int, context: BaseLintContext, config: MagicNumberConfig
+    ) -> bool:
+        """Check if number is in allowed context."""
+        return value in config.allowed_numbers or self._is_test_file(context.file_path)
+
+    def _is_typescript_special_context(
+        self, node: object, analyzer: TypeScriptMagicNumberAnalyzer, context: BaseLintContext
+    ) -> bool:
+        """Check if in TypeScript-specific special context."""
+        # Calls require type: ignore because node is typed as object but analyzer expects Node
+        in_enum = analyzer.is_enum_context(node)  # type: ignore[arg-type]
+        in_const_def = analyzer.is_constant_definition(node, context.file_content or "")  # type: ignore[arg-type]
+        return in_enum or in_const_def
+
+    def _is_test_file(self, file_path: object) -> bool:
+        """Check if file is a test file.
+
+        Args:
+            file_path: Path to check
+
+        Returns:
+            True if test file
+        """
+        path_str = str(file_path)
+        return any(
+            pattern in path_str
+            for pattern in [".test.", ".spec.", "test_", "_test.", "/tests/", "/test/"]
+        )
+
+    def _should_ignore_typescript(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
+        """
+        # Check standard ignore directives
+        if self._ignore_parser.should_ignore_violation(violation, context.file_content or ""):
+            return True
+
+        # Check TypeScript-style comments
+        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 = self._get_violation_line(violation, context)
+        if line_text is None:
+            return False
+
+        # Check for // thailint: ignore or // noqa
+        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
+        """
+        # Check for // thailint: ignore[magic-numbers]
+        if "// thailint: ignore[magic-numbers]" in line_text:
+            return True
+
+        # Check for // thailint: ignore (generic)
+        if "// thailint: ignore" in line_text:
+            after_ignore = line_text.split("// thailint: ignore")[1].split("//")[0]
+            if "[" not in after_ignore:
+                return True
+
+        # Check for // noqa
+        if "// noqa" in line_text:
+            return True
+
+        return False