fix(reg): cast TransportProtocol.undefined so mypy infers its own type

[JarryShaw]

• Searched for similar pull requests
• Followed the coding style (make pylint, make mypy, make isort)
• make test passes, and a test case covers the change — ran the scoped test file only (coverage+pytest and plain unittest), not the full suite, per this host's OOM history
• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md — N/A, changelog centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657; no behaviour change, though undefined does gain a rendered Sphinx description it previously lacked as an undoc-member (see below)

What is the purpose of your pull request?

• fix — corrects a defect

---

Description of your pull request and other information

Fixes #770.

mypy has no aenum plugin, so TransportProtocol is a plain class to it.
undefined = 0 in the BASE template is a bare int literal, inferring as
int, while the auto()-valued siblings infer as Any — the only member
that then disagreed with the four sites defaulting to it: the class
attribute __transport__, and the proto parameter on __new__, get
and get_all.

Wraps the literal in typing.cast instead, in the vendor BASE template
only, then regenerates. cast is the identity function at run time, so
undefined stays exactly 0 and still composes
(tcp | undefined is tcp). Regenerating from a byte-identical cached IANA
fetch changes only this member's comment and assignment in the generated
base module; tcp.py/udp.py/sctp.py/dccp.py are untouched, and every
member's name/port/svc/proto/value plus the counts (6147/6143/91/10) are
unchanged.

TransportProtocol is autoclassed with :undoc-members:
(docs/source/pcapkit/const/reg.rst), so undefined's comment is split:
a one-line #: contract (TransportProtocol(0) is undefined, the proto
sentinel default, what _missing_ extends from) is what Sphinx renders,
and the mypy/cast rationale stays in an adjacent plain # comment Sphinx
does not pick up. mypy.ini sets warn_redundant_casts, so this also
means the cast starts erroring on its own the day aenum ships stubs that
let mypy infer the type without it, rather than lingering unnoticed.

Two rejected alternatives, measured: an explicit member annotation
(undefined: 'TransportProtocol' = 0) does not fix the disagreement, it
only relocates it — one [assignment] at the member's own declaration
line, 113 errors/39 files rather than 116, so cast (112/38) wins on being
the only one that reaches zero, not on parity. auto() & 0 is run-time
identical to the bare literal (value 0, no burned counter slot, siblings
unaffected) and is rejected only because it leans on aenum's undocumented
internal handling of a composed auto(), not because it misbehaves.

mypy on the whole package: 116 errors/39 files → 112/38. lint.yml's own
pin (112/38, measured at 932cb48d1) already matches this count, so it
needs no change here.

Tests added: the generated source's shape, a direct mypy.api.run check,
and a runtime guard that undefined is still 0 and composes. The shape
check uses a plain containment test rather than assertIn/assertNotRegex
directly — both format their default failure message from the whole
~200 KiB generated module (measured: 219,113 chars for a bare assertIn
on this source), so a failure instead gets a short, bounded message.

The mypy check skips inline when mypy is not importable — it's a Pipfile
[dev-packages] entry, not a pyproject.toml extra, so no
unit-tests.yml job ever has it. Gating that instead with a tracked
HAS_MYPY flag was measured and rejected: mypy has no
MODULE_PROVIDERS entry in tests/_dependency_gates.py, so adding the
gate breaks tests/test_tier_guard.py's DependencyGateCoverageTests
outright (4 errors, 2 failures of its 9, measured). #779 tracks closing
that gap; neither file is edited here.

[JarryShaw]

Cross-review at 79e8699e7: NEEDS CHANGES (opus, a different model from the author). The cast itself is correct and unusually well evidenced — both items are elsewhere.

Confirmed, and more strongly than claimed. mypy goes 116/39 → 112/38, and the error lists were comm'd rather than just the totals: exactly the four [assignment] errors removed, nothing introduced, per-file counts otherwise byte-identical. The cast states a truth rather than silencing a mismatch — type(undefined) is TransportProtocol holds at every point, with no lifecycle window where it does not. Runtime is unchanged across every composition identity (tcp|undefined is tcp, undefined|undefined, undefined & tcp, TransportProtocol(0), bool()). Regeneration is deterministic and attributable: diff -u of the two regenerated apptype.py files is exactly the PR's two hunks. Member data identical by SHA-256 over sorted tuples, 6147/6143/91/10. And mypy.ini sets warn_redundant_casts = True, so if aenum ever ships stubs the cast will be flagged rather than left as dead scaffolding — it is self-cleaning.

