meltygui 0.1.0__py3-none-any.whl

meltygui/editor/code_line_fast.py

@@ -0,0 +1,152 @@
+"""draw_code_line_fast — ONE line of Python painted straight onto a draw list.
+
+The editor's look without the editor: the same Darcula palette
+(`text_editor.COLORS` through `tokenize`), the same definition BLOCK wash
+behind a tinted class/def body and the same occurrence washes behind every
+symbol whose definition carries a tint (`roster_tints.collect_def_tints`,
+adjusted through the same `_bg_adjust` knobs), the same glyph-toward-wash
+mix. No render_func, no draw_state, no wrapper: a plain function over a
+draw list, so a list of code rows (the Ctrl+B picker, search results) costs
+a few `add_text` calls per row instead of a one-line editor body each.
+
+Two halves, deliberately split:
+  • `CodeLineTints` resolves WHAT to paint behind a line (block tint +
+    span washes) — the only part that touches the roster, memoized per
+    (file, 64-line chunk) so a picker of N rows in one file runs the scan
+    once per chunk, not once per row. Resolve it when the rows are BUILT
+    (the picker open), never per frame.
+  • `draw_code_line_fast` paints — cheap enough to run every frame.
+
+Monospace contract: every caller pushes the editor's font
+(`push_code_font`), so glyph x = col * char_w and consecutive same-colour
+ASCII tokens merge into one `add_text` exactly as draw_text's fast path
+does. Font Awesome icons are NOT monospaced: each is drawn in its own cell.
+"""
+import bisect
+
+import meltygui_imgui as imgui
+from meltygui.hdr_color import pack_color
+
+from meltygui.core.styling.fonts import Font
+from meltygui.core.melty import Melty
+from meltygui.core.runtime.toggles import Toggles
+
+
+def push_code_font(font=Font.FONTAWESOME_MONO_19):
+    """Push the editor's font (JetBrains Mono + Font Awesome) and measure it.
+    Returns (pushed, char_w, line_h): pass `pushed` to `pop_code_font`,
+    `char_w` / `line_h` to every `draw_code_line_fast` call in the batch."""
+    pushed = False
+    if Melty.font_mgr is not None:
+        handle = Melty.font_mgr.get(font)
+        if handle is not None:
+            imgui.push_font(handle)
+            pushed = True
+    return pushed, imgui.calc_text_size("0").x, imgui.get_text_line_height()
+
+
+def pop_code_font(pushed):
+    if pushed:
+        imgui.pop_font()
+
+
+def _u32(rgb, alpha):
+    return pack_color(rgb[0], rgb[1], rgb[2], alpha)
+
+
+def _wash_factors():
+    """(block, symbol, text) factor tuples for `_bg_adjust` — the exact
+    triples draw_text builds from Toggles.TextEditor each frame."""
+    min_b = Toggles.TextEditor.bg_min_brightness
+    max_b = Toggles.TextEditor.bg_max_brightness
+    return ((Toggles.TextEditor.bg_tint_saturation,
+             Toggles.TextEditor.bg_tint_value, min_b, max_b),
+            (Toggles.TextEditor.symbol_tint_saturation,
+             Toggles.TextEditor.symbol_tint_value, min_b, max_b),
+            (Toggles.TextEditor.text_tint_saturation,
+             Toggles.TextEditor.text_tint_value, min_b, max_b))
+
+
+def _split_emphasis(col, token, emphasis):
+    """Pieces of `token` (starting at column `col`) as (start_col, text,
+    bright) — cut at the boundaries of the `emphasis` column spans."""
+    end = col + len(token)
+    cuts = {col, end}
+    for c0, c1 in emphasis:
+        if col < c0 < end:
+            cuts.add(c0)
+        if col < c1 < end:
+            cuts.add(c1)
+    edges = sorted(cuts)
+    out = []
+    for a, b in zip(edges, edges[1:]):
+        bright = any(c0 <= a < c1 for c0, c1 in emphasis)
+        out.append((a, token[a - col:b - col], bright))
+    return out
+
+
+
+
+
+class CodeLineTints:
+    """Resolves (block_tint, spans) for lines of files, memoized per
+    (file, text identity, 64-line chunk): the roster's windowed occurrence
+    scan runs once per chunk touched, and every line of that chunk reads
+    its washes from the result. Build one per row set (picker open, search
+    landing); it holds the file texts it was given."""
+    CHUNK = 64
+
+    def __init__(self):
+        self._chunks = {}   # (path, id(text), chunk_lo) -> (blocks, spans_by_line)
+        self._texts = {}    # id(text) -> text (holds the id's)
+
+    def tints(self, path, text, line):
+        """`line` is 1-based. Returns (block_tint | None, [(col0, col1, rgb,
+        scale)]) — columns relative to the RAW line (indent included); use
+        `shift_spans` after stripping a display line."""
+        if not text or line < 1:
+            return None, []
+        lo = ((line - 1) // self.CHUNK) * self.CHUNK
+        key = (str(path), id(text), lo)
+        got = self._chunks.get(key)
+        if got is None:
+            got = self._chunks[key] = self._scan(path, text, lo)
+            self._texts[id(text)] = text
+        blocks, by_line = got
+        bl = line - 1
+        block_tint, best_start = None, -1
+        for start, _idx, end, tint in blocks:
+            if start <= bl <= end and start > best_start:
+                block_tint, best_start = tint, start
+        return block_tint, by_line.get(bl, [])
+
+    def _scan(self, path, text, lo):
+        from meltygui.editor.roster_tints import collect_def_tints
+        from meltygui.editor.text_editor import _line_starts
+        starts = _line_starts(text)
+        hi = min(lo + self.CHUNK - 1, len(starts) - 1)
+        try:
+            blocks, spans, _lines, _names = collect_def_tints(
+                text, 0, path, window=(lo, hi), hold_live=False)
+        except Exception:
+            return (), {}
+        by_line = {}
+        for s, e, rgb, scale in spans:
+            # bisect on the memoized line starts: the line holding `s`.
+            li = bisect.bisect_right(starts, s) - 1
+            if li < lo or li > hi:
+                continue
+            ls = starts[li]
+            by_line.setdefault(li, []).append((s - ls, e - ls, rgb, scale))
+        return tuple(blocks), by_line
+
+
+def shift_spans(spans, offset):
+    """Line-relative spans after `offset` leading characters were stripped
+    from the display text (spans that fell inside the strip are dropped)."""
+    out = []
+    for c0, c1, rgb, scale in spans:
+        c0, c1 = c0 - offset, c1 - offset
+        if c1 > 0:
+            out.append((max(0, c0), c1, rgb, scale))
+    return out

meltygui/editor/diff.py

@@ -0,0 +1,139 @@
+"""Line comparison primitives shared by text inspection and integrations."""
+import difflib
+import bisect
+
+def diff_opcodes(a_lines, b_lines):
+    """Non-equal SequenceMatcher opcodes over two line lists, with the common
+    prefix/suffix trimmed BEFORE matching. SequenceMatcher walks its full
+    matching structure even for identical inputs — 108ms on an 11k-line file
+    with ZERO changes, paid on the render thread at every diff open — while
+    real compares differ in a few localized spans. Trimming equal edge lines
+    first drops the identical/localized case to ~2ms and leaves the spread
+    case unchanged. The opcodes reconstruct b exactly and change the same
+    number of lines as untrimmed difflib (pinned across repo-history pairs
+    in tests/test_diff_trim.py); when a change is bracketed by identical
+    lines (an inserted block that starts or ends with the blank line that
+    also precedes/follows it) its ANCHOR can land a line away from
+    untrimmed difflib's — equally minimal, equally valid, the same freedom
+    every trimming diff tool (git included) exercises. Bit-exact parity is
+    NOT attainable from a window: difflib resolves those ties through its
+    global longest-match recursion, so the same local shape anchors
+    differently depending on far-away content (fast_dock vs text_editor
+    pairs, 08-24). Offsets are restored before returning."""
+    len_a, len_b = len(a_lines), len(b_lines)
+    lo = 0
+    limit = min(len_a, len_b)
+    while lo < limit and a_lines[lo] == b_lines[lo]:
+        lo += 1
+    hi = 0
+    limit = min(len_a, len_b) - lo
+    while hi < limit and a_lines[len_a - 1 - hi] == b_lines[len_b - 1 - hi]:
+        hi += 1
+    sm = difflib.SequenceMatcher(a=a_lines[lo:len_a - hi],
+                                 b=b_lines[lo:len_b - hi], autojunk=False)
+    return [(tag, i1 + lo, i2 + lo, j1 + lo, j2 + lo)
+            for tag, i1, i2, j1, j2 in sm.get_opcodes() if tag != "equal"]
+
+
+
+def _diff_blocks(base, new):
+    """Change blocks for the side-by-side compare view: SequenceMatcher
+    opcodes over lines, as (new0, new1, base0, base1, tag) tuples with
+    0-based half-open LINE ranges — new* in the editable buffer (left
+    pane), base* in the reference (right pane, which draws the ribbons).
+    tag is 'replace' / 'delete' / 'insert' (delete = lines only in the
+    reference). Empty list = identical. diff_opcodes trims the common
+    prefix/suffix before matching — the difference between ~108ms and
+    ~2ms on the render thread for a big file's diff open."""
+    from meltygui.editor.diff import diff_opcodes
+    return [(j1, j2, i1, i2, tag)
+            for tag, i1, i2, j1, j2 in diff_opcodes(base.split("\n"),
+                                                    new.split("\n"))]
+
+
+def _incremental_diff_blocks(base, old_text, new_text, blocks):
+    """Splice-update `blocks` (the diff base→old_text) into the diff
+    base→new_text for a LOCALIZED edit (typing) without re-matching the
+    whole file: line-trim the old↔new change window, widen it (+margin)
+    out of any overlapping blocks so both edges sit in verified-EQUAL
+    regions, map those edges into base space exactly (cumulative block
+    delta — exact outside blocks), SequenceMatcher only the windows, and
+    splice: blocks before stay, blocks after shift by the line delta. The
+    result is a correct (possibly non-minimal) diff. Returns None when the
+    edit isn't localized enough to pay off — the caller falls back to the
+    full (debounced) diff."""
+    old_lines = old_text.split("\n")
+    new_lines = new_text.split("\n")
+    old_count, new_count = len(old_lines), len(new_lines)
+    overlap = min(old_count, new_count)
+    common_head = 0
+    while (common_head < overlap
+           and old_lines[common_head] == new_lines[common_head]):
+        common_head += 1
+    if common_head == old_count and old_count == new_count:
+        return list(blocks)                    # identical diff
+    common_tail = 0
+    while (common_tail < overlap - common_head
+           and old_lines[old_count - 1 - common_tail]
+           == new_lines[new_count - 1 - common_tail]):
+        common_tail += 1
+    line_delta = new_count - old_count
+    window_start = max(0, common_head - 8)
+    window_end = min(old_count, old_count - common_tail + 8)
+    # Widen past any overlapping block (fixpoint - widening can reach the
+    # next block...).
+    grew = True
+    while grew:
+        grew = False
+        for n0, n1, _b0, _b1, _t in blocks:
+            if (n0 < window_end and n1 > window_start
+                    and (n0 < window_start or n1 > window_end)):
+                window_start = min(window_start, n0)
+                window_end = max(window_end, n1)
+                grew = True
+    if (window_end - window_start) > 0.5 * max(old_count, 1):
+        return None                            # not localized - full diff
+    before, inside, after = [], [], []
+    for block in blocks:
+        if block[1] <= window_start:
+            before.append(block)
+        elif block[0] >= window_end:
+            after.append(block)
+        elif window_start <= block[0] and block[1] <= window_end:
+            inside.append(block)
+        else:
+            return None                        # straddler (shouldn't happen)
+    delta_before = sum((b1 - b0) - (n1 - n0)
+                       for n0, n1, b0, b1, _t in before)
+    delta_inside = sum((b1 - b0) - (n1 - n0)
+                       for n0, n1, b0, b1, _t in inside)
+    base_lines = base.split("\n")
+    base_start = window_start + delta_before
+    base_end = window_end + delta_before + delta_inside
+    if (not (0 <= base_start <= base_end <= len(base_lines))
+            or window_end + line_delta < window_start):
+        return None
+    matcher = difflib.SequenceMatcher(
+        a=base_lines[base_start:base_end],
+        b=new_lines[window_start:window_end + line_delta], autojunk=False)
+    local = [(window_start + j1, window_start + j2,
+              base_start + i1, base_start + i2, tag)
+             for tag, i1, i2, j1, j2 in matcher.get_opcodes() if tag != "equal"]
+    return (before + local
+            + [(n0 + line_delta, n1 + line_delta, b0, b1, t)
+               for n0, n1, b0, b1, t in after])
+
+
+def _diff_disp_span(pane, l0, l1):
+    """Half-open buffer line range -> half-open display line range. A range
+    swallowed by a collapsed fold collapses onto the fold header's row, so
+    its wash/ribbon lands on the collapse line (IntelliJ-style)."""
+    d2b = getattr(pane, "_diff_d2b", None)
+    if d2b is None:
+        return l0, l1
+    d0 = max(bisect.bisect_right(d2b, int(l0)) - 1, 0)
+    if l1 <= l0:
+        return d0, d0
+    d1 = max(bisect.bisect_right(d2b, int(l1) - 1) - 1, 0) + 1
+    return d0, max(d1, d0)
+

meltygui/editor/external_changes.py

@@ -0,0 +1,159 @@
+"""External Changes window — the outside-in twin of draw_pending_saves.
+
+PendingSave tracks edits made IN the studio that haven't reached disk yet;
+ExternalChanges tracks edits made OUTSIDE the studio that have. FileWatch
+already sees every fs event in the watched dirs — _on_event hands each one
+here together with the pre-change code_cache text, which becomes the diff
+baseline. Current text is never stored: the watcher pops code_cache on every
+change, so Melty.read_code at render time is both fresh and cheap.
+"""
+
+import difflib
+from pathlib import Path
+
+from meltygui.core.rendering.render_funcs import RenderFuncs
+from meltygui.core.windowing.glfw_utils import request_render
+from meltygui.core.core_render import render_func
+from meltygui.core.rendering.window_decoration import window
+from meltygui.editor.pending_save import _diff_lines_with_numbers
+
+
+class ExternalChanges:
+    # resolved path (str) → file text BEFORE the first recorded change
+    # This is setdefault-only: later events on the same file keep the same
+    # baseline, so the window shows the accumulated drift since the studio
+    # last opened the file - not just the latest write.
+    originals = {}
+    _window_ds = None   # draw_external_changes' draw_state - the wake target
+    # path → (id(baseline), id(disk text)) stamped when a recompile absorbed
+    # this exact drift into the pending queue (PendingSave.resolve_external).
+    # Absorbing must not hide the entry - the window keeps showing what an
+    # external program changed until the user dismisses it. The marker only
+    # stops re-processing: absorb skips the file while the ids still match,
+    # and find_conflicts won't call the absorbed drift a conflict. Both ids
+    # are content-free change signals (baseline is setdefault-once; the
+    # watcher pops code_cache on every write, so a NEW external edit yields a
+    # new disk object and the marker naturally expires).
+    absorbed = {}
+    # path → disk text the last absorb was computed against (the SYNC frame).
+    # `originals` is display-only accumulation (setdefault-once, kept until the
+    # user dismisses); merging must diff from the last text the pending queue
+    # and live co_firstlineno's were rebased to - after an absorb that is the
+    # absorbed disk, not the original baseline. Diffing new drift from the old
+    # baseline would re-apply already-absorbed hunks (false lineno shifts,
+    # phantom conflicts). Falls back to `originals` before the first absorb.
+    synced = {}
+
+    @classmethod
+    def on_file_event(cls, src_path, old_text):
+        """Called from FileWatch._on_event (observer thread) for every fs
+        event, with the code_cache text as it was BEFORE the event popped it.
+        old_text=None means the studio never read the file — nothing to
+        baseline against, so it isn't tracked."""
+        from meltygui.core.melty import FileWatch
+        from meltygui.core.melty import Melty
+        if FileWatch.is_self_write(src_path):
+            return              # an in-process save, not an outside program
+        # An external write obsoletes any cached NO-OP pending edits for this
+        # file (data == load-time original): they'd shadow the new disk
+        # content on every span reload. Before the old_text gate - the queue
+        # must clear even for a file the studio never cached. Hopped to the
+        # render thread; frame time invalidates the queue.
+        from meltygui.editor.pending_save import PendingSave
+        Melty.post_to_render(lambda p=src_path: PendingSave.drop_noop_entries_for(p))
+        if old_text is None:
+            return
+        try:
+            resolved = str(Path(src_path).resolve())
+        except OSError:
+            return
+        cls.originals.setdefault(resolved, old_text)
+        # Same wake mechanism as FileWatch.dispatch_event_for: the flag makes
+        # core_render skip the blit cache for the window's next pass, so the
+        # new diff actually renders instead of replaying a stale tile.
+        ds = cls._window_ds
+        if ds is not None:
+            ds._external_change = True
+        # The conflict window shares the same edge: external drift may now
+        # overlap a pending span. Lazy import (merge_files imports this module).
+        try:
+            from meltygui.core.runtime.extensions import call
+            call('conflicts_changed')
+        except Exception:
+            pass
+        request_render()
+
+    @classmethod
+    def dismiss_all(cls):
+        cls.originals.clear()
+        cls.absorbed.clear()
+        cls.synced.clear()
+
+    @classmethod
+    def untrack(cls, path):
+        """Drop every record for `path` — dismissals and drift-back heals.
+        The next external event re-baselines from whatever the cache holds
+        then, so a stale sync frame must never outlive its originals entry."""
+        cls.originals.pop(path, None)
+        cls.absorbed.pop(path, None)
+        cls.synced.pop(path, None)
+
+    @classmethod
+    def mark_absorbed(cls, path, disk_text):
+        """Record that the CURRENT drift of `path` (baseline → `disk_text`,
+        the held read_code object) has been folded into the pending queue."""
+        baseline = cls.originals.get(path)
+        if baseline is not None:
+            cls.absorbed[path] = (id(baseline), id(disk_text))
+        # The sync point moved with this absorb: the merge window's original
+        # world (symbol_roster.World over synced/originals) re-keys on it.
+        try:
+            from meltygui.code.symbol_roster import bump_disk_generation
+            bump_disk_generation()
+        except Exception:
+            pass
+
+    @classmethod
+    def is_absorbed(cls, path, disk_text):
+        """True while `path`'s tracked drift is exactly the one a recompile
+        already absorbed — expires the moment either side changes object."""
+        baseline = cls.originals.get(path)
+        return (baseline is not None
+                and cls.absorbed.get(path) == (id(baseline), id(disk_text)))
+
+    @classmethod
+    def recompile_all(cls):
+        """External changes are no longer hotswapped directly from here (the
+        raw whole-module reload bypassed the pending machinery and caused
+        stale-tile invalidation issues). Delegate to the Pending Saves window:
+        PendingSave.recompile_all hotswaps the pending queue through the
+        established per-entry path — external drift is NOT absorbed; it is
+        merged manually via the merge window. recompile_all_ui drives
+        the Pending Saves button's own runner draw_state (busy spinner,
+        fading check mark + summary), so any caller of this alias gets the
+        exact button-click UI. Kept for backward compatibility — the MCP
+        recompile tool now calls PendingSave.recompile_all_ui directly."""
+        from meltygui.editor.pending_save import PendingSave
+        return PendingSave.recompile_all_ui()
+
+
+# Hotswap / dual-identity guard. A hotswap re-executes this module — under the
+# BARE 'lsd....' name, while meltygui's _on_event hook imports the 'src.lsd....' one -
+# so without this the window body and the event feed end up on two different
+# ExternalChanges classes (split-brain: events land in a dict the window never
+# reads). Alias the mutable state from whichever twin is already loaded, so
+# every identity shares ONE originals dict and a hotswap never wipes the queue.
+import sys as _sys
+for _n in ("meltygui.editor.external_changes",
+           "lsd.gl_gui.view.core_views.external_changes"):
+    _twin = getattr(_sys.modules.get(_n), "ExternalChanges", None)
+    if _twin is not None and _twin is not ExternalChanges:
+        ExternalChanges.originals = _twin.originals
+        ExternalChanges._window_ds = _twin._window_ds
+        ExternalChanges.absorbed = getattr(_twin, "absorbed", ExternalChanges.absorbed)
+        ExternalChanges.synced = getattr(_twin, "synced", ExternalChanges.synced)
+        break
+
+
+from meltygui.view.file_view import draw_external_changes
+draw_external_changes = window(disable_scroll=False, tint=(0.16296297311782837, 0.212430558282882, 0.2611111), icon=None)(draw_external_changes)

meltygui/editor/file_header.py

@@ -0,0 +1,41 @@
+"""File labels shared by the file UI and chat change summaries."""
+from pathlib import Path
+import meltygui_imgui as imgui
+from meltygui.core.melty import Melty
+from meltygui.core.runtime.toggles import Toggles, Tint
+from meltygui.hdr_color import pack_color
+from meltygui.core.cache.tile_cache import add_shadow
+from meltygui.editor.source_ui import _tab_text_color
+
+_ELLIPSIZE_MEMO = globals().get("_ELLIPSIZE_MEMO", {})
+
+
+def _ellipsize_search(text, max_width):
+    low, high = 0, len(text)
+    while low < high:
+        mid = (low + high + 1) // 2
+        if imgui.calc_text_size(text[:mid] + "\u2026").x <= max_width:
+            low = mid
+        else:
+            high = mid - 1
+    return text[:low].rstrip() + "\u2026"
+
+
+def _ellipsize(text, max_width):
+    """`text` cut to fit `max_width` pixels in the current font with a
+    trailing ellipsis; unchanged when it already fits."""
+    # Memoized per (text, width, font scale): the commit-file column runs
+    # this for each row every frame, and each miss is a calc_text_size
+    # binary search.
+    memo_key = (text, max_width, Melty.ui_scale)
+    hit = _ELLIPSIZE_MEMO.get(memo_key)
+    if hit is not None:
+        return hit
+    if max_width <= 0 or imgui.calc_text_size(text).x <= max_width:
+        result = text
+    else:
+        result = _ellipsize_search(text, max_width)
+    if len(_ELLIPSIZE_MEMO) > 4096:
+        _ELLIPSIZE_MEMO.clear()
+    _ELLIPSIZE_MEMO[memo_key] = result
+    return result

meltygui/editor/live_usage.py

@@ -0,0 +1,169 @@
+"""Display-time USAGE index for live values.
+
+A usage of a captured symbol is never captured and never holds the value:
+`build_usage_index` maps each occurrence of a bound name inside an
+instrumented def to its position, and the paint pass (live_view_views.
+_draw_usage_labels) resolves the governing BINDING at draw time and reads
+that binding's single store entry by reference. Nothing runs in the user's
+function for usages, and the only derived data is the formatted label.
+
+stdlib-only (tokenize) on purpose: exact word boundaries, and string/comment
+interiors are excluded for free. The index is rebuilt only when the parse
+source changes or the store's key set grows (the caller memoizes) — never
+per frame.
+"""
+
+import bisect
+import io
+import keyword
+import tokenize
+
+# A NAME right after one of these is never a value usage: definitions,
+# import aliases, loop/with/except binding targets, lambda params,
+# attribute access.
+_SKIP_AFTER = frozenset((
+    "def", "class", "import", "from", "as", "global", "nonlocal",
+    "for", "lambda", "."))
+
+_OPEN_BRACKETS = frozenset("([{")
+_CLOSE_BRACKETS = frozenset(")]}")
+_SKIP_TOKEN_TYPES = frozenset((
+    tokenize.NL, tokenize.NEWLINE, tokenize.INDENT, tokenize.DEDENT,
+    tokenize.COMMENT, tokenize.ENCODING, tokenize.ENDMARKER))
+
+
+def binding_name(key_path, labels):
+    """The SYMBOL a store key binds — its label when that's a plain
+    identifier, else the name encoded in the key tail ('x', 'x#1',
+    'line:N#x'). None for keys that don't name a symbol (call-site keys
+    like 'live_view()#1', expression labels, keyword tails)."""
+    label = (labels or {}).get(key_path)
+    if isinstance(label, str) and label.isidentifier() \
+            and not keyword.iskeyword(label):
+        return label
+    tail = key_path[-1] if key_path else None
+    if not isinstance(tail, str):
+        return None
+    if tail.startswith("line:"):
+        name = tail.partition("#")[2]
+    else:
+        name = tail.partition("#")[0]
+    if name.isidentifier() and not keyword.iskeyword(name):
+        return name
+    return None
+
+
+def _next_significant(tokens, i):
+    """The next token past NL/comment/indent noise, else None."""
+    for j in range(i + 1, len(tokens)):
+        if tokens[j][0] not in _SKIP_TOKEN_TYPES:
+            return tokens[j]
+    return None
+
+
+def build_usage_index(def_text, first_line, binding_lines, exclude_ranges=()):
+    """Occurrences of the bound names inside one def's source.
+
+    `def_text` is the def's source slice (its `def` line first), sitting at
+    parse line `first_line`; `binding_lines` maps name → SORTED parse lines
+    of that name's binding sites (from the store's anchors);
+    `exclude_ranges` are (lo, hi) parse-line ranges to skip — nested def
+    bodies, where an occurrence is the closure's own scope, not a value
+    read of the outer binding.
+
+    Returns [(parse_line, col, name, last_on_line), …] sorted by position:
+    every NAME token equal to a bound name that is a genuine USE — not an
+    attribute (`.name`), not a keyword argument (`name=` inside brackets),
+    not a binding/definition target (first occurrence of the name on one
+    of its own binding lines, or a NAME right after def/for/as/…), and
+    only with at least one binding textually ABOVE it (same-line bindings
+    govern nothing on their own line: in `x = x + 1` the RHS x reads the
+    previous binding). `last_on_line` is True when no further CODE token
+    follows on the occurrence's line (comments don't count) — the pill may
+    then run past the symbol's width, since there's nothing to cover."""
+    out = []
+    # The slice keeps the module's indentation; tokenize likes column-0
+    # code, so strip the first line's indent from every line that carries it
+    # and tack it back onto the reported columns. Lines that don't start
+    # with it live inside multi-line strings - the tokenizer consumes those
+    # as part of the STRING token, so leaving them untouched is fine.
+    lines = def_text.split("\n")
+    indent = len(lines[0]) - len(lines[0].lstrip()) if lines else 0
+    if indent:
+        pad = " " * indent
+        lines = [l[indent:] if l.startswith(pad) else l for l in lines]
+        def_text = "\n".join(lines)
+    try:
+        tokens = list(tokenize.generate_tokens(io.StringIO(def_text).readline))
+    except (tokenize.TokenError, IndentationError, SyntaxError):
+        return out
+    previous = None            # last significant token string
+    depth = 0                  # bracket depth, for the kwarg test
+    seen_on_line = set()       # (line, name) - binding-target skip
+    for i, tok in enumerate(tokens):
+        token_type, string, start = tok[0], tok[1], tok[2]
+        if token_type in _SKIP_TOKEN_TYPES:
+            continue
+        if token_type == tokenize.OP:
+            if string in _OPEN_BRACKETS:
+                depth += 1
+            elif string in _CLOSE_BRACKETS:
+                depth = max(0, depth - 1)
+            previous = string
+            continue
+        if token_type != tokenize.NAME:
+            previous = string
+            continue
+        name = string
+        line = first_line - 1 + start[0]
+        col = start[1] + indent
+        skip_after = previous in _SKIP_AFTER
+        previous = name
+        binding_list = binding_lines.get(name)
+        if not binding_list or skip_after or keyword.iskeyword(name):
+            continue
+        if any(lo <= line <= hi for lo, hi in exclude_ranges):
+            continue
+        # Keyword argument: `f(name=...)` names the call's parameter, not
+        # this local - a bare `=` (never `==`) inside brackets.
+        if depth > 0:
+            nxt = _next_significant(tokens, i)
+            if nxt is not None and nxt[0] == tokenize.OP and nxt[1] == "=":
+                continue
+        # Binding target: the FIRST occurrence of the name on one of its
+        # own binding lines is the assignment's left side; later ones on
+        # the same line (`x = x + 1`) are reads of the previous binding.
+        first_on_line = (line, name) not in seen_on_line
+        seen_on_line.add((line, name))
+        if first_on_line and _in_sorted(binding_list, line):
+            continue
+        if bisect.bisect_left(binding_list, line) == 0:
+            continue          # nothing bound above - nothing to show
+        nxt = _next_significant(tokens, i)
+        last_on_line = nxt is None or nxt[2][0] > start[0]
+        out.append((line, col, name, last_on_line))
+    return out
+
+
+def _in_sorted(sorted_lines, line):
+    ix = bisect.bisect_left(sorted_lines, line)
+    return ix < len(sorted_lines) and sorted_lines[ix] == line
+
+
+def governing_key(binding_lines, binding_keys, line, publish_seq):
+    """The store key a usage at parse `line` reads: among this name's
+    bindings textually ABOVE the line, the one that PUBLISHED last
+    (`publish_seq`: key → monotonic publish counter — the branch-not-taken
+    rule: the textually-later `else:` binding loses to the `if:` binding
+    that actually ran). Unpublished/unknown keys rank below every published
+    one; ties (no seq data at all) fall back to textual order — the latest
+    binding above wins. None when no binding sits above the line."""
+    ix = bisect.bisect_left(binding_lines, line)
+    best = None
+    best_rank = None
+    for j in range(ix):
+        key = binding_keys[j]
+        rank = (publish_seq.get(key, -1), j)
+        if best_rank is None or rank > best_rank:
+            best, best_rank = key, rank
+    return best