feat: add ref map to resolver graph node data

BREAKING CHANGE: resolver.graph node data is now an object that has `data` and `refMap`.

```ts
export interface IGraphNodeData {
   /**
   * A map of the refs in this node, and where they point
   *
   * Example:
   *
   * ```json
   * {
   *   "#/users/address": "file:///api.json/#models/address",
   * }
   * ```
   */
  refMap: Dictionary<string>;

  /**
  * This node's resolved data
  */
  data?: any;
}
```

Author: lottamus

package.json

@@ -45,8 +45,8 @@
   },
   "dependencies": {
     "@stoplight/json": "^3.1.2",
+    "@stoplight/types": "^11.1.1",
     "@stoplight/path": "^1.3.0",
-    "@stoplight/types": "^11.0.0",
     "@types/urijs": "1.x.x",
     "dependency-graph": "~0.8.0",
     "fast-memoize": "^2.5.1",

src/__tests__/resolver.spec.ts

@@ -1,8 +1,8 @@
 import * as fs from 'fs';
+import produce from 'immer';
 import * as _ from 'lodash';
 import * as URI from 'urijs';
 
-import produce from 'immer';
 import { Cache } from '../cache';
 import { Resolver } from '../resolver';
 import { defaultGetRef, ResolveRunner } from '../runner';
@@ -252,14 +252,14 @@ describe('resolver', () => {
       let resolved = await resolver.resolve(source);
       expect(resolved.result).toEqual(source);
 
-      source = produce(source, (next: any) => {
-        next.hello.$ref = true;
+      source = produce(source, (draft: any) => {
+        draft.hello.$ref = true;
       });
       resolved = await resolver.resolve(source);
       expect(resolved.result).toEqual(source);
 
-      source = produce(source, (next: any) => {
-        next.hello.$ref = 1;
+      source = produce(source, (draft: any) => {
+        draft.hello.$ref = 1;
       });
       resolved = await resolver.resolve(source);
       expect(resolved.result).toEqual(source);
@@ -880,9 +880,12 @@ describe('resolver', () => {
 
       const resolver = new Resolver();
       const resolved = await resolver.resolve(source);
-      expect(resolved.refMap).toEqual({
+      const refMap: any = {
         '#/hello': '#/word',
-      });
+      };
+
+      expect(resolved.refMap).toEqual(refMap);
+      expect(resolved.graph.getNodeData('root').refMap).toEqual(refMap);
     });
 
     test('should point to its original target', async () => {
@@ -898,11 +901,14 @@ describe('resolver', () => {
 
       const resolver = new Resolver();
       const resolved = await resolver.resolve(source);
-      expect(resolved.refMap).toEqual({
+      const refMap: any = {
         // word1, not word2 (which is what it ultimately resolves to)
         '#/hello': '#/word1',
         '#/word1': '#/word2',
-      });
+      };
+
+      expect(resolved.refMap).toEqual(refMap);
+      expect(resolved.graph.getNodeData('root').refMap).toEqual(refMap);
     });
 
     test('should handle remote authorities', async () => {
@@ -949,13 +955,15 @@ describe('resolver', () => {
       });
 
       const resolved = await resolver.resolve(source);
-
-      expect(resolved.refMap).toEqual({
+      const refMap: any = {
         '#/inner/data': 'custom://obj1/',
         '#/inner/dataInner': 'custom://obj1/#/inner/foo',
         '#/inner/dataInner2': '#/data2',
         '#/data2': 'custom://ob2/#/two',
-      });
+      };
+
+      expect(resolved.refMap).toEqual(refMap);
+      expect(resolved.graph.getNodeData('root').refMap).toEqual(refMap);
     });
   });
 

src/crawler.ts

@@ -14,10 +14,8 @@ export class ResolveCrawler implements Types.ICrawler {
   // to properly calculate the resolve target
   public jsonPointer?: string;
 
-  // @ts-ignore
   public readonly pointerGraph = new DepGraph<string>({ circular: true });
 
-  // @ts-ignore
   public readonly pointerStemGraph = new DepGraph<string>({ circular: true });
 
   private _runner: Types.IResolveRunner;
@@ -146,7 +144,7 @@ export class ResolveCrawler implements Types.ICrawler {
         }
 
         const targetRef = `${this._runner.baseUri.toString()}${targetPointer}`;
-        if (!this._runner.graph.hasNode(targetRef)) this._runner.graph.addNode(targetRef);
+        if (!this._runner.graph.hasNode(targetRef)) this._runner.graph.addNode(targetRef, { refMap: {} });
         if (this._runner.root !== targetRef) this._runner.graph.addDependency(this._runner.root, targetRef);
 
         // register parent as a dependant of the target
@@ -166,7 +164,7 @@ export class ResolveCrawler implements Types.ICrawler {
     } else {
       // remote pointer
       const remoteRef = ref.toString();
-      if (!this._runner.graph.hasNode(remoteRef)) this._runner.graph.addNode(remoteRef);
+      if (!this._runner.graph.hasNode(remoteRef)) this._runner.graph.addNode(remoteRef, { refMap: {} });
       if (this._runner.root !== remoteRef) this._runner.graph.addDependency(this._runner.root, remoteRef);
 
       if (this._runner.dereferenceRemote && !this._runner.atMaxUriDepth()) {

src/runner.ts

@@ -24,7 +24,7 @@ export class ResolveRunner implements Types.IResolveRunner {
   public readonly id: number;
   public readonly baseUri: uri.URI;
   public readonly uriCache: Types.ICache;
-  public readonly graph: DepGraph<any>;
+  public readonly graph: Types.IResolveRunner['graph'];
   public readonly root: string;
 
   public depth: number;
@@ -70,7 +70,7 @@ export class ResolveRunner implements Types.IResolveRunner {
 
     this.graph = graph;
     if (!this.graph.hasNode(this.root)) {
-      this.graph.addNode(this.root);
+      this.graph.addNode(this.root, { refMap: {}, data: this._source });
     }
 
     if (this.baseUri && this.depth === 0) {
@@ -159,8 +159,11 @@ export class ResolveRunner implements Types.IResolveRunner {
         // if not, we should set on our targetPath
         if (!resolvedTargetPath.length) resolvedTargetPath = targetPath || [];
 
+        // refMap deprecated, use graph
         resolved.refMap[String(this.baseUri.clone().fragment(pathToPointer(resolvedTargetPath)))] = String(r.uri);
 
+        this._setGraphNodeEdge(String(this.root), pathToPointer(resolvedTargetPath), String(r.uri));
+
         if (r.error) {
           resolved.errors.push(r.error);
         }
@@ -180,9 +183,7 @@ export class ResolveRunner implements Types.IResolveRunner {
             } else {
               set(draft, resolvedTargetPath, r.resolved.result);
 
-              if (this.graph.hasNode(String(r.uri))) {
-                this.graph.setNodeData(String(r.uri), r.resolved.result);
-              }
+              this._setGraphNodeData(String(r.uri), r.resolved.result);
             }
           }
         });
@@ -223,14 +224,15 @@ export class ResolveRunner implements Types.IResolveRunner {
                 // TODO: we might want to track and expose these circulars in the future?
                 if (isCircular) continue;
 
+                // refMap deprecated, use graph
                 resolved.refMap[pathToPointer(dependantPath)] = pathToPointer(pointerPath);
 
+                this._setGraphNodeEdge(this.root, pathToPointer(dependantPath), pathToPointer(pointerPath));
+
                 if (val !== void 0) {
                   set(draft, dependantPath, val);
 
-                  if (this.graph.hasNode(pathToPointer(pointerPath))) {
-                    this.graph.setNodeData(pathToPointer(pointerPath), original(val));
-                  }
+                  this._setGraphNodeData(pathToPointer(pointerPath), original(val));
                 } else {
                   resolved.errors.push({
                     code: 'POINTER_MISSING',
@@ -289,6 +291,8 @@ export class ResolveRunner implements Types.IResolveRunner {
       }
     }
 
+    this._setGraphNodeData(this.root, this._source);
+
     return resolved;
   }
 
@@ -535,4 +539,24 @@ export class ResolveRunner implements Types.IResolveRunner {
 
     return false;
   }
+
+  private _setGraphNodeData(nodeId: string, data: any) {
+    if (!this.graph.hasNode(nodeId)) return;
+
+    const graphNodeData = this.graph.getNodeData(nodeId) || {};
+    graphNodeData.data = data;
+
+    this.graph.setNodeData(nodeId, graphNodeData);
+  }
+
+  private _setGraphNodeEdge(nodeId: string, fromPointer: string, toNodeId: string) {
+    if (!this.graph.hasNode(nodeId)) return;
+
+    const graphNodeData = this.graph.getNodeData(nodeId) || {};
+    graphNodeData.refMap = graphNodeData.refMap || {};
+
+    graphNodeData.refMap[fromPointer] = toNodeId;
+
+    this.graph.setNodeData(nodeId, graphNodeData);
+  }
 }

src/types.ts

@@ -1,4 +1,4 @@
-import { Segment } from '@stoplight/types';
+import { Dictionary, Segment } from '@stoplight/types';
 import { DepGraph } from 'dependency-graph';
 
 /**
@@ -113,7 +113,7 @@ export interface IResolveResult {
    * A graph of every single reference in source.
    *
    */
-  graph: DepGraph<any>;
+  graph: DepGraph<IGraphNodeData>;
 
   /** Any errors that occured during the resolution process. */
   errors: IResolveError[];
@@ -222,6 +222,22 @@ export interface IRefHandlerOpts {
   parentPointer: string;
 }
 
+export interface IGraphNodeData {
+  /**
+   * A map of the refs in this node, and where they point
+   *
+   * Example:
+   *
+   * ```json
+   * {
+   *   "#/users/address": "file:///api.json/#models/card",
+   * }
+   * ```
+   */
+  refMap: Dictionary<string>;
+  data?: any;
+}
+
 export interface IResolveRunner {
   id: number;
   source: any;
@@ -231,7 +247,7 @@ export interface IResolveRunner {
   depth: number;
   baseUri: uri.URI;
 
-  graph: DepGraph<any>;
+  graph: DepGraph<IGraphNodeData>;
   root: string;
 
   atMaxUriDepth: () => boolean;