devsper 2.1.6__py3-none-any.whl

devsper/tools/code_intelligence/api_surface_extractor.py

@@ -0,0 +1,73 @@
+"""Extract the public API surface: non-_ prefixed functions and classes with signatures."""
+
+import ast
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class ApiSurfaceExtractorTool(Tool):
+    """
+    Extract public API: top-level functions and classes that do not start with underscore.
+    """
+
+    name = "api_surface_extractor"
+    description = "Extract public API surface (non-_ names) with argument lists."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Path to file or directory"},
+            "max_symbols": {"type": "integer", "description": "Max symbols (default 80)"},
+        },
+        "required": ["path"],
+    }
+
+    def _arg_list(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+        args = [a.arg for a in node.args.args if a.arg != "self"]
+        if node.args.vararg:
+            args.append("*" + node.args.vararg.arg)
+        if node.args.kwarg:
+            args.append("**" + node.args.kwarg.arg)
+        return ", ".join(args)
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        max_symbols = kwargs.get("max_symbols", 80)
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if not isinstance(max_symbols, int) or max_symbols < 1:
+            max_symbols = 80
+        p = Path(path).resolve()
+        if not p.exists():
+            return f"Error: path not found: {path}"
+        files = [p] if p.is_file() and p.suffix == ".py" else list(p.rglob("*.py")) if p.is_dir() else []
+        symbols = []
+        for f in files:
+            if not f.is_file():
+                continue
+            try:
+                tree = ast.parse(f.read_text(encoding="utf-8", errors="replace"))
+                rel = f.relative_to(p if p.is_dir() else f.parent)
+                for node in ast.iter_child_nodes(tree):
+                    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                        if node.name.startswith("_"):
+                            continue
+                        kind = "class" if isinstance(node, ast.ClassDef) else "def"
+                        if kind == "def":
+                            sig = f"{node.name}({self._arg_list(node)})"  # type: ignore[arg-type]
+                        else:
+                            sig = node.name
+                        symbols.append({"file": str(rel), "kind": kind, "signature": sig})
+                    if len(symbols) >= max_symbols:
+                        break
+            except (SyntaxError, OSError):
+                continue
+            if len(symbols) >= max_symbols:
+                break
+        import json
+
+        return json.dumps({"api": symbols}, indent=2)
+
+
+register(ApiSurfaceExtractorTool())

devsper/tools/code_intelligence/architecture_analyzer.py

@@ -0,0 +1,65 @@
+"""Analyze codebase architecture: package layout, entry points, and high-level structure."""
+
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class ArchitectureAnalyzerTool(Tool):
+    """
+    Report high-level architecture: top-level packages, __main__ and main-like files, and layout.
+    """
+
+    name = "architecture_analyzer"
+    description = "Analyze codebase architecture: packages, entry points, layout."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Root path"},
+            "max_depth": {"type": "integer", "description": "Max depth for layout (default 3)"},
+        },
+        "required": ["path"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        max_depth = kwargs.get("max_depth", 3)
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if not isinstance(max_depth, int) or max_depth < 1:
+            max_depth = 3
+        root = Path(path).resolve()
+        if not root.exists() or not root.is_dir():
+            return f"Error: path must be an existing directory: {path}"
+        top_dirs = []
+        for d in root.iterdir():
+            if d.is_dir() and not d.name.startswith(".") and d.name != "__pycache__":
+                top_dirs.append(d.name)
+        main_files = []
+        for p in root.rglob("*.py"):
+            if not p.is_file():
+                continue
+            name = p.name.lower()
+            if name in ("__main__.py", "main.py", "run.py", "app.py"):
+                main_files.append(str(p.relative_to(root)).replace("\\", "/"))
+        layout = []
+        for d in sorted(top_dirs)[:20]:
+            sub = root / d
+            if sub.is_dir():
+                py_count = sum(1 for _ in sub.rglob("*.py"))
+                layout.append(f"  {d}/ ({py_count} .py files)")
+        lines = [
+            "Architecture summary",
+            "=" * 40,
+            "Top-level packages: " + ", ".join(sorted(top_dirs)[:15]),
+            "",
+            "Entry-point-like files: " + ", ".join(main_files[:10]) or "none found",
+            "",
+            "Layout (top-level):",
+            "\n".join(layout),
+        ]
+        return "\n".join(lines)
+
+
+register(ArchitectureAnalyzerTool())

devsper/tools/code_intelligence/codebase_indexer.py

@@ -0,0 +1,71 @@
+"""Index a codebase: list modules, files, and top-level symbols (functions/classes)."""
+
+import ast
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class CodebaseIndexerTool(Tool):
+    """
+    Build a simple index of a Python codebase: files, modules, and top-level function/class names.
+    """
+
+    name = "codebase_indexer"
+    description = "Index a Python codebase: list files and top-level functions/classes."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Root path to index"},
+            "max_depth": {"type": "integer", "description": "Max directory depth (default 5)"},
+            "extensions": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "File extensions to include (default ['.py'])",
+            },
+        },
+        "required": ["path"],
+    }
+
+    def _index_file(self, p: Path) -> list[str]:
+        symbols = []
+        try:
+            tree = ast.parse(p.read_text(encoding="utf-8", errors="replace"))
+            for node in ast.walk(tree):
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                    if node.col_offset == 0:
+                        kind = "class" if isinstance(node, ast.ClassDef) else "function"
+                        symbols.append(f"{kind}:{node.name}")
+        except (SyntaxError, OSError):
+            pass
+        return symbols
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        max_depth = kwargs.get("max_depth", 5)
+        extensions = kwargs.get("extensions") or [".py"]
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if not isinstance(max_depth, int) or max_depth < 1:
+            max_depth = 5
+        root = Path(path).resolve()
+        if not root.exists() or not root.is_dir():
+            return f"Error: path must be an existing directory: {path}"
+        index = []
+        for depth, _ in enumerate(root.rglob("*")):
+            if depth > 1000:
+                break
+        for p in root.rglob("*"):
+            if p.is_file() and p.suffix.lower() in extensions:
+                rel = p.relative_to(root)
+                if len(rel.parts) > max_depth:
+                    continue
+                symbols = self._index_file(p)
+                index.append({"file": str(rel), "symbols": symbols})
+        import json
+
+        return json.dumps({"root": str(root), "index": index[:200]}, indent=2)
+
+
+register(CodebaseIndexerTool())

