sourcecode 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Genera mapas de contexto estructurado para agentes IA."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

sourcecode/cli.py

@@ -51,6 +51,11 @@ def main(
         "--dependencies",
         help="Incluir dependencias directas, versiones exactas y transitivas cuando haya lockfiles compatibles",
     ),
+    graph_modules: bool = typer.Option(
+        False,
+        "--graph-modules",
+        help="Incluir grafo estructural de modulos, imports y relaciones simples del codigo",
+    ),
     no_redact: bool = typer.Option(
         False,
         "--no-redact",
@@ -95,6 +100,7 @@ def main(
 
     from sourcecode.dependency_analyzer import DependencyAnalyzer
     from sourcecode.detectors import ProjectDetector, build_default_detectors
+    from sourcecode.graph_analyzer import GraphAnalyzer
     from sourcecode.redactor import SecretRedactor, redact_dict
     from sourcecode.scanner import FileScanner
     from sourcecode.schema import AnalysisMetadata, EntryPoint, SourceMap, StackDetection
@@ -118,11 +124,33 @@ def main(
                 filtered[name] = value
         return filtered
 
+    def prune_workspace_paths(
+        tree: dict[str, Any], workspace_paths: list[str]
+    ) -> dict[str, Any]:
+        pruned = dict(tree)
+        for workspace_path in workspace_paths:
+            parts = [part for part in workspace_path.split("/") if part]
+            if not parts:
+                continue
+            node = pruned
+            for index, part in enumerate(parts):
+                if not isinstance(node, dict) or part not in node:
+                    break
+                if index == len(parts) - 1:
+                    node.pop(part, None)
+                    break
+                child = node.get(part)
+                if not isinstance(child, dict):
+                    break
+                node = child
+        return pruned
+
     file_tree = filter_sensitive_files(raw_tree)
     manifests = scanner.find_manifests()
     detector = ProjectDetector(build_default_detectors())
     workspace_analysis = WorkspaceAnalyzer().analyze(target, manifests)
     dependency_analyzer = DependencyAnalyzer() if dependencies else None
+    graph_analyzer = GraphAnalyzer() if graph_modules else None
 
     root_manifests = [
         manifest
@@ -142,6 +170,17 @@ def main(
         root_dependencies, root_summary = dependency_analyzer.analyze(target)
         dependency_records.extend(root_dependencies)
         dependency_summaries.append(root_summary)
+    module_graphs = []
+    if graph_analyzer is not None:
+        root_graph_tree = (
+            prune_workspace_paths(
+                file_tree,
+                [workspace.path for workspace in workspace_analysis.workspaces],
+            )
+            if workspace_analysis.workspaces
+            else file_tree
+        )
+        module_graphs.append(graph_analyzer.analyze(target, root_graph_tree))
 
     for workspace in workspace_analysis.workspaces:
         workspace_root = target / workspace.path
@@ -174,6 +213,15 @@ def main(
             )
             dependency_records.extend(workspace_dependencies)
             dependency_summaries.append(workspace_summary)
+        if graph_analyzer is not None:
+            workspace_graph = graph_analyzer.analyze(
+                    workspace_root,
+                    workspace_tree,
+                    workspace=workspace.path,
+                )
+            module_graphs.append(
+                graph_analyzer.prefix_graph(workspace_graph, workspace.path, workspace.path)
+            )
 
     stacks, project_type = detector.classify_results(
         file_tree,
@@ -186,6 +234,7 @@ def main(
         if dependency_analyzer is not None
         else None
     )
+    module_graph = graph_analyzer.merge_graphs(module_graphs) if graph_analyzer is not None else None
 
     # 3. Construir el schema
     metadata = AnalysisMetadata(analyzed_path=str(target))
@@ -197,6 +246,7 @@ def main(
         entry_points=entry_points,
         dependencies=dependency_records,
         dependency_summary=dependency_summary,
+        module_graph=module_graph,
     )
 
     # 4. Serializar (con o sin modo compact)

sourcecode/graph_analyzer.py

@@ -0,0 +1,759 @@
+"""Analisis estructural offline para modulos, imports y relaciones simples."""
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import replace
+from pathlib import Path, PurePosixPath
+from typing import Any, Optional
+
+from sourcecode.schema import GraphEdge, GraphNode, ModuleGraph, ModuleGraphSummary
+from sourcecode.tree_utils import flatten_file_tree
+
+
+class GraphAnalyzer:
+    """Construye un grafo estructural parcial y seguro del proyecto."""
+
+    _PYTHON_EXTENSIONS = {".py"}
+    _NODE_EXTENSIONS = {".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"}
+    _GO_EXTENSIONS = {".go"}
+    _JVM_EXTENSIONS = {".java", ".kt", ".scala"}
+    _SUPPORTED_EXTENSIONS = _PYTHON_EXTENSIONS | _NODE_EXTENSIONS | _GO_EXTENSIONS | _JVM_EXTENSIONS
+
+    def __init__(
+        self,
+        *,
+        max_files: int = 200,
+        max_file_size: int = 200_000,
+        max_nodes: int = 1_000,
+        max_edges: int = 2_000,
+    ) -> None:
+        self.max_files = max_files
+        self.max_file_size = max_file_size
+        self.max_nodes = max_nodes
+        self.max_edges = max_edges
+
+    def analyze(
+        self,
+        root: Path,
+        file_tree: dict[str, Any],
+        *,
+        workspace: str | None = None,
+    ) -> ModuleGraph:
+        source_files = [
+            path
+            for path in flatten_file_tree(file_tree)
+            if Path(path).suffix in self._SUPPORTED_EXTENSIONS and (root / path).is_file()
+        ]
+        limitations: list[str] = []
+        if len(source_files) > self.max_files:
+            limitations.append(
+                f"max_files_reached:{len(source_files)}>{self.max_files}"
+            )
+            source_files = source_files[: self.max_files]
+
+        nodes: list[GraphNode] = []
+        edges: list[GraphEdge] = []
+        node_ids: set[str] = set()
+        edge_keys: set[tuple[str, str, str, str]] = set()
+
+        python_modules = self._build_python_module_map(source_files)
+        node_modules = {path: path for path in source_files if Path(path).suffix in self._NODE_EXTENSIONS}
+        go_imports = self._build_go_import_map(root, source_files)
+        jvm_types = self._build_jvm_type_map(root, source_files)
+
+        for relative_path in source_files:
+            absolute_path = root / relative_path
+            try:
+                if absolute_path.stat().st_size > self.max_file_size:
+                    limitations.append(f"file_too_large:{relative_path}")
+                    continue
+                content = absolute_path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                limitations.append(f"read_error:{relative_path}")
+                continue
+
+            suffix = absolute_path.suffix
+            module_node = GraphNode(
+                id=f"module:{relative_path}",
+                kind="module",
+                language=self._language_for_suffix(suffix),
+                path=relative_path,
+                display_name=relative_path,
+                workspace=workspace,
+            )
+            self._append_node(nodes, node_ids, module_node)
+
+            file_nodes: list[GraphNode] = []
+            file_edges: list[GraphEdge] = []
+            file_limitations: list[str] = []
+
+            if suffix in self._PYTHON_EXTENSIONS:
+                file_nodes, file_edges, file_limitations = self._analyze_python_file(
+                    relative_path, content, python_modules, workspace
+                )
+            elif suffix in self._NODE_EXTENSIONS:
+                file_nodes, file_edges, file_limitations = self._analyze_node_file(
+                    relative_path, content, node_modules, workspace
+                )
+            elif suffix in self._GO_EXTENSIONS:
+                file_nodes, file_edges, file_limitations = self._analyze_go_file(
+                    relative_path, content, go_imports, workspace
+                )
+            elif suffix in self._JVM_EXTENSIONS:
+                file_nodes, file_edges, file_limitations = self._analyze_jvm_file(
+                    relative_path, content, jvm_types, workspace
+                )
+
+            limitations.extend(file_limitations)
+            for node in file_nodes:
+                self._append_node(nodes, node_ids, node)
+            for edge in file_edges:
+                self._append_edge(edges, edge_keys, edge)
+            if len(nodes) >= self.max_nodes or len(edges) >= self.max_edges:
+                limitations.append("graph_budget_reached")
+                break
+
+        if len(nodes) > self.max_nodes:
+            nodes = nodes[: self.max_nodes]
+        if len(edges) > self.max_edges:
+            edges = edges[: self.max_edges]
+
+        summary = ModuleGraphSummary(
+            requested=True,
+            node_count=len(nodes),
+            edge_count=len(edges),
+            languages=sorted({node.language for node in nodes}),
+            methods=sorted({edge.method for edge in edges}),
+            limitations=self._unique(limitations),
+        )
+        return ModuleGraph(nodes=nodes, edges=edges, summary=summary)
+
+    def merge_graphs(self, graphs: list[ModuleGraph]) -> ModuleGraph:
+        nodes: list[GraphNode] = []
+        edges: list[GraphEdge] = []
+        limitations: list[str] = []
+        node_ids: set[str] = set()
+        edge_keys: set[tuple[str, str, str, str]] = set()
+        for graph in graphs:
+            for node in graph.nodes:
+                self._append_node(nodes, node_ids, node)
+            for edge in graph.edges:
+                self._append_edge(edges, edge_keys, edge)
+            limitations.extend(graph.summary.limitations)
+        return ModuleGraph(
+            nodes=nodes,
+            edges=edges,
+            summary=ModuleGraphSummary(
+                requested=bool(graphs),
+                node_count=len(nodes),
+                edge_count=len(edges),
+                languages=sorted({node.language for node in nodes}),
+                methods=sorted({edge.method for edge in edges}),
+                limitations=self._unique(limitations),
+            ),
+        )
+
+    def prefix_graph(self, graph: ModuleGraph, prefix: str, workspace: str) -> ModuleGraph:
+        """Reescribe ids y paths de un grafo de workspace al espacio de paths del repo."""
+        node_id_map: dict[str, str] = {}
+        prefixed_nodes: list[GraphNode] = []
+        clean_prefix = prefix.strip("/")
+        for node in graph.nodes:
+            prefixed_path = f"{clean_prefix}/{node.path}".strip("/")
+            new_id = self._node_id(node.kind, prefixed_path, node.symbol)
+            node_id_map[node.id] = new_id
+            prefixed_nodes.append(
+                replace(
+                    node,
+                    id=new_id,
+                    path=prefixed_path,
+                    workspace=workspace,
+                )
+            )
+        prefixed_edges: list[GraphEdge] = []
+        for edge in graph.edges:
+            prefixed_edges.append(
+                replace(
+                    edge,
+                    source=node_id_map.get(edge.source, edge.source),
+                    target=node_id_map.get(edge.target, edge.target),
+                )
+            )
+        return ModuleGraph(
+            nodes=prefixed_nodes,
+            edges=prefixed_edges,
+            summary=replace(graph.summary),
+        )
+
+    def _analyze_python_file(
+        self,
+        relative_path: str,
+        content: str,
+        module_map: dict[str, str],
+        workspace: str | None,
+    ) -> tuple[list[GraphNode], list[GraphEdge], list[str]]:
+        limitations: list[str] = []
+        try:
+            tree = ast.parse(content, filename=relative_path)
+        except SyntaxError:
+            return [], [], [f"python_parse_error:{relative_path}"]
+
+        module_node_id = f"module:{relative_path}"
+        current_module = module_map.get(relative_path)
+        nodes: list[GraphNode] = []
+        edges: list[GraphEdge] = []
+        function_node_ids: dict[str, str] = {}
+        class_node_ids: dict[str, str] = {}
+        imported_function_node_ids: dict[str, str] = {}
+        imported_class_node_ids: dict[str, str] = {}
+
+        for node in tree.body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                function_node_id = f"function:{relative_path}:{node.name}"
+                function_node_ids[node.name] = function_node_id
+                nodes.append(
+                    GraphNode(
+                        id=function_node_id,
+                        kind="function",
+                        language="python",
+                        path=relative_path,
+                        symbol=node.name,
+                        display_name=node.name,
+                        workspace=workspace,
+                    )
+                )
+                edges.append(
+                    GraphEdge(
+                        source=module_node_id,
+                        target=function_node_id,
+                        kind="contains",
+                        confidence="high",
+                        method="ast",
+                    )
+                )
+            elif isinstance(node, ast.ClassDef):
+                class_node_id = f"class:{relative_path}:{node.name}"
+                class_node_ids[node.name] = class_node_id
+                nodes.append(
+                    GraphNode(
+                        id=class_node_id,
+                        kind="class",
+                        language="python",
+                        path=relative_path,
+                        symbol=node.name,
+                        display_name=node.name,
+                        workspace=workspace,
+                    )
+                )
+                edges.append(
+                    GraphEdge(
+                        source=module_node_id,
+                        target=class_node_id,
+                        kind="contains",
+                        confidence="high",
+                        method="ast",
+                    )
+                )
+
+        for ast_node in ast.walk(tree):
+            if isinstance(ast_node, ast.Import):
+                for alias in ast_node.names:
+                    target_path = self._resolve_python_import(alias.name, module_map)
+                    if target_path is None:
+                        continue
+                    edges.append(
+                        GraphEdge(
+                            source=module_node_id,
+                            target=f"module:{target_path}",
+                            kind="imports",
+                            confidence="high",
+                            method="ast",
+                        )
+                    )
+            elif isinstance(ast_node, ast.ImportFrom):
+                target_path = self._resolve_python_from_import(
+                    ast_node, current_module, module_map
+                )
+                if target_path is None:
+                    continue
+                edges.append(
+                    GraphEdge(
+                        source=module_node_id,
+                        target=f"module:{target_path}",
+                        kind="imports",
+                        confidence="high",
+                        method="ast",
+                    )
+                )
+                for alias in ast_node.names:
+                    local_name = alias.asname or alias.name
+                    imported_function_node_ids[local_name] = (
+                        f"function:{target_path}:{alias.name}"
+                    )
+                    imported_class_node_ids[local_name] = (
+                        f"class:{target_path}:{alias.name}"
+                    )
+
+        for top_level in tree.body:
+            if isinstance(top_level, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                source_id = function_node_ids.get(top_level.name)
+                if source_id is None:
+                    continue
+                for nested in ast.walk(top_level):
+                    if isinstance(nested, ast.Call) and isinstance(nested.func, ast.Name):
+                        target_id = function_node_ids.get(nested.func.id) or imported_function_node_ids.get(
+                            nested.func.id
+                        )
+                        if target_id is not None and target_id != source_id:
+                            edges.append(
+                                GraphEdge(
+                                    source=source_id,
+                                    target=target_id,
+                                    kind="calls",
+                                    confidence="medium",
+                                    method="ast",
+                                )
+                            )
+            elif isinstance(top_level, ast.ClassDef):
+                source_id = class_node_ids.get(top_level.name)
+                if source_id is None:
+                    continue
+                for base in top_level.bases:
+                    if isinstance(base, ast.Name):
+                        target_id = class_node_ids.get(base.id) or imported_class_node_ids.get(
+                            base.id
+                        )
+                        if target_id is not None:
+                            edges.append(
+                                GraphEdge(
+                                    source=source_id,
+                                    target=target_id,
+                                    kind="extends",
+                                    confidence="medium",
+                                    method="ast",
+                                )
+                            )
+        return nodes, edges, limitations
+
+    def _analyze_node_file(
+        self,
+        relative_path: str,
+        content: str,
+        module_map: dict[str, str],
+        workspace: str | None,
+    ) -> tuple[list[GraphNode], list[GraphEdge], list[str]]:
+        module_node_id = f"module:{relative_path}"
+        nodes: list[GraphNode] = []
+        edges: list[GraphEdge] = []
+        limitations: list[str] = []
+
+        function_pattern = re.compile(
+            r"^\s*(?:export\s+)?function\s+([A-Za-z_][A-Za-z0-9_]*)",
+            re.MULTILINE,
+        )
+        class_pattern = re.compile(
+            r"^\s*(?:export\s+)?class\s+([A-Za-z_][A-Za-z0-9_]*)(?:\s+extends\s+([A-Za-z_][A-Za-z0-9_]*))?",
+            re.MULTILINE,
+        )
+        function_node_ids: dict[str, str] = {}
+        class_node_ids: dict[str, str] = {}
+
+        for match in function_pattern.finditer(content):
+            name = match.group(1)
+            node_id = f"function:{relative_path}:{name}"
+            function_node_ids[name] = node_id
+            nodes.append(
+                GraphNode(
+                    id=node_id,
+                    kind="function",
+                    language="nodejs",
+                    path=relative_path,
+                    symbol=name,
+                    display_name=name,
+                    workspace=workspace,
+                )
+            )
+            edges.append(
+                GraphEdge(
+                    source=module_node_id,
+                    target=node_id,
+                    kind="contains",
+                    confidence="medium",
+                    method="heuristic",
+                )
+            )
+
+        for match in class_pattern.finditer(content):
+            name = match.group(1)
+            base = match.group(2)
+            node_id = f"class:{relative_path}:{name}"
+            class_node_ids[name] = node_id
+            nodes.append(
+                GraphNode(
+                    id=node_id,
+                    kind="class",
+                    language="nodejs",
+                    path=relative_path,
+                    symbol=name,
+                    display_name=name,
+                    workspace=workspace,
+                )
+            )
+            edges.append(
+                GraphEdge(
+                    source=module_node_id,
+                    target=node_id,
+                    kind="contains",
+                    confidence="medium",
+                    method="heuristic",
+                )
+            )
+            if base and base in class_node_ids:
+                edges.append(
+                    GraphEdge(
+                        source=node_id,
+                        target=class_node_ids[base],
+                        kind="extends",
+                        confidence="low",
+                        method="heuristic",
+                    )
+                )
+
+        patterns = [
+            re.compile(r"""import\s+(?:[^'"]+?\s+from\s+)?['"]([^'"]+)['"]"""),
+            re.compile(r"""require\(\s*['"]([^'"]+)['"]\s*\)"""),
+        ]
+        found_specs: set[str] = set()
+        for pattern in patterns:
+            for match in pattern.finditer(content):
+                spec = match.group(1)
+                if spec in found_specs:
+                    continue
+                found_specs.add(spec)
+                if spec.startswith("."):
+                    target_path = self._resolve_node_import(relative_path, spec, module_map)
+                    if target_path is None:
+                        limitations.append(f"node_unresolved:{relative_path}:{spec}")
+                        continue
+                    edges.append(
+                        GraphEdge(
+                            source=module_node_id,
+                            target=f"module:{target_path}",
+                            kind="imports",
+                            confidence="medium",
+                            method="heuristic",
+                        )
+                    )
+                else:
+                    limitations.append(f"node_external:{relative_path}:{spec}")
+
+        return nodes, edges, limitations
+
+    def _analyze_go_file(
+        self,
+        relative_path: str,
+        content: str,
+        import_map: dict[str, str],
+        workspace: str | None,
+    ) -> tuple[list[GraphNode], list[GraphEdge], list[str]]:
+        module_node_id = f"module:{relative_path}"
+        nodes: list[GraphNode] = []
+        edges: list[GraphEdge] = []
+        limitations: list[str] = []
+
+        for match in re.finditer(r"(?m)^func\s+([A-ZA-Za-z_][A-Za-z0-9_]*)\s*\(", content):
+            name = match.group(1)
+            node_id = f"function:{relative_path}:{name}"
+            nodes.append(
+                GraphNode(
+                    id=node_id,
+                    kind="function",
+                    language="go",
+                    path=relative_path,
+                    symbol=name,
+                    display_name=name,
+                    workspace=workspace,
+                )
+            )
+            edges.append(
+                GraphEdge(
+                    source=module_node_id,
+                    target=node_id,
+                    kind="contains",
+                    confidence="medium",
+                    method="heuristic",
+                )
+            )
+
+        import_specs = re.findall(r'"([^"]+)"', self._extract_go_import_block(content))
+        for spec in import_specs:
+            target_path = import_map.get(spec)
+            if target_path is None:
+                continue
+            edges.append(
+                GraphEdge(
+                    source=module_node_id,
+                    target=f"module:{target_path}",
+                    kind="imports",
+                    confidence="medium",
+                    method="heuristic",
+                )
+            )
+        return nodes, edges, limitations
+
+    def _analyze_jvm_file(
+        self,
+        relative_path: str,
+        content: str,
+        type_map: dict[str, tuple[str, str]],
+        workspace: str | None,
+    ) -> tuple[list[GraphNode], list[GraphEdge], list[str]]:
+        module_node_id = f"module:{relative_path}"
+        language = self._language_for_suffix(Path(relative_path).suffix)
+        nodes: list[GraphNode] = []
+        edges: list[GraphEdge] = []
+        limitations: list[str] = []
+        imported_type_map = {
+            imported.split(".")[-1]: imported
+            for imported in re.findall(r"(?m)^\s*import\s+([A-Za-z0-9_.]+)", content)
+        }
+
+        class_pattern = re.compile(
+            r"(?m)^\s*(?:public\s+|private\s+|protected\s+|internal\s+)?"
+            r"(?:class|interface|object|trait)\s+([A-Za-z_][A-Za-z0-9_]*)"
+            r"(?:\s+extends\s+([A-Za-z_][A-Za-z0-9_.]*))?"
+        )
+        local_class_ids: dict[str, str] = {}
+        for match in class_pattern.finditer(content):
+            name = match.group(1)
+            base = match.group(2)
+            node_id = f"class:{relative_path}:{name}"
+            local_class_ids[name] = node_id
+            nodes.append(
+                GraphNode(
+                    id=node_id,
+                    kind="class",
+                    language=language,
+                    path=relative_path,
+                    symbol=name,
+                    display_name=name,
+                    workspace=workspace,
+                )
+            )
+            edges.append(
+                GraphEdge(
+                    source=module_node_id,
+                    target=node_id,
+                    kind="contains",
+                    confidence="medium",
+                    method="heuristic",
+                )
+            )
+            if base:
+                base_short = base.split(".")[-1]
+                if base_short in local_class_ids:
+                    edges.append(
+                        GraphEdge(
+                            source=node_id,
+                            target=local_class_ids[base_short],
+                            kind="extends",
+                            confidence="low",
+                            method="heuristic",
+                        )
+                    )
+                else:
+                    imported_base = imported_type_map.get(base_short)
+                    fqcn = imported_base or base
+                    mapping = type_map.get(fqcn)
+                    if mapping is None:
+                        continue
+                    base_path, _base_name = mapping
+                    edges.append(
+                        GraphEdge(
+                            source=node_id,
+                            target=f"class:{base_path}:{base_short}",
+                            kind="extends",
+                            confidence="low",
+                            method="heuristic",
+                        )
+                    )
+
+        for imported in imported_type_map.values():
+            mapping = type_map.get(imported)
+            if mapping is None:
+                limitations.append(f"jvm_unresolved:{relative_path}:{imported}")
+                continue
+            target_path, _symbol = mapping
+            edges.append(
+                GraphEdge(
+                    source=module_node_id,
+                    target=f"module:{target_path}",
+                    kind="imports",
+                    confidence="medium",
+                    method="heuristic",
+                )
+            )
+        return nodes, edges, limitations
+
+    def _build_python_module_map(self, source_files: list[str]) -> dict[str, str]:
+        module_map: dict[str, str] = {}
+        for relative_path in source_files:
+            path = PurePosixPath(relative_path)
+            if path.suffix not in self._PYTHON_EXTENSIONS:
+                continue
+            if path.name == "__init__.py":
+                module_name = ".".join(path.parts[:-1])
+            else:
+                module_name = ".".join(path.with_suffix("").parts)
+            if module_name:
+                module_map[relative_path] = module_name
+        return module_map
+
+    def _build_go_import_map(self, root: Path, source_files: list[str]) -> dict[str, str]:
+        go_mod = root / "go.mod"
+        if not go_mod.exists():
+            return {}
+        module_name = ""
+        for line in go_mod.read_text(encoding="utf-8", errors="replace").splitlines():
+            stripped = line.strip()
+            if stripped.startswith("module "):
+                module_name = stripped.removeprefix("module ").strip()
+                break
+        if not module_name:
+            return {}
+        mapping: dict[str, str] = {}
+        for relative_path in source_files:
+            path = PurePosixPath(relative_path)
+            if path.suffix not in self._GO_EXTENSIONS:
+                continue
+            directory = "." if len(path.parts) == 1 else "/".join(path.parts[:-1])
+            import_path = module_name if directory == "." else f"{module_name}/{directory}"
+            mapping[import_path] = relative_path
+        return mapping
+
+    def _build_jvm_type_map(self, root: Path, source_files: list[str]) -> dict[str, tuple[str, str]]:
+        mapping: dict[str, tuple[str, str]] = {}
+        package_pattern = re.compile(r"(?m)^\s*package\s+([A-Za-z0-9_.]+)")
+        type_pattern = re.compile(
+            r"(?m)^\s*(?:public\s+|private\s+|protected\s+|internal\s+)?"
+            r"(?:class|interface|object|trait)\s+([A-Za-z_][A-Za-z0-9_]*)"
+        )
+        for relative_path in source_files:
+            if Path(relative_path).suffix not in self._JVM_EXTENSIONS:
+                continue
+            try:
+                content = (root / relative_path).read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            package_match = package_pattern.search(content)
+            type_match = type_pattern.search(content)
+            if type_match is None:
+                continue
+            package_name = package_match.group(1) if package_match else ""
+            symbol = type_match.group(1)
+            fqcn = f"{package_name}.{symbol}" if package_name else symbol
+            mapping[fqcn] = (relative_path, symbol)
+        return mapping
+
+    def _resolve_python_import(
+        self, module_name: str, module_map: dict[str, str]
+    ) -> Optional[str]:
+        for path, candidate in module_map.items():
+            if candidate == module_name:
+                return path
+        return None
+
+    def _resolve_python_from_import(
+        self,
+        node: ast.ImportFrom,
+        current_module: str | None,
+        module_map: dict[str, str],
+    ) -> Optional[str]:
+        if node.level and current_module:
+            package_parts = current_module.split(".")
+            base_parts = package_parts[:-1]
+            if node.level > 1:
+                base_parts = base_parts[: max(0, len(base_parts) - (node.level - 1))]
+            target_module = ".".join(base_parts + ([node.module] if node.module else []))
+        else:
+            target_module = node.module or ""
+        if not target_module:
+            return None
+        return self._resolve_python_import(target_module, module_map)
+
+    def _resolve_node_import(
+        self, source_path: str, spec: str, module_map: dict[str, str]
+    ) -> Optional[str]:
+        base_dir = PurePosixPath(source_path).parent
+        spec_path = PurePosixPath(spec)
+        candidate_base = (base_dir / spec_path).as_posix()
+        candidates = [
+            candidate_base,
+            f"{candidate_base}.js",
+            f"{candidate_base}.jsx",
+            f"{candidate_base}.ts",
+            f"{candidate_base}.tsx",
+            f"{candidate_base}/index.js",
+            f"{candidate_base}/index.ts",
+            f"{candidate_base}/index.tsx",
+        ]
+        for candidate in candidates:
+            normalized = PurePosixPath(candidate).as_posix()
+            if normalized in module_map:
+                return normalized
+        return None
+
+    def _extract_go_import_block(self, content: str) -> str:
+        block_match = re.search(r"import\s*\((.*?)\)", content, re.DOTALL)
+        if block_match is not None:
+            return block_match.group(1)
+        single_imports = re.findall(r'(?m)^\s*import\s+"([^"]+)"', content)
+        return "\n".join(f'"{item}"' for item in single_imports)
+
+    def _append_node(self, nodes: list[GraphNode], node_ids: set[str], node: GraphNode) -> None:
+        if len(nodes) >= self.max_nodes or node.id in node_ids:
+            return
+        node_ids.add(node.id)
+        nodes.append(node)
+
+    def _append_edge(
+        self,
+        edges: list[GraphEdge],
+        edge_keys: set[tuple[str, str, str, str]],
+        edge: GraphEdge,
+    ) -> None:
+        if len(edges) >= self.max_edges:
+            return
+        key = (edge.source, edge.target, edge.kind, edge.method)
+        if key in edge_keys:
+            return
+        edge_keys.add(key)
+        edges.append(edge)
+
+    def _language_for_suffix(self, suffix: str) -> str:
+        if suffix in self._PYTHON_EXTENSIONS:
+            return "python"
+        if suffix in self._NODE_EXTENSIONS:
+            return "nodejs"
+        if suffix in self._GO_EXTENSIONS:
+            return "go"
+        if suffix == ".java":
+            return "java"
+        if suffix == ".kt":
+            return "kotlin"
+        if suffix == ".scala":
+            return "scala"
+        return "unknown"
+
+    def _node_id(self, kind: str, path: str, symbol: str | None = None) -> str:
+        if symbol:
+            return f"{kind}:{path}:{symbol}"
+        return f"{kind}:{path}"
+
+    def _unique(self, values: list[str]) -> list[str]:
+        result: list[str] = []
+        for value in values:
+            if value not in result:
+                result.append(value)
+        return result

sourcecode/schema.py

@@ -96,6 +96,51 @@ class DependencySummary:
     limitations: list[str] = field(default_factory=list)
 
 
+@dataclass
+class GraphNode:
+    """Nodo del grafo estructural del codigo."""
+
+    id: str
+    kind: str
+    language: str
+    path: str
+    symbol: Optional[str] = None
+    display_name: Optional[str] = None
+    workspace: Optional[str] = None
+
+
+@dataclass
+class GraphEdge:
+    """Arista del grafo estructural del codigo."""
+
+    source: str
+    target: str
+    kind: str
+    confidence: Literal["high", "medium", "low"] = "medium"
+    method: Literal["ast", "heuristic", "unresolved"] = "heuristic"
+
+
+@dataclass
+class ModuleGraphSummary:
+    """Resumen del analisis estructural del grafo."""
+
+    requested: bool = False
+    node_count: int = 0
+    edge_count: int = 0
+    languages: list[str] = field(default_factory=list)
+    methods: list[str] = field(default_factory=list)
+    limitations: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ModuleGraph:
+    """Grafo de modulos, simbolos y relaciones del proyecto."""
+
+    nodes: list[GraphNode] = field(default_factory=list)
+    edges: list[GraphEdge] = field(default_factory=list)
+    summary: ModuleGraphSummary = field(default_factory=ModuleGraphSummary)
+
+
 @dataclass
 class SourceMap:
     """Schema completo del output v1.0.
@@ -115,3 +160,4 @@ class SourceMap:
     entry_points: list[EntryPoint] = field(default_factory=list)
     dependencies: list[DependencyRecord] = field(default_factory=list)
     dependency_summary: Optional[DependencySummary] = None
+    module_graph: Optional[ModuleGraph] = None

{sourcecode-0.3.0.dist-info → sourcecode-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 0.3.0
+Version: 0.4.0
 Summary: Genera un mapa de contexto estructurado de proyectos de software para agentes IA
 License: MIT
 Requires-Python: >=3.9
@@ -52,6 +52,12 @@ Include direct dependencies, exact versions, and transitive dependencies when co
 sourcecode . --dependencies
 ```
 
+Include an internal module graph with imports and simple structural relations:
+
+```bash
+sourcecode . --graph-modules
+```
+
 Show the version:
 
 ```bash
@@ -64,6 +70,7 @@ Main options:
 - `--output PATH`: write to a file instead of `stdout`.
 - `--compact`: return a reduced view with `schema_version`, `project_type`, `stacks`, `entry_points`, and `file_tree_depth1`.
 - `--dependencies`: include direct dependencies, resolved versions, and transitive relationships when lockfiles make that possible.
+- `--graph-modules`: include a structural graph with modules, imports, and simple relations such as `contains`, `calls`, or `extends`.
 - `--depth INTEGER`: maximum file tree depth.
 - `--no-redact`: disable secret redaction.
 
@@ -161,6 +168,7 @@ The full schema includes:
 - `entry_points`: detected entry points by stack.
 - `dependencies`: optional dependency records with declared and resolved versions.
 - `dependency_summary`: optional summary with ecosystem coverage, counts, and known limitations.
+- `module_graph`: optional structural graph with nodes, edges, and analysis limits.
 
 Example dependency block:
 
@@ -204,6 +212,61 @@ Example dependency block:
 
 Dependency analysis is still offline and conservative: if a lockfile does not expose a reliable transitive graph, `sourcecode` reports direct dependencies and records the limitation instead of guessing.
 
+Example module graph block:
+
+```json
+{
+  "module_graph": {
+    "nodes": [
+      {
+        "id": "module:app/main.py",
+        "kind": "module",
+        "language": "python",
+        "path": "app/main.py",
+        "symbol": null,
+        "display_name": "app/main.py",
+        "workspace": null
+      },
+      {
+        "id": "function:app/main.py:run",
+        "kind": "function",
+        "language": "python",
+        "path": "app/main.py",
+        "symbol": "run",
+        "display_name": "run",
+        "workspace": null
+      }
+    ],
+    "edges": [
+      {
+        "source": "module:app/main.py",
+        "target": "module:app/utils.py",
+        "kind": "imports",
+        "confidence": "high",
+        "method": "ast"
+      },
+      {
+        "source": "function:app/main.py:run",
+        "target": "function:app/utils.py:helper",
+        "kind": "calls",
+        "confidence": "medium",
+        "method": "ast"
+      }
+    ],
+    "summary": {
+      "requested": true,
+      "node_count": 2,
+      "edge_count": 2,
+      "languages": ["python"],
+      "methods": ["ast"],
+      "limitations": []
+    }
+  }
+}
+```
+
+Graph analysis is also offline and conservative. `sourcecode` prefers partial but defensible edges over pretending to build a perfect semantic call graph, and it records parse failures, unresolved imports, or analysis budgets in `module_graph.summary.limitations`.
+
 Detailed reference: [docs/schema.md](/Users/user/Documents/workspace/atlas/atlas-cli/docs/schema.md).
 
 ## Development

{sourcecode-0.3.0.dist-info → sourcecode-0.4.0.dist-info}/RECORD

@@ -1,10 +1,11 @@
-sourcecode/__init__.py,sha256=sw7UZiMGE-MNL0gak-WMvhCd_M-yBDowwBXfPLOuDDI,99
+sourcecode/__init__.py,sha256=iBHGXEsmbN21QO7wvQ3ZZhBy96xjvWrfacPsjTSGcds,99
 sourcecode/classifier.py,sha256=7ubGTn5vfw9z-9eosLIYDtQUu7d8dvB4XKKDxysUVSM,6910
-sourcecode/cli.py,sha256=vNf8DvdKmOyB8Sp3goK4lBDv3qQFzb6tKcULVziGxhA,8167
+sourcecode/cli.py,sha256=NysuO95KIxpBEpRiwor93_WFvdMvjk0ArDRv8KPX440,10136
 sourcecode/dependency_analyzer.py,sha256=c8tSbUpug-2avKNWCP4-_e2_uhBwWl96LwL1Be8O90M,39067
+sourcecode/graph_analyzer.py,sha256=hskmEr-c5z3HjWr2S_2ccaVSMrpikYdMY-ExbAiaK60,29353
 sourcecode/redactor.py,sha256=abSf5jH_IzYzpjF3lEN6hCwdXxvmyHs-3DHz9fd8Mic,2883
 sourcecode/scanner.py,sha256=TvcuD77m_NF8OlTj3XH1b_jO0qrto8c90fND96ecqb0,6182
-sourcecode/schema.py,sha256=Z1yg9FzwBsLEA-uIEofVqzXOEhFZNdP3e7LJvyFRcxk,3346
+sourcecode/schema.py,sha256=h5uemXKCrPVpEslO2iM_Kw3ax-4UmpOpkfK50HgTNo4,4517
 sourcecode/serializer.py,sha256=hezTYOAAvZ2yPn7Te7Eu42ajbMhVCsUkuUZtqx4wjAs,3085
 sourcecode/tree_utils.py,sha256=5WHQc2L-AGqxKFfYYcQftE6hETxgUxP9MWDuaThcAUw,991
 sourcecode/workspace.py,sha256=1L4xH38gU89fLeMYSuF3ft7lSdCyTfMfJ9NQt5q4Ric,6904
@@ -27,7 +28,7 @@ sourcecode/detectors/rust.py,sha256=iUz9lE4HfBy8CBaDwGhfh6kLsNIovrH2ay2v3y6qNDc,
 sourcecode/detectors/systems.py,sha256=qf5M9tio1H6XDorSstTWIxKe0xVLR_QGTJpFGyhDz4A,1690
 sourcecode/detectors/terraform.py,sha256=5EOKQtTViWo7u3tFK0h45YD8GQPwhrww0cOicxGPPn4,1732
 sourcecode/detectors/tooling.py,sha256=wPvudLCJZ8_cr9GIx44C8jkLAlEN9uTUZcJsP7eVYnQ,1937
-sourcecode-0.3.0.dist-info/METADATA,sha256=kLVxfZvLBfFwiXaIvhRWXCfwi3H-gJasHWAs0-wfiEc,5613
-sourcecode-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-0.3.0.dist-info/entry_points.txt,sha256=voDtdlGU2-jR3wCZpQoOls_0eUKaDVCKIfajGHFDATs,50
-sourcecode-0.3.0.dist-info/RECORD,,
+sourcecode-0.4.0.dist-info/METADATA,sha256=gj14EtCMRfrSsiMpfMN1E2AaRObCQCU3Z_Io7Xpx_b4,7339
+sourcecode-0.4.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-0.4.0.dist-info/entry_points.txt,sha256=voDtdlGU2-jR3wCZpQoOls_0eUKaDVCKIfajGHFDATs,50
+sourcecode-0.4.0.dist-info/RECORD,,