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

src/linters/cqs/function_analyzer.py

@@ -0,0 +1,201 @@
+"""
+Purpose: AST visitor that builds CQSPattern objects for each function in Python code
+
+Scope: Per-function CQS analysis with config-driven filtering
+
+Overview: Provides FunctionAnalyzer class that traverses Python AST to analyze each function
+    for CQS patterns. Builds CQSPattern objects containing INPUT and OUTPUT operations for
+    each function/method. Applies configuration filtering including ignore_methods for
+    constructor exclusion, ignore_decorators for property-like methods, and detect_fluent_interface
+    for return self patterns. Tracks class context via stack for proper method detection.
+
+Dependencies: ast module, InputDetector, OutputDetector, CQSConfig, CQSPattern
+
+Exports: FunctionAnalyzer
+
+Interfaces: FunctionAnalyzer.analyze(tree: ast.Module) -> list[CQSPattern]
+
+Implementation: AST NodeVisitor with class context tracking and config-based filtering
+
+Suppressions:
+    - N802: visit_ClassDef, visit_FunctionDef, visit_AsyncFunctionDef follow Python AST
+        visitor naming convention (camelCase required by ast.NodeVisitor)
+    - invalid-name: AST visitor methods follow required camelCase naming convention
+"""
+
+import ast
+from collections.abc import Sequence
+
+from .config import CQSConfig
+from .input_detector import InputDetector
+from .output_detector import OutputDetector
+from .types import CQSPattern, InputOperation, OutputOperation
+
+
+def _get_name_from_decorator(dec: ast.expr) -> str | None:
+    """Extract decorator name from a single decorator expression."""
+    if isinstance(dec, ast.Name):
+        return dec.id
+    if isinstance(dec, ast.Attribute):
+        return dec.attr
+    if isinstance(dec, ast.Call):
+        return _get_name_from_call_decorator(dec.func)
+    return None
+
+
+def _get_name_from_call_decorator(func: ast.expr) -> str | None:
+    """Extract name from Call decorator's func attribute."""
+    if isinstance(func, ast.Name):
+        return func.id
+    if isinstance(func, ast.Attribute):
+        return func.attr
+    return None
+
+
+def _get_decorator_names(decorators: list[ast.expr]) -> list[str]:
+    """Extract decorator names from decorator list."""
+    names = [_get_name_from_decorator(dec) for dec in decorators]
+    return [name for name in names if name is not None]
+
+
+def _has_return_self(body: Sequence[ast.stmt]) -> bool:
+    """Check if function body ends with 'return self'."""
+    if not body:
+        return False
+
+    last_stmt = body[-1]
+    if not isinstance(last_stmt, ast.Return):
+        return False
+    if last_stmt.value is None:
+        return False
+    return isinstance(last_stmt.value, ast.Name) and last_stmt.value.id == "self"
+
+
+def _is_fluent_interface(node: ast.FunctionDef | ast.AsyncFunctionDef, config: CQSConfig) -> bool:
+    """Check if function uses fluent interface pattern (return self)."""
+    if not config.detect_fluent_interface:
+        return False
+    return _has_return_self(node.body)
+
+
+def _is_function_definition(stmt: ast.stmt) -> bool:
+    """Check if statement is a function definition."""
+    return isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef))
+
+
+def _detect_inputs_in_body(
+    body: Sequence[ast.stmt], input_detector: InputDetector
+) -> list[InputOperation]:
+    """Detect INPUT operations in function body statements."""
+    inputs: list[InputOperation] = []
+    stmts = [stmt for stmt in body if not _is_function_definition(stmt)]
+    for stmt in stmts:
+        mini_module = ast.Module(body=[stmt], type_ignores=[])
+        stmt_inputs = input_detector.find_inputs(mini_module)
+        inputs.extend(stmt_inputs)
+    return inputs
+
+
+def _detect_outputs_in_body(
+    body: Sequence[ast.stmt], output_detector: OutputDetector
+) -> list[OutputOperation]:
+    """Detect OUTPUT operations in function body statements."""
+    outputs: list[OutputOperation] = []
+    stmts = [stmt for stmt in body if not _is_function_definition(stmt)]
+    for stmt in stmts:
+        mini_module = ast.Module(body=[stmt], type_ignores=[])
+        stmt_outputs = output_detector.find_outputs(mini_module)
+        outputs.extend(stmt_outputs)
+    return outputs
+
+
+class FunctionAnalyzer(ast.NodeVisitor):
+    """Analyzes Python AST to build CQSPattern objects for each function."""
+
+    def __init__(self, file_path: str, config: CQSConfig) -> None:
+        """Initialize the analyzer."""
+        self._file_path = file_path
+        self._config = config
+        self._input_detector = InputDetector()
+        self._output_detector = OutputDetector()
+        self._patterns: list[CQSPattern] = []
+        self._class_stack: list[str] = []
+
+    def analyze(self, tree: ast.Module) -> list[CQSPattern]:
+        """Analyze AST and return CQSPattern for each function."""
+        self._patterns = []
+        self._class_stack = []
+        self.visit(tree)
+        return list(self._patterns)
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:  # noqa: N802  # pylint: disable=invalid-name
+        """Visit class definition to track class context."""
+        self._class_stack.append(node.name)
+        self.generic_visit(node)
+        self._class_stack.pop()
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:  # noqa: N802  # pylint: disable=invalid-name
+        """Visit function definition to analyze for CQS patterns."""
+        self._analyze_function(node, is_async=False)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:  # noqa: N802  # pylint: disable=invalid-name
+        """Visit async function definition to analyze for CQS patterns."""
+        self._analyze_function(node, is_async=True)
+
+    def _analyze_function(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef, is_async: bool
+    ) -> None:
+        """Analyze a function/method for CQS patterns."""
+        # Check if function should be ignored
+        if self._should_ignore_function(node):
+            self.generic_visit(node)
+            return
+
+        # Check for fluent interface pattern
+        if _is_fluent_interface(node, self._config):
+            self.generic_visit(node)
+            return
+
+        # Detect INPUTs and OUTPUTs in function body only (not nested functions)
+        inputs = _detect_inputs_in_body(node.body, self._input_detector)
+        outputs = _detect_outputs_in_body(node.body, self._output_detector)
+
+        # Build pattern
+        pattern = self._build_pattern(node, is_async, inputs, outputs)
+        self._patterns.append(pattern)
+
+        # Continue visiting nested functions
+        self.generic_visit(node)
+
+    def _build_pattern(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+        is_async: bool,
+        inputs: list[InputOperation],
+        outputs: list[OutputOperation],
+    ) -> CQSPattern:
+        """Build CQSPattern from function node and detected operations."""
+        is_method = len(self._class_stack) > 0
+        class_name = self._class_stack[-1] if self._class_stack else None
+
+        return CQSPattern(
+            function_name=node.name,
+            line=node.lineno,
+            column=node.col_offset,
+            file_path=self._file_path,
+            inputs=inputs,
+            outputs=outputs,
+            is_method=is_method,
+            is_async=is_async,
+            class_name=class_name,
+        )
+
+    def _should_ignore_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+        """Check if function should be ignored based on config."""
+        # Check ignore_methods (e.g., __init__, __new__)
+        if node.name in self._config.ignore_methods:
+            return True
+
+        # Check ignore_decorators (e.g., @property, @cached_property)
+        decorator_names = _get_decorator_names(node.decorator_list)
+        return any(name in self._config.ignore_decorators for name in decorator_names)

