quantilica-cli 0.7.0__tar.gz → 0.9.0__tar.gz

{quantilica_cli-0.7.0 → quantilica_cli-0.9.0}/CHANGELOG.md

@@ -5,6 +5,46 @@ Todas as mudanças notáveis deste projeto serão documentadas neste arquivo.
 O formato segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/),
 e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
 
+## [0.9.0] - 2026-10-04
+
+Registra o `cvm-fetcher` como fonte instalável sob demanda, após a v0.1.0 do
+fetcher (wheel no GitHub Releases, entrada no índice PEP 503 do ecossistema).
+
+### Adicionado
+- Fonte `cvm` em `SOURCES_REGISTRY` (`quantilica install cvm`), apontando
+  para a distribuição `cvm-fetcher`.
+
+## [0.8.0] - 2026-10-03
+
+Onda A.2 do plano `2026-10-03-padronizacao-core-e-consolidacao-fetchers` —
+decorators de ciclo de vida no SDK (`quantilica.cli.sdk`) e abstração de
+pré-visualização tabular de sincronização.
+
+### Adicionado
+- `FetcherApp.command_convert(func)`: decorator que registra o subcomando
+  `convert` com flags canônicas (`-i/--input`, `-o/--output`, `--verbose`,
+  padrões derivados de `default_output`). Configura logging Rich, trata
+  `ImportError` graciosamente (sugerindo `pip install {nome}[analysis]`,
+  saída com código 1) e exibe confirmação com check verde.
+- `FetcherApp.command_pipeline(func)`: decorator que registra o subcomando
+  `pipeline` encadeando sincronização (passo 1/2, via `sync`) e conversão
+  analítica (passo 2/2, via `func`). Opções: grupos, `--output`,
+  `--parquet-dir`, `--workers`, `--dry-run` (interrompe antes do passo 2) e
+  `--verbose`.
+- `FetcherApp.command_archive(func)`: decorator que registra o subcomando
+  `archive` para arquivamento histórico, com o mesmo padrão de flags e
+  tratamento gracioso de `ImportError`.
+- `SyncPlanItem`/`SyncPlan`: dataclasses (imutáveis) para planejamento de
+  sincronização, com `SyncPlan.render_table(console=None)` que renderiza uma
+  tabela Rich (`Dataset | Partição | Arquivo | URL`) e o sumário `Total: X
+  arquivos planejados. Y ignorados fora de cobertura.` Importados do
+  `quantilica.cli.sdk`.
+- `quantilica health`: subcomando de diagnóstico que faz sondas HTTP leves
+  (HEAD com fallback para GET, timeout padrão 5s) contra as fontes canônicas
+  do ecossistema — BCB SGS, SIDRA, Tesouro Direto, Comex e INMET — em
+  paralelo, com saída em tabela Rich (`Fonte | Estado | Latência | HTTP`) ou
+  em JSON estruturado via `--json`. Usa `quantilica.core.http` para o probe.
+
 ## [0.7.0] - 2026-10-02
 
 Onda 2 — extensões do SDK (`quantilica.cli.sdk`) para eliminação de

