@versu/core - Core Library

The core business logic powering Versu. This package is completely framework-agnostic and can be integrated into any TypeScript/JavaScript project, CI/CD system, or custom tooling.

For comprehensive documentation, examples, and configuration options, please refer to the our website https://versuhq.github.io/.

Installation

npm install @versu/core

Quick Start

import { VersuRunner, type RunnerOptions } from "@versu/core";

const options: RunnerOptions = {
  repoRoot: "/path/to/repository",
  // ...other options as needed
};

const runner = new VersuRunner(options);

const result = await runner.run();

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

VersuRunner API

Options

type RunnerOptions = {
  // Required
  repoRoot: string; // Absolute path to repository root
  prereleaseMode: boolean; // Generate pre-release versions
  prereleaseId: string; // Pre-release identifier, e.g. 'alpha', 'beta', 'rc'
  bumpUnchanged: boolean; // Bump modules with no changes (prerelease mode only)
  addBuildMetadata: boolean; // Append short SHA as build metadata (+sha)
  timestampVersions: boolean; // Use timestamp-based pre-release identifiers
  appendSnapshot: boolean; // Append -SNAPSHOT suffix (Gradle only)
  createTags: boolean; // Create git tags for bumped modules
  generateChangelog: boolean; // Generate CHANGELOG.md files
  generateReleaseNotes: boolean; // Generate release notes files (e.g. RELEASE.md)
  pushChanges: boolean; // Commit and push version changes to remote
  dryRun: boolean; // Preview changes without writing anything
  sequentialTagPush: boolean; // Push tags one by one instead of all at once
  commitReleaseNotes: boolean; // Include release notes in the version commit
  stripModulePrefix: boolean; // Strip module name from tags (single-module projects)
  tagVersionPrefix: string; // Prefix for tag versions (e.g., 'v'; use '' for none)

  // Optional
  adapter?: string; // Language adapter ID (auto-detected if omitted)
  changelogFilename?: string; // Changelog filename (default: 'CHANGELOG.md')
  releaseNotesFilename?: string; // Release notes filename (default: 'RELEASE.md')
  fromRef?: string; // Git ref to use as the lower boundary for commit analysis
  provider?: string; // Version control provider name (auto-detected if omitted)
};

Result

type RunnerResult = {
  bumped: boolean; // Whether any version was updated
  discoveredModules: Array<Module>; // All modules found in the repository
  changedModules: Array<ModuleChangeResult>; // Modules whose version changed ({ id, from, to })
  createdTags: CreatedTagResult[]; // Created tags ({ moduleId, tag })
  changelogPaths: ChangesRendererResult[]; // Generated changelog files ({ moduleId, path })
  releaseNotesPaths: ChangesRendererResult[]; // Generated release notes files ({ moduleId, path })
};

Configuration

Versu core uses cosmiconfig for configuration loading and Zod for validation.

You can provide configuration in any of the supported config files (e.g., .versurc, versu.config.js, etc.) or via package.json under the versu key. For the full list please refer to cosmiconfig search places documentation.

Configuration Example

{
  "plugins": ["@versu/plugin-gradle"],
  "versioning": {
    "breakingChange": {
      "stable": "major",
      "prerelease": "premajor"
    },
    "unknownCommitType": {
      "stable": "patch",
      "prerelease": "prepatch"
    },
    "commitTypes": {
      "feat": {
        "stable": "minor",
        "prerelease": "preminor"
      },
      "fix": {
        "stable": "patch",
        "prerelease": "prepatch"
      }
    },
    "cascadeRules": {
      "stable": {
        "major": "major",
        "minor": "minor",
        "patch": "patch"
      },
      "prerelease": {
        "premajor": "premajor",
        "preminor": "preminor",
        "prepatch": "prepatch",
        "prerelease": "prerelease"
      }
    }
  },
  "changelog": {
    "root": {
      "context": {
        "prependPlaceholder": "<!-- Next Version Placeholder -->"
      }
    },
    "module": {
      "context": {
        "prependPlaceholder": "<!-- Next Version Placeholder -->"
      }
    }
  }
}

Changelog & Release Notes Configuration:

