github2gerrit 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

github2gerrit/cli.py

@@ -7,8 +7,12 @@ import json
 import logging
 import os
 import tempfile
+from collections.abc import Callable
 from pathlib import Path
+from typing import TYPE_CHECKING
 from typing import Any
+from typing import Protocol
+from typing import TypeVar
 from typing import cast
 from urllib.parse import urlparse
 
@@ -16,7 +20,9 @@ import click
 import typer
 
 from . import models
+from .config import _is_github_actions_context
 from .config import apply_config_to_env
+from .config import apply_parameter_derivation
 from .config import load_org_config
 from .core import Orchestrator
 from .core import SubmissionResult
@@ -31,6 +37,31 @@ from .models import GitHubContext
 from .models import Inputs
 
 
+def _is_verbose_mode() -> bool:
+    """Check if verbose mode is enabled via environment variable."""
+    return os.getenv("G2G_VERBOSE", "").lower() in ("true", "1", "yes")
+
+
+def _log_exception_conditionally(
+    logger: logging.Logger, message: str, *args: Any
+) -> None:
+    """Log exception with traceback only if verbose mode is enabled."""
+    if _is_verbose_mode():
+        logger.exception(message, *args)
+    else:
+        logger.error(message, *args)
+
+
+class ConfigurationError(Exception):
+    """Raised when configuration validation fails.
+
+    This custom exception is used instead of typer.BadParameter to provide
+    cleaner error messages to end users without exposing Python tracebacks.
+    When caught, it displays user-friendly messages prefixed with
+    "Configuration validation failed:" rather than raw exception details.
+    """
+
+
 def _parse_github_target(url: str) -> tuple[str | None, str | None, int | None]:
     """
     Parse a GitHub repository or pull request URL.
@@ -73,14 +104,36 @@ def _parse_github_target(url: str) -> tuple[str | None, str | None, int | None]:
 APP_NAME = "github2gerrit"
 
 
-class _SingleUsageGroup(click.Group):  # type: ignore[misc]
-    def format_usage(self, ctx: Any, formatter: Any) -> None:
+if TYPE_CHECKING:
+    BaseGroup = object
+else:
+    BaseGroup = click.Group
+
+
+class _FormatterProto(Protocol):
+    def write_usage(self, prog: str, args: str, prefix: str = ...) -> None: ...
+
+
+class _ContextProto(Protocol):
+    @property
+    def command_path(self) -> str: ...
+
+
+class _SingleUsageGroup(BaseGroup):
+    def format_usage(
+        self, ctx: _ContextProto, formatter: _FormatterProto
+    ) -> None:
         # Force a simplified usage line without COMMAND [ARGS]...
         formatter.write_usage(
             ctx.command_path, "[OPTIONS] TARGET_URL", prefix="Usage: "
         )
 
 
+# Error message constants to comply with TRY003
+_MSG_MISSING_REQUIRED_INPUT = "Missing required input: {field_name}"
+_MSG_INVALID_FETCH_DEPTH = "FETCH_DEPTH must be a positive integer"
+_MSG_ISSUE_ID_MULTILINE = "Issue ID must be single line"
+
 app: typer.Typer = typer.Typer(
     add_completion=False,
     no_args_is_help=False,
@@ -98,7 +151,17 @@ def _resolve_org(default_org: str | None) -> str:
     return ""
 
 
-@app.command()  # type: ignore[misc]
+if TYPE_CHECKING:
+    F = TypeVar("F", bound=Callable[..., object])
+
+    def typed_app_command(
+        *args: object, **kwargs: object
+    ) -> Callable[[F], F]: ...
+else:
+    typed_app_command = app.command
+
+
+@typed_app_command()
 def main(
     ctx: typer.Context,
     target_url: str | None = typer.Argument(
@@ -390,7 +453,7 @@ def _process_bulk(data: Inputs, gh: GitHubContext) -> None:
                 per_ctx, allow_duplicates=data.allow_duplicates
             )
         except DuplicateChangeError as exc:
-            log.exception("Skipping PR #%d", pr_number)
+            _log_exception_conditionally(log, "Skipping PR #%d", pr_number)
             typer.echo(f"Skipping PR #{pr_number}: {exc}")
             continue
 
@@ -402,7 +465,7 @@ def _process_bulk(data: Inputs, gh: GitHubContext) -> None:
                 if result_multi.change_urls:
                     all_urls.extend(result_multi.change_urls)
                     for url in result_multi.change_urls:
-                        typer.echo(f"Gerrit change URL: {url}")
+                        log.info("Gerrit change URL: %s", url)
                         log.info(
                             "PR #%d created Gerrit change: %s",
                             pr_number,
@@ -416,7 +479,9 @@ def _process_bulk(data: Inputs, gh: GitHubContext) -> None:
                         result_multi.change_numbers,
                     )
         except Exception as exc:
-            log.exception("Failed to process PR #%d", pr_number)
+            _log_exception_conditionally(
+                log, "Failed to process PR #%d", pr_number
+            )
             typer.echo(f"Failed to process PR #{pr_number}: {exc}")
             log.info("Continuing to next PR despite failure")
             continue
@@ -452,8 +517,10 @@ def _process_single(data: Inputs, gh: GitHubContext) -> None:
             log.debug("Local checkout preparation failed: %s", exc)
 
         orch = Orchestrator(workspace=workspace)
+        pipeline_success = False
         try:
             result = orch.execute(inputs=data, gh=gh)
+            pipeline_success = True
         except Exception as exc:
             log.debug("Execution failed; continuing to write outputs: %s", exc)
 
@@ -466,7 +533,7 @@ def _process_single(data: Inputs, gh: GitHubContext) -> None:
             )
             # Output Gerrit change URL(s) to console
             for url in result.change_urls:
-                typer.echo(f"Gerrit change URL: {url}")
+                log.info("Gerrit change URL: %s", url)
         if result.change_numbers:
             os.environ["GERRIT_CHANGE_REQUEST_NUM"] = "\n".join(
                 result.change_numbers
@@ -485,7 +552,10 @@ def _process_single(data: Inputs, gh: GitHubContext) -> None:
             }
         )
 
-        log.info("Submission pipeline complete.")
+        if pipeline_success:
+            log.info("Submission pipeline completed SUCCESSFULLY ✅")
+        else:
+            log.error("Submission pipeline FAILED ❌")
         return
 
 
@@ -562,6 +632,10 @@ def _load_effective_inputs() -> Inputs:
         or os.getenv("GITHUB_REPOSITORY_OWNER")
     )
     cfg = load_org_config(org_for_cfg)
+
+    # Apply dynamic parameter derivation for missing Gerrit parameters
+    cfg = apply_parameter_derivation(cfg, org_for_cfg, save_to_config=True)
+
     apply_config_to_env(cfg)
 
     # Refresh inputs after applying configuration to environment
@@ -661,9 +735,9 @@ def _process() -> None:
     # Validate inputs
     try:
         _validate_inputs(data)
-    except typer.BadParameter as exc:
-        log.exception("Validation failed")
-        typer.echo(str(exc), err=True)
+    except ConfigurationError as exc:
+        _log_exception_conditionally(log, "Configuration validation failed")
+        typer.echo(f"Configuration validation failed: {exc}", err=True)
         raise typer.Exit(code=2) from exc
 
     gh = _read_github_context()
@@ -707,7 +781,7 @@ def _process() -> None:
         try:
             check_for_duplicates(gh, allow_duplicates=data.allow_duplicates)
         except DuplicateChangeError as exc:
-            log.exception("Duplicate change detected")
+            _log_exception_conditionally(log, "Duplicate change detected")
             typer.echo(f"Error: {exc}", err=True)
             typer.echo(
                 "Use --allow-duplicates to override this check.", err=True
@@ -803,27 +877,87 @@ def _validate_inputs(data: Inputs) -> None:
             "USE_PR_AS_COMMIT and SUBMIT_SINGLE_COMMITS cannot be enabled at "
             "the same time"
         )
-        raise typer.BadParameter(msg)
-
-    # Presence checks for required fields used by existing action
-    for field_name in (
-        "gerrit_known_hosts",
-        "gerrit_ssh_privkey_g2g",
-        "gerrit_ssh_user_g2g",
-        "gerrit_ssh_user_g2g_email",
-    ):
+        raise ConfigurationError(msg)
+
+    # Context-aware validation: different requirements for GH Actions vs CLI
+    is_github_actions = _is_github_actions_context()
+
+    # SSH private key is always required
+    required_fields = ["gerrit_ssh_privkey_g2g"]
+
+    # Gerrit parameters can be derived in GH Actions if organization available
+    # In local CLI context, we're more strict about explicit configuration
+    if is_github_actions:
+        # In GitHub Actions: allow derivation if organization is available
+        if not data.organization:
+            # No organization means no derivation possible
+            required_fields.extend(
+                [
+                    "gerrit_ssh_user_g2g",
+                    "gerrit_ssh_user_g2g_email",
+                ]
+            )
+    else:
+        # In local CLI: require explicit values or organization + derivation
+        # This prevents unexpected behavior when running locally
+        missing_gerrit_params = [
+            field
+            for field in ["gerrit_ssh_user_g2g", "gerrit_ssh_user_g2g_email"]
+            if not getattr(data, field)
+        ]
+        if missing_gerrit_params:
+            if data.organization:
+                log.info(
+                    "Local CLI usage: Gerrit parameters can be derived from "
+                    "organization '%s'. Missing: %s. Consider setting "
+                    "G2G_ENABLE_DERIVATION=true to enable derivation.",
+                    data.organization,
+                    ", ".join(missing_gerrit_params),
+                )
+                # Allow derivation in local mode only if explicitly enabled
+                if not _env_bool("G2G_ENABLE_DERIVATION", False):
+                    required_fields.extend(missing_gerrit_params)
+            else:
+                required_fields.extend(missing_gerrit_params)
+
+    for field_name in required_fields:
         if not getattr(data, field_name):
             log.error("Missing required input: %s", field_name)
-            raise typer.BadParameter(f"Missing required input: {field_name}")  # noqa: TRY003
+            if field_name in [
+                "gerrit_ssh_user_g2g",
+                "gerrit_ssh_user_g2g_email",
+            ]:
+                if data.organization:
+                    if is_github_actions:
+                        log.error(
+                            "These fields can be derived automatically from "
+                            "organization '%s'",
+                            data.organization,
+                        )
+                    else:
+                        log.error(
+                            "These fields can be derived from organization "
+                            "'%s'",
+                            data.organization,
+                        )
+                        log.error("Set G2G_ENABLE_DERIVATION=true to enable")
+                else:
+                    log.error(
+                        "These fields require either explicit values or an "
+                        "ORGANIZATION for derivation"
+                    )
+            raise ConfigurationError(
+                _MSG_MISSING_REQUIRED_INPUT.format(field_name=field_name)
+            )
 
     # Validate fetch depth is a positive integer
     if data.fetch_depth <= 0:
         log.error("Invalid FETCH_DEPTH: %s", data.fetch_depth)
-        raise typer.BadParameter("FETCH_DEPTH must be a positive integer")  # noqa: TRY003
+        raise ConfigurationError(_MSG_INVALID_FETCH_DEPTH)
 
     # Validate Issue ID is a single line string if provided
     if data.issue_id and ("\n" in data.issue_id or "\r" in data.issue_id):
-        raise typer.BadParameter("Issue ID must be single line")  # noqa: TRY003
+        raise ConfigurationError(_MSG_ISSUE_ID_MULTILINE)
 
 
 def _log_effective_config(data: Inputs, gh: GitHubContext) -> None:
@@ -833,10 +967,10 @@ def _log_effective_config(data: Inputs, gh: GitHubContext) -> None:
     log.info("  SUBMIT_SINGLE_COMMITS: %s", data.submit_single_commits)
     log.info("  USE_PR_AS_COMMIT: %s", data.use_pr_as_commit)
     log.info("  FETCH_DEPTH: %s", data.fetch_depth)
-    log.info(
-        "  GERRIT_KNOWN_HOSTS: %s",
-        "<provided>" if data.gerrit_known_hosts else "<missing>",
+    known_hosts_status = (
+        "<provided>" if data.gerrit_known_hosts else "<will auto-discover>"
     )
+    log.info("  GERRIT_KNOWN_HOSTS: %s", known_hosts_status)
     log.info("  GERRIT_SSH_PRIVKEY_G2G: %s", safe_privkey)
     log.info("  GERRIT_SSH_USER_G2G: %s", data.gerrit_ssh_user_g2g)
     log.info("  GERRIT_SSH_USER_G2G_EMAIL: %s", data.gerrit_ssh_user_g2g_email)

github2gerrit/config.py

@@ -58,8 +58,8 @@ log = logging.getLogger("github2gerrit.config")
 
 DEFAULT_CONFIG_PATH = "~/.config/github2gerrit/configuration.txt"
 
-# Recognized keys. Unknown keys are still passed through, but these are
-# the most relevant to current tooling and action inputs/options.
+# Recognized keys. Unknown keys will be reported as warnings to help
+# users catch typos and missing functionality.
 KNOWN_KEYS: set[str] = {
     # Action inputs
     "SUBMIT_SINGLE_COMMITS",
@@ -74,6 +74,15 @@ KNOWN_KEYS: set[str] = {
     "PR_NUMBER",
     "SYNC_ALL_OPEN_PRS",
     "PRESERVE_GITHUB_PRS",
+    "ALLOW_GHE_URLS",
+    "DRY_RUN",
+    "ALLOW_DUPLICATES",
+    "ISSUE_ID",
+    "G2G_VERBOSE",
+    "G2G_SKIP_GERRIT_COMMENTS",
+    "G2G_ENABLE_DERIVATION",
+    "G2G_AUTO_SAVE_CONFIG",
+    "GITHUB_TOKEN",
     # Optional inputs (reusable workflow compatibility)
     "GERRIT_SERVER",
     "GERRIT_SERVER_PORT",
@@ -264,6 +273,17 @@ def load_org_config(
             )
 
     normalized = _normalize_keys(result)
+
+    # Report unknown configuration keys to help users catch typos
+    unknown_keys = set(normalized.keys()) - KNOWN_KEYS
+    if unknown_keys:
+        log.warning(
+            "Unknown configuration keys found in [%s]: %s. "
+            "These will be ignored. Check for typos or missing functionality.",
+            effective_org or "default",
+            ", ".join(sorted(unknown_keys)),
+        )
+
     return normalized
 
 
@@ -295,6 +315,198 @@ def filter_known(
     return {k: v for k, v in cfg.items() if k in KNOWN_KEYS}
 
 
+def _is_github_actions_context() -> bool:
+    """Detect if running in GitHub Actions environment."""
+    return (
+        os.getenv("GITHUB_ACTIONS") == "true"
+        or os.getenv("GITHUB_EVENT_NAME", "").strip() != ""
+    )
+
+
+def _is_local_cli_context() -> bool:
+    """Detect if running as local CLI tool."""
+    return not _is_github_actions_context()
+
+
+def derive_gerrit_parameters(organization: str | None) -> dict[str, str]:
+    """Derive Gerrit parameters from GitHub organization name.
+
+    Args:
+        organization: GitHub organization name
+
+    Returns:
+        Dict with derived parameter values:
+        - GERRIT_SSH_USER_G2G: [org].gh2gerrit
+        - GERRIT_SSH_USER_G2G_EMAIL: releng+[org]-gh2gerrit@linuxfoundation.org
+        - GERRIT_SERVER: gerrit.[org].org
+    """
+    if not organization:
+        return {}
+
+    org = organization.strip().lower()
+    return {
+        "GERRIT_SSH_USER_G2G": f"{org}.gh2gerrit",
+        "GERRIT_SSH_USER_G2G_EMAIL": (
+            f"releng+{org}-gh2gerrit@linuxfoundation.org"
+        ),
+        "GERRIT_SERVER": f"gerrit.{org}.org",
+    }
+
+
+def apply_parameter_derivation(
+    cfg: dict[str, str],
+    organization: str | None = None,
+    save_to_config: bool = True,
+) -> dict[str, str]:
+    """Apply dynamic parameter derivation for missing Gerrit parameters.
+
+    This function derives standard Gerrit parameters when they are not
+    explicitly configured. The derivation is based on the GitHub organization:
+
+    - gerrit_ssh_user_g2g: [org].gh2gerrit
+    - gerrit_ssh_user_g2g_email: releng+[org]-gh2gerrit@linuxfoundation.org
+    - gerrit_server: gerrit.[org].org
+
+    Derivation behavior depends on execution context:
+    - GitHub Actions: Automatic derivation when organization is available
+    - Local CLI: Requires G2G_ENABLE_DERIVATION=true for automatic derivation
+
+    Args:
+        cfg: Configuration dictionary to augment
+        organization: GitHub organization name for derivation
+        save_to_config: Whether to save derived parameters to config file
+
+    Returns:
+        Configuration dictionary with derived values for missing parameters
+    """
+    if not organization:
+        return cfg
+
+    # Check execution context to determine derivation strategy
+    is_github_actions = _is_github_actions_context()
+    enable_derivation = is_github_actions or os.getenv(
+        "G2G_ENABLE_DERIVATION", ""
+    ).strip().lower() in ("1", "true", "yes", "on")
+
+    if not enable_derivation:
+        log.debug(
+            "Parameter derivation disabled for local CLI usage. "
+            "Set G2G_ENABLE_DERIVATION=true to enable automatic derivation."
+        )
+        return cfg
+
+    # Only derive parameters that are missing or empty
+    derived = derive_gerrit_parameters(organization)
+    result = dict(cfg)
+    newly_derived = {}
+
+    for key, value in derived.items():
+        if key not in result or not result[key].strip():
+            log.debug(
+                "Deriving %s from organization '%s': %s (context: %s)",
+                key,
+                organization,
+                value,
+                "GitHub Actions" if is_github_actions else "Local CLI",
+            )
+            result[key] = value
+            newly_derived[key] = value
+
+    # Save newly derived parameters to configuration file for future use
+    # Default to true for local CLI, false for GitHub Actions
+    default_auto_save = "false" if _is_github_actions_context() else "true"
+    auto_save_enabled = os.getenv(
+        "G2G_AUTO_SAVE_CONFIG", default_auto_save
+    ).strip().lower() in ("1", "true", "yes", "on")
+    if save_to_config and newly_derived and auto_save_enabled:
+        # Save to config in local CLI mode to create persistent configuration
+        try:
+            save_derived_parameters_to_config(organization, newly_derived)
+            log.info(
+                "Automatically saved derived parameters to configuration "
+                "file for organization '%s'. "
+                "This creates a persistent configuration that you can "
+                "customize if needed.",
+                organization,
+            )
+        except Exception as exc:
+            log.warning("Failed to save derived parameters to config: %s", exc)
+
+    return result
+
+
+def save_derived_parameters_to_config(
+    organization: str,
+    derived_params: dict[str, str],
+    config_path: str | None = None,
+) -> None:
+    """Save derived parameters to the organization's configuration file.
+
+    This function updates the configuration file to include any derived
+    parameters that are not already present in the organization section.
+    This creates a persistent configuration that users can modify if needed.
+
+    Args:
+        organization: GitHub organization name for config section
+        derived_params: Dictionary of derived parameter key-value pairs
+        config_path: Path to config file (optional, uses default if not
+                    provided)
+
+    Raises:
+        Exception: If saving fails
+    """
+    if not organization or not derived_params:
+        return
+
+    if config_path is None:
+        config_path = (
+            os.getenv("G2G_CONFIG_PATH", "").strip() or DEFAULT_CONFIG_PATH
+        )
+
+    config_file = Path(config_path).expanduser()
+
+    try:
+        # Ensure the directory exists
+        config_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Parse existing content using configparser
+        cp = _load_ini(config_file)
+
+        # Find or create the organization section
+        org_section = _select_section(cp, organization)
+        if org_section is None:
+            # Section doesn't exist, we'll need to add it
+            cp.add_section(organization)
+            org_section = organization
+
+        # Add derived parameters that don't already exist
+        params_added = []
+        for key, value in derived_params.items():
+            if not cp.has_option(org_section, key):
+                cp.set(org_section, key, f'"{value}"')
+                params_added.append(key)
+
+        # Only write if we added parameters
+        if params_added:
+            # Write the updated configuration
+            with config_file.open("w", encoding="utf-8") as f:
+                cp.write(f)
+
+            log.debug(
+                "Saved derived parameters to configuration file %s [%s]: %s",
+                config_file,
+                organization,
+                ", ".join(params_added),
+            )
+
+    except Exception as exc:
+        log.warning(
+            "Failed to save derived parameters to configuration file %s: %s",
+            config_file,
+            exc,
+        )
+
+
 def overlay_missing(
     primary: dict[str, str],
     fallback: dict[str, str],