lintro 0.23.1__tar.gz → 0.24.3__tar.gz

{lintro-0.23.1/lintro.egg-info → lintro-0.24.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lintro
-Version: 0.23.1
+Version: 0.24.3
 Summary: A unified CLI tool for code formatting, linting, and quality assurance
 Author-email: TurboCoder13 <turbocoder13@gmail.com>
 License: MIT License
@@ -45,8 +45,10 @@ Requires-Dist: click==8.1.8
 Requires-Dist: coverage-badge==1.1.2
 Requires-Dist: darglint==1.8.1
 Requires-Dist: loguru==0.7.3
+Requires-Dist: packaging>=24.0
 Requires-Dist: pathspec>=0.12.0
 Requires-Dist: pydantic>=2.10.0
+Requires-Dist: rich>=14.0.0
 Requires-Dist: tabulate==0.9.0
 Requires-Dist: yamllint==1.37.1
 Requires-Dist: httpx==0.28.1

lintro-0.24.3/docs/debugging.md

@@ -0,0 +1,172 @@
+# Debugging Lintro
+
+This guide explains how to use Lintro's logging system to diagnose issues.
+
+## Quick Start
+
+```bash
+# Show DEBUG logs on console
+lintro check --debug .
+
+# Run with debug logging for a specific tool
+lintro check --debug --tools ruff .
+```
+
+## Log Locations
+
+### Console Output
+
+| Mode      | Log Level | What You See                                   |
+| --------- | --------- | ---------------------------------------------- |
+| Default   | WARNING+  | Tool failures, parse errors, permission issues |
+| `--debug` | DEBUG+    | Full execution trace, commands, file counts    |
+
+### File Logs
+
+Debug logs are always written to file, regardless of console verbosity:
+
+```text
+~/.lintro/run-<timestamp>/debug.log
+```
+
+Each run creates a new timestamped directory containing:
+
+- `debug.log` - Full DEBUG+ logs with timestamps
+- Output files (JSON, CSV, etc.) if requested
+
+### Log Rotation
+
+- **Max files**: 5 rotated log files
+- **Max size**: 100MB per file
+- **Total**: Up to 500MB of logs retained
+
+## Log Levels
+
+| Level   | When Used          | Example                                         |
+| ------- | ------------------ | ----------------------------------------------- |
+| DEBUG   | Execution details  | `[ruff] Ready: 45 files, timeout=30s`           |
+| WARNING | Recoverable issues | `Failed to parse .prettierrc: Unexpected token` |
+| ERROR   | Critical failures  | `Command not found: ruff`                       |
+
+## What Gets Logged
+
+### Tool Execution (DEBUG)
+
+```text
+[ruff] Preparing execution for 3 input paths
+File discovery complete: 45 files matching ['*.py']
+[ruff] Ready: 45 files, timeout=30s
+Running subprocess: ruff check --output-format json... (timeout=30s, cwd=/project)
+```
+
+### Subprocess Failures (DEBUG + WARNING)
+
+```text
+# DEBUG - stderr preview on non-zero exit
+Subprocess ruff exited with code 1, stderr: error: invalid config...
+
+# WARNING - timeouts and missing commands
+Subprocess ruff timed out after 30s
+Command not found: ruff. Ensure it is installed and in PATH.
+```
+
+### Config Parse Errors (WARNING)
+
+```text
+Failed to parse JSON config .prettierrc: Expecting property name (line 5, col 3)
+Failed to parse pyproject.toml at /project/pyproject.toml: Invalid value
+```
+
+### Permission Issues (WARNING)
+
+```text
+Cannot write to /project/.lintro (permission denied), using fallback: /tmp/lintro/run-...
+```
+
+## Common Debug Scenarios
+
+### Tool Not Running
+
+**Symptom**: Tool shows "skipped" or doesn't appear in output.
+
+**Debug**:
+
+```bash
+lintro check --debug --tools <tool_name> .
+```
+
+**Look for**:
+
+- `Skipping <tool>: version check failed` - Tool not installed or wrong version
+- `[<tool>] Early exit: No files to check` - No matching files found
+- `Command not found: <tool>` - Tool binary not in PATH
+
+### Silent Failures
+
+**Symptom**: Tool reports ERROR status but no issues shown.
+
+**Debug**:
+
+```bash
+lintro check --debug .
+# Then check the debug log
+cat ~/.lintro/run-*/debug.log | grep -A5 "failed\|error\|stderr"
+```
+
+**Look for**:
+
+- `Subprocess <tool> exited with code N, stderr: ...` - Tool execution error
+- `Failed to parse <config>` - Config file is malformed
+
+### Slow Execution
+
+**Symptom**: Lintro takes a long time or times out.
+
+**Debug**:
+
+```bash
+lintro check --debug .
+```
+
+**Look for**:
+
+- `File discovery complete: N files` - Too many files being scanned?
+- `Subprocess <tool> timed out after Ns` - Increase timeout with
+  `--tool-options tool:timeout=N`
+
+### Config Not Applied
+
+**Symptom**: Tool doesn't respect your config file.
+
+**Debug**:
+
+```bash
+lintro config --verbose
+lintro check --debug .
+```
+
+**Look for**:
+
+- `Discovered <tool> config at ...` - Config file found
+- `Failed to parse <config>` - Config file has syntax errors
+
+## Environment Variables
+
+| Variable       | Purpose                                                       |
+| -------------- | ------------------------------------------------------------- |
+| `LINTRO_DEBUG` | Set to `1` to enable debug logging (alternative to `--debug`) |
+| `NO_COLOR`     | Set to `1` to disable colored output                          |
+
+## Getting Help
+
+If debug logs don't help diagnose the issue:
+
+1. Run with `--debug` and save the output
+2. Check `~/.lintro/run-*/debug.log` for the full trace
+3. [Open an issue][issues] with:
+   - Lintro version (`lintro --version`)
+   - Tool versions (`ruff --version`, etc.)
+   - Relevant debug log excerpts
+   - Steps to reproduce
+
+[issues]: https://github.com/TurboCoder13/py-lintro/issues

{lintro-0.23.1 → lintro-0.24.3}/lintro/__init__.py

@@ -1,3 +1,3 @@
 """Lintro - A unified CLI core for code formatting, linting, and quality assurance."""
 
-__version__ = "0.23.1"
+__version__ = "0.24.3"

{lintro-0.23.1 → lintro-0.24.3}/lintro/config/config_loader.py

@@ -112,8 +112,13 @@ def _load_pyproject_fallback() -> tuple[dict[str, Any], Path | None]:
                 with pyproject_path.open("rb") as f:
                     data = tomllib.load(f)
                 return data.get("tool", {}).get("lintro", {}), pyproject_path
-            except (OSError, tomllib.TOMLDecodeError) as e:
-                logger.debug(f"Failed to load pyproject.toml: {e}")
+            except tomllib.TOMLDecodeError as e:
+                logger.warning(
+                    f"Failed to parse pyproject.toml at {pyproject_path}: {e}",
+                )
+                return {}, None
+            except OSError as e:
+                logger.debug(f"Could not read pyproject.toml at {pyproject_path}: {e}")
                 return {}, None
 
         # Move up one directory

lintro-0.24.3/lintro/enums/display_column.py

@@ -0,0 +1,35 @@
+"""Display column enum definitions.
+
+This module defines the standard columns used in issue table output.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class DisplayColumn(StrEnum):
+    """Standard columns for issue table display.
+
+    Values are title-case strings used as table column headers.
+    """
+
+    FILE = "File"
+    LINE = "Line"
+    COLUMN = "Column"
+    CODE = "Code"
+    SEVERITY = "Severity"
+    FIXABLE = "Fixable"
+    MESSAGE = "Message"
+
+
+# Standard column order for display - includes all fields since most tools report them
+STANDARD_COLUMNS: list[DisplayColumn] = [
+    DisplayColumn.FILE,
+    DisplayColumn.LINE,
+    DisplayColumn.COLUMN,
+    DisplayColumn.CODE,
+    DisplayColumn.SEVERITY,
+    DisplayColumn.FIXABLE,
+    DisplayColumn.MESSAGE,
+]

{lintro-0.23.1 → lintro-0.24.3}/lintro/formatters/__init__.py

@@ -5,12 +5,11 @@ tool's issues by using the BaseIssue.to_display_row() method.
 """
 
 # Base classes and utilities
+from lintro.enums.display_column import STANDARD_COLUMNS, DisplayColumn
 from lintro.formatters.core.format_registry import OutputStyle, TableDescriptor
 
 # Unified formatter - the preferred way to format issues
 from lintro.formatters.formatter import (
-    EXTENDED_COLUMNS,
-    STANDARD_COLUMNS,
     UnifiedTableDescriptor,
     format_issues,
     format_issues_with_sections,
@@ -24,7 +23,7 @@ __all__ = [
     "format_tool_result",
     "UnifiedTableDescriptor",
     "STANDARD_COLUMNS",
-    "EXTENDED_COLUMNS",
+    "DisplayColumn",
     # Base classes
     "TableDescriptor",
     "OutputStyle",

{lintro-0.23.1 → lintro-0.24.3}/lintro/formatters/formatter.py

@@ -19,22 +19,23 @@ Example:
 from __future__ import annotations
 
 from collections.abc import Sequence
-from typing import TYPE_CHECKING
 
+from lintro.enums.display_column import STANDARD_COLUMNS, DisplayColumn
 from lintro.enums.output_format import OutputFormat, normalize_output_format
 from lintro.formatters.core.format_registry import TableDescriptor, get_style
 from lintro.parsers.base_issue import BaseIssue
 from lintro.utils.path_utils import normalize_file_path_for_display
 
-if TYPE_CHECKING:
-    pass
-
-
-# Standard columns for display (basic)
-STANDARD_COLUMNS = ["File", "Line", "Col", "Code", "Message"]
-
-# Extended columns including severity and fixable status
-EXTENDED_COLUMNS = ["File", "Line", "Col", "Code", "Severity", "Fixable", "Message"]
+# Map DisplayColumn enum to row dict keys
+_COLUMN_KEY_MAP: dict[DisplayColumn, str] = {
+    DisplayColumn.FILE: "file",
+    DisplayColumn.LINE: "line",
+    DisplayColumn.COLUMN: "column",
+    DisplayColumn.CODE: "code",
+    DisplayColumn.MESSAGE: "message",
+    DisplayColumn.SEVERITY: "severity",
+    DisplayColumn.FIXABLE: "fixable",
+}
 
 
 class UnifiedTableDescriptor(TableDescriptor):
@@ -46,27 +47,14 @@ class UnifiedTableDescriptor(TableDescriptor):
 
     def __init__(
         self,
-        columns: list[str] | None = None,
-        *,
-        include_severity: bool = False,
-        include_fixable: bool = False,
+        columns: list[DisplayColumn] | None = None,
     ) -> None:
         """Initialize the descriptor.
 
         Args:
-            columns: Custom column list, or None to use defaults.
-            include_severity: Include severity column.
-            include_fixable: Include fixable column.
+            columns: Custom column list, or None to use STANDARD_COLUMNS.
         """
-        if columns is not None:
-            self._columns = columns
-        elif include_severity or include_fixable:
-            self._columns = EXTENDED_COLUMNS
-        else:
-            self._columns = STANDARD_COLUMNS
-
-        self._include_severity = include_severity
-        self._include_fixable = include_fixable
+        self._columns = columns if columns is not None else STANDARD_COLUMNS
 
     def get_columns(self) -> list[str]:
         """Return the column names.
@@ -74,7 +62,7 @@ class UnifiedTableDescriptor(TableDescriptor):
         Returns:
             List of column header names.
         """
-        return self._columns
+        return [str(col) for col in self._columns]
 
     def get_rows(self, issues: Sequence[BaseIssue]) -> list[list[str]]:
         """Extract row data from issues using to_display_row().
@@ -87,18 +75,6 @@ class UnifiedTableDescriptor(TableDescriptor):
         """
         rows: list[list[str]] = []
 
-        # Map column names to row dict keys
-        column_key_map = {
-            "File": "file",
-            "Line": "line",
-            "Col": "column",
-            "Column": "column",
-            "Code": "code",
-            "Message": "message",
-            "Severity": "severity",
-            "Fixable": "fixable",
-        }
-
         for issue in issues:
             display_data = issue.to_display_row()
 
@@ -110,7 +86,7 @@ class UnifiedTableDescriptor(TableDescriptor):
 
             row = []
             for col in self._columns:
-                key = column_key_map.get(col, col.lower())
+                key = _COLUMN_KEY_MAP.get(col, str(col).lower())
                 value = display_data.get(key, "")
                 row.append(str(value) if value else "")
 
@@ -123,10 +99,8 @@ def format_issues(
     issues: Sequence[BaseIssue],
     output_format: OutputFormat | str = OutputFormat.GRID,
     *,
-    columns: list[str] | None = None,
+    columns: list[DisplayColumn] | None = None,
     tool_name: str | None = None,
-    include_severity: bool = False,
-    include_fixable: bool = False,
 ) -> str:
     """Format any issues using unified display.
 
@@ -138,8 +112,6 @@ def format_issues(
         output_format: Output format (grid, json, plain, etc.).
         columns: Custom column list (defaults to STANDARD_COLUMNS).
         tool_name: Tool name for JSON output.
-        include_severity: Include severity column in output.
-        include_fixable: Include fixable column in output.
 
     Returns:
         Formatted string.
@@ -152,11 +124,7 @@ def format_issues(
         return "No issues found."
 
     normalized_format = normalize_output_format(output_format)
-    descriptor = UnifiedTableDescriptor(
-        columns=columns,
-        include_severity=include_severity,
-        include_fixable=include_fixable,
-    )
+    descriptor = UnifiedTableDescriptor(columns=columns)
 
     style = get_style(normalized_format)
     cols = descriptor.get_columns()
@@ -205,7 +173,6 @@ def format_issues_with_sections(
             issues,
             output_format=normalized_format,
             tool_name=tool_name,
-            include_fixable=group_by_fixable,
         )
 
     # Partition issues by fixable status
@@ -239,7 +206,6 @@ def format_tool_result(
     issues: Sequence[BaseIssue],
     output_format: OutputFormat | str = OutputFormat.GRID,
     *,
-    include_severity: bool = False,
     group_by_fixable: bool = False,
 ) -> str:
     """Format a tool's results with appropriate sections and metadata.
@@ -251,7 +217,6 @@ def format_tool_result(
         tool_name: Name of the tool.
         issues: List of issues from the tool.
         output_format: Output format.
-        include_severity: Include severity column.
         group_by_fixable: Group by fixable status.
 
     Returns:
@@ -269,5 +234,4 @@ def format_tool_result(
         issues,
         output_format=output_format,
         tool_name=tool_name,
-        include_severity=include_severity,
     )

lintro-0.24.3/lintro/parsers/ruff/ruff_format_issue.py

@@ -0,0 +1,24 @@
+"""Model for ruff formatting issues."""
+
+from dataclasses import dataclass, field
+
+from lintro.parsers.base_issue import BaseIssue
+
+
+@dataclass
+class RuffFormatIssue(BaseIssue):
+    """Represents a ruff formatting issue.
+
+    Inherits from BaseIssue to be compatible with the unified formatter.
+
+    Attributes:
+        file: File path that would be reformatted.
+        code: Defaults to "FORMAT" for format issues.
+        message: Defaults to "Would reformat file" for format issues.
+        fixable: Defaults to True since format issues are auto-fixable by fmt.
+    """
+
+    # file is inherited from BaseIssue
+    code: str = field(default="FORMAT")
+    message: str = field(default="Would reformat file")
+    fixable: bool = field(default=True)

{lintro-0.23.1 → lintro-0.24.3}/lintro/plugins/base.py

@@ -25,6 +25,8 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
+from loguru import logger
+
 from lintro.config.lintro_config import LintroConfig
 from lintro.models.core.tool_result import ToolResult
 from lintro.plugins.execution_preparation import (
@@ -372,6 +374,8 @@ class BaseToolPlugin(ABC):
             cmd = self._build_command(ctx.rel_files)
             success, output = self._run_subprocess(cmd, cwd=ctx.cwd)
         """
+        logger.debug(f"[{self.name}] Preparing execution for {len(paths)} input paths")
+
         result = prepare_execution(
             paths=paths,
             options=options,
@@ -383,13 +387,19 @@ class BaseToolPlugin(ABC):
         )
 
         if "early_result" in result:
-            return ExecutionContext(early_result=result["early_result"])
+            early_result = result["early_result"]
+            logger.debug(f"[{self.name}] Early exit: {early_result.output}")
+            return ExecutionContext(early_result=early_result)
+
+        files = result.get("files", [])
+        timeout = result.get("timeout", DEFAULT_TIMEOUT)
+        logger.debug(f"[{self.name}] Ready: {len(files)} files, timeout={timeout}s")
 
         return ExecutionContext(
-            files=result.get("files", []),
+            files=files,
             rel_files=result.get("rel_files", []),
             cwd=result.get("cwd"),
-            timeout=result.get("timeout", DEFAULT_TIMEOUT),
+            timeout=timeout,
         )
 
     def _get_executable_command(self, tool_name: str) -> list[str]:

{lintro-0.23.1 → lintro-0.24.3}/lintro/plugins/execution_preparation.py

@@ -194,6 +194,9 @@ def prepare_execution(
         definition.default_timeout,
     )
 
+    logger.debug(
+        f"Prepared execution: {len(files)} files, cwd={cwd}, timeout={timeout}s",
+    )
     return {
         "files": files,
         "rel_files": rel_files,

{lintro-0.23.1 → lintro-0.24.3}/lintro/plugins/file_discovery.py

@@ -105,6 +105,9 @@ def discover_files(
         )
         progress.update(task, description=f"Found {len(files)} files")
 
+    logger.debug(
+        f"File discovery: {len(files)} files matching {definition.file_patterns}",
+    )
     return files
 
 

{lintro-0.23.1 → lintro-0.24.3}/lintro/plugins/subprocess_executor.py

@@ -12,6 +12,8 @@ import sys
 import threading
 from typing import TYPE_CHECKING
 
+from loguru import logger
+
 if TYPE_CHECKING:
     from collections.abc import Callable
 
@@ -138,6 +140,9 @@ def run_subprocess(
     """
     validate_subprocess_command(cmd)
 
+    cmd_str = " ".join(cmd[:5]) + ("..." if len(cmd) > 5 else "")
+    logger.debug(f"Running subprocess: {cmd_str} (timeout={timeout}s, cwd={cwd})")
+
     try:
         result = subprocess.run(  # nosec B603 - args list, shell=False
             cmd,
@@ -147,8 +152,18 @@ def run_subprocess(
             cwd=cwd,
             env=env,
         )
+
+        if result.returncode != 0:
+            stderr_preview = (result.stderr or "")[:500]
+            if stderr_preview:
+                logger.debug(
+                    f"Subprocess {cmd[0]} exited with code {result.returncode}, "
+                    f"stderr: {stderr_preview}",
+                )
+
         return result.returncode == 0, result.stdout + result.stderr
     except subprocess.TimeoutExpired as e:
+        logger.warning(f"Subprocess {cmd[0]} timed out after {timeout}s")
         # Preserve partial output from the original exception
         partial_output = ""
         if e.output:
@@ -170,6 +185,9 @@ def run_subprocess(
             output=partial_output,
         ) from e
     except FileNotFoundError as e:
+        logger.warning(
+            f"Command not found: {cmd[0]}. Ensure it is installed and in PATH.",
+        )
         raise FileNotFoundError(
             f"Command not found: {cmd[0]}. "
             f"Please ensure it is installed and in your PATH.",
@@ -207,6 +225,11 @@ def run_subprocess_streaming(
     """
     validate_subprocess_command(cmd)
 
+    cmd_str = " ".join(cmd[:5]) + ("..." if len(cmd) > 5 else "")
+    logger.debug(
+        f"Running subprocess (streaming): {cmd_str} (timeout={timeout}s, cwd={cwd})",
+    )
+
     try:
         # Use Popen for streaming output  # nosec B603
         process = subprocess.Popen(
@@ -237,6 +260,9 @@ def run_subprocess_streaming(
 
         if reader_thread.is_alive():
             # Timeout occurred during reading - kill the process
+            logger.warning(
+                f"Subprocess {cmd[0]} timed out after {timeout}s (reading output)",
+            )
             process.kill()
             # Brief timeout for cleanup; ignore if process doesn't die cleanly
             with contextlib.suppress(subprocess.TimeoutExpired):
@@ -251,6 +277,9 @@ def run_subprocess_streaming(
         try:
             returncode = process.wait(timeout=timeout)
         except subprocess.TimeoutExpired as e:
+            logger.warning(
+                f"Subprocess {cmd[0]} timed out after {timeout}s (during wait)",
+            )
             process.kill()
             process.wait(timeout=1.0)
             raise subprocess.TimeoutExpired(
@@ -258,9 +287,21 @@ def run_subprocess_streaming(
                 timeout=timeout,
                 output="\n".join(output_lines),
             ) from e
+
+        if returncode != 0:
+            output_preview = "\n".join(output_lines)[:500]
+            if output_preview:
+                logger.debug(
+                    f"Subprocess {cmd[0]} exited with code {returncode}, "
+                    f"output: {output_preview}",
+                )
+
         return returncode == 0, "\n".join(output_lines)
 
     except FileNotFoundError as e:
+        logger.warning(
+            f"Command not found: {cmd[0]}. Ensure it is installed and in PATH.",
+        )
         raise FileNotFoundError(
             f"Command not found: {cmd[0]}. "
             f"Please ensure it is installed and in your PATH.",

{lintro-0.23.1 → lintro-0.24.3}/lintro/tools/definitions/bandit.py

@@ -318,6 +318,7 @@ class BanditPlugin(BaseToolPlugin):
             return ctx.early_result  # type: ignore[return-value]
 
         cmd: list[str] = self._build_check_command(files=ctx.rel_files)
+        logger.debug(f"[bandit] Running: {' '.join(cmd[:10])}... (cwd={ctx.cwd})")
 
         output: str
         execution_failure: bool = False

{lintro-0.23.1 → lintro-0.24.3}/lintro/tools/definitions/mypy.py

@@ -303,7 +303,7 @@ class MypyPlugin(BaseToolPlugin):
                 issues_count=0,
             )
 
-        logger.debug("Mypy discovered {} python file(s)", len(ctx.files))
+        logger.debug("[mypy] Discovered {} python file(s)", len(ctx.files))
 
         # Set config file if discovered
         if not self.options.get("config_file") and config_path:
@@ -314,7 +314,7 @@ class MypyPlugin(BaseToolPlugin):
             )
 
         cmd = self._build_command(files=ctx.rel_files)
-        logger.debug("Running mypy with cwd={} and cmd={}", ctx.cwd, cmd)
+        logger.debug("[mypy] Running with cwd={} and cmd={}", ctx.cwd, cmd)
 
         try:
             success, output = self._run_subprocess(

{lintro-0.23.1 → lintro-0.24.3}/lintro/tools/implementations/ruff/check.py

@@ -125,10 +125,12 @@ def execute_ruff_check(
         )
 
     # Debug logging for CI diagnostics
-    logger.debug(f"ruff check command: {' '.join(cmd)}")
-    logger.debug(f"ruff check success: {success_lint}")
+    logger.debug(f"[ruff] check command: {' '.join(cmd)}")
+    logger.debug(f"[ruff] check success: {success_lint}")
     if not success_lint:
-        logger.warning(f"ruff check failed with output:\n{output_lint[:2000]}")
+        # Log full output to debug file only - raw JSON output is parsed and
+        # formatted into tables, so no need to show it in console warnings
+        logger.debug(f"[ruff] check full output:\n{output_lint}")
 
     lint_issues = parse_ruff_output(output=output_lint)
     lint_issues_count: int = len(lint_issues)
@@ -167,12 +169,12 @@ def execute_ruff_check(
             )
 
         # Debug logging for CI diagnostics
-        logger.debug(f"ruff format --check command: {' '.join(format_cmd)}")
-        logger.debug(f"ruff format --check success: {success_format}")
+        logger.debug(f"[ruff] format --check command: {' '.join(format_cmd)}")
+        logger.debug(f"[ruff] format --check success: {success_format}")
         if not success_format:
-            logger.warning(
-                f"ruff format check failed with output:\n{output_format[:2000]}",
-            )
+            # Log full output to debug file only - output is parsed and
+            # formatted into tables, so no need to show it in console warnings
+            logger.debug(f"[ruff] format check full output:\n{output_format}")
 
         format_files = parse_ruff_format_check_output(output=output_format)
         # Normalize files to absolute paths to keep behavior consistent with