Improve rdf command error messages and documentation

[jviotti]

Signed-off-by: Juan Cruz Viotti jv@jviotti.com

[augmentcode]

🤖 Augment PR Summary

Summary: This PR improves the jsonschema rdf command’s diagnostics and user-facing documentation for JSON-LD annotation resolution.

Changes:

• Expands docs/rdf.markdown with a clearer contract: resolution errors enforce syntactic/well-formed JSON-LD constraints and report precise schema locations, while semantic correctness remains the author’s responsibility.
• Documents stricter handling of language tags (canonical BCP 47 form) as a deliberate JSON-LD 1.1 deviation, and clarifies x-jsonld-self template variable matching behavior.
• Adds an override facet name mapping and extends RdfResolutionError to carry schemaLocation, optional conflictingSchemaLocation, and optional inertOverrideLocation.
• Updates generic exception printing to include these new fields in both text and JSON output.
• Enhances non-JSON output with a targeted hint when an x-jsonld-override mark is present but ineffective.
• Extends existing RDF failure tests to assert the new schema-location fields and adds two new regression tests for inert overrides and non-boolean override values.

Technical Notes: The new location fields are threaded from the JSON-LD resolution layer through command_rdf.cc into print_exception, and validated via golden-output shell tests for both human-readable and --json modes.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. No suggestions at this time.

Comment augment review to trigger a new review at any time.

[cubic-dev-ai]

1 issue found across 12 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/error.h">

<violation number="1" location="src/error.h:938">
P3: The x-jsonld-override hint block is copied verbatim into two catch handlers (`PositionError<RdfResolutionError>` and `RdfResolutionError`) within the same `try_catch` function. Since `PositionError<T>` inherits from `T`, a single helper (or a small static function that takes the error reference and `is_json`) could print this hint once and be reused by both handlers, keeping the message in one place and making future edits to the wording less error-prone.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The x-jsonld-override hint block is copied verbatim into two catch handlers (PositionError<RdfResolutionError> and RdfResolutionError) within the same try_catch function. Since PositionError<T> inherits from T, a single helper (or a small static function that takes the error reference and is_json) could print this hint once and be reused by both handlers, keeping the message in one place and making future edits to the wording less error-prone.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/error.h, line 938:

<comment>The x-jsonld-override hint block is copied verbatim into two catch handlers (`PositionError<RdfResolutionError>` and `RdfResolutionError`) within the same `try_catch` function. Since `PositionError<T>` inherits from `T`, a single helper (or a small static function that takes the error reference and `is_json`) could print this hint once and be reused by both handlers, keeping the message in one place and making future edits to the wording less error-prone.</comment>

<file context>
@@ -863,10 +935,26 @@ inline auto try_catch(const sourcemeta::core::Options &options,
   } catch (const PositionError<RdfResolutionError> &error) {
     const auto is_json{options.contains("json")};
     print_exception(is_json, error);
+    if (!is_json && error.inert_override_location().has_value()) {
+      std::cerr << "\nThe x-jsonld-override mark was ignored because it does "
+                   "not enclose the\n";
</file context>