kairo-code 0.1.0__py3-none-any.whl

kairo_code/tools/files.py

@@ -0,0 +1,315 @@
+"""File operation tools for Kairo Code"""
+
+import os
+from pathlib import Path
+from glob import glob
+
+from ..sandbox import get_sandbox
+
+
+# Constants for file operations
+MAX_READ_LINES = 500
+MAX_LINE_LENGTH = 1000
+TRUNCATION_WARNING = "\n... [File truncated. Use offset/limit to read more] ..."
+
+
+def read_file(
+    path: str,
+    offset: int = 0,
+    limit: int | None = None,
+    show_line_numbers: bool = True
+) -> str:
+    """
+    Read and return file contents with line numbers.
+
+    Args:
+        path: Path to the file
+        offset: Line number to start from (0-indexed)
+        limit: Maximum number of lines to read (default: MAX_READ_LINES)
+        show_line_numbers: Whether to prefix lines with numbers
+
+    Returns:
+        File contents with optional line numbers
+    """
+    # Validate path through sandbox
+    sandbox = get_sandbox()
+    valid, error, filepath = sandbox.validate_path(path, "read")
+    if not valid:
+        raise PermissionError(error)
+
+    if not filepath.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    if not filepath.is_file():
+        raise ValueError(f"Not a file: {path}")
+
+    # Check file size first
+    file_size = filepath.stat().st_size
+    if file_size > 10 * 1024 * 1024:  # 10MB
+        raise ValueError(f"File too large ({file_size // 1024 // 1024}MB). Max is 10MB.")
+
+    limit = limit or MAX_READ_LINES
+
+    with open(filepath, 'r', errors='replace') as f:
+        lines = f.readlines()
+
+    total_lines = len(lines)
+
+    # Apply offset and limit
+    selected_lines = lines[offset:offset + limit]
+    truncated = len(lines) > offset + limit
+
+    # Format output
+    output_lines = []
+
+    # Add file info header
+    output_lines.append(f"# File: {filepath}")
+    output_lines.append(f"# Lines: {offset + 1}-{min(offset + len(selected_lines), total_lines)} of {total_lines}")
+    output_lines.append("")
+
+    for i, line in enumerate(selected_lines, start=offset + 1):
+        # Truncate long lines
+        line = line.rstrip('\n\r')
+        if len(line) > MAX_LINE_LENGTH:
+            line = line[:MAX_LINE_LENGTH] + "... [line truncated]"
+
+        if show_line_numbers:
+            output_lines.append(f"{i:4d} | {line}")
+        else:
+            output_lines.append(line)
+
+    if truncated:
+        output_lines.append(TRUNCATION_WARNING)
+        output_lines.append(f"# To continue: read_file(\"{path}\", offset={offset + limit})")
+
+    return "\n".join(output_lines)
+
+
+def write_file(path: str, content: str) -> str:
+    """Write content to a file. Creates parent directories if needed."""
+    # Use sandbox for safe writes
+    sandbox = get_sandbox()
+    return sandbox.safe_write(path, content)
+
+
+def edit_file(path: str, old_string: str, new_string: str) -> str:
+    """
+    Make a targeted edit to a file by replacing old_string with new_string.
+
+    This is the PREFERRED way to modify files - more reliable than full rewrites.
+
+    Args:
+        path: Path to the file
+        old_string: Exact string to find and replace (must be unique in file)
+        new_string: String to replace it with
+
+    Returns:
+        Confirmation message with diff preview
+    """
+    sandbox = get_sandbox()
+    valid, error, filepath = sandbox.validate_path(path, "write")
+    if not valid:
+        raise PermissionError(error)
+
+    if not filepath.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    content = filepath.read_text()
+
+    # Check that old_string exists and is unique
+    count = content.count(old_string)
+
+    if count == 0:
+        # Try to provide helpful feedback
+        lines = content.split('\n')
+        for i, line in enumerate(lines, 1):
+            if old_string[:50] in line:  # Check partial match
+                raise ValueError(
+                    f"Exact match not found, but similar content at line {i}. "
+                    f"Make sure old_string matches exactly including whitespace."
+                )
+        raise ValueError(f"old_string not found in file. Read the file first to see current content.")
+
+    if count > 1:
+        raise ValueError(
+            f"old_string appears {count} times in file. "
+            f"Provide more context to make it unique."
+        )
+
+    # Perform the replacement
+    new_content = content.replace(old_string, new_string, 1)
+    filepath.write_text(new_content)
+
+    # Generate a simple diff preview
+    old_preview = old_string[:100] + ("..." if len(old_string) > 100 else "")
+    new_preview = new_string[:100] + ("..." if len(new_string) > 100 else "")
+
+    return f"""Edit successful: {filepath}
+
+Changed:
+- {old_preview}
++ {new_preview}
+"""
+
+
+def list_files(pattern: str, root: str | None = None, max_results: int = 100) -> list[str]:
+    """
+    List files matching a glob pattern.
+
+    Args:
+        pattern: Glob pattern (e.g., "*.py", "**/*.js")
+        root: Root directory to search from (defaults to cwd)
+        max_results: Maximum number of results to return
+
+    Returns:
+        List of matching file paths
+    """
+    root_path = Path(root).resolve() if root else Path.cwd()
+    matches = glob(str(root_path / pattern), recursive=True)
+
+    # Sort by modification time (newest first) and limit
+    matches.sort(key=lambda x: os.path.getmtime(x), reverse=True)
+
+    return matches[:max_results]
+
+
+def search_files(
+    query: str,
+    pattern: str = "**/*",
+    root: str | None = None,
+    context_lines: int = 0,
+    max_results: int = 50
+) -> list[dict]:
+    """
+    Search for text in files matching a pattern.
+
+    Args:
+        query: Text to search for (case-insensitive)
+        pattern: Glob pattern for files to search
+        root: Root directory
+        context_lines: Number of lines of context before/after match
+        max_results: Maximum number of matches to return
+
+    Returns:
+        List of dicts with file, line_number, content, and context
+    """
+    root_path = Path(root).resolve() if root else Path.cwd()
+    results = []
+
+    # Skip binary and large files
+    skip_extensions = {'.pyc', '.pyo', '.so', '.dylib', '.dll', '.exe', '.bin',
+                       '.jpg', '.jpeg', '.png', '.gif', '.ico', '.pdf', '.zip',
+                       '.tar', '.gz', '.node', '.woff', '.woff2', '.ttf'}
+
+    for filepath in glob(str(root_path / pattern), recursive=True):
+        path = Path(filepath)
+
+        if not path.is_file():
+            continue
+
+        if path.suffix.lower() in skip_extensions:
+            continue
+
+        # Skip large files
+        try:
+            if path.stat().st_size > 1024 * 1024:  # 1MB
+                continue
+        except OSError:
+            continue
+
+        try:
+            lines = path.read_text(errors='replace').splitlines()
+
+            for i, line in enumerate(lines):
+                if query.lower() in line.lower():
+                    result = {
+                        "file": str(path),
+                        "line": i + 1,
+                        "content": line.strip()[:200]
+                    }
+
+                    # Add context if requested
+                    if context_lines > 0:
+                        start = max(0, i - context_lines)
+                        end = min(len(lines), i + context_lines + 1)
+                        result["context"] = "\n".join(
+                            f"{j + 1}: {lines[j]}"
+                            for j in range(start, end)
+                        )
+
+                    results.append(result)
+
+                    if len(results) >= max_results:
+                        return results
+
+        except (UnicodeDecodeError, PermissionError, OSError):
+            continue
+
+    return results
+
+
+def tree(path: str = ".", max_depth: int = 3, max_files: int = 100) -> str:
+    """
+    Generate a tree view of directory structure.
+
+    Args:
+        path: Root directory to display
+        max_depth: Maximum depth to traverse
+        max_files: Maximum number of files to show
+
+    Returns:
+        Formatted tree string
+    """
+    root_path = Path(path).expanduser().resolve()
+
+    if not root_path.exists():
+        raise FileNotFoundError(f"Directory not found: {path}")
+
+    if not root_path.is_dir():
+        raise ValueError(f"Not a directory: {path}")
+
+    output = [f"{root_path.name}/"]
+    file_count = 0
+
+    def _tree_recursive(current_path: Path, prefix: str, depth: int) -> None:
+        nonlocal file_count
+
+        if depth > max_depth or file_count >= max_files:
+            return
+
+        # Get contents, sorted (directories first, then files)
+        try:
+            contents = sorted(
+                current_path.iterdir(),
+                key=lambda p: (not p.is_dir(), p.name.lower())
+            )
+        except PermissionError:
+            output.append(f"{prefix}[permission denied]")
+            return
+
+        # Skip hidden and common ignore patterns
+        ignore_patterns = {'.git', '__pycache__', 'node_modules', '.venv', 'venv',
+                          '.idea', '.vscode', '.pytest_cache', 'dist', 'build'}
+
+        contents = [p for p in contents
+                    if p.name not in ignore_patterns
+                    and not p.name.startswith('.')]
+
+        for i, item in enumerate(contents):
+            if file_count >= max_files:
+                output.append(f"{prefix}... [truncated, {max_files} items shown]")
+                return
+
+            is_last = i == len(contents) - 1
+            connector = "└── " if is_last else "├── "
+            next_prefix = prefix + ("    " if is_last else "│   ")
+
+            if item.is_dir():
+                output.append(f"{prefix}{connector}{item.name}/")
+                _tree_recursive(item, next_prefix, depth + 1)
+            else:
+                output.append(f"{prefix}{connector}{item.name}")
+                file_count += 1
+
+    _tree_recursive(root_path, "", 1)
+    return "\n".join(output)