src/linters/cqs/input_detector.py

@@ -0,0 +1,139 @@
+"""
+Purpose: AST-based detector for INPUT (query) operations in CQS analysis
+
+Scope: Detects assignment patterns where function call results are captured
+
+Overview: Provides InputDetector class that uses AST traversal to find INPUT operations
+    which are query-like assignments that capture function call return values. Detects
+    patterns including simple assignments (x = func()), tuple unpacking (x, y = func()),
+    async assignments (x = await func()), attribute assignments (self.x = func()),
+    subscript assignments (cache[key] = func()), annotated assignments (result: int = func()),
+    and walrus operator patterns ((x := func())). Excludes non-call assignments like
+    literals, variable copies, and expression results.
+
+Dependencies: ast module for Python AST traversal
+
+Exports: InputDetector
+
+Interfaces: InputDetector.find_inputs(tree: ast.AST) -> list[InputOperation]
+
+Implementation: AST NodeVisitor pattern with visit_Assign, visit_AnnAssign, visit_NamedExpr
+
+Suppressions:
+    - N802: visit_Assign, visit_AnnAssign, visit_NamedExpr follow Python AST visitor
+        naming convention (camelCase required by ast.NodeVisitor)
+    - invalid-name: visit_Assign, visit_AnnAssign, visit_NamedExpr follow Python AST visitor
+        naming convention (camelCase required by ast.NodeVisitor)
+"""
+
+import ast
+
+from .types import InputOperation
+
+
+def _is_call_expression(node: ast.expr) -> bool:
+    """Check if expression is a Call or Await(Call)."""
+    if isinstance(node, ast.Call):
+        return True
+    if isinstance(node, ast.Await) and isinstance(node.value, ast.Call):
+        return True
+    return False
+
+
+def _unwrap_await(node: ast.expr) -> ast.expr:
+    """Unwrap Await to get inner expression."""
+    if isinstance(node, ast.Await):
+        return node.value
+    return node
+
+
+def _extract_target_name(target: ast.expr) -> str:
+    """Extract string representation of assignment target."""
+    if isinstance(target, ast.Name):
+        return target.id
+    if isinstance(target, ast.Tuple):
+        return ", ".join(_extract_target_name(elt) for elt in target.elts)
+    return ast.unparse(target)
+
+
+class InputDetector(ast.NodeVisitor):
+    """Detects INPUT (query) operations that capture function call results."""
+
+    def __init__(self) -> None:
+        """Initialize the detector."""
+        self._inputs: list[InputOperation] = []
+
+    def find_inputs(self, tree: ast.AST) -> list[InputOperation]:
+        """Find INPUT operations in AST.
+
+        Args:
+            tree: Python AST to analyze
+
+        Returns:
+            List of detected InputOperation objects
+        """
+        self._inputs = []
+        self.visit(tree)
+        return list(self._inputs)
+
+    def visit_Assign(self, node: ast.Assign) -> None:  # noqa: N802  # pylint: disable=invalid-name
+        """Visit assignment to check for INPUT pattern.
+
+        Detects: x = func(), x, y = func(), self.x = func(), x[key] = func()
+
+        Args:
+            node: AST Assign node to analyze
+        """
+        if _is_call_expression(node.value):
+            call_node = _unwrap_await(node.value)
+            for target in node.targets:
+                self._inputs.append(
+                    InputOperation(
+                        line=node.lineno,
+                        column=node.col_offset,
+                        expression=ast.unparse(call_node),
+                        target=_extract_target_name(target),
+                    )
+                )
+        self.generic_visit(node)
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:  # noqa: N802  # pylint: disable=invalid-name
+        """Visit annotated assignment to check for INPUT pattern.
+
+        Detects: result: int = func()
+
+        Args:
+            node: AST AnnAssign node to analyze
+        """
+        if node.value is not None and node.target is not None:
+            if _is_call_expression(node.value):
+                call_node = _unwrap_await(node.value)
+                self._inputs.append(
+                    InputOperation(
+                        line=node.lineno,
+                        column=node.col_offset,
+                        expression=ast.unparse(call_node),
+                        target=_extract_target_name(node.target),
+                    )
+                )
+        self.generic_visit(node)
+
+    def visit_NamedExpr(self, node: ast.NamedExpr) -> None:  # noqa: N802  # pylint: disable=invalid-name
+        """Visit named expression (walrus operator) to check for INPUT pattern.
+
+        Detects: (x := func())
+
+        Args:
+            node: AST NamedExpr node to analyze
+        """
+        if _is_call_expression(node.value):
+            call_node = _unwrap_await(node.value)
+            self._inputs.append(
+                InputOperation(
+                    line=node.lineno,
+                    column=node.col_offset,
+                    expression=ast.unparse(call_node),
+                    target=node.target.id,
+                )
+            )
+        self.generic_visit(node)

