npm remote test comments cite moved harness helpers, and the comment cap has no ratchet for a citation-only fix

Problem

!1943 (merged) extracted the shared npm remote integration fixture harness and closed #788 (closed). Doing so moved several helpers out of two test files, which left three citations of those helpers pointing at the wrong place. Two are comments that are now false. The third is the reason both were left that way.

scripts/ci/check-comment-caps.sh caps a touched comment block in a _test.go file at 2 lines and charges the whole block, with no waiver by design. So correcting a one-line citation inside a long legacy block reports the whole block as a breach, and the only compliant edit is to compress the block to 2 lines and delete the rest. In both cases below, compressing would cost more than the wrong citation does, so !1943 (merged) left the citation wrong and said so in its description.

The two wrong citations

Both verified on main at 3c26bfef6.

internal/format/npm/remote_tarball_integration_test.go:38-42 lists what the file reuses from the rest of the test binary and names seedNamespace, seedNpmRepositoryKind and rpTxRunner. The file no longer calls any of the three directly. They arrive through rpSeedRemoteRepository and rpNewOperations, and the only occurrence of each name in the file is the header mention itself. A two-line note under the block records that the list is neither current nor complete, so the staleness is disclosed rather than hidden, but a reader looking for the names still finds a list that does not describe the file. Editing the sentence reports the block at 40 lines against the cap of 2.

internal/format/npm/remote_disttags_integration_test.go:1050 calls its cap-breach test "the only caller of rdtNewFixture's maxPackumentBytes override". Which test sets the knob is still true. Where the knob lives is not: it is a field on rpConfig, applied in rpNewFixture at remote_packument_harness_integration_test.go:409. Editing it reports 18 lines against the cap of 2, and the block also carries the leader and follower split, the Retry-After rationale and the barrier note.

The decision worth making

A refactor that moves a symbol cited from a long legacy comment block currently has two options, and neither is good:

  • leave the citation false, which is what !1943 (merged) did twice, and which has no ratchet, so the count of false citations only grows;
  • absorb an unrelated compression of a block the MR did not otherwise touch, which enlarges the diff and deletes context the block was carrying for a reason.

!1943 (merged) flagged this as worth a separate decision rather than a per-MR judgement, which is why it is here rather than in that MR.

Options to weigh:

  • allow a citation-only correction inside an over-cap block, on the grounds that it does not grow the block;
  • measure the cap on the delta rather than on the whole block;
  • keep the cap as is and accept that these citations rot, with a periodic sweep to fix them in dedicated MRs where the compression is the point.

Acceptance

  • The two citations above either name the right symbol or are gone.
  • scripts/ci/check-comment-caps.sh behaviour for a citation-only edit is decided and written down in the place that describes the cap.

Source

Raised by !1943 (merged)'s "Two things deliberately left alone" section, and by verifying #788 (closed) before closing it.

Related to #788 (closed)