argusf 0.1.0.dev0__py3-none-any.whl

argusf/reporting/formatting.py

@@ -0,0 +1,162 @@
+"""Shared formatting helpers for the text and JSON reporters."""
+
+from typing import IO, TYPE_CHECKING
+
+import click
+
+from argusf.analysis.rules import RuleRegistry
+from argusf.analysis.syntax_errors import SYNTAX_ERROR_CODE, SYNTAX_ERROR_NAME
+from argusf.autofix.context import FixContext, FixMode
+from argusf.autofix.models import Applicability
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+    from argusf.ir.models import Finding, RunResult
+
+
+def display_root(source_root: Path) -> Path:
+    """The directory findings' paths are shown relative to."""
+    return source_root.parent if source_root.is_file() else source_root
+
+
+def summary_line(result: RunResult, active_findings: list[Finding], context: FixContext) -> str:
+    """Build the run's trailing summary line for text reports."""
+    fixed = result.fixed_count
+    remaining = len(active_findings)
+    findings_part = f"{remaining} finding(s)."
+    if context.mode in (FixMode.FIX, FixMode.FIX_ONLY) and fixed:
+        findings_part = f"{fixed + remaining} finding(s) ({fixed} fixed, {remaining} remaining)."
+    return (
+        f"\nChecked {result.total_files} file(s) in {result.elapsed:.2f}s"
+        f" ({result.files_from_cache} from cache)."
+        f" {findings_part}"
+    )
+
+
+def display_position(finding: Finding) -> tuple[int, int]:
+    """Return a finding's 1-based (row, column).
+
+    The single source of truth for the 0-based (stored) to 1-based
+    (displayed) conversion shared by every text and JSON format.
+    """
+    return finding.line + 1, (finding.column or 0) + 1
+
+
+def echo(stream: IO[str] | None, message: str = "") -> None:
+    """Write a line to the given output stream."""
+    click.echo(message, file=stream)
+
+
+def rule_names() -> dict[str, str]:
+    """Map every rule id (plus ERROR) to its display name."""
+    names = {rule_cls.metadata.id: rule_cls.metadata.name for rule_cls in RuleRegistry.values()}
+    names[SYNTAX_ERROR_CODE] = SYNTAX_ERROR_NAME
+    return names
+
+
+def fix_applies(finding: Finding, context: FixContext) -> bool:
+    """Whether the finding's fix applies at this safety level.
+
+    The single predicate behind the [*] marker and every fixable
+    tally; deliberately mode-independent, so a plain report marks
+    exactly what --fix would apply.
+    """
+    return finding.fix is not None and context.applies(finding.fix)
+
+
+def fix_marker(finding: Finding, context: FixContext) -> str:
+    """The `[*] ` marker for a fixable finding, else empty."""
+    return "[*] " if fix_applies(finding, context) else ""
+
+
+def _applicable_count(active_findings: list[Finding], context: FixContext) -> int:
+    return sum(1 for finding in active_findings if fix_applies(finding, context))
+
+
+def _hidden_count(active_findings: list[Finding], context: FixContext) -> int:
+    """Count fixes one --unsafe-fixes away: unsafe fixes while off."""
+    if context.unsafe_fixes:
+        return 0
+    return sum(
+        1
+        for finding in active_findings
+        if finding.fix is not None and finding.fix.applicability is Applicability.UNSAFE
+    )
+
+
+def _hidden_clause(active_findings: list[Finding], context: FixContext) -> str:
+    hidden = _hidden_count(active_findings, context)
+    if not hidden:
+        return ""
+    return f" ({hidden} hidden fix(es) can be enabled with the `--unsafe-fixes` option)"
+
+
+def fixable_hint_line(active_findings: list[Finding], context: FixContext) -> str | None:
+    """Build the fixable-count hint line, or None if none apply."""
+    applicable = _applicable_count(active_findings, context)
+    hidden_clause = _hidden_clause(active_findings, context)
+    if applicable:
+        return f"[*] {applicable} fixable with the `--fix` option{hidden_clause}."
+    if hidden_clause:
+        return f"No fixes available{hidden_clause}."
+    return None
+
+
+def _additional_clause(active_findings: list[Finding], context: FixContext) -> str:
+    hidden = _hidden_count(active_findings, context)
+    if not hidden:
+        return ""
+    return f" ({hidden} additional fix(es) available with `--unsafe-fixes`)"
+
+
+def fixed_only_line(result: RunResult, active_findings: list[Finding], context: FixContext) -> str | None:
+    """The FIX_ONLY summary line, or None when nothing was fixed."""
+    if not result.fixed_count:
+        return None
+    return f"Fixed {result.fixed_count} finding(s){_additional_clause(active_findings, context)}."
+
+
+def would_fix_line(result: RunResult, active_findings: list[Finding], context: FixContext) -> str | None:
+    """The --diff would-fix summary line, or None."""
+    if not result.fixed_count:
+        hidden_clause = _hidden_clause(active_findings, context)
+        return f"No fixes available{hidden_clause}." if hidden_clause else None
+    return f"Would fix {result.fixed_count} finding(s){_additional_clause(active_findings, context)}."
+
+
+def _write_show_fixes(write: Callable[[str], None], result: RunResult, root: Path) -> None:
+    names = rule_names()
+    write(f"Fixed {result.fixed_count} finding(s):")
+    for path, counts in result.fixed_by_file.items():
+        write(f"- {path.relative_to(root)}:")
+        rows = sorted(((count, code) for code, count in counts.items()), key=lambda row: (-row[0], row[1]))
+        for count, code in rows:
+            write(f"    {count} \u00d7 {code} ({names[code]})")
+
+
+def write_text_epilogue(
+    write: Callable[[str], None],
+    result: RunResult,
+    active_findings: list[Finding],
+    context: FixContext,
+    root: Path,
+) -> None:
+    """Write the shared tail of a text report.
+
+    Emits the --show-fixes enumeration, then either the fix-only
+    summary (the whole report in FIX_ONLY mode) or the summary line
+    plus the fixable hint.
+    """
+    if context.show_fixes and result.fixed_by_file:
+        _write_show_fixes(write, result, root)
+    if context.mode is FixMode.FIX_ONLY:
+        line = fixed_only_line(result, active_findings, context)
+        if line:
+            write(line)
+        return
+    write(summary_line(result, active_findings, context))
+    hint = fixable_hint_line(active_findings, context)
+    if hint:
+        write(hint)

