@pnpm/resolving.tarball-url 1100.0.0 → 1101.0.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# @pnpm/resolving.tarball-url
+
+## 1101.0.0
+
+### Major Changes
+
+- The `registries` setting now declares a registry once, keyed by its URL, with everything about that registry in the entry: how it lays out tarball URLs, the scopes routed to it, and the bare-specifier prefix it answers to.
+
+  ```yaml
+  registries:
+    https://artifactory.example.com/artifactory/api/npm/npm-virtual/:
+      serverType: artifactory
+      scopes: ['@acme', '@acme-internal']
+      prefix: work
+  ```
+
+  - **`serverType`** tells pnpm how the registry lays out its tarball URLs, which decides whether a URL can be omitted from `pnpm-lock.yaml`:
+    - **undeclared** (the default) — strict. Only the exact canonical URL is treated as reconstructible.
+    - **`npm`** — the registry behaves like `registry.npmjs.org`, which also serves a scoped package from its percent-encoded path. Declare this for a faithful mirror or caching proxy of the public registry so its tarball URLs can be omitted too.
+    - **`artifactory`** — JFrog Artifactory repeats the scope in a scoped package's tarball filename (`@acme/widget/-/@acme/widget-1.0.0.tgz`) where the npm registry strips it (`@acme/widget/-/widget-1.0.0.tgz`). Declaring it lets pnpm rebuild that URL, so it is omitted from `pnpm-lock.yaml` instead of being written out for every scoped package [pnpm/get-npm-tarball-url#16](https://github.com/pnpm/get-npm-tarball-url/issues/16).
+  - **`scopes`** lists the `@`-prefixed scopes that resolve from this registry. A bare `'@'` is the scope-less default registry, the one the `registry` setting names.
+  - **`prefix`** is the alias a dependency addresses this registry by, as in `"foo": "work:^1.0.0"`.
+
+  The layout is never inferred from the registry URL, so nothing changes unless you declare it; `registry.npmjs.org` continues to behave as `npm` without being declared. Because the lockfile depends on `serverType`, it is read from `pnpm-workspace.yaml` only — a `serverType` in the global `config.yaml` is ignored, so one developer's machine cannot shape a lockfile their collaborators read back with a different layout. Credentials are rejected in this setting, in a key as well as in a field, and still belong in `.npmrc`. An entry that routes nothing to itself and matches no configured registry is reported as a warning rather than silently ignored.
+
+  ### Migrating
+
+  The older `registries` shape, a map of `<scope>: <url>` strings, still works and needs no change:
+
+  ```yaml
+  registries:
+    '@acme': https://npm.acme.example/
+  ```
+
+  `namedRegistries` is deprecated in favor of the `prefix` field, and is still read for prefixes `registries` does not declare.
+
+  `toLockfileResolution` and `isCanonicalRegistryTarballUrl` now take their registry and layout as an options object rather than positional arguments, so `@pnpm/lockfile.utils` and `@pnpm/resolving.tarball-url` get a major bump.
+
+### Patch Changes
+
+- Fixed `404` errors when installing from a registry that serves scoped packages only from a percent-encoded path, such as GitHub Enterprise Server. Outside `registry.npmjs.org`, a tarball URL that encodes the scope separator as `%2f` or `%2F` is no longer mistaken for one that pnpm can rebuild from the package name, version, and registry, so it is kept in `pnpm-lock.yaml` and requested verbatim on the next install [#13534](https://github.com/pnpm/pnpm/issues/13534).
+
+- Updated dependencies:
+  - @pnpm/types@1102.0.0
+
+## 1100.0.1
+
+### Patch Changes
+
+- Republished every package: the tarballs published by the v11.13.1 through v11.16.0 releases were missing most of their compiled files due to a packing bug [#13164](https://github.com/pnpm/pnpm/issues/13164).

package/lib/index.d.ts

@@ -1,12 +1,24 @@
+import type { RegistryServerType } from '@pnpm/types';
+export interface TarballUrlOptions {
+    registry?: string;
+    /**
+     * Undeclared by default, which is the strict reading: only the exact
+     * canonical URL is reconstructible. See {@link RegistryServerType}.
+     */
+    serverType?: RegistryServerType;
+}
 /**
  * Build the canonical tarball URL of an npm package — i.e. the URL pnpm derives
  * from a package's name, version, and registry. Vendored from the
  * `get-npm-tarball-url` package so the logic and its inverse
  * ({@link isCanonicalRegistryTarballUrl}) live together in the monorepo.
+ *
+ * This is the single source of the URL shape: the lockfile writer drops a
+ * tarball URL only when this function rebuilds it, and the lockfile reader
+ * rebuilds it with this function. Both sides therefore agree by construction,
+ * under every {@link RegistryServerType}.
  */
-export declare function getNpmTarballUrl(pkgName: string, pkgVersion: string, opts?: {
-    registry?: string;
-}): string;
+export declare function getNpmTarballUrl(pkgName: string, pkgVersion: string, opts?: TarballUrlOptions): string;
 /**
  * Whether `tarball` is the canonical npm registry URL derived from the package
  * name, version, and registry — i.e. it can be dropped from the lockfile and
@@ -20,10 +32,11 @@ export declare function getNpmTarballUrl(pkgName: string, pkgVersion: string, op
  * to `getNpmTarballUrl(name, version, { registry })` so nothing host-specific
  * is persisted to `pnpm-lock.yaml`.
  *
- * Percent-encoding is case-insensitive, so the `%2f` unescape matches both
- * `%2f` and `%2F` in the URLs npm produces for scoped packages.
+ * A `serverType` the user declared (via `getRegistryServerType` in
+ * `@pnpm/config.normalize-registries`) wins; otherwise the built-in layout of
+ * a known registry applies, and an unknown registry is read strictly.
  */
 export declare function isCanonicalRegistryTarballUrl(tarball: string, pkg: {
     name: string;
     version: string;
-}, registry: string): boolean;
+}, opts: TarballUrlOptions): boolean;

