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

src/linters/file_header/markdown_parser.py

@@ -0,0 +1,124 @@
+"""
+Purpose: Markdown YAML frontmatter extraction and parsing
+
+Scope: Markdown file header parsing from YAML frontmatter
+
+Overview: Extracts YAML frontmatter from Markdown files. Frontmatter must be at the
+    start of the file, enclosed in --- markers. Parses YAML content to extract
+    field values using PyYAML when available, falling back to regex parsing if not.
+    Handles both simple key-value pairs and complex YAML structures including lists.
+    Flattens nested structures into string representations for field validation.
+
+Dependencies: re module for frontmatter pattern matching, yaml module (optional) for parsing, logging module
+
+Exports: MarkdownHeaderParser class
+
+Interfaces: extract_header(code) -> str | None for frontmatter extraction,
+    parse_fields(header) -> dict[str, str] for field parsing
+
+Implementation: YAML frontmatter extraction with PyYAML parsing and regex fallback for robustness
+"""
+
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+
+class MarkdownHeaderParser:  # thailint: ignore[srp]
+    """Extracts and parses Markdown file headers from YAML frontmatter.
+
+    Method count (10) exceeds SRP guideline (8) because proper A-grade complexity
+    refactoring requires extracting small focused helper methods. Class maintains
+    single responsibility of YAML frontmatter parsing - all methods support this
+    core purpose through either PyYAML or simple regex parsing fallback.
+    """
+
+    # Pattern to match YAML frontmatter at start of file
+    FRONTMATTER_PATTERN = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
+
+    def extract_header(self, code: str) -> str | None:
+        """Extract YAML frontmatter from Markdown file."""
+        if not code or not code.strip():
+            return None
+
+        match = self.FRONTMATTER_PATTERN.match(code)
+        return match.group(1).strip() if match else None
+
+    def parse_fields(self, header: str) -> dict[str, str]:
+        """Parse YAML frontmatter into field dictionary."""
+        yaml_result = self._try_yaml_parse(header)
+        if yaml_result is not None:
+            return yaml_result
+
+        return self._parse_simple_yaml(header)
+
+    def _try_yaml_parse(self, header: str) -> dict[str, str] | None:
+        """Try to parse with PyYAML, returning None if unavailable or failed."""
+        try:
+            import yaml
+
+            data = yaml.safe_load(header)
+            if isinstance(data, dict):
+                return self._flatten_yaml_dict(data)
+        except ImportError:
+            logger.debug("PyYAML not available, using simple parser")
+        except Exception:  # noqa: BLE001
+            logger.debug("YAML parsing failed, falling back to simple parser")
+        return None
+
+    def _flatten_yaml_dict(self, data: dict) -> dict[str, str]:
+        """Convert YAML dict to string values."""
+        result: dict[str, str] = {}
+        for key, value in data.items():
+            result[str(key)] = self._convert_value(value)
+        return result
+
+    def _convert_value(self, value: object) -> str:
+        """Convert a single YAML value to string."""
+        if isinstance(value, list):
+            return ", ".join(str(v) for v in value)
+        if value is not None:
+            return str(value)
+        return ""
+
+    def _parse_simple_yaml(  # thailint: ignore[nesting,dry]
+        self, header: str
+    ) -> dict[str, str]:
+        """Simple regex-based YAML parsing fallback."""
+        fields: dict[str, str] = {}
+        current_field: str | None = None
+        current_value: list[str] = []
+
+        for line in header.split("\n"):
+            if self._is_field_start(line):
+                self._save_field(fields, current_field, current_value)
+                current_field, current_value = self._start_field(line)
+            elif current_field and line.strip():
+                current_value.append(self._process_continuation(line))
+
+        self._save_field(fields, current_field, current_value)
+        return fields
+
+    def _is_field_start(self, line: str) -> bool:
+        """Check if line starts a new field (not indented, has colon)."""
+        return not line.startswith(" ") and ":" in line
+
+    def _start_field(self, line: str) -> tuple[str, list[str]]:
+        """Parse field start and return field name and initial value."""
+        parts = line.split(":", 1)
+        field_name = parts[0].strip()
+        value = parts[1].strip() if len(parts) > 1 else ""
+        return field_name, [value] if value else []
+
+    def _process_continuation(self, line: str) -> str:
+        """Process a continuation line (list item or multiline value)."""
+        stripped = line.strip()
+        return stripped[2:] if stripped.startswith("- ") else stripped
+
+    def _save_field(
+        self, fields: dict[str, str], field_name: str | None, values: list[str]
+    ) -> None:
+        """Save field to dictionary if field name exists."""
+        if field_name:
+            fields[field_name] = "\n".join(values).strip()

