/**
 * Docs Folder Numbering Collision Prevention
 *
 * Prevents duplicate numbered folder prefixes in user documentation folders.
 * Supports both 2-digit (NN) and 3-digit (NNN) patterns:
 * - 2-digit: 01-platform, 02-architecture (default range 1-98, 99 reserved)
 * - 3-digit: 001-platform, 100-advanced (extended range)
 *
 * @module utils/docs-folder-numbering
 */
/**
 * Options for docs folder number utilities
 */
export interface DocsFolderNumberOptions {
    /** Starting number to search from (default: 1) */
    startFrom?: number;
    /** Maximum number to search up to (default: 98, reserves 99 for archive) */
    maxNumber?: number;
    /** Whether to find gaps in sequence (default: true) */
    findGaps?: boolean;
}
/**
 * Error thrown when all available folder number slots are exhausted
 */
export declare class DocsNumberingOverflowError extends Error {
    constructor(startFrom: number, maxNumber: number);
}
/**
 * Get all used folder number prefixes in a docs directory
 *
 * Scans the directory for folders matching the NN-name pattern
 * and returns a Set of the numeric prefixes in use.
 *
 * @param docsPath - Path to the docs directory
 * @returns Set of used numeric prefixes
 *
 * @example
 * ```typescript
 * // If docs/ contains: 01-platform, 02-architecture, 04-deployment
 * const used = getUsedDocsFolderNumbers('/path/to/docs');
 * // Returns: Set([1, 2, 4])
 * ```
 */
export declare function getUsedDocsFolderNumbers(docsPath: string): Set<number>;
/**
 * Get the next available folder number prefix
 *
 * Finds the next available number for a new docs folder,
 * either by finding a gap in the sequence or returning max + 1.
 *
 * @param docsPath - Path to the docs directory
 * @param options - Configuration options
 * @returns Next available number
 * @throws {DocsNumberingOverflowError} When all slots from startFrom to maxNumber are used
 *
 * @example
 * ```typescript
 * // If docs/ contains: 01-platform, 02-architecture, 04-deployment
 * const next = getNextAvailableDocsFolderNumber('/path/to/docs');
 * // Returns: 3 (finds the gap)
 *
 * // If docs/ contains: 01-platform, 02-architecture, 03-development
 * const next = getNextAvailableDocsFolderNumber('/path/to/docs');
 * // Returns: 4 (next sequential)
 * ```
 */
export declare function getNextAvailableDocsFolderNumber(docsPath: string, options?: DocsFolderNumberOptions): number;
/**
 * Check if a specific folder number prefix would cause a collision
 *
 * @param docsPath - Path to the docs directory
 * @param number - Number prefix to check (1-99)
 * @returns true if the number is already in use
 *
 * @example
 * ```typescript
 * // If docs/ contains: 01-platform
 * hasDocsFolderCollision('/path/to/docs', 1);  // true
 * hasDocsFolderCollision('/path/to/docs', 2);  // false
 * ```
 */
export declare function hasDocsFolderCollision(docsPath: string, number: number): boolean;
/**
 * Format a folder number as a two-digit prefix
 *
 * @param number - Number to format (1-99)
 * @returns Two-digit string (e.g., "01", "12")
 *
 * @example
 * ```typescript
 * formatDocsFolderNumber(1);   // "01"
 * formatDocsFolderNumber(12);  // "12"
 * ```
 */
export declare function formatDocsFolderNumber(number: number): string;
/**
 * Generate a safe folder name with the next available number
 *
 * Combines collision detection with folder name generation.
 *
 * @param docsPath - Path to the docs directory
 * @param name - Folder name without number prefix
 * @param options - Configuration options
 * @returns Full folder name with unique number prefix
 *
 * @example
 * ```typescript
 * // If docs/ contains: 01-platform, 02-architecture
 * generateSafeDocsFolderName('/path/to/docs', 'development');
 * // Returns: "03-development"
 * ```
 */
export declare function generateSafeDocsFolderName(docsPath: string, name: string, options?: DocsFolderNumberOptions): string;
/**
 * Detect all folder number collisions in a docs directory
 *
 * Scans for multiple folders sharing the same numeric prefix.
 *
 * @param docsPath - Path to the docs directory
 * @returns Map of colliding number to array of folder names
 *
 * @example
 * ```typescript
 * // If docs/ contains: 04-deployment, 04-workflows (collision!)
 * const collisions = detectDocsFolderCollisions('/path/to/docs');
 * // Returns: Map { 4 => ['04-deployment', '04-workflows'] }
 * ```
 */
export declare function detectDocsFolderCollisions(docsPath: string): Map<number, string[]>;
//# sourceMappingURL=docs-folder-numbering.d.ts.map