GenVer

A TypeScript library for handling automated versioning in applications, especially within Git workflows. This library provides utilities to parse branch names, generate branch filters, count merges, and generate release version strings based on the Git history and branch formats.

• Installation
• Usage
  • Branch Format Descriptor
  • Parsing Branch Names
  • Generating Branch Filters
  • Counting Merges
  • Determining Release Sub-Version
  • Generating Release Version String
• API Reference
  • Branch Utilities
  • Git Utilities
  • Version Utilities
• Testing
• Contributing
• License

Install the package via npm:

npm install trinoor_genver

Or via Yarn:

yarn add trinoor_genver

Import the necessary functions and types from the library:

import {
  parseBranch,
  generateBranchFilter,
  countMergesIntoCommit,
  determineReleaseSubVersion,
  generateReleaseVersionString,
} from 'trinoor_genver';

import type {
  BranchFormatDescriptor,
  BranchVersion,
  ReleaseSubVersion,
} from 'trinoor_genver';

Define a BranchFormatDescriptor to specify your branch naming conventions and mode overrides.

const branchFormatDescriptor: BranchFormatDescriptor = {
  gitFilterTemplate: 'v{{major}}.{{release}}.{{patch}}/{{mode}}',
  branchParserRegex: '^v(?<major>\\d )\\.(?<release>\\d )\\.(?<patch>\\d )/(?<mode>\\w )$',
  modeOverrides: {
    dev: 'dev',
    test: 'test',
    main: 'main',
  },
};

Use parseBranch to extract version information from a branch name.

const branchName = 'v1.0.0/dev';
const branchVersion: BranchVersion = parseBranch(branchName, branchFormatDescriptor);

console.log(branchVersion);
// Output:
// {
//   major: 1,
//   release: 0,
//   patch: 0,
//   mode: 'dev',
// }

Generate Git branch filters based on version components and modes.

const branchFilter = generateBranchFilter(branchFormatDescriptor, '*', '*', '*', 'dev');

console.log(branchFilter);
// Output: 'v*.*.*/dev'

Count the number of merges into a specific commit, which is useful for determining preview or release candidate numbers.

const dir = '/path/to/your/repo';
const mergeCount = await countMergesIntoCommit(dir, branchFormatDescriptor);

console.log(`Number of merges: ${mergeCount}`);

Determine the release sub-version (e.g., preview, release candidate, unversioned) based on the branch and commit.

const subVersion: ReleaseSubVersion = await determineReleaseSubVersion({
  dir,
  branchVersion,
  branchFormatDescriptor,
});

console.log(subVersion);
// Possible outputs:
// { type: 'preview', count: 2 }
// { type: 'releaseCandidate', count: 1 }
// { type: 'release' }
// { type: 'unversioned', hash: 'abc1234' }

Generate a full release version string incorporating the app name, version numbers, sub-version, and optional fork name.

const releaseVersion = generateReleaseVersionString({
  appName: 'myapp',
  branchVersion,
  subVersion,
  forkName: 'myfork', // Optional
});

console.log(releaseVersion);
// Possible outputs:
// 'myapp-v1.0.0-pre2-myfork'
// 'myapp-v1.0.0-rc1'
// 'myapp-v1.0.0'
// 'myapp-abc1234'

• BranchMode: Represents the mode of a branch. Possible values are 'dev', 'test', and 'main'.

  type BranchMode = 'dev' | 'test' | 'main';

• BranchFormatModeOverrides: Overrides for branch modes in the branch naming convention.

  interface BranchFormatModeOverrides {
    dev: string;
    test: string;
    main: string;
  }

• BranchFormatDescriptor: Describes the format of branches for parsing and generating branch names.

  interface BranchFormatDescriptor {
    gitFilterTemplate: string;
    modeOverrides: BranchFormatModeOverrides;
    branchParserRegex: string;
  }

• BranchFilterTemplateArgs: Arguments for the branch filter template.

  interface BranchFilterTemplateArgs {
    major: number | string;
    release: number | string;
    patch: number | string;
    mode: string;
  }

• BranchVersion: Contains version information extracted from a branch name.

  interface BranchVersion {
    major: number;
    release: number;
    patch: number;
    mode: BranchMode;
  }

• parseBranch(branch: string, descriptor: BranchFormatDescriptor): BranchVersion

  Parses a branch name and returns its version components.

• generateBranchFilter(descriptor: BranchFormatDescriptor, major: number | string, release: number | string, patch: number | string, mode: 'dev' | 'test' | 'main' | 'any'): string

  Generates a Git branch filter string based on the provided version components and mode.

• countMergesIntoCommit(dir: string, descriptor: BranchFormatDescriptor, commit?: string): Promise<number>

  Counts the number of merges into the specified commit.

• getCommitBranchVersionString(opts: GetCommitBranchVersionOpts): Promise<string | undefined>

  Retrieves the branch name associated with a specific commit.

• getCurrentCommitId(dir: string): Promise<string>

  Gets the hash of the current commit.

• getInitialCommitId(dir: string): Promise<string>

  Gets the hash of the initial commit in the repository.

• GetCommitBranchVersionOpts: Options for getting the branch version string of a commit.

  interface GetCommitBranchVersionOpts {
    dir: string;
    commit: string;
    branchFormatDescriptor: BranchFormatDescriptor;
  }

• ReleaseSubVersion: Represents the sub-version type and associated data.

  type ReleaseSubVersion =
    | { type: 'release' }
    | { type: 'preview' | 'releaseCandidate'; count: number }
    | { type: 'unversioned'; hash: string };

• GenerateReleaseVersionArgs: Arguments for determining the release sub-version.

  interface GenerateReleaseVersionArgs {
    dir: string;
    branchVersion: BranchVersion | undefined;
    commit?: string;
    branchFormatDescriptor: BranchFormatDescriptor;
  }

• GenerateReleaseVersionStringArgs: Arguments for generating the release version string.

  interface GenerateReleaseVersionStringArgs {
    branchVersion: BranchVersion | undefined;
    subVersion: ReleaseSubVersion;
    appName: string;
    forkName?: string;
  }

• determineReleaseSubVersion(args: GenerateReleaseVersionArgs): Promise<ReleaseSubVersion>

  Determines the sub-version type based on the branch and commit.

• generateReleaseSubVersionString(subVersion: ReleaseSubVersion): string

  Generates a sub-version string (e.g., 'pre2', 'rc1', or commit hash).

• generateReleaseVersionString(args: GenerateReleaseVersionStringArgs): string

  Generates the full release version string.

The library includes a comprehensive test suite to ensure functionality and reliability. The tests cover various scenarios, including:

• Parsing branch names.
• Generating branch filters.
• Counting merges.
• Determining previous branches.
• Generating release version strings.

To run the tests:

1. Clone the repository:

   git clone https://github.com/yourusername/trinoor_genver.git

2. Install dependencies:

   cd trinoor_genver
   npm install

3. Run the tests:

   npm test

The tests are written using Bun test runner. Ensure you have Bun installed to execute the tests.