Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(mcp): add code_outline / code_search / code_expand tools (#2146)
AutoCoder9a37e753953e
diff --git a/docs/design/2026-05-20-code-tools-design.md b/docs/design/2026-05-20-code-tools-design.mdnew file mode 100644index 000000000..27e5f1ade--- /dev/null+++ b/docs/design/2026-05-20-code-tools-design.md@@ -0,0 +1,293 @@+# Code Tools MCP 集成设计文档++**日期**:2026-05-20+**范围**:向 OpenViking 新增 `code_outline`、`code_search`、`code_expand` 三个 MCP 工具++---++## 概述++三个新 MCP 工具通过 OpenViking 现有的 `@mcp.tool()` 端点向 AI Agent 暴露代码结构导航能力。典型使用顺序:++```+code_outline → 查看文件符号结构+code_search → 跨目录查找符号位置+code_expand → 展开完整实现代码+```++**仅支持 `viking://` URI**(不支持直接本地路径),与现有 `read`、`grep`、`list` 等工具保持一致,符合服务端既有安全边界(参见 `local_input_guard.py`:HTTP MCP 端拒绝直接的本地文件系统路径)。需要分析本地代码时,先用 `add_resource` 入库为 `viking://` 资源即可。++---++## 架构++```+mcp_endpoint.py+ ├── code_outline(uri) → openviking.parse.parsers.code.ast+ ├── code_search(query, uri) → openviking.parse.parsers.code.ast+ └── code_expand(uri, symbol) → openviking.parse.parsers.code.ast++openviking/parse/parsers/code/ast/+ ├── skeleton.py (修改:给 FunctionSig、ClassSkeleton 加行号字段)+ ├── extractor.py (修改:新增 extract() 返回 CodeSkeleton,extract_skeleton 复用之)+ ├── code_tools.py (新增:outline_file、search_symbols、expand_symbol)+ └── languages/+ ├── python.py (修改:读取 node.start_point / end_point)+ ├── js_ts.py (修改)+ ├── go.py (修改)+ ├── rust.py (修改)+ ├── java.py (修改)+ ├── cpp.py (修改:3 处函数提取路径都要改)+ └── ...+```++无新增依赖,使用已安装的 `tree-sitter` Python 绑定。++---++## 各组件改动说明++### 1. `skeleton.py` — 新增行号字段++给 `FunctionSig` 和 `ClassSkeleton` 加 `line_start`、`line_end`:++```python+@dataclass+class FunctionSig:+ name: str+ params: str+ return_type: str+ docstring: str+ line_start: int = 0 # 1-indexed,起始行(含)+ line_end: int = 0 # 1-indexed,结束行(含)++@dataclass+class ClassSkeleton:+ name: str+ bases: List[str]+ docstring: str+ methods: List[FunctionSig] = field(default_factory=list)+ line_start: int = 0+ line_end: int = 0+```++默认值 `0` 保持向后兼容,现有调用方(`extract_skeleton`、嵌入流水线)无需改动。++`to_text()` **不改**——它服务于 embedding/LLM 输入场景,行号会污染那条路径。outline 的展示由 `code_tools.outline_file()` 独立实现。++### 2. `extractor.py` — 新增 `extract()` 返回 `CodeSkeleton`++现有 `ASTExtractor.extract_skeleton()` 返回的是格式化文本字符串,不是 `CodeSkeleton` 对象。代码工具需要原始结构,因此在 `ASTExtractor` 上新增公开方法:++```python+def extract(self, file_name: str, content: str) -> Optional[CodeSkeleton]:+ """Return raw CodeSkeleton or None for unsupported/failed extraction."""+ lang = self._detect_language(file_name)+ extractor = self._get_extractor(lang)+ if extractor is None:+ return None+ try:+ return extractor.extract(file_name, content)+ except Exception as e:+ logger.warning(+ "AST extraction failed for '%s' (language: %s): %s", file_name, lang, e+ )+ return None+```++`extract_skeleton()` 重构为先调 `extract()`、再 `.to_text(verbose)`,逻辑完全等价。++### 3. 各语言提取器 — 读取节点行号++每个 `_extract_function` / `_extract_class` / `_extract_struct` 在构造 `FunctionSig` / `ClassSkeleton` 时多传两个参数:++```python+# tree-sitter node.start_point = (row, col),0-indexed+line_start = node.start_point[0] + 1+line_end = node.end_point[0] + 1+```++**特别注意 `cpp.py`**:该文件有三处函数构造路径——`_extract_function_declarator`、`_extract_function`、`_extract_function_proto`——三处都要传行号。其他语言每个文件改 2 处(函数 + 类/struct)即可。++### 4. `code_tools.py` — 新增模块++新建 `openviking/parse/parsers/code/ast/code_tools.py`,三个纯函数,无 I/O 无异步,输入字符串、返回格式化字符串。I/O 与逻辑分离便于独立测试。++```python+def outline_file(content: str, file_name: str) -> str:+ """返回源文件的符号结构(含行号、总行数)。+ 内部:ASTExtractor.extract() -> CodeSkeleton -> 专用 outline 格式器。"""++def search_symbols(query: str, files: list[tuple[str, str]]) -> str:+ """在多个 (content, file_name) 中搜索符号名包含 query 的符号+ (大小写不敏感子串匹配)。"""++def expand_symbol(content: str, file_name: str, symbol: str) -> str:+ """返回符号完整源码。symbol 支持两种形式:+ - 'foo' 匹配任意位置同名函数/类/方法+ - 'Foo.bar' 精确匹配 Foo 类下的 bar 方法+ 同名多个返回第一个;区分大小写。"""+```++### 5. `mcp_endpoint.py` — 新增三个工具++```python+async def code_outline(uri: str) -> str:+ """展示源文件的符号结构——类、函数、方法及其行号范围。+ uri 必须是 viking:// URI。"""++async def code_search(query: str, uri: str) -> str:+ """在 viking:// 目录下按名称搜索符号。query 对符号名做大小写不敏感+ 子串匹配,返回匹配符号及其文件位置和行号。最多扫描 200 个文件。+ uri 必填——不提供默认值以避免误扫整个 VikingFS。"""++async def code_expand(uri: str, symbol: str) -> str:+ """返回源文件中指定符号(函数、类或方法)的完整源码。+ symbol 支持 'bar' 和 'Foo.bar' 两种形式。"""+```++---++## URI 解析++仅处理 `viking://` URI,通过 `service.fs` 调用:++```+viking://resources/owner/repo/src/auth.py+ → service.fs.read(uri, ctx=ctx) # 文件内容++viking://resources/owner/repo/src/+ → service.fs.ls(uri, ctx=ctx, recursive=True, output="original")+ 返回 dict 列表,字段:name、isDir、uri(camelCase)+```++辅助函数 `_resolve_code_dir(uri, service, ctx)` 完成 ls + 按扩展名过滤 + 并发读取。++支持的扩展名(与 `extractor._EXT_MAP` 对齐):+`.py .js .jsx .ts .tsx .java .c .cpp .cc .h .hpp .rs .go .cs .php .lua`++---++## 数据流++### `code_outline(uri)`++```+uri+ → service.fs.read() → content+ → ASTExtractor.extract() → CodeSkeleton(或 None)+ → outline_file() → 格式化字符串+```++None 时直接返回 `"不支持的语言:{file_name}"` 或 `"解析 {file_name} 失败"`。++### `code_search(query, uri)`++```+uri(目录)+ → service.fs.ls(recursive=True, output="original")+ → 按扩展名过滤,截断到 200 个 → list[uri]+ → asyncio.gather + Semaphore(10) 并发 service.fs.read()+ → list[(content, file_name)]+ → 逐文件 ASTExtractor.extract() → list[CodeSkeleton]+ → search_symbols(query, ...) → 格式化字符串+```++并发模式参考已有 `read` 工具(`mcp_endpoint.py:290`)。解析失败的文件跳过、记录 warning,不中断整体搜索。++### `code_expand(uri, symbol)`++```+uri+ → service.fs.read() → content+ → ASTExtractor.extract() → CodeSkeleton+ → expand_symbol() → content 的 [line_start-1 : line_end] 行 + 位置标注+```++---++## 输出格式++### `code_outline`++`outline_file()` 不复用 `CodeSkeleton.to_text()`(那是嵌入流水线格式),自带格式器:++```+auth.py [Python, 120 lines]++imports: os, typing.Optional, fastapi.HTTPException++class AuthHandler L18-62+ + __init__(self, secret: str) L20-25+ + authenticate(self, token: str) -> Optional[User] L27-45+ + verify_scope(self, user: User, scope: str) -> bool L47-60++def get_handler() -> AuthHandler L65-70+```++- 头部行的语言名直接用 `CodeSkeleton.language`(Python/JavaScript/TypeScript 等,保留 `extractor` 已有 casing)+- 总行数由 `outline_file()` 内 `content.count("\n") + 1` 计算+- 不输出 docstring,行号是导航主信息++### `code_search`++```+2 matches for "authenticate" (scanned 47 files)++src/auth.py+ AuthHandler.authenticate L27-45+ authenticate_request L75-88+```++如果到达 200 文件上限,输出末尾追加 `(scanning stopped at 200-file cap; narrow uri to search more)`。++### `code_expand`++```+# src/auth.py L27-45++def authenticate(self, token: str) -> Optional[User]:+ payload = jwt.decode(token, self.secret)+ user_id = payload.get("sub")+ if not user_id:+ raise HTTPException(status_code=401)+ return db.get(User, user_id)+```++---++## 错误处理++| 场景 | 工具 | 返回内容 |+|------|------|---------|+| 不支持的语言(扩展名不在 `_EXT_MAP`) | outline / expand | `"不支持的语言:{file_name}"` |+| 不支持的语言 | search | 静默跳过该文件 |+| 解析失败 | outline / expand | `"解析 {file_name} 失败:{reason}"`(明确错误,**不** "继续") |+| 解析失败 | search | 记录 warning,跳过该文件,继续 |+| 符号未找到 | expand | `"在 {file_name} 中未找到符号 '{symbol}'"` |+| URI 不存在 | 全部 | 透传 `AGFSNotFoundError` 或 `FileNotFoundError` |+| 目录为空 / 无可解析文件 | search | `"在 {uri} 中未找到支持的源文件"` |+| 传入非 viking:// URI | 全部 | `"仅支持 viking:// URI;本地路径请先 add_resource"` |++---++## 涉及文件清单++| 文件 | 改动类型 |+|------|---------|+| `openviking/parse/parsers/code/ast/skeleton.py` | 新增 `line_start`、`line_end` 字段(默认 0) |+| `openviking/parse/parsers/code/ast/extractor.py` | 新增 `extract()` 返回 `CodeSkeleton`;`extract_skeleton` 重构复用之 |+| `openviking/parse/parsers/code/ast/languages/python.py` | 读取节点行号(2 处) |+| `openviking/parse/parsers/code/ast/languages/js_ts.py` | 读取节点行号(2 处) |+| `openviking/parse/parsers/code/ast/languages/go.py` | 读取节点行号(2 处:function、struct) |+| `openviking/parse/parsers/code/ast/languages/rust.py` | 读取节点行号(2 处) |+| `openviking/parse/parsers/code/ast/languages/java.py` | 读取节点行号(2 处) |+| `openviking/parse/parsers/code/ast/languages/cpp.py` | 读取节点行号(**3 处**:declarator、function、proto) |+| `openviking/parse/parsers/code/ast/languages/csharp.py` | 读取节点行号(2 处) |+| `openviking/parse/parsers/code/ast/languages/php.py` | 读取节点行号(2 处) |+| `openviking/parse/parsers/code/ast/languages/lua.py` | 读取节点行号(2 处) |+| `openviking/parse/parsers/code/ast/code_tools.py` | **新增文件** |+| `openviking/server/mcp_endpoint.py` | 新增 3 个工具 + viking:// 校验辅助 |diff --git a/openviking/parse/parsers/code/ast/code_tools.py b/openviking/parse/parsers/code/ast/code_tools.pynew file mode 100644index 000000000..4873b8623--- /dev/null+++ b/openviking/parse/parsers/code/ast/code_tools.py@@ -0,0 +1,183 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Pure I/O-free formatters powering the code_outline / code_search / code_expand+MCP tools. Inputs are source strings; outputs are agent-facing text.++The MCP layer handles all URI resolution and I/O; this module deals only with+content -> CodeSkeleton -> formatted text.+"""++from __future__ import annotations++from typing import Iterable, List, Optional, Tuple++from openviking.parse.parsers.code.ast.extractor import get_extractor+from openviking.parse.parsers.code.ast.skeleton import (+ CodeSkeleton,+ FunctionSig,+ _compact_params,+)+++def _line_span(item) -> str:+ if item.line_start and item.line_end:+ return f" L{item.line_start}-{item.line_end}"+ return ""+++def _format_function(fn: FunctionSig, indent: str, prefix: str) -> str:+ ret = f" -> {fn.return_type}" if fn.return_type else ""+ params = _compact_params(fn.params)+ return f"{indent}{prefix}{fn.name}({params}){ret}{_line_span(fn)}"+++def _outline_text(skeleton: CodeSkeleton, total_lines: int) -> str:+ lines: List[str] = [f"{skeleton.file_name} [{skeleton.language}, {total_lines} lines]"]+ if skeleton.module_doc:+ first = skeleton.module_doc.split("\n", 1)[0].strip()+ if first:+ lines.append(f'module: "{first}"')+ if skeleton.imports:+ lines.append(f"imports: {', '.join(skeleton.imports)}")+ lines.append("")++ for cls in skeleton.classes:+ bases = f"({', '.join(cls.bases)})" if cls.bases else ""+ lines.append(f"class {cls.name}{bases}{_line_span(cls)}")+ for method in cls.methods:+ lines.append(_format_function(method, " ", "+ "))+ lines.append("")++ for fn in skeleton.functions:+ lines.append(_format_function(fn, "", "def "))++ return "\n".join(lines).rstrip()+++def outline_file(content: str, file_name: str) -> str:+ """Return outline view of one source file (header + symbols + line spans).++ Returns an "Error: ..." sentinel string when the language is unsupported or+ parsing fails — callers can detect by the "Error:" prefix.+ """+ skeleton = get_extractor().extract(file_name, content)+ if skeleton is None:+ return _failure_message(file_name)+ total_lines = content.count("\n") + 1 if content else 0+ return _outline_text(skeleton, total_lines)+++def _failure_message(file_name: str) -> str:+ if not get_extractor().supports(file_name):+ return f"Error: unsupported language for {file_name}"+ return f"Error: failed to parse {file_name}"+++def _iter_symbols(skeleton: CodeSkeleton) -> Iterable[Tuple[str, int, int]]:+ """Yield (display_name, line_start, line_end) for every symbol."""+ for cls in skeleton.classes:+ yield cls.name, cls.line_start, cls.line_end+ for method in cls.methods:+ yield f"{cls.name}.{method.name}", method.line_start, method.line_end+ for fn in skeleton.functions:+ yield fn.name, fn.line_start, fn.line_end+++def search_symbols(query: str, files: List[Tuple[str, str]]) -> str:+ """Case-insensitive substring search across symbol names in many files.++ files: list of (content, file_name) tuples. Files whose language is+ unsupported or fails to parse are silently skipped (the caller already+ filtered by extension).+ """+ if not query:+ return "Error: empty query"++ needle = query.lower()+ extractor = get_extractor()+ scanned = 0+ hits_by_file: List[Tuple[str, List[Tuple[str, int, int]]]] = []+ total = 0++ for content, file_name in files:+ scanned += 1+ skeleton = extractor.extract(file_name, content)+ if skeleton is None:+ continue+ file_hits: List[Tuple[str, int, int]] = []+ for name, start, end in _iter_symbols(skeleton):+ tail = name.rsplit(".", 1)[-1]+ haystack = name.lower() if "." in needle else tail.lower()+ if needle in haystack:+ file_hits.append((name, start, end))+ if file_hits:+ hits_by_file.append((file_name, file_hits))+ total += len(file_hits)++ if total == 0:+ return f'No matches for "{query}" (scanned {scanned} files)'++ out: List[str] = [f'{total} matches for "{query}" (scanned {scanned} files)']+ for file_name, file_hits in hits_by_file:+ out.append("")+ out.append(file_name)+ for name, start, end in file_hits:+ span = f" L{start}-{end}" if start and end else ""+ out.append(f" {name}{span}")+ return "\n".join(out)+++def _resolve_symbol(+ skeleton: CodeSkeleton, symbol: str+) -> Optional[Tuple[str, int, int]]:+ """Find a symbol by 'foo' (bare) or 'Foo.bar' (qualified). Case sensitive.++ Search priority for bare names (no dot):+ 1. Top-level functions — exact name match+ 2. Classes — exact name match+ 3. Methods in any class — bare method name, first class that contains it wins+ (returns qualified display name "ClassName.method" so the caller knows+ where the method lives; use 'Foo.bar' to target a specific class)+ """+ if "." in symbol:+ cls_name, method_name = symbol.split(".", 1)+ for cls in skeleton.classes:+ if cls.name == cls_name:+ for method in cls.methods:+ if method.name == method_name:+ return f"{cls.name}.{method.name}", method.line_start, method.line_end+ return None++ for fn in skeleton.functions:+ if fn.name == symbol:+ return fn.name, fn.line_start, fn.line_end+ for cls in skeleton.classes:+ if cls.name == symbol:+ return cls.name, cls.line_start, cls.line_end+ for method in cls.methods:+ if method.name == symbol:+ return f"{cls.name}.{method.name}", method.line_start, method.line_end+ return None+++def expand_symbol(content: str, file_name: str, symbol: str) -> str:+ """Return the source for `symbol` from `content`, with a location header.++ Accepts 'foo' (any function/class/method named foo, first match wins) or+ 'Foo.bar' (method bar inside class Foo).+ """+ skeleton = get_extractor().extract(file_name, content)+ if skeleton is None:+ return _failure_message(file_name)++ match = _resolve_symbol(skeleton, symbol)+ if match is None:+ return f"Error: symbol '{symbol}' not found in {file_name}"++ display_name, start, end = match+ if not start or not end:+ return f"Error: symbol '{symbol}' found but line numbers unavailable in {file_name}"++ lines = content.splitlines()+ body = "\n".join(lines[start - 1 : end])+ return f"# {file_name} L{start}-{end} ({display_name})\n\n{body}"diff --git a/openviking/parse/parsers/code/ast/extractor.py b/openviking/parse/parsers/code/ast/extractor.pyindex e737cf02c..fee68b992 100644--- a/openviking/parse/parsers/code/ast/extractor.py+++ b/openviking/parse/parsers/code/ast/extractor.py@@ -89,17 +89,15 @@ class ASTExtractor:self._cache[lang] = Nonereturn None- def extract_skeleton(- self, file_name: str, content: str, verbose: bool = False- ) -> Optional[str]:- """Extract skeleton text from source code.+ def supports(self, file_name: str) -> bool:+ """True if the file extension maps to a known language (parsing may still fail)."""+ return self._detect_language(file_name) is not None- Returns None for unsupported languages or on extraction failure,- signalling the caller to fall back to LLM.+ def extract(self, file_name: str, content: str) -> Optional[CodeSkeleton]:+ """Return raw CodeSkeleton, or None for unsupported language / parse failure.- Args:- verbose: If True, include full docstrings (for ast_llm / LLM input).- If False, only first line of each docstring (for ast / embedding).+ Consumers that need the structured object (line numbers, traversal) call+ this; consumers that want the legacy formatted text use extract_skeleton."""lang = self._detect_language(file_name)extractor = self._get_extractor(lang)@@ -107,17 +105,30 @@ class ASTExtractor:return Nonetry:- skeleton: CodeSkeleton = extractor.extract(file_name, content)- return skeleton.to_text(verbose=verbose)+ return extractor.extract(file_name, content)except Exception as e:logger.warning(- "AST extraction failed for '%s' (language: %s), falling back to LLM: %s",- file_name,- lang,- e,+ "AST extraction failed for '%s' (language: %s): %s", file_name, lang, e)return None+ def extract_skeleton(+ self, file_name: str, content: str, verbose: bool = False+ ) -> Optional[str]:+ """Extract skeleton text from source code.++ Returns None for unsupported languages or on extraction failure,+ signalling the caller to fall back to LLM.++ Args:+ verbose: If True, include full docstrings (for ast_llm / LLM input).+ If False, only first line of each docstring (for ast / embedding).+ """+ skeleton = self.extract(file_name, content)+ if skeleton is None:+ return None+ return skeleton.to_text(verbose=verbose)+# Module-level singleton_extractor: Optional[ASTExtractor] = Nonediff --git a/openviking/parse/parsers/code/ast/languages/cpp.py b/openviking/parse/parsers/code/ast/languages/cpp.pyindex cb4a4bd2e..f548df9d6 100644--- a/openviking/parse/parsers/code/ast/languages/cpp.py+++ b/openviking/parse/parsers/code/ast/languages/cpp.py@@ -79,7 +79,14 @@ def _extract_function(node, content_bytes: bytes, docstring: str = "") -> Functiif sub.type == "function_declarator":name, params = _extract_function_declarator(sub, content_bytes)- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)+ return FunctionSig(+ name=name,+ params=params,+ return_type=return_type,+ docstring=docstring,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )def _extract_class(node, content_bytes: bytes, docstring: str = "") -> ClassSkeleton:@@ -127,11 +134,23 @@ def _extract_class(node, content_bytes: bytes, docstring: str = "") -> ClassSkeldoc = _preceding_doc(siblings, idx, content_bytes)methods.append(FunctionSig(- name=fn_name, params=fn_params, return_type=ret_type, docstring=doc+ name=fn_name,+ params=fn_params,+ return_type=ret_type,+ docstring=doc,+ line_start=child.start_point[0] + 1,+ line_end=child.end_point[0] + 1,))- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=methods)+ return ClassSkeleton(+ name=name,+ bases=bases,+ docstring=docstring,+ methods=methods,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )def _extract_typedef_struct(@@ -155,9 +174,11 @@ def _extract_typedef_struct(return Noneskeleton = _extract_class(struct_node, content_bytes, docstring=docstring)- # Prefer the typedef alias as the canonical name+ # Prefer the typedef alias as the canonical name; span the outer typedef.if typedef_name:skeleton.name = typedef_name+ skeleton.line_start = node.start_point[0] + 1+ skeleton.line_end = node.end_point[0] + 1return skeleton if skeleton.name else Nonediff --git a/openviking/parse/parsers/code/ast/languages/csharp.py b/openviking/parse/parsers/code/ast/languages/csharp.pyindex 7394e62e0..7c626a778 100644--- a/openviking/parse/parsers/code/ast/languages/csharp.py+++ b/openviking/parse/parsers/code/ast/languages/csharp.py@@ -98,7 +98,14 @@ def _extract_method(node, content_bytes: bytes, docstring: str = "") -> Functionif accessors:params = f"{{ {' '.join(accessors)} }}"- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)+ return FunctionSig(+ name=name,+ params=params,+ return_type=return_type,+ docstring=docstring,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )def _extract_class(node, content_bytes: bytes, docstring: str = "") -> ClassSkeleton:@@ -127,7 +134,14 @@ def _extract_class(node, content_bytes: bytes, docstring: str = "") -> ClassSkeldoc = _preceding_doc(siblings, idx, content_bytes)methods.append(_extract_method(child, content_bytes, docstring=doc))- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=methods)+ return ClassSkeleton(+ name=name,+ bases=bases,+ docstring=docstring,+ methods=methods,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )class CSharpExtractor(LanguageExtractor):diff --git a/openviking/parse/parsers/code/ast/languages/go.py b/openviking/parse/parsers/code/ast/languages/go.pyindex 7a61a2ea5..1f793d0fc 100644--- a/openviking/parse/parsers/code/ast/languages/go.py+++ b/openviking/parse/parsers/code/ast/languages/go.py@@ -50,7 +50,14 @@ def _extract_function(node, content_bytes: bytes, docstring: str = "") -> Functielif child.type == "type_identifier":return_type = _node_text(child, content_bytes)- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)+ return FunctionSig(+ name=name,+ params=params,+ return_type=return_type,+ docstring=docstring,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )def _extract_struct(node, content_bytes: bytes, docstring: str = "") -> ClassSkeleton:@@ -59,7 +66,14 @@ def _extract_struct(node, content_bytes: bytes, docstring: str = "") -> ClassSkeif child.type == "type_identifier":name = _node_text(child, content_bytes)break- return ClassSkeleton(name=name, bases=[], docstring=docstring, methods=[])+ return ClassSkeleton(+ name=name,+ bases=[],+ docstring=docstring,+ methods=[],+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )class GoExtractor(LanguageExtractor):diff --git a/openviking/parse/parsers/code/ast/languages/java.py b/openviking/parse/parsers/code/ast/languages/java.pyindex eec544be5..91a1e93ab 100644--- a/openviking/parse/parsers/code/ast/languages/java.py+++ b/openviking/parse/parsers/code/ast/languages/java.py@@ -61,7 +61,14 @@ def _extract_method(node, content_bytes: bytes, docstring: str = "") -> Functionraw = raw[1:-1]params = raw.strip()- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)+ return FunctionSig(+ name=name,+ params=params,+ return_type=return_type,+ docstring=docstring,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )def _extract_class(node, content_bytes: bytes, docstring: str = "") -> ClassSkeleton:@@ -93,7 +100,14 @@ def _extract_class(node, content_bytes: bytes, docstring: str = "") -> ClassSkeldoc = _preceding_doc(siblings, idx, content_bytes)methods.append(_extract_method(child, content_bytes, docstring=doc))- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=methods)+ return ClassSkeleton(+ name=name,+ bases=bases,+ docstring=docstring,+ methods=methods,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )class JavaExtractor(LanguageExtractor):diff --git a/openviking/parse/parsers/code/ast/languages/js_ts.py b/openviking/parse/parsers/code/ast/languages/js_ts.pyindex 424cc3c08..375ca7449 100644--- a/openviking/parse/parsers/code/ast/languages/js_ts.py+++ b/openviking/parse/parsers/code/ast/languages/js_ts.py@@ -90,7 +90,14 @@ def _extract_function(if not docstring:docstring = _first_string_in_body(body_node, content_bytes)- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)+ return FunctionSig(+ name=name,+ params=params,+ return_type=return_type,+ docstring=docstring,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )def _extract_class(@@ -138,7 +145,14 @@ def _extract_class(methods.append(fn)break- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=methods)+ return ClassSkeleton(+ name=name,+ bases=bases,+ docstring=docstring,+ methods=methods,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )class JsTsExtractor(LanguageExtractor):diff --git a/openviking/parse/parsers/code/ast/languages/lua.py b/openviking/parse/parsers/code/ast/languages/lua.pyindex dd1a01b8f..8af37e745 100644--- a/openviking/parse/parsers/code/ast/languages/lua.py+++ b/openviking/parse/parsers/code/ast/languages/lua.py@@ -125,10 +125,19 @@ class LuaExtractor(LanguageExtractor):params = _extract_params(params_node, content_bytes)+ fn_start = child.start_point[0] + 1+ fn_end = child.end_point[0] + 1if name_node.type == "identifier":name = _node_text(name_node, content_bytes)functions.append(- FunctionSig(name=name, params=params, return_type="", docstring=doc)+ FunctionSig(+ name=name,+ params=params,+ return_type="",+ docstring=doc,+ line_start=fn_start,+ line_end=fn_end,+ ))elif name_node.type in ("dot_index_expression", "method_index_expression"):# M.foo or M:foo — map to class method@@ -137,11 +146,25 @@ class LuaExtractor(LanguageExtractor):table_name = _node_text(id_children[0], content_bytes)method_name = _node_text(id_children[1], content_bytes)fn = FunctionSig(- name=method_name, params=params, return_type="", docstring=doc+ name=method_name,+ params=params,+ return_type="",+ docstring=doc,+ line_start=fn_start,+ line_end=fn_end,)if table_name not in _classes:_classes[table_name] = ClassSkeleton(- name=table_name, bases=[], docstring="", methods=[]+ name=table_name,+ bases=[],+ docstring="",+ methods=[],+ line_start=fn_start,+ line_end=fn_end,+ )+ else:+ _classes[table_name].line_end = max(+ _classes[table_name].line_end, fn_end)_classes[table_name].methods.append(fn)diff --git a/openviking/parse/parsers/code/ast/languages/php.py b/openviking/parse/parsers/code/ast/languages/php.pyindex e33e1d3bb..8b9df46d6 100644--- a/openviking/parse/parsers/code/ast/languages/php.py+++ b/openviking/parse/parsers/code/ast/languages/php.py@@ -187,7 +187,14 @@ def _extract_function_like(node, content_bytes: bytes, docstring: str = "") -> Fif return_type:break- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)+ return FunctionSig(+ name=name,+ params=params,+ return_type=return_type,+ docstring=docstring,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )def _extract_class(@@ -234,7 +241,14 @@ def _extract_class(doc = _preceding_doc(siblings, idx, content_bytes)methods.append(_extract_function_like(child, content_bytes, docstring=doc))- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=methods)+ return ClassSkeleton(+ name=name,+ bases=bases,+ docstring=docstring,+ methods=methods,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )def _dedup_keep_order(items: List[str]) -> List[str]:diff --git a/openviking/parse/parsers/code/ast/languages/python.py b/openviking/parse/parsers/code/ast/languages/python.pyindex af573a6b9..735e0f4ca 100644--- a/openviking/parse/parsers/code/ast/languages/python.py+++ b/openviking/parse/parsers/code/ast/languages/python.py@@ -51,7 +51,14 @@ def _extract_function(node, content_bytes: bytes) -> FunctionSig:body_node = childdocstring = _first_string_child(body_node, content_bytes)- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)+ return FunctionSig(+ name=name,+ params=params,+ return_type=return_type,+ docstring=docstring,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )def _extract_class(node, content_bytes: bytes) -> ClassSkeleton:@@ -82,7 +89,14 @@ def _extract_class(node, content_bytes: bytes) -> ClassSkeleton:if sub.type == "function_definition":methods.append(_extract_function(sub, content_bytes))- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=methods)+ return ClassSkeleton(+ name=name,+ bases=bases,+ docstring=docstring,+ methods=methods,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )def _extract_imports(node, content_bytes: bytes) -> List[str]:diff --git a/openviking/parse/parsers/code/ast/languages/rust.py b/openviking/parse/parsers/code/ast/languages/rust.pyindex 1dde6b99a..5b6eb6a69 100644--- a/openviking/parse/parsers/code/ast/languages/rust.py+++ b/openviking/parse/parsers/code/ast/languages/rust.py@@ -47,7 +47,14 @@ def _extract_function(node, content_bytes: bytes, docstring: str = "") -> Functielif child.type == "generic_type":return_type = _node_text(child, content_bytes)- return FunctionSig(name=name, params=params, return_type=return_type, docstring=docstring)+ return FunctionSig(+ name=name,+ params=params,+ return_type=return_type,+ docstring=docstring,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )def _extract_struct_or_trait(node, content_bytes: bytes, docstring: str = "") -> ClassSkeleton:@@ -62,7 +69,14 @@ def _extract_struct_or_trait(node, content_bytes: bytes, docstring: str = "") ->if sub.type == "type_identifier":bases.append(_node_text(sub, content_bytes))- return ClassSkeleton(name=name, bases=bases, docstring=docstring, methods=[])+ return ClassSkeleton(+ name=name,+ bases=bases,+ docstring=docstring,+ methods=[],+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )def _extract_impl(node, content_bytes: bytes) -> ClassSkeleton:@@ -80,7 +94,14 @@ def _extract_impl(node, content_bytes: bytes) -> ClassSkeleton:doc = _preceding_doc(siblings, idx, content_bytes)methods.append(_extract_function(sub, content_bytes, docstring=doc))- return ClassSkeleton(name=f"impl {name}", bases=[], docstring="", methods=methods)+ return ClassSkeleton(+ name=f"impl {name}",+ bases=[],+ docstring="",+ methods=methods,+ line_start=node.start_point[0] + 1,+ line_end=node.end_point[0] + 1,+ )class RustExtractor(LanguageExtractor):diff --git a/openviking/parse/parsers/code/ast/skeleton.py b/openviking/parse/parsers/code/ast/skeleton.pyindex 739e99f1e..260712482 100644--- a/openviking/parse/parsers/code/ast/skeleton.py+++ b/openviking/parse/parsers/code/ast/skeleton.py@@ -18,6 +18,8 @@ class FunctionSig:params: str # raw parameter string, e.g. "source, instruction, **kwargs"return_type: str # e.g. "ParseResult" or ""docstring: str # first line only+ line_start: int = 0 # 1-indexed, inclusive; 0 = unknown (back-compat)+ line_end: int = 0 # 1-indexed, inclusive; 0 = unknown@dataclass@@ -26,6 +28,8 @@ class ClassSkeleton:bases: List[str]docstring: strmethods: List[FunctionSig] = field(default_factory=list)+ line_start: int = 0+ line_end: int = 0@dataclassdiff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.pyindex f66171f81..1d76b2ff3 100644--- a/openviking/server/mcp_endpoint.py+++ b/openviking/server/mcp_endpoint.py@@ -3,7 +3,8 @@"""MCP (Model Context Protocol) endpoint for OpenViking server.Exposes tools to Claude Code (or any MCP client) via streamable HTTP:- find, search, read, list, remember, add_resource, grep, glob, forget, health+ find, search, read, list, remember, add_resource, grep, glob,+ code_outline, code_search, code_expand, forget, healthMounted on the FastAPI app at /mcp. The MCP session manager lifecycle istied to the FastAPI app lifespan (not a sub-app lifespan) so the task group@@ -15,6 +16,7 @@ are extracted from HTTP request scope and propagated via contextvars.from __future__ import annotations+import asyncioimport contextvarsimport osfrom contextlib import asynccontextmanager@@ -29,6 +31,12 @@ from starlette.requests import Requestfrom starlette.responses import JSONResponsefrom starlette.types import ASGIApp, Receive, Scope, Send+from openviking.parse.parsers.code.ast.code_tools import (+ expand_symbol,+ outline_file,+ search_symbols,+)+from openviking.parse.parsers.code.ast.extractor import get_extractorfrom openviking.server.auth import resolve_identityfrom openviking.server.dependencies import get_server_config, get_servicefrom openviking.server.identity import RequestContext@@ -784,6 +792,152 @@ async def forget(uri: str, recursive: bool = False) -> str:return f"Deleted: {uri}"+# -- code navigation -------------------------------------------------------++_CODE_SEARCH_FILE_CAP = 200+_CODE_SEARCH_CONCURRENCY = 10+++def _require_viking_uri(uri: str) -> Optional[str]:+ """Return error message if uri is not a viking:// URI, else None."""+ if not isinstance(uri, str) or not uri.startswith("viking://"):+ return (+ "Error: only viking:// URIs are supported; "+ "use add_resource to ingest local code as a viking:// resource first."+ )+ return None+++def _entry_field(entry, key: str, fallback_key: str, default):+ """ls entries are dicts (camelCase) or objects (snake_case); read both."""+ if isinstance(entry, dict):+ return entry.get(key, default)+ return getattr(entry, fallback_key, default)+++def _filter_code_uris(entries) -> tuple[list[str], bool]:+ """Pick file entries whose extension is supported by the AST extractor, capped.++ Returns (uris, capped) where capped is True when the 200-file limit was hit+ and there may be more matching files beyond the cap.+ """+ extractor = get_extractor()+ uris: list[str] = []+ for e in entries:+ is_dir = _entry_field(e, "isDir", "is_dir", False)+ if is_dir:+ continue+ entry_uri = _entry_field(e, "uri", "uri", "")+ if not entry_uri:+ continue+ if extractor.supports(entry_uri):+ uris.append(entry_uri)+ if len(uris) > _CODE_SEARCH_FILE_CAP:+ return uris[:_CODE_SEARCH_FILE_CAP], True+ return uris, False+++async def code_outline(uri: str) -> str:+ """Show a file's symbol structure — classes, functions, methods, and their line ranges.+ Returns a structural map without reading implementation bodies.++ Use to survey a file before deciding what to read. More efficient than reading the whole+ file when you only need to locate a method or understand a file's API surface.+ Typical workflow: code_search → code_outline → code_expand.++ uri must be a viking:// file URI (not a directory)."""+ err = _require_viking_uri(uri)+ if err:+ return err+ service = get_service()+ ctx = _get_ctx()+ try:+ content = await service.fs.read(uri, ctx=ctx)+ except Exception as exc:+ return f"Error: failed to read {uri}: {exc}"+ if not isinstance(content, str):+ return f"Error: {uri} is not text"+ return outline_file(content, uri)+++async def code_search(query: str, uri: str) -> str:+ """Search symbol names (class / function / method) by substring across a viking://+ directory. Returns structured results: symbol type, class context, file URI, line range.++ Use when you don't know which file contains the symbol you're looking for. Returns+ structural context (class ownership, location) that raw text search does not provide.++ Skip if you already know the exact file; use code_outline or Read directly.++ Scans up to 200 source files. Narrow uri to a subdirectory for deeper coverage.+ uri is required to avoid accidentally walking the entire VikingFS."""+ err = _require_viking_uri(uri)+ if err:+ return err+ if not query:+ return "Error: empty query"++ service = get_service()+ ctx = _get_ctx()+ try:+ entries = await service.fs.ls(uri, ctx=ctx, recursive=True, output="original")+ except Exception as exc:+ return f"Error: failed to list {uri}: {exc}"++ code_uris, capped = _filter_code_uris(entries or [])+ if not code_uris:+ return f"No supported source files found under {uri}"++ semaphore = asyncio.Semaphore(_CODE_SEARCH_CONCURRENCY)++ async def _read(u: str) -> Optional[tuple[str, str]]:+ async with semaphore:+ try:+ body = await service.fs.read(u, ctx=ctx)+ except Exception as exc:+ logger.warning("code_search: read failed for %s: %s", u, exc)+ return None+ if isinstance(body, str):+ return body, u+ return None++ fetched = await asyncio.gather(*[_read(u) for u in code_uris])+ files = [pair for pair in fetched if pair is not None]+ result = search_symbols(query, files)+ if capped:+ result += "\n\n(scanning stopped at 200-file cap; narrow uri to search more)"+ return result+++async def code_expand(uri: str, symbol: str) -> str:+ """Return the full source of a single named symbol (function, class, or method).+ Reads only that symbol's body, avoiding the overhead of reading an entire file.++ Use when you need the implementation of one specific symbol. For reading multiple+ symbols from the same file, Read is often more efficient.++ `symbol` accepts 'bar' (top-level) or 'Foo.bar' (method).+ uri must be a viking:// file URI."""+ err = _require_viking_uri(uri)+ if err:+ return err+ if not symbol:+ return "Error: empty symbol"++ service = get_service()+ ctx = _get_ctx()+ try:+ content = await service.fs.read(uri, ctx=ctx)+ except Exception as exc:+ return f"Error: failed to read {uri}: {exc}"+ if not isinstance(content, str):+ return f"Error: {uri} is not text"+ return expand_symbol(content, uri, symbol)++# -- health ----------------------------------------------------------------@@ -807,7 +961,7 @@ async def mcp_lifespan():"""Run the MCP session manager. Call this inside the FastAPI lifespan."""async with mcp.session_manager.run():logger.info(- "MCP endpoint ready (10 tools: find, search, read, list, remember, add_resource, grep, glob, forget, health)"+ "MCP endpoint ready (13 tools: find, search, read, list, remember, add_resource, grep, glob, code_outline, code_search, code_expand, forget, health)")yielddiff --git a/tests/mcp_benchmark/server.py b/tests/mcp_benchmark/server.pynew file mode 100644index 000000000..1eee86883--- /dev/null+++ b/tests/mcp_benchmark/server.py@@ -0,0 +1,228 @@+"""Minimal stdio MCP server that exposes the 3 new code-navigation tools+backed by the *actual* code_tools / extractor modules from the OpenViking+repo. Stubs the heavy openviking dependencies (pyagfs, etc.) and maps+viking:// URIs to local disk so we can drive an end-to-end MCP test+without building the full openviking stack.++URI scheme:+ viking://local/<ABSOLUTE-PATH> -> /<ABSOLUTE-PATH> on local disk++This is *only* for the end-to-end MCP verification. Production runs through+openviking.server.mcp_endpoint with the real VikingFS.+"""+from __future__ import annotations++import asyncio+import importlib.util+import logging+import os+import sys+import types+from pathlib import Path+from typing import Optional++ROOT = Path(__file__).parent.parent.parent++# Stub openviking_cli.utils.get_logger so extractor.py imports cleanly.+ovc = types.ModuleType("openviking_cli")+ovc_utils = types.ModuleType("openviking_cli.utils")+ovc_utils.get_logger = lambda name: logging.getLogger(name)+sys.modules["openviking_cli"] = ovc+sys.modules["openviking_cli.utils"] = ovc_utils++for pkg in (+ "openviking",+ "openviking.parse",+ "openviking.parse.parsers",+ "openviking.parse.parsers.code",+ "openviking.parse.parsers.code.ast",+ "openviking.parse.parsers.code.ast.languages",+):+ m = types.ModuleType(pkg)+ m.__path__ = []+ sys.modules[pkg] = m+++def _load(name: str, rel: str):+ spec = importlib.util.spec_from_file_location(name, ROOT / rel)+ mod = importlib.util.module_from_spec(spec)+ sys.modules[name] = mod+ spec.loader.exec_module(mod)+ return mod+++_load("openviking.parse.parsers.code.ast.skeleton",+ "openviking/parse/parsers/code/ast/skeleton.py")+_load("openviking.parse.parsers.code.ast.languages.base",+ "openviking/parse/parsers/code/ast/languages/base.py")+_load("openviking.parse.parsers.code.ast.languages.python",+ "openviking/parse/parsers/code/ast/languages/python.py")+_load("openviking.parse.parsers.code.ast.extractor",+ "openviking/parse/parsers/code/ast/extractor.py")+_load("openviking.parse.parsers.code.ast.code_tools",+ "openviking/parse/parsers/code/ast/code_tools.py")++from openviking.parse.parsers.code.ast.code_tools import ( # noqa: E402+ expand_symbol,+ outline_file,+ search_symbols,+)+from openviking.parse.parsers.code.ast.extractor import get_extractor # noqa: E402++from mcp.server.fastmcp import FastMCP # noqa: E402++logger = logging.getLogger("openviking_mcp_test")++mcp = FastMCP("openviking-code-tools-test")++_VIKING_PREFIX = "viking://local"+_CODE_SEARCH_FILE_CAP = 200+_CODE_SEARCH_CONCURRENCY = 10+++def _uri_to_path(uri: str) -> Optional[Path]:+ """Map viking://local/<abs-path> -> Path('<abs-path>'). None on bad URI."""+ if not isinstance(uri, str) or not uri.startswith(_VIKING_PREFIX):+ return None+ rest = uri[len(_VIKING_PREFIX):]+ if not rest.startswith("/"):+ return None+ return Path(rest)+++def _require_viking_uri(uri: str) -> Optional[str]:+ if not isinstance(uri, str) or not uri.startswith("viking://"):+ return (+ "Error: only viking:// URIs are supported; "+ "use add_resource to ingest local code as a viking:// resource first."+ )+ return None+++async def _read_text(uri: str) -> tuple[Optional[str], Optional[str]]:+ """Returns (content, error_msg). Content is None iff error_msg is set."""+ path = _uri_to_path(uri)+ if path is None:+ return None, f"Error: {uri} is not a viking://local URI in this test server"+ try:+ return await asyncio.to_thread(path.read_text, encoding="utf-8"), None+ except FileNotFoundError as exc:+ return None, f"Error: failed to read {uri}: {exc}"+ except UnicodeDecodeError:+ return None, f"Error: {uri} is not text"+ except Exception as exc:+ return None, f"Error: failed to read {uri}: {exc}"+++async def _walk(uri: str) -> tuple[Optional[list[str]], Optional[str]]:+ """Recursively list viking:// URIs under a directory. Returns (uris, error)."""+ root = _uri_to_path(uri)+ if root is None or not root.is_dir():+ return None, f"Error: failed to list {uri}: not a directory"+ found: list[str] = []+ try:+ def _scan() -> list[str]:+ out: list[str] = []+ for p in root.rglob("*"):+ if p.is_file():+ out.append(f"{_VIKING_PREFIX}{p}")+ return out+ found = await asyncio.to_thread(_scan)+ return found, None+ except Exception as exc:+ return None, f"Error: failed to list {uri}: {exc}"+++async def code_outline(uri: str) -> str:+ """Show a file's symbol structure — classes, functions, methods, and their line ranges.+ Returns a structural map without reading implementation bodies.++ Use to survey a file before deciding what to read. More efficient than reading the whole+ file when you only need to locate a method or understand a file's API surface.+ Typical workflow: code_search → code_outline → code_expand.++ uri must be a viking://local file URI in this test server."""+ err = _require_viking_uri(uri)+ if err:+ return err+ content, err = await _read_text(uri)+ if err:+ return err+ return outline_file(content, uri)+++async def code_search(query: str, uri: str) -> str:+ """Search symbol names (class / function / method) by substring across a viking://local directory.+ Returns structured results: symbol type, class context, file URI, and line range.++ Use when you don't know which file contains the symbol you're looking for. Returns+ structural context (class ownership, location) that raw text search does not provide.++ Skip if you already know the exact file; use code_outline or Read directly.++ Scans up to 200 source files. Narrow uri to a subdirectory for deeper coverage."""+ err = _require_viking_uri(uri)+ if err:+ return err+ if not query:+ return "Error: empty query"++ all_uris, err = await _walk(uri)+ if err:+ return err++ extractor = get_extractor()+ code_uris: list[str] = []+ for u in all_uris or []:+ if extractor.supports(u):+ code_uris.append(u)+ if len(code_uris) >= _CODE_SEARCH_FILE_CAP:+ break++ if not code_uris:+ return f"No supported source files found under {uri}"++ capped = len(code_uris) >= _CODE_SEARCH_FILE_CAP+ sem = asyncio.Semaphore(_CODE_SEARCH_CONCURRENCY)++ async def _fetch(u: str):+ async with sem:+ body, ferr = await _read_text(u)+ if ferr:+ logger.warning("code_search: %s", ferr)+ return None+ return body, u++ fetched = await asyncio.gather(*[_fetch(u) for u in code_uris])+ files = [pair for pair in fetched if pair is not None]+ result = search_symbols(query, files)+ if capped:+ result += "\n\n(scanning stopped at 200-file cap; narrow uri to search more)"+ return result+++async def code_expand(uri: str, symbol: str) -> str:+ """Return the full source of a single named symbol (function, class, or method).+ Reads only that symbol's body, avoiding the overhead of reading an entire file.++ Use when you need the implementation of one specific symbol. For reading multiple+ symbols from the same file, Read is often more efficient.++ `symbol` accepts 'bar' (top-level) or 'Foo.bar' (method).+ uri must be a viking://local file URI in this test server."""+ err = _require_viking_uri(uri)+ if err:+ return err+ if not symbol:+ return "Error: empty symbol"+ content, err = await _read_text(uri)+ if err:+ return err+ return expand_symbol(content, uri, symbol)+++if __name__ == "__main__":+ mcp.run()diff --git a/tests/parse/run_code_tests.py b/tests/parse/run_code_tests.pynew file mode 100644index 000000000..091ef69a8--- /dev/null+++ b/tests/parse/run_code_tests.py@@ -0,0 +1,62 @@+#!/usr/bin/env python3+"""Run tests/parse/test_code_tools.py without the full openviking dependency stack.++Uses the same stub-then-load pattern as tests/mcp_benchmark/server.py.+"""+import importlib.util+import logging+import sys+import types+from pathlib import Path++ROOT = Path(__file__).parent.parent.parent++# Stub openviking_cli so extractor.py imports cleanly.+ovc = types.ModuleType("openviking_cli")+ovc_utils = types.ModuleType("openviking_cli.utils")+ovc_utils.get_logger = lambda name: logging.getLogger(name)+sys.modules["openviking_cli"] = ovc+sys.modules["openviking_cli.utils"] = ovc_utils++# Stub the openviking package hierarchy so __init__.py files are skipped.+for pkg in (+ "openviking",+ "openviking.parse",+ "openviking.parse.parsers",+ "openviking.parse.parsers.code",+ "openviking.parse.parsers.code.ast",+ "openviking.parse.parsers.code.ast.languages",+):+ m = types.ModuleType(pkg)+ m.__path__ = [str(ROOT / pkg.replace(".", "/"))]+ sys.modules[pkg] = m+++def _load(name: str, rel: str):+ spec = importlib.util.spec_from_file_location(name, ROOT / rel)+ mod = importlib.util.module_from_spec(spec)+ sys.modules[name] = mod+ spec.loader.exec_module(mod)+ return mod+++_load("openviking.parse.parsers.code.ast.skeleton",+ "openviking/parse/parsers/code/ast/skeleton.py")+_load("openviking.parse.parsers.code.ast.languages.base",+ "openviking/parse/parsers/code/ast/languages/base.py")+for lang in ("python", "js_ts", "go", "rust", "java", "cpp", "csharp", "php", "lua"):+ _load(f"openviking.parse.parsers.code.ast.languages.{lang}",+ f"openviking/parse/parsers/code/ast/languages/{lang}.py")+_load("openviking.parse.parsers.code.ast.extractor",+ "openviking/parse/parsers/code/ast/extractor.py")+_load("openviking.parse.parsers.code.ast.code_tools",+ "openviking/parse/parsers/code/ast/code_tools.py")++if __name__ == "__main__":+ import pytest+ sys.exit(pytest.main([+ str(Path(__file__).parent / "test_code_tools.py"),+ "--noconftest",+ "-o", "addopts=",+ "-v",+ ] + sys.argv[1:]))diff --git a/tests/parse/test_code_tools.py b/tests/parse/test_code_tools.pynew file mode 100644index 000000000..55a2333b2--- /dev/null+++ b/tests/parse/test_code_tools.py@@ -0,0 +1,381 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Tests for the code-navigation pure functions backing the+code_outline / code_search / code_expand MCP tools."""++from openviking.parse.parsers.code.ast.code_tools import (+ expand_symbol,+ outline_file,+ search_symbols,+)+from openviking.parse.parsers.code.ast.extractor import get_extractor+++PY_SAMPLE = '''"""Module top doc."""++import os+from typing import List+++class Greeter:+ """Greets people."""++ def __init__(self, name: str):+ self.name = name++ def greet(self, who: str) -> str:+ """Return a greeting."""+ return f"Hello {who} from {self.name}"+++def make_greeter(name: str) -> Greeter:+ return Greeter(name)+'''+++# ---------------------------------------------------------------------------+# Line numbers populated by extractors+# ---------------------------------------------------------------------------+++class TestLineNumbers:+ def test_python_class_and_method_lines(self):+ skel = get_extractor().extract("greeter.py", PY_SAMPLE)+ assert skel is not None+ assert len(skel.classes) == 1+ cls = skel.classes[0]+ assert cls.name == "Greeter"+ # Class spans from `class Greeter:` to end of greet body+ assert cls.line_start == 7+ assert cls.line_end >= 15++ method_names = [m.name for m in cls.methods]+ assert "__init__" in method_names+ assert "greet" in method_names++ greet = next(m for m in cls.methods if m.name == "greet")+ assert greet.line_start == 13+ assert greet.line_end == 15++ def test_python_top_level_function_lines(self):+ skel = get_extractor().extract("greeter.py", PY_SAMPLE)+ assert len(skel.functions) == 1+ fn = skel.functions[0]+ assert fn.name == "make_greeter"+ assert fn.line_start == 18+ assert fn.line_end == 19++ def test_unsupported_language_returns_none(self):+ assert get_extractor().extract("readme.md", "# hello") is None+++GO_SAMPLE = """\+package main++type Greeter struct {+\tName string+}++func (g *Greeter) Greet(who string) string {+\treturn "Hello " + who+}++func MakeGreeter(name string) *Greeter {+\treturn &Greeter{Name: name}+}+"""++TS_SAMPLE = """\+class Greeter {+ name: string;+ constructor(name: string) {+ this.name = name;+ }+ greet(who: string): string {+ return `Hello ${who}`;+ }+}++function makeGreeter(name: string): Greeter {+ return new Greeter(name);+}+"""++RS_SAMPLE = """\+pub struct Greeter {+ pub name: String,+}++impl Greeter {+ pub fn greet(&self, who: &str) -> String {+ format!("Hello {}", who)+ }+}++pub fn make_greeter(name: String) -> Greeter {+ Greeter { name }+}+"""++JAVA_SAMPLE = """\+public class Greeter {+ private String name;++ public Greeter(String name) {+ this.name = name;+ }++ public String greet(String who) {+ return "Hello " + who;+ }+}+"""++CPP_SAMPLE = """\+#include <string>++class Greeter {+public:+ std::string greet(const std::string& who) {+ return "Hello " + who;+ }+};+"""++CS_SAMPLE = """\+public class Greeter {+ public string Name { get; set; }+ public string Greet(string who) {+ return "Hello " + who;+ }+}+"""++PHP_SAMPLE = """\+<?php++class Greeter {+ public $name;+ public function greet($who) {+ return "Hello $who";+ }+}++function makeGreeter($name) {+ return new Greeter();+}+"""++LUA_SAMPLE = """\+function Greeter:greet(who)+ return "Hello " .. who+end++function makeGreeter(name)+ return name+end+"""++_LANG_SAMPLES = [+ ("greeter.go", GO_SAMPLE, "Go"),+ ("greeter.ts", TS_SAMPLE, "TypeScript"),+ ("greeter.rs", RS_SAMPLE, "Rust"),+ ("Greeter.java", JAVA_SAMPLE, "Java"),+ ("greeter.cpp", CPP_SAMPLE, "C++"),+ ("Greeter.cs", CS_SAMPLE, "C#"),+ ("greeter.php", PHP_SAMPLE, "PHP"),+ ("greeter.lua", LUA_SAMPLE, "Lua"),+]+++class TestLineNumbersAllLanguages:+ """Regression: every language extractor must populate non-zero line numbers.++ Prior to this commit all extractors left line_start/line_end at the default+ of 0. These tests ensure the node.start_point / end_point wiring is correct+ for each supported language by asserting that every class and function in the+ sample snippet carries a positive, ordered span.+ """++ def _check_non_zero(self, file_name: str, src: str, lang_name: str):+ import pytest++ ext = get_extractor()+ if not ext.supports(file_name):+ pytest.skip(f"tree-sitter grammar for {lang_name} not installed")+ skel = ext.extract(file_name, src)+ assert skel is not None, f"{lang_name}: parse returned None"++ symbols = []+ for cls in skel.classes:+ symbols.append((f"class {cls.name}", cls.line_start, cls.line_end))+ for m in cls.methods:+ symbols.append((f"{cls.name}.{m.name}", m.line_start, m.line_end))+ for fn in skel.functions:+ symbols.append((f"fn {fn.name}", fn.line_start, fn.line_end))++ assert symbols, f"{lang_name}: no symbols extracted"+ for sym, start, end in symbols:+ assert start > 0, f"{lang_name} {sym}: line_start is 0 (not populated)"+ assert end >= start, f"{lang_name} {sym}: line_end {end} < line_start {start}"++ def test_go_line_numbers(self):+ self._check_non_zero("greeter.go", GO_SAMPLE, "Go")++ def test_typescript_line_numbers(self):+ self._check_non_zero("greeter.ts", TS_SAMPLE, "TypeScript")++ def test_rust_line_numbers(self):+ self._check_non_zero("greeter.rs", RS_SAMPLE, "Rust")++ def test_java_line_numbers(self):+ self._check_non_zero("Greeter.java", JAVA_SAMPLE, "Java")++ def test_cpp_line_numbers(self):+ self._check_non_zero("greeter.cpp", CPP_SAMPLE, "C++")++ def test_csharp_line_numbers(self):+ self._check_non_zero("Greeter.cs", CS_SAMPLE, "C#")++ def test_php_line_numbers(self):+ self._check_non_zero("greeter.php", PHP_SAMPLE, "PHP")++ def test_lua_line_numbers(self):+ self._check_non_zero("greeter.lua", LUA_SAMPLE, "Lua")+++# ---------------------------------------------------------------------------+# outline_file+# ---------------------------------------------------------------------------+++class TestOutlineFile:+ def test_outline_python(self):+ out = outline_file(PY_SAMPLE, "greeter.py")+ assert out.startswith("greeter.py [Python,")+ assert "20 lines" in out # 19 newlines + 1+ assert "imports: os, typing.List" in out+ assert 'module: "Module top doc."' in out+ assert "class Greeter L7-" in out+ assert "+ __init__(self, name: str) L10-11" in out+ assert "+ greet(self, who: str) -> str L13-15" in out+ assert "def make_greeter(name: str) -> Greeter L18-19" in out+ # outline must not leak docstrings (it's a navigation view)+ assert '"""' not in out+ assert "Return a greeting" not in out++ def test_outline_empty_file(self):+ # Empty content: no symbols, but the header should still appear+ out = outline_file("", "empty.py")+ assert out.startswith("empty.py [Python,")+ # 0 newlines + 1 = 1 line in our convention; tolerated either way+ assert "lines]" in out++ def test_outline_unsupported_language(self):+ out = outline_file("# nothing", "notes.md")+ assert out == "Error: unsupported language for notes.md"+++# ---------------------------------------------------------------------------+# search_symbols+# ---------------------------------------------------------------------------+++SECOND_FILE = '''def greet():+ pass+++class Other:+ def helper(self):+ pass+'''+++class TestSearchSymbols:+ def test_substring_case_insensitive(self):+ result = search_symbols(+ "greet",+ [(PY_SAMPLE, "greeter.py"), (SECOND_FILE, "other.py")],+ )+ # Four substring hits on leaf name "greet":+ # greeter.py : Greeter (class), Greeter.greet (method), make_greeter (fn)+ # other.py : greet (top-level fn)+ assert result.startswith('4 matches for "greet"')+ assert "scanned 2 files" in result+ assert "greeter.py" in result+ assert "other.py" in result+ assert "Greeter.greet" in result+ assert "make_greeter" in result++ def test_qualified_name_search(self):+ # Searching the full qualified name must also match.+ result = search_symbols("Greeter.greet", [(PY_SAMPLE, "greeter.py")])+ assert "1 matches" in result+ assert "Greeter.greet" in result++ def test_query_only_matches_leaf_name(self):+ result = search_symbols("helper", [(SECOND_FILE, "other.py")])+ assert "1 matches" in result+ assert "Other.helper" in result++ def test_no_match(self):+ result = search_symbols("nonexistent_xyz", [(PY_SAMPLE, "greeter.py")])+ assert result.startswith("No matches")+ assert "scanned 1 files" in result++ def test_empty_query(self):+ assert search_symbols("", [(PY_SAMPLE, "greeter.py")]) == "Error: empty query"++ def test_skips_unsupported_silently(self):+ # Markdown file is silently skipped (still counts toward scanned total)+ result = search_symbols(+ "greet",+ [(PY_SAMPLE, "greeter.py"), ("# heading", "notes.md")],+ )+ assert "scanned 2 files" in result+ assert "notes.md" not in result+++# ---------------------------------------------------------------------------+# expand_symbol+# ---------------------------------------------------------------------------+++class TestExpandSymbol:+ def test_expand_top_level_function(self):+ out = expand_symbol(PY_SAMPLE, "greeter.py", "make_greeter")+ assert out.startswith("# greeter.py L18-19 (make_greeter)")+ assert "def make_greeter(name: str) -> Greeter:" in out+ assert "return Greeter(name)" in out++ def test_expand_class(self):+ out = expand_symbol(PY_SAMPLE, "greeter.py", "Greeter")+ assert "(Greeter)" in out+ assert "class Greeter:" in out+ assert "def greet" in out # body included++ def test_expand_qualified_method(self):+ out = expand_symbol(PY_SAMPLE, "greeter.py", "Greeter.greet")+ assert "(Greeter.greet)" in out+ assert "def greet(self, who: str) -> str:" in out+ # Should NOT include __init__ or class header+ assert "class Greeter" not in out+ assert "__init__" not in out++ def test_expand_bare_method_resolves_to_first_match(self):+ # bare 'greet' should find the method via class walk (first match)+ out = expand_symbol(PY_SAMPLE, "greeter.py", "greet")+ assert "(Greeter.greet)" in out+ assert "def greet" in out++ def test_expand_missing_symbol(self):+ out = expand_symbol(PY_SAMPLE, "greeter.py", "does_not_exist")+ assert out == "Error: symbol 'does_not_exist' not found in greeter.py"++ def test_expand_unsupported_language(self):+ out = expand_symbol("# hello", "readme.md", "anything")+ assert out == "Error: unsupported language for readme.md"++ def test_expand_qualified_missing_class(self):+ out = expand_symbol(PY_SAMPLE, "greeter.py", "NoSuchClass.greet")+ assert "symbol 'NoSuchClass.greet' not found" in outdiff --git a/tests/server/test_mcp_endpoint_code.py b/tests/server/test_mcp_endpoint_code.pynew file mode 100644index 000000000..fa5df16f2--- /dev/null+++ b/tests/server/test_mcp_endpoint_code.py@@ -0,0 +1,375 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++"""Tests for the code-navigation MCP tools (code_outline / code_search /+code_expand) in openviking/server/mcp_endpoint.py.++The pure formatters in openviking.parse.parsers.code.ast.code_tools are+covered by tests/parse/test_code_tools.py. These tests cover the MCP wiring:+URI validation, service.fs.read / service.fs.ls plumbing, extension filtering,+the 200-file cap, and error mapping.+"""++from types import SimpleNamespace++import pytest++from openviking.server.dependencies import set_service+from openviking.server.identity import RequestContext, Role+from openviking.server.mcp_endpoint import (+ _filter_code_uris,+ _mcp_ctx,+ _require_viking_uri,+ code_expand,+ code_outline,+ code_search,+)+from openviking_cli.session.user_id import UserIdentifier++DEFAULT_CTX = RequestContext(+ user=UserIdentifier.the_default_user("test_user"),+ role=Role.ROOT,+)+++PY_SAMPLE = '''"""Module top doc."""+++class Greeter:+ def greet(self, who: str) -> str:+ return f"Hello {who}"+++def make_greeter() -> Greeter:+ return Greeter()+'''++[email protected](autouse=True)+def _set_mcp_identity(service):+ """Set identity contextvar and wire service for all tests."""+ set_service(service)+ token = _mcp_ctx.set(DEFAULT_CTX)+ yield+ _mcp_ctx.reset(token)+++def _patch_fs(monkeypatch, service, *, read=None, ls=None):+ """Replace service.fs.read / .ls with async fakes."""+ if read is not None:+ monkeypatch.setattr(service.fs, "read", read)+ if ls is not None:+ monkeypatch.setattr(service.fs, "ls", ls)+++# ---------------------------------------------------------------------------+# _require_viking_uri (internal helper, but small contract worth pinning)+# ---------------------------------------------------------------------------+++class TestRequireVikingUri:+ def test_accepts_viking_uri(self):+ assert _require_viking_uri("viking://resources/foo.py") is None++ def test_rejects_local_path(self):+ msg = _require_viking_uri("/tmp/foo.py")+ assert msg is not None+ assert "viking://" in msg++ def test_rejects_http_url(self):+ msg = _require_viking_uri("https://example.com/foo.py")+ assert msg is not None++ def test_rejects_non_string(self):+ assert _require_viking_uri(None) is not None # type: ignore[arg-type]+++# ---------------------------------------------------------------------------+# _filter_code_uris+# ---------------------------------------------------------------------------+++class TestFilterCodeUris:+ def test_keeps_supported_extensions(self):+ entries = [+ {"uri": "viking://r/a.py", "isDir": False},+ {"uri": "viking://r/b.md", "isDir": False},+ {"uri": "viking://r/c.ts", "isDir": False},+ {"uri": "viking://r/d.txt", "isDir": False},+ ]+ uris, capped = _filter_code_uris(entries)+ assert uris == ["viking://r/a.py", "viking://r/c.ts"]+ assert capped is False++ def test_skips_directories(self):+ entries = [+ {"uri": "viking://r/sub", "isDir": True},+ {"uri": "viking://r/a.py", "isDir": False},+ ]+ uris, capped = _filter_code_uris(entries)+ assert uris == ["viking://r/a.py"]+ assert capped is False++ def test_supports_object_entries(self):+ entries = [+ SimpleNamespace(uri="viking://r/a.py", is_dir=False),+ SimpleNamespace(uri="viking://r/sub", is_dir=True),+ ]+ uris, capped = _filter_code_uris(entries)+ assert uris == ["viking://r/a.py"]+ assert capped is False++ def test_caps_at_200(self):+ entries = [{"uri": f"viking://r/f{i}.py", "isDir": False} for i in range(250)]+ uris, capped = _filter_code_uris(entries)+ assert len(uris) == 200+ assert capped is True++ def test_exactly_200_not_capped(self):+ entries = [{"uri": f"viking://r/f{i}.py", "isDir": False} for i in range(200)]+ uris, capped = _filter_code_uris(entries)+ assert len(uris) == 200+ assert capped is False+++# ---------------------------------------------------------------------------+# code_outline+# ---------------------------------------------------------------------------+++class TestCodeOutline:+ async def test_rejects_non_viking_uri(self, service):+ out = await code_outline("/tmp/foo.py")+ assert "viking://" in out++ async def test_outline_via_fs_read(self, service, monkeypatch):+ captured = {}++ async def fake_read(uri, ctx=None, **_):+ captured["uri"] = uri+ captured["ctx"] = ctx+ return PY_SAMPLE++ _patch_fs(monkeypatch, service, read=fake_read)++ out = await code_outline("viking://resources/greeter.py")+ assert captured["uri"] == "viking://resources/greeter.py"+ assert captured["ctx"] == DEFAULT_CTX+ assert "class Greeter" in out+ assert "def make_greeter" in out+ assert " L" in out # line spans rendered++ async def test_unsupported_language_returns_sentinel(self, service, monkeypatch):+ async def fake_read(uri, ctx=None, **_):+ return "# heading"++ _patch_fs(monkeypatch, service, read=fake_read)+ out = await code_outline("viking://resources/notes.md")+ assert out.startswith("Error: unsupported language")++ async def test_read_failure(self, service, monkeypatch):+ async def fake_read(uri, ctx=None, **_):+ raise RuntimeError("boom")++ _patch_fs(monkeypatch, service, read=fake_read)+ out = await code_outline("viking://resources/x.py")+ assert out.startswith("Error: failed to read")+ assert "boom" in out++ async def test_non_text_content(self, service, monkeypatch):+ async def fake_read(uri, ctx=None, **_):+ return b"\x00\x01binary"++ _patch_fs(monkeypatch, service, read=fake_read)+ out = await code_outline("viking://resources/x.py")+ assert out.endswith("is not text")+++# ---------------------------------------------------------------------------+# code_search+# ---------------------------------------------------------------------------+++class TestCodeSearch:+ async def test_rejects_non_viking_uri(self, service):+ out = await code_search("foo", "/tmp/dir")+ assert "viking://" in out++ async def test_empty_query(self, service):+ out = await code_search("", "viking://resources")+ assert out == "Error: empty query"++ async def test_lists_and_searches(self, service, monkeypatch):+ ls_calls = {}+ read_uris: list[str] = []++ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):+ ls_calls["uri"] = uri+ ls_calls["ctx"] = ctx+ ls_calls["recursive"] = recursive+ ls_calls["output"] = output+ return [+ {"uri": "viking://r/a.py", "isDir": False},+ {"uri": "viking://r/sub", "isDir": True},+ {"uri": "viking://r/b.md", "isDir": False},+ {"uri": "viking://r/c.py", "isDir": False},+ ]++ async def fake_read(uri, ctx=None, **_):+ read_uris.append(uri)+ if uri.endswith("a.py"):+ return PY_SAMPLE+ if uri.endswith("c.py"):+ return "def other():\n pass\n"+ return ""++ _patch_fs(monkeypatch, service, ls=fake_ls, read=fake_read)++ out = await code_search("greet", "viking://r")+ assert ls_calls["recursive"] is True+ assert ls_calls["output"] == "original"+ assert ls_calls["ctx"] == DEFAULT_CTX+ # b.md must be filtered out before any read happens+ assert "viking://r/b.md" not in read_uris+ assert set(read_uris) == {"viking://r/a.py", "viking://r/c.py"}+ # search hits Greeter + Greeter.greet in a.py+ assert "viking://r/a.py" in out+ assert "Greeter" in out++ async def test_empty_directory(self, service, monkeypatch):+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):+ return []++ _patch_fs(monkeypatch, service, ls=fake_ls)+ out = await code_search("greet", "viking://empty")+ assert "No supported source files" in out++ async def test_no_code_files(self, service, monkeypatch):+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):+ return [{"uri": "viking://r/notes.md", "isDir": False}]++ _patch_fs(monkeypatch, service, ls=fake_ls)+ out = await code_search("greet", "viking://r")+ assert "No supported source files" in out++ async def test_ls_failure(self, service, monkeypatch):+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):+ raise RuntimeError("ls denied")++ _patch_fs(monkeypatch, service, ls=fake_ls)+ out = await code_search("greet", "viking://r")+ assert out.startswith("Error: failed to list")+ assert "ls denied" in out++ async def test_read_failures_are_skipped(self, service, monkeypatch):+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):+ return [+ {"uri": "viking://r/a.py", "isDir": False},+ {"uri": "viking://r/b.py", "isDir": False},+ ]++ async def fake_read(uri, ctx=None, **_):+ if uri.endswith("b.py"):+ raise RuntimeError("denied")+ return PY_SAMPLE++ _patch_fs(monkeypatch, service, ls=fake_ls, read=fake_read)+ out = await code_search("greet", "viking://r")+ # Search should still report the matches from a.py despite b.py failing.+ assert "viking://r/a.py" in out+ assert "Greeter" in out++ async def test_file_cap_warning(self, service, monkeypatch):+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):+ return [{"uri": f"viking://r/f{i}.py", "isDir": False} for i in range(250)]++ async def fake_read(uri, ctx=None, **_):+ return PY_SAMPLE++ _patch_fs(monkeypatch, service, ls=fake_ls, read=fake_read)+ out = await code_search("greet", "viking://r")+ assert "200-file cap" in out++ async def test_no_cap_warning_below_threshold(self, service, monkeypatch):+ async def fake_ls(uri, ctx=None, recursive=False, output=None, **_):+ return [{"uri": "viking://r/a.py", "isDir": False}]++ async def fake_read(uri, ctx=None, **_):+ return PY_SAMPLE++ _patch_fs(monkeypatch, service, ls=fake_ls, read=fake_read)+ out = await code_search("greet", "viking://r")+ assert "200-file cap" not in out+++# ---------------------------------------------------------------------------+# code_expand+# ---------------------------------------------------------------------------+++class TestCodeExpand:+ async def test_rejects_non_viking_uri(self, service):+ out = await code_expand("/tmp/foo.py", "Greeter")+ assert "viking://" in out++ async def test_empty_symbol(self, service):+ out = await code_expand("viking://r/a.py", "")+ assert out == "Error: empty symbol"++ async def test_expand_bare_symbol(self, service, monkeypatch):+ captured = {}++ async def fake_read(uri, ctx=None, **_):+ captured["uri"] = uri+ captured["ctx"] = ctx+ return PY_SAMPLE++ _patch_fs(monkeypatch, service, read=fake_read)+ out = await code_expand("viking://r/a.py", "make_greeter")+ assert captured["uri"] == "viking://r/a.py"+ assert captured["ctx"] == DEFAULT_CTX+ assert "(make_greeter)" in out+ assert "def make_greeter" in out++ async def test_expand_qualified_symbol(self, service, monkeypatch):+ async def fake_read(uri, ctx=None, **_):+ return PY_SAMPLE++ _patch_fs(monkeypatch, service, read=fake_read)+ out = await code_expand("viking://r/a.py", "Greeter.greet")+ assert "(Greeter.greet)" in out+ assert "def greet" in out++ async def test_missing_symbol(self, service, monkeypatch):+ async def fake_read(uri, ctx=None, **_):+ return PY_SAMPLE++ _patch_fs(monkeypatch, service, read=fake_read)+ out = await code_expand("viking://r/a.py", "does_not_exist")+ assert "not found" in out+ assert "does_not_exist" in out++ async def test_read_failure(self, service, monkeypatch):+ async def fake_read(uri, ctx=None, **_):+ raise RuntimeError("boom")++ _patch_fs(monkeypatch, service, read=fake_read)+ out = await code_expand("viking://r/a.py", "Greeter")+ assert out.startswith("Error: failed to read")+ assert "boom" in out++ async def test_non_text_content(self, service, monkeypatch):+ async def fake_read(uri, ctx=None, **_):+ return b"\x00binary"++ _patch_fs(monkeypatch, service, read=fake_read)+ out = await code_expand("viking://r/a.py", "Greeter")+ assert out.endswith("is not text")++ async def test_unsupported_language(self, service, monkeypatch):+ async def fake_read(uri, ctx=None, **_):+ return "# heading"++ _patch_fs(monkeypatch, service, read=fake_read)+ out = await code_expand("viking://r/notes.md", "anything")+ assert out.startswith("Error: unsupported language")