autosnippet 3.2.21 → 3.3.2

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

@@ -0,0 +1,320 @@
+/**
+ * DimensionAnalyzer — 多维度知识健康分析
+ *
+ * 灵感来源:
+ *   - ISO/IEC 25010 质量模型 (8 大特性: 可靠性、安全性、可维护性…)
+ *   - ThoughtWorks Tech Radar (Adopt/Trial/Assess/Hold 四环)
+ *   - 雷达图/蛛网图可视化模型
+ *
+ * 核心思路: 不再按「模块 × 文件数」衡量覆盖，
+ * 而是按「知识维度」衡量项目在各工程方向上的规范成熟度。
+ * 某维度 Recipe 为 0 → 该方向完全空白，标示为 gap。
+ *
+ * @module DimensionAnalyzer
+ */
+/**
+ * 标准维度列表
+ *
+ * 覆盖主流软件工程关切方向，任何项目都应有所涉猎。
+ * `topics` 与 `categories` 匹配 knowledge_entries 的字段。
+ */
+const DIMENSION_DEFS = [
+    {
+        id: 'architecture',
+        name: '架构设计',
+        description: '模块结构、分层策略、依赖管理、设计模式',
+        topics: ['architecture', 'scaffold', 'workflow'],
+        categories: ['architecture', 'project-profile'],
+        weight: 1.0,
+        suggestedTopics: ['module-boundary', 'dependency-rule', 'layer-strategy'],
+        relatedRoles: ['core', 'foundation', 'app'],
+    },
+    {
+        id: 'coding-standards',
+        name: '编码规范',
+        description: '命名约定、代码风格、文档注释、import 顺序',
+        topics: ['conventions'],
+        categories: ['code-standard'],
+        weight: 0.8,
+        suggestedTopics: ['naming-convention', 'code-style', 'documentation'],
+        relatedRoles: [],
+    },
+    {
+        id: 'error-handling',
+        name: '错误处理',
+        description: '异常模式、错误恢复、输入验证、防御性编程',
+        topics: ['error-handling', 'constraints'],
+        categories: [],
+        weight: 1.0,
+        suggestedTopics: ['exception-pattern', 'error-recovery', 'input-validation'],
+        relatedRoles: ['service', 'networking', 'core'],
+    },
+    {
+        id: 'concurrency',
+        name: '并发与线程',
+        description: '线程安全、异步模式、竞态条件防护、锁策略',
+        topics: ['concurrency', 'async'],
+        categories: [],
+        weight: 0.9,
+        suggestedTopics: ['thread-safety', 'async-pattern', 'race-condition'],
+        relatedRoles: ['service', 'networking', 'storage'],
+    },
+    {
+        id: 'data-management',
+        name: '数据管理',
+        description: '持久化、缓存、序列化、数据流向完整性',
+        topics: ['data', 'data-flow', 'memory'],
+        categories: ['event-and-data-flow'],
+        weight: 0.8,
+        suggestedTopics: ['persistence', 'caching', 'serialization', 'data-integrity'],
+        relatedRoles: ['storage', 'model'],
+    },
+    {
+        id: 'networking',
+        name: '网络通信',
+        description: 'API 契约、请求模式、重试策略、实时通信',
+        topics: ['networking', 'real-time'],
+        categories: [],
+        weight: 0.7,
+        suggestedTopics: ['api-contract', 'retry-strategy', 'request-pattern'],
+        relatedRoles: ['networking'],
+    },
+    {
+        id: 'ui-patterns',
+        name: '界面模式',
+        description: 'UI 组件规范、生命周期、导航、数据绑定',
+        topics: ['ui', 'binding', 'pagination'],
+        categories: [],
+        weight: 0.7,
+        suggestedTopics: ['component-pattern', 'lifecycle', 'navigation'],
+        relatedRoles: ['ui', 'feature'],
+    },
+    {
+        id: 'testing',
+        name: '测试策略',
+        description: '测试模式、Mock 策略、CI/CD 流程',
+        topics: ['testing', 'test'],
+        categories: [],
+        weight: 0.9,
+        suggestedTopics: ['unit-test', 'mock-strategy', 'ci-cd'],
+        relatedRoles: [],
+    },
+    {
+        id: 'security',
+        name: '安全',
+        description: '认证授权、输入校验、加密、权限控制',
+        topics: ['security', 'auth'],
+        categories: [],
+        weight: 1.0,
+        suggestedTopics: ['authentication', 'authorization', 'encryption'],
+        relatedRoles: ['networking', 'service'],
+    },
+    {
+        id: 'performance',
+        name: '性能优化',
+        description: '内存管理、懒加载、缓存策略、渲染优化',
+        topics: ['performance', 'optimization'],
+        categories: [],
+        weight: 0.8,
+        suggestedTopics: ['memory-management', 'lazy-loading', 'rendering'],
+        relatedRoles: ['ui', 'storage'],
+    },
+    {
+        id: 'observability',
+        name: '可观测性',
+        description: '日志规范、事件追踪、监控诊断',
+        topics: ['logging', 'event', 'monitoring'],
+        categories: [],
+        weight: 0.7,
+        suggestedTopics: ['logging-standard', 'event-tracking', 'diagnostics'],
+        relatedRoles: ['service', 'core'],
+    },
+];
+/* ═══ DimensionAnalyzer Class ═════════════════════════════ */
+export class DimensionAnalyzer {
+    #db;
+    constructor(db) {
+        this.#db = db;
+    }
+    /**
+     * 分析项目知识健康雷达
+     *
+     * @param moduleRoles — 项目中存在的模块角色 (用于 gap 优先级推断)
+     */
+    analyze(moduleRoles) {
+        // 1. 从 DB 获取所有活跃 recipe 的维度分类信息
+        const recipes = this.#fetchRecipeMetadata();
+        // 2. 将每条 recipe 映射到维度
+        const dimensionCounts = new Map();
+        for (const def of DIMENSION_DEFS) {
+            dimensionCounts.set(def.id, { count: 0, titles: [] });
+        }
+        let totalRecipes = 0;
+        for (const recipe of recipes) {
+            totalRecipes++;
+            const dimId = this.#classifyRecipe(recipe);
+            if (dimId) {
+                const entry = dimensionCounts.get(dimId);
+                entry.count++;
+                if (entry.titles.length < 3) {
+                    entry.titles.push(recipe.title);
+                }
+            }
+        }
+        // 3. 计算各维度得分与状态
+        const dimensions = DIMENSION_DEFS.map((def) => {
+            const entry = dimensionCounts.get(def.id);
+            return this.#scoreDimension(def, entry.count, entry.titles);
+        });
+        // 4. 加权平均健康分
+        let weightedSum = 0;
+        let weightTotal = 0;
+        for (let i = 0; i < DIMENSION_DEFS.length; i++) {
+            weightedSum += dimensions[i].score * DIMENSION_DEFS[i].weight;
+            weightTotal += DIMENSION_DEFS[i].weight;
+        }
+        const overallScore = weightTotal > 0 ? Math.round(weightedSum / weightTotal) : 0;
+        // 5. 统计覆盖
+        const coveredDimensions = dimensions.filter((d) => d.recipeCount > 0).length;
+        const totalDimensions = dimensions.length;
+        const radar = {
+            dimensions,
+            overallScore,
+            totalRecipes,
+            coveredDimensions,
+            totalDimensions,
+            dimensionCoverage: totalDimensions > 0 ? coveredDimensions / totalDimensions : 0,
+        };
+        // 6. 生成维度空白 (gaps)
+        const roleSet = new Set(moduleRoles);
+        const gaps = this.#detectDimensionGaps(dimensions, roleSet);
+        return { radar, gaps };
+    }
+    /* ─── 从 DB 获取 recipe 元数据 ─────────────────── */
+    #fetchRecipeMetadata() {
+        try {
+            const rows = this.#db
+                .prepare(`SELECT title, category, topicHint, kind
+           FROM knowledge_entries
+           WHERE lifecycle IN ('active', 'pending')`)
+                .all();
+            return rows.map((r) => ({
+                title: String(r.title ?? ''),
+                category: String(r.category ?? ''),
+                topicHint: String(r.topicHint ?? ''),
+                kind: String(r.kind ?? ''),
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    /* ─── Recipe → 维度分类 ────────────────────────── */
+    /**
+     * 将 recipe 分类到最匹配的维度
+     *
+     * 优先级: topicHint 精确匹配 → category 匹配 → null
+     */
+    #classifyRecipe(recipe) {
+        // 1. topicHint 精确匹配
+        if (recipe.topicHint) {
+            for (const def of DIMENSION_DEFS) {
+                if (def.topics.includes(recipe.topicHint)) {
+                    return def.id;
+                }
+            }
+        }
+        // 2. category 匹配
+        if (recipe.category) {
+            for (const def of DIMENSION_DEFS) {
+                if (def.categories.includes(recipe.category)) {
+                    return def.id;
+                }
+            }
+        }
+        return null;
+    }
+    /* ─── 维度评分 ─────────────────────────────────── */
+    #scoreDimension(def, recipeCount, titles) {
+        // 得分: 每条 recipe 贡献 20 分, 上限 100
+        const score = Math.min(100, recipeCount * 20);
+        // 状态阈值
+        let status;
+        if (recipeCount === 0) {
+            status = 'missing';
+        }
+        else if (recipeCount === 1) {
+            status = 'weak';
+        }
+        else if (recipeCount <= 4) {
+            status = 'adequate';
+        }
+        else {
+            status = 'strong';
+        }
+        // 雷达环级 (对应 Tech Radar)
+        let level;
+        if (score >= 80) {
+            level = 'adopt';
+        }
+        else if (score >= 40) {
+            level = 'trial';
+        }
+        else if (score > 0) {
+            level = 'assess';
+        }
+        else {
+            level = 'hold';
+        }
+        return {
+            id: def.id,
+            name: def.name,
+            description: def.description,
+            recipeCount,
+            score,
+            status,
+            level,
+            topRecipes: titles,
+        };
+    }
+    /* ─── 维度空白检测 ─────────────────────────────── */
+    #detectDimensionGaps(dimensions, moduleRoles) {
+        const gaps = [];
+        for (let i = 0; i < dimensions.length; i++) {
+            const dim = dimensions[i];
+            const def = DIMENSION_DEFS[i];
+            if (dim.status !== 'missing' && dim.status !== 'weak') {
+                continue;
+            }
+            // 优先级推断: 维度权重 × 是否有关联模块角色
+            const hasRelatedModules = def.relatedRoles.length === 0 || def.relatedRoles.some((r) => moduleRoles.has(r));
+            let priority;
+            if (dim.status === 'missing' && def.weight >= 0.9) {
+                priority = 'high';
+            }
+            else if (dim.status === 'missing' && hasRelatedModules) {
+                priority = 'high';
+            }
+            else if (dim.status === 'missing') {
+                priority = 'medium';
+            }
+            else {
+                // weak
+                priority = hasRelatedModules && def.weight >= 0.9 ? 'medium' : 'low';
+            }
+            const affectedRoles = def.relatedRoles.filter((r) => moduleRoles.has(r));
+            gaps.push({
+                dimension: def.id,
+                dimensionName: def.name,
+                recipeCount: dim.recipeCount,
+                status: dim.status,
+                priority,
+                suggestedTopics: def.suggestedTopics,
+                affectedRoles,
+            });
+        }
+        // 按优先级排序
+        const priorityOrder = { high: 0, medium: 1, low: 2 };
+        return gaps.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+    }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * LayerInferrer — 拓扑排序层级推断
+ *
+ * 基于模块依赖图，通过去环 + 拓扑排序 + 最长路径法推断架构层级 (L0-Ln)。
+ * 底层 (L0) = Foundation/Core，顶层 = App/UI。
+ *
+ * @module LayerInferrer
+ */
+import type { CyclicDependency, Edge, LayerHierarchy } from './PanoramaTypes.js';
+export declare class LayerInferrer {
+    #private;
+    /**
+     * 从模块依赖边推断架构层级
+     * @param edges - 模块间依赖边 (from depends_on/calls/data_flow to)
+     * @param modules - 所有模块名
+     * @param cycles - 已检测到的循环依赖
+     */
+    infer(edges: Edge[], modules: string[], cycles: CyclicDependency[]): LayerHierarchy;
+}

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

@@ -0,0 +1,182 @@
+/**
+ * LayerInferrer — 拓扑排序层级推断
+ *
+ * 基于模块依赖图，通过去环 + 拓扑排序 + 最长路径法推断架构层级 (L0-Ln)。
+ * 底层 (L0) = Foundation/Core，顶层 = App/UI。
+ *
+ * @module LayerInferrer
+ */
+/* ═══ Constants ═══════════════════════════════════════════ */
+/** 层级命名启发式 — 按优先级排列，匹配模块名（边界安全） */
+const LAYER_NAME_HINTS = [
+    { pattern: /^(foundation|core|base|shared|common)$/i, name: 'Foundation', bias: -2 },
+    { pattern: /foundation/i, name: 'Foundation', bias: -2 },
+    { pattern: /^(model|entity|dto)$/i, name: 'Model', bias: -1 },
+    { pattern: /service|repository|manager|provider|store/i, name: 'Service', bias: 0 },
+    { pattern: /network|api|http/i, name: 'Networking', bias: 0 },
+    { pattern: /(?:^ui$|^ui[A-Z]|view|screen|component|widget)/i, name: 'UI', bias: 1 },
+    { pattern: /router|coordinator|navigation/i, name: 'Routing', bias: 1 },
+    { pattern: /^(app|main|launch|entry)$/i, name: 'Application', bias: 2 },
+    { pattern: /test|spec|mock/i, name: 'Test', bias: 3 },
+];
+/* ═══ LayerInferrer Class ═════════════════════════════════ */
+export class LayerInferrer {
+    /**
+     * 从模块依赖边推断架构层级
+     * @param edges - 模块间依赖边 (from depends_on/calls/data_flow to)
+     * @param modules - 所有模块名
+     * @param cycles - 已检测到的循环依赖
+     */
+    infer(edges, modules, cycles) {
+        // 1. 建图 (邻接表: from → to[])
+        const adjacency = new Map();
+        const reverseAdj = new Map();
+        const allModules = new Set(modules);
+        for (const mod of allModules) {
+            adjacency.set(mod, new Set());
+            reverseAdj.set(mod, new Set());
+        }
+        // 收集环中的节点
+        const cycleEdges = new Set();
+        for (const c of cycles) {
+            for (let i = 0; i < c.cycle.length; i++) {
+                const from = c.cycle[i];
+                const to = c.cycle[(i + 1) % c.cycle.length];
+                cycleEdges.add(`${from}→${to}`);
+            }
+        }
+        // 2. 添加边 (跳过环边)
+        const violations = [];
+        for (const edge of edges) {
+            if (!allModules.has(edge.from) || !allModules.has(edge.to) || edge.from === edge.to) {
+                continue;
+            }
+            const edgeKey = `${edge.from}→${edge.to}`;
+            if (cycleEdges.has(edgeKey)) {
+                // 环边作为违规记录，不加入 DAG
+                continue;
+            }
+            adjacency.get(edge.from).add(edge.to);
+            reverseAdj.get(edge.to).add(edge.from);
+        }
+        // 3. 拓扑排序 (Kahn's algorithm)
+        const inDegree = new Map();
+        for (const mod of allModules) {
+            inDegree.set(mod, reverseAdj.get(mod)?.size ?? 0);
+        }
+        const queue = [];
+        for (const [mod, deg] of inDegree) {
+            if (deg === 0) {
+                queue.push(mod);
+            }
+        }
+        const order = [];
+        while (queue.length > 0) {
+            const node = queue.shift();
+            order.push(node);
+            for (const neighbor of adjacency.get(node) ?? []) {
+                const newDeg = (inDegree.get(neighbor) ?? 1) - 1;
+                inDegree.set(neighbor, newDeg);
+                if (newDeg === 0) {
+                    queue.push(neighbor);
+                }
+            }
+        }
+        // 未排入的节点 (仍在环中) 追加到末尾
+        for (const mod of allModules) {
+            if (!order.includes(mod)) {
+                order.push(mod);
+            }
+        }
+        // 4. 分配层级: 最长路径法
+        // A 依赖 B → A 的 level ≥ B 的 level + 1
+        // reverseAdj: "B 被 A 依赖" → predecessors 是 reverseAdj(node) = {A}
+        // 但我们要的是 "A 依赖 B" → A 的 predecessors = adjacency(A) 出度目标的 level
+        // 换言之: level(A) = max(level(dep) for dep in adjacency(A)) + 1
+        // 底层 (无出度) = L0
+        const levels = new Map();
+        // 反向遍历: 从源头 (无出度) 开始
+        const reverseOrder = [...order].reverse();
+        for (const node of reverseOrder) {
+            const deps = adjacency.get(node) ?? new Set();
+            if (deps.size === 0) {
+                levels.set(node, 0);
+            }
+            else {
+                let maxDepLevel = 0;
+                for (const dep of deps) {
+                    maxDepLevel = Math.max(maxDepLevel, levels.get(dep) ?? 0);
+                }
+                levels.set(node, maxDepLevel + 1);
+            }
+        }
+        // 5. 聚合: 同层模块分组
+        const layerGroups = new Map();
+        for (const [mod, level] of levels) {
+            if (!layerGroups.has(level)) {
+                layerGroups.set(level, []);
+            }
+            layerGroups.get(level).push(mod);
+        }
+        // 按 level 排序
+        const sortedLevels = [...layerGroups.entries()].sort((a, b) => a[0] - b[0]);
+        // 6. 推断层级名
+        const levelEntries = sortedLevels.map(([level, mods]) => ({
+            level,
+            name: this.#inferLayerName(mods, level, sortedLevels.length),
+            modules: mods.sort(),
+        }));
+        // 7. 检测层级违规 (高层 → 低层调用正常；低层 → 高层调用为违规)
+        for (const edge of edges) {
+            const fromLevel = levels.get(edge.from);
+            const toLevel = levels.get(edge.to);
+            if (fromLevel !== undefined && toLevel !== undefined && fromLevel < toLevel) {
+                violations.push({
+                    from: edge.from,
+                    to: edge.to,
+                    fromLayer: fromLevel,
+                    toLayer: toLevel,
+                    relation: edge.relation,
+                });
+            }
+        }
+        return { levels: levelEntries, violations };
+    }
+    /* ─── Layer Naming ──────────────────────────────── */
+    #inferLayerName(modules, level, totalLevels) {
+        // 投票: 每个匹配的 hint 累加权重，取最高分的名称
+        const votes = new Map();
+        for (const mod of modules) {
+            for (const hint of LAYER_NAME_HINTS) {
+                if (hint.pattern.test(mod)) {
+                    votes.set(hint.name, (votes.get(hint.name) ?? 0) + 1);
+                    break; // 每个模块只投一票（匹配第一个 hint）
+                }
+            }
+        }
+        if (votes.size > 0) {
+            // 选最高票
+            let best = '';
+            let bestCount = 0;
+            for (const [name, count] of votes) {
+                if (count > bestCount) {
+                    best = name;
+                    bestCount = count;
+                }
+            }
+            return best;
+        }
+        // 基于层级位置推断
+        const position = totalLevels > 1 ? level / (totalLevels - 1) : 0.5;
+        if (position <= 0.2) {
+            return 'Foundation';
+        }
+        if (position <= 0.5) {
+            return 'Service';
+        }
+        if (position <= 0.8) {
+            return 'Feature';
+        }
+        return 'Application';
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * ModuleDiscoverer — 模块发现与文件归属
+ *
+ * 从 DB（code_entities / knowledge_edges）读取已扫描的模块数据。
+ * 前提：PanoramaScanner.ensureData() 保证 DB 中已有结构数据。
+ *
+ *   策略 1:   code_entities entity_type='module' + is_part_of 边 → 完整数据
+ *   策略 1.5: module 实体存在但无 is_part_of 边 → 文件系统 + DB 路径补全
+ *
+ * 若 DB 中无 module 实体，返回空数组（由 PanoramaScanner 负责兜底扫描）。
+ *
+ * @module ModuleDiscoverer
+ */
+import type { CeDbLike } from './PanoramaTypes.js';
+import type { ModuleCandidate } from './RoleRefiner.js';
+export declare class ModuleDiscoverer {
+    #private;
+    constructor(db: CeDbLike, projectRoot: string);
+    /**
+     * 从 DB 中读取已扫描的模块数据。
+     * 若无 module 实体，返回空数组（让调用侧决定是否重新扫描）。
+     */
+    discover(): ModuleCandidate[];
+}