/**
 * Find Project Root Utility
 *
 * CRITICAL: This utility finds the SpecWeave project root by searching for .specweave directory.
 * Use this instead of process.cwd() when the working directory may not be the project root.
 *
 * Common scenarios where CWD != project root:
 * - Hooks executed from parent directory
 * - CI/CD pipelines with different working directories
 * - Background jobs spawned from different locations
 * - Multi-repo setups where scripts run from umbrella root
 *
 * @module utils/find-project-root
 */
/**
 * Find project root by searching for .specweave/config.json
 *
 * Walks up the directory tree from startDir until it finds a directory
 * containing .specweave/config.json. Requires config.json to distinguish
 * real projects from stale .specweave/ folders (created by runtime bugs).
 *
 * @param startDir - Directory to start searching from (defaults to process.cwd())
 * @returns Project root path or null if not found
 *
 * @example
 * // From /projects/my-app/src/components
 * findProjectRoot()
 * // Returns: "/projects/my-app" (if .specweave/config.json exists there)
 *
 * @example
 * // No .specweave/config.json found anywhere in tree
 * findProjectRoot()
 * // Returns: null
 */
export declare function findProjectRoot(startDir?: string): string | null;
/**
 * Get project root, falling back to CWD if not found
 *
 * This is the RECOMMENDED function to use in most cases.
 * It returns a valid path even if .specweave doesn't exist.
 *
 * NOTE: This returns the NEAREST project root (for config reading).
 * For increment operations in multi-repo setups, use resolveEffectiveRoot()
 * which returns the umbrella root.
 *
 * @param startDir - Directory to start searching from (defaults to process.cwd())
 * @returns Project root path or process.cwd() if not found
 *
 * @example
 * // .specweave exists
 * getProjectRoot() // Returns: "/projects/my-app"
 *
 * // .specweave doesn't exist
 * getProjectRoot() // Returns: process.cwd() (e.g., "/projects/my-app")
 */
export declare function getProjectRoot(startDir?: string): string;
/**
 * Check if current directory is within a SpecWeave project
 *
 * @param startDir - Directory to check (defaults to process.cwd())
 * @returns true if .specweave directory exists in tree
 */
export declare function isInsideSpecWeaveProject(startDir?: string): boolean;
/**
 * Check if a directory has an initialized SpecWeave project with actual increments.
 *
 * A repo is considered "initialized" only when `.specweave/increments/` exists
 * and contains at least one non-hidden entry. A `.specweave/` folder with just
 * logs, state, or config is NOT considered initialized.
 *
 * @param dir - Directory to check (the repo root, not .specweave/ itself)
 * @returns true if the directory has .specweave/increments/ with content
 */
export declare function hasSpecweaveIncrements(dir: string): boolean;
/**
 * Find the umbrella root by walking up from the nearest project root.
 *
 * In a multi-repo umbrella project, nested repos each have their own
 * .specweave/config.json, but the umbrella root is the TOPMOST one
 * with `umbrella.enabled: true` or a sibling `repositories/` directory.
 *
 * @param startDir - Directory to start searching from (defaults to process.cwd())
 * @returns Umbrella root path or null if not inside an umbrella project
 */
export declare function findUmbrellaRoot(startDir?: string): string | null;
/**
 * Resolve the effective project root for increment operations.
 *
 * - In a multi-repo umbrella: returns the umbrella root (increments belong there)
 * - In a single-repo project: returns the nearest project root
 * - Fallback: returns process.cwd()
 *
 * @param startDir - Directory to start searching from (defaults to process.cwd())
 * @returns Effective project root path
 */
export declare function resolveEffectiveRoot(startDir?: string): string;
/**
 * Get the umbrella-aware .specweave directory path.
 *
 * Uses resolveEffectiveRoot() to find the correct root — returns the
 * umbrella root's .specweave/ when inside an umbrella workspace, or
 * the nearest project root's .specweave/ in standalone mode.
 *
 * This is the RECOMMENDED function for code that writes to .specweave/.
 * Unlike getSpecWeaveDir() which uses findProjectRoot() (nearest root,
 * returns null), this always returns a valid path.
 *
 * @param startDir - Directory to start searching from (defaults to process.cwd())
 * @returns Absolute path to the effective .specweave directory
 */
export declare function getSpecweavePath(startDir?: string): string;
/**
 * Get SpecWeave directory path (.specweave folder)
 *
 * @param projectRoot - Project root (will search if not provided)
 * @returns Path to .specweave directory or null if not found
 */
export declare function getSpecWeaveDir(projectRoot?: string): string | null;
/**
 * Resolve a path relative to project root
 *
 * Useful for constructing paths that should be relative to project root,
 * not the current working directory.
 *
 * @param relativePath - Path relative to project root
 * @param startDir - Directory to start search from (defaults to process.cwd())
 * @returns Resolved absolute path or null if project root not found
 *
 * @example
 * // From any subdirectory
 * resolveFromProjectRoot('.specweave/config.json')
 * // Returns: "/projects/my-app/.specweave/config.json"
 */
export declare function resolveFromProjectRoot(relativePath: string, startDir?: string): string | null;
//# sourceMappingURL=find-project-root.d.ts.map