spectra-cli 4.1.1 → 4.3.0

package/dist/knowledge-graph/query-helpers.js

@@ -0,0 +1,559 @@
+/**
+ * Feature 155 — Agent-Context MCP Tools 的查询基建。
+ *
+ * 暴露给 src/mcp/agent-context-tools.ts 的工具函数：
+ *   - bfsTraverse：反向 / 正向 BFS，遍历前 budget 截断（FR-012）
+ *   - canonicalizeSymbolId：把用户传入的 symbol id 归一到 graph 实际 id
+ *   - resolveSymbolFuzzy：symbol-not-found 时分层 fuzzy 解析 + 高置信度自动 resolve（Feature 174）
+ *   - computeRiskTier：按 directCallers + transitive 判定 low / medium / high
+ *   - getReverseAdjacency：反向邻接表 lazy 构建 + LRU 缓存
+ *
+ * 输入合同：
+ *   query-helpers 直接消费 GraphJSON `{nodes, links}`（与 graph.json 序列化形态一致），
+ *   不依赖 UnifiedGraph in-memory 类型，避免与 build-time 路径耦合。
+ *
+ * 不变量：
+ *   - 所有函数对 graphData 只读（禁止修改 nodes / links / metadata）
+ *   - confidence 数值直接读 link.confidenceScore；缺失时尝试 link.confidence
+ *     通过 CONFIDENCE_SCORES 映射；仍失败 → 跳过该边并记 'missing-confidence-score' warning
+ *   - canonicalize 控制字符 / 非 UTF-8 → 返回 null（调用方按 invalid-symbol-id 处理）
+ *   - reverse adjacency cache key = `${graphPath}::${mtimeMs}::${sizeBytes}::${linksLength}::${relations}`
+ *     graph.json 重生成（mtime/size 必变）→ 自动 evict
+ */
+import path from 'node:path';
+import { CONFIDENCE_SCORES } from '../panoramic/graph/confidence-mapper.js';
+import { levenshtein } from '../utils/string-distance.js';
+// ============================================================
+// 常量
+// ============================================================
+const DEFAULT_RELATIONS = ['calls'];
+/** 控制字符正则（包含 \x00-\x1f, \x7f；保留制表符不在内是因为 git diff 路径不会含 \t） */
+const CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
+/** baseRef / symbol id 不可见字符快速校验 */
+// NON_PRINTABLE_RE removed - CONTROL_CHAR_RE is sufficient
+// ============================================================
+// confidence 数值解析
+// ============================================================
+/**
+ * 解析一条边的 confidence 数值。
+ *
+ * 优先级：edge.confidenceScore（已含数字）→ edge.confidence 走 CONFIDENCE_SCORES 映射 → null。
+ *
+ * 返回 null 表示"无法判定 confidence"，调用方应跳过该边并记 warning。
+ */
+export function resolveEdgeConfidence(edge) {
+    if (typeof edge.confidenceScore === 'number' && Number.isFinite(edge.confidenceScore)) {
+        return edge.confidenceScore;
+    }
+    const tier = edge.confidence;
+    if (tier !== undefined && tier in CONFIDENCE_SCORES) {
+        return CONFIDENCE_SCORES[tier];
+    }
+    return null;
+}
+// ============================================================
+// canonicalize symbol id
+// ============================================================
+/**
+ * 把用户输入的 target / symbolId 归一到 graph 实际 id。
+ *
+ * 归一规则（按顺序尝试，命中即返回）：
+ *   1. graph.nodes 中存在字面相等的 id → 直接返回
+ *   2. 把 `./prefix` `a/` `b/` 等前缀剥掉 → 再查
+ *   3. 三段输入 `A::B::C` 容错为 `A::B.C` → 再查（Codex round-1 C-1 修订）
+ *   4. 把绝对路径 → 仓库相对路径（按 graphData.graph?.metadata 或 projectRoot 选项）→ 再查
+ *
+ * 失败返回 null，调用方按 symbol-not-found 处理（建议同时调 resolveSymbolFuzzy 提候选/自动 resolve）。
+ *
+ * 控制字符 / 非 UTF-8 / 空字符串段输入返回 null（调用方按 invalid-symbol-id 处理）。
+ */
+export function canonicalizeSymbolId(rawTarget, graphData, options = {}) {
+    if (typeof rawTarget !== 'string') {
+        return { canonicalId: null, reason: 'invalid' };
+    }
+    // 入口先 NFC normalize + trim，避免空白 / unicode 表示差异让用户输入被误判
+    const normalized = rawTarget.normalize('NFC').trim();
+    if (normalized.length === 0) {
+        return { canonicalId: null, reason: 'invalid' };
+    }
+    if (CONTROL_CHAR_RE.test(normalized)) {
+        return { canonicalId: null, reason: 'invalid' };
+    }
+    // 拒绝多 `::` 或空段
+    const segs = normalized.split('::');
+    if (segs.some((s) => s.length === 0)) {
+        return { canonicalId: null, reason: 'invalid' };
+    }
+    // 直接命中
+    if (hasNode(graphData, normalized)) {
+        return { canonicalId: normalized, reason: 'ok' };
+    }
+    const candidates = [];
+    // 剥前缀：./ a/ b/
+    const stripped = normalized
+        .replace(/^\.\//, '')
+        .replace(/^a\//, '')
+        .replace(/^b\//, '');
+    if (stripped !== normalized) {
+        candidates.push(stripped);
+    }
+    // 三段 → 两段（A::B::C → A::B.C）
+    if (segs.length >= 3) {
+        const merged = segs[0] + '::' + segs.slice(1).join('.');
+        candidates.push(merged);
+    }
+    // 绝对路径 → repo-relative（按 projectRoot 截断）
+    const projectRoot = options.projectRoot;
+    if (projectRoot && normalized.startsWith(projectRoot)) {
+        const relative = path.relative(projectRoot, normalized);
+        if (relative.length > 0) {
+            candidates.push(relative);
+        }
+    }
+    // repo-relative → 绝对路径（graph 实际可能用绝对 path 形态，例如 baseline 跑出的 graph.json）
+    if (projectRoot && !path.isAbsolute(normalized.split('::')[0] ?? '')) {
+        const filePart = normalized.split('::')[0] ?? '';
+        const symbolPart = normalized.includes('::') ? normalized.slice(filePart.length) : '';
+        const abs = path.join(projectRoot, filePart) + symbolPart;
+        candidates.push(abs);
+    }
+    for (const c of candidates) {
+        if (hasNode(graphData, c)) {
+            return { canonicalId: c, reason: 'ok' };
+        }
+    }
+    return { canonicalId: null, reason: 'not-found' };
+}
+function hasNode(graphData, id) {
+    for (const n of graphData.nodes) {
+        if (n.id === id)
+            return true;
+    }
+    return false;
+}
+/** path-suffix 层锁定的精确常量（FR-003 边界规则：恰好满足 >= 0.9） */
+const PATH_SUFFIX_CONFIDENCE = 0.9;
+/** autoResolve 阈值下限（production floor，FR-012） */
+const AUTO_RESOLVE_FLOOR = 0.9;
+/** Levenshtein 相对距离阈值（distance/maxLen ≤ 0.35 才纳入候选） */
+const LEVENSHTEIN_RATIO = 0.35;
+/** 超过此长度跳过 Levenshtein 层，防 O(m×n) 退化（FR-010） */
+const LEVENSHTEIN_MAX_QUERY_LEN = 512;
+/**
+ * 取 nodeId 文件分隔符之后的 symbol 段（无分隔符则返回整个 nodeId）。
+ *
+ * 兼容两种分隔符（与 moduleFileFromId 取最早分隔符一致）：
+ *   - Feature 151 格式 `<file>::<symbolName>`（例 `engine.py::Value.__add__`）
+ *   - 旧 panoramic 格式 `<file>#<symbolName>`（例 `engine.py#Value`）
+ * 兼容 `#` 避免对旧格式 graph 的 partial-name 回归（Codex GREEN W-2）。
+ */
+function symbolSeg(nodeId) {
+    const idxColon = nodeId.indexOf('::');
+    const idxHash = nodeId.indexOf('#');
+    let cut = -1;
+    let sepLen = 0;
+    if (idxColon >= 0 && (idxHash < 0 || idxColon <= idxHash)) {
+        cut = idxColon;
+        sepLen = 2;
+    }
+    else if (idxHash >= 0) {
+        cut = idxHash;
+        sepLen = 1;
+    }
+    return cut >= 0 ? nodeId.slice(cut + sepLen) : nodeId;
+}
+/**
+ * 生成 typo 比对用的多种表示集合（Feature 174 C-1 修复）。
+ *
+ * 不能只对完整 node.id 算 Levenshtein —— `micrograd/` 等 package 前缀会把 typo 距离
+ * 推到阈值之外。这里额外提供去前缀的 `basename(file)::symbol` 与纯 symbol 表示，
+ * 让拼写错误的相对距离回落到可命中范围。
+ */
+function nodeMatchReps(nodeId) {
+    const reps = new Set([nodeId]);
+    const seg = symbolSeg(nodeId);
+    reps.add(seg);
+    const filePart = moduleFileFromId(nodeId);
+    const base = filePart.split('/').pop() ?? filePart;
+    if (nodeId.includes('::')) {
+        reps.add(base + '::' + seg);
+    }
+    else {
+        reps.add(base);
+    }
+    return [...reps];
+}
+/** 层 (b) path-suffix：query 含路径语义（`::` 或 `/`）时，按 `/`+query 后缀匹配 */
+function layerPathSuffix(graphData, query) {
+    // C-2 修复：bare 单 token（无 `::` 无 `/`）必须落到 partial-name 层，
+    // 否则可能误匹配某个 `*/Value` 文件节点并以 0.9 抢先 autoResolve。
+    if (!query.includes('::') && !query.includes('/'))
+        return [];
+    const lowerQuery = query.toLowerCase();
+    const results = [];
+    for (const node of graphData.nodes) {
+        const lowerId = node.id.toLowerCase();
+        if (lowerId === lowerQuery || lowerId.endsWith('/' + lowerQuery)) {
+            results.push({ id: node.id, confidence: PATH_SUFFIX_CONFIDENCE, matchKind: 'path-suffix' });
+        }
+    }
+    return results;
+}
+/**
+ * 层 (c) partial-name：query 仅含方法名/类名时按唯一性加权。
+ *
+ * 匹配条件：symbolSeg(node) === query 或 symbolSeg(node).endsWith('.' + query)（大小写不敏感）。
+ * 打分（Open Question A 决策）：
+ *   - 唯一命中（matchCount === 1）：qualified `Class.method` → 0.95，bare 单 token → 0.90
+ *   - 多义（matchCount > 1）：max(0.70, 0.85 - rank * (0.15 / (matchCount - 1)))，按相对唯一性递减
+ */
+function layerPartialName(graphData, query) {
+    const lowerQuery = query.toLowerCase();
+    const isQualified = query.includes('.');
+    const matched = [];
+    for (const node of graphData.nodes) {
+        const seg = symbolSeg(node.id).toLowerCase();
+        if (seg === lowerQuery || seg.endsWith('.' + lowerQuery)) {
+            matched.push(node.id);
+        }
+    }
+    const matchCount = matched.length;
+    if (matchCount === 0)
+        return [];
+    return matched.map((id, rank) => {
+        let confidence;
+        if (matchCount === 1) {
+            confidence = isQualified ? 0.95 : 0.9;
+        }
+        else {
+            confidence = Math.max(0.7, 0.85 - rank * (0.15 / (matchCount - 1)));
+        }
+        return { id, confidence, matchKind: 'partial-name' };
+    });
+}
+/**
+ * 层 (d) Levenshtein：对每个 node 的多种表示取相对距离最小者（C-1 修复）。
+ *
+ * 仅纳入相对编辑距离 ≤ LEVENSHTEIN_RATIO 的候选；confidence 线性映射到 [0.50, 0.75]。
+ */
+function layerLevenshtein(graphData, query) {
+    const lowerQuery = query.toLowerCase();
+    const results = [];
+    for (const node of graphData.nodes) {
+        let bestRatio = Infinity;
+        let bestConf = 0;
+        for (const rep of nodeMatchReps(node.id)) {
+            const r = rep.toLowerCase();
+            const threshold = Math.ceil(Math.max(lowerQuery.length, r.length) * LEVENSHTEIN_RATIO);
+            if (threshold === 0)
+                continue;
+            // 长度差剪枝（Codex GREEN W-1）：|len(a)-len(b)| 是编辑距离的精确下界，
+            // 超阈值必然不命中，跳过 DP 计算——结果不变，避免长 nodeId 上的性能退化。
+            if (Math.abs(lowerQuery.length - r.length) > threshold)
+                continue;
+            const dist = levenshtein(lowerQuery, r);
+            if (dist > threshold)
+                continue;
+            const ratio = dist / threshold;
+            if (ratio < bestRatio) {
+                bestRatio = ratio;
+                bestConf = Math.max(0.5, Math.min(0.75, 0.75 - ratio * 0.25));
+            }
+        }
+        if (bestRatio !== Infinity) {
+            results.push({ id: node.id, confidence: bestConf, matchKind: 'levenshtein' });
+        }
+    }
+    return results;
+}
+/** 去重：同 id 保留最高 confidence */
+function deduplicateCandidates(raw) {
+    const best = new Map();
+    for (const c of raw) {
+        const prev = best.get(c.id);
+        if (prev === undefined || c.confidence > prev.confidence)
+            best.set(c.id, c);
+    }
+    return [...best.values()];
+}
+/**
+ * 去重 → 按 confidence 降序 → 判定 autoResolved → top-N。
+ *
+ * C-3 修复：autoResolved 用**去重后、slice 之前**的 deduped.length 判唯一，
+ * 不能用 slice(0,limit) 后的长度，否则 limit=1 会把多候选误判为唯一候选。
+ */
+function buildResult(raw, limit, threshold) {
+    const deduped = deduplicateCandidates(raw);
+    deduped.sort((a, b) => b.confidence - a.confidence);
+    const autoResolved = deduped.length === 1 && deduped[0].confidence >= threshold;
+    return { candidates: deduped.slice(0, limit), autoResolved };
+}
+/**
+ * 分层 fuzzy 解析 symbol id（Feature 174）。
+ *
+ * 四层命中即停（分数递减）：
+ *   (a) exact      — 复用 canonicalizeSymbolId，confidence 1.0
+ *   (b) path-suffix — 文件路径后缀匹配，confidence 0.9
+ *   (c) partial-name — 仅方法名/类名，按唯一性加权（唯一 ≥0.9 / 多义 0.7~0.85）
+ *   (d) levenshtein — 拼写相似，confidence 0.5~0.75（query > 512 跳过）
+ *
+ * autoResolved = 去重后唯一候选 且 confidence ≥ max(0.9, opts.autoResolveThreshold)。
+ * 空 / 纯空白 / 含控制字符 query → { candidates: [], autoResolved: false }（不抛异常）。
+ * graphData 只读。
+ */
+export function resolveSymbolFuzzy(graphData, query, opts = {}) {
+    // limit 至少为 1：display cap 不应小于 1，否则 autoResolved=true 时 candidates 被
+    // slice 成空数组、与 autoResolved 语义矛盾（Codex REFACTOR review）。
+    const limit = Math.max(1, opts.limit ?? 10);
+    // floor：production 阈值不得低于 0.9（FR-012，防绕过 FR-003 硬阈值）
+    const threshold = Math.max(AUTO_RESOLVE_FLOOR, opts.autoResolveThreshold ?? AUTO_RESOLVE_FLOOR);
+    // 前置 guard：空 / 纯空白 / 控制字符
+    if (typeof query !== 'string')
+        return { candidates: [], autoResolved: false };
+    const trimmed = query.trim();
+    if (trimmed.length === 0 || CONTROL_CHAR_RE.test(query)) {
+        return { candidates: [], autoResolved: false };
+    }
+    // 层 (a) exact —— 复用 canonicalizeSymbolId
+    const canon = canonicalizeSymbolId(query, graphData, { projectRoot: opts.projectRoot });
+    if (canon.reason === 'ok' && canon.canonicalId !== null) {
+        return {
+            candidates: [{ id: canon.canonicalId, confidence: 1.0, matchKind: 'exact' }],
+            autoResolved: true, // exact 必然唯一且 1.0 >= threshold
+        };
+    }
+    // 层 (b) path-suffix
+    const pathSuffix = layerPathSuffix(graphData, query);
+    if (pathSuffix.length > 0)
+        return buildResult(pathSuffix, limit, threshold);
+    // 层 (c) partial-name
+    const partialName = layerPartialName(graphData, query);
+    if (partialName.length > 0)
+        return buildResult(partialName, limit, threshold);
+    // 层 (d) Levenshtein（query 过长跳过，防性能退化）
+    if (query.length <= LEVENSHTEIN_MAX_QUERY_LEN) {
+        const lev = layerLevenshtein(graphData, query);
+        if (lev.length > 0)
+            return buildResult(lev, limit, threshold);
+    }
+    return { candidates: [], autoResolved: false };
+}
+// ============================================================
+// risk tier
+// ============================================================
+/**
+ * 按 directCallers + transitive 节点数判定 risk tier。
+ *
+ * 阈值（spec FR-014）：
+ *   - directCallers ≥ 10 或 transitive ≥ 50 → high
+ *   - directCallers ≥ 3  或 transitive ≥ 15 → medium
+ *   - 其余 → low
+ */
+export function computeRiskTier(directCallers, transitive) {
+    if (directCallers >= 10 || transitive >= 50)
+        return 'high';
+    if (directCallers >= 3 || transitive >= 15)
+        return 'medium';
+    return 'low';
+}
+// ============================================================
+// reverse adjacency cache（LRU ≤ 8）
+// ============================================================
+const ADJ_CACHE_LIMIT = 8;
+/**
+ * 反向邻接表 cache（按 graphPath + mtime + size + linksLength + relations 建 key）。
+ *
+ * 用 Map 实现 LRU：超过 LIMIT 时按插入顺序 evict 最早条目。同 key 命中时
+ * delete + set 把它放到最尾，模拟 "recently used"。
+ */
+const adjCache = new Map();
+function buildAdjKey(graphPath, mtimeMs, sizeBytes, linksLength, relations, direction) {
+    return `${graphPath}::${mtimeMs}::${sizeBytes}::${linksLength}::${relations.join(',')}::${direction}`;
+}
+/**
+ * 获取（或构建）反向邻接表。
+ *
+ * direction 决定邻接方向：
+ *   - upstream：target → 进入此节点的 inbound 边（callers）
+ *   - downstream：source → 离开此节点的 outbound 边（callees）
+ *   - both：合并 inbound + outbound
+ *
+ * 仅保留 relation 在 relations 集合内的边；其他 relation 的边不进入邻接表。
+ */
+export function getReverseAdjacency(graphData, graphPath, mtimeMs, sizeBytes, relations, direction) {
+    const key = buildAdjKey(graphPath, mtimeMs, sizeBytes, graphData.links.length, relations, direction);
+    const cached = adjCache.get(key);
+    if (cached !== undefined) {
+        // LRU：把命中的条目挪到最尾
+        adjCache.delete(key);
+        adjCache.set(key, cached);
+        return cached;
+    }
+    const adj = new Map();
+    const allowedRelations = new Set(relations);
+    for (const link of graphData.links) {
+        if (!allowedRelations.has(link.relation))
+            continue;
+        if (direction === 'upstream' || direction === 'both') {
+            // target ← source
+            const list = adj.get(link.target) ?? [];
+            list.push({ sourceId: link.source, edge: link });
+            adj.set(link.target, list);
+        }
+        if (direction === 'downstream' || direction === 'both') {
+            // source → target，但反向邻接表存储到 source 的 list 上以便 BFS 统一从 currentId 找下一跳
+            const list = adj.get(link.source) ?? [];
+            list.push({ sourceId: link.target, edge: link });
+            adj.set(link.source, list);
+        }
+    }
+    // 写入 cache，超 LIMIT 时 evict 最早
+    if (adjCache.size >= ADJ_CACHE_LIMIT) {
+        const oldestKey = adjCache.keys().next().value;
+        if (oldestKey !== undefined)
+            adjCache.delete(oldestKey);
+    }
+    adjCache.set(key, adj);
+    return adj;
+}
+/** 测试 / debug 用：清空 reverse adjacency cache */
+export function clearReverseAdjacencyCache() {
+    adjCache.clear();
+}
+// ============================================================
+// BFS traverse（核心）
+// ============================================================
+/**
+ * 从 startId 出发做 BFS，返回受影响的节点列表。
+ *
+ * 关键合同（FR-012）：
+ *   - budget 在**遍历前**应用：每次准备 enqueue 一个新节点之前，检查
+ *     `affected.length + 1 > effectiveBudget`，超即停止入队并 push 'budget-truncated' warning
+ *   - start node 不计入 budget；budget 仅约束 affected 数量
+ *   - depth 是边数：depth=2 含 direct caller (depth=1) + 二级 caller (depth=2)
+ *   - confidence 缺失：跳过 + 记 'missing-confidence-score' warning（不当作 0 静默通过）
+ *   - sharedVisited 跨调用共享：detect_changes 多 changedSymbol 用同一 globalVisited
+ *     去重，让 affected 不重复计入同一节点
+ *
+ * 返回的 warnings 是去重的：同一类 warning 多次触发只 push 一次。
+ */
+export function bfsTraverse(graphData, startId, options) {
+    const effectiveDepth = Math.max(0, Math.floor(options.depth));
+    const effectiveBudget = Math.max(0, Math.floor(options.budget));
+    const minConfidence = Math.max(0, Math.min(1, options.minConfidence));
+    const relations = options.relations && options.relations.length > 0 ? options.relations : DEFAULT_RELATIONS;
+    const warnings = new Set();
+    const affected = [];
+    if (effectiveDepth === 0) {
+        if (options.depth !== effectiveDepth)
+            warnings.add('depth-clamped');
+        return { affected, warnings: [...warnings] };
+    }
+    if (effectiveBudget === 0) {
+        return { affected, warnings: ['budget-zero'] };
+    }
+    const visited = options.sharedVisited ?? new Set();
+    visited.add(startId);
+    const adj = getReverseAdjacency(graphData, options.graphPath, options.graphMtimeMs, options.graphSizeBytes, relations, options.direction);
+    const queue = [{ id: startId, depth: 0, path: [startId] }];
+    let confidenceFiltered = 0;
+    let truncated = false;
+    // BFS 主循环
+    while (queue.length > 0) {
+        if (truncated)
+            break;
+        const cur = queue.shift();
+        if (cur.depth >= effectiveDepth)
+            continue;
+        const neighbors = adj.get(cur.id);
+        if (neighbors === undefined)
+            continue;
+        for (const ne of neighbors) {
+            if (truncated)
+                break;
+            const conf = resolveEdgeConfidence(ne.edge);
+            if (conf === null) {
+                warnings.add('missing-confidence-score');
+                continue;
+            }
+            if (conf < minConfidence) {
+                confidenceFiltered++;
+                continue;
+            }
+            if (visited.has(ne.sourceId))
+                continue;
+            // budget 遍历前截断（FR-012 关键合同）
+            if (affected.length + 1 > effectiveBudget) {
+                warnings.add('budget-truncated');
+                truncated = true;
+                break;
+            }
+            visited.add(ne.sourceId);
+            const nextDepth = cur.depth + 1;
+            const nextPath = [...cur.path, ne.sourceId];
+            const reason = buildReason(cur.id, ne.sourceId, ne.edge);
+            affected.push({
+                id: ne.sourceId,
+                depth: nextDepth,
+                confidence: conf,
+                reason,
+                path: nextPath,
+            });
+            // 只有还能继续展开（下一深度 < effectiveDepth）才入队
+            if (nextDepth < effectiveDepth) {
+                queue.push({ id: ne.sourceId, depth: nextDepth, path: nextPath });
+            }
+        }
+    }
+    if (affected.length === 0 && confidenceFiltered > 0) {
+        warnings.add('confidence-filtered-all');
+    }
+    if (options.depth !== effectiveDepth || options.budget !== effectiveBudget) {
+        warnings.add('input-clamped');
+    }
+    return { affected, warnings: [...warnings] };
+}
+function buildReason(fromId, toId, edge) {
+    const fromLabel = labelFromId(fromId);
+    const toLabel = labelFromId(toId);
+    return `${edge.relation} via ${fromLabel} ← ${toLabel}`;
+}
+function labelFromId(id) {
+    // 取 `file::Class.method` 中最右侧 segment 作为可读 label
+    const idx = id.lastIndexOf('::');
+    return idx >= 0 ? id.slice(idx + 2) : id;
+}
+// ============================================================
+// 节点 id → 节点 metadata 抽取（context tool 用）
+// ============================================================
+/**
+ * 取节点的 module file 部分。
+ *
+ * 兼容两种分隔符（同一个 graph 内可能并存）：
+ *   - Feature 151 新格式：`<file>::<symbolName>` 例 `micrograd/engine.py::Value.__add__`
+ *   - 旧 panoramic 格式：`<file>#<symbolName>` 例 `micrograd/engine.py#Value`
+ *
+ * 模块节点本身（id 既不含 `::` 也不含 `#`）→ 返回 id 自身。
+ * 取最早出现的分隔符位置作为 cut 点。
+ */
+export function moduleFileFromId(nodeId) {
+    const idxColon = nodeId.indexOf('::');
+    const idxHash = nodeId.indexOf('#');
+    const cuts = [idxColon, idxHash].filter((i) => i >= 0);
+    if (cuts.length === 0)
+        return nodeId;
+    const first = Math.min(...cuts);
+    return nodeId.slice(0, first);
+}
+/**
+ * 在 graph 中找指定 node 的 GraphNode 对象。
+ * O(n) — 仅小规模 graph 使用，调用频率不高（仅 context handler 的 definition 字段）。
+ */
+export function findNode(graphData, id) {
+    for (const n of graphData.nodes) {
+        if (n.id === id)
+            return n;
+    }
+    return null;
+}
+//# sourceMappingURL=query-helpers.js.map

package/dist/knowledge-graph/query-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-helpers.js","sourceRoot":"","sources":["../../src/knowledge-graph/query-helpers.ts"],"names":[],"mappings":"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"}

package/dist/knowledge-graph/relativize.d.ts

@@ -0,0 +1,51 @@
+/** relativizePosix 单值结果 */
+export interface RelativizeResult {
+    /** 相对化后的值（projectRoot 外时 = 原绝对值） */
+    value: string;
+    /** 是否为 projectRoot 之外的路径（调用方据此标 external） */
+    external: boolean;
+}
+/**
+ * 跨平台「绝对 / 异源路径」判定（Codex implement-C1.1 / new-2）。
+ *
+ * 命中任一即视为非 POSIX 相对路径：
+ * - POSIX 绝对（`/...`）
+ * - Windows 绝对（`C:\...` / `C:/...` / UNC `\\...`）
+ * - Windows 盘符前缀（含 drive-relative `C:foo`，`path.win32.isAbsolute` 对其返回 false 会漏判）
+ *
+ * 用于：加载期 graph-format-stale 检测 + 写入前 portable 守卫——保证 POSIX 运行时也能识别
+ * 旧 Windows 导出图里的绝对/盘符路径，三处调用点共用同一判定避免分叉。
+ */
+export declare function isAbsoluteForeignPath(p: string): boolean;
+/**
+ * segment-aware 包含判定：filePart 是否真位于 root 之内（Codex implement-C1.2）。
+ *
+ * 用 `path.relative` 段级判定，避免两类误判：
+ * - 前缀歧义：`/repo/app-old` 不应判为在 `/repo/app` 内（startsWith 会误判）
+ * - 同名目录：`..foo`（合法子目录）不应被 `rel.startsWith('..')` 误判为越界
+ *
+ * 仅当 rel 恰为 `..` 或以 `../`(POSIX) / `..\`(Win) 起始 / 仍是绝对路径时，判为不在 root 内。
+ */
+export declare function isPathContainedUnder(root: string, filePart: string): boolean;
+/**
+ * 把绝对路径相对化为相对 projectRoot 的 POSIX 路径。
+ *
+ * - 输入非绝对（已相对 / 逻辑名）→ 原样返回（幂等），external=false。
+ * - 输入绝对且在 projectRoot 内 → strip 前缀 + POSIX 化，external=false。
+ * - 输入绝对但在 projectRoot 外 → 返回原绝对值，external=true。
+ *
+ * @param absPath 待处理路径（可能绝对、可能已相对）
+ * @param projectRoot 项目根（相对化基准）
+ */
+export declare function relativizePosix(absPath: string, projectRoot: string): RelativizeResult;
+/**
+ * 相对化一个 symbol id（形如 `<path>::<name>` / `<path>::<name>.<member>` / 纯 `<path>`）。
+ *
+ * 只相对化第一个 `::` 之前的路径部分，保留 `::` / `.` 结构分隔符与 symbol 段不变。
+ *
+ * @param id 原始 symbol id（路径部分可能绝对）
+ * @param projectRoot 相对化基准
+ * @returns 相对化后的 id + 路径部分是否 external
+ */
+export declare function relativizeSymbolId(id: string, projectRoot: string): RelativizeResult;
+//# sourceMappingURL=relativize.d.ts.map

package/dist/knowledge-graph/relativize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relativize.d.ts","sourceRoot":"","sources":["../../src/knowledge-graph/relativize.ts"],"names":[],"mappings":"AAiBA,2BAA2B;AAC3B,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAO5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAoBtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAUpF"}