@dpml/core/dist/index.d.cts

DPML Core: Implementations of base compiler, and provide a simple framework for domain developers.

/**
 * 表示DPML文档中的单个节点
 * 使用不可变设计，所有属性只读
 */
interface DPMLNode {
    /** 节点标签名 */
    readonly tagName: string;
    /** 节点属性集合 */
    readonly attributes: Map<string, string>;
    /** 子节点集合 */
    readonly children: DPMLNode[];
    /** 节点文本内容 */
    readonly content: string;
    /** 父节点引用 */
    readonly parent: DPMLNode | null;
    /** 源代码位置信息 */
    readonly sourceLocation?: SourceLocation;
}
/**
 * 源码定位信息
 */
interface SourceLocation {
    /** 开始行号 */
    startLine: number;
    /** 开始列号 */
    startColumn: number;
    /** 结束行号 */
    endLine: number;
    /** 结束列号 */
    endColumn: number;
    /** 源文件名 */
    fileName?: string;
}

/**
 * DPML文档类型
 * 表示完整DPML文档的纯数据结构
 */
interface DPMLDocument {
    /** 文档根节点 */
    readonly rootNode: DPMLNode;
    /** 节点ID索引，用于快速访问 */
    readonly nodesById?: Map<string, DPMLNode>;
    /** 文档元数据 */
    readonly metadata: DocumentMetadata;
}
/**
 * 文档元数据类型
 */
interface DocumentMetadata {
    /** 文档标题 */
    title?: string;
    /** 文档描述 */
    description?: string;
    /** 创建时间 */
    createdAt?: Date;
    /** 最后修改时间 */
    modifiedAt?: Date;
    /** 来源文件名 */
    sourceFileName?: string;
    /** 用户自定义元数据 */
    custom?: Record<string, unknown>;
}

/**
 * 解析选项配置类型
 * 支持错误处理和验证行为配置
 */
interface ParseOptions {
    /** 是否在错误时立即抛出 */
    throwOnError?: boolean;
    /** 源文件名，用于错误报告 */
    fileName?: string;
    /** 底层XML解析器选项 */
    xmlParserOptions?: XMLParserOptions;
    /** 后处理器选项 */
    postProcessorOptions?: Record<string, boolean>;
    /** 内存优化选项，用于处理大文件 */
    memoryOptimization?: MemoryOptimizationOptions;
}
/**
 * XML解析器选项
 */
interface XMLParserOptions {
    /** 是否保留空白字符 */
    preserveWhitespace?: boolean;
    /** 是否解析注释 */
    parseComments?: boolean;
    /** 是否启用命名空间支持 */
    enableNamespaces?: boolean;
    /** 最大嵌套层级 */
    maxDepth?: number;
    /** 是否验证节点引用完整性 */
    validateReferences?: boolean;
    /** 是否解析CDATA部分 */
    parseCDATA?: boolean;
    /** 是否使用流式处理（用于大文件） */
    useStreaming?: boolean;
}
/**
 * 内存优化选项
 */
interface MemoryOptimizationOptions {
    /** 是否启用内存优化 */
    enabled?: boolean;
    /** 大文件阈值（字节数），超过此值将应用优化 */
    largeFileThreshold?: number;
    /** 是否使用流式处理 */
    useStreaming?: boolean;
    /** 批处理大小 */
    batchSize?: number;
}

/**
 * 解析错误类型定义
 * 定义解析过程中可能出现的各种错误类型
 */

/**
 * 解析错误代码枚举
 */
declare enum ParseErrorCode {
    UNKNOWN_ERROR = "PARSE_UNKNOWN_ERROR",
    INVALID_CONTENT = "PARSE_INVALID_CONTENT",
    XML_SYNTAX_ERROR = "PARSE_XML_SYNTAX_ERROR",
    XML_INVALID_TAG = "PARSE_XML_INVALID_TAG",
    XML_MISSING_CLOSING_TAG = "PARSE_XML_MISSING_CLOSING_TAG",
    XML_INVALID_ATTRIBUTE = "PARSE_XML_INVALID_ATTRIBUTE",
    DPML_INVALID_STRUCTURE = "PARSE_DPML_INVALID_STRUCTURE",
    DPML_INVALID_TAG = "PARSE_DPML_INVALID_TAG",
    DPML_INVALID_ATTRIBUTE = "PARSE_DPML_INVALID_ATTRIBUTE",
    DPML_MISSING_REQUIRED_TAG = "PARSE_DPML_MISSING_REQUIRED_TAG",
    DPML_MISSING_REQUIRED_ATTRIBUTE = "PARSE_DPML_MISSING_REQUIRED_ATTRIBUTE"
}
/**
 * 基础解析错误类
 * 所有解析错误的基类
 */
declare class ParseError extends Error {
    /**
     * 错误代码
     */
    readonly code: ParseErrorCode;
    /**
     * 错误位置信息
     */
    readonly position?: SourceLocation;
    /**
     * 源代码片段
     */
    readonly source?: string;
    /**
     * 原始错误
     */
    readonly cause?: unknown;
    /**
     * 创建解析错误实例
     * @param message 错误消息
     * @param code 错误代码
     * @param position 位置信息
     * @param source 源代码片段
     * @param cause 原始错误
     */
    constructor(message: string, code?: ParseErrorCode, position?: SourceLocation, source?: string, cause?: unknown);
    /**
     * 格式化错误信息，包含位置和上下文
     * @returns 格式化的错误信息
     */
    formatMessage(): string;
    /**
     * 重写toString方法，提供更详细的错误信息
     * @returns 格式化的错误字符串
     */
    toString(): string;
}
/**
 * XML解析错误类
 * 处理XML解析过程中的错误
 */
