loop-autopsy 0.1.0__py3-none-any.whl

loop_autopsy/__init__.py

@@ -0,0 +1,57 @@
+"""loop-autopsy: stops runaway loops in Jupyter and shows the evidence for why
+they never ended.
+
+Usage in a notebook::
+
+    %load_ext loop_autopsy
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .config import Finding, LoopStopped, Settings  # noqa: F401
+
+_LOADED: dict = {}
+
+
+def load_ipython_extension(ip) -> None:
+    from .heatmap import CellHealth
+    from .magics import AutopsyMagics
+    from .monitor import Monitor
+    from .report import display_report
+    from .transformer import RUNTIME_NAME, LoopTransformer
+
+    if id(ip) in _LOADED:
+        print("loop-autopsy is already loaded. Use %autopsy help for options.")
+        return
+    settings = Settings()
+    monitor = Monitor(ip, settings)
+    transformer = LoopTransformer(monitor.register, lambda: settings.max_watched, monitor.is_paused)
+    health = CellHealth(ip, settings, monitor.stats, show=display_report)
+
+    ip.user_ns[RUNTIME_NAME] = monitor
+    ip.user_ns_hidden[RUNTIME_NAME] = monitor  # keep it out of %who / %whos
+    ip.ast_transformers.append(transformer)
+    ip.events.register("pre_run_cell", monitor.pre_run_cell)
+    health.register()
+    monitor.install_exception_handler()
+    ip.register_magics(AutopsyMagics(ip, monitor))
+    _LOADED[id(ip)] = (monitor, transformer, health)
+    print(f"loop-autopsy {__version__} is watching your loops. Type %autopsy help for options.")
+
+
+def unload_ipython_extension(ip) -> None:
+    entry = _LOADED.pop(id(ip), None)
+    if entry is None:
+        return
+    monitor, transformer, health = entry
+    monitor.enabled = False  # functions instrumented earlier keep working, unwatched
+    if transformer in ip.ast_transformers:
+        ip.ast_transformers.remove(transformer)
+    try:
+        ip.events.unregister("pre_run_cell", monitor.pre_run_cell)
+    except ValueError:
+        pass
+    health.unregister()
+    monitor.remove_exception_handler()

loop_autopsy/config.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field, fields
+from typing import Any, Optional, Tuple
+
+
+class LoopStopped(BaseException):
+    """Raised inside a watched loop to stop it.
+
+    It derives from BaseException (like KeyboardInterrupt) so that a normal
+    ``except Exception:`` block inside the student's loop cannot swallow it.
+    """
+
+    def __init__(self, finding: "Finding"):
+        super().__init__(finding.title)
+        self.finding = finding
+
+
+@dataclass
+class Finding:
+    """What a detection rule proved about a loop."""
+
+    kind: str  # stuck | cycle | wrong_direction | jumped_over | growing_iterable | memory | time_limit
+    title: str
+    explanation: str
+    hint: str
+    culprits: Tuple[str, ...] = ()
+
+
+@dataclass
+class LoopInfo:
+    """Static facts about one loop, collected when the cell is transformed."""
+
+    loop_id: int
+    kind: str  # "while" | "for"
+    lineno: int
+    header: str
+    test_src: str = ""
+    cond_names: Tuple[str, ...] = ()
+    watched: Tuple[str, ...] = ()
+    compare: Optional[tuple] = None  # (left, op, right); side = ("name", n) | ("const", v)
+    iter_name: Optional[str] = None
+    receivers: Tuple[str, ...] = ()  # names used as ``name.method(...)``; checked at run time
+    repeat_safe: bool = True
+    waits_for_user: bool = False
+
+
+@dataclass
+class LoopState:
+    """Run-time record of one execution of a loop."""
+
+    info: LoopInfo
+    started: float
+    replay_rows: int = 6
+    rounds: int = 0
+    checks: int = 0
+    stride: int = 1
+    next_check: int = 1
+    last_check: float = 0.0
+    history: deque = field(default_factory=deque)
+    scratch: dict = field(default_factory=dict)
+    stopped: Optional[Finding] = None
+
+    def __post_init__(self):
+        self.history = deque(maxlen=max(1, self.replay_rows))
+        self.last_check = self.started
+
+
+@dataclass
+class Settings:
+    """User-adjustable settings (``%autopsy config key=value``)."""
+
+    time_limit: float = 60.0
+    direction_after: int = 500
+    jump_after: int = 100
+    growth_after: int = 2000
+    memory_stop: float = 0.85
+    memory_warn: float = 0.75
+    max_output_lines: int = 1000
+    replay_rows: int = 6
+    max_watched: int = 25
+    heatmap: str = "auto"  # on | off | auto
+    time_yellow: float = 1.0
+    time_red: float = 10.0
+    mem_yellow: float = 0.50
+    mem_red: float = 0.80
+
+    def update(self, key: str, raw: str) -> Any:
+        """Set ``key`` from a string such as ``"30"``; returns the new value."""
+        names = {f.name: f for f in fields(self)}
+        if key not in names:
+            raise KeyError(f"unknown setting {key!r}; choose from: {', '.join(names)}")
+        current = getattr(self, key)
+        if isinstance(current, str):
+            value: Any = raw.strip().strip("'\"").lower()
+            if key == "heatmap" and value not in ("on", "off", "auto"):
+                raise ValueError("heatmap must be on, off or auto")
+        elif isinstance(current, int) and not isinstance(current, bool):
+            value = int(float(raw))
+        else:
+            value = float(raw)
+        if isinstance(value, (int, float)) and value < 0:
+            raise ValueError(f"{key} cannot be negative")
+        setattr(self, key, value)
+        return value
+
+    def as_dict(self) -> dict:
+        return {f.name: getattr(self, f.name) for f in fields(self)}

loop_autopsy/detectors.py

@@ -0,0 +1,279 @@
+"""
+Each ``check_*`` function receives the loop's static ``LoopInfo``, its run-time
+``LoopState`` and ``values`` (the watched variables right now) and returns a
+``Finding`` when it can prove the loop will not end, otherwise ``None``.
+Private bookkeeping lives in ``state.scratch``.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from decimal import Decimal
+from fractions import Fraction
+from typing import Any, Dict, Optional
+
+from .config import Finding, LoopInfo, LoopState, Settings
+
+OPAQUE = object()  # "cannot see inside this value"
+SCALARS = (bool, int, float, complex, Fraction, Decimal)
+SMALL = 50  # containers up to this size are fingerprinted by content
+MAX_STORED = 50_000  # fingerprints kept per loop run
+FULL_BUDGET = 1_000_000  # elements visited by one full fingerprint
+# Methods on these types only change the object itself, which is fingerprinted.
+BUILTIN_RECEIVERS = (str, bytes, list, dict, set, frozenset, tuple, deque, bytearray, int, float, complex)
+
+
+# --------------------------------------------------------------------------- fingerprints
+def cheap_fp(value: Any, depth: int = 0) -> Any:
+    """Fast fingerprint. Equal states always give equal results; different
+    states *may* collide, which the full fingerprint then rules out."""
+    t = type(value)
+    if value is None or t in SCALARS:
+        return value
+    if t in (str, bytes):
+        return value if len(value) <= 64 else (t.__name__, len(value), hash(value))
+    if t is range:
+        return ("range", value.start, value.stop, value.step)
+    if depth >= 3:
+        return (t.__name__, id(value)) if t in (list, dict, set, deque, bytearray, tuple, frozenset) else OPAQUE
+    if t in (tuple, frozenset, list, set, deque, bytearray) and len(value) <= SMALL:
+        parts = tuple(cheap_fp(x, depth + 1) for x in value)
+        if any(p is OPAQUE for p in parts):
+            return OPAQUE
+        return (t.__name__, id(value) if t not in (tuple, frozenset) else 0) + parts
+    if t is dict and len(value) <= SMALL:
+        parts = tuple((cheap_fp(k, depth + 1), cheap_fp(v, depth + 1)) for k, v in value.items())
+        if any(p is OPAQUE for pair in parts for p in pair):
+            return OPAQUE
+        return ("dict", id(value)) + parts
+    if t in (tuple, frozenset, list, set, deque, bytearray, dict):
+        return (t.__name__, id(value), len(value))
+    return OPAQUE
+
+
+def full_fp(value: Any, budget: Optional[list] = None, depth: int = 0) -> Any:
+    """Complete, content-based fingerprint (hashable), or OPAQUE."""
+    if budget is None:
+        budget = [FULL_BUDGET]
+    t = type(value)
+    if value is None or t in SCALARS or t in (str, bytes):
+        return value
+    if t is range:
+        return ("range", value.start, value.stop, value.step)
+    if depth > 20:
+        return OPAQUE  # e.g. a list that contains itself
+    if t in (list, tuple, deque, bytearray, set, frozenset, dict):
+        budget[0] -= len(value)
+        if budget[0] < 0:
+            return OPAQUE
+        if t is dict:
+            parts = []
+            for k, v in value.items():
+                fk, fv = full_fp(k, budget, depth + 1), full_fp(v, budget, depth + 1)
+                if fk is OPAQUE or fv is OPAQUE:
+                    return OPAQUE
+                parts.append((fk, fv))
+            return ("dict", tuple(parts))
+        parts = []
+        for x in value:
+            fx = full_fp(x, budget, depth + 1)
+            if fx is OPAQUE:
+                return OPAQUE
+            parts.append(fx)
+        if t in (set, frozenset):
+            return (t.__name__, frozenset(parts))
+        return (t.__name__, tuple(parts))
+    return OPAQUE
+
+
+def _show(value: Any, width: int = 40) -> str:
+    text = repr(value)
+    return text if len(text) <= width else text[: width - 3] + "..."
+
+
+def _numeric(x: Any) -> bool:
+    return isinstance(x, (int, float, Fraction, Decimal)) and not isinstance(x, bool)
+
+
+# --------------------------------------------------------------------------- R1 / R2
+def check_repeat(info: LoopInfo, state: LoopState, values: Dict[str, Any]) -> Optional[Finding]:
+    """R1 stuck / R2 cycle: the loop returned to an exact earlier state."""
+    s = state.scratch
+    if info.kind != "while" or not info.repeat_safe or s.get("rep_off"):
+        return None
+    for name in info.receivers:  # e.g. random.random(): hidden state, cannot prove anything
+        if type(values.get(name, OPAQUE)) not in BUILTIN_RECEIVERS:
+            s["rep_off"] = "calls"
+            return None
+    cheap = []
+    for name, value in values.items():
+        fp = cheap_fp(value)
+        if fp is OPAQUE:
+            s["rep_off"] = True
+            return None
+        cheap.append((name, fp))
+    try:
+        key = hash(tuple(cheap))
+    except TypeError:
+        s["rep_off"] = True
+        return None
+    seen = s.setdefault("rep_seen", {})
+    if key not in seen:
+        if len(seen) < MAX_STORED:
+            seen[key] = state.rounds
+        return None
+
+    full = tuple((n, full_fp(v)) for n, v in values.items())
+    if any(fp is OPAQUE for _, fp in full):
+        s["rep_off"] = True
+        return None
+    try:
+        fkey = hash(full)
+    except TypeError:
+        s["rep_off"] = True
+        return None
+    full_seen = s.setdefault("rep_full", {})
+    if fkey not in full_seen:
+        if len(full_seen) < MAX_STORED:
+            full_seen[fkey] = state.rounds
+        return None
+
+    if state.stride > 1:
+        # Sampled checks cannot tell the exact cycle length: re-measure every round.
+        s["rep_refine"] = True
+        state.stride = 1
+        state.next_check = state.rounds + 1
+        s["rep_seen"], s["rep_full"] = {}, {}
+        return None
+    distance = state.rounds - full_seen[fkey]
+    return _stuck_finding(info, values) if distance <= 1 else _cycle_finding(info, values, distance)
+
+
+def _cond_values(info: LoopInfo, values: Dict[str, Any]) -> str:
+    return ", ".join(f"`{n} = {_show(values[n])}`" for n in info.cond_names if n in values)
+
+
+def _stuck_finding(info: LoopInfo, values: Dict[str, Any]) -> Finding:
+    cond = info.test_src or "True"
+    if info.cond_names:
+        names = ", ".join(f"`{n}`" for n in info.cond_names)
+        explanation = (
+            f"Nothing changed between rounds: {_cond_values(info, values)} stayed exactly the same, "
+            f"so the condition `{cond}` is True every time and the loop can never end."
+        )
+        example = ""
+        if info.compare and info.compare[0][0] == "name":
+            var, op = info.compare[0][1], info.compare[1]
+            if op in ("<", "<="):
+                example = f" (for example `{var} += 1`)"
+            elif op in (">", ">="):
+                example = f" (for example `{var} -= 1`)"
+        hint = f"Add a line inside the loop that changes {names} so that `{cond}` eventually becomes False{example}."
+    else:
+        explanation = (
+            f"The condition `{cond}` never changes and nothing inside the loop changes either, "
+            f"so every round is identical and no `break` is ever reached."
+        )
+        hint = "Add a `break` that runs when the work is done, or use a condition that can become False."
+    return Finding("stuck", "stuck loop", explanation, hint, tuple(info.cond_names))
+
+
+def _cycle_finding(info: LoopInfo, values: Dict[str, Any], k: int) -> Finding:
+    cond = info.test_src or "True"
+    shown = _cond_values(info, values)
+    explanation = (
+        f"Every {k} rounds the loop comes back to exactly the same values"
+        f"{' (' + shown + ')' if shown else ''}. "
+        f"Nothing else can change them, so it will repeat this {k}-round cycle forever."
+    )
+    hint = f"Look at the replay table: the values go round in a circle instead of moving towards making `{cond}` False."
+    return Finding("cycle", f"loop stuck in a {k}-round cycle", explanation, hint, tuple(info.cond_names))
+
+
+# --------------------------------------------------------------------------- R3 / R4
+def _side_value(side, values):
+    kind, data = side
+    return data if kind == "const" else values.get(data)
+
+
+def check_direction(info: LoopInfo, state: LoopState, values: Dict[str, Any],
+                    settings: Settings) -> Optional[Finding]:
+    """R3 wrong direction and R4 jumped over, for simple comparisons."""
+    if info.kind != "while" or not info.compare:
+        return None
+    left, op, right = info.compare
+    a, b = _side_value(left, values), _side_value(right, values)
+    if not (_numeric(a) and _numeric(b)):
+        return None
+    s = state.scratch
+    moving = left if left[0] == "name" else right  # the variable side we talk about
+    var = moving[1]
+    target = b if moving is left else a
+    now_val = values.get(var)
+
+    if op == "!=":
+        gap = b - a
+        prev = s.get("jump_prev")
+        if prev is not None and (prev > 0) != (gap > 0):
+            s["jump_crossed"] = (s.get("jump_prev_val"), now_val)
+            s["jump_streak"] = 0
+        elif s.get("jump_crossed") and prev is not None and abs(gap) > abs(prev):
+            s["jump_streak"] = s.get("jump_streak", 0) + 1
+        elif s.get("jump_crossed"):
+            s["jump_streak"] = 0
+        s["jump_prev"], s["jump_prev_val"] = gap, now_val
+        if s.get("jump_crossed") and s.get("jump_streak", 0) >= settings.jump_after:
+            before, after = s["jump_crossed"]
+            return Finding(
+                "jumped_over", "loop jumped over its stop value",
+                f"`{info.test_src}` only becomes False when `{var}` is exactly {_show(target)}. "
+                f"`{var}` went from {_show(before)} to {_show(after)}, jumping over {_show(target)}, "
+                f"and has moved further away ever since (now {_show(now_val)}).",
+                f"Use `<` or `>` instead of `!=` in the condition, or change the step so `{var}` "
+                f"lands exactly on {_show(target)}.",
+                (var,),
+            )
+        return None
+
+    gap = (b - a) if op in ("<", "<=") else (a - b)
+    prev = s.get("dir_prev")
+    if prev is not None and gap > prev:
+        if s.get("dir_streak", 0) == 0:
+            s["dir_start"] = s.get("dir_prev_val")
+        s["dir_streak"] = s.get("dir_streak", 0) + 1
+    else:
+        s["dir_streak"] = 0
+    s["dir_prev"], s["dir_prev_val"] = gap, now_val
+    if s.get("dir_streak", 0) >= settings.direction_after:
+        return Finding(
+            "wrong_direction", "loop moving the wrong way",
+            f"The loop stops when `{info.test_src}` becomes False, which needs `{var}` to reach {_show(target)}. "
+            f"But over the last {s['dir_streak']:,} checks `{var}` went from {_show(s.get('dir_start'))} "
+            f"to {_show(now_val)}, moving further away from {_show(target)} every time.",
+            f"Check the line that updates `{var}`: should it go the other way (for example `+=` instead of `-=`)?",
+            (var,),
+        )
+    return None
+
+
+# --------------------------------------------------------------------------- R7
+def check_time(info: LoopInfo, state: LoopState, settings: Settings, now: float) -> Optional[Finding]:
+    """R7: honest fallback when nothing could be proven."""
+    if settings.time_limit <= 0 or info.waits_for_user:
+        return None
+    elapsed = now - state.started
+    if elapsed < settings.time_limit:
+        return None
+    reason = ""
+    off = state.scratch.get("rep_off")
+    if info.kind == "while" and (not info.repeat_safe or off == "calls"):
+        reason = " (it calls functions whose effects loop-autopsy cannot check)"
+    elif info.kind == "while" and off:
+        reason = " (it uses values loop-autopsy cannot look inside)"
+    return Finding(
+        "time_limit", "loop ran too long",
+        f"This loop has been running for {elapsed:.0f} s ({state.rounds:,} rounds). loop-autopsy could not prove "
+        f"that it is stuck{reason}. It might just be slow, or stuck in a way the rules cannot see.",
+        "Use the replay table to see whether the values move towards the stop condition. "
+        f"To allow longer loops: `%autopsy config time_limit={int(settings.time_limit * 5)}`.",
+    )

