docs(wire): VcsTrendPoint/VcsTrend test comment claims #[serde(flatten)] Vcs, but the field is nested

[dekobon]

Summary

The test comment for vcs_trend_point_round_trips_through_yaml_and_cbor
in src/wire.rs claims VcsTrendPoint and VcsTrend use
#[serde(flatten)] Vcs, but neither struct uses #[serde(flatten)] —
the Vcs block is a nested vcs: key. The comment's CBOR-footgun
rationale (flatten + CBOR) therefore describes a hazard the code does
not actually have.

Location

• src/wire.rs:1064-1067

Evidence

The comment (lines 1064-1067):

/// Issue #702: `VcsTrendPoint` and `VcsTrend` use `#[serde(flatten)]
/// Vcs`, a known CBOR footgun. CBOR is a *written* trend format but was
/// never *read back* in tests — pin the round-trip for both YAML and
/// CBOR.

The actual struct definitions carry no flatten attribute; the Vcs
block is a plain nested field:

pub struct VcsTrendPoint {
    pub as_of: i64,
    pub vcs: Vcs,        // nested key "vcs", not flattened
}

rg -n flatten src/wire.rs returns only the comment itself — there is
no #[serde(flatten)] anywhere in the file. The module docs and the
VcsTrendPoint / VcsTrend doc comments elsewhere correctly describe
the metrics as sitting "under a nested vcs key (issue #684)", directly
contradicting this test comment.

Expected Behavior

The comment should describe the actual serialized shape: a nested vcs
object (not a flattened set of keys). The round-trip-test rationale can
keep the "written-but-never-read-back CBOR" motivation, but must not
attribute it to #[serde(flatten)].

Actual Behavior

The comment asserts a #[serde(flatten)] design that does not exist,
misleading a reader about both the wire shape and the specific CBOR
hazard being guarded against. (The #[serde(flatten)]+CBOR footgun is
real in general — adjacently-tagged/flattened maps can break CBOR
round-trips — but it does not apply here because no field is flattened.)

Impact

Documentation-only. A maintainer reading the test to understand the
serialized VCS-trend shape (or deciding whether flatten-related CBOR
caveats apply when editing these structs) is actively misinformed. No
runtime behavior is affected.

---

Resolution

Corrected the wire.rs test comment: VcsTrendPoint/VcsTrend use a nested vcs key, not serde(flatten). Kept the write-only-untested CBOR round-trip rationale. Commit a7e35ad.

[dekobon]

General Plan for Fix

Root Cause

The comment was likely written when an earlier VcsTrendPoint design
flattened the Vcs block (the #[serde(flatten)] + CBOR interaction is
a genuine footgun worth a round-trip test). The structs were later
reshaped to nest the metrics under a vcs key (issue #684), but the
test comment was not updated to match.

Implementation Steps

1. Edit the comment above vcs_trend_point_round_trips_through_yaml_and_cbor
   (src/wire.rs:1064-1067) to describe the actual nested-vcs-key
   shape. Keep the real motivation — CBOR is a written trend format that
   was never read back in tests, so the round-trip is worth pinning — but
   drop the false #[serde(flatten)] attribution.

   Suggested replacement:

   /// Issue #702: `VcsTrendPoint` and `VcsTrend` nest the always-slim
   /// `Vcs` block under a `vcs` key (#684). CBOR is a *written* trend
   /// format but was never *read back* in tests — pin the round-trip for
   /// both YAML and CBOR so a future serde-shape change (e.g. switching
   /// to `#[serde(flatten)]`, a known CBOR footgun) is caught.
   

2. No code change — the test body and struct definitions are correct.

Tests to Add/Update

• None. The existing round-trip tests already exercise the nested shape;
  only the comment is wrong.

Verification

• rg -n flatten src/wire.rs returns no matches after the edit (or
  only a correct forward-looking mention).
• cargo test -p big-code-analysis --features vcs-git wire:: passes
  (round-trip tests still green; behavior unchanged).
• Manual read: the comment now matches the pub vcs: Vcs nested
  field and the #684 nested-key wording used elsewhere in the file.

[dekobon]

Fixed in commit a7e35ad. The wire.rs test comment no longer claims VcsTrendPoint/VcsTrend use #[serde(flatten)] (confirmed: flatten appears only in the comment; the vcs field is a plain nested key). The accurate write-only-untested CBOR round-trip rationale is kept.

[dekobon]

Fixed and merged to main in #957. GitHub did not auto-close this from the batched commit's single Fixes #a #b #c … trailer (only the first referenced issue auto-closes); closing manually. See the Resolution section in the body for details.