emrg: the cross-reference guard omits the two roles whose rule differs from its own #2541

What is there

tests/test_docstring_cross_references_resolve.py reads Sphinx cross-reference roles in this tree's Python sources and reports any that name something the tree does not have. Its role set is four: func, class, meth, data.

Two roles written in the same tree are outside that set.

What the tree contains

Measured on master 22e01111, over git ls-files '*.py':

• :mod: — 21 sites. emrg/server/daemon.py:702 cites emrg.tools.shell_dialects; emrg/sandbox/win32/__init__.py:10-20 cites ten module paths; several files cite ctypes.
• :attr: — 14 sites. Two of them name a field of a ctypes.Structure declared by a _fields_ list in the same file (emrg/sandbox/win32/abi.py:108-109, SubAuthority and SubAuthorityCount). The other twelve name an ordinary class attribute through its class (for example RunnerFailureRule.start_line) or a bare member name.

Neither role is checked today, so a stale one is invisible — the same failure the guard exists for, one role over.

Why adding them to the existing set would be a guard that always passes

emrg.sandbox.win32.sid is a dotted name. The existing dotted rule decides a reference by its head, and for func, meth, class or data that is the decidable half, because the tail of os.path.expandvars cannot be followed statically. But a module path always starts with a package name that is bound somewhere in the tree, so a mod reference admitted to the current rule resolves on its head every time and reports nothing however stale the tail is. mod needs the whole path to be a module: one of this tree's, derived from its files, or one the interpreter can find.

attr needs the opposite adjustment. Its exclusion is stated as "it names a member, not a binding", which is right about what the role claims, but the reason given for the tree's own sites — ctypes structure fields — holds for two of the fourteen. Twelve name an ordinary class attribute, and those are members the tree declares and can be asked about.

What the fix must satisfy

1. A mod reference resolves only when the whole dotted path is a module of this tree or one the interpreter can find. A path whose head is imported but whose tail is not a module is reported.
2. An attr reference resolves through its head when it is dotted, and when it is bare against the member names the tree declares, _fields_ field names included.
3. Both rules are proven in both directions: an arm where the reference must resolve, an arm where it must be reported, and for mod an arm showing that the existing head rule would have passed the case being reported.
4. The whole-tree arm stays green, and the module docstring's claim about attr is replaced by what is measured.