Improve decode diagnostics across formats

Author: adz

TASKS.md

@@ -23,10 +23,7 @@ Completed rename, parser, bridge, compatibility, JSON Schema, docs, and projecti
   - Prefer expanding safe static auto-resolution over making `fieldWith` implicit through runtime metadata.
   - Keep `fieldWith` for true schema boundaries such as validated wrappers, imported contracts, and explicit child schemas.
 
-- [ ] **Task 32: Improve decode diagnostics**
-  - Make decode failures consistently report path, expected shape, actual token/value, and validation/wrapper context.
-  - Align JSON, XML, KeyValue, YAML, and imported JSON Schema errors around the same mental model.
-  - Treat debuggability as a core ergonomics feature for the explicit schema approach.
+- [x] **Task 32:** Added path-aware decode diagnostics across `Json`, `Xml`, `KeyValue`, and `Yaml`, including missing-field paths, collection indices/items, and `Schema.tryMap` validation context, with matching regression coverage in the unit test suite.
 
 - [ ] **Task 33: Ship canonical pattern docs**
   - Add copy-pasteable reference patterns for basic records, nested records, validated wrappers, versioned contracts, config contracts, JSON Schema import, and the C# bridge.
@@ -44,3 +41,14 @@ Completed rename, parser, bridge, compatibility, JSON Schema, docs, and projecti
   - Add a verification step so docs generation catches broken asset references before publishing.
 
 - [x] **Task 30:** Fixed the docs-site asset root by aligning `PackageProjectUrl` with the GitHub Pages URL instead of the repo URL, and hardened `scripts/generate-api-docs.sh` to clear stale `fsdocs` cache, build the doc assemblies first, and fail if generated output points theme/search assets at `github.com/adz/CodecMapper/...`.
+
+- [ ] **Task 35: Add property-based test coverage for codec laws**
+  - Add property-based tests for the real F# implementation rather than a sidecar model, since the main risks here are semantic drift, parser edge cases, and encode/decode symmetry across many inputs.
+  - Start with fixed representative schemas that already exist in the repo, then generate values for them: primitives, nested records, options, validated wrappers, collections, and numeric boundary cases.
+  - Make round-trip laws the first goal: `deserialize (serialize x) = x` for JSON and XML wherever the format supports the same shape.
+  - Add parser robustness properties for malformed inputs so failures stay deterministic and do not hang, over-consume input, or silently accept trailing content.
+  - Add format-symmetry properties where appropriate so one authored schema preserves the same semantic value across JSON and XML.
+  - Prefer `FsCheck.Xunit` in `tests/CodecMapper.Tests` so the property layer stays close to the existing xUnit and `Swensen.Unquote` test style.
+  - Keep the current example-based parser tests for exact regressions and expected error text; property tests should expand coverage, not replace those focused cases.
+  - Avoid starting with arbitrary recursive schema generation. The first iteration should optimize for debuggable failures and useful shrinking, not maximal generator cleverness.
+  - Treat generator design as part of the contract: keep generated values inside the supported deterministic surface instead of exploring JSON/XML features that the library intentionally leaves out.

src/CodecMapper/Json.fs

@@ -25,7 +25,59 @@ module Json =
         Decode: Decoder<'T>
     }
 
+    type internal DecodePathSegment =
+        | Property of string
+        | Index of int
+
+    type internal JsonDecodeException(path: DecodePathSegment list, detail: string, ?inner: exn) =
+        inherit System.Exception(detail, defaultArg inner null)
+
+        member _.Path = path
+        member _.Detail = detail
+
+        override _.Message =
+            let renderPath segments =
+                let builder = StringBuilder("$")
+
+                for segment in segments do
+                    match segment with
+                    | Property name ->
+                        builder.Append('.') |> ignore
+                        builder.Append(name) |> ignore
+                    | Index index ->
+                        builder.Append('[') |> ignore
+                        builder.Append(index) |> ignore
+                        builder.Append(']') |> ignore
+
+                builder.ToString()
+
+            sprintf "JSON decode error at %s: %s" (renderPath path) detail
+
     module internal Runtime =
