downstream_issue.py

# This file is part of sync2jira.
# Copyright (C) 2016 Red Hat, Inc.
#
# sync2jira is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# sync2jira is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with sync2jira; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110.15.0 USA
#
# Authors:  Ralph Bean <rbean@redhat.com>

from datetime import datetime, timezone
import difflib
import logging
import operator
import os
import re
from typing import Any, Dict, Optional, Union
import unicodedata

from dotenv import load_dotenv
from jira import JIRAError
import jira.client
from jira.client import Issue as JIssue
from jira.client import ResultList
import pypandoc
import snowflake.connector

import Rover_Lookup
from sync2jira.intermediary import Issue, PR
from sync2jira.jira_auth import (
    build_jira_client_kwargs,
    invalidate_oauth2_cache_for_config,
)

load_dotenv()
# The date the service was upgraded
# This is used to ensure legacy comments are not touched
UPDATE_DATE = datetime(2019, 7, 9, 18, 18, 36, 480291, tzinfo=timezone.utc)

# Jira REST API rejects comment bodies longer than this (characters).
JIRA_TEXT_BODY_MAX_CHARS = 32750
# When truncating, keep at least this many characters of the original body.
# If the hyperlink(s) wouldn't leave this much room, drop the hyperlink instead.
JIRA_TEXT_BODY_MIN_CHARS = 1024

log = logging.getLogger("sync2jira")
logging.getLogger("snowflake.connector").setLevel(logging.WARNING)

remote_link_title = "Upstream issue"
duplicate_issues_subject = "FYI: Duplicate Sync2jira Issues"

SNOWFLAKE_QUERY = f"""
SELECT
    CONCAT(p.PKEY, '-', a.issue_key) AS issue_key,
    remote_link_url,
    updated
FROM
    (
        SELECT
            ji.PROJECT_ID AS project_id,
            ji.ISSUENUM AS issue_key,
            rl.URL AS remote_link_url,
            ji.updated
        FROM
            JIRA_DB.CLOUD_MARTS.JIRA_REMOTELINK AS rl
            INNER JOIN JIRA_DB.CLOUD_MARTS.JIRA_ISSUE AS ji ON ji.ID = rl.ISSUEID
            AND rl.TITLE = '{remote_link_title}' AND rl.URL = ?
    ) AS a
    LEFT JOIN JIRA_DB.CLOUD_MARTS.JIRA_PROJECT AS p on a.project_id = p.ID
"""


GH_URL_PATTERN = re.compile(r"https://github\.com/[^/]+/[^/]+/(issues|pull)/\d+")
field_name_cache = {}


class UrlCache(dict):
    """A dict-like object, intended to be used as a cache, which contains a
    limited number of entries -- excess entries are deleted in FIFO order.
    """

    MAX_SIZE = 20000

    def __setitem__(self, key, value):
        while len(self) >= self.MAX_SIZE:
            del self[next(iter(self))]
        super().__setitem__(key, value)


jira_cache = UrlCache()


def validate_github_url(url):
    """URL validation"""
    return bool(GH_URL_PATTERN.fullmatch(url))


def get_snowflake_conn():
    """Get Snowflake connection - lazy initialization

    Supports two authentication methods:
    1. JWT authentication with private key file (if SNOWFLAKE_PRIVATE_KEY_FILE is set)
    2. Password authentication with PAT (if SNOWFLAKE_PAT is set)
    """
    account = os.getenv("SNOWFLAKE_ACCOUNT")
    user = os.getenv("SNOWFLAKE_USER")
    role = os.getenv("SNOWFLAKE_ROLE")
    warehouse = os.getenv("SNOWFLAKE_WAREHOUSE", "DEFAULT")
    database = os.getenv("SNOWFLAKE_DATABASE", "JIRA_DB")
    schema = os.getenv("SNOWFLAKE_SCHEMA", "PUBLIC")

    # Build base connection parameters
    conn_params = {
        "account": account,
        "user": user,
        "role": role,
        "warehouse": warehouse,
        "database": database,
        "schema": schema,
        "paramstyle": "qmark",
    }

    # Check for private key file (JWT authentication)
    private_key_file = os.getenv("SNOWFLAKE_PRIVATE_KEY_FILE")
    if private_key_file:
        conn_params["authenticator"] = "SNOWFLAKE_JWT"
        conn_params["private_key_file"] = private_key_file

        # Add private key file password if specified
        private_key_file_pwd = os.getenv("SNOWFLAKE_PRIVATE_KEY_FILE_PWD")
        if private_key_file_pwd:
            conn_params["private_key_file_pwd"] = private_key_file_pwd
    else:
        # Fall back to password authentication
        password = os.getenv("SNOWFLAKE_PAT")
        if not password:
            raise ValueError(
                "Either SNOWFLAKE_PRIVATE_KEY_FILE or SNOWFLAKE_PAT must be set"
            )
        conn_params["password"] = password

    return snowflake.connector.connect(**conn_params)


def execute_snowflake_query(issue):
    if not validate_github_url(issue.url):
        log.error(f"Invalid GitHub URL format: {issue.url}")
        return []
    conn = get_snowflake_conn()
    # Execute the Snowflake query
    with conn as c:
        cursor = c.cursor()
        cursor.execute(SNOWFLAKE_QUERY, (issue.url,))
        results = cursor.fetchall()
        cursor.close()
    return results


def _build_field_name_cache(client):
    """Build the field name cache for the given JIRA client."""
    global field_name_cache
    # Reset the cache to just the standard fields
    field_name_cache = {
        f: f for f in ("priority", "assignee", "summary", "description")
    }

    # fetching the custom fields from the JIRA client
    try:
        all_fields = client.fields()
    except Exception as e:
        log.error(f"Error building field name cache: {e}")
        raise

    # updating the cache with the custom fields
    for field in all_fields:
        field_name_cache[field["name"]] = field["id"]


def _get_field_id_by_name(client, field_name):
    """
    Convert a human-readable custom field name to its JIRA field ID.

    :param jira.client.JIRA client: JIRA client
    :param str field_name: Human-readable field name (e.g., "Story Points", "Epic Link")
    :returns: Field ID (e.g., "customfield_12310243") or None if not found
    :rtype: Optional[str]
    """
    # Check cache first
    if field_ID := field_name_cache.get(field_name):
        return field_ID
    # If not in cache, build the cache
    _build_field_name_cache(client)

    return field_name_cache.get(field_name)


