autosnippet 3.3.0 → 3.3.3

package/dist/lib/service/panorama/PanoramaScanner.d.ts

@@ -0,0 +1,52 @@
+/**
+ * PanoramaScanner — 全景数据内置扫描器
+ *
+ * 在全景数据缺失时自动运行轻量级结构扫描（Phase 1→2.1），
+ * 填充 code_entities + knowledge_edges，使 PanoramaService 能产生有效数据。
+ *
+ * 非 MCP 操作，而是 PanoramaService 的内置依赖。
+ * 调用时机：
+ *   - PanoramaService 发现 DB 中无 code_entities 时自动触发
+ *   - 手动调用 invalidate + getResult 时检查并补充
+ *
+ * @module PanoramaScanner
+ */
+export interface PanoramaScannerOptions {
+    projectRoot: string;
+    container: ScannerContainer;
+    logger?: ScannerLogger;
+}
+export interface ScannerContainer {
+    get(name: string): any;
+}
+export interface ScannerLogger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+}
+export interface ScanResult {
+    entities: number;
+    edges: number;
+    modules: number;
+    durationMs: number;
+}
+export declare class PanoramaScanner {
+    #private;
+    constructor(opts: PanoramaScannerOptions);
+    /**
+     * 检测 DB 中是否已有该项目的 code_entities 数据
+     */
+    hasData(): boolean;
+    /**
+     * 确保全景数据存在。无数据时自动执行扫描。
+     * 幂等：扫描过一次后不再重复（重启进程或手动 reset 可重新触发）。
+     */
+    ensureData(): Promise<ScanResult | null>;
+    /**
+     * 执行完整扫描（强制，不检查缓存）
+     */
+    scan(): Promise<ScanResult>;
+    /**
+     * 重置扫描状态（允许下次 ensureData 重新扫描）
+     */
+    reset(): void;
+}

package/dist/lib/service/panorama/PanoramaScanner.js

