dynamic-systems-testing-framework 1.0.1__py3-none-any.whl

dstf/authoring/tree_pointer.py

@@ -0,0 +1,33 @@
+"""A pointer into a raw metrics tree (``/metrics``, ``/metrics/children/0``,
+...), resolved to the node it names. UI-free: the builtins read a node
+through it to build their ops, and the Test page reads one to tell whether
+a form row's node moved and whether a criterion it is asked to reveal
+exists. The shell imports no builtin, so the one reader lives here."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def node_at(tree: dict, path: str) -> dict:
+    """The raw node at ``path``, a pointer whose first token names the tree
+    itself (``/metrics``, ``/metrics/children/0``, ...)."""
+    node: Any = tree
+    for token in [t for t in path.split("/") if t][1:]:
+        # A pointer alternates `children` (a key) and an index (into that
+        # list): consume each token as what it is.
+        node = node[int(token)] if token.isdigit() else node[token]
+    return node
+
+
+def node_or_none(tree: dict | None, path: str) -> dict | None:
+    """The node at ``path``, or ``None`` when the pointer names none of
+    ``tree`` — a stale selection, or one naming a raw key (``/metrics/
+    combinator`` resolves to a word, which is no node)."""
+    if tree is None:
+        return None
+    try:
+        node = node_at(tree, path)
+    except (KeyError, IndexError, TypeError, ValueError):
+        return None
+    return node if isinstance(node, dict) else None

dstf/authoring/tree_text.py

@@ -0,0 +1,61 @@
+"""What a tree node READS as. UI-free, so the Test page's rows and the
+Edit tree capability's form titles say the same thing: a form's title
+names its node the way the node's row does. Every function takes a
+`tree_view` node (``kind``, ``label``, ``path``), never a raw spec node."""
+
+from __future__ import annotations
+
+from ..reporting.tree_rows import leaves_of
+
+
+def nodes_of(view: dict | None) -> list[dict]:
+    """Every node of a `tree_view`, combinators included, in tree order."""
+    if view is None:
+        return []
+    return [view] + [
+        node for child in view.get("children") or [] for node in nodes_of(child)
+    ]
+
+
+def leaf_name(leaf: dict) -> str:
+    """``metric · label`` — what a criterion's row READS. The label is the
+    expression the model wrote for the variable (`nrmse · pipe.T[1]`), which
+    the tree view carries beside the `variable` a patch op targets; a
+    variable with no expression reads as its name, as it always did."""
+    return f"{leaf.get('metric')} · {leaf.get('label') or leaf.get('variable')}"
+
+
+def node_text(node: dict) -> str:
+    if node.get("kind") == "leaf":
+        return leaf_name(node)
+    n = len(leaves_of(node))
+    text = f"{node.get('combinator')} · {n} {'criterion' if n == 1 else 'criteria'}"
+    if node.get("combinator") == "k-of-n" and node.get("k") is not None:
+        text += f" · k={node['k']}"
+    if node.get("combinator") == "weighted" and node.get("threshold") is not None:
+        text += f" · threshold {node['threshold']:g}"
+    return text
+
+
+def count_text(node: dict) -> str:
+    """A combinator's row text while its kind is read from the dropdown
+    beside it: `node_text` without the kind — ``3 criteria``,
+    ``k=2 · 3 criteria``, ``threshold 0.5 · 3 criteria``."""
+    n = len(leaves_of(node))
+    parts = [f"{n} {'criterion' if n == 1 else 'criteria'}"]
+    if node.get("combinator") == "k-of-n" and node.get("k") is not None:
+        parts.insert(0, f"k={node['k']}")
+    if node.get("combinator") == "weighted" and node.get("threshold") is not None:
+        parts.insert(0, f"threshold {node['threshold']:g}")
+    return " · ".join(parts)
+
+
+def parent_kinds(view: dict | None) -> dict[str, str | None]:
+    """Each node's path -> its parent's combinator (None for the root):
+    what a leaf's `+` reads, since the parent takes the child it adds."""
+    kinds: dict[str, str | None] = {}
+    for node in nodes_of(view):
+        kinds.setdefault(str(node.get("path")), None)
+        for child in node.get("children") or []:
+            kinds[str(child.get("path"))] = node.get("combinator")
+    return kinds

dstf/authoring/typed_number.js

