feat(pm): implement catalog protocol for dependency resolution

[elrrrrrrr]

Summary

• Add catalog: dependency protocol support — define shared version specs in .utoo.toml, reference via catalog: or catalog:<name> in package.json
• Resolve catalog specs inline in process_dependency (same pattern as workspace:/git:)
• Normalize default catalog keys ("" / "default") at config build time
• Add catalog-aware lock freshness check
• Add e2e test fixture and test cases

Test plan

• cargo test -p utoo-pm -p utoo-ruborist — all pass
• cargo clippy — no warnings
• ./e2e/utoo-pm.sh — catalog e2e tests

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant enhancement to dependency management by adding a 'catalog' protocol. This feature enables developers to centralize and share dependency version specifications across projects or within a monorepo, promoting consistency and simplifying updates. By resolving these catalog entries during the dependency processing phase and ensuring lock file freshness checks are catalog-aware, the system gains improved reliability and maintainability for managing shared dependencies.

Highlights

• Catalog Dependency Protocol: Implemented support for a new catalog: dependency protocol, allowing shared version specifications to be defined in .utoo.toml and referenced in package.json.
• Inline Catalog Resolution: Catalog specifications are now resolved inline within the process_dependency function, following a pattern similar to workspace: and git: protocols.
• Default Catalog Key Normalization: The default catalog keys ("" and "default") are normalized during configuration build time to ensure consistent lookup.
• Catalog-Aware Lock Freshness Check: The is_pkg_lock_outdated function has been updated to correctly account for catalog-resolved dependencies when checking the freshness of the package-lock.json file.
• End-to-End Testing: New end-to-end test fixtures and test cases have been added to validate the functionality and update flow of the catalog protocol.

Changelog

• crates/pm/src/helper/lock.rs
  • Imported resolve_catalog_spec for catalog-aware lock file checks.
  • Removed the deps_map_equals_lock helper function.
  • Refactored is_pkg_lock_outdated to use a new deps_match closure that incorporates catalog resolution.
• crates/pm/src/helper/ruborist_context.rs
  • Imported get_catalogs function.
  • Modified BuildDepsOptions to include catalog definitions retrieved from get_catalogs.
• crates/pm/src/util/config_file.rs
  • Imported Catalogs type.
  • Updated the catalogs method to normalize default catalog keys, mapping both "" and "default" to the default catalog.
• crates/pm/src/util/user_config.rs
  • Imported Catalogs type.
  • Implemented caching for the get_catalogs function using OnceLock to improve performance.
• crates/ruborist/src/lib.rs
  • Moved the spec module to its own top-level module.
  • Updated node module export to reflect its new location.
• crates/ruborist/src/model/mod.rs
  • Removed the spec module from the model module exports.
• crates/ruborist/src/model/node.rs
  • Added the Copy trait to the NodeType enum.
• crates/ruborist/src/resolver/builder.rs
  • Updated imports for PackageSpec, Protocol, Catalogs, and resolve_catalog_spec from the new spec module.
  • Added a catalogs field to BuildDepsConfig for passing catalog definitions.
  • Implemented logic within process_dependency to resolve catalog: protocol specifications using the provided catalogs.
• crates/ruborist/src/resolver/edges.rs
  • Updated comments to clarify that catalog: specs are added as-is and resolved later in process_dependency.
• crates/ruborist/src/resolver/git.rs
  • Updated the import path for PackageSpec.
• crates/ruborist/src/resolver/preload.rs
  • Updated the import path for SpecStr.
• crates/ruborist/src/service/api.rs
  • Imported Catalogs type.
  • Added a catalogs field to BuildDepsOptions.
  • Passed catalog definitions from BuildDepsOptions to BuildDepsConfig during dependency graph construction.
• crates/ruborist/src/spec/mod.rs
  • Renamed from crates/ruborist/src/model/spec.rs.
  • Added Catalog to the Protocol enum.
  • Updated is_local method for Protocol to correctly handle Catalog.
  • Modified From<&str> implementation for PackageSpec to parse catalog: protocol.
  • Introduced Catalogs type alias and resolve_catalog_spec function for catalog lookup.
• crates/utoo-wasm/src/deps.rs
  • Initialized catalogs field in BuildDepsOptions with an empty HashMap.
• e2e/pm/catalog-test/.utoo.toml
  • Added a new configuration file defining default and named catalogs for testing.
• e2e/pm/catalog-test/package.json
  • Added a new package.json file demonstrating catalog: dependency usage.
• e2e/pm/catalog-test/packages/app/package.json
  • Added a new package.json file for a workspace app using catalog: dependencies.
• e2e/pm/catalog-test/packages/utils/package.json
  • Added a new package.json file for a workspace utility using named catalog: dependencies.
• e2e/utoo-pm.sh
  • Added new end-to-end tests for the catalog protocol, including basic installation and catalog update flows.
• next.js
  • Updated the subproject commit hash.

Activity

• The pull request was created and includes a detailed summary of the changes.
• The changes were generated with Claude Code, indicating an initial submission without prior human review comments or activity.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces support for the catalog: dependency protocol, allowing shared version specifications to be defined in .utoo.toml and referenced in package.json. The changes involve refactoring the PackageSpec and Protocol definitions into a new spec module, updating configuration handling to load and cache catalog definitions, and modifying the dependency resolution builder to correctly process catalog: specs. Comprehensive end-to-end tests have been added to validate the new functionality, including basic installation and catalog update flows. The implementation appears robust and well-tested, enhancing the package manager's flexibility for managing dependencies.