def _resolve_field_identifier(client, field_identifier):
    """
    Resolve a field identifier (either a name or an ID) to a field ID.
    If the identifier is already an ID (starts with 'customfield_'), return it as-is.
    Otherwise, treat it as a name and convert it to an ID.

    :param jira.client.JIRA client: JIRA client
    :param str field_identifier: Field name (e.g., "Story Points") or ID (e.g., "customfield_12310243")
    :returns: Field ID or None if not found
    :rtype: Optional[str]
    """
    # If it's already a customfield ID, return as-is
    if field_identifier.startswith("customfield_"):
        return field_identifier

    # Otherwise, treat it as a name (custom field name or standard field) and convert to ID
    return _get_field_id_by_name(client, field_identifier)


def check_jira_status(client):
    """
    Function tests the status of the JIRA server.


    :param jira.client.JIRA client: JIRA client
    :return: True/False if the server is up
    :rtype: Bool
    """
    # Search for any issue remote title
    try:
        client.server_info()
        return True
    except Exception:
        return False


def _comment_format(comment):
    """
    Function to format JIRA comments.

    :param dict comment: Upstream comment
    :returns: Comments formatted
    :rtype: String
    """
    pretty_date = comment["date_created"].strftime("%a %b %d")
    return "[%s] Upstream, %s wrote [%s]:\n\n{quote}\n%s\n{quote}" % (
        comment["id"],
        comment["author"],
        pretty_date,
        comment["body"],
    )


def _truncate_jira_text(
    body: str,
    upstream_issue_url: Optional[str] = None,
    max_chars: Optional[int] = None,
) -> str:
    """
    Ensure ``body`` fits within *max_chars* (default: comment limit).

    If truncated, a notice is prepended and a truncation marker appended.  When
    an upstream URL is available it is included — *unless* the link is so
    long that it would eat into the minimum body budget, in which case the link
    is dropped entirely.
    """
    if max_chars is None:
        max_chars = JIRA_TEXT_BODY_MAX_CHARS

    if len(body) <= max_chars:
        return body

    log.info(
        "Truncating Jira text body from %d to max %d characters",
        len(body),
        max_chars,
    )

    head = "{warning}*(Truncated.)*{warning}\n"
    tail = "\n\n{warning}*....*{warning}\n"

    link_block = ""
    if upstream_issue_url:
        link_block = f"[See More|{upstream_issue_url}]\n"

    fixed_overhead = len(head) + len(tail) + 1  # +1 for the \n before body
    link_overhead = 2 * len(link_block)
    if fixed_overhead + link_overhead + JIRA_TEXT_BODY_MIN_CHARS > max_chars:
        link_block = ""
        link_overhead = 0

    core_len = max_chars - fixed_overhead - link_overhead
    return head + link_block + "\n" + body[:core_len] + tail + link_block


def _comment_format_legacy(comment):
    """
    Legacy function to format JIRA comments.
    This is still used to match comments so no
    duplicates are created.

    :param dict comment: Upstream comment
    :returns: Comments formatted
    :rtype: String
    """
    return "Upstream, %s wrote:\n\n{quote}\n%s\n{quote}" % (
        comment["name"],
        comment["body"],
    )


def get_jira_client(issue, config, invalidate_oauth2_cache=False):
    """
    Function to match and create JIRA client.

    :param sync2jira.intermediary.Issue issue: Issue object
    :param dict config: Config dict
    :param bool invalidate_oauth2_cache: If True, clear OAuth2 token cache for this
        instance before building the client (e.g. after a JIRAError on retry).
    :returns: Matching JIRA client
    :rtype: jira.client.JIRA
    """
    # The name of the jira instance to use is stored under the 'map'
    # key in the config where each upstream is mapped to jira projects.
    # It is conveniently added to the Issue object from intermediary.py
    # so we can use it here:

    if not isinstance(issue, Issue) and not isinstance(issue, PR):
        log.error("passed in issue is not an Issue instance")
        log.error("It is a %s", type(issue).__name__)
        raise TypeError(f"Got {type(issue).__name__}, expected Issue")

    # Use the Jira instance set in the issue config. If none then
    # use the configured default jira instance.
    jira_instance = issue.downstream.get(
        "jira_instance", config["sync2jira"].get("default_jira_instance")
    )
    if not jira_instance:
        log.error("No jira_instance for issue and there is no default in the config")
        raise Exception("No configured jira_instance for issue")

    jira_instance_config = config["sync2jira"]["jira"][jira_instance]
    if invalidate_oauth2_cache:
        invalidate_oauth2_cache_for_config(jira_instance_config)
    client_kwargs = build_jira_client_kwargs(jira_instance_config)
    client = jira.client.JIRA(**client_kwargs)
    client.server_info()  # This raises an exception if authentication was not successful
    return client


def get_existing_jira_issue(client, issue, config):
    """
    Get a jira issue by the linked remote issue.

    :param jira.client.JIRA client: JIRA client
    :param sync2jira.intermediary.Issue issue: Issue object
    :param Dict config: Config dict
    :returns: Returns a list of matching JIRA issues if any are found
    :rtype: JIssue or None
    """

    issue_keys = _get_existing_jira_issue_keys(issue)
    if not issue_keys:
        return None
    jql = f"key in ({','.join(issue_keys)})"
    results: ResultList[JIssue] = client.search_issues(jql)
    if not results:
        # JQL/search index can lag right after create, or hide archived issues.
        # Resolve by issue key (direct GET) before giving up and duplicating.
        for key in issue_keys:
            try:
                found = client.issue(key)
            except JIRAError:
                continue
            log.info(
                "JQL missed key %s for upstream %s; using direct issue fetch.",
                key,
                issue.url,
            )
            results = ResultList[JIssue]((found,))
            break
        else:
            log.warning(
                "Downstream issue not found for upstream %s after JQL %r and direct fetch for keys %s.",
                issue.url,
                jql,
                issue_keys,
            )
            return None

    # If there is more than one issue, remove duplicates and filter the list
    # down to one.
    if len(results) > 1:
        results = _filter_downstream_issues(results, issue, client, config)

        # If there is more than one result, select only the most-recently updated one.
        if len(results) > 1:
            log.debug(
                "Found %i results for query with issue %r",
                len(results),
                issue.url,
            )
            results.sort(
                key=lambda x: datetime.strptime(
                    x.fields.updated, "%Y-%m-%dT%H:%M:%S.%f+0000"
                ),
                reverse=True,  # Biggest (most recent) first
            )
            results = ResultList[JIssue]((results[0],))  # A list of one item

    # Cache the result for next time and return it.
    jira_cache[issue.url] = results[0].key
    return results[0]


