nws: refactored the NWS source files to relocate normalization logic to internal/normalizers.

internal/normalizers/nws/metar.go

@@ -0,0 +1,51 @@
+// FILE: ./internal/normalizers/nws/metar.go
+package nws
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// metarPhenomenon is a typed view of NWS presentWeather objects.
+type metarPhenomenon struct {
+	Intensity  *string `json:"intensity"` // "light", "heavy", or null
+	Modifier   *string `json:"modifier"`  // "freezing", "showers", etc., or null
+	Weather    string  `json:"weather"`   // e.g. "rain", "snow", "fog_mist", ...
+	RawString  string  `json:"rawString"`
+	InVicinity *bool   `json:"inVicinity"`
+}
+
+func decodeMetarPhenomena(raw []map[string]any) []metarPhenomenon {
+	if len(raw) == 0 {
+		return nil
+	}
+
+	out := make([]metarPhenomenon, 0, len(raw))
+	for _, m := range raw {
+		b, err := json.Marshal(m)
+		if err != nil {
+			continue
+		}
+
+		var p metarPhenomenon
+		if err := json.Unmarshal(b, &p); err != nil {
+			continue
+		}
+
+		p.Weather = strings.ToLower(strings.TrimSpace(p.Weather))
+		p.RawString = strings.TrimSpace(p.RawString)
+		out = append(out, p)
+	}
+
+	return out
+}
+
+func containsWeather(phenomena []metarPhenomenon, weather string) bool {
+	weather = strings.ToLower(strings.TrimSpace(weather))
+	for _, p := range phenomena {
+		if p.Weather == weather {
+			return true
+		}
+	}
+	return false
+}

internal/normalizers/nws/observation.go