src/linters/file_header/python_parser.py

@@ -1,29 +1,29 @@
 """
-File: src/linters/file_header/python_parser.py
 Purpose: Python docstring extraction and parsing for file headers
-Exports: PythonHeaderParser class
-Depends: Python ast module
-Implements: AST-based docstring extraction with field parsing
-Related: linter.py for parser usage, field_validator.py for field validation
 
-Overview:
-    Extracts module-level docstrings from Python files using AST parsing.
+Scope: Python file header parsing from module-level docstrings
+
+Overview: Extracts module-level docstrings from Python files using AST parsing.
     Parses structured header fields from docstring content and handles both
     well-formed and malformed headers. Provides field extraction and validation
-    support for FileHeaderRule.
+    support for FileHeaderRule. Uses ast.get_docstring() for reliable extraction
+    and gracefully handles syntax errors in source code.
+
+Dependencies: Python ast module for AST parsing, base_parser.BaseHeaderParser for field parsing
+
+Exports: PythonHeaderParser class
 
-Usage:
-    parser = PythonHeaderParser()
-    header = parser.extract_header(code)
-    fields = parser.parse_fields(header)
+Interfaces: extract_header(code) -> str | None for docstring extraction, parse_fields(header) inherited from base
 
-Notes: Uses ast.get_docstring() for reliable module-level docstring extraction
+Implementation: AST-based docstring extraction with syntax error handling
 """
 
 import ast
 
+from src.linters.file_header.base_parser import BaseHeaderParser
 
-class PythonHeaderParser:
+
+class PythonHeaderParser(BaseHeaderParser):
     """Extracts and parses Python file headers from docstrings."""
 
     def extract_header(self, code: str) -> str | None:
@@ -40,47 +40,3 @@ class PythonHeaderParser:
             return ast.get_docstring(tree)
         except SyntaxError:
             return None
-
-    def parse_fields(self, header: str) -> dict[str, str]:  # thailint: ignore[nesting]
-        """Parse structured fields from header text.
-
-        Args:
-            header: Header docstring text
-
-        Returns:
-            Dictionary mapping field_name -> field_value
-        """
-        fields: dict[str, str] = {}
-        current_field: str | None = None
-        current_value: list[str] = []
-
-        for line in header.split("\n"):
-            if self._is_new_field_line(line):
-                current_field = self._save_and_start_new_field(
-                    fields, current_field, current_value, line
-                )
-                current_value = [line.split(":", 1)[1].strip()]
-            elif current_field:
-                current_value.append(line.strip())
-
-        self._save_current_field(fields, current_field, current_value)
-        return fields
-
-    def _is_new_field_line(self, line: str) -> bool:
-        """Check if line starts a new field."""
-        return ":" in line and not line.startswith(" ")
-
-    def _save_and_start_new_field(
-        self, fields: dict[str, str], current_field: str | None, current_value: list[str], line: str
-    ) -> str:
-        """Save current field and start new one."""
-        if current_field:
-            fields[current_field] = "\n".join(current_value).strip()
-        return line.split(":", 1)[0].strip()
-
-    def _save_current_field(
-        self, fields: dict[str, str], current_field: str | None, current_value: list[str]
-    ) -> None:
-        """Save the last field."""
-        if current_field:
-            fields[current_field] = "\n".join(current_value).strip()

src/linters/file_header/typescript_parser.py

