spectra-cli 4.1.1

package/dist/panoramic/builders/dynamic-scenarios-builder.js

@@ -0,0 +1,361 @@
+import { dedupeComponentEvidence, minConfidence, summarizeDynamicScenarios, } from '../models/component-view-model.js';
+import { loadTemplate } from '../utils/template-loader.js';
+export function buildDynamicScenarios(options) {
+    const warnings = new Set(options.componentView.warnings);
+    const scenarios = [];
+    if (options.storedModules.length === 0) {
+        warnings.add('未找到 stored module specs，dynamic scenarios 仅基于组件视图和弱信号构建。');
+    }
+    const primary = buildPrimaryFlowScenario(options.componentView, options.runtime);
+    if (primary) {
+        scenarios.push(primary);
+    }
+    else {
+        warnings.add('未识别到高信号 request/control 主链路。');
+    }
+    const eventScenario = buildEventFlowScenario(options.componentView, options.eventSurface);
+    if (eventScenario) {
+        scenarios.push(eventScenario);
+    }
+    const sessionScenario = buildSessionFlowScenario(options.componentView);
+    if (sessionScenario) {
+        scenarios.push(sessionScenario);
+    }
+    if (scenarios.length === 0) {
+        warnings.add('当前批次未构建出可稳定复核的 dynamic scenarios。');
+    }
+    const model = {
+        projectName: options.componentView.projectName,
+        generatedAt: new Date().toISOString(),
+        scenarios,
+        warnings: [...warnings].sort((a, b) => a.localeCompare(b)),
+        stats: summarizeDynamicScenarios({ scenarios }),
+    };
+    return {
+        title: `动态链路: ${options.componentView.projectName}`,
+        generatedAt: model.generatedAt,
+        model,
+        warnings: model.warnings,
+    };
+}
+export function renderDynamicScenarios(output) {
+    const template = loadTemplate('dynamic-scenarios.hbs', import.meta.url);
+    return template(output);
+}
+function buildPrimaryFlowScenario(componentView, runtime) {
+    const entry = findEntryComponent(componentView.components);
+    const transport = componentView.components.find((component) => component.category === 'transport');
+    const parser = componentView.components.find((component) => component.category === 'parser');
+    const session = componentView.components.find((component) => component.category === 'session' || component.category === 'store');
+    const trigger = findTriggerName(entry);
+    if (!entry || !trigger) {
+        return undefined;
+    }
+    const steps = [];
+    let index = 1;
+    steps.push(createStep({
+        index: index++,
+        actor: entry,
+        action: `接收 ${trigger}`,
+        detail: `${entry.name} 作为入口组件启动主请求链路。`,
+        evidence: entry.evidence,
+        confidence: entry.confidence,
+        inferred: entry.inferred,
+    }));
+    if (transport) {
+        steps.push(createStep({
+            index: index++,
+            actor: entry,
+            action: '委托 transport',
+            target: transport,
+            detail: `${entry.name} 将请求交给 ${transport.name}，由 transport 层负责对外通信。`,
+            evidence: mergeEvidence(entry.evidence, transport.evidence),
+            confidence: mergeConfidence(entry.confidence, transport.confidence),
+            inferred: entry.inferred || transport.inferred,
+        }));
+    }
+    if (parser) {
+        const parserActor = transport ?? entry;
+        steps.push(createStep({
+            index: index++,
+            actor: parserActor,
+            action: '交给解析层',
+            target: parser,
+            detail: `${parser.name} 对返回消息或 stream payload 进行解析，提炼上层可消费结果。`,
+            evidence: mergeEvidence(parserActor.evidence, parser.evidence),
+            confidence: mergeConfidence(parserActor.confidence, parser.confidence),
+            inferred: parserActor.inferred || parser.inferred,
+        }));
+    }
+    if (session) {
+        const sessionActor = parser ?? transport ?? entry;
+        steps.push(createStep({
+            index: index++,
+            actor: sessionActor,
+            action: '更新会话状态',
+            target: session,
+            detail: `${session.name} 负责 session / transcript / local state 的更新或持久化。`,
+            evidence: mergeEvidence(sessionActor.evidence, session.evidence),
+            confidence: mergeConfidence(sessionActor.confidence, session.confidence),
+            inferred: sessionActor.inferred || session.inferred,
+        }));
+    }
+    if (runtime?.topology.services[0]) {
+        const service = runtime.topology.services[0];
+        steps.push({
+            index: index++,
+            actorId: entry.id,
+            actor: entry.name,
+            action: '运行于目标宿主',
+            target: service.name,
+            detail: `${service.name} 提供本链路的运行时宿主边界。`,
+            confidence: 'low',
+            inferred: true,
+            evidence: [{
+                    sourceType: 'runtime-topology',
+                    ref: service.sourceFile,
+                    note: service.name,
+                    inferred: true,
+                }],
+        });
+    }
+    const confidence = deriveScenarioConfidence(steps);
+    const category = inferScenarioCategory(trigger);
+    return {
+        id: 'primary-flow',
+        title: `${trigger} 主链路`,
+        category,
+        trigger,
+        participants: dedupeStrings([entry.name, transport?.name, parser?.name, session?.name]),
+        summary: `${entry.name} 驱动主请求链路${transport ? `，经由 ${transport.name}` : ''}${parser ? `，并由 ${parser.name} 完成解析` : ''}。`,
+        steps,
+        outcome: parser
+            ? `解析层 ${parser.name} 将结果交回上层调用者。`
+            : '链路结果返回到入口组件。',
+        confidence,
+        inferred: confidence !== 'high',
+        evidence: dedupeComponentEvidence(steps.flatMap((step) => step.evidence)),
+    };
+}
+function buildEventFlowScenario(componentView, eventSurface) {
+    const channel = eventSurface?.channels[0];
+    if (!channel || channel.publishers.length === 0 || channel.subscribers.length === 0) {
+        return undefined;
+    }
+    const publisher = findComponentBySymbol(componentView.components, channel.publishers[0].symbolName);
+    const subscriber = findComponentBySymbol(componentView.components, channel.subscribers[0].symbolName);
+    if (!publisher || !subscriber) {
+        return undefined;
+    }
+    const steps = [
+        createStep({
+            index: 1,
+            actor: publisher,
+            action: `发布事件 ${channel.channelName}`,
+            detail: `${publisher.name} 发布 ${channel.kind} ${channel.channelName}。`,
+            evidence: [{
+                    sourceType: 'event-surface',
+                    ref: channel.channelName,
+                    note: 'publisher',
+                }],
+            confidence: 'medium',
+            inferred: false,
+        }),
+        createStep({
+            index: 2,
+            actor: subscriber,
+            action: `消费事件 ${channel.channelName}`,
+            detail: `${subscriber.name} 订阅并处理 ${channel.channelName} 负载。`,
+            evidence: [{
+                    sourceType: 'event-surface',
+                    ref: channel.channelName,
+                    note: 'subscriber',
+                }],
+            confidence: 'medium',
+            inferred: false,
+        }),
+    ];
+    return {
+        id: `event-${channel.channelName}`,
+        title: `${channel.channelName} 事件链路`,
+        category: 'event-flow',
+        trigger: channel.channelName,
+        participants: [publisher.name, subscriber.name],
+        summary: `${publisher.name} -> ${channel.channelName} -> ${subscriber.name}`,
+        steps,
+        outcome: `${subscriber.name} 完成事件处理。`,
+        confidence: 'medium',
+        inferred: false,
+        evidence: dedupeComponentEvidence(steps.flatMap((step) => step.evidence)),
+    };
+}
+function buildSessionFlowScenario(componentView) {
+    const session = componentView.components.find((component) => component.category === 'session' || component.category === 'store');
+    const entry = findEntryComponent(componentView.components);
+    if (!session || !entry) {
+        return undefined;
+    }
+    const relevantMethod = session.keyMethods.find((method) => /(load|save|persist|resume|session)/i.test(method.name));
+    if (!relevantMethod) {
+        return undefined;
+    }
+    const steps = [
+        createStep({
+            index: 1,
+            actor: entry,
+            action: '触发会话恢复或持久化',
+            target: session,
+            detail: `${entry.name} 需要从 ${session.name} 恢复或更新 session 状态。`,
+            evidence: mergeEvidence(entry.evidence, session.evidence),
+            confidence: mergeConfidence(entry.confidence, session.confidence),
+            inferred: entry.inferred || session.inferred,
+        }),
+        {
+            index: 2,
+            actorId: session.id,
+            actor: session.name,
+            action: `执行 ${relevantMethod.name}`,
+            detail: `${session.name} 通过 ${relevantMethod.name} 处理本地状态或 transcript。`,
+            confidence: session.confidence,
+            inferred: session.inferred,
+            evidence: dedupeComponentEvidence(relevantMethod.evidence),
+        },
+    ];
+    return {
+        id: 'session-flow',
+        title: `${session.name} 会话链路`,
+        category: 'session-flow',
+        trigger: relevantMethod.name,
+        participants: [entry.name, session.name],
+        summary: `${entry.name} 与 ${session.name} 协作维护 session 状态。`,
+        steps,
+        outcome: `${session.name} 完成会话状态更新。`,
+        confidence: deriveScenarioConfidence(steps),
+        inferred: true,
+        evidence: dedupeComponentEvidence(steps.flatMap((step) => step.evidence)),
+    };
+}
+function createStep(input) {
+    return {
+        index: input.index,
+        actorId: input.actor.id,
+        actor: input.actor.name,
+        action: input.action,
+        targetId: input.target?.id,
+        target: input.target?.name,
+        detail: input.detail,
+        confidence: input.confidence,
+        inferred: input.inferred,
+        evidence: dedupeComponentEvidence(input.evidence),
+    };
+}
+function findEntryComponent(components) {
+    return components.find((component) => ['query', 'client', 'service', 'module'].includes(component.category)
+        && findTriggerName(component) !== undefined) ?? components.find((component) => ['query', 'client', 'service', 'module'].includes(component.category));
+}
+function findTriggerName(component) {
+    if (!component) {
+        return undefined;
+    }
+    const rankedMethod = component.keyMethods
+        .map((method) => ({
+        name: method.name,
+        score: scoreTriggerMethod(method.name),
+    }))
+        .filter((method) => method.score > 0)
+        .sort((left, right) => {
+        const scoreDiff = right.score - left.score;
+        return scoreDiff !== 0 ? scoreDiff : left.name.localeCompare(right.name);
+    })[0];
+    return rankedMethod?.name;
+}
+function inferScenarioCategory(trigger) {
+    if (/(interrupt|control)/i.test(trigger))
+        return 'control-flow';
+    if (/(session|resume|persist)/i.test(trigger))
+        return 'session-flow';
+    return 'request-flow';
+}
+function deriveScenarioConfidence(steps) {
+    if (steps.length >= 3 && steps.every((step) => step.confidence !== 'low')) {
+        return 'high';
+    }
+    if (steps.length >= 2) {
+        return 'medium';
+    }
+    return 'low';
+}
+function findComponentBySymbol(components, symbolName) {
+    return components.find((component) => component.name === symbolName
+        || component.keyMethods.some((method) => method.ownerName === symbolName || method.name === symbolName));
+}
+function mergeEvidence(left, right) {
+    return dedupeComponentEvidence([...left, ...right]);
+}
+function mergeConfidence(left, right) {
+    return minConfidence(left, right);
+}
+function dedupeStrings(values) {
+    return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))]
+        .sort((a, b) => a.localeCompare(b));
+}
+function scoreTriggerMethod(name) {
+    const lower = name.toLowerCase();
+    if (/(query|request|process)/.test(lower))
+        return 5;
+    if (/(interrupt|control)/.test(lower))
+        return 4;
+    if (/(stream|send|receive)/.test(lower))
+        return 3;
+    if (/(connect|run|execute|initialize|start)/.test(lower))
+        return 2;
+    if (/(session|resume|persist)/.test(lower))
+        return 1;
+    return 0;
+}
+// ============================================================
+// DocumentGenerator Adapter
+// ============================================================
+/**
+ * context 扩展键：ComponentViewBuilderGenerator 完成后将 ViewModel 存入 context
+ * DynamicScenariosBuilderGenerator 在 extract 中读取此字段
+ */
+const CONTEXT_COMPONENT_VIEW_MODEL_KEY = '__componentViewModel';
+/**
+ * DynamicScenariosBuilderGenerator
+ *
+ * 将 buildDynamicScenarios() 适配为 DocumentGenerator 接口。
+ * 依赖 ComponentViewBuilderGenerator 先行运行并将 ComponentViewModel
+ * 存入 context（通过 CONTEXT_COMPONENT_VIEW_MODEL_KEY）。
+ *
+ * TInput: ComponentViewModel（从 context 中读取）
+ * TOutput: DynamicScenariosOutput
+ */
+export class DynamicScenariosBuilderGenerator {
+    id = 'dynamic-scenarios-builder';
+    name = '动态链路场景生成器';
+    description = '基于 ComponentViewModel 构建关键动态链路说明，展示组件间交互的请求/控制/事件链路';
+    isApplicable(context) {
+        // 检查 context 中是否已有 ComponentViewModel
+        // 若无，则当前 Generator 无法运行
+        return CONTEXT_COMPONENT_VIEW_MODEL_KEY in context;
+    }
+    async extract(context) {
+        // 从 context 中纯读取 ViewModel（由 ComponentViewBuilderGenerator 先行注入）
+        const viewModel = context[CONTEXT_COMPONENT_VIEW_MODEL_KEY];
+        if (!viewModel) {
+            throw new Error('DynamicScenariosBuilderGenerator: context 中不存在 ComponentViewModel，请先运行 ComponentViewBuilderGenerator');
+        }
+        return viewModel;
+    }
+    async generate(input, _options) {
+        return buildDynamicScenarios({
+            componentView: input,
+            storedModules: [],
+        });
+    }
+    render(output) {
+        return renderDynamicScenarios(output);
+    }
+}
+//# sourceMappingURL=dynamic-scenarios-builder.js.map