@@ -0,0 +1,145 @@
+// FILE: ./internal/normalizers/nws/observation.go
+package nws
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/model"
+	normcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/common"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
+)
+
+// ObservationNormalizer converts:
+//
+//	standards.SchemaRawNWSObservationV1 -> standards.SchemaWeatherObservationV1
+//
+// It interprets NWS GeoJSON station observations and maps them into the
+// canonical model.WeatherObservation representation.
+//
+// Precedence for determining ConditionCode (WMO):
+//  1. presentWeather (METAR phenomena objects) — strongest signal
+//  2. textDescription keyword fallback — reusable across providers
+//  3. cloudLayers sky-only fallback — NWS/METAR-specific
+type ObservationNormalizer struct{}
+
+func (ObservationNormalizer) Match(e event.Event) bool {
+	return strings.TrimSpace(e.Schema) == standards.SchemaRawNWSObservationV1
+}
+
+func (ObservationNormalizer) Normalize(ctx context.Context, in event.Event) (*event.Event, error) {
+	_ = ctx // normalization is pure/CPU; keep ctx for future expensive steps
+
+	rawBytes, err := normcommon.PayloadBytes(in)
+	if err != nil {
+		return nil, fmt.Errorf("nws observation normalize: %w", err)
+	}
+
+	var parsed nwsObservationResponse
+	if err := json.Unmarshal(rawBytes, &parsed); err != nil {
+		return nil, fmt.Errorf("nws observation normalize: decode raw payload: %w", err)
+	}
+
+	obs, effectiveAt, err := buildObservation(parsed)
+	if err != nil {
+		return nil, err
+	}
+
+	out := in
+	out.Schema = standards.SchemaWeatherObservationV1
+	out.Payload = obs
+
+	// EffectiveAt is optional; for observations it is naturally the observation timestamp.
+	if !effectiveAt.IsZero() {
+		t := effectiveAt.UTC()
+		out.EffectiveAt = &t
+	}
+
+	if err := out.Validate(); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}
+
+// buildObservation contains the domain mapping logic (provider -> canonical model).
+func buildObservation(parsed nwsObservationResponse) (model.WeatherObservation, time.Time, error) {
+	// Timestamp (RFC3339)
+	var ts time.Time
+	if s := strings.TrimSpace(parsed.Properties.Timestamp); s != "" {
+		t, err := time.Parse(time.RFC3339, s)
+		if err != nil {
+			return model.WeatherObservation{}, time.Time{}, fmt.Errorf("nws observation normalize: invalid timestamp %q: %w", s, err)
+		}
+		ts = t
+	}
+
+	cloudLayers := make([]model.CloudLayer, 0, len(parsed.Properties.CloudLayers))
+	for _, cl := range parsed.Properties.CloudLayers {
+		cloudLayers = append(cloudLayers, model.CloudLayer{
+			BaseMeters: cl.Base.Value,
+			Amount:     cl.Amount,
+		})
+	}
+
+	// Preserve raw presentWeather objects (for troubleshooting / drift analysis).
+	present := make([]model.PresentWeather, 0, len(parsed.Properties.PresentWeather))
+	for _, pw := range parsed.Properties.PresentWeather {
+		present = append(present, model.PresentWeather{Raw: pw})
+	}
+
+	// Decode presentWeather into typed METAR phenomena for mapping.
+	phenomena := decodeMetarPhenomena(parsed.Properties.PresentWeather)
+
+	providerDesc := strings.TrimSpace(parsed.Properties.TextDescription)
+
+	// Determine canonical WMO condition code.
+	wmo := mapNWSToWMO(providerDesc, cloudLayers, phenomena)
+
+	// Canonical condition text comes from our WMO table.
+	// NWS observation responses typically do not include a day/night flag -> nil.
+	canonicalText := standards.WMOText(wmo, nil)
+
+	obs := model.WeatherObservation{
+		StationID:   parsed.Properties.StationID,
+		StationName: parsed.Properties.StationName,
+		Timestamp:   ts,
+
+		ConditionCode: wmo,
+		ConditionText: canonicalText,
+		IsDay:         nil,
+
+		ProviderRawDescription: providerDesc,
+
+		// Transitional / human-facing:
+		// keep output consistent by populating TextDescription from canonical text.
+		TextDescription: canonicalText,
+		IconURL:         parsed.Properties.Icon,
+
+		TemperatureC: parsed.Properties.Temperature.Value,
+		DewpointC:    parsed.Properties.Dewpoint.Value,
+
+		WindDirectionDegrees: parsed.Properties.WindDirection.Value,
+		WindSpeedKmh:         parsed.Properties.WindSpeed.Value,
+		WindGustKmh:          parsed.Properties.WindGust.Value,
+
+		BarometricPressurePa: parsed.Properties.BarometricPressure.Value,
+		SeaLevelPressurePa:   parsed.Properties.SeaLevelPressure.Value,
+		VisibilityMeters:     parsed.Properties.Visibility.Value,
+
+		RelativeHumidityPercent: parsed.Properties.RelativeHumidity.Value,
+		WindChillC:              parsed.Properties.WindChill.Value,
+		HeatIndexC:              parsed.Properties.HeatIndex.Value,
+
+		ElevationMeters: parsed.Properties.Elevation.Value,
+		RawMessage:      parsed.Properties.RawMessage,
+
+		PresentWeather: present,
+		CloudLayers:    cloudLayers,
+	}
+
+	return obs, ts, nil
+}

internal/normalizers/nws/register.go

