spectra-cli 4.2.0 → 4.3.0

package/dist/mcp/graph-tools.js

@@ -8,6 +8,8 @@ import { resolve } from 'node:path';
 import { z } from 'zod';
 import { GraphQueryEngine } from '../panoramic/graph/graph-query.js';
 import { resolveGraphJsonPath } from '../panoramic/graph/graph-paths.js';
+import { buildErrorResponse } from './lib/tool-response.js';
+import { withTelemetry } from './lib/telemetry.js';
 /** 按 projectRoot 缓存 GraphQueryEngine 实例 + graph.json stat 元数据 */
 const engineCache = new Map();
 /**
@@ -90,32 +92,58 @@ export function getCachedGraphData(projectRoot) {
             sizeBytes: stat.size,
         };
     }
-    catch {
+    catch (err) {
+        // Feature 193 FR-006：graph-format-stale 必须显式上抛，不得静默退化为 null
+        // （否则 impact/context/detect_changes 把"旧绝对格式图"误报成"缺图 graph-not-built"，
+        // agent 无法区分应重建 vs 应首次构建）。其余加载失败仍按既有契约返回 null。
+        if (err instanceof Error && err.message.includes('graph-format-stale')) {
+            throw err;
+        }
         return null;
     }
 }
+/** 判定一个 caught error 是否为加载期 graph-format-stale 信号（Feature 193 FR-006） */
+export function isGraphFormatStaleError(err) {
+    return err instanceof Error && err.message.includes('graph-format-stale');
+}
 // ──────────────────────────────────────────────────────────
-// 统一错误响应构建器
+// Feature 177 — 统一错误契约骨架（拆 engine 加载边界）
+//
+// 删除原本地 buildErrorResponse（返回旧 {error,hint} 契约），改用
+// lib/tool-response.ts 的统一 {code,message,hint?} 契约。
 // ──────────────────────────────────────────────────────────
 /**
- * 构建 MCP 错误响应
- * @param err - 错误对象或消息字符串
- * @param hint - 附加提示（可选）
+ * 6 个 graph 工具共享的执行骨架，拆分两类错误边界（spec AD-3 / Codex CRITICAL-1）：
+ *   - getEngine 失败（缺图 statSync ENOENT / 坏图 loadFromFile 解析失败）→ graph-not-built
+ *   - 加载成功后的查询期异常 → graph-query-failed
+ *
+ * 不靠 error message 内容猜分类（不稳定且可能泄露路径）。查询方法（query/getNode/
+ * findPath/getCommunity/getGodNodes/getHyperedges）操作纯内存 rawGraph：getCommunity
+ * 唯一的文件 IO（读 GRAPH_REPORT.md）已在 engine 内部 try/catch graceful 降级，不外抛，
+ * 故查询期 err.message 不含路径，保留以利诊断（与删除前的本地实现行为一致）。
+ *
+ * success 路径由 query 回调直接构造 envelope（保持原 JSON.stringify 形态，byte 兼容 AC-5）。
  */
-function buildErrorResponse(err, hint) {
-    const errorMessage = err instanceof Error ? err.message : String(err);
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify({
-                    error: errorMessage,
-                    hint: hint ?? '运行 `spectra graph` 先生成图谱',
-                }),
-            },
-        ],
-        isError: true,
-    };
+function runGraphTool(projectRoot, query) {
+    let engine;
+    try {
+        engine = getEngine(projectRoot);
+    }
+    catch (err) {
+        // Feature 193 FR-006：旧绝对格式图（copy 自其他 worktree）必须给明确 stale 信号，
+        // 不得静默退化为通用 graph-not-built（否则 agent 不知道是格式问题还是缺图）。
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('graph-format-stale')) {
+            return buildErrorResponse('graph-format-stale', msg, '当前 worktree 的图为旧绝对路径格式（可能 copy 自主仓/其他 worktree）。优先运行 `spectra batch --mode graph-only`（纯 AST · 零 LLM · <2min）在当前 worktree 重建图；或 `spectra batch` 重建完整图。');
+        }
+        return buildErrorResponse('graph-not-built', '图谱未构建或加载失败', '优先运行 `spectra batch --mode graph-only` 快速建图（纯 AST · 零 LLM · 无需认证 · <2min）；需要完整 spec 关系图再跑 `spectra batch`');
+    }
+    try {
+        return query(engine);
+    }
+    catch (err) {
+        return buildErrorResponse('graph-query-failed', err instanceof Error ? err.message : String(err));
+    }
 }
 // ──────────────────────────────────────────────────────────
 // 工具注册主函数
