coltrace 0.1.0.dev4__py3-none-any.whl

coltrace/cli.py

@@ -0,0 +1,668 @@
+"""Command-line presentation for static column lineage reports."""
+
+from __future__ import annotations
+
+import webbrowser
+from collections.abc import Iterator
+from contextlib import contextmanager
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+import typer
+
+from .exporters import export_html, export_json, load_report
+from .graph import AmbiguousColumnError, ColumnNotFoundError, LineageGraph
+from .lineage_models import Column, LineageReport
+from .scanner import ScanConfig
+
+app = typer.Typer(
+    name="coltrace",
+    help="Explore static Pandas column lineage and potential change impact.",
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+)
+
+
+class ExportFormat(StrEnum):
+    json = "json"
+    html = "html"
+
+
+class EvidenceFilter(StrEnum):
+    all = "all"
+    confirmed = "confirmed"
+
+
+class RelationFilter(StrEnum):
+    derive = "derive"
+    rename = "rename"
+    passthrough = "pass"
+
+
+class GraphView(StrEnum):
+    history = "history"
+    columns = "columns"
+
+
+SnapshotOption = Annotated[
+    Path | None,
+    typer.Option("--from", help="Snapshot JSON; default: .coltrace/scan.json."),
+]
+ProjectOption = Annotated[
+    Path | None,
+    typer.Option("--project", help="Analyze this project now instead of reading a snapshot."),
+]
+ModuleOption = Annotated[str | None, typer.Option(help="Select an exact module name.")]
+FunctionOption = Annotated[str | None, typer.Option(help="Select a function or qualified scope.")]
+DataFrameOption = Annotated[str | None, typer.Option(help="Select an exact DataFrame identity.")]
+ColumnIDOption = Annotated[
+    str | None, typer.Option("--column-id", help="Select an exact column version by its ID.")
+]
+VersionOption = Annotated[int | None, typer.Option(min=0, help="Select a column version.")]
+DepthOption = Annotated[
+    int | None, typer.Option(min=0, help="Maximum dependency distance in column-to-column hops.")
+]
+RelationOption = Annotated[RelationFilter | None, typer.Option(help="Filter dependency relations.")]
+EvidenceOption = Annotated[EvidenceFilter, typer.Option(help="Filter dependency evidence.")]
+DiagnosticsOption = Annotated[bool, typer.Option(help="Show all diagnostics, including hints.")]
+ColumnArgument = Annotated[
+    str | None, typer.Argument(help="Column name; use --column-id to select an exact version.")
+]
+
+
+@contextmanager
+def _errors() -> Iterator[None]:
+    """Translate expected data/input errors without hiding programming failures."""
+    try:
+        yield
+    except AmbiguousColumnError as exc:
+        typer.echo("Ambiguous column. Select one with --column-id:", err=True)
+        for candidate in exc.candidates:
+            typer.echo(
+                f"  {candidate.id}  {candidate.name}@{candidate.version}  "
+                f"{candidate.location.path}:{candidate.location.line}  "
+                f"{candidate.module}::{candidate.scope}  "
+                f"dataframe={candidate.dataframe_id} context={candidate.context} "
+                f"origin={candidate.origin} evidence={candidate.evidence}",
+                err=True,
+            )
+        raise typer.Exit(3) from exc
+    except ColumnNotFoundError as exc:
+        typer.echo(f"Column not found: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    except (OSError, ValueError) as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(2) from exc
+
+
+def _report(snapshot: Path | None, project: Path | None) -> LineageReport:
+    if snapshot is not None and project is not None:
+        raise ValueError("Use either --from or --project, not both.")
+    if project is not None:
+        from .analysis import analyze_project
+
+        return analyze_project(project)
+    path = snapshot if snapshot is not None else Path(".coltrace/scan.json")
+    if not path.is_file():
+        raise ValueError(
+            f"Snapshot not found: {path}. Run 'coltrace scan PROJECT' first, "
+            "or use --from FILE or --project DIRECTORY."
+        )
+    report = load_report(path)
+    from . import __version__
+
+    if report.tool_version != __version__:
+        typer.echo(
+            f"Snapshot uses ColTrace {report.tool_version}; current tool is {__version__}. "
+            "Re-scan the project to include newly supported lineage. Existing facts are retained.",
+            err=True,
+        )
+    return report
+
+
+def _selection(
+    graph: LineageGraph,
+    column: str | None,
+    column_id: str | None,
+    module: str | None,
+    function: str | None,
+    dataframe: str | None,
+    version: int | None,
+    *,
+    required: bool,
+) -> Column | None:
+    if column is not None and column_id is not None:
+        raise ValueError("Use either COLUMN or --column-id, not both.")
+    selector = column_id if column_id is not None else column
+    if selector is None:
+        if required:
+            raise ValueError("Provide a column name or --column-id ID.")
+        if any(value is not None for value in (module, function, dataframe, version)):
+            raise ValueError("Selection filters require COLUMN or --column-id ID.")
+        return None
+    return graph.select(
+        selector, module=module, function=function, dataframe=dataframe, version=version
+    )
+
+
+def _diagnostics(report: LineageReport, *, detailed: bool) -> None:
+    errors = sum(item.severity == "error" for item in report.diagnostics)
+    warnings = len(report.diagnostics) - errors
+    typer.echo(f"Diagnostics: {errors} error(s), {warnings} warning(s).")
+    if detailed:
+        for diagnostic in report.diagnostics:
+            typer.echo(
+                f"  {diagnostic.code} {diagnostic.location.path}:{diagnostic.location.line} "
+                f"[{diagnostic.scope}] {diagnostic.message}"
+            )
+            if diagnostic.hint:
+                typer.echo(f"    Hint: {diagnostic.hint}")
+    elif report.diagnostics:
+        typer.echo("Use --diagnostics for details; unsupported code may leave lineage gaps.")
+
+
+def _display_columns(
+    label: str, columns: list[dict[str, Any]], *, inconclusive: bool = False
+) -> None:
+    typer.echo(f"{label}:")
+    if not columns:
+        if inconclusive:
+            typer.echo("  Not determined: analysis is incomplete.")
+        else:
+            typer.echo("  None identified within the analyzed subset.")
+    for column in columns:
+        location = column["location"]
+        typer.echo(
+            f"  {column['name']}@{column['version']}  "
+            f"{location['path']}:{location['line']}  "
+            f"{column['module']}::{column['scope']}  "
+            f"distance={column.get('distance', '?')} "
+            f"evidence={column.get('path_evidence', column['evidence'])} "
+            f"completeness={column.get('path_completeness', column['completeness'])}"
+        )
+        typer.echo(f"    ID: {column['id']}")
+
+
+def _display_history(query: dict[str, Any]) -> bool:
+    """Present recorded analysis events as a readable source-to-use narrative."""
+    history = query.get("history", {})
+    if not history.get("recorded"):
+        typer.echo(
+            "Recorded history unavailable in this snapshot. Re-scan the project to include "
+            "source expressions, transformation steps, and uses."
+        )
+        return False
+    typer.echo("Column history (static analysis order):")
+    names = {
+        node["id"]: f"{node['name']}@{node['version']}"
+        for node in history.get("nodes", [])
+        if node.get("node_type") == "column"
+    }
+    stages = history.get("stages", [])
+    for index, event in enumerate(stages, 1):
+        location = event["location"]
+        category = event.get("category", "transform")
+        typer.echo(
+            f"  {index:02d}. [{category}] {event['label']}\n"
+            f"      {location['path']}:{location['line']} in "
+            f"{event['module']}::{event['scope']}"
+        )
+        if event.get("expression") and (
+            event["kind"] != "callback_step"
+            or event["label"].startswith("Return")
+            or "guard" in event["label"]
+        ):
+            expression = event["expression"].strip()
+            if expression in event["label"]:
+                expression = ""
+            for line in expression.splitlines():
+                typer.echo(f"      {line}")
+        inputs = [names.get(key, key) for key in event.get("inputs", [])]
+        outputs = [names.get(key, key) for key in event.get("outputs", [])]
+        if (
+            event.get("event_ids")
+            and len(event["event_ids"]) > 1
+            and event["kind"] in {"filter", "dropna", "projection"}
+        ):
+            labels = list(dict.fromkeys(name.rsplit("@", 1)[0] for name in outputs))
+            if labels:
+                typer.echo(f"      Retained columns: {', '.join(labels)}")
+        elif outputs or (inputs and event["category"] in {"use", "boundary"}):
+            typer.echo(
+                f"      Columns: {', '.join(inputs) or '(source)'} -> "
+                f"{', '.join(outputs) or '(use)'}"
+            )
+        if event.get("evidence") == "unresolved":
+            typer.echo(
+                f"      Evidence: {event.get('evidence', 'inferred')}; "
+                f"completeness: {event.get('completeness', 'partial')}."
+            )
+    if not stages:
+        typer.echo("  No relevant events recorded within the selected filters.")
+    typer.echo(
+        "Stages can branch; graph arrows show causality. Row filters preserve values "
+        "while changing which rows continue."
+    )
+    return True
+
+
+def _display_journey(query: dict[str, Any]) -> bool:
+    """Keep direct column actions separate from creation ancestry and frame use."""
+    journey = query.get("journey", {})
+    if not journey.get("recorded"):
+        typer.echo(
+            "Recorded column journey unavailable in this snapshot. Re-scan the project "
+            "to include direct actions and destinations."
+        )
+        return False
+    for source in query.get("history", {}).get("sources", []):
+        if source["kind"] == "source" and source.get("expression"):
+            place = source["location"]
+            typer.echo(f"DataFrame source context: {place['path']}:{place['line']}")
+            for line in source["expression"].strip().splitlines():
+                typer.echo(f"  {line}")
+    for label, group in (("Direct value inputs", "direct"), ("Earlier value inputs", "transitive")):
+        ancestors = query["upstream"][group]
+        if ancestors:
+            typer.echo(f"{label}:")
+            for ancestor in ancestors:
+                place = ancestor["location"]
+                typer.echo(
+                    f"  {ancestor['name']}@{ancestor['version']}  "
+                    f"{place['path']}:{place['line']}  {ancestor['module']}::{ancestor['scope']}"
+                )
+    typer.echo("Column journey (direct uses and outcomes):")
+    for index, step in enumerate(journey.get("steps", []), 1):
+        place = step["location"]
+        typer.echo(
+            f"  {index:02d}. [{step['relationship']}] {step['label']}\n"
+            f"      {place['path']}:{place['line']} in {step['module']}::{step['scope']}"
+        )
+        typer.echo(f"      {step['explanation']}")
+        expression = step.get("expression", "").strip()
+        if expression and expression not in step["label"]:
+            for line in expression.splitlines():
+                typer.echo(f"      {line}")
+        if step.get("evidence") == "unresolved":
+            typer.echo("      Evidence: unresolved; completeness: unresolved.")
+    if not journey.get("steps"):
+        typer.echo("  No eligible recorded action under these query filters.")
+    typer.echo("Derived columns and their outcomes:")
+    derived = journey.get("derived_columns", [])
+    if not derived:
+        typer.echo("  None identified within the analyzed subset and query filters.")
+    for item in derived:
+        fate = item["fate"]
+        place = fate["location"]
+        typer.echo(
+            f"  {item['name']} ({item['relationship']}, distance={item['distance']})\n"
+            f"    {fate['label']} at {place['path']}:{place['line']}"
+        )
+        if item.get("definition"):
+            definition = item["definition"]
+            place = definition["location"]
+            typer.echo(f"    Defined: {place['path']}:{place['line']} in {definition['scope']}")
+        if item.get("upstream"):
+            inputs = ", ".join(f"{value['name']}@{value['version']}" for value in item["upstream"])
+            typer.echo(f"    Value inputs: {inputs}")
+        for frame in item.get("dataframes", []):
+            bindings = ", ".join(
+                dict.fromkeys(
+                    f"{binding['name']} in {binding['scope']}" for binding in frame["bindings"]
+                )
+            )
+            typer.echo(
+                f"    DataFrame: {bindings or frame.get('origin', 'unknown')} [{frame['id']}]"
+            )
+    typer.echo("DataFrames carrying the selected column:")
+    for frame in journey.get("dataframes", []):
+        bindings = frame.get("bindings", [])
+        names = ", ".join(
+            dict.fromkeys(f"{binding['name']} in {binding['scope']}" for binding in bindings)
+        )
+        typer.echo(f"  {names or frame.get('origin', 'unknown')} [{frame['id']}]")
+        place = frame.get("location")
+        if place:
+            typer.echo(f"    {frame.get('origin', 'unknown')} at {place['path']}:{place['line']}")
+    fate = journey.get("fate", {})
+    if fate:
+        place = fate["location"]
+        typer.echo(f"Observed outcome: {fate['label']} at {place['path']}:{place['line']}.")
+    typer.echo(
+        "Frame passage does not prove an internal column read. No later observed use "
+        "does not prove the column is unused."
+    )
+    typer.echo("Use --full-history for creation details, including callback control/configuration.")
+    return True
+
+
+def _display_query(
+    query: dict[str, Any],
+    report: LineageReport,
+    *,
+    impact: bool = False,
+    detailed: bool = False,
+    full_history: bool = False,
+) -> None:
+    column = query["column"]
+    location = column["location"]
+    typer.echo(f"Column: {column['name']}@{column['version']}")
+    typer.echo(f"ID: {column['id']}")
+    typer.echo(f"DataFrame: {column['dataframe_id']}")
+    origin = "First observed" if column["origin"] in {"external_unknown", "opaque"} else "Defined"
+    typer.echo(
+        f"{origin}: {location['path']}:{location['line']} in {column['module']}::{column['scope']}"
+    )
+    typer.echo(f"Evidence: {column['evidence']}; completeness: {column['completeness']}.")
+    frame = next((item for item in report.dataframes if item.id == column["dataframe_id"]), None)
+    if frame is not None:
+        typer.echo(
+            f"DataFrame origin: {frame.origin} at {frame.location.path}:{frame.location.line} "
+            f"in {frame.module}::{frame.scope} (evidence={frame.evidence})."
+        )
+    if column["context"].startswith("template:"):
+        typer.echo("Analysis context: isolated function template; no concrete caller resolved.")
+    inconclusive = (
+        column["origin"] == "opaque"
+        or column["evidence"] == "unresolved"
+        or column["completeness"] == "unresolved"
+    )
+    if inconclusive:
+        typer.echo(
+            "Trace status: inconclusive; the column crosses an unresolved analysis boundary."
+        )
+        typer.echo("Missing upstream/downstream results do not establish absence of dependencies.")
+    elif column["completeness"] != "complete" or query["diagnostics"]:
+        typer.echo("Trace status: partial; only identified dependencies are shown.")
+    if impact:
+        typer.echo("Potential impact from identified dependencies; behavior may remain unchanged.")
+    recorded = False
+    if not impact:
+        recorded = _display_history(query) if full_history else _display_journey(query)
+    if recorded and not detailed and not inconclusive:
+        boundaries = query["history"].get("boundaries", [])
+        if boundaries:
+            typer.echo(
+                "The history reaches an unresolved boundary. Later internal transformations "
+                "cannot be inferred from that call."
+            )
+        typer.echo("Use --diagnostics for dependency details and diagnostic messages.")
+        return
+    for direction in ("upstream", "downstream"):
+        if query["direction"] not in ("both", direction):
+            continue
+        relationships = query[direction]
+        _display_columns(
+            f"{direction.capitalize()} - direct",
+            relationships["direct"],
+            inconclusive=inconclusive,
+        )
+        _display_columns(
+            f"{direction.capitalize()} - transitive",
+            relationships["transitive"],
+            inconclusive=inconclusive,
+        )
+    typer.echo("Read/consumption locations:")
+    if not query["consumptions"]:
+        typer.echo("  None identified.")
+    consumed_columns = {column["id"]: f"{column['name']}@{column['version']}"}
+    for side in ("upstream", "downstream"):
+        for group in ("direct", "transitive"):
+            for item in query[side][group]:
+                consumed_columns[item["id"]] = f"{item['name']}@{item['version']}"
+    for consumption in query["consumptions"]:
+        place = consumption["location"]
+        label = consumed_columns.get(consumption["column_id"], consumption["column_id"])
+        typer.echo(
+            f"  {place['path']}:{place['line']} "
+            f"{consumption['module']}::{consumption['scope']} ({consumption['kind']}: {label})"
+        )
+    if impact:
+        for key, label in (
+            ("direct_functions", "Functions/scopes with direct potential impact"),
+            ("transitive_functions", "Functions/scopes with transitive potential impact"),
+        ):
+            typer.echo(f"{label}:")
+            functions = query.get(key, [])
+            if not functions:
+                typer.echo("  None identified.")
+            for function in functions:
+                typer.echo(f"  {function['module']}::{function['scope']}")
+    elif query["functions"]:
+        label = "identified dependencies" if query["relations"] else "observed column uses"
+        typer.echo(f"Functions/scopes with {label}:")
+        for function in query["functions"]:
+            typer.echo(f"  {function['module']}::{function['scope']}")
+    if query["diagnostics"]:
+        typer.echo("Lineage gaps and related diagnostics:")
+        for diagnostic in query["diagnostics"]:
+            place = diagnostic["location"]
+            typer.echo(
+                f"  {diagnostic['code']} {place['path']}:{place['line']} {diagnostic['message']}"
+            )
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    version: Annotated[
+        bool, typer.Option("--version", is_eager=True, help="Show the installed package version.")
+    ] = False,
+) -> None:
+    if version:
+        from . import __version__
+
+        typer.echo(f"ColTrace {__version__}")
+        raise typer.Exit()
+
+
+@app.command()
+def scan(
+    path: Annotated[Path, typer.Argument(help="Python project directory.")] = Path("."),
+    out: Annotated[Path, typer.Option(help="Directory for the scan.json snapshot.")] = Path(
+        ".coltrace"
+    ),
+    exclude: Annotated[
+        list[str] | None,
+        typer.Option(help="Exclude a path/glob; repeat to override project exclusions."),
+    ] = None,
+    diagnostics: DiagnosticsOption = False,
+) -> None:
+    """Analyze a project without executing it and save a reusable snapshot."""
+    from .analysis import analyze_project
+
+    with _errors():
+        config = ScanConfig(exclude=tuple(exclude)) if exclude is not None else None
+        report = analyze_project(path, config=config)
+        destination = export_json(report, out / "scan.json")
+        typer.echo(
+            f"Analyzed {len(report.files)} file(s): {len(report.dataframes)} DataFrame(s), "
+            f"{len(report.columns)} column version(s), {len(report.operations)} operation(s)."
+        )
+        typer.echo(f"Snapshot: {destination.resolve()}")
+        _diagnostics(report, detailed=diagnostics)
+        if any(item.severity == "error" for item in report.diagnostics):
+            raise typer.Exit(1)
+
+
+@app.command()
+def trace(
+    column: ColumnArgument = None,
+    snapshot: SnapshotOption = None,
+    project: ProjectOption = None,
+    module: ModuleOption = None,
+    function: FunctionOption = None,
+    dataframe: DataFrameOption = None,
+    column_id: ColumnIDOption = None,
+    version: VersionOption = None,
+    depth: DepthOption = None,
+    relation: RelationOption = None,
+    evidence: EvidenceOption = EvidenceFilter.all,
+    upstream: Annotated[bool, typer.Option(help="Show only upstream dependencies.")] = False,
+    downstream: Annotated[bool, typer.Option(help="Show only downstream dependencies.")] = False,
+    full_history: Annotated[
+        bool, typer.Option(help="Include creation ancestry and callback control/configuration.")
+    ] = False,
+    diagnostics: DiagnosticsOption = False,
+) -> None:
+    """Show definitions, dependencies, consumption sites, and unresolved gaps."""
+    with _errors():
+        if upstream and downstream:
+            raise ValueError(
+                "Use either --upstream or --downstream; omit both for both directions."
+            )
+        report = _report(snapshot, project)
+        graph = LineageGraph(report)
+        selected = _selection(
+            graph, column, column_id, module, function, dataframe, version, required=True
+        )
+        assert selected is not None
+        direction: Literal["both", "upstream", "downstream"] = "both"
+        if upstream:
+            direction = "upstream"
+        elif downstream:
+            direction = "downstream"
+        query = graph.trace(
+            selected.id,
+            direction=direction,
+            depth=depth,
+            relation=relation.value if relation else None,
+            evidence=evidence.value,
+        )
+        _display_query(query, report, detailed=diagnostics, full_history=full_history)
+
+
+@app.command()
+def impact(
+    column: ColumnArgument = None,
+    snapshot: SnapshotOption = None,
+    project: ProjectOption = None,
+    module: ModuleOption = None,
+    function: FunctionOption = None,
+    dataframe: DataFrameOption = None,
+    column_id: ColumnIDOption = None,
+    version: VersionOption = None,
+    depth: DepthOption = None,
+    relation: RelationOption = None,
+    evidence: EvidenceOption = EvidenceFilter.all,
+    diagnostics: DiagnosticsOption = False,
+) -> None:
+    """Show direct and transitive potential impacts of changing a column."""
+    with _errors():
+        report = _report(snapshot, project)
+        graph = LineageGraph(report)
+        selected = _selection(
+            graph, column, column_id, module, function, dataframe, version, required=True
+        )
+        assert selected is not None
+        query = graph.impact(
+            selected.id,
+            depth=depth,
+            relation=relation.value if relation else None,
+            evidence=evidence.value,
+        )
+        _display_query(query, report, impact=True, detailed=diagnostics)
+
+
+@app.command()
+def graph(
+    column: ColumnArgument = None,
+    snapshot: SnapshotOption = None,
+    project: ProjectOption = None,
+    module: ModuleOption = None,
+    function: FunctionOption = None,
+    dataframe: DataFrameOption = None,
+    column_id: ColumnIDOption = None,
+    version: VersionOption = None,
+    depth: DepthOption = None,
+    relation: RelationOption = None,
+    evidence: EvidenceOption = EvidenceFilter.all,
+    output: Annotated[Path, typer.Option(help="Destination HTML file.")] = Path(
+        ".coltrace/graph.html"
+    ),
+    operations: Annotated[bool, typer.Option(help="Include operation nodes.")] = False,
+    view: Annotated[
+        GraphView, typer.Option(help="Selected column history or column dependency projection.")
+    ] = GraphView.history,
+    open_browser: Annotated[bool, typer.Option("--open", help="Open the local HTML file.")] = False,
+    diagnostics: DiagnosticsOption = False,
+) -> None:
+    """Generate an interactive, offline HTML graph (requires coltrace[viz])."""
+    with _errors():
+        report = _report(snapshot, project)
+        selected = _selection(
+            LineageGraph(report),
+            column,
+            column_id,
+            module,
+            function,
+            dataframe,
+            version,
+            required=False,
+        )
+        if depth is not None and selected is None:
+            raise ValueError("--depth requires COLUMN or --column-id ID.")
+        destination = export_html(
+            report,
+            output,
+            column_id=selected.id if selected else None,
+            depth=depth,
+            relation=relation.value if relation else None,
+            evidence=evidence.value,
+            operations=operations,
+            view=view.value,
+        )
+        typer.echo(f"Graph: {destination.resolve()}")
+        _diagnostics(report, detailed=diagnostics)
+        if open_browser and not webbrowser.open(destination.resolve().as_uri()):
+            typer.echo("Could not open a browser automatically. Open the HTML file above.")
+
+
+@app.command(name="export")
+def export_command(
+    column: ColumnArgument = None,
+    snapshot: SnapshotOption = None,
+    project: ProjectOption = None,
+    module: ModuleOption = None,
+    function: FunctionOption = None,
+    dataframe: DataFrameOption = None,
+    column_id: ColumnIDOption = None,
+    version: VersionOption = None,
+    depth: DepthOption = None,
+    relation: RelationOption = None,
+    evidence: EvidenceOption = EvidenceFilter.all,
+    format: Annotated[ExportFormat, typer.Option(help="Output format.")] = ExportFormat.json,
+    output: Annotated[
+        Path | None, typer.Option(help="Output file; defaults inside .coltrace.")
+    ] = None,
+    diagnostics: DiagnosticsOption = False,
+) -> None:
+    """Export a full snapshot or selected column neighborhood as JSON or HTML."""
+    with _errors():
+        report = _report(snapshot, project)
+        selected = _selection(
+            LineageGraph(report),
+            column,
+            column_id,
+            module,
+            function,
+            dataframe,
+            version,
+            required=False,
+        )
+        if depth is not None and selected is None:
+            raise ValueError("--depth requires COLUMN or --column-id ID.")
+        destination = output or Path(f".coltrace/export.{format.value}")
+        exporter = export_json if format is ExportFormat.json else export_html
+        destination = exporter(
+            report,
+            destination,
+            column_id=selected.id if selected else None,
+            depth=depth,
+            relation=relation.value if relation else None,
+            evidence=evidence.value,
+        )
+        typer.echo(f"Exported: {destination.resolve()}")
+        if format is ExportFormat.json and selected is not None:
+            typer.echo("This is a query export; use 'coltrace scan' to create a reusable snapshot.")
+        _diagnostics(report, detailed=diagnostics)