medsci-skills 4.1.0

package/skills/make-figures/scripts/build_strobe_template.py

@@ -0,0 +1,351 @@
+#!/usr/bin/env python3
+"""Build an editable STROBE participant flow diagram (.pptx) from a YAML config.
+
+Why this script exists
+----------------------
+The Graphviz path (``generate_flow_diagram.R --type strobe``) renders an
+auto-fitting monochrome diagram suitable for journal submission, but
+co-authors often want to nudge box positions, edit prose, or recolor stage
+labels in PowerPoint. This script produces a fully-editable .pptx in the
+classical Identification → Screening → Inclusion → Analysis convention used
+by the BMJ / Radiology / KJR cohort-study examples (Randolph 2018,
+PLoS ONE 2021).
+
+Unlike PRISMA, STROBE flow diagrams have study-specific spine structure
+(number of cohort-stage boxes and exclusions varies per study), so this is
+a single parametric builder rather than the PRISMA two-step
+(``build_prisma2020_template.py`` then ``fill_prisma_template.py``).
+
+YAML schema
+-----------
+    output_pptx: figures/figure1_strobe.pptx          # required
+    slide_size: [10.5, 11.0]                           # inches; auto-computed if omitted
+    title: "Figure 1. STROBE participant flow diagram"  # optional
+
+    # `stages:` is OPTIONAL. STROBE itself does not mandate a phase column —
+    # most cohort papers omit it (the column is a PRISMA 2020 convention). When
+    # `stages:` is present, the script renders a left phase column and merges
+    # consecutive same-stage spine rows under one label. When omitted (or empty),
+    # the spine shifts left, the slide narrows, and the figure looks like the
+    # plainer STROBE convention.
+    stages:
+      - {name: Identification, color: "#cfe1f5"}      # color = stage box fill
+      - {name: Screening,      color: "#cfe1f5"}
+      - {name: Inclusion,      color: "#cfe1f5"}
+      - {name: Analysis,       color: "#cfe1f5"}
+    spine:
+      - {id: enrolled,  stage: Identification, text: "..."}
+      - {id: screened,  stage: Screening,      text: "..."}
+      - {id: eligible,  stage: Inclusion,      text: "..."}
+      - {id: primary,   stage: Analysis,       text: "..."}
+      - {id: landmark,  stage: Analysis,       text: "..."}  # consecutive same-stage rows share one stage label
+    exclusions:
+      - {after: enrolled, text: "Excluded (n = 1,200):\\n- did not meet the index finding on any screening"}
+      - {after: screened, text: "Excluded (n = 3):\\n- prior outcome event / zero post-baseline follow-up"}
+
+Usage
+-----
+    python3 build_strobe_template.py \
+        --config figures/figure1_strobe.yaml \
+        --out    figures/figure1_strobe.pptx
+
+Open the resulting .pptx in PowerPoint to fine-tune positions or styling
+before saving as PDF / TIFF for submission.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+    HAS_YAML = True
+except ImportError:
+    HAS_YAML = False
+
+from lxml import etree
+from pptx import Presentation
+from pptx.dml.color import RGBColor
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.enum.text import MSO_ANCHOR, PP_ALIGN
+from pptx.oxml.ns import qn
+from pptx.util import Inches, Pt
+
+
+# ── Defaults ────────────────────────────────────────────────────────────────
+DEFAULT_SLIDE_W = 10.5    # default width when slide_size unset; height auto-computed
+FALLBACK_SLIDE_H = 11.0   # only used if auto-compute can't fit
+ABSOLUTE_MAX_SLIDE_H = 14.0  # PowerPoint hard upper bound for legible single-slide layouts
+
+# Column geometry (inches) — tighter than widescreen; better for vertical flow
+PHASE_X = 0.4
+PHASE_W = 1.4
+SPINE_X = 2.2
+SPINE_W = 3.6
+EXCL_X  = 6.4
+EXCL_W  = 3.7
+
+# Vertical spacing
+TITLE_Y = 0.25
+TITLE_H = 0.5
+TOP_PAD = 0.35           # below title before first row
+ROW_GAP = 0.35           # vertical gap between adjacent rows
+DEFAULT_ROW_H = 1.20     # slightly taller boxes for better text breathing room
+DEFAULT_EXCL_H = 1.05
+BOTTOM_PAD = 0.4         # margin below last row
+
+# Colors
+NAVY   = RGBColor(0x1F, 0x3A, 0x68)
+WHITE  = RGBColor(0xFF, 0xFF, 0xFF)
+BLACK  = RGBColor(0x00, 0x00, 0x00)
+LBLUE  = RGBColor(0xCF, 0xE1, 0xF5)
+
+
+# ── Helpers ─────────────────────────────────────────────────────────────────
+def _parse_color(hex_str: str | None, default: RGBColor) -> RGBColor:
+    if not hex_str:
+        return default
+    h = hex_str.lstrip("#")
+    return RGBColor(int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
+
+
+def _readable_text_color(bg: RGBColor) -> RGBColor:
+    """Return BLACK or WHITE depending on background luminance."""
+    # Relative luminance per WCAG (sRGB approx without gamma)
+    r, g, b = bg[0], bg[1], bg[2]
+    lum = 0.299 * r + 0.587 * g + 0.114 * b
+    return RGBColor(0x1F, 0x3A, 0x68) if lum > 160 else WHITE
+
+
+def add_box(slide, x, y, w, h, text, *,
+            fill=WHITE, border=BLACK, font_color=BLACK,
+            font_size=11, bold_first=True, anchor_middle=True,
+            align_center=True, line_pt=1.0, dash=False):
+    shape = slide.shapes.add_shape(
+        MSO_SHAPE.ROUNDED_RECTANGLE,
+        Inches(x), Inches(y), Inches(w), Inches(h),
+    )
+    shape.fill.solid()
+    shape.fill.fore_color.rgb = fill
+    shape.line.color.rgb = border
+    shape.line.width = Pt(line_pt)
+    if dash:
+        ln = shape.line._get_or_add_ln()
+        # Remove any existing prstDash to keep idempotent
+        for existing in ln.findall(qn("a:prstDash")):
+            ln.remove(existing)
+        prst = etree.SubElement(ln, qn("a:prstDash"))
+        prst.set("val", "dash")
+
+    tf = shape.text_frame
+    tf.word_wrap = True
+    tf.margin_left = tf.margin_right = Inches(0.10)
+    tf.margin_top = tf.margin_bottom = Inches(0.06)
+    if anchor_middle:
+        tf.vertical_anchor = MSO_ANCHOR.MIDDLE
+
+    lines = str(text).split("\n")
+    for i, line in enumerate(lines):
+        para = tf.paragraphs[0] if i == 0 else tf.add_paragraph()
+        para.alignment = PP_ALIGN.CENTER if align_center else PP_ALIGN.LEFT
+        run = para.add_run()
+        run.text = line
+        run.font.size = Pt(font_size)
+        run.font.color.rgb = font_color
+        run.font.bold = bool(bold_first and i == 0)
+    return shape
+
+
+def add_arrow(slide, x1, y1, x2, y2, *, color=BLACK, width_pt=1.25):
+    line = slide.shapes.add_connector(1, Inches(x1), Inches(y1), Inches(x2), Inches(y2))
+    line.line.color.rgb = color
+    line.line.width = Pt(width_pt)
+    # Arrow head on the destination end
+    line_xml = line.line._get_or_add_ln()
+    tail = etree.SubElement(line_xml, qn("a:tailEnd"))
+    tail.set("type", "triangle")
+    tail.set("w", "med")
+    tail.set("len", "med")
+
+
+def add_right_angle_arrow(slide, x1, y1, x2, y2, *, color=BLACK, width_pt=1.0):
+    """Spine right edge → exclusion left edge with a horizontal stub then arrow."""
+    # Use a single straight horizontal connector since both ends share y
+    add_arrow(slide, x1, y1, x2, y2, color=color, width_pt=width_pt)
+
+
+# ── Loader ──────────────────────────────────────────────────────────────────
+def load_config(path: Path) -> dict:
+    text = path.read_text(encoding="utf-8")
+    if path.suffix in (".yaml", ".yml"):
+        if not HAS_YAML:
+            sys.exit("PyYAML not installed; install or use JSON config.")
+        return yaml.safe_load(text)
+    if path.suffix == ".json":
+        return json.loads(text)
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        if HAS_YAML:
+            return yaml.safe_load(text)
+        sys.exit("Config not JSON and PyYAML unavailable.")
+
+
+# ── Builder ────────────────────────────────────────────────────────────────
+def build(cfg: dict, out_path: Path) -> None:
+    # Layout dimensions decided BEFORE slide creation so we can right-size the
+    # canvas to the content (no large empty bottom strip).
+    spine = cfg["spine"]
+    n_spine = len(spine)
+    spine_h = float(cfg.get("spine_box_height", DEFAULT_ROW_H))
+    excl_h  = float(cfg.get("exclusion_box_height", DEFAULT_EXCL_H))
+    title_text = cfg.get("title")
+
+    # Phase column is optional. STROBE itself does not mandate one (PRISMA does);
+    # most cohort papers omit it. Render only when the user supplies a non-empty
+    # `stages:` list in the YAML config.
+    stages_cfg = cfg.get("stages") or []
+    has_phase_column = bool(stages_cfg)
+
+    # Effective horizontal positions (collapse left margin when no phase column)
+    if has_phase_column:
+        spine_x_eff = SPINE_X
+        excl_x_eff  = EXCL_X
+    else:
+        excl_gap = EXCL_X - SPINE_X - SPINE_W   # preserve the spine→excl gap
+        spine_x_eff = PHASE_X
+        excl_x_eff  = spine_x_eff + SPINE_W + excl_gap
+
+    avail_top = TITLE_Y + TITLE_H + TOP_PAD if title_text else TITLE_Y
+    row_pitch = spine_h + ROW_GAP
+    last_row_end = avail_top + (n_spine - 1) * row_pitch + spine_h
+    auto_h = last_row_end + BOTTOM_PAD
+    auto_w = excl_x_eff + EXCL_W + PHASE_X      # right margin == left margin
+
+    if "slide_size" in cfg:
+        slide_w, slide_h = cfg["slide_size"]
+    else:
+        slide_w = max(auto_w, 4.0)
+        slide_h = min(max(auto_h, 4.0), ABSOLUTE_MAX_SLIDE_H)
+
+    # If the user gave a slide_size that's too short for the content, scale boxes down
+    needed = last_row_end + BOTTOM_PAD
+    if needed > slide_h:
+        scale = (slide_h - avail_top - BOTTOM_PAD) / (n_spine * row_pitch - ROW_GAP)
+        spine_h = max(0.7, spine_h * scale)
+        excl_h  = max(0.6, excl_h * scale)
+        row_pitch = spine_h + ROW_GAP
+
+    prs = Presentation()
+    prs.slide_width = Inches(slide_w)
+    prs.slide_height = Inches(slide_h)
+    blank_layout = prs.slide_layouts[6]
+    slide = prs.slides.add_slide(blank_layout)
+
+    # Title
+    if title_text:
+        title_box = slide.shapes.add_textbox(
+            Inches(PHASE_X), Inches(TITLE_Y),
+            Inches(slide_w - PHASE_X * 2), Inches(TITLE_H),
+        )
+        tf = title_box.text_frame
+        p = tf.paragraphs[0]
+        run = p.add_run()
+        run.text = title_text
+        run.font.size = Pt(13)
+        run.font.bold = True
+        run.font.color.rgb = NAVY
+
+    spine_y = {}
+    for i, b in enumerate(spine):
+        spine_y[b["id"]] = avail_top + i * row_pitch
+
+    # Phase column (optional) — group consecutive same-stage rows under one merged label.
+    if has_phase_column:
+        stage_color_lookup = {s["name"]: _parse_color(s.get("color"), NAVY) for s in stages_cfg}
+        stages_seq = [b.get("stage") for b in spine]
+        i = 0
+        while i < n_spine:
+            j = i
+            while j + 1 < n_spine and stages_seq[j + 1] == stages_seq[i]:
+                j += 1
+            sname = stages_seq[i]
+            y_top = spine_y[spine[i]["id"]]
+            y_bot = spine_y[spine[j]["id"]] + spine_h
+            h = y_bot - y_top
+            stage_fill = stage_color_lookup.get(sname, NAVY)
+            add_box(
+                slide, PHASE_X, y_top, PHASE_W, h,
+                sname,
+                fill=stage_fill,
+                border=stage_fill,
+                font_color=_readable_text_color(stage_fill),
+                font_size=14,
+                bold_first=True,
+                line_pt=0.0,
+            )
+            i = j + 1
+
+    # Spine boxes + arrows
+    for k, b in enumerate(spine):
+        y = spine_y[b["id"]]
+        add_box(
+            slide, spine_x_eff, y, SPINE_W, spine_h,
+            b["text"],
+            fill=WHITE, border=BLACK, font_color=BLACK,
+            font_size=11, bold_first=True,
+        )
+        if k > 0:
+            prev_y = spine_y[spine[k - 1]["id"]]
+            add_arrow(
+                slide,
+                spine_x_eff + SPINE_W / 2, prev_y + spine_h,
+                spine_x_eff + SPINE_W / 2, y,
+            )
+
+    # Exclusion boxes + connector arrows
+    # Vertically center each exclusion on its spine row's mid-height so the
+    # connector arrow can be strictly horizontal (no diagonal segments).
+    for excl in cfg.get("exclusions", []):
+        after_id = excl["after"]
+        y_after = spine_y[after_id]
+        y_mid = y_after + spine_h / 2
+        y_excl_top = y_mid - excl_h / 2
+        add_box(
+            slide, excl_x_eff, y_excl_top, EXCL_W, excl_h,
+            excl["text"],
+            fill=WHITE, border=BLACK, font_color=BLACK,
+            font_size=10, bold_first=False,
+            align_center=False,  # left-align text in exclusions
+            dash=True,           # dashed border to visually distinguish exclusion side-branches
+        )
+        # Strictly horizontal connector: both endpoints at y_mid
+        add_arrow(
+            slide,
+            spine_x_eff + SPINE_W, y_mid,
+            excl_x_eff,            y_mid,
+        )
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    prs.save(out_path)
+
+
+# ── CLI ─────────────────────────────────────────────────────────────────────
+def main():
+    p = argparse.ArgumentParser(description="Build an editable STROBE flow diagram .pptx from a YAML config.")
+    p.add_argument("--config", required=True, type=Path, help="YAML/JSON STROBE config")
+    p.add_argument("--out",    required=True, type=Path, help="Output .pptx path")
+    args = p.parse_args()
+
+    cfg = load_config(args.config)
+    if not isinstance(cfg, dict):
+        sys.exit(f"Config root must be a mapping; got {type(cfg)}")
+
+    build(cfg, args.out)
+    print(f"Wrote {args.out}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/make-figures/scripts/critic_figure.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""critic_figure.py — Quantitative checks for make-figures skill output.
+
+Part of the medsci-skills Critic Loop (Phase 1). This script runs deterministic
+checks that do NOT require a language model:
+
+  - DPI and physical dimensions vs. journal specification
+  - Dominant-color analysis against the Wong colorblind-safe palette
+  - OCR text extraction for minimum font-size estimation and
+    optional coverage comparison against a source-text file
+
+The qualitative side of the Critic Loop (layout balance, hierarchy,
+readability, exemplar comparison) is handled by the Claude session afterward
+using the rubrics in references/critic_rubrics/.
+
+Usage:
+    python critic_figure.py figures/fig1_stard.png \
+        --type stard --spec-min-dpi 600 --spec-width-in 7.0 \
+        --source-text figures/fig1_stard.txt \
+        --out figures/fig1_stard.critique.json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+from PIL import Image
+
+WONG_PALETTE: dict[str, tuple[int, int, int]] = {
+    "black":          (0, 0, 0),
+    "orange":         (230, 159, 0),
+    "sky_blue":       (86, 180, 233),
+    "bluish_green":   (0, 158, 115),
+    "yellow":         (240, 228, 66),
+    "blue":           (0, 114, 178),
+    "vermillion":     (213, 94, 0),
+    "reddish_purple": (204, 121, 167),
+}
+NEUTRAL_TOLERANCE = 25
+PALETTE_DISTANCE_THRESHOLD = 60
+DOMINANT_COLOR_TOP_N = 12
+DOMINANT_COLOR_MIN_FRACTION = 0.002
+OUT_OF_PALETTE_TOLERANCE = 0.15
+MIN_READABLE_PX = 14
+
+
+def color_distance(c1, c2) -> float:
+    return sum((a - b) ** 2 for a, b in zip(c1, c2)) ** 0.5
+
+
+def classify_color(rgb) -> str:
+    r, g, b = rgb
+    if max(r, g, b) - min(r, g, b) < NEUTRAL_TOLERANCE:
+        return "neutral"
+    best_name, best_dist = None, float("inf")
+    for name, palette_rgb in WONG_PALETTE.items():
+        d = color_distance(rgb, palette_rgb)
+        if d < best_dist:
+            best_name, best_dist = name, d
+    if best_dist < PALETTE_DISTANCE_THRESHOLD:
+        return f"wong:{best_name}"
+    return "out_of_palette"
+
+
+def check_palette(img: Image.Image) -> dict:
+    rgb_img = img.convert("RGB")
+    total = rgb_img.size[0] * rgb_img.size[1]
+    quant = rgb_img.quantize(colors=64).convert("RGB")
+    pixels = quant.getcolors(maxcolors=64 * 64)
+    if not pixels:
+        return {"passed": None, "note": "too many colors to quantize"}
+
+    dominant = []
+    out_frac = 0.0
+    for count, rgb in sorted(pixels, key=lambda x: -x[0])[:DOMINANT_COLOR_TOP_N]:
+        fraction = count / total
+        if fraction < DOMINANT_COLOR_MIN_FRACTION:
+            continue
+        label = classify_color(rgb)
+        dominant.append({"rgb": list(rgb), "fraction": round(fraction, 4), "class": label})
+        if label == "out_of_palette":
+            out_frac += fraction
+
+    return {
+        "passed": out_frac < OUT_OF_PALETTE_TOLERANCE,
+        "out_of_palette_fraction": round(out_frac, 4),
+        "tolerance": OUT_OF_PALETTE_TOLERANCE,
+        "dominant_colors": dominant,
+    }
+
+
+def check_dimensions(img: Image.Image, spec: dict) -> dict:
+    w_px, h_px = img.size
+    dpi = img.info.get("dpi", (None, None))
+    dpi_x = dpi[0] if dpi and dpi[0] else None
+    dpi_y = dpi[1] if dpi and dpi[1] else None
+    result = {
+        "width_px": w_px,
+        "height_px": h_px,
+        "dpi_x": dpi_x,
+        "dpi_y": dpi_y,
+    }
+    min_dpi = spec.get("min_dpi")
+    width_in = spec.get("width_in")
+    if min_dpi and dpi_x:
+        result["dpi_meets_spec"] = dpi_x >= min_dpi
+        result["required_dpi"] = min_dpi
+    if width_in and dpi_x:
+        actual_width_in = w_px / dpi_x
+        result["width_in"] = round(actual_width_in, 2)
+        result["width_matches_spec"] = abs(actual_width_in - width_in) < 0.3
+        result["required_width_in"] = width_in
+    return result
+
+
+def check_ocr(image_path: Path, source_text: Optional[str] = None) -> dict:
+    try:
+        import pytesseract
+    except ImportError:
+        return {"passed": None, "note": "pytesseract not installed; install with `pip install pytesseract` (tesseract binary already at /opt/homebrew/bin/tesseract)"}
+    try:
+        data = pytesseract.image_to_data(
+            str(image_path), output_type=pytesseract.Output.DICT
+        )
+    except Exception as exc:
+        return {"passed": None, "note": f"tesseract failed: {exc}"}
+
+    words = []
+    heights = []
+    for i, word in enumerate(data.get("text", [])):
+        if not word.strip():
+            continue
+        conf_raw = data["conf"][i]
+        try:
+            conf = int(conf_raw)
+        except (TypeError, ValueError):
+            conf = -1
+        if conf < 50:
+            continue
+        words.append(word.strip())
+        heights.append(data["height"][i])
+
+    result: dict = {
+        "word_count": len(words),
+    }
+    if heights:
+        heights_sorted = sorted(heights)
+        result["median_word_height_px"] = heights_sorted[len(heights_sorted) // 2]
+        result["min_word_height_px"] = min(heights)
+        result["min_readable_threshold_px"] = MIN_READABLE_PX
+
+    if source_text:
+        source_words = {w.lower().strip(".,:;()[]") for w in source_text.split() if len(w) > 2}
+        ocr_words = {w.lower().strip(".,:;()[]") for w in words if len(w) > 2}
+        missing = sorted(source_words - ocr_words)
+        result["missing_source_words"] = missing[:20]
+        result["missing_source_word_count"] = len(missing)
+        result["source_word_coverage"] = round(
+            len(source_words & ocr_words) / max(1, len(source_words)), 2
+        )
+    return result
+
+
+def critique(
+    image_path: Path,
+    figure_type: Optional[str] = None,
+    journal: Optional[str] = None,
+    source_text: Optional[str] = None,
+    spec: Optional[dict] = None,
+) -> dict:
+    img = Image.open(image_path)
+    spec = spec or {}
+    checks = {
+        "dimensions": check_dimensions(img, spec),
+        "palette": check_palette(img),
+        "ocr": check_ocr(image_path, source_text=source_text),
+    }
+
+    flags = []
+    dim = checks["dimensions"]
+    if dim.get("dpi_meets_spec") is False:
+        flags.append(
+            f"DPI below journal spec ({dim.get('dpi_x')} < {dim.get('required_dpi')})"
+        )
+    if dim.get("width_matches_spec") is False:
+        flags.append(
+            f"Width deviates from journal spec ({dim.get('width_in')} in vs {dim.get('required_width_in')} in)"
+        )
+    pal = checks["palette"]
+    if pal.get("passed") is False:
+        flags.append(
+            f"{pal['out_of_palette_fraction'] * 100:.1f}% pixels outside Wong palette (tolerance {OUT_OF_PALETTE_TOLERANCE * 100:.0f}%)"
+        )
+    ocr = checks["ocr"]
+    min_h = ocr.get("min_word_height_px")
+    if min_h and min_h < MIN_READABLE_PX:
+        flags.append(f"Smallest OCR text only {min_h}px tall (<{MIN_READABLE_PX}px threshold)")
+    if ocr.get("missing_source_word_count") and ocr["missing_source_word_count"] > 3:
+        flags.append(
+            f"{ocr['missing_source_word_count']} source words not detected by OCR (possible cropping/truncation)"
+        )
+
+    return {
+        "image": str(image_path),
+        "figure_type": figure_type,
+        "journal": journal,
+        "checks": checks,
+        "flags": flags,
+        "summary": "PASS" if not flags else f"{len(flags)} issue(s) flagged",
+    }
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Quantitative figure critic (medsci-skills Critic Loop, Phase 1).")
+    p.add_argument("image", help="Path to generated figure (PNG)")
+    p.add_argument(
+        "--type", dest="figure_type",
+        choices=[
+            "stard", "consort", "prisma", "pipeline",
+            "roc", "forest", "km", "calibration",
+            "bland_altman", "confusion_matrix",
+            "visual_abstract", "other",
+        ],
+    )
+    p.add_argument("--journal", help="Journal key (e.g., radiology, radiology_ai, eur_radiol)")
+    p.add_argument("--source-text", help="Path to text file with expected source strings for OCR coverage check")
+    p.add_argument("--spec-width-in", type=float, help="Expected figure width in inches (per figure_specs.md)")
+    p.add_argument("--spec-min-dpi", type=int, help="Minimum DPI (600 for line art, 300 for halftone)")
+    p.add_argument("--out", default=None, help="Path to JSON report (default: {image}.critique.json)")
+    args = p.parse_args()
+
+    image_path = Path(args.image)
+    if not image_path.exists():
+        print(f"ERROR: {image_path} not found", file=sys.stderr)
+        return 2
+
+    source_text = None
+    if args.source_text:
+        source_path = Path(args.source_text)
+        if not source_path.exists():
+            print(f"WARN: source text {source_path} not found; skipping OCR coverage check", file=sys.stderr)
+        else:
+            source_text = source_path.read_text(encoding="utf-8", errors="ignore")
+
+    report = critique(
+        image_path,
+        figure_type=args.figure_type,
+        journal=args.journal,
+        source_text=source_text,
+        spec={"width_in": args.spec_width_in, "min_dpi": args.spec_min_dpi},
+    )
+    out_path = Path(args.out) if args.out else image_path.with_suffix(image_path.suffix + ".critique.json")
+    out_path.write_text(json.dumps(report, indent=2, ensure_ascii=False))
+
+    print(json.dumps({"summary": report["summary"], "flags": report["flags"]}, indent=2, ensure_ascii=False))
+    print(f"\nFull report: {out_path}", file=sys.stderr)
+    return 0 if not report["flags"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())