spectra-cli 4.1.1

package/dist/panoramic/cache/cache-manager.js

@@ -0,0 +1,170 @@
+/**
+ * 缓存管理器
+ * 组合 ContentHasher 和 ManifestManager，提供缓存检查、记录、刷盘、清除功能
+ *
+ * 并发约束：CacheManager 不应与 batch 并发执行。
+ * 当前串行架构下无此问题，并发化时需引入写锁。
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { buildGeneratorCacheKey, resolveInputFiles } from './cache-key-builder.js';
+/**
+ * 缓存管理器
+ * 组合 ContentHasher 和 ManifestManager，实现缓存检查 / 记录 / 清除
+ */
+export class CacheManager {
+    hasher;
+    manifestManager;
+    manifestPath = '';
+    outputDir = '';
+    /** check() 阶段缓存的 cacheKey，供 record() 复用以避免重复计算 */
+    lastCacheKey = null;
+    lastInputFiles = null;
+    constructor(hasher, manifestManager) {
+        this.hasher = hasher;
+        this.manifestManager = manifestManager;
+    }
+    /**
+     * 初始化：计算 manifestPath 并加载 manifest
+     * @param outputDir panoramic 输出目录
+     */
+    async initialize(outputDir) {
+        this.outputDir = outputDir;
+        this.manifestPath = path.join(outputDir, '_meta', '_cache-manifest.json');
+        await this.manifestManager.load(this.manifestPath);
+    }
+    /**
+     * 检查 generator 是否命中缓存
+     * 内部计算 cacheKey，并对 manifest entry 的所有 inputFiles 做 stale 校验
+     *
+     * 三路 stale 校验（任一满足即判定 stale）：
+     * 1. 文件不存在（已删除）
+     * 2. 文件 mtime 早于记录的 mtime（文件被回滚）
+     * 3. 文件内容 SHA256 与记录不一致
+     *
+     * @returns 命中时返回 ManifestEntry，未命中或 stale 时返回 false
+     */
+    async check(generator, context) {
+        let cacheKey;
+        let inputFiles;
+        try {
+            cacheKey = await buildGeneratorCacheKey(generator, context, this.hasher, this.outputDir || undefined);
+            inputFiles = await resolveInputFiles(generator, context, this.outputDir || undefined);
+        }
+        catch {
+            // cache key 计算失败（如依赖文件已删除），判定 stale
+            this.lastCacheKey = null;
+            this.lastInputFiles = null;
+            return false;
+        }
+        // 缓存 cacheKey 和 inputFiles 供 record() 复用
+        this.lastCacheKey = cacheKey;
+        this.lastInputFiles = inputFiles;
+        const entry = this.manifestManager.get(cacheKey);
+        if (!entry) {
+            return false;
+        }
+        // 对每个 inputFile 做 stale 校验
+        for (const record of entry.inputFiles) {
+            // 文件不存在
+            if (!fs.existsSync(record.path)) {
+                return false;
+            }
+            const stat = fs.statSync(record.path);
+            // mtime 回滚（文件被回滚到更早的版本）→ 快速判定 stale
+            if (stat.mtimeMs < record.mtime) {
+                return false;
+            }
+            // 始终校验 hash（不以 mtime 相同作为跳过条件）
+            // 确保内容变化但 mtime 保持不变时（如 --preserve-timestamps）也能检测到 stale
+            const currentHash = await this.hasher.hashFile(record.path);
+            if (currentHash !== record.hash) {
+                return false;
+            }
+        }
+        // 全部通过，缓存命中
+        console.log(`[cache-hit] ${generator.id}: ${entry.inputFiles.length} files unchanged, reusing output`);
+        return entry;
+    }
+    /**
+     * 记录 generator 的执行结果到 manifest（内存操作）
+     * 仅由成功路径调用
+     *
+     * @param generator generator 实例
+     * @param context ProjectContext
+     * @param outputFiles 本次生成的输出文件路径列表
+     */
+    async record(generator, context, outputFiles) {
+        // 优先复用 check() 阶段缓存的 cacheKey/inputFiles，避免重复计算
+        const cacheKey = this.lastCacheKey ?? await buildGeneratorCacheKey(generator, context, this.hasher, this.outputDir || undefined);
+        const inputFiles = this.lastInputFiles ?? await resolveInputFiles(generator, context, this.outputDir || undefined);
+        // 用完后清空，避免跨 generator 误用
+        this.lastCacheKey = null;
+        this.lastInputFiles = null;
+        // 为每个输入文件构建 FileHashRecord
+        const fileRecords = [];
+        for (const filePath of inputFiles) {
+            try {
+                const stat = fs.statSync(filePath);
+                const hash = await this.hasher.hashFile(filePath);
+                fileRecords.push({
+                    path: filePath,
+                    hash,
+                    mtime: stat.mtimeMs,
+                    size: stat.size,
+                });
+            }
+            catch {
+                // 文件不可读时跳过
+            }
+        }
+        const entry = {
+            cacheKey,
+            generatorId: generator.id,
+            inputFiles: fileRecords,
+            outputFiles,
+            createdAt: Date.now(),
+        };
+        this.manifestManager.set(entry);
+    }
+    /**
+     * 将内存 manifest 原子写盘
+     */
+    async flush() {
+        await this.manifestManager.flush(this.manifestPath);
+    }
+    /**
+     * 清除缓存
+     * @param generatorId 指定 generator 时仅清除该 generator 的条目，否则清除全部
+     */
+    async clear(generatorId) {
+        if (generatorId === undefined) {
+            // 清除全部：删除 manifest 文件及 .tmp 残留
+            this.manifestManager.delete();
+            try {
+                if (fs.existsSync(this.manifestPath)) {
+                    fs.unlinkSync(this.manifestPath);
+                }
+                const tmpPath = `${this.manifestPath}.tmp`;
+                if (fs.existsSync(tmpPath)) {
+                    fs.unlinkSync(tmpPath);
+                }
+            }
+            catch {
+                // 删除失败时静默处理
+            }
+        }
+        else {
+            // 清除指定 generator 的条目
+            this.manifestManager.delete(generatorId);
+            await this.flush();
+        }
+    }
+    /**
+     * 返回统计摘要（委托 ManifestManager）
+     */
+    stats() {
+        return this.manifestManager.stats();
+    }
+}
+//# sourceMappingURL=cache-manager.js.map