argusf/reporting/registry.py

@@ -0,0 +1,20 @@
+"""The reporter protocol and its registry."""
+
+from typing import TYPE_CHECKING, Protocol
+
+from argusf.registry import Registry
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.ir.models import RunResult
+
+
+class Reporter(Protocol):
+    """Writes a run's results to some destination."""
+
+    def write_results(self, result: RunResult, source_root: Path) -> None:
+        """Write the run's results for `source_root`."""
+
+
+ReporterRegistry: Registry[str, type[Reporter]] = Registry()

argusf/reporting/reporters/__init__.py

@@ -0,0 +1,15 @@
+from .concise import ConciseReporter
+from .diff import DiffReporter
+from .json import JsonReporter
+from .null import NullReporter
+from .standard import StandardReporter
+from .statistics import StatisticsReporter
+
+__all__ = [
+    "ConciseReporter",
+    "DiffReporter",
+    "JsonReporter",
+    "NullReporter",
+    "StandardReporter",
+    "StatisticsReporter",
+]

argusf/reporting/reporters/base.py

@@ -0,0 +1,29 @@
+"""Shared base class for stream-writing reporters."""
+
+from typing import IO
+
+from argusf.autofix.context import FixContext
+from argusf.reporting.formatting import echo
+from argusf.reporting.registry import Reporter
+
+
+class StreamReporter(Reporter):
+    """Shared construction and line-echo for concrete reporters.
+
+    Purely an implementation convenience — consumers stay typed against
+    the Reporter protocol, and subclasses still owe write_results.
+    """
+
+    def __init__(self, stream: IO[str] | None = None, fix_context: FixContext | None = None) -> None:
+        """Store the output stream and fix context.
+
+        Args:
+            stream: Destination stream; None writes to stdout.
+            fix_context: The run's fix context; defaults to a plain
+                report context.
+        """
+        self._stream = stream
+        self._context = fix_context or FixContext()
+
+    def _echo(self, message: str = "") -> None:
+        echo(self._stream, message)

