feat: add purl to PkgInfo

The validation hooks will make sure that the name and version in
the package URL also match the package's "actual" name and version.

Author: agatakrajewska

README.md

@@ -50,24 +50,29 @@ export interface DepGraph {
   readonly rootPkg: {
     name: string;
     version?: string;
+    purl?: string;
   };
   // all unique packages in the graph (including root package)
   getPkgs(): Array<{
     name: string;
     version?: string;
+    purl?: string;
   }>;
   // all unique packages in the graph, except the root package
   getDepPkgs(): Array<{
     name: string;
     version?: string;
+    purl?: string;
   }>;
   pkgPathsToRoot(pkg: Pkg): Array<Array<{
     name: string;
     version?: string;
+    purl?: string;
   }>>;
   directDepsLeadingTo(pkg: Pkg): Array<{
     name: string;
     version?: string;
+    purl?: string;
   }>;
   countPathsToRoot(pkg: Pkg): number;
   toJSON(): DepGraphData;
@@ -94,6 +99,7 @@ export interface DepGraphData {
     info: {
       name: string;
       version?: string;
+    purl?: string;
     };
   }>;
   graph: {

package.json

@@ -64,6 +64,7 @@
     "lodash.union": "^4.6.0",
     "lodash.values": "^4.3.0",
     "object-hash": "^3.0.0",
+    "packageurl-js": "^1.0.0",
     "semver": "^7.0.0",
     "tslib": "^2"
   }

src/core/builder.ts

@@ -1,6 +1,7 @@
 import * as graphlib from '../graphlib';
 import * as types from './types';
 import { DepGraphImpl } from './dep-graph';
+import { validatePackageURL } from './validate-graph';
 
 export { DepGraphBuilder };
 
@@ -60,6 +61,8 @@ class DepGraphBuilder {
       throw new Error('DepGraphBuilder.addPkgNode() cant override root node');
     }
 
+    validatePackageURL(pkgInfo);
+
     const pkgId = DepGraphBuilder._getPkgId(pkgInfo);
 
     this._pkgs[pkgId] = pkgInfo;

src/core/dep-graph.ts

@@ -13,7 +13,7 @@ interface GraphNode {
 }
 
 class DepGraphImpl implements types.DepGraphInternal {
-  public static SCHEMA_VERSION = '1.2.0';
+  public static SCHEMA_VERSION = '1.3.0';
 
   public static getPkgId(pkg: types.Pkg): string {
     return `${pkg.name}@${pkg.version || ''}`;

src/core/types.ts

@@ -8,9 +8,13 @@ export interface Pkg {
   version?: string;
 }
 
+export type PurlString = string;
+
 export interface PkgInfo {
   name: string;
   version?: string;
+  purl?: PurlString;
+
   // NOTE: consider adding in the future
   // requires?: {
   //   name: string;

src/core/validate-graph.ts

@@ -1,4 +1,6 @@
 import * as graphlib from '../graphlib';
+import { PackageURL } from 'packageurl-js';
+import * as types from './types';
 import { ValidationError } from './errors';
 
 function assert(condition: boolean, msg: string) {
@@ -30,4 +32,45 @@ export function validateGraph(
     (pkgId) => !pkgNodes[pkgId] || pkgNodes[pkgId].size === 0,
   );
   assert(pkgsWithoutInstances.length === 0, 'not all pkgs have instance nodes');
+
+  for (const pkgId in pkgs) {
+    try {
+      validatePackageURL(pkgs[pkgId] as types.PkgInfo);
+    } catch (e) {
+      throw new ValidationError(`invalid pkg ${pkgId}: ${e}`);
+    }
+  }
+}
+
+export function validatePackageURL(pkg: types.PkgInfo): void {
+  if (!pkg.purl) {
+    return;
+  }
+
+  try {
+    const purlPkg = PackageURL.fromString(pkg.purl);
+
+    switch (purlPkg.type) {
+      // Within Snyk, maven packages use <namespace>:<name> as their *name*, but
+      // we expect those to be separated correctly in the PackageURL.
+      case 'maven':
+        assert(
+          pkg.name === purlPkg.namespace + ':' + purlPkg.name,
+          `name and packageURL name do not match`,
+        );
+        break;
+
+      default:
+        assert(
+          pkg.name === purlPkg.name,
+          `name and packageURL name do not match`,
+        );
+    }
+    assert(
+      pkg.version === purlPkg.version,
+      `version and packageURL version do not match`,
+    );
+  } catch (e) {
+    throw new ValidationError(`packageURL validation failed: ${e}`);
+  }
 }

test/core/__snapshots__/filter-from-graph.test.ts.snap

@@ -7310,7 +7310,7 @@ Object {
       },
     },
   ],
-  "schemaVersion": "1.2.0",
+  "schemaVersion": Any<String>,
 }
 `;
 
@@ -14624,7 +14624,7 @@ Object {
       },
     },
   ],
-  "schemaVersion": "1.2.0",
+  "schemaVersion": Any<String>,
 }
 `;
 
@@ -21938,7 +21938,7 @@ Object {
       },
     },
   ],
