ArgParser: correct map spellability, seen-set scaling, and help syntax

Three follow-ups to the Map support.

Only an unspellable enumerated case is rejected. Enumerated values are
matched with OrdinalIgnoreCase while an entry is split ordinally, so every
casing of a case name is an accepted spelling: a case named `Apple`
survives the separator 'A' because it may be spelled `apple`. The check now
rejects a case only when some character has no casing which avoids the
separators, which is the actual condition for unrepresentability. It also
now considers the separators jointly, so a case named `A` is rejected when
'a' and 'A' are the two separators, though neither alone would do it.

The seen-key set is carried between occurrences. A map with no entry
separator is filled by repeating the argument, and rebuilding the set from
every accumulated key on each occurrence made parsing N entries quadratic.
Each map field now has a persistent-set slot beside its accumulator, seeded
from it in O(1); both are committed only once every entry of the occurrence
has parsed and been found fresh, so a failure partway still leaves the
field untouched.

Help text describes each half of an entry in the syntax that half accepts.
A flag DU is spelled true/false and an enumerated value by case name, so
rendering the raw type left the user guessing: a map now reports e.g.
`map<Severity [one of: Low|High], bool>` rather than `map<Severity,
Enabled>`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: Smaug123

CHANGELOG.md

@@ -10,7 +10,8 @@ An unsupplied `Map` is empty, so (like a `list`) it may not be an `option` or ca
 Supplying the same key twice is an error rather than an overwrite.
 Each entry is split at its *first* key-value separator, so a value may contain that separator but a key may not.
 This means e.g. that some `Map<string, string>` are inexpressible (if the key contains the key-value separator); use `string list` and parse it yourself into a map if you need something smarter.
-Where the spellings are known at generation time we check them: an enumerated key or value whose case name contains a separator it must avoid is rejected rather than silently misparsed.
+Where the spellings are known at generation time we check them: an enumerated key or value with a case that no spelling can express is rejected rather than silently misparsed.
+Help text describes each half of an entry in the syntax that half accepts, so a flag-valued map advertises `map<..., bool>` and an enumerated one lists its case names.
 
 # WoofWare.Myriad.Plugins 10.3.1
 

ConsumePlugin/GeneratedMapArgs.fs

@@ -37,6 +37,34 @@ type MapArgs =
         Switches : Map<string, bool>
     }
 
+/// A flag-valued union: its values are spelled `true` and `false`, so help text must advertise
+/// `bool` rather than the union's name.
+type Enabled =
+    | [<ArgumentFlag true>] Yes
+    | [<ArgumentFlag false>] No
+
+/// An enumerated type with a case containing a cased letter, so that a cased letter can be used
+/// as a separator without making the case unspellable.
+type Alpha =
+    | Apple
+    | Pear
+
+/// Help text must describe each side of a map in the syntax that side actually accepts, and a
+/// cased separator must not be mistaken for one which makes a case unrepresentable.
+[<ArgParser>]
+type MapDisplayArgs =
+    {
+        /// An enumerated key and a flag-valued value: `--features=Low:true`.
+        [<ArgumentKeyValueSeparator ':'>]
+        Features : Map<Severity, Enabled>
+
+        /// `Apple` contains an `A`, but enumerated values are matched case-insensitively, so the
+        /// key may be spelled `apple` — which avoids the separator. Every `Map<Alpha, _>` is
+        /// therefore expressible, e.g. `--casing=appleAvalue`.
+        [<ArgumentKeyValueSeparator 'A'>]
+        Casing : Map<Alpha, string>
+    }
+
 type DeployArgs =
     {
         [<ArgumentKeyValueSeparator ':'>]

ConsumePlugin/MapArgs.fs

@@ -289,8 +289,9 @@ For key types which cannot spell the separator in the first place (like an `int`
 Do note that some types spell themselves with punctuation: `TimeSpan` uses colons and `Guid` uses hyphens, so choose a separator accordingly.
 If you need to express keys containing arbitrary characters, take a `string list` field and do the splitting yourself with whatever logic is appropriate to your domain.
 
-Where the spellings are known at generation time, we check rather than trust: a key or value which is an enumerated union has its case names checked against the separators, and generation fails if one of them contains a separator it must avoid.
-(Case names are arbitrary identifiers, so ``` ``a:b`` ``` is a perfectly legal case name which no command line could express as a key when `:` is the separator.)
+Where the spellings are known at generation time, we check rather than trust: a key or value which is an enumerated union has its case names checked against the separators, and generation fails for a case which no spelling can express.
+(Case names are arbitrary identifiers, so ``` ``a:b`` ``` is a perfectly legal case name, and no command line could express it as a key when `:` is the separator.)
+Note "no spelling": enumerated values are matched case-insensitively while entries are split case-sensitively, so a case named `Apple` survives the separator `A` — spell it `apple` — and only a character whose every casing is a separator is fatal.
 
 ### Help text
 

README.md

@@ -226,6 +226,51 @@ module TestArgParserMap =
 
         exc.Message |> shouldContainText "map<string, bool>"
 
+    // ------------------------------------------------------- component syntax in help
+
+    [<Test>]
+    let ``Help text describes each side of a map in the syntax that side accepts`` () =
+        let exc =
+            Assert.Throws<exn> (fun () -> MapDisplayArgs.parse' noEnv [ "--help" ] |> ignore<MapDisplayArgs>)
+
+        // A flag DU is spelled true/false, and an enumerated value by case name, exactly as they
+        // would be if they were scalar leaves rather than halves of a map entry.
+        exc.Message |> shouldContainText "map<Severity [one of: Low|High], bool>"
+
+    [<Test>]
+    let ``A cased separator does not make an enumerated case unspellable`` () =
+        // 'A' is the separator and the case is named `Apple`, but values are matched
+        // case-insensitively, so `apple` names the case while avoiding the separator.
+        let args = MapDisplayArgs.parse' noEnv [ "--casing=appleAvalue" ]
+
+        args.Casing |> shouldEqual (Map.ofList [ Alpha.Apple, "value" ])
+
+    [<Test>]
+    let ``A flag-valued map parses its values as booleans`` () =
+        let args =
+            MapDisplayArgs.parse' noEnv [ "--features=Low:true" ; "--features=High:false" ]
+
+        args.Features
+        |> shouldEqual (Map.ofList [ Severity.Low, Enabled.Yes ; Severity.High, Enabled.No ])
+
+    // ------------------------------------------------------- accumulating many occurrences
+
+    [<Test>]
+    let ``Many occurrences accumulate, and a late duplicate is still caught`` () =
+        // The seen-key set is carried between occurrences rather than rebuilt from the
+        // accumulator each time; this exercises that it is actually kept up to date.
+        let entries = List.init 500 (fun i -> $"k%i{i}", $"v%i{i}")
+
+        parseLabels entries |> shouldEqual (Map.ofList entries)
+
+        let exc =
+            Assert.Throws<exn> (fun () ->
+                MapArgs.parse' noEnv (renderLabels entries @ [ "--labels=k0:again" ])
+                |> ignore<MapArgs>
+            )
+
+        exc.Message |> shouldContainText "Key 'k0' was supplied more than once"
+
     // ------------------------------------------------------- reference implementation
 
     [<Test>]