feat: add function to return pacakge purl

Co-authored-by: Jordan Harband <[email protected]>
Signed-off-by: Brian DeHamer <[email protected]>

README.md

@@ -45,6 +45,16 @@ included then the default is `latest`.
 
 **Throws** if the package name is invalid, a dist-tag is invalid or a URL's protocol is not supported.
 
+### var purl = npa.toPurl(*arg*, *reg*)
+
+Returns the [purl (package URL)](https://github.com/package-url/purl-spec) form of the given pacakge name/spec.
+
+* *arg* - A package/version string. For example: `[email protected]` or `@bar/[email protected]`.
+* *reg* - Optionally the URL to the package registry. If not specified, assumes the default
+`https://registry.npmjs.org`.
+
+**Throws** if the package name is invalid, or the supplied arg can't be resolved to a purl.
+
 ## RESULT OBJECT
 
 The objects that are returned by npm-package-arg contain the following

lib/npa.js

@@ -1,6 +1,7 @@
 'use strict'
 module.exports = npa
 module.exports.resolve = resolve
+module.exports.toPurl = toPurl
 module.exports.Result = Result
 
 const url = require('url')
@@ -87,6 +88,24 @@ function resolve (name, spec, where, arg) {
   }
 }
 
+const defaultRegistry = 'https://registry.npmjs.org'
+
+function toPurl (arg, reg = defaultRegistry) {
+  const res = npa(arg)
+
+  if (res.type !== 'version') {
+    throw invalidPurlType(res.type, res.raw)
+  }
+
+  // URI-encode leading @ of scoped packages
+  let purl = 'pkg:npm/' + res.name.replace(/^@/, '%40') + '@' + res.rawSpec
+  if (reg !== defaultRegistry) {
+    purl += '?repository_url=' + reg
+  }
+
+  return purl
+}
+
 function invalidPackageName (name, valid, raw) {
   // eslint-disable-next-line max-len
   const err = new Error(`Invalid package name "${name}" of package "${raw}": ${valid.errors.join('; ')}.`)
@@ -101,6 +120,13 @@ function invalidTagName (name, raw) {
   return err
 }
 
+function invalidPurlType (type, raw) {
+  // eslint-disable-next-line max-len
+  const err = new Error(`Invalid type "${type}" of package "${raw}": Purl can only be generated for "version" types.`)
+  err.code = 'EINVALIDPURLTYPE'
+  return err
+}
+
 function Result (opts) {
   this.type = opts.type
   this.registry = opts.registry

test/purl.js

@@ -0,0 +1,46 @@
+'use strict'
+var test = require('tap').test
+var npa = require('..')
+
+test('toPurl - valid', function (t) {
+  // Unscoped package
+  t.equal(npa.toPurl('[email protected]'), 'pkg:npm/[email protected]')
+
+  // Scoped package
+  t.equal(
+    npa.toPurl('@foo/[email protected]'),
+    'pkg:npm/%40foo/[email protected]')
+
+  // Non-default registry
+  t.equal(
+    npa.toPurl({ name: '@foo/bar', rawSpec: '1.0.0' }, 'https://npm.pkg.github.com'),
+    'pkg:npm/%40foo/[email protected]?repository_url=https://npm.pkg.github.com'
+  )
+
+  // Default registry
+  t.equal(
+    npa.toPurl({ name: '@foo/bar', rawSpec: '1.0.0' }, 'https://registry.npmjs.org'),
+    'pkg:npm/%40foo/[email protected]'
+  )
+
+  t.end()
+})
+
+test('toPurl - invalid', function (t) {
+  // Invalid version
+  t.throws(() => npa.toPurl({ name: 'foo/bar', rawSpec: '1.0.0' }), {
+    code: 'EINVALIDPACKAGENAME',
+  })
+
+  // Invalid version
+  t.throws(() => npa.toPurl('[email protected]'), {
+    code: 'EINVALIDPURLTYPE',
+  })
+
+  // Invalid type
+  t.throws(() => npa.toPurl('git+ssh://[email protected]/user/foo#1.2.3'), {
+    code: 'EINVALIDPURLTYPE',
+  })
+
+  t.end()
+})