-  "schemaVersion": "1.2.0",
+  "schemaVersion": Any<String>,
 }
 `;
 
@@ -21966,7 +21966,7 @@ Object {
       },
     },
   ],
-  "schemaVersion": "1.2.0",
+  "schemaVersion": Any<String>,
 }
 `;
 
@@ -29262,7 +29262,7 @@ Object {
       },
     },
   ],
-  "schemaVersion": "1.2.0",
+  "schemaVersion": Any<String>,
 }
 `;
 
@@ -36558,6 +36558,6 @@ Object {
       },
     },
   ],
-  "schemaVersion": "1.2.0",
+  "schemaVersion": Any<String>,
 }
 `;

test/core/builder.test.ts

@@ -1,4 +1,5 @@
 import { DepGraphBuilder } from '../../src';
+import { ValidationError } from '../../src/core/errors';
 
 describe('builder', () => {
   let builder;
@@ -35,6 +36,89 @@ describe('builder', () => {
         );
       expect(packageAdded).toBeDefined();
     });
+
+    it('should throw error if invalid package URL is defined', () => {
+      const pkgToAdd = {
+        name: 'json',
+        version: '1.0.0',
+        purl: 'this-is:not/a-/purl',
+      };
+      expect(() => {
+        builder.addPkgNode(pkgToAdd, pkgToAdd.name);
+      }).toThrow(ValidationError);
+    });
+    it('should throw error if package URL defines different name', () => {
+      const pkgToAdd = {
+        name: 'json',
+        version: '1.0.0',
+        purl: 'pkg:rpm/[email protected]',
+      };
+      expect(() => {
+        builder.addPkgNode(pkgToAdd, pkgToAdd.name);
+      }).toThrow(ValidationError);
+    });
+    it('should throw error if package URL defines different version', () => {
+      const pkgToAdd = {
+        name: 'json',
+        version: '1.0.0',
+        purl: 'pkg:rpm/[email protected]',
+      };
+      expect(() => {
+        builder.addPkgNode(pkgToAdd, pkgToAdd.name);
+      }).toThrow(ValidationError);
+    });
+    it('successfully adds package with package URL', () => {
+      const pkgToAdd = {
+        name: 'json',
+        version: '1.0.0',
+        purl: 'pkg:rpm/rhel/[email protected]?repositories=a,b,c',
+      };
+      builder.addPkgNode(pkgToAdd, pkgToAdd.name);
+      const packageAdded = builder
+        .getPkgs()
+        .find(
+          (pkg) =>
+            pkg.name === pkgToAdd.name && pkg.version === pkgToAdd.version,
+        );
+      expect(packageAdded).toEqual(pkgToAdd);
+    });
+    it('successfully handles maven special case', () => {
+      const pkgToAdd = {
+        name: 'com.namespace:foo',
+        version: '1.0.0',
+        purl: 'pkg:maven/com.namespace/[email protected]',
+      };
+      builder.addPkgNode(pkgToAdd, pkgToAdd.name);
+      const packageAdded = builder
+        .getPkgs()
+        .find(
+          (pkg) =>
+            pkg.name === pkgToAdd.name && pkg.version === pkgToAdd.version,
+        );
+      expect(packageAdded).toEqual(pkgToAdd);
+    });
+    it('fails on missing group id on maven package', () => {
+      // the groupId in maven is the namespace in purl.
+      const pkgToAdd = {
+        name: 'foo',
+        version: '1.0.0',
+        purl: 'pkg:maven/com.namespace/[email protected]',
+      };
+      expect(() => {
+        builder.addPkgNode(pkgToAdd, pkgToAdd.name);
+      }).toThrow(ValidationError);
+    });
+    it('fails on different group id on maven package', () => {
+      // the groupId in maven is the namespace in purl.
+      const pkgToAdd = {
+        name: 'com.namespace:foo',
+        version: '1.0.0',
+        purl: 'pkg:maven/com.other/[email protected]',
+      };
+      expect(() => {
+        builder.addPkgNode(pkgToAdd, pkgToAdd.name);
+      }).toThrow(ValidationError);
+    });
   });
 
   describe('when using connectDep', () => {

test/core/equals.test.ts

@@ -125,4 +125,18 @@ describe('equals', () => {
     expect(a.equals(b, { compareRoot: false })).toBe(true);
     expect(b.equals(a, { compareRoot: false })).toBe(true);
   });
+
+  test('same graphs with different minor schema version', async () => {
+    const a = depGraphLib.createFromJSON({
+      ...helpers.loadFixture('equals/simple.json'),
+      schemaVersion: '1.2.0',
+    });
+    const b = depGraphLib.createFromJSON({
+      ...helpers.loadFixture('equals/simple.json'),
+      schemaVersion: '1.3.0',
+    });
+
+    expect(a.equals(b)).toBe(true);
+    expect(b.equals(a)).toBe(true);
+  });
 });

