fix: normalize 'default' as alias for the unnamed default catalog

pnpm/bun treat top-level `catalog` and `catalogs.default` as the same
default catalog, with `catalog:` and `catalog:default` both pointing at
it. Previously `catalogs.default` was stored under key "default" and
`catalog:default` looked up "default", so users who used the alias form
got no catalog resolution. Now both forms normalize to the canonical
"" key.

Author: theoephraim

packages/bumpy/src/utils/package-manager.ts

@@ -78,10 +78,26 @@ async function getWorkspaceGlobs(rootDir: string, pm: PackageManager): Promise<s
  */
 export const CATALOG_FILES = ['pnpm-workspace.yaml', 'package.json'] as const;
 
+/**
+ * Normalize a catalog name to its canonical form.
+ * pnpm/bun treat "default" and the unnamed top-level catalog interchangeably,
+ * so we store and look up the default catalog under "" regardless of which alias
+ * the user wrote.
+ */
+function normalizeCatalogName(name: string): string {
+  return name === 'default' ? '' : name;
+}
+
 /** Parse catalog definitions from the raw contents of pnpm-workspace.yaml and root package.json */
 export function parseCatalogs(pnpmWorkspaceYaml: string | null, rootPackageJson: string | null): CatalogMap {
   const catalogs: CatalogMap = new Map();
 
+  const addNamed = (raw: Record<string, Record<string, string>>): void => {
+    for (const [name, deps] of Object.entries(raw)) {
+      catalogs.set(normalizeCatalogName(name), deps);
+    }
+  };
+
   if (pnpmWorkspaceYaml) {
     try {
       const parsed = yaml.load(pnpmWorkspaceYaml) as {
@@ -93,9 +109,7 @@ export function parseCatalogs(pnpmWorkspaceYaml: string | null, rootPackageJson:
         catalogs.set('', parsed.catalog); // default catalog
       }
       if (parsed?.catalogs) {
-        for (const [name, deps] of Object.entries(parsed.catalogs)) {
-          catalogs.set(name, deps);
-        }
+        addNamed(parsed.catalogs);
       }
     } catch {
       // ignore malformed yaml
@@ -111,9 +125,7 @@ export function parseCatalogs(pnpmWorkspaceYaml: string | null, rootPackageJson:
         catalogs.set('', pkg.catalog as Record<string, string>);
       }
       if (pkg.catalogs && typeof pkg.catalogs === 'object') {
-        for (const [name, deps] of Object.entries(pkg.catalogs as Record<string, Record<string, string>>)) {
-          catalogs.set(name, deps);
-        }
+        addNamed(pkg.catalogs as Record<string, Record<string, string>>);
       }
 
       // Inside workspaces object (bun style)
@@ -124,9 +136,7 @@ export function parseCatalogs(pnpmWorkspaceYaml: string | null, rootPackageJson:
           catalogs.set('', ws.catalog as Record<string, string>);
         }
         if (ws.catalogs && typeof ws.catalogs === 'object') {
-          for (const [name, deps] of Object.entries(ws.catalogs as Record<string, Record<string, string>>)) {
-            catalogs.set(name, deps);
-          }
+          addNamed(ws.catalogs as Record<string, Record<string, string>>);
         }
       }
     } catch {
@@ -157,11 +167,15 @@ async function loadCatalogs(rootDir: string, pm: PackageManager): Promise<Catalo
   return parseCatalogs(pnpmYaml, pkgJsonText);
 }
 
+/** Extract the catalog name from a `catalog:` / `catalog:<name>` range, normalizing the default alias */
+function catalogNameFromRange(range: string): string {
+  return normalizeCatalogName(range.slice('catalog:'.length).trim());
+}
+
 /** Resolve a specific dependency's catalog: reference */
 export function resolveCatalogDep(depName: string, range: string, catalogs: CatalogMap): string | null {
   if (!range.startsWith('catalog:')) return null;
-  const catalogName = range.slice('catalog:'.length).trim() || '';
-  const catalog = catalogs.get(catalogName);
+  const catalog = catalogs.get(catalogNameFromRange(range));
   if (!catalog) return null;
   return catalog[depName] ?? null;
 }
@@ -203,6 +217,5 @@ export function isCatalogRefAffected(
   catalogChanges: Map<string, Set<string>>,
 ): boolean {
   if (!range.startsWith('catalog:')) return false;
-  const catalogName = range.slice('catalog:'.length).trim() || '';
-  return catalogChanges.get(catalogName)?.has(depName) ?? false;
+  return catalogChanges.get(catalogNameFromRange(range))?.has(depName) ?? false;
 }

packages/bumpy/test/utils/package-manager.test.ts

@@ -76,6 +76,26 @@ catalogs:
   test('tolerates malformed json', () => {
     expect(() => parseCatalogs(null, '{not valid json')).not.toThrow();
   });
+
+  test('catalogs.default is stored under "" so it merges with the top-level catalog', () => {
+    // pnpm treats top-level `catalog` and `catalogs.default` as aliases of the same default catalog
+    const yaml = `
+catalogs:
+  default:
+    react: ^19.0.0
+`;
+    const catalogs = parseCatalogs(yaml, null);
+    expect(catalogs.get('')).toEqual({ react: '^19.0.0' });
+    expect(catalogs.has('default')).toBe(false);
+  });
+
+  test('catalogs.default in package.json also normalizes to ""', () => {
+    const pkg = JSON.stringify({ catalogs: { default: { react: '^19.0.0' }, testing: { jest: '^30.0.0' } } });
+    const catalogs = parseCatalogs(null, pkg);
+    expect(catalogs.get('')).toEqual({ react: '^19.0.0' });
+    expect(catalogs.get('testing')).toEqual({ jest: '^30.0.0' });
+    expect(catalogs.has('default')).toBe(false);
+  });
 });
 
 describe('diffCatalogMaps', () => {
@@ -153,6 +173,11 @@ describe('isCatalogRefAffected', () => {
   test('returns false when depName is not in changes', () => {
     expect(isCatalogRefAffected('catalog:', 'lodash', changes)).toBe(false);
   });
+
+  test('catalog:default is an alias for catalog: (default catalog)', () => {
+    expect(isCatalogRefAffected('catalog:default', 'react', changes)).toBe(true);
+    expect(isCatalogRefAffected('catalog:default', 'jest', changes)).toBe(false);
+  });
 });
 
 describe('resolveCatalogDep (sanity check after refactor)', () => {
@@ -175,4 +200,9 @@ describe('resolveCatalogDep (sanity check after refactor)', () => {
     const catalogs: CatalogMap = new Map([['', {}]]);
     expect(resolveCatalogDep('react', 'catalog:', catalogs)).toBeNull();
   });
+
+  test('resolves catalog:default to the default catalog', () => {
+    const catalogs: CatalogMap = new Map([['', { react: '^19.0.0' }]]);
+    expect(resolveCatalogDep('react', 'catalog:default', catalogs)).toBe('^19.0.0');
+  });
 });