Online Report Python API
========================

Transform local file references in a LOBSTER report into immutable GitHub URLs (commit-pinned) for web publication.

API
---

::

  from lobster.tools.core.online_report.online_report import lobster_online_report
  lobster_online_report(config: Config, out_file: str)

Configuration Dataclass
-----------------------

::

  from lobster.tools.core.online_report.online_report import Config, lobster_online_report

  cfg = Config(
     repo_root=".",
     base_url="https://github.com/org/repo",
     commit_id="<GIT_COMMIT_SHA>",
     report="report.lobster",   # optional; defaults to "report.lobster"
  )

``Config`` fields:

- ``repo_root: str`` - Absolute or relative path to the Git repository root; used to compute in‑repo relative paths.
- ``base_url: str`` - Base GitHub (or forge) URL without trailing slash (e.g. ``https://github.com/org/repo``).
- ``commit_id: str`` - Commit hash ensuring links resolve to a stable snapshot.
- ``report: str`` - Path to the input LOBSTER report (default ``report.lobster``).

Stable API Function
-------------------

``lobster_online_report(config: Config, out_file: str) -> None``
  Loads the existing report, rewrites ``File_Reference`` locations as ``Github_Reference`` objects, then writes an updated artifact.

Example (Custom Root & Commit)
------------------------------

::

  from lobster.tools.core.online_report.online_report import Config, lobster_online_report

  cfg = Config(
     repo_root="/workspace/project",
     base_url="https://github.com/org/project",
     commit_id="d34sbd3p7e8n9a...",
     report="artifact/report.lobster",
  )

  lobster_online_report(cfg, "artifact/online_report.lobster")

Behavioral Notes
----------------
- Only items whose location is a ``File_Reference`` are converted; existing ``Github_Reference`` entries remain untouched.
- Paths outside ``repo_root`` are skipped with a warning (not inside repository).
- Output preserves all non-location metadata (tags, tracing status, messages).
- The tool does not perform a git rev-parse; it trusts the provided ``commit_id``.

Core Goals
----------
- Produce a shareable report with stable, clickable source links.
- Replace local file paths with web URLs.
- Enable publishing reports on webpages.

Error Conditions
----------------
- Missing input report file → ``FileNotFoundError``.
- Invalid config structure (when parsed from YAML) → ``KeyError`` / ``ValueError``.
- Non-string fields for ``base_url`` / ``repo_root`` / ``commit_id`` → ``ValueError``.