spectra-cli 4.1.1

package/dist/diff/structural-diff.js

@@ -0,0 +1,171 @@
+let nextId = 0;
+function generateId() {
+    return `drift-${Date.now()}-${nextId++}`;
+}
+/**
+ * 比较两个 CodeSkeleton，识别导出符号中的结构差异
+ *
+ * @param oldSkeleton - 基线骨架（spec 生成时）
+ * @param newSkeleton - 当前源代码骨架
+ * @returns DriftItem[]
+ */
+export function compareSkeletons(oldSkeleton, newSkeleton) {
+    const items = [];
+    // 构建旧/新导出的映射
+    const oldExports = new Map();
+    const newExports = new Map();
+    for (const exp of oldSkeleton.exports) {
+        oldExports.set(exp.name, exp);
+    }
+    for (const exp of newSkeleton.exports) {
+        newExports.set(exp.name, exp);
+    }
+    // 检测删除的导出（HIGH）
+    for (const [name, oldExp] of oldExports) {
+        if (!newExports.has(name)) {
+            items.push({
+                id: generateId(),
+                severity: 'HIGH',
+                category: 'Interface',
+                changeType: 'removal',
+                location: `${oldSkeleton.filePath}:${oldExp.startLine}`,
+                symbolName: name,
+                description: `导出符号 \`${name}\` (${oldExp.kind}) 已被删除 — Breaking Change`,
+                oldValue: oldExp.signature,
+                newValue: null,
+                proposedUpdate: `从接口定义章节中移除 \`${name}\` 的文档`,
+                detectedBy: 'structural',
+            });
+        }
+    }
+    // 检测新增的导出（LOW）
+    for (const [name, newExp] of newExports) {
+        if (!oldExports.has(name)) {
+            items.push({
+                id: generateId(),
+                severity: 'LOW',
+                category: 'Interface',
+                changeType: 'addition',
+                location: `${newSkeleton.filePath}:${newExp.startLine}`,
+                symbolName: name,
+                description: `新增导出符号 \`${name}\` (${newExp.kind})`,
+                oldValue: null,
+                newValue: newExp.signature,
+                proposedUpdate: `在接口定义章节中添加 \`${name}\` 的文档`,
+                detectedBy: 'structural',
+            });
+        }
+    }
+    // 检测修改的导出（MEDIUM）
+    for (const [name, oldExp] of oldExports) {
+        const newExp = newExports.get(name);
+        if (!newExp)
+            continue;
+        // 比较签名
+        if (oldExp.signature !== newExp.signature) {
+            items.push({
+                id: generateId(),
+                severity: 'MEDIUM',
+                category: 'Interface',
+                changeType: 'modification',
+                location: `${newSkeleton.filePath}:${newExp.startLine}`,
+                symbolName: name,
+                description: `导出符号 \`${name}\` 的签名已修改`,
+                oldValue: oldExp.signature,
+                newValue: newExp.signature,
+                proposedUpdate: `更新接口定义章节中 \`${name}\` 的签名为 \`${newExp.signature}\``,
+                detectedBy: 'structural',
+            });
+            continue;
+        }
+        // 比较类型参数
+        const oldTypeParams = (oldExp.typeParameters ?? []).join(', ');
+        const newTypeParams = (newExp.typeParameters ?? []).join(', ');
+        if (oldTypeParams !== newTypeParams) {
+            items.push({
+                id: generateId(),
+                severity: 'MEDIUM',
+                category: 'Interface',
+                changeType: 'modification',
+                location: `${newSkeleton.filePath}:${newExp.startLine}`,
+                symbolName: name,
+                description: `导出符号 \`${name}\` 的类型参数已修改`,
+                oldValue: oldTypeParams || '(无)',
+                newValue: newTypeParams || '(无)',
+                proposedUpdate: `更新 \`${name}\` 的类型参数文档`,
+                detectedBy: 'structural',
+            });
+        }
+        // 比较成员（类/接口）
+        if (oldExp.members && newExp.members) {
+            const memberDiffs = compareMembers(oldExp.members, newExp.members, name, newSkeleton.filePath, newExp.startLine);
+            items.push(...memberDiffs);
+        }
+    }
+    return items;
+}
+/**
+ * 比较类/接口的成员差异
+ */
+function compareMembers(oldMembers, newMembers, parentName, filePath, startLine) {
+    const items = [];
+    const oldMap = new Map(oldMembers.map((m) => [m.name, m]));
+    const newMap = new Map(newMembers.map((m) => [m.name, m]));
+    // 删除的成员
+    for (const [name, oldMember] of oldMap) {
+        if (!newMap.has(name)) {
+            items.push({
+                id: generateId(),
+                severity: 'MEDIUM',
+                category: 'Interface',
+                changeType: 'removal',
+                location: `${filePath}:${startLine}`,
+                symbolName: `${parentName}.${name}`,
+                description: `成员 \`${parentName}.${name}\` (${oldMember.kind}) 已被删除`,
+                oldValue: oldMember.signature,
+                newValue: null,
+                proposedUpdate: `从 \`${parentName}\` 的文档中移除 \`${name}\``,
+                detectedBy: 'structural',
+            });
+        }
+    }
+    // 新增的成员
+    for (const [name, newMember] of newMap) {
+        if (!oldMap.has(name)) {
+            items.push({
+                id: generateId(),
+                severity: 'LOW',
+                category: 'Interface',
+                changeType: 'addition',
+                location: `${filePath}:${startLine}`,
+                symbolName: `${parentName}.${name}`,
+                description: `\`${parentName}\` 新增成员 \`${name}\` (${newMember.kind})`,
+                oldValue: null,
+                newValue: newMember.signature,
+                proposedUpdate: `在 \`${parentName}\` 的文档中添加 \`${name}\``,
+                detectedBy: 'structural',
+            });
+        }
+    }
+    // 修改的成员签名
+    for (const [name, oldMember] of oldMap) {
+        const newMember = newMap.get(name);
+        if (newMember && oldMember.signature !== newMember.signature) {
+            items.push({
+                id: generateId(),
+                severity: 'MEDIUM',
+                category: 'Interface',
+                changeType: 'modification',
+                location: `${filePath}:${startLine}`,
+                symbolName: `${parentName}.${name}`,
+                description: `成员 \`${parentName}.${name}\` 的签名已修改`,
+                oldValue: oldMember.signature,
+                newValue: newMember.signature,
+                proposedUpdate: `更新 \`${parentName}.${name}\` 的签名文档`,
+                detectedBy: 'structural',
+            });
+        }
+    }
+    return items;
+}
+//# sourceMappingURL=structural-diff.js.map

