@hyperfrontend/versioning/repository/models

models

Repository data models: platforms, configurations, and inference results.

RepositoryPlatform plus KnownPlatform, PLATFORM_HOSTNAMES, isKnownPlatform, and detectPlatformFromHostname cover the supported source-code platforms (GitHub, GitLab, Bitbucket, Azure DevOps). RepositoryConfig (built via createRepositoryConfig, validated via isRepositoryConfig) carries the platform, owner, repo name, and the CompareUrlFormatter that produces version-diff URLs. RepositoryResolution (with createDisabledResolution, createExplicitResolution, createInferredResolution) captures how a resolution was reached — explicitly configured, inferred from package.json, or deliberately disabled.

API Reference

ƒ Functions

§function

createDisabledResolution(): RepositoryResolution

Creates a disabled repository resolution configuration.
No compare URLs will be generated.

Returns

RepositoryResolution

A RepositoryResolution with mode 'disabled'

Example

Disabling repository resolution

const config = createDisabledResolution()
// { mode: 'disabled' }

§function

createExplicitResolution(repository: RepositoryConfig): RepositoryResolution

Creates an explicit repository resolution configuration.

Parameters

Name	Type	Description
§repository	`RepositoryConfig`	The repository config to use

Returns

RepositoryResolution

A RepositoryResolution with mode 'explicit'

Example

Using an explicit repository configuration

const config = createExplicitResolution({
  platform: 'github',
  baseUrl: 'https://github.com/owner/repo'
})

§function

createInferredResolution(inferenceOrder: unknown): RepositoryResolution

Creates an inferred repository resolution configuration.

Parameters

Name	Type	Description
§inferenceOrder	`unknown`	Order to try inference sources (default: package-json first) (default: `...`)

Returns

RepositoryResolution

A RepositoryResolution with mode 'inferred'

Example

Configuring inference order

// Default order: package.json → git remote
const config = createInferredResolution()

// Custom order: git remote → package.json
const customOrder = createInferredResolution(['git-remote', 'package-json'])

§function

createRepositoryConfig(options: CreateRepositoryConfigOptions): RepositoryConfig

Creates a new RepositoryConfig.
Normalizes the base URL by stripping trailing slashes and validating that custom platforms have a formatter function.

Parameters

Name	Type	Description
§options	`CreateRepositoryConfigOptions`	Repository configuration options

Returns

RepositoryConfig

A new RepositoryConfig object

Example

Creating repository configurations

// GitHub repository
const config = createRepositoryConfig({
  platform: 'github',
  baseUrl: 'https://github.com/owner/repo'
})

// Custom platform
const customConfig = createRepositoryConfig({
  platform: 'custom',
  baseUrl: 'https://my-git.internal/repo',
  formatCompareUrl: (from, to) => `https://my-git.internal/diff/${from}/${to}`
})

§function

detectPlatformFromHostname(hostname: string): RepositoryPlatform

Detects platform from a hostname.
First checks for exact match in known platforms, then applies heuristics for self-hosted instances (e.g., github.company.com → github).

Parameters

Name	Type	Description
§hostname	`string`	Hostname to detect platform from (e.g., "github.com")

Returns

RepositoryPlatform

Detected platform or 'unknown' if not recognized

Example

Detecting platform from hostname

detectPlatformFromHostname('github.com')           // 'github'
detectPlatformFromHostname('gitlab.mycompany.com') // 'gitlab'
detectPlatformFromHostname('custom-git.internal')  // 'unknown'

§function

isKnownPlatform(platform: RepositoryPlatform): unknown

Checks if a platform identifier is a known platform with built-in support.

Parameters

Name	Type	Description
§platform	`RepositoryPlatform`	Platform identifier to check

Returns

unknown

True if the platform is a known platform

Example

Checking if platform has built-in support

isKnownPlatform('github')     // true
isKnownPlatform('gitlab')     // true
isKnownPlatform('custom')     // false
isKnownPlatform('unknown')    // false

§function

isRepositoryConfig(value: unknown): unknown

Checks if a value is a RepositoryConfig object.

Parameters

Name	Type	Description
§value	`unknown`	Value to check

Returns

unknown