declare class XMLParseError extends ParseError {
    /**
     * 错误上下文片段
     * 包含错误位置附近的内容
     */
    contextFragment?: string;
    /**
     * 创建XML解析错误实例
     * @param message 错误消息
     * @param code 错误代码
     * @param position 位置信息
     * @param source 源代码片段
     * @param cause 原始错误
     */
    constructor(message: string, code?: ParseErrorCode, position?: SourceLocation, source?: string, cause?: unknown);
    /**
     * 从原始XML解析错误创建XMLParseError
     * @param error 原始错误
     * @param content XML内容
     * @param fileName 文件名
     * @returns XML解析错误
     */
    static fromError(error: unknown, content?: string, fileName?: string): XMLParseError;
    /**
     * 从错误消息中提取位置信息
     * @param message 错误消息
     * @param fileName 文件名
     * @returns 源码位置信息或undefined
     */
    private static extractPositionFromMessage;
    /**
     * 从内容中提取源代码片段
     * @param content 完整内容
     * @param line 行号
     * @param column 列号
     * @returns 源代码片段
     */
    private static extractSourceSnippet;
    /**
     * 格式化错误信息，包含位置和上下文
     * @returns 格式化的错误信息
     */
    formatMessage(): string;
}
/**
 * DPML解析错误类
 * 处理DPML特定的解析错误
 */
declare class DPMLParseError extends ParseError {
    /**
     * 创建DPML解析错误实例
     * @param message 错误消息
     * @param code 错误代码
     * @param position 位置信息
     * @param source 源代码片段
     * @param cause 原始错误
     */
    constructor(message: string, code?: ParseErrorCode, position?: SourceLocation, source?: string, cause?: unknown);
    /**
     * 创建缺少必需标签的错误
     * @param tagName 标签名
     * @param position 位置信息
     * @returns DPML解析错误
     */
    static createMissingRequiredTagError(tagName: string, position?: SourceLocation): DPMLParseError;
    /**
     * 创建缺少必需属性的错误
     * @param attributeName 属性名
     * @param tagName 标签名
     * @param position 位置信息
     * @returns DPML解析错误
     */
    static createMissingRequiredAttributeError(attributeName: string, tagName: string, position?: SourceLocation): DPMLParseError;
    /**
     * 创建无效标签错误
     * @param tagName 标签名
     * @param position 位置信息
     * @returns DPML解析错误
     */
    static createInvalidTagError(tagName: string, position?: SourceLocation): DPMLParseError;
    /**
     * 创建无效属性错误
     * @param attributeName 属性名
     * @param tagName 标签名
     * @param position 位置信息
     * @returns DPML解析错误
     */
    static createInvalidAttributeError(attributeName: string, tagName: string, position?: SourceLocation): DPMLParseError;
}

/**
 * 解析结果类型定义
 * 定义DPML解析结果的标准接口
 */

/**
 * 解析结果接口
 * 用于非抛出错误模式下的返回结构
 */
interface ParseResult<T> {
    /**
     * 解析是否成功
     */
    success: boolean;
    /**
     * 解析结果数据
     * 仅在success为true时存在
     */
    data?: T;
    /**
     * 解析错误
     * 仅在success为false时存在
     */
    error?: ParseError;
    /**
     * 警告信息
     * 可能在success为true时也存在
     */
    warnings?: ParseError[];
}

/**
 * 定义用户友好的Schema接口，不包含内部实现细节。
 * 应用开发者使用这些接口定义DPML文档的结构。
 */
/**
 * 表示元素的属性定义。
 */
interface AttributeSchema {
    /**
     * 属性的名称。
     */
    name: string;
    /**
     * 属性值的预期类型 (例如：'string', 'number', 'boolean')。
     * 如果未指定，可能表示任何类型或需要根据上下文推断。
     */
    type?: string;
    /**
     * 指示此属性是否为必需。
     * @default false
     */
    required?: boolean;
    /**
     * 如果属性值是枚举类型，则定义允许的值列表。
     */
    enum?: string[];
    /**
     * 属性值应匹配的正则表达式模式。
     */
    pattern?: string;
    /**
     * 属性的默认值。
     */
    default?: string;
}
/**
 * 表示元素内容的定义。
 */
interface ContentSchema {
    /**
     * 内容的类型，可以是'text'（纯文本）或'mixed'（混合内容）。
     */
    type: 'text' | 'mixed';
    /**
     * 指示内容是否为必需。
     * @default false
     */
    required?: boolean;
    /**
     * 内容应匹配的正则表达式模式。
     */
    pattern?: string;
}
/**
 * 表示对另一个已定义类型的引用。
 */
interface TypeReference {
    /**
     * 引用的类型名称。
     * 这通常对应于DocumentSchema的types数组中定义的ElementSchema的element属性。
     */
    $ref: string;
}
/**
 * 表示元素可能包含的子元素集合。
 */
interface ChildrenSchema {
    /**
     * 允许作为子元素的元素列表。
     * 每个元素可以是直接的ElementSchema定义，也可以是对其他类型的引用。
     */
    elements: (ElementSchema | TypeReference)[];
    /**
     * 指示子元素的顺序是否重要。
     * @default false
     */
    orderImportant?: boolean;
    /**
     * 子元素的最小数量。
     */
    min?: number;
    /**
     * 子元素的最大数量。
     */
    max?: number;
}
/**
 * 表示元素（Element）的结构定义。
 */
interface ElementSchema {
    /**
     * 元素的名称（标签名）。
     */
    element: string;
    /**
     * 定义此元素允许或要求的属性。
     */
    attributes?: AttributeSchema[];
    /**
     * 定义此元素允许的内容模型。
     */
    content?: ContentSchema;
    /**
     * 定义此元素允许的子元素。
     */
    children?: ChildrenSchema;
}
/**
 * 表示文档（Document）级别的结构定义。
 */
