import { Tree } from '../../_dependencies/@hyperfrontend/project-scope/vfs/index.js';
import { Workspace, Project } from '../models';
import { BumpType } from '../../semver/models';

/**
 * A planned version bump for a package.
 */
interface PlannedBump {
    /** Package name */
    readonly name: string;
    /** Current version */
    readonly currentVersion: string;
    /** Next version after bump */
    readonly nextVersion: string;
    /** Type of bump */
    readonly bumpType: BumpType;
    /** Reason for the bump */
    readonly reason: BumpReason;
    /** Packages that triggered this bump (for cascade bumps) */
    readonly triggeredBy: readonly string[];
}
/**
 * Reason for a version bump.
 */
type BumpReason = 'direct' | 'cascade' | 'sync';
/**
 * Options for cascade bump calculation.
 */
interface CascadeBumpOptions {
    /**
     * Bump type for cascaded dependents.
     * Default is 'patch' - dependents get a patch bump when their dependencies change.
     */
    cascadeBumpType?: BumpType;
    /**
     * Whether to include dev dependencies in cascade.
     * Default is false - only production dependencies trigger cascades.
     */
    includeDevDependencies?: boolean;
    /**
     * Whether to include peer dependencies in cascade.
     * Default is true - peer dependency updates should cascade.
     */
    includePeerDependencies?: boolean;
    /**
     * Custom prerelease identifier for prerelease bumps.
     */
    prereleaseId?: string;
}
/**
 * Default cascade bump options.
 */
declare const DEFAULT_CASCADE_OPTIONS: Required<CascadeBumpOptions>;
/**
 * Result of cascade bump calculation.
 */
interface CascadeBumpResult {
    /** All planned bumps, in topological order */
    readonly bumps: readonly PlannedBump[];
    /** Packages explicitly bumped (direct changes) */
    readonly directBumps: readonly PlannedBump[];
    /** Packages bumped due to cascading */
    readonly cascadeBumps: readonly PlannedBump[];
    /** Total number of packages affected */
    readonly totalAffected: number;
}
/**
 * Input for calculating cascade bumps.
 */
interface DirectBumpInput {
    /** Package name */
    name: string;
    /** Type of bump */
    bumpType: BumpType;
}
/**
 * Calculates cascade bumps for a workspace given direct bumps.
 *
 * When packages are directly bumped (e.g., due to commits), their dependents
 * may also need version bumps. This function calculates all affected packages.
 *
 * @param workspace - Workspace containing projects and dependency graph
 * @param directBumps - Packages with direct changes
 * @param options - Configuration for cascade bump calculation
 * @returns Cascade bump result
 *
 * @example Calculate cascade bumps for a workspace
 * ```typescript
 * import { calculateCascadeBumps } from '@hyperfrontend/versioning'
 *
 * // If lib-utils is getting a minor bump
 * const result = calculateCascadeBumps(workspace, [
 *   { name: 'lib-utils', bumpType: 'minor' }
 * ])
 *
 * // result.bumps includes lib-utils and all packages that depend on it
 * for (const bump of result.bumps) {
 *   console.log(`${bump.name}: ${bump.currentVersion} -> ${bump.nextVersion}`)
 * }
 * ```
 */
declare function calculateCascadeBumps(workspace: Workspace, directBumps: readonly DirectBumpInput[], options?: CascadeBumpOptions): CascadeBumpResult;
/**
 * Calculates cascade bumps starting from a single package.
 *
 * @param workspace - Workspace containing projects and dependency graph
 * @param packageName - Package with direct changes
 * @param bumpType - Type of bump for the direct change
 * @param options - Configuration for cascade behavior
 * @returns Cascade bump result
 *
 * @example Calculate cascade bumps from a single package
 * ```typescript
 * import { discoverWorkspace, calculateCascadeBumpsFromPackage } from '@hyperfrontend/versioning'
 *
 * const workspace = discoverWorkspace()
 * const result = calculateCascadeBumpsFromPackage(workspace, '@myorg/utils', 'minor')
 *
 * console.log(`${result.totalAffected} packages will be bumped`)
 * for (const bump of result.bumps) {
 *   console.log(`${bump.name}: ${bump.currentVersion} -> ${bump.nextVersion}`)
 * }
 * ```
 */