def _get_existing_jira_issue_keys(issue: Issue) -> tuple[str, ...]:
    """
    Retrieve downstream Jira issue keys corresponding to a given upstream issue.

    The function first checks the local cache; if no cached result is found,
    it queries Snowflake. Returns empty tuple if no matches are found.

    :param sync2jira.intermediary.Issue issue: Issue object
    :returns: A tuple of Jira issue keys, empty if no matches are found
    :rtype: Tuple[str, ...]
    """
    if result := jira_cache.get(issue.url):
        issue_keys = (result,)
    else:
        results = execute_snowflake_query(issue)
        if not results:
            return ()
        issue_keys = tuple(row[0] for row in results)

    return issue_keys


def _filter_downstream_issues(
    results: ResultList[JIssue],
    issue: Issue,
    client: jira.client.JIRA,
    config,
) -> ResultList[JIssue]:
    """
    Remove duplicates; if the result would be an empty list, the original list
    is returned.

    :param ResultList[JIssue] results: Query results list
    :param sync2jira.intermediary.Issue issue: Target Issue object
    :param jira.client.JIRA client: JIRA client
    :param Dict config: Config dict
    :returns: a filtered list of matching JIRA issues or the original input
    :rtype: ResultList[JIssue]
    """
    filtered_results = ResultList[JIssue]()

    # TODO: there is pagure-specific code in here that handles the case where a
    #       dropped issue's URL is re-used by an issue opened later.
    #       I.e. pagure re-uses IDs.
    for result in results:
        description = result.fields.description or ""
        summary = result.fields.summary or ""
        if (
            issue.id in description
            or issue.title == summary
            or re.search(
                r"\[[a-zA-Z0-9!@#$%^&*()_+\-=\[\]{};':\\|,.<>/?]*] "
                + issue.upstream_title,
                summary,
            )
        ):
            username = find_username(issue, config)
            search = check_comments_for_duplicate(client, result, username)
            filtered_results.append(search if search else result)

    return filtered_results if filtered_results else results


def find_username(_issue, config):
    """
    Finds JIRA username for an issue object.

    :param sync2jira.intermediary.Issue _issue: Issue object (not used)
    :param Dict config: Config dict
    :returns: Username string
    :rtype: String
    """
    return config["sync2jira"]["jira_username"]


def _jira_user_display_label(user) -> Optional[str]:
    """Best-effort display string for a Jira User (Cloud: displayName, else name)."""
    if not user:
        return None
    return getattr(user, "displayName", None) or getattr(user, "name", None)


def check_comments_for_duplicate(client, result, username):
    """
    Checks comment of JIRA issue to see if it has been
    marked as a duplicate.

    :param jira.client.JIRA client: JIRA client
    :param jira.resource.Issue result: JIRA issue
    :param string username: Username of JIRA user
    :returns: duplicate JIRA issue or None
    :rtype: jira.resource.Issue or None
    """
    for comment in client.comments(result):
        search = re.search(r"Marking as duplicate of (\w*)-(\d*)", comment.body)
        author_label = _jira_user_display_label(comment.author)
        if search and author_label == username:
            issue_id = search.groups()[0] + "-" + search.groups()[1]
            return client.issue(issue_id)
    return None


def _find_comment_in_jira(comment, j_comments, issue_url: Optional[str] = None):
    """
    Helper function to filter out comments that are matching.

    :param Dict comment: Individual comment from upstream
    :param List j_comments: Comments from JIRA downstream
    :param Optional[str] upstream_issue_url: Upstream issue URL for truncation notices
    :returns: Item/None
    :rtype: jira.resource.Comment/None
    """
    if comment["date_created"] < UPDATE_DATE:
        # If the comment date is prior to the update_date, we should not try to
        # touch the comment; return the item as is.
        return comment

    formatted_comment = _truncate_jira_text(_comment_format(comment), issue_url)
    legacy_formatted_comment = _comment_format_legacy(comment)
    for item in j_comments:
        if item.raw["body"] == legacy_formatted_comment:
            # If the comment is in the legacy comment format,
            # return the item
            return item
        if str(comment["id"]) in item.raw["body"]:
            # The comment id's match, if they don't have the same body,
            # we need to edit the comment
            if item.raw["body"] != formatted_comment:
                # We need to update the comment
                item.update(body=formatted_comment)
                log.info("Updated one comment")
                # Now we can just return the item
            return item
    return None


def _comment_matching(g_comments, j_comments, upstream_issue_url: Optional[str] = None):
    """
    Function to filter out comments that are matching.

    :param List g_comments: Comments from Issue object
    :param List j_comments: Comments from JIRA downstream
    :param Optional[str] upstream_issue_url: Upstream issue URL (for Jira truncation)
    :returns: Returns a list of comments that are not matching
    :rtype: List
    """
    return list(
        filter(
            lambda x: _find_comment_in_jira(x, j_comments, upstream_issue_url) is None
            or x["changed"] is not None,
            g_comments,
        )
    )


def _get_existing_jira_issue_legacy(client, issue):
    """
    This is our old way of matching issues: use the special url field.
    This will be phased out and removed in a future release.
    """

    kwargs = dict(issue.downstream.items())
    kwargs["External issue URL"] = str(issue.url)
    kwargs = sorted(kwargs.items(), key=operator.itemgetter(0))

    query = (
        " AND ".join(f"'{k}'='{v}'" for k, v in kwargs if v is not None)
        + " AND (resolution is null OR resolution = Duplicate)"
    )
    results = client.search_issues(query)
    if results:
        return results[0]
    else:
        return None


def attach_link(client, downstream, remote_link):
    """
    Attaches the upstream link to the JIRA ticket.

    :param jira.client.JIRA client: JIRA client
    :param jira.resources.Issue downstream: Response from creating the JIRA ticket
    :param dict remote_link: Remote link dict with {'url': ..., 'title': ... }
    :return: downstream: Response from creating the JIRA ticket
    :rtype: jira.resources.Issue
    """
    log.info("Attaching tracking link %r to %r", remote_link, downstream.key)

    # This is crazy.  Querying for application links requires admin perms which
    # we don't have, so duck-punch the client to think it has already made the
    # query.
    client._applicationlinks = []  # pylint: disable=protected-access

    # Add the link.
    client.add_remote_link(downstream.id, remote_link)

    # Finally, after we've added the link, we have to edit the issue so that it
    # gets re-indexed; otherwise our searches won't work.  Also, handle some
    # weird API changes here...
    log.debug("Modifying desc of %r to trigger re-index.", downstream.key)
    modified_desc = (downstream.fields.description or "") + " "
    downstream.update({"description": modified_desc})

    return downstream


