figurelint 0.1.0__py3-none-any.whl

figurelint/__init__.py

@@ -0,0 +1,3 @@
+"""FigureLint: lint academic figures before submission."""
+
+__version__ = "0.1.0"

figurelint/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

figurelint/checks.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image, UnidentifiedImageError
+
+from .models import Finding, Severity
+
+SUPPORTED_RASTER_EXTENSIONS = {".png", ".jpg", ".jpeg"}
+SUPPORTED_VECTOR_EXTENSIONS = {".svg", ".pdf"}
+SUPPORTED_EXTENSIONS = SUPPORTED_RASTER_EXTENSIONS | SUPPORTED_VECTOR_EXTENSIONS
+
+
+def collect_figure_files(target: Path) -> list[Path]:
+    """Return supported figure files under target."""
+    if target.is_file():
+        return [target] if target.suffix.lower() in SUPPORTED_EXTENSIONS else []
+
+    if target.is_dir():
+        return sorted(
+            p
+            for p in target.rglob("*")
+            if p.is_file() and p.suffix.lower() in SUPPORTED_EXTENSIONS
+        )
+
+    return []
+
+
+def _extract_dpi(image: Image.Image) -> tuple[float, float] | None:
+    raw = image.info.get("dpi")
+    if not raw:
+        return None
+
+    try:
+        x, y = raw
+        return float(x), float(y)
+    except (TypeError, ValueError):
+        return None
+
+
+def check_raster(
+    path: Path,
+    *,
+    min_dpi: int | None = 300,
+    min_short_side: int | None = 600,
+) -> list[Finding]:
+    """Inspect one raster image and return technical findings."""
+    findings: list[Finding] = []
+
+    try:
+        with Image.open(path) as image:
+            image.verify()
+
+        with Image.open(path) as image:
+            width, height = image.size
+            mode = image.mode
+            dpi = _extract_dpi(image)
+            bands = image.getbands()
+
+    except (UnidentifiedImageError, OSError) as exc:
+        return [
+            Finding(
+                path=path,
+                severity=Severity.ERROR,
+                code="IMAGE_UNREADABLE",
+                message=f"Image could not be read: {exc}",
+            )
+        ]
+
+    if min_short_side is not None and min(width, height) < min_short_side:
+        findings.append(
+            Finding(
+                path=path,
+                severity=Severity.WARNING,
+                code="DIM_SMALL",
+                message=(
+                    f"Short side is {min(width, height)} px; "
+                    f"configured minimum is {min_short_side} px."
+                ),
+            )
+        )
+
+    if min_dpi is not None and dpi is None:
+        findings.append(
+            Finding(
+                path=path,
+                severity=Severity.WARNING,
+                code="DPI_MISSING",
+                message=(
+                    "No DPI metadata was found. Pixel dimensions may still be adequate, "
+                    "but submission systems can rely on DPI metadata."
+                ),
+            )
+        )
+    # PNG stores DPI through pixels-per-metre metadata, which can round a
+    # requested 300 DPI to values such as 299.9994 on read-back.
+    elif min_dpi is not None and min(dpi) < min_dpi - 0.5:
+        findings.append(
+            Finding(
+                path=path,
+                severity=Severity.WARNING,
+                code="DPI_LOW",
+                message=(
+                    f"Reported DPI is {dpi[0]:.0f}×{dpi[1]:.0f}; "
+                    f"configured minimum is {min_dpi} DPI."
+                ),
+            )
+        )
+
+    if "A" in bands or mode in {"LA", "PA"}:
+        findings.append(
+            Finding(
+                path=path,
+                severity=Severity.INFO,
+                code="ALPHA_CHANNEL",
+                message=(
+                    "Image contains transparency. Some publication workflows require "
+                    "flattened output."
+                ),
+            )
+        )
+
+    if path.suffix.lower() in {".jpg", ".jpeg"}:
+        findings.append(
+            Finding(
+                path=path,
+                severity=Severity.INFO,
+                code="JPEG_LOSSY",
+                message=(
+                    "JPEG uses lossy compression. For line art or text-heavy figures, "
+                    "PNG or a vector format is often preferable."
+                ),
+            )
+        )
+
+    return findings