R1 — the new mypy test cannot run on any CI job, and does not say so. mypy is in Pipfile [dev-packages]:48 and in no pyproject.toml extra (:232 is mypy-extensions, a different package); every unit-tests.yml install line is .[test,…], and lint.yml installs mypy but never invokes pytest. Measured with mypy blocked: OK (skipped=1). Worse, the inline try/except ImportError: self.skipTest(...) is invisible to the repo's own tripwire — _dependency_gates.py:_gates_of inspects skipUnless decorators only — so DependencyGateCoverageTests stays green at 9/9. tests/project/test_isort_clean.py:54-59 has the identical shape but documents it and cross-references #766; this adds a second silent instance of the gap #766 exists for. Either gate it the repo's way (HAS_MYPY + @unittest.skipUnless, which routes it through the guard) or add that paragraph and the #766 reference.

R2 — a false claim in the new comment, in both files, and it ships as published API documentation. The comment calls undefined "the identity element the flag composition below relies on". Measured:

' | TransportProtocol.'  in const/reg/apptype/apptype.py : 0
                         in vendor/reg/apptype/apptype.py: 0
                         in tcp.py (a sibling)           : 5287
'TransportProtocol.undefined' in tcp/udp/sctp/dccp.py    : 0  0  0  0

There is no composition below in either file the comment lives in, and the 5,287 compositions in the sibling modules never mention undefined. What the 0 actually buys is TransportProtocol(0) is undefined, bool(undefined) False, and its role as the proto sentinel at four sites plus ~200 extend_enum calls. This matters beyond wording because docs/source/pcapkit/const/reg.rst:72-74 autoclasses TransportProtocol with :members: and :undoc-members: — undefined was an undoc-member and now ships this six-line paragraph as its rendered description.

One stated measurement does not survive, though the conclusion does. The PR rejects the explicit annotation as leaving the "net error count unchanged". Measured, it gives 113 errors in 39 files, not 116 — it removes three of the four and leaves one at the declaration. So the right reason to prefer cast is 0 errors and 38 files against 1 and 39, not parity. Relatedly, auto() & 0 turns out runtime-identical and does not burn a counter slot, so its rejection rests entirely on the undocumented-aenum-behaviour argument — a judgement I agree with, but it is the only thing separating it from the chosen fix.

Three smaller test issues: assertNotRegex formats %r of the whole module, so one failing assertion dumped 217 KB into the log; the mypy test passes no --cache-dir and writes a 20 MB .mypy_cache/, costing 7.7 s of the module's 7.8 s in a *_unit.py-tier test; and its docstring claims "the same flags Makefile uses" while the effective config also includes mypy.ini via cwd discovery.

A useful finding for #773, which owns lint.yml: measured at the pin's own commit 932cb48d1, mypy is 112 errors in 38 files with the same distribution and the same findings as this head — the error sets differ only by two line-number shifts in schema/schema.py from unrelated commits. So that pin is accurate again on the numbers, not coincidentally; only its [932cb48d1] provenance label is stale.

[JarryShaw]

Cross-review at 19b361770 (sonnet, a different model from the author): NEEDS CHANGES — two items, both found fresh rather than carried over from round one.

1. The assertIn one line above the "fixed" check has the identical defect, and fires first. tests/vendor/test_vendor_reg_apptype_generator_unit.py:182 is a bare self.assertIn("undefined = cast('TransportProtocol', 0)", source). unittest's default message calls safe_repr(container) with short=False, so nothing truncates. Measured against this head: the module source is 211,072 chars and the failure message ~219,100, against 132 for the bounded re.search path two lines below. So in the actual regression this test exists to catch — the cast reverted to a bare literal — the unbounded assertIn fails first and the bounded snippet code is never reached. The comment claiming "a bounded search plus a snippet keeps a real failure's message short instead" is true only of the second check, while reading as if it governs both. Bound the first one too.