def _upgrade_jira_issue(client, downstream, issue, config):
    """
    Given an old legacy-style downstream issue, upgrade it to a new-style issue
    by marking it with an external-url field value.
    """
    log.info("Upgrading %r %r issue for %r", downstream.key, issue.downstream, issue)
    if config["sync2jira"]["testing"]:
        log.info("Testing flag is true.  Skipping actual upgrade.")
        return

    # Do it!
    remote_link = dict(url=issue.url, title=remote_link_title)
    attach_link(client, downstream, remote_link)


def match_user(emails: list[str], client: jira.client.JIRA) -> Optional[Dict[str, str]]:
    """Match an upstream user to an assignable downstream Jira user.

    Returns a dict with ``name`` (display name) and ``accountId`` for Jira Cloud,
    or None on failure.
    """

    for email in emails:
        # Get a list from Jira of users that match the supplied email address.
        # Use query= for Jira Cloud (GDPR strict mode rejects the username param).
        users = client.search_users(query=email)

        if not users:
            continue

        if len(users) == 1:
            u = users[0]
            return {
                "name": getattr(u, "displayName", None) or "<name-not-available>",
                "accountId": getattr(u, "accountId", None),
            }

        limit = 5
        log.warning(
            "Found %d Jira users for %r:  %s%s",
            len(users),
            email,
            ", ".join(
                getattr(u, "displayName", "<name-not-available>")
                for u in users[0:limit]
            ),
            "..." if len(users) > limit else "",
        )
        for user in users:
            # Filter by email when present (can be omitted in Cloud when hidden).
            if getattr(user, "emailAddress", None) == email:
                name = getattr(user, "displayName", None) or "<no-name-available>"
                aid = getattr(user, "accountId", None)
                log.info("Found matching user: %r", name)
                return {"name": name, "accountId": aid}
        else:
            log.warning("Found no Jira user which matches %r", email)

    return None


def assign_user(
    client: jira.client.JIRA, issue: Issue, downstream: JIssue, remove_all=False
):
    """
    Attempts to assign a JIRA issue to the correct
    user based on the issue.

    :param jira.client.JIRA client: JIRA Client
    :param sync2jira.intermediary.Issue issue: Issue object
    :param jira.resources.Issue downstream: JIRA issue object
    :param Bool remove_all: Flag to indicate if we should reset the assignees in the JIRA issue
    :returns: Nothing
    """
    # If removeAll flag, then we need to reset the assignees
    if remove_all:
        # Update the issue to have no assignees
        downstream.update(assignee={"name": ""})
        log.info("Cleared assignment of %s.", downstream.key)
        return

    # JIRA only supports one assignee; if we have more than one (i.e., from
    # GitHub), assign the issue to the first user (i.e., issue.assignee[0])
    # whose name is present and matches an acceptable Jira user.

    # See if any of the upstream assignees has a downstream email address.
    for assignee in issue.assignee:
        emails = Rover_Lookup.github_username_to_emails(
            assignee["login"],
            ldap_server=os.getenv("LDAP_SERVER"),
            ldap_base_dn=os.getenv("LDAP_BASE_DN"),
            ldap_bind_dn=os.getenv("LDAP_BIND_DN"),
            ldap_password=os.getenv("LDAP_PASSWORD"),
        )
        if not emails:
            continue

        # Try to match the upstream assignee's emails to a Jira user
        matched = match_user(emails, client)
        if matched and matched["accountId"]:
            # Jira Cloud assigns by accountId
            downstream.update({"assignee": {"accountId": matched["accountId"]}})
            log.info(
                "Assigned %s to %r,%r",
                downstream.key,
                matched["name"],
                matched["accountId"],
            )
            return

    if issue.assignee:
        log.warning(
            "Unable to assign %s from upstream assignees %s in %s",
            downstream.key,
            str([a.get("fullname", a.get("login", "<name>")) for a in issue.assignee]),
            issue.url,
        )

    # No downstream match for the upstream assignee; if there is a configured
    # owner for the project, assign it to them.
    owner = issue.downstream.get("owner")
    if owner:
        client.assign_issue(downstream.id, owner)
        log.info("Assigned %s to owner: %s", downstream.key, owner)
        return


def change_status(client, downstream, status, issue: Union[Issue, PR]):
    """
    Change the status of JIRA issue.


    :param jira.client.JIRA client: JIRA client
    :param jira.resources.Issue/PR downstream: JIRA issue or PR object
    :param String status: Title of status to which issue should be move
    :param sync2jira.intermediary.Issue issue: Issue object
    """
    transitions = client.transitions(downstream)
    tid = ""
    for t in transitions:
        if t["name"] and status.upper() == str(t["name"]).upper():
            tid = int(t["id"])
            break
    if tid:
        try:
            client.transition_issue(downstream, tid)
            log.info(
                "Updated %s to %s status for issue %s",
                downstream.key,
                status,
                issue.url,
            )
        except JIRAError as exc:
            log.error(
                "Updating %s to %s status for issue %s failed: %s",
                downstream.key,
                status,
                issue.url,
                exc,
            )
    else:
        log.warning(
            "Could not update %s to %s status for issue %s",
            downstream.key,
            status,
            issue.url,
        )


def _get_preferred_issue_types(config, issue):
    """
    Determine the appropriate issue type to specify when creating the
    downstream (Jira) issue.  In order of preference:
     - the issue type(s) from the mapping in the configuration file (if
        present), selected based on the upstream "tags" (labels)
     - the default issue type configured for the project (if any)
     - the upstream issue type (if any)
     - "Story" if the issue title contains "RFE"
     - otherwise, "Bug".

    In all cases, a list of one item is returned, except when the upstream
    issue has multiple tags which match multiple entries in the configured
    mapping, in which case multiple entries are returned, sorted in ascending
    lexicographical order.

    :param Dict config: Config dict
    :param sync2jira.intermediary.Issue issue: Issue object
    :returns: A list of issue types in order of preference
    :rtype: List
    """
    # History:
    # https://github.com/release-engineering/Sync2Jira/issues/147
    # Configuration artifact:
    #   'issue_types': {
    #     'bug': 'Bug',
    #     'enhancement': 'Story'
    #   }
    cmap = config["sync2jira"].get("map", {})
    conf = cmap.get("github", {}).get(issue.upstream, {})

    if issue_types := conf.get("issue_types"):
        type_list = [v for k, v in issue_types.items() if k in issue.tags]
        if type_list:
            type_list.sort()
            return type_list

    if issue_type := conf.get("type"):
        return [issue_type]

    if issue.issue_type:
        return [issue.issue_type]

    if "RFE" in issue.title:
        return ["Story"]

    return ["Bug"]


