thailint 0.4.2__py3-none-any.whl → 0.4.4__py3-none-any.whl

src/cli.py

@@ -59,12 +59,145 @@ def setup_logging(verbose: bool = False):
     )
 
 
+def _determine_project_root(
+    explicit_root: str | None, config_path: str | None, verbose: bool
+) -> Path:
+    """Determine project root with precedence rules.
+
+    Precedence order:
+    1. Explicit --project-root (highest priority)
+    2. Inferred from --config path directory
+    3. Auto-detection via get_project_root() (fallback)
+
+    Args:
+        explicit_root: Explicitly specified project root path (from --project-root)
+        config_path: Config file path (from --config)
+        verbose: Whether verbose logging is enabled
+
+    Returns:
+        Path to determined project root
+
+    Raises:
+        SystemExit: If explicit_root doesn't exist or is not a directory
+    """
+    from src.utils.project_root import get_project_root
+
+    # Priority 1: Explicit --project-root
+    if explicit_root:
+        return _resolve_explicit_project_root(explicit_root, verbose)
+
+    # Priority 2: Infer from --config path
+    if config_path:
+        return _infer_root_from_config(config_path, verbose)
+
+    # Priority 3: Auto-detection (fallback)
+    return _autodetect_project_root(verbose, get_project_root)
+
+
+def _resolve_explicit_project_root(explicit_root: str, verbose: bool) -> Path:
+    """Resolve and validate explicitly specified project root.
+
+    Args:
+        explicit_root: Explicitly specified project root path
+        verbose: Whether verbose logging is enabled
+
+    Returns:
+        Resolved project root path
+
+    Raises:
+        SystemExit: If explicit_root doesn't exist or is not a directory
+    """
+    root = Path(explicit_root)
+    # Check existence before resolving to handle relative paths in test environments
+    if not root.exists():
+        click.echo(f"Error: Project root does not exist: {explicit_root}", err=True)
+        sys.exit(2)
+    if not root.is_dir():
+        click.echo(f"Error: Project root must be a directory: {explicit_root}", err=True)
+        sys.exit(2)
+
+    # Now resolve after validation
+    root = root.resolve()
+
+    if verbose:
+        logger.debug(f"Using explicit project root: {root}")
+    return root
+
+
+def _infer_root_from_config(config_path: str, verbose: bool) -> Path:
+    """Infer project root from config file path.
+
+    Args:
+        config_path: Config file path
+        verbose: Whether verbose logging is enabled
+
+    Returns:
+        Inferred project root (parent directory of config file)
+    """
+    config_file = Path(config_path).resolve()
+    inferred_root = config_file.parent
+
+    if verbose:
+        logger.debug(f"Inferred project root from config path: {inferred_root}")
+    return inferred_root
+
+
+def _autodetect_project_root(verbose: bool, get_project_root) -> Path:
+    """Auto-detect project root using project root detection.
+
+    Args:
+        verbose: Whether verbose logging is enabled
+        get_project_root: Function to detect project root
+
+    Returns:
+        Auto-detected project root
+    """
+    auto_root = get_project_root(None)
+    if verbose:
+        logger.debug(f"Auto-detected project root: {auto_root}")
+    return auto_root
+
+
+def _get_project_root_from_context(ctx) -> Path:
+    """Get or determine project root from Click context.
+
+    This function defers the actual determination until needed to avoid
+    importing pyprojroot in test environments where it may not be available.
+
+    Args:
+        ctx: Click context containing CLI options
+
+    Returns:
+        Path to determined project root
+    """
+    # Check if already determined and cached
+    if "project_root" in ctx.obj:
+        return ctx.obj["project_root"]
+
+    # Determine project root using stored CLI options
+    explicit_root = ctx.obj.get("cli_project_root")
+    config_path = ctx.obj.get("cli_config_path")
+    verbose = ctx.obj.get("verbose", False)
+
+    project_root = _determine_project_root(explicit_root, config_path, verbose)
+
+    # Cache for future use
+    ctx.obj["project_root"] = project_root
+
+    return project_root
+
+
 @click.group()
 @click.version_option(version=__version__)
 @click.option("--verbose", "-v", is_flag=True, help="Enable verbose output")
 @click.option("--config", "-c", type=click.Path(), help="Path to config file")
+@click.option(
+    "--project-root",
+    type=click.Path(),
+    help="Explicitly specify project root directory (overrides auto-detection)",
+)
 @click.pass_context
-def cli(ctx, verbose: bool, config: str | None):
+def cli(ctx, verbose: bool, config: str | None, project_root: str | None):
     """
     thai-lint - AI code linter and governance tool
 
@@ -85,6 +218,10 @@ def cli(ctx, verbose: bool, config: str | None):
         # Lint with custom config
         thai-lint file-placement --config .thailint.yaml src/
 
+        \b
+        # Specify project root explicitly (useful in Docker)
+        thai-lint --project-root /workspace/root magic-numbers backend/
+
         \b
         # Get JSON output
         thai-lint file-placement --format json .
@@ -99,6 +236,11 @@ def cli(ctx, verbose: bool, config: str | None):
     # Setup logging
     setup_logging(verbose)
 
+    # Store CLI options for later project root determination
+    # (deferred to avoid pyprojroot import issues in test environments)
+    ctx.obj["cli_project_root"] = project_root
+    ctx.obj["cli_config_path"] = config
+
     # Load configuration
     try:
         if config:
@@ -551,6 +693,7 @@ def file_placement(  # pylint: disable=too-many-arguments,too-many-positional-ar
         thai-lint file-placement --rules '{"allow": [".*\\.py$"]}' .
     """
     verbose = ctx.obj.get("verbose", False)