devsper/tools/code_intelligence/dependency_graph_builder.py

@@ -0,0 +1,67 @@
+"""Build a dependency graph from Python files: module -> imported modules."""
+
+import ast
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class DependencyGraphBuilderTool(Tool):
+    """
+    Build a module-level dependency graph: for each .py file, list its imports (internal or external).
+    """
+
+    name = "dependency_graph_builder"
+    description = "Build a dependency graph from Python files (module -> imports)."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Root path of the codebase"},
+            "max_files": {"type": "integer", "description": "Max files to scan (default 150)"},
+        },
+        "required": ["path"],
+    }
+
+    def _imports(self, p: Path) -> list[str]:
+        imports = []
+        try:
+            tree = ast.parse(p.read_text(encoding="utf-8", errors="replace"))
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Import):
+                    for alias in node.names:
+                        imports.append(alias.name.split(".")[0])
+                elif isinstance(node, ast.ImportFrom):
+                    if node.module:
+                        imports.append(node.module.split(".")[0])
+        except (SyntaxError, OSError):
+            pass
+        return list(dict.fromkeys(imports))
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        max_files = kwargs.get("max_files", 150)
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if not isinstance(max_files, int) or max_files < 1:
+            max_files = 150
+        root = Path(path).resolve()
+        if not root.exists() or not root.is_dir():
+            return f"Error: path must be an existing directory: {path}"
+        edges = []
+        count = 0
+        for p in root.rglob("*.py"):
+            if count >= max_files:
+                break
+            if not p.is_file():
+                continue
+            count += 1
+            mod = str(p.relative_to(root)).replace("\\", "/").replace(".py", "").replace("/", ".")
+            for imp in self._imports(p):
+                edges.append({"from": mod, "to": imp})
+        import json
+
+        return json.dumps({"nodes": "inferred from edges", "edges": edges[:300]}, indent=2)
+
+
+register(DependencyGraphBuilderTool())