interface DocumentSchema {
    /**
     * 定义文档的根元素。
     * 可以是直接的元素定义、类型引用或表示纯文本根的字符串。
     */
    root: ElementSchema | TypeReference | string;
    /**
     * 定义可在本文档内部复用的类型（通常是ElementSchema）。
     * 这些类型可以通过TypeReference($ref)在root或其他ElementSchema的children中引用。
     */
    types?: ElementSchema[];
    /**
     * 定义适用于文档内所有元素的全局属性。
     */
    globalAttributes?: AttributeSchema[];
    /**
     * 定义文档可能使用的命名空间。
     */
    namespaces?: string[];
}
/**
 * Schema类型的联合类型，用于简化API参数类型定义。
 */
type Schema = DocumentSchema | ElementSchema;

/**
 * 表示 Schema 验证过程中遇到的错误。
 * @template T 可选的泛型，用于携带额外的错误详情。
 */
interface SchemaError<T = unknown> {
    /**
     * 错误描述信息，应清晰易懂。
     */
    message: string;
    /**
     * 错误代码，用于程序化识别错误类型。
     */
    code: string;
    /**
     * 错误在 Schema 对象中发生的路径。
     * 例如： "elements[0].attributes[1].name"
     */
    path: string;
    /**
     * 可选的额外错误详情。
     */
    details?: T;
}

/**
 * 表示经过处理（验证）后的 Schema 定义结果。
 * @template T 原始 Schema 对象的类型。
 */
interface ProcessedSchema<T extends object> {
    /**
     * 用户提供的原始 Schema 对象。
     */
    schema: T;
    /**
     * 指示 Schema 定义是否有效（是否通过了所有验证规则）。
     */
    isValid: boolean;
    /**
     * 如果 Schema 无效 (isValid 为 false)，则包含一个或多个 SchemaError 对象。
     * 如果 Schema 有效，则此属性为 undefined。
     */
    errors?: SchemaError[];
}

/**
 * 引用映射接口
 * 提供文档中ID到节点的映射关系
 */
interface ReferenceMap {
    /**
     * ID到节点的映射
     */
    readonly idMap: ReadonlyMap<string, DPMLNode>;
}

/**
 * 处理错误接口
 * 表示文档处理过程中的错误信息
 */
interface ProcessingError {
    /**
     * 错误代码
     */
    readonly code: string;
    /**
     * 错误消息
     */
    readonly message: string;
    /**
     * 文档路径
     */
    readonly path: string;
    /**
     * 源代码位置信息
     */
    readonly source: SourceLocation;
    /**
     * 错误的严重程度
     */
    readonly severity: 'error';
}

/**
 * 处理警告接口
 * 表示文档处理过程中的警告信息
 */
interface ProcessingWarning {
    /**
     * 警告代码
     */
    readonly code: string;
    /**
     * 警告消息
     */
    readonly message: string;
    /**
     * 文档路径
     */
    readonly path: string;
    /**
     * 源代码位置信息
     */
    readonly source: SourceLocation;
    /**
     * 警告的严重程度
     */
    readonly severity: 'warning';
}

/**
 * 验证结果接口
 * 包含文档验证结果的详细信息
 */
interface ValidationResult {
    /**
     * 是否通过验证
     */
    readonly isValid: boolean;
    /**
     * 验证过程中发现的错误
     */
    readonly errors: ReadonlyArray<ProcessingError>;
    /**
     * 验证过程中发现的警告
     */
    readonly warnings: ReadonlyArray<ProcessingWarning>;
}

/**
 * 处理结果接口，包含解析和处理后的数据
 */
interface ProcessingResult {
    /**
     * DPML文档对象
     */
    document: DPMLDocument;
    /**
     * 文档有效性标志
     */
    isValid: boolean;
    /**
     * 文档引用关系映射
     */
    references?: ReferenceMap;
    /**
     * 文档schema信息
     */
    schema?: unknown;
    /**
     * 验证结果详情
     */
    validation?: ValidationResult;
}

/**
 * 处理上下文接口
 * 提供处理过程中的核心上下文信息
 */
interface ProcessingContext {
    /**
     * 正在处理的DPML文档
     */
    readonly document: DPMLDocument;
    /**
     * 用于验证的已处理Schema
     */
    readonly schema: ProcessedSchema<any>;
}

/**
 * 转换上下文类，负责在转换过程中维护状态
 * 提供类型安全的数据访问方法
 */
declare class TransformContext {
    /**
     * 存储上下文数据的内部Map
     */
    private data;
    /**
     * 原始处理结果引用
     */
    private processingResult;
    /**
     * 创建上下文实例
     * @param processingResult 原始处理结果
     * @param initialData 可选的初始数据
     */
    constructor(processingResult: ProcessingResult, initialData?: Record<string, unknown>);
    /**
     * 类型安全的数据存储
     * @template T 值的类型
     * @param key 存储键
     * @param value 存储值
     */
    set<T>(key: string, value: T): void;
    /**
     * 类型安全的数据获取
     * @template T 期望的返回类型
     * @param key 获取键
     * @returns 获取的值，若不存在则返回undefined
     */
    get<T>(key: string): T | undefined;
    /**
     * 检查键是否存在
     * @param key 检查键
     * @returns 是否存在
     */
    has(key: string): boolean;
    /**
     * 获取原始文档
     * @returns 文档对象
     */
    getDocument(): DPMLDocument;
    /**
     * 获取引用关系
     * @returns 引用映射
     */
    getReferences(): ReferenceMap | undefined;
    /**
     * 获取验证结果
     * @returns 验证结果对象
     */
    getValidation(): ValidationResult;
    /**
     * 检查文档有效性
     * @returns 是否有效
     */
    isDocumentValid(): boolean;
    /**
     * 获取所有结果
     * @returns 所有存储的数据
     */
    getAllResults(): Record<string, unknown>;
}

