npm-package-arg 12.0.2: Result, npa, npa.resolve

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/npm-package-arg@12.0.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/npm-package-arg@12.0.2
Demonstrate these symbols/APIs:
  - Result
  - npa
  - npa.resolve
  - npa.toPurl

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:fa7f3679ae5bdc9c91cec777da587daa3a99651931f23a21896eded8c17592a7","contract":["npa('@scope/pkg@1.2.3') returns an npa.Result with type 'version', registry true, scope '@scope', escapedName '@scope%2fpkg', fetchSpec '1.2.3', and saveSpec null","npa('widget@^2.1.0') and npa('widget') return type 'range' with fetchSpec '^2.1.0' and '*' respectively, while npa.resolve('widget', 'next') returns type 'tag'","npa('alias-pkg@npm:@scope/real-pkg@3.0.0') returns type 'alias' whose subSpec is a resolved Result for '@scope/real-pkg@3.0.0'","npa parses https:// tarball URLs as type 'remote', git+https:// URLs with #semver: and ::path: modifiers as type 'git' with gitRange and gitSubdir, and file:/relative paths as type 'directory' or 'file'","npa.toPurl('@scope/pkg@1.2.3') encodes the leading '@' as 'pkg:npm/%40scope/pkg@1.2.3', appends '?repository_url=...' for non-default registries, and throws EINVALIDPURLTYPE on non-version specs","invalid package names, non-URI-safe tag names without slashes, and unsupported URL protocols throw Errors with codes EINVALIDPACKAGENAME, EINVALIDTAGNAME, and EUNSUPPORTEDPROTOCOL"],"goal":"verify pkg:npm/npm-package-arg@12.0.2","kind":"HOW","packages":["pkg:npm/npm-package-arg@12.0.2"],"schemaVersion":1,"symbols":["Result","npa","npa.resolve","npa.toPurl"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/npm-package-arg@12.0.2"],"schemaVersion":1,"subject":"pkg:npm/npm-package-arg@12.0.2","symbols":["Result","npa","npa.resolve","npa.toPurl"],"verifierAdapter":"node-typescript@1"}

{
  "name": "verify-npm-package-arg",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "verify-npm-package-arg",
      "version": "1.0.0",
      "dependencies": {
        "npm-package-arg": "12.0.2"
      }
    },
    "node_modules/hosted-git-info": {
      "version": "8.1.0",
      "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-8.1.0.tgz",
      "integrity": "sha512-Rw/B2DNQaPBICNXEm8balFz9a6WpZrkCGpcWFpy7nCj+NyhSdqXipmfvtmWt9xGfp0wZnBxB+iVpLmQMYt47Tw==",
      "license": "ISC",
      "dependencies": {
        "lru-cache": "^10.0.1"
      },
      "engines": {
        "node": "^18.17.0 || >=20.5.0"
      }
    },
    "node_modules/lru-cache": {
      "version": "10.4.3",
      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz",
      "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
      "license": "ISC"
    },
    "node_modules/npm-package-arg": {
      "version": "12.0.2",
      "resolved": "https://registry.npmjs.org/npm-package-arg/-/npm-package-arg-12.0.2.tgz",
      "integrity": "sha512-f1NpFjNI9O4VbKMOlA5QoBq/vSQPORHcTZ2feJpFkTHJ9eQkdlmZEKSjcAhxTGInC7RlEyScT9ui67NaOsjFWA==",
      "license": "ISC",
      "dependencies": {
        "hosted-git-info": "^8.0.0",
        "proc-log": "^5.0.0",
        "semver": "^7.3.5",
        "validate-npm-package-name": "^6.0.0"
      },
      "engines": {
        "node": "^18.17.0 || >=20.5.0"
      }
    },
    "node_modules/proc-log": {
      "version": "5.0.0",
      "resolved": "https://registry.npmjs.org/proc-log/-/proc-log-5.0.0.tgz",
      "integrity": "sha512-Azwzvl90HaF0aCz1JrDdXQykFakSSNPaPoiZ9fm5qJIMHioDZEi7OAdRwSm6rSoPtY3Qutnm3L7ogmg3dc+wbQ==",
      "license": "ISC",
      "engines": {
        "node": "^18.17.0 || >=20.5.0"
      }
    },
    "node_modules/semver": {
      "version": "7.8.5",
      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
      "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
      "license": "ISC",
      "bin": {
        "semver": "bin/semver.js"
      },
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/validate-npm-package-name": {
      "version": "6.0.2",
      "resolved": "https://registry.npmjs.org/validate-npm-package-name/-/validate-npm-package-name-6.0.2.tgz",
      "integrity": "sha512-IUoow1YUtvoBBC06dXs8bR8B9vuA3aJfmQNKMoaPG/OFsPmoQvw8xh+6Ye25Gx9DQhoEom3Pcu9MKHerm/NpUQ==",
      "license": "ISC",
      "engines": {
        "node": "^18.17.0 || >=20.5.0"
      }
    }
  }
}