declare function calculateCascadeBumpsFromPackage(workspace: Workspace, packageName: string, bumpType: BumpType, options?: CascadeBumpOptions): CascadeBumpResult;
/**
 * Gets a summary of the cascade bump calculation.
 *
 * @param result - Result object from cascade bump calculation
 * @returns Human-readable summary
 *
 * @example Get a summary of cascade bump results
 * ```typescript
 * import { calculateCascadeBumps, summarizeCascadeBumps } from '@hyperfrontend/versioning'
 *
 * const result = calculateCascadeBumps(workspace, [{ name: '@myorg/utils', bumpType: 'patch' }])
 * console.log(summarizeCascadeBumps(result))
 * // Output:
 * // 3 package(s) affected:
 * //   - 1 direct bump(s)
 * //   - 2 cascade bump(s)
 * ```
 */
declare function summarizeCascadeBumps(result: CascadeBumpResult): string;

/**
 * Result of a batch update operation.
 */
interface BatchUpdateResult {
    /** Packages successfully updated */
    readonly updated: readonly UpdatedPackage[];
    /** Packages that failed to update */
    readonly failed: readonly FailedUpdate[];
    /** Total number of packages processed */
    readonly total: number;
    /** Whether all updates succeeded */
    readonly success: boolean;
}
/**
 * Information about a successfully updated package.
 */
interface UpdatedPackage {
    /** Package name */
    readonly name: string;
    /** Path to package.json */
    readonly packageJsonPath: string;
    /** Previous version */
    readonly previousVersion: string;
    /** New version */
    readonly newVersion: string;
}
/**
 * Information about a failed update.
 */
interface FailedUpdate {
    /** Package name */
    readonly name: string;
    /** Path to package.json */
    readonly packageJsonPath: string;
    /** Error message */
    readonly error: string;
}
/**
 * Options for batch update operations.
 */
interface BatchUpdateOptions {
    /** Whether to update dependency references in other packages */
    updateDependencyReferences?: boolean;
}
/**
 * Default batch update options.
 */
declare const DEFAULT_BATCH_UPDATE_OPTIONS: Required<BatchUpdateOptions>;
/**
 * Applies planned bumps to the workspace using the VFS Tree.
 * Updates package.json version fields for all affected packages.
 *
 * Changes are buffered in the tree until `commitChanges()` is called,
 * enabling atomic commits and rollback on failure.
 *
 * @param tree - Virtual file system tree for buffered operations
 * @param workspace - Workspace containing projects to update
 * @param bumps - Planned version bumps
 * @param options - Update options
 * @returns Batch update result
 *
 * @example Apply planned bumps to workspace using VFS Tree
 * ```typescript
 * import { createTree, commitChanges } from '@hyperfrontend/project-scope'
 * import { applyBumps, calculateCascadeBumps } from '@hyperfrontend/versioning'
 *
 * const tree = createTree(workspaceRoot)
 * const cascadeResult = calculateCascadeBumps(workspace, directBumps)
 * const updateResult = applyBumps(tree, workspace, cascadeResult.bumps)
 *
 * if (updateResult.success) {
 *   commitChanges(tree) // Atomic commit of all changes
 *   console.log(`Updated ${updateResult.updated.length} packages`)
 * } else {
 *   console.error('Some updates failed:', updateResult.failed)
 *   // No commitChanges() call - changes are discarded
 * }
 * ```
 */
declare function applyBumps(tree: Tree, workspace: Workspace, bumps: readonly PlannedBump[], options?: BatchUpdateOptions): BatchUpdateResult;
/**
 * Updates a package.json file using a VFS Tree.
 *
 * @param tree - Virtual file system tree
 * @param packageJsonPath - Relative path to package.json
 * @param newVersion - New version string
 * @throws {Error} If the file doesn't exist
 *
 * @example Update a package.json version using VFS Tree
 * ```typescript
 * import { updatePackageVersionInTree } from '@hyperfrontend/versioning'
 *
 * // Inside an Nx generator
 * export default function bumpVersion(tree: Tree) {
 *   updatePackageVersionInTree(tree, 'libs/my-lib/package.json', '2.0.0')
 * }
 * ```
 */
declare function updatePackageVersionInTree(tree: Tree, packageJsonPath: string, newVersion: string): void;
/**
 * Updates dependency version references in a package.json file using a VFS Tree.
 *
 * Uses the `changeFile()` pattern for cleaner transformation.
 * Silently skips if the file doesn't exist.
 *
 * @param tree - Virtual file system tree
 * @param packageJsonPath - Relative path to package.json
 * @param versionUpdates - Map of package name to new version
 *
 * @example Update dependency version references using VFS Tree
 * ```typescript
 * import { updateDependencyReferencesInTree } from '@hyperfrontend/versioning'
 *
 * // Inside an Nx generator
 * export default function syncDeps(tree: Tree) {
 *   const updates = new Map([
 *     ['@myorg/utils', '2.0.0'],
 *     ['@myorg/core', '3.1.0'],
 *   ])
 *
 *   updateDependencyReferencesInTree(tree, 'apps/my-app/package.json', updates)
 * }
 * ```
 */