/**
 * Transformer接口定义，所有转换器实现此接口
 * 支持泛型输入输出类型，确保类型安全
 * @template TInput 输入数据类型
 * @template TOutput 输出数据类型
 */
interface Transformer<TInput, TOutput> {
    /**
     * 转换器名称，用于标识
     */
    name: string;
    /**
     * 转换器描述，说明功能（可选）
     */
    description?: string;
    /**
     * 执行转换的核心方法
     * @param input 输入数据，类型为TInput
     * @param context 转换上下文
     * @returns 转换后的输出，类型为TOutput
     */
    transform(input: TInput, context: TransformContext): TOutput;
}

/**
 * 转换选项接口，配置转换过程
 */
interface TransformOptions {
    /**
     * 初始上下文数据
     * 在转换开始前注入到上下文中
     */
    context?: Record<string, unknown>;
    /**
     * 结果模式选择
     * - 'full': 返回完整结果，包括transformers、merged和raw
     * - 'merged': 仅返回merged部分
     * - 'raw': 仅返回raw部分
     */
    resultMode?: 'full' | 'merged' | 'raw';
    /**
     * 包含的转换器
     * 如果提供，只有指定的转换器结果会被包含在最终结果中
     */
    include?: string[];
    /**
     * 排除的转换器
     * 如果提供，指定的转换器结果会被排除在最终结果外
     */
    exclude?: string[];
}

/**
 * 转换结果接口，定义转换输出的标准结构
 * 支持泛型指定结果类型
 */
interface TransformResult<T> {
    /**
     * 各转换器的结果映射
     * 键为转换器名称，值为对应转换器的输出
     */
    transformers: Record<string, unknown>;
    /**
     * 合并后的结果
     * 类型为用户指定的泛型参数T
     */
    merged: T;
    /**
     * 原始未处理的结果
     * 通常是最后一个转换器的直接输出
     */
    raw?: unknown;
    /**
     * 转换过程中的警告
     */
    warnings?: TransformWarning[];
    /**
     * 转换元数据信息
     */
    metadata: TransformMetadata;
}
/**
 * 转换警告接口
 */
interface TransformWarning {
    /**
     * 警告代码
     */
    code: string;
    /**
     * 警告消息
     */
    message: string;
    /**
     * 相关转换器
     */
    transformer?: string;
    /**
     * 警告严重程度
     */
    severity: 'low' | 'medium' | 'high';
}
/**
 * 转换元数据接口
 */
interface TransformMetadata {
    /**
     * 参与转换的转换器名称列表
     */
    transformers: string[];
    /**
     * 转换选项
     */
    options: TransformOptions;
    /**
     * 转换时间戳
     */
    timestamp: number;
    /**
     * 执行时间（毫秒）
     */
    executionTime?: number;
}

/**
 * 映射规则接口，用于结构映射
 * 支持泛型定义输入值和输出值类型
 */
interface MappingRule<TValue, TResult> {
    /**
     * CSS选择器，定位元素
     */
    selector: string;
    /**
     * 目标属性路径
     * 描述映射结果在目标对象中的位置
     * 例如："parameters.temperature"
     */
    targetPath: string;
    /**
     * 可选值转换函数
     * 对提取的值进行转换处理
     * @param value 从选择器提取的原始值
     * @returns 转换后的值
     */
    transform?: (value: TValue) => TResult;
}

/**
 * 收集配置接口，用于聚合转换器
 */
interface CollectorConfig {
    /**
     * CSS选择器，定位要收集的元素
     */
    selector: string;
    /**
     * 分组字段
     * 如果提供，结果将按此字段分组
     * 通常是属性名或可以从元素提取的值
     */
    groupBy?: string;
    /**
     * 排序字段
     * 如果提供，结果将按此字段排序
     * 通常是属性名或可以从元素提取的值
     */
    sortBy?: string;
}

/**
 * 关系配置接口，用于关系处理转换器
 */
interface RelationConfig {
    /**
     * 源选择器或属性
     * 定义关系的源端点
     */
    source: string;
    /**
     * 目标选择器或属性
     * 定义关系的目标端点
     */
    target: string;
    /**
     * 关系类型
     * 可选的关系类型描述
     */
    type?: string;
}

/**
 * 语义提取器接口，用于语义提取转换器
 * 支持泛型元素处理和结果类型
 */
interface SemanticExtractor<TElement, TResult> {
    /**
     * 提取器名称，用于标识
     */
    name: string;
    /**
     * CSS选择器，定位要处理的元素
     */
    selector: string;
    /**
     * 处理函数，处理提取的元素
     * @param elements 提取的元素数组
     * @returns 处理结果
     */
    processor: (elements: TElement[]) => TResult;
}

/**
 * 编译选项接口，控制编译行为
 */
interface CompileOptions {
    /**
     * 是否启用严格模式
     * 在严格模式下，会对文档结构进行更严格的验证
     */
    strictMode?: boolean;
    /**
     * 错误处理策略
     * - 'throw': 遇到错误时抛出异常
     * - 'warn': 遇到错误时记录警告但继续执行
     * - 'silent': 忽略错误并继续执行
     */
    errorHandling?: 'throw' | 'warn' | 'silent';
    /**
     * 转换选项
     * 控制转换过程的行为
     */
    transformOptions?: TransformOptions;
    /**
     * 自定义选项
     * 允许存储任意附加配置
     */
    custom?: Record<string, any>;
}

/**
 * 领域命令接口
 * 定义领域特定的CLI命令结构
 */
