Bug Report: Missing Warning for Unresolved References

[ringgelerch]

Expected Behavior

When generating Markdown documentation from a JSON Schema, unresolved $ref references (e.g., pointing to non-existent schema properties) should trigger a warning in the console output.

Actual Behavior

No warning is displayed when an unresolved $ref is encountered during Markdown generation. The process completes silently, potentially leading to incomplete or misleading documentation.

Steps to Reproduce

1. Use the following JSON Schema:

   {
     "meta:license": [
       "Copyright 2017 Adobe Systems Incorporated. All rights reserved.",
       "This file is licensed to you under the Apache License, Version 2.0 (the 'License');",
       "you may not use this file except in compliance with the License. You may obtain a copy",
       "of the License at http://www.apache.org/licenses/LICENSE-2.0"
     ],
     "$schema": "http://json-schema.org/draft-06/schema#",
     "$id": "https://example.com/schemas/complex",
     "title": "Complex References",
     "type": "object",
     "description": "This is an example schema that uses types defined in other schemas.",
     "properties": {
       "refnamed": {
         "version": "1.0.0",
         "testProperty": "test"
       },
       "refrefed": {
         "$ref": "#/properties/refnamed2",
         "version": "1.0.0",
         "testProperty": "test"
       }
     }
   }

2. Run the following command:

   jsonschema2md -d schemas/test -x -

3. Observe the console output:

   loading 1 schemas
   preparing schemas...
   preparing schemas
   preparing README...
   building readme
   README.md created
   preparing documentation...
   generating markdown
   

4. Note that no warning is shown for the broken reference:

   "$ref": "#/properties/refnamed2"

Environment

• Operating System: Windows 11 (WSL2)
• Node.js Version: v22.17.0
• jsonschema2md Version: 8.0.3

Additional Notes

• The issue may lead to silent failures in documentation generation, especially in large schemas where broken references are harder to detect manually.
• A warning or error message would greatly improve developer experience and reliability.

[Adityakumar37]

@ringgelerch @tripodsan i would like to work on this

[ringgelerch]

In the meantime, I discovered that the issue was caused by how I executed the command. The error output was being filtered.
The error output actually contains warnings, but I would expect the execution to fail in this case. Maybe it would make sense to add a parameter that controls whether execution should fail when broken references are detected.

[Adityakumar37]

@ringgelerch I understand now that the warnings are already present, but depending on how the command is executed they may not always be visible.
I agree that it would be useful to have an optional strict mode, such as a flag like --fail-on-broken-refs, which would cause the tool to exit with an error when unresolved $ref references are detected

I’d be happy to work on implementing this