Function sanity_check_line_spans

explainshell/extraction/postprocess.py:207–240

Reject an LLM extraction whose line spans look pathological. Raises ``ExtractionError`` when the sum of all option spans exceeds ``_MAX_COVERAGE_RATIO`` times the document extent (derived from the highest end-line in the options' own metadata). This catches the common failure mode

(options: list[Option])

def sanity_check_line_spans(options: list[Option]) -> None:
    """Reject an LLM extraction whose line spans look pathological.

    Raises ``ExtractionError`` when the sum of all option spans exceeds
    ``_MAX_COVERAGE_RATIO`` times the document extent (derived from the
    highest end-line in the options' own metadata).  This catches the
    common failure mode where the LLM returns near-document-sized ranges
    (e.g. ``[1, 927]``) for every option instead of precise per-option
    spans.
    """
    if not options:
        return

    total_span = 0
    max_end = 0
    for opt in options:
        meta = opt.meta or {}
        lines = meta.get("lines")
        if lines and isinstance(lines, list) and len(lines) == 2:
            total_span += max(lines[1] - lines[0] + 1, 0)
            max_end = max(max_end, lines[1])

    if max_end < 1:
        return

    coverage = total_span / max_end

    if coverage > _MAX_COVERAGE_RATIO:
        raise ExtractionError(
            f"line-span coverage {coverage:.1f}x exceeds {_MAX_COVERAGE_RATIO}x limit "
            f"({len(options)} options, {max_end} lines) "
            f"(try a stronger model?)",
            reason_class=FailureReason.LINE_SPAN_COVERAGE,
        )


def postprocess(