Sebuf

Phase 1: Foundation - Quick Wins Verification Report

Phase Goal: Existing bugs are fixed, pending work is landed, and resolved issues are closed so the codebase is clean before structural changes

Verified: 2026-02-05T16:01:10Z

Status: PASSED

Re-verification: No - initial verification

Goal Achievement#

Observable Truths#

# Truth Status Evidence
1 Running go build ./cmd/protoc-gen-go-client/ produces a binary without unused net/url imports for POST-only services ✓ VERIFIED fileNeedsURLImport() function exists in generator.go:73, conditionally returns true only for path params or query params. Golden file backward_compat_client.pb.go (POST-only) does NOT contain "net/url" import (verified via grep). Build succeeds.
2 A service with only POST methods generates client code without net/url in import block ✓ VERIFIED backward_compat_client.pb.go contains imports at lines 6-19, no "net/url" present. Has "net/http" but not "net/url".
3 A service with GET query params or path params still generates net/url import ✓ VERIFIED query_params_client.pb.go and http_verbs_comprehensive_client.pb.go both contain "net/url" import (verified via grep returning these files).
4 Cross-file unwrap annotations resolve correctly when wrapper message is in different proto file within same Go package ✓ VERIFIED GlobalUnwrapInfo struct exists in unwrap.go:61, CollectGlobalUnwrapInfo() exists at line 76. Test fixtures same_pkg_service.proto and same_pkg_wrapper.proto exist. TestCrossFileUnwrapResolution test passes with 4/4 subtests.
5 GitHub issue #91 (root-level arrays) is closed with documentation comment ✓ VERIFIED Issue state: CLOSED. Closing comment documents (sebuf.http.unwrap) = true syntax with proto example, expected JSON output, test file references, and cross-generator note.
6 GitHub issue #94 (field name casing) is confirmed closed with adequate documentation ✓ VERIFIED Issue state: CLOSED. Closing comment documents proto3's built-in json_name field option with proto example and rationale that sebuf-specific annotation would create confusion.

Score: 6/6 truths verified (100%)

Required Artifacts#

