spectra-cli 4.1.1

package/dist/cli/commands/watch.js

@@ -0,0 +1,188 @@
+/**
+ * watch 子命令 handler
+ * 监听文件变更，自动触发增量文档同步
+ */
+import { resolve } from 'node:path';
+import { execSync } from 'node:child_process';
+import { runBatch } from '../../batch/batch-orchestrator.js';
+import { checkAuth, handleError, EXIT_CODES } from '../utils/error-handler.js';
+import { loadProjectConfig, mergeConfig } from '../../config/project-config.js';
+import { FileWatcher, CATEGORY_LABEL } from '../../watcher/index.js';
+// ---------------------------------------------------------------------------
+// 模块级状态变量（进程内串行保护，FR-011）
+// ---------------------------------------------------------------------------
+/** 是否正在执行 batch */
+let isRunning = false;
+/** 收集等待中的变更文件（batch 执行期间新触发的变更）*/
+let pendingNextRound = new Set();
+/** 是否已收到停止信号 */
+let pendingShutdown = false;
+// ---------------------------------------------------------------------------
+// 辅助函数
+// ---------------------------------------------------------------------------
+/**
+ * 检测是否有外部 batch 进程正在运行（FR-010）
+ * 宁可漏检也不崩溃——异常时返回 false
+ */
+export function isExternalBatchRunning() {
+    try {
+        const output = execSync('pgrep -f "spectra batch"', {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        // 排除空输出（pgrep 无匹配时抛异常，但某些平台可能返回空字符串）
+        return output.trim().length > 0;
+    }
+    catch {
+        // pgrep 返回非 0 表示无匹配进程
+        return false;
+    }
+}
+/**
+ * 注册 SIGINT / SIGTERM 信号处理器（FR-003）
+ * 等待当前 batch 完成后再退出，避免留下孤儿进程
+ */
+function setupSignalHandlers(watcher) {
+    const shutdown = async () => {
+        // 防止重复触发
+        if (pendingShutdown)
+            return;
+        pendingShutdown = true;
+        console.log('\n[watch] 收到停止信号，等待当前更新完成...');
+        if (!isRunning) {
+            // 当前没有 batch 在跑，直接退出
+            await watcher.stop();
+            process.exit(EXIT_CODES.SUCCESS);
+        }
+        // 否则，batch 完成回调中负责检查 pendingShutdown 并退出
+    };
+    process.once('SIGINT', () => void shutdown());
+    process.once('SIGTERM', () => void shutdown());
+}
+/**
+ * 打印变更文件列表（FR-006）
+ */
+function printChangedFiles(events) {
+    console.log(`\n[watch] 检测到 ${events.length} 个文件变更：`);
+    for (const event of events) {
+        const label = CATEGORY_LABEL[event.category];
+        console.log(`  ${label} ${event.path}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// 主入口
+// ---------------------------------------------------------------------------
+/**
+ * 执行 watch 子命令
+ * 启动文件监听，变更触发后自动调用 runBatch({ incremental: true })
+ */
+export async function runWatchCommand(command) {
+    if (!checkAuth()) {
+        process.exitCode = EXIT_CODES.API_ERROR;
+        return;
+    }
+    // 解析配置（FR-002）
+    const projectRoot = resolve(command.target ?? process.cwd());
+    const debounceMs = command.watchDebounce !== undefined
+        ? command.watchDebounce * 1000 // CLI 传入的是秒，内部使用毫秒
+        : 3000;
+    const verbose = command.watchVerbose ?? false;
+    // 加载项目级配置（与 batch.ts 模式一致）
+    const fileConfig = loadProjectConfig(projectRoot);
+    const merged = mergeConfig({}, fileConfig, new Set());
+    console.log(`[watch] 正在启动文件监听...`);
+    console.log(`[watch] 项目根目录: ${projectRoot}`);
+    console.log(`[watch] Debounce 时长: ${debounceMs / 1000} 秒`);
+    // 重置模块级状态（支持同一进程多次调用，如测试场景）
+    isRunning = false;
+    pendingNextRound = new Set();
+    pendingShutdown = false;
+    // 先实例化 FileWatcher（回调稍后赋值，避免闭包时序依赖）
+    let watcher;
+    // onChange 回调：debounce 到期后触发
+    const handleChange = async (events) => {
+        printChangedFiles(events);
+        // FR-010：外部 batch 进程检测（队列变更，不丢弃）
+        if (isExternalBatchRunning()) {
+            for (const event of events) {
+                pendingNextRound.add(event.path);
+            }
+            console.log(`[watch] 检测到外部 spectra batch 正在运行，${events.length} 个变更已加入等待队列`);
+            return;
+        }
+        // FR-011：进程内串行保护
+        if (isRunning) {
+            for (const event of events) {
+                pendingNextRound.add(event.path);
+            }
+            console.log(`[watch] 当前有 batch 正在执行，${events.length} 个变更已加入等待队列`);
+            return;
+        }
+        // 启动 batch 执行循环
+        isRunning = true;
+        try {
+            await executeBatchLoop(projectRoot, verbose, merged.outputDir, merged.languages, merged.includeDocs, merged.includeImages);
+        }
+        finally {
+            isRunning = false;
+            if (pendingShutdown) {
+                console.log('[watch] 更新完成，正在退出...');
+                await watcher.stop();
+                process.exit(EXIT_CODES.SUCCESS);
+            }
+        }
+    };
+    // 实例化 FileWatcher（FR-001）
+    watcher = new FileWatcher({ projectRoot, debounceMs, verbose }, (events) => void handleChange(events));
+    // 注册信号处理器（FR-003）
+    setupSignalHandlers(watcher);
+    try {
+        // 启动监听（FR-001）
+        await watcher.start();
+        // 提示用户避免并发运行 batch（WONTFIX 缓解措施）
+        console.log('[watch] 注意：请勿同时运行 spectra batch，两者会竞争同一 checkpoint 文件');
+        // FR-013：启动完成后打印"已就绪"消息
+        console.log('[watch] 已就绪，监听文件变更中... (Ctrl+C 停止)');
+    }
+    catch (err) {
+        process.exitCode = handleError(err);
+    }
+}
+/**
+ * 执行 batch 并在 pendingNextRound 非空时继续下一轮
+ * 失败时不清空等待状态（FR-009）
+ */
+async function executeBatchLoop(projectRoot, verbose, outputDir, languages, includeDocs, includeImages) {
+    // 循环执行直到没有待处理变更
+    while (true) {
+        const batchStartTime = Date.now();
+        console.log('[watch] 触发增量更新...');
+        try {
+            // FR-007：复用 runBatch({ incremental: true })，透传配置文件的所有选项
+            const result = await runBatch(projectRoot, { incremental: true, outputDir, languages, includeDocs, includeImages });
+            const elapsed = ((Date.now() - batchStartTime) / 1000).toFixed(1);
+            console.log(`[watch] 增量更新完成（${elapsed}s）：` +
+                `成功 ${result.successful.length} / 总计 ${result.totalModules}` +
+                (result.failed.length > 0 ? `，失败 ${result.failed.length}` : ''));
+        }
+        catch (err) {
+            // FR-009：失败时不清空 pendingNextRound，保证下次触发仍会重新处理
+            const errMsg = err instanceof Error ? err.message : String(err);
+            console.error(`[watch] 增量更新失败: ${errMsg}`);
+            if (verbose) {
+                console.error(err);
+            }
+            // 失败后不继续循环，等待下次文件变更触发
+            return;
+        }
+        // 检查是否有新积压的变更
+        if (pendingNextRound.size === 0) {
+            // 没有待处理变更，退出循环
+            break;
+        }
+        // 有待处理变更，继续下一轮
+        console.log(`[watch] 有 ${pendingNextRound.size} 个变更在等待，启动下一轮更新...`);
+        pendingNextRound.clear();
+    }
+}
+//# sourceMappingURL=watch.js.map

package/dist/cli/commands/watch.js.map

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

package/dist/cli/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * spectra CLI 入口点
+ * 全局命令调度器
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA;;;GAGG"}

package/dist/cli/index.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * spectra CLI 入口点
+ * 全局命令调度器
+ */
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from './utils/parse-args.js';
+import { printError } from './utils/error-handler.js';
+import { runGenerate } from './commands/generate.js';
+import { runBatchCommand } from './commands/batch.js';
+import { runDiff } from './commands/diff.js';
+import { runInit } from './commands/init.js';
+import { runPrepare } from './commands/prepare.js';
+import { runAuthStatus } from './commands/auth-status.js';
+import { runMcpServer } from './commands/mcp-server.js';
+import { runPanoramicCommand } from './commands/panoramic.js';
+import { runCacheCommand } from './commands/cache.js';
+import { runWatchCommand } from './commands/watch.js';
+import { runGraphCommand } from './commands/graph.js';
+import { runCommunityCommand } from './commands/community.js';
+import { runQueryCommand } from './commands/query.js';
+import { runInstall } from './commands/install.js';
+import { runExportCommand } from './commands/export.js';
+import { runDirectionAuditCommand } from './commands/direction-audit.js';
+import { bootstrapAdapters } from '../adapters/index.js';
+import { bootstrapGenerators } from '../panoramic/generator-registry.js';
+import { bootstrapParsers } from '../panoramic/parser-registry.js';
+// 读取 package.json 版本号
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgPath = resolve(__dirname, '..', '..', 'package.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+const version = pkg.version;
+// 帮助文本
+const HELP_TEXT = `spectra — 代码逆向工程 Spec 生成工具 v${version}
+
+用法:
+  spectra generate <target> [--deep] [--output-dir <dir>]
+  spectra prepare <target> [--deep]
+  spectra batch [--force] [--incremental] [--languages <lang,...>] [--include-docs] [--include-images] [--mode <full|reading|code-only>] [--hyperedges] [--concurrency <N>] [--no-html] [--output-dir <dir>]
+  spectra diff <spec-file> <source> [--output-dir <dir>]
+  spectra init [--global] [--remove] [--target <claude|codex|both>]
+  spectra auth-status [--verify]
+  spectra panoramic <cross-package|architecture-ir|overview> [--json] [--project-root <dir>]
+  spectra cache <stats|clear> [--generator <id>] [--output-dir <dir>]
+  spectra watch [--debounce <seconds>] [--verbose]
+  spectra graph [--directed] [--output-dir <dir>]
+  spectra community [--min-size <N>] [--output-dir <dir>]
+  spectra query "<问题>" [--budget <N>] [--format json|text]
+  spectra install [--git] [--remove]
+  spectra export --format <obsidian|html> [--output-dir <dir>]
+  spectra direction-audit [--graph <path>] [--output <path>] [--format json|text]
+  spectra direction-audit --snapshot <path>
+  spectra direction-audit --compare-snapshot <path>
+  spectra mcp-server
+  spectra --version / --help
+
+子命令:
+  generate      对指定文件或目录生成 Spec（需要认证）
+  prepare       AST 预处理 + 上下文组装，输出到 stdout（无需认证）
+  batch         批量生成当前项目所有模块的 Spec
+  diff          检测 Spec 与源代码之间的漂移
+  init          安装 skills 到 Claude Code / Codex 的项目或全局目录
+  auth-status   查看当前认证状态（API Key / Claude CLI / Codex CLI）
+  panoramic     运行 panoramic 架构分析（cross-package / architecture-ir / overview）
+  cache         管理内容哈希缓存（stats / clear）
+  watch         监听文件变更，自动触发增量文档同步
+  graph         构建知识图谱并输出 _meta/graph.json
+  community     社区检测与架构洞察分析，输出 _meta/GRAPH_REPORT.md
+  query         查询知识图谱，返回相关模块及依赖关系子图
+  install       安装/卸载 Claude Code PreToolUse hook 和 git post-commit hook（≠ init：init = skill 安装，install = hook 安装）
+  export        将知识图谱导出为 Obsidian Vault 或 HTML 交互式可视化
+  direction-audit 依赖方向自查工具（SC-006 CI regression guard）
+  mcp-server    启动 MCP stdio server（供 Claude Code 插件调用）
+
+认证:
+  支持三种认证方式（自动检测，优先级按当前运行时动态排序）:
+  1. ANTHROPIC_API_KEY 环境变量（直接 SDK 调用）
+  2. Claude Code CLI 订阅登录（spawn CLI 子进程代理）
+  3. Codex CLI 登录态（spawn CLI 子进程代理）
+
+选项:
+  --global, -g   安装到全局 ~/.claude/skills/ 或 ~/.codex/skills/（由 --target 决定，仅 init）
+  --remove       移除已安装的 skills（仅 init）或 hooks（仅 install）
+  --target       目标平台: claude | codex | both（仅 init，默认按当前运行时自动选择）
+  --verify       在线验证认证凭证（仅 auth-status）
+  --deep         包含函数体进行深度分析（generate / prepare）
+  --force        强制重新生成所有 Spec（仅 batch）
+  --incremental  仅重生成受影响的 Spec（仅 batch）
+  --languages    仅处理指定语言，逗号分隔（如 typescript,python）（仅 batch）
+  --include-docs 启用 Markdown 文档和 OpenAPI/AsyncAPI 规范提取（仅 batch）
+  --include-images 启用图像/图表 Vision 提取（仅 batch）
+  --mode         批处理运行模式: full（默认，完整文档，LLM 全量）| reading（省约 38% 时间，模块级 LLM 仍运行，跳过架构叙事/ADR/产品文档层）| code-only（纯 AST，< 30s，无 LLM，最快）（仅 batch）
+  --hyperedges   启用 hyperedge LLM 提取（仅 batch + mode=full 生效，默认 false；可用 env SPECTRA_HYPEREDGES_ENABLED=true 等价开启）
+  --enable-adr   显式启用 ADR pipeline（v4.0.1 临时禁用，将在 v4.1 evidence-binding 重构后恢复；默认 false）（仅 batch）
+  --concurrency  最大并发模块数（仅 batch，默认 3；优先级 CLI > spec-driver.config.yaml batch.concurrency > 默认 3；≤0 / 非整数会规范化为 1 并打印 warn）
+  --html         显式启用 graph.html 生成（仅 batch；Feature 140 起默认已启用，本 flag 仅作显式标注，不影响行为）
+  --no-html      禁用 graph.html 生成（仅 batch；CI / 资源紧张场景使用；与 --html 同时出现时 --no-html 优先）
+  --json         以 JSON 格式输出结果（仅 panoramic）
+  --project-root 指定分析目标目录（仅 panoramic，默认为 cwd）
+  --generator    指定 generator ID（仅 cache clear）
+  --debounce     文件变更静默等待时长（秒，默认 3，仅 watch）
+  --verbose      打印详细变更日志（仅 watch）
+  --output-dir   自定义输出目录
+  --directed     输出有向图（仅 graph 命令）
+  --min-size     最小社区节点数过滤（仅 community 命令）
+  --budget       返回节点数量上限（仅 query 命令，默认 50）
+  --format       输出格式 text|json（仅 query 命令，默认 text）
+  --git          同时操作 git post-commit hook（仅 install）
+  --format       导出格式 obsidian|html（仅 export 命令，必填）
+  --version, -v  显示版本号
+  --help, -h     显示帮助信息`;
+async function main() {
+    // 注册所有语言适配器（在命令调度前执行）
+    bootstrapAdapters();
+    // 注册所有文档生成器
+    bootstrapGenerators();
+    // 注册所有制品解析器
+    bootstrapParsers();
+    const result = parseArgs(process.argv.slice(2));
+    if (!result.ok) {
+        printError(result.error.message);
+        console.log();
+        console.log(HELP_TEXT);
+        process.exitCode = 1;
+        return;
+    }
+    const { command } = result;
+    if (command.version) {
+        console.log(`spectra v${version}`);
+        return;
+    }
+    if (command.help) {
+        console.log(HELP_TEXT);
+        return;
+    }
+    switch (command.subcommand) {
+        case 'generate':
+            await runGenerate(command, version);
+            break;
+        case 'batch':
+            await runBatchCommand(command, version);
+            break;
+        case 'diff':
+            await runDiff(command, version);
+            break;
+        case 'init':
+            runInit(command);
+            break;
+        case 'prepare':
+            await runPrepare(command, version);
+            break;
+        case 'auth-status':
+            await runAuthStatus(command);
+            break;
+        case 'panoramic':
+            await runPanoramicCommand(command);
+            break;
+        case 'cache':
+            await runCacheCommand(command);
+            break;
+        case 'watch':
+            await runWatchCommand(command);
+            break;
+        case 'graph':
+            await runGraphCommand(command);
+            break;
+        case 'community':
+            await runCommunityCommand(command);
+            break;
+        case 'query':
+            await runQueryCommand(command);
+            break;
+        case 'install':
+            runInstall(command);
+            break;
+        case 'export':
+            await runExportCommand(command);
+            break;
+        case 'direction-audit':
+            await runDirectionAuditCommand(command);
+            break;
+        case 'mcp-server':
+            await runMcpServer(command);
+            break;
+    }
+}
+main().catch((err) => {
+    printError(`致命错误: ${err instanceof Error ? err.message : String(err)}`);
+    process.exitCode = 2;
+});
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

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

package/dist/cli/utils/error-handler.d.ts

@@ -0,0 +1,41 @@
+/**
+ * CLI 错误处理工具
+ * 友好的中文错误信息输出
+ */
+/** 退出码定义 */
+export declare const EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly TARGET_ERROR: 1;
+    readonly API_ERROR: 2;
+    /** Feature 127: 预算 gate 主动取消，供 CI 区分"成功 0 模块"和"被预算拦截" */
+    readonly BUDGET_EXCEEDED: 3;
+};
+/**
+ * 验证目标路径是否存在
+ * @returns 如果路径不存在则输出错误信息并返回 false
+ */
+export declare function validateTargetPath(target: string): boolean;
+/**
+ * 检查 ANTHROPIC_API_KEY 环境变量
+ * @deprecated 使用 checkAuth() 替代，支持 API Key 和 CLI 代理两种认证方式
+ * @returns 如果缺失则输出错误信息并返回 false
+ */
+export declare function checkApiKey(): boolean;
+/**
+ * 检查是否有可用的认证方式（API Key 或 Claude CLI）
+ * @returns 如果无可用方式则输出错误信息并返回 false
+ */
+export declare function checkAuth(): boolean;
+/**
+ * 处理运行时错误，输出友好信息
+ */
+export declare function handleError(err: unknown): number;
+/**
+ * 输出错误信息到 stderr
+ */
+export declare function printError(message: string): void;
+/**
+ * 输出警告信息
+ */
+export declare function printWarning(message: string): void;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/cli/utils/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,YAAY;AACZ,eAAO,MAAM,UAAU;;;;IAIrB,yDAAyD;;CAEjD,CAAC;AAEX;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAO1D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,OAAO,CASrC;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAYnC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAmBhD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAElD"}

package/dist/cli/utils/error-handler.js

@@ -0,0 +1,90 @@
+/**
+ * CLI 错误处理工具
+ * 友好的中文错误信息输出
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { detectAuth } from '../../auth/auth-detector.js';
+/** 退出码定义 */
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    TARGET_ERROR: 1,
+    API_ERROR: 2,
+    /** Feature 127: 预算 gate 主动取消，供 CI 区分"成功 0 模块"和"被预算拦截" */
+    BUDGET_EXCEEDED: 3,
+};
+/**
+ * 验证目标路径是否存在
+ * @returns 如果路径不存在则输出错误信息并返回 false
+ */
+export function validateTargetPath(target) {
+    const resolved = resolve(target);
+    if (!existsSync(resolved)) {
+        printError(`目标路径不存在: ${resolved}`);
+        return false;
+    }
+    return true;
+}
+/**
+ * 检查 ANTHROPIC_API_KEY 环境变量
+ * @deprecated 使用 checkAuth() 替代，支持 API Key 和 CLI 代理两种认证方式
+ * @returns 如果缺失则输出错误信息并返回 false
+ */
+export function checkApiKey() {
+    if (!process.env['ANTHROPIC_API_KEY']) {
+        printError('未设置 ANTHROPIC_API_KEY 环境变量\n' +
+            '  请设置后重试: export ANTHROPIC_API_KEY=your-key-here');
+        return false;
+    }
+    return true;
+}
+/**
+ * 检查是否有可用的认证方式（API Key 或 Claude CLI）
+ * @returns 如果无可用方式则输出错误信息并返回 false
+ */
+export function checkAuth() {
+    const result = detectAuth();
+    if (result.preferred) {
+        return true;
+    }
+    printError('未找到可用的认证方式。请选择以下方式之一：\n' +
+        '  1. 设置环境变量: export ANTHROPIC_API_KEY=your-key-here\n' +
+        '  2. 安装并登录 Claude Code: claude auth login\n' +
+        '  3. 安装并登录 Codex CLI: codex login');
+    return false;
+}
+/**
+ * 处理运行时错误，输出友好信息
+ */
+export function handleError(err) {
+    if (err instanceof Error) {
+        // API 相关错误
+        if (err.message.includes('API') || err.message.includes('api_key') || err.message.includes('authentication')) {
+            printError(`LLM API 错误: ${err.message}`);
+            return EXIT_CODES.API_ERROR;
+        }
+        // 文件系统错误
+        if ('code' in err && err.code === 'ENOENT') {
+            printError(`文件或目录不存在: ${err.message}`);
+            return EXIT_CODES.TARGET_ERROR;
+        }
+        printError(err.message);
+    }
+    else {
+        printError(`未知错误: ${String(err)}`);
+    }
+    return EXIT_CODES.API_ERROR;
+}
+/**
+ * 输出错误信息到 stderr
+ */
+export function printError(message) {
+    console.error(`✗ 错误: ${message}`);
+}
+/**
+ * 输出警告信息
+ */
+export function printWarning(message) {
+    console.warn(`⚠ 警告: ${message}`);
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/cli/utils/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../../src/cli/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,YAAY;AACZ,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,OAAO,EAAE,CAAC;IACV,YAAY,EAAE,CAAC;IACf,SAAS,EAAE,CAAC;IACZ,yDAAyD;IACzD,eAAe,EAAE,CAAC;CACV,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,UAAU,CAAC,YAAY,QAAQ,EAAE,CAAC,CAAC;QACnC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACtC,UAAU,CACR,8BAA8B;YAC9B,kDAAkD,CACnD,CAAC;QACF,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,UAAU,CACR,yBAAyB;QACzB,uDAAuD;QACvD,6CAA6C;QAC7C,mCAAmC,CACpC,CAAC;IACF,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,WAAW;QACX,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;YAC7G,UAAU,CAAC,eAAe,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACzC,OAAO,UAAU,CAAC,SAAS,CAAC;QAC9B,CAAC;QAED,SAAS;QACT,IAAI,MAAM,IAAI,GAAG,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtE,UAAU,CAAC,aAAa,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACvC,OAAO,UAAU,CAAC,YAAY,CAAC;QACjC,CAAC;QAED,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;SAAM,CAAC;QACN,UAAU,CAAC,SAAS,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,UAAU,CAAC,SAAS,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,CAAC,KAAK,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,CAAC,IAAI,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;AACnC,CAAC"}