ghostbuild 0.1.0__py3-none-any.whl

ghostbuild/__init__.py

@@ -0,0 +1,3 @@
+"""GhostBuild: reproducible build verification. Build it twice. Know what changed."""
+
+__version__ = "0.1.0"

ghostbuild/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m ghostbuild``."""
+
+from ghostbuild.cli import app
+
+if __name__ == "__main__":
+    app()

ghostbuild/adapters/__init__.py

@@ -0,0 +1,19 @@
+"""Registry of ecosystem adapters.
+
+To add an ecosystem, implement ``BuildAdapter`` and append an instance here.
+"""
+
+from __future__ import annotations
+
+from ghostbuild.adapters.base import BuildAdapter
+from ghostbuild.adapters.python import PythonAdapter
+
+ADAPTERS: tuple[BuildAdapter, ...] = (PythonAdapter(),)
+
+
+def get_adapters() -> tuple[BuildAdapter, ...]:
+    """Return all registered adapters, in detection order."""
+    return ADAPTERS
+
+
+__all__ = ["ADAPTERS", "BuildAdapter", "PythonAdapter", "get_adapters"]

ghostbuild/adapters/base.py

@@ -0,0 +1,68 @@
+"""The interface an ecosystem adapter implements.
+
+The engine only talks to this interface. To add an ecosystem (Node.js, Cargo,
+Go, ...), subclass ``BuildAdapter`` and register it in ``adapters/__init__.py``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from ghostbuild.config import Config
+from ghostbuild.models import ProjectInfo
+
+
+class BuildAdapter(ABC):
+    """Knows how to recognise, inspect and build one kind of project."""
+
+    #: Short identifier used in reports and configuration, e.g. ``"python"``.
+    id: str
+    #: Human-readable language name.
+    language: str
+
+    @abstractmethod
+    def detect(self, project_dir: Path) -> bool:
+        """Return True if this adapter can handle the project. Must not run project code."""
+
+    @abstractmethod
+    def inspect(self, project_dir: Path) -> ProjectInfo:
+        """Read project metadata from files. Must not run project code."""
+
+    @abstractmethod
+    def available_tools(self) -> dict[str, str | None]:
+        """Map tool name to a version/path, or ``None`` if it is not available."""
+
+    @abstractmethod
+    def missing_prerequisites(self, config: Config) -> list[str]:
+        """Return human-readable problems that would stop a local build."""
+
+    @abstractmethod
+    def build_command(self, source_dir: Path, output_dir: Path, config: Config) -> list[str]:
+        """Return the argument list (never a shell string) for a local build."""
+
+    @abstractmethod
+    def has_custom_build_command(self, config: Config) -> bool:
+        """Return True if the user overrode the default build command."""
+
+    @abstractmethod
+    def container_image(self, config: Config) -> str:
+        """Return the container image used for an independent rebuild."""
+
+    @abstractmethod
+    def container_script(self, config: Config) -> str:
+        """Return the ``sh`` script run inside the container.
+
+        The container mounts the prepared source read-only at ``/src`` and a
+        writable output directory at ``/out``. The script must write artifacts
+        to ``/out`` and print one ``GHOSTBUILD_ENV <json>`` line describing the
+        container environment.
+        """
+
+    def describe_build_tool(self) -> str | None:
+        """Return the local build tool and version, if known."""
+        return None
+
+    def collect_warnings(self, project: ProjectInfo) -> list[str]:
+        """Return reproducibility risks visible from project metadata."""
+        return []

ghostbuild/adapters/python.py

