docs(out): clarify _ensure_utf8_stdout docstring and test comments

* fix docstring: errors=replace handles un-encodable inputs (lone surrogates etc), not 'terminal cannot render' which is an OS concern not the encoder's

* tighten test comment to describe what's actually being verified

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: bearomorphism

commitizen/out.py

@@ -6,19 +6,20 @@
 
 
 def _ensure_utf8_stdout(stream: object) -> None:
-    """Reconfigure ``stream`` to UTF-8 if its current encoding can't represent
-    the unicode characters commitizen emits (e.g. ``\U0001f680`` 🚀, the
-    ``\u2019`` typographic apostrophe).
+    """Reconfigure non-UTF-8 stdout streams to emit UTF-8 bytes.
 
-    Without this, ``print`` raises ``UnicodeEncodeError`` mid-output on:
+    The primary fix is switching stdout from locale-dependent encodings to
+    UTF-8 so normal Unicode output (for example, ``\U0001f680`` 🚀 or the
+    ``\u2019`` typographic apostrophe) does not raise ``UnicodeEncodeError`` on:
 
     * Windows ``cmd.exe`` defaulting to ``cp1252`` (the historical case),
     * Linux/macOS terminals with a non-UTF-8 ``LANG`` such as
       ``de_CH.ISO8859-1`` (#956).
 
-    ``errors="replace"`` is used as a safety net for terminals that
-    genuinely can't render the bytes, so commitizen falls back to a
-    placeholder character instead of crashing.
+    ``errors="replace"`` is a defensive fallback for genuinely
+    un-encodable input, such as lone surrogates produced by buggy callers.
+    It does not make terminals render bytes; rendering is handled after the
+    encoder has produced UTF-8 bytes.
     """
     if not isinstance(stream, io.TextIOWrapper):
         return

tests/test_out.py

@@ -1,11 +1,11 @@
 """Tests for ``commitizen.out``.
 
 Mostly focused on the stdout-encoding helper introduced for #956: the
-function must reconfigure non-UTF-8 streams to UTF-8 with a permissive
-``errors="replace"`` strategy so commitizen output (emoji, typographic
-quotes) doesn't crash with ``UnicodeEncodeError`` on terminals using
-locale-dependent encodings such as ``cp1252`` (Windows) or
-``ISO8859-1`` (Linux/macOS).
+function must reconfigure non-UTF-8 streams to UTF-8 so commitizen output
+(emoji, typographic quotes) doesn't crash with ``UnicodeEncodeError`` on
+terminals using locale-dependent encodings such as ``cp1252`` (Windows) or
+``ISO8859-1`` (Linux/macOS). The helper also sets ``errors="replace"`` as a
+fallback for genuinely un-encodable input such as lone surrogates.
 """
 
 from __future__ import annotations
@@ -24,9 +24,12 @@ class _StubStream(io.TextIOWrapper):
     """
 
     reconfigure_calls: list[dict[str, Any]]
+    output: io.BytesIO
 
     def __init__(self, encoding: str) -> None:
-        super().__init__(io.BytesIO(), encoding=encoding)
+        output = io.BytesIO()
+        super().__init__(output, encoding=encoding)
+        self.output = output
         self.reconfigure_calls = []
 
     def reconfigure(self, **kwargs: Any) -> None:
@@ -78,8 +81,18 @@ def test_ensure_utf8_stdout_after_reconfigure_can_emit_emoji():
     stream = _StubStream(encoding="latin-1")
     _ensure_utf8_stdout(stream)
 
-    # Should not raise UnicodeEncodeError; ``errors="replace"`` lets
-    # genuinely-unrenderable bytes fall through as ``?`` instead of
-    # crashing the whole command.
+    # The primary regression guard: switching to UTF-8 means normal Unicode
+    # output, such as emoji, no longer raises UnicodeEncodeError.
     stream.write("Configuration complete \U0001f680")
     stream.flush()
+
+
+def test_ensure_utf8_stdout_replaces_lone_surrogate_on_write():
+    """``errors="replace"`` handles genuinely un-encodable input."""
+    stream = _StubStream(encoding="latin-1")
+    _ensure_utf8_stdout(stream)
+
+    stream.write("ok\udc00ok")
+    stream.flush()
+
+    assert stream.output.getvalue() == b"ok?ok"