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

src/linters/cqs/types.py

@@ -0,0 +1,82 @@
+"""
+Purpose: Core data structures for CQS (Command-Query Separation) linter
+
+Scope: Type definitions for INPUT operations, OUTPUT operations, and CQS patterns
+
+Overview: Defines the fundamental data structures used by the CQS linter to represent
+    and analyze code patterns. InputOperation represents query-like operations that
+    assign call results to variables. OutputOperation represents command-like operations
+    that are statement-level calls without capturing return values. CQSPattern aggregates
+    these operations for a single function and provides methods to detect CQS violations
+    (functions that mix INPUTs and OUTPUTs).
+
+Dependencies: dataclasses for structured data representation
+
+Exports: InputOperation, OutputOperation, CQSPattern
+
+Interfaces: CQSPattern.has_violation(), CQSPattern.get_full_name()
+
+Implementation: Immutable dataclasses with computed methods for violation detection
+
+Suppressions:
+    too-many-instance-attributes: CQSPattern requires 9 attributes to fully describe
+        a function's CQS analysis (name, location, file, inputs, outputs, flags)
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class InputOperation:
+    """Represents an INPUT (query) operation in code.
+
+    An INPUT operation is one where a function call result is captured and used,
+    typically through assignment: x = func().
+    """
+
+    line: int
+    column: int
+    expression: str  # e.g., "fetch_data()"
+    target: str  # e.g., "x" or "self.data"
+
+
+@dataclass(frozen=True)
+class OutputOperation:
+    """Represents an OUTPUT (command) operation in code.
+
+    An OUTPUT operation is a statement-level call where the return value is
+    discarded: func() as a standalone statement.
+    """
+
+    line: int
+    column: int
+    expression: str  # e.g., "save_data(result)"
+
+
+@dataclass
+class CQSPattern:  # pylint: disable=too-many-instance-attributes
+    """Represents a function's CQS analysis results.
+
+    Aggregates all INPUT and OUTPUT operations found within a function body
+    and provides methods to determine if the function violates CQS principles.
+    """
+
+    function_name: str
+    line: int
+    column: int
+    file_path: str
+    inputs: list[InputOperation] = field(default_factory=list)
+    outputs: list[OutputOperation] = field(default_factory=list)
+    is_method: bool = False
+    is_async: bool = False
+    class_name: str | None = None
+
+    def has_violation(self) -> bool:
+        """Return True if function mixes INPUTs and OUTPUTs (CQS violation)."""
+        return len(self.inputs) > 0 and len(self.outputs) > 0
+
+    def get_full_name(self) -> str:
+        """Return fully qualified name (ClassName.method or function)."""
+        if self.class_name:
+            return f"{self.class_name}.{self.function_name}"
+        return self.function_name

src/linters/cqs/typescript_cqs_analyzer.py

@@ -0,0 +1,61 @@
+"""
+Purpose: Coordinator for TypeScript CQS analysis returning per-function CQSPattern objects
+
+Scope: High-level analyzer that orchestrates TypeScriptFunctionAnalyzer for function-level detection
+
+Overview: Provides TypeScriptCQSAnalyzer class that coordinates CQS pattern detection in TypeScript
+    code. Handles tree-sitter parsing with proper availability checking, returning empty results
+    when tree-sitter is unavailable rather than raising exceptions. Delegates to
+    TypeScriptFunctionAnalyzer to build CQSPattern objects for each function/method, which
+    contain INPUT and OUTPUT operations along with function metadata (name, class context,
+    async status).
+
+Dependencies: TypeScriptBaseAnalyzer, TypeScriptFunctionAnalyzer, CQSConfig, CQSPattern
+
+Exports: TypeScriptCQSAnalyzer
+
+Interfaces: TypeScriptCQSAnalyzer.analyze(code, file_path, config) -> list[CQSPattern]
+
+Implementation: Coordinates TypeScriptFunctionAnalyzer with tree-sitter availability checking
+"""
+
+from src.analyzers.typescript_base import TREE_SITTER_AVAILABLE, TypeScriptBaseAnalyzer
+
+from .config import CQSConfig
+from .types import CQSPattern
+from .typescript_function_analyzer import TypeScriptFunctionAnalyzer
+
+
+class TypeScriptCQSAnalyzer(TypeScriptBaseAnalyzer):
+    """Analyzes TypeScript code for CQS patterns, returning per-function results."""
+
+    def __init__(self) -> None:
+        """Initialize analyzer with function analyzer."""
+        super().__init__()
+        self._function_analyzer = TypeScriptFunctionAnalyzer()
+
+    def analyze(
+        self,
+        code: str,
+        file_path: str,
+        config: CQSConfig,
+    ) -> list[CQSPattern]:
+        """Analyze TypeScript code for CQS patterns in each function.
+
+        Args:
+            code: TypeScript 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 tree-sitter is unavailable or parsing fails.
+        """
+        if not TREE_SITTER_AVAILABLE:
+            return []
+
+        root_node = self.parse_typescript(code)
+        if root_node is None:
+            return []
+
+        return self._function_analyzer.analyze(root_node, file_path, config)

src/linters/cqs/typescript_function_analyzer.py

@@ -0,0 +1,192 @@
+"""
+Purpose: Tree-sitter based analyzer that builds CQSPattern objects for TypeScript functions
+
+Scope: Per-function CQS analysis with config-driven filtering for TypeScript code
+
+Overview: Provides TypeScriptFunctionAnalyzer class that traverses TypeScript AST to analyze
+    each function for CQS patterns. Builds CQSPattern objects containing INPUT and OUTPUT
+    operations for each function/method. Extends TypeScriptBaseAnalyzer for tree-sitter
+    utilities and delegates function extraction to TypeScriptFunctionExtractor. Applies
+    configuration filtering including ignore_methods for constructor exclusion and
+    detect_fluent_interface for return this patterns.
+
+Dependencies: TypeScriptBaseAnalyzer, TypeScriptFunctionExtractor, TypeScriptInputDetector,
+    TypeScriptOutputDetector, CQSConfig, CQSPattern
+
+Exports: TypeScriptFunctionAnalyzer
+
+Interfaces: TypeScriptFunctionAnalyzer.analyze(root_node, file_path, config) -> list[CQSPattern]
+
+Implementation: Tree-sitter function extraction with per-function INPUT/OUTPUT detection
+"""
+
+from collections.abc import Callable
+
+from src.analyzers.typescript_base import (
+    TREE_SITTER_AVAILABLE,
+    Node,
+    TypeScriptBaseAnalyzer,
+)
+from src.linters.nesting.typescript_function_extractor import TypeScriptFunctionExtractor
+
+from .config import CQSConfig
+from .types import CQSPattern, InputOperation, OutputOperation
+from .typescript_input_detector import TypeScriptInputDetector
+from .typescript_output_detector import TypeScriptOutputDetector
+
+
+def _get_function_child_positions(func_node: Node) -> list[tuple[int, int]]:
+    """Get positions of child function nodes from a function_declaration."""
+    return [
+        (child.start_point[0], child.start_point[1])
+        for child in func_node.children
+        if child.type == "function"
+    ]
+
+
+def _get_child_function_positions(functions: list[tuple[Node, str]]) -> set[tuple[int, int]]:
+    """Get positions of function nodes that are children of function_declarations."""
+    declaration_nodes = (
+        func_node for func_node, _ in functions if func_node.type == "function_declaration"
+    )
+    return {pos for node in declaration_nodes for pos in _get_function_child_positions(node)}
+
+
+def _filter_duplicate_functions(
+    functions: list[tuple[Node, str]],
+) -> list[tuple[Node, str]]:
+    """Filter out duplicate function detections."""
+    declaration_positions = _get_child_function_positions(functions)
+    return [
+        (func_node, func_name)
+        for func_node, func_name in functions
+        if not (
+            func_node.type == "function"
+            and (func_node.start_point[0], func_node.start_point[1]) in declaration_positions
+        )
+    ]
+
+
+def _find_function_body(func_node: Node) -> Node | None:
+    """Find the statement_block (body) of a function."""
+    return next(
+        (child for child in func_node.children if child.type == "statement_block"),
+        None,
+    )
+
+
+def _ends_with_return_this(body_node: Node) -> bool:
+    """Check if function body ends with 'return this'."""
+    returns = [child for child in body_node.children if child.type == "return_statement"]
+    if not returns:
+        return False
+    return any(child.type == "this" for child in returns[-1].children)
+
+
+def _is_async_function(func_node: Node, text: str) -> bool:
+    """Check if function is async."""
+    if any(child.type == "async" for child in func_node.children):
+        return True
+    return text.startswith("async ")
+
+
+def _is_constructor_method(node: Node, get_text: Callable[[Node], str]) -> bool:
+    """Check if method is a constructor."""
+    for child in node.children:
+        if child.type == "property_identifier":
+            return get_text(child) == "constructor"
+    return False
+
+
+def _get_class_type_identifier(class_node: Node, get_text: Callable[[Node], str]) -> str | None:
+    """Extract the type identifier from a class node."""
+    for child in class_node.children:
+        if child.type == "type_identifier":
+            return get_text(child)
+    return None
+
+
+def _find_enclosing_class_name(func_node: Node, get_text: Callable[[Node], str]) -> str | None:
+    """Find enclosing class name for a method."""
+    current = func_node.parent
+    while current is not None:
+        if current.type in ("class_declaration", "class"):
+            return _get_class_type_identifier(current, get_text)
+        current = current.parent
+    return None
+
+
+class TypeScriptFunctionAnalyzer(TypeScriptBaseAnalyzer):
+    """Analyzes TypeScript AST to build CQSPattern objects for each function."""
+
+    def __init__(self) -> None:
+        """Initialize analyzer with input/output detectors."""
+        super().__init__()
+        self._function_extractor = TypeScriptFunctionExtractor()
+        self._input_detector = TypeScriptInputDetector()
+        self._output_detector = TypeScriptOutputDetector()
+
+    def analyze(self, root_node: Node, file_path: str, config: CQSConfig) -> list[CQSPattern]:
+        """Analyze TypeScript AST and return CQSPattern for each function."""
+        if not TREE_SITTER_AVAILABLE or root_node is None:
+            return []
+
+        functions = self._function_extractor.collect_all_functions(root_node)
+        functions = _filter_duplicate_functions(functions)
+
+        return [
+            self._analyze_function(func_node, func_name, file_path)
+            for func_node, func_name in functions
+            if not self._should_skip(func_node, func_name, config)
+        ]
+
+    def _should_skip(self, func_node: Node, func_name: str, config: CQSConfig) -> bool:
+        """Check if function should be skipped (ignored or fluent interface)."""
+        return self._is_ignored_method(
+            func_node, func_name, config
+        ) or self._is_fluent_interface_function(func_node, config)
+
+    def _is_ignored_method(self, func_node: Node, func_name: str, config: CQSConfig) -> bool:
+        """Check if method should be ignored based on config."""
+        if func_name in config.ignore_methods:
+            return True
+        if func_node.type != "method_definition":
+            return False
+        if not _is_constructor_method(func_node, self.extract_node_text):
+            return False
+        return "constructor" in config.ignore_methods or "__init__" in config.ignore_methods
+
+    def _is_fluent_interface_function(self, func_node: Node, config: CQSConfig) -> bool:
+        """Check if function uses fluent interface pattern."""
+        if not config.detect_fluent_interface:
+            return False
+        body_node = _find_function_body(func_node)
+        return body_node is not None and _ends_with_return_this(body_node)
+
+    def _analyze_function(self, func_node: Node, func_name: str, file_path: str) -> CQSPattern:
+        """Analyze a single function for CQS patterns."""
+        body_node = _find_function_body(func_node)
+        inputs, outputs = self._detect_operations(body_node)
+
+        return CQSPattern(
+            function_name=func_name,
+            line=func_node.start_point[0] + 1,
+            column=func_node.start_point[1],
+            file_path=file_path,
+            inputs=inputs,
+            outputs=outputs,
+            is_method=func_node.type == "method_definition",
+            is_async=_is_async_function(func_node, self.extract_node_text(func_node)),
+            class_name=_find_enclosing_class_name(func_node, self.extract_node_text),
+        )
+
+    def _detect_operations(
+        self, body_node: Node | None
+    ) -> tuple[list[InputOperation], list[OutputOperation]]:
+        """Detect INPUT and OUTPUT operations in function body."""
+        if body_node is None:
+            return [], []
+        return (
+            self._input_detector.find_inputs(body_node),
+            self._output_detector.find_outputs(body_node),
+        )

src/linters/cqs/typescript_input_detector.py

@@ -0,0 +1,203 @@
+"""
+Purpose: Tree-sitter based detector for INPUT (query) operations in TypeScript CQS analysis
+
+Scope: Detects assignment patterns where function call results are captured in TypeScript code
+
+Overview: Provides TypeScriptInputDetector class that uses tree-sitter AST traversal to find
+    INPUT operations in TypeScript code. INPUT operations are query-like assignments that
+    capture function call return values. Detects patterns including variable declarations
+    (const x = func(), let x = func()), destructuring (const { a, b } = func(),
+    const [a, b] = func()), await assignments (const x = await func()), and class field
+    assignments (this.x = func()). Uses tree-sitter node types lexical_declaration,
+    variable_declarator, assignment_expression, and call_expression for detection.
+
+Dependencies: tree-sitter via TypeScriptBaseAnalyzer
+
+Exports: TypeScriptInputDetector
+
+Interfaces: TypeScriptInputDetector.find_inputs(root_node) -> list[InputOperation]
+
+Implementation: Tree-sitter AST traversal with recursive node collection
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from src.analyzers.typescript_base import (
+    TREE_SITTER_AVAILABLE,
+    Node,
+    TypeScriptBaseAnalyzer,
+)
+
+from .types import InputOperation
+
+# Module-level helper functions for AST navigation
+
+
+def _find_child_by_type(node: Node, types: set[str]) -> Node | None:
+    """Find first child matching any of the given types."""
+    return next((child for child in node.children if child.type in types), None)
+
+
+def _find_children_after_token(node: Node, token: str) -> list[Node]:
+    """Get all children after a specific token."""
+    children = list(node.children)
+    for i, child in enumerate(children):
+        if child.type == token:
+            return children[i + 1 :]
+    return []
+
+
+def _find_after_token(node: Node, token: str, exclude_types: set[str] | None = None) -> Node | None:
+    """Find first child after a specific token, excluding certain types."""
+    exclude = exclude_types or set()
+    remaining = _find_children_after_token(node, token)
+    return next((c for c in remaining if c.type not in exclude), None)
+
+
+def _find_declarator_name(node: Node) -> Node | None:
+    """Find name/pattern node in variable declarator."""
+    return _find_child_by_type(node, {"identifier", "object_pattern", "array_pattern"})
+
+
+def _find_declarator_value(node: Node) -> Node | None:
+    """Find value node in variable declarator (after =)."""
+    return _find_after_token(node, "=", {":", "type_annotation"})
+
+
+def _find_assignment_left(node: Node) -> Node | None:
+    """Find left side of assignment expression."""
+    return _find_child_by_type(node, {"identifier", "member_expression", "subscript_expression"})
+
+
+def _find_assignment_right(node: Node) -> Node | None:
+    """Find right side of assignment expression (after =)."""
+    return _find_after_token(node, "=")
+
+
+def _extract_call_from_value(node: Node) -> Node | None:
+    """Extract call expression from value, handling await wrapper."""
+    if node.type == "call_expression":
+        return node
+    if node.type == "await_expression":
+        return next((c for c in node.children if c.type == "call_expression"), None)
+    return None
+
+
+def _find_pattern_value(pair_node: Node) -> Any:
+    """Find value identifier in pair pattern (e.g., a: b -> returns 'b')."""
+    children_after_colon = _find_children_after_token(pair_node, ":")
+    return next((c for c in children_after_colon if c.type == "identifier"), None)
+
+
+def _get_pattern_child_name(child: Node, get_text: Callable[[Node], str]) -> str | None:
+    """Extract name from an object pattern child node."""
+    if child.type == "shorthand_property_identifier_pattern":
+        return get_text(child)
+    if child.type == "pair_pattern":
+        value = _find_pattern_value(child)
+        return get_text(value) if value else None
+    return None
+
+
+def _extract_object_pattern_names(node: Node, get_text: Callable[[Node], str]) -> str:
+    """Extract names from object destructuring pattern."""
+    names = [
+        name
+        for child in node.children
+        if (name := _get_pattern_child_name(child, get_text)) is not None
+    ]
+    return ", ".join(names) if names else get_text(node)
+
+
+def _extract_array_pattern_names(node: Node, get_text: Callable[[Node], str]) -> str:
+    """Extract names from array destructuring pattern."""
+    names = [get_text(child) for child in node.children if child.type == "identifier"]
+    return ", ".join(names) if names else get_text(node)
+
+
+def _extract_target_name(name_node: Node, get_text: Callable[[Node], str]) -> str:
+    """Extract string representation of assignment target."""
+    if name_node.type == "identifier":
+        return get_text(name_node)
+    if name_node.type == "object_pattern":
+        return _extract_object_pattern_names(name_node, get_text)
+    if name_node.type == "array_pattern":
+        return _extract_array_pattern_names(name_node, get_text)
+    return get_text(name_node)
+
+
+class TypeScriptInputDetector(TypeScriptBaseAnalyzer):
+    """Detects INPUT (query) operations that capture function call results in TypeScript."""
+
+    def find_inputs(self, root_node: Node) -> list[InputOperation]:
+        """Find INPUT operations in TypeScript AST."""
+        if not TREE_SITTER_AVAILABLE or root_node is None:
+            return []
+        inputs: list[InputOperation] = []
+        self._find_inputs_recursive(root_node, inputs)
+        return inputs
+
+    def _find_inputs_recursive(self, node: Node, inputs: list[InputOperation]) -> None:
+        """Recursively find INPUT operations in AST."""
+        if node.type == "lexical_declaration":
+            self._check_lexical_declaration(node, inputs)
+        elif node.type == "assignment_expression":
+            self._check_assignment_expression(node, inputs)
+
+        for child in node.children:
+            self._find_inputs_recursive(child, inputs)
+
+    def _check_lexical_declaration(self, node: Node, inputs: list[InputOperation]) -> None:
+        """Check lexical declaration for INPUT patterns."""
+        for child in node.children:
+            if child.type == "variable_declarator":
+                self._check_variable_declarator(child, inputs)
+
+    def _check_variable_declarator(self, node: Node, inputs: list[InputOperation]) -> None:
+        """Check variable declarator for call expression assignment."""
+        name_node = _find_declarator_name(node)
+        value_node = _find_declarator_value(node)
+
+        if name_node is None or value_node is None:
+            return
+
+        call_node = _extract_call_from_value(value_node)
+        if call_node is None:
+            return
+
+        inputs.append(self._create_input_operation(node, name_node, call_node))
+
+    def _check_assignment_expression(self, node: Node, inputs: list[InputOperation]) -> None:
+        """Check assignment expression for INPUT pattern (this.x = func())."""
+        left_node = _find_assignment_left(node)
+        right_node = _find_assignment_right(node)
+
+        if left_node is None or right_node is None:
+            return
+
+        call_node = _extract_call_from_value(right_node)
+        if call_node is None:
+            return
+
+        target = self.extract_node_text(left_node)
+        expression = self.extract_node_text(call_node)
+        inputs.append(
+            InputOperation(
+                line=node.start_point[0] + 1,
+                column=node.start_point[1],
+                expression=expression,
+                target=target,
+            )
+        )
+
+    def _create_input_operation(
+        self, node: Node, name_node: Node, call_node: Node
+    ) -> InputOperation:
+        """Create an InputOperation from parsed nodes."""
+        return InputOperation(
+            line=node.start_point[0] + 1,
+            column=node.start_point[1],
+            expression=self.extract_node_text(call_node),
+            target=_extract_target_name(name_node, self.extract_node_text),
+        )

