Function normalize_option_fields

explainshell/extraction/llm/response.py:128–164

Normalize known LLM type mistakes in a raw option dict before validation. Fixes observed in the top-1000 corpus run: - ``has_argument: null`` → ``False`` (8 positional-arg options) - ``has_argument`` list with int elements → stringified (hdparm --set-sector-size) - ``has_argument``

(raw: dict)

def normalize_option_fields(raw: dict) -> dict:
    """Normalize known LLM type mistakes in a raw option dict before validation.

    Fixes observed in the top-1000 corpus run:
    - ``has_argument: null`` → ``False`` (8 positional-arg options)
    - ``has_argument`` list with int elements → stringified (hdparm --set-sector-size)
    - ``has_argument`` bare string (e.g. ``"1..99"``) → ``True`` (avrdude range params)
    - sigil embedded in the positional name (``"positional": "@server"``) →
      split into ``prefix`` + bare name; only for allowlisted sigil characters,
      so placeholder styling like ``<FILE>`` is untouched
    """
    raw = dict(raw)  # shallow copy to avoid mutating caller's data

    if raw.get("has_argument") is None and "has_argument" in raw:
        raw["has_argument"] = False

    # Normalize list elements to str (LLM sometimes returns ints for enum values).
    ha = raw.get("has_argument")
    if isinstance(ha, list) and ha and not all(isinstance(x, str) for x in ha):
        raw["has_argument"] = [str(x) for x in ha]

    # Coerce bare strings (e.g. range expressions like "0..7") to True.
    if isinstance(ha, str):
        raw["has_argument"] = True

    # Strip a leading sigil from the positional name into prefix.
    pos = raw.get("positional")
    if (
        isinstance(pos, str)
        and len(pos) > 1
        and pos[0] in models.OPTION_PREFIX_SIGILS
        and not raw.get("prefix")
    ):
        raw["prefix"] = pos[0]
        raw["positional"] = pos[1:]

    return raw


def sanitize_option_fields(