@hyperfrontend/versioning 0.1.0 → 0.3.0

package/repository/models/platform.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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}`
+ */
+export type KnownPlatform = 'github' | 'gitlab' | 'bitbucket' | 'azure-devops';
+/**
+ * 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)
+ */
+export type RepositoryPlatform = KnownPlatform | 'custom' | 'unknown';
+/**
+ * Checks if a platform identifier is a known platform with built-in support.
+ *
+ * @param platform - Platform identifier to check
+ * @returns True if the platform is a known platform
+ *
+ * @example
+ * ```typescript
+ * isKnownPlatform('github')     // true
+ * isKnownPlatform('gitlab')     // true
+ * isKnownPlatform('custom')     // false
+ * isKnownPlatform('unknown')    // false
+ * ```
+ */
+export declare function isKnownPlatform(platform: RepositoryPlatform): platform is KnownPlatform;
+/**
+ * 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.
+ */
+export declare const PLATFORM_HOSTNAMES: ReadonlyMap<string, KnownPlatform>;
+/**
+ * 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`).
+ *
+ * @param hostname - Hostname to detect platform from (e.g., "github.com")
+ * @returns Detected platform or 'unknown' if not recognized
+ *
+ * @example
+ * ```typescript
+ * detectPlatformFromHostname('github.com')           // 'github'
+ * detectPlatformFromHostname('gitlab.mycompany.com') // 'gitlab'
+ * detectPlatformFromHostname('custom-git.internal')  // 'unknown'
+ * ```
+ */
+export declare function detectPlatformFromHostname(hostname: string): RepositoryPlatform;
+//# sourceMappingURL=platform.d.ts.map

package/repository/models/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/versioning/src/repository/models/platform.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,cAAc,CAAA;AAE9E;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAA;AAErE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,kBAAkB,GAAG,QAAQ,IAAI,aAAa,CAEvF;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAahE,CAAA;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAoC/E"}

package/repository/models/repository-config.d.ts