package/dist/panoramic/builders/dynamic-scenarios-builder.js.map

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

package/dist/panoramic/cache/cache-key-builder.d.ts

@@ -0,0 +1,25 @@
+import type { DocumentGenerator, ProjectContext } from '../interfaces.js';
+import type { ContentHasher } from './content-hasher.js';
+/**
+ * 递归扫描 projectRoot 下所有源文件
+ * 排除噪声目录，仅收集指定扩展名，结果排序后返回
+ */
+export declare function scanSourceFiles(root: string, excludePaths?: string[]): string[];
+/**
+ * 解析 generator 的输入文件列表
+ * 优先使用 getDependencies()，fallback 为全量扫描
+ */
+export declare function resolveInputFiles(generator: DocumentGenerator<unknown, unknown>, context: ProjectContext, outputDir?: string): Promise<string[]>;
+/**
+ * 构建 generator 的 cache key
+ *
+ * key 材料：generator.id | projectRoot | workspaceType | packageManager
+ *          | detectedLanguages(sorted) | aggregatedFileHash
+ *
+ * @param generator - DocumentGenerator 实例
+ * @param context - 项目上下文
+ * @param hasher - ContentHasher 实例
+ * @returns SHA256 hex 字符串
+ */
+export declare function buildGeneratorCacheKey(generator: DocumentGenerator<unknown, unknown>, context: ProjectContext, hasher: ContentHasher, outputDir?: string): Promise<string>;
+//# sourceMappingURL=cache-key-builder.d.ts.map

