`buf format` silently deletes a comment that is separated from the following element by a blank line inside an option aggregate (not idempotent)

[garrettr]

buf version: 1.72.0 (also reproduces on 1.71.0; 1.70.0 is unaffected). Built from source at tag v1.72.0, linux/amd64, Go 1.26.4.

Command: buf format repro.proto, applied repeatedly to its own output.

Repro file (repro.proto)

syntax = "proto3";

package example.v1;

import "google/protobuf/descriptor.proto";

message CallerEntry {
  string service_account = 1;
}

message AclRule {
  repeated CallerEntry callers = 1;
}

extend google.protobuf.MethodOptions {
  AclRule acl = 50001;
}

message Req {}
message Resp {}

service ExampleService {
  rpc GetThing(Req) returns (Resp) {
    option (example.v1.acl) = {
      callers: [
        {service_account: "beta"},
        /* detached comment */

        {service_account: "gamma"}
      ]
    };
  }
}

Observed

Each pass produces different output, and the comment is destroyed on the second pass.

Pass 1 — the comment moves past the element it annotated, down to the closing bracket, and is dedented to the bracket's level:

      callers: [
        {service_account: "beta"},
        {service_account: "gamma"}
      /* detached comment */

      ]

Pass 2 — the comment is gone from the output entirely:

      callers: [
        {service_account: "beta"},
        {service_account: "gamma"}
      ]

Pass 3 and later are identical to pass 2, so the file settles into a stable state with the comment permanently lost.

Expected

format(format(x)) == format(x), and no comment content is ever dropped.

Notes

• The trigger is the blank line between the comment and the element that follows it. Deleting the blank line from the repro makes the file stable after pass 1 with the comment preserved in place.
• Comment style does not matter: a // detached comment in the same position is deleted the same way.
• The comment drifts one element per pass before being deleted, so a longer list delays the loss rather than avoiding it. With three following entries the deletion lands on pass 3 instead of pass 2, which makes it easy to miss — a single format run looks merely like an odd reflow, and the content disappears on a later, unrelated run.
• Practical impact: buf format -w in a pre-commit hook. The first commit that touches such a file moves the comment, a later commit deletes it, and neither diff is obviously a content loss to a reviewer.
• 1.70.0 does not lose the comment. It joins it onto the following element instead (/* detached comment */ {service_account: "gamma"}), which is stable under repeated formatting.

[garrettr]

I dug into this and found the root cause. It's in the trivia walker in protocompile's new printer, and it's broader than comment deletion — the same defect silently moves and drops blank lines, with no comments involved at all.

Root cause

The trivia walker assigns each scope one "slot" of detached trivia per element, and the printers look those slots up by element index. Inside a literal, an element whose value is a {...} brace ends before its own comma, so that comma opens a slot of its own. Every later slot is then shifted by one: detached trivia is attributed to the wrong element, and is dropped entirely once the shift pushes it past the final slot.

That accounts for the pass-by-pass drift in the original report. Dumping the trivia index for the repro above, a two-element array produces four slots, with the comment in slot[2] — the index the printer treats as "final slot, emit before ]". On the next pass it lands in slot[3], which no printer path reads, so it is dropped. Each brace-valued element adds one slot, which is why a longer list delays the deletion by a pass.

The same bug without any comments

Blank lines are tracked by the same shifted index, so they move too:

syntax = "proto3";

package example.v1;

import "google/protobuf/descriptor.proto";

message Item {
  string name = 1;
}

message ItemList {
  repeated Item items = 1;
}

extend google.protobuf.MessageOptions {
  ItemList item_list = 50001;
}

message Example {
  option (example.v1.item_list) = {
    items: [
      {name: "a"},

      {name: "b"},
      {name: "c"},
      {name: "d"}
    ]
  };
}

buf format moves the blank line down one element, from before {name: "b"} to before {name: "c"}. Move the blank line one element further down in the input and it is deleted outright, because it shifts past the last element.

This part needs no repeated passes and no comments — a single buf format reflows the file. I ran a differential format over ~1,500 .proto files from this repo and protocompile: three of them change, and in all three the current output shifts every blank line in a message literal down by one element relative to the source.

Fix

The fix belongs in protocompile (experimental/ast/printer/trivia.go), since that's where the formatter now lives: in a literal scope, when a brace would end an element but a comma follows, let the comma end it instead. Commas are optional between message literal fields, so a brace with no following comma must still end the element.

I've opened a PR upstream: bufbuild/protocompile#745

With that patch, the repro in this issue and the blank-line cases above are all fixed points from the first pass, and the existing TestFormat golden corpus is unchanged apart from the three files noted above, which move to matching their source.

[emcfarlane]

Thanks for finding the issue and putting up a fix! Will merge into protocompile and upstream here when available.