Function dedup_options

explainshell/extraction/postprocess.py:116–195

Remove options whose flag set is a subset of (or equal to) another's. Covers both strict-subset (e.g. {Z} vs {-M, Z}) and exact-match duplicates (e.g. two entries for {O}). When one option's combined flags (short ∪ long) are ⊆ another's, the smaller entry is removed. For **exact-m

(options: list[Option])

def dedup_options(options: list[Option]) -> tuple[list[Option], int]:
    """Remove options whose flag set is a subset of (or equal to) another's.

    Covers both strict-subset (e.g. {Z} vs {-M, Z}) and exact-match
    duplicates (e.g. two entries for {O}).  When one option's combined flags
    (short ∪ long) are ⊆ another's, the smaller entry is removed.

    For **exact-match** duplicates the first occurrence's position is kept.
    If a later duplicate has a longer description, the first entry is
    replaced with the later entry entirely (all fields, not just text).

    For **strict subsets** the superset entry survives with its own flags.
    If the subset has a longer description, the text and ``meta`` are
    transferred so that provenance (e.g. ``meta["lines"]``) stays
    consistent with the description text.

    When multiple supersets qualify, the **closest** one (smallest number
    of extra flags) is chosen so the subset merges into the most specific
    match rather than depending on input order.

    For **strict** subsets an additional cross-reference check is applied:
    the subset's description must mention at least one of the superset's
    extra flags.  This prevents false merges where dashless-option
    normalisation creates spurious flag overlaps (see ``_subset_has_cross_reference``).

    Returns (deduped_list, num_removed).
    """
    flags_list: list[frozenset[str]] = []
    for opt in options:
        if opt.short or opt.long:
            flags_list.append(frozenset(opt.short + opt.long))
        else:
            flags_list.append(frozenset())

    removed: set[int] = set()

    # Pass 1: exact-match dedup.  First occurrence's position wins;
    # if a later duplicate has a longer description, replace entirely.
    seen: dict[frozenset[str], int] = {}
    for i in range(len(options)):
        fi = flags_list[i]
        if not fi:
            continue
        if fi in seen:
            first = seen[fi]
            if len(options[i].text) > len(options[first].text):
                options[first] = options[i]
            removed.add(i)
        else:
            seen[fi] = i

    # Pass 2: strict-subset dedup.  For each surviving option, search
    # ALL other surviving options (bidirectional) for the closest
    # qualifying superset.
    for i in range(len(options)):
        if i in removed or not flags_list[i]:
            continue
        fi = flags_list[i]