import type { Document } from "yaml";
import type { ResolvedParamSet } from "./types.js";
/**
 * Collapse `$${` directly to `${`, used when the AST interpolator is skipped
 * (no placeholders to resolve) but escapes must still be honored so the literal
 * `${` reaches the loaded spec instead of a stray `$${`.
 */
export declare function collapseEscapes(text: string): string;
/**
 * Strip YAML comments from raw text. Replaces comment content (from `#` to
 * end of line) with spaces so that downstream regex position math is
 * unaffected while ensuring placeholders inside comments are not matched.
 *
 * Uses the yaml library's parser to identify block-scalar and quoted-string
 * ranges where `#` is literal content (not a comment).
 */
export declare function stripYamlComments(text: string): string;
/** A half-open [start, end) range representing a comment span in the text. */
interface CommentRange {
    start: number;
    end: number;
}
/**
 * Find all `${KEY}` placeholder references in a string.
 * Returns the set of param names referenced (without defaults).
 *
 * Only scans non-comment portions of the YAML text — placeholders inside
 * YAML comments (`# ...`) are intentionally ignored so that commented-out
 * references do not expand the matrix.
 */
export declare function findPlaceholders(text: string): Set<string>;
/**
 * Returns true if a param value can be safely injected as a bare YAML scalar
 * without quoting.
 */
export declare function isYamlSafeValue(value: string): boolean;
/** Information tracked per placeholder occurrence. */
interface PlaceholderEntry {
    key: string;
    defaultVal: string | undefined;
    sentinel: string;
}
/**
 * Pre-computed state derived from the raw YAML text only. Reuse this across
 * multiple `interpolateWithContext` calls when expanding a matrix of param
 * combinations over the same template text.
 */
export interface PreparedInterpolation {
    text: string;
    /** Parsed document with sentinel tokens in place of placeholders. */
    document: Document;
    /** Map from sentinel index to placeholder entry. */
    entries: PlaceholderEntry[];
    /** Whether the original text ended with a newline. */
    trailingNewline: boolean;
    /** Pre-computed comment ranges for position checks. */
    commentRanges: CommentRange[];
    /** Nonce used for sentinel tokens in this interpolation. */
    nonce: string;
    /** The sentinel prefix for this interpolation (includes nonce). */
    sentinelPrefix: string;
    /** Whether the source text contained `$${` escape sequences. */
    hasEscapes: boolean;
}
/**
 * Pre-compute text-dependent analysis (comment ranges, placeholder mapping,
 * YAML AST parse) once, so it can be reused across many
 * `interpolateWithContext` calls for different param combinations.
 *
 * @param text - Raw YAML string with placeholders
 * @returns Prepared interpolation context
 * @throws Error if malformed `${…}` placeholders are found
 */
export declare function prepareInterpolation(text: string): PreparedInterpolation;
/**
 * Interpolate a pre-analyzed template with a specific set of resolved params.
 * Use with `prepareInterpolation` for efficient matrix expansion.
 *
 * @param ctx - Pre-computed interpolation context from `prepareInterpolation`
 * @param resolved - Resolved param values for this combination
 * @returns Interpolated YAML string
 * @throws Error listing all unresolved placeholders
 */
export declare function interpolateWithContext(ctx: PreparedInterpolation, resolved: ResolvedParamSet): string;
/**
 * Resolve all `${KEY}` placeholders in a raw YAML string.
 *
 * - If a param is defined in `resolved`, its value is substituted.
 * - If a param has an inline default (`${FOO=bar}`) and is NOT
 *   in `resolved`, the default is used.
 * - If a param is neither defined nor has a default, an error is thrown.
 *
 * Values are substituted through the YAML AST, so all quoting and escaping
 * is handled correctly by the `yaml` library — no manual quote detection.
 *
 * @param text - Raw YAML string with placeholders
 * @param resolved - Resolved param values for this combination
 * @returns Interpolated YAML string
 * @throws Error listing all unresolved placeholders
 */
export declare function interpolateParams(text: string, resolved: ResolvedParamSet): string;
/**
 * Check whether a raw YAML string contains any `${KEY}` placeholders
 * (valid or malformed) in non-comment portions.
 */
export declare function hasParamPlaceholders(text: string): boolean;
export {};
//# sourceMappingURL=interpolate.d.ts.map