argusf/reporting/reporters/concise.py

@@ -0,0 +1,35 @@
+"""The concise (path:line:) findings reporter."""
+
+from typing import TYPE_CHECKING
+
+import click
+
+from argusf.autofix.context import FixMode
+from argusf.reporting.formatting import display_position, display_root, fix_marker, write_text_epilogue
+from argusf.reporting.registry import ReporterRegistry
+from argusf.reporting.reporters.base import StreamReporter
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.ir.models import RunResult
+
+
+@ReporterRegistry.register("concise")
+class ConciseReporter(StreamReporter):
+    """Minimal reporter: one `path:line: code message` per finding."""
+
+    def write_results(self, result: RunResult, source_root: Path) -> None:
+        """Write each finding as one line, then the epilogue."""
+        active_findings = result.active_findings()
+
+        root = display_root(source_root)
+        if self._context.mode is not FixMode.FIX_ONLY:
+            for finding in active_findings:
+                rel_path = finding.file_path.relative_to(root)
+                row, _ = display_position(finding)
+                rule_id = click.style(finding.rule_id, fg="red")
+                marker = fix_marker(finding, self._context)
+                self._echo(f"{rel_path}:{row}: {rule_id} {marker}{finding.message}")
+
+        write_text_epilogue(self._echo, result, active_findings, self._context, root)

argusf/reporting/reporters/diff.py

@@ -0,0 +1,30 @@
+"""The --diff reporter: diffs plus a would-fix summary."""
+
+from typing import TYPE_CHECKING
+
+import click
+
+from argusf.reporting.formatting import would_fix_line
+from argusf.reporting.reporters.base import StreamReporter
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.ir.models import RunResult
+
+
+class DiffReporter(StreamReporter):
+    """Prints per-file diffs then the would-fix summary.
+
+    The report for --diff runs; selected by mode in the CLI, so it is
+    left unregistered.
+    """
+
+    def write_results(self, result: RunResult, source_root: Path) -> None:  # noqa: ARG002 - diff labels are pre-rendered
+        """Write the rendered diffs, then the would-fix line."""
+        for _, diff in result.diffs:
+            # Diff text is newline-terminated already.
+            click.echo(diff, file=self._stream, nl=False)
+        line = would_fix_line(result, result.active_findings(), self._context)
+        if line:
+            self._echo(f"\n{line}" if result.diffs else line)

argusf/reporting/reporters/json.py

@@ -0,0 +1,59 @@
+"""The ruff-style JSON findings reporter."""
+
+import json
+from typing import TYPE_CHECKING
+
+from argusf.autofix.context import FixMode
+from argusf.reporting.formatting import display_position
+from argusf.reporting.registry import ReporterRegistry
+from argusf.reporting.reporters.base import StreamReporter
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.ir.models import Finding, RunResult
+
+
+@ReporterRegistry.register("json")
+class JsonReporter(StreamReporter):
+    """Emits findings as a ruff-style JSON array of violations."""
+
+    def write_results(self, result: RunResult, source_root: Path) -> None:  # noqa: ARG002 - filenames are absolute, so the root is not needed
+        """Write the findings as a JSON array (empty in FIX_ONLY)."""
+        if self._context.mode is FixMode.FIX_ONLY:
+            return
+
+        violations = [self._violation(finding) for finding in result.active_findings()]
+        self._echo(json.dumps(violations, indent=2))
+
+    def _violation(self, finding: Finding) -> dict[str, object]:
+        row, column = display_position(finding)
+        end_row = (finding.line if finding.end_line is None else finding.end_line) + 1
+        end_column = column if finding.end_column is None else finding.end_column + 1
+        return {
+            "code": finding.rule_id,
+            "end_location": {"column": end_column, "row": end_row},
+            "filename": str(finding.file_path),
+            "fix": self._fix_payload(finding),
+            "location": {"column": column, "row": row},
+            "message": finding.message,
+            "severity": finding.severity,
+            "suggestion": finding.suggestion,
+        }
+
+    def _fix_payload(self, finding: Finding) -> dict[str, object] | None:
+        fix = finding.fix
+        if fix is None:
+            return None
+        return {
+            "applicability": fix.applicability,
+            "edits": [
+                {
+                    "content": edit.content,
+                    "end_location": {"column": edit.span.end_col + 1, "row": edit.span.end_row + 1},
+                    "location": {"column": edit.span.start_col + 1, "row": edit.span.start_row + 1},
+                }
+                for edit in fix.edits
+            ],
+            "message": fix.message,
+        }

