feat(cli): add browser-open HTML reports and timestamped default report paths

Author: orenlab

CHANGELOG.md

@@ -75,6 +75,9 @@ ahead of the final `2.0.0` release.
     - `--md` → `.cache/codeclone/report.md`
     - `--sarif` → `.cache/codeclone/report.sarif`
     - `--text` → `.cache/codeclone/report.txt`
+- Added local report UX helpers:
+    - `--open-html-report` opens the generated HTML report after a successful write
+    - `--timestamped-report-paths` appends a UTC timestamp to default report filenames requested via bare report flags
 - Added optional-value path flags for default-path intent:
     - `--baseline`
     - `--metrics-baseline`

README.md

@@ -40,7 +40,9 @@ pip install codeclone        # or: uv tool install codeclone
 
 codeclone .                  # analyze current directory
 codeclone . --html           # generate HTML report
+codeclone . --html --open-html-report   # generate and open HTML report
 codeclone . --json --md --sarif --text   # generate machine-readable reports
+codeclone . --html --json --timestamped-report-paths   # keep timestamped report snapshots
 codeclone . --ci             # CI mode (--fail-on-new --no-color --quiet)
 ```
 
@@ -148,7 +150,11 @@ Contract errors (`2`) take precedence over gating failures (`3`).
 | Text     | `--text`  | `.cache/codeclone/report.txt`   |
 
 All report formats are rendered from one canonical JSON report document.
-Structural findings include:
+
+- `--open-html-report` opens the generated HTML report in the default browser and requires `--html`.
+- `--timestamped-report-paths` appends a UTC timestamp to default report filenames for bare report flags such as
+  `--html` or `--json`. Explicit report paths are not rewritten.
+  Structural findings include:
 
 - `duplicated_branches`
 - `clone_guard_exit_divergence`
@@ -284,7 +290,7 @@ Architecture: [`docs/architecture.md`](docs/architecture.md) · CFG semantics: [
 | Docker benchmark contract  | [`docs/book/18-benchmarking.md`](docs/book/18-benchmarking.md)                           |
 | Determinism                | [`docs/book/12-determinism.md`](docs/book/12-determinism.md)                             |
 
-##    * Benchmarking
+##     * Benchmarking
 
 <details>
 <summary>Reproducible Docker Benchmark</summary>

codeclone/_cli_args.py

@@ -299,8 +299,18 @@ def build_parser(version: str) -> _ArgumentParser:
         const=DEFAULT_TEXT_REPORT_PATH,
         help_text=ui.HELP_TEXT,
     )
+    _add_bool_optional_argument(
+        reporting_group,
+        flag="--timestamped-report-paths",
+        help_text=ui.HELP_TIMESTAMPED_REPORT_PATHS,
+    )
 
     ui_group = ap.add_argument_group("Output and UI")
+    _add_bool_optional_argument(
+        ui_group,
+        flag="--open-html-report",
+        help_text=ui.HELP_OPEN_HTML_REPORT,
+    )
     ui_group.add_argument(
         "--no-progress",
         dest="no_progress",

codeclone/_cli_meta.py

@@ -91,6 +91,7 @@ def _build_report_meta(
     health_grade: str | None,
     analysis_mode: str,
     metrics_computed: tuple[str, ...],
+    report_generated_at_utc: str,
 ) -> ReportMeta:
     project_name = scan_root.name or str(scan_root)
     return {
@@ -132,5 +133,5 @@ def _build_report_meta(
         "health_grade": health_grade,
         "analysis_mode": analysis_mode,
         "metrics_computed": list(metrics_computed),
-        "report_generated_at_utc": _current_report_timestamp_utc(),
+        "report_generated_at_utc": report_generated_at_utc,
     }

codeclone/_cli_reports.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import sys
+import webbrowser
 from pathlib import Path
 from typing import Protocol
 
@@ -74,12 +75,18 @@ def _write_report_output(
         sys.exit(ExitCode.CONTRACT_ERROR)
 
 
+def _open_html_report_in_browser(*, path: Path) -> None:
+    if not webbrowser.open_new_tab(path.as_uri()):
+        raise OSError("no browser handler available")
+
+
 def write_report_outputs(
     *,
     args: _QuietArgs,
     output_paths: _OutputPaths,
     report_artifacts: _ReportArtifacts,
     console: _PrinterLike,
+    open_html_report: bool = False,
 ) -> str | None:
     html_report_path: str | None = None
     saved_reports: list[tuple[str, Path]] = []
@@ -145,4 +152,12 @@ def write_report_outputs(
                 display = path
             console.print(f"  [bold]{label} report saved:[/bold] [dim]{display}[/dim]")
 
+    if open_html_report and output_paths.html is not None:
+        try:
+            _open_html_report_in_browser(path=output_paths.html)
+        except Exception as exc:
+            console.print(
+                ui.fmt_html_report_open_failed(path=output_paths.html, error=exc)
+            )
+
     return html_report_path

codeclone/cli.py

@@ -8,7 +8,7 @@
 import time
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Protocol, cast
+from typing import TYPE_CHECKING, Literal, Protocol, cast
 
 from . import __version__
 from . import ui_messages as ui
@@ -304,6 +304,7 @@ def print(self, *objects: object, **kwargs: object) -> None: ...
 
 
 LEGACY_CACHE_PATH = Path("~/.cache/codeclone/cache.json").expanduser()
+ReportPathOrigin = Literal["default", "explicit"]
 
 
 def _rich_progress_symbols() -> tuple[
@@ -382,7 +383,65 @@ def _is_debug_enabled(
     return debug_from_flag or debug_from_env
 
 
-def _resolve_output_paths(args: Namespace) -> OutputPaths:
+def _report_path_origins(argv: Sequence[str]) -> dict[str, ReportPathOrigin | None]:
+    origins: dict[str, ReportPathOrigin | None] = {
+        "html": None,
+        "json": None,
+        "md": None,
+        "sarif": None,
+        "text": None,
+    }
+    flag_to_field = {
+        "--html": "html",
+        "--json": "json",
+        "--md": "md",
+        "--sarif": "sarif",
+        "--text": "text",
+    }
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token == "--":
+            break
+        if "=" in token:
+            flag, _value = token.split("=", maxsplit=1)
+            field_name = flag_to_field.get(flag)
+            if field_name is not None:
+                origins[field_name] = "explicit"
+            index += 1
+            continue
+        field_name = flag_to_field.get(token)
+        if field_name is None:
+            index += 1
+            continue
+        next_token = argv[index + 1] if index + 1 < len(argv) else None
+        if next_token is None or next_token.startswith("-"):
+            origins[field_name] = "default"
+            index += 1
+            continue
+        origins[field_name] = "explicit"
+        index += 2
+    return origins
+
+
+def _report_path_timestamp_slug(report_generated_at_utc: str) -> str:
+    return report_generated_at_utc.replace("-", "").replace(":", "")
+
+
+def _timestamped_report_path(path: Path, *, report_generated_at_utc: str) -> Path:
+    suffix = path.suffix
+    stem = path.name[: -len(suffix)] if suffix else path.name
+    return path.with_name(
+        f"{stem}-{_report_path_timestamp_slug(report_generated_at_utc)}{suffix}"
+    )
+
+
+def _resolve_output_paths(
+    args: Namespace,
+    *,
+    report_path_origins: Mapping[str, ReportPathOrigin | None],
+    report_generated_at_utc: str,
+) -> OutputPaths:
     printer = cast("_PrinterLike", console)
     resolved: dict[str, Path | None] = {
         "html": None,
@@ -403,14 +462,23 @@ def _resolve_output_paths(args: Namespace) -> OutputPaths:
         raw_value = getattr(args, arg_name, None)
         if not raw_value:
             continue
-        resolved[field_name] = _validate_output_path(
+        path = _validate_output_path(
             raw_value,
             expected_suffix=expected_suffix,
             label=label,
             console=printer,
             invalid_message=ui.fmt_invalid_output_extension,
             invalid_path_message=ui.fmt_invalid_output_path,
         )
+        if (
+            args.timestamped_report_paths
+            and report_path_origins.get(field_name) == "default"
+        ):
+            path = _timestamped_report_path(
+                path,
+                report_generated_at_utc=report_generated_at_utc,
+            )
+        resolved[field_name] = path
 
     return OutputPaths(
         html=resolved["html"],
@@ -421,6 +489,26 @@ def _resolve_output_paths(args: Namespace) -> OutputPaths:
     )
 
 
+def _validate_report_ui_flags(*, args: Namespace, output_paths: OutputPaths) -> None:
+    if args.open_html_report and output_paths.html is None:
+        console.print(ui.fmt_contract_error(ui.ERR_OPEN_HTML_REPORT_REQUIRES_HTML))
+        sys.exit(ExitCode.CONTRACT_ERROR)
+
+    if args.timestamped_report_paths and not any(
+        (
+            output_paths.html,
+            output_paths.json,
+            output_paths.md,
+            output_paths.sarif,
+            output_paths.text,
+        )
+    ):
+        console.print(
+            ui.fmt_contract_error(ui.ERR_TIMESTAMPED_REPORT_PATHS_REQUIRES_REPORT)
+        )
+        sys.exit(ExitCode.CONTRACT_ERROR)
+
+
 def _resolve_cache_path(*, root_path: Path, args: Namespace, from_args: bool) -> Path:
     return _resolve_cache_path_impl(
         root_path=root_path,
@@ -629,12 +717,14 @@ def _write_report_outputs(
     args: Namespace,
     output_paths: OutputPaths,
     report_artifacts: ReportArtifacts,
+    open_html_report: bool = False,
 ) -> str | None:
     return _write_report_outputs_impl(
         args=cast("_QuietArgsLike", cast(object, args)),
         output_paths=output_paths,
         report_artifacts=report_artifacts,
         console=cast("_PrinterLike", console),
+        open_html_report=open_html_report,
     )
 
 
@@ -757,7 +847,7 @@ def _main_impl() -> None:
     global console
 
     run_started_at = time.monotonic()
-    from ._cli_meta import _build_report_meta
+    from ._cli_meta import _build_report_meta, _current_report_timestamp_utc
 
     ap = build_parser(__version__)
 
@@ -771,10 +861,13 @@ def _prepare_run_inputs() -> tuple[
         OutputPaths,
         Path,
         dict[str, object] | None,
+        str,
     ]:
         global console
         raw_argv = tuple(sys.argv[1:])
         explicit_cli_dests = collect_explicit_cli_dests(ap, argv=raw_argv)
+        report_path_origins = _report_path_origins(raw_argv)
+        report_generated_at_utc = _current_report_timestamp_utc()
         cache_path_from_args = any(
             arg in {"--cache-dir", "--cache-path"}
             or arg.startswith(("--cache-dir=", "--cache-path="))
@@ -896,7 +989,12 @@ def _prepare_run_inputs() -> tuple[
         if not args.quiet:
             print_banner(root=root_path)
 
-        output_paths = _resolve_output_paths(args)
+        output_paths = _resolve_output_paths(
+            args,
+            report_path_origins=report_path_origins,
+            report_generated_at_utc=report_generated_at_utc,
+        )
+        _validate_report_ui_flags(args=args, output_paths=output_paths)
         cache_path = _resolve_cache_path(
             root_path=root_path,
             args=args,
@@ -912,6 +1010,7 @@ def _prepare_run_inputs() -> tuple[
             output_paths,
             cache_path,
             shared_baseline_payload,
+            report_generated_at_utc,
         )
 
     (
@@ -924,6 +1023,7 @@ def _prepare_run_inputs() -> tuple[
         output_paths,
         cache_path,
         shared_baseline_payload,
+        report_generated_at_utc,
     ) = _prepare_run_inputs()
 
     cache = Cache(
@@ -1020,6 +1120,7 @@ def _prepare_run_inputs() -> tuple[
         ),
         analysis_mode=("clones_only" if args.skip_metrics else "full"),
         metrics_computed=_metrics_computed(args),
+        report_generated_at_utc=report_generated_at_utc,
     )
 
     baseline_for_diff = (
@@ -1096,6 +1197,7 @@ def _prepare_run_inputs() -> tuple[
         args=args,
         output_paths=output_paths,
         report_artifacts=report_artifacts,
+        open_html_report=args.open_html_report,
     )
 
     _enforce_gating(

codeclone/ui_messages.py

@@ -114,6 +114,13 @@
     "Generate a plain-text report.\n"
     "If FILE is omitted, writes to .cache/codeclone/report.txt."
 )
+HELP_OPEN_HTML_REPORT = (
+    "Open the generated HTML report in the default browser.\nRequires --html."
+)
+HELP_TIMESTAMPED_REPORT_PATHS = (
+    "Append a UTC timestamp to default report filenames.\n"
+    "Applies only to report flags passed without FILE."
+)
 HELP_NO_PROGRESS = "Disable progress output.\nRecommended for CI logs."
 HELP_PROGRESS = "Force-enable progress output."
 HELP_NO_COLOR = "Disable ANSI colors."
@@ -176,6 +183,9 @@
 )
 WARN_FAILED_FILES_HEADER = "\n[warning]{count} files failed to process:[/warning]"
 WARN_CACHE_SAVE_FAILED = "[warning]Failed to save cache: {error}[/warning]"
+WARN_HTML_REPORT_OPEN_FAILED = (
+    "[warning]Failed to open HTML report in browser: {path} ({error}).[/warning]"
+)
 
 ERR_INVALID_OUTPUT_EXT = (
     "[error]Invalid {label} output extension: {path} "
@@ -194,6 +204,13 @@
 ERR_REPORT_WRITE_FAILED = (
     "[error]Failed to write {label} report: {path} ({error}).[/error]"
 )
+ERR_OPEN_HTML_REPORT_REQUIRES_HTML = (
+    "[error]--open-html-report requires --html.[/error]"
+)
+ERR_TIMESTAMPED_REPORT_PATHS_REQUIRES_REPORT = (
+    "[error]--timestamped-report-paths requires at least one report output "
+    "flag.[/error]"
+)
 ERR_UNREADABLE_SOURCE_IN_GATING = (
     "One or more source files could not be read in CI/gating mode.\n"
     "Unreadable source files: {count}."
@@ -280,6 +297,10 @@ def fmt_report_write_failed(*, label: str, path: Path, error: object) -> str:
     return ERR_REPORT_WRITE_FAILED.format(label=label, path=path, error=error)
 
 
+def fmt_html_report_open_failed(*, path: Path, error: object) -> str:
+    return WARN_HTML_REPORT_OPEN_FAILED.format(path=path, error=error)
+
+
 def fmt_unreadable_source_in_gating(*, count: int) -> str:
     return ERR_UNREADABLE_SOURCE_IN_GATING.format(count=count)