kairo_code/tools/review.py

@@ -0,0 +1,390 @@
+"""Code review tools - checks for quality, modularity, and best practices"""
+
+import ast
+import os
+from pathlib import Path
+from dataclasses import dataclass
+from typing import Generator
+
+from .base import Tool, ToolResult
+
+
+@dataclass
+class CodeIssue:
+    """A code quality issue."""
+    severity: str  # "error", "warning", "info"
+    file: str
+    line: int
+    message: str
+    rule: str
+
+
+class CodeReviewTool(Tool):
+    """Review code for quality, modularity, and best practices."""
+
+    name = "code_review"
+    description = "Review code for quality issues: long files, complex functions, missing docs, etc."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "File or directory to review"},
+            "strict": {"type": "boolean", "description": "Use stricter thresholds (default: False)"},
+        },
+        "required": ["path"],
+    }
+
+    # Thresholds (normal / strict)
+    THRESHOLDS = {
+        "max_file_lines": (300, 200),
+        "max_function_lines": (50, 30),
+        "max_function_args": (6, 4),
+        "max_class_methods": (15, 10),
+        "max_nesting_depth": (4, 3),
+        "max_line_length": (100, 88),
+        "min_docstring_coverage": (0.5, 0.8),
+    }
+
+    def execute(self, path: str, strict: bool = False) -> ToolResult:
+        path_obj = Path(path)
+        issues: list[CodeIssue] = []
+
+        if not path_obj.exists():
+            return ToolResult(success=False, output="", error=f"Path not found: {path}")
+
+        files = [path_obj] if path_obj.is_file() else list(path_obj.rglob("*.py"))
+
+        for f in files[:50]:  # Limit files to review
+            try:
+                file_issues = list(self._review_file(f, strict))
+                issues.extend(file_issues)
+            except Exception as e:
+                issues.append(CodeIssue("error", str(f), 0, f"Failed to parse: {e}", "parse-error"))
+
+        if not issues:
+            return ToolResult(success=True, output="Code review passed! No issues found.")
+
+        # Format output
+        output_lines = [f"Found {len(issues)} issues:\n"]
+
+        # Group by file
+        by_file: dict[str, list[CodeIssue]] = {}
+        for issue in issues:
+            by_file.setdefault(issue.file, []).append(issue)
+
+        for file, file_issues in by_file.items():
+            output_lines.append(f"\n{file}:")
+            for issue in sorted(file_issues, key=lambda x: x.line):
+                icon = {"error": "❌", "warning": "⚠️", "info": "ℹ️"}.get(issue.severity, "•")
+                output_lines.append(f"  {icon} L{issue.line}: [{issue.rule}] {issue.message}")
+
+        # Summary
+        errors = sum(1 for i in issues if i.severity == "error")
+        warnings = sum(1 for i in issues if i.severity == "warning")
+        output_lines.append(f"\nSummary: {errors} errors, {warnings} warnings")
+
+        return ToolResult(
+            success=errors == 0,
+            output="\n".join(output_lines)[:8000]
+        )
+
+    def _review_file(self, file_path: Path, strict: bool) -> Generator[CodeIssue, None, None]:
+        """Review a single file."""
+        with open(file_path) as f:
+            content = f.read()
+            lines = content.split("\n")
+
+        str_path = str(file_path)
+        idx = 1 if strict else 0
+
+        # Check file length
+        max_lines = self.THRESHOLDS["max_file_lines"][idx]
+        if len(lines) > max_lines:
+            yield CodeIssue(
+                "warning", str_path, 1,
+                f"File has {len(lines)} lines (max: {max_lines}). Consider splitting into modules.",
+                "file-too-long"
+            )
+
+        # Check line lengths
+        for i, line in enumerate(lines, 1):
+            max_len = self.THRESHOLDS["max_line_length"][idx]
+            if len(line) > max_len:
+                yield CodeIssue(
+                    "info", str_path, i,
+                    f"Line is {len(line)} chars (max: {max_len})",
+                    "line-too-long"
+                )
+
+        # Parse AST for deeper analysis
+        try:
+            tree = ast.parse(content)
+        except SyntaxError as e:
+            yield CodeIssue("error", str_path, e.lineno or 1, f"Syntax error: {e.msg}", "syntax-error")
+            return
+
+        # Analyze functions and classes
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef):
+                yield from self._review_function(node, str_path, strict)
+            elif isinstance(node, ast.ClassDef):
+                yield from self._review_class(node, str_path, strict)
+
+    def _review_function(self, node: ast.FunctionDef, file_path: str, strict: bool) -> Generator[CodeIssue, None, None]:
+        """Review a function definition."""
+        idx = 1 if strict else 0
+
+        # Function length
+        func_lines = node.end_lineno - node.lineno if node.end_lineno else 0
+        max_func_lines = self.THRESHOLDS["max_function_lines"][idx]
+        if func_lines > max_func_lines:
+            yield CodeIssue(
+                "warning", file_path, node.lineno,
+                f"Function '{node.name}' has {func_lines} lines (max: {max_func_lines}). Consider breaking it up.",
+                "function-too-long"
+            )
+
+        # Argument count
+        arg_count = len(node.args.args) + len(node.args.kwonlyargs)
+        max_args = self.THRESHOLDS["max_function_args"][idx]
+        if arg_count > max_args:
+            yield CodeIssue(
+                "warning", file_path, node.lineno,
+                f"Function '{node.name}' has {arg_count} arguments (max: {max_args}). Consider using a config object.",
+                "too-many-args"
+            )
+
+        # Missing docstring (for public functions)
+        if not node.name.startswith("_"):
+            if not (node.body and isinstance(node.body[0], ast.Expr) and isinstance(node.body[0].value, ast.Constant)):
+                yield CodeIssue(
+                    "info", file_path, node.lineno,
+                    f"Function '{node.name}' has no docstring",
+                    "missing-docstring"
+                )
+
+        # Check nesting depth
+        max_depth = self._get_max_nesting(node)
+        max_allowed = self.THRESHOLDS["max_nesting_depth"][idx]
+        if max_depth > max_allowed:
+            yield CodeIssue(
+                "warning", file_path, node.lineno,
+                f"Function '{node.name}' has nesting depth {max_depth} (max: {max_allowed}). Consider early returns.",
+                "deep-nesting"
+            )
+
+    def _review_class(self, node: ast.ClassDef, file_path: str, strict: bool) -> Generator[CodeIssue, None, None]:
+        """Review a class definition."""
+        idx = 1 if strict else 0
+
+        # Method count
+        methods = [n for n in node.body if isinstance(n, ast.FunctionDef)]
+        max_methods = self.THRESHOLDS["max_class_methods"][idx]
+        if len(methods) > max_methods:
+            yield CodeIssue(
+                "warning", file_path, node.lineno,
+                f"Class '{node.name}' has {len(methods)} methods (max: {max_methods}). Consider splitting responsibilities.",
+                "class-too-large"
+            )
+
+        # Missing class docstring
+        if not (node.body and isinstance(node.body[0], ast.Expr) and isinstance(node.body[0].value, ast.Constant)):
+            yield CodeIssue(
+                "info", file_path, node.lineno,
+                f"Class '{node.name}' has no docstring",
+                "missing-docstring"
+            )
+
+    def _get_max_nesting(self, node: ast.AST, current_depth: int = 0) -> int:
+        """Get maximum nesting depth in a node."""
+        max_depth = current_depth
+
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, (ast.If, ast.For, ast.While, ast.With, ast.Try)):
+                child_depth = self._get_max_nesting(child, current_depth + 1)
+                max_depth = max(max_depth, child_depth)
+            else:
+                child_depth = self._get_max_nesting(child, current_depth)
+                max_depth = max(max_depth, child_depth)
+
+        return max_depth
+
+
+class ModularityCheckTool(Tool):
+    """Check code modularity and suggest improvements."""
+
+    name = "check_modularity"
+    description = "Analyze code structure and suggest how to make it more modular and reusable"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Directory to analyze"},
+        },
+        "required": ["path"],
+    }
+
+    def execute(self, path: str) -> ToolResult:
+        path_obj = Path(path)
+
+        if not path_obj.exists():
+            return ToolResult(success=False, output="", error=f"Path not found: {path}")
+
+        if not path_obj.is_dir():
+            return ToolResult(success=False, output="", error="Path must be a directory")
+
+        suggestions = []
+        stats = {
+            "files": 0,
+            "large_files": [],
+            "god_classes": [],
+            "long_functions": [],
+            "circular_imports": [],
+        }
+
+        py_files = list(path_obj.rglob("*.py"))
+        stats["files"] = len(py_files)
+
+        for f in py_files:
+            try:
+                with open(f) as fp:
+                    content = fp.read()
+                    lines = len(content.split("\n"))
+
+                if lines > 300:
+                    stats["large_files"].append((str(f.relative_to(path_obj)), lines))
+
+                tree = ast.parse(content)
+                for node in ast.walk(tree):
+                    if isinstance(node, ast.ClassDef):
+                        methods = [n for n in node.body if isinstance(n, ast.FunctionDef)]
+                        if len(methods) > 15:
+                            stats["god_classes"].append((str(f.relative_to(path_obj)), node.name, len(methods)))
+
+                    if isinstance(node, ast.FunctionDef):
+                        func_lines = (node.end_lineno or node.lineno) - node.lineno
+                        if func_lines > 50:
+                            stats["long_functions"].append((str(f.relative_to(path_obj)), node.name, func_lines))
+
+            except Exception:
+                continue
+
+        # Generate report
+        output_lines = ["# Modularity Analysis\n"]
+
+        output_lines.append(f"**Files analyzed:** {stats['files']}\n")
+
+        if stats["large_files"]:
+            output_lines.append("## Large Files (>300 lines)")
+            output_lines.append("Consider splitting these into smaller modules:\n")
+            for file, lines in sorted(stats["large_files"], key=lambda x: -x[1])[:10]:
+                output_lines.append(f"  - {file}: {lines} lines")
+
+            suggestions.append("Split large files into focused modules with single responsibilities")
+
+        if stats["god_classes"]:
+            output_lines.append("\n## Large Classes (>15 methods)")
+            output_lines.append("These might have too many responsibilities:\n")
+            for file, cls, methods in sorted(stats["god_classes"], key=lambda x: -x[2])[:10]:
+                output_lines.append(f"  - {file}: class {cls} ({methods} methods)")
+
+            suggestions.append("Extract related methods into separate classes or mixins")
+
+        if stats["long_functions"]:
+            output_lines.append("\n## Long Functions (>50 lines)")
+            output_lines.append("Consider breaking these into smaller helper functions:\n")
+            for file, func, lines in sorted(stats["long_functions"], key=lambda x: -x[2])[:10]:
+                output_lines.append(f"  - {file}: {func}() ({lines} lines)")
+
+            suggestions.append("Extract repeated logic into helper functions")
+
+        if suggestions:
+            output_lines.append("\n## Suggestions")
+            for i, s in enumerate(suggestions, 1):
+                output_lines.append(f"{i}. {s}")
+        else:
+            output_lines.append("\n✅ Code structure looks good!")
+
+        return ToolResult(success=True, output="\n".join(output_lines))
+
+
+class DependencyGraphTool(Tool):
+    """Visualize module dependencies."""
+
+    name = "dependency_graph"
+    description = "Show import dependencies between modules to identify coupling"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Directory to analyze"},
+        },
+        "required": ["path"],
+    }
+
+    def execute(self, path: str) -> ToolResult:
+        path_obj = Path(path)
+
+        if not path_obj.exists():
+            return ToolResult(success=False, output="", error=f"Path not found: {path}")
+
+        imports: dict[str, set[str]] = {}
+        py_files = list(path_obj.rglob("*.py"))
+
+        for f in py_files:
+            try:
+                with open(f) as fp:
+                    tree = ast.parse(fp.read())
+
+                module_name = f.stem
+                imports[module_name] = set()
+
+                for node in ast.walk(tree):
+                    if isinstance(node, ast.Import):
+                        for alias in node.names:
+                            imports[module_name].add(alias.name.split(".")[0])
+                    elif isinstance(node, ast.ImportFrom):
+                        if node.module:
+                            imports[module_name].add(node.module.split(".")[0])
+
+            except Exception:
+                continue
+
+        # Filter to only internal modules
+        internal_modules = set(imports.keys())
+
+        output_lines = ["# Module Dependency Graph\n"]
+
+        # Find modules with most dependencies (potential coupling issues)
+        dep_counts = []
+        for mod, deps in imports.items():
+            internal_deps = deps & internal_modules
+            if internal_deps:
+                dep_counts.append((mod, len(internal_deps), internal_deps))
+
+        if dep_counts:
+            output_lines.append("## Dependencies (internal modules only)\n")
+            for mod, count, deps in sorted(dep_counts, key=lambda x: -x[1]):
+                output_lines.append(f"**{mod}** ({count} deps)")
+                for d in sorted(deps):
+                    output_lines.append(f"  └─ {d}")
+                output_lines.append("")
+
+            # Find potential circular dependencies
+            output_lines.append("## Potential Issues\n")
+            circular = []
+            for mod, deps in imports.items():
+                internal_deps = deps & internal_modules
+                for dep in internal_deps:
+                    if dep in imports and mod in imports[dep]:
+                        pair = tuple(sorted([mod, dep]))
+                        if pair not in circular:
+                            circular.append(pair)
+
+            if circular:
+                output_lines.append("⚠️ Possible circular imports:")
+                for a, b in circular:
+                    output_lines.append(f"  - {a} ↔ {b}")
+            else:
+                output_lines.append("✅ No circular imports detected")
+        else:
+            output_lines.append("No internal dependencies found.")
+
+        return ToolResult(success=True, output="\n".join(output_lines))