interface DomainAction {
    /**
     * 命令名称
     * 应遵循kebab-case格式，如"validate-schema"
     */
    name: string;
    /**
     * 命令描述
     * 用于CLI帮助信息
     */
    description: string;
    /**
     * 位置参数定义
     * 定义命令的位置参数
     */
    args?: Array<DomainArgumentDefinition>;
    /**
     * 选项参数定义
     * 定义命令的选项参数
     */
    options?: Array<DomainOptionDefinition>;
    /**
     * 命令执行函数
     * 第一个参数为领域命令上下文，后续参数为命令参数
     * @param actionContext 领域命令上下文
     * @param args 命令参数
     */
    action: (actionContext: DomainActionContext, ...args: any[]) => Promise<void> | void;
}
/**
 * 领域命令执行上下文接口
 * 专为命令执行设计的上下文环境
 */
interface DomainActionContext {
    /**
     * 获取领域编译器
     * @returns 领域编译器实例
     */
    getCompiler<T = unknown>(): DomainCompiler<T>;
    /**
     * 获取领域标识符
     * @returns 领域标识符
     */
    getDomain(): string;
    /**
     * 获取领域描述
     * @returns 领域描述
     */
    getDescription(): string;
    /**
     * 获取编译选项
     * @returns 编译选项
     */
    getOptions(): Required<CompileOptions>;
}
/**
 * 领域命令参数定义
 */
interface DomainArgumentDefinition {
    /**
     * 参数名称
     */
    name: string;
    /**
     * 参数描述
     */
    description: string;
    /**
     * 是否必需
     * 默认为false
     */
    required?: boolean;
    /**
     * 默认值
     */
    defaultValue?: string;
    /**
     * 可选项列表
     */
    choices?: string[];
}
/**
 * 领域命令选项定义
 */
interface DomainOptionDefinition {
    /**
     * 选项标识，如 '-v, --verbose'
     */
    flags: string;
    /**
     * 选项描述
     */
    description: string;
    /**
     * 默认值
     */
    defaultValue?: string | boolean | number;
    /**
     * 是否必需
     * 默认为false
     */
    required?: boolean;
    /**
     * 可选项列表
     */
    choices?: string[];
}

/**
 * 领域配置接口，定义创建领域编译器所需的配置
 */
interface DomainConfig {
    /**
     * 领域标识符
     * 用于在CLI和其他场景中标识领域
     */
    domain: string;
    /**
     * 领域描述
     * 用于在CLI和其他场景中描述领域
     */
    description?: string;
    /**
     * 领域特定的架构定义
     */
    schema: Schema;
    /**
     * 转换器实例数组
     */
    transformers: Array<Transformer<unknown, unknown>>;
    /**
     * 可选的编译选项
     */
    options?: CompileOptions;
    /**
     * 领域命令配置
     * 用于定义领域特定的CLI命令
     */
    commands?: DomainCommandsConfig;
}
/**
 * 领域命令配置接口
 * 定义领域特定的CLI命令配置
 */
interface DomainCommandsConfig {
    /**
     * 是否包含标准命令
     * 如果为true，将包含validate和parse等标准命令
     * 默认为false
     */
    includeStandard?: boolean;
    /**
     * 自定义领域命令
     * 定义领域特定的CLI命令
     */
    actions?: Array<DomainAction>;
}

/**
 * 领域编译器接口，提供DPML编译与管理功能
 * @template T 编译后的领域对象类型
 */
interface DomainCompiler<T> {
    /**
     * 编译DPML内容为领域对象
     * @param content DPML内容字符串
     * @returns 编译后的领域对象
     */
    compile(content: string): Promise<T>;
    /**
     * 扩展当前配置
     * @param extensionConfig 要合并的配置片段
     */
    extend(extensionConfig: Partial<DomainConfig>): void;
    /**
     * 获取当前架构
     * @returns 当前架构对象
     */
    getSchema(): Schema;
    /**
     * 获取当前转换器集合
     * @returns 转换器数组
     */
    getTransformers(): Array<Transformer<unknown, unknown>>;
}

/**
 * CLI核心接口
 * 提供命令行界面核心功能
 */
interface CLI {
    /**
     * 执行CLI处理命令行参数
     * @param argv 命令行参数数组，默认使用process.argv
     */
    execute(argv?: string[]): Promise<void>;
    /**
     * 显示帮助信息
     */
    showHelp(): void;
    /**
     * 显示版本信息
     */
    showVersion(): void;
    /**
     * 注册外部命令
     * @param commands 符合CommandDefinition规范的命令数组
     */
    registerCommands(commands: CommandDefinition[]): void;
}
/**
 * CLI选项
 * 配置CLI基本信息
 */
interface CLIOptions {
    /**
     * CLI工具名称
     */
    name: string;
    /**
     * CLI版本号
     */
    version: string;
    /**d
     * CLI描述
     */
    description: string;
    /**
     * 默认领域，默认为'core'
     */
    defaultDomain?: string;
}
/**
 * 命令行参数定义
 */
interface ArgumentDefinition {
    /**
     * 参数名称
     */
    name: string;
    /**
     * 参数描述
     */
    description: string;
    /**
     * 是否必需
     */
    required?: boolean;
    /**
     * 默认值
     */
    defaultValue?: string;
    /**
     * 可选项列表
     */
    choices?: string[];
}
/**
 * 命令行选项定义
 */
interface OptionDefinition {
    /**
     * 选项标识，如 '-v, --verbose'
     */
    flags: string;
    /**
     * 选项描述
     */
    description: string;
    /**
     * 默认值
     */
    defaultValue?: string | boolean | number;
    /**
     * 是否必需
     */
    required?: boolean;
    /**
     * 可选项列表
     */
    choices?: string[];
}
/**
 * 命令行动作处理函数
 */
type CommandAction = (...args: unknown[]) => void | Promise<void>;
/**
 * 命令定义
 */
