sqlmirror 0.2.0__py3-none-any.whl

sqlmirror/mapper.py

@@ -0,0 +1,774 @@
+"""Convert Jira Cloud REST (v2) data into Data-Center-shaped table rows.
+
+Input formats (the contract shared by the Forge app and the CLI):
+
+Issue snapshot
+    {"v": 1, "type": "issue", "id": "10001", "fetchedAt": "...Z",
+     "issue": {...v2 issue JSON, fields included...},
+     "changelog": [...all histories...],
+     "comments":  [...all comments...],
+     "worklogs":  [...all worklogs...]}
+
+Tombstone
+    {"v": 1, "type": "deleted", "id": "10001", "deletedAt": "...Z"}
+
+Metadata
+    {"v": 1, "type": "metadata", "fetchedAt": "...Z", "projects": [...],
+     "statuses": [...], "priorities": [...], "resolutions": [...],
+     "issueTypes": [...], "fields": [...], "issueLinkTypes": [...],
+     "projectCategories": [...], "versions": {projectId: [...]},
+     "components": {projectId: [...]}}
+
+The mapper is pure: it returns rows and never touches the database.
+"""
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from typing import Any, Iterable
+
+from .util import parse_ts, stable_id, to_epoch_ms, to_float, to_int
+
+Rows = dict[str, list[dict[str, Any]]]
+
+CF_PREFIX = "customfield_"
+
+# Synthetic link types for parent/child relationships. Cloud models these as a
+# "parent" field; Data Center models them as issue links. Ids are far above the
+# range Cloud uses, so they never collide with real link types.
+SUBTASK_LINKTYPE_ID = 9_000_000_000_000_001
+EPIC_LINKTYPE_ID = 9_000_000_000_000_002
+PARENT_LINKTYPE_ID = 9_000_000_000_000_003
+SYNTHETIC_LINKTYPES = [
+    {"id": SUBTASK_LINKTYPE_ID, "linkname": "jira_subtask_link", "inward": "jira_subtask_inward",
+     "outward": "jira_subtask_outward", "pstyle": "jira_subtask"},
+    {"id": EPIC_LINKTYPE_ID, "linkname": "Epic-Story Link", "inward": "has Epic",
+     "outward": "is Epic of", "pstyle": "jira_gh_epic_story"},
+    {"id": PARENT_LINKTYPE_ID, "linkname": "Parent-Child Link", "inward": "has parent",
+     "outward": "is parent of", "pstyle": "sqlmirror_parent_child"},
+]
+SYNTHETIC_LINKTYPE_IDS = [t["id"] for t in SYNTHETIC_LINKTYPES]
+
+_SPRINT_STR = re.compile(r"(\w+)=([^,\]]*)")
+
+
+def cf_number(field_id: str) -> int | None:
+    if field_id and field_id.startswith(CF_PREFIX):
+        return to_int(field_id[len(CF_PREFIX):])
+    return None
+
+
+def adf_to_text(node: Any) -> str | None:
+    """Flatten Atlassian Document Format to plain text (used only if a v3 body sneaks in)."""
+    if node is None:
+        return None
+    if isinstance(node, str):
+        return node
+    if not isinstance(node, dict):
+        return str(node)
+    parts: list[str] = []
+
+    def walk(n: Any) -> None:
+        if isinstance(n, dict):
+            if n.get("type") == "text":
+                parts.append(n.get("text", ""))
+            elif n.get("type") == "hardBreak":
+                parts.append("\n")
+            for child in n.get("content", []) or []:
+                walk(child)
+            if n.get("type") in ("paragraph", "heading", "listItem", "codeBlock", "blockquote"):
+                parts.append("\n")
+        elif isinstance(n, list):
+            for child in n:
+                walk(child)
+
+    walk(node)
+    return "".join(parts).strip("\n")
+
+
+def _text(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, (dict, list)):
+        return adf_to_text(value)
+    return str(value)
+
+
+class RowSet:
+    """Accumulates rows per table, de-duplicating upsert rows by primary key."""
+
+    def __init__(self) -> None:
+        self.rows: dict[str, list[dict[str, Any]]] = defaultdict(list)
+        self._seen: dict[str, dict[Any, dict[str, Any]]] = defaultdict(dict)
+
+    def add(self, table: str, row: dict[str, Any]) -> None:
+        self.rows[table].append(row)
+
+    def upsert(self, table: str, key: Any, row: dict[str, Any]) -> None:
+        """Merge rows for the same key: later non-null values win."""
+        existing = self._seen[table].get(key)
+        if existing is None:
+            self._seen[table][key] = row
+            self.rows[table].append(row)
+        else:
+            for k, v in row.items():
+                if v is not None:
+                    existing[k] = v
+
+    def as_dict(self) -> Rows:
+        return dict(self.rows)
+
+
+class Mapper:
+    """Holds what we know about custom fields and turns API data into rows."""
+
+    def __init__(self) -> None:
+        # customfield number -> (type key, name)
+        self.custom_fields: dict[int, tuple[str | None, str | None]] = {}
+
+    # ------------------------------------------------------------ field registry
+    def register_fields(self, fields: Iterable[dict[str, Any]]) -> None:
+        for f in fields:
+            num = cf_number(f.get("id", ""))
+            if num is None:
+                continue
+            schema = f.get("schema") or {}
+            self.custom_fields[num] = (schema.get("custom"), f.get("name"))
+
+    def register_custom_field(self, num: int, typekey: str | None, name: str | None) -> None:
+        self.custom_fields[num] = (typekey, name)
+
+    # ------------------------------------------------------------------ users
+    @staticmethod
+    def user_key(user: Any) -> str | None:
+        if isinstance(user, dict):
+            return user.get("accountId") or user.get("key") or user.get("name")
+        if isinstance(user, str) and user:
+            return user
+        return None
+
+    def _add_user(self, rs: RowSet, user: Any) -> str | None:
+        key = self.user_key(user)
+        if not key:
+            return None
+        if not isinstance(user, dict):
+            user = {"accountId": key}
+        uid = stable_id("user", key)
+        display = user.get("displayName")
+        email = user.get("emailAddress")
+        first = last = None
+        if display:
+            bits = display.split(" ", 1)
+            first = bits[0]
+            last = bits[1] if len(bits) > 1 else None
+        active = user.get("active")
+        rs.upsert("app_user", uid, {"id": uid, "user_key": key, "lower_user_name": key.lower()})
+        rs.upsert(
+            "cwd_user",
+            uid,
+            {
+                "id": uid,
+                "directory_id": 1,
+                "user_name": key,
+                "lower_user_name": key.lower(),
+                "active": None if active is None else (1 if active else 0),
+                "created_date": None,
+                "updated_date": None,
+                "first_name": first,
+                "lower_first_name": first.lower() if first else None,
+                "last_name": last,
+                "lower_last_name": last.lower() if last else None,
+                "display_name": display,
+                "lower_display_name": display.lower() if display else None,
+                "email_address": email,
+                "lower_email_address": email.lower() if email else None,
+                "external_id": key,
+            },
+        )
+        return key
+
+    # --------------------------------------------------------- config objects
+    @staticmethod
+    def _status_row(s: dict[str, Any], seq: int | None = None) -> dict[str, Any]:
+        cat = s.get("statusCategory") or {}
+        return {
+            "id": str(s.get("id")),
+            "sequence": seq,
+            "pname": s.get("name"),
+            "description": s.get("description") or None,
+            "iconurl": s.get("iconUrl") or None,
+            "statuscategory": to_int(cat.get("id")),
+        }
+
+    @staticmethod
+    def _issuetype_row(t: dict[str, Any], seq: int | None = None) -> dict[str, Any]:
+        return {
+            "id": str(t.get("id")),
+            "sequence": seq,
+            "pname": t.get("name"),
+            "pstyle": "jira_subtask" if t.get("subtask") else None,
+            "description": t.get("description") or None,
+            "iconurl": t.get("iconUrl") or None,
+            "avatar": to_int(t.get("avatarId")),
+        }
+
+    @staticmethod
+    def _priority_row(p: dict[str, Any], seq: int | None = None) -> dict[str, Any]:
+        return {
+            "id": str(p.get("id")),
+            "sequence": seq,
+            "pname": p.get("name"),
+            "description": p.get("description") or None,
+            "iconurl": p.get("iconUrl") or None,
+            "status_color": p.get("statusColor") or None,
+        }
+
+    @staticmethod
+    def _resolution_row(r: dict[str, Any], seq: int | None = None) -> dict[str, Any]:
+        return {
+            "id": str(r.get("id")),
+            "sequence": seq,
+            "pname": r.get("name"),
+            "description": r.get("description") or None,
+            "iconurl": r.get("iconUrl") or None,
+        }
+
+    def _project_row(self, rs: RowSet, p: dict[str, Any]) -> int | None:
+        pid = to_int(p.get("id"))
+        if pid is None:
+            return None
+        lead = self._add_user(rs, p.get("lead")) if p.get("lead") else None
+        rs.upsert(
+            "project",
+            pid,
+            {
+                "id": pid,
+                "pname": p.get("name"),
+                "url": p.get("url") or None,
+                "lead": lead,
+                "description": _text(p.get("description")) or None,
+                "pkey": p.get("key"),
+                "pcounter": None,
+                "assigneetype": None,
+                "avatar": None,
+                "originalkey": p.get("key"),
+                "projecttype": p.get("projectTypeKey"),
+            },
+        )
+        if p.get("key"):
+            rs.upsert("project_key", pid, {"id": pid, "project_id": pid, "project_key": p.get("key")})
+        cat = p.get("projectCategory")
+        if isinstance(cat, dict) and cat.get("id"):
+            cid = to_int(cat.get("id"))
+            rs.upsert("projectcategory", cid, {"id": cid, "cname": cat.get("name"),
+                                               "description": cat.get("description") or None})
+            rs.add("project_category_assoc", {"project": pid, "category": cid})
+        return pid
+
+    def _version_row(self, rs: RowSet, v: dict[str, Any], project_id: int | None, seq: int | None = None) -> int | None:
+        vid = to_int(v.get("id"))
+        if vid is None:
+            return None
+        rs.upsert(
+            "projectversion",
+            vid,
+            {
+                "id": vid,
+                "project": to_int(v.get("projectId")) or project_id,
+                "vname": v.get("name"),
+                "description": v.get("description") or None,
+                "sequence": seq,
+                "released": "true" if v.get("released") else None,
+                "archived": "true" if v.get("archived") else None,
+                "url": None,
+                "startdate": parse_ts(v.get("startDate")),
+                "releasedate": parse_ts(v.get("releaseDate")),
+            },
+        )
+        return vid
+
+    def _component_row(self, rs: RowSet, c: dict[str, Any], project_id: int | None) -> int | None:
+        cid = to_int(c.get("id"))
+        if cid is None:
+            return None
+        lead = self._add_user(rs, c.get("lead")) if c.get("lead") else None
+        rs.upsert(
+            "component",
+            cid,
+            {
+                "id": cid,
+                "project": to_int(c.get("projectId")) or project_id,
+                "cname": c.get("name"),
+                "description": c.get("description") or None,
+                "url": None,
+                "lead": lead,
+                "assigneetype": None,
+                "archived": "Y" if c.get("archived") else "N",
+                "deleted": "N",
+            },
+        )
+        return cid
+
+    def _linktype_row(self, rs: RowSet, t: dict[str, Any]) -> int | None:
+        tid = to_int(t.get("id"))
+        if tid is None:
+            return None
+        rs.upsert("issuelinktype", tid, {"id": tid, "linkname": t.get("name"), "inward": t.get("inward"),
+                                         "outward": t.get("outward"), "pstyle": None})
+        return tid
+
+    # ------------------------------------------------------------- metadata
+    def map_metadata(self, meta: dict[str, Any]) -> Rows:
+        rs = RowSet()
+        self.register_fields(meta.get("fields") or [])
+
+        for cat in meta.get("projectCategories") or []:
+            cid = to_int(cat.get("id"))
+            if cid is not None:
+                rs.upsert("projectcategory", cid, {"id": cid, "cname": cat.get("name"),
+                                                   "description": cat.get("description") or None})
+        for p in meta.get("projects") or []:
+            self._project_row(rs, p)
+        for i, s in enumerate(meta.get("statuses") or []):
+            rs.upsert("issuestatus", str(s.get("id")), self._status_row(s, i + 1))
+        for i, t in enumerate(meta.get("issueTypes") or []):
+            rs.upsert("issuetype", str(t.get("id")), self._issuetype_row(t, i + 1))
+        for i, p in enumerate(meta.get("priorities") or []):
+            rs.upsert("priority", str(p.get("id")), self._priority_row(p, i + 1))
+        for i, r in enumerate(meta.get("resolutions") or []):
+            rs.upsert("resolution", str(r.get("id")), self._resolution_row(r, i + 1))
+        for t in meta.get("issueLinkTypes") or []:
+            self._linktype_row(rs, t)
+        for t in SYNTHETIC_LINKTYPES:
+            rs.upsert("issuelinktype", t["id"], dict(t))
+        for pid, versions in (meta.get("versions") or {}).items():
+            for i, v in enumerate(versions or []):
+                self._version_row(rs, v, to_int(pid), i + 1)
+        for pid, comps in (meta.get("components") or {}).items():
+            for c in comps or []:
+                self._component_row(rs, c, to_int(pid))
+        for f in meta.get("fields") or []:
+            num = cf_number(f.get("id", ""))
+            if num is None:
+                continue
+            schema = f.get("schema") or {}
+            rs.upsert(
+                "customfield",
+                num,
+                {
+                    "id": num,
+                    "cfkey": f.get("id"),
+                    "customfieldtypekey": schema.get("custom"),
+                    "customfieldsearcherkey": None,
+                    "cfname": f.get("name"),
+                    "description": f.get("description") or None,
+                    "defaultvalue": None,
+                    "fieldtype": None,
+                    "project": None,
+                    "issuetype": None,
+                },
+            )
+        return rs.as_dict()
+
+    # ---------------------------------------------------------------- issues
+    def map_issue(self, snap: dict[str, Any]) -> Rows:
+        rs = RowSet()
+        issue = snap.get("issue") or {}
+        f = issue.get("fields") or {}
+        iid = to_int(issue.get("id") or snap.get("id"))
+        if iid is None:
+            return rs.as_dict()
+
+        key = issue.get("key")
+        issuenum = to_int(key.rsplit("-", 1)[1]) if key and "-" in key else None
+
+        project = f.get("project") or {}
+        project_id = self._project_row(rs, project) if project else None
+
+        status = f.get("status") or {}
+        if status.get("id") is not None:
+            rs.upsert("issuestatus", str(status["id"]), self._status_row(status))
+        itype = f.get("issuetype") or {}
+        if itype.get("id") is not None:
+            rs.upsert("issuetype", str(itype["id"]), self._issuetype_row(itype))
+        prio = f.get("priority") or {}
+        if prio.get("id") is not None:
+            rs.upsert("priority", str(prio["id"]), self._priority_row(prio))
+        res = f.get("resolution") or {}
+        if res.get("id") is not None:
+            rs.upsert("resolution", str(res["id"]), self._resolution_row(res))
+
+        reporter = self._add_user(rs, f.get("reporter"))
+        assignee = self._add_user(rs, f.get("assignee"))
+        creator = self._add_user(rs, f.get("creator"))
+
+        votes = f.get("votes") or {}
+        watches = f.get("watches") or {}
+        security = f.get("security") or {}
+        rs.add(
+            "jiraissue",
+            {
+                "id": iid,
+                "pkey": key,
+                "issuenum": issuenum,
+                "project": project_id,
+                "reporter": reporter,
+                "assignee": assignee,
+                "creator": creator,
+                "issuetype": str(itype["id"]) if itype.get("id") is not None else None,
+                "summary": f.get("summary"),
+                "description": _text(f.get("description")),
+                "environment": _text(f.get("environment")),
+                "priority": str(prio["id"]) if prio.get("id") is not None else None,
+                "resolution": str(res["id"]) if res.get("id") is not None else None,
+                "issuestatus": str(status["id"]) if status.get("id") is not None else None,
+                "created": parse_ts(f.get("created")),
+                "updated": parse_ts(f.get("updated")),
+                "duedate": parse_ts(f.get("duedate")),
+                "resolutiondate": parse_ts(f.get("resolutiondate")),
+                "votes": to_int(votes.get("votes")) if isinstance(votes, dict) else None,
+                "watches": to_int(watches.get("watchCount")) if isinstance(watches, dict) else None,
+                "timeoriginalestimate": to_int(f.get("timeoriginalestimate")),
+                "timeestimate": to_int(f.get("timeestimate")),
+                "timespent": to_int(f.get("timespent")),
+                "workflow_id": None,
+                "security": to_int(security.get("id")) if isinstance(security, dict) else None,
+                "fixfor": None,
+                "component": None,
+                "archived": "N",
+                "archivedby": None,
+                "archiveddate": None,
+            },
+        )
+
+        # Versions and components: config rows plus issue associations.
+        for assoc, field_name in (("IssueFixVersion", "fixVersions"), ("IssueVersion", "versions")):
+            for v in f.get(field_name) or []:
+                vid = self._version_row(rs, v, project_id)
+                if vid is not None:
+                    rs.upsert("nodeassociation", (iid, vid, assoc), {
+                        "source_node_id": iid, "source_node_entity": "Issue", "sink_node_id": vid,
+                        "sink_node_entity": "Version", "association_type": assoc, "sequence": None})
+        for c in f.get("components") or []:
+            cid = self._component_row(rs, c, project_id)
+            if cid is not None:
+                rs.upsert("nodeassociation", (iid, cid, "IssueComponent"), {
+                    "source_node_id": iid, "source_node_entity": "Issue", "sink_node_id": cid,
+                    "sink_node_entity": "Component", "association_type": "IssueComponent", "sequence": None})
+
+        for label in f.get("labels") or []:
+            rs.upsert("label", ("sys", label), {"id": stable_id("label", iid, "", label), "fieldid": None,
+                                                "issue": iid, "label": label})
+
+        self._map_links(rs, iid, f)
+
+        for a in f.get("attachment") or []:
+            aid = to_int(a.get("id"))
+            if aid is None:
+                continue
+            rs.upsert("fileattachment", aid, {
+                "id": aid,
+                "issueid": iid,
+                "mimetype": a.get("mimeType"),
+                "filename": a.get("filename"),
+                "created": parse_ts(a.get("created")),
+                "filesize": to_int(a.get("size")),
+                "author": self._add_user(rs, a.get("author")),
+                "zip": None,
+                "thumbnailable": 1 if a.get("thumbnail") else 0,
+            })
+
+        for field_id, value in f.items():
+            num = cf_number(field_id)
+            if num is None or value is None:
+                continue
+            self._map_custom_value(rs, iid, num, value)
+
+        self._map_changelog(rs, iid, snap.get("changelog"))
+        self._map_comments(rs, iid, snap.get("comments"))
+        self._map_worklogs(rs, iid, snap.get("worklogs"))
+        return rs.as_dict()
+
+    # ------------------------------------------------------------------ links
+    def _map_links(self, rs: RowSet, iid: int, f: dict[str, Any]) -> None:
+        for link in f.get("issuelinks") or []:
+            lid = to_int(link.get("id"))
+            ltype = link.get("type") or {}
+            tid = self._linktype_row(rs, ltype) if ltype else None
+            if lid is None or tid is None:
+                continue
+            if link.get("outwardIssue"):
+                src, dst = iid, to_int(link["outwardIssue"].get("id"))
+            elif link.get("inwardIssue"):
+                src, dst = to_int(link["inwardIssue"].get("id")), iid
+            else:
+                continue
+            if src is None or dst is None:
+                continue
+            rs.upsert("issuelink", lid, {"id": lid, "linktype": tid, "source": src, "destination": dst,
+                                         "sequence": None})
+
+        # Parent/child relationships are owned by the child's snapshot.
+        parent = f.get("parent") or {}
+        pid = to_int(parent.get("id")) if parent else None
+        if pid is None:
+            return
+        own_type = f.get("issuetype") or {}
+        parent_type = ((parent.get("fields") or {}).get("issuetype")) or {}
+        if own_type.get("subtask"):
+            tid, tag = SUBTASK_LINKTYPE_ID, "subtask"
+        else:
+            parent_level = to_int(parent_type.get("hierarchyLevel"))
+            own_level = to_int(own_type.get("hierarchyLevel")) or 0
+            if parent_level is None:
+                parent_level = own_level + 1
+            if parent_level == 1:
+                tid, tag = EPIC_LINKTYPE_ID, "epic"
+            else:
+                tid, tag = PARENT_LINKTYPE_ID, "parent"
+        lid = stable_id(tag, pid, iid)
+        rs.upsert("issuelink", lid, {"id": lid, "linktype": tid, "source": pid, "destination": iid,
+                                     "sequence": None})
+
+    # ---------------------------------------------------------- custom fields
+    def _cfv(self, rs: RowSet, iid: int, num: int, idx: int, *, parentkey: str | None = None,
+             stringvalue: Any = None, numbervalue: Any = None, textvalue: Any = None,
+             datevalue: Any = None) -> None:
+        rs.add("customfieldvalue", {
+            "id": stable_id("cfv", iid, num, idx, parentkey or ""),
+            "issue": iid,
+            "customfield": num,
+            "updated": None,
+            "parentkey": parentkey,
+            "stringvalue": None if stringvalue is None else str(stringvalue),
+            "numbervalue": numbervalue,
+            "textvalue": textvalue,
+            "datevalue": datevalue,
+            "valuetype": None,
+        })
+
+    def _option(self, rs: RowSet, num: int, opt: dict[str, Any], parent_id: int | None = None) -> int | None:
+        oid = to_int(opt.get("id"))
+        if oid is None:
+            return None
+        rs.upsert("customfieldoption", oid, {
+            "id": oid, "customfield": num, "customfieldconfig": None, "parentoptionid": parent_id,
+            "sequence": None, "customvalue": opt.get("value") if opt.get("value") is not None else opt.get("name"),
+            "optiontype": None, "disabled": "Y" if opt.get("disabled") else "N",
+        })
+        return oid
+
+    def _map_custom_value(self, rs: RowSet, iid: int, num: int, value: Any) -> None:
+        typekey, _name = self.custom_fields.get(num, (None, None))
+        suffix = (typekey or "").rsplit(":", 1)[-1]
+        values = value if isinstance(value, list) else [value]
+
+        if suffix == "gh-sprint":
+            for i, s in enumerate(values):
+                sprint = self._sprint(rs, s)
+                if sprint is not None:
+                    self._cfv(rs, iid, num, i, stringvalue=sprint)
+            return
+        if suffix in ("gh-epic-link",):
+            return  # represented by the Epic-Story Link issue link
+        if suffix == "labels":
+            for v in values:
+                if v:
+                    rs.upsert("label", (num, v), {"id": stable_id("label", iid, num, v), "fieldid": num,
+                                                  "issue": iid, "label": str(v)})
+            return
+        if suffix == "cascadingselect" and isinstance(value, dict):
+            parent_id = self._option(rs, num, value)
+            if parent_id is not None:
+                self._cfv(rs, iid, num, 0, stringvalue=parent_id)
+            child = value.get("child")
+            if isinstance(child, dict):
+                child_id = self._option(rs, num, child, parent_id)
+                if child_id is not None:
+                    self._cfv(rs, iid, num, 0, parentkey="1", stringvalue=child_id)
+            return
+        if suffix in ("select", "multiselect", "radiobuttons", "multicheckboxes", "gh-epic-status"):
+            for i, v in enumerate(values):
+                if isinstance(v, dict):
+                    oid = self._option(rs, num, v)
+                    if oid is not None:
+                        self._cfv(rs, iid, num, i, stringvalue=oid)
+            return
+        if suffix in ("userpicker", "multiuserpicker", "people"):
+            for i, v in enumerate(values):
+                k = self._add_user(rs, v)
+                if k:
+                    self._cfv(rs, iid, num, i, stringvalue=k)
+            return
+        if suffix in ("grouppicker", "multigrouppicker"):
+            for i, v in enumerate(values):
+                name = v.get("name") if isinstance(v, dict) else v
+                if name:
+                    self._cfv(rs, iid, num, i, stringvalue=name)
+            return
+        if suffix in ("version", "multiversion"):
+            for i, v in enumerate(values):
+                if isinstance(v, dict):
+                    vid = self._version_row(rs, v, None)
+                    if vid is not None:
+                        self._cfv(rs, iid, num, i, numbervalue=float(vid))
+            return
+        if suffix == "project" and isinstance(value, dict):
+            pid = self._project_row(rs, value)
+            if pid is not None:
+                self._cfv(rs, iid, num, 0, numbervalue=float(pid))
+            return
+        if suffix in ("float", "importid"):
+            n = to_float(value)
+            if n is not None:
+                self._cfv(rs, iid, num, 0, numbervalue=n)
+            return
+        if suffix in ("datepicker", "datetime"):
+            self._cfv(rs, iid, num, 0, datevalue=parse_ts(value))
+            return
+        if suffix == "textarea":
+            self._cfv(rs, iid, num, 0, textvalue=_text(value))
+            return
+        if suffix in ("textfield", "url", "readonlyfield", "gh-epic-label", "gh-epic-color", "gh-lexo-rank"):
+            self._cfv(rs, iid, num, 0, stringvalue=_text(value))
+            return
+        self._map_unknown_value(rs, iid, num, values)
+
+    def _map_unknown_value(self, rs: RowSet, iid: int, num: int, values: list[Any]) -> None:
+        """Best effort for field types we have no rule for: infer from the value's shape."""
+        for i, v in enumerate(values):
+            if v is None:
+                continue
+            if isinstance(v, bool):
+                self._cfv(rs, iid, num, i, stringvalue="true" if v else "false")
+            elif isinstance(v, (int, float)):
+                self._cfv(rs, iid, num, i, numbervalue=float(v))
+            elif isinstance(v, str):
+                ts = parse_ts(v) if len(v) in (10, 24, 28, 29) and v[:4].isdigit() else None
+                if ts is not None:
+                    self._cfv(rs, iid, num, i, datevalue=ts)
+                elif len(v) > 255 or "\n" in v:
+                    self._cfv(rs, iid, num, i, textvalue=v)
+                else:
+                    self._cfv(rs, iid, num, i, stringvalue=v)
+            elif isinstance(v, dict):
+                if v.get("accountId"):
+                    self._cfv(rs, iid, num, i, stringvalue=self._add_user(rs, v))
+                elif "value" in v and v.get("id") is not None:
+                    oid = self._option(rs, num, v)
+                    self._cfv(rs, iid, num, i, stringvalue=oid)
+                elif v.get("type") == "doc":
+                    self._cfv(rs, iid, num, i, textvalue=adf_to_text(v))
+                elif v.get("id") is not None:
+                    self._cfv(rs, iid, num, i, stringvalue=v.get("id"))
+                elif v.get("name") is not None:
+                    self._cfv(rs, iid, num, i, stringvalue=v.get("name"))
+
+    def _sprint(self, rs: RowSet, s: Any) -> int | None:
+        if isinstance(s, str):  # legacy "Sprint@abc[id=1,rapidViewId=2,state=CLOSED,...]" format
+            parsed = {k: (None if v in ("<null>", "") else v) for k, v in _SPRINT_STR.findall(s)}
+            s = {
+                "id": parsed.get("id"), "name": parsed.get("name"), "state": (parsed.get("state") or "").lower(),
+                "boardId": parsed.get("rapidViewId"), "goal": parsed.get("goal"),
+                "startDate": parsed.get("startDate"), "endDate": parsed.get("endDate"),
+                "completeDate": parsed.get("completeDate"), "activatedDate": parsed.get("activatedDate"),
+                "sequence": parsed.get("sequence"),
+            }
+        if not isinstance(s, dict):
+            return None
+        sid = to_int(s.get("id"))
+        if sid is None:
+            return None
+        state = (s.get("state") or "").lower()
+        board = to_int(s.get("boardId") or s.get("originBoardId"))
+        rs.upsert("AO_60DB71_SPRINT", sid, {
+            "ID": sid,
+            "NAME": s.get("name"),
+            "GOAL": s.get("goal") or None,
+            "STARTED": state in ("active", "closed"),
+            "CLOSED": state == "closed",
+            "START_DATE": to_epoch_ms(s.get("startDate")),
+            "END_DATE": to_epoch_ms(s.get("endDate")),
+            "COMPLETE_DATE": to_epoch_ms(s.get("completeDate")),
+            "ACTIVATED_DATE": to_epoch_ms(s.get("activatedDate") or s.get("startDate")),
+            "RAPID_VIEW_ID": board,
+            "SEQUENCE": to_int(s.get("sequence")) or sid,
+        })
+        if board is not None:
+            rs.upsert("AO_60DB71_RAPIDVIEW", board, {"ID": board, "NAME": None, "FILTER_ID": None,
+                                                     "OWNER_USER_NAME": None})
+        return sid
+
+    # ---------------------------------------------------- changelog, comments
+    def _map_changelog(self, rs: RowSet, iid: int, histories: Any) -> None:
+        for h in histories or []:
+            hid = to_int(h.get("id"))
+            if hid is None:
+                continue
+            rs.upsert("changegroup", hid, {"id": hid, "issueid": iid, "author": self._add_user(rs, h.get("author")),
+                                           "created": parse_ts(h.get("created"))})
+            for idx, item in enumerate(h.get("items") or []):
+                old_value = item.get("from")
+                new_value = item.get("to")
+                if item.get("tmpFromAccountId") is not None or item.get("tmpToAccountId") is not None:
+                    old_value = item.get("tmpFromAccountId") or old_value
+                    new_value = item.get("tmpToAccountId") or new_value
+                rs.add("changeitem", {
+                    "id": stable_id("ci", hid, idx),
+                    "groupid": hid,
+                    "fieldtype": item.get("fieldtype"),
+                    "field": item.get("field"),
+                    "oldvalue": None if old_value is None else str(old_value),
+                    "oldstring": item.get("fromString"),
+                    "newvalue": None if new_value is None else str(new_value),
+                    "newstring": item.get("toString"),
+                })
+
+    @staticmethod
+    def _visibility(obj: dict[str, Any]) -> tuple[str | None, int | None]:
+        vis = obj.get("visibility") or {}
+        if vis.get("type") == "group":
+            return vis.get("value") or vis.get("identifier"), None
+        if vis.get("type") == "role":
+            return None, to_int(vis.get("identifier"))
+        return None, None
+
+    def _map_comments(self, rs: RowSet, iid: int, comments: Any) -> None:
+        for c in comments or []:
+            cid = to_int(c.get("id"))
+            if cid is None:
+                continue
+            group, role = self._visibility(c)
+            rs.upsert("jiraaction", cid, {
+                "id": cid,
+                "issueid": iid,
+                "author": self._add_user(rs, c.get("author")),
+                "actiontype": "comment",
+                "actionlevel": group,
+                "rolelevel": role,
+                "actionbody": _text(c.get("body")),
+                "created": parse_ts(c.get("created")),
+                "updateauthor": self._add_user(rs, c.get("updateAuthor")),
+                "updated": parse_ts(c.get("updated")),
+                "actionnum": None,
+            })
+
+    def _map_worklogs(self, rs: RowSet, iid: int, worklogs: Any) -> None:
+        for w in worklogs or []:
+            wid = to_int(w.get("id"))
+            if wid is None:
+                continue
+            group, role = self._visibility(w)
+            rs.upsert("worklog", wid, {
+                "id": wid,
+                "issueid": iid,
+                "author": self._add_user(rs, w.get("author")),
+                "grouplevel": group,
+                "rolelevel": role,
+                "worklogbody": _text(w.get("comment")),
+                "created": parse_ts(w.get("created")),
+                "updateauthor": self._add_user(rs, w.get("updateAuthor")),
+                "updated": parse_ts(w.get("updated")),
+                "startdate": parse_ts(w.get("started")),
+                "timeworked": to_int(w.get("timeSpentSeconds")),
+            })