@@ -0,0 +1,232 @@
+"""Python build adapter: PEP 517 projects built with ``python -m build``."""
+
+from __future__ import annotations
+
+import configparser
+import importlib.metadata
+import importlib.util
+import platform
+import re
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from ghostbuild.adapters.base import BuildAdapter
+from ghostbuild.config import Config, load_toml
+from ghostbuild.errors import ConfigError
+from ghostbuild.models import ProjectInfo
+
+# build-backend -> friendly build system name
+_BACKENDS = {
+    "setuptools.build_meta": "setuptools",
+    "setuptools.build_meta:__legacy__": "setuptools",
+    "hatchling.build": "hatch",
+    "poetry.core.masonry.api": "poetry",
+    "pdm.backend": "pdm",
+    "pdm.pep517.api": "pdm",
+    "flit_core.buildapi": "flit",
+    "maturin": "maturin",
+    "scikit_build_core.build": "scikit-build-core",
+}
+_LEGACY_BACKEND = "setuptools.build_meta:__legacy__"
+_LEGACY_REQUIRES = ["setuptools>=40.8.0", "wheel"]
+_CONFIG_FILES = (
+    "pyproject.toml", "setup.py", "setup.cfg", "MANIFEST.in", "hatch.toml",
+    "poetry.lock", "pdm.lock", "uv.lock", "Pipfile.lock", "tox.ini", "ghostbuild.toml",
+)  # fmt: skip
+_LOCK_FILES = ("poetry.lock", "pdm.lock", "uv.lock", "Pipfile.lock")
+_TOOLS_ON_PATH = ("hatch", "poetry", "pdm", "uv")
+
+_CONTAINER_SCRIPT = """\
+set -eu
+export HOME=/tmp/ghostbuild-home
+mkdir -p "$HOME" /tmp/work
+cp -a /src/. /tmp/work/
+cd /tmp/work
+python -m pip install --quiet --disable-pip-version-check --user '{requirement}'
+python -c 'import importlib.metadata as m, json, os, platform, time; print("GHOSTBUILD_ENV " + json.dumps({"python_version": platform.python_version(), "python_implementation": platform.python_implementation(), "os": platform.platform(), "architecture": platform.machine(), "build_tool": "build " + m.version("build"), "locale": os.environ.get("LC_ALL") or os.environ.get("LANG"), "timezone": os.environ.get("TZ") or "/".join(time.tzname)}))'
+python -m build --sdist --wheel --outdir /out .
+"""  # noqa: E501
+
+
+def _is_pinned(requirement: str) -> bool:
+    """Return True if a PEP 508 requirement pins an exact version or URL."""
+    return bool(re.search(r"(===?|@)", requirement))
+
+
+class PythonAdapter(BuildAdapter):
+    """Builds Python projects through the standard ``build`` frontend."""
+
+    id = "python"
+    language = "Python"
+
+    def detect(self, project_dir: Path) -> bool:
+        if (project_dir / "setup.py").is_file() or (project_dir / "setup.cfg").is_file():
+            return True
+        pyproject = project_dir / "pyproject.toml"
+        if not pyproject.is_file():
+            return False
+        data = load_toml(pyproject)
+        return any(k in data for k in ("build-system", "project")) or "poetry" in data.get(
+            "tool", {}
+        )
+
+    def inspect(self, project_dir: Path) -> ProjectInfo:
+        data: dict[str, Any] = {}
+        pyproject = project_dir / "pyproject.toml"
+        if pyproject.is_file():
+            data = load_toml(pyproject)
+        project = data.get("project", {})
+        poetry = data.get("tool", {}).get("poetry", {})
+        notes: list[str] = []
+
+        name, version = self._name_and_version(project_dir, project, poetry, notes)
+
+        build_system_table = data.get("build-system")
+        if build_system_table is not None:
+            backend = build_system_table.get("build-backend")
+            requires = list(build_system_table.get("requires", []))
+            if backend is None:
+                backend = _LEGACY_BACKEND
+                notes.append("[build-system] has no build-backend; pip would use setuptools.")
+        else:
+            backend, requires = _LEGACY_BACKEND, list(_LEGACY_REQUIRES)
+            notes.append("No [build-system] table; the default setuptools backend would be used.")
+            if poetry:
+                notes.append(
+                    "Found [tool.poetry] without [build-system]; add one (poetry-core) so the "
+                    "project builds with Poetry's backend."
+                )
+        build_system = _BACKENDS.get(backend, backend)
+        if build_system_table is None and not pyproject.is_file():
+            build_system = "setuptools (legacy setup.py/setup.cfg)"
+
+        dependencies = list(project.get("dependencies", []))
+        if not dependencies and poetry:
+            dependencies = [
+                f"{dep} {spec if isinstance(spec, str) else ''}".strip()
+                for dep, spec in poetry.get("dependencies", {}).items()
+                if dep.lower() != "python"
+            ]
+        requires_python = project.get("requires-python")
+        if requires_python is None and isinstance(poetry.get("dependencies", {}).get("python"), str):
+            requires_python = poetry["dependencies"]["python"]
+
+        config_files = [f for f in _CONFIG_FILES if (project_dir / f).is_file()]
+        config_files += sorted(p.name for p in project_dir.glob("requirements*.txt") if p.is_file())
+
+        return ProjectInfo(
+            path=str(project_dir),
+            name=name,
+            version=version,
+            language=self.language,
+            build_system=build_system,
+            build_backend=backend,
+            adapter=self.id,
+            config_files=config_files,
+            build_requires=requires,
+            dependencies=dependencies,
+            requires_python=requires_python,
+            lock_files=[f for f in _LOCK_FILES if (project_dir / f).is_file()],
+            notes=notes,
+        )
+
+    @staticmethod
+    def _name_and_version(
+        project_dir: Path, project: dict[str, Any], poetry: dict[str, Any], notes: list[str]
+    ) -> tuple[str | None, str | None]:
+        name = project.get("name") or poetry.get("name")
+        version = project.get("version") or poetry.get("version")
+        if version is None and "version" in project.get("dynamic", []):
+            version = "dynamic"
+        setup_cfg = project_dir / "setup.cfg"
+        if (name is None or version is None) and setup_cfg.is_file():
+            parser = configparser.ConfigParser(interpolation=None)
+            try:
+                parser.read(setup_cfg, encoding="utf-8")
+            except configparser.Error as exc:
+                notes.append(f"setup.cfg could not be parsed: {exc}")
+            else:
+                name = name or parser.get("metadata", "name", fallback=None)
+                cfg_version = parser.get("metadata", "version", fallback=None)
+                if version is None and cfg_version:
+                    version = "dynamic" if cfg_version.startswith(("attr:", "file:")) else cfg_version
+        if name is None and (project_dir / "setup.py").is_file():
+            notes.append("Name/version are defined in setup.py, which GhostBuild does not execute.")
+        if version == "dynamic":
+            notes.append("The version is computed at build time (dynamic).")
+        return name, version
+
+    def available_tools(self) -> dict[str, str | None]:
+        tools: dict[str, str | None] = {"python": f"{platform.python_version()} ({sys.executable})"}
+        for package in ("pip", "build", "setuptools", "wheel"):
+            tools[package] = self._package_version(package)
+        for executable in _TOOLS_ON_PATH:
+            tools[executable] = shutil.which(executable)
+        return tools
+
+    @staticmethod
+    def _package_version(package: str) -> str | None:
+        try:
+            return importlib.metadata.version(package)
+        except importlib.metadata.PackageNotFoundError:
+            return None
+
+    def describe_build_tool(self) -> str | None:
+        version = self._package_version("build")
+        return f"build {version}" if version else None
+
+    def missing_prerequisites(self, config: Config) -> list[str]:
+        if config.python.build_command:
+            return []
+        if importlib.util.find_spec("build") is None:
+            return [
+                "The 'build' package is not installed for this Python interpreter "
+                f"({sys.executable}). Install it with: python -m pip install build"
+            ]
+        return []
+
+    def has_custom_build_command(self, config: Config) -> bool:
+        return bool(config.python.build_command)
+
+    def build_command(self, source_dir: Path, output_dir: Path, config: Config) -> list[str]:
+        if config.python.build_command:
+            replacements = {
+                "{python}": sys.executable,
+                "{source_dir}": str(source_dir),
+                "{outdir}": str(output_dir),
+            }
+            command = []
+            for part in config.python.build_command:
+                for placeholder, value in replacements.items():
+                    part = part.replace(placeholder, value)
+                command.append(part)
+            return command
+        return [
+            sys.executable, "-m", "build", "--sdist", "--wheel",
+            "--outdir", str(output_dir), str(source_dir),
+        ]  # fmt: skip
+
+    def container_image(self, config: Config) -> str:
+        if config.python.docker_image:
+            return config.python.docker_image
+        return f"python:{sys.version_info.major}.{sys.version_info.minor}-slim"
+
+    def container_script(self, config: Config) -> str:
+        requirement = config.python.build_requirement
+        if "'" in requirement:
+            raise ConfigError("[python] build_requirement must not contain a single quote.")
+        # str.replace, not str.format: the script contains literal braces.
+        return _CONTAINER_SCRIPT.replace("{requirement}", requirement)
+
+    def collect_warnings(self, project: ProjectInfo) -> list[str]:
+        warnings = []
+        unpinned = [r for r in project.build_requires if not _is_pinned(r)]
+        if unpinned:
+            warnings.append(
+                "Build requirements are not pinned to exact versions "
+                f"({', '.join(unpinned)}). Builds in different environments may resolve "
+                "different versions, which is a common cause of differing artifacts."
+            )
+        return warnings