src/linters/cqs/linter.py

@@ -0,0 +1,159 @@
+"""
+Purpose: Main CQS linter rule implementing MultiLanguageLintRule interface
+
+Scope: Entry point for CQS (Command-Query Separation) violation detection in Python and TypeScript
+
+Overview: Provides CQSRule class that implements the MultiLanguageLintRule interface for
+    detecting functions that violate Command-Query Separation by mixing queries (INPUTs)
+    with commands (OUTPUTs). Supports both Python (via AST) and TypeScript (via tree-sitter).
+    Returns violations for functions that mix operations according to min_operations threshold.
+    Supports file path ignore patterns via glob matching.
+
+Dependencies: MultiLanguageLintRule, PythonCQSAnalyzer, TypeScriptCQSAnalyzer, CQSConfig,
+    build_cqs_violation
+
+Exports: CQSRule
+
+Interfaces: check(context: BaseLintContext) -> list[Violation]
+
+Implementation: Multi-language analysis with config-driven filtering and min_operations threshold
+"""
+
+from fnmatch import fnmatch
+
+from src.core.base import BaseLintContext, MultiLanguageLintRule
+from src.core.linter_utils import load_linter_config
+from src.core.types import Violation
+
+from .config import CQSConfig
+from .python_analyzer import PythonCQSAnalyzer
+from .types import CQSPattern
+from .typescript_cqs_analyzer import TypeScriptCQSAnalyzer
+from .violation_builder import build_cqs_violation
+
+
+class CQSRule(MultiLanguageLintRule):
+    """Detects CQS (Command-Query Separation) violations in Python and TypeScript code."""
+
+    def __init__(self, config: CQSConfig | None = None) -> None:
+        """Initialize the CQS rule.
+
+        Args:
+            config: Optional configuration override for testing
+        """
+        super().__init__()
+        self._config_override = config
+        self._python_analyzer = PythonCQSAnalyzer()
+        self._typescript_analyzer = TypeScriptCQSAnalyzer()
+
+    @property
+    def rule_id(self) -> str:
+        """Unique identifier for this rule."""
+        return "cqs"
+
+    @property
+    def rule_name(self) -> str:
+        """Human-readable name for this rule."""
+        return "Command-Query Separation"
+
+    @property
+    def description(self) -> str:
+        """Description of what this rule checks."""
+        return (
+            "Detects functions that violate Command-Query Separation by mixing "
+            "queries (functions that return values) with commands (functions that "
+            "perform side effects). Functions should either query state and return "
+            "a value, or command a change without returning data."
+        )
+
+    def _load_config(self, context: BaseLintContext) -> CQSConfig:
+        """Load configuration from context.
+
+        Args:
+            context: Lint context
+
+        Returns:
+            CQSConfig object
+        """
+        if self._config_override is not None:
+            return self._config_override
+        return load_linter_config(context, "cqs", CQSConfig)
+
+    def _check_python(self, context: BaseLintContext, config: CQSConfig) -> list[Violation]:
+        """Check Python code for CQS violations.
+
+        Args:
+            context: Lint context with Python file information
+            config: Loaded configuration
+
+        Returns:
+            List of violations found in Python code
+        """
+        file_path = str(context.file_path) if context.file_path else "unknown"
+
+        if self._matches_ignore_pattern(file_path, config):
+            return []
+
+        patterns = self._python_analyzer.analyze(context.file_content or "", file_path, config)
+        return self._patterns_to_violations(patterns, config)
+
+    def _check_typescript(self, context: BaseLintContext, config: CQSConfig) -> list[Violation]:
+        """Check TypeScript/JavaScript code for CQS violations.
+
+        Args:
+            context: Lint context with TypeScript/JavaScript file information
+            config: Loaded configuration
+
+        Returns:
+            List of violations found in TypeScript/JavaScript code
+        """
+        file_path = str(context.file_path) if context.file_path else "unknown"
+
+        if self._matches_ignore_pattern(file_path, config):
+            return []
+
+        patterns = self._typescript_analyzer.analyze(context.file_content or "", file_path, config)
+        return self._patterns_to_violations(patterns, config)
+
+    def _patterns_to_violations(
+        self, patterns: list[CQSPattern], config: CQSConfig
+    ) -> list[Violation]:
+        """Convert CQSPatterns to Violations, applying thresholds.
+
+        Args:
+            patterns: List of CQSPattern objects
+            config: CQS configuration
+
+        Returns:
+            List of Violation objects
+        """
+        violating_patterns = [p for p in patterns if self._is_violation(p, config)]
+        return [build_cqs_violation(p) for p in violating_patterns]
+
+    def _matches_ignore_pattern(self, file_path: str, config: CQSConfig) -> bool:
+        """Check if file path matches any ignore pattern.
+
+        Args:
+            file_path: Path to check
+            config: CQS configuration
+
+        Returns:
+            True if path matches an ignore pattern
+        """
+        return any(fnmatch(file_path, pattern) for pattern in config.ignore_patterns)
+
+    def _is_violation(self, pattern: CQSPattern, config: CQSConfig) -> bool:
+        """Check if pattern represents a violation based on config.
+
+        Args:
+            pattern: CQSPattern to check
+            config: CQS configuration
+
+        Returns:
+            True if pattern is a violation
+        """
+        if not pattern.has_violation():
+            return False
+
+        min_ops = config.min_operations
+        return len(pattern.inputs) >= min_ops and len(pattern.outputs) >= min_ops