Artifact Expected Status Details
internal/clientgen/generator.go Contains fileNeedsURLImport function and conditional import logic ✓ VERIFIED Function exists at line 73, checks path params (line 78) and query params on GET/DELETE (lines 87-91). Returns bool correctly.
internal/clientgen/generator.go:writeImports Conditionally emits net/url based on needsURL parameter ✓ VERIFIED Function signature at line 123 accepts needsURL bool parameter. Line 133-135: conditional if needsURL { gf.P(\"net/url"`) }`
internal/clientgen/testdata/golden/backward_compat_client.pb.go Should NOT have net/url import (POST-only service) ✓ VERIFIED Grep for "net/url" returns NO match in this file. Only has "net/http" at line 12. File exists and is substantive (30+ lines).
internal/httpgen/unwrap.go Contains GlobalUnwrapInfo and cross-file resolution ✓ VERIFIED GlobalUnwrapInfo struct at line 61, CollectGlobalUnwrapInfo() at line 76, NewGlobalUnwrapInfo() at line 67. All substantive implementations with proper logic.
internal/httpgen/generator.go:globalUnwrap Generator has globalUnwrap field of type *GlobalUnwrapInfo ✓ VERIFIED Line 17: globalUnwrap *GlobalUnwrapInfo field in Generator struct with comment.
internal/httpgen/testdata/proto/same_pkg_service.proto Cross-file test fixture exists ✓ VERIFIED File exists (1339 bytes, modified Feb 5 17:54). Contains service using cross-file wrapper.
internal/httpgen/testdata/proto/same_pkg_wrapper.proto Cross-file test fixture exists ✓ VERIFIED File exists (730 bytes, modified Feb 5 17:54). Contains wrapper message with unwrap annotation.

All required artifacts present, substantive, and wired correctly.

From To Via Status Details
generateClientFile fileNeedsURLImport needsURL boolean ✓ WIRED Line 54 calls needsURL := g.fileNeedsURLImport(file), line 57 passes to g.writeImports(gf, needsBytes, needsURL)
fileNeedsURLImport writeImports needsURL parameter ✓ WIRED needsURL result is passed to writeImports at line 57, writeImports uses it at line 133 to conditionally emit import
writeImports generated output conditional gf.P ✓ WIRED Lines 133-135: if needsURL { gf.P(\"net/url"`) }` - only emits import when true. Golden files confirm: backward_compat has no net/url, query_params has net/url
Generator.Generate CollectGlobalUnwrapInfo Phase 1 collection ✓ WIRED generator.go:44 calls g.globalUnwrap = CollectGlobalUnwrapInfo(g.plugin.Files) before code generation phase
collectUnwrapContext globalUnwrap map Cross-file resolution ✓ WIRED unwrap.go:109 checks if g.globalUnwrap != nil and uses g.globalUnwrap.UnwrapFields map at line 110 for cross-file lookups
generateUnwrapFile collectUnwrapContext Unwrap context creation ✓ WIRED unwrap.go:286 calls ctx := g.collectUnwrapContext(file), which uses global unwrap map when available

All critical links properly wired. Two-pass generation pattern implemented correctly.

Requirements Coverage#

Requirement Status Supporting Evidence
FOUND-02: Fix #105 - conditional net/url import ✓ SATISFIED fileNeedsURLImport function exists, writeImports conditionally emits net/url, backward_compat golden file has no net/url, issue #105 closed
FOUND-03: Land PR #98 - cross-file unwrap ✓ SATISFIED GlobalUnwrapInfo implemented, two-pass generation pattern in place, test fixtures exist, TestCrossFileUnwrapResolution passes, cross-file unwrap works
FOUND-05: Verify #91 closed ✓ SATISFIED Issue #91 closed with detailed comment documenting unwrap annotation syntax, proto example, test references, and cross-generator note
FOUND-06: Close #94 ✓ SATISFIED Issue #94 closed with comment documenting proto3 json_name field option and rationale against sebuf-specific annotation

All 4 requirements satisfied.

Anti-Patterns Found#

No blocker anti-patterns detected.

Warnings:

  • None

Info:

  • Cross-file unwrap implementation uses two-pass generation (collect then generate) - this is intentional design pattern
  • fileNeedsURLImport checks both path params AND query params - comprehensive coverage

Human Verification Required#

None. All success criteria can be verified programmatically and have been verified.

Verification Details#

Truth 1: Conditional net/url Import for POST-only Services#

Verified via:

  1. Code inspection: fileNeedsURLImport() exists at generator.go:73
  2. Logic check: Returns true only when path params exist OR query params on GET/DELETE exist
  3. Golden file check: backward_compat_client.pb.go (POST-only service) does NOT contain "net/url"
  4. Build check: go build ./cmd/protoc-gen-go-client/ succeeds without errors
  5. Test check: TestClientGenGoldenFiles passes

Evidence artifacts:

  • internal/clientgen/generator.go:71-96 - fileNeedsURLImport implementation
  • internal/clientgen/generator.go:123-144 - writeImports with conditional net/url
  • internal/clientgen/testdata/golden/backward_compat_client.pb.go - no net/url import present

Truth 2 & 3: POST-only vs GET/query-params Import Behavior#

Verified via:

  1. Grep for "net/url" in golden files directory
  2. backward_compat (POST-only): NO net/url import
  3. query_params: HAS net/url import
  4. http_verbs_comprehensive: HAS net/url import

Evidence: Grep returned only 2 files with "net/url", neither was backward_compat

Truth 4: Cross-file Unwrap Resolution#

Verified via:

  1. Code inspection: GlobalUnwrapInfo struct and CollectGlobalUnwrapInfo function exist
  2. Generator integration: globalUnwrap field in Generator struct, populated in Generate() at line 44
  3. Usage verification: collectUnwrapContext uses global map at unwrap.go:109-110
  4. Test fixtures: same_pkg_service.proto and same_pkg_wrapper.proto exist (verified via ls)
  5. Test execution: TestCrossFileUnwrapResolution passes with 4/4 subtests

Evidence artifacts:

  • internal/httpgen/unwrap.go:59-85 - GlobalUnwrapInfo definition and collection
  • internal/httpgen/generator.go:17 - globalUnwrap field
  • internal/httpgen/generator.go:44 - CollectGlobalUnwrapInfo call in Generate
  • internal/httpgen/unwrap.go:103-115 - collectUnwrapContext using global map
  • Test output: "PASS: TestCrossFileUnwrapResolution (0.33s)"

Truth 5: Issue #91 Closed with Documentation#

Verified via:

  1. GitHub API: gh issue view 91 --json state returns "CLOSED"
  2. Comment content: Contains unwrap annotation syntax, proto example, test file references
  3. Comment quality: Documents usage (repeated Item items = 1 [(sebuf.http.unwrap) = true]), expected output (array at root), test coverage, and cross-generator support

Evidence: Full closing comment retrieved via gh issue view 91 --json comments

Truth 6: Issue #94 Closed with Documentation#

Verified via:

  1. GitHub API: gh issue view 94 --json state returns "CLOSED"
  2. Comment content: Documents proto3's json_name field option
  3. Comment quality: Includes proto example, explains rationale (sebuf annotation would create confusion), references proto3 spec

Evidence: Full closing comment retrieved via gh issue view 94 --json comments

Additional Verification#

Build verification:

go build ./cmd/protoc-gen-go-client/   # SUCCESS
go build ./cmd/protoc-gen-go-http/     # SUCCESS

Test verification:

go test ./internal/clientgen/ -run TestClientGenGoldenFiles  # PASS
go test ./internal/httpgen/ -run TestCrossFileUnwrapResolution  # PASS (4/4 subtests)

Issue status verification:

gh issue view 91 --json state  # CLOSED
gh issue view 94 --json state  # CLOSED
gh issue view 105 --json state # CLOSED

Overall Assessment#

Phase 1 goal ACHIEVED.

All 4 success criteria from ROADMAP.md are fully satisfied:

  1. ✓ Conditional net/url import implemented and working
  2. ✓ Cross-file unwrap resolution implemented and tested
  3. ✓ Issue #91 closed with comprehensive documentation
  4. ✓ Issue #94 confirmed closed with adequate documentation

All 4 requirements (FOUND-02, FOUND-03, FOUND-05, FOUND-06) are satisfied.

The codebase is clean before structural changes. No bugs remain from Phase 1 scope. All pending work (PR #98) is landed. All resolved issues are properly closed with documentation.

Ready to proceed to Phase 2: Foundation - Shared Annotations.

Verified: 2026-02-05T16:01:10Z

Verifier: Claude (gsd-verifier)