@@ -0,0 +1,73 @@
+"""
+Purpose: TypeScript/JavaScript JSDoc comment extraction and parsing
+
+Scope: TypeScript and JavaScript file header parsing from JSDoc comments
+
+Overview: Extracts JSDoc-style comments (/** ... */) from TypeScript and JavaScript files.
+    Parses structured header fields from JSDoc content and handles both single-line
+    and multi-line field values. Distinguishes JSDoc comments from regular block
+    comments (/* ... */) by requiring the double asterisk syntax. Cleans formatting
+    characters including leading asterisks from content lines.
+
+Dependencies: re module for regex-based JSDoc pattern matching, base_parser.BaseHeaderParser for field parsing
+
+Exports: TypeScriptHeaderParser class
+
+Interfaces: extract_header(code) -> str | None for JSDoc extraction, parse_fields(header) inherited from base
+
+Implementation: Regex-based JSDoc extraction with content cleaning and formatting removal
+"""
+
+import re
+
+from src.linters.file_header.base_parser import BaseHeaderParser
+
+
+class TypeScriptHeaderParser(BaseHeaderParser):
+    """Extracts and parses TypeScript/JavaScript file headers from JSDoc comments."""
+
+    # Pattern to match JSDoc comment at start of file (allowing whitespace before)
+    JSDOC_PATTERN = re.compile(r"^\s*/\*\*\s*(.*?)\s*\*/", re.DOTALL)
+
+    def extract_header(self, code: str) -> str | None:
+        """Extract JSDoc comment from TypeScript/JavaScript code.
+
+        Args:
+            code: TypeScript/JavaScript source code
+
+        Returns:
+            JSDoc content or None if not found
+        """
+        if not code or not code.strip():
+            return None
+
+        match = self.JSDOC_PATTERN.match(code)
+        if not match:
+            return None
+
+        # Extract the content inside the JSDoc
+        jsdoc_content = match.group(1)
+
+        # Clean up the JSDoc content - remove leading * from each line
+        return self._clean_jsdoc_content(jsdoc_content)
+
+    def _clean_jsdoc_content(self, content: str) -> str:
+        """Remove JSDoc formatting (leading asterisks) from content.
+
+        Args:
+            content: Raw JSDoc content
+
+        Returns:
+            Cleaned content without leading asterisks
+        """
+        lines = content.split("\n")
+        cleaned_lines = []
+
+        for line in lines:
+            # Remove leading whitespace and asterisk
+            stripped = line.strip()
+            if stripped.startswith("*"):
+                stripped = stripped[1:].strip()
+            cleaned_lines.append(stripped)
+
+        return "\n".join(cleaned_lines)

src/linters/file_header/violation_builder.py

@@ -1,21 +1,22 @@
 """
-File: src/linters/file_header/violation_builder.py
 Purpose: Builds violation messages for file header linter
-Exports: ViolationBuilder class
-Depends: Violation type from core
-Implements: Message templates with context-specific details
-Related: linter.py for builder usage, atemporal_detector.py for temporal violations
 
-Overview:
-    Creates formatted violation messages for file header validation failures.
+Scope: Violation message creation for file header validation failures
+
+Overview: Creates formatted violation messages for file header validation failures.
     Handles missing fields, atemporal language, and other header issues with clear,
-    actionable messages. Provides consistent violation format across all validation types.
+    actionable messages. Provides consistent violation format across all validation types
+    including rule_id, message, location, severity, and helpful suggestions. Supports
+    multiple violation types with appropriate error messages and remediation guidance.
+
+Dependencies: Violation and Severity types from core.types module
+
+Exports: ViolationBuilder class
 
-Usage:
-    builder = ViolationBuilder("file-header.validation")
-    violation = builder.build_missing_field("Purpose", "test.py", 1)
+Interfaces: build_missing_field(field_name, file_path, line) -> Violation,
+    build_atemporal_violation(pattern, description, file_path, line) -> Violation
 
-Notes: Follows standard violation format with rule_id, message, location, severity, suggestion
+Implementation: Builder pattern with message templates for different violation types
 """
 
 from src.core.types import Severity, Violation

src/linters/file_placement/linter.py

@@ -6,22 +6,20 @@ Scope: Validate file organization against allow/deny patterns
 Overview: Implements file placement validation using regex patterns from JSON/YAML config.
     Orchestrates configuration loading, pattern validation, path resolution, rule checking,
     and violation creation through focused helper classes. Supports directory-specific rules,
-    global patterns, and generates helpful suggestions. Main linter class acts as coordinator.
+    global patterns, and generates helpful suggestions. Main linter class acts as coordinator
+    using composition pattern with specialized helper classes for configuration loading,
+    path resolution, pattern matching, and violation creation.
 
-Dependencies: src.core (base classes, types), pathlib, typing
+Dependencies: src.core (base classes, types), pathlib, typing, json, yaml modules
 
 Exports: FilePlacementLinter, FilePlacementRule
 
-Implementation: Composition pattern with helper classes for each responsibility
+Interfaces: lint_path(file_path) -> list[Violation], check_file_allowed(file_path) -> bool,
+    lint_directory(dir_path) -> list[Violation]
 
-SRP Exception: FilePlacementRule has 13 methods (exceeds max 8)
-    Justification: Framework adapter class that bridges BaseLintRule interface with
-    FilePlacementLinter implementation. Must handle multiple config sources (metadata vs file),
-    multiple config formats (wrapped vs unwrapped), project root detection with fallbacks,
-    and linter caching. This complexity is inherent to adapter pattern - splitting would
-    create unnecessary indirection between framework and implementation without improving
-    maintainability. All methods are focused on the single responsibility of integrating
-    file placement validation with the linting framework.
+Implementation: Composition pattern with helper classes for each responsibility
+    (ConfigLoader, PathResolver, PatternMatcher, PatternValidator, RuleChecker,
+    ViolationFactory)
 """
 
 import json

src/linters/print_statements/config.py

@@ -1,16 +1,7 @@
 """
