/**
 * Calendar version parsing, formatting, and comparison helpers.
 *
 * @remarks
 * Supports the full calver.org specification with all standard tokens:
 * Year (`YYYY`, `YY`, `0Y`), Month (`MM`, `M`, `0M`), Week (`WW`, `0W`),
 * Day (`DD`, `D`, `0D`), and Counter (`MICRO`/`PATCH`).
 *
 * `MICRO` is the CalVer-standard name for the counter segment.
 * `PATCH` is accepted as a SemVer-familiar alias and behaves identically.
 *
 * @packageDocumentation
 */
import type { CalVer, CalVerFormat, SchemeRules, ValidationResult } from './types';
/**
 * Validates that a CalVer format string is composed of valid tokens
 * and follows structural rules.
 *
 * @remarks
 * Structural rules enforced:
 * - Must have at least 2 segments
 * - First segment must be a year token
 * - Week tokens and Month/Day tokens are mutually exclusive
 * - Counter (MICRO/PATCH) can only appear as the last segment
 *
 * @param formatStr - Format string to validate.
 * @returns `true` when the format is valid.
 *
 * @example
 * ```ts
 * import { isValidCalVerFormat } from 'versionguard';
 *
 * isValidCalVerFormat('YYYY.MM.MICRO'); // true
 * isValidCalVerFormat('INVALID');        // false
 * ```
 *
 * @public
 * @since 0.3.0
 */
export declare function isValidCalVerFormat(formatStr: string): formatStr is CalVerFormat;
/**
 * Parsed token layout for a supported CalVer format string.
 *
 * @public
 * @since 0.1.0
 * @forgeIgnore E020
 */
export interface ParsedCalVerFormat {
    /**
     * Year token captured from the format string.
     */
    year: 'YYYY' | 'YY' | '0Y';
    /**
     * Month token captured from the format string when present.
     *
     * @defaultValue undefined
     */
    month?: 'MM' | 'M' | '0M';
    /**
     * Week token captured from the format string when present.
     *
     * @defaultValue undefined
     */
    week?: 'WW' | '0W';
    /**
     * Day token captured from the format string when present.
     *
     * @defaultValue undefined
     */
    day?: 'DD' | 'D' | '0D';
    /**
     * Counter token captured from the format string when present.
     * Both `MICRO` and `PATCH` map to the same numeric counter.
     *
     * @defaultValue undefined
     */
    counter?: 'MICRO' | 'PATCH';
}
/**
 * Breaks a CalVer format string into its component tokens.
 *
 * @remarks
 * This helper is used internally by parsing, formatting, and version generation helpers
 * to decide which date parts or counters are present in a given CalVer layout.
 *
 * @param calverFormat - Format string to inspect.
 * @returns The parsed token definition for the requested format.
 *
 * @example
 * ```ts
 * import { parseFormat } from 'versionguard';
 *
 * parseFormat('YYYY.MM.MICRO');
 * // => { year: 'YYYY', month: 'MM', counter: 'MICRO' }
 * ```
 *
 * @public
 * @since 0.1.0
 */
export declare function parseFormat(calverFormat: CalVerFormat): ParsedCalVerFormat;
/**
 * Builds a regular expression that matches a supported CalVer format.
 *
 * @remarks
 * The returned regular expression is anchored to the start and end of the string so it can
 * be used directly for strict validation of a complete version value.
 *
 * @param calverFormat - Format string to convert into a regular expression.
 * @returns A strict regular expression for the supplied CalVer format.
 *
 * @example
 * ```ts
 * import { getRegexForFormat } from 'versionguard';
 *
 * getRegexForFormat('YYYY.0M.0D').test('2026.03.21');
 * // => true
 * ```
 *
 * @public
 * @since 0.1.0
 */
export declare function getRegexForFormat(calverFormat: CalVerFormat): RegExp;
/**
 * Parses a CalVer string using the supplied format.
 *
 * @remarks
 * The parser returns `null` when the string does not structurally match the requested format.
 * It does not enforce range rules such as future-date rejection; use {@link validate} for that.
 *
 * @param version - Version string to parse.
 * @param calverFormat - Format expected for the version string.
 * @returns Parsed CalVer components, or `null` when the string does not match the format.
 *
 * @example
 * ```ts
 * import { parse } from 'versionguard';
 *
 * parse('2026.3.0', 'YYYY.M.MICRO')?.month;
 * // => 3
 * ```
 *
 * @see {@link validate} to apply date-range and future-date validation.
 * @public
 * @since 0.1.0
 */