@@ -0,0 +1,188 @@
+/**
+ * PanoramaScanner — 全景数据内置扫描器
+ *
+ * 在全景数据缺失时自动运行轻量级结构扫描（Phase 1→2.1），
+ * 填充 code_entities + knowledge_edges，使 PanoramaService 能产生有效数据。
+ *
+ * 非 MCP 操作，而是 PanoramaService 的内置依赖。
+ * 调用时机：
+ *   - PanoramaService 发现 DB 中无 code_entities 时自动触发
+ *   - 手动调用 invalidate + getResult 时检查并补充
+ *
+ * @module PanoramaScanner
+ */
+/* ═══ Silent Logger (fallback) ════════════════════════════ */
+const SILENT_LOGGER = {
+    info() { },
+    warn() { },
+};
+/* ═══ PanoramaScanner Class ═══════════════════════════════ */
+export class PanoramaScanner {
+    #projectRoot;
+    #container;
+    #logger;
+    #hasScanned = false;
+    constructor(opts) {
+        this.#projectRoot = opts.projectRoot;
+        this.#container = opts.container;
+        this.#logger = opts.logger ?? SILENT_LOGGER;
+    }
+    /**
+     * 检测 DB 中是否已有该项目的 code_entities 数据
+     */
+    hasData() {
+        try {
+            const db = this.#container.get('database');
+            const rawDb = db?.getDb ? db.getDb() : db;
+            if (!rawDb?.prepare) {
+                return false;
+            }
+            const row = rawDb
+                .prepare(`SELECT COUNT(*) as cnt FROM code_entities WHERE project_root = ?`)
+                .get(this.#projectRoot);
+            return (row?.cnt ?? 0) > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 确保全景数据存在。无数据时自动执行扫描。
+     * 幂等：扫描过一次后不再重复（重启进程或手动 reset 可重新触发）。
+     */
+    async ensureData() {
+        if (this.#hasScanned || this.hasData()) {
+            return null;
+        }
+        return this.scan();
+    }
+    /**
+     * 执行完整扫描（强制，不检查缓存）
+     */
+    async scan() {
+        const t0 = Date.now();
+        this.#logger.info('[PanoramaScanner] Starting structure scan...');
+        let entities = 0;
+        let edges = 0;
+        let modules = 0;
+        try {
+            const { runPhase1_FileCollection, runPhase1_5_AstAnalysis, runPhase1_6_EntityGraph, runPhase1_7_CallGraph, runPhase2_DependencyGraph, runPhase2_1_ModuleEntities, } = await import('../../external/mcp/handlers/bootstrap/shared/bootstrap-phases.js');
+            // Phase 1: 文件收集
+            const phase1 = await runPhase1_FileCollection(this.#projectRoot, this.#logger, {
+                maxFiles: 500,
+            });
+            if (!phase1.allFiles?.length) {
+                this.#logger.warn('[PanoramaScanner] No files found, skipping scan');
+                this.#hasScanned = true;
+                return { entities: 0, edges: 0, modules: 0, durationMs: Date.now() - t0 };
+            }
+            // Phase 1.5: AST 分析
+            const phase1_5 = await runPhase1_5_AstAnalysis(phase1.allFiles, phase1.langStats, this.#logger);
+            // Phase 1.6: Entity Graph 写入
+            if (phase1_5.astProjectSummary) {
+                const phase1_6 = await runPhase1_6_EntityGraph(phase1_5.astProjectSummary, this.#projectRoot, this.#container, this.#logger);
+                entities = phase1_6.codeEntityResult?.entitiesUpserted ?? 0;
+                edges = phase1_6.codeEntityResult?.edgesCreated ?? 0;
+            }
+            // Phase 1.7: Call Graph (增强耦合准确度)
+            if (phase1_5.astProjectSummary) {
+                try {
+                    await runPhase1_7_CallGraph(phase1_5.astProjectSummary, this.#projectRoot, this.#container, this.#logger);
+                }
+                catch {
+                    // Call graph 失败不阻塞
+                }
+            }
+            // Phase 2: 依赖图
+            if (phase1.discoverer) {
+                const phase2 = await runPhase2_DependencyGraph(phase1.discoverer, this.#container, this.#logger);
+                edges += phase2.depEdgesWritten;
+                // Phase 2.1: Module 实体
+                if (phase2.depGraphData) {
+                    await runPhase2_1_ModuleEntities(phase2.depGraphData, this.#projectRoot, this.#container, this.#logger);
+                    modules = phase2.depGraphData.nodes?.length ?? 0;
+                }
+            }
+            // Phase 2.2: 目录推断兜底
+            // 当 Phase 2.1 未产出 module 实体时（无 Package.swift / build.gradle 等），
+            // 从已有 code_entities 按顶层目录分组写入 module 实体
+            if (modules === 0 && entities > 0) {
+                modules = this.#inferModulesFromDirectories();
+            }
+        }
+        catch (err) {
+            this.#logger.warn(`[PanoramaScanner] Scan failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        this.#hasScanned = true;
+        const durationMs = Date.now() - t0;
+        this.#logger.info(`[PanoramaScanner] Scan complete: ${entities} entities, ${edges} edges, ${modules} modules (${durationMs}ms)`);
+        return { entities, edges, modules, durationMs };
+    }
+    /**
+     * 重置扫描状态（允许下次 ensureData 重新扫描）
+     */
+    reset() {
+        this.#hasScanned = false;
+    }
+    /* ─── 目录推断兜底 ─────────────────────────────── */
+    /**
+     * 从 code_entities 中按顶层目录分组写入 module 实体 + is_part_of 边。
+     * 仅在 Phase 2.1 未产出 module 时调用。
+     */
+    #inferModulesFromDirectories() {
+        try {
+            const db = this.#container.get('database');
+            const rawDb = db?.getDb ? db.getDb() : db;
+            if (!rawDb?.prepare) {
+                return 0;
+            }
+            // 查询所有非 module 实体的文件路径
+            const rows = rawDb
+                .prepare(`SELECT DISTINCT entity_id, file_path FROM code_entities
+           WHERE project_root = ? AND file_path IS NOT NULL AND entity_type != 'module'`)
+                .all(this.#projectRoot);
+            if (rows.length === 0) {
+                return 0;
+            }
+            // 按顶层目录分组
+            const groups = new Map();
+            for (const row of rows) {
+                const filePath = row.file_path;
+                if (!filePath) {
+                    continue;
+                }
+                const relative = filePath.startsWith(this.#projectRoot)
+                    ? filePath.slice(this.#projectRoot.length).replace(/^\//, '')
+                    : filePath;
+                const firstDir = relative.split('/')[0];
+                if (!firstDir || firstDir.startsWith('.')) {
+                    continue;
+                }
+                if (!groups.has(firstDir)) {
+                    groups.set(firstDir, []);
+                }
+                groups.get(firstDir).push(row.entity_id);
+            }
+            if (groups.size === 0) {
+                return 0;
+            }
+            // 写入 module 实体 + is_part_of 边
+            const insertEntity = rawDb.prepare(`INSERT OR IGNORE INTO code_entities (entity_id, name, entity_type, file_path, project_root)
+         VALUES (?, ?, 'module', NULL, ?)`);
+            const insertEdge = rawDb.prepare(`INSERT OR IGNORE INTO knowledge_edges (from_id, from_type, to_id, to_type, relation, weight)
+         VALUES (?, 'entity', ?, 'module', 'is_part_of', 1.0)`);
+            for (const [dirName, entityIds] of groups) {
+                insertEntity.run(dirName, dirName, this.#projectRoot);
+                for (const entityId of entityIds) {
+                    insertEdge.run(entityId, dirName);
+                }
+            }
+            this.#logger.info(`[PanoramaScanner] Directory fallback: inferred ${groups.size} modules from top-level dirs`);
+            return groups.size;
+        }
+        catch (err) {
+            this.#logger.warn(`[PanoramaScanner] Directory fallback failed: ${err instanceof Error ? err.message : String(err)}`);
+            return 0;
+        }
+    }
+}

package/dist/lib/service/panorama/PanoramaService.d.ts

@@ -0,0 +1,125 @@
+/**
+ * PanoramaService — 全景服务主入口
+ *
+ * 提供 4 个 operation:
+ *   overview — 项目骨架 + 层级 + token 预算截断
+ *   module   — 单模块详情 + Recipe 覆盖率
+ *   gaps     — 知识空白区 (有代码无 Recipe)
+ *   health   — 全景健康度 (覆盖率 + 耦合度 + 衰退)
+ *
+ * 模块发现委托给 ModuleDiscoverer（SRP）。
+ * 内存缓存 + 24h 过期策略。
+ *
+ * @module PanoramaService
+ */
+import type { SignalBus } from '../../infrastructure/signal/SignalBus.js';
+import { ModuleDiscoverer } from './ModuleDiscoverer.js';
+import type { PanoramaAggregator } from './PanoramaAggregator.js';
+import type { PanoramaScanner } from './PanoramaScanner.js';
+import type { CeDbLike, HealthRadar, KnowledgeGap, PanoramaModule, PanoramaResult } from './PanoramaTypes.js';
+export interface PanoramaServiceOptions {
+    aggregator: PanoramaAggregator;
+    db: CeDbLike;
+    projectRoot: string;
+    scanner?: PanoramaScanner;
+    moduleDiscoverer?: ModuleDiscoverer;
+    signalBus?: SignalBus;
+}
+export interface PanoramaOverview {
+    projectRoot: string;
+    moduleCount: number;
+    layerCount: number;
+    totalFiles: number;
+    totalRecipes: number;
+    overallCoverage: number;
+    layers: Array<{
+        level: number;
+        name: string;
+        modules: Array<{
+            name: string;
+            role: string;
+            fileCount: number;
+            recipeCount: number;
+        }>;
+    }>;
+    cycleCount: number;
+    gapCount: number;
+    /** 多维度知识健康雷达 */
+    healthRadar: HealthRadar;
+    computedAt: number;
+    stale: boolean;
+}
+export interface PanoramaModuleDetail {
+    module: PanoramaModule;
+    layerName: string;
+    neighbors: Array<{
+        name: string;
+        direction: 'in' | 'out';
+        weight: number;
+    }>;
+    /** File groups by subdirectory within the module */
+    fileGroups: Array<{
+        group: string;
+        files: string[];
+        count: number;
+    }>;
+    /** Recipes matched to this module (by category/trigger/file path) */
+    recipes: Array<{
+        id: string;
+        title: string;
+        trigger: string;
+        kind: string;
+    }>;
+    /** Files not covered by any matched recipe */
+    uncoveredFileCount: number;
+    /** Auto-generated structural summary for the agent */
+    summary: string;
+}
+export interface PanoramaHealth {
+    /** 多维度知识健康雷达 */
+    healthRadar: HealthRadar;
+    avgCoupling: number;
+    cycleCount: number;
+    gapCount: number;
+    highPriorityGaps: number;
+    moduleCount: number;
+    /** 综合健康分 0-100 (维度覆盖 60 + 无循环 20 + 无高优空白 10 + 耦合适中 10) */
+    healthScore: number;
+}
+export declare class PanoramaService {
+    #private;
+    constructor(opts: PanoramaServiceOptions);
+    /**
+     * 获取项目全景概览
+     */
+    getOverview(): PanoramaOverview;
+    /**
+     * 获取单模块详情 (enriched with file groups, recipes, and summary)
+     */
+    getModule(moduleName: string): PanoramaModuleDetail | null;
+    /**
+     * 获取知识空白区
+     */
+    getGaps(): KnowledgeGap[];
+    /**
+     * 获取全景健康度
+     */
+    getHealth(): PanoramaHealth;
+    /**
+     * 获取完整 PanoramaResult（内部使用或 Bootstrap 注入）
+     */
+    getResult(): PanoramaResult;
+    /**
+     * 确保全景数据已就绪（无数据时自动扫描）
+     * MCP handler / HTTP route 应在返回数据前调用此方法
+     */
+    ensureData(): Promise<void>;
+    /**
+     * 强制刷新缓存
+     */
+    invalidate(): void;
+    /**
+     * 强制重新扫描（invalidate + 重置 scanner）
+     */
+    rescan(): Promise<void>;
+}