@@ -126,7 +154,14 @@ function buildErrorResponse(err, hint) {
  */
 export function registerGraphTools(server) {
     // ─── 工具 1: graph_query — 关键词子图查询 ───
-    server.tool('graph_query', '查询知识图谱中与问题相关的模块和依赖关系子图。适用于探索代码库结构、查找相关模块时调用。', {
+    server.tool('graph_query', `查询知识图谱中与问题相关的模块和依赖关系子图，探索代码库结构、查找相关模块。
+
+Use when:
+- 不清楚结构、想按关键词找相关模块子图
+- 需要某主题（如"认证"）的依赖关系概览
+
+Typical chained usage:
+- batch → graph_query → graph_node（子图定位后看单节点详情）`, {
         question: z.string().describe('自然语言查询词，例如"认证模块"、"数据库连接"'),
         budget: z
             .number()
@@ -144,20 +179,21 @@ export function registerGraphTools(server) {
             .string()
             .optional()
             .describe('目标项目根目录绝对路径（默认使用当前工作目录）'),
-    }, async ({ question, budget, mode, depth, projectRoot }) => {
-        try {
-            const engine = getEngine(projectRoot);
-            const result = engine.query(question, { budget, mode, depth });
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result) }],
-            };
-        }
-        catch (err) {
-            return buildErrorResponse(err);
-        }
-    });
+    }, withTelemetry('graph_query', (args) => {
+        const { question, budget, mode, depth, projectRoot } = args;
+        return runGraphTool(projectRoot, (engine) => ({
+            content: [{ type: 'text', text: JSON.stringify(engine.query(question, { budget, mode, depth })) }],
+        }));
+    }));
     // ─── 工具 2: graph_node — 单节点详情查询 ───
-    server.tool('graph_node', '精确查找节点详情和邻居，适用于已知节点 ID 或名称关键词的场景。id 参数优先于 keyword。返回结果包含关联的语义边（references / conceptually_related_to / rationale_for）列表。', {
+    server.tool('graph_node', `精确查找节点详情和邻居，适用于已知节点 ID 或名称关键词的场景。id 优先于 keyword，返回含语义边（references / conceptually_related_to / rationale_for）列表。
+
+Use when:
+- 已知 symbol id 或 label 关键词，要看其邻居与语义边
+- graph_query 命中后深入单节点
+
+Typical chained usage:
+- graph_query → graph_node → graph_path（节点详情后查调用路径）`, {
         id: z
             .string()
             .optional()
@@ -174,47 +210,47 @@ export function registerGraphTools(server) {
             .string()
             .optional()
             .describe('目标项目根目录绝对路径（默认使用当前工作目录）'),
-    }, async ({ id, keyword, budget, projectRoot }) => {
-        try {
-            const engine = getEngine(projectRoot);
+    }, withTelemetry('graph_node', (args) => {
+        const { id, keyword, budget, projectRoot } = args;
+        return runGraphTool(projectRoot, (engine) => {
             const result = engine.getNode({ id, keyword, budget });
             // 追加语义边列表（schema v2.0 新字段，向后兼容现有字段）
             const semanticEdges = engine.getSemanticEdges(result.node?.id);
             return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({ ...result, semanticEdges }),
-                    },
-                ],
+                content: [{ type: 'text', text: JSON.stringify({ ...result, semanticEdges }) }],
             };
-        }
-        catch (err) {
-            return buildErrorResponse(err);
-        }
-    });
+        });
+    }));
     // ─── 工具 3: graph_path — 最短路径查询 ───