package/dist/diff/structural-diff.js.map

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

package/dist/extraction/artifact-classifier.d.ts

@@ -0,0 +1,19 @@
+import type { ArtifactKind } from './extraction-types.js';
+/** 永远跳过的目录前缀（与 projectRoot 无关，基于路径片段匹配） */
+export declare const EXCLUDED_DIR_SEGMENTS: Set<string>;
+/**
+ * 判断文件是否为敏感文件（应跳过处理）
+ * 仅匹配文件名部分，路径无关
+ *
+ * @param filePath - 文件路径（绝对或相对）
+ * @returns 是否为敏感文件
+ */
+export declare function isSensitiveFile(filePath: string): boolean;
+/**
+ * 对文件路径进行制品类型分类
+ *
+ * @param filePath - 文件路径（绝对或相对）
+ * @returns ArtifactKind（文件类型），或 null（不支持/应跳过）
+ */
+export declare function classifyFile(filePath: string): ArtifactKind | null;
+//# sourceMappingURL=artifact-classifier.d.ts.map

package/dist/extraction/artifact-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-classifier.d.ts","sourceRoot":"","sources":["../../src/extraction/artifact-classifier.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAM1D,2CAA2C;AAC3C,eAAO,MAAM,qBAAqB,aAAqD,CAAC;AA+CxF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGzD;AAmBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA6BlE"}

package/dist/extraction/artifact-classifier.js