-File: src/linters/print_statements/config.py
-
 Purpose: Configuration schema for print statements linter
 
-Exports: PrintStatementConfig dataclass
-
-Depends: dataclasses, typing
-
-Implements: PrintStatementConfig(enabled, ignore, allow_in_scripts, console_methods),
-    from_dict class method for loading configuration from dictionary
-
-Related: src/linters/magic_numbers/config.py, src/core/types.py
+Scope: Print statements linter configuration for all supported languages
 
 Overview: Defines configuration schema for print statements linter. Provides PrintStatementConfig
     dataclass with enabled flag, ignore patterns list, allow_in_scripts setting (default True to
@@ -19,9 +10,13 @@ Overview: Defines configuration schema for print statements linter. Provides Pri
     per-directory config overrides through from_dict class method. Integrates with orchestrator's
     configuration system to allow users to customize detection via .thailint.yaml configuration.
 
-Usage: config = PrintStatementConfig.from_dict(yaml_config, language="python")
+Dependencies: dataclasses module for configuration structure, typing module for type hints
+
+Exports: PrintStatementConfig dataclass
+
+Interfaces: from_dict(config, language) -> PrintStatementConfig for configuration loading from dictionary
 
-Notes: Dataclass with defaults matching common use cases, language-specific override support
+Implementation: Dataclass with defaults matching common use cases and language-specific override support
 """
 
 from dataclasses import dataclass, field

src/linters/print_statements/linter.py

@@ -1,28 +1,26 @@
 """
-File: src/linters/print_statements/linter.py
-
 Purpose: Main print statements linter rule implementation
 
-Exports: PrintStatementRule class
-
-Depends: BaseLintContext, MultiLanguageLintRule, PythonPrintStatementAnalyzer,
-    TypeScriptPrintStatementAnalyzer, ViolationBuilder, PrintStatementConfig, IgnoreDirectiveParser
-
-Implements: PrintStatementRule.check(context) -> list[Violation], properties for rule metadata
+Scope: Print and console statement detection for Python, TypeScript, and JavaScript files
 
-Related: src/linters/magic_numbers/linter.py, src/core/base.py
-
-Overview: Implements print statements linter rule following BaseLintRule interface. Orchestrates
+Overview: Implements print statements linter rule following MultiLanguageLintRule interface. Orchestrates
     configuration loading, Python AST analysis for print() calls, TypeScript tree-sitter analysis
     for console.* calls, and violation building through focused helper classes. Detects print and
     console statements that should be replaced with proper logging. Supports configurable
     allow_in_scripts option to permit print() in __main__ blocks and configurable console_methods
-    set for TypeScript/JavaScript. Handles ignore directives for suppressing specific violations.
+    set for TypeScript/JavaScript. Handles ignore directives for suppressing specific violations
+    through inline comments and configuration patterns.
+
+Dependencies: BaseLintContext and MultiLanguageLintRule from core, ast module, pathlib,
+    analyzer classes, config classes
+
+Exports: PrintStatementRule class implementing MultiLanguageLintRule interface
 
-Usage: rule = PrintStatementRule()
-    violations = rule.check(context)
+Interfaces: check(context) -> list[Violation] for rule validation, standard rule properties
+    (rule_id, rule_name, description)
 
-Notes: Composition pattern with helper classes, AST-based analysis for Python, tree-sitter for TS/JS
+Implementation: Composition pattern with helper classes (analyzers, violation builder),
+    AST-based analysis for Python, tree-sitter for TypeScript/JavaScript
 """
 
 import ast

src/linters/print_statements/python_analyzer.py

@@ -1,28 +1,22 @@
 """
-File: src/linters/print_statements/python_analyzer.py
-
 Purpose: Python AST analysis for finding print() call nodes
 
-Exports: PythonPrintStatementAnalyzer class
-
-Depends: ast module for AST parsing and node types
-
-Implements: PythonPrintStatementAnalyzer.find_print_calls(tree) -> list[tuple],
-    PythonPrintStatementAnalyzer.is_in_main_block(node) -> bool
-
-Related: src/linters/magic_numbers/python_analyzer.py
+Scope: Python print() statement detection and __main__ block context analysis
 
 Overview: Provides PythonPrintStatementAnalyzer class that traverses Python AST to find all
     print() function calls. Uses ast.walk() to traverse the syntax tree and collect
     Call nodes where the function is 'print'. Tracks parent nodes to detect if print calls
     are within __main__ blocks (if __name__ == "__main__":) for allow_in_scripts filtering.
     Returns structured data about each print call including the AST node, parent context,
-    and line number for violation reporting.
+    and line number for violation reporting. Handles both simple print() and builtins.print() calls.
+
+Dependencies: ast module for AST parsing and node types
+
+Exports: PythonPrintStatementAnalyzer class
 
-Usage: analyzer = PythonPrintStatementAnalyzer()
-    print_calls = analyzer.find_print_calls(ast.parse(code))
+Interfaces: find_print_calls(tree) -> list[tuple[Call, AST | None, int]], is_in_main_block(node) -> bool
 
-Notes: AST walk pattern with parent tracking for context detection
+Implementation: AST walk pattern with parent map for context detection and __main__ block identification
 """
 
 import ast

src/linters/print_statements/typescript_analyzer.py

@@ -1,28 +1,23 @@
 """
-File: src/linters/print_statements/typescript_analyzer.py
-
 Purpose: TypeScript/JavaScript console.* call detection using Tree-sitter AST analysis
 
-Exports: TypeScriptPrintStatementAnalyzer class
-
-Depends: TypeScriptBaseAnalyzer for tree-sitter parsing, tree-sitter Node type
-
-Implements: find_console_calls(root_node, methods) -> list[tuple]
-
-Related: src/linters/magic_numbers/typescript_analyzer.py, src/analyzers/typescript_base.py
+Scope: TypeScript and JavaScript console statement detection
 
 Overview: Analyzes TypeScript and JavaScript code to detect console.* method calls that should
     be replaced with proper logging. Uses Tree-sitter parser to traverse TypeScript/JavaScript
     AST and identify call expressions where the callee is console.log, console.warn, console.error,
     console.debug, or console.info (configurable). Returns structured data with the node, method
     name, and line number for each detected console call. Supports both TypeScript and JavaScript
-    files with shared detection logic.
+    files with shared detection logic. Handles member expression pattern matching to identify
+    console object method calls.
+
+Dependencies: TypeScriptBaseAnalyzer for tree-sitter parsing infrastructure, tree-sitter Node type, logging module
+
+Exports: TypeScriptPrintStatementAnalyzer class
 
-Usage: analyzer = TypeScriptPrintStatementAnalyzer()
-    root = analyzer.parse_typescript(code)
-    calls = analyzer.find_console_calls(root, {"log", "warn", "error"})
+Interfaces: find_console_calls(root_node, methods) -> list[tuple[Node, str, int]]
 
-Notes: Tree-sitter node traversal with call_expression and member_expression pattern matching
+Implementation: Tree-sitter node traversal with call_expression and member_expression pattern matching
 """
 
 import logging

src/linters/print_statements/violation_builder.py

@@ -1,27 +1,25 @@
 """
-File: src/linters/print_statements/violation_builder.py
-
 Purpose: Builds Violation objects for print statement detection
 
-Exports: ViolationBuilder class
-
-Depends: ast, pathlib.Path, src.core.types.Violation
-
-Implements: ViolationBuilder.create_python_violation(node, line, file_path) -> Violation,
-    ViolationBuilder.create_typescript_violation(method, line, file_path) -> Violation
-
-Related: src/linters/magic_numbers/violation_builder.py, src/core/types.py
+Scope: Violation creation for print and console statement detections
 
 Overview: Provides ViolationBuilder class that creates Violation objects for print statement
     detections. Generates descriptive messages suggesting the use of proper logging instead of
     print/console statements. Constructs complete Violation instances with rule_id, file_path,
     line number, column, message, and suggestions. Provides separate methods for Python print()
-    violations and TypeScript/JavaScript console.* violations with language-appropriate messages.
+    violations and TypeScript/JavaScript console.* violations with language-appropriate messages
+    and helpful remediation guidance.
+
+Dependencies: ast module for Python AST nodes, pathlib.Path for file paths,
+    src.core.types.Violation for violation structure
+
+Exports: ViolationBuilder class
 
-Usage: builder = ViolationBuilder("print-statements.detected")
-    violation = builder.create_python_violation(node, line, file_path)
+Interfaces: create_python_violation(node, line, file_path) -> Violation,
+    create_typescript_violation(method, line, file_path) -> Violation
 
-Notes: Message templates suggest logging as alternative, consistent with other linter patterns
+Implementation: Builder pattern with message templates suggesting logging as alternative
+    to print/console statements
 """
 
 import ast