loop_autopsy/growth.py

@@ -0,0 +1,204 @@
+"""Memory helpers and rules R5 (growing iterable) and R6 (memory).
+
+No third-party dependency is required; psutil is used only if installed.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+from .config import Finding, LoopInfo, LoopState, Settings
+
+_UNLIMITED = 1 << 60  # cgroup files use huge numbers for "no limit"
+_limit_cache: List[Optional[int]] = []
+
+
+# --------------------------------------------------------------------------- memory readings
+def format_bytes(n: Optional[float]) -> str:
+    if n is None:
+        return "?"
+    n = float(n)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if abs(n) < 1024 or unit == "TB":
+            return f"{n:.0f} {unit}" if unit in ("B", "KB") else f"{n:.1f} {unit}"
+        n /= 1024
+    return f"{n:.1f} TB"  # pragma: no cover
+
+
+def _read_int(path: str) -> Optional[int]:
+    try:
+        with open(path) as f:
+            text = f.read().strip()
+        return None if text in ("", "max") else int(text)
+    except (OSError, ValueError):
+        return None
+
+
+def memory_limit(refresh: bool = False) -> Optional[int]:
+    """Bytes this kernel may use: MEM_LIMIT -> cgroup v2 -> cgroup v1 -> physical RAM."""
+    if _limit_cache and not refresh:
+        return _limit_cache[0]
+    limit: Optional[int] = None
+    env = os.environ.get("MEM_LIMIT")
+    if env:
+        try:
+            limit = int(float(env))
+        except ValueError:
+            limit = None
+    if limit is None:
+        for path in ("/sys/fs/cgroup/memory.max", "/sys/fs/cgroup/memory/memory.limit_in_bytes"):
+            value = _read_int(path)
+            if value and value < _UNLIMITED:
+                limit = value
+                break
+    if limit is None:
+        try:
+            import psutil  # type: ignore
+
+            limit = int(psutil.virtual_memory().total)
+        except Exception:
+            try:
+                limit = os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES")
+            except (ValueError, OSError, AttributeError):
+                limit = None
+    _limit_cache[:] = [limit]
+    return limit
+
+
+def current_rss() -> Optional[int]:
+    """Resident memory of this process in bytes (best available method)."""
+    try:
+        with open("/proc/self/statm") as f:
+            pages = int(f.read().split()[1])
+        return pages * os.sysconf("SC_PAGE_SIZE")
+    except (OSError, ValueError, IndexError, AttributeError):
+        pass
+    try:
+        import psutil  # type: ignore
+
+        return int(psutil.Process().memory_info().rss)
+    except Exception:
+        pass
+    try:
+        import resource
+
+        peak = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+        return peak if sys.platform == "darwin" else peak * 1024
+    except Exception:  # pragma: no cover
+        return None
+
+
+def memory_fraction() -> Optional[float]:
+    rss, limit = current_rss(), memory_limit()
+    if not rss or not limit:
+        return None
+    return rss / limit
+
+
+# --------------------------------------------------------------------------- sizes
+def size_of(value: Any) -> int:
+    """Approximate bytes used by ``value`` (pandas / NumPy aware)."""
+    try:
+        if hasattr(value, "memory_usage") and callable(value.memory_usage):  # pandas
+            usage = value.memory_usage(deep=True)
+            return int(usage.sum() if hasattr(usage, "sum") else usage)
+        if hasattr(value, "nbytes") and isinstance(getattr(value, "nbytes"), int):  # NumPy
+            return int(value.nbytes)
+        base = sys.getsizeof(value)
+        if isinstance(value, (list, tuple, set, frozenset)) and value:
+            sample = list(value)[:1000] if not isinstance(value, (list, tuple)) else value[:1000]
+            per_item = sum(sys.getsizeof(x) for x in sample) / len(sample)
+            return int(base + per_item * len(value))
+        if isinstance(value, dict) and value:
+            items = list(value.items())[:1000]
+            per_item = sum(sys.getsizeof(k) + sys.getsizeof(v) for k, v in items) / len(items)
+            return int(base + per_item * len(value))
+        return base
+    except Exception:
+        return 0
+
+
+def largest_variables(namespace: Dict[str, Any], top: int = 3) -> List[Tuple[str, int]]:
+    """The ``top`` biggest user variables as ``(name, bytes)``."""
+    import types
+
+    sizes = []
+    for name, value in list(namespace.items()):
+        if name.startswith("_") or name in ("In", "Out", "exit", "quit", "get_ipython"):
+            continue
+        if isinstance(value, types.ModuleType) or callable(value):
+            continue
+        sizes.append((name, size_of(value)))
+    sizes.sort(key=lambda pair: pair[1], reverse=True)
+    return sizes[:top]
+
+
+def _lengths(values: Dict[str, Any]) -> Dict[str, int]:
+    out = {}
+    for name, value in values.items():
+        if isinstance(value, (list, dict, set, bytearray, str, bytes, tuple)) or hasattr(value, "__len__"):
+            try:
+                out[name] = len(value)
+            except Exception:
+                pass
+    return out
+
+
+def remember_start(state: LoopState, values: Dict[str, Any]) -> None:
+    """Called on the first check of a loop run: remember container sizes."""
+    state.scratch["len0"] = _lengths(values)
+
+
+# --------------------------------------------------------------------------- R5
+def check_growing_iterable(info: LoopInfo, state: LoopState, values: Dict[str, Any],
+                           settings: Settings) -> Optional[Finding]:
+    """R5: ``for x in items`` while ``items`` keeps growing."""
+    name = info.iter_name
+    if info.kind != "for" or not name or name not in values:
+        return None
+    try:
+        now = len(values[name])
+    except TypeError:
+        return None
+    start = state.scratch.get("len0", {}).get(name)
+    if start is None or state.rounds < settings.growth_after:
+        return None
+    grew = now - start
+    if grew >= 0.9 * state.rounds:
+        return Finding(
+            "growing_iterable", "loop over a list that keeps growing",
+            f"You are looping over `{name}` while adding to it. It started with {start:,} items and now has "
+            f"{now:,}: it grows as fast as the loop reads it, so the loop never reaches the end.",
+            f"Loop over a copy (`for ... in {name}[:]:`) or put new items in a separate list.",
+            (name,),
+        )
+    return None
+
+
+# --------------------------------------------------------------------------- R6
+def check_memory(info: LoopInfo, state: LoopState, values: Dict[str, Any],
+                 settings: Settings, fraction: Optional[float] = None) -> Optional[Finding]:
+    """R6: stop before the kernel runs out of memory."""
+    if fraction is None:
+        fraction = memory_fraction()
+    if fraction is None or fraction < settings.memory_stop:
+        return None
+    start = state.scratch.get("len0", {})
+    now = _lengths(values)
+    growth = sorted(((now[n] - start.get(n, 0), n) for n in now), reverse=True)
+    culprit = growth[0] if growth and growth[0][0] > 0 else None
+    limit = memory_limit()
+    detail = ""
+    if culprit:
+        grew, name = culprit
+        detail = f" `{name}` grew from {start.get(name, 0):,} to {now[name]:,} items during this loop."
+    return Finding(
+        "memory", "loop is running out of memory",
+        f"Memory is at {fraction:.0%} of your {format_bytes(limit)} limit.{detail} "
+        f"The kernel would crash soon, so the loop was stopped first.",
+        "If the loop should end, check its stop condition. If you really need all that data, "
+        "process it in smaller chunks instead of keeping everything in one list.",
+        (culprit[1],) if culprit else (),
+    )