docs(pcapng): repoint the generator's stale journal-defect citation

[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 under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible — 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

The defect is gone, not merely mis-cited. _journal_entry's docstring
cited pcapkit/protocols/schema/misc/pcapng.py:1376 for a
split-without-stripping-padding defect. The line number was correct when
written, but the fix is #699 (closing #678), not #728/#723 as an
earlier revision of this PR claimed: #699 added the
not line.strip(b'\x00') guard; #728 only moved it while rewriting the
parser to walk instead of split. #723 is a different symptom (content
shredded by the b'\n\n' split), confirmed with
git log -S "strip(b'\x00')" and by diffing 8af2cfda7 against 73b8cc87f.

Measured directly: built a misaligned journal entry through the real
_Blocks writer, bypassing _journal_entry's alignment loop, and parsed it
with the current Extractor — one entry, zero SchemaWarnings (an unrelated
ExtractionWarning: EOF reached fires on the aligned entry too, so it isn't
literally warning-free).

The docstring now cites #699 and the mechanism rather than a bare line
number. The workaround stays because dropping it regenerates the untracked
test.pcapng fixture (examples/captures/* is gitignored) — not because it
touches committed bytes, as an earlier revision said. Also fixed
_Blocks.journal's docstring, which credited "the caller" for padding
entry when _Blocks.block does it.

Swept every path.py:N citation in the file — only this one exists; two
other pcapkit-internal references (not one) carry no line number and are
fine as-is.

Closes #791

[JarryShaw]

Labelled docs + review: pending at 1c88384ec. The investigation answered #791 decisively, and refined the framing I filed it with.

I asked whether :1376 was already wrong when written or had drifted since. It is the second, with an identified cause — verified directly:

$ git show 12f3e58d9:pcapkit/protocols/schema/misc/pcapng.py | sed -n '1376p'
        for entry_buffer in self.entry.split(b'\n\n'):

$ git log --oneline -1 73b8cc87f
73b8cc87f fix(pcapng): walk the journal entry instead of splitting it on b'\n\n' (#728)

$ git show origin/main:pcapkit/protocols/schema/misc/pcapng.py | grep -n "entry.split"
1805:            Entries used to be split apart with ``self.entry.split(b'\n\n')``   <- past tense only

So the citation was correct when written at 12f3e58d9, and #728 (73b8cc87f, closing #723) moved the code out from under it by rewriting SystemdJournalExportBlock.post_process to walk the entry through io.BytesIO. That also settles the second half of #791: the defect it described is gone, so the comment was justifying a workaround on grounds that no longer hold.

Confirmed the behavioural claim on merged main rather than taking it — tests/protocols/misc/test_pcapng_unit.py -k "padding or journal": 11 passed, 26 subtests, including test_an_ordinary_journal_entry_is_not_broken_by_its_own_padding at :4174.

The fix does the right thing with the fixture: it keeps the alignment loop and says why — dropping it would change committed fixture bytes, which is wider than a citation fix — and flags removal as a follow-up rather than smuggling it in. It also replaces the bare number with the construct name plus issue links, which is the form that cannot drift; that is the pattern I would like the other instances of this defect class to follow.

One correction to my own report a moment ago: my first attempt to run that test printed FAILED (errors=1) on "Ran 1 test" — that was a test class name I guessed wrong, not a failure. The numbers above are from the corrected run.

Cross-review dispatched on a different model from the author before I set a verdict.

[JarryShaw]

Cross-review at 1c88384ec (haiku, a different model from the author): NEEDS CHANGES — the new docstring replaced a stale line number with a wrong causal story. This also corrects my own comment above, which repeated the same attribution.

The padding defect was fixed by #699 (for #678), not by #728 (for #723). Verified four ways:

$ git log -S "strip(b'\x00')" --oneline --reverse -- pcapkit/protocols/schema/misc/pcapng.py
8af2cfda7 fix(pcapng): stop a negative length reaching a read on a truncated capture (#678) (#699)

$ git show 73b8cc87f -- .../pcapng.py | grep -E "strip\(b'..x00'\)|if not line"
-                if not line or not line.strip(b'\x00'):
+                if not line:
+                if not line.strip(b'\x00'):

So #728 moved that guard, it did not add it — the NUL-only-line check already existed. The reviewer bisected it: 8af2cfda7 parses a misaligned entry cleanly with self.entry.split(b'\n\n') still fully in place. Two consequences for the prose:

• The split is not the cause. For b'MESSAGE=hello\n\x00\x00' the split is a no-op — no b'\n\n' present — and the failure still happened. The cause is bytes.strip() not treating NUL as whitespace, which post_process's own docstring already says at :1772-1779.
• pcapng: journal entry split on b'\n\n' shreds binary data that contains it #723 is the wrong issue. Its title is "journal entry split on b'\n\n' shreds binary data that contains it" — content shredding, not padding. Corroborating: the regression test lives in PCAPNGNegativeLengthTests, the class named for Every EOF-truncated PCAP-NG file raises an uncaught ValueError: pcapng_block_selector passes a negative __length__ to SchemaField #678's work.

Two things separate but true: the line number drifted because #728 rewrote the code, and the defect was fixed earlier by #699. My comment above conflated them.

Second false claim: "committed bytes".

$ git ls-files examples/captures/
examples/captures/dhcp.pcapng
examples/captures/in.pcap

test.pcapng is untracked — this file's own module docstring says so at :4-6. Keeping the loop is still right, but the honest cost is "regenerating an untracked fixture", not changing committed bytes.

Also: "neither error nor warning" is literally false — ExtractionWarning: EOF reached fires, identically on the aligned entry, so unattributable to padding. The accurate claim is the one the existing test asserts: no SchemaWarning.

The review confirmed the defect is gone, the fixture bytes are provably identical (sha256=a0da0ddf…, 3100 octets both trees), and the test numbers exactly (88/1/1753; 11/26). Its judgement on length is that 22 lines is not earned — the mechanism is already told more accurately in post_process's docstring and two test docstrings, so this is a fourth retelling and a fourth place to drift. I agree; routing a ~6-line replacement that cites #699 and drops the committed-bytes claim.

[JarryShaw]

Delta re-check at 3b977f873 (haiku, resumed so it re-checked its own findings): GOOD TO GO on all five, with three non-blocking nits. I took two of them — they were prose defects in a prose-precision PR, and shipping those here would have been the same mistake this PR exists to fix. New head d6ade65e8, content-only:

• "an untracked fixture, not a prose change" → "an untracked fixture change, not a prose one". The reviewer's point, which I asked it to judge and agree with: the appositive sits next to test.pcapng, so the nearest parse compares a file to a kind of change. The intended reading needed the reader to supply an elided noun.
• journal()'s cross-reference said "see _journal_entry for why that distinction matters" while pointing at prose whose conclusion is that it stopped mattering. Now "used to matter".

I skipped its third nit deliberately — restoring SystemdJournalExportBlock.post_process alongside #699 for navigability. The issue link is the drift-proof form #791 asked for, and re-adding the construct name lengthens exactly what we just trimmed from 22 lines to 10. Say the word if you'd rather have it.

What it verified rather than accepted, on a tree proven with PYTHONSAFEPATH=1 PYTHONPATH=… and an asserted pcapkit.__file__:

• Every clause of the replacement: _Blocks.block pads at :273 (body = self.pad(body)); pad is -len(data) % 4 so an aligned body gets zero octets; 8af2cfda7 is the sole introducer of not line.strip(b'\x00') and its tree parses the misaligned entry cleanly with the split still present; the link resolves to /pull/699; and ef859f776 is genuinely the merge-base the measurement names.
• The wrong causal story leaves no trace — grepping 723|728|1376|"so an unaligned" returns only unrelated hits (split high word first at :302, address.split('.') at :482, a local def split at :514).
• "untracked" is not an overcorrection: the three surviving uses of "committed" at :15, :44, :377 all refer to dhcp.pcapng, which is tracked — so the file now draws the distinction rather than flattening it.
• The fixture is still byte-identical: build_test() = 3100 octets, sha256=a0da0ddf… on both sides. Tests unchanged at 88 passed / 1 skipped / 1753 subtests.

It also confirmed nothing load-bearing went with the trim: the exact unpack requires a buffer of 8 bytes string survives in post_process's docstring and the tests, and "which the specification allows" is already in _Blocks' class docstring and forced arithmetically anyway.

Setting review: good-to-go. CI is re-running on the new head; I will say so if anything turns red rather than let the label imply otherwise.