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

internal/normalizers/doc.go

@@ -19,7 +19,8 @@
 // Example:
 //
 //	internal/normalizers/nws/observation.go
-//	internal/normalizers/nws/common.go
+//	internal/normalizers/nws/types.go
+//	internal/normalizers/nws/wmo_map.go
 //	internal/normalizers/openweather/observation.go
 //	internal/normalizers/openmeteo/observation.go
 //	internal/normalizers/common/units.go
@@ -27,14 +28,30 @@
 // Rules:
 //
 //  1. One normalizer per file.
-//     Each file contains exactly one Normalizer implementation (one type).
+//     Each file contains exactly one Normalizer implementation (one type that
+//     satisfies feedkit/normalize.Normalizer).
+//     Helper files are encouraged (types.go, common.go, mapping.go, etc.) as long
+//     as they do not define additional Normalizer types.
 //
-//  2. Provider-level shared helpers live in:
-//     internal/normalizers/<provider>/common.go
+//  2. Provider-level shared helpers live under the provider directory:
+//     internal/normalizers/<provider>/
+//
+//     You may use multiple helper files (recommended) when it improves clarity:
+//     - types.go        (provider JSON structs)
+//     - common.go       (provider-shared helpers)
+//     - mapping.go      (provider mapping logic)
+//     Use common.go only when you truly have “shared across multiple normalizers
+//     within this provider” helpers.
 //
 //  3. Cross-provider helpers live in:
 //     internal/normalizers/common/
 //
+//     Prefer extracting small, pure helpers here when they are reused by ≥2 providers.
+//     Keep these helpers:
+//     - deterministic (no I/O)
+//     - side-effect free
+//     - easy to read (avoid clever abstractions)
+//
 //  4. Matching is standardized on Event.Schema.
 //     (Do not match on event.Source or event.Kind in weatherfeeder normalizers.)
 //
@@ -82,10 +99,13 @@
 // Every normalizer type must have a doc comment that states:
 //
 //   - what it converts (e.g., “OpenWeather current -> WeatherObservation”)
-//   - which raw schema it matches (constant name + value)
-//   - which canonical schema it produces (constant name + value)
+//   - which raw schema it matches (constant identifier from internal/standards)
+//   - which canonical schema it produces (constant identifier from internal/standards)
 //   - any special caveats (units, day/night inference, missing fields, etc.)
 //
+// Including literal schema string values is optional,
+// but the constant identifiers are required.
+//
 // Event field handling (strong defaults)
 // --------------------------------------
 // Normalizers should treat the incoming event envelope as stable identity and
@@ -126,6 +146,22 @@
 //
 // which calls each provider’s Register() in a stable order.
 //
+// Registry ordering
+// -----------------------------
+// feedkit normalization uses a match-driven registry (“first match wins”).
+// Therefore order matters:
+//
+//   - Register more specific normalizers before more general ones.
+//   - Avoid “catch-all” Match() implementations.
+//   - Keep Match() cheap and deterministic (Schema equality checks are ideal).
+//
+// Reuse guidance (strong recommendation)
+// --------------------------------------
+// Before adding provider-specific logic, check internal/normalizers/common for an
+// existing helper (payload extraction, unit conversions, text fallbacks, etc.).
+// If you discover logic that could potentially apply to another provider, prefer extracting
+// it into internal/normalizers/common as appropriate.
+//
 // Testing guidance (recommended)
 // ------------------------------
 // Add a unit test per normalizer: