jentic-apitools-cli 0.0.0a4__py3-none-any.whl

jentic/apitools/cli/helpers.py

@@ -0,0 +1,295 @@
+"""Shared utilities for CLI commands."""
+
+from __future__ import annotations
+
+import functools
+import logging
+import sys
+import tempfile
+from pathlib import Path
+from urllib.parse import urlparse
+
+import click
+
+
+# Exit codes
+EXIT_SUCCESS = 0
+EXIT_RUNTIME_ERROR = 1
+EXIT_POLICY_FAILURE = 2
+
+
+def suppress_logging() -> None:
+    """Silence the console log handler so only command output reaches stdout."""
+    from jentic.apitools.common.utils.logging import configure_root_logger
+
+    configure_root_logger(level="CRITICAL")
+    root = logging.getLogger()
+    for handler in root.handlers:
+        if isinstance(handler, logging.StreamHandler) and not isinstance(
+            handler, logging.FileHandler
+        ):
+            handler.setLevel(logging.CRITICAL + 1)
+
+
+def quiet_option(fn):
+    """Shared ``-q / --quiet`` Click option decorator."""
+
+    @click.option(
+        "-q",
+        "--quiet",
+        is_flag=True,
+        default=False,
+        help="Suppress log output; only emit command results.",
+    )
+    @functools.wraps(fn)
+    def wrapper(*args, quiet: bool = False, **kwargs):
+        if quiet:
+            suppress_logging()
+        return fn(*args, **kwargs)
+
+    return wrapper
+
+
+SEVERITY_ORDER: dict[str, int] = {
+    "error": 1,
+    "warn": 2,
+    "warning": 2,
+    "info": 3,
+    "information": 3,
+    "hint": 4,
+}
+
+
+def resolve_spec_input(
+    spec: str,
+    stdin_filepath: str | None = None,
+) -> tuple[str, Path | None]:
+    """Resolve the SPEC argument to a spec URL and optional temp file.
+
+    Returns (spec_url, temp_path). The caller should clean up temp_path
+    if it is not None.
+    """
+    if spec == "-":
+        content = sys.stdin.read()
+        if not content.strip():
+            raise click.BadParameter("No input received from stdin", param_hint="SPEC")
+        ext = ".yaml"
+        if stdin_filepath:
+            ext = Path(stdin_filepath).suffix or ext
+        elif content.strip().startswith(("{", "[")):
+            ext = ".json"
+        tmp = tempfile.NamedTemporaryFile(suffix=ext, prefix="jentic-stdin-", delete=False)
+        tmp.write(content.encode("utf-8"))
+        tmp.close()
+        return Path(tmp.name).as_uri(), Path(tmp.name)
+
+    parsed = urlparse(spec)
+    if parsed.scheme in ("http", "https"):
+        return spec, None
+
+    path = Path(spec).resolve()
+    if not path.exists():
+        raise click.BadParameter(f"File not found: {spec}", param_hint="SPEC")
+    return path.as_uri(), None
+
+
+def resolve_label(
+    label: str | None,
+    vendor: str | None,
+    api: str | None,
+    spec: str,
+) -> str:
+    """Resolve the label from --label, --vendor/--api, or infer from spec.
+
+    Raises click.UsageError on conflicting or invalid combinations.
+    """
+    if label and vendor:
+        raise click.UsageError("--label and --vendor are mutually exclusive.")
+    if api and not vendor:
+        raise click.UsageError("--api requires --vendor.")
+    if vendor:
+        return f"{vendor}/{api or 'main'}"
+    if label:
+        return label
+    return infer_label(spec)
+
+
+def infer_label(spec: str) -> str:
+    """Derive a vendor/api label from a spec path or URL."""
+    parsed = urlparse(spec)
+    if parsed.scheme in ("http", "https"):
+        host = parsed.hostname or "unknown"
+        path_parts = [p for p in parsed.path.strip("/").split("/") if p]
+        api_name = path_parts[0] if path_parts else "api"
+        return f"{host}/{api_name}"
+    path = Path(spec)
+    return path.stem
+
+
+def write_output(content: str, output: str | None) -> None:
+    """Write content to a file or stdout."""
+    if output:
+        Path(output).parent.mkdir(parents=True, exist_ok=True)
+        Path(output).write_text(content, encoding="utf-8")
+        click.echo(f"Output written to {output}", err=True)
+    else:
+        click.echo(content)
+
+
+def format_diagnostics_text(diagnostics: list[dict], input_name: str) -> str:
+    """Format diagnostics as human-readable text."""
+    severity_icons = {
+        "error": "E",
+        "warning": "W",
+        "information": "I",
+        "hint": "H",
+    }
+
+    lines: list[str] = []
+    lines.append(f"Analysis of {input_name}")
+    lines.append("")
+
+    if not diagnostics:
+        lines.append("No issues found.")
+        return "\n".join(lines)
+
+    counts: dict[str, int] = {}
+    for d in diagnostics:
+        sev = d.get("severity", "unknown")
+        counts[sev] = counts.get(sev, 0) + 1
+
+    for d in diagnostics:
+        sev = d.get("severity", "unknown")
+        icon = severity_icons.get(sev, "?")
+        source = d.get("source", "")
+        code = d.get("code", "")
+        msg = d.get("message", "")
+        prefix = f"[{icon}]"
+        source_str = f" ({source})" if source else ""
+        code_str = f" {code}:" if code else ""
+        lines.append(f"  {prefix}{code_str} {msg}{source_str}")
+
+    lines.append("")
+    summary_parts = []
+    for sev in ("error", "warning", "information", "hint"):
+        if sev in counts:
+            summary_parts.append(f"{counts[sev]} {sev}{'s' if counts[sev] != 1 else ''}")
+    lines.append(f"Summary: {', '.join(summary_parts)}" if summary_parts else "Summary: no issues")
+    return "\n".join(lines)
+
+
+def format_score_text(scorecard: dict) -> str:
+    """Format a scorecard as human-readable text."""
+    lines: list[str] = []
+
+    summary = scorecard.get("summary", {})
+    api_meta = scorecard.get("apiMetadata", {})
+
+    api_name = api_meta.get("name", "Unknown API")
+    version = api_meta.get("apiDescriptionVersion", "")
+
+    lines.append(f"Score for {api_name}" + (f" ({version})" if version else ""))
+    lines.append("")
+
+    score = summary.get("score", "?")
+    grade = summary.get("grade", "?")
+    level = summary.get("level", "?")
+    lines.append(f"  Overall: {score}/100  Grade: {grade}  Level: {level}")
+    lines.append("")
+
+    dimensions = summary.get("dimensions", [])
+    if dimensions:
+        lines.append("  Dimensions:")
+        for dim in dimensions:
+            dim_name = dim.get("name", dim.get("kind", "?"))
+            dim_score = dim.get("score", "?")
+            dim_grade = dim.get("grade", "?")
+            lines.append(f"    {dim_name}: {dim_score}/100 ({dim_grade})")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def serialize_diagnostics(diagnostics: list) -> list[dict]:
+    """Convert JenticDiagnostic list to JSON-serializable dicts."""
+    from jentic.apitools.common.utils.diagnostic_utils import serialize_diagnostic
+
+    return [serialize_diagnostic(d) for d in diagnostics]
+
+
+def count_diagnostics_by_severity(diagnostics: list[dict]) -> dict[str, int]:
+    """Count diagnostics by severity level."""
+    counts: dict[str, int] = {}
+    for d in diagnostics:
+        sev = d.get("severity", "unknown")
+        counts[sev] = counts.get(sev, 0) + 1
+    return counts
+
+
+def check_fail_on(diagnostics: list[dict], fail_on: str) -> bool:
+    """Check if any diagnostic severity meets or exceeds the fail_on threshold.
+
+    Returns True if the policy is violated (should fail).
+    """
+    if fail_on == "none":
+        return False
+    threshold = SEVERITY_ORDER.get(fail_on)
+    if threshold is None:
+        return False
+    for d in diagnostics:
+        sev = d.get("severity", "unknown")
+        sev_order = SEVERITY_ORDER.get(sev, 99)
+        if sev_order <= threshold:
+            return True
+    return False
+
+
+# Provider name -> (settings attribute, env var hint)
+_PROVIDER_KEY_MAP: dict[str, tuple[str, str]] = {
+    "OPENAI": ("openai_api_key", "OPENAI_API_KEY or JENTIC_OPENAI_API_KEY"),
+    "CLAUDE": ("anthropic_api_key", "ANTHROPIC_API_KEY or JENTIC_ANTHROPIC_API_KEY"),
+    "ANTHROPIC": ("anthropic_api_key", "ANTHROPIC_API_KEY or JENTIC_ANTHROPIC_API_KEY"),
+    "GEMINI": ("gemini_api_key", "GEMINI_API_KEY or JENTIC_GEMINI_API_KEY"),
+}
+
+
+def validate_llm_credentials() -> None:
+    """Validate that LLM credentials are available for the configured providers.
+
+    Checks both the primary provider (LLM_PROVIDER) and the light provider
+    (LIGHT_LLM_PROVIDER). Raises click.UsageError with an actionable message
+    if required credentials are missing.
+    """
+    from jentic.apitools.common.settings import get_settings
+
+    llm_settings = get_settings().llm
+    providers_to_check = {llm_settings.provider.upper(), llm_settings.light_provider.upper()}
+
+    missing: list[str] = []
+    for provider in sorted(providers_to_check):
+        if provider == "BEDROCK":
+            try:
+                import boto3  # noqa: F401
+            except ImportError:
+                missing.append(
+                    f"  {provider}: boto3 is not installed. Install the 'bedrock' or 'all' extra."
+                )
+            continue
+
+        key_info = _PROVIDER_KEY_MAP.get(provider)
+        if key_info is None:
+            missing.append(f"  {provider}: unknown provider")
+            continue
+
+        attr_name, env_hint = key_info
+        if not getattr(llm_settings, attr_name, None):
+            missing.append(f"  {provider}: set {env_hint} in your environment or .env file")
+
+    if missing:
+        details = "\n".join(missing)
+        raise click.UsageError(
+            f"LLM analysis requires credentials for the configured provider(s), "
+            f"but the following are missing:\n{details}\n\n"
+            f"Current configuration: LLM_PROVIDER={llm_settings.provider}, "
+            f"LIGHT_LLM_PROVIDER={llm_settings.light_provider}"
+        )