package/dist/panoramic/cache/cache-manager.js.map

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

package/dist/panoramic/cache/content-hasher.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 内容哈希计算接口
+ */
+export interface ContentHasher {
+    /**
+     * 计算单个文件的 SHA256 哈希
+     * 对 .md 文件自动跳过 frontmatter 区域，只哈希正文
+     * @param filePath 文件绝对路径
+     * @returns SHA256 hex 字符串
+     */
+    hashFile(filePath: string): Promise<string>;
+    /**
+     * 计算文件集合的聚合哈希（各文件 hash 排序后合并再次 hash）
+     * @param filePaths 文件绝对路径列表
+     * @returns 聚合后的 SHA256 hex 字符串
+     */
+    hashFiles(filePaths: string[]): Promise<string>;
+    /**
+     * 计算字符串内容的 SHA256 哈希
+     * @param content 任意字符串
+     * @returns SHA256 hex 字符串
+     */
+    hashContent(content: string): string;
+}
+/**
+ * ContentHasher 的默认实现
+ * 使用 node:crypto 的 SHA256 哈希
+ */
+export declare class ContentHasherImpl implements ContentHasher {
+    /**
+     * 计算单个文件的 SHA256 哈希
+     * 对 .md 扩展名的文件，先剥离 frontmatter 再哈希
+     * 哈希输入为 filePath + content（确保不同路径的相同内容产生不同 hash）
+     */
+    hashFile(filePath: string): Promise<string>;
+    /**
+     * 计算文件集合的聚合哈希
+     * 并发计算各文件 hash，按 filePath 排序后拼接再次 SHA256
+     * 保证文件集合相同、顺序不同时结果一致
+     */
+    hashFiles(filePaths: string[]): Promise<string>;
+    /**
+     * 计算字符串内容的 SHA256 哈希（同步）
+     */
+    hashContent(content: string): string;
+}
+//# sourceMappingURL=content-hasher.d.ts.map

