autosnippet 3.3.0 → 3.3.3

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

@@ -0,0 +1,363 @@
+/**
+ * PanoramaService — 全景服务主入口
+ *
+ * 提供 4 个 operation:
+ *   overview — 项目骨架 + 层级 + token 预算截断
+ *   module   — 单模块详情 + Recipe 覆盖率
+ *   gaps     — 知识空白区 (有代码无 Recipe)
+ *   health   — 全景健康度 (覆盖率 + 耦合度 + 衰退)
+ *
+ * 模块发现委托给 ModuleDiscoverer（SRP）。
+ * 内存缓存 + 24h 过期策略。
+ *
+ * @module PanoramaService
+ */
+import { ModuleDiscoverer } from './ModuleDiscoverer.js';
+/* ═══ Constants ═══════════════════════════════════════════ */
+const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000; // 24h
+/* ═══ PanoramaService Class ═══════════════════════════════ */
+export class PanoramaService {
+    #aggregator;
+    #db;
+    #projectRoot;
+    #scanner;
+    #moduleDiscoverer;
+    #signalBus;
+    #cache = null;
+    #scanPromise = null;
+    #lastOverview = null;
+    constructor(opts) {
+        this.#aggregator = opts.aggregator;
+        this.#db = opts.db;
+        this.#projectRoot = opts.projectRoot;
+        this.#scanner = opts.scanner ?? null;
+        this.#moduleDiscoverer =
+            opts.moduleDiscoverer ?? new ModuleDiscoverer(opts.db, opts.projectRoot);
+        this.#signalBus = opts.signalBus ?? null;
+        // Phase 2: 订阅信号标记缓存失效
+        if (this.#signalBus) {
+            this.#signalBus.subscribe('guard|lifecycle|usage', () => {
+                this.#cache = null;
+            });
+        }
+    }
+    /* ─── Public API ────────────────────────────────── */
+    /**
+     * 获取项目全景概览
+     */
+    getOverview() {
+        const result = this.#getOrCompute();
+        const isStale = Date.now() - result.computedAt > STALE_THRESHOLD_MS;
+        let totalFiles = 0;
+        for (const [, mod] of result.modules) {
+            totalFiles += mod.fileCount;
+        }
+        // 使用项目级 recipe 总数，而非 per-module 之和
+        // 因为大多数 recipe scope 为 universal，无法匹配到具体模块
+        const totalRecipes = result.projectRecipeCount;
+        const overview = {
+            projectRoot: this.#projectRoot,
+            moduleCount: result.modules.size,
+            layerCount: result.layers.levels.length,
+            totalFiles,
+            totalRecipes,
+            overallCoverage: totalFiles > 0 ? totalRecipes / totalFiles : 0,
+            layers: result.layers.levels.map((l) => ({
+                level: l.level,
+                name: l.name,
+                modules: l.modules.map((mName) => {
+                    const mod = result.modules.get(mName);
+                    return {
+                        name: mName,
+                        role: mod?.refinedRole ?? 'feature',
+                        fileCount: mod?.fileCount ?? 0,
+                        recipeCount: mod?.recipeCount ?? 0,
+                    };
+                }),
+            })),
+            cycleCount: result.cycles.length,
+            gapCount: result.gaps.length,
+            healthRadar: result.healthRadar,
+            computedAt: result.computedAt,
+            stale: isStale,
+        };
+        // Phase 3: 发射 panorama 信号 — 覆盖率/健康度变化检测
+        if (this.#signalBus && this.#lastOverview) {
+            if (Math.abs(overview.overallCoverage - this.#lastOverview.overallCoverage) >= 0.05) {
+                this.#signalBus.send('panorama', 'PanoramaService.coverage', overview.overallCoverage, {
+                    metadata: {
+                        oldCoverage: this.#lastOverview.overallCoverage,
+                        newCoverage: overview.overallCoverage,
+                    },
+                });
+            }
+        }
+        this.#lastOverview = overview;
+        return overview;
+    }
+    /**
+     * 获取单模块详情 (enriched with file groups, recipes, and summary)
+     */
+    getModule(moduleName) {
+        const result = this.#getOrCompute();
+        const mod = result.modules.get(moduleName);
+        if (!mod) {
+            return null;
+        }
+        // Layer name: derive from module's own refinedRole (more accurate than level vote)
+        const layerName = PanoramaService.#roleToLayer(mod.refinedRole || mod.inferredRole);
+        // File groups: group by immediate subdirectory within the module
+        const fileGroups = PanoramaService.#groupFilesBySubdir(mod.files);
+        // Matched recipes from DB
+        const recipes = this.#findModuleRecipes(moduleName, mod);
+        // Uncovered file count estimate
+        const coveredFileCount = Math.min(recipes.length * 2, mod.fileCount); // rough heuristic
+        const uncoveredFileCount = Math.max(0, mod.fileCount - coveredFileCount);
+        // Neighbors from DB edges
+        const neighbors = [];
+        const outNeighbors = this.#db
+            .prepare(`SELECT DISTINCT to_id, weight FROM knowledge_edges
+         WHERE from_id = ? AND from_type = 'module' AND relation = 'depends_on'`)
+            .all(moduleName);
+        for (const n of outNeighbors) {
+            neighbors.push({
+                name: n.to_id,
+                direction: 'out',
+                weight: Number(n.weight ?? 1),
+            });
+        }
+        const inNeighbors = this.#db
+            .prepare(`SELECT DISTINCT from_id, weight FROM knowledge_edges
+         WHERE to_id = ? AND to_type = 'module' AND relation = 'depends_on'`)
+            .all(moduleName);
+        for (const n of inNeighbors) {
+            neighbors.push({
+                name: n.from_id,
+                direction: 'in',
+                weight: Number(n.weight ?? 1),
+            });
+        }
+        // Generate summary
+        const summary = PanoramaService.#generateModuleSummary(mod, layerName, fileGroups, recipes, neighbors);
+        return { module: mod, layerName, neighbors, fileGroups, recipes, uncoveredFileCount, summary };
+    }
+    /* ─── Module detail helpers ─────────────────────── */
+    /** Role → layer name mapping (consistent with PanoramaAggregator) */
+    static #roleToLayer(role) {
+        const map = {
+            core: 'Foundation',
+            foundation: 'Foundation',
+            model: 'Model',
+            service: 'Service',
+            networking: 'Infrastructure',
+            storage: 'Infrastructure',
+            ui: 'UI',
+            feature: 'Feature',
+            config: 'Configuration',
+            test: 'Test',
+            app: 'Application',
+        };
+        return map[role] ?? 'Feature';
+    }
+    /** Group file paths by their immediate subdirectory within the module */
+    static #groupFilesBySubdir(files) {
+        if (files.length === 0) {
+            return [];
+        }
+        // Find common prefix to determine module root
+        const prefix = PanoramaService.#commonPathPrefix(files);
+        const groups = new Map();
+        for (const f of files) {
+            const relative = f.slice(prefix.length);
+            const firstSlash = relative.indexOf('/');
+            const group = firstSlash > 0 ? relative.slice(0, firstSlash) : '(root)';
+            if (!groups.has(group)) {
+                groups.set(group, []);
+            }
+            groups.get(group).push(f);
+        }
+        return [...groups.entries()]
+            .sort((a, b) => b[1].length - a[1].length)
+            .map(([group, groupFiles]) => ({ group, files: groupFiles, count: groupFiles.length }));
+    }
+    static #commonPathPrefix(paths) {
+        if (paths.length === 0) {
+            return '';
+        }
+        let prefix = paths[0];
+        for (const p of paths) {
+            while (!p.startsWith(prefix)) {
+                const lastSlash = prefix.lastIndexOf('/');
+                if (lastSlash < 0) {
+                    return '';
+                }
+                prefix = prefix.slice(0, lastSlash + 1);
+            }
+        }
+        return prefix;
+    }
+    /** Find recipes related to this module by category, trigger, or title match */
+    #findModuleRecipes(moduleName, mod) {
+        try {
+            // Map refined role to typical recipe categories
+            const roleCategories = {
+                networking: ['Network', 'API', 'Http'],
+                storage: ['Storage', 'Database', 'Cache'],
+                ui: ['UI', 'View', 'Component'],
+                service: ['Service', 'Manager'],
+                model: ['Model', 'Entity'],
+                core: ['Core', 'Foundation', 'Utility'],
+                foundation: ['Core', 'Foundation', 'Utility'],
+                feature: ['Feature'],
+            };
+            const categories = roleCategories[mod.refinedRole] ?? [];
+            // Build a LIKE query that matches module name or related categories
+            const conditions = [];
+            const params = [];
+            // Match by module name in title or trigger
+            conditions.push('(title LIKE ? OR trigger LIKE ?)');
+            params.push(`%${moduleName}%`, `%${moduleName}%`);
+            // Match by category
+            for (const cat of categories) {
+                conditions.push('category = ?');
+                params.push(cat);
+            }
+            const whereClause = conditions.join(' OR ');
+            const rows = this.#db
+                .prepare(`SELECT id, title, trigger, kind FROM knowledge_entries
+           WHERE lifecycle IN ('active', 'staging', 'pending')
+             AND (${whereClause})
+           ORDER BY lifecycle ASC
+           LIMIT 20`)
+                .all(...params);
+            return rows.map((r) => ({
+                id: String(r.id ?? ''),
+                title: String(r.title ?? ''),
+                trigger: String(r.trigger ?? ''),
+                kind: String(r.kind ?? ''),
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Generate a structural summary for the agent */
+    static #generateModuleSummary(mod, layerName, fileGroups, recipes, neighbors) {
+        const lines = [];
+        // Identity
+        lines.push(`${mod.name} is a ${layerName} layer module (role: ${mod.refinedRole}, confidence: ${(mod.roleConfidence * 100).toFixed(0)}%).`);
+        // Structure
+        const groupDesc = fileGroups.map((g) => `${g.group}(${g.count})`).join(', ');
+        lines.push(`Contains ${mod.fileCount} files in ${fileGroups.length} groups: ${groupDesc}.`);
+        // Dependencies
+        const dependsOn = neighbors.filter((n) => n.direction === 'out').map((n) => n.name);
+        const usedBy = neighbors.filter((n) => n.direction === 'in').map((n) => n.name);
+        if (dependsOn.length > 0) {
+            lines.push(`Depends on: ${dependsOn.join(', ')}.`);
+        }
+        if (usedBy.length > 0) {
+            lines.push(`Used by: ${usedBy.join(', ')}.`);
+        }
+        if (dependsOn.length === 0 && usedBy.length === 0) {
+            lines.push('No dependency edges recorded (consider running a full bootstrap scan).');
+        }
+        // Knowledge coverage
+        lines.push(`Knowledge coverage: ${recipes.length} recipes matched, ${(mod.coverageRatio * 100).toFixed(0)}% estimated coverage.`);
+        if (recipes.length > 0) {
+            const recipeList = recipes
+                .slice(0, 5)
+                .map((r) => r.title)
+                .join('; ');
+            lines.push(`Key recipes: ${recipeList}.`);
+        }
+        if (mod.coverageRatio < 0.5) {
+            lines.push('Coverage is below 50% — consider submitting knowledge for uncovered file groups.');
+        }
+        return lines.join(' ');
+    }
+    /**
+     * 获取知识空白区
+     */
+    getGaps() {
+        const result = this.#getOrCompute();
+        return result.gaps;
+    }
+    /**
+     * 获取全景健康度
+     */
+    getHealth() {
+        const result = this.#getOrCompute();
+        let totalCoupling = 0;
+        let count = 0;
+        for (const [, mod] of result.modules) {
+            totalCoupling += mod.fanIn + mod.fanOut;
+            count++;
+        }
+        const avgCoupling = count > 0 ? totalCoupling / count : 0;
+        const highPriorityGaps = result.gaps.filter((g) => g.priority === 'high').length;
+        const radar = result.healthRadar;
+        // 健康分: 100 分制 (基于维度覆盖率 + 结构健康)
+        // 维度覆盖 60 分 + 无循环 20 分 + 无高优空白 10 分 + 耦合度适中 10 分
+        let healthScore = radar.overallScore * 0.6;
+        healthScore += result.cycles.length === 0 ? 20 : Math.max(0, 20 - result.cycles.length * 5);
+        healthScore += highPriorityGaps === 0 ? 10 : Math.max(0, 10 - highPriorityGaps * 2);
+        healthScore += avgCoupling < 10 ? 10 : Math.max(0, 10 - (avgCoupling - 10));
+        healthScore = Math.round(Math.max(0, Math.min(100, healthScore)));
+        return {
+            healthRadar: radar,
+            avgCoupling,
+            cycleCount: result.cycles.length,
+            gapCount: result.gaps.length,
+            highPriorityGaps,
+            moduleCount: count,
+            healthScore,
+        };
+    }
+    /**
+     * 获取完整 PanoramaResult（内部使用或 Bootstrap 注入）
+     */
+    getResult() {
+        return this.#getOrCompute();
+    }
+    /**
+     * 确保全景数据已就绪（无数据时自动扫描）
+     * MCP handler / HTTP route 应在返回数据前调用此方法
+     */
+    async ensureData() {
+        if (!this.#scanner) {
+            return;
+        }
+        if (!this.#scanPromise) {
+            this.#scanPromise = this.#scanner.ensureData().then(() => {
+                this.#cache = null; // 扫描后清除缓存以触发重新计算
+            });
+        }
+        await this.#scanPromise;
+    }
+    /**
+     * 强制刷新缓存
+     */
+    invalidate() {
+        this.#cache = null;
+        this.#scanPromise = null;
+    }
+    /**
+     * 强制重新扫描（invalidate + 重置 scanner）
+     */
+    async rescan() {
+        this.invalidate();
+        if (this.#scanner) {
+            this.#scanner.reset();
+            await this.ensureData();
+        }
+    }
+    /* ─── Cache + Compute ───────────────────────────── */
+    #getOrCompute() {
+        if (this.#cache) {
+            return this.#cache;
+        }
+        const candidates = this.#moduleDiscoverer.discover();
+        this.#cache = this.#aggregator.compute(candidates);
+        return this.#cache;
+    }
+}

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

