thailint 0.1.0__py3-none-any.whl

src/linters/nesting/__init__.py

@@ -0,0 +1,87 @@
+"""
+Purpose: Nesting depth linter package initialization
+
+Scope: Exports for nesting depth linter module
+
+Overview: Initializes the nesting depth linter package and exposes the main rule class for
+    external use. Exports NestingDepthRule as the primary interface for the nesting linter,
+    allowing the orchestrator to discover and instantiate the rule. Also exports configuration
+    and analyzer classes for advanced use cases. Provides a convenience lint() function for
+    direct usage without orchestrator setup. This module serves as the entry point for
+    the nesting linter functionality within the thai-lint framework.
+
+Dependencies: NestingDepthRule, NestingConfig, PythonNestingAnalyzer, TypeScriptNestingAnalyzer
+
+Exports: NestingDepthRule (primary), NestingConfig, PythonNestingAnalyzer, TypeScriptNestingAnalyzer, lint
+
+Interfaces: Standard Python package initialization with __all__ for explicit exports, lint() convenience function
+
+Implementation: Simple re-export pattern for package interface, convenience function wraps orchestrator
+"""
+
+from pathlib import Path
+from typing import Any
+
+from .config import NestingConfig
+from .linter import NestingDepthRule
+from .python_analyzer import PythonNestingAnalyzer
+from .typescript_analyzer import TypeScriptNestingAnalyzer
+
+__all__ = [
+    "NestingDepthRule",
+    "NestingConfig",
+    "PythonNestingAnalyzer",
+    "TypeScriptNestingAnalyzer",
+    "lint",
+]
+
+
+def lint(path: Path | str, config: dict[str, Any] | None = None, max_depth: int = 4) -> list:
+    """Lint a file or directory for nesting depth violations.
+
+    Args:
+        path: Path to file or directory to lint
+        config: Configuration dict (optional, uses defaults if not provided)
+        max_depth: Maximum allowed nesting depth (default: 4)
+
+    Returns:
+        List of violations found
+
+    Example:
+        >>> from src.linters.nesting import lint
+        >>> violations = lint('src/my_module.py', max_depth=3)
+        >>> for v in violations:
+        ...     print(f"{v.file_path}:{v.line} - {v.message}")
+    """
+    path_obj = Path(path) if isinstance(path, str) else path
+    project_root = path_obj if path_obj.is_dir() else path_obj.parent
+
+    orchestrator = _setup_nesting_orchestrator(project_root, config, max_depth)
+    violations = _execute_nesting_lint(orchestrator, path_obj)
+
+    return [v for v in violations if "nesting" in v.rule_id]
+
+
+def _setup_nesting_orchestrator(
+    project_root: Path, config: dict[str, Any] | None, max_depth: int
+) -> Any:
+    """Set up orchestrator with nesting config."""
+    from src.orchestrator.core import Orchestrator
+
+    orchestrator = Orchestrator(project_root=project_root)
+
+    if config:
+        orchestrator.config["nesting"] = config
+    else:
+        orchestrator.config["nesting"] = {"max_nesting_depth": max_depth}
+
+    return orchestrator
+
+
+def _execute_nesting_lint(orchestrator: Any, path_obj: Path) -> list:
+    """Execute linting on file or directory."""
+    if path_obj.is_file():
+        return orchestrator.lint_file(path_obj)
+    if path_obj.is_dir():
+        return orchestrator.lint_directory(path_obj)
+    return []

src/linters/nesting/config.py

