spectra-cli 4.1.1 → 4.3.0

package/dist/knowledge-graph/query-helpers.d.ts

@@ -0,0 +1,191 @@
+/**
+ * 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 type { GraphJSON, GraphEdge, GraphNode } from '../panoramic/graph/graph-types.js';
+/** BFS 方向语义 */
+export type BfsDirection = 'upstream' | 'downstream' | 'both';
+/** BFS 遍历输入选项 */
+export interface BfsTraverseOptions {
+    /** 遍历深度上限，0 表示不展开（仅返回 start node 自身的可达邻居计数为 0） */
+    depth: number;
+    /** 数值置信度阈值（0..1），按 link.confidenceScore >= minConfidence 过滤 */
+    minConfidence: number;
+    /** BFS 方向 */
+    direction: BfsDirection;
+    /** 输出节点上限（不含 start node），遍历前严格截断 */
+    budget: number;
+    /** 多 startId 共享 visited Set（detect_changes 跨 changedSymbol 共享），可选 */
+    sharedVisited?: Set<string>;
+    /** 用作 reverse adjacency cache key 的一部分 */
+    graphPath: string;
+    /** 用作 reverse adjacency cache key 的一部分（graph.json mtime） */
+    graphMtimeMs: number;
+    /** 用作 reverse adjacency cache key 的一部分（graph.json 字节数） */
+    graphSizeBytes: number;
+    /** 仅遍历指定 relation 的边（default ['calls']） */
+    relations?: ReadonlyArray<string>;
+}
+/** BFS 输出条目 */
+export interface BfsAffected {
+    id: string;
+    depth: number;
+    confidence: number;
+    reason: string;
+    /** 从 start 到 self 的 ancestor 链（含 self），可选用于自动化测试 */
+    path: string[];
+}
+/** BFS 输出 */
+export interface BfsTraverseResult {
+    affected: BfsAffected[];
+    warnings: string[];
+}
+/** 反向邻接表项 */
+interface ReverseAdjEntry {
+    sourceId: string;
+    edge: GraphEdge;
+}
+/** 反向邻接表（target id → 进入此节点的 inbound 边列表） */
+export type ReverseAdj = Map<string, ReverseAdjEntry[]>;
+/** baseRef / symbol id 不可见字符快速校验 */
+/**
+ * 解析一条边的 confidence 数值。
+ *
+ * 优先级：edge.confidenceScore（已含数字）→ edge.confidence 走 CONFIDENCE_SCORES 映射 → null。
+ *
+ * 返回 null 表示"无法判定 confidence"，调用方应跳过该边并记 warning。
+ */
+export declare function resolveEdgeConfidence(edge: GraphEdge): number | null;
+/**
+ * 把用户输入的 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 declare function canonicalizeSymbolId(rawTarget: string, graphData: Readonly<GraphJSON>, options?: {
+    projectRoot?: string;
+}): {
+    canonicalId: string | null;
+    reason: 'ok' | 'not-found' | 'invalid';
+};
+/** fuzzy match 命中层次 */
+export type MatchKind = 'exact' | 'path-suffix' | 'partial-name' | 'levenshtein';
+/** 单个 fuzzy match 候选结果 */
+export interface SymbolCandidate {
+    /** canonical symbol id */
+    id: string;
+    /** 置信度 0~1（各层规则见 resolveSymbolFuzzy 注释） */
+    confidence: number;
+    /** 命中层次 */
+    matchKind: MatchKind;
+}
+/** resolveSymbolFuzzy 返回值 */
+export interface FuzzyResolveResult {
+    /** 按 confidence 降序、长度 ≤ limit 的候选；去重后唯一且高分时触发 autoResolved */
+    candidates: SymbolCandidate[];
+    /** 去重后唯一候选且 confidence ≥ autoResolveThreshold(默认 0.9) 时为 true */
+    autoResolved: boolean;
+}
+/** resolveSymbolFuzzy 选项 */
+export interface FuzzyResolveOptions {
+    /** 透传给 canonicalizeSymbolId 做绝对↔相对路径归一 */
+    projectRoot?: string;
+    /** 纯函数内部候选上限（默认 10，测试可设更大值；handler 层另行 clamp 到 top-3） */
+    limit?: number;
+    /** 自动 resolve 阈值（默认 0.9；production handler floor 不得低于 0.9） */
+    autoResolveThreshold?: number;
+}
+/**
+ * 分层 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 declare function resolveSymbolFuzzy(graphData: Readonly<GraphJSON>, query: string, opts?: FuzzyResolveOptions): FuzzyResolveResult;
+/**
+ * 按 directCallers + transitive 节点数判定 risk tier。
+ *
+ * 阈值（spec FR-014）：
+ *   - directCallers ≥ 10 或 transitive ≥ 50 → high
+ *   - directCallers ≥ 3  或 transitive ≥ 15 → medium
+ *   - 其余 → low
+ */
+export declare function computeRiskTier(directCallers: number, transitive: number): 'low' | 'medium' | 'high';
+/**
+ * 获取（或构建）反向邻接表。
+ *
+ * direction 决定邻接方向：
+ *   - upstream：target → 进入此节点的 inbound 边（callers）
+ *   - downstream：source → 离开此节点的 outbound 边（callees）
+ *   - both：合并 inbound + outbound
+ *
+ * 仅保留 relation 在 relations 集合内的边；其他 relation 的边不进入邻接表。
+ */
+export declare function getReverseAdjacency(graphData: Readonly<GraphJSON>, graphPath: string, mtimeMs: number, sizeBytes: number, relations: ReadonlyArray<string>, direction: BfsDirection): ReverseAdj;
+/** 测试 / debug 用：清空 reverse adjacency cache */
+export declare function clearReverseAdjacencyCache(): void;
+/**
+ * 从 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 declare function bfsTraverse(graphData: Readonly<GraphJSON>, startId: string, options: BfsTraverseOptions): BfsTraverseResult;
+/**
+ * 取节点的 module file 部分。
+ *
+ * 兼容两种分隔符（同一个 graph 内可能并存）：
+ *   - Feature 151 新格式：`<file>::<symbolName>` 例 `micrograd/engine.py::Value.__add__`
+ *   - 旧 panoramic 格式：`<file>#<symbolName>` 例 `micrograd/engine.py#Value`
+ *
+ * 模块节点本身（id 既不含 `::` 也不含 `#`）→ 返回 id 自身。
+ * 取最早出现的分隔符位置作为 cut 点。
+ */
+export declare function moduleFileFromId(nodeId: string): string;
+/**
+ * 在 graph 中找指定 node 的 GraphNode 对象。
+ * O(n) — 仅小规模 graph 使用，调用频率不高（仅 context handler 的 definition 字段）。
+ */
+export declare function findNode(graphData: Readonly<GraphJSON>, id: string): GraphNode | null;
+export {};
+//# sourceMappingURL=query-helpers.d.ts.map

package/dist/knowledge-graph/query-helpers.d.ts.map

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