Workspace Dependency Version Synchronizer

Build a tool that reads a workspace configuration and synchronizes package versions using a centralized catalog system.

Overview

In monorepos, maintaining consistent dependency versions across multiple packages is challenging. This tool should parse workspace configurations, extract version information from a central catalog, and update package.json files accordingly.

Requirements

Read workspace configuration

• Read a workspace configuration file in YAML format that contains:
  • A packages array with glob patterns pointing to workspace packages
  • A catalog object mapping package names to version strings
• Parse and validate the YAML structure

Synchronize dependencies

• For each workspace package found via glob patterns:
  • Read the package.json file
  • Find dependencies with values starting with catalog:
  • Replace catalog: references with the corresponding version from the catalog
  • Keep all other dependencies unchanged
• Generate a report showing:
  • Number of packages processed
  • Number of dependencies updated
  • Any unresolved catalog references (catalog entries referenced but not found)

Test Cases

• Given a workspace with 2 packages and a catalog defining "react": "^18.2.0", when package A has "react": "catalog:" in dependencies, then after synchronization package A should have "react": "^18.2.0" @test

• Given a catalog with "lodash": "~4.17.21", when a package has both "lodash": "catalog:" and "express": "^4.18.0", then after synchronization only lodash should be updated while express remains unchanged @test

• Given a package with "unknown-pkg": "catalog:" but no catalog entry for "unknown-pkg", then the tool should report the unresolved reference and not modify that dependency @test

Implementation

@generates

API

/**
 * Reads workspace configuration and returns parsed data
 * @param {string} configPath - Path to workspace YAML configuration
 * @returns {Promise<WorkspaceConfig>} Parsed workspace configuration
 */
async function readWorkspaceConfig(configPath) {
  // IMPLEMENTATION HERE
}

/**
 * Synchronizes package dependencies using catalog versions
 * @param {string} workspaceRoot - Root directory of the workspace
 * @param {WorkspaceConfig} config - Parsed workspace configuration
 * @returns {Promise<SyncReport>} Report of synchronization results
 */
async function syncDependencies(workspaceRoot, config) {
  // IMPLEMENTATION HERE
}

/**
 * Updates a single package.json with catalog versions
 * @param {string} packagePath - Path to package.json
 * @param {Object} catalog - Map of package names to versions
 * @returns {Promise<UpdateResult>} Result of the update operation
 */
async function updatePackageJson(packagePath, catalog) {
  // IMPLEMENTATION HERE
}

module.exports = {
  readWorkspaceConfig,
  syncDependencies,
  updatePackageJson
};

Types

interface WorkspaceConfig {
  packages: string[];
  catalog: Record<string, string>;
}

interface SyncReport {
  packagesProcessed: number;
  dependenciesUpdated: number;
  unresolvedReferences: Array<{package: string, dependency: string}>;
}

interface UpdateResult {
  updated: boolean;
  changes: Array<{name: string, from: string, to: string}>;
}

Dependencies { .dependencies }

js-yaml { .dependency }

Parses YAML configuration files.

glob { .dependency }

Matches workspace packages using glob patterns.