dockerls 1.0.0__py3-none-any.whl

dockerls/cli/progress.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskID,
+    TextColumn,
+    TimeElapsedColumn,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from types import TracebackType
+
+
+class RichScanObserver:
+    """Renders scan progress as a single self-updating line.
+
+    Exactly one `Progress` (one Rich live display) exists per run, and it
+    renders to **stderr** while results are printed to stdout. That split is
+    what makes duplication structurally impossible: the live region and the
+    results stream are different file objects, so a result can never be
+    drawn into a progress frame, and piping stdout leaves the progress
+    display on the terminal where it belongs.
+
+    Anything that writes through `sys.stdout`/`sys.stderr` during the run
+    (a stray print, a loguru console sink) is captured by Rich and re-emitted
+    above the bar rather than tearing through the live region.
+    """
+
+    def __init__(self, console: Console | None = None, enabled: bool = True):
+        # Default to a dedicated stderr console so the caller's stdout
+        # console is never shared with the live display.
+        self._console = console if console is not None else Console(stderr=True)
+        self._enabled = enabled
+        self._progress: Progress | None = None
+        self._task_id: TaskID | None = None
+        self._total = 0
+        self._done = 0
+        self._entered = False
+
+    @property
+    def progress(self) -> Progress | None:
+        """The single live display, or None when disabled/not started."""
+        return self._progress
+
+    def __enter__(self) -> RichScanObserver:
+        if self._entered:
+            raise RuntimeError(
+                "RichScanObserver is not re-entrant: a second live display "
+                "would render a duplicate progress bar"
+            )
+        self._entered = True
+        if self._enabled:
+            self._progress = Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                BarColumn(bar_width=24),
+                TimeElapsedColumn(),
+                console=self._console,
+                transient=True,
+                # Stray writes get rendered above the bar instead of
+                # corrupting the live region into a duplicate.
+                redirect_stdout=True,
+                redirect_stderr=True,
+                refresh_per_second=8,
+            )
+            self._progress.start()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        if self._progress is not None:
+            self._progress.stop()
+            self._progress = None
+        self._task_id = None
+
+    def _describe(self, image_reference: str) -> str:
+        return f"Scanning {image_reference}... [{self._done + 1}/{self._total}]"
+
+    def phase(self, description: str) -> None:
+        if self._progress is None:
+            return
+        if self._task_id is None:
+            self._task_id = self._progress.add_task(description, total=None)
+        else:
+            self._progress.update(self._task_id, description=description)
+
+    def phase_result(self, title: str, facts: Sequence[tuple[str, str]]) -> None:
+        """Print what a phase produced, above the live progress line.
+
+        Rendered as a small tree so a run reads as a sequence of accounted
+        steps rather than a spinner that may or may not be stuck:
+
+            Discovering tags
+            ├─ found            100
+            ├─ unique digests    84
+            └─ duplicates        16
+
+        Written through `self._console` (stderr), so it never mixes with
+        results on stdout and `dockerls recommend > out.txt` still yields a
+        clean file. When the display is disabled -- `--no-progress`, or
+        `--format json` -- nothing is emitted at all.
+        """
+        if self._progress is None or not facts:
+            return
+        width = max(len(label) for label, _ in facts)
+        # Leading blank line: consecutive phases run together otherwise, and
+        # in a CI log they are the only structure the reader gets.
+        lines = ["", f"[bold]{title}[/bold]"]
+        for index, (label, value) in enumerate(facts):
+            branch = "└─" if index == len(facts) - 1 else "├─"
+            lines.append(f"[dim]{branch}[/dim] {label:<{width}}  [cyan]{value}[/cyan]")
+        # `Progress.console.print` routes through the live display, which
+        # moves the bar down and prints above it instead of tearing it.
+        self._progress.console.print("\n".join(lines))
+
+    def start(self, total: int) -> None:
+        self._total = total
+        self._done = 0
+        if self._progress is None:
+            return
+        if self._task_id is None:
+            self._task_id = self._progress.add_task("Scanning...", total=total)
+        else:
+            self._progress.update(self._task_id, total=total, completed=0)
+
+    def scanning(self, image_reference: str) -> None:
+        if self._progress is None or self._task_id is None:
+            return
+        self._progress.update(self._task_id, description=self._describe(image_reference))
+
+    def finished(self, image_reference: str, ok: bool) -> None:  # noqa: ARG002
+        self._done += 1
+        if self._progress is None or self._task_id is None:
+            return
+        self._progress.update(self._task_id, completed=self._done)

