@spec from_report(map()) :: {:ok, map()} | {:error, String.t()}

Generates a map of OCI annotation key-value pairs from a single-repo LEI report.

Returns {:ok, map} where all keys are dev.lowendinsight.* strings and all values are strings (per OCI spec). Returns {:error, reason} for unsupported formats.

Examples

iex> report = %{header: %{start_time: "2024-01-01T00:00:00Z"}, data: %{repo: "https://github.com/org/repo", results: %{risk: "critical", contributor_count: 1}}}
iex> {:ok, annotations} = Lei.OCI.Annotations.from_report(report)
iex> annotations["dev.lowendinsight.risk"]
"critical"

@spec from_results(map(), String.t(), String.t()) :: {:ok, map()}

Generates OCI annotations directly from a results map, repo URL, and timestamp.

Useful when you already have extracted analysis results and don't need to parse a full report structure.

@spec to_cli_flags(map()) :: [String.t()]

Returns annotations as a list of --annotation key=value CLI flag strings, suitable for passing to docker buildx build or oras push.

@spec to_json(map()) :: {:ok, String.t()}

Encodes annotations as a JSON string suitable for --annotation-file flags in OCI tooling (crane, oras, docker buildx).