autosnippet 3.2.9 → 3.2.11

package/dist/lib/service/knowledge/CodeEntityGraph.js

@@ -0,0 +1,1050 @@
+/**
+ * CodeEntityGraph — 代码实体关系图谱
+ *
+ * Phase E: 在 Semantic Memory 之上构建代码实体图谱
+ *
+ * 节点类型:
+ *   - class      : ObjC @interface / Swift class/struct
+ *   - protocol   : ObjC @protocol / Swift protocol
+ *   - category   : ObjC Category / Swift Extension
+ *   - module     : SPM/CocoaPods module
+ *   - pattern    : 设计模式 (singleton, delegate, etc.)
+ *
+ * 边类型 (复用 knowledge_edges 表):
+ *   - inherits    : 类继承
+ *   - conforms    : 协议遵循
+ *   - extends     : Category/Extension
+ *   - depends_on  : 模块依赖
+ *   - uses_pattern: 使用设计模式
+ *   - is_part_of  : 属于模块
+ *   - calls       : 方法调用 (Phase 5)
+ *   - data_flow   : 数据流向 (Phase 5)
+ *
+ * @module CodeEntityGraph
+ */
+import Logger from '../../infrastructure/logging/Logger.js';
+const logger = Logger.getInstance();
+/**
+ * @typedef {Object} CodeEntity
+ * @property {string} entityId   唯一标识 (通常 = name)
+ * @property {string} entityType - 'class'|'protocol'|'category'|'module'|'pattern'
+ * @property {string} name       显示名
+ * @property {string} [filePath] 源文件路径
+ * @property {number} [line]     起始行号
+ * @property {string} [superclass] 父类
+ * @property {string[]} [protocols] 遵循的协议列表
+ * @property {object} [metadata] 额外信息
+ */
+/**
+ * @typedef {Object} EntityEdge
+ * @property {string} fromId
+ * @property {string} fromType
+ * @property {string} toId
+ * @property {string} toType
+ * @property {string} relation
+ * @property {number} [weight]
+ * @property {object} [metadata]
+ */
+/**
+ * @typedef {Object} GraphPopulateResult
+ * @property {number} entitiesUpserted  插入/更新的实体数
+ * @property {number} edgesCreated      创建的边数
+ * @property {number} durationMs        耗时
+ */
+export class CodeEntityGraph {
+    projectRoot;
+    db;
+    log;
+    stmts;
+    /**
+     * @param {import('better-sqlite3').Database} db
+     * @param {object} [options]
+     * @param {string} [options.projectRoot]
+     * @param {import('winston').Logger} [options.logger]
+     */
+    constructor(db, options = {}) {
+        this.db = typeof db?.getDb === 'function' ? db.getDb() : db;
+        this.projectRoot = options.projectRoot || '';
+        this.log = options.logger || logger;
+        this.#ensureTable();
+        this.#prepareStatements();
+    }
+    // ────────────────────────────────────────────
+    // Public API — 图谱构建
+    // ────────────────────────────────────────────
+    /**
+     * 从 AST ProjectAstSummary 填充图谱 (Phase 1.5 → Phase 1.6)
+     *
+     * 写入: class/protocol/category 实体 + inherits/conforms/extends 边
+     *
+     * @param {object} astSummary - analyzeProject() 产出的 ProjectAstSummary
+     * @returns {GraphPopulateResult}
+     */
+    populateFromAst(astSummary) {
+        if (!astSummary) {
+            return { entitiesUpserted: 0, edgesCreated: 0, durationMs: 0 };
+        }
+        const t0 = Date.now();
+        let entities = 0;
+        let edges = 0;
+        const run = this.db.transaction(() => {
+            // ── 类 ──
+            for (const cls of astSummary.classes || []) {
+                this.#upsertEntity({
+                    entityId: cls.name,
+                    entityType: cls.isCategory ? 'category' : 'class',
+                    name: cls.name,
+                    filePath: cls.file || null,
+                    line: cls.line || null,
+                    superclass: cls.superclass || null,
+                    protocols: cls.protocols || [],
+                    metadata: {
+                        endLine: cls.endLine,
+                        isCategory: cls.isCategory || false,
+                    },
+                });
+                entities++;
+            }
+            // ── 协议 ──
+            for (const proto of astSummary.protocols || []) {
+                this.#upsertEntity({
+                    entityId: proto.name,
+                    entityType: 'protocol',
+                    name: proto.name,
+                    filePath: proto.file || null,
+                    line: proto.line || null,
+                    protocols: proto.inherits || [],
+                    metadata: {
+                        methodCount: proto.methods?.length || 0,
+                    },
+                });
+                entities++;
+            }
+            // ── Category ──
+            for (const cat of astSummary.categories || []) {
+                const catId = `${cat.className}(${cat.categoryName})`;
+                this.#upsertEntity({
+                    entityId: catId,
+                    entityType: 'category',
+                    name: catId,
+                    filePath: cat.file || null,
+                    line: cat.line || null,
+                    protocols: cat.protocols || [],
+                    metadata: {
+                        className: cat.className,
+                        categoryName: cat.categoryName,
+                        methodCount: cat.methods?.length || 0,
+                    },
+                });
+                entities++;
+            }
+            // ── 继承/遵循/扩展 边 (从 AST inheritanceGraph) ──
+            for (const edge of astSummary.inheritanceGraph || []) {
+                const fromType = this.#inferEntityType(edge.from, astSummary);
+                const toType = this.#inferEntityType(edge.to, astSummary);
+                this.#addEdge(edge.from, fromType, edge.to, toType, edge.type, {
+                    weight: 1.0,
+                    source: 'ast-bootstrap',
+                });
+                edges++;
+            }
+            // ── 设计模式 (从 patternStats) ──
+            for (const [patternType, stat] of Object.entries(astSummary.patternStats || {})) {
+                const patternId = `pattern:${patternType}`;
+                this.#upsertEntity({
+                    entityId: patternId,
+                    entityType: 'pattern',
+                    name: patternType,
+                    metadata: {
+                        count: stat.count,
+                        files: stat.files?.slice(0, 10),
+                    },
+                });
+                entities++;
+                // 实例 → uses_pattern 边
+                for (const inst of (stat.instances || []).slice(0, 50)) {
+                    const className = inst.className || inst.name;
+                    if (className) {
+                        this.#addEdge(className, 'class', patternId, 'pattern', 'uses_pattern', {
+                            weight: 0.8,
+                            source: 'ast-pattern-detection',
+                            file: inst.file,
+                        });
+                        edges++;
+                    }
+                }
+            }
+        });
+        run();
+        const result = { entitiesUpserted: entities, edgesCreated: edges, durationMs: Date.now() - t0 };
+        this.log.info(`[CodeEntityGraph] AST populate: ${entities} entities, ${edges} edges (${result.durationMs}ms)`);
+        return result;
+    }
+    /**
+     * 从 SPM 依赖图填充模块实体 (Phase 2)
+     *
+     * 当前 bootstrap.js 已将 SPM 边写入 knowledge_edges，
+     * 此方法补充 module 实体节点。
+     *
+     * @param {object} depGraphData - spm.getDependencyGraph() 产出
+     * @returns {GraphPopulateResult}
+     */
+    populateFromSpm(depGraphData) {
+        if (!depGraphData) {
+            return { entitiesUpserted: 0, edgesCreated: 0, durationMs: 0 };
+        }
+        const t0 = Date.now();
+        let entities = 0;
+        const run = this.db.transaction(() => {
+            for (const node of depGraphData.nodes || []) {
+                const nodeObj = typeof node === 'string' ? { id: node, label: node } : node;
+                this.#upsertEntity({
+                    entityId: nodeObj.id || nodeObj.label || String(node),
+                    entityType: 'module',
+                    name: nodeObj.label || nodeObj.id || String(node),
+                    metadata: {
+                        nodeType: nodeObj.type || 'module',
+                    },
+                });
+                entities++;
+            }
+        });
+        run();
+        const result = { entitiesUpserted: entities, edgesCreated: 0, durationMs: Date.now() - t0 };
+        this.log.info(`[CodeEntityGraph] SPM populate: ${entities} module entities (${result.durationMs}ms)`);
+        return result;
+    }
+    /**
+     * 从候选的 Relations 字段提取边写入图谱 (Phase 5/6)
+     *
+     * @param {Array<{title: string, relations: object}>} candidates 扁平关系数组或 Relations 对象
+     * @returns {GraphPopulateResult}
+     */
+    populateFromCandidateRelations(candidates) {
+        if (!candidates?.length) {
+            return { entitiesUpserted: 0, edgesCreated: 0, durationMs: 0 };
+        }
+        const t0 = Date.now();
+        let edges = 0;
+        const run = this.db.transaction(() => {
+            for (const candidate of candidates) {
+                const title = candidate.title || candidate.id || '';
+                if (!title) {
+                    continue;
+                }
+                // 处理 Relations 对象或扁平数组
+                let flatRelations;
+                const rels = candidate.relations;
+                if (typeof rels?.toFlatArray === 'function') {
+                    flatRelations = rels.toFlatArray();
+                }
+                else if (Array.isArray(candidate.relations)) {
+                    flatRelations = candidate.relations;
+                }
+                else if (candidate.relations && typeof candidate.relations === 'object') {
+                    // 桶结构 → 扁平
+                    flatRelations = [];
+                    for (const [type, list] of Object.entries(candidate.relations)) {
+                        for (const r of Array.isArray(list) ? list : []) {
+                            flatRelations.push({ type, target: r.target, description: r.description });
+                        }
+                    }
+                }
+                else {
+                    continue;
+                }
+                for (const rel of flatRelations) {
+                    if (!rel.target) {
+                        continue;
+                    }
+                    // 映射关系类型到边类型
+                    const relation = this.#mapRelationType(rel.type);
+                    this.#addEdge(title, 'recipe', rel.target, 'recipe', relation, {
+                        weight: 0.7,
+                        source: 'candidate-relations',
+                        description: rel.description || '',
+                    });
+                    edges++;
+                }
+            }
+        });
+        run();
+        const result = { entitiesUpserted: 0, edgesCreated: edges, durationMs: Date.now() - t0 };
+        this.log.info(`[CodeEntityGraph] Candidate relations: ${edges} edges (${result.durationMs}ms)`);
+        return result;
+    }
+    // ────────────────────────────────────────────
+    // Public API — 图谱查询
+    // ────────────────────────────────────────────
+    /**
+     * 获取单个实体信息
+     * @param {string} entityId
+     * @param {string} [entityType]
+     * @returns {CodeEntity|null}
+     */
+    getEntity(entityId, entityType) {
+        let row;
+        if (entityType) {
+            row = this.stmts.getEntity.get(entityId, entityType, this.projectRoot);
+        }
+        else {
+            row = this.db
+                .prepare(`SELECT * FROM code_entities WHERE entity_id = ? AND project_root = ? LIMIT 1`)
+                .get(entityId, this.projectRoot);
+        }
+        return row ? this.#mapEntity(row) : null;
+    }
+    /**
+     * 按类型列出所有实体
+     * @param {string} entityType - 'class'|'protocol'|'category'|'module'|'pattern'
+     * @param {number} [limit=200]
+     * @returns {CodeEntity[]}
+     */
+    listEntities(entityType, limit = 200) {
+        const rows = this.stmts.listByType.all(entityType, this.projectRoot, limit);
+        return rows.map((r) => this.#mapEntity(r));
+    }
+    /**
+     * 搜索实体 (名称模糊匹配)
+     * @param {string} query
+     * @param {object} [options]
+     * @param {string} [options.type] 过滤类型
+     * @param {number} [options.limit=20]
+     * @returns {CodeEntity[]}
+     */
+    searchEntities(query, options = {}) {
+        const pattern = `%${query}%`;
+        let sql = `SELECT * FROM code_entities WHERE project_root = ? AND name LIKE ?`;
+        const params = [this.projectRoot, pattern];
+        if (options.type) {
+            sql += ` AND entity_type = ?`;
+            params.push(options.type);
+        }
+        sql += ` ORDER BY name LIMIT ?`;
+        params.push(options.limit || 20);
+        return this.db
+            .prepare(sql)
+            .all(...params)
+            .map((r) => this.#mapEntity(r));
+    }
+    /**
+     * 获取实体的所有关系边
+     * @param {string} entityId
+     * @param {string} entityType
+     * @param {'both'|'out'|'in'} [direction='both']
+     * @returns {{ outgoing: EntityEdge[], incoming: EntityEdge[] }}
+     */
+    getEntityEdges(entityId, entityType, direction = 'both') {
+        const outgoing = direction === 'both' || direction === 'out'
+            ? this.db
+                .prepare(`SELECT * FROM knowledge_edges WHERE from_id = ? AND from_type = ?`)
+                .all(entityId, entityType)
+                .map((row) => this.#mapEdge(row))
+            : [];
+        const incoming = direction === 'both' || direction === 'in'
+            ? this.db
+                .prepare(`SELECT * FROM knowledge_edges WHERE to_id = ? AND to_type = ?`)
+                .all(entityId, entityType)
+                .map((row) => this.#mapEdge(row))
+            : [];
+        return { outgoing, incoming };
+    }
+    /**
+     * 获取继承链 (向上遍历 inherits 边)
+     * @param {string} className
+     * @param {number} [maxDepth=10]
+     * @returns {string[]} 继承链 [class, parent, grandparent, ...]
+     */
+    getInheritanceChain(className, maxDepth = 10) {
+        const chain = [className];
+        let current = className;
+        for (let i = 0; i < maxDepth; i++) {
+            const parent = this.db
+                .prepare(`SELECT to_id FROM knowledge_edges 
+         WHERE from_id = ? AND from_type = 'class' AND relation = 'inherits' LIMIT 1`)
+                .get(current);
+            if (!parent) {
+                break;
+            }
+            chain.push(parent.to_id);
+            current = parent.to_id;
+        }
+        return chain;
+    }
+    /**
+     * 获取所有子类/实现者 (向下遍历)
+     * @param {string} entityId
+     * @param {string} entityType - 'class'|'protocol'
+     * @param {number} [maxDepth=3]
+     * @returns {Array<{ id: string, type: string, depth: number, relation: string }>}
+     */
+    getDescendants(entityId, entityType, maxDepth = 3) {
+        const results = [];
+        const visited = new Set();
+        const queue = [{ id: entityId, type: entityType, depth: 0 }];
+        // 类的子类/Category + 协议的遵循者
+        const relations = entityType === 'protocol' ? ['conforms', 'inherits'] : ['inherits', 'extends'];
+        while (queue.length > 0) {
+            const { id, type, depth } = queue.shift();
+            if (depth >= maxDepth) {
+                continue;
+            }
+            const key = `${type}:${id}`;
+            if (visited.has(key)) {
+                continue;
+            }
+            visited.add(key);
+            for (const rel of relations) {
+                const children = this.db
+                    .prepare(`SELECT from_id, from_type FROM knowledge_edges 
+           WHERE to_id = ? AND to_type = ? AND relation = ?`)
+                    .all(id, type, rel);
+                for (const child of children) {
+                    const childKey = `${child.from_type}:${child.from_id}`;
+                    if (!visited.has(childKey)) {
+                        results.push({
+                            id: child.from_id,
+                            type: child.from_type,
+                            depth: depth + 1,
+                            relation: rel,
+                        });
+                        queue.push({
+                            id: child.from_id,
+                            type: child.from_type,
+                            depth: depth + 1,
+                        });
+                    }
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * 获取协议遵循关系 (className → 遵循的协议列表)
+     * @param {string} className
+     * @returns {string[]}
+     */
+    getConformances(className) {
+        const rows = this.db
+            .prepare(`SELECT to_id FROM knowledge_edges 
+       WHERE from_id = ? AND from_type IN ('class', 'category') AND relation = 'conforms'`)
+            .all(className);
+        return rows.map((r) => r.to_id);
+    }
+    /**
+     * 查找两个实体间的路径 (BFS)
+     * @param {string} fromId
+     * @param {string} fromType
+     * @param {string} toId
+     * @param {string} toType
+     * @param {number} [maxDepth=5]
+     * @returns {{ found: boolean, path: EntityEdge[], depth: number }}
+     */
+    findPath(fromId, fromType, toId, toType, maxDepth = 5) {
+        const visited = new Set();
+        const queue = [
+            {
+                id: fromId,
+                type: fromType,
+                path: [],
+            },
+        ];
+        while (queue.length > 0) {
+            const { id, type, path } = queue.shift();
+            if (path.length >= maxDepth) {
+                continue;
+            }
+            const key = `${type}:${id}`;
+            if (visited.has(key)) {
+                continue;
+            }
+            visited.add(key);
+            const neighbors = this.db
+                .prepare(`SELECT to_id, to_type, relation, weight FROM knowledge_edges WHERE from_id = ? AND from_type = ?`)
+                .all(id, type);
+            for (const n of neighbors) {
+                const step = {
+                    from: { id, type },
+                    to: { id: n.to_id, type: n.to_type },
+                    relation: n.relation,
+                };
+                const newPath = [...path, step];
+                if (n.to_id === toId && n.to_type === toType) {
+                    return { found: true, path: newPath, depth: newPath.length };
+                }
+                queue.push({ id: n.to_id, type: n.to_type, path: newPath });
+            }
+        }
+        return {
+            found: false,
+            path: [],
+            depth: -1,
+        };
+    }
+    /**
+     * 影响分析: 修改某实体后，哪些实体可能受影响
+     * @param {string} entityId
+     * @param {string} entityType
+     * @param {number} [maxDepth=3]
+     * @returns {Array<{ id: string, type: string, relation: string, depth: number }>}
+     */
+    getImpactRadius(entityId, entityType, maxDepth = 3) {
+        const impacted = [];
+        const visited = new Set();
+        const queue = [{ id: entityId, type: entityType, depth: 0 }];
+        while (queue.length > 0) {
+            const { id, type, depth } = queue.shift();
+            if (depth >= maxDepth) {
+                continue;
+            }
+            const key = `${type}:${id}`;
+            if (visited.has(key)) {
+                continue;
+            }
+            visited.add(key);
+            // 找出所有"依赖/引用此实体"的上游
+            const dependents = this.db
+                .prepare(`SELECT from_id, from_type, relation FROM knowledge_edges 
+         WHERE to_id = ? AND to_type = ?`)
+                .all(id, type);
+            for (const dep of dependents) {
+                const depKey = `${dep.from_type}:${dep.from_id}`;
+                if (!visited.has(depKey)) {
+                    impacted.push({
+                        id: dep.from_id,
+                        type: dep.from_type,
+                        relation: dep.relation,
+                        depth: depth + 1,
+                    });
+                    queue.push({
+                        id: dep.from_id,
+                        type: dep.from_type,
+                        depth: depth + 1,
+                    });
+                }
+            }
+        }
+        return impacted;
+    }
+    /**
+     * 项目拓扑概览 — 统计信息 + 关键度排名
+     * @returns {object}
+     */
+    getTopology() {
+        const entityStats = this.db
+            .prepare(`SELECT entity_type, COUNT(*) as count FROM code_entities 
+       WHERE project_root = ? GROUP BY entity_type`)
+            .all(this.projectRoot);
+        const edgeStats = this.db
+            .prepare(`SELECT relation, COUNT(*) as count FROM knowledge_edges GROUP BY relation`)
+            .all();
+        // 入度最高的实体 = 被依赖最多
+        const hotNodes = this.db
+            .prepare(`SELECT to_id, to_type, COUNT(*) as in_degree 
+       FROM knowledge_edges 
+       GROUP BY to_id, to_type 
+       ORDER BY in_degree DESC LIMIT 15`)
+            .all();
+        return {
+            entities: Object.fromEntries(entityStats.map((s) => [
+                s.entity_type,
+                s.count,
+            ])),
+            edges: Object.fromEntries(edgeStats.map((s) => [
+                s.relation,
+                s.count,
+            ])),
+            totalEntities: entityStats.reduce((sum, s) => sum + (s.count || 0), 0),
+            totalEdges: edgeStats.reduce((sum, s) => sum + (s.count || 0), 0),
+            hotNodes: hotNodes.map((n) => ({
+                id: n.to_id,
+                type: n.to_type,
+                inDegree: n.in_degree,
+            })),
+        };
+    }
+    /**
+     * 生成 Agent 可用的图谱上下文 (Markdown)
+     * @param {object} [options]
+     * @param {number} [options.maxEntities=30]
+     * @param {number} [options.maxEdges=50]
+     * @returns {string}
+     */
+    generateContextForAgent(options = {}) {
+        const maxEntities = options.maxEntities || 30;
+        const _maxEdges = options.maxEdges || 50;
+        const topo = this.getTopology();
+        if (topo.totalEntities === 0) {
+            return '';
+        }
+        const lines = [
+            '## 代码实体图谱 (Code Entity Graph)',
+            '',
+            `### 统计`,
+            ...Object.entries(topo.entities).map(([t, c]) => `- ${t}: ${c}`),
+            `- 总边数: ${topo.totalEdges}`,
+            '',
+        ];
+        // 核心实体 (入度最高)
+        if (topo.hotNodes.length > 0) {
+            lines.push('### 核心实体 (被依赖最多)');
+            for (const n of topo.hotNodes.slice(0, 10)) {
+                lines.push(`- \`${n.id}\` (${n.type}, 入度=${n.inDegree})`);
+            }
+            lines.push('');
+        }
+        // 类继承概览
+        const classes = this.listEntities('class', maxEntities);
+        if (classes.length > 0) {
+            lines.push('### 类继承关系');
+            for (const cls of classes) {
+                const chain = this.getInheritanceChain(cls.entityId, 5);
+                if (chain.length > 1) {
+                    lines.push(`- \`${chain.join(' → ')}\``);
+                }
+            }
+            lines.push('');
+        }
+        // 协议
+        const protocols = this.listEntities('protocol', 15);
+        if (protocols.length > 0) {
+            lines.push('### 协议');
+            for (const p of protocols) {
+                const conformers = this.getDescendants(p.entityId, 'protocol', 1);
+                const cNames = conformers.map((c) => c.id).slice(0, 5);
+                lines.push(`- \`${p.name}\` ← ${cNames.length > 0 ? cNames.map((n) => `\`${n}\``).join(', ') : '(无遵循者)'}`);
+            }
+            lines.push('');
+        }
+        // 调用图热路径 (Phase 5)
+        try {
+            const hotCallees = this.db
+                .prepare(`SELECT to_id, COUNT(*) as call_count
+           FROM knowledge_edges
+           WHERE relation = 'calls'
+           GROUP BY to_id
+           ORDER BY call_count DESC
+           LIMIT 15`)
+                .all();
+            if (hotCallees.length > 0) {
+                lines.push('### 调用图热路径 (Call Graph Hot Paths)');
+                for (const row of hotCallees) {
+                    // 查找前几个调用者
+                    const topCallers = this.db
+                        .prepare(`SELECT from_id FROM knowledge_edges
+               WHERE relation = 'calls' AND to_id = ?
+               LIMIT 3`)
+                        .all(row.to_id);
+                    const callerNames = topCallers
+                        .map((c) => `\`${c.from_id}\``)
+                        .join(', ');
+                    lines.push(`- \`${row.to_id}\` ← ${row.call_count} 次调用 (${callerNames}${topCallers.length < row.call_count ? '...' : ''})`);
+                }
+                lines.push('');
+            }
+            // 数据流边摘要
+            const dataFlowCount = this.db
+                .prepare(`SELECT COUNT(*) as cnt FROM knowledge_edges WHERE relation = 'data_flow'`)
+                .get();
+            if (dataFlowCount && dataFlowCount.cnt > 0) {
+                lines.push(`### 数据流`);
+                lines.push(`- 数据流边: ${dataFlowCount.cnt} 条`);
+                lines.push('');
+            }
+        }
+        catch (_e) {
+            // 调用图数据可能尚未填充, 静默跳过
+        }
+        return lines.join('\n');
+    }
+    // ────────────────────────────────────────────
+    // Public API — Phase 5: 调用图
+    // ────────────────────────────────────────────
+    /**
+     * 从解析后的调用边填充图谱 (Phase 5)
+     *
+     * @param {Array<{ caller: string, callee: string, callType: string, resolveMethod: string, line: number, file: string, isAwait: boolean }>} callEdges
+     * @param {Array<{ from: string, to: string, flowType: string, direction: string }>} dataFlowEdges
+     * @returns {GraphPopulateResult}
+     */
+    populateCallGraph(callEdges, dataFlowEdges) {
+        const t0 = Date.now();
+        let edges = 0;
+        let entities = 0;
+        const run = this.db.transaction(() => {
+            // ── 注册方法实体 (确保 from/to 的 entity 存在) ──
+            const registeredMethods = new Set();
+            for (const edge of callEdges) {
+                for (const fqn of [edge.caller, edge.callee]) {
+                    if (registeredMethods.has(fqn)) {
+                        continue;
+                    }
+                    registeredMethods.add(fqn);
+                    const entityId = this._extractEntityId(fqn);
+                    const entityName = entityId; // 短名
+                    const filePath = fqn.includes('::') ? fqn.split('::')[0] : null;
+                    this.#upsertEntity({
+                        entityId,
+                        entityType: 'method',
+                        name: entityName,
+                        filePath,
+                        metadata: { fqn, source: 'phase5-call-graph' },
+                    });
+                    entities++;
+                }
+            }
+            // ── 调用边 (聚合同一 caller-callee 对的多次调用，解决 Issue #4) ──
+            const aggregated = new Map(); // key = "callerId|calleeId" → aggregated metadata
+            for (const edge of callEdges) {
+                const callerId = this._extractEntityId(edge.caller);
+                const calleeId = this._extractEntityId(edge.callee);
+                const key = `${callerId}|${calleeId}`;
+                if (aggregated.has(key)) {
+                    const agg = aggregated.get(key);
+                    agg.callCount++;
+                    agg.callSites.push({ line: edge.line, isAwait: edge.isAwait });
+                    // 提升权重: direct 优先
+                    if (edge.resolveMethod === 'direct') {
+                        agg.resolveMethod = 'direct';
+                    }
+                    if (edge.isAwait) {
+                        agg.hasAwait = true;
+                    }
+                }
+                else {
+                    aggregated.set(key, {
+                        callerId,
+                        calleeId,
+                        callType: edge.callType,
+                        resolveMethod: edge.resolveMethod,
+                        file: edge.file,
+                        hasAwait: edge.isAwait,
+                        callCount: 1,
+                        callSites: [{ line: edge.line, isAwait: edge.isAwait }],
+                    });
+                }
+            }
+            for (const agg of aggregated.values()) {
+                this.#addEdge(agg.callerId, 'method', agg.calleeId, 'method', 'calls', {
+                    weight: agg.resolveMethod === 'direct' ? 1.0 : 0.6,
+                    source: 'phase5-call-graph',
+                    callType: agg.callType,
+                    resolveMethod: agg.resolveMethod,
+                    file: agg.file,
+                    isAwait: agg.hasAwait,
+                    callCount: agg.callCount,
+                    callSites: agg.callSites.slice(0, 10), // 最多保留 10 个调用点
+                });
+                edges++;
+            }
+            // ── 数据流边 ──
+            for (const flow of dataFlowEdges) {
+                const fromId = this._extractEntityId(flow.from || '');
+                const toId = this._extractEntityId(flow.to || '');
+                this.#addEdge(fromId, 'method', toId, 'method', 'data_flow', {
+                    weight: 0.5,
+                    source: 'phase5-data-flow',
+                    flowType: flow.flowType || '',
+                    direction: flow.direction || '',
+                });
+                edges++;
+            }
+        });
+        run();
+        const result = { entitiesUpserted: entities, edgesCreated: edges, durationMs: Date.now() - t0 };
+        this.log.info(`[CodeEntityGraph] Call graph: ${callEdges.length} call edges, ${dataFlowEdges.length} data flow edges, ${entities} method entities (${result.durationMs}ms)`);
+        return result;
+    }
+    /**
+     * 获取调用者 — 谁调用了这个方法？
+     *
+     * @param {string} methodId - "ClassName.methodName" 或 FQN
+     * @param {number} [maxDepth=2]
+     * @returns {Array<{ caller: string, depth: number, callType: string }>}
+     */
+    getCallers(methodId, maxDepth = 2) {
+        const results = [];
+        const visited = new Set();
+        const queue = [{ id: methodId, depth: 0 }];
+        while (queue.length > 0) {
+            const { id, depth } = queue.shift();
+            if (depth >= maxDepth || visited.has(id)) {
+                continue;
+            }
+            visited.add(id);
+            const callers = this.stmts.getCallers.all(id);
+            for (const row of callers) {
+                const meta = JSON.parse(row.metadata_json || '{}');
+                results.push({
+                    caller: row.from_id,
+                    depth: depth + 1,
+                    callType: meta.callType || 'unknown',
+                });
+                if (depth + 1 < maxDepth) {
+                    queue.push({ id: row.from_id, depth: depth + 1 });
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * 获取被调用者 — 这个方法调用了谁？
+     *
+     * @param {string} methodId - "ClassName.methodName" 或 FQN
+     * @param {number} [maxDepth=2]
+     * @returns {Array<{ callee: string, depth: number, callType: string }>}
+     */
+    getCallees(methodId, maxDepth = 2) {
+        const results = [];
+        const visited = new Set();
+        const queue = [{ id: methodId, depth: 0 }];
+        while (queue.length > 0) {
+            const { id, depth } = queue.shift();
+            if (depth >= maxDepth || visited.has(id)) {
+                continue;
+            }
+            visited.add(id);
+            const callees = this.stmts.getCallees.all(id);
+            for (const row of callees) {
+                const meta = JSON.parse(row.metadata_json || '{}');
+                results.push({
+                    callee: row.to_id,
+                    depth: depth + 1,
+                    callType: meta.callType || 'unknown',
+                });
+                if (depth + 1 < maxDepth) {
+                    queue.push({ id: row.to_id, depth: depth + 1 });
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * 获取方法的 Impact Radius (基于调用图)
+     * — 修改此方法可能影响哪些上游方法？
+     *
+     * @param {string} methodId - "ClassName.methodName"
+     * @returns {{ directCallers: number, transitiveCallers: number, affectedFiles: string[] }}
+     */
+    getCallImpactRadius(methodId) {
+        const callers = this.getCallers(methodId, 3);
+        const affectedFiles = new Set();
+        for (const c of callers) {
+            const entity = this.getEntity(c.caller, 'method');
+            if (entity?.filePath) {
+                affectedFiles.add(entity.filePath);
+            }
+        }
+        return {
+            directCallers: callers.filter((c) => c.depth === 1).length,
+            transitiveCallers: callers.length,
+            affectedFiles: [...affectedFiles],
+        };
+    }
+    /**
+     * 从 FQN 中提取短 Entity ID
+     *
+     * "src/service/UserService.ts::UserService.getUser" → "UserService.getUser"
+     * "src/utils/helpers.ts::formatDate" → "formatDate"
+     *
+     * @param {string} fqn
+     * @returns {string}
+     */
+    _extractEntityId(fqn) {
+        if (fqn.includes('::')) {
+            return fqn.split('::')[1];
+        }
+        return fqn;
+    }
+    /**
+     * 清除项目的所有代码实体 (重新 populate 前调用)
+     */
+    clearProject() {
+        const run = this.db.transaction(() => {
+            this.stmts.clearEntities.run(this.projectRoot);
+            // 清除 AST 产出的边 + Phase 5 调用图边 (保留 recipe/module 边)
+            this.db
+                .prepare(`DELETE FROM knowledge_edges WHERE metadata_json LIKE '%ast-bootstrap%' OR metadata_json LIKE '%ast-pattern-detection%' OR metadata_json LIKE '%phase5-%'`)
+                .run();
+        });
+        run();
+        this.log.info(`[CodeEntityGraph] Cleared entities for project: ${this.projectRoot}`);
+    }
+    /**
+     * 增量清除 — 仅删除指定文件的 call graph 边和 method 实体
+     *
+     * @param {string[]} filePaths 变更文件的相对路径列表
+     * @returns {{ deletedEdges: number, deletedEntities: number }}
+     */
+    clearCallGraphForFiles(filePaths) {
+        if (!filePaths?.length) {
+            return { deletedEdges: 0, deletedEntities: 0 };
+        }
+        let deletedEdges = 0;
+        let deletedEntities = 0;
+        const run = this.db.transaction(() => {
+            // 1. 删除相关 call edges (metadata_json 包含 file 字段)
+            const deleteEdgesStmt = this.db.prepare(`DELETE FROM knowledge_edges 
+         WHERE metadata_json LIKE ? 
+         AND (relation = 'calls' OR relation = 'data_flow')
+         AND metadata_json LIKE '%phase5-%'`);
+            for (const filePath of filePaths) {
+                // 匹配 metadata 中 "file":"xxx" 字段
+                const result = deleteEdgesStmt.run(`%"file":"${filePath}"%`);
+                deletedEdges += result.changes;
+            }
+            // 2. 删除相关 method 实体
+            const deleteEntitiesStmt = this.db.prepare(`DELETE FROM code_entities 
+         WHERE file_path = ? AND entity_type = 'method' AND project_root = ?`);
+            for (const filePath of filePaths) {
+                const result = deleteEntitiesStmt.run(filePath, this.projectRoot);
+                deletedEntities += result.changes;
+            }
+        });
+        run();
+        this.log.info(`[CodeEntityGraph] Incremental clear: ${deletedEdges} edges, ${deletedEntities} entities ` +
+            `for ${filePaths.length} files`);
+        return { deletedEdges, deletedEntities };
+    }
+    // ────────────────────────────────────────────
+    // Private — Schema & Statements
+    // ────────────────────────────────────────────
+    #ensureTable() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS code_entities (
+        id            INTEGER PRIMARY KEY AUTOINCREMENT,
+        entity_id     TEXT NOT NULL,
+        entity_type   TEXT NOT NULL,
+        project_root  TEXT NOT NULL,
+        name          TEXT NOT NULL,
+        file_path     TEXT,
+        line_number   INTEGER,
+        superclass    TEXT,
+        protocols     TEXT DEFAULT '[]',
+        metadata_json TEXT DEFAULT '{}',
+        created_at    INTEGER NOT NULL,
+        updated_at    INTEGER NOT NULL,
+        UNIQUE (entity_id, entity_type, project_root)
+      );
+      CREATE INDEX IF NOT EXISTS idx_ce_project    ON code_entities(project_root);
+      CREATE INDEX IF NOT EXISTS idx_ce_type       ON code_entities(entity_type);
+      CREATE INDEX IF NOT EXISTS idx_ce_name       ON code_entities(name);
+      CREATE INDEX IF NOT EXISTS idx_ce_file       ON code_entities(file_path);
+      CREATE INDEX IF NOT EXISTS idx_ce_superclass ON code_entities(superclass);
+    `);
+    }
+    #prepareStatements() {
+        this.stmts = {
+            upsert: this.db.prepare(`
+        INSERT INTO code_entities (entity_id, entity_type, project_root, name, file_path, line_number, superclass, protocols, metadata_json, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (entity_id, entity_type, project_root) DO UPDATE SET
+          name = excluded.name,
+          file_path = COALESCE(excluded.file_path, code_entities.file_path),
+          line_number = COALESCE(excluded.line_number, code_entities.line_number),
+          superclass = COALESCE(excluded.superclass, code_entities.superclass),
+          protocols = excluded.protocols,
+          metadata_json = excluded.metadata_json,
+          updated_at = excluded.updated_at
+      `),
+            getEntity: this.db.prepare(`SELECT * FROM code_entities WHERE entity_id = ? AND entity_type = ? AND project_root = ?`),
+            listByType: this.db.prepare(`SELECT * FROM code_entities WHERE entity_type = ? AND project_root = ? ORDER BY name LIMIT ?`),
+            clearEntities: this.db.prepare(`DELETE FROM code_entities WHERE project_root = ?`),
+            addEdge: this.db.prepare(`
+        INSERT OR REPLACE INTO knowledge_edges (from_id, from_type, to_id, to_type, relation, weight, metadata_json, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `),
+            // Phase 5: 调用图查询 (pre-prepared 避免每次调用都创建)
+            getCallers: this.db.prepare(`SELECT from_id, from_type, metadata_json FROM knowledge_edges
+         WHERE to_id = ? AND relation = 'calls'`),
+            getCallees: this.db.prepare(`SELECT to_id, to_type, metadata_json FROM knowledge_edges
+         WHERE from_id = ? AND relation = 'calls'`),
+            getEdge: this.db.prepare(`SELECT metadata_json FROM knowledge_edges
+         WHERE from_id = ? AND from_type = ? AND to_id = ? AND to_type = ? AND relation = ?`),
+        };
+    }
+    // ────────────────────────────────────────────
+    // Private — Helpers
+    // ────────────────────────────────────────────
+    #upsertEntity(entity) {
+        const now = Math.floor(Date.now() / 1000);
+        this.stmts.upsert.run(entity.entityId, entity.entityType, this.projectRoot, entity.name, entity.filePath || null, entity.line || null, entity.superclass || null, JSON.stringify(entity.protocols || []), JSON.stringify(entity.metadata || {}), now, now);
+    }
+    #addEdge(fromId, fromType, toId, toType, relation, metadata = {}) {
+        const now = Math.floor(Date.now() / 1000);
+        try {
+            this.stmts.addEdge.run(fromId, fromType, toId, toType, relation, metadata.weight || 1.0, JSON.stringify(metadata), now, now);
+        }
+        catch (err) {
+            // Ignore duplicate edge errors
+            if (err instanceof Error && !err.message.includes('UNIQUE constraint')) {
+                this.log.warn(`[CodeEntityGraph] addEdge failed: ${err.message}`);
+            }
+        }
+    }
+    /**
+     * 从 AST 数据推断实体类型
+     */
+    #inferEntityType(name, astSummary) {
+        if (!name) {
+            return 'class'; // guard against undefined
+        }
+        if (astSummary.protocols?.some((p) => p.name === name)) {
+            return 'protocol';
+        }
+        if (name.includes('(') && name.includes(')')) {
+            return 'category';
+        }
+        return 'class';
+    }
+    /**
+     * 映射 Relations 桶名到图谱边类型
+     */
+    #mapRelationType(type) {
+        const mapping = {
+            inherits: 'inherits',
+            implements: 'conforms',
+            calls: 'calls',
+            depends_on: 'depends_on',
+            data_flow: 'data_flow',
+            conflicts: 'conflicts',
+            extends: 'extends',
+            related: 'related',
+            alternative: 'related',
+            prerequisite: 'depends_on',
+            deprecated_by: 'related',
+            solves: 'related',
+            enforces: 'enforces',
+            references: 'references',
+        };
+        return mapping[type] || 'related';
+    }
+    #mapEdge(row) {
+        return {
+            fromId: row.from_id,
+            fromType: row.from_type,
+            toId: row.to_id,
+            toType: row.to_type,
+            relation: row.relation,
+            weight: row.weight,
+            metadata: JSON.parse(row.metadata_json || '{}'),
+        };
+    }
+    #mapEntity(row) {
+        return {
+            entityId: row.entity_id,
+            entityType: row.entity_type,
+            name: row.name,
+            filePath: row.file_path,
+            line: row.line_number,
+            superclass: row.superclass,
+            protocols: JSON.parse(row.protocols || '[]'),
+            metadata: JSON.parse(row.metadata_json || '{}'),
+            projectRoot: row.project_root,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        };
+    }
+}
+export default CodeEntityGraph;
+//# sourceMappingURL=CodeEntityGraph.js.map