src/linters/cqs/output_detector.py

@@ -0,0 +1,84 @@
+"""
+Purpose: AST-based detector for OUTPUT (command) operations in CQS analysis
+
+Scope: Detects statement-level calls where return values are discarded
+
+Overview: Provides OutputDetector class that uses AST traversal to find OUTPUT operations
+    which are command-like statement-level function calls that discard return values.
+    Detects patterns including statement calls (func()), async statements (await func()),
+    method calls (obj.method()), and chained calls (obj.method().method2()). Only ast.Expr
+    nodes containing Call or Await(Call) are detected as OUTPUT. All other constructs
+    (return, if, while, for, with, assert, raise, yield, assignments, comprehensions)
+    are naturally excluded because they use different AST node types.
+
+Dependencies: ast module for Python AST traversal
+
+Exports: OutputDetector
+
+Interfaces: OutputDetector.find_outputs(tree: ast.AST) -> list[OutputOperation]
+
+Implementation: AST NodeVisitor pattern with visit_Expr to detect statement-level calls
+
+Suppressions:
+    - N802: visit_Expr follows Python AST visitor naming convention
+        (camelCase required by ast.NodeVisitor)
+    - invalid-name: visit_Expr follows Python AST visitor naming convention
+        (camelCase required by ast.NodeVisitor)
+"""
+
+import ast
+
+from .types import OutputOperation
+
+
+def _extract_call_expression(node: ast.expr) -> ast.Call | None:
+    """Extract Call from expression, unwrapping Await if present."""
+    if isinstance(node, ast.Call):
+        return node
+    if isinstance(node, ast.Await) and isinstance(node.value, ast.Call):
+        return node.value
+    return None
+
+
+class OutputDetector(ast.NodeVisitor):
+    """Detects OUTPUT (command) operations that discard function call results."""
+
+    def __init__(self) -> None:
+        """Initialize the detector."""
+        self._outputs: list[OutputOperation] = []
+
+    def find_outputs(self, tree: ast.AST) -> list[OutputOperation]:
+        """Find OUTPUT operations in AST.
+
+        Args:
+            tree: Python AST to analyze
+
+        Returns:
+            List of detected OutputOperation objects
+        """
+        self._outputs = []
+        self.visit(tree)
+        return list(self._outputs)
+
+    def visit_Expr(self, node: ast.Expr) -> None:  # noqa: N802  # pylint: disable=invalid-name
+        """Visit expression statement to check for OUTPUT pattern.
+
+        Only statement-level expressions (ast.Expr) are OUTPUT. This naturally
+        excludes return statements, conditionals, assignments, comprehensions,
+        and other constructs that use the call result.
+
+        Detects: func(), await func(), obj.method(), obj.method().method2()
+
+        Args:
+            node: AST Expr node to analyze
+        """
+        call_node = _extract_call_expression(node.value)
+        if call_node is not None:
+            self._outputs.append(
+                OutputOperation(
+                    line=node.lineno,
+                    column=node.col_offset,
+                    expression=ast.unparse(call_node),
+                )
+            )
+        self.generic_visit(node)

