@mycodemap/mycodemap 0.1.0

package/dist/orchestrator/tool-orchestrator.d.ts

@@ -0,0 +1,108 @@
+/**
+ * [META] ToolOrchestrator - 工具编排器
+ * [WHY] 负责执行工具、超时控制、错误隔离、回退级联，是连接 IntentRouter、适配器和结果融合的"胶水"组件。
+ */
+import type { UnifiedResult, CodemapIntent } from './types.js';
+import { type ConfidenceResult } from './confidence.js';
+import type { ToolAdapter } from './adapters/base-adapter.js';
+/**
+ * 执行结果
+ */
+export interface ExecutionResult {
+    results: UnifiedResult[];
+    tool: string;
+    confidence: ConfidenceResult;
+}
+/**
+ * 安全执行结果
+ */
+export interface SafeExecutionResult {
+    results: UnifiedResult[];
+    error?: Error;
+}
+/**
+ * ToolOrchestrator 类 - 工具编排器核心控制器
+ */
+export declare class ToolOrchestrator {
+    /** 超时配置（毫秒） */
+    private readonly DEFAULT_TIMEOUT;
+    /** 工具适配器映射 */
+    private adapters;
+    /** 回退链配置 */
+    private fallbackChains;
+    /** 已执行过的工具（用于防止回退链循环） */
+    private executedTools;
+    /**
+     * 构造函数
+     * @param fallbackChains 自定义回退链配置
+     */
+    constructor(fallbackChains?: Record<string, string[]>);
+    /**
+     * 注册工具适配器
+     * @param adapter 工具适配器实例
+     */
+    registerAdapter(adapter: ToolAdapter): void;
+    /**
+     * 将 CodemapIntent 转换为适配器调用参数
+     * @param intent 意图对象
+     * @returns [keywords, options] 元组
+     */
+    private convertIntentToAdapterArgs;
+    /**
+     * 带超时控制的工具执行
+     *
+     * 使用 AbortController + Promise.race 实现真正的超时控制
+     *
+     * @param tool 工具名称
+     * @param intent 意图对象
+     * @param timeout 超时时间（毫秒），默认 30 秒
+     * @returns 工具执行结果数组
+     */
+    runToolWithTimeout(tool: string, intent: CodemapIntent, timeout?: number): Promise<UnifiedResult[]>;
+    /**
+     * 错误隔离的工具执行
+     *
+     * 包装工具执行，捕获所有异常
+     * 错误时返回空结果而非抛出异常（除致命错误外）
+     *
+     * @param tool 工具名称
+     * @param intent 意图对象
+     * @returns 安全执行结果
+     */
+    runToolSafely(tool: string, intent: CodemapIntent): Promise<SafeExecutionResult>;
+    /**
+     * 回退执行
+     *
+     * 执行主工具并计算置信度
+     * 当置信度 < medium 阈值时，依次执行回退链
+     * 合并主工具和回退工具的结果（去重 + 排序）
+     * 达到阈值或回退链耗尽后停止
+     *
+     * @param intent 意图对象
+     * @param primaryTool 主工具名称
+     * @returns 执行结果
+     */
+    executeWithFallback(intent: CodemapIntent, primaryTool: string): Promise<ExecutionResult>;
+    /**
+     * 并行执行
+     *
+     * 并行执行多个工具
+     * 每个工具独立超时控制
+     * 返回按工具分组的结果
+     *
+     * @param intent 意图对象
+     * @param tools 工具名称数组
+     * @returns 按工具分组的结果映射
+     */
+    executeParallel(intent: CodemapIntent, tools: string[]): Promise<Map<string, UnifiedResult[]>>;
+    /**
+     * 合并结果（去重 + 排序）
+     */
+    private mergeResults;
+    /**
+     * 获取中等阈值
+     */
+    private getMediumThreshold;
+}
+export type { ToolAdapter } from './adapters/base-adapter.js';
+//# sourceMappingURL=tool-orchestrator.d.ts.map

