spartastruct 0.1.0__py3-none-any.whl

spartastruct/__init__.py

@@ -0,0 +1,3 @@
+"""SpartaStruct — Instant architecture diagrams for any Python codebase."""
+
+__version__ = "0.1.0"

spartastruct/analyzer/__init__.py

@@ -0,0 +1 @@
+"""Package init."""

spartastruct/analyzer/base.py

@@ -0,0 +1,127 @@
+"""Core data model for SpartaStruct analysis results.
+
+All analysis modules produce instances of these dataclasses, and all
+diagram generators and renderers consume them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ParamInfo:
+    """A single function/method parameter with optional type annotation."""
+
+    name: str
+    type: str = "Any"
+
+
+@dataclass
+class AttributeInfo:
+    """A class attribute or instance variable."""
+
+    name: str
+    type: str = "Any"
+    visibility: str = "public"  # "public", "protected", "private"
+
+
+@dataclass
+class MethodInfo:
+    """A class method with full signature information."""
+
+    name: str
+    params: list[ParamInfo] = field(default_factory=list)
+    return_type: str = "None"
+    decorators: list[str] = field(default_factory=list)
+    is_async: bool = False
+    calls: list[str] = field(default_factory=list)
+    visibility: str = "public"  # "public", "protected", "private"
+
+
+@dataclass
+class ClassInfo:
+    """A Python class with all its members and metadata."""
+
+    name: str
+    bases: list[str] = field(default_factory=list)
+    decorators: list[str] = field(default_factory=list)
+    attributes: list[AttributeInfo] = field(default_factory=list)
+    methods: list[MethodInfo] = field(default_factory=list)
+    is_abstract: bool = False
+    is_dataclass: bool = False
+    orm_type: str | None = None  # "sqlalchemy", "django", "tortoise", "peewee"
+
+
+@dataclass
+class FunctionInfo:
+    """A module-level function."""
+
+    name: str
+    params: list[ParamInfo] = field(default_factory=list)
+    return_type: str = "None"
+    decorators: list[str] = field(default_factory=list)
+    is_async: bool = False
+    calls: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ImportInfo:
+    """Classified imports for a single Python file."""
+
+    stdlib: list[str] = field(default_factory=list)
+    third_party: list[str] = field(default_factory=list)
+    local: list[str] = field(default_factory=list)  # local project import edges
+
+
+@dataclass
+class RouteInfo:
+    """An HTTP route definition (FastAPI, Flask, or Django)."""
+
+    method: str  # "GET", "POST", "PUT", "DELETE", etc. or "ANY" for Flask catch-all
+    path: str
+    handler_name: str
+
+
+@dataclass
+class FileResult:
+    """Analysis results for a single Python file."""
+
+    path: str  # relative path from project root
+    classes: list[ClassInfo] = field(default_factory=list)
+    functions: list[FunctionInfo] = field(default_factory=list)
+    imports: ImportInfo = field(default_factory=ImportInfo)
+    routes: list[RouteInfo] = field(default_factory=list)
+
+
+@dataclass
+class AnalysisResult:
+    """Top-level container for an entire project analysis run."""
+
+    files_analyzed: list[FileResult] = field(default_factory=list)
+    frameworks: list[str] = field(default_factory=list)
+    entry_points: list[str] = field(default_factory=list)  # relative file paths
+    warnings: list[str] = field(default_factory=list)
+    llm_calls_succeeded: int = 0
+    files_skipped_large: int = 0
+    files_skipped_parse_error: int = 0
+
+    @property
+    def all_classes(self) -> list[ClassInfo]:
+        """Return all ClassInfo objects across all analyzed files."""
+        return [cls for fr in self.files_analyzed for cls in fr.classes]
+
+    @property
+    def all_functions(self) -> list[FunctionInfo]:
+        """Return all FunctionInfo objects across all analyzed files."""
+        return [fn for fr in self.files_analyzed for fn in fr.functions]
+
+    @property
+    def all_routes(self) -> list[RouteInfo]:
+        """Return all RouteInfo objects across all analyzed files."""
+        return [r for fr in self.files_analyzed for r in fr.routes]
+
+    @property
+    def orm_models(self) -> list[ClassInfo]:
+        """Return all classes that are ORM models."""
+        return [cls for cls in self.all_classes if cls.orm_type is not None]

spartastruct/analyzer/base_analyzer.py

@@ -0,0 +1,20 @@
+"""Protocol defining the interface every language analyzer must satisfy."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from spartastruct.analyzer.base import AnalysisResult
+
+
+class BaseAnalyzer(Protocol):
+    """Every language analyzer must implement this interface."""
+
+    def analyze(
+        self,
+        files: list[Path],
+        warnings: list[str] | None = None,
+    ) -> AnalysisResult:
+        """Analyze a list of source files and return a complete AnalysisResult."""
+        ...