interface CommandDefinition {
    /**
     * 命令名称
     */
    name: string;
    /**
     * 命令描述
     */
    description: string;
    /**
     * 位置参数定义
     */
    arguments?: ArgumentDefinition[];
    /**
     * 选项参数定义
     */
    options?: OptionDefinition[];
    /**
     * 命令执行函数
     */
    action: CommandAction;
    /**
     * 子命令定义
     */
    subcommands?: CommandDefinition[];
    /**
     * 所属领域，用于组织命令层次结构
     */
    category?: string;
}

/**
 * 领域DPML接口，提供编译和命令行功能的统一接口
 * @template T 编译后的领域对象类型
 */
interface DomainDPML<T> {
    /**
     * 领域编译器实例
     * 提供DPML编译与配置管理功能
     */
    compiler: DomainCompiler<T>;
    /**
     * 领域CLI实例
     * 提供命令行交互功能
     */
    cli: CLI;
}

/**
 * 框架错误类型定义
 * 定义框架模块中可能出现的各种错误类型
 */
/**
 * 配置验证错误
 * 当提供的领域配置无效时抛出
 */
declare class ConfigurationError extends Error {
    /**
     * 创建配置错误实例
     * @param message 错误消息
     */
    constructor(message: string);
}
/**
 * 编译错误
 * 当编译过程中发生错误时抛出
 */
declare class CompilationError extends Error {
    readonly cause?: Error | undefined;
    /**
     * 创建编译错误实例
     * @param message 错误消息
     * @param cause 可选的原始错误
     */
    constructor(message: string, cause?: Error | undefined);
}

/**
 * 转换器定义器接口，提供创建各种类型转换器的能力
 */
interface TransformerDefiner {
    /**
     * 定义结构映射转换器
     * @param name 转换器名称
     * @param rules 映射规则数组
     * @returns 结构映射转换器实例
     */
    defineStructuralMapper<TInput, TOutput>(name: string, rules: Array<MappingRule<unknown, unknown>>): Transformer<TInput, TOutput>;
    /**
     * 定义聚合转换器
     * @param name 转换器名称
     * @param config 收集配置
     * @returns 聚合转换器实例
     */
    defineAggregator<TInput, TOutput>(name: string, config: CollectorConfig): Transformer<TInput, TOutput>;
    /**
     * 定义模板转换器
     * @param name 转换器名称
     * @param template 模板字符串或函数
     * @param preprocessor 可选的数据预处理函数
     * @returns 模板转换器实例
     */
    defineTemplateTransformer<TInput>(name: string, template: string | ((data: unknown) => string), preprocessor?: (input: TInput) => unknown): Transformer<TInput, string>;
    /**
     * 定义关系处理转换器
     * @param name 转换器名称
     * @param nodeSelector 节点选择器
     * @param config 关系配置
     * @returns 关系处理转换器实例
     */
    defineRelationProcessor<TInput, TOutput>(name: string, nodeSelector: string, config: RelationConfig): Transformer<TInput, TOutput>;
    /**
     * 定义语义提取转换器
     * @param name 转换器名称
     * @param extractors 提取器数组
     * @returns 语义提取转换器实例
     */
    defineSemanticExtractor<TInput, TOutput>(name: string, extractors: Array<SemanticExtractor<unknown, unknown>>): Transformer<TInput, TOutput>;
    /**
     * 定义结果收集转换器
     * @param name 转换器名称
     * @param transformerNames 可选的转换器名称数组，用于选择性收集
     * @returns 结果收集转换器实例
     */
    defineResultCollector<TOutput>(name: string, transformerNames?: string[]): Transformer<unknown, TOutput>;
}

/**
 * 日志模块类型定义
 *
 * 该文件包含DPML日志模块所需的所有类型定义和接口，作为日志模块的类型基础架构。
 */
/**
 * 日志级别枚举，从DEBUG(最低)到FATAL(最高)
 * 数值顺序对应严重程度，用于日志级别比较
 */
declare enum LogLevel {
    DEBUG = 0,
    INFO = 1,
    WARN = 2,
    ERROR = 3,
    FATAL = 4
}
/**
 * 日志器接口，定义日志记录的核心方法
 * 所有日志器实现必须实现此接口
 */
type Logger = {
    /**
     * 记录调试级别的日志
     * @param message 日志消息
     * @param context 可选的上下文信息
     * @param error 可选的错误对象
     */
    debug(message: string, context?: Record<string, unknown>, error?: Error): void;
    /**
     * 记录信息级别的日志
     * @param message 日志消息
     * @param context 可选的上下文信息
     * @param error 可选的错误对象
     */
    info(message: string, context?: Record<string, unknown>, error?: Error): void;
    /**
     * 记录警告级别的日志
     * @param message 日志消息
     * @param context 可选的上下文信息
     * @param error 可选的错误对象
     */
    warn(message: string, context?: Record<string, unknown>, error?: Error): void;
    /**
     * 记录错误级别的日志
     * @param message 日志消息
     * @param context 可选的上下文信息
     * @param error 可选的错误对象
     */
    error(message: string, context?: Record<string, unknown>, error?: Error): void;
    /**
     * 记录致命错误级别的日志
     * @param message 日志消息
     * @param context 可选的上下文信息
     * @param error 可选的错误对象
     */
    fatal(message: string, context?: Record<string, unknown>, error?: Error): void;
};
/**
 * 日志条目结构，表示一条完整的日志记录
 * 包含时间戳、级别、消息和可选的上下文信息、错误对象和调用位置
 */
