Merge pull request #156 from 0xjuanma/fix/wc-ui

fix[ui/worldcup]: resolve ambiguous flags and backfill 2026 qualifier coverage

Author: 0xjuanma

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 ### Fixed
+- **World Cup Flags** - Fixed ambiguous FotMob short codes (e.g. South Africa/South Korea both `SOU`) and missing 2026 qualifier flags causing teams to render with the wrong code or no flag.
 
 ## [0.26.0] - 2026-06-10
 

internal/ui/worldcup/flag_coverage_test.go

@@ -0,0 +1,88 @@
+package worldcup
+
+import (
+	"sort"
+	"testing"
+)
+
+// alternateFlagCodes lists flagEmojis keys that intentionally have no
+// matching wcNameToCode entry: they exist purely so FotMob payloads that
+// surface alternate codes (e.g. "IRI" for Iran, "HOL" for Netherlands)
+// still render with a flag. The canonical name → code mapping lives in
+// wcNameToCode under the FIFA-standard code.
+var alternateFlagCodes = map[string]bool{
+	"HOL": true, // Netherlands alternate
+	"IRI": true, // Iran alternate
+	"GBR": true, // Great Britain (no corresponding national team in WC)
+}
+
+// unflaggedNameCodes lists wcNameToCode values that intentionally have no
+// flagEmojis entry because the country has no representable Unicode flag
+// emoji. Northern Ireland is the canonical example: there is no Unicode
+// regional indicator or subdivision tag for it (only ENG, SCT, WLS exist).
+// Teams in this list still get their FIFA code rendered, just without an
+// emoji prefix.
+var unflaggedNameCodes = map[string]bool{
+	"NIR": true, // Northern Ireland — no Unicode flag exists
+}
+
+// TestFlagCoverage_NameOverridesHaveFlags asserts every code that
+// wcNameToCode maps to is also a key in flagEmojis. Without this, adding
+// a new country to wcNameToCode without its flag would render as
+// "   XYZ" silently, with no compile-time or runtime warning.
+func TestFlagCoverage_NameOverridesHaveFlags(t *testing.T) {
+	var missing []string
+	for name, code := range wcNameToCode {
+		if unflaggedNameCodes[code] {
+			continue
+		}
+		if _, ok := flagEmojis[code]; !ok {
+			missing = append(missing, name+" → "+code)
+		}
+	}
+	if len(missing) > 0 {
+		sort.Strings(missing)
+		t.Errorf("wcNameToCode entries missing a matching flagEmojis flag (%d):\n  %s\n"+
+			"add the flag to flagEmojis, or add the code to unflaggedNameCodes if no Unicode flag exists",
+			len(missing), joinNewline(missing))
+	}
+}
+
+// TestFlagCoverage_NoOrphanedFlagEntries asserts every flagEmojis key
+// (except the documented alternate codes) is reachable from at least one
+// wcNameToCode value. This prevents flag entries from drifting out of
+// sync — e.g. a flag added without the corresponding name override would
+// never render in any World Cup view.
+func TestFlagCoverage_NoOrphanedFlagEntries(t *testing.T) {
+	reachable := make(map[string]bool, len(wcNameToCode))
+	for _, code := range wcNameToCode {
+		reachable[code] = true
+	}
+
+	var orphans []string
+	for code := range flagEmojis {
+		if alternateFlagCodes[code] {
+			continue
+		}
+		if !reachable[code] {
+			orphans = append(orphans, code)
+		}
+	}
+	if len(orphans) > 0 {
+		sort.Strings(orphans)
+		t.Errorf("flagEmojis entries with no wcNameToCode mapping (%d):\n  %s\n"+
+			"add the country name to wcNameToCode, or add the code to alternateFlagCodes if intentional",
+			len(orphans), joinNewline(orphans))
+	}
+}
+
+func joinNewline(items []string) string {
+	out := ""
+	for i, s := range items {
+		if i > 0 {
+			out += "\n  "
+		}
+		out += s
+	}
+	return out
+}

internal/ui/worldcup/flags_emoji.go