test/core/filter-from-graph.test.ts

@@ -36,7 +36,9 @@ describe('filter-from-graph', function () {
         depGraph.getDepPkgs().length - 1,
       );
 
-      expect(result).toMatchSnapshot();
+      expect(result.toJSON()).toMatchSnapshot({
+        schemaVersion: expect.any(String),
+      });
     });
 
     it('should not mutate original depGraph', async () => {
@@ -70,15 +72,19 @@ describe('filter-from-graph', function () {
       expect(result.getDepPkgs().length).toEqual(
         depGraph.getDepPkgs().length - pkgs.length,
       );
-      expect(result).toMatchSnapshot();
+      expect(result.toJSON()).toMatchSnapshot({
+        schemaVersion: expect.any(String),
+      });
     });
 
     it('should return an empty graph', async () => {
       const pkgs = depGraph.getDepPkgs();
       const result = await filterPackagesFromGraph(depGraph, pkgs);
 
       expect(result.getDepPkgs().length).toBe(0);
-      expect(result).toMatchSnapshot();
+      expect(result.toJSON()).toMatchSnapshot({
+        schemaVersion: expect.any(String),
+      });
     });
   });
 });

test/legacy/__snapshots__/from-dep-tree.test.ts.snap

@@ -140,7 +140,7 @@ Object {
       },
     },
   ],
-  "schemaVersion": "1.2.0",
+  "schemaVersion": Any<String>,
 }
 `;
 
@@ -659,7 +659,7 @@ Object {
       },
     },
   ],
-  "schemaVersion": "1.2.0",
+  "schemaVersion": Any<String>,
 }
 `;
 
@@ -7988,6 +7988,6 @@ Object {
       },
     },
   ],
-  "schemaVersion": "1.2.0",
+  "schemaVersion": Any<String>,
 }
 `;