spartastruct/analyzer/js_analyzer.py

@@ -0,0 +1,233 @@
+"""Regex-based analyzer for JavaScript and TypeScript source files."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from spartastruct.analyzer.base import (
+    AnalysisResult,
+    ClassInfo,
+    FileResult,
+    FunctionInfo,
+    ImportInfo,
+    MethodInfo,
+    RouteInfo,
+)
+
+# Class / interface declarations
+_CLASS_RE = re.compile(
+    r"(?:export\s+)?(?:abstract\s+)?(?:class|interface)\s+(\w+)"
+    r"(?:\s+extends\s+([\w,\s<>]+?))?(?:\s+implements\s+([\w,\s<>]+?))?"
+    r"\s*\{",
+    re.MULTILINE,
+)
+
+# Method inside a class body
+_METHOD_RE = re.compile(
+    r"(?:(?:public|private|protected|static|async|override|abstract|readonly)\s+)*"
+    r"(\w+)\s*\([^)]*\)\s*(?::\s*[\w<>\[\]|&\s]+?)?\s*[{;]",
+    re.MULTILINE,
+)
+_METHOD_SKIP = frozenset(
+    {"if", "for", "while", "switch", "catch", "super", "return", "new", "throw"}
+)
+
+# Named function declarations
+_FUNC_DECL_RE = re.compile(
+    r"(?:export\s+)?(?P<async>async\s+)?function\s+(?P<name>\w+)\s*\(",
+    re.MULTILINE,
+)
+
+# Arrow / expression functions: const foo = (async?) (...) =>
+_ARROW_RE = re.compile(
+    r"(?:export\s+)?(?:const|let|var)\s+(?P<name>\w+)\s*=\s*(?P<async>async\s+)?\(",
+    re.MULTILINE,
+)
+
+# ES module imports
+_IMPORT_FROM_RE = re.compile(
+    r"""import\s+(?:.*?\s+from\s+)?['"]([^'"]+)['"]""",
+    re.MULTILINE | re.DOTALL,
+)
+
+# CommonJS requires
+_REQUIRE_RE = re.compile(
+    r"""(?:const|let|var)\s+\w+\s*=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)""",
+    re.MULTILINE,
+)
+
+# Express routes
+_EXPRESS_ROUTE_RE = re.compile(
+    r"(?:app|router)\.(get|post|put|patch|delete|all)\s*\(\s*['\"`]([^'\"`]+)['\"`]",
+    re.MULTILINE | re.IGNORECASE,
+)
+
+# NestJS decorator routes
+_NESTJS_ROUTE_RE = re.compile(
+    r"@(Get|Post|Put|Patch|Delete|All)\s*\(\s*(?:['\"`]([^'\"`]*)['\"`])?\s*\)",
+    re.MULTILINE,
+)
+
+_JS_ENTRY_NAMES = frozenset(
+    {"index.js", "index.ts", "main.js", "main.ts", "app.js", "app.ts", "server.js", "server.ts"}
+)
+
+
+def _extract_class_body(source: str, brace_pos: int) -> str:
+    """Return the text between the first matching { } pair starting at brace_pos."""
+    depth = 0
+    start = None
+    for i in range(brace_pos, len(source)):
+        ch = source[i]
+        if ch == "{":
+            if start is None:
+                start = i + 1
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0 and start is not None:
+                return source[start:i]
+    return ""
+
+
+def _extract_methods(class_body: str) -> list[MethodInfo]:
+    methods: list[MethodInfo] = []
+    seen: set[str] = set()
+    for m in _METHOD_RE.finditer(class_body):
+        name = m.group(1)
+        if name in _METHOD_SKIP or name in seen:
+            continue
+        seen.add(name)
+        methods.append(MethodInfo(name=name))
+    return methods
+
+
+def _classify_import(module_path: str) -> tuple[str, str]:
+    if module_path.startswith("."):
+        return "local", module_path
+    return "third_party", module_path
+
+
+def _extract_routes(source: str) -> list[RouteInfo]:
+    routes: list[RouteInfo] = []
+    for m in _EXPRESS_ROUTE_RE.finditer(source):
+        routes.append(RouteInfo(
+            method=m.group(1).upper(),
+            path=m.group(2),
+            handler_name="handler",
+        ))
+    for m in _NESTJS_ROUTE_RE.finditer(source):
+        routes.append(RouteInfo(
+            method=m.group(1).upper(),
+            path=m.group(2) or "/",
+            handler_name="handler",
+        ))
+    return routes
+
+
+def _analyze_file(file_path: Path, project_root: Path) -> FileResult:
+    try:
+        source = file_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        source = ""
+
+    try:
+        rel_path = str(file_path.relative_to(project_root))
+    except ValueError:
+        rel_path = str(file_path)
+
+    # Classes / interfaces
+    classes: list[ClassInfo] = []
+    class_spans: list[tuple[int, int]] = []
+    for m in _CLASS_RE.finditer(source):
+        name = m.group(1)
+        bases_raw = (m.group(2) or "").strip()
+        bases = [b.strip() for b in re.split(r",\s*", bases_raw) if b.strip()]
+        brace_pos = m.end() - 1
+        class_body = _extract_class_body(source, brace_pos)
+        class_spans.append((brace_pos, brace_pos + len(class_body) + 2))
+        methods = _extract_methods(class_body)
+        classes.append(ClassInfo(name=name, bases=bases, methods=methods))
+
+    def _in_class(pos: int) -> bool:
+        return any(start <= pos <= end for start, end in class_spans)
+
+    # Module-level functions
+    functions: list[FunctionInfo] = []
+    seen_fns: set[str] = set()
+
+    for m in _FUNC_DECL_RE.finditer(source):
+        if _in_class(m.start()):
+            continue
+        name = m.group("name")
+        if name in seen_fns:
+            continue
+        seen_fns.add(name)
+        functions.append(FunctionInfo(name=name, is_async=bool(m.group("async"))))
+
+    for m in _ARROW_RE.finditer(source):
+        if _in_class(m.start()):
+            continue
+        name = m.group("name")
+        if name in seen_fns:
+            continue
+        seen_fns.add(name)
+        functions.append(FunctionInfo(name=name, is_async=bool(m.group("async"))))
+
+    # Imports
+    third_party: list[str] = []
+    local: list[str] = []
+
+    for m in _IMPORT_FROM_RE.finditer(source):
+        kind, path = _classify_import(m.group(1))
+        (local if kind == "local" else third_party).append(path)
+
+    for m in _REQUIRE_RE.finditer(source):
+        kind, path = _classify_import(m.group(1))
+        (local if kind == "local" else third_party).append(path)
+
+    imports = ImportInfo(
+        third_party=list(dict.fromkeys(third_party)),
+        local=list(dict.fromkeys(local)),
+    )
+
+    routes = _extract_routes(source)
+
+    return FileResult(
+        path=rel_path, classes=classes, functions=functions, imports=imports, routes=routes
+    )
+
+
+class JsAnalyzer:
+    """Analyzes JavaScript and TypeScript source files using regex-based extraction."""
+
+    def __init__(self, project_root: Path) -> None:
+        self._root = project_root.resolve()
+
+    def analyze(
+        self,
+        files: list[Path],
+        warnings: list[str] | None = None,
+    ) -> AnalysisResult:
+        if warnings is None:
+            warnings = []
+
+        file_results: list[FileResult] = []
+        for file_path in files:
+            try:
+                fr = _analyze_file(file_path, self._root)
+                file_results.append(fr)
+            except Exception as exc:  # noqa: BLE001
+                warnings.append(f"Failed to analyze {file_path.name}: {exc}")
+
+        entry_points = [
+            fr.path for fr in file_results
+            if Path(fr.path).name in _JS_ENTRY_NAMES
+        ]
+
+        return AnalysisResult(
+            files_analyzed=file_results,
+            entry_points=entry_points,
+            warnings=warnings,
+        )