@@ -0,0 +1,134 @@
+/**
+ * PanoramaTypes — 全景服务共享类型定义
+ *
+ * @module PanoramaTypes
+ */
+export interface CeDbLike {
+    getDb?: () => CeDbLike;
+    transaction(fn: () => void): () => void;
+    exec(sql: string): void;
+    prepare(sql: string): {
+        run(...params: unknown[]): {
+            changes: number;
+        };
+        get(...params: unknown[]): Record<string, unknown> | undefined;
+        all(...params: unknown[]): Record<string, unknown>[];
+    };
+}
+export interface Edge {
+    from: string;
+    to: string;
+    weight: number;
+    relation: string;
+}
+export interface PanoramaModule {
+    name: string;
+    inferredRole: string;
+    refinedRole: string;
+    roleConfidence: number;
+    layer: number;
+    fanIn: number;
+    fanOut: number;
+    files: string[];
+    fileCount: number;
+    recipeCount: number;
+    coverageRatio: number;
+}
+export interface LayerLevel {
+    level: number;
+    name: string;
+    modules: string[];
+}
+export interface LayerViolation {
+    from: string;
+    to: string;
+    fromLayer: number;
+    toLayer: number;
+    relation: string;
+}
+export interface LayerHierarchy {
+    levels: LayerLevel[];
+    violations: LayerViolation[];
+}
+export interface CyclicDependency {
+    cycle: string[];
+    severity: 'error' | 'warning';
+}
+/**
+ * 知识维度定义 (灵感来源: ISO/IEC 25010 质量模型 + ThoughtWorks Tech Radar)
+ *
+ * 每个维度代表项目应具备知识规范的一个方向，
+ * score 反映该方向上 Recipe 的丰厚程度。
+ */
+export interface HealthDimension {
+    /** 维度 ID */
+    id: string;
+    /** 人类可读名称 */
+    name: string;
+    /** 维度说明 */
+    description: string;
+    /** 该维度匹配到的 recipe 数 */
+    recipeCount: number;
+    /** 得分 0-100 */
+    score: number;
+    /** 状态: strong(≥5) / adequate(2-4) / weak(1) / missing(0) */
+    status: 'strong' | 'adequate' | 'weak' | 'missing';
+    /** 雷达环级: adopt / trial / assess / hold */
+    level: 'adopt' | 'trial' | 'assess' | 'hold';
+    /** 该维度下 recipe 标题示例 (最多 3 个) */
+    topRecipes: string[];
+}
+/**
+ * 项目知识健康雷达图
+ */
+export interface HealthRadar {
+    /** 各维度得分 */
+    dimensions: HealthDimension[];
+    /** 综合健康分 0-100 (加权平均) */
+    overallScore: number;
+    /** 活跃 recipe 总数 */
+    totalRecipes: number;
+    /** 已覆盖维度数 (recipeCount > 0) */
+    coveredDimensions: number;
+    /** 总维度数 */
+    totalDimensions: number;
+    /** 维度覆盖率 */
+    dimensionCoverage: number;
+}
+export interface KnowledgeGap {
+    /** 空白维度 ID */
+    dimension: string;
+    /** 空白维度名称 */
+    dimensionName: string;
+    /** 该维度已有 recipe 数 */
+    recipeCount: number;
+    /** 空白状态 */
+    status: 'weak' | 'missing';
+    /** 优先级 */
+    priority: 'high' | 'medium' | 'low';
+    /** 建议补充的主题方向 */
+    suggestedTopics: string[];
+    /** 受影响的模块角色 */
+    affectedRoles: string[];
+}
+export interface CallFlowSummary {
+    topCalledMethods: Array<{
+        id: string;
+        callCount: number;
+    }>;
+    entryPoints: string[];
+    dataProducers: string[];
+    dataConsumers: string[];
+}
+export interface PanoramaResult {
+    modules: Map<string, PanoramaModule>;
+    layers: LayerHierarchy;
+    cycles: CyclicDependency[];
+    gaps: KnowledgeGap[];
+    /** 多维度知识健康雷达 */
+    healthRadar: HealthRadar;
+    callFlowSummary: CallFlowSummary;
+    /** 项目级活跃 recipe 总数（不限模块匹配） */
+    projectRecipeCount: number;
+    computedAt: number;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * PanoramaTypes — 全景服务共享类型定义
+ *
+ * @module PanoramaTypes
+ */
+export {};

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

@@ -0,0 +1,48 @@
+/**
+ * RoleRefiner — 四重信号融合角色精化
+ *
+ * 将 TargetClassifier 的正则推断 (~65% 准确率) 提升到 ≥90%，
+ * 通过融合 AST 结构、CallGraph 行为、DataFlow 数据流、EntityGraph 拓扑四重信号。
+ *
+ * 信号权重:
+ *   AST 结构        0.30   继承链/协议/import/后缀
+ *   CallGraph 行为   0.30   被调用分析/扇入扇出比/调用类型
+ *   DataFlow 数据流  0.15   源汇分析/转换检测
+ *   EntityGraph 拓扑 0.10   入度分析/模式检测
+ *   正则基线         0.15   TargetClassifier 结果
+ *
+ * @module RoleRefiner
+ */
+import type { CeDbLike } from './PanoramaTypes.js';
+export type ModuleRole = 'core' | 'service' | 'ui' | 'networking' | 'storage' | 'test' | 'app' | 'routing' | 'utility' | 'model' | 'auth' | 'config' | 'feature';
+export interface RoleSignal {
+    role: ModuleRole;
+    confidence: number;
+    weight: number;
+    source: string;
+}
+export type RoleResolution = 'clear' | 'uncertain' | 'fallback';
+export interface RefinedRole {
+    refinedRole: ModuleRole;
+    confidence: number;
+    resolution: RoleResolution;
+    alternatives?: Array<[string, number]>;
+    signals: RoleSignal[];
+}
+export interface ModuleCandidate {
+    name: string;
+    inferredRole: ModuleRole;
+    files: string[];
+}
+export declare class RoleRefiner {
+    #private;
+    constructor(db: CeDbLike, projectRoot: string);
+    /**
+     * 精化单个模块的角色
+     */
+    refineRole(module: ModuleCandidate): RefinedRole;
+    /**
+     * 批量精化所有模块
+     */
+    refineAll(modules: ModuleCandidate[]): Map<string, RefinedRole>;
+}