{
  "name": "verify-npm-package-arg",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "npm-package-arg": "12.0.2"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/npm-package-arg@12.0.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/npm-package-arg@12.0.2"
  ],
  "symbols": [
    "Result",
    "npa",
    "npa.resolve",
    "npa.toPurl"
  ]
}

import npa from 'npm-package-arg'

export function parseSpec(arg, where) {
  return npa(arg, where)
}

export function resolveSpec(name, spec, where) {
  return npa.resolve(name, spec, where)
}

export function specToPurl(arg, registryUrl) {
  return registryUrl ? npa.toPurl(arg, registryUrl) : npa.toPurl(arg)
}

export { npa }

import assert from 'node:assert/strict'
import { npa, parseSpec, resolveSpec, specToPurl } from '../src/index.mjs'

// 1. Scoped registry version spec
const scopedVer = parseSpec('@scope/pkg@1.2.3')
assert.equal(scopedVer instanceof npa.Result, true)
assert.equal(scopedVer.type, 'version')
assert.equal(scopedVer.registry, true)
assert.equal(scopedVer.name, '@scope/pkg')
assert.equal(scopedVer.scope, '@scope')
assert.equal(scopedVer.escapedName, '@scope%2fpkg')
assert.equal(scopedVer.rawSpec, '1.2.3')
assert.equal(scopedVer.fetchSpec, '1.2.3')
assert.equal(scopedVer.saveSpec, null)
assert.equal(scopedVer.toString(), '@scope/pkg@1.2.3')

// 2. Semver range and bare package name
const rangeSpec = parseSpec('widget@^2.1.0')
assert.equal(rangeSpec.type, 'range')
assert.equal(rangeSpec.registry, true)
assert.equal(rangeSpec.name, 'widget')
assert.equal(rangeSpec.fetchSpec, '^2.1.0')

const bareSpec = parseSpec('widget')
assert.equal(bareSpec.type, 'range')
assert.equal(bareSpec.rawSpec, '*')
assert.equal(bareSpec.fetchSpec, '*')

// 3. Dist-tag spec
const tagSpec = resolveSpec('widget', 'next')
assert.equal(tagSpec.type, 'tag')
assert.equal(tagSpec.registry, true)
assert.equal(tagSpec.name, 'widget')
assert.equal(tagSpec.fetchSpec, 'next')

// 4. Alias spec (npm: protocol)
const aliasSpec = parseSpec('alias-pkg@npm:@scope/real-pkg@3.0.0')
assert.equal(aliasSpec.type, 'alias')
assert.equal(aliasSpec.name, 'alias-pkg')
assert.equal(aliasSpec.registry, true)
assert.equal(aliasSpec.subSpec.type, 'version')
assert.equal(aliasSpec.subSpec.name, '@scope/real-pkg')
assert.equal(aliasSpec.subSpec.fetchSpec, '3.0.0')

// 5. Remote tarball URL and git URL with semver range + subdir
const remoteSpec = parseSpec('https://example.com/pkg-1.0.0.tgz')
assert.equal(remoteSpec.type, 'remote')
assert.equal(remoteSpec.fetchSpec, 'https://example.com/pkg-1.0.0.tgz')
assert.equal(remoteSpec.saveSpec, 'https://example.com/pkg-1.0.0.tgz')

const gitSpec = parseSpec('git+https://example.com/repo.git#semver:^1.0.0::path:packages/core')
assert.equal(gitSpec.type, 'git')
assert.equal(gitSpec.fetchSpec, 'https://example.com/repo.git')
assert.equal(gitSpec.gitRange, '^1.0.0')
assert.equal(gitSpec.gitSubdir, '/packages/core')
assert.equal(gitSpec.gitCommittish, undefined)

// 6. Local file and directory specs
const dirSpec = resolveSpec('local-mod', 'file:./packages/local-mod')
assert.equal(dirSpec.type, 'directory')
assert.equal(dirSpec.saveSpec, 'file:packages/local-mod')

const tgzSpec = resolveSpec('local-tgz', './archive.tgz')
assert.equal(tgzSpec.type, 'file')
assert.equal(tgzSpec.saveSpec, 'file:archive.tgz')

// 7. Package URL (PURL) generation and error codes
assert.equal(specToPurl('@scope/pkg@1.2.3'), 'pkg:npm/%40scope/pkg@1.2.3')
assert.equal(
  specToPurl('widget@1.0.0', 'https://example.com/npm'),
  'pkg:npm/widget@1.0.0?repository_url=https://example.com/npm'
)

assert.throws(
  () => specToPurl('widget@^1.0.0'),
  (err) => err.code === 'EINVALIDPURLTYPE'
)

assert.throws(
  () => resolveSpec('Invalid Name!', '1.0.0'),
  (err) => err.code === 'EINVALIDPACKAGENAME'
)

assert.throws(
  () => parseSpec('widget@invalid tag'),
  (err) => err.code === 'EINVALIDTAGNAME'
)

assert.throws(
  () => parseSpec('ftp://example.com/pkg.tgz'),
  (err) => err.code === 'EUNSUPPORTEDPROTOCOL'
)