lintro 0.3.2__py3-none-any.whl

lintro/utils/formatting.py

@@ -0,0 +1,173 @@
+"""Formatting utilities for core output.
+
+Includes helpers to read multi-section ASCII art files and normalize
+ASCII blocks to a fixed size (width/height) while preserving shape.
+"""
+
+import random
+from pathlib import Path
+
+
+def read_ascii_art(filename: str) -> list[str]:
+    """Read ASCII art from a file.
+
+    Args:
+        filename: Name of the ASCII art file.
+
+    Returns:
+        List of lines from one randomly selected ASCII art section.
+    """
+    try:
+        # Get the path to the ASCII art file
+        ascii_art_dir: Path = Path(__file__).parent.parent / "ascii-art"
+        file_path: Path = ascii_art_dir / filename
+
+        # Read the file and parse sections
+        with file_path.open("r", encoding="utf-8") as f:
+            lines: list[str] = [line.rstrip() for line in f.readlines()]
+
+            # Find non-empty sections (separated by empty lines)
+            sections: list[list[str]] = []
+            current_section: list[str] = []
+
+            for line in lines:
+                if line.strip():
+                    current_section.append(line)
+                elif current_section:
+                    sections.append(current_section)
+                    current_section = []
+
+            # Add the last section if it's not empty
+            if current_section:
+                sections.append(current_section)
+
+            # Return a random section if there are multiple, otherwise return all lines
+            if sections:
+                return random.choice(sections)
+            return lines
+    except (FileNotFoundError, OSError):
+        # Return empty list if file not found or can't be read
+        return []
+
+
+def normalize_ascii_block(
+    lines: list[str],
+    *,
+    width: int,
+    height: int,
+    align: str = "center",
+    valign: str = "middle",
+) -> list[str]:
+    """Normalize an ASCII block to a fixed width/height.
+
+    Lines are trimmed on the right only (rstrip), then padded to ``width``.
+    If a line exceeds ``width``, it is truncated. The whole block is then
+    vertically padded/truncated to ``height``.
+
+    Args:
+        lines: Original ASCII block lines.
+        width: Target width in characters.
+        height: Target height in lines.
+        align: Horizontal alignment: 'left', 'center', or 'right'.
+        valign: Vertical alignment: 'top', 'middle', or 'bottom'.
+
+    Returns:
+        list[str]: Normalized lines of length == ``height`` where each line
+        has exactly ``width`` characters.
+    """
+    if width <= 0 or height <= 0:
+        return []
+
+    def _pad_line(s: str) -> str:
+        s = s.rstrip("\n").rstrip()
+        # Truncate if necessary
+        if len(s) > width:
+            return s[:width]
+        space = width - len(s)
+        if align == "left":
+            return s + (" " * space)
+        if align == "right":
+            return (" " * space) + s
+        # center
+        left = space // 2
+        right = space - left
+        return (" " * left) + s + (" " * right)
+
+    padded_lines: list[str] = [_pad_line(line) for line in lines]
+
+    # Vertical pad/truncate
+    if len(padded_lines) >= height:
+        # Truncate based on valign
+        if valign == "top":
+            return padded_lines[:height]
+        if valign == "bottom":
+            return padded_lines[-height:]
+        # middle
+        extra = len(padded_lines) - height
+        top_cut = extra // 2
+        return padded_lines[top_cut : top_cut + height]
+
+    # Need to add blank lines
+    blank = " " * width
+    missing = height - len(padded_lines)
+    if valign == "top":
+        return padded_lines + [blank] * missing
+    if valign == "bottom":
+        return [blank] * missing + padded_lines
+    top_pad = missing // 2
+    bottom_pad = missing - top_pad
+    return [blank] * top_pad + padded_lines + [blank] * bottom_pad
+
+
+def normalize_ascii_file_sections(
+    file_path: Path,
+    *,
+    width: int,
+    height: int,
+    align: str = "center",
+    valign: str = "middle",
+) -> list[list[str]]:
+    """Read a multi-section ASCII file and normalize all sections.
+
+    Sections are separated by empty lines. Each section is normalized
+    independently and returned as a list of lines.
+
+    Args:
+        file_path: Path to the ASCII art file.
+        width: Target width.
+        height: Target height.
+        align: Horizontal alignment.
+        valign: Vertical alignment.
+
+    Returns:
+        list[list[str]]: List of normalized sections.
+    """
+    try:
+        with file_path.open("r", encoding="utf-8") as f:
+            raw_lines: list[str] = [line.rstrip("\n") for line in f]
+    except (FileNotFoundError, OSError):
+        return []
+
+    sections: list[list[str]] = []
+    current: list[str] = []
+    for line in raw_lines:
+        if line.strip() == "":
+            if current:
+                sections.append(current)
+                current = []
+        else:
+            current.append(line)
+    if current:
+        sections.append(current)
+
+    normalized: list[list[str]] = [
+        normalize_ascii_block(
+            sec,
+            width=width,
+            height=height,
+            align=align,
+            valign=valign,
+        )
+        for sec in sections
+    ]
+    return normalized