• changelog.root - Configuration for root-level CHANGELOG.md generation
• changelog.module - Configuration for per-module CHANGELOG.md generation
• changelog.context.prependPlaceholder - Placeholder string in changelog files where new entries are inserted
• changelog.context.options - Advanced changelog generation options (templates, grouping, sorting)

Release notes follows the same pattern under release key.

Versu uses conventional-changelog-writer for changelog and release notes generation. You can pass any options supported by conventional-changelog-writer through the options field. For advanced customization with functions (like transform, commitsGroupsSort), use JavaScript configuration files (.versurc.js or versu.config.js).

Adapters

Versu supports multiple language ecosystems through adapters. The core package includes a plugin system for adding new adapter support. In order to support additional ecosystems, you need to implement the required interfaces and register them as plugins.

Creating Custom Adapters

To add support for new project types, create a plugin package that implements the adapter interfaces:

import {
  type AdapterIdentifier,
  type AdapterMetadata,
  type ModuleDetector,
  type ProjectInformation,
  type RawProjectInformation,
  type VersionUpdateStrategy,
  type ModuleRegistry,
  type ModuleSystemFactory,
  getProjectInformationFromRawData,
  exists,
} from "@versu/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 exists(path.join(projectRoot, "my-build-file"));
  }
}

// 2. Module detector for discovering project structure
class MyModuleDetector implements ModuleDetector {
  constructor(readonly repoRoot: string) {}

  async detect(): Promise<ProjectInformation> {
    // Discover modules and dependencies, then convert the raw
    // structure with getProjectInformationFromRawData.
    // Module IDs are Gradle-style (':' for root, ':module-a', ':libs:utils');
    // exactly one module of type 'root' is required.
    const raw: RawProjectInformation = {
      ":": {
        name: "root",
        path: ".",
        type: "root",
        affectedModules: [":module-a"],
        declaredVersion: false,
      },
      ":module-a": {
        name: "module-a",
        path: "module-a",
        type: "module",
        affectedModules: [],
        version: "2.0.0",
        declaredVersion: true,
      },
    };

    return getProjectInformationFromRawData(raw);
  }
}

// 3. Version update strategy for applying changes
class MyVersionUpdateStrategy implements VersionUpdateStrategy {
  constructor(private readonly moduleRegistry: ModuleRegistry) {}

  async writeVersionUpdates(
    moduleVersions: Map<string, string>,
  ): Promise<void> {
    // Apply version changes to build files
    for (const [moduleId, newVersion] of moduleVersions) {
      // Update version in your project's format
    }
  }
}

// 4. Module system factory to tie it all together
class MyModuleSystemFactory implements ModuleSystemFactory {
  constructor(private readonly repoRoot: string) {}

  async createDetector(outputFile: string): Promise<ModuleDetector> {
    return new MyModuleDetector(this.repoRoot);
  }

  async createVersionUpdateStrategy(
    moduleRegistry: ModuleRegistry,
  ): Promise<VersionUpdateStrategy> {
    return new MyVersionUpdateStrategy(moduleRegistry);
  }
}

Then create a plugin:

import type { PluginContract } from "@versu/core";

const myPlugin: PluginContract = {
  id: "my-adapter",
  name: "My Adapter",
  description: "Support for my build system",
  version: "1.0.0",
  authors: ["Your Name"],
  adapters: [
    {
      id: "my-adapter",
      adapterIdentifierFactory: async (_configDirectory: string) => ({
        id: "my-adapter",
        create: async () => new MyAdapterIdentifier(),
      }),
      moduleSystemFactory: async (repoRoot: string, _configDirectory: string) =>
        new MyModuleSystemFactory(repoRoot),
    },
  ],
};

export default myPlugin;

Publish the package with a name matching one of the discovery patterns (versu-plugin-*, @*/versu-plugin-*, @versu/plugin-*) so Versu can auto-detect it from node_modules, or reference it explicitly in the plugins array of your configuration.

See @versu/plugin-gradle for a complete implementation example.

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

• @versu/cli - Command-line interface
• @versu/action - GitHub Actions integration
• @versu/plugin-gradle - Gradle adapter plugin

Requirements

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

License

MIT License - see LICENSE for details.