export declare function parse(version: string, calverFormat: CalVerFormat): CalVer | null;
/**
 * Validates a CalVer string against formatting and date rules.
 *
 * @remarks
 * Validation checks the requested CalVer format, month and day ranges, and optionally rejects
 * future dates relative to the current system date.
 *
 * @param version - Version string to validate.
 * @param calverFormat - Format expected for the version string.
 * @param preventFutureDates - Whether future dates should be reported as errors.
 * @param schemeRules - Optional scheme rules for modifier validation and segment count warnings.
 * @returns A validation result containing any discovered errors and the parsed version on success.
 *
 * @example
 * ```ts
 * import { validate } from 'versionguard';
 *
 * validate('2026.3.0', 'YYYY.M.MICRO', false).valid;
 * // => true
 * ```
 *
 * @public
 * @since 0.1.0
 */
export declare function validate(version: string, calverFormat: CalVerFormat, preventFutureDates?: boolean, schemeRules?: SchemeRules): ValidationResult;
/**
 * Formats a parsed CalVer object back into a version string.
 *
 * @remarks
 * Missing `day` and `patch` values fall back to `1` and `0` respectively when the selected
 * format requires those tokens.
 *
 * @param version - Parsed CalVer value to serialize.
 * @returns The formatted CalVer string.
 *
 * @example
 * ```ts
 * import { format } from 'versionguard';
 *
 * const version = { year: 2026, month: 3, day: 21, format: 'YYYY.0M.0D', raw: '2026.03.21' };
 *
 * format(version);
 * // => '2026.03.21'
 * ```
 *
 * @public
 * @since 0.1.0
 */
export declare function format(version: CalVer): string;
/**
 * Creates the current CalVer string for a format.
 *
 * @remarks
 * This helper derives its values from the provided date and initializes any counter to `0`.
 * It is useful for generating a same-day baseline before incrementing counter-based formats.
 *
 * @param calverFormat - Format to generate.
 * @param now - Date used as the source for year, month, and day values.
 * @returns The current version string for the requested format.
 *
 * @example
 * ```ts
 * import { getCurrentVersion } from 'versionguard';
 *
 * getCurrentVersion('YYYY.M.MICRO', new Date('2026-03-21T00:00:00Z'));
 * // => '2026.3.0'
 * ```
 *
 * @public
 * @since 0.1.0
 */
export declare function getCurrentVersion(calverFormat: CalVerFormat, now?: Date): string;
/**
 * Compares two CalVer strings using a shared format.
 *
 * @remarks
 * Comparison is performed component-by-component in year, month, day, then counter order.
 * Missing day and counter values are treated as `0` during comparison.
 *
 * @param a - Left-hand version string.
 * @param b - Right-hand version string.
 * @param calverFormat - Format used to parse both versions.
 * @returns `1` when `a` is greater, `-1` when `b` is greater, or `0` when they are equal.
 *
 * @example
 * ```ts
 * import { compare } from 'versionguard';
 *
 * compare('2026.3.2', '2026.3.1', 'YYYY.M.MICRO');
 * // => 1
 * ```
 *
 * @public
 * @since 0.1.0
 */
export declare function compare(a: string, b: string, calverFormat: CalVerFormat): number;
/**
 * Increments a CalVer string.
 *
 * @remarks
 * Counter-based formats increment the existing counter. Formats without a counter are
 * promoted to a counter-based output by appending `.MICRO` with an initial value of `0`.
 *
 * @param version - Current version string.
 * @param calverFormat - Format used to parse the current version.
 * @returns The next version string.
 *
 * @example
 * ```ts
 * import { increment } from 'versionguard';
 *
 * increment('2026.3.1', 'YYYY.M.MICRO');
 * // => '2026.3.2'
 * ```
 *
 * @public
 * @since 0.1.0
 */
export declare function increment(version: string, calverFormat: CalVerFormat): string;
/**
 * Returns the most likely next CalVer candidates.
 *
 * @remarks
 * The first candidate is the version derived from the current date. The second candidate is the
 * incremented form of the supplied current version.
 *
 * @param currentVersion - Existing project version.
 * @param calverFormat - Format used to generate both candidates.
 * @returns Two candidate version strings ordered as current-date then incremented version.
 *
 * @example
 * ```ts
 * import { getNextVersions } from 'versionguard';
 *
 * getNextVersions('2026.3.1', 'YYYY.M.MICRO').length;
 * // => 2
 * ```
 *
 * @public
 * @since 0.1.0
 */
export declare function getNextVersions(currentVersion: string, calverFormat: CalVerFormat): string[];
//# sourceMappingURL=calver.d.ts.map