devsper/tools/code_intelligence/design_pattern_detector.py

@@ -0,0 +1,62 @@
+"""Detect simple design patterns in Python code: singleton-like, context manager, etc."""
+
+import ast
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class DesignPatternDetectorTool(Tool):
+    """
+    Detect heuristic design patterns: class with __enter__/__exit__, base class usage, etc.
+    """
+
+    name = "design_pattern_detector"
+    description = "Detect simple design patterns in Python code (context manager, inheritance)."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Path to file or directory"},
+            "max_results": {"type": "integer", "description": "Max results (default 30)"},
+        },
+        "required": ["path"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        max_results = kwargs.get("max_results", 30)
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if not isinstance(max_results, int) or max_results < 1:
+            max_results = 30
+        p = Path(path).resolve()
+        if not p.exists():
+            return f"Error: path not found: {path}"
+        files = [p] if p.is_file() and p.suffix == ".py" else list(p.rglob("*.py")) if p.is_dir() else []
+        patterns = []
+        for f in files:
+            if not f.is_file():
+                continue
+            try:
+                tree = ast.parse(f.read_text(encoding="utf-8", errors="replace"))
+                rel = str(f.relative_to(p if p.is_dir() else f.parent)).replace("\\", "/")
+                for node in ast.walk(tree):
+                    if isinstance(node, ast.ClassDef):
+                        names = {n.name for n in ast.iter_child_nodes(node) if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))}
+                        if "__enter__" in names and "__exit__" in names:
+                            patterns.append({"file": rel, "pattern": "context_manager", "class": node.name})
+                        if node.bases:
+                            patterns.append({"file": rel, "pattern": "inheritance", "class": node.name, "bases": [ast.unparse(b) for b in node.bases[:3]]})
+                    if len(patterns) >= max_results:
+                        break
+            except (SyntaxError, OSError):
+                continue
+            if len(patterns) >= max_results:
+                break
+        import json
+
+        return json.dumps({"patterns": patterns}, indent=2)
+
+
+register(DesignPatternDetectorTool())

devsper/tools/code_intelligence/large_function_detector.py