type LogEntry = {
    /**
     * 日志记录的时间戳
     */
    timestamp: Date;
    /**
     * 日志级别
     */
    level: LogLevel;
    /**
     * 日志消息
     */
    message: string;
    /**
     * 可选的上下文信息，提供额外的结构化数据
     */
    context?: Record<string, unknown>;
    /**
     * 可选的错误对象，通常用于错误和异常日志
     */
    error?: Error;
    /**
     * 可选的调用位置信息，记录日志调用的代码位置
     */
    caller?: CallerInfo;
};
/**
 * 调用位置信息，记录日志调用的代码位置
 * 用于调试和问题定位
 */
type CallerInfo = {
    /**
     * 文件名
     */
    fileName: string;
    /**
     * 可选的类名
     */
    className?: string;
    /**
     * 函数名
     */
    functionName: string;
    /**
     * 行号
     */
    lineNumber: number;
    /**
     * 可选的列号
     */
    columnNumber?: number;
};
/**
 * 日志器配置，控制日志器的行为
 */
type LoggerConfig = {
    /**
     * 最低记录级别，低于此级别的日志将被忽略
     */
    minLevel: LogLevel;
    /**
     * 可选的格式化器，用于将日志条目格式化为字符串
     */
    formatter?: LogFormatter;
    /**
     * 可选的传输器数组，用于将日志输出到不同目标
     */
    transports?: LogTransport[];
    /**
     * 可选的调用位置捕获配置，控制是否捕获和记录调用位置
     */
    callSiteCapture?: CallSiteCaptureConfig;
};
/**
 * 调用位置捕获配置，控制调用位置捕获的行为
 */
type CallSiteCaptureConfig = {
    /**
     * 是否启用调用位置捕获
     */
    enabled: boolean;
    /**
     * 可选的日志级别数组，指定哪些级别需要捕获调用位置
     * 如果未指定，则对所有级别启用
     */
    forLevels?: LogLevel[];
};
/**
 * 日志格式化器接口，负责将日志条目格式化为字符串
 */
type LogFormatter = {
    /**
     * 将日志条目格式化为字符串
     * @param entry 要格式化的日志条目
     * @returns 格式化后的字符串
     */
    format(entry: LogEntry): string;
};
/**
 * 日志传输器接口，负责将日志写入到目标位置
 */
type LogTransport = {
    /**
     * 将日志条目写入到目标位置
     * @param entry 要写入的日志条目
     */
    write(entry: LogEntry): void;
};

/**
 * DPML错误类型
 * 定义所有DPML处理过程中可能发生的错误
 */
/**
 * 命令重复错误
 * 当检测到重复的命令定义时抛出
 */
declare class DuplicateCommandError extends Error {
    readonly commandPath: string;
    /**
     * 创建命令重复错误实例
     * @param commandPath 重复命令的路径
     */
    constructor(commandPath: string);
}
/**
 * 无效命令错误
 * 当命令定义不符合要求时抛出
 */
declare class InvalidCommandError extends Error {
    readonly commandName?: string | undefined;
    /**
     * 创建无效命令错误实例
     * @param message 错误消息
     * @param commandName 命令名称
     */
    constructor(message: string, commandName?: string | undefined);
}
/**
 * 命令执行错误
 * 当命令执行过程中发生错误时抛出
 */
declare class CommandExecutionError extends Error {
    readonly commandPath: string;
    readonly cause?: unknown | undefined;
    /**
     * 创建命令执行错误实例
     * @param message 错误消息
     * @param commandPath 命令路径
     * @param cause 原始错误
     */
    constructor(message: string, commandPath: string, cause?: unknown | undefined);
}

/**
 * 解析服务模块
 * 解析DPML内容字符串，协调适配器和错误处理
 *
 * @param content DPML内容字符串
 * @param options 解析选项
 * @returns 解析后的DPML文档
 */
declare function parse<T = DPMLDocument>(content: string, options?: ParseOptions): T | ParseResult<T>;
/**
 * 异步解析DPML内容
 *
 * @param content DPML内容字符串
 * @param options 解析选项
 * @returns 解析后的DPML文档Promise
 */
declare function parseAsync<T = DPMLDocument>(content: string, options?: ParseOptions): Promise<T | ParseResult<T>>;

/**
 * 处理文档
 * 基于提供的Schema验证文档，并提供验证结果和引用信息
 *
 * @param document - 要处理的DPML文档
 * @param schema - 用于验证的已处理Schema
 * @returns 处理结果，包含验证信息和引用映射
 *
 * @example
 * const result = processDocument(document, schema);
 * if (result.validation.isValid) {
 *   // 文档有效，可以继续处理
 * } else {
 *   // 处理验证错误
 *   result.validation.errors.forEach(error => console.error(error.message));
 * }
 */
declare function processDocument<T extends ProcessingResult = ProcessingResult>(document: DPMLDocument, schema: ProcessedSchema<any>): T;

/**
 * Schema 模块服务层。
 * 负责协调 Schema 处理流程，例如创建 Schema 业务类实例并调用其方法。
 * @param schema 用户提供的原始 Schema 对象。
 * @returns 处理后的 Schema 结果。
 * @template T 原始 Schema 对象的类型，默认为UserSchema。
 * @template R 处理结果的类型，默认为 ProcessedSchema<T>。
 * 注意：这是一个骨架函数，具体逻辑将在后续任务中实现。
 */
declare function processSchema<T extends object = Schema, R extends ProcessedSchema<T> = ProcessedSchema<T>>(schema: T): R;

/**
 * DPML转换模块API
 * 提供转换和转换器注册的入口点
 */

/**
 * 执行转换过程，返回结果
 * @param processingResult 处理结果
 * @param options 转换选项
 * @returns 转换结果，类型由泛型参数T指定
 */
declare function transform<T>(processingResult: ProcessingResult, options?: TransformOptions): TransformResult<T>;
/**
 * 注册自定义转换器
 * @param transformer 要注册的转换器
 */