-    server.tool('graph_path', '查找两个节点间的最短调用路径，适用于理解模块依赖链、追踪调用关系。', {
+    server.tool('graph_path', `查找两个节点间的最短调用路径，适用于理解模块依赖链、追踪调用关系。
+
+Use when:
+- 想知道 A 如何调用到 B
+- 追踪跨模块依赖链路
+
+Typical chained usage:
+- graph_node → graph_path（确定两端节点后查路径）`, {
         source: z.string().describe('源节点 ID（路径起点）'),
         target: z.string().describe('目标节点 ID（路径终点）'),
         projectRoot: z
             .string()
             .optional()
             .describe('目标项目根目录绝对路径（默认使用当前工作目录）'),
-    }, async ({ source, target, projectRoot }) => {
-        try {
-            const engine = getEngine(projectRoot);
-            const result = engine.findPath(source, target);
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result) }],
-            };
-        }
-        catch (err) {
-            return buildErrorResponse(err);
-        }
-    });
+    }, withTelemetry('graph_path', (args) => {
+        const { source, target, projectRoot } = args;
+        return runGraphTool(projectRoot, (engine) => ({
+            content: [{ type: 'text', text: JSON.stringify(engine.findPath(source, target)) }],
+        }));
+    }));
     // ─── 工具 4: graph_community — 社区节点查询 ───
-    server.tool('graph_community', '获取指定社区的节点列表，用于识别代码聚类和模块边界。需要先运行 spectra graph 生成含社区信息的图谱。', {
+    server.tool('graph_community', `获取指定社区的节点列表，用于识别代码聚类和模块边界。需先运行 spectra graph 生成含社区信息的图谱。
+
+Use when:
+- 想识别代码的自然聚类 / 模块边界
+- 分析高内聚低耦合结构
+
+Typical chained usage:
+- batch → graph_community → graph_node（聚类后看具体节点）`, {
         communityId: z.string().describe('社区 ID（来自 graph.json 中节点的 metadata.community 字段）'),
         budget: z
             .number()
@@ -224,20 +260,21 @@ export function registerGraphTools(server) {
             .string()
             .optional()
             .describe('目标项目根目录绝对路径（默认使用当前工作目录）'),
-    }, async ({ communityId, budget, projectRoot }) => {
-        try {
-            const engine = getEngine(projectRoot);
-            const result = engine.getCommunity(communityId, budget);
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result) }],
-            };
-        }
-        catch (err) {
-            return buildErrorResponse(err);
-        }
-    });
+    }, withTelemetry('graph_community', (args) => {
+        const { communityId, budget, projectRoot } = args;
+        return runGraphTool(projectRoot, (engine) => ({
+            content: [{ type: 'text', text: JSON.stringify(engine.getCommunity(communityId, budget)) }],
+        }));
+    }));
     // ─── 工具 6: graph_hyperedges — 超边查询 ───
-    server.tool('graph_hyperedges', '查询知识图谱中的超边（Hyperedges），每条超边连接 3 个以上节点，表达命名流程或跨模块协作关系。支持按 label 模糊过滤和按节点 ID 精确过滤。', {
+    server.tool('graph_hyperedges', `查询知识图谱中的超边（Hyperedges），每条连接 3+ 节点，表达命名流程或跨模块协作。支持按 label 模糊过滤和节点 ID 精确过滤。
+
+Use when:
+- 想看跨多模块的协作流程
+- 按 label 找某命名流程
+
+Typical chained usage:
+- graph_query → graph_hyperedges（子图后看多节点协作）`, {
         label: z
             .string()
             .optional()
@@ -254,41 +291,17 @@ export function registerGraphTools(server) {
             .string()
             .optional()
             .describe('目标项目根目录绝对路径（默认使用当前工作目录）'),
-    }, async ({ label, node_id, limit, projectRoot }) => {
-        // 额外校验：label 或 node_id 为空字符串时返回明确错误
+    }, withTelemetry('graph_hyperedges', (args) => {
+        const { label, node_id, limit, projectRoot } = args;
+        // 额外校验：label 或 node_id 为空字符串时返回明确错误（统一 invalid-input）
         if (label !== undefined && label.trim().length === 0) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            error: 'label 参数不能为空字符串，请传入有效的过滤词或省略此参数',
-                        }),
-                    },
-                ],
-                isError: true,
-            };
+            return buildErrorResponse('invalid-input', 'label 参数不能为空字符串，请传入有效的过滤词或省略此参数');
         }
         if (node_id !== undefined && node_id.trim().length === 0) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            error: 'node_id 参数不能为空字符串，请传入有效的节点 ID 或省略此参数',
-                        }),
-                    },
-                ],
-                isError: true,
-            };
+            return buildErrorResponse('invalid-input', 'node_id 参数不能为空字符串，请传入有效的节点 ID 或省略此参数');
         }
