feat(cli): add history trends with ASCII charts and optional matplotlib export

- introduce ASCII line chart + trend summary renderer
- add matplotlib-based image export behind `viz` extra
- wire new `pacta history trends` subcommand with filters and JSON output
- add tests for trends output, ASCII rendering, and image export

Author: akhundMurad

pacta/cli/_ascii_chart.py

@@ -0,0 +1,213 @@
+"""
+ASCII chart rendering for terminal output.
+
+Provides simple chart rendering without external dependencies.
+"""
+
+from __future__ import annotations
+
+
+def render_line_chart(
+    values: list[float],
+    labels: list[str],
+    *,
+    width: int = 60,
+    height: int = 10,
+    title: str | None = None,
+) -> str:
+    """
+    Render a simple ASCII line chart.
+
+    Args:
+        values: Y-axis values (one per data point)
+        labels: X-axis labels (one per data point)
+        width: Chart width in characters
+        height: Chart height in lines
+        title: Optional chart title
+
+    Returns:
+        ASCII chart as a string
+    """
+    if not values:
+        return "No data to display."
+
+    lines: list[str] = []
+
+    # Title
+    if title:
+        lines.append(title)
+        lines.append("=" * len(title))
+        lines.append("")
+
+    # Calculate scale
+    min_val = min(values)
+    max_val = max(values)
+
+    # Handle edge case where all values are the same
+    if min_val == max_val:
+        min_val = 0 if max_val > 0 else max_val - 1
+        if max_val == 0:
+            max_val = 1
+
+    val_range = max_val - min_val
+
+    # Y-axis label width (for padding)
+    y_label_width = max(len(f"{max_val:.0f}"), len(f"{min_val:.0f}")) + 1
+
+    # Calculate chart area dimensions
+    chart_width = min(width - y_label_width - 3, len(values) * 3)
+    chart_width = max(chart_width, len(values))  # At least 1 char per point
+
+    # Map values to chart positions (column indices)
+    if len(values) == 1:
+        x_positions = [chart_width // 2]
+    else:
+        x_positions = [int((i / (len(values) - 1)) * (chart_width - 1)) for i in range(len(values))]
+
+    # Map values to row indices (0 = bottom, height-1 = top)
+    def value_to_row(v: float) -> int:
+        if val_range == 0:
+            return height // 2
+        normalized = (v - min_val) / val_range
+        return int(normalized * (height - 1))
+
+    # Build the chart grid
+    grid: list[list[str]] = [[" " for _ in range(chart_width)] for _ in range(height)]
+
+    # Plot points
+    for i, v in enumerate(values):
+        row = value_to_row(v)
+        col = x_positions[i]
+        if 0 <= row < height and 0 <= col < chart_width:
+            grid[row][col] = "\u25cf"  # Filled circle
+
+    # Connect points with lines (optional - use dashes for now)
+    for i in range(len(values) - 1):
+        row1 = value_to_row(values[i])
+        row2 = value_to_row(values[i + 1])
+        col1 = x_positions[i]
+        col2 = x_positions[i + 1]
+
+        # Simple horizontal connection if on same row
+        if row1 == row2 and col2 - col1 > 1:
+            for c in range(col1 + 1, col2):
+                if grid[row1][c] == " ":
+                    grid[row1][c] = "-"
+
+    # Render with Y-axis labels
+    for row_idx in range(height - 1, -1, -1):
+        # Show label at top, middle, and bottom
+        if row_idx == height - 1:
+            label = f"{max_val:>{y_label_width}.0f}"
+        elif row_idx == 0:
+            label = f"{min_val:>{y_label_width}.0f}"
+        elif row_idx == height // 2:
+            mid_val = (max_val + min_val) / 2
+            label = f"{mid_val:>{y_label_width}.0f}"
+        else:
+            label = " " * y_label_width
+
+        # Y-axis line character
+        if row_idx == 0:
+            axis_char = "\u2514"  # Bottom-left corner
+        else:
+            axis_char = "\u2502"  # Vertical line
+
+        lines.append(f"{label} {axis_char}{''.join(grid[row_idx])}")
+
+    # X-axis
+    lines.append(" " * (y_label_width + 1) + "\u2514" + "\u2500" * chart_width)
+
+    # X-axis labels (simplified - show first and last)
+    if labels:
+        label_line = " " * (y_label_width + 2)
+        if len(labels) == 1:
+            label_line += labels[0].center(chart_width)
+        else:
+            first_label = labels[0][:10]
+            last_label = labels[-1][:10]
+            spacing = chart_width - len(first_label) - len(last_label)
+            if spacing > 0:
+                label_line += first_label + " " * spacing + last_label
+            else:
+                label_line += first_label
+        lines.append(label_line)
+
+    return "\n".join(lines)
+
+
+def render_trend_summary(
+    values: list[float],
+    labels: list[str],
+    metric_name: str,
+) -> str:
+    """
+    Render a summary of the trend.
+
+    Args:
+        values: The data values
+        labels: The date labels
+        metric_name: Name of the metric being tracked
+
+    Returns:
+        Summary text
+    """
+    if not values:
+        return "No data available."
+
+    lines: list[str] = []
+    lines.append("")
+
+    first_val = values[0]
+    last_val = values[-1]
+    diff = last_val - first_val
+
+    # Trend direction
+    if diff < 0:
+        trend_icon = "\u2193"  # Down arrow
+        trend_word = "Improving" if metric_name == "violations" else "Decreasing"
+    elif diff > 0:
+        trend_icon = "\u2191"  # Up arrow
+        trend_word = "Worsening" if metric_name == "violations" else "Increasing"
+    else:
+        trend_icon = "\u2192"  # Right arrow
+        trend_word = "Stable"
+
+    diff_str = f"{diff:+.2f}" if isinstance(diff, float) and not diff.is_integer() else f"{diff:+.0f}"
+    lines.append(f"Trend: {trend_icon} {trend_word} ({diff_str} over period)")
+
+    # First and last values
+    first_str = (
+        f"{first_val:.2f}" if isinstance(first_val, float) and not first_val.is_integer() else f"{first_val:.0f}"
+    )
+    last_str = f"{last_val:.2f}" if isinstance(last_val, float) and not last_val.is_integer() else f"{last_val:.0f}"
+
+    first_label = labels[0] if labels else "start"
+    last_label = labels[-1] if labels else "end"
+
+    unit = _metric_unit(metric_name)
+    lines.append(f"First: {first_str} {unit} ({first_label})")
+    lines.append(f"Last:  {last_str} {unit} ({last_label})")
+
+    # Statistics
+    avg_val = float(sum(values) / len(values))
+    max_val = max(values)
+    min_val = min(values)
+
+    lines.append("")
+    avg_str = f"{avg_val:.2f}" if not avg_val.is_integer() else f"{avg_val:.0f}"
+    lines.append(f"Average: {avg_str} {unit}")
+    lines.append(f"Min: {min_val:.0f}, Max: {max_val:.0f}")
+
+    return "\n".join(lines)
+
+
+def _metric_unit(metric_name: str) -> str:
+    """Get the display unit for a metric."""
+    units = {
+        "violations": "violations",
+        "nodes": "nodes",
+        "edges": "edges",
+        "density": "ratio",
+    }
+    return units.get(metric_name, "")

pacta/cli/_mpl_chart.py

@@ -0,0 +1,134 @@
+"""
+Matplotlib chart rendering for image export.
+
+This module requires matplotlib (install with `pip install pacta[viz]`).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+
+def render_trends_chart(
+    values: list[float],
+    labels: list[str],
+    *,
+    metric: str,
+    output_path: str,
+    title: str | None = None,
+) -> None:
+    """
+    Render a trends chart to an image file using matplotlib.
+
+    Args:
+        values: Y-axis values (one per data point)
+        labels: X-axis labels (one per data point)
+        metric: The metric name being tracked
+        output_path: Path to save the image (PNG, SVG, PDF supported)
+        title: Optional chart title
+
+    Raises:
+        ImportError: If matplotlib is not installed
+    """
+    try:
+        import matplotlib.dates as mdates
+        import matplotlib.pyplot as plt
+    except ImportError as e:
+        raise ImportError("matplotlib is required for image export. Install it with: pip install pacta[viz]") from e
+
+    # Parse dates from labels if possible
+    dates = []
+    for label in labels:
+        try:
+            # Try to parse "Mon DD" format
+            dt = datetime.strptime(label, "%b %d")
+            # Use current year
+            dt = dt.replace(year=datetime.now().year)
+            dates.append(dt)
+        except ValueError:
+            dates = None
+            break
+
+    # Create figure
+    fig, ax = plt.subplots(figsize=(10, 6))
+
+    # Plot data
+    if dates:
+        ax.plot(dates, values, marker="o", linewidth=2, markersize=8, color="#2563eb")
+        ax.xaxis.set_major_formatter(mdates.DateFormatter("%b %d"))
+        ax.xaxis.set_major_locator(mdates.AutoDateLocator())
+        plt.xticks(rotation=45)
+    else:
+        x_positions = list(range(len(values)))
+        ax.plot(x_positions, values, marker="o", linewidth=2, markersize=8, color="#2563eb")
+        ax.set_xticks(x_positions)
+        ax.set_xticklabels(labels, rotation=45, ha="right")
+
+    # Styling
+    metric_labels = {
+        "violations": "Violations",
+        "nodes": "Node Count",
+        "edges": "Edge Count",
+        "density": "Density (edges/nodes)",
+    }
+    y_label = metric_labels.get(metric, metric.title())
+    ax.set_ylabel(y_label, fontsize=12)
+    ax.set_xlabel("Date", fontsize=12)
+
+    # Title
+    if title:
+        ax.set_title(title, fontsize=14, fontweight="bold")
+    else:
+        ax.set_title(f"{y_label} Over Time", fontsize=14, fontweight="bold")
+
+    # Grid
+    ax.grid(True, alpha=0.3)
+    ax.set_axisbelow(True)
+
+    # Fill area under curve
+    if dates:
+        ax.fill_between(dates, values, alpha=0.1, color="#2563eb")
+    else:
+        ax.fill_between(x_positions, values, alpha=0.1, color="#2563eb")
+
+    # Add trend annotation
+    if len(values) >= 2:
+        diff = values[-1] - values[0]
+        if diff < 0:
+            trend_text = f"Trend: {diff:+.1f} (Improving)" if metric == "violations" else f"Trend: {diff:+.1f}"
+            trend_color = "#16a34a"  # Green
+        elif diff > 0:
+            trend_text = f"Trend: {diff:+.1f} (Worsening)" if metric == "violations" else f"Trend: {diff:+.1f}"
+            trend_color = "#dc2626"  # Red
+        else:
+            trend_text = "Trend: Stable"
+            trend_color = "#6b7280"  # Gray
+
+        ax.annotate(
+            trend_text,
+            xy=(0.02, 0.98),
+            xycoords="axes fraction",
+            fontsize=10,
+            color=trend_color,
+            verticalalignment="top",
+            fontweight="bold",
+        )
+
+    # Tight layout
+    plt.tight_layout()
+
+    # Save
+    output = Path(output_path)
+    fig.savefig(output, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+
+
+def is_matplotlib_available() -> bool:
+    """Check if matplotlib is installed."""
+    try:
+        import matplotlib  # noqa: F401
+
+        return True
+    except ImportError:
+        return False