autosnippet 3.2.21 → 3.3.2

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

@@ -0,0 +1,108 @@
+/**
+ * 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;
+    }>;
+}
+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;
+    /**
+     * 获取单模块详情
+     */
+    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>;
+}

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

@@ -0,0 +1,220 @@
+/**
+ * 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;
+    }
+    /**
+     * 获取单模块详情
+     */
+    getModule(moduleName) {
+        const result = this.#getOrCompute();
+        const mod = result.modules.get(moduleName);
+        if (!mod) {
+            return null;
+        }
+        // 找到该模块所在层级
+        const layerName = result.layers.levels.find((l) => l.modules.includes(moduleName))?.name ?? 'Unknown';
+        // 从 DB 查邻居边
+        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),
+            });
+        }
+        return { module: mod, layerName, neighbors };
+    }
+    /**
+     * 获取知识空白区
+     */
+    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>;
+}