def _create_jira_issue(client, issue, config):
    """
    Create a JIRA issue and adds all relevant
    information in the issue to the JIRA issue.

    :param jira.client.JIRA client: JIRA client
    :param sync2jira.intermediary.Issue issue: Issue object
    :param Dict config: Config dict
    :returns: Returns JIRA issue that was created
    :rtype: jira.resources.Issue
    """
    custom_fields = issue.downstream.get("custom_fields", {})
    preferred_types = _get_preferred_issue_types(config, issue)
    description = _build_description(issue)

    kwargs = dict(
        summary=issue.title,
        description=description,
        issuetype=dict(name=preferred_types[0]),
    )
    if issue.downstream["project"]:
        kwargs["project"] = dict(key=issue.downstream["project"])
    if issue.downstream.get("component"):
        # TODO - make this a list in the config
        kwargs["components"] = [dict(name=issue.downstream["component"])]

    for key, custom_field in custom_fields.items():
        # If key is a field name, resolve it to an ID
        field_id = _resolve_field_identifier(client, key)
        if not field_id:
            raise ValueError(
                f"Could not resolve custom field '{key}' to an ID, skipping"
            )
        if type(custom_field) is str:
            kwargs[field_id] = custom_field.replace("[remote-link]", issue.url)
        else:
            kwargs[field_id] = custom_field

    # Add labels if needed
    if "labels" in issue.downstream.keys():
        kwargs["labels"] = issue.downstream["labels"]

    log.info("Creating issue for %r:  %r", issue, kwargs)
    if config["sync2jira"]["testing"]:
        log.info("Testing flag is true.  Skipping actual creation.")
        return None

    downstream = client.create_issue(**kwargs)
    jira_cache[issue.url] = downstream.key

    # Add values to the Epic link, QA, and EXD-Service fields if present
    if (
        issue.downstream.get("epic-link")
        or issue.downstream.get("qa-contact")
        or issue.downstream.get("EXD-Service")
    ):
        if issue.downstream.get("epic-link"):
            # Try to get and update the custom field

            custom_field: Optional[str] = _get_field_id_by_name(client, "Epic Link")
            if custom_field:
                try:
                    downstream.update({custom_field: issue.downstream["epic-link"]})
                except JIRAError:
                    client.add_comment(
                        downstream,
                        f"Error adding Epic-Link: {issue.downstream['epic-link']}",
                    )
            else:
                log.warning("Could not resolve 'Epic Link' field name to ID")
        if issue.downstream.get("qa-contact"):
            # Try to get and update the custom field
            custom_field = _get_field_id_by_name(client, "QA Contact")
            if custom_field:
                downstream.update({custom_field: issue.downstream["qa-contact"]})
            else:
                log.warning("Could not resolve 'QA Contact' field name to ID")
        if issue.downstream.get("EXD-Service"):
            # Try to update the custom field
            exd_service_info = issue.downstream["EXD-Service"]
            custom_field = _get_field_id_by_name(client, "EXD-Service")
            if custom_field:
                try:
                    downstream.update(
                        {
                            custom_field: {
                                "value": f"{exd_service_info['guild']}",
                                "child": {"value": f"{exd_service_info['value']}"},
                            }
                        }
                    )
                except JIRAError:
                    client.add_comment(
                        downstream,
                        f"Error adding EXD-Service field.\n"
                        f"Project: {exd_service_info['guild']}\n"
                        f"Value: {exd_service_info['value']}",
                    )
            else:
                log.warning("Could not resolve 'EXD-Service' field name to ID")
    # Add upstream issue ID in comment if required
    if "upstream_id" in issue.downstream.get("issue_updates", []):
        comment = (
            f"Creating issue for "
            f"[{issue.upstream}-#{issue.upstream_id}|{issue.url}]"
        )
        client.add_comment(downstream, comment)
    if len(preferred_types) > 1:
        comment = "Some labels look like issue types but were not considered:  "
        comment += str(preferred_types[1:])
        client.add_comment(downstream, comment)

    remote_link = dict(url=issue.url, title=remote_link_title)
    attach_link(client, downstream, remote_link)

    default_status = issue.downstream.get("default_status")
    if default_status is not None:
        change_status(client, downstream, default_status, issue)

    # Update relevant information (i.e., tags, assignees, etc.) if the User
    # opted in
    _update_jira_issue(downstream, issue, client, config)

    return downstream


def _label_matching(jira_labels, issue_labels):
    """
    Filters through jira_labels to ensure no duplicate labels are present and
    no jira_labels are removed.

    :param List jira_labels: Existing JIRA labels
    :param List issue_labels: Upstream labels
    :returns: Updated filtered labels
    :rtype: List
    """
    # We want to get the union of the jira_labels and the issue_labels --
    # i.e., all the labels in jira_labels without duplicates from issue_labels
    updated_labels = list(set(jira_labels).union(set(issue_labels)))
    # Return our labels
    return updated_labels


def _update_jira_issue(existing, issue, client, config):
    """
    Updates an existing JIRA issue (i.e., tags, assignee, comments, etc.).

    :param jira.resources.Issue existing: Existing JIRA issue that was found
    :param sync2jira.intermediary.Issue issue: Upstream issue we're pulling data from
    :param jira.client.JIRA client: JIRA Client
    :returns: Nothing
    """
    # Start with comments
    # Only synchronize comments for listings that op-in
    log.info("Updating information for upstream issue: %s", issue.url)

    # Get a list of what the user wants to update for the upstream issue
    updates = issue.downstream.get("issue_updates", [])

    # Update relevant data if needed.
    # If the user has specified nothing, just return.
    if not updates:
        return

    # Get fields representing project item fields in GitHub and Jira
    github_project_fields = issue.downstream.get("github_project_fields", {})
    # Only synchronize comments for listings that op-in
    if "github_project_fields" in updates and github_project_fields:
        log.info("Looking for GitHub project fields")
        _update_github_project_fields(
            client, existing, issue, github_project_fields, config
        )

    # Only synchronize comments for listings that op-in
    if "comments" in updates:
        log.info("Looking for new comments")
        _update_comments(client, existing, issue)

    # Only synchronize tags for listings that op-in
    if any("tags" in item for item in updates):
        log.info("Looking for new tags")
        _update_tags(updates, existing, issue)

    # Only synchronize fixVersion for listings that op-in
    if issue.fixVersion and any("fixVersion" in item for item in updates):
        log.info("Looking for new fixVersions")
        _update_fixVersion(updates, existing, issue, client)

    # Only synchronize assignee for listings that op-in
    for item in updates:
        if isinstance(item, dict):
            if assignee := item.get("assignee"):
                log.info("Looking for new assignee(s)")
                _update_assignee(
                    client, existing, issue, assignee.get("overwrite", False)
                )
                break

    # Only synchronize descriptions for listings that op-in
    if "description" in updates:
        log.info("Looking for new description")
        _update_description(existing, issue)

    # Only synchronize title for listings that op-in
    if "title" in updates:
        # Update the title if needed
        if issue.title != existing.fields.summary:
            log.info("Looking for new title")
            _update_title(issue, existing)

    # Only synchronize transition (status) for listings that op-in
    if any("transition" in item for item in updates):
        log.info("Looking for new transition(s)")
        _update_transition(client, existing, issue)

    # Only execute 'on_close' events for listings that opt-in
    # and when the issue is closed.
    if issue.status == "Closed":
        log.info("Attempting to update downstream issue on upstream closed event")
        _update_on_close(existing, updates)

    log.info("Done updating %s!", issue.url)