+        let private asDecodeException detail path inner =
+            JsonDecodeException(path, detail, inner) :> exn
+
+        let decodeFailure detail =
+            raise (asDecodeException detail [] null)
+
+        let private prependPath segment (ex: exn) =
+            match ex with
+            | :? JsonDecodeException as decodeEx -> asDecodeException decodeEx.Detail (segment :: decodeEx.Path) ex
+            | _ -> asDecodeException ex.Message [ segment ] ex
+
+        let withPath segment f =
+            try
+                f ()
+            with ex ->
+                raise (prependPath segment ex)
+
+        let withValidationContext f =
+            try
+                f ()
+            with
+            | :? JsonDecodeException -> reraise ()
+            | ex -> raise (asDecodeException ("Validation failed: " + ex.Message) [] ex)
+
         let inline skipWhitespace (src: JsonSource) =
             let mutable i = src.Offset
             let data = src.Data
@@ -878,10 +930,13 @@ module Json =
                         if valSrc.Data = null then
                             match f.Codec.MissingValue with
                             | Some value -> value
-                            | None -> failwithf "Missing required key: %s" f.Name
+                            | None ->
+                                Runtime.withPath (Property f.Name) (fun () ->
+                                    Runtime.decodeFailure (sprintf "Missing required key '%s'" f.Name))
                         else
-                            let struct (v, _) = f.Codec.Decode valSrc
-                            v)
+                            Runtime.withPath (Property f.Name) (fun () ->
+                                let struct (v, _) = f.Codec.Decode valSrc
+                                v))
 
                 struct (ctor args, current)
 
@@ -922,10 +977,15 @@ module Json =
                     continueLoop <- false
                     src <- src.Advance(1)
 
+                let mutable index = 0
+
                 while continueLoop do
-                    let struct (item, nextSrc) = innerCodec.Decode src
+                    let struct (item, nextSrc) =
+                        Runtime.withPath (Index index) (fun () -> innerCodec.Decode src)
+
                     results <- item :: results
                     src <- Runtime.skipWhitespace nextSrc
+                    index <- index + 1
 
                     if src.Offset < src.Data.Length && src.Data[src.Offset] = 44uy then
                         src <- src.Advance(1)
@@ -973,10 +1033,15 @@ module Json =
                     continueLoop <- false
                     src <- src.Advance(1)
 
+                let mutable index = 0
+
                 while continueLoop do
-                    let struct (item, nextSrc) = innerCodec.Decode src
+                    let struct (item, nextSrc) =
+                        Runtime.withPath (Index index) (fun () -> innerCodec.Decode src)
+
                     results.Add(item)
                     src <- Runtime.skipWhitespace nextSrc
+                    index <- index + 1
 
                     if src.Offset < src.Data.Length && src.Data[src.Offset] = 44uy then
                         src <- src.Advance(1)
@@ -1007,7 +1072,10 @@ module Json =
 
             {
                 Encode = (fun w v -> innerCodec.Encode w (unwrapFunc v))
-                Decode = (fun src -> let struct (v, s) = innerCodec.Decode src in struct (wrap v, s))
+                Decode =
+                    (fun src ->
+                        let struct (v, s) = innerCodec.Decode src
+                        struct (Runtime.withValidationContext (fun () -> wrap v), s))
                 MissingValue = innerCodec.MissingValue |> Option.map wrap
             }
         | _ -> failwithf "Unsupported schema type: %O" schema.Definition
@@ -1018,7 +1086,15 @@ module Json =
 
         {
             Encode = (fun w v -> compiled.Encode w (box v))
-            Decode = (fun src -> let struct (v, s) = compiled.Decode src in struct (unbox v, s))
+            Decode =
+                (fun src ->
+                    try
+                        let struct (v, s) = compiled.Decode src
+                        struct (unbox v, s)
+                    with ex ->
+                        match ex with
+                        | :? JsonDecodeException -> raise ex
+                        | _ -> Runtime.decodeFailure ex.Message)
         }
 
     ///
@@ -1042,7 +1118,7 @@ module Json =
         let rest = Runtime.skipWhitespace rest
 
         if rest.Offset <> bytes.Length then
-            failwith "Trailing content after top-level JSON value"
+            Runtime.decodeFailure "Trailing content after top-level JSON value"
 
         v
 