@@ -1,3 +1,4 @@
+// FILE: ./internal/normalizers/nws/register.go
 package nws
 
 import (
@@ -5,17 +6,11 @@ import (
 )
 
 // Register registers NWS normalizers into the provided registry.
-//
-// This is intentionally empty as a stub. As normalizers are implemented,
-// register them here, e.g.:
-//
-//	reg.Register(ObservationNormalizer{})
-//	reg.Register(ForecastNormalizer{})
-//	reg.Register(AlertsNormalizer{})
 func Register(reg *fknormalize.Registry) {
 	if reg == nil {
 		return
 	}
 
-	// TODO: register NWS normalizers here.
+	// Observations
+	reg.Register(ObservationNormalizer{})
 }

internal/normalizers/nws/types.go

@@ -0,0 +1,89 @@
+// FILE: ./internal/normalizers/nws/types.go
+package nws
+
+// nwsObservationResponse is a minimal-but-sufficient representation of the NWS
+// station observation GeoJSON payload needed for mapping into model.WeatherObservation.
+type nwsObservationResponse struct {
+	ID         string `json:"id"`
+	Properties struct {
+		StationID       string `json:"stationId"`
+		StationName     string `json:"stationName"`
+		Timestamp       string `json:"timestamp"`
+		TextDescription string `json:"textDescription"`
+		Icon            string `json:"icon"`
+
+		RawMessage string `json:"rawMessage"`
+
+		Elevation struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"elevation"`
+
+		Temperature struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"temperature"`
+
+		Dewpoint struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"dewpoint"`
+
+		WindDirection struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"windDirection"`
+
+		WindSpeed struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"windSpeed"`
+
+		WindGust struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"windGust"`
+
+		BarometricPressure struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"barometricPressure"`
+
+		SeaLevelPressure struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"seaLevelPressure"`
+
+		Visibility struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"visibility"`
+
+		RelativeHumidity struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"relativeHumidity"`
+
+		WindChill struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"windChill"`
+
+		HeatIndex struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"heatIndex"`
+
+		// NWS returns "presentWeather" as decoded METAR phenomena objects.
+		// We decode these as generic maps, then optionally interpret them in metar.go.
+		PresentWeather []map[string]any `json:"presentWeather"`
+
+		CloudLayers []struct {
+			Base struct {
+				UnitCode string   `json:"unitCode"`
+				Value    *float64 `json:"value"`
+			} `json:"base"`
+			Amount string `json:"amount"`
+		} `json:"cloudLayers"`
+	} `json:"properties"`
+}

internal/normalizers/nws/wmo_map.go

@@ -0,0 +1,223 @@
+// FILE: ./internal/normalizers/nws/wmo_map.go
+package nws
+
+import (
+	"strings"
+
+	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/model"
+	normcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/common"
+)
+
+// mapNWSToWMO maps NWS signals into a canonical WMO code.
+//
+// Precedence:
+//  1. METAR phenomena (presentWeather) — most reliable for precip/hazards
+//  2. textDescription keywords — weaker, but reusable across providers
+//  3. cloud layers fallback — only for sky-only conditions
+func mapNWSToWMO(providerDesc string, cloudLayers []model.CloudLayer, phenomena []metarPhenomenon) model.WMOCode {
+	// 1) Prefer METAR phenomena if present.
+	if code := wmoFromPhenomena(phenomena); code != model.WMOUnknown {
+		return code
+	}
+
+	// 2) Reusable fallback: infer WMO from human text description.
+	if code := normcommon.WMOFromTextDescription(providerDesc); code != model.WMOUnknown {
+		return code
+	}
+
+	// 3) NWS/METAR-specific sky fallback.
+	if code := wmoFromCloudLayers(cloudLayers); code != model.WMOUnknown {
+		return code
+	}
+
+	return model.WMOUnknown
+}
+
+func wmoFromPhenomena(phenomena []metarPhenomenon) model.WMOCode {
+	if len(phenomena) == 0 {
+		return model.WMOUnknown
+	}
+
+	intensityOf := func(p metarPhenomenon) string {
+		if p.Intensity == nil {
+			return ""
+		}
+		return strings.ToLower(strings.TrimSpace(*p.Intensity))
+	}
+	modifierOf := func(p metarPhenomenon) string {
+		if p.Modifier == nil {
+			return ""
+		}
+		return strings.ToLower(strings.TrimSpace(*p.Modifier))
+	}
+
+	// Pass 1: thunder + hail overrides everything (hazard).
+	hasThunder := false
+	hailIntensity := ""
+	for _, p := range phenomena {
+		switch p.Weather {
+		case "thunderstorms":
+			hasThunder = true
+		case "hail":
+			if hailIntensity == "" {
+				hailIntensity = intensityOf(p)
+			}
+		}
+	}
+	if hasThunder {
+		if hailIntensity != "" || containsWeather(phenomena, "hail") {
+			if hailIntensity == "heavy" {
+				return 99
+			}
+			return 96
+		}
+		return 95
+	}
+
+	// Pass 2: freezing hazards.
+	for _, p := range phenomena {
+		if modifierOf(p) != "freezing" {
+			continue
+		}
+		switch p.Weather {
+		case "rain":
+			if intensityOf(p) == "light" {
+				return 66
+			}
+			return 67
+		case "drizzle":
+			if intensityOf(p) == "light" {
+				return 56
+			}
+			return 57
+		case "fog", "fog_mist":
+			return 48
+		}
+	}
+
+	// Pass 3: fog / obscuration.
+	for _, p := range phenomena {
+		switch p.Weather {
+		case "fog", "fog_mist":
+			return 45
+		case "haze", "smoke", "dust", "sand", "spray", "volcanic_ash":
+			return 45
+		}
+	}
+
+	// Pass 4: precip families.
+	for _, p := range phenomena {
+		inten := intensityOf(p)
+		mod := modifierOf(p)
+
+		if mod == "showers" {
+			switch p.Weather {
+			case "rain":
+				if inten == "light" {
+					return 80
+				}
+				if inten == "heavy" {
+					return 82
+				}
+				return 81
+			case "snow":
+				if inten == "light" {
+					return 85
+				}
+				return 86
+			}
+		}
+
+		switch p.Weather {
+		case "drizzle":
+			if inten == "heavy" {
+				return 55
+			}
+			if inten == "light" {
+				return 51
+			}
+			return 53
+
+		case "rain":
+			if inten == "heavy" {
+				return 65
+			}
+			if inten == "light" {
+				return 61
+			}
+			return 63
+
+		case "snow":
+			if inten == "heavy" {
+				return 75
+			}
+			if inten == "light" {
+				return 71
+			}
+			return 73
+
+		case "snow_grains":
+			return 77
+
+		case "ice_pellets", "snow_pellets":
+			return 73
+		}
+	}
+
+	return model.WMOUnknown
+}
+
+func wmoFromCloudLayers(cloudLayers []model.CloudLayer) model.WMOCode {
+	// NWS cloud layer amount values commonly include:
+	// OVC, BKN, SCT, FEW, SKC, CLR, VV (vertical visibility / obscured sky)
+	//
+	// Conservative mapping within our current WMO subset:
+	// - OVC / BKN / VV => Cloudy (3)
+	// - SCT => Partly Cloudy (2)
+	// - FEW => Mainly Sunny/Clear (1)
+	// - CLR / SKC => Sunny/Clear (0)
+	//
+	// Multiple layers: bias toward “most cloudy”.
+	mostCloudy := ""
+
+	for _, cl := range cloudLayers {
+		a := strings.ToUpper(strings.TrimSpace(cl.Amount))
+		if a == "" {
+			continue
+		}
+
+		switch a {
+		case "OVC":
+			return 3
+		case "BKN", "VV":
+			if mostCloudy != "OVC" {
+				mostCloudy = a
+			}
+		case "SCT":
+			if mostCloudy == "" {
+				mostCloudy = "SCT"
+			}
+		case "FEW":
+			if mostCloudy == "" {
+				mostCloudy = "FEW"
+			}
+		case "CLR", "SKC":
+			if mostCloudy == "" {
+				mostCloudy = "CLR"
+			}
+		}
+	}
+
+	switch mostCloudy {
+	case "BKN", "VV":
+		return 3
+	case "SCT":
+		return 2
+	case "FEW":
+		return 1
+	case "CLR":
+		return 0
+	default:
+		return model.WMOUnknown
+	}
+}