def _update_transition(client, existing, issue):
    """
    Helper function to update the transition of a downstream JIRA issue.

    Supports an optional ``issue_types`` filter on transition entries in
    ``issue_updates``.  When present, the transition only fires if the
    downstream JIRA issue's type is in the list.

    :param jira.client.JIRA client: JIRA client
    :param jira.resource.Issue existing: Existing JIRA issue
    :param sync2jira.intermediary.Issue issue: Upstream issue
    :returns: Nothing
    """
    for entry in issue.downstream.get("issue_updates", []):
        if not isinstance(entry, dict) or "transition" not in entry:
            continue

        closed_status = entry["transition"]

        # Normalize legacy True value to "Closed"
        if closed_status is True:
            closed_status = "Closed"
        if not isinstance(closed_status, str):
            log.warning(
                "Ignoring malformed transition value %r (expected a string) in "
                "issue_updates config for %s",
                closed_status,
                existing.key,
            )
            continue

        type_filters = entry.get("issue_types")
        if type_filters is not None:
            jira_type = existing.fields.issuetype.name
            if jira_type not in type_filters:
                log.info(
                    "Skipping issue transition '%s': issue type '%s' not in %s",
                    closed_status,
                    jira_type,
                    type_filters,
                )
                continue

        if (
            issue.status == "Closed"
            and existing.fields.status.name.upper() != closed_status.upper()
        ):
            hyperlink = f"[Upstream issue|{issue.url}]"
            comment_body = (
                f"{hyperlink} closed. Attempting transition to {closed_status}."
            )
            client.add_comment(existing, comment_body)
            change_status(client, existing, closed_status, issue)
            return


def _update_title(issue, existing):
    """
    Helper function to sync upstream/downstream title.

    :param sync2jira.intermediary.Issue issue: Upstream issue
    :param jira.resource.Issue existing: Existing JIRA issue
    :returns: Nothing
    """
    # Then we can update the title
    data = {"summary": issue.title}
    existing.update(data)
    log.info("Updated title")


def _update_comments(client, existing, issue):
    """
    Helper function to sync comments between existing JIRA issue and upstream issue.

    :param jira.client.JIRA client: JIRA client
    :param jira.resource.Issue existing: Existing JIRA issue
    :param sync2jira.intermediary.Issue issue: Upstream issue
    :returns: Nothing
    """
    # Get all existing comments
    comments = client.comments(existing)
    # Remove any comments that have already been added
    comments_d = _comment_matching(issue.comments, comments, issue.url)
    # Loop through the comments that remain
    for comment in comments_d:
        # Format and add them
        comment_body = _truncate_jira_text(_comment_format(comment), issue.url)
        client.add_comment(existing, comment_body)
    if len(comments_d) > 0:
        log.info("Comments synchronization done on %i comments.", len(comments_d))


def _update_fixVersion(updates, existing, issue, client):
    """
    Helper function to sync comments between existing JIRA issue and upstream issue.

    :param List updates: Downstream updates requested by the user
    :param jira.resource.Issue existing: Existing JIRA issue
    :param sync2jira.intermediary.Issue issue: Upstream issue
    :param jira.client.JIRA client: JIRA client
    :returns: Nothing
    """
    fix_version = []
    # If we are not supposed to overwrite JIRA content
    fv = filter(lambda d: "fixVersion" in d, updates)
    if not bool(next(fv)["fixVersion"]["overwrite"]):
        # We need to make sure we're not deleting any fixVersions on JIRA
        # Get all fixVersions for the issue
        for version in existing.fields.fixVersions:
            fix_version.append({"name": version.name})

    # GitHub does not allow for multiple fixVersions (milestones),
    # but JIRA does, which is why we're looping here. Hopefully, one
    # day GitHub will support multiple fixVersions.
    for version in issue.fixVersion:
        if version is not None:
            # Update the fixVersion only if it's already not in JIRA
            result = filter(lambda v: v["name"] == str(version), fix_version)
            # If we have a result, skip; if not, then add it to fix_version
            if not result or not list(result):
                fix_version.append({"name": version})

    # We don't want to make an API call if the labels are the same
    jira_labels = []
    for label in existing.fields.fixVersions:
        jira_labels.append({"name": label.name})
    res = [i for i in jira_labels if i not in fix_version] + [
        j for j in fix_version if j not in jira_labels
    ]
    if res:
        data = {"fixVersions": fix_version}
        # If the fixVersion is not in JIRA, it will throw an error
        try:
            existing.update(data)
            log.info("Updated %s fixVersion(s)", len(fix_version))
        except JIRAError:
            log.warning(
                "Error updating the fixVersion. %s is an invalid fixVersion.",
                issue.fixVersion,
            )
            # Add a comment to indicate there was an issue
            client.add_comment(
                existing, f"Error updating fixVersion: {issue.fixVersion}"
            )