2. A transient agent-coordination fact baked into a permanent docstring, pointing at the wrong issue. :81 says fixing the HAS_MYPY gap "requires editing tests/_dependency_gates.py itself, which is #774's file to change, not this one's." #774 is a PR about HAS_VENDOR_DEPS and the vendor extra on engine-tests — it touches the same file, not the same gap, and it will be gone the moment it merges. Neither #774 nor #766 owns this gap, so I have filed #779 for it: mypy has no MODULE_PROVIDERS entry, and the guard's bare subscript at _dependency_gates.py:682 turns that into an opaque KeyError upstream of any DEPENDENCY_GATE_EXCLUSIONS filtering. Cite #779; drop the ownership clause.

R1's mechanism independently reproduced, twice over. The reviewer re-created Route 1 in a scratch worktree touching only the test file and got exactly the claimed Ran 9 tests ... FAILED (failures=2, errors=4). I confirmed both halves myself: grep -n "'mypy'" tests/_dependency_gates.py on 110381b63 returns nothing, and :682 is an unguarded MODULE_PROVIDERS[...] subscript. So Route 2 was the only route available here — but it is invisible to the guard by construction, since _gates_of (:1008-1021) walks node.decorator_list only and never a function body. That is the #745 hazard, now tracked as #779 rather than asserted in a docstring.

Everything else held up under independent reproduction. Every R2 clause checked live: TransportProtocol(0) is undefined, bool(undefined) is False, int(undefined) == 0, tcp | undefined is tcp; all four sentinel defaults confirmed at :2270, :2294, :2383, :2441; _missing_ extends unassigned/reserved rows from it at :2493-2586; mypy.ini:7 is warn_redundant_casts = True; and Sphinx's find_attr_docs() returns only the #: semantics block, so the plain-# mypy rationale does not ship as rendered docs. Mypy counts re-derived from scratch: base 116 errors / 39 files with 4 [assignment], head 112 / 38 with zero, explicit-annotation alternative 113 / 39 with one relocated — so "cast wins 0/38 against 1/39" is exact. The crawler was run against live IANA data and tcp/udp/sctp/dccp/__init__ came back SHA-256-identical to the committed files. --cache-dir=/dev/null writes no cache and changes no output. Merged into 110381b63 in a scratch worktree: clean, and the PR's six vendor tests pass on the merge result.

One coverage note, not a change request: of the three new tests, two fail against 83b58ebda and the third passes both before and after by design, since cast is a runtime no-op — not fix-discriminating, and honestly so.

Routed to the worker. Label moves to review: needs-changes.

[JarryShaw]

Round-three cross-review at 47849d1fc (sonnet, a different model from the author): GOOD TO GO.

Both required changes verified independently rather than re-read. For the bounded check it reverted the const module's cast back to a bare undefined = 0 in a scratch worktree to reproduce the real regression, then ran the test: it fails with AssertionError: the cast is gone; expected "undefined = cast('TransportProtocol', 0)" at 69 characters, and 1,413 bytes for the whole captured output including the traceback — against ~219,100 for the assertIn it replaced. It also checked the real head for residue from the worker's own revert-and-measure cycle and found none: line 41 still carries the cast, tree clean.

#779 confirmed as the right citation by reading it, and grep -n '#774' is empty in both the test file and the PR body.

The unprompted third fix checks out too, which is the one I most expected to be wrong. .github/workflows/lint.yml:23 pins mypy 112 errors in 38 files (506 checked), and mypy run on this head with the Makefile's own flags gives Found 112 errors in 38 files (checked 506 source files) — exact. So "already matches, needs no change" is true, and the stale "per #773 owning that file" clause it replaced is gone. Correcting myself: my first read of that pin gave 115/39/496 and looked like a contradiction — it was a stale working tree six commits behind origin/main, not a disagreement.

One commit sitting directly on 110381b63; the four sibling generated files hash byte-identical to round two; python -m unittest gives Ran 6 tests, OK and coverage run -m pytest gives 6 passed / 11 subtests, in agreement, so no pytest-subtests discrepancy; isort --check-only clean on all three files.

Settled in earlier rounds and not re-run: the R2 docstring clauses, the live-IANA regeneration, --cache-dir=/dev/null, Sphinx's find_attr_docs(), and the 116/112/113 mypy triple — nothing in this round touched the source those rest on.

Ten CI legs still outstanding on this head, so this is a review verdict rather than a merge signal.