+    project_root = _get_project_root_from_context(ctx)
 
     if not paths:
         paths = (".",)
@@ -558,17 +701,19 @@ def file_placement(  # pylint: disable=too-many-arguments,too-many-positional-ar
     path_objs = [Path(p) for p in paths]
 
     try:
-        _execute_file_placement_lint(path_objs, config_file, rules, format, recursive, verbose)
+        _execute_file_placement_lint(
+            path_objs, config_file, rules, format, recursive, verbose, project_root
+        )
     except Exception as e:
         _handle_linting_error(e, verbose)
 
 
 def _execute_file_placement_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments
-    path_objs, config_file, rules, format, recursive, verbose
+    path_objs, config_file, rules, format, recursive, verbose, project_root=None
 ):
     """Execute file placement linting."""
     _validate_paths_exist(path_objs)
-    orchestrator = _setup_orchestrator(path_objs, config_file, rules, verbose)
+    orchestrator = _setup_orchestrator(path_objs, config_file, rules, verbose, project_root)
     all_violations = _execute_linting_on_paths(orchestrator, path_objs, recursive)
 
     # Filter to only file-placement violations
@@ -627,26 +772,55 @@ def _find_project_root(start_path: Path) -> Path:
     return get_project_root(start_path)
 
 
-def _setup_orchestrator(path_objs, config_file, rules, verbose):
+def _setup_orchestrator(path_objs, config_file, rules, verbose, project_root=None):
     """Set up and configure the orchestrator."""
     from src.orchestrator.core import Orchestrator
     from src.utils.project_root import get_project_root
 
+    # Use provided project_root or fall back to auto-detection
+    project_root = _get_or_detect_project_root(path_objs, project_root, get_project_root)
+
+    orchestrator = Orchestrator(project_root=project_root)
+    _apply_orchestrator_config(orchestrator, config_file, rules, verbose)
+
+    return orchestrator
+
+
+def _get_or_detect_project_root(path_objs, project_root, get_project_root):
+    """Get provided project root or auto-detect from paths.
+
+    Args:
+        path_objs: List of path objects
+        project_root: Optionally provided project root
+        get_project_root: Function to detect project root
+
+    Returns:
+        Project root path
+    """
+    if project_root is not None:
+        return project_root
+
     # Find actual project root (where .git or pyproject.toml exists)
     # This ensures .artifacts/ is always created at project root, not in subdirectories
     first_path = path_objs[0] if path_objs else Path.cwd()
     search_start = first_path if first_path.is_dir() else first_path.parent
-    project_root = get_project_root(search_start)
+    return get_project_root(search_start)
 
-    orchestrator = Orchestrator(project_root=project_root)
 
+def _apply_orchestrator_config(orchestrator, config_file, rules, verbose):
+    """Apply configuration to orchestrator.
+
+    Args:
+        orchestrator: Orchestrator instance
+        config_file: Path to config file (optional)
+        rules: Inline JSON rules (optional)
+        verbose: Whether verbose logging is enabled
+    """
     if rules:
         _apply_inline_rules(orchestrator, rules, verbose)
     elif config_file:
         _load_config_file(orchestrator, config_file, verbose)
 
-    return orchestrator
-
 
 def _apply_inline_rules(orchestrator, rules, verbose):
     """Parse and apply inline JSON rules."""