@@ -13,7 +13,9 @@ func FlagEmoji(shortName string) string {
 }
 
 // flagEmojis maps FIFA 3-letter codes to Unicode regional indicator flag emojis.
-// Covers all 32 WC 2022 teams plus the additional 16 teams confirmed for 2026.
+// Covers all 32 WC 2022 teams plus the additional teams confirmed for 2026 and
+// the broader set of confederation qualifiers that surface in FotMob payloads
+// during the WC 2026 qualifying cycle.
 var flagEmojis = map[string]string{
 	// WC 2022 participants
 	"QAT": "🇶🇦",
@@ -114,6 +116,53 @@ var flagEmojis = map[string]string{
 	"BHR": "🇧🇭",
 	"KUW": "🇰🇼",
 	"NZL": "🇳🇿",
+	// WC 2026 confirmed qualifiers / strong qualifying candidates not in WC 2022.
+	"UZB": "🇺🇿", // Uzbekistan — first-ever WC qualifier (AFC)
+	"CPV": "🇨🇻", // Cape Verde — first-ever WC qualifier (CAF)
+	"CUW": "🇨🇼", // Curaçao (CONCACAF)
+	"HAI": "🇭🇹", // Haiti
+	"SUR": "🇸🇷", // Suriname
+	"NCL": "🇳🇨", // New Caledonia (OFC playoff candidate)
+	"DOM": "🇩🇴", // Dominican Republic
+	"GUA": "🇬🇹", // Guatemala
+	"SLV": "🇸🇻", // El Salvador
+	"PRK": "🇰🇵", // North Korea / DPR Korea
+	// CAF coverage useful in 2026 qualifying rounds and intercontinental playoffs.
+	"BFA": "🇧🇫", // Burkina Faso
+	"ETH": "🇪🇹", // Ethiopia
+	"GAB": "🇬🇦", // Gabon
+	"LBY": "🇱🇾", // Libya
+	"NIG": "🇳🇪", // Niger
+	"MAD": "🇲🇬", // Madagascar
+	"MOZ": "🇲🇿", // Mozambique
+	"ANG": "🇦🇴", // Angola
+	"ZAM": "🇿🇲", // Zambia
+	"SLE": "🇸🇱", // Sierra Leone
+	"EQG": "🇬🇶", // Equatorial Guinea
+	"BEN": "🇧🇯", // Benin
+	"TOG": "🇹🇬", // Togo
+	"COM": "🇰🇲", // Comoros
+	"SDN": "🇸🇩", // Sudan
+	"MTN": "🇲🇷", // Mauritania
+	"NAM": "🇳🇦", // Namibia
+	"BOT": "🇧🇼", // Botswana
+	"RWA": "🇷🇼", // Rwanda
+	// AFC / UEFA tail coverage for qualifying rounds and FotMob's broader payload.
+	"KAZ": "🇰🇿", // Kazakhstan
+	"TJK": "🇹🇯", // Tajikistan
+	"KGZ": "🇰🇬", // Kyrgyzstan
+	"TKM": "🇹🇲", // Turkmenistan
+	"LUX": "🇱🇺", // Luxembourg
+	"CYP": "🇨🇾", // Cyprus
+	"MLT": "🇲🇹", // Malta
+	"LVA": "🇱🇻", // Latvia
+	"LTU": "🇱🇹", // Lithuania
+	"EST": "🇪🇪", // Estonia
+	"MDA": "🇲🇩", // Moldova
+	"BLR": "🇧🇾", // Belarus
+	"FRO": "🇫🇴", // Faroe Islands
+	"LIE": "🇱🇮", // Liechtenstein
+	"RUS": "🇷🇺", // Russia
 	// Common alternate codes
 	"HOL": "🇳🇱", // Netherlands alternate
 	"GBR": "🇬🇧",

internal/ui/worldcup/team_label.go

@@ -10,12 +10,17 @@ import (
 // "<flag-emoji> <CODE>", where <CODE> is the FIFA 3-letter abbreviation.
 //
 // The code resolution chain is:
-//  1. team.ShortName, if non-empty (already a 3-letter code from FotMob).
+//  1. team.ShortName, if non-empty AND it resolves to a registered flag.
+//     This guards against FotMob shipping a non-FIFA shortName (e.g. "SOU"
+//     for both "South Africa" and "South Korea") that would otherwise mask
+//     the correct FIFA code.
 //  2. A WC-local Name → code override map for known mismatches where FotMob
-//     ships the full English name without a short code (e.g. "Netherlands" → "NED").
-//  3. A deterministic fallback: uppercase the first 3 letters of the name with
-//     spaces stripped (e.g. "Cape Verde" → "CAP"). This is never ideal but
-//     keeps every cell aligned even when we receive an unknown country.
+//     ships the full English name without a populated short code
+//     (e.g. "Netherlands" → "NED") or ships an ambiguous short code.
+//  3. team.ShortName as-is (no flag) when the override map has no match.
+//  4. A deterministic fallback: uppercase the first 3 letters of the name
+//     with spaces stripped (e.g. "Cape Verde" → "CAP"). This is never ideal
+//     but keeps every cell aligned even when we receive an unknown country.
 //
 // When no flag emoji is registered for the resolved code, the emoji slot is
 // padded with two spaces so that columns stay aligned across rows.
@@ -42,13 +47,22 @@ func MatchupTeamLabel(short, full string, tbd bool) string {
 // teamCode resolves a team to its canonical 3-letter code using the chain
 // described on TeamLabel. The returned code is always truncated to at most
 // three characters so every WC view renders teams in the same column width.
+//
+// ShortName is preferred only when it resolves to a registered flag emoji.
+// This guards against FotMob occasionally shipping a non-FIFA shortName
+// (e.g. "SOU" for both "South Africa" and "South Korea") that would
+// otherwise mask the correct FIFA code available in wcNameToCode.
 func teamCode(short, full string) string {
-	if c := strings.ToUpper(strings.TrimSpace(short)); c != "" {
-		return capCode(c)
+	capped := capCode(strings.ToUpper(strings.TrimSpace(short)))
+	if capped != "" && FlagEmoji(capped) != "" {
+		return capped
 	}
 	if c, ok := wcNameToCode[strings.ToLower(strings.TrimSpace(full))]; ok {
 		return capCode(c)
 	}
+	if capped != "" {
+		return capped
+	}
 	stripped := strings.ToUpper(strings.ReplaceAll(full, " ", ""))
 	return capCode(stripped)
 }
@@ -196,4 +210,55 @@ var wcNameToCode = map[string]string{
 	"france":            "FRA",
 	"italy":             "ITA",
 	"tunisia":           "TUN",
+	// WC 2026 confirmed qualifiers / strong qualifying candidates not in WC 2022.
+	"uzbekistan":              "UZB",
+	"cape verde":              "CPV",
+	"cabo verde":              "CPV",
+	"curacao":                 "CUW",
+	"curaçao":                 "CUW",
+	"haiti":                   "HAI",
+	"suriname":                "SUR",
+	"new caledonia":           "NCL",
+	"dominican republic":      "DOM",
+	"guatemala":               "GUA",
+	"el salvador":             "SLV",
+	"dpr korea":               "PRK",
+	"korea dpr":               "PRK",
+	// CAF coverage useful in 2026 qualifying rounds and intercontinental playoffs.
+	"burkina faso":            "BFA",
+	"ethiopia":                "ETH",
+	"gabon":                   "GAB",
+	"libya":                   "LBY",
+	"niger":                   "NIG",
+	"madagascar":              "MAD",
+	"mozambique":              "MOZ",
+	"angola":                  "ANG",
+	"zambia":                  "ZAM",
+	"sierra leone":            "SLE",
+	"equatorial guinea":       "EQG",
+	"benin":                   "BEN",
+	"togo":                    "TOG",
+	"comoros":                 "COM",
+	"sudan":                   "SDN",
+	"mauritania":              "MTN",
+	"namibia":                 "NAM",
+	"botswana":                "BOT",
+	"rwanda":                  "RWA",
+	// AFC / UEFA tail coverage for qualifying rounds.
+	"kazakhstan":              "KAZ",
+	"tajikistan":              "TJK",
+	"kyrgyzstan":              "KGZ",
+	"turkmenistan":            "TKM",
+	"luxembourg":              "LUX",
+	"cyprus":                  "CYP",
+	"malta":                   "MLT",
+	"latvia":                  "LVA",
+	"lithuania":               "LTU",
+	"estonia":                 "EST",
+	"moldova":                 "MDA",
+	"belarus":                 "BLR",
+	"faroe islands":           "FRO",
+	"liechtenstein":           "LIE",
+	"russia":                  "RUS",
+	"israel":                  "ISR",
 }

internal/ui/worldcup/team_label_test.go

@@ -11,8 +11,10 @@ func TestTeamLabel(t *testing.T) {
 	argFlag := FlagEmoji("ARG")
 	nedFlag := FlagEmoji("NED")
 	ausFlag := FlagEmoji("AUS")
-	if argFlag == "" || nedFlag == "" || ausFlag == "" {
-		t.Fatal("expected ARG/NED/AUS to have flag emojis registered")
+	korFlag := FlagEmoji("KOR")
+	rsaFlag := FlagEmoji("RSA")
+	if argFlag == "" || nedFlag == "" || ausFlag == "" || korFlag == "" || rsaFlag == "" {
+		t.Fatal("expected ARG/NED/AUS/KOR/RSA to have flag emojis registered")
 	}
 
 	tests := []struct {
@@ -60,6 +62,16 @@ func TestTeamLabel(t *testing.T) {
 			team: api.Team{Name: "Australia", ShortName: "AUST"},
 			want: ausFlag + " AUS", // "AUST" → "AUS" → flag resolves
 		},
+		{
+			name: "ambiguous shortname without flag falls back to name override (KOR)",
+			team: api.Team{Name: "South Korea", ShortName: "SOU"},
+			want: korFlag + " KOR",
+		},
+		{
+			name: "ambiguous shortname without flag falls back to name override (RSA)",
+			team: api.Team{Name: "South Africa", ShortName: "SOU"},
+			want: rsaFlag + " RSA",
+		},
 	}
 
 	for _, tt := range tests {
@@ -116,3 +128,44 @@ func TestTeamLabel_AlwaysContainsCode(t *testing.T) {
 		}
 	}
 }
+
+// TestTeamLabel_WC2026Qualifiers asserts a representative sample of teams
+// added for the WC 2026 qualifying cycle resolves to "<flag> <CODE>". This
+// guards against either the flagEmojis or wcNameToCode entries being
+// silently removed.
+func TestTeamLabel_WC2026Qualifiers(t *testing.T) {
+	cases := []struct {
+		name string
+		code string
+	}{
+		{"Uzbekistan", "UZB"},
+		{"Cape Verde", "CPV"},
+		{"Curaçao", "CUW"},
+		{"Curacao", "CUW"},
+		{"Haiti", "HAI"},
+		{"Suriname", "SUR"},
+		{"New Caledonia", "NCL"},
+		{"Dominican Republic", "DOM"},
+		{"Guatemala", "GUA"},
+		{"El Salvador", "SLV"},
+		{"North Korea", "PRK"},
+		{"Burkina Faso", "BFA"},
+		{"Madagascar", "MAD"},
+		{"Kazakhstan", "KAZ"},
+		{"Luxembourg", "LUX"},
+		{"Israel", "ISR"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			flag := FlagEmoji(tc.code)
+			if flag == "" {
+				t.Fatalf("missing flagEmojis entry for %s (%s)", tc.name, tc.code)
+			}
+			got := TeamLabel(api.Team{Name: tc.name})
+			want := flag + " " + tc.code
+			if got != want {
+				t.Errorf("TeamLabel({Name:%q}) = %q, want %q", tc.name, got, want)
+			}
+		})
+	}
+}