npm-package-arg 12.0.2: 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 npm-package-arg.resolve in 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:
  - npm-package-arg.resolve

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:eb7c5fcacac7d487cd1ddec9abaa7ffdea60c6c937e450a368ada19d7d26de95","contract":["npa.resolve(name, spec) classifies exact semver as type 'version', ranges as 'range', and dist-tags as 'tag' with registry: true and saveSpec: null","npa.resolve('@scope/pkg', spec) populates scope ('@scope') and URL-escaped escapedName ('@scope%2fpkg')","npa.resolve(aliasName, 'npm:target@version') returns type 'alias' with subSpec containing the resolved target Result","npa.resolve(name, relativePath, where) resolves directory and .tgz file specs relative to where with 'file:' saveSpec and resolved fetchSpec","npa.resolve(name, 'https://example.com/pkg.tgz') returns type 'remote' with matching saveSpec and fetchSpec","npa.resolve throws EINVALIDPACKAGENAME for invalid package names and EINVALIDTAGNAME for characters that encodeURIComponent encodes"],"goal":"verify npm-package-arg.resolve in pkg:npm/npm-package-arg@12.0.2","kind":"HOW","packages":["pkg:npm/npm-package-arg@12.0.2"],"schemaVersion":1,"symbols":["npm-package-arg.resolve"]},"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":["npm-package-arg.resolve"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-npm-package-arg-resolve",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-npm-package-arg-resolve",
      "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": "sample-npm-package-arg-resolve",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "npm-package-arg": "12.0.2"
  },
  "scripts": {
    "test": "node test/contract.mjs"
  }
}

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

import npa from 'npm-package-arg'

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

import assert from 'node:assert/strict'
import path from 'node:path'
import npa from 'npm-package-arg'
import { resolveSpec } from '../src/index.mjs'

// 1. Exact version resolution from registry
const versionRes = resolveSpec('demo-pkg', '1.2.3')
assert.equal(versionRes.type, 'version')
assert.equal(versionRes.registry, true)
assert.equal(versionRes.name, 'demo-pkg')
assert.equal(versionRes.rawSpec, '1.2.3')
assert.equal(versionRes.fetchSpec, '1.2.3')
assert.equal(versionRes.saveSpec, null)
assert.equal(versionRes.raw, 'demo-pkg@1.2.3')

// 2. Scoped semver range resolution from registry
const rangeRes = npa.resolve('@scope/demo-pkg', '^2.0.0')
assert.equal(rangeRes.type, 'range')
assert.equal(rangeRes.registry, true)
assert.equal(rangeRes.name, '@scope/demo-pkg')
assert.equal(rangeRes.scope, '@scope')
assert.equal(rangeRes.escapedName, '@scope%2fdemo-pkg')
assert.equal(rangeRes.fetchSpec, '^2.0.0')
assert.equal(rangeRes.saveSpec, null)

// 3. Dist-tag resolution from registry
const tagRes = npa.resolve('demo-pkg', 'next')
assert.equal(tagRes.type, 'tag')
assert.equal(tagRes.registry, true)
assert.equal(tagRes.fetchSpec, 'next')
assert.equal(tagRes.saveSpec, null)

// 4. Alias resolution (npm: target)
const aliasRes = npa.resolve('aliased-pkg', 'npm:target-pkg@1.0.0')
assert.equal(aliasRes.type, 'alias')
assert.equal(aliasRes.registry, true)
assert.equal(aliasRes.name, 'aliased-pkg')
assert.equal(aliasRes.saveSpec, null)
assert.equal(aliasRes.fetchSpec, null)
assert.equal(aliasRes.subSpec.type, 'version')
assert.equal(aliasRes.subSpec.name, 'target-pkg')
assert.equal(aliasRes.subSpec.fetchSpec, '1.0.0')

// 5. Relative directory and tarball resolution against a base directory
const baseDir = process.cwd()
const dirRes = npa.resolve('local-dir-pkg', './packages/local-dir-pkg', baseDir)
assert.equal(dirRes.type, 'directory')
assert.equal(dirRes.name, 'local-dir-pkg')
assert.equal(dirRes.saveSpec, 'file:packages/local-dir-pkg')
assert.equal(dirRes.fetchSpec, path.resolve(baseDir, 'packages/local-dir-pkg'))

const fileRes = npa.resolve('local-tar-pkg', './archives/pkg.tgz', baseDir)
assert.equal(fileRes.type, 'file')
assert.equal(fileRes.name, 'local-tar-pkg')
assert.equal(fileRes.saveSpec, 'file:archives/pkg.tgz')
assert.equal(fileRes.fetchSpec, path.resolve(baseDir, 'archives/pkg.tgz'))

// 6. Remote tarball URL resolution
const remoteRes = npa.resolve('remote-pkg', 'https://example.com/pkg-1.0.0.tgz')
assert.equal(remoteRes.type, 'remote')
assert.equal(remoteRes.name, 'remote-pkg')
assert.equal(remoteRes.saveSpec, 'https://example.com/pkg-1.0.0.tgz')
assert.equal(remoteRes.fetchSpec, 'https://example.com/pkg-1.0.0.tgz')

// 7. Error cases: invalid package name and invalid tag name
assert.throws(
  () => npa.resolve('Invalid Package Name!', '1.0.0'),
  (err) => err && err.code === 'EINVALIDPACKAGENAME'
)
assert.throws(
  () => npa.resolve('demo-pkg', 'invalid?tag'),
  (err) => err && err.code === 'EINVALIDTAGNAME'
)