@hyperfrontend/versioning/repository/parse

parse

Parsers for repository URLs and package.json repository declarations.

parseRepositoryUrl recognizes the common URL shapes (HTTPS, SSH, git+https://, scoped paths) and returns a ParsedRepository carrying platform, owner, and repo. createRepositoryConfigFromUrl is the convenience wrapper that goes straight from a URL to a usable RepositoryConfig. inferRepositoryFromPackageJson and inferRepositoryFromPackageJsonObject read the repository field of a package.json (whether string or object form) and produce a config; extractRepositoryUrl is the lower-level helper that just returns the URL string.

API Reference

ƒ Functions

§function

createRepositoryConfigFromUrl(gitUrl: string): RepositoryConfig

Creates a RepositoryConfig from a git URL.
This is a convenience function that combines parseRepositoryUrl with createRepositoryConfig to produce a ready-to-use configuration.

Parameters

Name	Type	Description
§gitUrl	`string`	Git repository URL in any supported format

Returns

RepositoryConfig

RepositoryConfig or null if URL cannot be parsed

Example

Creating config from git URLs

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

const config = createRepositoryConfigFromUrl('git@gitlab.com:group/project.git')
// → { platform: 'gitlab', baseUrl: 'https://gitlab.com/group/project' }

§function

extractRepositoryUrl(packageJsonContent: string): string

Extracts the repository URL from package.json content.
Unlike inferRepositoryFromPackageJson, this returns just the URL string without creating a RepositoryConfig. Useful when you need the raw URL.

Parameters

Name	Type	Description
§packageJsonContent	`string`	Raw JSON string content of package.json

Returns

string

Repository URL string or null if not found

Example

Extracting raw repository URL

extractRepositoryUrl('{"repository": {"url": "https://github.com/owner/repo"}}')
// → 'https://github.com/owner/repo'

extractRepositoryUrl('{"repository": "github:owner/repo"}')
// → null (shorthand is not a URL)

§function

inferRepositoryFromPackageJson(packageJsonContent: string): RepositoryConfig

Infers repository configuration from package.json content.
Handles multiple formats:

Shorthand: "github:owner/repo", "gitlab:group/project", "bitbucket:team/repo"
Bare shorthand: "owner/repo" (defaults to GitHub)
URL string: "https://github.com/owner/repo"
Object with URL: { "type": "git", "url": "https://..." }

Parameters

Name	Type	Description
§packageJsonContent	`string`	Raw JSON string content of package.json

Returns

RepositoryConfig

RepositoryConfig or null if repository cannot be inferred

Example

Inferring repository from package.json content

// Shorthand format
inferRepositoryFromPackageJson('{"repository": "github:owner/repo"}')
// → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }

// URL string
inferRepositoryFromPackageJson('{"repository": "https://github.com/owner/repo"}')
// → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }

// Object format
inferRepositoryFromPackageJson('{"repository": {"type": "git", "url": "https://github.com/owner/repo"}}')
// → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }

// Bare shorthand (defaults to GitHub)
inferRepositoryFromPackageJson('{"repository": "owner/repo"}')
// → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }

§function

inferRepositoryFromPackageJsonObject(packageJson: PackageJsonForRepository): RepositoryConfig

Infers repository configuration from a parsed package.json object.
This is useful when you already have the parsed object.

Parameters

Name	Type	Description
§packageJson	`PackageJsonForRepository`	Parsed package.json object

Returns

RepositoryConfig

RepositoryConfig or null if repository cannot be inferred

Example

Inferring repository from parsed object

const pkg = { repository: 'github:owner/repo' }
inferRepositoryFromPackageJsonObject(pkg)
// → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }

§function

parseRepositoryUrl(gitUrl: string): ParsedRepository

Parses a git URL and extracts platform and base URL.
Supports multiple URL formats:

https://github.com/owner/repo
https://github.com/owner/repo.git
git+https://github.com/owner/repo.git
git://github.com/owner/repo.git
git@github.com:owner/repo.git (SSH format)

Handles self-hosted instances by detecting platform from hostname:

github.mycompany.com → github
gitlab.internal.com → gitlab

Handles Azure DevOps URL formats:

https://dev.azure.com/org/project/_git/repo
https://org.visualstudio.com/project/_git/repo

Parameters

Name	Type	Description
§gitUrl	`string`	Git repository URL in any supported format

Returns

ParsedRepository

Parsed repository info with platform and base URL, or null if parsing fails

Example

Parsing various git URL formats

// GitHub HTTPS
parseRepositoryUrl('https://github.com/owner/repo')
// → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }

// SSH format
parseRepositoryUrl('git@github.com:owner/repo.git')
// → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }

// Azure DevOps
parseRepositoryUrl('https://dev.azure.com/org/proj/_git/repo')
// → { platform: 'azure-devops', baseUrl: 'https://dev.azure.com/org/proj/_git/repo' }

// Self-hosted GitLab
parseRepositoryUrl('https://gitlab.mycompany.com/team/project')
// → { platform: 'gitlab', baseUrl: 'https://gitlab.mycompany.com/team/project' }

◈ Interfaces

§interface

PackageJsonForRepository

Minimal package.json structure for repository inference.

Properties

§readonly repository?:string | PackageJsonRepository—

Repository field - can be a string or object.

§interface

PackageJsonRepository

Repository field formats from package.json.
Package.json supports multiple formats for the repository field:

Shorthand: "github:owner/repo"
URL string: "https://github.com/owner/repo"
Object: { "type": "git", "url": "..." }

Properties

§readonly directory?:string—

Directory within the repository (for monorepos).

§readonly type?:string—

Repository type (typically "git").

§readonly url:string—

Repository URL.

§interface

ParsedRepository

Parsed repository information extracted from a git URL.

Properties

§readonly baseUrl:string—

Base URL for the repository (without trailing slashes or .git suffix).

§readonly platform:RepositoryPlatform—

Detected platform type.