Reject unsupported OpenAPI versions in the lint command

[jviotti]

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

[augmentcode]

🤖 Augment PR Summary

Summary: This PR makes lint reject OpenAPI revisions unsupported by the bundled OpenAPI implementation.

Changes:

• Adds a helper that identifies string-valued openapi declarations not recognized by Core.
• Runs that check in both normal linting and --fix processing before schema linting begins.
• Introduces UnsupportedOpenAPIVersionError, preserving the declared revision for text and JSON error output.
• Maps this error to the existing “not supported” exit status.
• Adds CLI tests for OpenAPI 3.0, a newer 3.3 revision, malformed 3.1, and a non-string openapi field.
• Verifies that rejected inputs are not modified by --fix.

Technical Notes: Supported revision recognition remains delegated to sourcemeta::core::openapi_version, which currently recognizes valid 3.1.x and 3.2.x declarations.

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

[augmentcode]

Review completed. 1 suggestion posted.

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

[augmentcode]

src/utils.h:135 treats any object with a string-valued openapi member as an OpenAPI description even when it lacks required OpenAPI members such as info, despite JSON Schema permitting arbitrary/custom keyword names. Consequently, a JSON Schema containing "openapi": "3.0.3" now exits with an unsupported-version error instead of being linted (unlike the analogous non-string case covered by the new test), so this rejects inputs that are not OpenAPI descriptions.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[cubic-dev-ai]

2 issues found across 8 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="test/lint/fail_lint_openapi_version_not_a_string.clitest">

<violation number="1" location="test/lint/fail_lint_openapi_version_not_a_string.clitest:38">
P2: The expected end column in `"position"` is off by one. `"openapi": 3` on line 6 spans columns 3-15 (`  "openapi": 3` — key at 3-12, colon at 13, space at 14, value `3` at 15), so the position should be `[ 6, 3, 6, 15 ]`. The existing `fail_lint_positions_json.clitest` confirms the same tracker reports the full key/value span for an object member (`"unknown-1": 1` → `[ 6, 5, 6, 18 ]`, where the value sits at column 18). As written with end column 14, the `COMPARE result_1.txt AGAINST expected_1.txt` will fail in CI.</violation>
</file>

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

<violation number="1" location="src/utils.h:136">
P2: Only classify an unrecognized `openapi` string as an unsupported OpenAPI revision after confirming the document has OpenAPI's required structure; otherwise valid JSON Schemas using `openapi` as a custom keyword are rejected by `lint`.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The expected end column in "position" is off by one. "openapi": 3 on line 6 spans columns 3-15 ( "openapi": 3 — key at 3-12, colon at 13, space at 14, value 3 at 15), so the position should be [ 6, 3, 6, 15 ]. The existing fail_lint_positions_json.clitest confirms the same tracker reports the full key/value span for an object member ("unknown-1": 1 → [ 6, 5, 6, 18 ], where the value sits at column 18). As written with end column 14, the COMPARE result_1.txt AGAINST expected_1.txt will fail in CI.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At test/lint/fail_lint_openapi_version_not_a_string.clitest, line 38:

<comment>The expected end column in `"position"` is off by one. `"openapi": 3` on line 6 spans columns 3-15 (`  "openapi": 3` — key at 3-12, colon at 13, space at 14, value `3` at 15), so the position should be `[ 6, 3, 6, 15 ]`. The existing `fail_lint_positions_json.clitest` confirms the same tracker reports the full key/value span for an object member (`"unknown-1": 1` → `[ 6, 5, 6, 18 ]`, where the value sits at column 18). As written with end column 14, the `COMPARE result_1.txt AGAINST expected_1.txt` will fail in CI.</comment>

<file context>
@@ -0,0 +1,44 @@
+1>       "message": "Future versions of JSON Schema will refuse to evaluate unknown keywords or custom keywords from optional vocabularies that don't have an x- prefix",
+1>       "description": null,
+1>       "schemaLocation": [ "openapi" ],
+1>       "position": [ 6, 3, 6, 14 ]
+1>     }
+1>   ]
</file context>

Suggested change

	1> "position": [ 6, 3, 6, 14 ]
	+1> "position": [ 6, 3, 6, 15 ]

[cubic-dev-ai]

P2: Only classify an unrecognized openapi string as an unsupported OpenAPI revision after confirming the document has OpenAPI's required structure; otherwise valid JSON Schemas using openapi as a custom keyword are rejected by lint.

Prompt for AI agents

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

<comment>Only classify an unrecognized `openapi` string as an unsupported OpenAPI revision after confirming the document has OpenAPI's required structure; otherwise valid JSON Schemas using `openapi` as a custom keyword are rejected by `lint`.</comment>

<file context>
@@ -116,6 +117,25 @@ inline auto looks_like_test_document(const sourcemeta::core::JSON &document)
+  }
+
+  return sourcemeta::core::openapi_version(document).has_value() ? nullptr
+                                                                 : version;
+}
+
</file context>