feat: add code understanding service

- Add CodeUnderstandingService using Python AST
- Implement parse_python_code, extract_functions, extract_classes
- Implement get_file_structure
- Follow TDD principles
- All tests passing

Infrastructure layer and core services progressing

Author: yunlongwen

src/agently/core/__init__.py

@@ -1,5 +1,5 @@
-"""
-Core Services Layer - Core Capabilities
-"""
+"""Core Services Layer - Core Capabilities"""
 
-__all__ = []
+from agently.core.code_understanding import CodeUnderstandingService
+
+__all__ = ["CodeUnderstandingService"]

src/agently/core/code_understanding.py

@@ -0,0 +1,102 @@
+"""Code understanding service using Python AST"""
+
+import ast
+from pathlib import Path
+from typing import Any, List, Dict
+
+from agently.logging import LoggingMixin
+
+
+class CodeUnderstandingService(LoggingMixin):
+    """Service for understanding code structure"""
+
+    def parse_python_code(self, file_path: Path) -> ast.AST:
+        """Parse Python code into AST
+
+        Args:
+            file_path: Path to Python file
+
+        Returns:
+            AST of the Python code
+
+        Raises:
+            SyntaxError: If code has syntax errors
+        """
+        self.logger.info("Parsing Python code", file_path=str(file_path))
+        code = file_path.read_text()
+        return ast.parse(code)
+
+    def extract_functions(self, file_path: Path) -> List[ast.FunctionDef]:
+        """Extract function definitions from code
+
+        Args:
+            file_path: Path to Python file
+
+        Returns:
+            List of function definitions
+        """
+        self.logger.info("Extracting functions", file_path=str(file_path))
+        tree = self.parse_python_code(file_path)
+        functions = []
+
+        # First, get all top-level functions
+        for node in tree.body:
+            if isinstance(node, ast.FunctionDef):
+                functions.append(node)
+            elif isinstance(node, ast.ClassDef):
+                # Get methods from classes
+                for item in node.body:
+                    if isinstance(item, ast.FunctionDef):
+                        functions.append(item)
+
+        return functions
+
+    def extract_classes(self, file_path: Path) -> List[ast.ClassDef]:
+        """Extract class definitions from code
+
+        Args:
+            file_path: Path to Python file
+
+        Returns:
+            List of class definitions
+        """
+        self.logger.info("Extracting classes", file_path=str(file_path))
+        tree = self.parse_python_code(file_path)
+        classes = []
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                classes.append(node)
+
+        return classes
+
+    def get_file_structure(self, file_path: Path) -> Dict[str, Any]:
+        """Get complete structure of a Python file
+
+        Args:
+            file_path: Path to Python file
+
+        Returns:
+            Dictionary with classes, functions, imports
+        """
+        self.logger.info("Getting file structure", file_path=str(file_path))
+        tree = self.parse_python_code(file_path)
+
+        structure: Dict[str, Any] = {
+            "classes": [],
+            "functions": [],
+            "imports": [],
+        }
+
+        structure["functions"] = [f.name for f in self.extract_functions(file_path)]
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                structure["classes"].append(node.name)
+            elif isinstance(node, (ast.Import, ast.ImportFrom)):
+                if isinstance(node, ast.Import):
+                    for alias in node.names:
+                        structure["imports"].append(alias.name)
+                elif isinstance(node, ast.ImportFrom):
+                    structure["imports"].append(node.module)
+
+        return structure

tests/unit/test_code_understanding.py

@@ -0,0 +1,105 @@
+"""Tests for code understanding service"""
+
+from pathlib import Path
+
+import pytest
+
+from agently.core.code_understanding import CodeUnderstandingService
+
+
+class TestCodeUnderstandingService:
+    """Test CodeUnderstandingService class"""
+
+    def test_parse_python_code(self, tmp_path: Path):
+        """Test parsing Python code"""
+        # Setup
+        code_file = tmp_path / "test.py"
+        code = """
+def hello_world():
+    print("Hello, World!")
+"""
+        code_file.write_text(code)
+
+        # Test
+        service = CodeUnderstandingService()
+        ast = service.parse_python_code(code_file)
+
+        # Assert
+        assert ast is not None
+        assert hasattr(ast, "body")
+        assert len(ast.body) > 0
+
+    def test_extract_functions(self, tmp_path: Path):
+        """Test extracting functions from code"""
+        # Setup
+        code_file = tmp_path / "test.py"
+        code = """
+def function_one():
+    pass
+
+def function_two(arg1, arg2):
+    return arg1 + arg2
+
+class MyClass:
+    def method_one(self):
+        pass
+"""
+        code_file.write_text(code)
+
+        # Test
+        service = CodeUnderstandingService()
+        functions = service.extract_functions(code_file)
+
+        # Assert
+        assert len(functions) >= 3  # 2 functions + 1 class method
+        function_names = [f.name for f in functions]
+        assert "function_one" in function_names
+        assert "function_two" in function_names
+        assert "method_one" in function_names
+
+    def test_extract_classes(self, tmp_path: Path):
+        """Test extracting classes from code"""
+        # Setup
+        code_file = tmp_path / "test.py"
+        code = """
+class ClassOne:
+    pass
+
+class ClassTwo:
+    pass
+"""
+        code_file.write_text(code)
+
+        # Test
+        service = CodeUnderstandingService()
+        classes = service.extract_classes(code_file)
+
+        # Assert
+        assert len(classes) == 2
+        class_names = [c.name for c in classes]
+        assert "ClassOne" in class_names
+        assert "ClassTwo" in class_names
+
+    def test_get_file_structure(self, tmp_path: Path):
+        """Test getting file structure"""
+        # Setup
+        code_file = tmp_path / "test.py"
+        code = """
+class MyClass:
+    def method_one(self):
+        pass
+
+def function_one():
+    pass
+"""
+        code_file.write_text(code)
+
+        # Test
+        service = CodeUnderstandingService()
+        structure = service.get_file_structure(code_file)
+
+        # Assert
+        assert "classes" in structure
+        assert "functions" in structure
+        assert len(structure["classes"]) >= 1
+        assert len(structure["functions"]) >= 1