From e3d3262216801728a6dc6a42eee09013f7a45052 Mon Sep 17 00:00:00 2001
From: axisrow <axisrow@users.noreply.github.com>
Date: Fri, 10 Jul 2026 11:51:17 +0800
Subject: [PATCH] chore: vulture whitelist for verified false-positive
 ensure_ascii (#1136)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds [tool.vulture] to pyproject.toml (ignore_names=["ensure_ascii"]) and a
regression test locking the parameter in place.

safe_json_dumps(ensure_ascii=...) is an intentional call-site-compat no-op
after the orjson migration (#956) — orjson always emits UTF-8, live call
sites pass it today (e.g. generation_runs repository, src/models.py:666).
Removing it would break them. Classified as a false-positive in #1136; the
goal of that issue is 0 high-confidence findings via whitelist, NOT deletion.

vulture >=2.1 auto-reads [tool.vulture], so the whitelist applies to both
bare `python -m vulture src/` and scripts/code_health.py without touching
either. Before: 1 finding (src/utils/json.py:23, 100%). After: 0.

Part of #1136 / #1130.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 pyproject.toml           | 14 ++++++++++++++
 tests/test_utils_json.py | 11 +++++++++++
 2 files changed, 25 insertions(+)

diff --git a/pyproject.toml b/pyproject.toml
index e6afea0e..26d784fe 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -237,6 +237,20 @@ exclude_lines = [
 [tool.bandit]
 exclude_dirs = ["tests"]
 
+# Dead-code scan whitelist (vulture, #1136). vulture auto-reads this section,
+# so it applies both to `python -m vulture src/` and to scripts/code_health.py.
+# Every name here is a VERIFIED false-positive — do not delete the code it
+# refers to; each entry must say why it is intentionally "unused".
+[tool.vulture]
+ignore_names = [
+    # src/utils/json.py safe_json_dumps(ensure_ascii=...): intentional
+    # call-site-compatibility parameter after the orjson migration (#956) —
+    # orjson is always UTF-8, the flag is accepted so existing
+    # `safe_json_dumps(obj, ensure_ascii=True)` calls don't break, but has
+    # no effect. Removing it would break call sites. See issue #1136.
+    "ensure_ascii",
+]
+
 # Doc-coverage (interrogate, #1072). scripts/doc_coverage.py and the advisory
 # CI step read this. `fail_under` is a SOFT baseline — a ratchet floor that
 # surfaces regressions without forcing a docstring-everything sprint. Raise it
diff --git a/tests/test_utils_json.py b/tests/test_utils_json.py
index 5f9ea0e2..1c62296f 100644
--- a/tests/test_utils_json.py
+++ b/tests/test_utils_json.py
@@ -69,6 +69,17 @@ def test_kwargs_forwarded():
     assert result == '{"a":2,"b":1}'
 
 
+def test_ensure_ascii_accepted_for_call_site_compat():
+    # `ensure_ascii` is an intentional no-op kept for call-site compatibility
+    # after the orjson migration (#956): orjson is always UTF-8. Live call
+    # sites pass it (e.g. generation_runs repository), so the parameter must
+    # keep being accepted with either value. Vulture-whitelisted in
+    # pyproject.toml [tool.vulture] — do not remove (#1136).
+    payload = {"text": "привет"}
+    assert safe_json_dumps(payload, ensure_ascii=True) == safe_json_dumps(payload, ensure_ascii=False)
+    assert "привет" in safe_json_dumps(payload, ensure_ascii=True)
+
+
 def test_custom_default_does_not_receive_datetime():
     # With a custom default, datetime must be serialized natively by orjson, NOT
     # routed to the caller's default (which may not handle it) — review on #956.