fix(telegram): JS-truthy empty-list rich-text gates + mutation coverage

Render optional rich-text fields (credit/caption/cell text) when the value
is an empty list []. Upstream gates these with `value.x ? ... : ""`; JS
arrays are always truthy, so credit: [] renders a blank credit, while the
prior Python-truthiness gate wrongly skipped it. Add a _present() helper
that renders for everything except None/absent and the empty string "".

Strip with the exact ECMAScript WhiteSpace+LineTerminator set (JS_WHITESPACE)
instead of Python's broader Unicode-whitespace strip(), matching JS
trimEnd()/trim() character-for-character.

Add regression tests, each verified to fail on its mutation:
- empty-list credit renders (truthiness trap)
- no-backtick pre block emits a 3-backtick fence (max(3,...)/else 3)
- truncation reserves room for the ellipsis (end = LIMIT - 3)
- exact-limit-length input passes through unchanged (<= boundary)

Author: patrick-chinchill

src/chat_sdk/adapters/telegram/rich.py

@@ -39,6 +39,43 @@
 # Upstream: /`+/g -- runs of one or more backticks.
 BACKTICKS = re.compile(r"`+")
 
+# The exact set of characters JS ``String.prototype.trim``/``trimEnd`` removes:
+# the ECMAScript WhiteSpace set plus the LineTerminator set. Python's bare
+# ``str.strip()``/``str.rstrip()`` strip a broader Unicode-whitespace set (e.g.
+# the C0 separators ``\x1c``-``\x1f`` and NEL ``\x85``, which JS keeps; and they
+# do NOT strip the BOM ````, which JS removes). Passing this explicit
+# string to ``strip``/``rstrip`` matches JS character-for-character.
+JS_WHITESPACE = (
+    "\t\n\v\f\r "  # \t \n \v \f \r and SPACE
+    " "  # NO-BREAK SPACE
+    " "  # OGHAM SPACE MARK
+    "           "  # EN QUAD..HAIR SPACE
+    "
"  # LINE SEPARATOR
+    "
"  # PARAGRAPH SEPARATOR
+    " "  # NARROW NO-BREAK SPACE
+    " "  # MEDIUM MATHEMATICAL SPACE
+    "　"  # IDEOGRAPHIC SPACE
+    ""  # ZERO WIDTH NO-BREAK SPACE (BOM)
+)
+
+
+def _present(value: TelegramRichText | None) -> bool:
+    """Match JS truthiness for an optional ``TelegramRichText`` field.
+
+    Upstream gates these fields with ``value.x ? ... : ""``. The only values
+    a ``TelegramRichText`` (``str | list | object``) can take that differ from
+    Python truthiness is the empty list ``[]``: JS arrays are ALWAYS truthy, so
+    ``credit: []`` renders upstream but a bare ``if value.get("credit")`` would
+    skip it in Python. We therefore render whenever the value is present and is
+    not the empty string ``""`` (the only falsy ``TelegramRichText`` in JS):
+
+    - ``None`` / absent -> skip (JS ``undefined`` is falsy)
+    - ``""`` -> skip (JS ``""`` is falsy)
+    - ``[]`` -> render (JS arrays are truthy)
+    - ``[span]`` / ``"text"`` / object -> render (truthy)
+    """
+    return value is not None and value != ""
+
 
 def truncate_rich_markdown(markdown: str) -> str:
     """Truncate *markdown* to the Telegram rich-message character limit.
@@ -81,7 +118,7 @@ def _inline_code(value: str) -> str:
     runs = BACKTICKS.findall(value)
     size = max(1, *(len(run) + 1 for run in runs)) if runs else 1
     marker = "`" * size
-    has_boundary_space = value.startswith(" ") and value.endswith(" ") and len(value.strip()) > 0
+    has_boundary_space = value.startswith(" ") and value.endswith(" ") and len(value.strip(JS_WHITESPACE)) > 0
     padding = " " if value.startswith("`") or value.endswith("`") or has_boundary_space else ""
     return f"{marker}{padding}{value}{padding}{marker}"
 
@@ -196,46 +233,46 @@ def _plain(markdown: TelegramRichText) -> str:
 def _caption(value: TelegramRichCaption | None = None) -> str:
     if not value:
         return ""
-    credit = f"\n{_text(value['credit'])}" if value.get("credit") else ""
+    credit = f"\n{_text(value['credit'])}" if _present(value.get("credit")) else ""
     return f"{_text(value['text'])}{credit}"
 
 
 def _plain_caption(value: TelegramRichCaption | None = None) -> str:
     if not value:
         return ""
-    credit = f"\n{_plain(value['credit'])}" if value.get("credit") else ""
+    credit = f"\n{_plain(value['credit'])}" if _present(value.get("credit")) else ""
     return f"{_plain(value['text'])}{credit}"
 
 
 def _cell(value: TelegramRichCell) -> str:
-    return _text(value["text"]) if value.get("text") else ""
+    return _text(value["text"]) if _present(value.get("text")) else ""
 
 
 def _item(value: TelegramRichItem) -> str:
     checked = ""
     if value.get("has_checkbox"):
         checked = "[x] " if value.get("is_checked") else "[ ] "
     content = "\n\n".join(_block(b) for b in value["blocks"]).replace("\n", "\n  ")
-    return f"{value['label']} {checked}{content}".rstrip()
+    return f"{value['label']} {checked}{content}".rstrip(JS_WHITESPACE)
 
 
 def _plain_item(value: TelegramRichItem) -> str:
     checked = ""
     if value.get("has_checkbox"):
         checked = "[x] " if value.get("is_checked") else "[ ] "
     content = "\n".join(b for b in (_plain_block(blk) for blk in value["blocks"]) if b).replace("\n", "\n  ")
-    return f"{value['label']} {checked}{content}".rstrip()
+    return f"{value['label']} {checked}{content}".rstrip(JS_WHITESPACE)
 
 
 def _table(value: TelegramRichBlockTable) -> str:
     rows = [f"| {' | '.join(_cell(c) for c in row)} |" for row in value["cells"]]
     if len(rows) == 0:
-        return _text(value["caption"]) if value.get("caption") else ""
+        return _text(value["caption"]) if _present(value.get("caption")) else ""
 
     columns = max(len(row) for row in value["cells"])
     separator = f"| {' | '.join('---' for _ in range(columns))} |"
     content = "\n".join([rows[0], separator, *rows[1:]])
-    return f"{_text(value['caption'])}\n\n{content}" if value.get("caption") else content
+    return f"{_text(value['caption'])}\n\n{content}" if _present(value.get("caption")) else content
 
 
 def _quote(value: str) -> str:
@@ -261,10 +298,10 @@ def _block(value: TelegramRichBlock) -> str:
             return "\n".join(_item(i) for i in value["items"])
         case "blockquote":
             content = "\n\n".join(_block(b) for b in value["blocks"])
-            credit = f"\n\n{_text(value['credit'])}" if value.get("credit") else ""
+            credit = f"\n\n{_text(value['credit'])}" if _present(value.get("credit")) else ""
             return _quote(f"{content}{credit}")
         case "pullquote":
-            credit = f"\n\n{_text(value['credit'])}" if value.get("credit") else ""
+            credit = f"\n\n{_text(value['credit'])}" if _present(value.get("credit")) else ""
             return _quote(f"{_text(value['text'])}{credit}")
         case "collage" | "slideshow":
             content = "\n\n".join(b for b in (_block(blk) for blk in value["blocks"]) if b)
@@ -295,21 +332,22 @@ def _plain_block(value: TelegramRichBlock) -> str:
             return "\n".join(_plain_item(i) for i in value["items"])
         case "blockquote":
             content = "\n\n".join(b for b in (_plain_block(blk) for blk in value["blocks"]) if b)
-            credit = f"\n\n{_plain(value['credit'])}" if value.get("credit") else ""
+            credit = f"\n\n{_plain(value['credit'])}" if _present(value.get("credit")) else ""
             return f"{content}{credit}"
         case "pullquote":
-            credit = f"\n\n{_plain(value['credit'])}" if value.get("credit") else ""
+            credit = f"\n\n{_plain(value['credit'])}" if _present(value.get("credit")) else ""
             return f"{_plain(value['text'])}{credit}"
         case "collage" | "slideshow":
             content = "\n\n".join(b for b in (_plain_block(blk) for blk in value["blocks"]) if b)
             description = _plain_caption(value.get("caption"))
             return "\n\n".join(part for part in (content, description) if part)
         case "table":
             rows = [
-                "\t".join(_plain(entry["text"]) if entry.get("text") else "" for entry in row) for row in value["cells"]
+                "\t".join(_plain(entry["text"]) if _present(entry.get("text")) else "" for entry in row)
+                for row in value["cells"]
             ]
             content = "\n".join(rows)
-            return f"{_plain(value['caption'])}\n\n{content}" if value.get("caption") else content
+            return f"{_plain(value['caption'])}\n\n{content}" if _present(value.get("caption")) else content
         case "details":
             body = "\n\n".join(b for b in (_plain_block(blk) for blk in value["blocks"]) if b)
             return f"{_plain(value['summary'])}\n\n{body}"
@@ -403,12 +441,12 @@ def _media(blocks: list[TelegramRichBlock], result: list[RichMedia]) -> None:
 
 def rich_message_to_markdown(message: TelegramRichMessage) -> str:
     """Render a Telegram rich message to Markdown."""
-    return "\n\n".join(b for b in (_block(blk) for blk in message["blocks"]) if b).strip()
+    return "\n\n".join(b for b in (_block(blk) for blk in message["blocks"]) if b).strip(JS_WHITESPACE)
 
 
 def rich_message_to_text(message: TelegramRichMessage) -> str:
     """Render a Telegram rich message to plain text."""
-    return "\n\n".join(b for b in (_plain_block(blk) for blk in message["blocks"]) if b).strip()
+    return "\n\n".join(b for b in (_plain_block(blk) for blk in message["blocks"]) if b).strip(JS_WHITESPACE)
 
 
 def rich_message_media(message: TelegramRichMessage) -> list[RichMedia]:

tests/test_telegram_rich.py

@@ -32,6 +32,7 @@
     TelegramRichBlockList,
     TelegramRichBlockPhoto,
     TelegramRichBlockPre,
+    TelegramRichBlockPullquote,
     TelegramRichBlockTable,
     TelegramRichBlockText,
     TelegramRichCell,
@@ -347,3 +348,91 @@ def test_truncation_passes_through_under_limit_text_unchanged() -> None:
     text = "😀" * 5
     assert truncate_rich_markdown(text) == text
     assert truncate_rich_markdown("plain") == "plain"
+
+
+# ---------------------------------------------------------------------------
+# Fidelity: empty-LIST rich-text field renders (JS arrays are truthy)
+# ---------------------------------------------------------------------------
+
+
+def test_empty_list_credit_renders_like_a_present_credit() -> None:
+    """An empty-list ``credit`` ([]) renders, matching JS array truthiness.
+
+    Upstream gates the credit with ``value.credit ? ... : ""``; a JS array is
+    ALWAYS truthy, so ``credit: []`` produces a blank credit (a leading-newline
+    empty line in the quote), whereas absent / empty-string skip it. A bare
+    Python-truthiness gate (``if value.get("credit")``) would wrongly skip
+    ``[]`` -- this test fails under that regression.
+    """
+    # credit=[] -> truthy in JS -> credit segment "\n\n" + text([]) ("") renders.
+    # quote("Quote\n\n") -> "> Quote\n> \n> " -> trailing ws trimmed by .strip().
+    with_empty_list: TelegramRichBlockPullquote = {"type": "pullquote", "text": "Quote", "credit": []}
+    assert rich_message_to_markdown({"blocks": [with_empty_list]}) == "> Quote\n> \n>"
+
+    # Absent credit -> JS undefined is falsy -> skipped entirely.
+    absent: TelegramRichBlockPullquote = {"type": "pullquote", "text": "Quote"}
+    assert rich_message_to_markdown({"blocks": [absent]}) == "> Quote"
+
+    # Empty-string credit -> JS "" is falsy -> skipped (the ONLY falsy RichText).
+    empty_string: TelegramRichBlockPullquote = {"type": "pullquote", "text": "Quote", "credit": ""}
+    assert rich_message_to_markdown({"blocks": [empty_string]}) == "> Quote"
+
+    # A real credit span renders the same blank-line-separated shape as [].
+    with_author: TelegramRichBlockPullquote = {"type": "pullquote", "text": "Quote", "credit": "Author"}
+    assert rich_message_to_markdown({"blocks": [with_author]}) == "> Quote\n> \n> Author"
+
+
+# ---------------------------------------------------------------------------
+# Mutation coverage: fence default width, truncation reserve, exact boundary
+# ---------------------------------------------------------------------------
+
+
+def test_pre_block_without_internal_backticks_emits_a_three_backtick_fence() -> None:
+    """A code/pre block with NO internal backticks uses the default 3-fence.
+
+    ``_code_block`` sizes the fence as ``max(3, longest_run + 1)`` and falls
+    back to ``3`` when there are no backtick runs. This pins the no-run default:
+    the mutations ``else 3`` -> ``else 2`` and ``max(3, ...)`` -> ``max(2, ...)``
+    both shrink the fence to 2 backticks and fail this assertion.
+    """
+    fence = "`" * 3
+    pre: TelegramRichBlockPre = {"type": "pre", "language": "python", "text": "hello world"}
+    markdown = rich_message_to_markdown({"blocks": [pre]})
+
+    assert markdown == f"{fence}python\nhello world\n{fence}"
+    # Exactly three opening backticks -- never two.
+    assert len(markdown) - len(markdown.lstrip("`")) == 3
+
+
+def test_truncation_reserves_room_for_the_ellipsis() -> None:
+    """Truncation reserves 3 chars for ``...`` so the result stays at the limit.
+
+    With an unclosed bold marker straddling the boundary, the correct reserve
+    (``end = LIMIT - 3``) returns a result of length EXACTLY ``LIMIT`` on the
+    first iteration. The mutation ``end = LIMIT`` over-shoots, the shrink loop
+    diverges, and it returns a shorter (length ``LIMIT - 2``) result -- so an
+    exact-length assertion fails under the mutation.
+    """
+    # 'a' x (LIMIT-1) + '**' opens an unclosed bold span right at the boundary;
+    # the trailing run keeps the input over the limit.
+    over_limit = ("a" * (TELEGRAM_RICH_MESSAGE_LIMIT - 1)) + "**" + ("b" * 200)
+    result = truncate_rich_markdown(over_limit)
+
+    # The ellipsis fits within the limit -- length is exactly the limit here,
+    # never over it (mutation would yield LIMIT - 2, killing the equality).
+    assert len(result) == TELEGRAM_RICH_MESSAGE_LIMIT
+    assert result.endswith("...")
+
+
+def test_exact_limit_length_passes_through_unchanged() -> None:
+    """A string of length EXACTLY ``LIMIT`` is returned verbatim (no ``...``).
+
+    The early-return guard is ``len(characters) <= LIMIT``. At the boundary
+    ``len == LIMIT`` the input must pass through; the mutation ``<=`` -> ``<``
+    would instead truncate it (appending ``...``), failing this assertion.
+    """
+    exact = "a" * TELEGRAM_RICH_MESSAGE_LIMIT
+    result = truncate_rich_markdown(exact)
+
+    assert result == exact
+    assert not result.endswith("...")