import type { z } from 'zod';
import type { PluginSpecStore } from '#src/plugins/index.js';
import type { ProjectDefinition } from '#src/schema/project-definition.js';
import type { RefContextSlot } from './ref-context-slot.js';
import type { DefinitionEntityType, ReferencePath } from './types.js';
/**
 * Context provided to expression parsers during validation.
 * Contains the project definition data and plugin store needed for
 * validating expressions against model fields, roles, etc.
 */
export interface ExpressionValidationContext {
    /** The project definition data */
    readonly definition: ProjectDefinition;
    /** The plugin spec store for accessing plugin-registered configuration */
    readonly pluginStore: PluginSpecStore;
}
/**
 * Result of parsing a ref expression.
 * Success carries the parsed value; failure carries the error message.
 */
export type RefExpressionParseResult<T> = {
    success: true;
    value: T;
} | {
    success: false;
    error: string;
};
/**
 * A warning from validating a ref expression.
 * Warnings are non-blocking - they don't prevent loading the project definition.
 */
export interface RefExpressionWarning {
    /** Warning message */
    message: string;
    /** Path within the expression where the warning occurred */
    expressionPath?: string;
    /** Start position in the expression for inline highlighting */
    start?: number;
    /** End position in the expression for inline highlighting */
    end?: number;
}
/**
 * A dependency found in a ref expression.
 * Used for tracking which entities the expression references,
 * enabling rename handling.
 */
export interface RefExpressionDependency {
    /** The type of entity being referenced */
    entityType: DefinitionEntityType;
    /** The ID of the entity being referenced */
    entityId: string;
    /** Start position (inclusive) in the expression text to replace on rename */
    start: number;
    /** End position (exclusive) in the expression text to replace on rename */
    end: number;
}
/**
 * Slot map type for expressions - maps slot keys to RefContextSlot instances.
 * Similar to RefContextSlotMap but used for expression parser slots.
 */
export type ExpressionSlotMap<T extends Record<string, DefinitionEntityType> = Record<string, never>> = {
    [K in keyof T]: RefContextSlot<T[K]>;
};
/**
 * Resolved slot paths after slot resolution.
 * Maps slot keys to their resolved paths in the definition.
 */
export type ResolvedExpressionSlots<T extends Record<string, DefinitionEntityType> = Record<string, never>> = {
    [K in keyof T]: ReferencePath;
};
/**
 * A pluggable parser for ref expressions.
 *
 * The parser is format-agnostic - the core references system
 * doesn't know or care what format the expressions are in. The parser
 * handles all parsing, validation, and rename handling.
 *
 * Parsers can declare required slots via the TRequiredSlots generic parameter.
 * When a parser requires slots, TypeScript enforces that they are provided
 * when calling `withExpression()`.
 *
 * @typeParam TValue - The type of the raw expression value (e.g., string for TS expressions)
 * @typeParam TParseResult - The type of the parsed result (e.g., AST for TS expressions)
 * @typeParam TRequiredSlots - Record of required slot names to entity types
 *
 * @example
 * ```typescript
 * // A simple parser with no required slots
 * class StubParser extends RefExpressionParser<string, undefined> {
 *   readonly name = 'stub';
 *   parse(): undefined { return undefined; }
 *   getWarnings(): [] { return []; }
 *   getReferencedEntities(): [] { return []; }
 * }
 *
 * // A parser that requires a model slot
 * class AuthorizerParser extends RefExpressionParser<
 *   string,
 *   TsAst,
 *   { model: typeof modelEntityType }
 * > {
 *   readonly name = 'authorizer';
 *   // TypeScript enforces slot requirement in withExpression()
 * }
 * ```
 */
export declare abstract class RefExpressionParser<TValue = unknown, TParseResult = unknown, TRequiredSlots extends Record<string, DefinitionEntityType> = Record<string, never>> {
    /** Unique name for this parser type (used for serialization) */
    abstract readonly name: string;
    /**
     * Creates a new Zod schema instance for validating the expression value.
     *
     * @returns A fresh Zod schema that validates the raw expression value
     */
    abstract createSchema(): z.ZodType<TValue>;
    /**
     * Parse the raw value and return the parse result.
     * The result is cached on the marker for subsequent operations.
     *
     * @param value - The raw expression value
     * @param projectDef - The project definition for context
     * @returns Success with parsed value, or failure with error message
     */
    abstract parse(value: TValue, projectDef: ProjectDefinition): RefExpressionParseResult<TParseResult>;
    /**
     * Get validation warnings for a successfully parsed expression.
     * Only called when parse() succeeds. Parse failures are handled by validate().
     *
     * @param parseResult - The successfully parsed result
     * @param context - Validation context with project definition and plugin store
     * @param resolvedSlots - The resolved slot paths for this expression
     * @returns Array of warnings (empty if valid)
     */
    abstract getWarnings(parseResult: TParseResult, context: ExpressionValidationContext, resolvedSlots: ResolvedExpressionSlots<TRequiredSlots>): RefExpressionWarning[];
    /**
     * Get entity references from the expression with their positions.
     *
     * Used by the generic rename system to detect and apply renames.
     * Each returned dependency identifies an entity by ID and marks the
     * position in the expression text that should be replaced with the
     * entity's new name if it is renamed.
     *
     * @param value - The raw expression value
     * @param parseResult - The cached parse result
     * @param definition - The project definition
     * @param resolvedSlots - The resolved slot paths for this expression
     * @returns Array of entity references with positions for rename
     */
    abstract getReferencedEntities(value: TValue, parseResult: RefExpressionParseResult<TParseResult>, definition: ProjectDefinition, resolvedSlots: ResolvedExpressionSlots<TRequiredSlots>): RefExpressionDependency[];
    /**
     * Convenience method that combines parse() and getWarnings() into a single call.
     * Parses the expression and returns all validation warnings (including parse errors).
     *
     * @param value - The raw expression value
     * @param projectDef - The project definition for context
     * @param context - Validation context with project definition and plugin store
     * @param resolvedSlots - The resolved slot paths for this expression
     * @returns Array of warnings (empty if valid)
     */
    validate(value: TValue, projectDef: ProjectDefinition, context: ExpressionValidationContext, resolvedSlots: ResolvedExpressionSlots<TRequiredSlots>): RefExpressionWarning[];
    /**
     * Phantom property for TRequiredSlots type inference.
     * This is never actually used at runtime.
     * @internal
     */
    readonly _requiredSlots?: TRequiredSlots;
}
/**
 * Fully resolved expression - output from extractDefinitionRefs.
 * Contains the expression value, parser instance, and resolved slot paths.
 */
export interface DefinitionExpression {
    /** Path to the expression in the definition */
    path: ReferencePath;
    /** The raw expression value */
    value: unknown;
    /** Reference to the parser that handles this expression */
    parser: RefExpressionParser<any, any, any>;
    /** Resolved slot paths (slot key → resolved path in definition) */
    resolvedSlots: Record<string, ReferencePath>;
}
//# sourceMappingURL=expression-types.d.ts.map