feat(core): support catalog: specifiers

Closes #258

Author: JamieMason

.cursorrules

@@ -177,6 +177,13 @@ Use grep/rg ONLY for: multiple file types, intentionally searching comments, non
 2. Read actual implementation
 3. Base advice on verified facts
 
+### Before Writing Tests
+
+1. Read 2-3 existing tests in same file
+2. Identify the pattern (TestBuilder methods, assertion style)
+3. Match that pattern exactly
+4. Never invent APIs - only use what exists
+
 ### Scope Boundaries (Off-Limits)
 
 - Don't modify: Context creation, 3-phase pattern

src/catalogs.rs

@@ -0,0 +1,202 @@
+use {
+  crate::{config::Config, specifier::Specifier},
+  log::debug,
+  serde::Deserialize,
+  std::{collections::HashMap, fs, rc::Rc, time::Instant},
+};
+
+pub type Catalog = HashMap<String, Rc<Specifier>>;
+pub type CatalogsByName = HashMap<String, Catalog>;
+
+/// Extract catalogs from the project configuration.
+///
+/// Attempts to read catalog definitions from:
+/// 1. pnpm-workspace.yaml (pnpm catalogs)
+/// 2. package.json at project root (bun catalogs)
+///
+/// See:
+/// - https://pnpm.io/catalogs
+/// - https://bun.sh/docs/pm/catalogs
+pub fn from_config(config: &Config) -> Option<CatalogsByName> {
+  let start = Instant::now();
+  let catalogs = try_from_pnpm(config).or_else(|| try_from_bun(config));
+  debug!("Catalog discovery completed in {:?}", start.elapsed());
+  catalogs
+}
+
+/// Try to read catalogs from pnpm-workspace.yaml
+///
+/// pnpm supports both:
+/// - `catalog:` (singular) - default catalog
+/// - `catalogs:` (plural) - named catalogs
+///
+/// Example pnpm-workspace.yaml:
+/// ```yaml
+/// packages:
+///   - 'packages/*'
+/// catalog:
+///   chalk: ^4.1.2
+/// catalogs:
+///   react16:
+///     react: ^16.7.0
+///     react-dom: ^16.7.0
+/// ```
+fn try_from_pnpm(config: &Config) -> Option<CatalogsByName> {
+  let file_path = config.cli.cwd.join("pnpm-workspace.yaml");
+
+  if !file_path.exists() {
+    return None;
+  }
+
+  debug!("Reading catalogs from pnpm-workspace.yaml");
+
+  let contents = fs::read_to_string(&file_path).ok()?;
+  let workspace: PnpmWorkspace = serde_yaml::from_str(&contents).ok()?;
+
+  let mut catalogs_by_name = CatalogsByName::new();
+
+  // Add default catalog if present
+  if let Some(default_catalog) = workspace.catalog {
+    let mut catalog = Catalog::new();
+    for (name, version) in default_catalog {
+      catalog.insert(name, Specifier::new(&version));
+    }
+    if !catalog.is_empty() {
+      catalogs_by_name.insert("default".to_string(), catalog);
+    }
+  }
+
+  // Add named catalogs if present
+  if let Some(named_catalogs) = workspace.catalogs {
+    for (catalog_name, dependencies) in named_catalogs {
+      let mut catalog = Catalog::new();
+      for (name, version) in dependencies {
+        catalog.insert(name, Specifier::new(&version));
+      }
+      if !catalog.is_empty() {
+        catalogs_by_name.insert(catalog_name, catalog);
+      }
+    }
+  }
+
+  if catalogs_by_name.is_empty() {
+    debug!("No catalogs found in pnpm-workspace.yaml");
+    None
+  } else {
+    debug!("Found {} catalog(s) in pnpm-workspace.yaml", catalogs_by_name.len());
+    Some(catalogs_by_name)
+  }
+}
+
+/// Try to read catalogs from package.json at project root
+///
+/// Bun supports catalogs defined in the root package.json:
+/// - At top level: `catalog` and `catalogs`
+/// - Under workspaces: `workspaces.catalog` and `workspaces.catalogs`
+///
+/// Example package.json:
+/// ```json
+/// {
+///   "workspaces": {
+///     "catalog": {
+///       "react": "^19.0.0"
+///     },
+///     "catalogs": {
+///       "testing": {
+///         "jest": "30.0.0"
+///       }
+///     }
+///   }
+/// }
+/// ```
+fn try_from_bun(config: &Config) -> Option<CatalogsByName> {
+  let file_path = config.cli.cwd.join("package.json");
+
+  if !file_path.exists() {
+    return None;
+  }
+
+  debug!("Reading catalogs from package.json");
+
+  let contents = fs::read_to_string(&file_path).ok()?;
+  let package_json: BunPackageJson = serde_json::from_str(&contents).ok()?;
+
+  let mut catalogs_by_name = CatalogsByName::new();
+
+  // Try workspaces.catalog and workspaces.catalogs first
+  if let Some(workspaces) = package_json.workspaces {
+    if let Some(default_catalog) = workspaces.catalog {
+      let mut catalog = Catalog::new();
+      for (name, version) in default_catalog {
+        catalog.insert(name, Specifier::new(&version));
+      }
+      if !catalog.is_empty() {
+        catalogs_by_name.insert("default".to_string(), catalog);
+      }
+    }
+
+    if let Some(named_catalogs) = workspaces.catalogs {
+      for (catalog_name, dependencies) in named_catalogs {
+        let mut catalog = Catalog::new();
+        for (name, version) in dependencies {
+          catalog.insert(name, Specifier::new(&version));
+        }
+        if !catalog.is_empty() {
+          catalogs_by_name.insert(catalog_name, catalog);
+        }
+      }
+    }
+  }
+
+  // Fall back to top-level catalog and catalogs
+  if catalogs_by_name.is_empty() {
+    if let Some(default_catalog) = package_json.catalog {
+      let mut catalog = Catalog::new();
+      for (name, version) in default_catalog {
+        catalog.insert(name, Specifier::new(&version));
+      }
+      if !catalog.is_empty() {
+        catalogs_by_name.insert("default".to_string(), catalog);
+      }
+    }
+
+    if let Some(named_catalogs) = package_json.catalogs {
+      for (catalog_name, dependencies) in named_catalogs {
+        let mut catalog = Catalog::new();
+        for (name, version) in dependencies {
+          catalog.insert(name, Specifier::new(&version));
+        }
+        if !catalog.is_empty() {
+          catalogs_by_name.insert(catalog_name, catalog);
+        }
+      }
+    }
+  }
+
+  if catalogs_by_name.is_empty() {
+    debug!("No catalogs found in package.json");
+    None
+  } else {
+    debug!("Found {} catalog(s) in package.json", catalogs_by_name.len());
+    Some(catalogs_by_name)
+  }
+}
+
+#[derive(Debug, Deserialize)]
+struct PnpmWorkspace {
+  catalog: Option<HashMap<String, String>>,
+  catalogs: Option<HashMap<String, HashMap<String, String>>>,
+}
+
+#[derive(Debug, Deserialize)]
+struct BunPackageJson {
+  catalog: Option<HashMap<String, String>>,
+  catalogs: Option<HashMap<String, HashMap<String, String>>>,
+  workspaces: Option<BunWorkspaces>,
+}
+
+#[derive(Debug, Deserialize)]
+struct BunWorkspaces {
+  catalog: Option<HashMap<String, String>>,
+  catalogs: Option<HashMap<String, HashMap<String, String>>>,
+}