package/dist/panoramic/cache/content-hasher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-hasher.d.ts","sourceRoot":"","sources":["../../../src/panoramic/cache/content-hasher.ts"],"names":[],"mappings":"AAaA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;OAIG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEhD;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CACtC;AA0CD;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAajD;;;;OAIG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBrD;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAMrC"}

package/dist/panoramic/cache/content-hasher.js

@@ -0,0 +1,89 @@
+/**
+ * 内容哈希引擎
+ * 使用 Node.js 原生 crypto.createHash('sha256') 计算文件和内容哈希
+ * 对 .md 文件自动跳过 frontmatter 区域，只哈希正文
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+// ============================================================
+// frontmatter 处理
+// ============================================================
+/** 扫描 frontmatter 闭合标记的最大行数 */
+const FRONTMATTER_SCAN_LIMIT = 50;
+/**
+ * 从 Markdown 内容中剥离 frontmatter，返回正文
+ *
+ * 边界规则（来自 spec clarifications）：
+ * 1. 首行不是 `---`：返回原文（无 frontmatter）
+ * 2. 首行是 `---`：从第 2 行开始扫描，找到仅含 `---` 的行即为闭合标记，返回其后正文
+ * 3. 扫描超过第 50 行仍未找到闭合：降级返回原文（未闭合 frontmatter）
+ */
+function stripFrontmatter(content) {
+    const lines = content.split('\n');
+    // 首行不是 --- → 无 frontmatter，返回全文
+    if (lines.length === 0 || lines[0]?.trim() !== '---') {
+        return content;
+    }
+    // 从第 2 行开始查找闭合 ---
+    const scanLimit = Math.min(lines.length, FRONTMATTER_SCAN_LIMIT);
+    for (let i = 1; i < scanLimit; i++) {
+        if (lines[i]?.trim() === '---') {
+            // 找到闭合标记，返回其后的正文
+            return lines.slice(i + 1).join('\n');
+        }
+    }
+    // 50 行内未找到闭合标记 → 降级返回全文
+    return content;
+}
+// ============================================================
+// ContentHasherImpl 实现
+// ============================================================
+/**
+ * ContentHasher 的默认实现
+ * 使用 node:crypto 的 SHA256 哈希
+ */
+export class ContentHasherImpl {
+    /**
+     * 计算单个文件的 SHA256 哈希
+     * 对 .md 扩展名的文件，先剥离 frontmatter 再哈希
+     * 哈希输入为 filePath + content（确保不同路径的相同内容产生不同 hash）
+     */
+    async hashFile(filePath) {
+        const rawContent = await fs.readFile(filePath, 'utf-8');
+        const ext = path.extname(filePath).toLowerCase();
+        // .md 文件跳过 frontmatter
+        const content = ext === '.md' ? stripFrontmatter(rawContent) : rawContent;
+        return crypto
+            .createHash('sha256')
+            .update(filePath + content)
+            .digest('hex');
+    }
+    /**
+     * 计算文件集合的聚合哈希
+     * 并发计算各文件 hash，按 filePath 排序后拼接再次 SHA256
+     * 保证文件集合相同、顺序不同时结果一致
+     */
+    async hashFiles(filePaths) {
+        // 按路径排序，确保顺序一致
+        const sortedPaths = [...filePaths].sort();
+        // 并发计算各文件 hash
+        const hashes = await Promise.all(sortedPaths.map((p) => this.hashFile(p)));
+        // 拼接所有 hash 再次 SHA256
+        const combined = hashes.join('');
+        return crypto
+            .createHash('sha256')
+            .update(combined)
+            .digest('hex');
+    }
+    /**
+     * 计算字符串内容的 SHA256 哈希（同步）
+     */
+    hashContent(content) {
+        return crypto
+            .createHash('sha256')
+            .update(content)
+            .digest('hex');
+    }
+}
+//# sourceMappingURL=content-hasher.js.map