src/linters/cqs/python_analyzer.py

@@ -0,0 +1,54 @@
+"""
+Purpose: Coordinator for Python CQS analysis returning per-function CQSPattern objects
+
+Scope: High-level analyzer that orchestrates FunctionAnalyzer for function-level detection
+
+Overview: Provides PythonCQSAnalyzer class that coordinates CQS pattern detection in Python
+    code. Handles AST parsing with proper SyntaxError handling, returning empty results for
+    unparseable code rather than raising exceptions. Delegates to FunctionAnalyzer to build
+    CQSPattern objects for each function/method, which contain INPUT and OUTPUT operations
+    along with function metadata (name, class context, async status).
+
+Dependencies: ast module, FunctionAnalyzer, CQSConfig, CQSPattern
+
+Exports: PythonCQSAnalyzer
+
+Interfaces: PythonCQSAnalyzer.analyze(code, file_path, config) -> list[CQSPattern]
+
+Implementation: Coordinates FunctionAnalyzer with error handling for AST parsing failures
+"""
+
+import ast
+
+from .config import CQSConfig
+from .function_analyzer import FunctionAnalyzer
+from .types import CQSPattern
+
+
+class PythonCQSAnalyzer:
+    """Analyzes Python code for CQS patterns, returning per-function results."""
+
+    def analyze(
+        self,
+        code: str,
+        file_path: str,
+        config: CQSConfig,
+    ) -> list[CQSPattern]:
+        """Analyze Python code for CQS patterns in each function.
+
+        Args:
+            code: Python source code to analyze
+            file_path: Path to the source file (for error context)
+            config: CQS configuration settings
+
+        Returns:
+            List of CQSPattern objects, one per function/method.
+            Returns empty list if code cannot be parsed due to SyntaxError.
+        """
+        try:
+            tree = ast.parse(code, filename=file_path)
+        except SyntaxError:
+            return []
+
+        analyzer = FunctionAnalyzer(file_path, config)
+        return analyzer.analyze(tree)