True if the value is a RepositoryConfig

Example

Type-checking repository config values

const config = { platform: 'github', baseUrl: 'https://...' }
if (isRepositoryConfig(config)) {
  // config is typed as RepositoryConfig
}

§function

isRepositoryResolution(value: unknown): unknown

Checks if a value is a RepositoryResolution object.

Parameters

Name	Type	Description
§value	`unknown`	Value to check

Returns

unknown

True if the value is a RepositoryResolution

Example

Type-checking resolution configurations

import { isRepositoryResolution } from '@hyperfrontend/versioning'

const config = loadConfig()
if (isRepositoryResolution(config.repository)) {
  console.log('Repository mode:', config.repository.mode)
}

◈ Interfaces

§interface

CreateRepositoryConfigOptions

Options for creating a repository config.

Properties

§readonly baseUrl:string—

Base URL for the repository. Trailing slashes will be automatically stripped.

§readonly formatCompareUrl?:CompareUrlFormatter—

Custom compare URL formatter. Required when platform is 'custom'.

§readonly platform:RepositoryPlatform—

Platform type - determines URL format for known platforms.

§interface

RepositoryConfig

Repository configuration for compare URL generation.
Supports both standard platforms and self-hosted instances. When using a known platform, compare URLs are generated automatically. For custom or unknown platforms, provide a formatCompareUrl function.

Properties

§readonly baseUrl:string—

Base URL for the repository.
This is the URL without any trailing slashes or paths like /compare.

§readonly formatCompareUrl?:CompareUrlFormatter—

Custom compare URL formatter.
Required when platform is 'custom'. Optional for known platforms (overrides built-in formatter).
Receives the from and to tags, returns the full compare URL.

§readonly platform:RepositoryPlatform—

Platform type - determines URL format for known platforms.

§interface

RepositoryResolution

Full repository resolution configuration.
Provides fine-grained control over repository resolution behavior.

Properties

§readonly inferenceOrder?:unknown—

Inference source order when mode is 'inferred'.
Sources are tried in order until one succeeds. Default: ['package-json', 'git-remote']

§readonly mode:RepositoryResolutionMode—

Resolution mode.

§readonly repository?:RepositoryConfig—

Explicit repository config.
Required when mode is 'explicit'. Ignored when mode is 'inferred' or 'disabled'.

◆ Types

§type

CompareUrlFormatter

Custom compare URL formatter function.

type CompareUrlFormatter = (fromCommit: string, toCommit: string) => string

§type

KnownPlatform

Known git hosting platforms with built-in compare URL support.
Each platform has a specific URL format for compare links:

github: {baseUrl}/compare/{fromCommit}...{toCommit}
gitlab: {baseUrl}/-/compare/{fromCommit}...{toCommit}
bitbucket: {baseUrl}/compare/{toCommit}..{fromCommit} (reversed order)
azure-devops: {baseUrl}/compare?version=GT{toCommit}&compareVersion=GT{fromCommit}

type KnownPlatform = "github" | "gitlab" | "bitbucket" | "azure-devops"

§type

RepositoryInferenceSource

Sources for repository inference, in order of preference.

package-json: Read from repository field in package.json
git-remote: Read from git remote get-url origin

type RepositoryInferenceSource = "package-json" | "git-remote"

§type

RepositoryPlatform

Platform identifier.

Known platforms have built-in compare URL formatters
custom requires a custom formatCompareUrl function
unknown indicates platform could not be determined (no URL generation)

type RepositoryPlatform = KnownPlatform | "custom" | "unknown"

§type

RepositoryResolutionMode

How to resolve repository information for compare URLs.

explicit: Use only the provided RepositoryConfig; error if missing
inferred: Auto-detect from package.json repository field or git remote
disabled: Do not generate compare URLs (default for backward compatibility)

type RepositoryResolutionMode = "explicit" | "inferred" | "disabled"

● Variables

§type

DEFAULT_INFERENCE_ORDER

Default inference order when mode is 'inferred'.

§type

PLATFORM_HOSTNAMES

Known platform hostnames mapped to their platform type. Used for automatic platform detection from repository URLs.
Includes both standard SaaS domains and common patterns for self-hosted instances.