autosnippet 3.3.5 → 3.3.7

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

@@ -1,140 +1,26 @@
 /**
  * DimensionAnalyzer — 多维度知识健康分析
  *
+ * **v2: 从统一维度注册表 (DimensionRegistry) 派生维度**
+ *
  * 灵感来源:
  *   - 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'],
-    },
-];
+import { classifyRecipeToDimension, DIMENSION_REGISTRY, resolveActiveDimensions, } from '#domain/dimension/index.js';
 /* ═══ DimensionAnalyzer Class ═════════════════════════════ */
 export class DimensionAnalyzer {
     #db;
-    constructor(db) {
+    #projectRoot;
+    constructor(db, projectRoot) {
         this.#db = db;
+        this.#projectRoot = projectRoot;
     }
     /**
      * 分析项目知识健康雷达
@@ -142,11 +28,13 @@ export class DimensionAnalyzer {
      * @param moduleRoles — 项目中存在的模块角色 (用于 gap 优先级推断)
      */
     analyze(moduleRoles) {
+        // 0. 按项目语言过滤活跃维度（排除无关语言/框架维度）
+        const activeDims = this.#resolveActiveDims();
         // 1. 从 DB 获取所有活跃 recipe 的维度分类信息
         const recipes = this.#fetchRecipeMetadata();
         // 2. 将每条 recipe 映射到维度
         const dimensionCounts = new Map();
-        for (const def of DIMENSION_DEFS) {
+        for (const def of activeDims) {
             dimensionCounts.set(def.id, { count: 0, titles: [] });
         }
         let totalRecipes = 0;
@@ -162,16 +50,16 @@ export class DimensionAnalyzer {
             }
         }
         // 3. 计算各维度得分与状态
-        const dimensions = DIMENSION_DEFS.map((def) => {
+        const dimensions = activeDims.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;
+        for (let i = 0; i < activeDims.length; i++) {
+            weightedSum += dimensions[i].score * activeDims[i].weight;
+            weightTotal += activeDims[i].weight;
         }
         const overallScore = weightTotal > 0 ? Math.round(weightedSum / weightTotal) : 0;
         // 5. 统计覆盖
@@ -187,9 +75,26 @@ export class DimensionAnalyzer {
         };
         // 6. 生成维度空白 (gaps)
         const roleSet = new Set(moduleRoles);
-        const gaps = this.#detectDimensionGaps(dimensions, roleSet);
+        const gaps = this.#detectDimensionGaps(dimensions, activeDims, roleSet);
         return { radar, gaps };
     }
+    /* ─── 按项目语言解析活跃维度 ───────────────────── */
+    #resolveActiveDims() {
+        try {
+            const row = this.#db
+                .prepare(`SELECT primary_lang FROM bootstrap_snapshots
+           WHERE project_root = ? ORDER BY created_at DESC LIMIT 1`)
+                .get(this.#projectRoot);
+            const primaryLang = row?.primary_lang;
+            if (primaryLang) {
+                return resolveActiveDimensions(primaryLang);
+            }
+        }
+        catch {
+            // 无 bootstrap 数据 → 回退全量维度
+        }
+        return DIMENSION_REGISTRY;
+    }
     /* ─── 从 DB 获取 recipe 元数据 ─────────────────── */
     #fetchRecipeMetadata() {
         try {
@@ -213,26 +118,10 @@ export class DimensionAnalyzer {
     /**
      * 将 recipe 分类到最匹配的维度
      *
-     * 优先级: topicHint 精确匹配 → category 匹配 → null
+     * 委托给 DimensionRegistry.classifyRecipeToDimension()
      */
     #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;
+        return classifyRecipeToDimension(recipe.topicHint, recipe.category);
     }
     /* ─── 维度评分 ─────────────────────────────────── */
     #scoreDimension(def, recipeCount, titles) {
@@ -268,8 +157,8 @@ export class DimensionAnalyzer {
         }
         return {
             id: def.id,
-            name: def.name,
-            description: def.description,
+            name: def.label,
+            description: def.qualityDescription,
             recipeCount,
             score,
             status,
@@ -278,11 +167,11 @@ export class DimensionAnalyzer {
         };
     }
     /* ─── 维度空白检测 ─────────────────────────────── */
-    #detectDimensionGaps(dimensions, moduleRoles) {
+    #detectDimensionGaps(dimensions, activeDims, moduleRoles) {
         const gaps = [];
         for (let i = 0; i < dimensions.length; i++) {
             const dim = dimensions[i];
-            const def = DIMENSION_DEFS[i];
+            const def = activeDims[i];
             if (dim.status !== 'missing' && dim.status !== 'weak') {
                 continue;
             }
@@ -305,11 +194,11 @@ export class DimensionAnalyzer {
             const affectedRoles = def.relatedRoles.filter((r) => moduleRoles.has(r));
             gaps.push({
                 dimension: def.id,
-                dimensionName: def.name,
+                dimensionName: def.label,
                 recipeCount: dim.recipeCount,
                 status: dim.status,
                 priority,
-                suggestedTopics: def.suggestedTopics,
+                suggestedTopics: [...def.suggestedTopics],
                 affectedRoles,
             });
         }

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

@@ -4,9 +4,23 @@
  * 基于模块依赖图，通过去环 + 拓扑排序 + 最长路径法推断架构层级 (L0-Ln)。
  * 底层 (L0) = Foundation/Core，顶层 = App/UI。
  *
+ * 当配置文件声明了明确的层级结构时（如 Boxfile 的 layer 定义），
+ * 优先使用配置层级，仅对未覆盖的模块做拓扑推断。
+ *
  * @module LayerInferrer
  */
 import type { CyclicDependency, Edge, LayerHierarchy } from './PanoramaTypes.js';
+export interface ConfigLayer {
+    name: string;
+    order: number;
+    accessibleLayers: string[];
+}
+export interface InferOptions {
+    /** 来自配置文件的层级定义（如 Boxfile、Project.swift 等） */
+    configLayers?: ConfigLayer[] | null;
+    /** 模块 → 配置层级名映射 */
+    moduleLayerMap?: Map<string, string>;
+}
 export declare class LayerInferrer {
     #private;
     /**
@@ -14,6 +28,7 @@ export declare class LayerInferrer {
      * @param edges - 模块间依赖边 (from depends_on/calls/data_flow to)
      * @param modules - 所有模块名
      * @param cycles - 已检测到的循环依赖
+     * @param options - 可选配置：configLayers（配置声明的层级）和 moduleLayerMap（模块→层级映射）
      */
-    infer(edges: Edge[], modules: string[], cycles: CyclicDependency[]): LayerHierarchy;
+    infer(edges: Edge[], modules: string[], cycles: CyclicDependency[], options?: InferOptions): LayerHierarchy;
 }

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

@@ -4,6 +4,9 @@
  * 基于模块依赖图，通过去环 + 拓扑排序 + 最长路径法推断架构层级 (L0-Ln)。
  * 底层 (L0) = Foundation/Core，顶层 = App/UI。
  *
+ * 当配置文件声明了明确的层级结构时（如 Boxfile 的 layer 定义），
+ * 优先使用配置层级，仅对未覆盖的模块做拓扑推断。
+ *
  * @module LayerInferrer
  */
 /* ═══ Constants ═══════════════════════════════════════════ */
@@ -26,8 +29,122 @@ export class LayerInferrer {
      * @param edges - 模块间依赖边 (from depends_on/calls/data_flow to)
      * @param modules - 所有模块名
      * @param cycles - 已检测到的循环依赖
+     * @param options - 可选配置：configLayers（配置声明的层级）和 moduleLayerMap（模块→层级映射）
      */
-    infer(edges, modules, cycles) {
+    infer(edges, modules, cycles, options) {
+        // 如果有配置文件声明的层级且覆盖了大部分模块，优先使用
+        if (options?.configLayers?.length && options.moduleLayerMap?.size) {
+            const coverage = this.#computeConfigCoverage(modules, options.moduleLayerMap);
+            if (coverage >= 0.5) {
+                return this.#inferFromConfig(edges, modules, options.configLayers, options.moduleLayerMap);
+            }
+        }
+        return this.#inferFromTopology(edges, modules, cycles);
+    }
+    /* ─── Config-based layer inference ──────────────── */
+    /**
+     * 基于配置文件声明的层级直接分配
+     * 未被配置覆盖的模块附加到最近匹配的层级
+     */
+    #inferFromConfig(edges, modules, configLayers, moduleLayerMap) {
+        // 按 order 排序层级
+        const sortedLayers = [...configLayers].sort((a, b) => a.order - b.order);
+        // 构建层级名 → level 映射 (底层 = L0, 反序: order 最大的是底层)
+        // 配置中 order=0 是最高层 (如 Accessories), order=N 是最底层 (如 Vendors)
+        const maxOrder = sortedLayers.length > 0 ? sortedLayers[sortedLayers.length - 1].order : 0;
+        const layerNameToLevel = new Map();
+        for (const cl of sortedLayers) {
+            // 反转: 配置中 order 越大越底层 → level 越小
+            layerNameToLevel.set(cl.name, maxOrder - cl.order);
+        }
+        // 分配每个模块到层级
+        const moduleLevels = new Map();
+        const uncovered = [];
+        for (const mod of modules) {
+            const layerName = moduleLayerMap.get(mod);
+            if (layerName && layerNameToLevel.has(layerName)) {
+                moduleLevels.set(mod, layerNameToLevel.get(layerName));
+            }
+            else {
+                uncovered.push(mod);
+            }
+        }
+        // 未覆盖的模块: 基于依赖关系推断最可能的层级
+        for (const mod of uncovered) {
+            const depEdges = edges.filter((e) => e.from === mod);
+            let bestLevel = maxOrder + 1; // 默认最高层
+            for (const e of depEdges) {
+                const targetLevel = moduleLevels.get(e.to);
+                if (targetLevel !== undefined) {
+                    bestLevel = Math.min(bestLevel, targetLevel + 1);
+                }
+            }
+            // 如果没有依赖线索, 查看谁依赖它
+            if (bestLevel > maxOrder) {
+                const reverseEdges = edges.filter((e) => e.to === mod);
+                for (const e of reverseEdges) {
+                    const sourceLevel = moduleLevels.get(e.from);
+                    if (sourceLevel !== undefined) {
+                        bestLevel = Math.min(bestLevel, Math.max(0, sourceLevel - 1));
+                    }
+                }
+            }
+            // 兜底: 放到最高层
+            if (bestLevel > maxOrder) {
+                bestLevel = maxOrder;
+            }
+            moduleLevels.set(mod, bestLevel);
+        }
+        // 聚合: 同层模块分组
+        const layerGroups = new Map();
+        for (const [mod, level] of moduleLevels) {
+            if (!layerGroups.has(level)) {
+                layerGroups.set(level, []);
+            }
+            layerGroups.get(level).push(mod);
+        }
+        // 构建 levelEntries, 使用配置中的层级名
+        const levelToConfigName = new Map();
+        for (const cl of sortedLayers) {
+            levelToConfigName.set(maxOrder - cl.order, cl.name);
+        }
+        const sortedLevels = [...layerGroups.entries()].sort((a, b) => a[0] - b[0]);
+        const levelEntries = sortedLevels.map(([level, mods]) => ({
+            level,
+            name: levelToConfigName.get(level) ?? this.#inferLayerName(mods, level, sortedLevels.length),
+            modules: mods.sort(),
+        }));
+        // 检测层级违规（基于 access 规则）
+        const violations = [];
+        for (const edge of edges) {
+            const fromLevel = moduleLevels.get(edge.from);
+            const toLevel = moduleLevels.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 };
+    }
+    #computeConfigCoverage(modules, moduleLayerMap) {
+        if (modules.length === 0) {
+            return 0;
+        }
+        let covered = 0;
+        for (const mod of modules) {
+            if (moduleLayerMap.has(mod)) {
+                covered++;
+            }
+        }
+        return covered / modules.length;
+    }
+    /* ─── Topology-based layer inference ────────────── */
+    #inferFromTopology(edges, modules, cycles) {
         // 1. 建图 (邻接表: from → to[])
         const adjacency = new Map();
         const reverseAdj = new Map();

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

@@ -21,4 +21,13 @@ export declare class ModuleDiscoverer {
      * 若无 module 实体，返回空数组（让调用侧决定是否重新扫描）。
      */
     discover(): ModuleCandidate[];
+    /**
+     * 读取 config layers 元数据（如果存在）
+     * @returns 从 `__config_layers__` 实体中恢复的层级定义
+     */
+    readConfigLayers(): Array<{
+        name: string;
+        order: number;
+        accessibleLayers: string[];
+    }> | null;
 }

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

@@ -58,10 +58,11 @@ export class ModuleDiscoverer {
      * 若无 module 实体，返回空数组（让调用侧决定是否重新扫描）。
      */
     discover() {
-        // 从 code_entities 查 entity_type = 'module'
+        // 从 code_entities 查 entity_type = 'module'（排除 external/host 节点）
         const moduleEntities = this.#db
             .prepare(`SELECT DISTINCT entity_id, name FROM code_entities
-         WHERE entity_type = 'module' AND project_root = ?`)
+         WHERE entity_type = 'module' AND project_root = ?
+           AND COALESCE(json_extract(metadata_json, '$.nodeType'), 'local') NOT IN ('external', 'host')`)
             .all(this.#projectRoot);
         if (moduleEntities.length === 0) {
             return [];
@@ -90,13 +91,68 @@ export class ModuleDiscoverer {
         if (totalFileCount === 0) {
             this.#enrichModuleFiles(moduleFiles);
         }
+        // 读取模块 metadata 中的 configLayer 信息
+        const moduleLayerMap = this.#readModuleLayerMetadata(moduleEntities);
         return [...moduleFiles.entries()].map(([name, files]) => ({
             name,
             inferredRole: inferTargetRole(name),
             files: [...files],
+            configLayer: moduleLayerMap.get(name),
         }));
     }
+    /**
+     * 读取 config layers 元数据（如果存在）
+     * @returns 从 `__config_layers__` 实体中恢复的层级定义
+     */
+    readConfigLayers() {
+        try {
+            const row = this.#db
+                .prepare(`SELECT metadata_json FROM code_entities
+           WHERE entity_id = '__config_layers__' AND entity_type = 'config' AND project_root = ?
+           LIMIT 1`)
+                .get(this.#projectRoot);
+            if (!row?.metadata_json) {
+                return null;
+            }
+            const meta = typeof row.metadata_json === 'string' ? JSON.parse(row.metadata_json) : row.metadata_json;
+            if (Array.isArray(meta.layers) && meta.layers.length > 0) {
+                return meta.layers;
+            }
+        }
+        catch {
+            /* skip parse error */
+        }
+        return null;
+    }
     /* ─── 策略 1.5: 模块文件充填 ───────────────────── */
+    /**
+     * 从 code_entities metadata 中读取每个模块的 layer 信息
+     */
+    #readModuleLayerMetadata(moduleEntities) {
+        const result = new Map();
+        for (const me of moduleEntities) {
+            const moduleName = me.entity_id;
+            try {
+                const row = this.#db
+                    .prepare(`SELECT metadata_json FROM code_entities
+             WHERE entity_id = ? AND entity_type = 'module' AND project_root = ?
+             LIMIT 1`)
+                    .get(moduleName, this.#projectRoot);
+                if (row?.metadata_json) {
+                    const meta = typeof row.metadata_json === 'string'
+                        ? JSON.parse(row.metadata_json)
+                        : row.metadata_json;
+                    if (meta.layer && typeof meta.layer === 'string') {
+                        result.set(moduleName, meta.layer);
+                    }
+                }
+            }
+            catch {
+                /* skip parse error */
+            }
+        }
+        return result;
+    }
     /**
      * 为已知模块名填充文件路径：
      *   a. 文件系统扫描（递归 4 层找模块同名目录）

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

@@ -8,7 +8,7 @@
  */
 import type { CouplingAnalyzer } from './CouplingAnalyzer.js';
 import { DimensionAnalyzer } from './DimensionAnalyzer.js';
-import type { LayerInferrer } from './LayerInferrer.js';
+import type { ConfigLayer, LayerInferrer } from './LayerInferrer.js';
 import type { CeDbLike, PanoramaResult } from './PanoramaTypes.js';
 import type { ModuleCandidate, RoleRefiner } from './RoleRefiner.js';
 export interface PanoramaAggregatorOptions {
@@ -24,6 +24,10 @@ export declare class PanoramaAggregator {
     constructor(opts: PanoramaAggregatorOptions);
     /**
      * 计算完整全景数据
+     * @param moduleCandidates 模块候选列表
+     * @param options.configLayers 来自配置文件的层级声明（如 Boxfile layer 定义）
      */
-    compute(moduleCandidates: ModuleCandidate[]): PanoramaResult;
+    compute(moduleCandidates: ModuleCandidate[], options?: {
+        configLayers?: ConfigLayer[] | null;
+    }): PanoramaResult;
 }