@@ -1052,6 +1128,6 @@ module Json =
         let rest = Runtime.skipWhitespace rest
 
         if rest.Offset <> bytes.Length then
-            failwith "Trailing content after top-level JSON value"
+            Runtime.decodeFailure "Trailing content after top-level JSON value"
 
         v

src/CodecMapper/KeyValue.fs

@@ -32,12 +32,47 @@ module KeyValue =
         Decode: Map<string, string> -> 'T
     }
 
+    type internal KeyValueDecodeException(path: string list, detail: string, ?inner: exn) =
+        inherit System.Exception(detail, defaultArg inner null)
+
+        member _.Path = path
+        member _.Detail = detail
+
+        override _.Message =
+            let renderedPath =
+                match path with
+                | [] -> "$"
+                | _ -> "$." + String.concat "." path
+
+            sprintf "KeyValue decode error at %s: %s" renderedPath detail
+
     type CompiledCodec = {
         Encode: string list -> obj -> (string * string) list
         Decode: string list -> Map<string, string> -> obj option
         MissingValue: obj option
     }
 
+    let private asDecodeException detail path inner =
+        KeyValueDecodeException(path, detail, inner) :> exn
+
+    let private decodeFailure path detail =
+        raise (asDecodeException detail path null)
+
+    let private withPath path f =
+        try
+            f ()
+        with ex ->
+            match ex with
+            | :? KeyValueDecodeException as decodeEx -> raise (asDecodeException decodeEx.Detail path ex)
+            | _ -> raise (asDecodeException ex.Message path ex)
+
+    let private withValidationContext path f =
+        try
+            f ()
+        with
+        | :? KeyValueDecodeException -> reraise ()
+        | ex -> raise (asDecodeException ("Validation failed: " + ex.Message) path ex)
+
     let private keyName (options: Options) (segments: string list) =
         match segments with
         | [] -> failwith "KeyValue paths must contain at least one segment"
@@ -106,7 +141,10 @@ module KeyValue =
         match schema.Definition with
         | Primitive targetType -> {
             Encode = (fun path value -> [ keyName options path, formatPrimitive targetType value ])
-            Decode = (fun path values -> tryFindValue options path values |> Option.map (parsePrimitive targetType))
+            Decode =
+                (fun path values ->
+                    tryFindValue options path values
+                    |> Option.map (fun value -> withPath path (fun () -> parsePrimitive targetType value)))
             MissingValue = None
           }
         | Record(_, fields, ctor) ->
@@ -143,9 +181,11 @@ module KeyValue =
                                         match field.Codec.MissingValue with
                                         | Some value -> value
                                         | None ->
-                                            failwithf
-                                                "Missing required key: %s"
-                                                (keyName options (path @ [ field.Field.Name ])))
+                                            let fieldPath = path @ [ field.Field.Name ]
+
+                                            decodeFailure
+                                                fieldPath
+                                                (sprintf "Missing required key '%s'" (keyName options fieldPath)))
 
                             Some(ctor args))
                 MissingValue = None
@@ -231,7 +271,10 @@ module KeyValue =
 
             {
                 Encode = (fun path value -> innerCodec.Encode path (unwrap value))
-                Decode = (fun path values -> innerCodec.Decode path values |> Option.map wrap)
+                Decode =
+                    (fun path values ->
+                        innerCodec.Decode path values
+                        |> Option.map (fun value -> withValidationContext path (fun () -> wrap value)))
                 MissingValue = innerCodec.MissingValue |> Option.map wrap
             }
         | List _
@@ -247,9 +290,14 @@ module KeyValue =
             Encode = (fun value -> compiled.Encode [] (box value) |> Map.ofList)
             Decode =
                 (fun values ->
-                    match compiled.Decode [] values with
-                    | Some value -> unbox value
-                    | None -> failwith "KeyValue payload did not contain any decodable fields")
+                    try
+                        match compiled.Decode [] values with
+                        | Some value -> unbox value
+                        | None -> decodeFailure [] "Payload did not contain any decodable fields"
+                    with ex ->
+                        match ex with
+                        | :? KeyValueDecodeException -> raise ex
+                        | _ -> decodeFailure [] ex.Message)
         }
 
     /// Compiles a schema into a reusable flat key/value codec using dotted keys.