Sync Upstream

Sync with upstream libphonenumber

This package is a Go port of google/libphonenumber, tracking its Java reference implementation. A sync is two independent operations — do them in order, but understand they're different in kind:

1. Metadata regen — mechanical. Rebuild the embedded data/ blobs from a new upstream release. Fully automated by cmd/buildmetadata.
2. Code reconciliation — judgment. Port new Java logic changes into the Go files. Can't be automated; this is the real reason SYNC.md exists.

State lives in SYNC.md: the code baseline (Code reconciled against vX.Y.Z) and the deliberate divergences (what we intentionally do not port). Read it first. The embedded-metadata version is tracked separately in the generated metadata/version.go (metadata.Version) — never hand-edit that.

Run everything from the repo root (/Users/rowan/nyaruka/phonenumbers).

Argument

The skill takes one optional argument selecting which operation(s) to run:

• /sync-upstream data — Phase 1 only (metadata regen). An automated metadata update can invoke this mode directly.
• /sync-upstream code — Phase 2 only (code reconciliation, against the metadata version already built — see the note at the top of Phase 2).
• /sync-upstream — both phases, in order.

Whichever mode runs, finish with Finalize below: commit the changes and stop. This skill never releases — no tag, no push, no CHANGELOG.md. The user cuts releases separately with /release.

Phase 1 — Metadata regen (mechanical)

go run ./cmd/buildmetadata            # latest upstream release
# go run ./cmd/buildmetadata v9.0.32  # or pin a specific tag

This resolves the target tag, wipes and re-clones upstream into _build/ (a shallow --depth=1 checkout at the target tag — gitignored), rebuilds every embedded blob (data/, metadata/data/, carrier/data/, geocoding/data/, timezone/data/), and rewrites the generated metadata/version.go with the tag it built from.

Then:

go test ./...

Review the diff. The only files that may change are the embedded blobs (data/, metadata/data/, carrier/data/, geocoding/data/, timezone/data/) and the generated metadata/version.go:

• No changes at all → the metadata is already up to date; nothing to commit for Phase 1. In data mode report that and stop; in a full sync continue to Phase 2 (the code baseline may still lag the metadata version).
• Changes outside that set → something is wrong; stop and report the unexpected changes without committing.

In data mode, that's the whole job — skip to Finalize. Phase 1 has already bumped metadata/version.go, and the Code reconciled against baseline in SYNC.md stays where it is (the two versions are tracked separately for exactly this case).

The target tag you built becomes the new code baseline once Phase 2 reconciles against it.

Phase 2 — Code reconciliation (judgment)

Goal: apply any upstream Java logic changes between the old baseline (SYNC.md) and the target to each Go port. The target is the tag Phase 1 built — in code-only mode, the version already in metadata/version.go (metadata.Version), i.e. reconcile the code up to where the embedded metadata already is.

Get both tags side by side for diffing

Phase 1 leaves _build/ as a shallow clone at the target tag. In code-only mode _build/ may be missing (it's gitignored) — recreate it at the target first:

TARGET=v9.0.32    # metadata.Version, from metadata/version.go
git clone --depth=1 --branch "$TARGET" https://github.com/google/libphonenumber _build

Then fetch the baseline tag into it so you can diff tree-to-tree (no merge base needed — git diff A B compares trees):

BASE=v9.0.31      # from SYNC.md "Code reconciled against"
git -C _build fetch --depth=1 origin tag "$BASE"

Diff each ported source, baseline→target

The per-file headers are the source of truth for the Go→Java mapping — every reconcilable file carries a // Port of <upstream/path>. header. Enumerate them:

grep -rn "Port of" --include='*.go' . | grep -v _test.go | grep -v _build/

For each upstream path P, diff it across the window and reconcile anything non-trivial:

git -C _build diff "$BASE" "$TARGET" -- "$P"

The mapping (kept current; if files move, the headers win and this table is refreshed):

internal/serialize and internal/stringbuilder are Go-specific scaffolding (gzip/binary decode; a java.lang.StringBuilder stand-in) with no upstream logic to reconcile — skip them.

The corresponding upstream tests move in lockstep. The Go tests mirror the Java test classes (e.g. PhoneNumberUtilTest → phonenumberutil_test.go and friends); diff those too and port new cases:

git -C _build diff "$BASE" "$TARGET" -- "$(echo "$P" | sed 's#/src/#/test/#')"