Four measured ceilings and the dead code they found

[donislawdev]

What this is

Four ceilings and one clean-up, all measured on this tree rather than taken from a
textbook. Every number pinned here is today's maximum, so the whole set is green
from the first run and only fires when something grows past what already exists.

This started as a question about adopting an external complexity analyser. The
measurement said no: five of the six things that tool takes are taken here already,
often better, and its duplicate detector finds nothing in this tree - 168 files
scanned, zero logic clones, nine cross-file groups that are all data tables. Its
Python reader also counts and / or, which scores driver.doctor at 27 where
ruff scores the same function 6 - a ranking inversion on a flat table of ternaries.
A second, disagreeing number on an axis that already has one is two ceilings over
one head. So the gaps it did point at were closed with what is already installed.

The five commits

Remove five definitions nothing calls.BeanEngine.in_scope_now and the
BeanCore.in_scope behind it were recorded as unused when the connections page
moved its row highlight onto the stored scoped record; the follow-up the entry
promised never came. ScrollableFrame.yview_fraction, .set_yview_fraction and
PortTable.age have no caller anywhere and no mention in any document. Two comments
that described the deleted path were corrected - they claimed the highlight asks the
engine live, which it has not done for two releases.

A complexity crowd count.max-complexity watches one function and is blind to
the drift the size ratchet grew a second knob for: the runners-up climbing together,
none of them a record. At a ceiling of 29, cli._run_session could reach 29 from 27
with every gate green the whole way. Three functions are in the 70% band today and
the next one sits one branch below it.

PLR0913, and both rule lists held to each other. Argument count is the one
measurement on ruff's pylint-refactor list that nothing here already takes -
PLR0912 is C90 on the same function, PLR0915 is FUNCTION_CEILING measured worse
because the ratchet counts logic lines and leaves comments free, PLR0911 needs a
branch per return. Pinned to the widest signature that exists (14), not to ruff's
default of 5, which would be red on 25 signatures before catching anything.
--select on the workflow command line replaces the list in pyproject.toml, so a
rule could be configured, visible to ruff check locally, and absent from the only
run that can block a merge. Both lists are recorded in the suite now, and a third
check refuses a rule that is neither blocking nor reported.

A nesting-depth ceiling. The axis test_code_shape.py said out loud it did not
measure. Nothing else can see it: ruff has no depth rule, the size ceiling is blind
to it, and complexity scores a flat chain of eight elif exactly like eight nested
if. The band is absolute rather than a percentage - 70% of 5 lands on the same
line today, but at a ceiling of 4 it would mean "3 or more" and the count would jump
from 12 to 82.

A dead-code guard, resolved to a fixed point. A dead caller keeps its callee
looking alive, which is exactly how BeanCore.in_scope stayed invisible. The scan
reads an allow-list of trees and never walks the repository root, so it cannot reach
directories that exist on a maintainer machine and in no checkout - one that did
would call a name used locally and dead in CI.

Two things were wrong on the first attempt

Both were caught by measurement rather than review, and both are written down where
the next reader will hit them.

The depth metric walked an if body without adding the level that body sits at, so
four nested blocks measured three. Its own test found it - which is why the three
metric tests went in before any constant was filled in. The first pinned band (3)
was the wrong measurement and became 12 once the metric was fixed.

The dead-code guard scanned its own file, where the exception list lives, so writing
a name into that list was a mention of itself and the scan reported it as used. The
guard disarmed itself in the act of recording an exception, and the two entries on
that list were exactly the names it would have stopped watching.

Two measured decisions worth knowing about

The dead-code scan counts every word, comments and strings included. Counting only
code tokens finds six more names and five of them are alive: four are called from
inside run_gui("""...""") blocks - the GUI tests are Python source in a string, run
in a subprocess, and the suite holds 204 of those calls - and one is reached through
getattr. A guard that accuses living code is a guard people switch off. The price
is named in the file: a definition whose name is an ordinary English word survives on
prose alone, which is how PortTable.age had to be found by hand.

The three depth-metric tests are in PROVEN_BY_HAND, not MUTATIONS. Any patch to
the metric moves the measurement of the whole package, so it reddens the two ratchet
tests pinned to it as well - measured, three tests red at once - and a registry entry
names one test.

Verification

• ruff check --select F,B,C90,PLR0913 . clean, mypy clean over 66 modules.
• Guards for the touched code: 335 passed. Meta guards (shape, hygiene, registry,
  conventions, README, release, packaging): 97 passed. smoke_gui.py OK.
• tools/mutate.py --changed for this branch: 29 entries, 29 caught, none survived.
  Six of those entries are new and each was run on its own as well.
• End to end: a function nothing calls was planted in the package, the guard caught
  it by name, and the file was restored byte for byte.
• Every pinned number was re-measured independently of the test that asserts it.

The full suite, the real-Tk render check, semgrep, diff-cover and the executable
build were deliberately left to this pull request - they need the platforms CI has.