-        try {
-            const engine = getEngine(projectRoot);
-            const hyperedges = engine.getHyperedges({
-                label,
-                nodeId: node_id,
-                limit,
-            });
+        return runGraphTool(projectRoot, (engine) => {
+            const hyperedges = engine.getHyperedges({ label, nodeId: node_id, limit });
             const filtered = (label !== undefined && label.length > 0) || (node_id !== undefined && node_id.length > 0);
             return {
                 content: [
@@ -298,13 +311,17 @@ export function registerGraphTools(server) {
                     },
                 ],
             };
-        }
-        catch (err) {
-            return buildErrorResponse(err);
-        }
-    });
+        });
+    }));
     // ─── 工具 5: graph_god_nodes — 枢纽节点识别 ───
-    server.tool('graph_god_nodes', '识别知识图谱中度数最高的枢纽节点，用于定位过度耦合的核心模块、分析架构瓶颈。', {
+    server.tool('graph_god_nodes', `识别知识图谱中度数最高的枢纽节点，用于定位过度耦合的核心模块、分析架构瓶颈。
+
+Use when:
+- 找过度耦合的"上帝模块"
+- 架构瓶颈 / 重构优先级分析
+
+Typical chained usage:
+- graph_god_nodes → impact（枢纽节点再做影响面评估）`, {
         limit: z
             .number()
             .optional()
@@ -313,17 +330,11 @@ export function registerGraphTools(server) {
             .string()
             .optional()
             .describe('目标项目根目录绝对路径（默认使用当前工作目录）'),
-    }, async ({ limit, projectRoot }) => {
-        try {
-            const engine = getEngine(projectRoot);
-            const result = engine.getGodNodes(limit);
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result) }],
-            };
-        }
-        catch (err) {
-            return buildErrorResponse(err);
-        }
-    });
+    }, withTelemetry('graph_god_nodes', (args) => {
+        const { limit, projectRoot } = args;
+        return runGraphTool(projectRoot, (engine) => ({
+            content: [{ type: 'text', text: JSON.stringify(engine.getGodNodes(limit)) }],
+        }));
+    }));
 }
 //# sourceMappingURL=graph-tools.js.map

package/dist/mcp/graph-tools.js.map

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