@@ -0,0 +1,132 @@
+import type { RepositoryPlatform } from './platform';
+/**
+ * Custom compare URL formatter function.
+ *
+ * @param fromCommit - The source commit hash for comparison (older version)
+ * @param toCommit - The target commit hash for comparison (newer version)
+ * @returns Full compare URL string
+ *
+ * @example
+ * ```typescript
+ * const formatter: CompareUrlFormatter = (from, to) =>
+ *   `https://my-git.internal/diff/${from}/${to}`
+ * ```
+ */
+export type CompareUrlFormatter = (fromCommit: string, toCommit: string) => string;
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * // GitHub repository
+ * const github: RepositoryConfig = {
+ *   platform: 'github',
+ *   baseUrl: 'https://github.com/owner/repo'
+ * }
+ *
+ * // Self-hosted GitLab
+ * const gitlabSelfHosted: RepositoryConfig = {
+ *   platform: 'gitlab',
+ *   baseUrl: 'https://gitlab.mycompany.com/team/project'
+ * }
+ *
+ * // Custom platform with formatter
+ * const custom: RepositoryConfig = {
+ *   platform: 'custom',
+ *   baseUrl: 'https://custom-git.internal/repo',
+ *   formatCompareUrl: (from, to) => `https://custom-git.internal/diff/${from}/${to}`
+ * }
+ * ```
+ */
+export interface RepositoryConfig {
+    /**
+     * Platform type - determines URL format for known platforms.
+     */
+    readonly platform: RepositoryPlatform;
+    /**
+     * Base URL for the repository.
+     *
+     * This is the URL without any trailing slashes or paths like `/compare`.
+     *
+     * @example
+     * - GitHub: `"https://github.com/owner/repo"`
+     * - GitLab: `"https://gitlab.com/group/project"`
+     * - Azure DevOps: `"https://dev.azure.com/org/project/_git/repo"`
+     */
+    readonly baseUrl: string;
+    /**
+     * 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 formatCompareUrl?: CompareUrlFormatter;
+}
+/**
+ * Options for creating a repository config.
+ */
+export interface CreateRepositoryConfigOptions {
+    /**
+     * Platform type - determines URL format for known platforms.
+     */
+    readonly platform: RepositoryPlatform;
+    /**
+     * Base URL for the repository.
+     * Trailing slashes will be automatically stripped.
+     */
+    readonly baseUrl: string;
+    /**
+     * Custom compare URL formatter.
+     * Required when platform is 'custom'.
+     */
+    readonly formatCompareUrl?: CompareUrlFormatter;
+}
+/**
+ * Creates a new RepositoryConfig.
+ *
+ * Normalizes the base URL by stripping trailing slashes and validating
+ * that custom platforms have a formatter function.
+ *
+ * @param options - Repository configuration options
+ * @returns A new RepositoryConfig object
+ * @throws {Error} if platform is 'custom' but no formatCompareUrl is provided
+ *
+ * @example
+ * ```typescript
+ * // 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}`
+ * })
+ * ```
+ */
+export declare function createRepositoryConfig(options: CreateRepositoryConfigOptions): RepositoryConfig;
+/**
+ * Checks if a value is a RepositoryConfig object.
+ *
+ * @param value - Value to check
+ * @returns True if the value is a RepositoryConfig
+ *
+ * @example
+ * ```typescript
+ * const config = { platform: 'github', baseUrl: 'https://...' }
+ * if (isRepositoryConfig(config)) {
+ *   // config is typed as RepositoryConfig
+ * }
+ * ```
+ */
+export declare function isRepositoryConfig(value: unknown): value is RepositoryConfig;
+//# sourceMappingURL=repository-config.d.ts.map

package/repository/models/repository-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-config.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/versioning/src/repository/models/repository-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAGpD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAA;IAErC;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,mBAAmB,CAAA;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAA;IAErC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,mBAAmB,CAAA;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,gBAAgB,CAgB/F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAY5E"}

package/repository/models/resolution.d.ts

@@ -0,0 +1,121 @@
+import type { RepositoryConfig } from './repository-config';
+/**
+ * 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)
+ */
+export type RepositoryResolutionMode = 'explicit' | 'inferred' | 'disabled';
+/**
+ * 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`
+ */
+export type RepositoryInferenceSource = 'package-json' | 'git-remote';
+/**
+ * Full repository resolution configuration.
+ *
+ * Provides fine-grained control over repository resolution behavior.
+ *
+ * @example
+ * ```typescript
+ * // Explicit configuration - must provide repository
+ * const explicit: RepositoryResolution = {
+ *   mode: 'explicit',
+ *   repository: {
+ *     platform: 'github',
+ *     baseUrl: 'https://github.com/owner/repo'
+ *   }
+ * }
+ *
+ * // Auto-detection with custom order
+ * const inferred: RepositoryResolution = {
+ *   mode: 'inferred',
+ *   inferenceOrder: ['git-remote', 'package-json']  // Try git first
+ * }
+ *
+ * // Disabled
+ * const disabled: RepositoryResolution = {
+ *   mode: 'disabled'
+ * }
+ * ```
+ */
+export interface RepositoryResolution {
+    /**
+     * Resolution mode.
+     */
+    readonly mode: RepositoryResolutionMode;
+    /**
+     * Explicit repository config.
+     *
+     * Required when `mode` is `'explicit'`.
+     * Ignored when `mode` is `'inferred'` or `'disabled'`.
+     */
+    readonly repository?: RepositoryConfig;
+    /**
+     * Inference source order when `mode` is `'inferred'`.
+     *
+     * Sources are tried in order until one succeeds.
+     * Default: `['package-json', 'git-remote']`
+     */
+    readonly inferenceOrder?: readonly RepositoryInferenceSource[];
+}
+/**
+ * Creates a disabled repository resolution configuration.
+ *
+ * No compare URLs will be generated.
+ *
+ * @returns A RepositoryResolution with mode 'disabled'
+ *
+ * @example
+ * ```typescript
+ * const config = createDisabledResolution()
+ * // { mode: 'disabled' }
+ * ```
+ */
+export declare function createDisabledResolution(): RepositoryResolution;
+/**
+ * Creates an explicit repository resolution configuration.
+ *
+ * @param repository - The repository config to use
+ * @returns A RepositoryResolution with mode 'explicit'
+ *
+ * @example
+ * ```typescript
+ * const config = createExplicitResolution({
+ *   platform: 'github',
+ *   baseUrl: 'https://github.com/owner/repo'
+ * })
+ * ```
+ */
+export declare function createExplicitResolution(repository: RepositoryConfig): RepositoryResolution;
+/**
+ * Creates an inferred repository resolution configuration.
+ *
+ * @param inferenceOrder - Order to try inference sources (default: package-json first)
+ * @returns A RepositoryResolution with mode 'inferred'
+ *
+ * @example
+ * ```typescript
+ * // Default order: package.json → git remote
+ * const config = createInferredResolution()
+ *
+ * // Custom order: git remote → package.json
+ * const customOrder = createInferredResolution(['git-remote', 'package-json'])
+ * ```
+ */
+export declare function createInferredResolution(inferenceOrder?: readonly RepositoryInferenceSource[]): RepositoryResolution;
+/**
+ * Checks if a value is a RepositoryResolution object.
+ *
+ * @param value - Value to check
+ * @returns True if the value is a RepositoryResolution
+ */
+export declare function isRepositoryResolution(value: unknown): value is RepositoryResolution;
+/**
+ * Default inference order when mode is 'inferred'.
+ */
+export declare const DEFAULT_INFERENCE_ORDER: readonly RepositoryInferenceSource[];
+//# sourceMappingURL=resolution.d.ts.map

package/repository/models/resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/versioning/src/repository/models/resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAE3D;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAA;AAE3E;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,cAAc,GAAG,YAAY,CAAA;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAA;IAEvC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAA;IAEtC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAA;CAC/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,IAAI,oBAAoB,CAE/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,gBAAgB,GAAG,oBAAoB,CAK3F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,GAAE,SAAS,yBAAyB,EAAmC,GACpF,oBAAoB,CAKtB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,oBAAoB,CASpF;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,yBAAyB,EAAmC,CAAA"}