@@ -759,13 +933,18 @@ def _execute_linting_on_paths(orchestrator, path_objs: list[Path], recursive: bo
     return violations
 
 
-def _setup_nesting_orchestrator(path_objs: list[Path], config_file: str | None, verbose: bool):
+def _setup_nesting_orchestrator(
+    path_objs: list[Path], config_file: str | None, verbose: bool, project_root: Path | None = None
+):
     """Set up orchestrator for nesting command."""
-    # Use first path to determine project root
-    first_path = path_objs[0] if path_objs else Path.cwd()
-    project_root = first_path if first_path.is_dir() else first_path.parent
-
     from src.orchestrator.core import Orchestrator
+    from src.utils.project_root import get_project_root
+
+    # Use provided project_root or fall back to auto-detection
+    if project_root is None:
+        first_path = path_objs[0] if path_objs else Path.cwd()
+        search_start = first_path if first_path.is_dir() else first_path.parent
+        project_root = get_project_root(search_start)
 
     orchestrator = Orchestrator(project_root=project_root)
 
@@ -780,14 +959,34 @@ def _apply_nesting_config_override(orchestrator, max_depth: int | None, verbose:
     if max_depth is None:
         return
 
+    # Ensure nesting config exists
     if "nesting" not in orchestrator.config:
         orchestrator.config["nesting"] = {}
-    orchestrator.config["nesting"]["max_nesting_depth"] = max_depth
+
+    nesting_config = orchestrator.config["nesting"]
+
+    # Set top-level max_nesting_depth
+    nesting_config["max_nesting_depth"] = max_depth
+
+    # Override language-specific configs to ensure CLI option takes precedence
+    _override_language_specific_nesting(nesting_config, max_depth)
 
     if verbose:
         logger.debug(f"Overriding max_nesting_depth to {max_depth}")
 
 
+def _override_language_specific_nesting(nesting_config: dict, max_depth: int):
+    """Override language-specific nesting depth configs.
+
+    Args:
+        nesting_config: Nesting configuration dictionary
+        max_depth: Maximum nesting depth to set
+    """
+    for lang in ["python", "typescript", "javascript"]:
+        if lang in nesting_config:
+            nesting_config[lang]["max_nesting_depth"] = max_depth
+
+
 def _run_nesting_lint(orchestrator, path_objs: list[Path], recursive: bool):
     """Execute nesting lint on files or directories."""
     all_violations = _execute_linting_on_paths(orchestrator, path_objs, recursive)
@@ -851,6 +1050,7 @@ def nesting(  # pylint: disable=too-many-arguments,too-many-positional-arguments
         thai-lint nesting --config .thailint.yaml src/
     """
     verbose = ctx.obj.get("verbose", False)
+    project_root = _get_project_root_from_context(ctx)
 
     # Default to current directory if no paths provided
     if not paths:
@@ -859,17 +1059,19 @@ def nesting(  # pylint: disable=too-many-arguments,too-many-positional-arguments
     path_objs = [Path(p) for p in paths]
 
     try:
-        _execute_nesting_lint(path_objs, config_file, format, max_depth, recursive, verbose)
+        _execute_nesting_lint(
+            path_objs, config_file, format, max_depth, recursive, verbose, project_root
+        )
     except Exception as e:
         _handle_linting_error(e, verbose)
 
 
 def _execute_nesting_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments
-    path_objs, config_file, format, max_depth, recursive, verbose
+    path_objs, config_file, format, max_depth, recursive, verbose, project_root=None
 ):
     """Execute nesting lint."""
     _validate_paths_exist(path_objs)
-    orchestrator = _setup_nesting_orchestrator(path_objs, config_file, verbose)
+    orchestrator = _setup_nesting_orchestrator(path_objs, config_file, verbose, project_root)
     _apply_nesting_config_override(orchestrator, max_depth, verbose)
     nesting_violations = _run_nesting_lint(orchestrator, path_objs, recursive)
 
@@ -880,12 +1082,18 @@ def _execute_nesting_lint(  # pylint: disable=too-many-arguments,too-many-positi
     sys.exit(1 if nesting_violations else 0)
 
 
-def _setup_srp_orchestrator(path_objs: list[Path], config_file: str | None, verbose: bool):
+def _setup_srp_orchestrator(
+    path_objs: list[Path], config_file: str | None, verbose: bool, project_root: Path | None = None
+):
     """Set up orchestrator for SRP command."""
-    first_path = path_objs[0] if path_objs else Path.cwd()
-    project_root = first_path if first_path.is_dir() else first_path.parent
-
     from src.orchestrator.core import Orchestrator
+    from src.utils.project_root import get_project_root
+
+    # Use provided project_root or fall back to auto-detection
+    if project_root is None:
+        first_path = path_objs[0] if path_objs else Path.cwd()
+        search_start = first_path if first_path.is_dir() else first_path.parent
+        project_root = get_project_root(search_start)
 
     orchestrator = Orchestrator(project_root=project_root)
 
@@ -988,6 +1196,7 @@ def srp(  # pylint: disable=too-many-arguments,too-many-positional-arguments
         thai-lint srp --config .thailint.yaml src/
     """
     verbose = ctx.obj.get("verbose", False)
+    project_root = _get_project_root_from_context(ctx)
 
     if not paths:
         paths = (".",)
@@ -995,17 +1204,19 @@ def srp(  # pylint: disable=too-many-arguments,too-many-positional-arguments
     path_objs = [Path(p) for p in paths]
 
     try:
-        _execute_srp_lint(path_objs, config_file, format, max_methods, max_loc, recursive, verbose)
+        _execute_srp_lint(
+            path_objs, config_file, format, max_methods, max_loc, recursive, verbose, project_root
+        )
     except Exception as e:
         _handle_linting_error(e, verbose)
 
 
 def _execute_srp_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments
-    path_objs, config_file, format, max_methods, max_loc, recursive, verbose
+    path_objs, config_file, format, max_methods, max_loc, recursive, verbose, project_root=None
 ):
     """Execute SRP lint."""
     _validate_paths_exist(path_objs)
-    orchestrator = _setup_srp_orchestrator(path_objs, config_file, verbose)
+    orchestrator = _setup_srp_orchestrator(path_objs, config_file, verbose, project_root)
     _apply_srp_config_override(orchestrator, max_methods, max_loc, verbose)
     srp_violations = _run_srp_lint(orchestrator, path_objs, recursive)
 
@@ -1085,6 +1296,7 @@ def dry(  # pylint: disable=too-many-arguments,too-many-positional-arguments
         thai-lint dry --format json .
     """
     verbose = ctx.obj.get("verbose", False)
+    project_root = _get_project_root_from_context(ctx)
 
     if not paths:
         paths = (".",)
@@ -1093,18 +1305,34 @@ def dry(  # pylint: disable=too-many-arguments,too-many-positional-arguments
 
     try:
         _execute_dry_lint(
-            path_objs, config_file, format, min_lines, no_cache, clear_cache, recursive, verbose
+            path_objs,
+            config_file,
+            format,
+            min_lines,
+            no_cache,
+            clear_cache,
+            recursive,
+            verbose,
+            project_root,
         )
     except Exception as e:
         _handle_linting_error(e, verbose)
 
 
 def _execute_dry_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments
-    path_objs, config_file, format, min_lines, no_cache, clear_cache, recursive, verbose
+    path_objs,
+    config_file,
+    format,
+    min_lines,
+    no_cache,
+    clear_cache,
+    recursive,
+    verbose,
+    project_root=None,
 ):
     """Execute DRY linting."""
     _validate_paths_exist(path_objs)
-    orchestrator = _setup_dry_orchestrator(path_objs, config_file, verbose)
+    orchestrator = _setup_dry_orchestrator(path_objs, config_file, verbose, project_root)
     _apply_dry_config_override(orchestrator, min_lines, no_cache, verbose)
 
     if clear_cache:
@@ -1119,14 +1347,16 @@ def _execute_dry_lint(  # pylint: disable=too-many-arguments,too-many-positional
     sys.exit(1 if dry_violations else 0)
 
 
-def _setup_dry_orchestrator(path_objs, config_file, verbose):
+def _setup_dry_orchestrator(path_objs, config_file, verbose, project_root=None):
     """Set up orchestrator for DRY linting."""
     from src.orchestrator.core import Orchestrator
     from src.utils.project_root import get_project_root
 
-    first_path = path_objs[0] if path_objs else Path.cwd()
-    search_start = first_path if first_path.is_dir() else first_path.parent
-    project_root = get_project_root(search_start)
+    # Use provided project_root or fall back to auto-detection
+    if project_root is None:
+        first_path = path_objs[0] if path_objs else Path.cwd()
+        search_start = first_path if first_path.is_dir() else first_path.parent
+        project_root = get_project_root(search_start)
 
     orchestrator = Orchestrator(project_root=project_root)
 
@@ -1213,16 +1443,18 @@ def _run_dry_lint(orchestrator, path_objs, recursive):
 
 
 def _setup_magic_numbers_orchestrator(
-    path_objs: list[Path], config_file: str | None, verbose: bool
+    path_objs: list[Path], config_file: str | None, verbose: bool, project_root: Path | None = None
 ):
     """Set up orchestrator for magic-numbers command."""
     from src.orchestrator.core import Orchestrator
     from src.utils.project_root import get_project_root
 
-    # Find actual project root (where .git or .thailint.yaml exists)
-    first_path = path_objs[0] if path_objs else Path.cwd()
-    search_start = first_path if first_path.is_dir() else first_path.parent
-    project_root = get_project_root(search_start)
+    # Use provided project_root or fall back to auto-detection
+    if project_root is None:
+        # Find actual project root (where .git or .thailint.yaml exists)
+        first_path = path_objs[0] if path_objs else Path.cwd()
+        search_start = first_path if first_path.is_dir() else first_path.parent
+        project_root = get_project_root(search_start)
 
     orchestrator = Orchestrator(project_root=project_root)
 
@@ -1289,6 +1521,7 @@ def magic_numbers(  # pylint: disable=too-many-arguments,too-many-positional-arg
         thai-lint magic-numbers --config .thailint.yaml src/
     """
     verbose = ctx.obj.get("verbose", False)
+    project_root = _get_project_root_from_context(ctx)
 
     if not paths:
         paths = (".",)
@@ -1296,17 +1529,19 @@ def magic_numbers(  # pylint: disable=too-many-arguments,too-many-positional-arg
     path_objs = [Path(p) for p in paths]
 
     try:
-        _execute_magic_numbers_lint(path_objs, config_file, format, recursive, verbose)
+        _execute_magic_numbers_lint(
+            path_objs, config_file, format, recursive, verbose, project_root
+        )
     except Exception as e:
         _handle_linting_error(e, verbose)
 
 
 def _execute_magic_numbers_lint(  # pylint: disable=too-many-arguments,too-many-positional-arguments
-    path_objs, config_file, format, recursive, verbose
+    path_objs, config_file, format, recursive, verbose, project_root=None
 ):
     """Execute magic-numbers lint."""
     _validate_paths_exist(path_objs)
-    orchestrator = _setup_magic_numbers_orchestrator(path_objs, config_file, verbose)
+    orchestrator = _setup_magic_numbers_orchestrator(path_objs, config_file, verbose, project_root)
     magic_numbers_violations = _run_magic_numbers_lint(orchestrator, path_objs, recursive)
 
     if verbose:

src/linters/dry/python_analyzer.py

@@ -62,6 +62,9 @@ class PythonDuplicateAnalyzer(BaseTokenAnalyzer):  # thailint: ignore[srp.violat
         """
         super().__init__()
         self._filter_registry = filter_registry or create_default_registry()
+        # Performance optimization: Cache parsed AST to avoid re-parsing for each hash window
+        self._cached_ast: ast.Module | None = None
+        self._cached_content: str | None = None
 
     def analyze(self, file_path: Path, content: str, config: DRYConfig) -> list[CodeBlock]:
         """Analyze Python file for duplicate code blocks, excluding docstrings.
@@ -74,37 +77,46 @@ class PythonDuplicateAnalyzer(BaseTokenAnalyzer):  # thailint: ignore[srp.violat
         Returns:
             List of CodeBlock instances with hash values
         """
-        # Get docstring line ranges
-        docstring_ranges = self._get_docstring_ranges_from_content(content)
+        # Performance optimization: Parse AST once and cache for _is_single_statement_in_source() calls
+        self._cached_ast = self._parse_content_safe(content)
+        self._cached_content = content
 
-        # Tokenize with line number tracking
-        lines_with_numbers = self._tokenize_with_line_numbers(content, docstring_ranges)
+        try:
+            # Get docstring line ranges
+            docstring_ranges = self._get_docstring_ranges_from_content(content)
 
-        # Generate rolling hash windows
-        windows = self._rolling_hash_with_tracking(lines_with_numbers, config.min_duplicate_lines)
+            # Tokenize with line number tracking
+            lines_with_numbers = self._tokenize_with_line_numbers(content, docstring_ranges)
 
-        blocks = []
-        for hash_val, start_line, end_line, snippet in windows:
-            # Skip blocks that are single logical statements
-            # Check the original source code, not the normalized snippet
-            if self._is_single_statement_in_source(content, start_line, end_line):
-                continue
+            # Generate rolling hash windows
+            windows = self._rolling_hash_with_tracking(lines_with_numbers, config.min_duplicate_lines)
 
-            block = CodeBlock(
-                file_path=file_path,
-                start_line=start_line,
-                end_line=end_line,
-                snippet=snippet,
-                hash_value=hash_val,
-            )
+            blocks = []
+            for hash_val, start_line, end_line, snippet in windows:
+                # Skip blocks that are single logical statements
+                # Check the original source code, not the normalized snippet
+                if self._is_single_statement_in_source(content, start_line, end_line):
+                    continue
 
-            # Apply extensible filters (keyword arguments, imports, etc.)
-            if self._filter_registry.should_filter_block(block, content):
-                continue
+                block = CodeBlock(
+                    file_path=file_path,
+                    start_line=start_line,
+                    end_line=end_line,
+                    snippet=snippet,
+                    hash_value=hash_val,
+                )
+
+                # Apply extensible filters (keyword arguments, imports, etc.)
+                if self._filter_registry.should_filter_block(block, content):
+                    continue
 
-            blocks.append(block)
+                blocks.append(block)
 
-        return blocks
+            return blocks
+        finally:
+            # Clear cache after analysis to avoid memory leaks
+            self._cached_ast = None
+            self._cached_content = None
 
     def _get_docstring_ranges_from_content(self, content: str) -> set[int]:
         """Extract line numbers that are part of docstrings.
@@ -225,10 +237,19 @@ class PythonDuplicateAnalyzer(BaseTokenAnalyzer):  # thailint: ignore[srp.violat
         return hashes
 
     def _is_single_statement_in_source(self, content: str, start_line: int, end_line: int) -> bool:
-        """Check if a line range in the original source is a single logical statement."""
-        tree = self._parse_content_safe(content)
-        if tree is None:
-            return False
+        """Check if a line range in the original source is a single logical statement.
+
+        Performance optimization: Uses cached AST if available (set by analyze() method)
+        to avoid re-parsing the entire file for each hash window check.
+        """
+        # Use cached AST if available and content matches
+        if self._cached_ast is not None and content == self._cached_content:
+            tree = self._cached_ast
+        else:
+            # Fallback: parse content (used by tests or standalone calls)
+            tree = self._parse_content_safe(content)
+            if tree is None:
+                return False
 
         return self._check_overlapping_nodes(tree, start_line, end_line)
 
@@ -241,9 +262,19 @@ class PythonDuplicateAnalyzer(BaseTokenAnalyzer):  # thailint: ignore[srp.violat
             return None
 
     def _check_overlapping_nodes(self, tree: ast.Module, start_line: int, end_line: int) -> bool:
-        """Check if any AST node overlaps and matches single-statement pattern."""
+        """Check if any AST node overlaps and matches single-statement pattern.
+
+        Performance optimization: Pre-filter nodes by line range before expensive pattern checks.
+        """
         for node in ast.walk(tree):
-            if self._node_overlaps_and_matches(node, start_line, end_line):
+            # Quick line range check to skip nodes that don't overlap
+            if not hasattr(node, "lineno") or not hasattr(node, "end_lineno"):
+                continue
+            if node.end_lineno < start_line or node.lineno > end_line:
+                continue  # No overlap, skip expensive pattern matching
+
+            # Node overlaps - check if it matches single-statement pattern
+            if self._is_single_statement_pattern(node, start_line, end_line):
                 return True
         return False
 

src/orchestrator/core.py

@@ -101,8 +101,9 @@ class Orchestrator:
         self.config_loader = LinterConfigLoader()
         self.ignore_parser = IgnoreDirectiveParser(self.project_root)
 
-        # Auto-discover and register all linting rules from src.linters
-        self.registry.discover_rules("src.linters")
+        # Performance optimization: Defer rule discovery until first file is linted
+        # This eliminates ~0.077s overhead for commands that don't need rules (--help, config, etc.)
+        self._rules_discovered = False
 
         # Use provided config or load from project root
         if config is not None:
@@ -208,6 +209,12 @@ class Orchestrator:
 
         return violations
 
+    def _ensure_rules_discovered(self) -> None:
+        """Ensure rules have been discovered and registered (lazy initialization)."""
+        if not self._rules_discovered:
+            self.registry.discover_rules("src.linters")
+            self._rules_discovered = True
+
     def _get_rules_for_file(self, file_path: Path, language: str) -> list[BaseLintRule]:
         """Get rules applicable to this file.
 
@@ -218,6 +225,9 @@ class Orchestrator:
         Returns:
             List of rules to execute against this file.
         """
+        # Lazy initialization: discover rules on first lint operation
+        self._ensure_rules_discovered()
+
         # For now, return all registered rules
         # Future: filter by language, configuration, etc.
         return self.registry.list_all()

src/utils/project_root.py

@@ -4,29 +4,52 @@ Purpose: Centralized project root detection for consistent file placement
 Scope: Single source of truth for finding project root directory
 
 Overview: Uses pyprojroot package to provide reliable project root detection across
-    different environments (development, CI/CD, user installations). Delegates all
-    project root detection logic to the industry-standard pyprojroot library which
-    handles various project markers and edge cases that we cannot anticipate.
+    different environments (development, CI/CD, user installations). Falls back to
+    manual detection if pyprojroot is not available (e.g., in test environments).
+    Searches for standard project markers like .git, .thailint.yaml, and pyproject.toml.
 
-Dependencies: pyprojroot for robust project root detection
+Dependencies: pyprojroot (optional, with manual fallback)
 
 Exports: is_project_root(), get_project_root()
 
 Interfaces: Path-based functions for checking and finding project roots
 
-Implementation: Pure delegation to pyprojroot with fallback to start_path when no root found
+Implementation: pyprojroot delegation with manual fallback for test environments
 """
 
 from pathlib import Path
 
-from pyprojroot import find_root
+# Try to import pyprojroot, but don't fail if it's not available
+try:
+    from pyprojroot import find_root
+
+    HAS_PYPROJROOT = True
+except ImportError:
+    HAS_PYPROJROOT = False
+
+
+def _has_marker(path: Path, marker_name: str, is_dir: bool = False) -> bool:
+    """Check if a directory contains a specific marker.
+
+    Args:
+        path: Directory path to check
+        marker_name: Name of marker file or directory
+        is_dir: True if marker is a directory, False if it's a file
+
+    Returns:
+        True if marker exists, False otherwise
+    """
+    marker_path = path / marker_name
+    if is_dir:
+        return marker_path.is_dir()
+    return marker_path.is_file()
 
 
 def is_project_root(path: Path) -> bool:
     """Check if a directory is a project root.
 
-    Uses pyprojroot to detect if the given path is a project root by checking
-    if finding the root from this path returns the same path.
+    Uses pyprojroot if available, otherwise checks for common project markers
+    like .git, .thailint.yaml, or pyproject.toml.
 
     Args:
         path: Directory path to check
@@ -43,6 +66,21 @@ def is_project_root(path: Path) -> bool:
     if not path.exists() or not path.is_dir():
         return False
 
+    if HAS_PYPROJROOT:
+        return _check_root_with_pyprojroot(path)
+
+    return _check_root_with_markers(path)
+
+
+def _check_root_with_pyprojroot(path: Path) -> bool:
+    """Check if path is project root using pyprojroot.
+
+    Args:
+        path: Directory path to check
+
+    Returns:
+        True if path is a project root, False otherwise
+    """
     try:
         # Find root from this path - if it equals this path, it's a root
         found_root = find_root(path)
@@ -52,6 +90,22 @@ def is_project_root(path: Path) -> bool:
         return False
 
 
+def _check_root_with_markers(path: Path) -> bool:
+    """Check if path contains project root markers.
+
+    Args:
+        path: Directory path to check
+
+    Returns:
+        True if path contains .git, .thailint.yaml, or pyproject.toml
+    """
+    return (
+        _has_marker(path, ".git", is_dir=True)
+        or _has_marker(path, ".thailint.yaml", is_dir=False)
+        or _has_marker(path, "pyproject.toml", is_dir=False)
+    )
+
+
 def _try_find_with_criterion(criterion: object, start_path: Path) -> Path | None:
     """Try to find project root with a specific criterion.
 
@@ -68,14 +122,42 @@ def _try_find_with_criterion(criterion: object, start_path: Path) -> Path | None
         return None
 
 
+def _find_root_manual(start_path: Path) -> Path:
+    """Manually find project root by walking up directory tree.
+
+    Fallback implementation when pyprojroot is not available.
+
+    Args:
+        start_path: Directory to start searching from
+
+    Returns:
+        Path to project root, or start_path if no markers found
+    """
+    current = start_path.resolve()
+
+    # Walk up the directory tree
+    for parent in [current] + list(current.parents):
+        # Check for project markers
+        if (
+            _has_marker(parent, ".git", is_dir=True)
+            or _has_marker(parent, ".thailint.yaml", is_dir=False)
+            or _has_marker(parent, "pyproject.toml", is_dir=False)
+        ):
+            return parent
+
+    # No markers found, return start path
+    return current
+
+
 def get_project_root(start_path: Path | None = None) -> Path:
     """Find project root by walking up the directory tree.
 
     This is the single source of truth for project root detection.
     All code that needs to find the project root should use this function.
 
-    Uses pyprojroot which searches for standard project markers (.git directory,
-    pyproject.toml, .thailint.yaml, etc) starting from start_path and walking upward.
+    Uses pyprojroot if available, otherwise uses manual detection searching for
+    standard project markers (.git directory, pyproject.toml, .thailint.yaml, etc)
+    starting from start_path and walking upward.
 
     Args:
         start_path: Directory to start searching from. If None, uses current working directory.
@@ -87,13 +169,29 @@ def get_project_root(start_path: Path | None = None) -> Path:
         >>> root = get_project_root()
         >>> config_file = root / ".thailint.yaml"
     """
-    from pyprojroot import has_dir, has_file
-
     if start_path is None:
         start_path = Path.cwd()
 
     current = start_path.resolve()
 
+    if HAS_PYPROJROOT:
+        return _find_root_with_pyprojroot(current)
+
+    # Manual fallback for test environments
+    return _find_root_manual(current)
+
+
+def _find_root_with_pyprojroot(current: Path) -> Path:
+    """Find project root using pyprojroot library.
+
+    Args:
+        current: Current path to start searching from
+
+    Returns:
+        Path to project root, or current if no markers found
+    """
+    from pyprojroot import has_dir, has_file
+
     # Search for project root markers in priority order
     # Try .git first (most reliable), then .thailint.yaml, then pyproject.toml
     for criterion in [has_dir(".git"), has_file(".thailint.yaml"), has_file("pyproject.toml")]:

{thailint-0.4.2.dist-info → thailint-0.4.4.dist-info}/METADATA

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: thailint
-Version: 0.4.2
+Version: 0.4.4
 Summary: The AI Linter - Enterprise-grade linting and governance for AI-generated code across multiple languages
 License: MIT
+License-File: LICENSE
 Keywords: linter,ai,code-quality,static-analysis,file-placement,governance,multi-language,cli,docker,python
 Author: Steve Jackson
 Requires-Python: >=3.11,<4.0
@@ -15,6 +16,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Quality Assurance
@@ -35,7 +37,7 @@ Description-Content-Type: text/markdown
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-267%2F267%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-296%2F296%20passing-brightgreen.svg)](tests/)
 [![Coverage](https://img.shields.io/badge/coverage-87%25-brightgreen.svg)](htmlcov/)
 
 The AI Linter - Enterprise-ready linting and governance for AI-generated code across multiple languages.
@@ -201,6 +203,44 @@ docker run --rm -v $(pwd):/data \
   washad/thailint:latest nesting /data/src
 ```
 
+### Docker with Sibling Directories
+
+For Docker environments with sibling directories (e.g., separate config and source directories), use `--project-root` or config path inference:
+
+```bash
+# Directory structure:
+# /workspace/
+# ├── root/           # Contains .thailint.yaml and .git
+# ├── backend/        # Code to lint
+# └── tools/
+
+# Option 1: Explicit project root (recommended)
+docker run --rm -v $(pwd):/data \
+  washad/thailint:latest \
+  --project-root /data/root \
+  magic-numbers /data/backend/
+
+# Option 2: Config path inference (automatic)
+docker run --rm -v $(pwd):/data \
+  washad/thailint:latest \
+  --config /data/root/.thailint.yaml \
+  magic-numbers /data/backend/
+
+# With ignore patterns resolving from project root
+docker run --rm -v $(pwd):/data \
+  washad/thailint:latest \
+  --project-root /data/root \
+  --config /data/root/.thailint.yaml \
+  magic-numbers /data/backend/
+```
+
+**Priority order:**
+1. `--project-root` (highest priority - explicit specification)
+2. Inferred from `--config` path directory
+3. Auto-detection from file location (fallback)
+
+See **[Docker Usage](#docker-usage)** section below for more examples.
+
 ## Configuration
 
 Create `.thailint.yaml` in your project root:
@@ -1033,6 +1073,8 @@ See `just --list` or `just help` for all available commands.
 
 ## Docker Usage
 
+### Basic Docker Commands
+
 ```bash
 # Pull published image
 docker pull washad/thailint:latest
@@ -1061,6 +1103,44 @@ docker run --rm -v $(pwd):/data \
     washad/thailint:latest file-placement --format json /data
 ```
 
+### Docker with Sibling Directories (Advanced)
+
+For complex Docker setups with sibling directories, use `--project-root` for explicit control:
+
+```bash
+# Scenario: Monorepo with separate config and code directories
+# Directory structure:
+# /workspace/
+# ├── config/           # Contains .thailint.yaml
+# ├── backend/app/      # Python backend code
+# ├── frontend/         # TypeScript frontend
+# └── tools/            # Build tools
+
+# Explicit project root (recommended for Docker)
+docker run --rm -v /path/to/workspace:/workspace \
+  washad/thailint:latest \
+  --project-root /workspace/config \
+  magic-numbers /workspace/backend/
+
+# Config path inference (automatic - no --project-root needed)
+docker run --rm -v /path/to/workspace:/workspace \
+  washad/thailint:latest \
+  --config /workspace/config/.thailint.yaml \
+  magic-numbers /workspace/backend/
+
+# Lint multiple sibling directories with shared config
+docker run --rm -v /path/to/workspace:/workspace \
+  washad/thailint:latest \
+  --project-root /workspace/config \
+  nesting /workspace/backend/ /workspace/frontend/
+```
+
+**When to use `--project-root` in Docker:**
+- **Sibling directory structures** - When config/code aren't nested
+- **Monorepos** - Multiple projects sharing one config
+- **CI/CD** - Explicit paths prevent auto-detection issues
+- **Ignore patterns** - Ensures patterns resolve from correct base directory
+
 ## Documentation
 
 ### Comprehensive Guides

{thailint-0.4.2.dist-info → thailint-0.4.4.dist-info}/RECORD

@@ -2,7 +2,7 @@ src/__init__.py,sha256=f601zncODr2twrUHqTLS5wyOdZqZi9tMjAe2INhRKqU,2175
 src/analyzers/__init__.py,sha256=fFloZtjkBGwYbAhKTxS3Qy3yDr2_3i3WSfKTw1mAioo,972
 src/analyzers/typescript_base.py,sha256=4I7fAcMOAY9vY1AXh52QpohgFmguBECwOkvBRP4zCS4,5054
 src/api.py,sha256=pJ5l3qxccKBEY-BkANwzTgLAl1ZFq7OP6hx6LSxbhDw,4664
-src/cli.py,sha256=54g24wpF1tzyJW6gflZoIDYfeewjP123no3XliJdVsQ,40544
+src/cli.py,sha256=VvMTaltsFKtCE4DNu6HqnSgKyZYulq3qALO8uteafI8,48092
 src/config.py,sha256=2ebAjIpAhw4bHbOxViEA5nCjfBlDEIrMR59DBrzcYzM,12460
 src/core/__init__.py,sha256=5FtsDvhMt4SNRx3pbcGURrxn135XRbeRrjSUxiXwkNc,381
 src/core/base.py,sha256=Eklcagi2ktfY4Kytl_ObXov2U49N9OGDpw4cu4PUzGY,7824
@@ -30,7 +30,7 @@ src/linters/dry/duplicate_storage.py,sha256=3OxE2mtoWGAsNNrB8J2c-4JirLUoqZ9ptydO
 src/linters/dry/file_analyzer.py,sha256=ufSQ85ddsGTqGnBHZNTdV_5DGfTpUmJOB58sIdJNV0I,2928
 src/linters/dry/inline_ignore.py,sha256=ASfA-fp_1aPpkakN2e0T6qdTh8S7Jqj89ovxXJLmFlc,4439
 src/linters/dry/linter.py,sha256=XMLwCgGrFX0l0dVUJs1jpsXOfgxeKKDbxOtN5h5Emhk,5835
-src/linters/dry/python_analyzer.py,sha256=Qj9dElypv8K3Qno20F5JfuOm7IKGvDyuGSvb4032n7Q,21140
+src/linters/dry/python_analyzer.py,sha256=RoC_OD0UqI0j5HVEwSZWUZVyHDNUtywvxse0HRumLoI,22748
 src/linters/dry/storage_initializer.py,sha256=ykMALFs4uMUrN0_skEwySDl_t5Dm_LGHllF0OxDhiUI,1366
 src/linters/dry/token_hasher.py,sha256=mCFuP0FQFALyKghBgZHcspsoOxgT7C7ZkfspnhFA5U4,3609
 src/linters/dry/typescript_analyzer.py,sha256=n1rsQYp7nuPhgErbG8hWawkywRz-iFGhrGlQXDrIa14,21494
@@ -71,13 +71,13 @@ src/linters/srp/typescript_analyzer.py,sha256=Wi0P_G1v5AnZYtMN3sNm1iHva84-8Kep2L
 src/linters/srp/typescript_metrics_calculator.py,sha256=2VLRux_tf1Cw645wwTuol3Z5A6-mkl4cgyW34myy00Q,2728
 src/linters/srp/violation_builder.py,sha256=jaIjVtRYWUTs1SVJVwd0FxCojo0DxhPzfhyfMKmAroM,3881
 src/orchestrator/__init__.py,sha256=XXLDJq2oaB-TpP2Y97GRnde9EkITGuFCmuLrDfxI9nY,245
-src/orchestrator/core.py,sha256=zb4H4HtDNLmnsRCUXI3oNtfM3T-nTPW9Q2pAbI61VEs,8374
+src/orchestrator/core.py,sha256=z0YcwsK18uhlztIPi54ux3mOm8fHMREYJoudsJPhC0Q,8857
 src/orchestrator/language_detector.py,sha256=rHyVMApit80NTTNyDH1ObD1usKD8LjGmH3DwqNAWYGc,2736
 src/templates/thailint_config_template.yaml,sha256=u8WFv2coE4uqfgf_slw7xjo4kGYIowDm1RIgxsKQzrE,4275
 src/utils/__init__.py,sha256=NiBtKeQ09Y3kuUzeN4O1JNfUIYPQDS2AP1l5ODq-Dec,125
-src/utils/project_root.py,sha256=kGxQU1nHItffiR6iIHT_xCy9RQJtl1Y6dgSUnJHRJQ8,3498
-thailint-0.4.2.dist-info/LICENSE,sha256=kxh1J0Sb62XvhNJ6MZsVNe8PqNVJ7LHRn_EWa-T3djw,1070
-thailint-0.4.2.dist-info/METADATA,sha256=HT1yu78t_cI-2Mv3kw0Kci1o6iBAEdz3jpwJwS6dOkg,34038
-thailint-0.4.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-thailint-0.4.2.dist-info/entry_points.txt,sha256=l7DQJgU18sVLDpSaXOXY3lLhnQHQIRrSJZTQjG1cEAk,62
-thailint-0.4.2.dist-info/RECORD,,
+src/utils/project_root.py,sha256=b3YTEGTa9RPcOeHn1IByMMWyRiUabfVlpnlektL0A0o,6156
+thailint-0.4.4.dist-info/METADATA,sha256=1cmCJ3Myhrt90V0qWw-gfDr6cVP6nRO5fOZmy-TGSVY,36717
+thailint-0.4.4.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+thailint-0.4.4.dist-info/entry_points.txt,sha256=l7DQJgU18sVLDpSaXOXY3lLhnQHQIRrSJZTQjG1cEAk,62
+thailint-0.4.4.dist-info/licenses/LICENSE,sha256=kxh1J0Sb62XvhNJ6MZsVNe8PqNVJ7LHRn_EWa-T3djw,1070
+thailint-0.4.4.dist-info/RECORD,,

{thailint-0.4.2.dist-info → thailint-0.4.4.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.3
+Generator: poetry-core 2.2.1
 Root-Is-Purelib: true
 Tag: py3-none-any