argusf/reporting/reporters/null.py

@@ -0,0 +1,21 @@
+"""A no-op reporter for programmatic and test use."""
+
+from typing import TYPE_CHECKING
+
+from argusf.reporting.registry import Reporter
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.ir.models import RunResult
+
+
+class NullReporter(Reporter):
+    """Discards results; for programmatic and test use.
+
+    Deliberately unregistered, so a user can never pick it as their
+    --output-format.
+    """
+
+    def write_results(self, result: RunResult, source_root: Path) -> None:
+        """Do nothing with the results."""

argusf/reporting/reporters/standard.py

@@ -0,0 +1,78 @@
+"""The standard detailed findings reporter."""
+
+from typing import TYPE_CHECKING
+
+import click
+
+from argusf.autofix.context import FixMode
+from argusf.reporting.formatting import display_position, display_root, fix_marker, write_text_epilogue
+from argusf.reporting.registry import ReporterRegistry
+from argusf.reporting.reporters.base import StreamReporter
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.ir.models import Finding, RunResult
+
+
+@ReporterRegistry.register("standard")
+class StandardReporter(StreamReporter):
+    """Detailed reporter with code context and suggestions."""
+
+    def write_results(self, result: RunResult, source_root: Path) -> None:
+        """Write each finding with context, then the epilogue."""
+        active_findings = result.active_findings()
+
+        root = display_root(source_root)
+        if self._context.mode is not FixMode.FIX_ONLY:
+            for finding in active_findings:
+                rel_path = finding.file_path.relative_to(root)
+                self._write_finding(finding, rel_path)
+
+        write_text_epilogue(self._echo, result, active_findings, self._context, root)
+
+    def _write_finding(self, finding: Finding, rel_path: Path) -> None:
+        row, col = display_position(finding)
+        rule_id = click.style(finding.rule_id, fg="red", bold=True)
+        self._echo(f"{rule_id} {fix_marker(finding, self._context)}{finding.message}")
+        self._echo(f" --> {rel_path}:{row}:{col}")
+
+        source_line = self._read_line(finding.file_path, finding.line)
+        if source_line is not None:
+            gutter = f"{row:>4} | "
+            self._echo("  |")
+            self._echo(f"{gutter}{source_line}")
+            zero_col = finding.column or 0
+            underline = " " * (len(gutter) + zero_col) + "^" * self._underline_width(finding, source_line, zero_col)
+            self._echo(click.style(underline, fg="red"))
+
+        if finding.suggestion:
+            self._echo(f"{click.style('help', fg='cyan')}: {finding.suggestion}")
+
+        self._echo()
+
+    def _underline_width(self, finding: Finding, source_line: str, col: int) -> int:
+        """Width of the caret underline for a finding on this line.
+
+        Columns are 0-based with an exclusive end. Multi-line spans
+        underline to end-of-line; everything is clamped to the visible
+        line, with a one-caret floor for zero-width spans (e.g. a
+        missing token at EOL).
+        """
+        if finding.end_line is not None and finding.end_line != finding.line:
+            width = len(source_line) - col
+        elif finding.end_column is not None:
+            width = finding.end_column - col
+        else:
+            width = 1
+        return max(1, min(width, len(source_line) - col))
+
+    def _read_line(self, file_path: Path, line_no: int) -> str | None:
+        try:
+            with open(file_path, errors="replace") as f:
+                for i, line in enumerate(f):
+                    if i == line_no:
+                        return line.rstrip("\n")
+        except OSError:
+            pass
+        return None

