Reasoning Modules — Reference

2.1 Kinds and the fields you write

Every query that answers “which functions” returns subjects, never display names — the same identity code.Call.caller holds and callers_of(fn) takes. So an answer from one query feeds straight into another, and name stays what it is: an optional label for reading, not an identity.

Three fields decide whether the queries work at all:

• code.Call.caller and code.Call.callee hold the subject you recorded a Function under, not its display name. The queries compare them directly, so display names make every function look uncalled, with nothing to tell you why.
• code.Function.test names a test that reaches the function, and untested reads its absence. Write it only where a test really does reach, or the rule falls silent everywhere instead of where it should be.
• code.Function.called says something in this codebase calls this function, and uncalled reads its absence — the same shape as test. Record it on the CALLEE, next to the Call you record for the same edge. That looks redundant and is not: a rule ranges over one kind, so “does any Call name me?” is a question nothing can conclude from. Recorded here, the absence is a fact about this function and uncalled is an ordinary rule. Recording the Call alone is not enough — write both, or every function you recorded comes back uncalled however many callers the store holds.

code.Function.callers and code.callees are degree — how many distinct functions call this one, and how many it calls. Distinct neighbours, not call sites: a caller that calls you three times is one dependency, not three, and counting sites would rank a function by how chatty its callers happen to be.

They are recorded rather than counted for you, for the same reason called is — and unlike called, write them for every function, zero included. Those above are read by their absence, so a value everywhere silences the rule. callers is read by comparison, and a function nothing calls has a fan-in of zero, which is a fact rather than a gap. Optional and absent-tolerant: record neither and everything else answers as before, with hub simply never concluding.

code.UnresolvedCall is the opposite record: a call you saw and could not name a target for. It asserts no edge, deliberately — a missing edge is a known gap, and a guessed one is a wrong answer no query could tell from a fact. Write caller as the subject of the enclosing function (as on Call), site as the location to look at, and text as the callee exactly as it appears in the source. site is what makes an entry worth having; a subject without one is skipped. This kind is optional and absent-tolerant — see §2.5 for what it buys you.

code.Rationale is a reason the author wrote down, attached to what it explains. Every other kind here is structure — something a reader could recompute from your source. This is the part that cannot be recomputed: why the structure is the way it is.

It is stated, never inferred, for the reason Counterpart is: intent is a claim only a reader can make, and an inferred one produces facts you cannot tell from the real ones. Write subject as the subject of the Function or Class it explains, marker as which convention it was, text as what the author wrote, and site as where to read it in full. text is what makes an entry worth having; a subject without one is skipped.

Which comments count is your producer’s decision, exactly as what counts as a branch is — and the same warning applies in the same direction. A convention wide enough to sweep ordinary comments turns every line in your tree into a fact and rationale_for into noise. Choose something an author had to type on purpose. Ours records WHY: and NOTE: at the start of a comment, uppercase, and nothing else.

code.Function.explained says a reason exists, and unexplained_critical reads its absence — the same shape as test and called. Write it only where a reason really was recorded, or the rule falls silent everywhere instead of firing.

language says what a fact is about — python, cpp, rust, whatever you call it. It is optional, and a store that never records it works exactly as before. Record it once your store holds more than one language: module is a path, so it hints at the language at best and no query can rely on it, and without language there is no way to ask about one half of a repository. It also tells two producers apart, which matters because branches is whatever your analysis counted, and two producers can both be right on different scales while complexity compares them against one threshold either way.

code.Counterpart records two functions that have to agree — an encoder and its decoder, a writer and its reader, two siblings that ought to guard their inputs alike. Nothing in a call graph says two functions are halves of one contract; that is a claim about intent, and only you know it. State the pair, name in relation what is being counted, and give the count each side handles. left_covers and right_covers count members of that one named set, which makes them comparable to each other and to nothing else.

2.2 Derived and maintained for you

2.3 How to count branches and loops

hotspot fires at a complexity above 10. A fixed threshold over a number you compute yourself only means something if we agree on how it is computed, so here is the rule. Follow it and your numbers are comparable — to your own past numbers, to another producer’s, and to the threshold.

complexity is one, plus one for each decision the function makes:

else, default and a bare case _ are where control lands when none of the decisions above them fired, so they add nothing — three arms and a catch-all is three, not four.

Two scope rules decide what belongs to which function:

• a named nested function is its own Function, with its own counts; its decisions are not charged to the function that contains it;
• an anonymous inline function — a lambda, a closure, a block — counts toward the function containing it. It is part of that function’s text and cannot be called from anywhere else, so there is no other function for its decisions to belong to.

The list is closed. Anything not on it counts nothing, including constructs with a fair claim to being a decision. An assert is the clearest one: it is a conditional failure, and most complexity tools count it — but in some languages it is a macro or a compiled-out call that a reader working from source cannot reliably see, and a rule that some producers can follow and others cannot is the problem this rule exists to solve. A number everyone computes the same way is worth more than a number that is arguably more faithful.

If you want a different scale — a stricter threshold, a metric of your own — define your own module named code.

2.4 Queries

2.5 What the answers can and cannot mean

The queries are only as good as the data, and for a codebase that has consequences worth stating plainly.

A call graph derived from source is a lower bound. Python decides calls as it runs, so anything reading source sees the calls the source makes plain and no others — a call through a variable, a handler table or getattr is not visible. Every edge you record that way is real; edges are missing. That matters most for uncalled(): a function reached only dynamically appears there. Read it as candidates to look at, never a list to delete.

How loose that bound is, is measurable. Record an UnresolvedCall wherever your producer sees a call and cannot name the target, and dispatch_sites() lists them: the location, and the callee as written. Read it beside uncalled() — any of those sites could be the call that a function on that list is reached by. A codebase with two dispatch sites and one with two hundred deserve very different trust in the same uncalled() answer, and this is what tells them apart. Nothing on the list is a defect by itself: a plugin table, a callback and a decorator all work exactly this way. It is a measure of how much of your call graph is decidable by reading.

Recording none of them is fine. The kind is absent-tolerant — everything else answers as before, and dispatch_sites() returns nothing.

untested inherits that bound, since reaching a function is worked out over the same graph — and reaching is not executing, because a branch may never be taken. Read it the same way.

critical() cannot tell deliberate from overlooked, and unexplained() can. Two functions can be identical in every structural respect — same complexity, neither reached by a test — and be entirely different objects: one whose author wrote down why it is shaped that way and why it is not tested, and one that says nothing. critical() returns both, because everything it reads is structure. Record Rationale and explained and unexplained() is the same list with the accounted-for taken out. A short unexplained() under a long critical() is a good result: the risk is known and written down rather than absent. Record none of it and unexplained() is simply critical() again, which is where you were.

There is no dependency age, and that is the schema being honest rather than an omission. Python’s package metadata carries no release date, so an age could only come from asking an index — which means sending a dependency list to a third party. A field nothing can honestly fill is worse than no field, because it reads as a capability.

unused_dependencies() matches by name, so a distribution whose import name differs from its package name (Pillow is imported as PIL) will look unused.

A subject missing the field a query reads is skipped, not fatal. You are never obliged to fill every field of a kind, and one half-written subject does not take out the answer for the complete ones beside it — a Dependency with no name, a Counterpart with no relation, an UnresolvedCall with no site and a Rationale with no text are each passed over, and everything else answers as it would have. So a partial record costs you that record and nothing more.