def _update_assignee(client, existing, issue, overwrite):
    """
    Helper function which updates an existing JIRA assignee from the upstream issue.

    :param jira.client.JIRA client: JIRA client
    :param jira.resource.Issue existing: Existing JIRA issue
    :param sync2jira.intermediary.Issue issue: Upstream issue
    :param bool overwrite: Overwrite existing JIRA assignee
    :returns: Nothing
    """

    us_exists = bool(
        issue.assignee and issue.assignee[0] and issue.assignee[0].get("fullname")
    )
    assignee = existing.fields.assignee
    ds_exists = bool(assignee) and _jira_user_display_label(assignee) is not None
    if overwrite:
        if not ds_exists:
            # Let assign_user() figure out what to do.
            update = True
        elif us_exists:
            # Overwrite the downstream assignment only if it is different from
            # the upstream one.
            un = issue.assignee[0]["fullname"]
            dn = _jira_user_display_label(assignee)
            update = un != dn and remove_diacritics(un) != dn
        else:
            # Without an upstream owner, update only if the downstream is not
            # assigned to the project owner.
            update = issue.downstream.get("owner") != _jira_user_display_label(assignee)
    else:
        # We're not overwriting, so call assign_user() only if the downstream
        # doesn't already have an assignment.
        update = not ds_exists

    # De-assign the downstream issue if the upstream issue is unassigned and we
    # are overwriting.
    clear = overwrite and ds_exists and not us_exists

    if update:
        assign_user(client, issue, existing, remove_all=clear)


def _update_jira_labels(issue, labels):
    """Update a Jira issue with 'labels'

    Do this only if the current labels would change.

    :param jira.resource.Issue issue: Jira issue to be updated
    :param list<strings> labels: Labels to be applied on the issue
    :returns: None
    """
    _labels = sorted(labels)
    if _labels == sorted(issue.fields.labels):
        return

    data = {"labels": _labels}
    issue.update(data)
    log.info("Updated %s tag(s)", len(_labels))


def _update_github_project_fields(
    client, existing, issue, github_project_fields, config
):
    """Update a Jira issue with GitHub project item field values

    :param jira.client.JIRA client: JIRA client
    :param jira.resource.Issue existing: Existing JIRA issue
    :param sync2jira.intermediary.Issue issue: Upstream issue
    :param dict github_project_fields: Fields representing GitHub project item fields in GitHub and Jira
    :param dict config: configuration options
    """

    default_jira_fields = config["sync2jira"].get("default_jira_fields", {})
    for name, values in github_project_fields.items():
        if name not in dir(issue):
            log.error(
                f"Configuration error: github_project_field key, {name:r}, is not in issue object."
            )
            continue

        log.info(f"Looking at GHP field '{name}' with configuration '{values}'")
        fieldvalue = getattr(issue, name)
        log.info(f"Issue value for field '{name}' is '{fieldvalue}'")
        if name == "storypoints":
            if not isinstance(fieldvalue, int):
                if fieldvalue is not None:
                    log.info(
                        f"Story point field value '{fieldvalue}' is a {type(fieldvalue)}, not an 'int'"
                    )
                continue

            field_identifier = default_jira_fields.get("storypoints")
            if not field_identifier:
                log.warning(
                    "Configuration error: Missing 'storypoints' in `default_jira_fields`"
                )
                continue
            # Resolve the field identifier to an ID
            jirafieldname = _resolve_field_identifier(client, field_identifier)
            if not jirafieldname:
                raise ValueError(
                    f"Could not resolve custom field '{field_identifier}' to an ID, skipping"
                )

            log.debug(f"Jira issue story point field name is:  '{jirafieldname}'")
            try:
                existing.update({jirafieldname: fieldvalue})
                log.info("Jira issue story point update was successful")
            except JIRAError as err:
                # Note the failure in a comment to the downstream issue
                log.error(
                    f"Error updating Jira issue story points field ({jirafieldname}: {fieldvalue}): {err}"
                )
                client.add_comment(
                    existing,
                    "Error updating GitHub project storypoints field ({}: {}): {}".format(
                        jirafieldname, fieldvalue, err
                    ),
                )
        elif name == "priority":
            jira_priority = values.get("options", {}).get(fieldvalue)
            if not jira_priority:
                log.info(
                    f"Priority field value mapping for '{fieldvalue}' is '{jira_priority}'"
                )
                continue
            try:
                field_identifier = default_jira_fields.get("priority", "priority")
                # Resolve to field ID (convert name to ID if needed)
                jirafieldname = _resolve_field_identifier(client, field_identifier)
                if not jirafieldname:
                    log.warning(
                        f"Could not resolve field identifier '{field_identifier}' for priority, using 'priority'"
                    )
                    jirafieldname = "priority"
                log.info(
                    f"Configured Jira issue priority field name is:  '{jirafieldname}'"
                )
            except KeyError:
                jirafieldname = "priority"
                log.info(
                    f"Default Jira issue priority field name is:  '{jirafieldname}'"
                )
            try:
                existing.update({jirafieldname: {"name": jira_priority}})
                log.info("Jira issue priority update was successful")
            except JIRAError as err:
                # Note the failure in a comment to the downstream issue
                log.error(
                    f"Error updating Jira issue priority field ({jirafieldname}: {jira_priority}): {err}"
                )
                client.add_comment(
                    existing,
                    "Error updating GitHub project priority field ({}: {}): {}".format(
                        jirafieldname, jira_priority, err
                    ),
                )


def _update_tags(updates, existing, issue):
    """
    Helper function to sync tags between upstream issue and downstream JIRA issue.

    :param List updates: Downstream updates requested by the user
    :param jira.resource.Issue existing: Existing JIRA issue
    :param sync2jira.intermediary.Issue issue: Upstream issue
    :returns: Nothing
    """
    # Get all existing tags on the issue
    updated_labels = issue.tags

    # Ensure no duplicates if overwrite is set to false
    if not bool(next(filter(lambda d: "tags" in d, updates))["tags"]["overwrite"]):
        updated_labels = _label_matching(updated_labels, existing.fields.labels)

    # Ensure that the tags are all valid
    updated_labels = verify_tags(updated_labels)

    # Now we can update the JIRA if labels are different
    _update_jira_labels(existing, updated_labels)


def _build_description(issue):
    # Build the description of the JIRA issue.
    #
    # Truncate issue.content *before* wrapping it with {quote} and the
    # metadata prefix so the closing {quote} and decoration are never lost.
    issue_updates = issue.downstream.get("issue_updates", [])

    # Build the prefix lines that will appear above the quoted content.
    prefix_parts = []
    if issue.reporter:
        prefix_parts.append(
            f"[{issue.id}] Upstream Reporter: {issue.reporter['fullname']}"
        )
    if issue.status and any("transition" in item for item in issue_updates):
        prefix_parts.append("Upstream issue status: " + issue.status)

    prefix = "\n".join(prefix_parts) + "\n" if prefix_parts else ""
    suffix = ""
    if "url" in issue_updates:
        suffix = f"\nUpstream URL: {issue.url}"
    if "description" in issue_updates:
        quote_wrapper = "Upstream description: {quote}{quote}"
        decoration_len = len(prefix) + len(quote_wrapper)
        budget = JIRA_TEXT_BODY_MAX_CHARS - decoration_len
        description = prefix
        content = issue.content or ""
        if len(content) > budget:
            upstream_url = getattr(issue, "url", None)
            content = _truncate_jira_text(content, upstream_url, max_chars=budget)
            description += f"Upstream description: {{quote}}{content}{{quote}}"
        else:
            description += f"Upstream description: {{quote}}{content}{{quote}}" + suffix
    else:
        description = prefix + suffix

    return description