dockerls/cli/publish_prompt.py

@@ -0,0 +1,123 @@
+"""Perguntar destino e responsabilidade **antes** do build, não depois.
+
+Três coisas precisam estar decididas antes de um `docker build` começar: para
+onde a imagem vai, quem responde por ela, e para quem se avisa quando ela
+tiver uma vulnerabilidade. Nenhuma delas era perguntada -- o `--push` publicava
+a tag local como está, e `--labels` aceitava um JSON vazio sem exigir nada.
+
+A ordem importa e é o ponto do módulo. Descobrir que o destino está errado
+depois de validar, construir e escanear desperdiça o trabalho inteiro, e é
+exatamente quando alguém está mais propenso a publicar em qualquer lugar só
+para não repetir a espera. Rotular depois do build é pior ainda: a imagem já
+existe, e rotular passa a significar reconstruir.
+
+Nada aqui pergunta o que já foi respondido por opção de linha de comando, e
+`--non-interactive` (assim como `--ci-mode`) troca a pergunta por uma falha
+explícita, porque um pipeline não tem quem responda e travar esperando entrada
+é o pior comportamento possível num runner.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from rich.console import Console
+from rich.prompt import Prompt
+
+from dockerls.domain.value_objects.build_labels import REQUIRED_FIELDS, BuildIdentity
+from dockerls.domain.value_objects.registry_target import RegistryTarget
+
+console = Console()
+
+#: Exemplos por provedor, mostrados na pergunta do destino. Um formato errado
+#: de Artifact Registry só falharia na hora do push, minutos depois.
+DESTINATION_EXAMPLES = (
+    "Azure ACR        meuregistro.azurecr.io/apps/minha-app",
+    "Google Artifact  us-central1-docker.pkg.dev/meu-projeto/containers/minha-app",
+    "Google GCR       gcr.io/meu-projeto/minha-app",
+    "Docker Hub       minhaorg/minha-app",
+    "Registry privado registry.interna:5000/time/minha-app",
+)
+
+
+def interactive_available(*, non_interactive: bool) -> bool:
+    """Se dá para perguntar: alguém precisa estar do outro lado do terminal."""
+    return not non_interactive and sys.stdin.isatty()
+
+
+def resolve_destination(
+    destination: str | None,
+    tag: str,
+    *,
+    non_interactive: bool,
+) -> RegistryTarget | None:
+    """O destino de publicação, perguntado quando não veio por opção.
+
+    None significa "não publicar", que é uma resposta legítima e o padrão:
+    construir sem publicar é o fluxo mais comum.
+    """
+    answer = (destination or "").strip()
+    if not answer:
+        if not interactive_available(non_interactive=non_interactive):
+            return None
+        console.print("\n[bold]Where is this image going?[/bold]")
+        for example in DESTINATION_EXAMPLES:
+            console.print(f"  [dim]{example}[/dim]")
+        answer = Prompt.ask(
+            "Destination (empty = do not publish)",
+            default="",
+            show_default=False,
+            console=console,
+        ).strip()
+        if not answer:
+            return None
+
+    target = RegistryTarget.parse(answer, tag)
+    target.validate()
+    console.print(
+        f"[dim]Destino: {target.reference}  ({target.provider})\n"
+        f"Authentication: {target.login_hint}[/dim]"
+    )
+    return target
+
+
+def resolve_identity(
+    identity: BuildIdentity,
+    *,
+    non_interactive: bool,
+) -> BuildIdentity:
+    """Completa os rótulos obrigatórios, perguntando o que falta.
+
+    Em modo não interativo os que faltarem viram erro em vez de pergunta: um
+    pipeline não tem quem responda, e publicar sem responsável é o cenário que
+    estes campos existem para impedir.
+    """
+    missing = identity.missing()
+    if not missing:
+        return identity
+    if not interactive_available(non_interactive=non_interactive):
+        identity.require_complete()
+        return identity
+
+    prompts = dict(REQUIRED_FIELDS)
+    answers: dict[str, str] = {}
+    console.print("\n[bold]Who answers for this image?[/bold]")
+    console.print(
+        "[dim]Becomes an OCI label on the manifest. It is what someone reads at three "
+        "in the morning to find out where the image came from and who to call.[/dim]"
+    )
+    for name in missing:
+        answers[name] = Prompt.ask(f"  {prompts[name]}", console=console).strip()
+
+    completed = BuildIdentity(
+        owner=answers.get("owner", identity.owner),
+        security_contact=answers.get("security_contact", identity.security_contact),
+        source=answers.get("source", identity.source),
+        title=identity.title,
+        description=identity.description,
+        version=identity.version,
+        revision=identity.revision,
+        extra=identity.extra,
+    )
+    completed.require_complete()
+    return completed

dockerls/cli/rendering.py

@@ -0,0 +1,214 @@
+"""Shared Rich rendering for Dockerfile validation results.
+
+`analyze-dockerfile` and `build --validate-only` report the same thing --
+which OWASP checks a Dockerfile passed, warned on or failed -- so they render
+it through the same code. Duplicating the table is how the two commands
+started drifting apart, with `build` printing nothing at all.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.panel import Panel
+from rich.table import Table
+
+from dockerls.domain.entities.dockerfile_analysis import ValidationStatus
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from dockerls.domain.entities.dockerfile_analysis import (
+        DockerfileAnalysis,
+        DockerfileValidationResult,
+        HardeningRule,
+    )
+
+# Valores de status renderizados, não senhas. Bandit's B105 (hardcoded
+# password) matches on the dict *key* looking like a secret name -- "PASS"
+# does, "WARN"/"FAIL"/"SKIP" don't -- so only that one line ever needs the
+# suppression; the others never triggered anything to suppress.
+_STATUS_ICONS = {
+    "PASS": "[green]PASS[/green]",  # nosec B105
+    "WARN": "[yellow]WARN[/yellow]",
+    "FAIL": "[red]FAIL[/red]",
+    "SKIP": "[dim]SKIP[/dim]",
+}
+
+_SEVERITY_STYLES = {
+    "CRITICAL": "red bold",
+    "HIGH": "red",
+    "MEDIUM": "yellow",
+    "LOW": "dim",
+    "INFO": "dim",
+}
+
+_TIER_COLORS = {"A": "green", "B": "yellow", "C": "yellow", "D": "red", "F": "red"}
+
+
+def render_validation_report(
+    console: Console,
+    validation: DockerfileValidationResult,
+    analysis: DockerfileAnalysis | None = None,
+    suggestions: list[HardeningRule] | None = None,
+    title: str = "Dockerfile Analysis Report",
+) -> None:
+    """Render the header, summary, checks table, score and suggestions.
+
+    Every section is optional except the checks table: a caller that has no
+    analysis or no suggestions simply gets fewer panels, never a `None`.
+    """
+    _render_header(console, validation, title)
+    _render_summary(console, validation)
+    _render_checks(console, validation)
+    if analysis is not None:
+        _render_score(console, analysis)
+        _render_template_origin(console, analysis)
+    if suggestions:
+        _render_suggestions(console, suggestions)
+
+
+def _render_header(console: Console, validation: DockerfileValidationResult, title: str) -> None:
+    path = validation.dockerfile_path or "Dockerfile"
+    console.print(Panel(f"[bold cyan]{title}[/bold cyan]\n[dim]{path}[/dim]", expand=False))
+    console.print()
+
+
+def _render_summary(console: Console, validation: DockerfileValidationResult) -> None:
+    status_color = "green" if validation.errors == 0 else "red"
+    console.print(
+        f"[{status_color} bold]Summary:[/{status_color} bold] "
+        f"[green]{validation.passed} passed[/green] | "
+        f"[yellow]{validation.warnings} warnings[/yellow] | "
+        f"[red]{validation.errors} errors[/red]"
+    )
+    console.print()
+
+
+def _render_checks(console: Console, validation: DockerfileValidationResult) -> None:
+    if not validation.checks:
+        console.print("[dim]No validation checks were produced for this Dockerfile.[/dim]")
+        console.print()
+        return
+
+    table = Table(title="Validation Checks", expand=False)
+    table.add_column("Status", style="bold", width=8)
+    table.add_column("Check", style="cyan")
+    table.add_column("Message", style="white")
+    table.add_column("Severity", justify="center")
+
+    for check in validation.checks:
+        severity = check.severity.value
+        severity_style = _SEVERITY_STYLES.get(severity, "")
+        table.add_row(
+            _STATUS_ICONS.get(check.status.value, check.status.value),
+            check.check,
+            check.message,
+            f"[{severity_style}]{severity}[/{severity_style}]" if severity_style else severity,
+        )
+
+    console.print(table)
+    console.print()
+    _render_controls(console, validation)
+
+
+def _render_controls(console: Console, validation: DockerfileValidationResult) -> None:
+    """Cite the published control behind each finding that failed.
+
+    Only failures and warnings: a passing check needs no justification, and
+    printing a citation for all twelve rules would bury the two the reader
+    has to act on.
+
+    A rule with no published control says so. Leaving the line out would
+    read as "citation omitted", and the difference between "this is CIS 4.1"
+    and "this is our opinion" is exactly what the reader is entitled to.
+    """
+    actionable = [
+        check
+        for check in validation.checks
+        if check.status in (ValidationStatus.FAIL, ValidationStatus.WARN) and check.rule_id
+    ]
+    if not actionable:
+        return
+
+    console.print("[bold]Reference controls[/bold]")
+    seen: set[str] = set()
+    for check in actionable:
+        rule_id = check.rule_id or ""
+        if rule_id in seen:
+            continue
+        seen.add(rule_id)
+        console.print(f"  [cyan]{rule_id}[/cyan]  {check.check}")
+        if check.rationale:
+            console.print(f"    [dim]{check.rationale}[/dim]")
+        for reference in check.references:
+            console.print(f"    [green]->[/green] {reference}")
+        if not check.references:
+            console.print(
+                "    [dim]-> DockerLs guidance; no published control in the catalogue "
+                "covers this rule[/dim]"
+            )
+    console.print()
+
+
+def _render_score(console: Console, analysis: DockerfileAnalysis) -> None:
+    tier_color = _TIER_COLORS.get(analysis.security_tier, "white")
+    ready = "[green]Yes[/green]" if analysis.is_production_ready else "[red]No[/red]"
+    console.print(
+        Panel(
+            f"[bold]Security Score: {analysis.security_score}/100[/bold]\n"
+            f"Tier: [{tier_color} bold]{analysis.security_tier}[/{tier_color} bold]\n"
+            f"Production Ready: {ready}",
+            expand=False,
+        )
+    )
+    console.print()
+
+
+def _render_template_origin(console: Console, analysis: DockerfileAnalysis) -> None:
+    """This Dockerfile against the hardened template it most resembles.
+
+    Purely informative -- it does not touch the score or the tier, which
+    keep measuring the Dockerfile as it is, not where it came from. Silent
+    when nothing matched closely enough: a generic Dockerfile is not "an
+    edited template with a 0% match", it is just not one.
+    """
+    origin = analysis.template_origin
+    if origin is None:
+        return
+
+    console.print(
+        Panel(
+            f"[bold]Derived from template:[/bold] [cyan]{origin.template_name}[/cyan]\n"
+            f"Similarity: {origin.similarity:.0%}\n"
+            "[dim]Diff against the hardened template shown below.[/dim]",
+            title="Template origin",
+            expand=False,
+        )
+    )
+    for line in origin.diff[:60]:
+        style = ""
+        if line.startswith("+") and not line.startswith("+++"):
+            style = "green"
+        elif line.startswith("-") and not line.startswith("---"):
+            style = "red"
+        elif line.startswith("@@"):
+            style = "cyan"
+        console.print(f"[{style}]{line}[/{style}]" if style else line, soft_wrap=True)
+    if len(origin.diff) > 60:
+        console.print(f"[dim]... {len(origin.diff) - 60} more diff line(s) omitted[/dim]")
+    console.print()
+
+
+def _render_suggestions(console: Console, suggestions: list[HardeningRule]) -> None:
+    console.print(Panel("[bold yellow]Recommendations[/bold yellow]", expand=False))
+
+    for i, suggestion in enumerate(suggestions, 1):
+        priority_style = _SEVERITY_STYLES.get(suggestion.priority.value, "")
+        console.print(f"\n[{priority_style}]#{i}. {suggestion.title}[/{priority_style}]")
+        console.print(f"   [dim]{suggestion.description}[/dim]")
+        console.print(f"   Current: [yellow]{suggestion.current_state}[/yellow]")
+        console.print(f"   Fix: [green]{suggestion.suggested_fix}[/green]")
+        console.print(f"   [italic]Reason: {suggestion.reason}[/italic]")
+
+    console.print()

