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

internal/normalizers/common/doc.go

@@ -0,0 +1,49 @@
+// Package common contains cross-provider helper code used by weatherfeeder normalizers.
+//
+// Purpose
+// -------
+// Normalizers convert provider-specific RAW payloads into canonical internal/model types.
+// Some small utilities are naturally reusable across multiple providers (unit conversions,
+// payload extraction, common parsing, shared fallbacks). Those belong here.
+//
+// This package is intentionally "boring":
+//   - pure helpers (deterministic, no I/O)
+//   - minimal abstractions (prefer straightforward functions)
+//   - easy to unit test
+//
+// What belongs here
+// -----------------
+// Put code in internal/normalizers/common when it is:
+//
+//   - potentially reusable by more than one provider
+//   - provider-agnostic (no NWS/OpenWeather/Open-Meteo specific assumptions)
+//   - stable, small, and readable
+//
+// Typical examples:
+//   - unit conversion helpers (°F <-> °C, m/s <-> km/h, hPa <-> Pa, etc.)
+//   - json.RawMessage payload extraction helpers (with good error messages)
+//   - shared parsing helpers (timestamps, simple numeric coercions)
+//   - generic fallbacks (e.g., mapping a human text description into a coarse canonical code),
+//     so long as the logic truly applies across providers
+//
+// What does NOT belong here
+// -------------------------
+// Do NOT put the following in this package:
+//
+//   - Normalizer implementations (types that satisfy feedkit/normalize.Normalizer)
+//   - provider-specific JSON structs or mapping logic (put those under
+//     internal/normalizers/<provider>/)
+//   - network or filesystem I/O (sources fetch; normalizers transform)
+//   - code that depends on event.Source naming, config fields, or driver-specific params
+//
+// Style and API guidelines
+// ------------------------
+//   - Prefer small, single-purpose functions.
+//   - Keep function names explicit (avoid clever generic “DoThing” helpers).
+//   - Return typed errors with context (include schema/field names where helpful).
+//   - Keep dependencies minimal: standard library + weatherfeeder packages only.
+//   - Add unit tests for any non-trivial logic (especially parsing and fallbacks).
+//
+// Keeping this clean matters: common is shared by all providers, so complexity here
+// multiplies across the project.
+package common