package/dist/orchestrator/tool-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-orchestrator.d.ts","sourceRoot":"","sources":["../../src/orchestrator/tool-orchestrator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAA2B,MAAM,YAAY,CAAC;AACxF,OAAO,EAAqC,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAgB9D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,eAAe;IACf,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmB;IAEnD,cAAc;IACd,OAAO,CAAC,QAAQ,CAAuC;IAEvD,YAAY;IACZ,OAAO,CAAC,cAAc,CAA2B;IAEjD,yBAAyB;IACzB,OAAO,CAAC,aAAa,CAA0B;IAE/C;;;OAGG;gBACS,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAIrD;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAI3C;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAWlC;;;;;;;;;OASG;IACG,kBAAkB,CACtB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,MAA6B,GACrC,OAAO,CAAC,aAAa,EAAE,CAAC;IA0D3B;;;;;;;;;OASG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAUtF;;;;;;;;;;;OAWG;IACG,mBAAmB,CACvB,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC;IAoD3B;;;;;;;;;;OAUG;IACG,eAAe,CACnB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;IAmBxC;;OAEG;IACH,OAAO,CAAC,YAAY;IA0BpB;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAG3B;AAGD,YAAY,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/orchestrator/tool-orchestrator.js

@@ -0,0 +1,247 @@
+/**
+ * [META] ToolOrchestrator - 工具编排器
+ * [WHY] 负责执行工具、超时控制、错误隔离、回退级联，是连接 IntentRouter、适配器和结果融合的"胶水"组件。
+ */
+import { calculateConfidence, getThreshold } from './confidence.js';
+/**
+ * 默认超时时间（毫秒）
+ */
+const DEFAULT_TIMEOUT = 30000;
+/**
+ * 预定义回退链（仅内部调试用，默认关闭）
+ * 用户可见输出必须走 CodeMap 语义链路
+ */
+const FALLBACK_CHAINS = {
+    'ast-grep': ['rg-internal'], // AST搜索 → 文本搜索（内部）
+    'codemap': ['rg-internal'], // 结构分析 → 文本搜索（内部）
+};
+/**
+ * ToolOrchestrator 类 - 工具编排器核心控制器
+ */
+export class ToolOrchestrator {
+    /** 超时配置（毫秒） */
+    DEFAULT_TIMEOUT = DEFAULT_TIMEOUT;
+    /** 工具适配器映射 */
+    adapters = new Map();
+    /** 回退链配置 */
+    fallbackChains;
+    /** 已执行过的工具（用于防止回退链循环） */
+    executedTools = new Set();
+    /**
+     * 构造函数
+     * @param fallbackChains 自定义回退链配置
+     */
+    constructor(fallbackChains) {
+        this.fallbackChains = fallbackChains ?? FALLBACK_CHAINS;
+    }
+    /**
+     * 注册工具适配器
+     * @param adapter 工具适配器实例
+     */
+    registerAdapter(adapter) {
+        this.adapters.set(adapter.name, adapter);
+    }
+    /**
+     * 将 CodemapIntent 转换为适配器调用参数
+     * @param intent 意图对象
+     * @returns [keywords, options] 元组
+     */
+    convertIntentToAdapterArgs(intent) {
+        const keywords = intent.keywords || [];
+        const options = {
+            intent: intent.intent,
+            targets: intent.targets,
+            scope: intent.scope,
+            timeout: DEFAULT_TIMEOUT,
+        };
+        return [keywords, options];
+    }
+    /**
+     * 带超时控制的工具执行
+     *
+     * 使用 AbortController + Promise.race 实现真正的超时控制
+     *
+     * @param tool 工具名称
+     * @param intent 意图对象
+     * @param timeout 超时时间（毫秒），默认 30 秒
+     * @returns 工具执行结果数组
+     */
+    async runToolWithTimeout(tool, intent, timeout = this.DEFAULT_TIMEOUT) {
+        // console.debug(`执行工具: ${tool}, 超时: ${timeout}ms`);
+        const adapter = this.adapters.get(tool);
+        if (!adapter) {
+            // console.warn(`工具 ${tool} 未注册，返回空结果`);
+            return [];
+        }
+        // 检查工具是否可用
+        if (!(await adapter.isAvailable())) {
+            // console.warn(`工具 ${tool} 不可用，返回空结果`);
+            return [];
+        }
+        // 将 intent 转换为适配器调用参数
+        const [keywords, options] = this.convertIntentToAdapterArgs(intent);
+        // 创建 AbortController 用于超时控制
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => {
+            controller.abort();
+        }, timeout);
+        // 将 signal 添加到 options
+        const optionsWithSignal = {
+            ...options,
+            signal: controller.signal,
+            timeout,
+        };
+        // 使用 Promise.race 实现硬超时
+        const executionPromise = adapter.execute(keywords, optionsWithSignal);
+        try {
+            const results = await Promise.race([
+                executionPromise,
+                new Promise((_, reject) => {
+                    controller.signal.addEventListener('abort', () => {
+                        reject(new DOMException('工具执行超时', 'AbortError'));
+                    });
+                })
+            ]);
+            // console.debug(`工具 ${tool} 执行成功，返回 ${results.length} 条结果`);
+            return results;
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                // console.warn(`工具 ${tool} 执行超时 (${timeout}ms)`);
+            }
+            else {
+                // console.error(`工具 ${tool} 执行失败: ${error}`);
+            }
+            // 超时或错误时返回空结果，触发回退
+            return [];
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * 错误隔离的工具执行
+     *
+     * 包装工具执行，捕获所有异常
+     * 错误时返回空结果而非抛出异常（除致命错误外）
+     *
+     * @param tool 工具名称
+     * @param intent 意图对象
+     * @returns 安全执行结果
+     */
+    async runToolSafely(tool, intent) {
+        try {
+            const results = await this.runToolWithTimeout(tool, intent);
+            return { results };
+        }
+        catch (error) {
+            // console.error(`工具 ${tool} 执行异常:`, error);
+            return { results: [], error: error };
+        }
+    }
+    /**
+     * 回退执行
+     *
+     * 执行主工具并计算置信度
+     * 当置信度 < medium 阈值时，依次执行回退链
+     * 合并主工具和回退工具的结果（去重 + 排序）
+     * 达到阈值或回退链耗尽后停止
+     *
+     * @param intent 意图对象
+     * @param primaryTool 主工具名称
+     * @returns 执行结果
+     */
+    async executeWithFallback(intent, primaryTool) {
+        // 重置已执行工具集合
+        this.executedTools.clear();
+        // 1. 执行主工具
+        let results = await this.runToolWithTimeout(primaryTool, intent);
+        let confidence = calculateConfidence(results, intent.intent);
+        // console.debug(`主工具 ${primaryTool} 置信度: ${confidence.score.toFixed(2)} (${confidence.level})`);
+        // 2. 检查是否需要回退（低于当前 intent 的中等阈值）
+        const threshold = this.getMediumThreshold(intent.intent);
+        if (confidence.score < threshold) {
+            const fallbackTools = this.fallbackChains[primaryTool] || [];
+            for (const fallbackTool of fallbackTools) {
+                // 防止循环执行同一工具
+                if (this.executedTools.has(fallbackTool)) {
+                    // console.warn(`跳过已执行的工具: ${fallbackTool}`);
+                    continue;
+                }
+                this.executedTools.add(fallbackTool);
+                // console.warn(`[LOW CONFIDENCE] ${primaryTool} confidence: ${confidence.score.toFixed(2)}, trying ${fallbackTool}...`);
+                const fallbackResults = await this.runToolWithTimeout(fallbackTool, intent);
+                const fallbackConfidence = calculateConfidence(fallbackResults, intent.intent);
+                // 3. 合并结果（去重 + 排序）
+                results = this.mergeResults(results, fallbackResults);
+                // 更新置信度（取最大值）
+                confidence = {
+                    score: Math.max(confidence.score, fallbackConfidence.score),
+                    level: confidence.score > fallbackConfidence.score ? confidence.level : fallbackConfidence.level,
+                    reasons: [...confidence.reasons, ...fallbackConfidence.reasons]
+                };
+                // console.debug(`回退工具 ${fallbackTool} 置信度: ${fallbackConfidence.score.toFixed(2)}, 合并后: ${confidence.score.toFixed(2)}`);
+                // 4. 达到阈值则停止回退
+                if (confidence.score >= threshold) {
+                    confidence.reasons.push(`回退到 ${fallbackTool} 后达到阈值`);
+                    break;
+                }
+            }
+        }
+        return { results, tool: primaryTool, confidence };
+    }
+    /**
+     * 并行执行
+     *
+     * 并行执行多个工具
+     * 每个工具独立超时控制
+     * 返回按工具分组的结果
+     *
+     * @param intent 意图对象
+     * @param tools 工具名称数组
+     * @returns 按工具分组的结果映射
+     */
+    async executeParallel(intent, tools) {
+        const resultsMap = new Map();
+        // 并行执行所有工具
+        const promises = tools.map(async (tool) => {
+            const results = await this.runToolWithTimeout(tool, intent);
+            return { tool, results };
+        });
+        const allResults = await Promise.all(promises);
+        // 收集结果
+        for (const { tool, results } of allResults) {
+            resultsMap.set(tool, results);
+        }
+        return resultsMap;
+    }
+    /**
+     * 合并结果（去重 + 排序）
+     */
+    mergeResults(primary, fallback) {
+        // 合并所有结果
+        const allResults = [...primary, ...fallback];
+        // 去重（基于 file:line）
+        const seen = new Map();
+        for (const result of allResults) {
+            const key = `${result.file}:${result.line ?? ''}`;
+            const existing = seen.get(key);
+            if (!existing) {
+                seen.set(key, result);
+            }
+            else if (result.relevance > existing.relevance) {
+                // 保留分数更高的结果
+                seen.set(key, result);
+            }
+        }
+        // 按 relevance 降序排序
+        return Array.from(seen.values()).sort((a, b) => b.relevance - a.relevance);
+    }
+    /**
+     * 获取中等阈值
+     */
+    getMediumThreshold(intent) {
+        return getThreshold(intent, 'medium');
+    }
+}
+//# sourceMappingURL=tool-orchestrator.js.map