lintro/utils/output_manager.py

@@ -0,0 +1,301 @@
+"""Output manager for Lintro auto-generated results.
+
+Handles creation of timestamped output directories and writing all required formats.
+"""
+
+import csv
+import datetime
+import html
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from lintro.models.core.tool_result import ToolResult
+
+# Constants
+DEFAULT_BASE_DIR: str = ".lintro"
+DEFAULT_KEEP_LAST: int = 10
+DEFAULT_TIMESTAMP_FORMAT: str = "%Y%m%d-%H%M%S"
+DEFAULT_RUN_PREFIX: str = "run-"
+DEFAULT_TEMP_PREFIX: str = ".lintro"
+
+
+def _markdown_escape(text: str) -> str:
+    """Escape text for Markdown formatting.
+
+    Args:
+        text: str: Text to escape.
+
+    Returns:
+        str: Escaped text safe for Markdown.
+    """
+    return text.replace("|", r"\|").replace("\n", " ")
+
+
+def _html_escape(text: str) -> str:
+    """Escape text for HTML formatting.
+
+    Args:
+        text: str: Text to escape.
+
+    Returns:
+        str: Escaped text safe for HTML.
+    """
+    return html.escape(text)
+
+
+class OutputManager:
+    """Manages output directories and result files for Lintro runs.
+
+    This class creates a timestamped directory under .lintro/run-{timestamp}/
+    and provides methods to write all required output formats.
+    """
+
+    def __init__(
+        self,
+        base_dir: str = DEFAULT_BASE_DIR,
+        keep_last: int = DEFAULT_KEEP_LAST,
+    ) -> None:
+        """Initialize the OutputManager.
+
+        Args:
+            base_dir: str: Base directory for output (default: .lintro).
+            keep_last: int: Number of runs to keep (default: 10).
+        """
+        # Allow override via environment variable
+        env_base_dir: str | None = os.environ.get("LINTRO_LOG_DIR")
+        if env_base_dir:
+            self.base_dir = Path(env_base_dir)
+        else:
+            self.base_dir = Path(base_dir)
+        self.keep_last = keep_last
+        self.run_dir = self._create_run_dir()
+
+    def _create_run_dir(self) -> Path:
+        """Create a new timestamped run directory.
+
+        Returns:
+            Path: Path to the created run directory.
+        """
+        timestamp: str = datetime.datetime.now().strftime(DEFAULT_TIMESTAMP_FORMAT)
+        run_dir: Path = self.base_dir / f"{DEFAULT_RUN_PREFIX}{timestamp}"
+        try:
+            run_dir.mkdir(parents=True, exist_ok=True)
+        except PermissionError:
+            # Fallback to temp directory if not writable
+            temp_base: Path = Path(tempfile.gettempdir()) / DEFAULT_TEMP_PREFIX
+            run_dir = temp_base / f"{DEFAULT_RUN_PREFIX}{timestamp}"
+            run_dir.mkdir(parents=True, exist_ok=True)
+        return run_dir
+
+    def write_console_log(
+        self,
+        content: str,
+    ) -> None:
+        """Write the console log to console.log in the run directory.
+
+        Args:
+            content: str: The console output as a string.
+        """
+        (self.run_dir / "console.log").write_text(content, encoding="utf-8")
+
+    def write_json(
+        self,
+        data: object,
+        filename: str = "results.json",
+    ) -> None:
+        """Write data as JSON to the run directory.
+
+        Args:
+            data: object: The data to serialize as JSON.
+            filename: str: The output filename (default: results.json).
+        """
+        import json
+
+        with open(self.run_dir / filename, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+    def write_markdown(
+        self,
+        content: str,
+        filename: str = "report.md",
+    ) -> None:
+        """Write Markdown content to the run directory.
+
+        Args:
+            content: str: Markdown content as a string.
+            filename: str: The output filename (default: report.md).
+        """
+        (self.run_dir / filename).write_text(content, encoding="utf-8")
+
+    def write_html(
+        self,
+        content: str,
+        filename: str = "report.html",
+    ) -> None:
+        """Write HTML content to the run directory.
+
+        Args:
+            content: str: HTML content as a string.
+            filename: str: The output filename (default: report.html).
+        """
+        (self.run_dir / filename).write_text(content, encoding="utf-8")
+
+    def write_csv(
+        self,
+        rows: list[list[str]],
+        header: list[str],
+        filename: str = "summary.csv",
+    ) -> None:
+        """Write CSV data to the run directory.
+
+        Args:
+            rows: list[list[str]]: List of rows (each row is a list of strings).
+            header: list[str]: List of column headers.
+            filename: str: The output filename (default: summary.csv).
+        """
+        with open(self.run_dir / filename, "w", encoding="utf-8", newline="") as f:
+            writer = csv.writer(f)
+            writer.writerow(header)
+            writer.writerows(rows)
+
+    def write_reports_from_results(
+        self,
+        results: list["ToolResult"],
+    ) -> None:
+        """Generate and write Markdown, HTML, and CSV reports from tool results.
+
+        Args:
+            results: list["ToolResult"]: List of ToolResult objects from a Lintro run.
+        """
+        self._write_markdown_report(results=results)
+        self._write_html_report(results=results)
+        self._write_csv_summary(results=results)
+
+    def _write_markdown_report(
+        self,
+        results: list["ToolResult"],
+    ) -> None:
+        """Write a Markdown report summarizing all tool results and issues.
+
+        Args:
+            results: list["ToolResult"]: List of ToolResult objects from the linting
+                run.
+        """
+        lines: list[str] = ["# Lintro Report", ""]
+        lines.append("## Summary\n")
+        lines.append("| Tool | Issues |")
+        lines.append("|------|--------|")
+        for r in results:
+            lines.append(f"| {r.name} | {r.issues_count} |")
+        lines.append("")
+        for r in results:
+            lines.append(f"### {r.name} ({r.issues_count} issues)")
+            if hasattr(r, "issues") and r.issues:
+                lines.append("| File | Line | Code | Message |")
+                lines.append("|------|------|------|---------|")
+                for issue in r.issues:
+                    file: str = _markdown_escape(getattr(issue, "file", ""))
+                    line = getattr(issue, "line", "")
+                    code: str = _markdown_escape(getattr(issue, "code", ""))
+                    msg: str = _markdown_escape(getattr(issue, "message", ""))
+                    lines.append(f"| {file} | {line} | {code} | {msg} |")
+                lines.append("")
+            else:
+                lines.append("No issues found.\n")
+        self.write_markdown(content="\n".join(lines))
+
+    def _write_html_report(
+        self,
+        results: list["ToolResult"],
+    ) -> None:
+        """Write an HTML report summarizing all tool results and issues.
+
+        Args:
+            results: list["ToolResult"]: List of ToolResult objects from the linting
+                run.
+        """
+        html: list[str] = ["<html><head><title>Lintro Report</title></head><body>"]
+        html.append("<h1>Lintro Report</h1>")
+        html.append("<h2>Summary</h2>")
+        html.append("<table border='1'><tr><th>Tool</th><th>Issues</th></tr>")
+        for r in results:
+            html.append(
+                f"<tr><td>{_html_escape(r.name)}</td><td>{r.issues_count}</td></tr>",
+            )
+        html.append("</table>")
+        for r in results:
+            html.append(f"<h3>{_html_escape(r.name)} ({r.issues_count} issues)</h3>")
+            if hasattr(r, "issues") and r.issues:
+                html.append(
+                    "<table border='1'><tr><th>File</th><th>Line</th><th>Code</th>"
+                    "<th>Message</th></tr>"
+                )
+                for issue in r.issues:
+                    file: str = _html_escape(getattr(issue, "file", ""))
+                    line = getattr(issue, "line", "")
+                    code: str = _html_escape(getattr(issue, "code", ""))
+                    msg: str = _html_escape(getattr(issue, "message", ""))
+                    html.append(
+                        f"<tr><td>{file}</td><td>{line}</td><td>{code}</td>"
+                        f"<td>{msg}</td></tr>"
+                    )
+                html.append("</table>")
+            else:
+                html.append("<p>No issues found.</p>")
+        html.append("</body></html>")
+        self.write_html(content="\n".join(html))
+
+    def _write_csv_summary(
+        self,
+        results: list["ToolResult"],
+    ) -> None:
+        """Write a CSV summary of all tool results and issues.
+
+        Args:
+            results: list["ToolResult"]: List of ToolResult objects from the linting
+                run.
+        """
+        rows: list[list[str]] = []
+        header: list[str] = ["tool", "issues_count", "file", "line", "code", "message"]
+        for r in results:
+            if hasattr(r, "issues") and r.issues:
+                for issue in r.issues:
+                    rows.append(
+                        [
+                            r.name,
+                            r.issues_count,
+                            getattr(issue, "file", ""),
+                            getattr(issue, "line", ""),
+                            getattr(issue, "code", ""),
+                            getattr(issue, "message", ""),
+                        ],
+                    )
+            else:
+                rows.append([r.name, r.issues_count, "", "", "", ""])
+        self.write_csv(rows=rows, header=header)
+
+    def cleanup_old_runs(self) -> None:
+        """Remove old run directories, keeping only the most recent N runs."""
+        if not self.base_dir.exists():
+            return
+        runs: list[Path] = sorted(
+            [
+                d
+                for d in self.base_dir.iterdir()
+                if d.is_dir() and d.name.startswith(DEFAULT_RUN_PREFIX)
+            ],
+            key=lambda d: d.name,
+            reverse=True,
+        )
+        for old_run in runs[self.keep_last :]:
+            shutil.rmtree(old_run)
+
+    def get_run_dir(self) -> Path:
+        """Get the current run directory.
+
+        Returns:
+            Path: Path to the current run directory.
+        """
+        return self.run_dir

lintro/utils/path_utils.py

@@ -0,0 +1,41 @@
+"""Path utilities for Lintro.
+
+Small helpers to normalize paths for display consistency.
+"""
+
+import os
+
+
+def normalize_file_path_for_display(file_path: str) -> str:
+    """Normalize file path to be relative to project root for consistent display.
+
+    This ensures all tools show file paths in the same format:
+    - Relative to project root (like ./src/file.py)
+    - Consistent across all tools regardless of how they output paths
+
+    Args:
+        file_path: File path (can be absolute or relative). If empty, returns as is.
+
+    Returns:
+        Normalized relative path from project root (e.g., "./src/file.py")
+    """
+    # Fast-path: empty or whitespace-only input
+    if not file_path or not str(file_path).strip():
+        return file_path
+    try:
+        # Get the current working directory (project root)
+        project_root: str = os.getcwd()
+
+        # Convert to absolute path first, then make relative to project root
+        abs_path: str = os.path.abspath(file_path)
+        rel_path: str = os.path.relpath(abs_path, project_root)
+
+        # Ensure it starts with "./" for consistency (like darglint format)
+        if not rel_path.startswith("./") and not rel_path.startswith("../"):
+            rel_path = "./" + rel_path
+
+        return rel_path
+
+    except (ValueError, OSError):
+        # If path normalization fails, return the original path
+        return file_path