@@ -0,0 +1,104 @@
+/**
+ * 文件制品分类器（Feature 107）
+ * 根据文件扩展名和路径规则判断文件类型，支持敏感文件过滤
+ * 参考 Graphify detect.py 的文件分类策略
+ */
+import * as path from 'node:path';
+// ============================================================
+// 路径扫描排除规则（硬编码边界）
+// ============================================================
+/** 永远跳过的目录前缀（与 projectRoot 无关，基于路径片段匹配） */
+export const EXCLUDED_DIR_SEGMENTS = new Set(['node_modules', 'dist', '.git', 'specs']);
+// ============================================================
+// 扩展名映射
+// ============================================================
+/** Markdown 文档扩展名 → document */
+const DOCUMENT_EXTENSIONS = new Set(['.md', '.mdx']);
+/** API 规范扩展名 → api-spec（须配合文件名模式过滤） */
+const API_SPEC_EXTENSIONS = new Set(['.yaml', '.yml', '.json']);
+/** 支持的图像扩展名 → image（仅 PNG/JPG/JPEG/SVG，其余跳过） */
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.svg']);
+// ============================================================
+// 敏感文件模式（参考 Graphify detect.py::_is_sensitive()）
+// ============================================================
+/**
+ * 敏感文件名正则列表
+ * 匹配 .env 系列、私钥、证书、密钥文件等
+ */
+const SENSITIVE_FILENAME_PATTERNS = [
+    /^\.env(\..+)?$/i, // .env, .env.local, .env.production 等
+    /\.(pem|key|crt|cer|pfx|p12|p8)$/i, // 证书和私钥
+    /^(id_rsa|id_dsa|id_ecdsa|id_ed25519)(\.pub)?$/i, // SSH 密钥
+    /^credentials(\..+)?$/i, // credentials 文件
+    /^secret(\..+)?$/i, // secret 文件
+    /\.keystore$/i, // Java KeyStore
+    /\.jks$/i, // Java KeyStore 别名
+];
+// ============================================================
+// 公开 API
+// ============================================================
+/**
+ * 判断文件是否在排除目录中（不应扫描）
+ * 检查路径中所有片段，匹配到任意排除目录即返回 true
+ */
+function isInExcludedDir(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const segments = normalized.split('/');
+    return segments.some((segment) => EXCLUDED_DIR_SEGMENTS.has(segment));
+}
+/**
+ * 判断文件是否为敏感文件（应跳过处理）
+ * 仅匹配文件名部分，路径无关
+ *
+ * @param filePath - 文件路径（绝对或相对）
+ * @returns 是否为敏感文件
+ */
+export function isSensitiveFile(filePath) {
+    const basename = path.basename(filePath);
+    return SENSITIVE_FILENAME_PATTERNS.some((pattern) => pattern.test(basename));
+}
+/**
+ * 判断文件是否应被扫描为 API 规范
+ * 除了扩展名匹配，还要求文件名包含 openapi / swagger / asyncapi 关键字
+ * 避免将普通 JSON/YAML 配置文件误判为 API 规范
+ */
+function isApiSpecFile(filePath) {
+    if (!API_SPEC_EXTENSIONS.has(path.extname(filePath).toLowerCase())) {
+        return false;
+    }
+    const basename = path.basename(filePath).toLowerCase();
+    return (basename.includes('openapi') ||
+        basename.includes('swagger') ||
+        basename.includes('asyncapi'));
+}
+/**
+ * 对文件路径进行制品类型分类
+ *
+ * @param filePath - 文件路径（绝对或相对）
+ * @returns ArtifactKind（文件类型），或 null（不支持/应跳过）
+ */
+export function classifyFile(filePath) {
+    // 排除目录边界检查（specs/、node_modules/、dist/、.git/）
+    if (isInExcludedDir(filePath)) {
+        return null;
+    }
+    // 敏感文件跳过
+    if (isSensitiveFile(filePath)) {
+        return null;
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    // Markdown 文档
+    if (DOCUMENT_EXTENSIONS.has(ext)) {
+        return 'document';
+    }
+    // API 规范（需文件名关键字匹配）
+    if (isApiSpecFile(filePath)) {
+        return 'api-spec';
+    }
+    // 图像
+    if (IMAGE_EXTENSIONS.has(ext)) {
+        return 'image';
+    }
+    return null;
+}
+//# sourceMappingURL=artifact-classifier.js.map

package/dist/extraction/artifact-classifier.js.map

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

package/dist/extraction/extraction-cache.d.ts

@@ -0,0 +1,32 @@
+import type { ExtractionResult } from './extraction-types.js';
+/**
+ * 计算文件提取哈希
+ * 策略：SHA256(body + absolutePath)
+ * Markdown 文件剥离 frontmatter 后计算（frontmatter 变化不影响 hash）
+ *
+ * @param filePath - 文件绝对路径（纳入哈希，确保同内容不同路径的缓存独立）
+ * @param content - 文件完整内容
+ * @param isMarkdown - 是否剥离 frontmatter（默认 false）
+ * @returns 64 位十六进制 SHA256 哈希字符串
+ */
+export declare function fileExtractHash(filePath: string, content: string, isMarkdown?: boolean): string;
+/**
+ * 加载文件提取缓存
+ * 命中返回已验证的 ExtractionResult，未命中或损坏返回 null
+ *
+ * @param hash - 文件提取哈希（由 fileExtractHash 生成）
+ * @param outputDir - 输出目录（绝对路径）
+ * @returns 缓存的 ExtractionResult，或 null（未命中）
+ */
+export declare function loadExtractCache(hash: string, outputDir: string): ExtractionResult | null;
+/**
+ * 保存文件提取缓存
+ * 使用原子写入防止写入中断导致数据损坏
+ *
+ * @param hash - 文件提取哈希
+ * @param outputDir - 输出目录（绝对路径）
+ * @param result - 要缓存的提取结果
+ * @param filePath - 来源文件路径（用于 debug 标注，不影响 cache lookup）
+ */
+export declare function saveExtractCache(hash: string, outputDir: string, result: ExtractionResult, filePath?: string): Promise<void>;
+//# sourceMappingURL=extraction-cache.d.ts.map

package/dist/extraction/extraction-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-cache.d.ts","sourceRoot":"","sources":["../../src/extraction/extraction-cache.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAmD9D;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,UAAQ,GAAG,MAAM,CAK7F;AAgBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAoBzF;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,gBAAgB,EACxB,QAAQ,SAAK,GACZ,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/extraction/extraction-cache.js

@@ -0,0 +1,117 @@
+/**
+ * 文件级提取结果缓存（Feature 107）
+ * 基于 SHA256(content body + absolutePath) 的哈希缓存
+ * 参考 Graphify cache.py 的 SHA256(body + path) 策略
+ *
+ * 缓存路径：{outputDir}/_meta/extraction-cache/{hash}.json
+ * 写入方式：原子 rename（复用 writeAtomicJson）
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { writeAtomicJson } from '../utils/atomic-write.js';
+import { ExtractionResultSchema } from './extraction-types.js';
+// ============================================================
+// Frontmatter 剥离（Markdown 文件专用）
+// ============================================================
+/**
+ * 剥离 Markdown frontmatter，返回 body 部分
+ * 仅当内容以 "---\n" 开头时进行剥离，否则原样返回
+ * 目的：frontmatter 变化（如 lastUpdated）不触发重新提取
+ */
+function stripMarkdownFrontmatter(content) {
+    if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) {
+        return content;
+    }
+    // 查找第二个 "---" 分隔符
+    const firstDash = content.indexOf('---\n', 3);
+    const firstDashCR = content.indexOf('---\r\n', 3);
+    const endIdx = firstDash !== -1
+        ? (firstDashCR !== -1 ? Math.min(firstDash, firstDashCR) : firstDash)
+        : firstDashCR;
+    if (endIdx === -1) {
+        // 未找到闭合分隔符，原样返回
+        return content;
+    }
+    // 返回 frontmatter 之后的内容
+    const afterClose = content.indexOf('\n', endIdx);
+    return afterClose !== -1 ? content.slice(afterClose + 1) : content;
+}
+// ============================================================
+// 公开 API
+// ============================================================
+/**
+ * 计算文件提取哈希
+ * 策略：SHA256(body + absolutePath)
+ * Markdown 文件剥离 frontmatter 后计算（frontmatter 变化不影响 hash）
+ *
+ * @param filePath - 文件绝对路径（纳入哈希，确保同内容不同路径的缓存独立）
+ * @param content - 文件完整内容
+ * @param isMarkdown - 是否剥离 frontmatter（默认 false）
+ * @returns 64 位十六进制 SHA256 哈希字符串
+ */
+export function fileExtractHash(filePath, content, isMarkdown = false) {
+    const body = isMarkdown ? stripMarkdownFrontmatter(content) : content;
+    // SHA256(body + absolutePath) 保证：内容相同但路径不同时缓存独立
+    const input = body + path.resolve(filePath);
+    return crypto.createHash('sha256').update(input, 'utf-8').digest('hex');
+}
+/**
+ * 缓存目录路径
+ */
+function cacheDirPath(outputDir) {
+    return path.join(outputDir, '_meta', 'extraction-cache');
+}
+/**
+ * 缓存文件路径
+ */
+function cacheFilePath(outputDir, hash) {
+    return path.join(cacheDirPath(outputDir), `${hash}.json`);
+}
+/**
+ * 加载文件提取缓存
+ * 命中返回已验证的 ExtractionResult，未命中或损坏返回 null
+ *
+ * @param hash - 文件提取哈希（由 fileExtractHash 生成）
+ * @param outputDir - 输出目录（绝对路径）
+ * @returns 缓存的 ExtractionResult，或 null（未命中）
+ */
+export function loadExtractCache(hash, outputDir) {
+    const filePath = cacheFilePath(outputDir, hash);
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const entry = JSON.parse(content);
+        // 使用 Zod 验证缓存结果，防止旧版本缓存格式不兼容
+        const parsed = ExtractionResultSchema.safeParse(entry.result);
+        if (!parsed.success) {
+            return null;
+        }
+        return parsed.data;
+    }
+    catch {
+        // 文件损坏或格式不兼容，视为未命中
+        return null;
+    }
+}
+/**
+ * 保存文件提取缓存
+ * 使用原子写入防止写入中断导致数据损坏
+ *
+ * @param hash - 文件提取哈希
+ * @param outputDir - 输出目录（绝对路径）
+ * @param result - 要缓存的提取结果
+ * @param filePath - 来源文件路径（用于 debug 标注，不影响 cache lookup）
+ */
+export async function saveExtractCache(hash, outputDir, result, filePath = '') {
+    const entry = {
+        filePath,
+        cachedAt: new Date().toISOString(),
+        result,
+    };
+    const targetPath = cacheFilePath(outputDir, hash);
+    writeAtomicJson(targetPath, entry);
+}
+//# sourceMappingURL=extraction-cache.js.map