package/dist/panoramic/cache/content-hasher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-hasher.js","sourceRoot":"","sources":["../../../src/panoramic/cache/content-hasher.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAiClC,+DAA+D;AAC/D,iBAAiB;AACjB,+DAA+D;AAE/D,+BAA+B;AAC/B,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAElC;;;;;;;GAOG;AACH,SAAS,gBAAgB,CAAC,OAAe;IACvC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAElC,gCAAgC;IAChC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;QACrD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,mBAAmB;IACnB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACjE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;YAC/B,iBAAiB;YACjB,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,wBAAwB;IACxB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,+DAA+D;AAC/D,uBAAuB;AACvB,+DAA+D;AAE/D;;;GAGG;AACH,MAAM,OAAO,iBAAiB;IAC5B;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,QAAgB;QAC7B,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACxD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;QAEjD,uBAAuB;QACvB,MAAM,OAAO,GAAG,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;QAE1E,OAAO,MAAM;aACV,UAAU,CAAC,QAAQ,CAAC;aACpB,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC;aAC1B,MAAM,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAS,CAAC,SAAmB;QACjC,eAAe;QACf,MAAM,WAAW,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC;QAE1C,eAAe;QACf,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAC9B,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CACzC,CAAC;QAEF,sBAAsB;QACtB,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjC,OAAO,MAAM;aACV,UAAU,CAAC,QAAQ,CAAC;aACpB,MAAM,CAAC,QAAQ,CAAC;aAChB,MAAM,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,OAAe;QACzB,OAAO,MAAM;aACV,UAAU,CAAC,QAAQ,CAAC;aACpB,MAAM,CAAC,OAAO,CAAC;aACf,MAAM,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;CACF"}

package/dist/panoramic/cache/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * cache 模块统一导出
+ * 薄壳文件，不含业务逻辑，按 Phase 逐步补充导出
+ */
+export { FileHashRecordSchema, ManifestEntrySchema, CacheManifestSchema, type FileHashRecord, type ManifestEntry, type CacheManifest, } from './schemas.js';
+export { type ContentHasher, ContentHasherImpl, } from './content-hasher.js';
+export { type ManifestManager, type ManifestStats, ManifestManagerImpl, } from './manifest-manager.js';
+export { CacheManager } from './cache-manager.js';
+export { buildGeneratorCacheKey, scanSourceFiles, resolveInputFiles } from './cache-key-builder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/panoramic/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/panoramic/cache/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,KAAK,aAAa,EAClB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/panoramic/cache/index.js

@@ -0,0 +1,13 @@
+/**
+ * cache 模块统一导出
+ * 薄壳文件，不含业务逻辑，按 Phase 逐步补充导出
+ */
+// Phase A: 基础设施层
+export { FileHashRecordSchema, ManifestEntrySchema, CacheManifestSchema, } from './schemas.js';
+export { ContentHasherImpl, } from './content-hasher.js';
+// Phase B: Manifest 管理层
+export { ManifestManagerImpl, } from './manifest-manager.js';
+// Phase C: 缓存拦截层
+export { CacheManager } from './cache-manager.js';
+export { buildGeneratorCacheKey, scanSourceFiles, resolveInputFiles } from './cache-key-builder.js';
+//# sourceMappingURL=index.js.map

package/dist/panoramic/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/panoramic/cache/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,iBAAiB;AACjB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GAIpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAEL,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAE7B,wBAAwB;AACxB,OAAO,EAGL,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAE/B,iBAAiB;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

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