figurelint/cli.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from .checks import check_raster, collect_figure_files
+from .github_annotations import format_github_annotation
+from .models import Severity
+from .pdf_checks import check_pdf
+from .presets import available_preset_names, get_preset, resolve_thresholds
+from .svg_checks import check_svg
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Lint academic figures before submission.",
+)
+console = Console()
+
+
+@app.command("presets")
+def list_presets() -> None:
+    """List built-in FigureLint presets."""
+    table = Table(title="FigureLint presets")
+    table.add_column("Name", no_wrap=True)
+    table.add_column("Purpose", overflow="fold")
+    table.add_column("DPI", justify="right")
+    table.add_column("Raster min", justify="right")
+    table.add_column("SVG font", justify="right")
+    table.add_column("SVG stroke", justify="right")
+    table.add_column("Provenance")
+
+    def show(value: int | float | None, unit: str = "") -> str:
+        if value is None:
+            return "—"
+        if isinstance(value, float):
+            return f"{value:g}{unit}"
+        return f"{value}{unit}"
+
+    for name in available_preset_names():
+        preset = get_preset(name)
+        thresholds = preset.thresholds
+        provenance = (
+            preset.source_name
+            if preset.is_publisher_verified
+            else "FigureLint convenience preset"
+        )
+        font_range = (
+            f"{show(thresholds.min_font_size_pt)}–{show(thresholds.max_font_size_pt)}pt"
+            if thresholds.max_font_size_pt is not None
+            else show(thresholds.min_font_size_pt, "pt")
+        )
+        stroke_range = (
+            f"{show(thresholds.min_stroke_width_pt)}–{show(thresholds.max_stroke_width_pt)}pt"
+            if thresholds.max_stroke_width_pt is not None
+            else show(thresholds.min_stroke_width_pt, "pt")
+        )
+        table.add_row(
+            preset.name,
+            preset.description,
+            show(thresholds.min_dpi),
+            show(thresholds.min_short_side, "px"),
+            font_range,
+            stroke_range,
+            provenance,
+        )
+
+    console.print(table)
+    console.print(
+        "[dim]Names: " + ", ".join(available_preset_names()) + "[/dim]"
+    )
+    console.print(
+        "[dim]Convenience presets are not publisher policies. "
+        "Source-verified publisher presets show official source metadata.[/dim]"
+    )
+
+
+@app.command()
+def check(
+    target: Path = typer.Argument(
+        ...,
+        exists=True,
+        readable=True,
+        help="Figure file or directory to inspect.",
+    ),
+    preset: str = typer.Option(
+        "default",
+        "--preset",
+        help="Named threshold preset. Run 'figurelint presets' to list profiles.",
+    ),
+    min_dpi: Optional[int] = typer.Option(
+        None,
+        "--min-dpi",
+        min=1,
+        help="Override the preset minimum raster/effective PDF image DPI.",
+    ),
+    min_short_side: Optional[int] = typer.Option(
+        None,
+        "--min-short-side",
+        min=1,
+        help="Override the preset minimum raster short side in pixels.",
+    ),
+    min_font_size_pt: Optional[float] = typer.Option(
+        None,
+        "--min-font-size-pt",
+        min=0.1,
+        help="Override the preset minimum resolvable SVG font size in points.",
+    ),
+    max_font_size_pt: Optional[float] = typer.Option(
+        None,
+        "--max-font-size-pt",
+        min=0.1,
+        help="Override the preset maximum resolvable SVG font size in points.",
+    ),
+    min_stroke_width_pt: Optional[float] = typer.Option(
+        None,
+        "--min-stroke-width-pt",
+        min=0.01,
+        help="Override the preset minimum resolvable SVG stroke width in points.",
+    ),
+    max_stroke_width_pt: Optional[float] = typer.Option(
+        None,
+        "--max-stroke-width-pt",
+        min=0.01,
+        help="Override the preset maximum resolvable SVG stroke width in points.",
+    ),
+    min_pdf_short_side_in: Optional[float] = typer.Option(
+        None,
+        "--min-pdf-short-side-in",
+        min=0.01,
+        help="Override the preset minimum PDF page short side in inches.",
+    ),
+    max_pdf_long_side_in: Optional[float] = typer.Option(
+        None,
+        "--max-pdf-long-side-in",
+        min=0.1,
+        help="Override the preset maximum PDF page long side in inches.",
+    ),
+    github_annotations: bool = typer.Option(
+        False,
+        "--github-annotations",
+        help="Emit GitHub Actions workflow annotations for findings.",
+    ),
+    strict: bool = typer.Option(
+        False,
+        "--strict",
+        help="Exit with code 1 when warnings are present.",
+    ),
+) -> None:
+    """Check one figure or every supported figure in a directory."""
+    try:
+        active_preset, thresholds = resolve_thresholds(
+            preset,
+            min_dpi=min_dpi,
+            min_short_side=min_short_side,
+            min_font_size_pt=min_font_size_pt,
+            max_font_size_pt=max_font_size_pt,
+            min_stroke_width_pt=min_stroke_width_pt,
+            max_stroke_width_pt=max_stroke_width_pt,
+            min_pdf_short_side_in=min_pdf_short_side_in,
+            max_pdf_long_side_in=max_pdf_long_side_in,
+        )
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc), param_hint="--preset") from exc
+
+    files = collect_figure_files(target)
+
+    if not files:
+        console.print("[yellow]No supported PNG/JPEG/SVG/PDF figures found.[/yellow]")
+        raise typer.Exit(code=0)
+
+    override_values = (
+        min_dpi,
+        min_short_side,
+        min_font_size_pt,
+        max_font_size_pt,
+        min_stroke_width_pt,
+        max_stroke_width_pt,
+        min_pdf_short_side_in,
+        max_pdf_long_side_in,
+    )
+    override_suffix = (
+        " + CLI overrides"
+        if any(value is not None for value in override_values)
+        else ""
+    )
+    console.print(f"[dim]Preset: {active_preset.name}{override_suffix}[/dim]")
+    if active_preset.is_publisher_verified and active_preset.source_url:
+        console.print(f"[dim]Official source: {active_preset.source_url}[/dim]")
+
+    table = Table(title="FigureLint")
+    table.add_column("File", overflow="fold")
+    table.add_column("Severity")
+    table.add_column("Code", min_width=26, no_wrap=True)
+    table.add_column("Message", overflow="fold")
+
+    error_count = 0
+    warning_count = 0
+
+    for path in files:
+        suffix = path.suffix.lower()
+        if suffix == ".svg":
+            svg_policy = active_preset.svg_policy
+            findings = check_svg(
+                path,
+                min_font_size_pt=thresholds.min_font_size_pt,
+                max_font_size_pt=thresholds.max_font_size_pt,
+                min_stroke_width_pt=thresholds.min_stroke_width_pt,
+                max_stroke_width_pt=thresholds.max_stroke_width_pt,
+                panel_label_size_pt=(
+                    svg_policy.panel_label_size_pt if svg_policy else None
+                ),
+                panel_label_require_bold=(
+                    svg_policy.panel_label_require_bold if svg_policy else False
+                ),
+                panel_label_require_upright=(
+                    svg_policy.panel_label_require_upright if svg_policy else False
+                ),
+                preferred_font_families=(
+                    svg_policy.preferred_font_families if svg_policy else ()
+                ),
+                require_consistent_font_family=(
+                    svg_policy.require_consistent_font_family
+                    if svg_policy
+                    else False
+                ),
+            )
+        elif suffix == ".pdf":
+            findings = check_pdf(
+                path,
+                min_image_dpi=thresholds.min_dpi,
+                min_page_short_side_in=thresholds.min_pdf_short_side_in,
+                max_page_long_side_in=thresholds.max_pdf_long_side_in,
+            )
+        else:
+            findings = check_raster(
+                path,
+                min_dpi=thresholds.min_dpi,
+                min_short_side=thresholds.min_short_side,
+            )
+
+        if not findings:
+            table.add_row(str(path), "pass", "OK", "No findings.")
+            continue
+
+        for finding in findings:
+            if finding.severity is Severity.ERROR:
+                error_count += 1
+            elif finding.severity is Severity.WARNING:
+                warning_count += 1
+
+            table.add_row(
+                str(finding.path),
+                finding.severity.value,
+                finding.code,
+                finding.message,
+            )
+            if github_annotations:
+                typer.echo(format_github_annotation(finding))
+
+    console.print(table)
+    console.print(
+        f"Checked {len(files)} file(s): "
+        f"{error_count} error(s), {warning_count} warning(s)."
+    )
+
+    if error_count:
+        raise typer.Exit(code=2)
+    if strict and warning_count:
+        raise typer.Exit(code=1)
+
+
+if __name__ == "__main__":
+    app()