package/dist/extraction/extraction-cache.js.map

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

package/dist/extraction/extraction-pipeline.d.ts

@@ -0,0 +1,44 @@
+import type { ExtractionResult } from './extraction-types.js';
+/** 提取管道选项 */
+export interface ExtractionPipelineOptions {
+    /** 目标项目根目录（绝对路径） */
+    projectRoot: string;
+    /** 输出目录（绝对路径，缓存写入 {outputDir}/_meta/extraction-cache/） */
+    outputDir: string;
+    /** 是否启用 Markdown + API 规范提取 */
+    includeDocs: boolean;
+    /** 是否启用图像/图表 Vision 提取 */
+    includeImages: boolean;
+}
+/**
+ * Feature 140 FR-010 — 提取管道输出。
+ *
+ * - `results`: 既有 ExtractionResult[]（每个文件一个 ExtractionResult，含 nodes/edges）
+ * - `readmeContent`: 仅 includeDocs=true 时，projectRoot 下的 README 全量内容（不截断）；
+ *   未启用或不存在时为 undefined。下游 narrative / hyperedge 用作 shared header 注入。
+ */
+export interface ExtractionPipelineOutput {
+    results: ExtractionResult[];
+    readmeContent?: string;
+}
+/**
+ * 在 projectRoot 下定位 README 文件（不区分大小写）。
+ * 优先级：README.md > readme.md > Readme.md > 其他大小写组合（按目录条目自然顺序）。
+ * 找不到时返回 undefined。
+ *
+ * **导出原因**：batch-orchestrator 在 generateBatchProjectDocs 之前需要早期 README 读取
+ * （narrative 在 docs 阶段生成，早于 extraction-pipeline）；共享同一个 findReadmePath
+ * 助手避免两处大小写匹配候选列表漂移（修复 Codex review CRITICAL 2）。
+ *
+ * @param projectRoot - 项目根目录绝对路径
+ * @returns README 文件绝对路径；找不到返回 undefined
+ */
+export declare function findReadmePath(projectRoot: string): string | undefined;
+/**
+ * 运行多模态提取管道
+ *
+ * @param options - 管道选项
+ * @returns ExtractionPipelineOutput — { results, readmeContent? }；不抛出异常
+ */
+export declare function runExtractionPipeline(options: ExtractionPipelineOptions): Promise<ExtractionPipelineOutput>;
+//# sourceMappingURL=extraction-pipeline.d.ts.map

package/dist/extraction/extraction-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-pipeline.d.ts","sourceRoot":"","sources":["../../src/extraction/extraction-pipeline.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAc9D,aAAa;AACb,MAAM,WAAW,yBAAyB;IACxC,oBAAoB;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,WAAW,EAAE,OAAO,CAAC;IACrB,0BAA0B;IAC1B,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA+KD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAetE;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CA+EnC"}