declare function updateDependencyReferencesInTree(tree: Tree, packageJsonPath: string, versionUpdates: Map<string, string>): void;
/**
 * Creates a summary of the batch update result.
 *
 * @param result - Result object from batch update operation
 * @returns Human-readable summary
 *
 * @example Create a summary of the batch update result
 * ```typescript
 * import { batchUpdateVersions, summarizeBatchUpdate } from '@hyperfrontend/versioning'
 *
 * const result = batchUpdateVersions(workspace, updates)
 * console.log(summarizeBatchUpdate(result))
 * // Output:
 * // Successfully updated 3 package(s)
 * //
 * // Updated packages:
 * //   @myorg/utils: 1.0.0 -> 1.1.0
 * //   @myorg/core: 2.0.0 -> 2.1.0
 * ```
 */
declare function summarizeBatchUpdate(result: BatchUpdateResult): string;

/**
 * Validation result for a single check.
 */
interface ValidationResult {
    /** Whether the check passed */
    readonly valid: boolean;
    /** Error message if invalid */
    readonly error?: string;
    /** Warning message (valid but potentially problematic) */
    readonly warning?: string;
}
/**
 * Aggregated validation report.
 */
interface ValidationReport {
    /** All validation results */
    readonly results: readonly ValidationCheckResult[];
    /** Whether all checks passed */
    readonly valid: boolean;
    /** Total number of errors */
    readonly errorCount: number;
    /** Total number of warnings */
    readonly warningCount: number;
    /** Packages with validation errors */
    readonly invalidPackages: readonly string[];
}
/**
 * Result of a specific validation check.
 */
interface ValidationCheckResult {
    /** Check identifier */
    readonly checkId: string;
    /** Human-readable check name */
    readonly checkName: string;
    /** Package being checked (null for workspace-level checks) */
    readonly packageName: string | null;
    /** Check result */
    readonly result: ValidationResult;
}
/**
 * Validates a workspace for common issues.
 *
 * @param workspace - The workspace to validate
 * @returns Validation report
 *
 * @example Validate a workspace for common issues
 * ```typescript
 * import { validateWorkspace } from '@hyperfrontend/versioning'
 *
 * const report = validateWorkspace(workspace)
 *
 * if (!report.valid) {
 *   console.error(`${report.errorCount} error(s) found`)
 *   for (const result of report.results) {
 *     if (!result.result.valid) {
 *       console.error(`  ${result.checkName}: ${result.result.error}`)
 *     }
 *   }
 * }
 * ```
 */
declare function validateWorkspace(workspace: Workspace): ValidationReport;
/**
 * Validates a single project.
 *
 * @param project - The project to validate
 * @returns Validation result
 *
 * @example Validate a single project
 * ```typescript
 * import { discoverProject, validateProject } from '@hyperfrontend/versioning'
 *
 * const project = discoverProject('./libs/my-lib')
 * if (project) {
 *   const result = validateProject(project)
 *   if (!result.valid) {
 *     console.error('Validation failed:', result.error)
 *   }
 * }
 * ```
 */
declare function validateProject(project: Project): ValidationResult;
/**
 * Creates a summary of the validation report.
 *
 * @param report - Report object from workspace validation
 * @returns Human-readable summary
 *
 * @example Create a summary of the validation report
 * ```typescript
 * import { validateWorkspace, summarizeValidation } from '@hyperfrontend/versioning'
 *
 * const report = validateWorkspace(workspace)
 * console.log(summarizeValidation(report))
 * // Output:
 * // Workspace validation passed
 * //   2 warning(s)
 * ```
 */
declare function summarizeValidation(report: ValidationReport): string;

export { DEFAULT_BATCH_UPDATE_OPTIONS, DEFAULT_CASCADE_OPTIONS, applyBumps, calculateCascadeBumps, calculateCascadeBumpsFromPackage, summarizeBatchUpdate, summarizeCascadeBumps, summarizeValidation, updateDependencyReferencesInTree, updatePackageVersionInTree, validateProject, validateWorkspace };
export type { BatchUpdateOptions, BatchUpdateResult, BumpReason, CascadeBumpOptions, CascadeBumpResult, DirectBumpInput, FailedUpdate, PlannedBump, UpdatedPackage, ValidationCheckResult, ValidationReport, ValidationResult };