@@ -0,0 +1,83 @@
+import { type ManifestEntry } from './schemas.js';
+/** manifest 统计摘要 */
+export interface ManifestStats {
+    /** 缓存条目总数 */
+    entryCount: number;
+    /** 所有 ManifestEntry.inputFiles[*].size 的累加值（字节） */
+    totalSizeBytes: number;
+    /** manifest 最后更新时间（Unix ms），无记录时为 undefined */
+    lastUpdatedAt: number | undefined;
+    /** generatorId → 条目数 */
+    byGenerator: Record<string, number>;
+}
+/**
+ * manifest 管理接口
+ */
+export interface ManifestManager {
+    /**
+     * 加载 manifest 文件
+     * 版本不兼容时自动清空并打印警告，不抛错
+     * @param manifestPath _cache-manifest.json 的绝对路径
+     */
+    load(manifestPath: string): Promise<void>;
+    /**
+     * 根据 cacheKey 查询 manifest entry
+     * @returns entry 对象，不存在时返回 undefined
+     */
+    get(cacheKey: string): ManifestEntry | undefined;
+    /**
+     * 更新或插入一条 manifest entry（内存操作，不立即写盘）
+     */
+    set(entry: ManifestEntry): void;
+    /**
+     * 删除指定 generatorId 的所有条目（内存操作）
+     * generatorId 为 undefined 时删除全部条目
+     */
+    delete(generatorId?: string): void;
+    /**
+     * 将当前内存中的 manifest 原子写入磁盘
+     * @param manifestPath 写入目标路径
+     */
+    flush(manifestPath: string): Promise<void>;
+    /**
+     * 返回当前 manifest 的统计摘要
+     */
+    stats(): ManifestStats;
+}
+/**
+ * ManifestManager 的默认实现
+ */
+export declare class ManifestManagerImpl implements ManifestManager {
+    /** 内存态 manifest */
+    private manifest;
+    /** manifest 文件路径 */
+    private manifestPath;
+    /**
+     * 加载 manifest 文件
+     * 文件不存在时静默保持空 manifest
+     * version 不兼容或 JSON 损坏时 warn 并清空，不抛错
+     */
+    load(manifestPath: string): Promise<void>;
+    /**
+     * 根据 cacheKey 查询 entry
+     */
+    get(cacheKey: string): ManifestEntry | undefined;
+    /**
+     * 更新或插入 entry（内存操作）
+     */
+    set(entry: ManifestEntry): void;
+    /**
+     * 删除条目（内存操作）
+     * generatorId 为 undefined 时清空全部
+     */
+    delete(generatorId?: string): void;
+    /**
+     * 将内存 manifest 原子写盘
+     */
+    flush(manifestPath: string): Promise<void>;
+    /**
+     * 返回统计摘要
+     */
+    stats(): ManifestStats;
+}
+//# sourceMappingURL=manifest-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-manager.d.ts","sourceRoot":"","sources":["../../../src/panoramic/cache/manifest-manager.ts"],"names":[],"mappings":"AAOA,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AAMtB,oBAAoB;AACpB,MAAM,WAAW,aAAa;IAC5B,aAAa;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;;OAGG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAEjD;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAEhC;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;OAGG;IACH,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3C;;OAEG;IACH,KAAK,IAAI,aAAa,CAAC;CACxB;AAeD;;GAEG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,mBAAmB;IACnB,OAAO,CAAC,QAAQ,CAAwC;IAExD,oBAAoB;IACpB,OAAO,CAAC,YAAY,CAAc;IAElC;;;;OAIG;IACG,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B/C;;OAEG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIhD;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAI/B;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAelC;;OAEG;IACG,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhD;;OAEG;IACH,KAAK,IAAI,aAAa;CA0BvB"}

package/dist/panoramic/cache/manifest-manager.js