package/dist/orchestrator/tool-orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-orchestrator.js","sourceRoot":"","sources":["../../src/orchestrator/tool-orchestrator.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/types.d.ts

@@ -0,0 +1,162 @@
+import type { SourceLocation } from '../types/index.js';
+/**
+ * UnifiedResult 统一结果接口
+ * 用于规范化不同工具的输出格式
+ */
+export interface UnifiedResult {
+    /** 唯一标识 */
+    id: string;
+    /** 来源工具 */
+    source: 'codemap' | 'ast-grep' | 'rg-internal' | 'ai-feed';
+    /** 工具返回的原始分数（0-1） */
+    toolScore: number;
+    /** 结果类型 */
+    type: 'file' | 'symbol' | 'code' | 'documentation' | 'risk-assessment';
+    /** 文件路径 */
+    file: string;
+    /** 行号（可选）- 保留向后兼容，建议使用 location */
+    line?: number;
+    /** 结构化位置信息（新增） */
+    location?: SourceLocation;
+    /** 截断后的内容 */
+    content: string;
+    /** 归一化相关度（0-1） */
+    relevance: number;
+    /** 匹配的关键词 */
+    keywords: string[];
+    /** 元数据（可选） */
+    metadata?: {
+        /** 符号类型 */
+        symbolType?: 'class' | 'function' | 'interface' | 'variable';
+        /** 依赖文件列表 */
+        dependencies?: string[];
+        /** 关联的测试文件 */
+        testFile?: string;
+        /** 提交次数 */
+        commitCount?: number;
+        /** 依赖复杂度评分 */
+        gravity?: number;
+        /** 热度评分对象 */
+        heatScore?: HeatScore;
+        /** 影响文件数 */
+        impactCount?: number;
+        /** 是否稳定 */
+        stability?: boolean;
+        /** 风险等级 */
+        riskLevel?: 'high' | 'medium' | 'low';
+    };
+}
+/**
+ * HeatScore 热度评分接口
+ */
+export interface HeatScore {
+    /** 30天修改次数 */
+    freq30d: number;
+    /** 最后提交标签 */
+    lastType: string;
+    /** 最后修改日期（ISO 字符串格式） */
+    lastDate: string | null;
+    /** 是否稳定 (沉积岩 vs 火山灰) */
+    stability: boolean;
+}
+/**
+ * ToolOptions 工具选项类型
+ * 用于 execute 方法的 options 参数
+ */
+export interface ToolOptions {
+    /** 超时时间（毫秒） */
+    timeout?: number;
+    /** 返回结果数量上限 */
+    topK?: number;
+    /** 是否包含测试文件 */
+    includeTests?: boolean;
+    /** 其他扩展选项 */
+    [key: string]: unknown;
+}
+/**
+ * IntentType 意图类型
+ */
+export type IntentType = 'impact' | 'dependency' | 'search' | 'documentation' | 'complexity' | 'overview' | 'refactor' | 'reference';
+/**
+ * CodemapIntent Codemap 意图对象
+ */
+export interface CodemapIntent {
+    intent: IntentType;
+    targets: string[];
+    keywords: string[];
+    scope: 'direct' | 'transitive';
+    tool: string;
+    secondary?: string;
+}
+/**
+ * AnalyzeArgs 分析命令参数
+ */
+export interface AnalyzeArgs {
+    intent?: string;
+    targets?: string[];
+    keywords?: string[];
+    scope?: 'direct' | 'transitive';
+    topK?: number;
+    includeTests?: boolean;
+    includeGitHistory?: boolean;
+    json?: boolean;
+    /** 输出完全结构化的 JSON（不包含自然语言字符串） */
+    structured?: boolean;
+    outputMode?: 'machine' | 'human';
+}
+/**
+ * Confidence 置信度对象
+ */
+export interface Confidence {
+    /** 置信度分数 (0-1) */
+    score: number;
+    /** 置信度级别 */
+    level: 'high' | 'medium' | 'low';
+}
+/**
+ * ConfidenceResult 置信度结果
+ */
+export interface ConfidenceResult {
+    /** 置信度分数 (0-1) */
+    score: number;
+    /** 置信度级别 */
+    level: 'high' | 'medium' | 'low';
+    /** 置信度来源说明 */
+    reasons: string[];
+}
+/**
+ * CodemapOutput Codemap 统一输出格式
+ * 用于规范 analyze 命令的 machine/json 输出
+ */
+export interface CodemapOutput {
+    /** Schema 版本，格式: "v1.0.0" */
+    schemaVersion: string;
+    /** 执行的 intent 类型 */
+    intent: string;
+    /** 主要工具 */
+    tool: string;
+    /** 置信度信息 */
+    confidence: Confidence;
+    /** 结果列表 */
+    results: UnifiedResult[];
+    /** 可选的元数据 */
+    metadata?: {
+        /** 执行时间（毫秒） */
+        executionTime?: number;
+        /** 结果总数 */
+        resultCount?: number;
+        /** 总数（兼容旧字段） */
+        total?: number;
+        /** 范围 */
+        scope?: string;
+    };
+}
+/**
+ * 类型守卫：检查对象是否为 CodemapOutput
+ */
+export declare function isCodemapOutput(obj: unknown): obj is CodemapOutput;
+/**
+ * 计算置信度级别
+ */
+export declare function calculateConfidenceLevel(score: number): 'high' | 'medium' | 'low';
+//# sourceMappingURL=types.d.ts.map