src/linters/cqs/typescript_output_detector.py

@@ -0,0 +1,117 @@
+"""
+Purpose: Tree-sitter based detector for OUTPUT (command) operations in TypeScript CQS analysis
+
+Scope: Detects statement-level calls where return values are discarded in TypeScript code
+
+Overview: Provides TypeScriptOutputDetector class that uses tree-sitter AST traversal to find
+    OUTPUT operations in TypeScript code. OUTPUT operations are command-like statement-level
+    function calls that discard return values. Detects patterns including statement calls
+    (func();), async statement calls (await func();), method calls (obj.method();), and
+    chained method calls (obj.method().method2();). Only expression_statement nodes containing
+    call_expression or await_expression are detected as OUTPUT. Naturally excludes return
+    statements, conditionals, assignments, and other constructs that use call results.
+
+Dependencies: tree-sitter via TypeScriptBaseAnalyzer
+
+Exports: TypeScriptOutputDetector
+
+Interfaces: TypeScriptOutputDetector.find_outputs(root_node) -> list[OutputOperation]
+
+Implementation: Tree-sitter AST traversal targeting expression_statement nodes
+"""
+
+from src.analyzers.typescript_base import (
+    TREE_SITTER_AVAILABLE,
+    Node,
+    TypeScriptBaseAnalyzer,
+)
+
+from .types import OutputOperation
+
+
+class TypeScriptOutputDetector(TypeScriptBaseAnalyzer):
+    """Detects OUTPUT (command) operations that discard function call results in TypeScript."""
+
+    def find_outputs(self, root_node: Node) -> list[OutputOperation]:
+        """Find OUTPUT operations in TypeScript AST.
+
+        Args:
+            root_node: Tree-sitter AST root node to analyze
+
+        Returns:
+            List of detected OutputOperation objects
+        """
+        if not TREE_SITTER_AVAILABLE or root_node is None:
+            return []
+
+        outputs: list[OutputOperation] = []
+        self._find_outputs_recursive(root_node, outputs)
+        return outputs
+
+    def _find_outputs_recursive(self, node: Node, outputs: list[OutputOperation]) -> None:
+        """Recursively find OUTPUT operations in AST.
+
+        Only expression_statement containing call_expression or await_expression
+        with call_expression are OUTPUT operations.
+
+        Args:
+            node: Current tree-sitter node
+            outputs: List to accumulate OutputOperation objects
+        """
+        if node.type == "expression_statement":
+            self._check_expression_statement(node, outputs)
+
+        # Recurse into children
+        for child in node.children:
+            self._find_outputs_recursive(child, outputs)
+
+    def _check_expression_statement(self, node: Node, outputs: list[OutputOperation]) -> None:
+        """Check expression statement for OUTPUT pattern.
+
+        Handles: func();, await func();, obj.method();
+
+        Args:
+            node: expression_statement node
+            outputs: List to append outputs to
+        """
+        call_node = self._find_call_in_expression(node)
+        if call_node is None:
+            return
+
+        expression = self.extract_node_text(call_node)
+        line = node.start_point[0] + 1
+        column = node.start_point[1]
+
+        outputs.append(OutputOperation(line=line, column=column, expression=expression))
+
+    def _find_call_in_expression(self, node: Node) -> Node | None:
+        """Find call expression in expression statement.
+
+        Handles direct calls and await expressions containing calls.
+
+        Args:
+            node: expression_statement node
+
+        Returns:
+            call_expression node or None
+        """
+        for child in node.children:
+            if child.type == "call_expression":
+                return child
+            if child.type == "await_expression":
+                return self._find_call_in_await(child)
+        return None
+
+    def _find_call_in_await(self, node: Node) -> Node | None:
+        """Find call expression inside await expression.
+
+        Args:
+            node: await_expression node
+
+        Returns:
+            call_expression node or None
+        """
+        for child in node.children:
+            if child.type == "call_expression":
+                return child
+        return None