ghostbuild/cli.py

@@ -0,0 +1,341 @@
+"""Command-line interface (Typer + Rich)."""
+
+from __future__ import annotations
+
+import shlex
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+from rich.text import Text
+
+from ghostbuild import __version__
+from ghostbuild.config import (
+    CONFIG_FILENAME,
+    EXAMPLE_CONFIG,
+    REPORT_FORMATS,
+    load_config,
+)
+from ghostbuild.detection import detect_project
+from ghostbuild.engine.isolation import (
+    ISOLATION_CHOICES,
+    DockerStatus,
+    detect_docker,
+    resolve_isolation,
+)
+from ghostbuild.engine.verifier import compare_directories, verify_project
+from ghostbuild.errors import GhostBuildError, LocalFallbackNotApproved, PathError
+from ghostbuild.models import VerificationResult, to_plain
+from ghostbuild.reports import json_report
+from ghostbuild.reports.html_report import write_html
+from ghostbuild.reports.terminal import render_banner, render_result, render_scan
+from ghostbuild.utils.filesystem import validate_directory
+
+# Exit codes: 2 is reserved for usage errors (Typer/Click).
+EXIT_REPRODUCIBLE = 0
+EXIT_NON_REPRODUCIBLE = 1
+EXIT_INCONCLUSIVE = 3
+EXIT_ERROR = 4
+EXIT_DECLINED = 5
+_VERDICT_EXIT = {
+    "reproducible": EXIT_REPRODUCIBLE,
+    "non-reproducible": EXIT_NON_REPRODUCIBLE,
+    "inconclusive": EXIT_INCONCLUSIVE,
+}
+
+app = typer.Typer(
+    name="ghostbuild",
+    help="Build it twice. Know what changed. Reproducible build verification.",
+    add_completion=False,
+    no_args_is_help=False,
+)
+
+NoColorOption = Annotated[bool, typer.Option("--no-color", help="Disable coloured output.")]
+VerboseOption = Annotated[bool, typer.Option("--verbose", help="Show full details and build logs.")]
+ConfigOption = Annotated[
+    Optional[Path],
+    typer.Option("--config", "-c", help="Path to a ghostbuild.toml (default: <project>/ghostbuild.toml)."),
+]
+
+
+def _consoles(no_color: bool) -> tuple[Console, Console]:
+    """Return (stdout console, stderr console). Progress and errors go to stderr."""
+    return Console(no_color=no_color), Console(stderr=True, no_color=no_color)
+
+
+@contextmanager
+def _handle_errors(err: Console) -> Iterator[None]:
+    """Turn expected GhostBuild errors into a clean message and exit code 4."""
+    try:
+        yield
+    except GhostBuildError as exc:
+        err.print(Text(f"Error: {exc}", style="bold red"))
+        raise typer.Exit(EXIT_ERROR) from exc
+
+
+def _check_format(value: str | None) -> str | None:
+    if value is not None and value not in REPORT_FORMATS:
+        raise typer.BadParameter(f"must be one of: {', '.join(REPORT_FORMATS)}", param_hint="--format")
+    return value
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"ghostbuild {__version__}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: Annotated[
+        bool,
+        typer.Option("--version", "-V", callback=_version_callback, is_eager=True,
+                     help="Show the version and exit."),
+    ] = False,
+) -> None:  # fmt: skip
+    """Build it twice. Know what changed."""
+    if ctx.invoked_subcommand is None:
+        render_banner(Console())
+
+
+@app.command()
+def version() -> None:
+    """Show the installed GhostBuild version."""
+    typer.echo(f"ghostbuild {__version__}")
+
+
+@app.command()
+def init(
+    path: Annotated[Path, typer.Argument(help="Where to write the example configuration.")] = Path(
+        CONFIG_FILENAME
+    ),
+    force: Annotated[bool, typer.Option("--force", help="Overwrite an existing file.")] = False,
+) -> None:
+    """Write an example ghostbuild.toml containing all defaults."""
+    out, err = _consoles(False)
+    if path.exists() and not force:
+        err.print(Text(f"Error: {path} already exists. Use --force to overwrite it.", style="bold red"))
+        raise typer.Exit(EXIT_ERROR)
+    path.write_text(EXAMPLE_CONFIG, encoding="utf-8")
+    out.print(Text(f"Wrote {path}"))
+
+
+@app.command()
+def scan(
+    project_dir: Annotated[Path, typer.Argument(help="Project directory to inspect.")] = Path("."),
+    config_path: ConfigOption = None,
+    no_color: NoColorOption = False,
+) -> None:
+    """Inspect a project: name, build system, requirements and available tools.
+
+    Reads project files only. No build is run.
+    """
+    out, err = _consoles(no_color)
+    with _handle_errors(err):
+        load_config(config_path, validate_directory(project_dir, "project directory"))
+        adapter, project = detect_project(project_dir)
+        docker = detect_docker()
+        render_scan(out, to_plain(project), adapter.available_tools(), to_plain(docker))
+
+
+def _interactive() -> bool:
+    return sys.stdin.isatty()
+
+
+def _choose_isolation(requested: str, docker: DockerStatus, err: Console) -> str:
+    """Resolve the isolation mode, asking before any local fallback."""
+    try:
+        return resolve_isolation(requested, docker, local_approved=False)
+    except LocalFallbackNotApproved as exc:
+        if not _interactive():
+            raise
+        err.print(Text(f"Docker is unavailable: {docker.reason}.", style="bold yellow"))
+        err.print(
+            "A local rebuild uses the same interpreter and tools as the original build, so it "
+            "is NOT equivalent to an independent clean-container build. It can only show "
+            "repeatability on this machine."
+        )
+        if not typer.confirm("Use the weaker local rebuild instead?", default=False):
+            raise typer.Exit(EXIT_DECLINED) from exc
+        return resolve_isolation(requested, docker, local_approved=True)
+
+
+def _present_plan(err: Console, project_dir: Path, command: list[str], mode: str, image: str | None) -> None:
+    err.print(Text("\nBuild plan", style="bold"))
+    err.print(Text(f"  Project: {project_dir}"))
+    err.print(Text(f"  Original build: runs on this host in a temporary copy: {shlex.join(command)}"))
+    if mode == "docker":
+        err.print(Text(f"  Independent rebuild: runs inside a Docker container ({image}), source mounted read-only"))
+    else:
+        err.print(Text("  Independent rebuild: runs on this host in a second temporary copy (LOCAL, weaker isolation)",
+                       style="yellow"))  # fmt: skip
+    err.print(Text("  Your project directory is only read, never modified.", style="dim"))
+    err.print(Text("  WARNING: building runs code from this project (build backend, setup.py, hooks).",
+                   style="bold yellow"))  # fmt: skip
+
+
+@app.command()
+def verify(
+    project_dir: Annotated[Path, typer.Argument(help="Project directory to verify.")] = Path("."),
+    output: Annotated[Optional[Path], typer.Option("--output", "-o", help="Directory for reports.")] = None,
+    fmt: Annotated[
+        Optional[str],
+        typer.Option("--format", "-f", help="Output format: terminal, json or html."),
+    ] = None,
+    keep_artifacts: Annotated[
+        bool, typer.Option("--keep-artifacts", help="Keep both builds' artifacts in the output directory.")
+    ] = False,
+    isolation: Annotated[
+        str,
+        typer.Option(help="Rebuild isolation: auto (Docker if available), docker, or local."),
+    ] = "auto",
+    yes: Annotated[
+        bool, typer.Option("--yes", "-y", help="Approve running the project's build without prompting.")
+    ] = False,
+    timeout: Annotated[Optional[int], typer.Option(help="Per-build timeout in seconds.", min=1)] = None,
+    config_path: ConfigOption = None,
+    verbose: VerboseOption = False,
+    no_color: NoColorOption = False,
+) -> None:
+    """Build the project twice and compare the artifacts.
+
+    This executes the project's build scripts. GhostBuild asks for consent first
+    (or use --yes) and never silently weakens isolation.
+    """
+    out, err = _consoles(no_color)
+    if isolation not in ISOLATION_CHOICES:
+        raise typer.BadParameter(f"must be one of: {', '.join(ISOLATION_CHOICES)}", param_hint="--isolation")
+    _check_format(fmt)
+    result: VerificationResult
+    with _handle_errors(err):
+        root = validate_directory(project_dir, "project directory")
+        config = load_config(config_path, root)
+        fmt = fmt or config.report.format
+        output_dir = (output or Path(config.report.output_dir)).resolve()
+        _check_output_dir(output_dir, keep_artifacts)
+        adapter, project = detect_project(root)
+        err.print(Text(f"GhostBuild v{__version__}", style="bold"))
+        err.print(Text(f"Detected: {project.language}   Build system: {project.build_system}"))
+
+        mode = _choose_isolation(isolation, detect_docker(), err)
+        image = adapter.container_image(config) if mode == "docker" else None
+        command = adapter.build_command(Path("<source>"), Path("<output>"), config)
+        _present_plan(err, root, command, mode, image)
+        if not yes:
+            if not _interactive():
+                raise GhostBuildError(
+                    "Refusing to run build commands without consent in a non-interactive session. "
+                    "Re-run with --yes to approve."
+                )
+            if not typer.confirm("Run these build commands now?", default=False):
+                err.print("Aborted. No build commands were run.")
+                raise typer.Exit(EXIT_DECLINED)
+
+        err.print()
+        with err.status("Starting...") as status:
+            def on_stage(index: int, total: int, label: str) -> None:
+                err.print(Text(f"[{index}/{total}] {label}", style="bold cyan"))
+                status.update(f"{label}...")
+
+            result = verify_project(
+                root, adapter, project, config,
+                mode=mode,
+                timeout=timeout or config.build.timeout_seconds,
+                keep_artifacts_dir=(output_dir / "artifacts") if keep_artifacts else None,
+                skip_paths=[output_dir],
+                on_stage=on_stage,
+            )  # fmt: skip
+        _emit(result, output_dir, fmt, out, err, verbose)
+    raise typer.Exit(_VERDICT_EXIT[result.verdict.value])
+
+
+def _check_output_dir(output_dir: Path, keep_artifacts: bool) -> None:
+    if output_dir.exists() and not output_dir.is_dir():
+        raise PathError(f"The output path exists and is not a directory: {output_dir}")
+    kept = output_dir / "artifacts"
+    if keep_artifacts and kept.exists() and any(kept.iterdir()):
+        raise PathError(
+            f"{kept} already contains files. GhostBuild will not overwrite or delete them; "
+            "choose another --output directory or remove it yourself."
+        )
+
+
+def _emit(
+    result: VerificationResult, output_dir: Path, fmt: str, out: Console, err: Console, verbose: bool
+) -> None:
+    """Write result.json (always) and print/write the requested format."""
+    saved = json_report.write_json(result, output_dir)
+    data = result.to_dict()
+    if fmt == "json":
+        typer.echo(json_report.to_json(data), nl=False)
+    else:
+        render_result(out, data, verbose)
+    if fmt == "html":
+        err.print(Text(f"HTML report saved to: {write_html(data, output_dir)}"))
+    err.print(Text(f"Report saved to: {saved.parent}/"))
+
+
+@app.command()
+def compare(
+    dir_a: Annotated[Path, typer.Argument(help="First (original) artifact directory.")],
+    dir_b: Annotated[Path, typer.Argument(help="Second (rebuilt) artifact directory.")],
+    pattern: Annotated[
+        Optional[list[str]], typer.Option("--pattern", "-p", help="Artifact glob (repeatable).")
+    ] = None,
+    output: Annotated[Optional[Path], typer.Option("--output", "-o", help="Write reports to this directory.")] = None,
+    fmt: Annotated[Optional[str], typer.Option("--format", "-f", help="terminal, json or html.")] = None,
+    config_path: ConfigOption = None,
+    verbose: VerboseOption = False,
+    no_color: NoColorOption = False,
+) -> None:
+    """Compare two existing artifact directories. No builds are run."""
+    out, err = _consoles(no_color)
+    _check_format(fmt)
+    with _handle_errors(err):
+        first = validate_directory(dir_a, "first directory")
+        second = validate_directory(dir_b, "second directory")
+        config = load_config(config_path, None)
+        fmt = fmt or "terminal"
+        if fmt == "html" and output is None:
+            raise PathError("--format html needs --output to choose where to write the report.")
+        result = compare_directories(first, second, config, pattern or None)
+        if output is not None:
+            _emit(result, output.resolve(), fmt, out, err, verbose)
+        else:
+            data = result.to_dict()
+            if fmt == "json":
+                typer.echo(json_report.to_json(data), nl=False)
+            else:
+                render_result(out, data, verbose)
+    raise typer.Exit(_VERDICT_EXIT[result.verdict.value])
+
+
+@app.command()
+def report(
+    path: Annotated[Path, typer.Argument(help="A result.json file or a directory containing one.")] = Path(
+        "ghostbuild-results"
+    ),
+    fmt: Annotated[str, typer.Option("--format", "-f", help="terminal, json or html.")] = "terminal",
+    output: Annotated[
+        Optional[Path], typer.Option("--output", "-o", help="Directory to write an HTML report to.")
+    ] = None,
+    verbose: VerboseOption = False,
+    no_color: NoColorOption = False,
+) -> None:
+    """Display or regenerate a report from a stored result.json."""
+    out, err = _consoles(no_color)
+    _check_format(fmt)
+    with _handle_errors(err):
+        data = json_report.load_result(path)
+        if fmt == "json":
+            typer.echo(json_report.to_json(data), nl=False)
+        elif fmt == "html":
+            target = output or (path if path.is_dir() else path.parent)
+            err.print(Text(f"HTML report saved to: {write_html(data, target.resolve())}"))
+        else:
+            render_result(out, data, verbose)