dockerls/cli/runtime.py

@@ -0,0 +1,65 @@
+"""As Settings do processo e o logging, sem o contêiner de dependências.
+
+Isto morava em `cli/dependencies.py`, e o problema não era o código: era o
+módulo. `dependencies.py` importa a aplicação inteira -- pipeline de scan,
+clientes HTTP, pydantic-settings, SQLAlchemy -- e o callback que roda antes
+de *todo* subcomando só precisava daqui. `dockerls version`, que imprime
+uma string, pagava ~250ms para configurar um sink de log.
+
+Separado, o callback importa este módulo (Settings + logging, e nada mais)
+e os comandos que de fato trabalham seguem importando `dependencies`, que
+reexporta estes nomes para não mudar nada do lado de quem chama.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import TYPE_CHECKING
+
+from dockerls.infrastructure.config.settings import Settings
+from dockerls.infrastructure.logging.setup import setup_logging
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+# Populated by _settings() on first use; exposed so commands can tell the
+# user exactly which file the run's diagnostics landed in.
+_LOG_FILE: Path | None = None
+
+
+@lru_cache(maxsize=1)
+def _settings() -> Settings:
+    global _LOG_FILE
+    s = Settings()
+    s.ensure_dirs()
+    _LOG_FILE = setup_logging(s.log_level, log_dir=s.log_dir)
+    return s
+
+
+def current_log_file() -> Path | None:
+    _settings()
+    return _LOG_FILE
+
+
+def configure_logging() -> None:
+    """Detach loguru's default stderr sink before any command runs.
+
+    Until a sink is configured, loguru logs everything from DEBUG up to
+    stderr. Commands that never touched Settings -- `build` was one --
+    inherited that default and leaked INFO lines into the terminal.
+    """
+    _settings()
+
+
+def enable_console_logging() -> None:
+    """Re-attach the stderr sink (``--verbose``) on top of the file sink.
+
+    The stderr sink runs at the configured `log_level` here (INFO by
+    default, DEBUG via DOCKERLS_LOG_LEVEL) rather than the WARNING floor
+    that applies without ``--verbose``.
+    """
+    s = _settings()
+    global _LOG_FILE
+    _LOG_FILE = setup_logging(
+        s.log_level, log_dir=s.log_dir, console=True, console_level=s.log_level
+    )

dockerls/cli/scan_failure.py

@@ -0,0 +1,71 @@
+"""A causa de um scan que não completou, em uma linha legível.
+
+O terminal mostrava o stderr cru do scanner. Para uma tag inexistente o
+Trivy responde com um bloco de várias linhas que menciona o socket do
+Docker -- um daemon que este modo de scan nem usa --, e o leitor tinha
+que garimpar nesse texto a única informação que importa: a tag não existe
+no registry.
+
+A causa já vem classificada em `ScanErrorKind` (ver
+`integrations/scan_errors.py`). Aqui ela vira a frase que o usuário lê. O
+texto bruto continua indo para o arquivo de log e para `--format json`
+via `ScanResult.error_message`: resumir na tela não é esconder, é parar
+de despejar num lugar onde ninguém consegue ler.
+
+Uma função só, usada por `analyze`, `compare`, `advisor` e `alternatives`,
+porque quatro cópias da mesma frase divergem na primeira vez que uma
+delas for corrigida.
+"""
+
+from __future__ import annotations
+
+from dockerls.domain.entities.scan_result import ScanErrorKind
+
+#: O que cada causa classificada significa, nos termos de quem lê. São
+#: afirmações sobre o que aconteceu, não instruções -- a ação sugerida é
+#: assunto de quem renderiza (`recommend` tem a sua própria tabela de
+#: dicas, que responde "o que fazer" em vez de "o que houve").
+_CAUSES: dict[ScanErrorKind, str] = {
+    ScanErrorKind.NOT_FOUND: "tag not found on the registry",
+    ScanErrorKind.AUTH_REQUIRED: "the registry requires credentials",
+    ScanErrorKind.RATE_LIMITED: "rate limited by the registry",
+    ScanErrorKind.DB_INIT_FAILED: "the vulnerability database could not be prepared",
+    ScanErrorKind.TIMEOUT: "the scan exceeded its timeout",
+    ScanErrorKind.SCANNER_MISSING: "no scanner executable was found",
+    ScanErrorKind.INVALID_OUTPUT: "the scanner produced output that could not be parsed",
+    ScanErrorKind.BLOCKED_BY_POLICY: "the network policy refused this host",
+}
+
+#: Quanto do stderr cru sobrevive quando não há causa classificada. O
+#: texto inteiro está no log e no JSON; aqui só cabe o suficiente para
+#: distinguir uma falha da outra.
+REASON_MAX_LEN = 90
+
+
+def short_reason(reason: str) -> str:
+    """Colapsa um stderr de várias linhas em uma linha legível."""
+    collapsed = " ".join(reason.split())
+    if len(collapsed) <= REASON_MAX_LEN:
+        return collapsed
+    return collapsed[: REASON_MAX_LEN - 3] + "..."
+
+
+def describe_scan_failure(kind: ScanErrorKind | str, message: str = "") -> str:
+    """`KIND -- causa em português claro`, sem o dump do scanner.
+
+    Sem classificação (UNKNOWN, ou um scanner cuja saída ninguém mapeou
+    ainda) sobra o começo do stderr, colapsado numa linha: é pior que uma
+    frase, e ainda assim melhor que nada.
+    """
+    try:
+        classified = ScanErrorKind(kind)
+    except ValueError:
+        # Um `kind` que não é um membro do enum vem de dado externo
+        # (cache antigo, JSON de outra versão). Não é motivo para o
+        # comando morrer: o rótulo é mostrado como veio.
+        return f"{kind} -- {short_reason(message) or 'no details'}"
+
+    cause = _CAUSES.get(classified)
+    if cause:
+        return f"{classified.value} -- {cause}"
+    return f"{classified.value} -- {short_reason(message) or 'no details'}"

dockerls/cli/text.py

@@ -0,0 +1,39 @@
+"""Render third-party text as text, never as formatting instructions.
+
+Rich interprets square-bracket markup in everything it prints, and a large
+share of what this tool prints did not originate here. CVE titles come from
+upstream advisories, package names and file paths come from inside the image
+under analysis, error strings come from a scanner's stderr, and catalogue
+metadata comes from a repository on the internet. All of it is data.
+
+Left unescaped, a description reading
+
+    [red]FIXED - no action needed[/red]
+
+is *interpreted*: the brackets vanish, the words are styled, and the report
+now contains a sentence that looks like the tool's own annotation. Whoever
+controls an advisory or a package's metadata controls how a finding is
+presented -- they can style a CRITICAL to look benign, or make text
+disappear. That is the one place in this codebase where untrusted input
+becomes presentation logic, and it closes here.
+
+`safe()` is applied at the point of interpolation rather than by turning
+markup off wholesale, because the styling this tool applies to its *own*
+strings is what makes the output readable. The rule is simple: our literals
+may carry markup; anything that arrived from outside goes through `safe`.
+"""
+
+from __future__ import annotations
+
+from rich.markup import escape
+
+
+def safe(value: object) -> str:
+    """Escape Rich markup in `value` so it renders exactly as it reads.
+
+    Accepts any object and stringifies it: the call sites interpolate CVE
+    ids, package names, paths, counts and enum values, and requiring the
+    caller to remember which of those are already strings is how one gets
+    missed.
+    """
+    return escape("" if value is None else str(value))