Module jsonpath_diagnostics 

Domain-specific hints for JSONPath parse errors.

serde_json_path is RFC 9535-compliant. The authoring mistake the P2a launch-prep validation pass surfaced and confirmed against serde_json_path 0.7.x is:

• § 10 — dashed keys after a . segment (e.g. $.package-name or $.foo[?@.dashed-key == 'x']) are rejected; bracket notation ($['package-name'], $.foo[?@['dashed-key']) is required by the spec. This applies in both top-level path segments and inside filter expressions.

(A previously-suspected pitfall — outer parentheses on filter predicates $.foo[?(@.bar == 'baz')] — was investigated during Phase 4 and confirmed valid against serde_json_path 0.7.2; the original report mis-attributed a dashed-key error to the parens. See the v0.9.15 Phase 4 commit for the test that proved it.)

The raw serde_json_path error message says what failed (lexical / syntax) but not why. This helper inspects the source path for the dashed-key pattern and appends a hint pointing at the canonical-correct form.

Functions

diagnose_path

Inspect a JSONPath source string for known-bad patterns and return a hint string when one applies.

format_parse_error

Build a complete error-message string for a JSONPath parse failure: invalid JSONPath "<path>": <serde_json_path err> plus any domain-specific hint from diagnose_path.