src/context.rs

@@ -1,5 +1,6 @@
 use {
   crate::{
+    catalogs::CatalogsByName,
     config::Config,
     dependency::UpdateUrl,
     instance::Instance,
@@ -33,6 +34,12 @@ use {
 /// See PATTERNS.md "Ownership and Borrowing" section for details.
 #[derive(Debug)]
 pub struct Context {
+  /// If present, the contents of each bun or pnpm catalog. The default catalog
+  /// is keyed under "default" and named by their names.
+  ///
+  /// - https://pnpm.io/catalogs
+  /// - https://bun.sh/docs/pm/catalogs
+  pub catalogs: Option<CatalogsByName>,
   /// All default configuration with user config applied
   pub config: Config,
   /// The internal names of all failed updates
@@ -67,7 +74,12 @@ impl Context {
   /// Called from: src/main.rs
   /// Next step: visit_packages() in src/visit_packages.rs
   /// See also: .cursorrules for critical invariants
-  pub fn create(config: Config, packages: Packages, registry_client: Option<Arc<dyn RegistryClient>>) -> Self {
+  pub fn create(
+    config: Config,
+    packages: Packages,
+    registry_client: Option<Arc<dyn RegistryClient>>,
+    catalogs: Option<CatalogsByName>,
+  ) -> Self {
     let mut instances = vec![];
     let updates_by_internal_name = HashMap::new();
     let all_dependency_types = config.rcfile.get_all_dependency_types();
@@ -107,6 +119,7 @@ impl Context {
     });
 
     Self {
+      catalogs,
       config,
       failed_updates,
       instances,

src/instance_state.rs

@@ -206,6 +206,8 @@ impl Ord for InstanceState {
 
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 pub enum ValidInstance {
+  /// - ✓ Instance uses the catalog: protocol and wins out
+  IsCatalog,
   /// - ✓ Instance is configured to be ignored by Syncpack
   IsIgnored,
   /// - ✓ Instance is a local package and its version is valid
@@ -258,6 +260,11 @@ pub enum InvalidInstance {
 pub enum FixableInstance {
   /// - ✘ Instance is in a banned version group
   IsBanned,
+  /// - ✓ Instance is in a highest/lowest semver group
+  /// - ✓ One or more other instances use the catalog: protocol
+  /// - ✘ Instance does not use the catalog: protocol
+  /// - ! catalog: protocol wins
+  DiffersToCatalog,
   /// - ✘ Instance mismatches the version of its locally-developed package
   DiffersToLocal,
   /// - ✘ Instance mismatches highest/lowest semver in its group

src/instance_test.rs

@@ -22,8 +22,10 @@ fn returns_correct_registry_update_url() {
       "lit": "npm:lit@3.2.1",
     }
   })]);
+
+  let catalogs = None;
   let registry_client = None;
-  let ctx = Context::create(config, packages, registry_client);
+  let ctx = Context::create(config, packages, registry_client, catalogs);
 
   let get_update_url_by_name = |name: &str| {
     ctx

src/main.rs

@@ -19,6 +19,7 @@ use {
 #[path = "test/test.rs"]
 mod test;
 
+mod catalogs;
 mod cli;
 mod commands;
 mod config;
@@ -60,6 +61,7 @@ async fn main() {
   debug!("{:#?}", config.rcfile);
 
   let packages = Packages::from_config(&config);
+  let catalogs = None; // catalogs::from_config(&config);
 
   match packages.all.len() {
     0 => {
@@ -81,6 +83,7 @@ async fn main() {
     } else {
       None
     },
+    catalogs,
   );
 
   // PHASE 2 & 3: Inspect and Run