# `Lei.OCI.Annotations`
[🔗](https://github.com/gtri/lowendinsight/blob/main/lib/oci/annotations.ex#L5)

Generates OCI image annotations from LowEndInsight analysis reports.

Annotations follow the `dev.lowendinsight.*` namespace using OCI annotation
conventions (reverse-DNS prefix, hyphenated keys, string values).

See `docs/OCI_ANNOTATION_SCHEMA.md` for the full schema specification.

# `from_report`

```elixir
@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"

# `from_results`

```elixir
@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.

# `to_cli_flags`

```elixir
@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`.

# `to_json`

```elixir
@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).

---

*Consult [api-reference.md](api-reference.md) for complete listing*