argusf/reporting/reporters/statistics.py

@@ -0,0 +1,99 @@
+"""The --statistics reporter: per-rule finding counts."""
+
+import json
+from collections import Counter
+from dataclasses import dataclass
+from typing import IO, TYPE_CHECKING
+
+from argusf.reporting.formatting import display_root, fix_applies, rule_names, write_text_epilogue
+from argusf.reporting.reporters.base import StreamReporter
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.autofix.context import FixContext
+    from argusf.ir.models import Finding, RunResult
+
+
+@dataclass(frozen=True)
+class _StatisticsRow:
+    count: int
+    code: str
+    name: str
+    fixable_count: int
+
+
+class StatisticsReporter(StreamReporter):
+    """Reports per-rule finding counts instead of the findings.
+
+    Takes the shape of a reporter but is its own CLI option, so it is
+    left unregistered.
+    """
+
+    _TEXT_FORMATS = ("standard", "concise")
+
+    def __init__(
+        self, output_format: str, stream: IO[str] | None = None, fix_context: FixContext | None = None
+    ) -> None:
+        """Bind the reporter to a text or JSON output format.
+
+        Args:
+            output_format: One of "standard", "concise", or "json".
+            stream: Destination stream; None writes to stdout.
+            fix_context: The run's fix context.
+
+        Raises:
+            ValueError: On an unsupported output format.
+        """
+        if output_format != "json" and output_format not in self._TEXT_FORMATS:
+            supported = (*self._TEXT_FORMATS, "json")
+            raise ValueError(
+                f"Statistics output does not support format {output_format!r}. Must be one of {supported!s}"
+            )
+        super().__init__(stream, fix_context)
+        self._output_format = output_format
+
+    def write_results(self, result: RunResult, source_root: Path) -> None:
+        """Write per-rule statistics in the chosen format."""
+        if self._output_format == "json":
+            self._write_json(result)
+        else:
+            self._write_text(result, source_root)
+
+    def _write_text(self, result: RunResult, source_root: Path) -> None:
+        active_findings = result.active_findings()
+        for row in self._statistics_rows(active_findings):
+            marker = "[*]" if row.fixable_count else "[ ]"
+            self._echo(f"{row.count}\t{row.code}\t{marker} {row.name}")
+
+        write_text_epilogue(self._echo, result, active_findings, self._context, display_root(source_root))
+
+    def _write_json(self, result: RunResult) -> None:
+        rows = [
+            {
+                "code": row.code,
+                "name": row.name,
+                "count": row.count,
+                "fixable": row.fixable_count > 0,
+                "fixable_count": row.fixable_count,
+            }
+            for row in self._statistics_rows(result.active_findings())
+        ]
+        self._echo(json.dumps(rows, indent=2))
+
+    def _statistics_rows(self, active_findings: list[Finding]) -> list[_StatisticsRow]:
+        """Build the per-rule statistics rows, sorted for display.
+
+        Rows sort by count descending with ties broken by code
+        ascending ("ERROR" < "RGUS...", so syntax errors lead). The
+        fixable count is how many of a rule's findings have a fix
+        applicable at this run's safety level.
+        """
+        counts = Counter(finding.rule_id for finding in active_findings)
+        fixable_counts = Counter(finding.rule_id for finding in active_findings if fix_applies(finding, self._context))
+        names = rule_names()
+        rows = [
+            _StatisticsRow(count=count, code=code, name=names[code], fixable_count=fixable_counts[code])
+            for code, count in counts.items()
+        ]
+        return sorted(rows, key=lambda row: (-row.count, row.code))