@muverse/core - Core Library

The core business logic powering μVERSE (Version Engine for Repo Semantic Evolution). This package is completely framework-agnostic and can be integrated into any TypeScript/JavaScript project, CI/CD system, or custom tooling.

Installation

npm install @muverse/core

Quick Start

import { VerseRunner } from '@muverse/core';

const runner = new VerseRunner({
  repoRoot: '/path/to/repository',
  adapter: 'gradle', // Optional - auto-detected if not specified
  dryRun: false,
  pushTags: true,
  pushChanges: true,
  generateChangelog: true
});

const result = await runner.run();

console.log(`Bumped: ${result.bumped}`);
console.log(`Changed modules:`, result.changedModules);
console.log(`Created tags:`, result.createdTags);

For detailed pre-release configuration and examples, see PRERELEASE.md.

VerseRunner API

Options

interface RunnerOptions {
  repoRoot: string;                    // Path to repository root
  adapter?: string;                    // Language adapter (auto-detected if not specified)
  dryRun?: boolean;                    // Preview changes without writing (default: false)
  pushTags?: boolean;                  // Push version tags (default: true)
  prereleaseMode?: boolean;            // Generate pre-release versions (default: false)
  prereleaseId?: string;               // Pre-release identifier: alpha, beta, rc, etc. (default: 'alpha')
  bumpUnchanged?: boolean;             // Bump modules with no changes in prerelease mode (default: false)
  addBuildMetadata?: boolean;          // Add build metadata with short SHA (default: false)
  timestampVersions?: boolean;         // Use timestamp-based prerelease IDs (default: false)
  appendSnapshot?: boolean;            // Add -SNAPSHOT suffix (Gradle only) (default: false)
  pushChanges?: boolean;               // Commit and push version changes (default: true)
  generateChangelog?: boolean;         // Generate changelogs (default: true)
}

Result

interface RunnerResult {
  bumped: boolean;                     // Whether any version was updated
  changedModules: Array<{
    name: string;                      // Module name
    from: string;                      // Previous version
    to: string;                        // New version
  }>;
  createdTags: string[];              // Git tags that were created
  changelogPaths: string[];           // Generated changelog file paths
}

Configuration

μVERSE core uses cosmiconfig for configuration loading and Zod for validation.

Supported Configuration Files

1. package.json (in a "muverse" property)
2. .muverserc.json
3. .muverserc.yaml / .muverserc.yml
4. .muverserc.js or muverse.config.js (JavaScript)

Configuration Example

{
  "defaultBump": "patch",
  "commitTypes": {
    "feat": "minor",
    "fix": "patch",
    "perf": "patch",
    "docs": "ignore"
  },
  "dependencyRules": {
    "onMajorOfDependency": "minor",
    "onMinorOfDependency": "patch",
    "onPatchOfDependency": "none"
  }
}

Adapters

Gradle Adapter

Built-in support for Gradle projects (Groovy & Kotlin DSL).

Features:

• Multi-module project detection
• Version management through root gradle.properties
• Dependency detection
• Both Groovy and Kotlin DSL support

Version Format:

# Root module
version=1.0.0

# Submodules
core.version=2.1.0
api.version=1.5.0

Creating Custom Adapters

To add support for new project types, implement a language adapter following the pattern in src/adapters/gradle/:

import { 
  AdapterIdentifier,
  ModuleDetector,
  VersionUpdateStrategy,
  ModuleSystemFactory,
  AdapterMetadata,
  RawProjectInformation,
  ProcessedModuleChange
} from '@muverse/core';

// 1. Adapter identifier for auto-detection
class MyAdapterIdentifier implements AdapterIdentifier {
  readonly metadata: AdapterMetadata = {
    id: 'my-adapter',
    capabilities: { supportsSnapshots: false }
  };

  async accept(projectRoot: string): Promise<boolean> {
    // Check for adapter-specific files
    return await fileExists(path.join(projectRoot, 'my-build-file'));
  }
}

// 2. Module detector for discovering project structure
class MyModuleDetector implements ModuleDetector {
  async detectModules(projectRoot: string): Promise<RawProjectInformation> {
    // Discover and return modules and dependencies
    return {
      modules: [
        { name: 'root', path: projectRoot, version: '1.0.0' },
        { name: 'module-a', path: join(projectRoot, 'module-a'), version: '2.0.0' }
      ],
      dependencies: [
        { from: 'module-a', to: 'root' }
      ]
    };
  }
}

// 3. Version update strategy for applying changes
class MyVersionUpdateStrategy implements VersionUpdateStrategy {
  async applyVersionUpdates(
    changes: ProcessedModuleChange[],
    projectRoot: string
  ): Promise<void> {
    // Apply version changes to build files
    for (const change of changes) {
      // Update version in your project's format
    }
  }
}

// 4. Module system factory to tie it all together
class MyModuleSystemFactory implements ModuleSystemFactory {
  createDetector(): ModuleDetector {
    return new MyModuleDetector();
  }
  
  createVersionUpdateStrategy(): VersionUpdateStrategy {
    return new MyVersionUpdateStrategy();
  }
}

Then register your adapter:

1. Add to src/factories/module-system-factory.ts in the createModuleSystemFactory function
2. Add to src/services/adapter-identifier-registry.ts in the registry initialization

Development

Building

# From monorepo root
npm run build

# Or from core package
cd packages/core
npm run build

Testing

# From monorepo root
npm test

# Or from core package
cd packages/core
npm test
npm run test:coverage

Publishing

npm publish --workspace packages/core --access public

Related Packages

• @muverse/cli - Command-line interface
• @muverse/action - GitHub Actions integration

Requirements

• Node.js: >= 20
• TypeScript: >= 5.0 (if using TypeScript)

License

MIT License - see LICENSE for details.