@@ -0,0 +1,64 @@
+// A number field the server cannot overwrite while it is typed in: what the
+// field shows is what was typed, until it loses focus; a server value is
+// taken only while the field is not being typed in. (The passthrough is
+// NiceGUI's own, elements/input.js.)
+//
+// And a PREVIEW (D149): a value the server shows in the field in place of
+// what it holds, staging nothing — a handle held on the plot, the field
+// following it. `previewed` is that value (null: none) and `revision` the
+// number of the drag it is of. It is shown whatever the field's typing
+// state, except in a field typed in SINCE that drag began: what a person
+// types is never painted over.
+//
+// The server sets it by calling `preview(value, revision)` on this
+// component — never by a prop. A prop write resends the element, and
+// NiceGUI renders the page's whole tree again for any element it is sent:
+// with a 30-row table open that was a 50 to 77 ms task in the browser for
+// every move of a held handle. A method call changes this component's own
+// state, and it alone is drawn again.
+export default {
+  template: `
+    <q-input ref="qRef" v-bind="$attrs" :model-value="display" @update:model-value="typed" @blur="typing = false" @wheel="wheel">
+      <template v-for="(_, slot) in $slots" v-slot:[slot]="slotProps">
+        <slot :name="slot" v-bind="slotProps || {}" />
+      </template>
+    </q-input>
+  `,
+  inheritAttrs: false,
+  props: { modelValue: null },
+  emits: ["update:modelValue"],
+  data() {
+    return { shown: this.modelValue, typing: false, typedIn: null, previewed: null, revision: 0 };
+  },
+  computed: {
+    display() {
+      const previewing = this.previewed !== null && this.previewed !== undefined;
+      return previewing && this.typedIn !== this.revision ? this.previewed : this.shown;
+    },
+  },
+  watch: {
+    modelValue(value) {
+      if (!this.typing) this.shown = value;
+    },
+  },
+  methods: {
+    preview(value, revision) {
+      this.previewed = value;
+      this.revision = revision;
+    },
+    typed(value) {
+      this.typing = true;
+      this.typedIn = this.revision;
+      this.shown = value;
+      this.$emit("update:modelValue", value);
+    },
+    // A focused `type=number` input steps by 1 per wheel notch and keeps the
+    // page from scrolling: scrolling on with the pointer still over the
+    // field just typed in turned 0.3 into 3.3, staged. Left before the
+    // browser acts on the wheel, the input steps nothing and the page
+    // scrolls. (The arrow keys' step is untouched.)
+    wheel(event) {
+      if (event.target === document.activeElement) event.target.blur();
+    },
+  },
+};

dstf/authoring/typed_number.py

@@ -0,0 +1,76 @@
+"""The tool's number field: one that keeps what is typed in it.
+
+NiceGUI resends a whole element — its ``model-value`` with it — on any write
+of one of its props (a hint, a validation mark, ``update()``), and leaves the
+value out only when it equals the raw string the browser last sent
+(``"0.0" != "0"``, ``None != ""``). A stage that rescores takes longer than
+the gap between two keys, so the answer to one keystroke landed under the
+keys that followed: `0.25` typed over 0.3 read — and staged — `0.025`.
+
+Imports ``nicegui`` at module level, as ``forms`` does: neither is on the
+path of ``import dstf.authoring``, and a capability imports it inside the
+function that draws.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from nicegui import ui
+from nicegui.events import GenericEventArguments
+
+
+class TypedNumber(ui.number, component="typed_number.js"):
+    """``ui.number`` whose field shows what was typed until it is left: a
+    value from the server is taken only while the field is not being typed
+    in (``typed_number.js``). Every number field of the tool is one. The
+    mouse wheel over a focused one scrolls the page and steps nothing: the
+    field is left first (a browser steps a focused number input by 1 per
+    notch).
+
+    A field's own VALUE is still never set from the server while it is
+    typed in: Discard and a released drag rebuild the editor, and a linked
+    twin's mirror lands in the field that is not typed in. What the server
+    does show in a field that may hold the focus is a PREVIEW
+    (:meth:`preview`, D149): beside the value, never in its place.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        # `ui.number` names `q-input` itself, over the registered component.
+        component = type(self).component
+        assert component is not None  # the class statement registered it
+        self.tag = component.tag
+        #: The preview the browser was last told to show, and of which drag.
+        self.previewed: float | None = None
+        self.preview_revision = 0
+
+    def preview(self, value: float | None, revision: int = 0) -> None:
+        """Show ``value`` in the field in place of what it holds — a handle
+        held on the plot, the field following it (D149) — or, with None,
+        what it holds again. The field's value does not change, so nothing
+        is handed to ``on_change`` and nothing is staged. ``revision`` is
+        the number of the drag the preview is of: the component shows a
+        preview whatever its typing state, but not in a field typed in
+        since THAT drag began (``typed_number.js``).
+
+        A METHOD CALL on the component, not a prop: a prop write resends
+        the element, and the browser then renders the page's whole tree
+        again — a long task per move of the handle on an editor of thirty
+        rows. ``previewed`` and ``preview_revision`` are what was last
+        sent."""
+        same = self.previewed == value
+        if same and (value is None or self.preview_revision == revision):
+            return
+        self.previewed, self.preview_revision = value, revision
+        self.run_method("preview", value, revision)
+
+    def _event_args_to_value(self, e: GenericEventArguments) -> float | None:
+        """What was typed, as the number it is — and a negative zero as
+        zero. `-0` is on the way to every negative number and is what a
+        refused `-0.5` backspaces to; a float of it is −0.0, which was
+        staged as it came and written `-0.0` by Save. Here, the one place a
+        typed text becomes a number for every field of the tool: a table's
+        cell and a tolerance's side take their value from this."""
+        value = super()._event_args_to_value(e)
+        return 0.0 if value == 0 else value

