feat(evaluate): provide rich diagnostic information on failure

Refs #21

Author: char0n

README.md

@@ -48,6 +48,7 @@
         - [Immutable.js](#immutablejs-evaluation-realm)
         - [Custom](#custom-evaluation-realms)
         - [Composing Realms](#composing-evaluation-realms)
+      - [Diagnostics](#diagnostics)
     - [Compilation](#compilation)
     - [Representation](#representation)
       - [JSON String](#json-string)
@@ -508,6 +509,22 @@ const structure = [
 evaluate(structure, '/0/a/b/1', { realm : compositeRealm }); // => 'd'
 ```
 
+##### Diagnostics
+
+`@swaggerexpert/json-pointer` provides rich diagnostic information to help identify and resolve issues during JSON Pointer evaluation.
+
+When evaluation fails, the library throws errors from a well-defined hierarchy — all extending from `JSONPointerEvaluateError`.
+These errors carry detailed diagnostic metadata describing what failed, where it failed, and why.
+
+Each error includes:
+
+- `jsonPointer` – the full pointer being evaluated
+- `referenceToken` – the token that caused the failure
+- `referenceTokenPosition` – the index of that token within the pointer
+- `referenceTokens` – the full list of parsed reference tokens
+- `currentValue` – the value being evaluated at the point of failure
+- `realm` – the name of the evaluation realm (e.g., "json")
+
 #### Compilation
 
 Compilation is the process of transforming a list of reference tokens into a JSON Pointer.

src/errors/JSONPointerTypeError.js

@@ -1,16 +1,5 @@
 import JSONPointerEvaluateError from './JSONPointerEvaluateError.js';
 
-class JSONPointerTypeError extends JSONPointerEvaluateError {
-  constructor(message, options) {
-    if (
-      typeof message === 'undefined' &&
-      (typeof options?.referenceToken === 'string' || typeof options?.referenceToken === 'number')
-    ) {
-      message = `Reference token '${options.referenceToken}' cannot be applied to non object/array value)`;
-    }
-
-    super(message, options);
-  }
-}
+class JSONPointerTypeError extends JSONPointerEvaluateError {}
 
 export default JSONPointerTypeError;

src/evaluate/index.js

@@ -26,12 +26,14 @@ const evaluate = (
         if (testArrayDash(referenceToken)) {
           if (strictArrays) {
             throw new JSONPointerIndexError(
-              'Invalid array index: "-" always refers to a nonexistent element during evaluation',
+              `Invalid array index "-" at position ${referenceTokenPosition} in ${jsonPointer}. The "-" token always refers to a nonexistent element during evaluation`,
               {
                 jsonPointer,
                 referenceTokens,
                 referenceToken,
                 referenceTokenPosition,
+                currentValue: current,
+                realm: realm.name,
               },
             );
           } else {
@@ -41,48 +43,64 @@ const evaluate = (
 
         if (!testArrayIndex(referenceToken) && strictArrays) {
           throw new JSONPointerIndexError(
-            `Invalid array index: '${referenceToken}' (MUST be "0", or digits without a leading "0")`,
+            `Invalid array index "${referenceToken}" at position ${referenceTokenPosition} in ${jsonPointer}: index MUST be "0", or digits without a leading "0"`,
             {
               jsonPointer,
               referenceTokens,
               referenceToken,
               referenceTokenPosition,
+              currentValue: current,
+              realm: realm.name,
             },
           );
         }
 
         const index = Number(referenceToken);
         if (index >= realm.sizeOf(current) && strictArrays) {
-          throw new JSONPointerIndexError(`Invalid array index: '${index}' out of bounds`, {
-            jsonPointer,
-            referenceTokens,
-            referenceToken: index,
-            referenceTokenPosition,
-          });
+          throw new JSONPointerIndexError(
+            `Invalid array index "${index}" at position ${referenceTokenPosition} in ${jsonPointer}: out of bounds`,
+            {
+              jsonPointer,
+              referenceTokens,
+              referenceToken: index,
+              referenceTokenPosition,
+              currentValue: current,
+              realm: realm.name,
+            },
+          );
         }
         return realm.evaluate(current, referenceToken);
       }
 
       if (realm.isObject(current)) {
         if (!realm.has(current, referenceToken) && strictObjects) {
-          throw new JSONPointerKeyError(`Invalid object key: '${referenceToken}' not found`, {
-            jsonPointer,
-            referenceTokens,
-            referenceToken,
-            referenceTokenPosition,
-          });
+          throw new JSONPointerKeyError(
+            `Invalid object key "${referenceToken}" at position ${referenceTokenPosition} in ${jsonPointer}: key not found in object`,
+            {
+              jsonPointer,
+              referenceTokens,
+              referenceToken,
+              referenceTokenPosition,
+              currentValue: current,
+              realm: realm.name,
+            },
+          );
         }
 
         return realm.evaluate(current, referenceToken);
       }
 
-      throw new JSONPointerTypeError(undefined, {
-        jsonPointer,
-        referenceTokens,
-        referenceToken,
-        referenceTokenPosition,
-        currentValue: current,
-      });
+      throw new JSONPointerTypeError(
+        `Invalid reference token "${referenceToken}" at position ${referenceTokenPosition} in ${jsonPointer}: cannot be applied to a non-object/non-array value`,
+        {
+          jsonPointer,
+          referenceTokens,
+          referenceToken,
+          referenceTokenPosition,
+          currentValue: current,
+          realm: realm.name,
+        },
+      );
     }, value);
   } catch (error) {
     if (error instanceof JSONPointerEvaluateError) {

src/evaluate/realms/apidom.js

@@ -30,10 +30,13 @@ class ApiDOMEvaluationRealm extends EvaluationRealm {
       const uniqueKeys = new Set(keys);
 
       if (keys.length !== uniqueKeys.size) {
-        throw new JSONPointerKeyError(`Object keys must be unique for '${referenceToken}'`, {
-          currentValue: node,
-          referenceToken,
-        });
+        throw new JSONPointerKeyError(
+          `Object key "${referenceToken}" is not unique — JSON Pointer requires unique member names`,
+          {
+            currentValue: node,
+            referenceToken,
+          },
+        );
       }
 
       return node.hasKey(referenceToken);

src/evaluate/realms/minim.js

@@ -30,10 +30,13 @@ class MinimEvaluationRealm extends EvaluationRealm {
       const uniqueKeys = new Set(keys);
 
       if (keys.length !== uniqueKeys.size) {
-        throw new JSONPointerKeyError(`Object keys must be unique for '${referenceToken}'`, {
-          currentValue: node,
-          referenceToken,
-        });
+        throw new JSONPointerKeyError(
+          `Object key "${referenceToken}" is not unique — JSON Pointer requires unique member names`,
+          {
+            currentValue: node,
+            referenceToken,
+          },
+        );
       }
 
       return node.hasKey(referenceToken);