docs(const,vendor): fix RFC anchor typos and missing section- prefixes

[JarryShaw]

Please follow the guide below

• 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
• Added a changelog entry -- N/A -- changelog centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• chore — anything else

---

Description of your pull request and other information

Fixes #942, plus two defect classes the invariant it required then found:
(1) the same secion/section-2.2 typo at a second FTP site, and (2) ten
generated fragments missing section- entirely (RFC 8684/8765), traced to
two generators discarding IANA's literal "Section" word; fixed both plus all
10 generated lines.

ACCEPTED_FRAGMENT now accepts exactly Sphinx's own three anchor prefixes
(section-N/appendix-X/page-N, from sphinx.roles._format_rfc_target),
adding page-N (confirmed real: RFC 793 id="page-5") to match
test_changelog_md.py. Deliberately still rejects bare introduction/
section -- neither is in Sphinx's known set, and both would trade shape
validation for an open-ended vocabulary; recorded in the test's docstring.

The invariant is shape-only, not anchor existence: :rfc:959#section-4.1``
passes it but the anchor doesn't exist on RFC 959's real page (filed as
#944, not fixed here). Census: 645 total, 0 malformed. isort/pylint
unchanged against 9ea0d6a5a.

[JarryShaw]

NEEDS CHANGES at eeb4e62fa — but not because anything here is wrong. Everything in this PR verified, by me, re-running rather than reading the report:

• Source diff touches exactly the two FEATCode class-docstring lines; get()'s :rfc:5797#section-2`` is untouched, as it should be.
• The new test fails 2/2 with the two lines reverted and passes with them restored.
• My own independent census: 645 :rfc:-with-fragment citations under pcapkit/, 2 still malformed.
• tests/project/ 197 passed / 1 skipped. One commit, correct authorship.
• Worth stating because the author disclosed it rather than hiding it: some reconnaissance ran against the main checkout by mistake. I checked — git status there is clean and both files still carry the typos, so nothing leaked.

The one change needed is a reversal of my own instruction. I told the author to leave any other malformed fragment alone, so it recorded the second one in a KNOWN_DEFECTS tuple instead of fixing it. That was my call and it was wrong:

:rfc:5797#secion-2.2`` at pcapkit/vendor/ftp/command.py:269 and `pcapkit/const/ftp/command.py:257` is the same defect — same missing `t`, same two files, same one-character fix, same silently-dead anchor, found by this PR's own sweep. Splitting it into a second PR buys a full review cycle for two characters, and a tuple documenting a bug we could have fixed in the same breath will outlive its reason and read as intentional to whoever finds it next.

So: fix both secion-2.2 sites, delete KNOWN_DEFECTS and the known subtraction, and the invariant becomes a plain "no malformed :rfc: fragment anywhere under pcapkit/" at zero. Round 2 is with the author now.

Keeping the best part of this as-is: the module docstring establishes from docutils.parsers.rst.roles.rfc_reference_role that the fragment is appended to the base URL verbatim and never validated — which is why no build warns, rather than an assumption that it doesn't.

[JarryShaw]

Round 2 verified at 36c50c2a1 — everything re-run by me, not read off the report. Label moved to review: pending; a cross-review on a third model is in flight, so this is not a good-to-go yet.

• All four sites fixed, and only those four: the two FEATCode class docstrings (#secion-3) and the two Command.feat attribute docstrings under if TYPE_CHECKING: (#secion-2.2). get()'s :rfc:5797#section-2`` untouched throughout.
• KNOWN_DEFECTS and the Known NamedTuple are gone, along with the known subtraction. test_no_new_malformed_fragments is now test_no_malformed_fragments with a plain empty-set assertion, and a third exact-site pin was added for the feat docstring — the author's reasoning being that the house style (RetiredNameTests, FailedLookupExceptionTests) pins fixed defects by site and not only by shape. Agreed.
• The invariant holds at zero. My own census over pcapkit/: 645 :rfc: roles carrying a # fragment, 0 malformed. grep -rn secion pcapkit/ returns nothing.
• Pre-fix proof, mine: reverting all four lines fails 3/3 tests; restoring passes 3/3. tests/project whole directory 199 tests, OK, 1 skipped.
• One commit, merge-base 1bd576ec1 = current main, correct authorship.

Two process notes worth recording rather than leaving implicit. This widening was my correction of my own brief, not a defect in the author's work — round 1 did exactly what I asked and I asked for the wrong thing. And the label swap needed three attempts: gh pr edit --remove-label … --add-label … is a single GraphQL mutation and it half-applied, landing the removal and dropping the addition, so this PR briefly carried no review: label at all. Adding via REST worked. Flagging because a silently-missing verdict label is worse than a stale one.

[JarryShaw]

NEEDS CHANGES at 36c50c2a1 — Fable cross-review (author was Sonnet). The four-line fix is correct and complete; the finding is in the new test's own contract, and it is a real one.

The regex blesses 10 provably dead anchors — the exact defect class the test exists to prevent. ACCEPTED_FRAGMENT's bare-\d+(\.\d+)* alternative accepts 9 fragments in pcapkit/const/tcp/mp_tcp_option.py (:rfc:8684#3.1 … `#3.7`) and one at `pcapkit/const/reg/apptype/tcp.py:268` (`:rfc:`8765#6.1). Measured: rfc8684.html carries id="section-3.1" once and id="3.1" zero times. So the module docstring's opening line — "Every :rfc: role's # fragment must name a real RFC anchor shape" — is false for that alternative.

The review recommended grandfathering these because fixing them "would require an IANA regeneration". It does not, which is why I am fixing instead. Traced: pcapkit/vendor/tcp/mp_tcp_option.py:59 and pcapkit/vendor/reg/apptype/apptype.py:1146 both emit f'…#{match.group("sec")}…', parsing IANA's RFC8684, Section 3.1 into sec = "3.1" and simply omitting the section- prefix. grep -rnE ':rfc:[0-9]+#[0-9]' pcapkit/vendor/is empty — the vendor tree synthesises these rather than carrying them, the same generator/generated split this PR already handles forftp/command.py`. Two f-string tokens plus ten mechanical const lines, no crawl.

Two docstring claims are also wrong, both confirmed. "nitpicky mode only checks py: targets" fails twice over: grep -cE 'nitpicky|nitpick_ignore' docs/source/conf.py returns 0, so nitpicky is not enabled at all, and it checks every domain rather than only py:. The true reason nothing warns is that :rfc: emits a plain nodes.reference with a refuri, never a pending_xref. And under Sphinx the role is sphinx.roles.RFC, not the cited docutils…rfc_reference_role — both append verbatim, so the conclusion holds, but the cited implementation is the one that does not run.

Round 3 is with the author: fix both generators, fix the 10 const lines, drop the bare alternative outright, and re-prove the census at 0 under the stricter regex.

One correction to the review, and one to a framing of mine. It reported the 9 sites as being in mp_tcp_option.py "+ its vendor pair" — the vendor file carries none of them. And its note that git grep secion is not zero tree-wide is about my brief, not about what I published here: my earlier comment scoped that grep to pcapkit/, where it is genuinely zero. The 6 hits are the test file quoting the historical typo on purpose.

I am widening this past what #942 literally names. I think that is right — the test found the defect, the fix is mechanical, and grandfathering 10 dead links inside the invariant meant to catch them repeats the KNOWN_DEFECTS mistake one layer down. Say the word if you would rather it were split out.

[JarryShaw]

Round 3 verified at ca41c6b23. review: pending; an Opus cross-review is in flight on the new content, so not a good-to-go yet. Everything below I re-ran rather than read off the report.

• All 14 literal sites plus both generator lines changed, and nothing else. +182/−16 over seven files: the four secion sites, the ten bare-number sites (9 in const/tcp/mp_tcp_option.py, 1 at const/reg/apptype/tcp.py:268), and #{sec} → #section-{sec} in vendor/tcp/mp_tcp_option.py:59 and vendor/reg/apptype/apptype.py:1146.
• The ten new anchors are real, which is the point of the whole exercise. Fetched both RFCs and grepped: id="section-3.1", 3.2, 3.3, 3.3.8, 3.4.1, 3.4.2, 3.5, 3.6, 3.7 in rfc8684.html and id="section-6.1" in rfc8765.html — each exactly once. Shape-conformance would not have been enough; these resolve.
• The bare alternative is gone, not merely unused. ACCEPTED_FRAGMENT is now \A(?:section-\d+(?:\.\d+)*|appendix-[A-Z](?:\.\d+)*)\Z. My own census with an independently written strict regex: 645 fragments, 0 malformed.
• Pre-fix proof: reverting all 14 sites fails 3/3, and the assertion names exactly those 14 findings. Restored, 3/3 pass. tests/project 199 tests OK, 1 skipped. One commit, merge-base 1bd576ec1, correct authorship.
• Both docstring claims I had found wrong are now right, and checked against the real source rather than restated: the role that runs under Sphinx is sphinx.roles.RFC.build_uri, returning a nodes.reference and never a pending_xref; and nothing warns because there is no cross-reference node to inspect — not because nitpicky is py:-scoped, which it isn't, and which this repo does not enable anyway.

The author also volunteered its reasoning on the scope question rather than just complying, and I agree with it: the 10 dead anchors were surfaced by the very test #942 asked for, and grandfathering them would have repeated the KNOWN_DEFECTS mistake one layer down.

What the cross-review is specifically hunting, because it is the one thing neither of us can settle by reading the diff: both generators interpolate #section-{sec} where sec comes from re.fullmatch(r'RFC(?P<rfc>\d+)(, Section (?P<sec>.*?))?', rfc). A lazy unanchored .*? could in principle capture a range or an appendix, which would make the generator emit #section-3.1 and 3.2 on input it has not seen yet — and the new test reads only the generated tree, never the generator, so it would not catch it.

[JarryShaw]

NEEDS CHANGES at ca41c6b23 — Opus cross-review (author Sonnet; the earlier Fable pass produced the finding round 3 implements, so it could not review its own prescription). Two blocking items, both small, and it refuted a framing of mine.

My error first. I wrote above that the new test could not catch a generator emitting a bad fragment, since it reads only the generated tree. Wrong. The review enumerated what #section-{sec} can produce and I verified each against the regex: section-3.1 and 3.2, section-4.1.1.1., section-A.1, section- — all four rejected. A regeneration producing one would fail test_no_malformed_fragments. The limitation is ordering, not a hole.

1. ACCEPTED_FRAGMENT rejects page-N, which is real and which this repo already blesses. sphinx.roles._format_rfc_target titles exactly {'appendix', 'page', 'section'}; tests/project/test_changelog_md.py:184 enumerates '793#page-5' as a correctly rendered citation; and id="page-5" is present in RFC 959's HTML. So two test files in the same directory now disagree about what a valid anchor is, and a correct future :rfc:793#page-5`` would fail. Adding |page-\d+, justified as Sphinx's own set rather than "shapes in use today".

2. The invariant is shape-only, and the body reads as though it were anchor coverage. The review proved the gap with a live case: :rfc:959#section-4.1`` at six sites, four of them in the two ftp/command.py files this PR edits. RFC 959 predates per-subsection anchors — its HTML carries only `section-1`…`section-8`, and `id="section-4.1"` returns 0 on both rfc-editor and datatracker. A dead link of exactly #942's kind, which this test passes.

Filed as #944 rather than fixed here, because the fix is an editorial choice about what to cite instead — #section-4, a #page-N, or no fragment — not a spelling correction. needs: decision. This PR gains one sentence stating the limitation and pointing at #944.

3. The title is narrower than the change — still names only #secion-3 while the commit headline and body cover two defect classes. Being widened.

Everything else came back confirmed, independently: the 645/0 census, both corrected docstring claims against the real Sphinx source, and the loosened FEATCode pin — mutation-tested, and it fails on the citation line rather than the base-class part.

Two notes needing no action, recorded so nobody re-finds them: mp_tcp_option.py does not .strip() its split tokens where apptype.py does — pre-existing, and it would fail the new test rather than pass silently; and docs/source/**/*.rst holds 184 further :rfc: fragments outside the pcapkit/-only sweep, all censused as well-formed.

[JarryShaw]

GOOD TO GO at 480fdd1f4 — round 4 closes both of the Opus review's blocking items and the title point, all three verified by me rather than read off the report.

• ACCEPTED_FRAGMENT now accepts page-N: \A(?:section-\d+(?:\.\d+)*|appendix-[A-Z](?:\.\d+)*|page-\d+)\Z. My own table over the widened regex: page-5 accepted; page-, section-, section-A.1, section-3.1 and 3.2, introduction and bare section all rejected. Widening masked nothing — reverting all 14 sites still fails 3/3 with the same 14 findings, and restoring passes 3/3. Census unchanged at 645 total, 0 malformed; tests/project 199 OK, 1 skipped.
• The shape-only limitation is stated, in the module docstring and the PR body, pointing at docs(const,vendor): six :rfc:959#section-4.1 citations name an anchor RFC 959 does not have #944 as the live instance it cannot catch.
• Title widened to match the commit headline, which had been carrying two defect classes under a round-1 title.
• I rebased it onto 9ea0d6a5a (it was BEHIND after docs(conventions,const): resolve part B's unresolved cross-references (#934) #941 merged, and the ruleset has strict_required_status_checks_policy: true). All seven files are byte-identical to the head I verified, and the merge-base delta is unchanged, so the verdict carries forward rather than needing a re-review. The six pcapkit/ files are also byte-identical between 1bd576ec1 and 9ea0d6a5a, which is what lets round 3's zero-delta linter result stand without re-running.

One place I disagree with the cross-review, in the author's favour. It framed the sibling tests/project/test_changelog_md.py as blessing 9293#introduction and 9293#section as valid anchors, implying the stricter regex wrongly rejects them. Reading that test's own comment — "Measured against sphinx.roles._format_rfc_target: it titles three anchor prefixes and leaves every other anchor as written" — it is asserting rendering behaviour and explicitly enumerating the left-alone cases. It makes no validity claim. So the genuine disagreement between the two files was page-N alone, which is now fixed, and rejecting the other two is the right call: neither appears under pcapkit/, and a bare section is indistinguishable from a citation that lost its number.

Three cross-reviews across four rounds, each on a model other than the Sonnet author: Fable found the KNOWN_DEFECTS shape problem, Opus found the dead page-N rejection and #944, and Opus also refuted a framing of mine about the generator being unguarded. Unpublished and yours to merge — CI is re-running on the rebased head; I'll confirm it lands clean.

[JarryShaw]

Carrying the GOOD TO GO forward to daf6cb258. My verdict above names 480fdd1f4, which my own rebase then superseded — and a verdict pinned to a head that no longer exists is worse than none, so recording the move here rather than leaving the label to imply it.

main advanced to 2dd988862 — not a maintainer push but github-actions[bot], "Bumped build to 1", touching only conda/build and conda/requirements.txt. The ruleset's strict_required_status_checks_policy means any push to main puts every open PR out of date, so this needed rebasing to stay mergeable.

The rebase is content-preserving, checked rather than assumed: every file in the merge-base delta is byte-identical by md5 between 480fdd1f4 and daf6cb258, and the bot's two files are disjoint from all seven of this PR's. So nothing here has changed since the head I verified, and the verdict stands unaltered.

CI is re-running on the new head. I will confirm it lands clean before calling this ready to merge; it remains unpublished and yours.