def _update_description(existing, issue):
    """
    Helper function to sync description between upstream issue and downstream JIRA issue.

    :param jira.resource.Issue existing: Existing JIRA issue
    :param sync2jira.intermediary.Issue issue: Upstream issue
    :returns: Nothing
    """

    new_description = _build_description(issue)

    # Now we can update the JIRA issue if we need to
    if new_description != existing.fields.description:
        # This logging is temporary and will be used to debug an
        # issue regarding phantom updates
        # Get the diff between new_description and existing
        diff = difflib.unified_diff(existing.fields.description, new_description)
        log.debug("Issue %s", issue.title)
        log.debug("Diff: %s", "".join(diff))
        log.debug("Old: %s", existing.fields.description)
        log.debug("New: %s", new_description)

        data = {"description": new_description}
        existing.update(data)
        log.info("Updated description")


UPDATE_ENTRY = Union[str, dict[str, Union[str, dict[str, Any]]]]


def _update_on_close(existing, updates: list[UPDATE_ENTRY]):
    """Update downstream Jira issue when upstream issue was closed

    Example update configuration:
    [
        ...,
        {
            "on_close": {
                {
                    "apply_labels": [
                        "closed-upstream"
                    ]
                }
            }
        },
        ...,
    ]

    :param jira.resource.Issue existing: existing Jira issue
    :param dict updates: update configuration
    :return: None
    """
    for item in updates:
        if isinstance(item, dict):
            if new_labels := item.get("on_close", {}).get("apply_labels", []):
                break
    else:
        return

    existing_labels = set(existing.fields.labels)
    updated_labels = existing_labels.union(new_labels)
    log.info("Applying 'on_close' labels %s to downstream Jira issue", updated_labels)
    _update_jira_labels(existing, list(updated_labels))


def verify_tags(tags):
    """
    Helper function which ensures the tags are JIRA ready :).

    :param List tags: Input tags
    :returns: Updates tags
    :rtype: List
    """
    updated_tags = []
    for tag in tags:
        updated_tags.append(tag.replace(" ", "_"))
    return updated_tags


def sync_with_jira(issue, config):
    """
    Attempts to sync an upstream issue with JIRA (i.e., by finding
    an existing issue or creating a new one).

    :param sync2jira.intermediary.Issue issue: Issue object
    :param Dict config: Config dict
    :returns: Nothing
    """

    log.info('[Issue] Considering upstream %s, "%s"', issue.url, issue.title)

    # Create a client connection for this issue
    client = get_jira_client(issue, config)

    retry = False
    while True:
        try:
            update_jira(client, config, issue)
            break
        except JIRAError:
            # We got an error from Jira; if this was a re-try attempt, let the
            # exception propagate (and crash the run).
            if retry:
                log.info("[Issue] Jira retry failed; aborting")
                raise
            # The error may be due to expired/revoked auth. Ask get_jira_client to
            # invalidate OAuth2 cache so the next call fetches a new token (no-op for PAT).
            log.info("[Issue] Jira request failed; refreshing the Jira client")
            client = get_jira_client(issue, config, invalidate_oauth2_cache=True)

        # Retry the update
        retry = True


def convert_content(content: str) -> str:
    """Convert GitHub Flavored Markdown to Jira format via pypandoc.

    Falls back to disabling TeX math extensions if the initial conversion
    fails (e.g. content misinterpreted as LaTeX).  Returns the original
    content unchanged if both attempts fail.

    :param str content: GitHub Flavored Markdown text
    :returns: Jira-formatted text, or the original content on failure
    :rtype: str
    """
    try:
        content = pypandoc.convert_text(content, "jira", format="gfm")
    except Exception as e:
        log.warning("pypandoc conversion failed, retrying with TeX disabled: %s", e)
        try:
            sanitized = content.replace("\\", "\\\\").replace("$", "\\$")
            content = pypandoc.convert_text(
                sanitized,
                "jira",
                format="gfm-tex_math_dollars-tex_math_single_backslash",
            )
        except Exception as e2:
            log.warning("pypandoc fallback also failed; using raw content: %s", e2)
    return content


def update_jira(client, config, issue):
    # Check the status of the JIRA client
    if not config["sync2jira"]["develop"] and not check_jira_status(client):
        log.warning("The JIRA server looks like its down. Shutting down...")
        raise RuntimeError("Jira server status check failed; aborting...")

    if issue.downstream.get("issue_updates"):
        if (
            issue.source == "github"
            and issue.content
            and "github_markdown" in issue.downstream["issue_updates"]
        ):
            issue.content = convert_content(issue.content)

    # First, check to see if we have a matching issue using the new method.
    # If we do, then bail out.  No sync needed.
    log.info("Looking for matching downstream issue via new method.")
    existing = get_existing_jira_issue(client, issue, config)
    if existing:
        # If we found an existing JIRA issue already
        log.info("Found existing, matching downstream %r.", existing.key)
        if config["sync2jira"]["testing"]:
            log.info("Testing flag is true.  Skipping actual update.")
            return
        # Update relevant metadata (i.e. tags, assignee, etc)
        _update_jira_issue(existing, issue, client, config)
        return

    # If we're *not* configured to do legacy matching (upgrade mode), then
    # there is nothing left to do but to create the issue and return.
    if not config["sync2jira"].get("legacy_matching", True):
        log.debug("Legacy matching disabled.")
        _create_jira_issue(client, issue, config)
        return

    # Otherwise, if we *are* configured to do legacy matching, then try and
    # find this issue the old way.
    # - If we can't find it, create it.
    # - If we can find it, upgrade it to the new method.
    log.info("Looking for matching downstream issue via legacy method.")
    match = _get_existing_jira_issue_legacy(client, issue)
    if not match:
        _create_jira_issue(client, issue, config)
    else:
        _upgrade_jira_issue(client, match, issue, config)


def remove_diacritics(text):
    """Convert text from UTF-8 to its ASCII equivalent"""
    if not text:
        return ""
    normalized_text = unicodedata.normalize("NFD", text)
    return "".join(c for c in normalized_text if not unicodedata.combining(c))