feat: implement catalog protocol reads (feature flagged)

catalogs/protocol-parser/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @pnpm/catalogs.protocol-parser
+
+## 0.1.0
+
+Initial release

catalogs/protocol-parser/README.md

@@ -0,0 +1,3 @@
+# @pnpm/catalogs.protocol-parser
+
+> Parse catalog protocol specifiers and return the catalog name.

catalogs/protocol-parser/jest.config.js

@@ -0,0 +1 @@
+module.exports = require('../../jest.config.js')

catalogs/protocol-parser/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@pnpm/catalogs.protocol-parser",
+  "version": "0.1.0",
+  "description": "Parse catalog protocol specifiers and return the catalog name.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "engines": {
+    "node": ">=18.12"
+  },
+  "files": [
+    "lib",
+    "!*.map"
+  ],
+  "repository": "https://github.com/pnpm/pnpm/blob/main/catalogs/protocol-parser",
+  "keywords": [
+    "pnpm9",
+    "pnpm",
+    "types"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/pnpm/pnpm/issues"
+  },
+  "homepage": "https://github.com/pnpm/pnpm/blob/main/catalogs/protocol-parser#readme",
+  "scripts": {
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "compile": "tsc --build && pnpm run lint --fix",
+    "prepublishOnly": "pnpm run compile",
+    "test": "pnpm run compile && pnpm run _test",
+    "_test": "jest"
+  },
+  "funding": "https://opencollective.com/pnpm",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "devDependencies": {
+    "@pnpm/catalogs.protocol-parser": "workspace:*"
+  }
+}

catalogs/protocol-parser/src/index.ts

@@ -0,0 +1 @@
+export { parseCatalogProtocol } from './parseCatalogProtocol'

catalogs/protocol-parser/src/parseCatalogProtocol.ts

@@ -0,0 +1,18 @@
+const CATALOG_PROTOCOL = 'catalog:'
+
+/**
+ * Parse a package.json dependency specifier using the catalog: protocol.
+ * Returns null if the given specifier does not start with 'catalog:'.
+ */
+export function parseCatalogProtocol (pref: string): string | 'default' | null {
+  if (!pref.startsWith(CATALOG_PROTOCOL)) {
+    return null
+  }
+
+  const catalogNameRaw = pref.slice(CATALOG_PROTOCOL.length).trim()
+
+  // Allow a specifier of 'catalog:' to be a short-hand for 'catalog:default'.
+  const catalogNameNormalized = catalogNameRaw === '' ? 'default' : catalogNameRaw
+
+  return catalogNameNormalized
+}

catalogs/protocol-parser/test/parseCatalogProtocol.test.ts

@@ -0,0 +1,20 @@
+import { parseCatalogProtocol } from '@pnpm/catalogs.protocol-parser'
+
+test('parses named catalog', () => {
+  expect(parseCatalogProtocol('catalog:foo')).toBe('foo')
+  expect(parseCatalogProtocol('catalog:bar')).toBe('bar')
+})
+
+test('returns null for specifier not using catalog protocol', () => {
+  expect(parseCatalogProtocol('^1.0.0')).toBe(null)
+})
+
+describe('default catalog', () => {
+  test('parses explicit default catalog', () => {
+    expect(parseCatalogProtocol('catalog:default')).toBe('default')
+  })
+
+  test('parses implicit catalog', () => {
+    expect(parseCatalogProtocol('catalog:')).toBe('default')
+  })
+})

catalogs/protocol-parser/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "@pnpm/tsconfig",
+  "composite": true,
+  "compilerOptions": {
+    "outDir": "lib",
+    "rootDir": "src"
+  },
+  "include": [
+    "src/**/*.ts",
+    "../../__typings__/**/*.d.ts"
+  ],
+  "references": []
+}

catalogs/protocol-parser/tsconfig.lint.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts",
+    "../../__typings__/**/*.d.ts"
+  ]
+}

catalogs/types/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @pnpm/catalogs.types
+
+## 0.1.0
+
+Initial release

catalogs/types/README.md

@@ -0,0 +1,3 @@
+# @pnpm/catalogs.types
+
+> Types related to the pnpm catalogs feature.

catalogs/types/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pnpm/catalogs.types",
+  "version": "0.1.0",
+  "description": "Types related to the pnpm catalogs feature.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "engines": {
+    "node": ">=18.12"
+  },
+  "files": [
+    "lib",
+    "!*.map"
+  ],
+  "repository": "https://github.com/pnpm/pnpm/blob/main/catalogs/types",
+  "keywords": [
+    "pnpm9",
+    "pnpm",
+    "types"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/pnpm/pnpm/issues"
+  },
+  "homepage": "https://github.com/pnpm/pnpm/blob/main/catalogs/types#readme",
+  "scripts": {
+    "lint": "eslint \"src/**/*.ts\"",
+    "compile": "tsc --build && pnpm run lint --fix",
+    "prepublishOnly": "pnpm run compile",
+    "test": "pnpm run compile"
+  },
+  "funding": "https://opencollective.com/pnpm",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "devDependencies": {
+    "@pnpm/catalogs.types": "workspace:*"
+  }
+}

catalogs/types/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Catalogs parsed from the pnpm-workspace.yaml file.
+ *
+ * https://github.com/pnpm/rfcs/pull/1
+ */
+export interface Catalogs {
+  /**
+   * The default catalog.
+   *
+   * The default catalog can be defined in 2 ways.
+   *
+   *   1. Users can specify a top-level "catalog" field or,
+   *   2. An explicitly named "default" catalog under the "catalogs" map.
+   *
+   * This field contains either definition. Note that it's an error to define
+   * the default catalog using both options. The parser will fail when reading
+   * the workspace manifest.
+   */
+  readonly default?: Catalog
+
+  /**
+   * Named catalogs.
+   */
+  readonly [catalogName: string]: Catalog | undefined
+}
+
+export interface Catalog {
+  readonly [dependencyName: string]: string | undefined
+}