dstf/authoring/unscorable.py

@@ -0,0 +1,141 @@
+"""What an editor refuses to stage because it can never score: a negative
+tolerance — a number, or either side of a pair; a value's or a time's; the
+criterion's or a table row's — a tube's constant width whose sides sum
+below zero (a negative number, or a pair that leaves nothing between its
+bounds) with no positive minimum width under it, and bounds out of order.
+And one value that scores but says nothing: a tube's minimum width below
+zero, a floor under no width.
+
+The EDITOR's rule, raised from a capability's ``act`` before anything is
+staged, the way a window that ends before it starts is refused. It is not
+the scorer's and not the spec parser's: a spec written by hand that holds
+such a value is read, staged and scored exactly as it always was."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TypeGuard
+
+
+class Refused(ValueError):
+    """A value an editor will not stage, said as its reason. A person's own
+    — a negative tolerance on the way to a good one, bounds out of order,
+    a required cell left blank — so it is shown and never logged
+    (`errors.USER_ERRORS`): as a plain `ValueError`, which a bug's also
+    is, each keystroke of one logged a traceback."""
+
+
+#: The keys that hold a tolerance, on a criterion and in a row of its tables.
+TOLERANCES = ("tolerance", "time_tolerance")
+
+#: The keys that hold a tube's constant width (``TubeConfig``).
+WIDTHS = ("tube_abs", "tube_rel")
+
+#: The key that holds a tube's minimum width: ONE number, a floor under
+#: both sides.
+MIN_WIDTH = "tube_min_width"
+
+#: The metrics whose two bounds may not be EQUAL either: the scorer refuses
+#: a scalar leaf with ``min_value >= max_value`` when it is built
+#: (``modes._validate_scalar_config``), as its drag editor does
+#: (``handles.edit_scalar_handle``). A range with equal bounds scores.
+STRICT_BOUNDS = frozenset({"scalar"})
+
+_SIDES = ("lower", "upper")
+
+
+def _is_number(value: object) -> TypeGuard[int | float]:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _num(value: float) -> str:
+    """A number in a refusal, to 12 significant digits, its minus as U+2212
+    (the report's sign). The sign only: an exponent's ``-`` stays."""
+    text = f"{float(value):.12g}"
+    return f"−{text[1:]}" if text.startswith("-") else text
+
+
+def refuse_negative(
+    key: str,
+    value: object,
+    side_names: tuple[str, str] | None = None,
+    where: str = "",
+) -> None:
+    """Raise :class:`Refused` when the tolerance ``value`` held under ``key``
+    is negative: ``tolerance must not be negative; got −0.5`` for a number,
+    ``tolerance (lower side) must not be negative; got −0.5`` for a side of
+    a pair — named as its fields are where they have words for it
+    (``side_names``: a time tolerance's ``early`` / ``late``), ``where``
+    before it (``"row 1: "``). A zero is a tolerance. Anything that is no
+    number or pair of numbers is not this rule's to refuse."""
+    if isinstance(value, dict):
+        named = dict(zip(_SIDES, side_names or _SIDES))
+        sides = [(f"{key} ({named[s]} side)", value.get(s)) for s in _SIDES]
+    else:
+        sides = [(key, value)]
+    for what, side in sides:
+        if _is_number(side) and side < 0:
+            raise Refused(f"{where}{what} must not be negative; got {_num(side)}")
+
+
+def refuse_negative_width(key: str, value: object, floor: object) -> None:
+    """Raise :class:`Refused` when the tube width ``value`` held under ``key``
+    puts the tube's upper bound under its lower one, so that nothing is
+    ever inside it (it was staged, and read "0.0% inside tube"): a negative
+    NUMBER — both sides — ``tube_abs must not be negative; got −0.3``, and
+    a PAIR of numbers whose sides sum below zero, ``tube_abs sides must not
+    sum below zero; got lower −0.1, upper −0.5``. The sum, not either
+    side: a pair with one side negative and a sum above zero is a band
+    shifted off its reference, which a run can lie in, and one whose sides
+    sum to exactly zero is a band of no width — a zero is a tolerance.
+
+    Only where ``floor``, the leaf's minimum width, is no positive number.
+    A positive one widens BOTH sides to itself
+    (``algorithms._tube_bounds``), so no width over it leaves nothing
+    inside: ``{"lower": -0.1, "upper": -0.5}`` over a floor of 0.2 is a
+    tube 0.2 either side of its reference. Such a leaf, written by hand,
+    was refused every edit — a window end, and the Min width that would
+    repair one with no floor — with the width's sentence. A floor that is
+    absent, zero, negative or no number floors nothing, and the width is
+    refused as it was: the floor cleared from such a leaf too."""
+    if _is_number(floor) and floor > 0:
+        return
+    if _is_number(value):
+        refuse_negative(key, value)
+        return
+    if not isinstance(value, dict):
+        return
+    lower, upper = value.get("lower"), value.get("upper")
+    if _is_number(lower) and _is_number(upper) and lower + upper < 0:
+        raise Refused(
+            f"{key} sides must not sum below zero; "
+            f"got lower {_num(lower)}, upper {_num(upper)}"
+        )
+
+
+def refuse_negative_floor(key: str, value: object) -> None:
+    """Raise :class:`Refused` when the tube's minimum width ``value`` held
+    under ``key`` is a negative number: ``tube_min_width must not be
+    negative; got −0.3``. A floor below zero is under every width: it
+    floors nothing, and the criterion scores as if the field were empty —
+    which is what the field should then be. Only a NUMBER is this rule's:
+    the floor takes one, and anything else is the leaf's config error,
+    said by its row (``comparison.sides.parse_number``)."""
+    if _is_number(value):
+        refuse_negative(key, value)
+
+
+def refuse_bounds(metric: str, params: Mapping[str, object]) -> None:
+    """Raise :class:`Refused` when ``params`` holds both bounds out of order:
+    ``min_value 9 exceeds max_value 2`` — and, for a metric of
+    :data:`STRICT_BOUNDS`, when they are equal."""
+    lo, hi = params.get("min_value"), params.get("max_value")
+    if not _is_number(lo) or not _is_number(hi):
+        return
+    if lo > hi:
+        raise Refused(f"min_value {_num(lo)} exceeds max_value {_num(hi)}")
+    if lo == hi and metric in STRICT_BOUNDS:
+        raise Refused(
+            f"min_value {_num(lo)} equals max_value {_num(hi)}; "
+            f"a {metric} leaf needs min_value < max_value"
+        )

dstf/authoring/variable_rows.py

@@ -0,0 +1,216 @@
+"""The Variables drawer's rows (the roadmap's 3c; DESIGN.md "The Variables
+drawer"), as data: the page draws them and knows none of the rules.
+
+Every variable of the last result, in groups, with arrays folded into one
+row the way the plots fold them (`discovery.plots.derive_plots`: by
+RESULT-FILE NAME, a UnitTests element never), filtered, and each row's
+state against the plots: in the selected plot's context,
+its subject, some plot's subject. Three groupings (the
+drawer's group menu): by component — the tracked ones first, then by the
+first dot component of the NAME, inside any ``der(...)`` ("(top level)"
+for a name with none), the diagnostics last; flat, one group; and tracked
+first, the rest in one group after them. Two orders: result-file order, or
+A→Z by what a row reads as. Three reads (the names menu): the expression,
+the result-file name, or both."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Collection, Mapping, Sequence
+from dataclasses import dataclass, replace
+
+from ..discovery.plots import ResolvedPlot
+from ..figures.families import family_label, group_families, mask_quoted
+
+TOP_LEVEL = "(top level)"
+#: The one group of the flat grouping, and the second of "tracked first".
+ALL, OTHER = "All variables", "Other variables"
+
+
+@dataclass(frozen=True)
+class VarRow:
+    #: the family key (``pipe.T[]``; a lone variable's too when it has one,
+    #: ``$DER.x[]``), else the name. Not unique: the tracked ``pipe.T[1:2]``
+    #: keys ``pipe.T[]`` as the untracked rest of the array does — ``id`` is.
+    key: str
+    #: ``<group rank>/<group title>/<key>``, unique within the drawer. The
+    #: rank is in it because a title is not unique: the tracked
+    #: ``Tracked.a[1:2]`` and the untracked ``Tracked.a[3:4]`` beside it are
+    #: both "Tracked" and both key ``Tracked.a[]``. A tracked family in a
+    #: group of untracked ones too (Flat) keys ``tracked:<key>``: under Flat
+    #: both ``pipe.T[]`` rows are in "All variables".
+    id: str
+    members: tuple[str, ...]  #: names, by index; one for a lone variable
+    text: str  #: what it reads as: the family label, or the label
+    #: what it reads as by result-file names: the family label
+    #: (``pipe.T[1:2]``), or the name
+    file_text: str
+    name: str | None  #: the muted name beside ``text``, when they differ
+    #: members the selected plot draws as CONTEXT — what its check adds or
+    #: takes off
+    on_selected: int
+    elsewhere: tuple[int, ...]  #: other plots showing any member, 0-based
+    #: whether a member is the selected plot's SUBJECT: its check is on and
+    #: grey, since a plot cannot lose its subject
+    is_subject: bool
+    #: the plot (0-based) a member is the subject of, or None: a variable
+    #: with a plot of its own has its "+ new plot" grey
+    subject_of: int | None
+
+
+@dataclass(frozen=True)
+class VarGroup:
+    #: 0 tracked, 1 a prefix group, 2 top level, 3 diagnostics: a variable
+    #: named ``Tracked.a`` is in a prefix group titled "Tracked", never in
+    #: the tracked one
+    rank: int
+    title: str
+    rows: tuple[VarRow, ...]
+
+
+def _group(name: str, tracked: set[str], diagnostics: set[str]) -> tuple[int, str]:
+    if name in tracked:
+        return 0, "Tracked"
+    if name in diagnostics:
+        return 3, "Diagnostics"
+    # a derivative is in the group of what it differentiates:
+    # `der(pipe.T[1])` is in "pipe", never "der(pipe"
+    while name.startswith("der("):
+        name = name[4:]
+    # found in the mask: `'a.b'.c` is in "'a.b'", never "'a"
+    masked = mask_quoted(name)
+    dot = masked.find(".")
+    if dot == -1:
+        return 2, TOP_LEVEL
+    # the component, not its index: `port[2, 1].C[1]` is in "port"
+    bracket = masked.find("[", 0, dot)
+    return 1, name[: dot if bracket == -1 else bracket]
+
+
+def variable_groups(
+    *,
+    names: Sequence[str],
+    tracked: Sequence[str],
+    diagnostics: Collection[str],
+    labels: Mapping[str, str],
+    plots: Sequence[ResolvedPlot],
+    selected: int | None,
+    keep: Callable[[str], bool],
+    unit_tests: Collection[str] = (),
+    group: str = "component",
+    order: str = "file",
+    read: str = "both",
+) -> list[VarGroup]:
+    """``names`` in the drawer's groups, each row's state read off
+    ``plots`` and the ``selected`` one (None: no plot); ``keep`` is the
+    filter, asked of the name AND the label. Absent from either map, a name
+    reads as itself.
+
+    The rows fold as the plots do (the owner's ruling O3,
+    :func:`~dstf.discovery.plots.derive_plots`): by RESULT-FILE NAME, never
+    by label, and each of the ``unit_tests`` names is a row of its own
+    whatever its expression reads — three UnitTests variables whose
+    expressions are ``pipe.T[1:3]`` are three plots, and one row over them
+    named a plot there is not. A row READS ``labels`` (the plain label),
+    with the name muted beside it where they differ.
+
+    ``group`` (the drawer's group menu): ``component`` — tracked, then by
+    component, top level, diagnostics; ``flat`` — one group, "All
+    variables"; ``tracked`` — "Tracked", then "Other variables" with
+    everything else, diagnostics included. Families fold in every one, the
+    tracked names apart from the rest: under Flat the tracked
+    ``pipe.T[1:2]`` and the untracked rest of the array fold to the same
+    key, and one row over both hid which of them the test tracks.
+    ``order``: ``file`` keeps a group's rows in first-appearance
+    (result-file) order; ``name`` sorts them by what they are shown as —
+    ``file_text`` when ``read`` (the names menu) is ``file``, else
+    ``text``."""
+    tracked_set, diag, apart = set(tracked), set(diagnostics), set(unit_tests)
+    kept = [n for n in names if keep(n) or (n in labels and keep(labels[n]))]
+    by_group: dict[tuple[int, str], list[str]] = {}
+    for name in kept:
+        if group == "flat":
+            where = (1, ALL)
+        elif group == "tracked":
+            where = (0, "Tracked") if name in tracked_set else (1, OTHER)
+        else:
+            where = _group(name, tracked_set, diag)
+        by_group.setdefault(where, []).append(name)
+    # the plots indexed once: scanning every plot per name cost 395 ms over
+    # 6,093 names and 300 plots
+    index: dict[str, list[int]] = {}
+    subject_of: dict[str, int] = {}
+    for i, plot in enumerate(plots):
+        for name in plot.subject:
+            subject_of.setdefault(name, i)
+        for name in plot.series:
+            at = index.setdefault(name, [])
+            if not at or at[-1] != i:
+                at.append(i)
+    # the page's cards can lag the Session's plots by one sync
+    chosen = (
+        plots[selected] if selected is not None and 0 <= selected < len(plots) else None
+    )
+    context = set(chosen.context) if chosen is not None else set()
+    subject = set(chosen.subject) if chosen is not None else set()
+    showing = {n: tuple(index.get(n, ())) for n in kept}
+    position = {n: i for i, n in enumerate(kept)}
+    out: list[VarGroup] = []
+    for rank, title in sorted(by_group, key=lambda g: (g[0], g[1].casefold(), g[1])):
+        in_group = by_group[rank, title]
+        # Folded apart, then merged back in result-file order (a family's
+        # first appearance, `group_families`' own order).
+        families = sorted(
+            [(n, [n]) for n in in_group if n in apart]
+            + group_families(
+                [n for n in in_group if n in tracked_set and n not in apart]
+            )
+            + group_families(
+                [n for n in in_group if n not in tracked_set and n not in apart]
+            ),
+            key=lambda f: min(position[m] for m in f[1]),
+        )
+        rows = []
+        for key, members in families:
+            text = family_label(key, members, labels)
+            file_text = family_label(key, members)
+            lone = members[0] if len(members) == 1 else None
+            on = [m for m in members if m in context]
+            elsewhere = sorted(
+                {i for m in members for i in showing[m] if i != selected}
+            )
+            rows.append(
+                VarRow(
+                    key=key,
+                    id=f"{rank}/{title}/"
+                    + ("tracked:" if rank != 0 and members[0] in tracked_set else "")
+                    + key,
+                    members=tuple(members),
+                    text=text,
+                    file_text=file_text,
+                    name=lone if lone is not None and text != lone else None,
+                    on_selected=len(on),
+                    elsewhere=tuple(elsewhere),
+                    is_subject=any(m in subject for m in members),
+                    subject_of=next(
+                        (subject_of[m] for m in members if m in subject_of), None
+                    ),
+                )
+            )
+        if order == "name":
+            shown = (lambda r: r.file_text) if read == "file" else (lambda r: r.text)
+            rows.sort(key=lambda r: (shown(r).casefold(), shown(r)))
+        out.append(VarGroup(rank, title, tuple(rows)))
+    return out
+
+
+def cap(groups: list[VarGroup], limit: int) -> tuple[list[VarGroup], int, int]:
+    """At most ``limit`` rows, groups in order: ``(groups, shown, total)``.
+    A result of thousands of names drew thousands of rows otherwise."""
+    total = sum(len(g.rows) for g in groups)
+    out, left = [], limit
+    for g in groups:
+        if left <= 0:
+            break
+        out.append(replace(g, rows=g.rows[:left]))
+        left -= len(out[-1].rows)
+    return out, min(total, limit), total