@@ -0,0 +1,68 @@
+"""Detect large functions by line count and list them with locations."""
+
+import ast
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class LargeFunctionDetectorTool(Tool):
+    """
+    List functions that exceed a line-count threshold (default 50 lines).
+    """
+
+    name = "large_function_detector"
+    description = "Detect large functions by line count in Python files."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Path to file or directory"},
+            "min_lines": {"type": "integer", "description": "Minimum lines to flag (default 50)"},
+            "max_results": {"type": "integer", "description": "Max results (default 25)"},
+        },
+        "required": ["path"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        min_lines = kwargs.get("min_lines", 50)
+        max_results = kwargs.get("max_results", 25)
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if not isinstance(min_lines, int) or min_lines < 1:
+            min_lines = 50
+        if not isinstance(max_results, int) or max_results < 1:
+            max_results = 25
+        p = Path(path).resolve()
+        if not p.exists():
+            return f"Error: path not found: {path}"
+        files = [p] if p.is_file() and p.suffix == ".py" else list(p.rglob("*.py")) if p.is_dir() else []
+        large = []
+        for f in files:
+            if not f.is_file():
+                continue
+            try:
+                text = f.read_text(encoding="utf-8", errors="replace")
+                tree = ast.parse(text)
+                rel = str(f.relative_to(p if p.is_dir() else f.parent)).replace("\\", "/")
+                for node in ast.walk(tree):
+                    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        end = node.end_lineno or node.lineno
+                        line_count = end - node.lineno + 1
+                        if line_count >= min_lines:
+                            large.append({"file": rel, "function": node.name, "lines": line_count, "line_start": node.lineno})
+                    if len(large) >= max_results:
+                        break
+            except (SyntaxError, OSError):
+                continue
+            if len(large) >= max_results:
+                break
+        if not large:
+            return f"No functions with >= {min_lines} lines found."
+        import json
+
+        return json.dumps({"large_functions": large}, indent=2)
+
+
+register(LargeFunctionDetectorTool())

devsper/tools/code_intelligence/module_responsibility_mapper.py

@@ -0,0 +1,56 @@
+"""Map module responsibility using docstrings and top-level exports."""
+
+import ast
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class ModuleResponsibilityMapperTool(Tool):
+    """
+    Map each module to a short responsibility summary (docstring or first line).
+    """
+
+    name = "module_responsibility_mapper"
+    description = "Map modules to responsibility summaries (docstring/first line)."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Root path"},
+            "max_modules": {"type": "integer", "description": "Max modules (default 50)"},
+        },
+        "required": ["path"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        max_modules = kwargs.get("max_modules", 50)
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if not isinstance(max_modules, int) or max_modules < 1:
+            max_modules = 50
+        root = Path(path).resolve()
+        if not root.exists() or not root.is_dir():
+            return f"Error: path must be an existing directory: {path}"
+        results = []
+        for p in root.rglob("*.py"):
+            if len(results) >= max_modules:
+                break
+            if not p.is_file():
+                continue
+            try:
+                text = p.read_text(encoding="utf-8", errors="replace")
+                tree = ast.parse(text)
+                doc = ast.get_docstring(tree) or ""
+                first = text.strip().split("\n")[0][:60] if text.strip() else ""
+                summary = (doc.split("\n")[0] if doc else first).strip() or "(no summary)"
+                results.append({"module": str(p.relative_to(root)).replace("\\", "/"), "responsibility": summary[:200]})
+            except (SyntaxError, OSError):
+                continue
+        import json
+
+        return json.dumps({"modules": results}, indent=2)
+
+
+register(ModuleResponsibilityMapperTool())

devsper/tools/code_intelligence/parallel_codebase_analysis.py

@@ -0,0 +1,44 @@
+"""Split codebase analysis into batches for parallel/swarm processing."""
+
+import json
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class ParallelCodebaseAnalysisTool(Tool):
+    """
+    Split a codebase into file batches for parallel analysis (e.g. by swarm workers).
+    """
+
+    name = "parallel_codebase_analysis"
+    description = "Split codebase into batches for parallel analysis. Returns batch plan."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Root path"},
+            "batch_size": {"type": "integer", "description": "Files per batch (default 10)"},
+            "extension": {"type": "string", "description": "File extension (default .py)"},
+        },
+        "required": ["path"],
+    }
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        batch_size = kwargs.get("batch_size", 10)
+        extension = kwargs.get("extension", ".py")
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if not isinstance(batch_size, int) or batch_size < 1:
+            batch_size = 10
+        root = Path(path).resolve()
+        if not root.exists() or not root.is_dir():
+            return f"Error: path must be an existing directory: {path}"
+        files = [str(p.relative_to(root)).replace("\\", "/") for p in root.rglob(f"*{extension}") if p.is_file()]
+        batches = [files[i : i + batch_size] for i in range(0, len(files), batch_size)]
+        result = {"root": str(root), "total_files": len(files), "batch_size": batch_size, "num_batches": len(batches), "batches": batches}
+        return json.dumps(result, indent=2)
+
+
+register(ParallelCodebaseAnalysisTool())

devsper/tools/code_intelligence/refactor_candidate_detector.py