figurelint/github_annotations.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .models import Finding, Severity
+
+
+def _escape_data(value: str) -> str:
+    return (
+        value.replace("%", "%25")
+        .replace("\r", "%0D")
+        .replace("\n", "%0A")
+    )
+
+
+def _escape_property(value: str) -> str:
+    return (
+        _escape_data(value)
+        .replace(":", "%3A")
+        .replace(",", "%2C")
+    )
+
+
+def _annotation_level(severity: Severity) -> str:
+    if severity is Severity.ERROR:
+        return "error"
+    if severity is Severity.WARNING:
+        return "warning"
+    return "notice"
+
+
+def _annotation_path(path: Path) -> str:
+    try:
+        relative = path.resolve().relative_to(Path.cwd().resolve())
+        return relative.as_posix()
+    except (OSError, ValueError):
+        return path.as_posix()
+
+
+def format_github_annotation(finding: Finding) -> str:
+    """Format a finding as a GitHub Actions workflow command."""
+    level = _annotation_level(finding.severity)
+    path = _escape_property(_annotation_path(finding.path))
+    title = _escape_property(finding.code)
+    message = _escape_data(finding.message)
+    return f"::{level} file={path},title={title}::{message}"

figurelint/models.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class Severity(str, Enum):
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class Finding:
+    path: Path
+    severity: Severity
+    code: str
+    message: str