github2gerrit 0.1.9__py3-none-any.whl → 0.1.11__py3-none-any.whl

github2gerrit/ssh_common.py

@@ -35,14 +35,17 @@ def build_ssh_options(
         batch_mode: Enable batch mode (non-interactive)
         connect_timeout: Connection timeout in seconds
         additional_options: Additional SSH options to include
-        respect_user_ssh_config: If True, respect user SSH config; if None, check G2G_RESPECT_USER_SSH env var
+        respect_user_ssh_config: If True, respect user SSH config; if None,
+            check G2G_RESPECT_USER_SSH env var
 
     Returns:
         List of SSH option strings suitable for ssh command line
     """
     # Check if we should respect user SSH config
     if respect_user_ssh_config is None:
-        respect_user_ssh_config = os.getenv("G2G_RESPECT_USER_SSH", "false").lower() in ("true", "1", "yes")
+        respect_user_ssh_config = os.getenv(
+            "G2G_RESPECT_USER_SSH", "false"
+        ).lower() in ("true", "1", "yes")
 
     options = []
     if not respect_user_ssh_config:
@@ -57,7 +60,8 @@ def build_ssh_options(
     if identities_only and not respect_user_ssh_config:
         options.extend(
             [
-                "-o IdentitiesOnly=yes",  # Critical: prevents SSH agent scanning
+                "-o IdentitiesOnly=yes",  # Critical: prevents SSH agent
+                # scanning
                 "-o IdentityAgent=none",
             ]
         )
@@ -107,7 +111,8 @@ def build_git_ssh_command(
         batch_mode: Enable batch mode (non-interactive)
         connect_timeout: Connection timeout in seconds
         additional_options: Additional SSH options to include
-        respect_user_ssh_config: If True, respect user SSH config; if None, check G2G_RESPECT_USER_SSH env var
+        respect_user_ssh_config: If True, respect user SSH config; if None,
+            check G2G_RESPECT_USER_SSH env var
 
     Returns:
         Complete SSH command string suitable for GIT_SSH_COMMAND
@@ -158,9 +163,11 @@ def augment_known_hosts_with_bracketed_entries(
     hostname: str,
     port: int = 22,
 ) -> str:
-    """Augment known_hosts content with bracketed [host]:port entries for non-standard ports.
+    """Augment known_hosts content with bracketed [host]:port entries for
+    non-standard ports.
 
-    This function adds bracketed [host]:port variants for existing plain host entries
+    This function adds bracketed [host]:port variants for existing plain host
+    entries
     to satisfy StrictHostKeyChecking with non-standard SSH ports.
 
     Args:
@@ -169,15 +176,21 @@ def augment_known_hosts_with_bracketed_entries(
         port: SSH port (default 22)
 
     Returns:
-        Augmented known_hosts content (always normalized to end with single newline)
+        Augmented known_hosts content (always normalized to end with single
+        newline)
     """
     if not known_hosts_content.strip():
         return known_hosts_content
 
-    original_lines = [ln.rstrip() for ln in known_hosts_content.strip().splitlines() if ln.strip()]
+    original_lines = [
+        ln.rstrip()
+        for ln in known_hosts_content.strip().splitlines()
+        if ln.strip()
+    ]
     augmented = list(original_lines)
 
-    # Add bracketed [host]:port variants for non-standard ports if hostname provided
+    # Add bracketed [host]:port variants for non-standard ports if hostname
+    # provided
     if hostname and original_lines:
         bracket_prefix = f"[{hostname}]:{port} "
         plain_prefix = f"{hostname} "
@@ -199,7 +212,8 @@ def merge_known_hosts_content(
     base_content: str,
     additional_content: str,
 ) -> str:
-    """Merge additional known_hosts content into base content without duplicates.
+    """Merge additional known_hosts content into base content without
+    duplicates.
 
     Args:
         base_content: Original known_hosts content
@@ -241,4 +255,9 @@ def augment_known_hosts(
     # This is a placeholder for known hosts augmentation logic
     # The actual implementation would use ssh-keyscan or similar
     # to fetch and add host keys to the known_hosts file
-    log.debug("Would augment known_hosts at %s with %s:%d", known_hosts_path, hostname, port)
+    log.debug(
+        "Would augment known_hosts at %s with %s:%d",
+        known_hosts_path,
+        hostname,
+        port,
+    )

github2gerrit/ssh_discovery.py

@@ -30,17 +30,31 @@ class SSHDiscoveryError(Exception):
 
 
 # Error message constants to comply with TRY003
-_MSG_HOST_UNREACHABLE = "Host {hostname}:{port} is not reachable. Check network connectivity and server availability."
+_MSG_HOST_UNREACHABLE = (
+    "Host {hostname}:{port} is not reachable. Check network connectivity "
+    "and server availability."
+)
 _MSG_NO_KEYS_FOUND = (
-    "No SSH host keys found for {hostname}:{port}. The server may not be running SSH or may be blocking connections."
+    "No SSH host keys found for {hostname}:{port}. The server may not be "
+    "running SSH or may be blocking connections."
 )
 _MSG_NO_VALID_KEYS = (
-    "No valid SSH host keys found for {hostname}:{port}. The ssh-keyscan output was empty or malformed."
+    "No valid SSH host keys found for {hostname}:{port}. The ssh-keyscan "
+    "output was empty or malformed."
+)
+_MSG_CONNECTION_FAILED = (
+    "Failed to connect to {hostname}:{port} for SSH key discovery. "
+    "Error: {error}"
+)
+_MSG_KEYSCAN_FAILED = (
+    "ssh-keyscan failed with return code {returncode}: {error}"
+)
+_MSG_UNEXPECTED_ERROR = (
+    "Unexpected error during SSH key discovery for {hostname}:{port}: {error}"
+)
+_MSG_SAVE_FAILED = (
+    "Failed to save host keys to configuration file {config_file}: {error}"
 )
-_MSG_CONNECTION_FAILED = "Failed to connect to {hostname}:{port} for SSH key discovery. Error: {error}"
-_MSG_KEYSCAN_FAILED = "ssh-keyscan failed with return code {returncode}: {error}"
-_MSG_UNEXPECTED_ERROR = "Unexpected error during SSH key discovery for {hostname}:{port}: {error}"
-_MSG_SAVE_FAILED = "Failed to save host keys to configuration file {config_file}: {error}"
 
 
 def is_host_reachable(hostname: str, port: int, timeout: int = 5) -> bool:
@@ -53,7 +67,9 @@ def is_host_reachable(hostname: str, port: int, timeout: int = 5) -> bool:
 
 
 @external_api_call(ApiType.SSH, "fetch_ssh_host_keys")
-def fetch_ssh_host_keys(hostname: str, port: int = 22, timeout: int = 10) -> str:
+def fetch_ssh_host_keys(
+    hostname: str, port: int = 22, timeout: int = 10
+) -> str:
     """
     Fetch SSH host keys for a given hostname and port using ssh-keyscan.
 
@@ -72,7 +88,9 @@ def fetch_ssh_host_keys(hostname: str, port: int = 22, timeout: int = 10) -> str
 
     # First check if the host is reachable
     if not is_host_reachable(hostname, port, timeout=5):
-        raise SSHDiscoveryError(_MSG_HOST_UNREACHABLE.format(hostname=hostname, port=port))
+        raise SSHDiscoveryError(
+            _MSG_HOST_UNREACHABLE.format(hostname=hostname, port=port)
+        )
 
     try:
         # Use ssh-keyscan to fetch all available key types
@@ -127,13 +145,23 @@ def fetch_ssh_host_keys(hostname: str, port: int = 22, timeout: int = 10) -> str
             # ssh-keyscan returns 1 when it can't connect
             error_msg = exc.stderr or exc.stdout or "Connection failed"
             raise SSHDiscoveryError(
-                _MSG_CONNECTION_FAILED.format(hostname=hostname, port=port, error=error_msg)
+                _MSG_CONNECTION_FAILED.format(
+                    hostname=hostname, port=port, error=error_msg
+                )
             ) from exc
         else:
             error_msg = exc.stderr or exc.stdout or "Unknown error"
-            raise SSHDiscoveryError(_MSG_KEYSCAN_FAILED.format(returncode=exc.returncode, error=error_msg)) from exc
+            raise SSHDiscoveryError(
+                _MSG_KEYSCAN_FAILED.format(
+                    returncode=exc.returncode, error=error_msg
+                )
+            ) from exc
     except Exception as exc:
-        raise SSHDiscoveryError(_MSG_UNEXPECTED_ERROR.format(hostname=hostname, port=port, error=exc)) from exc
+        raise SSHDiscoveryError(
+            _MSG_UNEXPECTED_ERROR.format(
+                hostname=hostname, port=port, error=exc
+            )
+        ) from exc
     else:
         return discovered_keys
 
@@ -172,7 +200,9 @@ def extract_gerrit_info_from_gitreview(content: str) -> tuple[str, int] | None:
 
 
 @external_api_call(ApiType.SSH, "discover_and_save_host_keys")
-def discover_and_save_host_keys(hostname: str, port: int, organization: str, config_path: str | None = None) -> str:
+def discover_and_save_host_keys(
+    hostname: str, port: int, organization: str, config_path: str | None = None
+) -> str:
     """
     Discover SSH host keys and save them to the organization's configuration.
 
@@ -198,7 +228,9 @@ def discover_and_save_host_keys(hostname: str, port: int, organization: str, con
     return host_keys
 
 
-def save_host_keys_to_config(host_keys: str, organization: str, config_path: str | None = None) -> None:
+def save_host_keys_to_config(
+    host_keys: str, organization: str, config_path: str | None = None
+) -> None:
     """
     Save SSH host keys to the organization's configuration file.
 
@@ -214,7 +246,9 @@ def save_host_keys_to_config(host_keys: str, organization: str, config_path: str
     from .config import DEFAULT_CONFIG_PATH
 
     if config_path is None:
-        config_path = os.getenv("G2G_CONFIG_PATH", "").strip() or DEFAULT_CONFIG_PATH
+        config_path = (
+            os.getenv("G2G_CONFIG_PATH", "").strip() or DEFAULT_CONFIG_PATH
+        )
 
     config_file = Path(config_path).expanduser()
 
@@ -283,7 +317,9 @@ def save_host_keys_to_config(host_keys: str, organization: str, config_path: str
 
             # Insert the GERRIT_KNOWN_HOSTS entry
             escaped_keys = host_keys.replace("\n", "\\n")
-            new_lines.insert(section_end, f'GERRIT_KNOWN_HOSTS = "{escaped_keys}"')
+            new_lines.insert(
+                section_end, f'GERRIT_KNOWN_HOSTS = "{escaped_keys}"'
+            )
 
         # Write the updated configuration
         config_file.write_text("\n".join(new_lines), encoding="utf-8")
@@ -295,7 +331,9 @@ def save_host_keys_to_config(host_keys: str, organization: str, config_path: str
         )
 
     except Exception as exc:
-        raise SSHDiscoveryError(_MSG_SAVE_FAILED.format(config_file=config_file, error=exc)) from exc
+        raise SSHDiscoveryError(
+            _MSG_SAVE_FAILED.format(config_file=config_file, error=exc)
+        ) from exc
 
 
 def auto_discover_gerrit_host_keys(
@@ -326,14 +364,21 @@ def auto_discover_gerrit_host_keys(
             gerrit_port = 29418
 
         if organization is None:
-            organization = (os.getenv("ORGANIZATION") or os.getenv("GITHUB_REPOSITORY_OWNER") or "").strip()
+            organization = (
+                os.getenv("ORGANIZATION")
+                or os.getenv("GITHUB_REPOSITORY_OWNER")
+                or ""
+            ).strip()
 
         if not gerrit_hostname:
             log.debug("No Gerrit hostname provided for auto-discovery")
             return None
 
         if not organization:
-            log.warning("No organization specified for SSH host key auto-discovery. Cannot save to configuration file.")
+            log.warning(
+                "No organization specified for SSH host key auto-discovery. "
+                "Cannot save to configuration file."
+            )
             save_to_config = False
 
         log.info(
@@ -363,7 +408,9 @@ def auto_discover_gerrit_host_keys(
         log.warning("SSH host key auto-discovery failed: %s", exc)
         return None
     except Exception as exc:
-        log.warning("Unexpected error during SSH host key auto-discovery: %s", exc)
+        log.warning(
+            "Unexpected error during SSH host key auto-discovery: %s", exc
+        )
         return None
     else:
         return host_keys

github2gerrit/trailers.py

@@ -0,0 +1,340 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2025 The Linux Foundation
+"""
+Common trailer constants and parsing utilities.
+
+This module provides shared functionality for working with Git commit
+trailers, particularly GitHub PR metadata trailers used for reconciliation.
+"""
+
+import logging
+import re
+
+
+log = logging.getLogger(__name__)
+
+
+# Trailer key constants
+GITHUB_PR_TRAILER = "GitHub-PR"
+GITHUB_HASH_TRAILER = "GitHub-Hash"
+CHANGE_ID_TRAILER = "Change-Id"
+SIGNED_OFF_BY_TRAILER = "Signed-off-by"
+
+# Standard trailer keys we recognize
+KNOWN_TRAILER_KEYS = {
+    GITHUB_PR_TRAILER,
+    GITHUB_HASH_TRAILER,
+    CHANGE_ID_TRAILER,
+    SIGNED_OFF_BY_TRAILER,
+}
+
+
+def parse_trailers(commit_message: str) -> dict[str, list[str]]:
+    """
+    Parse Git-style trailers from a commit message.
+
+    Trailers are key-value pairs at the end of a commit message,
+    after the last blank line, in the format "Key: value".
+
+    Args:
+        commit_message: Full commit message text
+
+    Returns:
+        Dictionary mapping trailer keys to lists of values
+    """
+    trailers: dict[str, list[str]] = {}
+
+    if not commit_message.strip():
+        return trailers
+
+    lines = commit_message.strip().split("\n")
+
+    # Find the start of trailers (after the last blank line)
+    trailer_start = 0
+    for i in range(len(lines) - 1, -1, -1):
+        if not lines[i].strip():
+            trailer_start = i + 1
+            break
+
+    # Parse trailer lines
+    for raw_line in lines[trailer_start:]:
+        line = raw_line.strip()
+        if ":" in line:
+            key, value = line.split(":", 1)
+            key = key.strip()
+            value = value.strip()
+
+            if key:
+                if key not in trailers:
+                    trailers[key] = []
+                trailers[key].append(value)
+
+    return trailers
+
+
+def extract_github_metadata(commit_message: str) -> dict[str, str]:
+    """
+    Extract GitHub PR metadata trailers from a commit message.
+
+    Args:
+        commit_message: Full commit message text
+
+    Returns:
+        Dictionary with GitHub-* trailer values (single values, not lists)
+    """
+    trailers = parse_trailers(commit_message)
+    metadata = {}
+
+    for key in [GITHUB_PR_TRAILER, GITHUB_HASH_TRAILER]:
+        values = trailers.get(key, [])
+        if values:
+            # Take the last value if multiple exist
+            metadata[key] = values[-1]
+
+    return metadata
+
+
+def extract_change_ids(commit_message: str) -> list[str]:
+    """
+    Extract Change-Id trailer values from a commit message.
+
+    Args:
+        commit_message: Full commit message text
+
+    Returns:
+        List of Change-Id values found
+    """
+    trailers = parse_trailers(commit_message)
+    return trailers.get(CHANGE_ID_TRAILER, [])
+
+
+def has_trailer(
+    commit_message: str, key: str, value: str | None = None
+) -> bool:
+    """
+    Check if a commit message contains a specific trailer.
+
+    Args:
+        commit_message: Full commit message text
+        key: Trailer key to check for
+        value: Optional specific value to match (if None, any value matches)
+
+    Returns:
+        True if the trailer exists with the specified value (or any value)
+    """
+    trailers = parse_trailers(commit_message)
+
+    if key not in trailers:
+        return False
+
+    if value is None:
+        return True
+
+    return value in trailers[key]
+
+
+def add_trailers(commit_message: str, new_trailers: dict[str, str]) -> str:
+    """
+    Add trailers to a commit message, avoiding duplicates.
+
+    Args:
+        commit_message: Original commit message
+        new_trailers: Dictionary of trailers to add (key -> value)
+
+    Returns:
+        Commit message with trailers added
+    """
+    if not new_trailers:
+        return commit_message
+
+    existing_trailers = parse_trailers(commit_message)
+    msg = commit_message.rstrip()
+
+    # Collect trailers that need to be added
+    to_add = []
+    for key, value in new_trailers.items():
+        if key not in existing_trailers or value not in existing_trailers[key]:
+            to_add.append(f"{key}: {value}")
+
+    if to_add:
+        if msg and not msg.endswith("\n"):
+            msg += "\n"
+        if not msg.endswith("\n\n"):
+            msg += "\n"
+        msg += "\n".join(to_add) + "\n"
+
+    return msg
+
+
+def normalize_subject_for_matching(subject: str) -> str:
+    """
+    Normalize a commit subject line for similarity matching.
+
+    This removes common noise and standardizes the format to improve
+    matching accuracy when commits have minor subject changes.
+
+    Args:
+        subject: Original commit subject line
+
+    Returns:
+        Normalized subject for comparison
+    """
+    if not subject:
+        return ""
+
+    # Remove common prefixes and suffixes
+    normalized = subject.strip()
+
+    # Remove version numbers and tags in brackets/parentheses
+    normalized = re.sub(r"\s*[\[\(][vV]?\d+[\.\d]*[\]\)]\s*", " ", normalized)
+
+    # Remove "WIP:", "DRAFT:", etc. prefixes
+    normalized = re.sub(
+        r"^\s*(WIP|DRAFT|TODO|FIXME|HACK):\s*",
+        "",
+        normalized,
+        flags=re.IGNORECASE,
+    )
+
+    # Remove trailing punctuation and whitespace
+    normalized = re.sub(r"[.!]+\s*$", "", normalized)
+
+    # Normalize whitespace
+    normalized = re.sub(r"\s+", " ", normalized).strip()
+
+    # Convert to lowercase for case-insensitive matching
+    return normalized.lower()
+
+
+def compute_file_signature(file_paths: list[str]) -> str:
+    """
+    Compute a normalized signature for a set of file paths.
+
+    This creates a deterministic hash of the files touched by a commit,
+    useful for matching commits that affect the same files.
+
+    Args:
+        file_paths: List of file paths
+
+    Returns:
+        Hex string signature of the file set
+    """
+    import hashlib
+
+    if not file_paths:
+        return ""
+
+    # Normalize paths: lowercase, remove leading/trailing slashes
+    normalized_paths = []
+    for path in file_paths:
+        normalized = path.strip().lower()
+        normalized = normalized.strip("/")
+        if normalized:
+            normalized_paths.append(normalized)
+
+    # Sort for deterministic ordering
+    normalized_paths.sort()
+
+    # Create hash of the sorted, normalized path list
+    content = "\n".join(normalized_paths)
+    hash_obj = hashlib.sha256(content.encode("utf-8"))
+    return hash_obj.hexdigest()[:12]  # 12 hex chars = 48 bits
+
+
+def extract_subject_tokens(subject: str) -> set[str]:
+    """
+    Extract meaningful tokens from a subject line for similarity matching.
+
+    Args:
+        subject: Commit subject line
+
+    Returns:
+        Set of normalized tokens
+    """
+    if not subject:
+        return set()
+
+    # Normalize the subject
+    normalized = normalize_subject_for_matching(subject)
+
+    # Split on common delimiters and filter out short/common words
+    tokens = re.split(r"[\s\-_\.,:;/\\]+", normalized)
+
+    # Filter tokens: must be at least 3 chars and not common stop words
+    stop_words = {
+        "the",
+        "and",
+        "for",
+        "are",
+        "but",
+        "not",
+        "you",
+        "all",
+        "can",
+        "had",
+        "has",
+        "was",
+        "one",
+        "our",
+        "out",
+        "day",
+        "get",
+        "use",
+        "man",
+        "new",
+        "now",
+        "old",
+        "see",
+        "two",
+        "way",
+        "who",
+        "its",
+        "did",
+        "yes",
+        "his",
+        "her",
+        "him",
+        "how",
+        "may",
+        "say",
+        "she",
+        "add",
+        "fix",
+        "set",
+        "put",
+        "run",
+        "try",
+        "let",
+        "end",
+    }
+
+    meaningful_tokens = set()
+    for raw_token in tokens:
+        token = raw_token.strip()
+        if len(token) >= 3 and token not in stop_words:
+            meaningful_tokens.add(token)
+
+    return meaningful_tokens
+
+
+def compute_jaccard_similarity(set1: set[str], set2: set[str]) -> float:
+    """
+    Compute Jaccard similarity between two sets of tokens.
+
+    Args:
+        set1: First set of tokens
+        set2: Second set of tokens
+
+    Returns:
+        Jaccard similarity coefficient (0.0 to 1.0)
+    """
+    if not set1 and not set2:
+        return 1.0
+
+    if not set1 or not set2:
+        return 0.0
+
+    intersection = len(set1.intersection(set2))
+    union = len(set1.union(set2))
+
+    return intersection / union if union > 0 else 0.0

github2gerrit/utils.py

@@ -68,7 +68,9 @@ def is_verbose_mode() -> bool:
     return os.getenv("G2G_VERBOSE", "").lower() in ("true", "1", "yes")
 
 
-def log_exception_conditionally(logger: logging.Logger, message: str, *args: Any) -> None:
+def log_exception_conditionally(
+    logger: logging.Logger, message: str, *args: Any
+) -> None:
     """Log exception with traceback only if verbose mode is enabled.
 
     Args:
@@ -110,4 +112,6 @@ def append_github_output(outputs: dict[str, str]) -> None:
     except Exception as exc:
         # Use a basic logger since we can't import from other modules
         # without creating circular dependencies
-        logging.getLogger(__name__).debug("Failed to write GITHUB_OUTPUT: %s", exc)
+        logging.getLogger(__name__).debug(
+            "Failed to write GITHUB_OUTPUT: %s", exc
+        )