codebuff-agent 2.1.74__py3-none-any.whl

jupyter_ext/agent/ast_tools.py

@@ -0,0 +1,451 @@
+"""
+AST 기반 코드 구조 분석 도구.
+
+Python ast 모듈을 사용하여 코드 구조를 정확하게 파싱합니다.
+AutoCodeRover의 계층적 검색 API 패턴을 참조하여 설계:
+- 시그니처만 반환 (본문 제외) → 토큰 절약
+- 결과 수 제한 (50개 cap) → 에이전트 혼란 방지
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import Path
+from typing import Optional
+
+from codebuff_core.directory_policy import AST_EXCLUDED_DIRS as _EXCLUDE_DIRS
+from langchain_core.tools import BaseTool, tool
+
+_MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
+_MAX_RESULTS = 50
+
+
+def _format_annotation(node: Optional[ast.expr]) -> Optional[str]:
+    """AST annotation 노드를 문자열로 변환."""
+    if node is None:
+        return None
+    return ast.unparse(node)
+
+
+def _extract_args(args: ast.arguments) -> list[str]:
+    """함수 인자 리스트를 문자열로 추출."""
+    result = []
+    # positional args (defaults는 뒤에서부터 매칭)
+    n_defaults = len(args.defaults)
+    n_args = len(args.args)
+    for i, arg in enumerate(args.args):
+        s = arg.arg
+        if arg.annotation:
+            s += f": {ast.unparse(arg.annotation)}"
+        default_idx = i - (n_args - n_defaults)
+        if default_idx >= 0:
+            s += f" = {ast.unparse(args.defaults[default_idx])}"
+        result.append(s)
+    # *args
+    if args.vararg:
+        s = f"*{args.vararg.arg}"
+        if args.vararg.annotation:
+            s += f": {ast.unparse(args.vararg.annotation)}"
+        result.append(s)
+    # keyword-only args
+    for i, arg in enumerate(args.kwonlyargs):
+        s = arg.arg
+        if arg.annotation:
+            s += f": {ast.unparse(arg.annotation)}"
+        if i < len(args.kw_defaults) and args.kw_defaults[i] is not None:
+            s += f" = {ast.unparse(args.kw_defaults[i])}"
+        result.append(s)
+    # **kwargs
+    if args.kwarg:
+        s = f"**{args.kwarg.arg}"
+        if args.kwarg.annotation:
+            s += f": {ast.unparse(args.kwarg.annotation)}"
+        result.append(s)
+    return result
+
+
+def _parse_file_safe(file_path: Path) -> Optional[ast.Module]:
+    """파일을 안전하게 AST 파싱. 실패 시 None 반환."""
+    try:
+        if file_path.stat().st_size > _MAX_FILE_SIZE:
+            return None
+        source = file_path.read_text(encoding="utf-8", errors="ignore")
+        return ast.parse(source, filename=str(file_path))
+    except (SyntaxError, UnicodeDecodeError, OSError):
+        return None
+
+
+def _should_skip_dir(name: str) -> bool:
+    """디렉토리를 건너뛸지 판단."""
+    return name.startswith(".") or name in _EXCLUDE_DIRS
+
+
+def _collect_py_files(root: Path, scope: Optional[Path] = None) -> list[Path]:
+    """워크스페이스에서 Python 파일 수집."""
+    target = scope or root
+    if target.is_file():
+        return [target] if target.suffix == ".py" else []
+
+    files = []
+    for p in target.rglob("*.py"):
+        if any(_should_skip_dir(part) for part in p.relative_to(target).parts):
+            continue
+        if p.is_file():
+            files.append(p)
+    return files
+
+
+def _build_signature(
+    name: str,
+    args: ast.arguments,
+    returns: Optional[ast.expr],
+    is_async: bool = False,
+) -> str:
+    """함수/메서드 시그니처 문자열 생성."""
+    prefix = "async def" if is_async else "def"
+    arg_strs = _extract_args(args)
+    ret = f" -> {ast.unparse(returns)}" if returns else ""
+    return f"{prefix} {name}({', '.join(arg_strs)}){ret}"
+
+
+# =============================================================================
+# Tool 1: analyze_file_structure
+# =============================================================================
+
+
+def create_analyze_file_structure_tool(workspace_root: str) -> BaseTool:
+    """파일 구조 분석용 LangChain 도구를 생성합니다."""
+    base_path = Path(workspace_root)
+
+    @tool
+    def analyze_file_structure(path: str) -> str:
+        """파일의 코드 구조를 AST로 분석합니다. 클래스, 함수, import 목록을 시그니처와 함께 반환합니다.
+        본문은 포함하지 않아 토큰을 절약합니다.
+
+        이 도구의 용도:
+        - 파일의 전체 구조 빠르게 파악 (클래스, 함수, import)
+        - 클래스의 메서드 목록과 시그니처 확인
+        - grep보다 정확한 구조적 분석 (주석/문자열 내 매칭 제외)
+
+        Args:
+            path: 분석할 Python 파일 경로 (workspace 상대 경로)
+
+        Returns:
+            JSON: classes, functions, imports, top_level_variables, total_lines
+        """
+        target = base_path / path
+        if not target.is_file():
+            return json.dumps(
+                {"success": False, "error": f"파일을 찾을 수 없음: {path}"}
+            )
+        if target.suffix != ".py":
+            return json.dumps(
+                {"success": False, "error": "Python 파일(.py)만 지원합니다"}
+            )
+
+        tree = _parse_file_safe(target)
+        if tree is None:
+            return json.dumps(
+                {
+                    "success": True,
+                    "data": {
+                        "path": path,
+                        "classes": [],
+                        "functions": [],
+                        "imports": [],
+                        "top_level_variables": [],
+                        "total_lines": 0,
+                        "parse_error": True,
+                    },
+                }
+            )
+
+        classes = []
+        functions = []
+        imports = []
+        variables = []
+
+        for node in ast.iter_child_nodes(tree):
+            if isinstance(node, ast.ClassDef):
+                bases = [ast.unparse(b) for b in node.bases]
+                methods = []
+                for item in node.body:
+                    if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        methods.append(
+                            {
+                                "name": item.name,
+                                "line": item.lineno,
+                                "args": _extract_args(item.args),
+                                "returns": _format_annotation(item.returns),
+                                "is_async": isinstance(item, ast.AsyncFunctionDef),
+                            }
+                        )
+                classes.append(
+                    {
+                        "name": node.name,
+                        "line": node.lineno,
+                        "bases": bases,
+                        "methods": methods,
+                    }
+                )
+
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                functions.append(
+                    {
+                        "name": node.name,
+                        "line": node.lineno,
+                        "args": _extract_args(node.args),
+                        "returns": _format_annotation(node.returns),
+                        "is_async": isinstance(node, ast.AsyncFunctionDef),
+                    }
+                )
+
+            elif isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.asname:
+                        imports.append(f"import {alias.name} as {alias.asname}")
+                    else:
+                        imports.append(f"import {alias.name}")
+
+            elif isinstance(node, ast.ImportFrom):
+                module = node.module or ""
+                names = ", ".join(
+                    f"{a.name} as {a.asname}" if a.asname else a.name
+                    for a in node.names
+                )
+                imports.append(f"from {module} import {names}")
+
+            elif isinstance(node, ast.Assign):
+                for target_node in node.targets:
+                    if isinstance(target_node, ast.Name):
+                        variables.append(target_node.id)
+
+            elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+                variables.append(node.target.id)
+
+        # total_lines
+        try:
+            source = target.read_text(encoding="utf-8", errors="ignore")
+            total_lines = len(source.splitlines())
+        except OSError:
+            total_lines = 0
+
+        return json.dumps(
+            {
+                "success": True,
+                "data": {
+                    "path": path,
+                    "classes": classes,
+                    "functions": functions,
+                    "imports": imports,
+                    "top_level_variables": variables,
+                    "total_lines": total_lines,
+                },
+            }
+        )
+
+    return analyze_file_structure
+
+
+# =============================================================================
+# Tool 2: search_symbol_definition
+# =============================================================================
+
+
+def create_search_symbol_definition_tool(workspace_root: str) -> BaseTool:
+    """심볼 정의 검색용 LangChain 도구를 생성합니다."""
+    base_path = Path(workspace_root)
+
+    @tool
+    def search_symbol_definition(
+        symbol_name: str,
+        symbol_type: Optional[str] = None,
+        path: Optional[str] = None,
+    ) -> str:
+        """워크스페이스에서 클래스, 함수, 메서드의 정의 위치를 AST로 검색합니다.
+        grep과 달리 주석이나 문자열 안의 매칭을 제외하고 실제 정의만 찾습니다.
+
+        이 도구의 용도:
+        - 클래스/함수가 어디에 정의되어 있는지 정확히 찾기
+        - 동일 이름의 함수가 여러 파일에 있을 때 모두 찾기
+        - 메서드가 어떤 클래스에 속하는지 확인
+
+        Args:
+            symbol_name: 검색할 심볼 이름 (예: "DataProcessor", "process")
+            symbol_type: 선택적 필터 ("class", "function", "method"). 미지정시 모두 검색.
+            path: 선택적 검색 범위 제한 (디렉토리 또는 파일의 workspace 상대 경로)
+
+        Returns:
+            JSON: 매칭되는 심볼 정의 목록 (파일, 라인, 시그니처, 소속 클래스)
+        """
+        if not symbol_name:
+            return json.dumps({"success": False, "error": "심볼 이름이 필요합니다"})
+
+        scope = base_path / path if path else None
+        if scope and not scope.exists():
+            return json.dumps(
+                {"success": False, "error": f"경로를 찾을 수 없음: {path}"}
+            )
+
+        py_files = _collect_py_files(base_path, scope)
+        definitions: list[dict] = []
+
+        for file_path in py_files:
+            tree = _parse_file_safe(file_path)
+            if tree is None:
+                continue
+
+            rel_path = str(file_path.relative_to(base_path))
+
+            # 탑레벨 함수/클래스 탐색
+            for node in ast.iter_child_nodes(tree):
+                if isinstance(node, ast.ClassDef):
+                    if node.name == symbol_name and symbol_type in (None, "class"):
+                        bases = [ast.unparse(b) for b in node.bases]
+                        base_str = f"({', '.join(bases)})" if bases else ""
+                        definitions.append(
+                            {
+                                "file": rel_path,
+                                "line": node.lineno,
+                                "type": "class",
+                                "class": None,
+                                "signature": f"class {node.name}{base_str}",
+                            }
+                        )
+                    # 클래스 내 메서드 탐색
+                    if symbol_type in (None, "method", "function"):
+                        for item in node.body:
+                            if (
+                                isinstance(
+                                    item, (ast.FunctionDef, ast.AsyncFunctionDef)
+                                )
+                                and item.name == symbol_name
+                            ):
+                                sig = _build_signature(
+                                    item.name,
+                                    item.args,
+                                    item.returns,
+                                    isinstance(item, ast.AsyncFunctionDef),
+                                )
+                                definitions.append(
+                                    {
+                                        "file": rel_path,
+                                        "line": item.lineno,
+                                        "type": "method",
+                                        "class": node.name,
+                                        "signature": sig,
+                                    }
+                                )
+
+                elif (
+                    isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+                    and node.name == symbol_name
+                ):
+                    if symbol_type in (None, "function"):
+                        sig = _build_signature(
+                            node.name,
+                            node.args,
+                            node.returns,
+                            isinstance(node, ast.AsyncFunctionDef),
+                        )
+                        definitions.append(
+                            {
+                                "file": rel_path,
+                                "line": node.lineno,
+                                "type": "function",
+                                "class": None,
+                                "signature": sig,
+                            }
+                        )
+
+            if len(definitions) >= _MAX_RESULTS:
+                break
+
+        truncated = len(definitions) > _MAX_RESULTS
+        definitions = definitions[:_MAX_RESULTS]
+
+        return json.dumps(
+            {
+                "success": True,
+                "data": {
+                    "symbol": symbol_name,
+                    "definitions": definitions,
+                    "total_found": len(definitions),
+                    "truncated": truncated,
+                },
+            }
+        )
+
+    return search_symbol_definition
+
+
+# =============================================================================
+# Tool 3: analyze_dependencies
+# =============================================================================
+
+
+def create_analyze_dependencies_tool(workspace_root: str) -> BaseTool:
+    """파일 의존성 분석용 LangChain 도구를 생성합니다."""
+    base_path = Path(workspace_root)
+
+    @tool
+    def analyze_dependencies(path: str) -> str:
+        """파일의 import 의존성과 변수 사용을 AST로 분석합니다.
+
+        이 도구의 용도:
+        - 파일이 어떤 모듈을 import하는지 정확히 파악
+        - 정의된 이름과 사용된 이름 비교로 미정의 변수 탐지
+        - 코드 리팩토링 전 의존성 관계 파악
+
+        Args:
+            path: 분석할 Python 파일 경로 (workspace 상대 경로)
+
+        Returns:
+            JSON: imports, from_imports, defined_names, used_names, undefined_names
+        """
+        target = base_path / path
+        if not target.is_file():
+            return json.dumps(
+                {"success": False, "error": f"파일을 찾을 수 없음: {path}"}
+            )
+        if target.suffix != ".py":
+            return json.dumps(
+                {"success": False, "error": "Python 파일(.py)만 지원합니다"}
+            )
+
+        try:
+            source = target.read_text(encoding="utf-8", errors="ignore")
+        except OSError as e:
+            return json.dumps({"success": False, "error": f"파일 읽기 오류: {e}"})
+
+        from codebuff_core.core.code_validator import CodeValidator
+
+        validator = CodeValidator()
+        deps = validator.analyze_dependencies(source)
+        undefined_issues = validator.check_undefined_names(source)
+
+        undefined = [
+            {
+                "name": issue.message.split("'")[1],
+                "line": issue.line,
+                "severity": issue.severity.value,
+            }
+            for issue in undefined_issues
+        ]
+
+        return json.dumps(
+            {
+                "success": True,
+                "data": {
+                    "path": path,
+                    "imports": deps.imports,
+                    "from_imports": deps.from_imports,
+                    "defined_names": sorted(deps.defined_names),
+                    "used_names": sorted(deps.used_names),
+                    "undefined_names": undefined,
+                },
+            }
+        )
+
+    return analyze_dependencies