up

docs/dev/normalized-rule-recipes.md

@@ -0,0 +1,94 @@
+# Normalized Version Rule Recipes
+
+_Status: 2025-10-29_
+
+This guide captures the minimum wiring required for connectors and Merge coordination tasks to finish the normalized-version rollout that unblocks FEEDMERGE-COORD-02-9xx.
+
+## 1. Quick-start checklist
+
+1. Ensure your mapper already emits `AffectedPackage.VersionRanges` (SemVer, NEVRA, EVR).  If you only have vendor/product strings, capture the raw range text before trimming so it can feed the helper.
+2. Call `SemVerRangeRuleBuilder.BuildNormalizedRules(rawRange, patchedVersion, provenance)` for each range and place the result in `AffectedPackage.NormalizedVersions`.
+3. Set a provenance note in the format `connector:{advisoryId}:{index}` so Merge can differentiate connector-provided rules from canonical fallbacks.
+4. Verify with `dotnet test` that the connector snapshot fixtures now include the `normalizedVersions` array and update fixtures by setting the connector-specific `UPDATE_*_FIXTURES=1` environment variable.
+5. Tail Merge logs (or the test output) for the new warning `Normalized version rules missing for {AdvisoryKey}`; an empty warning stream means the connector/merge artefacts are ready to close FEEDMERGE-COORD-02-901/902.
+
+## 2. Code snippet: SemVer connector (CCCS/Cisco/ICS-CISA)
+
+```csharp
+using StellaOps.Concelier.Normalization.SemVer;
+
+private static IReadOnlyList<AffectedPackage> BuildPackages(MyDto dto, DateTimeOffset recordedAt)
+{
+    var packages = new List<AffectedPackage>();
+
+    foreach (var entry in dto.AffectedEntries.Select((value, index) => (value, index)))
+    {
+        var rangeText = entry.value.Range?.Trim();
+        var patched = entry.value.FixedVersion;
+        var provenance = $"{MyConnectorPlugin.SourceName}:{dto.AdvisoryId}:{entry.index}";
+
+        var normalizedRules = SemVerRangeRuleBuilder.BuildNormalizedRules(rangeText, patched, provenance);
+        var primitives = SemVerRangeRuleBuilder.Build(rangeText, patched, provenance)
+            .Select(result => result.Primitive.ToAffectedVersionRange(provenance))
+            .ToArray();
+
+        packages.Add(new AffectedPackage(
+            AffectedPackageTypes.SemVer,
+            entry.value.PackageId,
+            versionRanges: primitives,
+            normalizedVersions: normalizedRules,
+            provenance: new[]
+            {
+                new AdvisoryProvenance(
+                    MyConnectorPlugin.SourceName,
+                    "package",
+                    entry.value.PackageId,
+                    recordedAt,
+                    new[] { ProvenanceFieldMasks.AffectedPackages })
+            }));
+    }
+
+    return packages;
+}
+```
+
+A few notes:
+
+- If you already have `SemVerPrimitive` instances, call `.ToNormalizedVersionRule(provenance)` on each primitive instead of rebuilding from raw strings.
+- Use `SemVerRangeRuleBuilder.BuildNormalizedRules` when the connector only tracks raw range text plus an optional fixed/patched version.
+- For products that encode ranges like `"ExampleOS 4.12 - 4.14"`, run a small regex to peel off the version substring (see §3) and use the same provenance note when emitting the rule and the original range primitive.
+
+## 3. Parsing helper for trailing version phrases
+
+Many of the overdue connectors store affected products as natural-language phrases.  The following helper normalises common patterns (`1.2 - 1.4`, `<= 3.5`, `Version 7.2 and later`).
+
+```csharp
+private static string? TryExtractRangeSuffix(string productString)
+{
+    if (string.IsNullOrWhiteSpace(productString))
+    {
+        return null;
+    }
+
+    var match = Regex.Match(productString, "(?<range>(?:<=?|>=?)?\s*\d+(?:\.\d+){0,2}(?:\s*-\s*\d+(?:\.\d+){0,2})?)", RegexOptions.CultureInvariant);
+    return match.Success ? match.Groups["range"].Value.Trim() : null;
+}
+```
+
+Once you extract the `range` fragment, feed it to `SemVerRangeRuleBuilder.BuildNormalizedRules(range, null, provenance)`.  Keep the original product string as-is so operators can still see the descriptive text.
+
+## 4. Merge dashboard hygiene
+
+- Run `dotnet build src/Concelier/__Libraries/StellaOps.Concelier.Merge/StellaOps.Concelier.Merge.csproj` after wiring a connector to confirm no warnings appear.
+- Merge counter tag pairs to watch in Grafana/CI logs:
+  - `concelier.merge.normalized_rules{package_type="npm"}` – increases once the connector emits normalized arrays.
+  - `concelier.merge.normalized_rules_missing{package_type="vendor"}` – should trend to zero once rollout completes.
+- The Merge service now logs `Normalized version rules missing for {AdvisoryKey}; sources=...; packageTypes=...` when a connector still needs to supply normalized rules.  Use this as the acceptance gate for FEEDMERGE-COORD-02-901/902.
+
+## 5. Documentation touchpoints
+
+- Update the connector `TASKS.md` entry with the date you flipped on normalized rules and note the provenance format you chose.
+- Record any locale-specific parsing (e.g., German `bis`) in the connector README so future contributors can regenerate fixtures confidently.
+- When opening the PR, include `dotnet test` output covering the connector tests so reviewers see the normalized array diff.
+
+Once each connector follows the steps above, we can mark FEEDCONN-CCCS-02-009, FEEDCONN-CISCO-02-009, FEEDCONN-CERTBUND-02-010, FEEDCONN-ICSCISA-02-012, and the FEEDMERGE-COORD-02-90x tasks as resolved.