package/dist/mcp/lib/file-nav-helpers.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Feature 171 — File Navigation 纯计算/IO helper（对标 response-helpers.ts，便于 ≥95% 单测）
+ *
+ * 把 view_file / search_in_file / list_directory 的全部可独立测试逻辑下沉到本模块，
+ * 让 file-nav-tools.ts 的 handler 保持薄编排。
+ *
+ * 🔴 路径安全（resolveSafePath）是 LFI 红线：词法 containment 先于 fs，realpath 穿透 symlink，
+ *    path.relative 防前缀碰撞，全部错误码脱敏（不回传绝对路径）。
+ */
+/** view_file 无定位参数时的默认窗口（对标 OpenHands 前 200 行） */
+export declare const DEFAULT_VIEW_WINDOW = 200;
+/** search_in_file 默认返回命中数 */
+export declare const DEFAULT_MAX_MATCHES = 50;
+/** maxMatches 安全上界（clamp） */
+export declare const MAX_MATCHES_CAP = 1000;
+/** 用户 pattern 长度上界（ReDoS 缓解：限制输入） */
+export declare const MAX_PATTERN_LENGTH = 200;
+/** contextLines 上界 */
+export declare const MAX_CONTEXT_LINES = 20;
+/** list_directory depth 上界 */
+export declare const MAX_DIR_DEPTH = 10;
+/** list_directory 单次最多返回条目（防超大目录灌爆 payload） */
+export declare const MAX_DIR_ENTRIES = 5000;
+/** path 参数长度上界（防超长 path 灌爆响应 / 异常输入） */
+export declare const MAX_PATH_LENGTH = 4096;
+/** 用户正则可搜索的内容字节上界（ReDoS 缓解：限制 regex 作用的输入规模） */
+export declare const MAX_REGEX_CONTENT_BYTES = 2000000;
+export type SafePathErrorCode = 'path-outside-root' | 'invalid-input' | 'file-not-found';
+export type SafePathResult = {
+    ok: true;
+    realPath: string;
+} | {
+    ok: false;
+    code: SafePathErrorCode;
+};
+/**
+ * 解析并校验用户路径在 projectRoot 内（含 symlink 穿透）。
+ *
+ * 判定顺序（FR-013，修 Codex PATH-CLASSIFICATION）：
+ *   1. NUL 字节 → invalid-input
+ *   2. realRoot = realpath(projectRoot)（projectRoot 自身 symlink 也解析）
+ *   3. 词法 containment（path.relative）→ 越界(含不存在)立即 path-outside-root，不触 fs
+ *   4. realpath 穿透候选 → ENOENT/error → file-not-found（脱敏）
+ *   5. realpath 后再 containment → symlink 逃逸 → path-outside-root
+ * posix-only（Windows 归一化 YAGNI）。
+ */
+export declare function resolveSafePath(projectRoot: string, userPath: string): SafePathResult;
+export interface FileSlice {
+    lines: string[];
+    startLine: number;
+    endLine: number;
+    totalLines: number;
+    truncated: boolean;
+}
+/**
+ * 将内容拆为行数组：按 \r?\n 切分；末尾换行不计为额外空行；空内容 → []。
+ */
+export declare function splitLines(content: string): string[];
+/**
+ * 按行区间切片，带行号前缀。无定位参数时返回前 defaultWindow 行 + truncated 标志。
+ * 区间端点被安全 clamp 到 [1, totalLines]，超界不抛错。
+ */
+export declare function sliceLines(content: string, opts?: {
+    startLine?: number;
+    endLine?: number;
+    defaultWindow?: number;
+}): FileSlice;
+/** UTF-8 byte / 4 的 token 代理（改名避开 token-counter.ts 的 estimateTokens 命名碰撞） */
+export declare function estimateUtf8ByteTokens(text: string): number;
+/** 二进制探测：前缀字节含 NUL 即判二进制 */
+export declare function isBinary(buf: Buffer): boolean;
+/** 把数值 clamp 到 [min, max]，非法值（NaN/缺省）回退 fallback；返回是否被 clamp */
+export declare function clampInt(value: number | undefined, min: number, max: number, fallback: number): {
+    value: number;
+    clamped: boolean;
+};
+export interface SearchMatch {
+    line: number;
+    text: string;
+    before: string[];
+    after: string[];
+}
+export type MatchResult = {
+    ok: true;
+    matches: SearchMatch[];
+    totalMatches: number;
+    returnedMatches: number;
+    warnings: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * ReDoS 启发式：探测高危结构，命中则拒绝。覆盖：
+ *   - 嵌套量词组后接量词/有界重复：(a+)+ / (.*)* / (a{1,99}){1,99}
+ *   - 量化的交替组：(a|a)+ / (a|b)*
+ * 非完整 ReDoS 证明（配合 pattern 长度 + content byte 上界，FR-005 明示）。
+ */
+export declare function isRiskyRegex(pattern: string): boolean;
+/**
+ * 在内容内逐行匹配 pattern，返回带上下文行的命中列表。
+ * 失败（空/超长/非法正则/高危正则）返回 { ok:false, reason }，由 handler 映射 invalid-input。
+ */
+export declare function matchInFile(content: string, pattern: string, opts?: {
+    isRegex?: boolean;
+    maxMatches?: number;
+    contextLines?: number;
+}): MatchResult;
+export interface DirEntry {
+    name: string;
+    type: 'file' | 'dir' | 'symlink';
+    size: number | null;
+}
+/**
+ * 列举目录条目（可递归 depth 层）。默认仅过滤 .git；includeIgnored=true 含 .git。
+ * 超 MAX_DIR_ENTRIES 截断并加 listing-truncated warning。readdir 失败的子目录静默跳过。
+ */
+export declare function buildDirListing(absDir: string, opts?: {
+    depth?: number;
+    includeIgnored?: boolean;
+    maxEntries?: number;
+}): {
+    entries: DirEntry[];
+    warnings: string[];
+};
+/** 生成 file-nav 工具的下一步引导（风格对齐 generateNextStepHint，闭环 view_file ↔ context） */
+export declare function buildFileNavHint(toolName: 'view_file' | 'search_in_file' | 'list_directory', data: Record<string, unknown>): string;
+//# sourceMappingURL=file-nav-helpers.d.ts.map

package/dist/mcp/lib/file-nav-helpers.d.ts.map

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