Fail fast on punctuation-only controller ids in EPICS GUI emission

The EPICS CA id validator accepts `[A-Za-z0-9_-]+`, so ids like `"___"`
and `"-"` pass validation and reach `_coerce_pascal_name` in the GUI
emission path. That helper delegates to `pvi.device.enforce_pascal_case`,
which strips non-Pascal characters and unconditionally indexes `s[0]` on
the result. When every character is stripped the index raises
`IndexError`, blowing up GUI emission at `connect()` time with an opaque
traceback.

Pre-strip the id with the same regex pvi uses (`NON_PASCAL_CHARS_RE`)
and raise `ValueError` with a message that names the offending id when
the strip yields the empty string. Choosing fail-fast over an `"X"`
fallback keeps the failure traceable: a silent fallback would generate
nonsense GUI names that the user would have to reverse-engineer back to
the bad id.

Fixes #369

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: gilesknap

src/fastcs/transports/epics/emission.py

@@ -11,7 +11,12 @@
 from collections.abc import Callable
 
 from pvi._format.dls import DLSFormatter  # type: ignore
-from pvi.device import Device, DeviceRef, enforce_pascal_case  # type: ignore
+from pvi.device import (  # type: ignore
+    NON_PASCAL_CHARS_RE,
+    Device,
+    DeviceRef,
+    enforce_pascal_case,
+)
 
 from fastcs.controllers import ControllerAPI
 from fastcs.logging import logger
@@ -36,9 +41,24 @@ def _coerce_pascal_name(controller_id: str) -> str:
     union of every transport's charset and may legitimately start with a
     digit (e.g. UUID-flavoured test prefixes), so we prepend ``X`` when
     needed before delegating to ``pvi.device.enforce_pascal_case``.
+
+    Some otherwise-valid transport ids (the EPICS CA validator accepts
+    ``[A-Za-z0-9_-]+`` so ``"___"`` and ``"-"`` are legal) contain no
+    Pascal-usable characters at all. ``enforce_pascal_case`` strips
+    everything and then unconditionally indexes ``s[0]``, raising
+    ``IndexError`` on the empty string. We fail fast with a clearer
+    ``ValueError`` instead -- a silent fallback would produce nonsense
+    GUI names that the user can't trace back to the offending id.
     """
+    stripped = NON_PASCAL_CHARS_RE.sub("", controller_id)
+    if not stripped:
+        raise ValueError(
+            f"Controller id {controller_id!r} contains no characters usable "
+            "in a Pascal-case name; pick an id with at least one ASCII "
+            "letter or digit"
+        )
     candidate = enforce_pascal_case(controller_id)
-    if candidate and not candidate[0].isupper():
+    if not candidate[0].isupper():
         candidate = "X" + candidate
     return candidate
 

tests/transports/epics/test_emission.py

@@ -10,6 +10,7 @@
 from fastcs.transports.epics.emission import (
     DOCS_EXT,
     INDEX_STEM,
+    _coerce_pascal_name,
     emit_docs_files,
     emit_gui_files,
 )
@@ -174,3 +175,32 @@ def test_docs_creates_missing_output_dir(two_apis, tmp_path: Path):
 
     assert (nested / f"alpha{DOCS_EXT}").is_file()
     assert (nested / f"{INDEX_STEM}{DOCS_EXT}").is_file()
+
+
+# --- _coerce_pascal_name fail-fast (#369) ----------------------------------
+
+
+@pytest.mark.parametrize("bad_id", ["___", "-", "_-_", "----"])
+def test_coerce_pascal_name_rejects_all_punctuation_ids(bad_id: str):
+    """Ids that strip to empty would IndexError inside ``enforce_pascal_case``.
+
+    The EPICS CA validator accepts ``[A-Za-z0-9_-]+`` so ids like ``"___"``
+    and ``"-"`` reach GUI emission. We raise ``ValueError`` rather than
+    falling back to a generated name so the offending id surfaces in the
+    error message instead of producing a nonsense PascalStr the user
+    can't trace.
+    """
+    with pytest.raises(ValueError, match=repr(bad_id)) as excinfo:
+        _coerce_pascal_name(bad_id)
+
+    assert "Pascal-case" in str(excinfo.value)
+
+
+def test_coerce_pascal_name_accepts_digit_leading_id():
+    """Happy path: digit-leading ids are still coerced via ``X`` prefix."""
+    assert _coerce_pascal_name("120e1b6") == "X120e1b6"
+
+
+def test_coerce_pascal_name_accepts_normal_pascal_id():
+    """Happy path: ordinary Pascal-friendly ids round-trip cleanly."""
+    assert _coerce_pascal_name("alpha") == "Alpha"