proof-pdf 0.1.0__py3-none-any.whl

proof_pdf/__init__.py

@@ -0,0 +1,14 @@
+"""Print-PDF conformance verification.
+
+Wraps veraPDF (the PDF/A engine) and adds the checks veraPDF cannot make: the
+PDF/X-4 structural identity (page boxes, ``/Trapped``, the X output intent and
+XMP), the finished-page geometry, and best-effort colour sanity (total ink
+coverage, overprint, rich-black small text, stray RGB, effective image DPI).
+
+The entry point is :func:`proof_pdf.core.verify_file`; the CLI group lives in
+:mod:`proof_pdf.cli` and is the ``proof-pdf`` console script.
+
+The package takes PDF paths and nothing else. The finished-page geometry it checks
+against is a parameter (:class:`PageGeometry`) with no default, so a file from a
+printer is held to its own dimensions or the layer is skipped.
+"""

proof_pdf/cli.py

@@ -0,0 +1,300 @@
+"""The ``proof-pdf`` subcommands -- hold a print PDF to PDF/X-4 + PDF/A.
+
+``verify`` wraps veraPDF and adds the PDF/X-4, geometry and colour checks
+veraPDF cannot make. ``preview`` rasterises pages with the page-box guides drawn
+on, so a geometry finding can be seen rather than only read.
+
+Both take files or directories; a directory expands to every PDF beneath it,
+minus anything matching ``--exclude`` (``core.expand_targets``).
+The commands take paths only, so a file a printer sends back can be checked
+the same way a freshly built one is.
+"""
+
+import dataclasses
+import importlib.metadata
+import json
+import logging
+import os
+import pathlib
+import typing
+
+import typer
+
+from . import core, preview, verapdf
+from .models import (
+    DEFAULT_MAX_TAC,
+    DEFAULT_MIN_DPI,
+    DEFAULT_SMALL_TEXT_PT,
+    FileReport,
+    Finding,
+    PageGeometry,
+    Profile,
+    Severity,
+)
+
+logger = logging.getLogger(__name__)
+
+pdf_app = typer.Typer(
+    pretty_exceptions_enable=False,
+    help="Verify and proof print PDFs (PDF/X-4 + PDF/A).",
+    no_args_is_help=True,
+)
+
+
+def version_string() -> str:
+    """``1.2.3``, plus ``(commit abc123)`` when the image or build recorded one in PROOFPRESS_REVISION."""
+    version = importlib.metadata.version("proof-pdf")
+    revision = os.environ.get("PROOFPRESS_REVISION")
+    return f"{version} (commit {revision[:12]})" if revision and revision != "unknown" else version
+
+
+def _show_version(value: bool) -> None:
+    # An eager option callback: click would otherwise reject a bare ``--version`` as a missing command.
+    if value:
+        typer.echo(f"proof-pdf {version_string()}")
+        raise typer.Exit()
+
+
+@pdf_app.callback()
+def _main(
+    version: typing.Annotated[
+        bool, typer.Option("--version", help="Show the version and exit.", callback=_show_version, is_eager=True)
+    ] = False,
+) -> None:
+    pass
+
+
+# A hung Ghostscript on a 400 MB file would otherwise block a CI run for ever.
+DEFAULT_TIMEOUT = 900.0
+
+_MARK = {
+    Severity.ERROR: typer.style("x", fg=typer.colors.RED),
+    Severity.WARN: typer.style("!", fg=typer.colors.YELLOW),
+}
+
+PathsArg = typing.Annotated[
+    list[pathlib.Path] | None,
+    typer.Argument(help="PDFs to process. A directory contributes every PDF beneath it."),
+]
+GsOpt = typing.Annotated[str, typer.Option("--gs", help="Ghostscript executable.")]
+TimeoutOpt = typing.Annotated[float, typer.Option("--timeout", help="Per-tool timeout, in seconds.")]
+ExcludeOpt = typing.Annotated[
+    list[str] | None,
+    typer.Option("--exclude", help="Glob, relative to a directory argument, of PDFs to skip. Repeatable."),
+]
+QuietOpt = typing.Annotated[bool, typer.Option("--quiet", help="Exit code only, for CI.")]
+
+
+@pdf_app.command("verify")
+def verify_cmd(
+    files: PathsArg = None,
+    exclude: ExcludeOpt = None,
+    flavour: typing.Annotated[
+        str, typer.Option("--flavour", help="veraPDF PDF/A flavour: 2b, 2a, 2u, 1b, 3b, 4...")
+    ] = "2b",
+    pdfa: typing.Annotated[bool, typer.Option("--pdfa/--no-pdfa", help="Run the veraPDF PDF/A layer.")] = True,
+    pdfx: typing.Annotated[bool, typer.Option("--pdfx/--no-pdfx", help="Check the PDF/X-4 identity.")] = True,
+    colour: typing.Annotated[
+        bool, typer.Option("--colour/--no-colour", help="Check ink, overprint, RGB, rich black and image DPI.")
+    ] = True,
+    trim_mm: typing.Annotated[
+        str | None,
+        typer.Option(
+            "--trim-mm", help="Expected finished size as WxH in mm, e.g. 105x148. Enables the geometry layer."
+        ),
+    ] = None,
+    bleed_mm: typing.Annotated[float, typer.Option("--bleed-mm", help="Expected bleed per side, in mm.")] = 3.0,
+    tolerance_mm: typing.Annotated[
+        float, typer.Option("--tolerance-mm", help="Allowed geometry deviation, in mm.")
+    ] = 0.25,
+    max_tac: typing.Annotated[
+        float, typer.Option("--max-tac", help="Total-ink-coverage ceiling, in percent.")
+    ] = DEFAULT_MAX_TAC,
+    small_text_pt: typing.Annotated[
+        float, typer.Option("--small-text-pt", help="Rich-black cutoff (pt).")
+    ] = DEFAULT_SMALL_TEXT_PT,
+    min_dpi: typing.Annotated[
+        float, typer.Option("--min-dpi", help="Minimum effective resolution for placed images.")
+    ] = DEFAULT_MIN_DPI,
+    strict_cmyk: typing.Annotated[
+        bool, typer.Option("--strict-cmyk", help="Fail, rather than warn, on RGB vector fills.")
+    ] = False,
+    verapdf_bin: typing.Annotated[str, typer.Option("--verapdf", help="veraPDF executable.")] = "verapdf",
+    gs_bin: GsOpt = "gs",
+    timeout: TimeoutOpt = DEFAULT_TIMEOUT,
+    as_json: typing.Annotated[
+        bool, typer.Option("--json", help="Emit machine-readable findings instead of a report.")
+    ] = False,
+    quiet: QuietOpt = False,
+) -> None:
+    """Verify each PDF is a valid dual PDF/X-4 + PDF/A file."""
+    targets = core.expand_targets(files or [], exclude or [])
+    if not targets:
+        typer.echo("no PDFs to verify", err=True)
+        raise typer.Exit(1)
+
+    profile = Profile(
+        flavour=flavour,
+        pdfa=pdfa,
+        pdfx=pdfx,
+        colour=colour,
+        geometry=_page_geometry(trim_mm, bleed_mm, tolerance_mm) if trim_mm else None,
+        max_tac=max_tac,
+        small_text_pt=small_text_pt,
+        min_dpi=min_dpi,
+        strict_cmyk=strict_cmyk,
+    )
+    reports = [core.verify_file(t, profile, verapdf_bin=verapdf_bin, gs_bin=gs_bin, timeout=timeout) for t in targets]
+
+    if as_json:
+        typer.echo(json.dumps([_as_record(r) for r in reports], indent=2))
+    elif not quiet:
+        for report in reports:
+            _print_report(report)
+        _print_summary(reports, profile)
+    raise typer.Exit(1 if any(not r.ok for r in reports) else 0)
+
+
+@pdf_app.command("preview")
+def preview_cmd(
+    files: PathsArg = None,
+    exclude: ExcludeOpt = None,
+    dpi: typing.Annotated[int, typer.Option("--dpi", help="Raster resolution.")] = 300,
+    guides: typing.Annotated[
+        bool, typer.Option("--guides/--no-guides", help="Draw trim/bleed/safe guides from the page boxes.")
+    ] = True,
+    safe_mm: typing.Annotated[float, typer.Option("--safe", help="Safe-area inset from the trim edge, in mm.")] = 3.0,
+    out: typing.Annotated[
+        pathlib.Path | None,
+        typer.Option("--out", help="Output directory (default: a preview/ folder beside each PDF)."),
+    ] = None,
+    gs_bin: GsOpt = "gs",
+    timeout: TimeoutOpt = DEFAULT_TIMEOUT,
+    quiet: QuietOpt = False,
+) -> None:
+    """Rasterise each PDF to one PNG per page, overlaying the page-box guides."""
+    targets = core.expand_targets(files or [], exclude or [])
+    if not targets:
+        typer.echo("no PDFs to preview", err=True)
+        raise typer.Exit(1)
+    if not preview.gs_available(gs_bin):
+        typer.echo(f"Ghostscript not found ({gs_bin}) -- cannot render previews", err=True)
+        raise typer.Exit(1)
+
+    written: list[pathlib.Path] = []
+    for target in targets:
+        dst = out if out is not None else target.parent / "preview"
+        try:
+            pngs = preview.preview_file(
+                target, dst, dpi=dpi, guides=guides, safe_mm=safe_mm, gs_bin=gs_bin, timeout=timeout
+            )
+        except preview.GhostscriptError as exc:
+            typer.secho(f"FAIL -- Ghostscript could not render {_rel(target)}: {exc}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(1) from exc
+        written += pngs
+        if not quiet:
+            for png in pngs:
+                typer.echo(f"wrote {_rel(png)}")
+    if not quiet:
+        note = " with trim/bleed/safe guides" if guides else ""
+        typer.secho(f"\nOK -- {len(written)} page(s){note} from {len(targets)} file(s)", fg=typer.colors.GREEN)
+
+
+def _page_geometry(trim_mm: str, bleed_mm: float, tolerance_mm: float) -> PageGeometry:
+    """Parse ``--trim-mm WxH`` into a :class:`PageGeometry`."""
+    parts = trim_mm.lower().replace("*", "x").split("x")
+    if len(parts) != 2:
+        raise typer.BadParameter(f"--trim-mm must look like 105x148, got {trim_mm!r}")
+    try:
+        width, height = (float(p) for p in parts)
+    except ValueError as exc:
+        raise typer.BadParameter(f"--trim-mm must be two numbers, got {trim_mm!r}") from exc
+    if width <= 0 or height <= 0:
+        raise typer.BadParameter(f"--trim-mm must be positive, got {trim_mm!r}")
+    return PageGeometry(trim_w_mm=width, trim_h_mm=height, bleed_mm=bleed_mm, tolerance_mm=tolerance_mm)
+
+
+def _rel(path: pathlib.Path) -> str:
+    """*path* relative to the working directory when that is shorter to read."""
+    try:
+        return str(path.resolve().relative_to(pathlib.Path.cwd()))
+    except ValueError:  # outside the working tree -- an absolute path is the clearest thing to show
+        return str(path)
+
+
+def _as_record(report: FileReport) -> dict:
+    return {
+        "path": str(report.path),
+        "ok": report.ok,
+        "findings": [dataclasses.asdict(f) for f in report.findings],
+    }
+
+
+def _print_report(report: FileReport) -> None:
+    status = typer.style("OK", fg=typer.colors.GREEN) if report.ok else typer.style("FAIL", fg=typer.colors.RED)
+    typer.echo(f"  {_rel(report.path):<52} {status}")
+    for finding, pages in _collapse(report.findings):
+        typer.echo(f"      {_MARK[finding.severity]} {_labelled(finding, pages)}")
+
+
+def _collapse(findings: list[Finding]) -> list[tuple[Finding, list[int]]]:
+    """Group findings that differ only by page number, preserving first-seen order.
+
+    A job says the same thing about all fifty of its cards. Printed one line per
+    page that is a hundred lines of noise burying whatever else was found, so the
+    identical ones collapse into a single line naming the pages.
+    """
+    grouped: dict[tuple[str, Severity, str], list[int]] = {}
+    first: dict[tuple[str, Severity, str], Finding] = {}
+    for finding in findings:
+        key = (finding.check, finding.severity, finding.message)
+        first.setdefault(key, finding)
+        if finding.page is not None:
+            grouped.setdefault(key, []).append(finding.page)
+        else:
+            grouped.setdefault(key, [])
+    return [(first[key], pages) for key, pages in grouped.items()]
+
+
+def _labelled(finding: Finding, pages: list[int]) -> str:
+    """One finding's line, with its page numbers folded into ranges."""
+    if not pages:
+        return finding.label()
+    where = "page" if len(pages) == 1 else "pages"
+    return f"[{finding.check}] ({where} {_ranges(pages)}) {finding.message}"
+
+
+def _ranges(pages: list[int]) -> str:
+    """``[1, 2, 3, 7]`` as ``"1-3, 7"``."""
+    spans: list[tuple[int, int]] = []
+    for page in sorted(set(pages)):
+        if spans and page == spans[-1][1] + 1:
+            spans[-1] = (spans[-1][0], page)
+        else:
+            spans.append((page, page))
+    return ", ".join(str(lo) if lo == hi else f"{lo}-{hi}" for lo, hi in spans)
+
+
+def _print_summary(reports: list[FileReport], profile: Profile) -> None:
+    layers = ", ".join(
+        name
+        for name, on in (
+            (f"PDF/A-{profile.flavour}", profile.pdfa),
+            ("PDF/X-4", profile.pdfx),
+            ("geometry", profile.geometry is not None),
+            ("colour", profile.colour),
+        )
+        if on
+    )
+    failed = [r for r in reports if not r.ok]
+    typer.echo("")
+    if failed:
+        typer.secho(f"FAIL -- {len(failed)} of {len(reports)} file(s) failed: {layers}", fg=typer.colors.RED)
+        return
+    warnings = sum(len(r.warnings) for r in reports)
+    note = f" ({warnings} advisory warning(s))" if warnings else ""
+    typer.secho(f"OK -- all {len(reports)} file(s) passed: {layers}{note}", fg=typer.colors.GREEN)
+
+
+# Re-exported so callers can special-case a genuine tool failure if they wish.
+VeraPdfError = verapdf.VeraPdfError

proof_pdf/colour.py

@@ -0,0 +1,365 @@
+"""Best-effort colour sanity -- the things neither PDF/A nor PDF/X judge.
+
+Four checks a printer cares about but no standard enforces:
+
+* **Total area coverage** -- the summed ink of the four plates. Rasterise each
+  page to DeviceCMYK with Ghostscript and take the peak; over the FOGRA51
+  ceiling the ink will not dry and will set off. This is the objective one, so
+  it is an ``ERROR``.
+* **Stray RGB** -- a raster still in an RGB space in a job destined for a CMYK
+  press. Every raster should already be converted to CMYK, so an
+  RGB image here means one escaped the workflow: an ``ERROR``. Vector RGB fills
+  are advisory by default, since a RIP will convert them against the output
+  intent; ``--strict-cmyk`` promotes them when that is not wanted.
+* **Overprint** -- an applied ``ExtGState`` turning overprint on. Usually
+  deliberate, so advisory: it is flagged, not failed.
+* **Rich-black small text** -- small text painted in a built black (K plus other
+  plates) mis-registers. Advisory.
+
+The raster step shells out to Ghostscript (its absence or failure is surfaced as
+a failure by the caller, not silently skipped); the rest read the
+:class:`pikepdf.Pdf` through :mod:`.content`, so they see nested Form XObjects.
+"""
+
+import logging
+import pathlib
+import shutil
+import subprocess
+import tempfile
+
+import pikepdf
+from PIL import Image, ImageMath
+
+from . import content
+from .models import Finding, Severity
+
+logger = logging.getLogger(__name__)
+
+
+class GhostscriptError(RuntimeError):
+    """Ghostscript exited non-zero, or timed out, while rasterising for ink coverage."""
+
+
+# Rasterising DeviceCMYK: 150 dpi resolves solids and small type without the
+# per-pixel cost of press resolution. TAC is an ink property, so more dpi buys
+# nothing here.
+_TAC_DPI = 150
+# A built black: the K plate is heavy and at least this much other ink rides on
+# top. Pure process black (0/0/0/K) never trips it.
+_RICH_K_MIN = 0.5
+_RICH_OTHER_MIN = 0.3
+
+# Colour-space families, as classified from a PDF colour space object.
+_RGB = "rgb"
+_CMYK = "cmyk"
+_GRAY = "gray"
+_OTHER = "other"
+
+_DEVICE_FAMILIES = {
+    "/DeviceRGB": _RGB,
+    "/CalRGB": _RGB,
+    "/Lab": _OTHER,
+    "/DeviceCMYK": _CMYK,
+    "/DeviceGray": _GRAY,
+    "/CalGray": _GRAY,
+    "/Pattern": _OTHER,
+}
+# Spot and multi-ink spaces carry an *alternate* space that is only a preview
+# hint -- a Separation whose alternate is DeviceRGB is a correct spot colour, not
+# stray RGB. Never look past these.
+_SPOT_FAMILIES = ("/Separation", "/DeviceN")
+_ICC_COMPONENTS = {1: _GRAY, 3: _RGB, 4: _CMYK}
+
+# Text-showing operators: whatever fill is in force when one runs is the colour
+# the glyphs are painted in.
+_SHOW_TEXT = ("Tj", "TJ", "'", '"')
+
+
+def gs_available(binary: str) -> bool:
+    """Whether the Ghostscript *binary* resolves (TAC needs it, nothing else)."""
+    return shutil.which(binary) is not None
+
+
+# ------------------------------------------------------------ total ink ----
+def check_tac(binary: str, path: str, max_tac: float, *, timeout: float | None = None) -> list[Finding]:
+    """Flag any page whose peak total ink coverage exceeds *max_tac* percent."""
+    findings: list[Finding] = []
+    for i, peak in enumerate(_page_tac_peaks(binary, path, timeout=timeout), start=1):
+        if peak > max_tac:
+            findings.append(
+                Finding("tac", Severity.ERROR, f"peak ink coverage {peak:.0f}% exceeds the {max_tac:.0f}% limit", i)
+            )
+    return findings
+
+
+def _page_tac_peaks(binary: str, path: str, *, timeout: float | None = None) -> list[float]:
+    """The peak TAC (0-400%) of each page, via a DeviceCMYK Ghostscript raster."""
+    with tempfile.TemporaryDirectory() as tmp:
+        pattern = str(pathlib.Path(tmp) / "page-%03d.tif")
+        try:
+            result = subprocess.run(
+                [
+                    binary,
+                    "-q",
+                    "-dNOPAUSE",
+                    "-dBATCH",
+                    "-dSAFER",
+                    "-sDEVICE=tiff32nc",
+                    f"-r{_TAC_DPI}",
+                    f"-sOutputFile={pattern}",
+                    path,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise GhostscriptError(f"ghostscript timed out after {timeout:.0f}s") from exc
+        if result.returncode != 0:
+            message = result.stderr.strip() or "ghostscript failed"
+            logger.error(f"ghostscript failed (rc={result.returncode}): {message}")
+            raise GhostscriptError(message)
+        # Sort by the numeric page index, not lexicographically: `page-1000.tif`
+        # must not sort before `page-999.tif` (wrong page labels past 999).
+        pages = sorted(pathlib.Path(tmp).glob("page-*.tif"), key=lambda t: int(t.stem.rsplit("-", 1)[-1]))
+        peaks: list[float] = []
+        for tif in pages:
+            peaks.append(_peak_tac(tif))
+            # A 50-page file at 150 dpi is ~150 MB of TIFF if it all stays on
+            # disk; each raster is dead the moment its peak is read.
+            tif.unlink(missing_ok=True)
+        return peaks
+
+
+def _peak_tac(tif: pathlib.Path) -> float:
+    """Peak C+M+Y+K over every pixel of a CMYK TIFF, as a percentage."""
+    with Image.open(tif) as img:
+        img.load()
+        c, m, y, k = (band.convert("I") for band in img.split())
+        total = ImageMath.lambda_eval(lambda a: a["cc"] + a["mm"] + a["yy"] + a["kk"], cc=c, mm=m, yy=y, kk=k)
+    peak = total.getextrema()[1]
+    return peak / 255.0 * 100.0
+
+
+# ------------------------------------------------------------- overprint ----
+def check_overprint(pdf: pikepdf.Pdf) -> list[Finding]:
+    """Note pages that *apply* an ExtGState enabling overprint (advisory).
+
+    Fires on the ``gs`` operator rather than on the resource dictionary, so it
+    sees overprint set inside a Form XObject, and does not fire on a graphics
+    state that is declared but never invoked.
+    """
+    findings: list[Finding] = []
+    for i, page in enumerate(pdf.pages, start=1):
+        if any(_sets_overprint(op) for op in content.iter_operations(page)):
+            findings.append(
+                Finding(
+                    "overprint", Severity.WARN, "overprint is enabled -- confirm it is intentional, not knockout", i
+                )
+            )
+    return findings
+
+
+def _sets_overprint(op: content.Operation) -> bool:
+    if op.operator != "gs":
+        return False
+    state = _lookup_resource(op.resources, "/ExtGState", op.operands)
+    if state is None:
+        return False
+    return _truthy(state.get("/OP")) or _truthy(state.get("/op"))
+
+
+def _lookup_resource(resources: pikepdf.Object | None, category: str, operands: list) -> pikepdf.Object | None:
+    """Resolve a name operand against one category of a resource dictionary."""
+    if resources is None or not operands:
+        return None
+    table = resources.get(category)
+    if table is None:
+        return None
+    try:
+        return table.get(str(operands[0]))
+    except KeyError, TypeError:
+        return None
+
+
+def _truthy(value: object) -> bool:
+    """A PDF boolean object read as a plain bool."""
+    return value is not None and str(value) == "True"
+
+
+# ---------------------------------------------------------- colour space ----
+def check_colour_spaces(pdf: pikepdf.Pdf, *, strict: bool) -> list[Finding]:
+    """Flag artwork still in an RGB colour space on a CMYK-destined page.
+
+    Images are an ``ERROR``: every raster is expected to have gone through CMYK
+    conversion, so one in RGB is an escape that will be converted by the
+    RIP with whatever profile it feels like. Vector ``rg``/``RG`` fills are a
+    ``WARN`` unless *strict*, since the document legitimately declares an RGB
+    profile too.
+    """
+    findings: list[Finding] = []
+    vector_severity = Severity.ERROR if strict else Severity.WARN
+    for i, page in enumerate(pdf.pages, start=1):
+        images: set[str] = set()
+        vector = False
+        for op in content.iter_operations(page):
+            if op.operator in ("rg", "RG"):
+                vector = True
+            elif op.operator == "Do":
+                name = _rgb_image_name(op)
+                if name is not None:
+                    images.add(name)
+        for name in sorted(images):
+            findings.append(
+                Finding(
+                    "colour-space",
+                    Severity.ERROR,
+                    f"image {name} is in an RGB colour space -- it must be converted to CMYK for a FOGRA51 press",
+                    i,
+                )
+            )
+        if vector:
+            findings.append(
+                Finding(
+                    "colour-space",
+                    vector_severity,
+                    "vector artwork is filled in DeviceRGB -- confirm the RIP is meant to convert it",
+                    i,
+                )
+            )
+    return findings
+
+
+def _rgb_image_name(op: content.Operation) -> str | None:
+    """The name of the image this ``Do`` paints, if that image is in an RGB space."""
+    xobject = content.lookup_xobject(op.resources, op.operands)
+    if xobject is None or str(xobject.get("/Subtype")) != "/Image":
+        return None
+    if classify_colour_space(xobject.get("/ColorSpace"), op.resources) != _RGB:
+        return None
+    return str(op.operands[0])
+
+
+def classify_colour_space(space: object, resources: pikepdf.Object | None, *, depth: int = 0) -> str:
+    """Which colour family a PDF colour space object belongs to.
+
+    Resolves named spaces through the resource dictionary and looks through
+    ``/Indexed`` to its base, but deliberately stops at ``/Separation`` and
+    ``/DeviceN``: their alternate space is a rendering hint for a spot ink, and
+    treating it as the artwork's own space produces false positives on entirely
+    correct print files.
+    """
+    if space is None or depth > 4:
+        return _OTHER
+    if isinstance(space, pikepdf.Array) or (hasattr(space, "__len__") and not isinstance(space, pikepdf.Name)):
+        return _classify_array(space, resources, depth)
+    name = str(space)
+    if name in _DEVICE_FAMILIES:
+        return _DEVICE_FAMILIES[name]
+    named = _lookup_resource(resources, "/ColorSpace", [name])
+    if named is not None:
+        return classify_colour_space(named, resources, depth=depth + 1)
+    return _OTHER
+
+
+def _classify_array(space, resources: pikepdf.Object | None, depth: int) -> str:
+    try:
+        head = str(space[0])
+    except IndexError, TypeError:
+        return _OTHER
+    if head in _SPOT_FAMILIES:
+        return _OTHER
+    if head == "/ICCBased":
+        return _classify_icc(space)
+    if head == "/Indexed":
+        base = space[1] if len(space) > 1 else None
+        return classify_colour_space(base, resources, depth=depth + 1)
+    if head in _DEVICE_FAMILIES:
+        return _DEVICE_FAMILIES[head]
+    return _OTHER
+
+
+def _classify_icc(space) -> str:
+    """An ``[/ICCBased stream]`` space, classified by the stream's ``/N``."""
+    try:
+        components = int(space[1].get("/N"))
+    except IndexError, TypeError, ValueError, AttributeError:
+        return _OTHER
+    return _ICC_COMPONENTS.get(components, _OTHER)
+
+
+# ------------------------------------------------ rich-black small text ----
+def check_rich_black(pdf: pikepdf.Pdf, small_text_pt: float) -> list[Finding]:
+    """Flag small text painted in a built (rich) black on any page (advisory)."""
+    findings: list[Finding] = []
+    for i, page in enumerate(pdf.pages, start=1):
+        smallest = _smallest_rich_black_text(page, small_text_pt)
+        if smallest is not None:
+            findings.append(
+                Finding(
+                    "rich-black",
+                    Severity.WARN,
+                    f"text as small as {smallest:.1f}pt is set in rich black -- "
+                    "use process black to avoid mis-registration",
+                    i,
+                )
+            )
+    return findings
+
+
+def _smallest_rich_black_text(page: pikepdf.Page, small_text_pt: float) -> float | None:
+    """Effective point size of the smallest rich-black run on the page, if any.
+
+    Text state (font size, fill, text matrix) is tracked across the whole walk
+    rather than reset per Form XObject: a form that shows text essentially always
+    sets its own ``Tf`` and ``BT`` first, and this check is advisory, so the
+    extra reach costs nothing and buys visibility into nested content.
+    """
+    text_matrix: content.Matrix = content.IDENTITY
+    font_size = 0.0
+    fill: tuple[float, float, float, float] | None = None
+    smallest: float | None = None
+
+    for op in content.iter_operations(page):
+        name, args = op.operator, op.operands
+        if name == "BT":
+            text_matrix = content.IDENTITY
+        elif name == "Tm":
+            text_matrix = content.matrix(args)
+        elif name in ("Td", "TD"):
+            text_matrix = content.mul(_translation(args), text_matrix)
+        elif name == "Tf":
+            font_size = _number(args, 1)
+        elif name == "k":
+            fill = _cmyk(args)
+        elif name in ("g", "rg"):
+            fill = None  # grayscale / RGB black is never rich black
+        elif name in _SHOW_TEXT and _is_rich_black(fill):
+            size = font_size * content.vertical_scale(content.mul(text_matrix, op.ctm))
+            if size <= small_text_pt and (smallest is None or size < smallest):
+                smallest = size
+    return smallest
+
+
+def _translation(args: list) -> content.Matrix:
+    return (1.0, 0.0, 0.0, 1.0, _number(args, 0), _number(args, 1))
+
+
+def _number(args: list, index: int) -> float:
+    try:
+        return float(args[index])
+    except IndexError, TypeError, ValueError:
+        return 0.0
+
+
+def _cmyk(args: list) -> tuple[float, float, float, float] | None:
+    if len(args) < 4:
+        return None
+    return (_number(args, 0), _number(args, 1), _number(args, 2), _number(args, 3))
+
+
+def _is_rich_black(fill: tuple[float, float, float, float] | None) -> bool:
+    if fill is None:
+        return False
+    c, m, y, k = fill
+    return k >= _RICH_K_MIN and (c + m + y) >= _RICH_OTHER_MIN