@@ -0,0 +1,50 @@
+"""
+Purpose: Configuration schema for nesting depth linter
+
+Scope: NestingConfig dataclass with max_nesting_depth setting
+
+Overview: Defines configuration schema for nesting depth linter. Provides NestingConfig dataclass
+    with max_nesting_depth field (default 4), validation logic, and config loading from YAML/JSON.
+    Supports per-file and per-directory config overrides. Validates that max_depth is positive
+    integer. Integrates with the orchestrator's configuration system to allow users to customize
+    nesting depth limits via .thailint.yaml configuration files.
+
+Dependencies: dataclasses, typing
+
+Exports: NestingConfig dataclass
+
+Interfaces: NestingConfig(max_nesting_depth: int = 4), from_dict class method for loading config
+
+Implementation: Dataclass with validation and defaults, matches reference implementation default
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class NestingConfig:
+    """Configuration for nesting depth linter."""
+
+    max_nesting_depth: int = 4  # Default from reference implementation
+    enabled: bool = True
+
+    def __post_init__(self) -> None:
+        """Validate configuration values."""
+        if self.max_nesting_depth <= 0:
+            raise ValueError(f"max_nesting_depth must be positive, got {self.max_nesting_depth}")
+
+    @classmethod
+    def from_dict(cls, config: dict[str, Any]) -> "NestingConfig":
+        """Load configuration from dictionary.
+
+        Args:
+            config: Dictionary containing configuration values
+
+        Returns:
+            NestingConfig instance with values from dictionary
+        """
+        return cls(
+            max_nesting_depth=config.get("max_nesting_depth", 4),
+            enabled=config.get("enabled", True),
+        )

src/linters/nesting/linter.py

@@ -0,0 +1,257 @@
+"""
+Purpose: Main nesting depth linter rule implementation
+
+Scope: NestingDepthRule class implementing BaseLintRule interface
+
+Overview: Implements nesting depth linter rule following BaseLintRule interface. Detects excessive
+    nesting depth in Python and TypeScript code using AST analysis. Supports configurable
+    max_nesting_depth limit (default 4). Provides helpful violation messages with refactoring
+    suggestions (early returns, guard clauses, extract method). Integrates with orchestrator for
+    automatic rule discovery. Handles both Python (using ast) and TypeScript (using typescript-estree)
+    code analysis. Gracefully handles syntax errors by reporting them as violations rather than
+    crashing. Supports configuration loading from context metadata for per-file customization.
+
+Dependencies: BaseLintRule, BaseLintContext, Violation, PythonNestingAnalyzer, TypeScriptNestingAnalyzer
+
+Exports: NestingDepthRule class
+
+Interfaces: NestingDepthRule.check(context) -> list[Violation], properties for rule metadata
+
+Implementation: AST-based analysis with configurable limits and helpful error messages
+"""
+
+import ast
+from typing import Any
+
+from src.core.base import BaseLintContext, BaseLintRule
+from src.core.types import Severity, Violation
+from src.linter_config.ignore import IgnoreDirectiveParser
+
+from .config import NestingConfig
+from .python_analyzer import PythonNestingAnalyzer
+from .typescript_analyzer import TypeScriptNestingAnalyzer
+
+
+class NestingDepthRule(BaseLintRule):
+    """Detects excessive nesting depth in functions."""
+
+    def __init__(self) -> None:
+        """Initialize the nesting depth rule."""
+        self._ignore_parser = IgnoreDirectiveParser()
+
+    @property
+    def rule_id(self) -> str:
+        """Unique identifier for this rule."""
+        return "nesting.excessive-depth"
+
+    @property
+    def rule_name(self) -> str:
+        """Human-readable name for this rule."""
+        return "Excessive Nesting Depth"
+
+    @property
+    def description(self) -> str:
+        """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.
+
+        Args:
+            context: Lint context with file information
+
+        Returns:
+            List of violations found
+        """
+        if context.file_content is None:
+            return []
+
+        # Load configuration
+        config = self._load_config(context)
+        if not config.enabled:
+            return []
+
+        # Analyze based on language
+        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) -> NestingConfig:
+        """Load configuration from context metadata.
+
+        Args:
+            context: Lint context containing metadata
+
+        Returns:
+            NestingConfig instance with configuration values
+        """
+        metadata = getattr(context, "metadata", None)
+        if metadata is None or not isinstance(metadata, dict):
+            return NestingConfig()
+
+        config_dict = metadata.get("nesting", {})
+        if not isinstance(config_dict, dict):
+            return NestingConfig()
+
+        return NestingConfig.from_dict(config_dict)
+
+    def _check_python(self, context: BaseLintContext, config: NestingConfig) -> list[Violation]:
+        """Check Python code for nesting violations.
+
+        Args:
+            context: Lint context with Python file information
+            config: Nesting configuration
+
+        Returns:
+            List of violations found in Python code
+        """
+        try:
+            tree = ast.parse(context.file_content or "")
+        except SyntaxError as e:
+            return [self._create_syntax_error_violation(e, context)]
+
+        analyzer = PythonNestingAnalyzer()
+        functions = analyzer.find_all_functions(tree)
+        return self._check_functions(functions, config, context)
+
+    def _check_functions(
+        self,
+        functions: list[ast.FunctionDef | ast.AsyncFunctionDef],
+        config: NestingConfig,
+        context: BaseLintContext,
+    ) -> list[Violation]:
+        """Check list of functions for nesting violations."""
+        violations = []
+        for func in functions:
+            violation = self._check_single_function(func, config, context)
+            if violation:
+                violations.append(violation)
+        return violations
+
+    def _check_single_function(
+        self,
+        func: ast.FunctionDef | ast.AsyncFunctionDef,
+        config: NestingConfig,
+        context: BaseLintContext,
+    ) -> Violation | None:
+        """Check a single function for nesting violations."""
+        analyzer = PythonNestingAnalyzer()
+        max_depth, _line = analyzer.calculate_max_depth(func)
+
+        if max_depth <= config.max_nesting_depth:
+            return None
+
+        violation = self._create_nesting_violation(func, max_depth, config, context)
+        if self._ignore_parser.should_ignore_violation(violation, context.file_content or ""):
+            return None
+
+        return violation
+
+    def _create_syntax_error_violation(
+        self, error: SyntaxError, context: BaseLintContext
+    ) -> Violation:
+        """Create violation for syntax error."""
+        return Violation(
+            rule_id=self.rule_id,
+            file_path=str(context.file_path or ""),
+            line=error.lineno or 0,
+            column=error.offset or 0,
+            message=f"Syntax error: {error.msg}",
+            severity=Severity.ERROR,
+            suggestion="Fix syntax errors before checking nesting depth",
+        )
+
+    def _create_nesting_violation(
+        self,
+        func: ast.FunctionDef | ast.AsyncFunctionDef,
+        max_depth: int,
+        config: NestingConfig,
+        context: BaseLintContext,
+    ) -> Violation:
+        """Create violation for excessive nesting."""
+        return Violation(
+            rule_id=self.rule_id,
+            file_path=str(context.file_path or ""),
+            line=func.lineno,
+            column=func.col_offset,
+            message=f"Function '{func.name}' has excessive nesting depth ({max_depth})",
+            severity=Severity.ERROR,
+            suggestion=(
+                f"Maximum nesting depth of {max_depth} exceeds limit of {config.max_nesting_depth}. "
+                "Consider extracting nested logic to separate functions, using early returns, "
+                "or applying guard clauses to reduce nesting."
+            ),
+        )
+
+    def _check_typescript(self, context: BaseLintContext, config: NestingConfig) -> list[Violation]:
+        """Check TypeScript code for nesting violations."""
+        analyzer = TypeScriptNestingAnalyzer()
+        root_node = analyzer.parse_typescript(context.file_content or "")
+
+        if root_node is None:
+            return []
+
+        functions = analyzer.find_all_functions(root_node)
+        return self._check_typescript_functions(functions, config, context)
+
+    def _check_typescript_functions(
+        self, functions: list, config: NestingConfig, context: BaseLintContext
+    ) -> list[Violation]:
+        """Check TypeScript functions for nesting violations."""
+        violations = []
+
+        for func_node, func_name in functions:
+            violation = self._check_single_typescript_function(
+                func_node, func_name, config, context
+            )
+            if violation:
+                violations.append(violation)
+
+        return violations
+
+    def _check_single_typescript_function(
+        self, func_node: Any, func_name: str, config: NestingConfig, context: BaseLintContext
+    ) -> Violation | None:
+        """Check a single TypeScript function for nesting violations."""
+        analyzer = TypeScriptNestingAnalyzer()
+        max_depth, _line = analyzer.calculate_max_depth(func_node)
+
+        if max_depth <= config.max_nesting_depth:
+            return None
+
+        violation = self._create_typescript_nesting_violation(
+            func_node, func_name, max_depth, config, context
+        )
+
+        if self._ignore_parser.should_ignore_violation(violation, context.file_content or ""):
+            return None
+
+        return violation
+
+    def _create_typescript_nesting_violation(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+        self,
+        func_node: Any,  # tree-sitter Node
+        func_name: str,
+        max_depth: int,
+        config: NestingConfig,
+        context: BaseLintContext,
+    ) -> Violation:
+        """Create violation for excessive nesting in TypeScript."""
+        line = func_node.start_point[0] + 1  # Convert to 1-indexed
+        column = func_node.start_point[1]
+
+        return Violation(
+            rule_id=self.rule_id,
+            file_path=str(context.file_path or ""),
+            line=line,
+            column=column,
+            message=f"Function '{func_name}' has excessive nesting depth ({max_depth})",
+            severity=Severity.ERROR,
+            suggestion=(
+                f"Maximum nesting depth of {max_depth} exceeds limit of {config.max_nesting_depth}. "
+                "Consider extracting nested logic to separate functions, using early returns, "
+                "or applying guard clauses to reduce nesting."
+            ),
+        )

src/linters/nesting/python_analyzer.py

@@ -0,0 +1,89 @@
+"""
+Purpose: Python AST-based nesting depth calculator
+
+Scope: Python code nesting depth analysis using ast module
+
+Overview: Analyzes Python code to calculate maximum nesting depth using AST traversal. Implements
+    visitor pattern to walk AST, tracking current depth and maximum depth found. Increments depth
+    for If, For, While, With, AsyncWith, Try, ExceptHandler, Match, and match_case nodes. Starts
+    depth counting at 1 for function body, matching reference implementation behavior. Returns
+    maximum depth found and location information for violation reporting. Provides helper method
+    to find all function definitions in an AST tree for batch processing.
+
+Dependencies: ast module for Python parsing
+
+Exports: PythonNestingAnalyzer class with calculate_max_depth method
+
+Interfaces: calculate_max_depth(func_node: ast.FunctionDef) -> tuple[int, int], find_all_functions
+
+Implementation: AST visitor pattern with depth tracking, based on reference implementation algorithm
+"""
+
+import ast
+
+
+class PythonNestingAnalyzer:
+    """Calculates maximum nesting depth in Python functions."""
+
+    def calculate_max_depth(
+        self, func_node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> tuple[int, int]:
+        """Calculate maximum nesting depth in a function.
+
+        Args:
+            func_node: AST node for function definition
+
+        Returns:
+            Tuple of (max_depth, line_number_of_max_depth)
+        """
+        max_depth = 0
+        max_depth_line = func_node.lineno
+
+        def visit_node(node: ast.AST, current_depth: int = 0) -> None:
+            nonlocal max_depth, max_depth_line
+
+            if current_depth > max_depth:
+                max_depth = current_depth
+                max_depth_line = getattr(node, "lineno", func_node.lineno)
+
+            # Nodes that increase nesting depth
+            if isinstance(
+                node,
+                (
+                    ast.If,
+                    ast.For,
+                    ast.While,
+                    ast.With,
+                    ast.AsyncWith,
+                    ast.Try,
+                    ast.ExceptHandler,
+                    ast.Match,
+                    ast.match_case,
+                ),
+            ):
+                current_depth += 1
+
+            # Visit children
+            for child in ast.iter_child_nodes(node):
+                visit_node(child, current_depth)
+
+        # Start at depth 1 for function body (matching reference implementation)
+        for stmt in func_node.body:
+            visit_node(stmt, 1)
+
+        return max_depth, max_depth_line
+
+    def find_all_functions(self, tree: ast.AST) -> list[ast.FunctionDef | ast.AsyncFunctionDef]:
+        """Find all function definitions in AST.
+
+        Args:
+            tree: Python AST to search
+
+        Returns:
+            List of all FunctionDef and AsyncFunctionDef nodes found
+        """
+        functions = []
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                functions.append(node)
+        return functions

src/linters/nesting/typescript_analyzer.py

@@ -0,0 +1,180 @@
+"""
+Purpose: TypeScript AST-based nesting depth calculator
+
+Scope: TypeScript code nesting depth analysis using tree-sitter parser
+
+Overview: Analyzes TypeScript code to calculate maximum nesting depth using AST traversal.
+    Implements visitor pattern to walk TypeScript AST from tree-sitter, tracking current depth
+    and maximum depth found. Increments depth for if_statement, for_statement, for_in_statement,
+    while_statement, do_statement, try_statement, switch_statement nodes. Starts depth counting
+    at 1 for function body. Returns maximum depth found and location.
+
+Dependencies: tree-sitter, tree-sitter-typescript for TypeScript parsing
+
+Exports: TypeScriptNestingAnalyzer class with calculate_max_depth and parse_typescript methods
+
+Interfaces: calculate_max_depth(func_node) -> tuple[int, int], parse_typescript(code: str)
+
+Implementation: tree-sitter AST visitor pattern with depth tracking for TypeScript
+"""
+
+from typing import Any
+
+try:
+    import tree_sitter_typescript as tstypescript
+    from tree_sitter import Language, Node, Parser
+
+    TS_LANGUAGE = Language(tstypescript.language_typescript())
+    TS_PARSER = Parser(TS_LANGUAGE)
+    TREE_SITTER_AVAILABLE = True
+except ImportError:
+    TREE_SITTER_AVAILABLE = False
+    TS_PARSER = None  # type: ignore
+    Node = Any  # type: ignore
+
+
+class TypeScriptNestingAnalyzer:
+    """Calculates maximum nesting depth in TypeScript functions."""
+
+    # Tree-sitter node types that increase nesting depth
+    NESTING_NODE_TYPES = {
+        "if_statement",
+        "for_statement",
+        "for_in_statement",
+        "while_statement",
+        "do_statement",
+        "try_statement",
+        "switch_statement",
+        "with_statement",  # Deprecated but exists
+    }
+
+    def parse_typescript(self, code: str) -> Node | None:
+        """Parse TypeScript code to AST using tree-sitter.
+
+        Args:
+            code: TypeScript source code to parse
+
+        Returns:
+            Tree-sitter AST root node, or None if parsing fails
+        """
+        if not TREE_SITTER_AVAILABLE or TS_PARSER is None:
+            return None
+
+        tree = TS_PARSER.parse(bytes(code, "utf8"))
+        return tree.root_node
+
+    def calculate_max_depth(self, func_node: Node) -> tuple[int, int]:
+        """Calculate maximum nesting depth in a TypeScript function."""
+        if not TREE_SITTER_AVAILABLE:
+            return 0, 0
+
+        body_node = self._find_function_body(func_node)
+        if not body_node:
+            return 0, func_node.start_point[0] + 1
+
+        return self._calculate_depth_in_body(body_node)
+
+    def _find_function_body(self, func_node: Node) -> Node | None:
+        """Find the statement_block node in a function."""
+        for child in func_node.children:
+            if child.type == "statement_block":
+                return child
+        return None
+
+    def _calculate_depth_in_body(self, body_node: Node) -> tuple[int, int]:
+        """Calculate max depth within a function body."""
+        max_depth = 0
+        max_depth_line = body_node.start_point[0] + 1
+
+        def visit_node(node: Node, current_depth: int = 0) -> None:
+            nonlocal max_depth, max_depth_line
+
+            if current_depth > max_depth:
+                max_depth = current_depth
+                max_depth_line = node.start_point[0] + 1
+
+            new_depth = current_depth + 1 if node.type in self.NESTING_NODE_TYPES else current_depth
+
+            for child in node.children:
+                visit_node(child, new_depth)
+
+        for child in body_node.children:
+            visit_node(child, 1)
+
+        return max_depth, max_depth_line
+
+    def find_all_functions(self, root_node: Node) -> list[tuple[Node, str]]:
+        """Find all function definitions in TypeScript AST.
+
+        Args:
+            root_node: Tree-sitter root node
+
+        Returns:
+            List of tuples: (function_node, function_name)
+        """
+        if not TREE_SITTER_AVAILABLE:
+            return []
+
+        functions: list[tuple[Node, str]] = []
+        self._collect_functions(root_node, functions)
+        return functions
+
+    def _collect_functions(self, node: Node, functions: list[tuple[Node, str]]) -> None:
+        """Recursively collect function nodes from AST."""
+        function_entry = self._extract_function_if_applicable(node)
+        if function_entry:
+            functions.append(function_entry)
+
+        for child in node.children:
+            self._collect_functions(child, functions)
+
+    def _extract_function_if_applicable(self, node: Node) -> tuple[Node, str] | None:
+        """Extract function node and name if node is a function type."""
+        if node.type == "function_declaration":
+            return self._extract_function_declaration(node)
+        if node.type == "arrow_function":
+            return self._extract_arrow_function(node)
+        if node.type == "method_definition":
+            return self._extract_method_definition(node)
+        if node.type in ("function_expression", "function"):
+            return self._extract_function_expression(node)
+        return None
+
+    def _extract_function_declaration(self, node: Node) -> tuple[Node, str]:
+        """Extract name from function declaration node."""
+        name_node = self._find_child_by_type(node, "identifier")
+        name = name_node.text.decode("utf8") if name_node and name_node.text else "<anonymous>"
+        return (node, name)
+
+    def _extract_arrow_function(self, node: Node) -> tuple[Node, str]:
+        """Extract name from arrow function node."""
+        name = "<arrow>"
+        parent = node.parent
+        if parent and parent.type == "variable_declarator":
+            id_node = self._find_child_by_type(parent, "identifier")
+            if id_node and id_node.text:
+                name = id_node.text.decode("utf8")
+        return (node, name)
+
+    def _extract_method_definition(self, node: Node) -> tuple[Node, str]:
+        """Extract name from method definition node."""
+        name_node = self._find_child_by_type(node, "property_identifier")
+        name = name_node.text.decode("utf8") if name_node and name_node.text else "<method>"
+        return (node, name)
+
+    def _extract_function_expression(self, node: Node) -> tuple[Node, str]:
+        """Extract name from function expression node."""
+        name = "<function>"
+        parent = node.parent
+        if parent and parent.type == "variable_declarator":
+            id_node = self._find_child_by_type(parent, "identifier")
+            if id_node and id_node.text:
+                name = id_node.text.decode("utf8")
+        return (node, name)
+
+    def _find_child_by_type(self, node: Node, child_type: str) -> Node | None:
+        """Find first child node matching the given type."""
+        for child in node.children:
+            if child.type == child_type:
+                return child
+        return None

src/orchestrator/__init__.py

@@ -0,0 +1,9 @@
+"""Multi-language orchestrator for coordinating linting operations.
+
+This package provides the main orchestration engine that coordinates rule execution
+across files and languages.
+"""
+
+from .core import Orchestrator
+
+__all__ = ["Orchestrator"]