feat: add helpers to extract processed api from spectral context

The Spectral 'context' object contains processed data about the
OpenAPI definition being validated, including the resolved and
unresolved versions of the definition and information about
references. We use these objects in rule functions and they need
to be extracted from deeply nested fields in the spectral context.
Rather than always needing to remember or look up the fields,
this commit allows us to use simple helper functions to get the
data we need.

Signed-off-by: Dustin Popp <[email protected]>

Author: dpopp07

docs/openapi-ruleset-utilities.md

@@ -354,6 +354,39 @@ for OpenAPI documents where a `required` property is not defined under the `prop
 
 #### Returns `boolean`
 
+### `getResolvedSpec(context)`
+
+Returns the programmatic representation of an OpenAPI document, stored in the
+Spectral-created "context" object, with all non-circular references resolved.
+
+#### Parameters
+
+- **`context`** `<object>`: passed as an argument to Spectral-based rule functions
+
+#### Returns `object`: the resolved version of an OpenAPI document
+
+### `getUnresolvedSpec(context)`
+
+Returns the programmatic representation of an OpenAPI document, stored in
+the Spectral-created "context" object, with all references still intact.
+
+#### Parameters
+
+- **`context`** `<object>`: passed as an argument to Spectral-based rule functions
+
+#### Returns `object`: the unresolved version of an OpenAPI document
+
+### `getNodes(context)`
+
+Returns the graph nodes, with information about references and the locations
+they resolve to, that are computed by the Spectral resolver.
+
+#### Parameters
+
+- **`context`** `<object>`: passed as an argument to Spectral-based rule functions
+
+#### Returns `object`: the graph nodes
+
 ### `validateComposedSchemas(schema, path, validate, includeSelf, includeNot)`
 
 Performs validation on a schema and all of its composed schemas.

packages/utilities/src/utils/index.js

@@ -1,5 +1,5 @@
 /**
- * Copyright 2017 - 2024 IBM Corporation.
+ * Copyright 2017 - 2025 IBM Corporation.
  * SPDX-License-Identifier: Apache2.0
  */
 
@@ -13,6 +13,7 @@ module.exports = {
   schemaHasProperty: require('./schema-has-property'),
   schemaLooselyHasConstraint: require('./schema-loosely-has-constraint'),
   schemaRequiresProperty: require('./schema-requires-property'),
+  ...require('./spectral-context-utils'),
   validateComposedSchemas: require('./validate-composed-schemas'),
   validateNestedSchemas: require('./validate-nested-schemas'),
   validateSubschemas: require('./validate-subschemas'),

packages/utilities/src/utils/spectral-context-utils.js

@@ -0,0 +1,40 @@
+/**
+ * Copyright 2025 IBM Corporation.
+ * SPDX-License-Identifier: Apache2.0
+ */
+
+/**
+ * Returns the programmatic representation of an OpenAPI document, stored in the
+ * Spectral-created "context" object, with all non-circular references resolved.
+ * @param {object} context passed as an argument to Spectral-based rule functions
+ * @returns {object} the resolved version of an OpenAPI document
+ */
+function getResolvedSpec(context) {
+  return context.documentInventory.resolved;
+}
+
+/**
+ * Returns the programmatic representation of an OpenAPI document, stored in
+ * the Spectral-created "context" object, with all references still intact.
+ * @param {object} context passed as an argument to Spectral-based rule functions
+ * @returns {object} the unresolved version of an OpenAPI document
+ */
+function getUnresolvedSpec(context) {
+  return context.document.parserResult.data;
+}
+
+/**
+ * Returns the graph nodes, with information about references and the locations
+ * they resolve to, that are computed by the Spectral resolver.
+ * @param {object} context passed as an argument to Spectral-based rule functions
+ * @returns {object} the graph nodes
+ */
+function getNodes(context) {
+  return context.documentInventory.graph.nodes;
+}
+
+module.exports = {
+  getNodes,
+  getResolvedSpec,
+  getUnresolvedSpec,
+};

packages/utilities/test/spectral-context-utils.test.js

@@ -0,0 +1,42 @@
+/**
+ * Copyright 2025 IBM Corporation.
+ * SPDX-License-Identifier: Apache2.0
+ */
+
+const { getNodes, getResolvedSpec, getUnresolvedSpec } = require('../src');
+
+describe('Utility functions: Spectral Context Utils', () => {
+  const mockSpectralContextObject = {
+    documentInventory: {
+      resolved: 'resolved spec',
+      graph: {
+        nodes: 'graph nodes',
+      },
+    },
+    document: {
+      parserResult: {
+        data: 'unresolved spec',
+      },
+    },
+  };
+
+  describe('getNodes', () => {
+    it('should return graph nodes from context object', async () => {
+      expect(getNodes(mockSpectralContextObject)).toBe('graph nodes');
+    });
+  });
+
+  describe('getResolvedSpec', () => {
+    it('should return graph nodes from context object', async () => {
+      expect(getResolvedSpec(mockSpectralContextObject)).toBe('resolved spec');
+    });
+  });
+
+  describe('getUnresolvedSpec', () => {
+    it('should return graph nodes from context object', async () => {
+      expect(getUnresolvedSpec(mockSpectralContextObject)).toBe(
+        'unresolved spec'
+      );
+    });
+  });
+});