package/dist/panoramic/cache/cache-key-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-key-builder.d.ts","sourceRoot":"","sources":["../../../src/panoramic/cache/cache-key-builder.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA6BzD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAmCnF;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC9C,OAAO,EAAE,cAAc,EACvB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC,CASnB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC9C,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,aAAa,EACrB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAqBjB"}

package/dist/panoramic/cache/cache-key-builder.js

@@ -0,0 +1,119 @@
+/**
+ * cache key 构建器
+ *
+ * cache key 材料构成：
+ *   generator.id | projectRoot | workspaceType | packageManager | detectedLanguages | aggregatedFileHash
+ *
+ * 明确排除 existingSpecs（每次运行都变化）和 configFiles（Map 序列化顺序不稳定）
+ * 以避免运行时易变数据导致缓存频繁失效。
+ *
+ * fallback 路径：当 generator 未实现 getDependencies() 时，
+ * 退回到全量源文件扫描。性能影响：中大型项目首次扫描可能耗时数百 ms，
+ * 但结果会被 CacheManager 缓存为 manifest entry，后续检查仅做 mtime/hash 比对。
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+// ============================================================
+// 常量
+// ============================================================
+/** fallback 扫描时排除的目录 */
+const EXCLUDED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '_meta',
+    'dist',
+    '.cache',
+]);
+/** fallback 扫描时收集的文件扩展名 */
+const INCLUDED_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx',
+    '.json', '.md', '.yaml', '.yml',
+    '.toml', '.lock',
+]);
+/** fallback 扫描时：无扩展名但需要包含的文件名前缀（Dockerfile, .env 等） */
+const INCLUDED_FILENAME_PREFIXES = ['Dockerfile', '.env'];
+// ============================================================
+// 辅助函数
+// ============================================================
+/**
+ * 递归扫描 projectRoot 下所有源文件
+ * 排除噪声目录，仅收集指定扩展名，结果排序后返回
+ */
+export function scanSourceFiles(root, excludePaths = []) {
+    const results = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            // 目录不可读时跳过
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            // 跳过明确排除的路径（如 outputDir）
+            if (excludePaths.some((excluded) => fullPath.startsWith(excluded))) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                if (!EXCLUDED_DIRS.has(entry.name)) {
+                    walk(fullPath);
+                }
+            }
+            else if (entry.isFile()) {
+                const ext = path.extname(entry.name).toLowerCase();
+                if (INCLUDED_EXTENSIONS.has(ext) || INCLUDED_FILENAME_PREFIXES.some((prefix) => entry.name.startsWith(prefix))) {
+                    results.push(fullPath);
+                }
+            }
+        }
+    }
+    walk(root);
+    return results.sort();
+}
+/**
+ * 解析 generator 的输入文件列表
+ * 优先使用 getDependencies()，fallback 为全量扫描
+ */
+export async function resolveInputFiles(generator, context, outputDir) {
+    // 优先使用 generator 声明的依赖
+    if (typeof generator.getDependencies === 'function') {
+        const deps = await Promise.resolve(generator.getDependencies(context));
+        return [...deps].sort();
+    }
+    // fallback: 扫描 projectRoot 下所有源文件（排除 outputDir 避免自我引用）
+    return scanSourceFiles(context.projectRoot, outputDir ? [outputDir] : []);
+}
+/**
+ * 构建 generator 的 cache key
+ *
+ * key 材料：generator.id | projectRoot | workspaceType | packageManager
+ *          | detectedLanguages(sorted) | aggregatedFileHash
+ *
+ * @param generator - DocumentGenerator 实例
+ * @param context - 项目上下文
+ * @param hasher - ContentHasher 实例
+ * @returns SHA256 hex 字符串
+ */
+export async function buildGeneratorCacheKey(generator, context, hasher, outputDir) {
+    // 解析输入文件列表
+    const inputFiles = await resolveInputFiles(generator, context, outputDir);
+    // 计算文件集合的聚合哈希
+    const aggregatedFileHash = await hasher.hashFiles(inputFiles);
+    // 构建 key 材料字符串
+    const keyMaterial = [
+        generator.id,
+        context.projectRoot,
+        context.workspaceType,
+        context.packageManager,
+        [...context.detectedLanguages].sort().join(','),
+        aggregatedFileHash,
+    ].join('|');
+    return crypto
+        .createHash('sha256')
+        .update(keyMaterial)
+        .digest('hex');
+}
+//# sourceMappingURL=cache-key-builder.js.map

