suitable-loop 0.1.0__py3-none-any.whl

suitable_loop/__init__.py

@@ -0,0 +1,3 @@
+"""Suitable Loop — Local Production Engineering Platform."""
+
+__version__ = "0.1.0"

suitable_loop/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m suitable_loop`."""
+
+from .server import main
+
+main()

suitable_loop/analyzers/__init__.py

@@ -0,0 +1 @@
+"""Suitable Loop analysis engines."""

suitable_loop/analyzers/code_analyzer.py

@@ -0,0 +1,652 @@
+"""AST-based Python code analyzer for Suitable Loop.
+
+Walks a project directory, parses Python source files, and extracts
+functions, classes, imports, and call relationships into the database.
+"""
+
+from __future__ import annotations
+
+import ast
+import fnmatch
+import hashlib
+import logging
+import time
+from pathlib import Path
+
+from suitable_loop.config import SuitableLoopConfig
+from suitable_loop.db import Database
+from suitable_loop.models import (
+    CallEdge,
+    ClassEntity,
+    FileDependency,
+    FileEntity,
+    FunctionEntity,
+    ImportEntity,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _end_line(node: ast.AST) -> int:
+    """Return the end line of an AST node, falling back to start line."""
+    return getattr(node, "end_lineno", None) or node.lineno
+
+
+def _get_docstring(node: ast.AST) -> str | None:
+    """Extract the docstring from a function or class node."""
+    try:
+        return ast.get_docstring(node)
+    except Exception:
+        return None
+
+
+def _signature_from_args(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+    """Build a human-readable signature string from function arguments."""
+    parts: list[str] = []
+    args = node.args
+
+    # Positional-only args
+    for arg in args.posonlyargs:
+        parts.append(arg.arg)
+    if args.posonlyargs:
+        parts.append("/")
+
+    # Regular positional args
+    num_defaults = len(args.defaults)
+    num_args = len(args.args)
+    for i, arg in enumerate(args.args):
+        name = arg.arg
+        default_idx = i - (num_args - num_defaults)
+        if default_idx >= 0:
+            name += "=..."
+        parts.append(name)
+
+    # *args
+    if args.vararg:
+        parts.append(f"*{args.vararg.arg}")
+    elif args.kwonlyargs:
+        parts.append("*")
+
+    # Keyword-only args
+    for i, arg in enumerate(args.kwonlyargs):
+        name = arg.arg
+        if i < len(args.kw_defaults) and args.kw_defaults[i] is not None:
+            name += "=..."
+        parts.append(name)
+
+    # **kwargs
+    if args.kwarg:
+        parts.append(f"**{args.kwarg.arg}")
+
+    return f"({', '.join(parts)})"
+
+
+class _CallCollector(ast.NodeVisitor):
+    """Collect function calls within a function body.
+
+    Each call is recorded as (callee_name, line_number).  For attribute
+    calls like ``self.foo()`` or ``module.bar()`` the full dotted name
+    is stored.
+    """
+
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, int]] = []
+
+    def visit_Call(self, node: ast.Call) -> None:  # noqa: N802
+        name = self._resolve_call_name(node.func)
+        if name:
+            self.calls.append((name, node.lineno))
+        self.generic_visit(node)
+
+    @staticmethod
+    def _resolve_call_name(node: ast.expr) -> str | None:
+        if isinstance(node, ast.Name):
+            return node.id
+        if isinstance(node, ast.Attribute):
+            parts: list[str] = [node.attr]
+            current = node.value
+            while isinstance(current, ast.Attribute):
+                parts.append(current.attr)
+                current = current.value
+            if isinstance(current, ast.Name):
+                parts.append(current.id)
+            parts.reverse()
+            return ".".join(parts)
+        return None
+
+
+class CodeAnalyzer:
+    """Indexes a Python codebase by parsing ASTs and persisting entities."""
+
+    def __init__(self, db: Database, config: SuitableLoopConfig) -> None:
+        self.db = db
+        self.config = config
+        # Temporary storage for raw calls accumulated during file indexing.
+        # List of (file_path, caller_qualified_name, callee_name, line).
+        self._raw_calls: list[tuple[str, str, str, int]] = []
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def index_codebase(self, project_path: str, force: bool = False) -> dict:
+        """Walk *project_path* and index every ``.py`` file.
+
+        Returns a summary dict with counts of files, functions, classes,
+        imports, and call edges processed.
+        """
+        root = Path(project_path).resolve()
+        if not root.is_dir():
+            raise FileNotFoundError(f"Project path does not exist: {root}")
+
+        self._raw_calls.clear()
+
+        py_files = self._discover_files(root)
+        logger.info("Discovered %d Python files in %s", len(py_files), root)
+
+        stats: dict[str, int] = {
+            "files_total": len(py_files),
+            "files_indexed": 0,
+            "files_skipped": 0,
+            "functions": 0,
+            "classes": 0,
+            "imports": 0,
+            "call_edges": 0,
+        }
+
+        for file_path in py_files:
+            file_stats = self._index_file(file_path, str(root), force=force)
+            if file_stats["indexed"]:
+                stats["files_indexed"] += 1
+                stats["functions"] += file_stats["functions"]
+                stats["classes"] += file_stats["classes"]
+                stats["imports"] += file_stats["imports"]
+            else:
+                stats["files_skipped"] += 1
+
+        # Resolve file-level dependencies now that all files are in the DB.
+        self._resolve_file_dependencies(str(root))
+
+        # Resolve raw calls across the whole project into call edges.
+        edge_count = self._resolve_calls(str(root))
+        stats["call_edges"] = edge_count
+
+        self.db.commit()
+        logger.info(
+            "Indexing complete: %d files indexed, %d skipped, %d functions, "
+            "%d classes, %d call edges",
+            stats["files_indexed"],
+            stats["files_skipped"],
+            stats["functions"],
+            stats["classes"],
+            stats["call_edges"],
+        )
+        return stats
+
+    # ------------------------------------------------------------------
+    # File-level indexing
+    # ------------------------------------------------------------------
+
+    def _index_file(
+        self, file_path: Path, project_root: str, *, force: bool = False
+    ) -> dict:
+        """Index a single Python file.
+
+        Returns a small dict with keys ``indexed`` (bool) and entity counts.
+        """
+        result = {"indexed": False, "functions": 0, "classes": 0, "imports": 0}
+
+        try:
+            source = file_path.read_text(encoding="utf-8", errors="replace")
+        except OSError as exc:
+            logger.warning("Cannot read %s: %s", file_path, exc)
+            return result
+
+        content_hash = hashlib.sha256(source.encode("utf-8")).hexdigest()
+        stat = file_path.stat()
+        rel_path = str(file_path)
+
+        # Check whether the file has changed since the last indexing.
+        existing = self.db.get_file_by_path(rel_path)
+        if existing and not force and existing.hash == content_hash:
+            logger.debug("Skipping unchanged file: %s", rel_path)
+            return result
+
+        # Upsert the file entity.
+        file_entity = FileEntity(
+            path=rel_path,
+            project_root=project_root,
+            size_bytes=stat.st_size,
+            last_modified=stat.st_mtime,
+            last_indexed=time.time(),
+            line_count=source.count("\n") + 1,
+            hash=content_hash,
+        )
+        file_id = self.db.upsert_file(file_entity)
+
+        # Clear stale data for this file before re-inserting.
+        self.db.clear_file_data(file_id)
+
+        # Parse the AST.
+        try:
+            functions, classes, imports, raw_calls = self._parse_ast(source, rel_path)
+        except SyntaxError as exc:
+            logger.warning("Syntax error in %s: %s", rel_path, exc)
+            return result
+
+        # Compute cyclomatic complexity for each function.
+        complexity_map = self._compute_complexity(source)
+
+        # Persist functions.
+        for func in functions:
+            func.file_id = file_id
+            func.complexity = complexity_map.get(func.name, 0)
+            self.db.insert_function(func)
+        result["functions"] = len(functions)
+
+        # Persist classes.
+        for cls in classes:
+            cls.file_id = file_id
+            self.db.insert_class(cls)
+        result["classes"] = len(classes)
+
+        # Persist imports (file dependencies are resolved in a second pass).
+        for imp in imports:
+            imp.file_id = file_id
+            self.db.insert_import(imp)
+        result["imports"] = len(imports)
+
+        # Stash raw calls for cross-file resolution later.
+        for caller_qname, callee_name, line in raw_calls:
+            self._raw_calls.append((rel_path, caller_qname, callee_name, line))
+
+        self.db.commit()
+        result["indexed"] = True
+        return result
+
+    # ------------------------------------------------------------------
+    # AST parsing
+    # ------------------------------------------------------------------
+
+    def _parse_ast(
+        self, source: str, file_path: str
+    ) -> tuple[
+        list[FunctionEntity],
+        list[ClassEntity],
+        list[ImportEntity],
+        list[tuple[str, str, int]],
+    ]:
+        """Parse *source* and extract entities.
+
+        Returns:
+            (functions, classes, imports, raw_calls)
+            where raw_calls is a list of ``(caller_qualified_name, callee_name, line)``.
+        """
+        tree = ast.parse(source, filename=file_path)
+
+        functions: list[FunctionEntity] = []
+        classes: list[ClassEntity] = []
+        imports: list[ImportEntity] = []
+        raw_calls: list[tuple[str, str, int]] = []
+
+        module_name = self._path_to_module(file_path)
+
+        for node in ast.iter_child_nodes(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                func = self._extract_function(node, module_name, class_name=None)
+                functions.append(func)
+                raw_calls.extend(
+                    self._collect_calls(node, func.qualified_name)
+                )
+
+            elif isinstance(node, ast.ClassDef):
+                cls = self._extract_class(node, module_name)
+                classes.append(cls)
+                # Extract methods inside the class.
+                for item in ast.iter_child_nodes(node):
+                    if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        method = self._extract_function(
+                            item, module_name, class_name=node.name
+                        )
+                        functions.append(method)
+                        raw_calls.extend(
+                            self._collect_calls(item, method.qualified_name)
+                        )
+
+            elif isinstance(node, ast.Import):
+                for alias in node.names:
+                    imports.append(
+                        ImportEntity(module=alias.name, alias=alias.asname)
+                    )
+
+            elif isinstance(node, ast.ImportFrom):
+                base = node.module or ""
+                for alias in node.names:
+                    full_module = f"{base}.{alias.name}" if base else alias.name
+                    imports.append(
+                        ImportEntity(module=full_module, alias=alias.asname)
+                    )
+
+        return functions, classes, imports, raw_calls
+
+    # ------------------------------------------------------------------
+    # Entity extraction helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _extract_function(
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+        module_name: str,
+        class_name: str | None,
+    ) -> FunctionEntity:
+        if class_name:
+            qualified_name = f"{module_name}.{class_name}.{node.name}"
+        else:
+            qualified_name = f"{module_name}.{node.name}"
+
+        return FunctionEntity(
+            name=node.name,
+            qualified_name=qualified_name,
+            class_name=class_name,
+            line_start=node.lineno,
+            line_end=_end_line(node),
+            signature=_signature_from_args(node),
+            docstring=_get_docstring(node),
+            is_method=class_name is not None,
+            is_async=isinstance(node, ast.AsyncFunctionDef),
+        )
+
+    @staticmethod
+    def _extract_class(node: ast.ClassDef, module_name: str) -> ClassEntity:
+        bases = []
+        for base in node.bases:
+            if isinstance(base, ast.Name):
+                bases.append(base.id)
+            elif isinstance(base, ast.Attribute):
+                parts: list[str] = [base.attr]
+                current = base.value
+                while isinstance(current, ast.Attribute):
+                    parts.append(current.attr)
+                    current = current.value
+                if isinstance(current, ast.Name):
+                    parts.append(current.id)
+                parts.reverse()
+                bases.append(".".join(parts))
+
+        return ClassEntity(
+            name=node.name,
+            qualified_name=f"{module_name}.{node.name}",
+            line_start=node.lineno,
+            line_end=_end_line(node),
+            bases=bases,
+            docstring=_get_docstring(node),
+        )
+
+    @staticmethod
+    def _collect_calls(
+        node: ast.FunctionDef | ast.AsyncFunctionDef, caller_qname: str
+    ) -> list[tuple[str, str, int]]:
+        collector = _CallCollector()
+        collector.visit(node)
+        return [(caller_qname, name, line) for name, line in collector.calls]
+
+    # ------------------------------------------------------------------
+    # File dependency resolution (second pass)
+    # ------------------------------------------------------------------
+
+    def _resolve_file_dependencies(self, project_root: str) -> None:
+        """Resolve imports to file dependencies now that all files are indexed."""
+        all_files = self.db.get_all_files(project_root)
+
+        for f in all_files:
+            self.db.delete_file_dependencies_by_source(f.id)
+            imports = self.db.get_imports_by_file(f.id)
+            for imp in imports:
+                resolved = self._resolve_import_to_file(imp.module, project_root)
+                if resolved is not None and resolved.id != f.id:
+                    self.db.insert_file_dependency(
+                        FileDependency(source_file_id=f.id, target_file_id=resolved.id)
+                    )
+
+        self.db.commit()
+
+    # ------------------------------------------------------------------
+    # Call resolution
+    # ------------------------------------------------------------------
+
+    def _resolve_calls(self, project_root: str) -> int:
+        """Resolve accumulated raw calls into :class:`CallEdge` records.
+
+        Resolution strategy (in order):
+        1. ``self.<method>()`` — look for a method with the same class in the
+           same file.
+        2. Bare ``func()`` — look in the same module, then across the project.
+        3. ``module.func()`` — try to match via imports recorded in the same
+           file.
+
+        Returns the number of call edges inserted.
+        """
+        # Build lookup caches.
+        all_files = self.db.get_all_files(project_root)
+        # qname -> FunctionEntity (with id populated)
+        qname_index: dict[str, FunctionEntity] = {}
+        # bare name -> list of FunctionEntity
+        name_index: dict[str, list[FunctionEntity]] = {}
+        # file_path -> file_id
+        file_id_index: dict[str, int] = {}
+
+        for f in all_files:
+            file_id_index[f.path] = f.id  # type: ignore[arg-type]
+            for func in self.db.get_functions_by_file(f.id):  # type: ignore[arg-type]
+                qname_index[func.qualified_name] = func
+                name_index.setdefault(func.name, []).append(func)
+
+        # Build import alias index: (file_path, alias_or_module_tail) -> full module
+        import_alias_index: dict[tuple[str, str], str] = {}
+        for f in all_files:
+            for imp in self.db.get_imports_by_file(f.id):  # type: ignore[arg-type]
+                key_name = imp.alias or imp.module.rsplit(".", 1)[-1]
+                import_alias_index[(f.path, key_name)] = imp.module
+
+        inserted = 0
+        for file_path, caller_qname, callee_name, line in self._raw_calls:
+            caller = qname_index.get(caller_qname)
+            if caller is None:
+                continue
+
+            file_id = file_id_index.get(file_path)
+            callee = self._resolve_single_call(
+                caller_qname, callee_name, file_path,
+                qname_index, name_index, import_alias_index,
+            )
+            if callee is None:
+                continue
+
+            edge = CallEdge(
+                caller_id=caller.id,
+                callee_id=callee.id,
+                file_id=file_id,
+                line_number=line,
+            )
+            if self.db.insert_call_edge(edge) is not None:
+                inserted += 1
+
+        self._raw_calls.clear()
+        return inserted
+
+    @staticmethod
+    def _resolve_single_call(
+        caller_qname: str,
+        callee_name: str,
+        file_path: str,
+        qname_index: dict[str, FunctionEntity],
+        name_index: dict[str, list[FunctionEntity]],
+        import_alias_index: dict[tuple[str, str], str],
+    ) -> FunctionEntity | None:
+        # Derive the module part of the caller's qualified name.
+        # For "pkg.mod.Class.method" the module is "pkg.mod".
+        caller_parts = caller_qname.rsplit(".", 1)
+        caller_module = caller_parts[0] if len(caller_parts) > 1 else ""
+        # If caller is a method, module is one level higher.
+        # e.g. "pkg.mod.MyClass.my_method" -> class_prefix = "pkg.mod.MyClass"
+        # We try the class prefix first for self.* calls.
+
+        # 1. self.<method> — resolve within the same class.
+        if "." in callee_name:
+            prefix, method_name = callee_name.rsplit(".", 1)
+            if prefix == "self":
+                # caller_qname is like "mod.Class.method"; class qname is "mod.Class"
+                class_qname = caller_qname.rsplit(".", 1)[0]
+                candidate_qname = f"{class_qname}.{method_name}"
+                if candidate_qname in qname_index:
+                    return qname_index[candidate_qname]
+
+            # 3. module.func() — resolve via imports.
+            # prefix might be an import alias.
+            resolved_module = import_alias_index.get((file_path, prefix))
+            if resolved_module:
+                candidate_qname = f"{resolved_module}.{method_name}"
+                if candidate_qname in qname_index:
+                    return qname_index[candidate_qname]
+
+            # Try direct dotted qualified name in the same module.
+            candidate_qname = f"{caller_module}.{callee_name}"
+            if candidate_qname in qname_index:
+                return qname_index[candidate_qname]
+
+            return None
+
+        # 2. Bare func() — same module first, then project-wide.
+        same_module_qname = f"{caller_module}.{callee_name}"
+        if same_module_qname in qname_index:
+            return qname_index[same_module_qname]
+
+        # Check if callee_name matches an import alias that points to a function.
+        resolved_module = import_alias_index.get((file_path, callee_name))
+        if resolved_module and resolved_module in qname_index:
+            return qname_index[resolved_module]
+
+        # Fall back to first project-wide match by bare name.
+        candidates = name_index.get(callee_name, [])
+        if len(candidates) == 1:
+            return candidates[0]
+
+        return None
+
+    # ------------------------------------------------------------------
+    # Cyclomatic complexity via radon
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _compute_complexity(source: str) -> dict[str, int]:
+        """Return ``{function_name: complexity}`` for all functions in *source*.
+
+        Uses ``radon.complexity`` when available; returns an empty dict if
+        radon is not installed or the source cannot be analysed.
+        """
+        try:
+            from radon.complexity import cc_visit  # type: ignore[import-untyped]
+        except ImportError:
+            logger.debug("radon is not installed; skipping complexity analysis")
+            return {}
+
+        try:
+            blocks = cc_visit(source)
+        except Exception:
+            return {}
+
+        result: dict[str, int] = {}
+        for block in blocks:
+            result[block.name] = block.complexity
+        return result
+
+    # ------------------------------------------------------------------
+    # File discovery
+    # ------------------------------------------------------------------
+
+    def _discover_files(self, root: Path) -> list[Path]:
+        """Recursively find ``.py`` files under *root*, respecting config."""
+        exclude_patterns = self.config.analysis.exclude_patterns
+        max_size = self.config.analysis.max_file_size_kb * 1024
+
+        results: list[Path] = []
+        for py_file in root.rglob("*.py"):
+            rel = str(py_file.relative_to(root))
+            if self._is_excluded(rel, exclude_patterns):
+                continue
+            try:
+                if py_file.stat().st_size > max_size:
+                    logger.debug("Skipping oversized file: %s", py_file)
+                    continue
+            except OSError:
+                continue
+            results.append(py_file)
+
+        return sorted(results)
+
+    @staticmethod
+    def _is_excluded(rel_path: str, patterns: list[str]) -> bool:
+        parts = rel_path.replace("\\", "/").split("/")
+        for pattern in patterns:
+            # Strip **/ wrappers to get the core directory name.
+            core = pattern.strip("*").strip("/")
+            if core and core in parts:
+                return True
+            if fnmatch.fnmatch(rel_path, pattern):
+                return True
+        return False
+
+    # ------------------------------------------------------------------
+    # Import resolution helpers
+    # ------------------------------------------------------------------
+
+    def _resolve_import_to_file(
+        self, module: str, project_root: str
+    ) -> FileEntity | None:
+        """Try to map an import module string to a file already in the DB.
+
+        Handles several forms:
+        - ``codezero.db`` — full dotted module
+        - ``db`` — bare module name
+        - ``db.Database`` — module.name where name is a class/function, not a
+          sub-module — we try the full path first, then strip the last
+          component and retry.
+        """
+        root = Path(project_root)
+
+        # Try progressively shorter suffixes of the dotted path.  For each
+        # suffix also try dropping the last component (it may be a symbol name,
+        # not a sub-package).
+        parts = module.split(".")
+        attempts: list[list[str]] = []
+        for start in range(len(parts)):
+            sub = parts[start:]
+            if sub:
+                attempts.append(sub)
+            # Also try without the last component (e.g. "db.Database" -> "db")
+            if len(sub) > 1:
+                attempts.append(sub[:-1])
+
+        for sub in attempts:
+            candidates = [
+                root / Path(*sub).with_suffix(".py"),
+                root / Path(*sub) / "__init__.py",
+            ]
+            for candidate in candidates:
+                entity = self.db.get_file_by_path(str(candidate))
+                if entity is not None:
+                    return entity
+        return None
+
+    @staticmethod
+    def _path_to_module(file_path: str) -> str:
+        """Convert a file path to a dotted module name.
+
+        ``/project/pkg/mod.py``  ->  ``pkg.mod``
+        ``/project/pkg/__init__.py``  ->  ``pkg``
+        """
+        p = Path(file_path)
+        parts = list(p.with_suffix("").parts)
+        if parts and parts[-1] == "__init__":
+            parts.pop()
+        return ".".join(parts[-3:]) if len(parts) > 3 else ".".join(parts)