catalogs/types/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "@pnpm/tsconfig",
+  "composite": true,
+  "compilerOptions": {
+    "outDir": "lib",
+    "rootDir": "src"
+  },
+  "include": [
+    "src/**/*.ts",
+    "../../__typings__/**/*.d.ts"
+  ],
+  "references": []
+}

catalogs/types/tsconfig.lint.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts",
+    "../../__typings__/**/*.d.ts"
+  ]
+}

lockfile/lockfile-file/src/lockfileFormatConverters.ts

@@ -113,6 +113,9 @@ function normalizeLockfile (lockfile: InlineSpecifiersLockfile, opts: NormalizeL
   if (lockfileToSave.time) {
     lockfileToSave.time = pruneTimeInLockfileV6(lockfileToSave.time, lockfile.importers ?? {})
   }
+  if ((lockfileToSave.catalogs != null) && isEmpty(lockfileToSave.catalogs)) {
+    delete lockfileToSave.catalogs
+  }
   if ((lockfileToSave.overrides != null) && isEmpty(lockfileToSave.overrides)) {
     delete lockfileToSave.overrides
   }

lockfile/lockfile-file/src/sortLockfileKeys.ts

@@ -35,6 +35,7 @@ type RootKey = keyof LockfileFile
 const ROOT_KEYS: readonly RootKey[] = [
   'lockfileVersion',
   'settings',
+  'catalogs',
   'overrides',
   'packageExtensionsChecksum',
   'pnpmfileChecksum',
@@ -86,6 +87,15 @@ export function sortLockfileKeys (lockfile: LockfileFileV9): LockfileFileV9 {
       })
     }
   }
+  if (lockfile.catalogs != null) {
+    lockfile.catalogs = sortKeys(lockfile.catalogs)
+    for (const [catalogName, catalog] of Object.entries(lockfile.catalogs)) {
+      lockfile.catalogs[catalogName] = sortKeys(catalog, {
+        compare: lexCompare,
+        deep: true,
+      })
+    }
+  }
   for (const key of ['dependencies', 'devDependencies', 'optionalDependencies', 'time', 'patchedDependencies'] as const) {
     if (!lockfile[key]) continue
     lockfile[key] = sortKeys<any>(lockfile[key]) // eslint-disable-line @typescript-eslint/no-explicit-any

lockfile/lockfile-types/src/index.ts

@@ -13,6 +13,7 @@ export interface Lockfile {
   importers: Record<string, ProjectSnapshot>
   lockfileVersion: string
   time?: Record<string, string>
+  catalogs?: CatalogSnapshots
   packages?: PackageSnapshots
   overrides?: Record<string, string>
   packageExtensionsChecksum?: string
@@ -135,3 +136,24 @@ export type PackageBin = string | { [name: string]: string }
  * }
  */
 export type ResolvedDependencies = Record<string, string>
+
+export interface CatalogSnapshots {
+  [catalogName: string]: { [dependencyName: string]: ResolvedCatalogEntry }
+}
+
+export interface ResolvedCatalogEntry {
+  /**
+   * The real specifier that should be used for this dependency's catalog entry.
+   * This would be the ^1.2.3 portion of:
+   *
+   * @example
+   * catalog:
+   *   foo: ^1.2.3
+   */
+  readonly specifier: string
+
+  /**
+   * The concrete version that the requested specifier resolved to. Ex: 1.2.3
+   */
+  readonly version: string
+}

pkg-manager/core/package.json

@@ -19,6 +19,8 @@
     "@pnpm/build-modules": "workspace:*",
     "@pnpm/builder.policy": "3.0.0",
     "@pnpm/calc-dep-state": "workspace:*",
+    "@pnpm/catalogs.protocol-parser": "workspace:*",
+    "@pnpm/catalogs.types": "workspace:*",
     "@pnpm/constants": "workspace:*",
     "@pnpm/core-loggers": "workspace:*",
     "@pnpm/crypto.base32-hash": "workspace:*",

pkg-manager/core/src/getPeerDependencyIssues.ts

@@ -55,6 +55,7 @@ export async function getPeerDependencyIssues (
   } = await resolveDependencies(
     projectsToResolve,
     {
+      catalogs: ctx.catalogs,
       currentLockfile: ctx.currentLockfile,
       allowedDeprecatedVersions: {},
       allowNonAppliedPatches: false,

pkg-manager/core/src/install/allCatalogsAreUpToDate.ts

@@ -0,0 +1,11 @@
+import { type CatalogSnapshots } from '@pnpm/lockfile-file'
+import { type Catalogs } from '@pnpm/catalogs.types'
+
+export function allCatalogsAreUpToDate (
+  catalogsConfig: Catalogs,
+  snapshot: CatalogSnapshots | undefined
+): boolean {
+  return Object.entries(snapshot ?? {})
+    .every(([catalogName, catalog]) => Object.entries(catalog ?? {})
+      .every(([alias, entry]) => entry.specifier === catalogsConfig[catalogName]?.[alias]))
+}

pkg-manager/core/src/install/extendInstallOptions.ts

@@ -144,6 +144,8 @@ export interface StrictInstallOptions {
 
   supportedArchitectures?: SupportedArchitectures
   hoistWorkspacePackages?: boolean
+
+  useBetaCatalogsFeat?: boolean
 }
 
 export type InstallOptions =