package/lib/index.js

@@ -1,13 +1,29 @@
+const PUBLIC_NPM_REGISTRY = 'https://registry.npmjs.org/';
+/**
+ * registry.npmjs.org is the one registry whose layout pnpm knows without being
+ * told, so it is a row of data rather than a hostname comparison. A declared
+ * `serverType` wins over it.
+ */
+const DEFAULT_REGISTRY_SERVER_TYPES = {
+    [PUBLIC_NPM_REGISTRY]: 'npm',
+};
 /**
  * Build the canonical tarball URL of an npm package — i.e. the URL pnpm derives
  * from a package's name, version, and registry. Vendored from the
  * `get-npm-tarball-url` package so the logic and its inverse
  * ({@link isCanonicalRegistryTarballUrl}) live together in the monorepo.
+ *
+ * This is the single source of the URL shape: the lockfile writer drops a
+ * tarball URL only when this function rebuilds it, and the lockfile reader
+ * rebuilds it with this function. Both sides therefore agree by construction,
+ * under every {@link RegistryServerType}.
  */
 export function getNpmTarballUrl(pkgName, pkgVersion, opts) {
     const registry = normalizeRegistry(opts?.registry);
-    const scopelessName = getScopelessName(pkgName);
-    return `${registry}${pkgName}/-/${scopelessName}-${removeBuildMetadataFromVersion(pkgVersion)}.tgz`;
+    // Artifactory keeps the scope in the filename of a scoped package's tarball
+    // (`@acme/widget/-/@acme/widget-1.0.0.tgz`); the npm layout strips it.
+    const filenameName = opts?.serverType === 'artifactory' ? pkgName : getScopelessName(pkgName);
+    return `${registry}${pkgName}/-/${filenameName}-${removeBuildMetadataFromVersion(pkgVersion)}.tgz`;
 }
 /**
  * Whether `tarball` is the canonical npm registry URL derived from the package
@@ -22,17 +38,27 @@ export function getNpmTarballUrl(pkgName, pkgVersion, opts) {
  * to `getNpmTarballUrl(name, version, { registry })` so nothing host-specific
  * is persisted to `pnpm-lock.yaml`.
  *
- * Percent-encoding is case-insensitive, so the `%2f` unescape matches both
- * `%2f` and `%2F` in the URLs npm produces for scoped packages.
+ * A `serverType` the user declared (via `getRegistryServerType` in
+ * `@pnpm/config.normalize-registries`) wins; otherwise the built-in layout of
+ * a known registry applies, and an unknown registry is read strictly.
  */
-export function isCanonicalRegistryTarballUrl(tarball, pkg, registry) {
-    const expectedTarball = getNpmTarballUrl(pkg.name, pkg.version, { registry });
-    const actualTarball = tarball.replace(/%2f/gi, '/');
-    return removeProtocol(expectedTarball) === removeProtocol(actualTarball);
+export function isCanonicalRegistryTarballUrl(tarball, pkg, opts) {
+    const expectedTarball = removeProtocol(getNpmTarballUrl(pkg.name, pkg.version, opts));
+    const actualTarball = removeProtocol(tarball);
+    if (expectedTarball === actualTarball)
+        return true;
+    // A registry behaving like registry.npmjs.org serves a scoped package from
+    // both the encoded and the unencoded path. A registry that has not been
+    // declared to behave like it may serve only the encoded one, so its URL is
+    // kept. See https://github.com/pnpm/pnpm/issues/13534.
+    return effectiveServerType(opts) === 'npm' && expectedTarball === actualTarball.replace(/%2f/gi, '/');
+}
+function effectiveServerType(opts) {
+    return opts.serverType ?? DEFAULT_REGISTRY_SERVER_TYPES[normalizeRegistry(opts.registry)];
 }
 function normalizeRegistry(registry) {
     if (!registry)
-        return 'https://registry.npmjs.org/';
+        return PUBLIC_NPM_REGISTRY;
     return registry.endsWith('/') ? registry : `${registry}/`;
 }
 function removeBuildMetadataFromVersion(version) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnpm/resolving.tarball-url",
-  "version": "1100.0.0",
+  "version": "1101.0.0",
   "description": "Build and recognize the canonical tarball URL of an npm package",
   "keywords": [
     "pnpm",
@@ -28,9 +28,12 @@
     "lib",
     "!*.map"
   ],
+  "dependencies": {
+    "@pnpm/types": "1102.0.0"
+  },
   "devDependencies": {
     "@jest/globals": "30.4.1",
-    "@pnpm/resolving.tarball-url": "1100.0.0"
+    "@pnpm/resolving.tarball-url": "1101.0.0"
   },
   "engines": {
     "node": ">=22.13"