@@ -0,0 +1,81 @@
+"""Detect refactor candidates: long functions, high branch count, deep nesting."""
+
+import ast
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class RefactorCandidateDetectorTool(Tool):
+    """
+    Detect refactor candidates: functions with many lines, many branches, or deep nesting.
+    """
+
+    name = "refactor_candidate_detector"
+    description = "Detect refactor candidates: long functions, high complexity, deep nesting."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Path to file or directory"},
+            "min_lines": {"type": "integer", "description": "Flag functions with >= N lines (default 30)"},
+            "min_branches": {"type": "integer", "description": "Flag functions with >= N branches (default 8)"},
+        },
+        "required": ["path"],
+    }
+
+    def _complexity(self, node: ast.AST) -> tuple[int, int]:
+        branches = 0
+        max_nest = 0
+
+        def visit(n: ast.AST, depth: int) -> None:
+            nonlocal branches, max_nest
+            max_nest = max(max_nest, depth)
+            if isinstance(n, (ast.If, ast.While, ast.For, ast.With, ast.Try, ast.Assert)):
+                branches += 1
+            if isinstance(n, ast.comprehension):
+                branches += 1
+            for c in ast.iter_child_nodes(n):
+                visit(c, depth + 1)
+
+        visit(node, 0)
+        return branches, max_nest
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        min_lines = kwargs.get("min_lines", 30)
+        min_branches = kwargs.get("min_branches", 8)
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if not isinstance(min_lines, int) or min_lines < 1:
+            min_lines = 30
+        if not isinstance(min_branches, int) or min_branches < 1:
+            min_branches = 8
+        p = Path(path).resolve()
+        if not p.exists():
+            return f"Error: path not found: {path}"
+        files = [p] if p.is_file() and p.suffix == ".py" else list(p.rglob("*.py")) if p.is_dir() else []
+        candidates = []
+        for f in files:
+            if not f.is_file():
+                continue
+            try:
+                text = f.read_text(encoding="utf-8", errors="replace")
+                tree = ast.parse(text)
+                lines = text.splitlines()
+                rel = str(f.relative_to(p if p.is_dir() else f.parent)).replace("\\", "/")
+                for node in ast.walk(tree):
+                    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        start, end = node.lineno, node.end_lineno or node.lineno
+                        line_count = end - start + 1
+                        branches, nest = self._complexity(node)
+                        if line_count >= min_lines or branches >= min_branches:
+                            candidates.append({"file": rel, "name": node.name, "lines": line_count, "branches": branches, "max_nesting": nest})
+            except (SyntaxError, OSError):
+                continue
+        import json
+
+        return json.dumps({"candidates": candidates[:40]}, indent=2)
+
+
+register(RefactorCandidateDetectorTool())

devsper/tools/code_intelligence/repository_semantic_index.py

@@ -0,0 +1,61 @@
+"""Build a semantic-style index: modules and their docstrings / first line summary."""
+
+import ast
+from pathlib import Path
+
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+
+class RepositorySemanticIndexTool(Tool):
+    """
+    Index modules with docstrings and first-line summaries for semantic search (keyword match).
+    """
+
+    name = "repository_semantic_index"
+    description = "Build a semantic index of a repo: module docstrings and summaries."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Root path to index"},
+            "max_files": {"type": "integer", "description": "Max files to index (default 100)"},
+        },
+        "required": ["path"],
+    }
+
+    def _extract_summary(self, p: Path) -> dict:
+        try:
+            text = p.read_text(encoding="utf-8", errors="replace")
+            tree = ast.parse(text)
+            doc = ast.get_docstring(tree)
+            first_line = text.strip().split("\n")[0][:80] if text.strip() else ""
+            return {"docstring": (doc or "")[:300], "first_line": first_line}
+        except (SyntaxError, OSError):
+            return {"docstring": "", "first_line": ""}
+
+    def run(self, **kwargs) -> str:
+        path = kwargs.get("path")
+        max_files = kwargs.get("max_files", 100)
+        if not path or not isinstance(path, str):
+            return "Error: path must be a non-empty string"
+        if not isinstance(max_files, int) or max_files < 1:
+            max_files = 100
+        root = Path(path).resolve()
+        if not root.exists() or not root.is_dir():
+            return f"Error: path must be an existing directory: {path}"
+        entries = []
+        for p in root.rglob("*.py"):
+            if len(entries) >= max_files:
+                break
+            if not p.is_file():
+                continue
+            rel = p.relative_to(root)
+            summary = self._extract_summary(p)
+            if summary["docstring"] or summary["first_line"]:
+                entries.append({"file": str(rel), **summary})
+        import json
+
+        return json.dumps({"root": str(root), "entries": entries}, indent=2)
+
+
+register(RepositorySemanticIndexTool())