package/dist/panoramic/cache/cache-key-builder.js.map

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

package/dist/panoramic/cache/cache-manager.d.ts

@@ -0,0 +1,58 @@
+import type { DocumentGenerator, ProjectContext } from '../interfaces.js';
+import type { ContentHasher } from './content-hasher.js';
+import type { ManifestManager, ManifestStats } from './manifest-manager.js';
+import type { ManifestEntry } from './schemas.js';
+/**
+ * 缓存管理器
+ * 组合 ContentHasher 和 ManifestManager，实现缓存检查 / 记录 / 清除
+ */
+export declare class CacheManager {
+    private hasher;
+    private manifestManager;
+    private manifestPath;
+    private outputDir;
+    /** check() 阶段缓存的 cacheKey，供 record() 复用以避免重复计算 */
+    private lastCacheKey;
+    private lastInputFiles;
+    constructor(hasher: ContentHasher, manifestManager: ManifestManager);
+    /**
+     * 初始化：计算 manifestPath 并加载 manifest
+     * @param outputDir panoramic 输出目录
+     */
+    initialize(outputDir: string): Promise<void>;
+    /**
+     * 检查 generator 是否命中缓存
+     * 内部计算 cacheKey，并对 manifest entry 的所有 inputFiles 做 stale 校验
+     *
+     * 三路 stale 校验（任一满足即判定 stale）：
+     * 1. 文件不存在（已删除）
+     * 2. 文件 mtime 早于记录的 mtime（文件被回滚）
+     * 3. 文件内容 SHA256 与记录不一致
+     *
+     * @returns 命中时返回 ManifestEntry，未命中或 stale 时返回 false
+     */
+    check(generator: DocumentGenerator<unknown, unknown>, context: ProjectContext): Promise<ManifestEntry | false>;
+    /**
+     * 记录 generator 的执行结果到 manifest（内存操作）
+     * 仅由成功路径调用
+     *
+     * @param generator generator 实例
+     * @param context ProjectContext
+     * @param outputFiles 本次生成的输出文件路径列表
+     */
+    record(generator: DocumentGenerator<unknown, unknown>, context: ProjectContext, outputFiles: string[]): Promise<void>;
+    /**
+     * 将内存 manifest 原子写盘
+     */
+    flush(): Promise<void>;
+    /**
+     * 清除缓存
+     * @param generatorId 指定 generator 时仅清除该 generator 的条目，否则清除全部
+     */
+    clear(generatorId?: string): Promise<void>;
+    /**
+     * 返回统计摘要（委托 ManifestManager）
+     */
+    stats(): ManifestStats;
+}
+//# sourceMappingURL=cache-manager.d.ts.map

package/dist/panoramic/cache/cache-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-manager.d.ts","sourceRoot":"","sources":["../../../src/panoramic/cache/cache-manager.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC5E,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlE;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,YAAY,CAAc;IAClC,OAAO,CAAC,SAAS,CAAc;IAC/B,kDAAkD;IAClD,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,cAAc,CAAyB;gBAEnC,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe;IAKnE;;;OAGG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlD;;;;;;;;;;OAUG;IACG,KAAK,CACT,SAAS,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC9C,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,GAAG,KAAK,CAAC;IAoDjC;;;;;;;OAOG;IACG,MAAM,CACV,SAAS,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC9C,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,IAAI,CAAC;IAoChB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;OAGG;IACG,KAAK,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBhD;;OAEG;IACH,KAAK,IAAI,aAAa;CAGvB"}