@@ -0,0 +1,119 @@
+/**
+ * Manifest 管理器
+ * 内存态 manifest 管理，含加载、查询、更新、删除、原子刷盘、统计
+ * 版本不兼容或 JSON 损坏时打印 warn 并清空，不抛错
+ */
+import * as fs from 'node:fs';
+import { writeAtomicJson } from '../../utils/atomic-write.js';
+import { CacheManifestSchema, } from './schemas.js';
+// ============================================================
+// ManifestManagerImpl 实现
+// ============================================================
+/** 创建空 manifest 的工厂函数 */
+function createEmptyManifest() {
+    return {
+        version: '1',
+        updatedAt: 0,
+        entries: {},
+    };
+}
+/**
+ * ManifestManager 的默认实现
+ */
+export class ManifestManagerImpl {
+    /** 内存态 manifest */
+    manifest = createEmptyManifest();
+    /** manifest 文件路径 */
+    manifestPath = '';
+    /**
+     * 加载 manifest 文件
+     * 文件不存在时静默保持空 manifest
+     * version 不兼容或 JSON 损坏时 warn 并清空，不抛错
+     */
+    async load(manifestPath) {
+        this.manifestPath = manifestPath;
+        if (!fs.existsSync(manifestPath)) {
+            this.manifest = createEmptyManifest();
+            return;
+        }
+        try {
+            const content = fs.readFileSync(manifestPath, 'utf-8');
+            const data = JSON.parse(content);
+            const result = CacheManifestSchema.safeParse(data);
+            if (!result.success) {
+                console.warn('[cache] manifest 解析失败，自动清空缓存');
+                this.manifest = createEmptyManifest();
+                return;
+            }
+            this.manifest = result.data;
+        }
+        catch {
+            // JSON.parse 失败等情况
+            console.warn('[cache] manifest 文件损坏，自动清空缓存');
+            this.manifest = createEmptyManifest();
+        }
+    }
+    /**
+     * 根据 cacheKey 查询 entry
+     */
+    get(cacheKey) {
+        return this.manifest.entries[cacheKey];
+    }
+    /**
+     * 更新或插入 entry（内存操作）
+     */
+    set(entry) {
+        this.manifest.entries[entry.cacheKey] = entry;
+    }
+    /**
+     * 删除条目（内存操作）
+     * generatorId 为 undefined 时清空全部
+     */
+    delete(generatorId) {
+        if (generatorId === undefined) {
+            this.manifest.entries = {};
+            return;
+        }
+        // 遍历删除匹配 generatorId 的条目
+        const entries = this.manifest.entries;
+        for (const key of Object.keys(entries)) {
+            if (entries[key]?.generatorId === generatorId) {
+                delete entries[key];
+            }
+        }
+    }
+    /**
+     * 将内存 manifest 原子写盘
+     */
+    async flush(manifestPath) {
+        this.manifest.updatedAt = Date.now();
+        writeAtomicJson(manifestPath, this.manifest);
+    }
+    /**
+     * 返回统计摘要
+     */
+    stats() {
+        const entries = this.manifest.entries;
+        const keys = Object.keys(entries);
+        let totalSizeBytes = 0;
+        const byGenerator = {};
+        for (const key of keys) {
+            const entry = entries[key];
+            if (!entry)
+                continue;
+            // 累加 inputFiles 的 size
+            for (const file of entry.inputFiles) {
+                totalSizeBytes += file.size;
+            }
+            // 按 generatorId 分组计数
+            byGenerator[entry.generatorId] = (byGenerator[entry.generatorId] ?? 0) + 1;
+        }
+        return {
+            entryCount: keys.length,
+            totalSizeBytes,
+            lastUpdatedAt: this.manifest.updatedAt > 0 ? this.manifest.updatedAt : undefined,
+            byGenerator,
+        };
+    }
+}
+//# sourceMappingURL=manifest-manager.js.map

package/dist/panoramic/cache/manifest-manager.js.map

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