declare function registerTransformer<TInput, TOutput>(transformer: Transformer<TInput, TOutput>): void;

/**
 * Framework模块API
 * 提供创建领域DPML编译器的功能
 */

/**
 * 创建领域DPML
 *
 * @template T 编译后的领域对象类型
 * @param config 领域配置
 * @returns 领域DPML实例，包含编译器和CLI
 *
 * @example
 * ```typescript
 * // 创建一个User模型的领域DPML
 * interface User {
 *   id: string;
 *   name: string;
 *   email: string;
 * }
 *
 * const userDPML = createDomainDPML<User>({
 *   domain: 'user',
 *   schema: userSchema,
 *   transformers: [userTransformer]
 * });
 *
 * // 使用编译器
 * const user = await userDPML.compiler.compile('<user id="1" name="张三" email="zhangsan@example.com" />');
 *
 * // 使用CLI
 * await userDPML.cli.execute();
 * ```
 */
declare function createDomainDPML<T>(config: DomainConfig): DomainDPML<T>;
/**
 * 创建转换器定义器
 *
 * @returns 转换器定义器实例，提供各种转换器的定义方法
 *
 * @example
 * ```typescript
 * // 获取转换器定义器
 * const definer = createTransformerDefiner();
 *
 * // 定义结构映射转换器
 * const mapperTransformer = definer.defineStructuralMapper([
 *   { selector: 'user', targetPath: 'userInfo' },
 *   { selector: 'user[id]', targetPath: 'userInfo.id' }
 * ]);
 *
 * // 定义模板转换器
 * const templateTransformer = definer.defineTemplateTransformer('Hello, {{name}}!');
 * ```
 */
declare function createTransformerDefiner(): TransformerDefiner;

/**
 * DPML日志模块标准API
 *
 * 该模块是DPML日志系统的标准公共API，严格遵循设计文档规范，
 * 提供了获取日志器、创建自定义日志器和设置日志级别的功能。
 */

/**
 * 获取默认日志器
 * @returns 默认日志器实例
 * @example
 * ```typescript
 * // 获取默认日志器
 * const logger = getDefaultLogger();
 * logger.info('Hello DPML');
 * ```
 */
declare function getDefaultLogger(): Logger;
/**
 * 获取日志器
 * @param name 日志器名称
 * @returns 日志器实例
 * @example
 * ```typescript
 * // 获取命名日志器
 * const dbLogger = getLogger('database');
 * dbLogger.debug('DB connection established');
 * ```
 */
declare function getLogger(name: string): Logger;
/**
 * 创建自定义配置的日志器
 * @param name 日志器名称
 * @param config 日志器配置
 * @returns 日志器实例
 * @example
 * ```typescript
 * // 创建自定义日志器
 * const logger = createLogger('api', {
 *   minLevel: LogLevel.INFO
 * });
 * ```
 */
declare function createLogger(name: string, config: LoggerConfig): Logger;
/**
 * 设置默认日志级别
 * @param level 日志级别
 * @example
 * ```typescript
 * // 设置默认日志级别为DEBUG
 * setDefaultLogLevel(LogLevel.DEBUG);
 * ```
 */
declare function setDefaultLogLevel(level: LogLevel): void;

/**
 * CLI模块API
 * 提供创建命令行界面的功能
 */

/**
 * 创建命令行界面
 *
 * @param options CLI选项
 * @param commands 命令定义数组
 * @returns CLI实例
 *
 * @example
 * ```typescript
 * // 创建基本CLI
 * const cli = createCLI(
 *   {
 *     name: 'dpml',
 *     version: '1.0.0',
 *     description: 'DPML命令行工具'
 *   },
 *   [
 *     {
 *       name: 'parse',
 *       description: '解析DPML文档',
 *       arguments: [
 *         { name: 'file', description: 'DPML文件路径', required: true }
 *       ],
 *       options: [
 *         { flags: '-o, --output <file>', description: '输出文件路径' }
 *       ],
 *       action: (file, options) => {
 *
 *
 *       }
 *     }
 *   ]
 * );
 *
 * // 执行CLI
 * await cli.execute(process.argv);
 * ```
 */
declare function createCLI(options: CLIOptions, commands: CommandDefinition[]): CLI;

export { type ArgumentDefinition, type AttributeSchema, type CLI, type CLIOptions, type CallSiteCaptureConfig, type CallerInfo, type ChildrenSchema, type CollectorConfig, type CommandAction, type CommandDefinition, CommandExecutionError, CompilationError, type CompileOptions, ConfigurationError, type ContentSchema, type DPMLDocument, type DPMLNode, DPMLParseError, type DocumentMetadata, type DocumentSchema, type DomainAction, type DomainActionContext, type DomainArgumentDefinition, type DomainCommandsConfig, type DomainCompiler, type DomainConfig, type DomainDPML, type DomainOptionDefinition, DuplicateCommandError, type ElementSchema, InvalidCommandError, type LogEntry, type LogFormatter, LogLevel, type LogTransport, type Logger, type LoggerConfig, type MappingRule, type MemoryOptimizationOptions, type OptionDefinition, ParseError, ParseErrorCode, type ParseOptions, type ParseResult, type ProcessedSchema, type ProcessingContext, type ProcessingError, type ProcessingResult, type ProcessingWarning, type ReferenceMap, type RelationConfig, type Schema, type SchemaError, type SemanticExtractor, type SourceLocation, TransformContext, type TransformMetadata, type TransformOptions, type TransformResult, type TransformWarning, type Transformer, type TransformerDefiner, type TypeReference, type ValidationResult, XMLParseError, type XMLParserOptions, createCLI, createDomainDPML, createLogger, createTransformerDefiner, getDefaultLogger, getLogger, parse, parseAsync, processDocument, processSchema, registerTransformer, setDefaultLogLevel, transform };