feat(validator-speclynx): expose parse result via toolbox (#209)

Author: char0n

packages/jentic-openapi-validator-speclynx/README.md

@@ -197,13 +197,13 @@ if "dict" in validator.accepts():
 ## Custom Plugins
 
 Create custom validation plugins as ES modules (`.mjs` files). Plugins use the ApiDOM visitor pattern and receive
-a toolbox with dependencies and diagnostics array:
+a toolbox with dependencies, diagnostics array, and parse result:
 
 ```javascript
 // custom-plugin.mjs
 
 export default (toolbox) => {
-    const {diagnostics, deps} = toolbox;
+    const {diagnostics, deps, parseResult} = toolbox;
     const {DiagnosticSeverity} = deps['vscode-languageserver-types'];
     const {toValue} = deps['@speclynx/apidom-core'];
 

packages/jentic-openapi-validator-speclynx/src/jentic/apitools/openapi/validator/backends/speclynx/__init__.py

@@ -64,6 +64,7 @@ def __init__(
                   @speclynx/apidom-datamodel, @speclynx/apidom-json-path, @speclynx/apidom-json-pointer,
                   @speclynx/apidom-traverse, and @speclynx/apidom-reference
                 - diagnostics: Array to collect validation diagnostics
+                - parseResult: The full ApiDOM parse result for accessing document metadata
                 See resources/plugins/example-plugin.mjs.sample for plugin format.
         """
         self.speclynx_path = speclynx_path

packages/jentic-openapi-validator-speclynx/src/jentic/apitools/openapi/validator/backends/speclynx/resources/plugins/example-plugin.mjs.sample

@@ -6,17 +6,19 @@
  *
  * Plugin structure:
  * - Must export a default function that accepts a toolbox object with:
- *   - diagnostics: Array to collect validation diagnostics
  *   - deps: External dependencies (vscode-languageserver-types, @speclynx/apidom-core, etc.)
+ *   - diagnostics: Array to collect validation diagnostics
+ *   - parseResult: The full ApiDOM parse result for accessing document metadata
  * - Returns an object with pre/post hooks and a visitor property
  * - The visitor contains methods named after ApiDOM element types
  * - Each visitor method receives a path object with information about the current element
  *   - path.node: The actual ApiDOM element being visited
  *   - path.getPathKeys(): Returns the JSON path to the element
  *
  * @param {Object} toolbox - Plugin toolbox
- * @param {Array} toolbox.diagnostics - Array to collect validation diagnostics
  * @param {Object} toolbox.deps - External dependencies
+ * @param {Array} toolbox.diagnostics - Array to collect validation diagnostics
+ * @param {Object} toolbox.parseResult - The ApiDOM parse result
  */
 
 export default (toolbox) => {

packages/jentic-openapi-validator-speclynx/src/jentic/apitools/openapi/validator/backends/speclynx/resources/plugins/openapi-document.mjs

@@ -12,6 +12,7 @@
  *   @speclynx/apidom-datamodel, @speclynx/apidom-json-path, @speclynx/apidom-json-pointer,
  *   @speclynx/apidom-traverse, and @speclynx/apidom-reference
  * - diagnostics: Array to collect validation diagnostics
+ * - parseResult: The full ApiDOM parse result for accessing document metadata
  */
 
 export default (toolbox) => {

packages/jentic-openapi-validator-speclynx/src/jentic/apitools/openapi/validator/backends/speclynx/resources/speclynx.mjs

@@ -140,7 +140,7 @@ async function validate(document, cliOptions) {
         return {valid: false, diagnostics};
     }
 
-    // Toolbox creation - provides deps and diagnostics to plugins
+    // Toolbox creation - provides deps, diagnostics, and parseResult to plugins
     const createToolbox = () => ({
         deps: {
             'vscode-languageserver-types': vscodeLanguageServerTypes,
@@ -152,6 +152,7 @@ async function validate(document, cliOptions) {
             '@speclynx/apidom-reference': apidomReference,
         },
         diagnostics,
+        parseResult,
         ...createToolboxBase()
     });
 

packages/jentic-openapi-validator-speclynx/tests/fixtures/plugins/parseresult-check.mjs

@@ -0,0 +1,46 @@
+/**
+ * Test plugin that verifies parseResult is available in the toolbox.
+ *
+ * This plugin emits a diagnostic if parseResult is missing or doesn't contain
+ * expected properties, helping catch regressions in toolbox wiring.
+ */
+
+export default (toolbox) => {
+    const {diagnostics, deps, parseResult} = toolbox;
+    const {DiagnosticSeverity} = deps['vscode-languageserver-types'];
+
+    return {
+        visitor: {
+            InfoElement() {
+                // Verify parseResult is available
+                if (!parseResult) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        message: 'toolbox.parseResult is missing',
+                        code: 'missing-parseresult',
+                        range: {
+                            start: {line: 0, character: 0},
+                            end: {line: 0, character: 0}
+                        },
+                        data: {path: []}
+                    });
+                    return;
+                }
+
+                // For valid OpenAPI 3.x documents, parseResult.api should exist
+                if (parseResult.api) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Information,
+                        message: 'parseResult.api is available',
+                        code: 'parseresult-api-available',
+                        range: {
+                            start: {line: 0, character: 0},
+                            end: {line: 0, character: 0}
+                        },
+                        data: {path: []}
+                    });
+                }
+            }
+        }
+    };
+};

packages/jentic-openapi-validator-speclynx/tests/fixtures/plugins/version-validator.mjs

@@ -6,6 +6,7 @@
  *   @speclynx/apidom-datamodel, @speclynx/apidom-json-path, @speclynx/apidom-json-pointer,
  *   @speclynx/apidom-traverse, and @speclynx/apidom-reference
  * - diagnostics: Array to collect validation diagnostics
+ * - parseResult: The full ApiDOM parse result for accessing document metadata
  */
 
 export default (toolbox) => {

packages/jentic-openapi-validator-speclynx/tests/test_speclynx_validate.py

@@ -123,6 +123,26 @@ def test_both_default_and_custom_plugins_produce_diagnostics(
         # Custom plugin should detect integer version
         assert any("version" in d.message.lower() for d in result.diagnostics)
 
+    def test_parseresult_available_in_toolbox(self, speclynx_validator_with_plugins):
+        """Test that parseResult is available to plugins via toolbox.
+
+        The parseresult-check.mjs plugin emits an informational diagnostic
+        when parseResult.api is available, verifying the toolbox wiring.
+        """
+        document = {
+            "openapi": "3.0.0",
+            "info": {"title": "Test API", "version": "1.0.0"},
+            "paths": {},
+        }
+        result = speclynx_validator_with_plugins.validate(document)
+        assert result.valid is True
+        # The parseresult-check plugin should emit info diagnostic confirming parseResult.api exists
+        parseresult_diagnostic = next(
+            (d for d in result.diagnostics if d.code == "parseresult-api-available"), None
+        )
+        assert parseresult_diagnostic is not None, "parseResult should be available to plugins"
+        assert "parseResult.api is available" in parseresult_diagnostic.message
+
     def test_validate_empty_document_produces_error(self, speclynx_validator, tmp_path):
         """Test that empty documents produce validation errors.