package/dist/orchestrator/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/orchestrator/types.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/types.js

@@ -0,0 +1,39 @@
+// [META] since:2026-03-02 | owner:orchestrator-team | stable:true
+// [WHY] Core type definitions with optional fields for flexible unified results
+/**
+ * 类型守卫：检查对象是否为 CodemapOutput
+ */
+export function isCodemapOutput(obj) {
+    if (typeof obj !== 'object' || obj === null) {
+        return false;
+    }
+    const output = obj;
+    // 检查必需字段
+    if (typeof output.schemaVersion !== 'string')
+        return false;
+    if (typeof output.intent !== 'string')
+        return false;
+    if (typeof output.tool !== 'string')
+        return false;
+    if (typeof output.confidence !== 'object' || output.confidence === null)
+        return false;
+    const confidence = output.confidence;
+    if (typeof confidence.score !== 'number')
+        return false;
+    if (!['high', 'medium', 'low'].includes(confidence.level))
+        return false;
+    if (!Array.isArray(output.results))
+        return false;
+    return true;
+}
+/**
+ * 计算置信度级别
+ */
+export function calculateConfidenceLevel(score) {
+    if (score >= 0.7)
+        return 'high';
+    if (score >= 0.4)
+        return 'medium';
+    return 'low';
+}
+//# sourceMappingURL=types.js.map

package/dist/orchestrator/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/orchestrator/types.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,gFAAgF;AA6KhF;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,MAAM,GAAG,GAA8B,CAAC;IAE9C,SAAS;IACT,IAAI,OAAO,MAAM,CAAC,aAAa,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC3D,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACpD,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClD,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,IAAI,MAAM,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAEtF,MAAM,UAAU,GAAG,MAAM,CAAC,UAAqC,CAAC;IAChE,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACvD,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAe,CAAC;QAAE,OAAO,KAAK,CAAC;IAElF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAEjD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAa;IACpD,IAAI,KAAK,IAAI,GAAG;QAAE,OAAO,MAAM,CAAC;IAChC,IAAI,KAAK,IAAI,GAAG;QAAE,OAAO,QAAQ,CAAC;IAClC,OAAO,KAAK,CAAC;AACf,CAAC"}