{quantilica_cli-0.7.0 → quantilica_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quantilica-cli
-Version: 0.7.0
+Version: 0.9.0
 Summary: Unified CLI for Quantilica open data fetchers
 Author-email: "Komesu, D.K." <daniel@dkko.me>
 License-Expression: MIT

{quantilica_cli-0.7.0 → quantilica_cli-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quantilica-cli"
-version = "0.7.0"
+version = "0.9.0"
 description = "Unified CLI for Quantilica open data fetchers"
 readme = "README.md"
 authors = [{ name = "Komesu, D.K.", email = "daniel@dkko.me" }]

{quantilica_cli-0.7.0 → quantilica_cli-0.9.0}/src/quantilica/cli/cli.py

@@ -13,6 +13,7 @@ from rich.logging import RichHandler
 from rich.table import Table
 
 from quantilica.cli import __version__
+from quantilica.cli.health import cmd_health
 from quantilica.cli.manifests import app as manifests_app
 from quantilica.cli.sources import (
     app as sources_app,
@@ -35,10 +36,11 @@ app = typer.Typer(
 app.add_typer(manifests_app, name="manifests")
 app.add_typer(sources_app, name="sources")
 
-# Adiciona comandos top-level install, uninstall e doctor
+# Adiciona comandos top-level install, uninstall, doctor e health
 app.command("install")(cmd_install)
 app.command("uninstall")(cmd_uninstall)
 app.command("doctor")(cmd_doctor)
+app.command("health")(cmd_health)
 
 console = Console()
 

quantilica_cli-0.9.0/src/quantilica/cli/health.py

@@ -0,0 +1,188 @@
+"""Comando `quantilica health` — sondas de disponibilidade das fontes.
+
+Realiza sondas HTTP leves (HEAD com fallback para GET) contra as fontes
+canônicas de dados do ecossistema Quantilica e reporta o resultado em
+tabela Rich ou JSON estruturado.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+import json
+import time
+from typing import Annotated
+
+import httpx2
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+DEFAULT_TIMEOUT = 5.0
+USER_AGENT = "quantilica-cli (health)"
+
+# Lista canônica de fontes sondadas (nome, URL de sonda leve).
+HEALTH_SOURCES: list[tuple[str, str]] = [
+    ("bcb", "https://api.bcb.gov.br/dados/serie/bcdata.sgs.1/dados?formato=json"),
+    ("sidra", "https://servicodados.ibge.gov.br/api/v3/calendario"),
+    (
+        "tesouro_direto",
+        "https://www.tesourotransparente.gov.br/ckan/api/3/action/package_search?rows=1",
+    ),
+    ("comex", "https://balanca.economia.gov.br"),
+    ("inmet", "https://apitempo.inmet.gov.br/estacoes"),
+]
+
+
+def _make_client(timeout: float) -> httpx2.Client:
+    """Cria o cliente HTTP usado pelas sondas.
+
+    Args:
+        timeout: Timeout (segundos) aplicado a cada requisição.
+
+    Returns:
+        Um httpx2.Client configurado com redirects e User-Agent da CLI.
+    """
+    return httpx2.Client(
+        timeout=timeout,
+        follow_redirects=True,
+        headers={"User-Agent": USER_AGENT},
+    )
+
+
+def _probe(client: httpx2.Client, name: str, url: str) -> dict[str, object]:
+    """Executa uma sonda HEAD (com fallback GET) contra uma fonte.
+
+    Args:
+        client: O cliente HTTP a ser usado.
+        name: Nome canônico da fonte.
+        url: URL alvo da sonda.
+
+    Returns:
+        Dicioário com name, url, status, http_status, latency_ms e error.
+    """
+    start = time.perf_counter()
+    try:
+        response = client.head(url)
+        # Muitos endpoints não implementam HEAD — fallback para GET leve.
+        if response.status_code >= 400:
+            response = client.get(url)
+        latency_ms = (time.perf_counter() - start) * 1000.0
+        if response.status_code < 400:
+            return {
+                "name": name,
+                "url": url,
+                "status": "ok",
+                "http_status": response.status_code,
+                "latency_ms": round(latency_ms, 1),
+                "error": None,
+            }
+        return {
+            "name": name,
+            "url": url,
+            "status": "falha",
+            "http_status": response.status_code,
+            "latency_ms": round(latency_ms, 1),
+            "error": f"HTTP {response.status_code}",
+        }
+    except Exception as exc:
+        latency_ms = (time.perf_counter() - start) * 1000.0
+        return {
+            "name": name,
+            "url": url,
+            "status": "falha",
+            "http_status": None,
+            "latency_ms": round(latency_ms, 1),
+            "error": f"{type(exc).__name__}: {exc}",
+        }
+
+
+def _run_probes(timeout: float, fail_fast: bool) -> list[dict[str, object]]:
+    """Sonda todas as fontes, em sequência (fail-fast) ou em paralelo.
+
+    Args:
+        timeout: Timeout por requisição, em segundos.
+        fail_fast: Se True, interrompe as sondas na primeira falha.
+
+    Returns:
+        A lista de resultados por fonte.
+    """
+    with _make_client(timeout=timeout) as client:
+        if fail_fast:
+            results = []
+            for name, url in HEALTH_SOURCES:
+                result = _probe(client, name, url)
+                results.append(result)
+                if result["status"] != "ok":
+                    break
+            return results
+
+        with concurrent.futures.ThreadPoolExecutor(
+            max_workers=len(HEALTH_SOURCES)
+        ) as pool:
+            futures = [
+                (name, pool.submit(_probe, client, name, url))
+                for name, url in HEALTH_SOURCES
+            ]
+            return [future.result() for _, future in futures]
+
+
+def _render_table(results: list[dict[str, object]]) -> None:
+    """Renderiza o relatório de health como tabela Rich.
+
+    Args:
+        results: Resultados das sondas.
+    """
+    table = Table(title="Health — fontes de dados", show_header=True)
+    table.add_column("Fonte", style="cyan")
+    table.add_column("Status")
+    table.add_column("Código", justify="right")
+    table.add_column("Latência (ms)", justify="right")
+
+    for r in results:
+        if r["status"] == "ok":
+            status = "[green]OK[/green]"
+        else:
+            status = "[red]FALHA[/red]"
+        code = str(r["http_status"]) if r["http_status"] is not None else "-"
+        latency = str(r["latency_ms"]) if r["latency_ms"] is not None else "-"
+        table.add_row(str(r["name"]), status, code, latency)
+
+    console.print(table)
+
+
+def cmd_health(
+    json_output: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help="Saída em JSON estruturado em vez de tabela.",
+        ),
+    ] = False,
+    fail_fast: Annotated[
+        bool,
+        typer.Option(
+            "--fail-fast",
+            help="Interrompe as sondas na primeira falha e encerra com código 1.",
+        ),
+    ] = False,
+    timeout: Annotated[
+        float,
+        typer.Option(
+            "--timeout",
+            help="Timeout (s) aplicado a cada sonda HTTP.",
+        ),
+    ] = DEFAULT_TIMEOUT,
+) -> None:
+    """Verifica a disponibilidade das fontes de dados (sondas HTTP leves)."""
+    results = _run_probes(timeout, fail_fast)
+
+    if json_output:
+        status = "ok" if all(r["status"] == "ok" for r in results) else "degraded"
+        print(json.dumps({"status": status, "sources": results}))
+    else:
+        _render_table(results)
+
+    if fail_fast and any(r["status"] != "ok" for r in results):
+        raise typer.Exit(code=1)

{quantilica_cli-0.7.0 → quantilica_cli-0.9.0}/src/quantilica/cli/sdk.py

@@ -10,6 +10,7 @@ import contextlib
 import datetime as dt
 import threading
 from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Annotated, Any
 
@@ -23,8 +24,9 @@ from quantilica.core.storage import (
     build_stamped_filename,
     stamp_filename,
 )
-from rich.console import Group
+from rich.console import Console, Group
 from rich.live import Live
+from rich.rule import Rule
 from rich.table import Table
 
 from quantilica.cli.ui import (
@@ -38,6 +40,78 @@ from quantilica.cli.ui import (
 
 logger = get_logger(__name__)
 
+__all__ = [
+    "DataRepository",
+    "FetcherApp",
+    "SyncPlan",
+    "SyncPlanItem",
+    "default_client",
+    "default_path_builder",
+    "make_resolve_groups",
+]
+
+
+@dataclass(frozen=True)
+class SyncPlanItem:
+    """A single dataset file planned for synchronization.
+
+    Args:
+        dataset: Canonical dataset (group) identifier.
+        partition: Human-readable partition label (e.g. ``2023-05``), or None.
+        filename: The stamped file name for the entry.
+        url: Remote URL for the resource.
+        target: Local destination path.
+        dataset_name: Optional human-readable dataset name.
+    """
+
+    dataset: str
+    partition: str | None
+    filename: str
+    url: str
+    target: Path
+    dataset_name: str = ""
+
+
+@dataclass(frozen=True)
+class SyncPlan:
+    """Preview plan for a synchronization run (``--dry-run``).
+
+    Args:
+        items: Planned :class:`SyncPlanItem` entries.
+        skipped: Number of entries ignored (outside of coverage).
+    """
+
+    items: list[SyncPlanItem] = field(default_factory=list)
+    skipped: int = 0
+
+    def render_table(self, console: Console | None = None) -> None:
+        """Render the plan as a Rich table with a summary footer.
+
+        Args:
+            console: Optional Rich Console to print to (defaults to the shared
+                console from :mod:`quantilica.cli.ui`).
+        """
+        con = console or get_console()
+        table = Table(
+            "Dataset",
+            "Partição",
+            "Arquivo",
+            "URL",
+            title="Arquivos a baixar (dry-run)",
+        )
+        for item in self.items:
+            table.add_row(
+                item.dataset,
+                item.partition or "—",
+                item.filename,
+                item.url,
+            )
+        con.print(table)
+        con.print(
+            f"Total: {len(self.items)} arquivos planejados. "
+            f"{self.skipped} ignorados fora de cobertura."
+        )
+
 
 def default_client() -> HttpClient:
     """Create a default HttpClient with standard configuration.
@@ -243,6 +317,211 @@ class FetcherApp:
         """
         self.app.command(name=name, **kwargs)(cmd_func)
 
+    def command_convert(
+        self, func: Callable[[Path, Path], Any]
+    ) -> Callable[[Path, Path], Any]:
+        """Register the standard ``convert`` subcommand.
+
+        The generated command exposes the canonical flags (``-i/--input``,
+        ``-o/--output``, ``--verbose``) and delegates to ``func(input, output)``.
+        An ``ImportError`` propagating from ``func`` is treated as missing
+        analytical extras and exits gracefully with code 1.
+
+        Args:
+            func: Callable receiving ``(input, output)`` paths and performing
+                the conversion.
+
+        Returns:
+            The original ``func`` (the method can be used as a decorator).
+        """
+        console = get_console()
+
+        @self.app.command("convert")
+        def convert(
+            input: Annotated[
+                Path,
+                typer.Option(
+                    "-i",
+                    "--input",
+                    help="Diretório de origem com arquivos brutos",
+                ),
+            ] = self.default_output,
+            output: Annotated[
+                Path,
+                typer.Option("-o", "--output", help="Diretório de destino"),
+            ] = self.default_output,
+            verbose: Annotated[
+                bool, typer.Option("--verbose", help="Logs detalhados")
+            ] = False,
+        ) -> None:
+            setup_rich_logging(verbose, console=console)
+            try:
+                func(input, output)
+            except ImportError:
+                console.print(
+                    f"[red]Erro:[/red] convert requer extras de análise: "
+                    f"pip install {self.name}\[analysis]"
+                )
+                raise typer.Exit(1) from None
+            console.print(
+                f"[green]✓[/green] Conversão concluída em [dim]{output}[/dim]."
+            )
+
+        return func
+
+    def command_archive(
+        self, func: Callable[[Path, Path], Any]
+    ) -> Callable[[Path, Path], Any]:
+        """Register the standard ``archive`` subcommand.
+
+        Mirrors :meth:`command_convert` with the canonical flags
+        (``-i/--input``, ``-o/--output``, ``--verbose``) and delegates to
+        ``func(input, output)``. An ``ImportError`` propagating from ``func``
+        is treated as missing analytical extras and exits gracefully with
+        code 1.
+
+        Args:
+            func: Callable receiving ``(input, output)`` paths and creating
+                the historical archive.
+
+        Returns:
+            The original ``func`` (the method can be used as a decorator).
+        """
+        console = get_console()
+
+        @self.app.command("archive")
+        def archive(
+            input: Annotated[
+                Path,
+                typer.Option(
+                    "-i",
+                    "--input",
+                    help="Diretório de dados a arquivar",
+                ),
+            ] = self.default_output,
+            output: Annotated[
+                Path,
+                typer.Option("-o", "--output", help="Diretório do arquivo histórico"),
+            ] = self.default_output,
+            verbose: Annotated[
+                bool, typer.Option("--verbose", help="Logs detalhados")
+            ] = False,
+        ) -> None:
+            setup_rich_logging(verbose, console=console)
+            try:
+                func(input, output)
+            except ImportError:
+                console.print(
+                    f"[red]Erro:[/red] archive requer extras de análise: "
+                    f"pip install {self.name}\[analysis]"
+                )
+                raise typer.Exit(1) from None
+            console.print(f"[green]✓[/green] Arquivo criado em [dim]{output}[/dim].")
+
+        return func
+
+    def command_pipeline(
+        self, convert_func: Callable[[Path, Path], Any]
+    ) -> Callable[[Path, Path], Any]:
+        """Register the standard ``pipeline`` subcommand (sync → convert).
+
+        Step 1/2 invokes the built-in ``sync`` command (same flags: groups,
+        ``-o/--output``, ``--parquet-dir``, ``--workers``, ``--dry-run``,
+        ``--verbose``). Step 2/2 invokes ``convert_func(output, parquet_dir)``.
+        With ``--dry-run`` the plan is only listed and the conversion step is
+        skipped. An ``ImportError`` from ``convert_func`` is treated as
+        missing analytical extras.
+
+        Args:
+            convert_func: Callable receiving ``(output, parquet_dir)`` paths
+                and performing the conversion.
+
+        Returns:
+            The original ``convert_func`` (usable as a decorator).
+        """
+        console = get_console()
+
+        @self.app.command("pipeline")
+        def pipeline(
+            ctx: typer.Context,
+            groups: Annotated[
+                list[str] | None,
+                typer.Argument(
+                    help="Grupos a baixar. Use 'list' para ver grupos "
+                    "disponíveis. Padrão: todos."
+                ),
+            ] = None,
+            output: Annotated[
+                Path | None,
+                typer.Option("-o", "--output", help="Diretório de saída"),
+            ] = None,
+            parquet_dir: Annotated[
+                Path | None,
+                typer.Option(
+                    "--parquet-dir",
+                    help="Diretório para os Parquet (padrão: igual a --output)",
+                ),
+            ] = None,
+            workers: Annotated[
+                int, typer.Option("--workers", help="Downloads paralelos")
+            ] = 4,
+            dry_run: Annotated[
+                bool, typer.Option("--dry-run", help="Listar arquivos sem baixar")
+            ] = False,
+            verbose: Annotated[
+                bool, typer.Option("--verbose", help="Logs detalhados")
+            ] = False,
+        ) -> None:
+            setup_rich_logging(verbose, console=console)
+            actual_output = output or self.default_output
+            parquet_out = parquet_dir or actual_output
+
+            console.print(Rule("[bold]Passo 1/2: Download[/bold]"))
+            sync_cmd = next(
+                (
+                    cmd.callback
+                    for cmd in self.app.registered_commands
+                    if cmd.name == "sync"
+                ),
+                None,
+            )
+            if sync_cmd is None:
+                console.print(
+                    "[red]Erro:[/red] pipeline requer o comando 'sync' "
+                    "(build_default_commands=True)."
+                )
+                raise typer.Exit(1) from None
+            ctx.invoke(
+                sync_cmd,
+                groups=groups,
+                output=actual_output,
+                dry_run=dry_run,
+                workers=workers,
+                verbose=verbose,
+            )
+
+            if dry_run:
+                console.print(
+                    "\n[yellow]Dry-run:[/yellow] conversão (passo 2/2) não executada."
+                )
+                return
+
+            console.print(Rule("[bold]Passo 2/2: Conversão[/bold]"))
+            try:
+                convert_func(actual_output, parquet_out)
+            except ImportError:
+                console.print(
+                    f"[red]Erro:[/red] pipeline (conversão) requer extras de "
+                    f"análise: pip install {self.name}\[analysis]"
+                )
+                raise typer.Exit(1) from None
+            console.print(
+                f"[green]✓[/green] Pipeline concluído: Parquet em "
+                f"[dim]{parquet_out}[/dim]."
+            )
+
+        return convert_func
+
     def _safe_head_date(self, url: str) -> dt.date | None:
         with contextlib.suppress(Exception):
             return self.client.head_last_modified_date(url)

{quantilica_cli-0.7.0 → quantilica_cli-0.9.0}/src/quantilica/cli/sources.py

@@ -30,6 +30,7 @@ SOURCES_REGISTRY: dict[str, str] = {
     "anp": "anp-fetcher",
     "bcb-sgs": "bcb-sgs-fetcher",
     "comex": "comex-fetcher",
+    "cvm": "cvm-fetcher",
     "datasus": "datasus-fetcher",
     "inmet": "inmet-fetcher",
     "pdet": "pdet-fetcher",

quantilica_cli-0.9.0/tests/test_health.py

@@ -0,0 +1,208 @@
+"""Testes para o comando `quantilica health` (sondas de disponibilidade)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from unittest.mock import patch
+
+import httpx2
+from typer.testing import CliRunner
+
+from quantilica.cli import health
+from quantilica.cli.cli import app
+from quantilica.cli.health import HEALTH_SOURCES
+
+runner = CliRunner()
+
+SOURCE_NAMES = [name for name, _ in HEALTH_SOURCES]
+URLS = {url: name for name, url in HEALTH_SOURCES}
+
+
+def _handler(status_by_url: dict[str, int], head_405: bool = False):
+    """Cria um handler de MockTransport mapeando URL -> status HTTP."""
+
+    def handle(request: httpx2.Request) -> httpx2.Response:
+        url = str(request.url).split("?")[0]
+        status = status_by_url.get(url, 200)
+        if request.method == "HEAD" and head_405:
+            return httpx2.Response(405)
+        return httpx2.Response(status)
+
+    return handle
+
+
+def _patch_client(
+    status_by_url: dict[str, int],
+    head_405: bool = False,
+):
+    """Parchea o cliente de sondas com um MockTransport determinístico."""
+    transport = httpx2.MockTransport(_handler(status_by_url, head_405))
+    fake_client = httpx2.Client(transport=transport, follow_redirects=True)
+    return patch.object(health, "_make_client", return_value=fake_client)
+
+
+def _all_ok() -> dict[str, int]:
+    return {url: 200 for url in URLS}
+
+
+def _parse_json(output: str) -> dict[str, Any]:
+    lines = [line for line in output.splitlines() if line.startswith("{")]
+    assert lines, f"nenhuma linha JSON na saída: {output!r}"
+    return json.loads(lines[-1])
+
+
+# --- modo tabela -----------------------------------------------------------
+
+
+def test_health_table_all_ok() -> None:
+    with _patch_client(_all_ok()):
+        result = runner.invoke(app, ["health"])
+    assert result.exit_code == 0
+    for name in SOURCE_NAMES:
+        assert name in result.output
+    assert "OK" in result.output
+    assert "FALHA" not in result.output
+
+
+def test_health_table_with_failure() -> None:
+    statuses = _all_ok()
+    statuses["https://balanca.economia.gov.br"] = 500
+    with _patch_client(statuses):
+        result = runner.invoke(app, ["health"])
+    assert result.exit_code == 0
+    assert "FALHA" in result.output
+    assert "OK" in result.output
+
+
+def test_health_head_fallback_to_get() -> None:
+    # HEAD retorna 405 e o CLI deve refazer com GET (levemente diferente).
+    handlers: list[str] = []
+
+    def handle(request: httpx2.Request) -> httpx2.Response:
+        handlers.append(request.method)
+        if request.method == "HEAD":
+            return httpx2.Response(405)
+        return httpx2.Response(200)
+
+    transport = httpx2.MockTransport(handle)
+    with patch.object(
+        health, "_make_client", return_value=httpx2.Client(transport=transport)
+    ):
+        result = runner.invoke(app, ["health"])
+    assert result.exit_code == 0
+    assert "OK" in result.output
+    assert "HEAD" in handlers
+    assert "GET" in handlers
+
+
+# --- modo --json -------------------------------------------------------------
+
+
+def test_health_json_all_ok() -> None:
+    with _patch_client(_all_ok()):
+        result = runner.invoke(app, ["health", "--json"])
+    assert result.exit_code == 0
+    payload = _parse_json(result.output)
+    assert payload["status"] == "ok"
+    source_names = [s["name"] for s in payload["sources"]]
+    assert source_names == SOURCE_NAMES
+    for source in payload["sources"]:
+        assert source["status"] == "ok"
+        assert source["http_status"] == 200
+        assert isinstance(source["latency_ms"], (int, float))
+        assert source["error"] is None
+
+
+def test_health_json_degraded() -> None:
+    statuses = _all_ok()
+    statuses["https://balanca.economia.gov.br"] = 503
+    with _patch_client(statuses):
+        result = runner.invoke(app, ["health", "--json"])
+    assert result.exit_code == 0
+    payload = _parse_json(result.output)
+    assert payload["status"] == "degraded"
+    comex = next(s for s in payload["sources"] if s["name"] == "comex")
+    assert comex["status"] == "falha"
+    assert comex["http_status"] == 503
+    assert comex["error"] == "HTTP 503"
+
+
+def test_health_json_network_error() -> None:
+    def handler(request: httpx2.Request) -> httpx2.Response:
+        if "inmet" in str(request.url):
+            raise httpx2.ConnectError("boom")
+        return httpx2.Response(200)
+
+    transport = httpx2.MockTransport(handler)
+    with patch.object(
+        health, "_make_client", return_value=httpx2.Client(transport=transport)
+    ):
+        result = runner.invoke(app, ["health", "--json"])
+    assert result.exit_code == 0
+    payload = _parse_json(result.output)
+    assert payload["status"] == "degraded"
+    inmet = next(s for s in payload["sources"] if s["name"] == "inmet")
+    assert inmet["status"] == "falha"
+    assert inmet["http_status"] is None
+    assert "ConnectError" in inmet["error"]
+
+
+# --- --fail-fast ------------------------------------------------------------
+
+
+def test_health_fail_fast_exit_code_ok() -> None:
+    with _patch_client(_all_ok()):
+        result = runner.invoke(app, ["health", "--fail-fast", "--json"])
+    assert result.exit_code == 0
+    payload = _parse_json(result.output)
+    assert payload["status"] == "ok"
+
+
+def test_health_fail_fast_exit_code_on_failure() -> None:
+    statuses = _all_ok()
+    statuses["https://balanca.economia.gov.br"] = 500
+    with _patch_client(statuses):
+        result = runner.invoke(app, ["health", "--fail-fast"])
+    assert result.exit_code == 1
+
+
+def test_health_fail_fast_stops_probes() -> None:
+    # com a primeira fonte falhando em fail-fast, as demais não são sondadas.
+    probes: list[str] = []
+
+    def fake_probe(client: httpx2.Client, name: str, url: str) -> dict[str, object]:
+        probes.append(name)
+        status = "falha" if name == "bcb" else "ok"
+        return {
+            "name": name,
+            "url": url,
+            "status": status,
+            "http_status": 500 if status == "falha" else 200,
+            "latency_ms": 1.0,
+            "error": None if status == "ok" else "HTTP 500",
+        }
+
+    with (
+        _patch_client(_all_ok()),
+        patch.object(health, "_probe", side_effect=fake_probe),
+    ):
+        result = runner.invoke(app, ["health", "--fail-fast"])
+    assert result.exit_code == 1
+    assert probes == ["bcb"]
+
+
+# --- --timeout ------------------------------------------------------------
+
+
+def test_health_passes_timeout_to_client() -> None:
+    with patch.object(
+        health, "_make_client", return_value=httpx2.Client()
+    ) as mock_client:
+        result = runner.invoke(app, ["health", "--timeout", "2.5", "--json"])
+    assert result.exit_code == 0
+    mock_client.assert_called_once_with(timeout=2.5)
+
+
+def test_health_sources_canonical_list() -> None:
+    assert SOURCE_NAMES == ["bcb", "sidra", "tesouro_direto", "comex", "inmet"]

quantilica_cli-0.9.0/tests/test_sdk_onda_a2.py

@@ -0,0 +1,295 @@
+"""Testes unitários para Onda A.2 do SDK (command_convert/pipeline/archive, SyncPlan)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+import typer
+from rich.console import Console
+from typer.testing import CliRunner
+
+from quantilica.cli.sdk import SyncPlan, SyncPlanItem
+from tests.test_sdk import _grouped, make_app
+
+runner = CliRunner()
+
+
+# ---------------------------------------------------------------
+# SyncPlan / SyncPlanItem
+# ---------------------------------------------------------------
+
+
+def _sample_item(
+    dataset: str = "exp", partition: str | None = "2023-05"
+) -> SyncPlanItem:
+    return SyncPlanItem(
+        dataset=dataset,
+        partition=partition,
+        filename=f"{dataset}-monthly_2023-05.csv",
+        url=f"https://example.test/{dataset}-monthly.csv",
+        target=Path(f"/data/output/{dataset}/{dataset}-monthly_2023-05.csv"),
+        dataset_name="Exportações",
+    )
+
+
+def test_sync_plan_item_is_frozen():
+    item = _sample_item()
+    with pytest.raises(Exception):  # noqa: B017 (FrozenInstanceError levantada dinamicamente)
+        item.dataset = "imp"  # type: ignore[misc]
+
+
+def test_sync_plan_is_frozen():
+    plan = SyncPlan(items=[_sample_item()])
+    with pytest.raises(Exception):  # noqa: B017 (FrozenInstanceError levantada dinamicamente)
+        plan.skipped = 5  # type: ignore[misc]
+
+
+def test_sync_plan_item_defaults():
+    item = _sample_item()
+    assert item.dataset_name == "Exportações"
+    plain = SyncPlanItem(
+        dataset="d", partition=None, filename="f", url="u", target=Path("t")
+    )
+    assert plain.dataset_name == ""
+
+
+def test_sync_plan_defaults():
+    plan = SyncPlan()
+    assert plan.items == []
+    assert plan.skipped == 0
+
+
+def test_render_table_prints_columns_and_rows(capsys: pytest.CaptureFixture[str]):
+    plan = SyncPlan(
+        items=[_sample_item("exp", "2023-05"), _sample_item("imp", None)], skipped=3
+    )
+    console = Console(record=True, width=120, legacy_windows=False)
+    plan.render_table(console=console)
+    output = console.export_text()
+    assert "exp" in output
+    assert "exp-monthly_2023-05.csv" in output
+    assert "https://example.test/exp-monthly.csv" in output
+    # partição ausente é exibida como "—"
+    assert "—" in output
+    assert "Total: 2 arquivos planejados. 3 ignorados fora de cobertura." in output
+
+
+def test_render_table_uses_shared_console_when_none(capsys: pytest.CaptureFixture[str]):
+    plan = SyncPlan(items=[_sample_item()], skipped=1)
+    plan.render_table()
+    output = capsys.readouterr().out
+    assert "Total: 1 arquivos planejados. 1 ignorados fora de cobertura." in output
+
+
+# ---------------------------------------------------------------
+# command_convert
+# ---------------------------------------------------------------
+
+
+def test_command_convert_success(tmp_path: Path):
+    app = make_app()
+    calls: list[tuple[Path, Path]] = []
+
+    @app.command_convert
+    def conv(input: Path, output: Path) -> None:
+        calls.append((input, output))
+
+    result = runner.invoke(
+        _grouped(app.app), ["fd", "convert", "-i", str(tmp_path), "-o", str(tmp_path)]
+    )
+    assert result.exit_code == 0, result.output
+    assert calls == [(tmp_path, tmp_path)]
+    assert "Conversão concluída" in result.output
+    assert "✓" in result.output
+
+
+def test_command_convert_defaults_to_default_output(tmp_path: Path):
+    app = make_app()
+    calls: list[tuple[Path, Path]] = []
+
+    @app.command_convert
+    def conv(input: Path, output: Path) -> None:
+        calls.append((input, output))
+
+    default = app.default_output
+    result = runner.invoke(_grouped(app.app), ["fd", "convert"])
+    assert result.exit_code == 0, result.output
+    assert calls == [(default, default)]
+
+
+def test_command_convert_graceful_import_error(tmp_path: Path):
+    app = make_app()
+
+    @app.command_convert
+    def conv(input: Path, output: Path) -> None:
+        raise ImportError("No module named 'polars'")
+
+    result = runner.invoke(_grouped(app.app), ["fd", "convert", "-i", str(tmp_path)])
+    assert result.exit_code == 1
+    assert "convert requer extras de análise" in result.output
+    assert "pip install comex-fetcher[analysis]" in result.output
+
+
+def test_command_convert_verbose_sets_logging(tmp_path: Path):
+    app = make_app()
+
+    @app.command_convert
+    def conv(input: Path, output: Path) -> None:
+        raise typer.Exit(3)
+
+    result = runner.invoke(_grouped(app.app), ["fd", "convert", "--verbose"])
+    assert result.exit_code == 3
+
+
+# ---------------------------------------------------------------
+# command_pipeline
+# ---------------------------------------------------------------
+
+
+def test_command_pipeline_runs_both_steps(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    app = make_app()
+    calls: list[tuple[Path, Path]] = []
+    sync_calls: list[tuple[list, Path, int]] = []
+
+    def fake_download(entries, output_dir, workers=4):
+        sync_calls.append((entries, output_dir, workers))
+        return len(entries), len(entries), []
+
+    monkeypatch.setattr(app, "download_datasets", fake_download)
+
+    @app.command_pipeline
+    def conv(data_dir: Path, parquet_dir: Path) -> None:
+        calls.append((data_dir, parquet_dir))
+
+    raw = tmp_path / "raw"
+    parquet = tmp_path / "parquet"
+    result = runner.invoke(
+        _grouped(app.app),
+        ["fd", "pipeline", "exp", "-o", str(raw), "--parquet-dir", str(parquet)],
+    )
+    assert result.exit_code == 0, result.output
+    assert "Passo 1/2: Download" in result.output
+    assert "Passo 2/2: Conversão" in result.output
+    # Passo 1 invocou o sync (download_datasets) uma vez
+    assert len(sync_calls) == 1
+    entries, out_dir, workers = sync_calls[0]
+    assert out_dir == raw
+    assert [e["id"] for e in entries] == ["exp-monthly"]
+    # Passo 2 invocou a convert_func com (output, parquet_dir)
+    assert calls == [(raw, parquet)]
+    assert "✓" in result.output
+
+
+def test_command_pipeline_dry_run_skips_conversion(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    app = make_app()
+    downloads: list[tuple] = []
+    monkeypatch.setattr(
+        app,
+        "download_datasets",
+        lambda entries, output_dir, workers=4: (
+            downloads.append(output_dir) or (0, 0, [])
+        ),
+    )
+    converted: list[Path] = []
+
+    @app.command_pipeline
+    def conv(data_dir: Path, parquet_dir: Path) -> None:
+        converted.append(parquet_dir)
+
+    result = runner.invoke(_grouped(app.app), ["fd", "pipeline", "exp", "--dry-run"])
+    assert result.exit_code == 0, result.output
+    assert "Passo 1/2: Download" in result.output
+    assert "Passo 2/2: Conversão" not in result.output
+    assert converted == []
+    # dry-run: nenhum download executado (download_datasets não foi invocado)
+    assert downloads == []
+
+
+def test_command_pipeline_graceful_import_error(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    app = make_app()
+    monkeypatch.setattr(
+        app, "download_datasets", lambda entries, output_dir, workers=4: (0, 0, [])
+    )
+
+    @app.command_pipeline
+    def conv(data_dir: Path, parquet_dir: Path) -> None:
+        raise ImportError("No module named 'polars'")
+
+    result = runner.invoke(
+        _grouped(app.app), ["fd", "pipeline", "exp", "-o", str(tmp_path)]
+    )
+    assert result.exit_code == 1
+    assert "pipeline (conversão) requer extras de análise" in result.output
+    assert "comex-fetcher[analysis]" in result.output
+
+
+def test_command_pipeline_parquet_dir_defaults_to_output(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    app = make_app()
+    monkeypatch.setattr(
+        app, "download_datasets", lambda entries, output_dir, workers=4: (0, 0, [])
+    )
+    calls: list[tuple[Path, Path]] = []
+
+    @app.command_pipeline
+    def conv(data_dir: Path, parquet_dir: Path) -> None:
+        calls.append((data_dir, parquet_dir))
+
+    raw = tmp_path / "raw"
+    result = runner.invoke(_grouped(app.app), ["fd", "pipeline", "exp", "-o", str(raw)])
+    assert result.exit_code == 0, result.output
+    assert calls == [(raw, raw)]
+
+
+def test_command_pipeline_requires_sync_command():
+    app = make_app(build_default_commands=False)
+
+    @app.command_pipeline
+    def conv(data_dir: Path, parquet_dir: Path) -> None:
+        raise AssertionError("não deveria ser chamado")
+
+    result = runner.invoke(_grouped(app.app), ["fd", "pipeline", "exp"])
+    assert result.exit_code == 1
+    assert "pipeline requer o comando 'sync'" in result.output
+
+
+# ---------------------------------------------------------------
+# command_archive
+# ---------------------------------------------------------------
+
+
+def test_command_archive_success(tmp_path: Path):
+    app = make_app()
+    calls: list[tuple[Path, Path]] = []
+
+    @app.command_archive
+    def arch(input: Path, output: Path) -> None:
+        calls.append((input, output))
+
+    result = runner.invoke(
+        _grouped(app.app), ["fd", "archive", "-i", str(tmp_path), "-o", str(tmp_path)]
+    )
+    assert result.exit_code == 0, result.output
+    assert calls == [(tmp_path, tmp_path)]
+    assert "Arquivo criado" in result.output
+
+
+def test_command_archive_graceful_import_error(tmp_path: Path):
+    app = make_app()
+
+    @app.command_archive
+    def arch(input: Path, output: Path) -> None:
+        raise ImportError("No module named 'some_extra'")
+
+    result = runner.invoke(_grouped(app.app), ["fd", "archive", "-o", str(tmp_path)])
+    assert result.exit_code == 1
+    assert "archive requer extras de análise" in result.output
+    assert "pip install comex-fetcher[analysis]" in result.output