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

sourcecode/__init__.py

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

sourcecode/cli.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Optional, cast
 
 import typer
 
@@ -16,6 +16,8 @@ app = typer.Typer(
 )
 
 FORMAT_CHOICES = ["json", "yaml"]
+GRAPH_DETAIL_CHOICES = ["high", "medium", "full"]
+GRAPH_EDGE_CHOICES = {"imports", "calls", "contains", "extends"}
 
 
 def version_callback(value: bool) -> None:
@@ -56,6 +58,23 @@ def main(
         "--graph-modules",
         help="Incluir grafo estructural de modulos, imports y relaciones simples del codigo",
     ),
+    graph_detail: str = typer.Option(
+        "high",
+        "--graph-detail",
+        help="Nivel de detalle del grafo: high|medium|full",
+        show_default=True,
+    ),
+    max_nodes: Optional[int] = typer.Option(
+        None,
+        "--max-nodes",
+        help="Limite de nodos para `--graph-modules` en modos high/medium",
+        min=1,
+    ),
+    graph_edges: Optional[str] = typer.Option(
+        None,
+        "--graph-edges",
+        help="Tipos de arista para `--graph-modules` separados por comas: imports,calls,contains,extends",
+    ),
     no_redact: bool = typer.Option(
         False,
         "--no-redact",
@@ -85,6 +104,12 @@ def main(
             err=True,
         )
         raise typer.Exit(code=1)
+    if graph_detail not in GRAPH_DETAIL_CHOICES:
+        typer.echo(
+            f"Error: valor invalido '{graph_detail}' para --graph-detail. Opciones: {', '.join(GRAPH_DETAIL_CHOICES)}",
+            err=True,
+        )
+        raise typer.Exit(code=1)
 
     # Resolver y validar path
     target = path.resolve()
@@ -100,7 +125,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.graph_analyzer import GraphAnalyzer, GraphDetail
     from sourcecode.redactor import SecretRedactor, redact_dict
     from sourcecode.scanner import FileScanner
     from sourcecode.schema import AnalysisMetadata, EntryPoint, SourceMap, StackDetection
@@ -151,6 +176,21 @@ def main(
     workspace_analysis = WorkspaceAnalyzer().analyze(target, manifests)
     dependency_analyzer = DependencyAnalyzer() if dependencies else None
     graph_analyzer = GraphAnalyzer() if graph_modules else None
+    parsed_graph_edges = (
+        {edge.strip() for edge in graph_edges.split(",") if edge.strip()}
+        if graph_edges
+        else None
+    )
+    if parsed_graph_edges is not None:
+        invalid_edges = sorted(parsed_graph_edges - GRAPH_EDGE_CHOICES)
+        if invalid_edges:
+            typer.echo(
+                "Error: valores invalidos para --graph-edges: "
+                f"{', '.join(invalid_edges)}. Opciones: {', '.join(sorted(GRAPH_EDGE_CHOICES))}",
+                err=True,
+            )
+            raise typer.Exit(code=1)
+    graph_detail_typed = cast(GraphDetail, graph_detail)
 
     root_manifests = [
         manifest
@@ -180,7 +220,14 @@ def main(
             if workspace_analysis.workspaces
             else file_tree
         )
-        module_graphs.append(graph_analyzer.analyze(target, root_graph_tree))
+        module_graphs.append(
+            graph_analyzer.analyze(
+                target,
+                root_graph_tree,
+                detail="full",
+                entry_points=entry_points,
+            )
+        )
 
     for workspace in workspace_analysis.workspaces:
         workspace_root = target / workspace.path
@@ -215,10 +262,12 @@ def main(
             dependency_summaries.append(workspace_summary)
         if graph_analyzer is not None:
             workspace_graph = graph_analyzer.analyze(
-                    workspace_root,
-                    workspace_tree,
-                    workspace=workspace.path,
-                )
+                workspace_root,
+                workspace_tree,
+                workspace=workspace.path,
+                detail="full",
+                entry_points=workspace_entry_points,
+            )
             module_graphs.append(
                 graph_analyzer.prefix_graph(workspace_graph, workspace.path, workspace.path)
             )
@@ -234,7 +283,17 @@ 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
+    module_graph = (
+        graph_analyzer.merge_graphs(
+            module_graphs,
+            detail=graph_detail_typed,
+            edge_kinds=parsed_graph_edges,
+            max_nodes=max_nodes,
+            entry_points=entry_points,
+        )
+        if graph_analyzer is not None
+        else None
+    )
 
     # 3. Construir el schema
     metadata = AnalysisMetadata(analyzed_path=str(target))
@@ -247,6 +306,7 @@ def main(
         dependencies=dependency_records,
         dependency_summary=dependency_summary,
         module_graph=module_graph,
+        module_graph_summary=module_graph.summary if module_graph is not None else None,
     )
 
     # 4. Serializar (con o sin modo compact)

sourcecode/graph_analyzer.py

@@ -1,15 +1,19 @@
-"""Analisis estructural offline para modulos, imports y relaciones simples."""
+"""Analisis estructural offline optimizado para LLMs y modo full."""
 from __future__ import annotations
 
 import ast
 import re
+from collections import Counter, defaultdict
 from dataclasses import replace
 from pathlib import Path, PurePosixPath
-from typing import Any, Optional
+from typing import Any, Literal, Optional
 
-from sourcecode.schema import GraphEdge, GraphNode, ModuleGraph, ModuleGraphSummary
+from sourcecode.schema import EntryPoint, GraphEdge, GraphNode, ModuleGraph, ModuleGraphSummary
 from sourcecode.tree_utils import flatten_file_tree
 
+GraphDetail = Literal["high", "medium", "full"]
+GraphImportance = Literal["high", "medium", "low"]
+
 
 class GraphAnalyzer:
     """Construye un grafo estructural parcial y seguro del proyecto."""
@@ -19,6 +23,16 @@ class GraphAnalyzer:
     _GO_EXTENSIONS = {".go"}
     _JVM_EXTENSIONS = {".java", ".kt", ".scala"}
     _SUPPORTED_EXTENSIONS = _PYTHON_EXTENSIONS | _NODE_EXTENSIONS | _GO_EXTENSIONS | _JVM_EXTENSIONS
+    _DEFAULT_EDGE_KINDS: dict[GraphDetail, tuple[str, ...]] = {
+        "high": ("imports",),
+        "medium": ("imports", "calls"),
+        "full": ("imports", "calls", "contains", "extends"),
+    }
+    _DEFAULT_MAX_NODES: dict[GraphDetail, Optional[int]] = {
+        "high": 80,
+        "medium": 160,
+        "full": None,
+    }
 
     def __init__(
         self,
@@ -39,6 +53,98 @@ class GraphAnalyzer:
         file_tree: dict[str, Any],
         *,
         workspace: str | None = None,
+        detail: GraphDetail = "full",
+        edge_kinds: set[str] | None = None,
+        max_nodes: int | None = None,
+        entry_points: list[EntryPoint] | None = None,
+    ) -> ModuleGraph:
+        full_graph = self._analyze_full(root, file_tree, workspace=workspace)
+        return self._project_graph(
+            full_graph,
+            detail=detail,
+            edge_kinds=edge_kinds,
+            max_nodes=max_nodes,
+            entry_points=entry_points or [],
+        )
+
+    def merge_graphs(
+        self,
+        graphs: list[ModuleGraph],
+        *,
+        detail: GraphDetail = "full",
+        edge_kinds: set[str] | None = None,
+        max_nodes: int | None = None,
+        entry_points: list[EntryPoint] | None = None,
+    ) -> 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)
+        merged = 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),
+            ),
+        )
+        return self._project_graph(
+            merged,
+            detail=detail,
+            edge_kinds=edge_kinds,
+            max_nodes=max_nodes,
+            entry_points=entry_points or [],
+        )
+
+    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_full(
+        self,
+        root: Path,
+        file_tree: dict[str, Any],
+        *,
+        workspace: str | None,
     ) -> ModuleGraph:
         source_files = [
             path
@@ -47,9 +153,7 @@ class GraphAnalyzer:
         ]
         limitations: list[str] = []
         if len(source_files) > self.max_files:
-            limitations.append(
-                f"max_files_reached:{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] = []
@@ -58,7 +162,9 @@ class GraphAnalyzer:
         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}
+        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)
 
@@ -114,78 +220,392 @@ class GraphAnalyzer:
                 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)
+        nodes = nodes[: self.max_nodes]
+        edges = edges[: self.max_edges]
         return ModuleGraph(
             nodes=nodes,
             edges=edges,
             summary=ModuleGraphSummary(
-                requested=bool(graphs),
+                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}),
+                detail="full",
+                edge_kinds=sorted({edge.kind 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("/")
+    def _project_graph(
+        self,
+        graph: ModuleGraph,
+        *,
+        detail: GraphDetail,
+        edge_kinds: set[str] | None,
+        max_nodes: int | None,
+        entry_points: list[EntryPoint],
+    ) -> ModuleGraph:
+        active_edge_kinds = edge_kinds or set(self._DEFAULT_EDGE_KINDS[detail])
+        budget = (
+            max_nodes if detail != "full" and max_nodes is not None else self._DEFAULT_MAX_NODES[detail]
+        )
+        ranked_nodes = self._rank_nodes(graph, entry_points)
+        importance_by_id = {node.id: node.importance for node in ranked_nodes}
+        if detail == "full":
+            projected_nodes = ranked_nodes
+            projected_edges = [
+                edge for edge in graph.edges if edge.kind in active_edge_kinds
+            ]
+            truncated = False
+            base_limitations = list(graph.summary.limitations)
+        elif detail == "medium":
+            projected_nodes = self._select_medium_nodes(ranked_nodes, entry_points)
+            projected_nodes = self._expand_medium_call_targets(projected_nodes, ranked_nodes, graph.edges)
+            projected_edges = [
+                edge
+                for edge in graph.edges
+                if edge.kind in active_edge_kinds
+                and edge.source in {node.id for node in projected_nodes}
+                and edge.target in {node.id for node in projected_nodes}
+            ]
+            projected_nodes, projected_edges, truncated, base_limitations = self._apply_budget(
+                projected_nodes,
+                projected_edges,
+                importance_by_id,
+                budget,
+                list(graph.summary.limitations),
+            )
+        else:
+            collapsed_nodes, collapsed_edges = self._collapse_high_graph(
+                ranked_nodes,
+                graph.edges,
+                entry_points,
+            )
+            projected_nodes, projected_edges, truncated, base_limitations = self._apply_budget(
+                collapsed_nodes,
+                [edge for edge in collapsed_edges if edge.kind in active_edge_kinds],
+                {node.id: node.importance for node in collapsed_nodes},
+                budget,
+                list(graph.summary.limitations),
+            )
+
+        summary = self._build_summary(
+            projected_nodes,
+            projected_edges,
+            detail=detail,
+            edge_kinds=active_edge_kinds,
+            budget=budget,
+            entry_points=entry_points,
+            limitations=base_limitations,
+            truncated=truncated,
+        )
+        return ModuleGraph(nodes=projected_nodes, edges=projected_edges, summary=summary)
+
+    def _rank_nodes(self, graph: ModuleGraph, entry_points: list[EntryPoint]) -> list[GraphNode]:
+        module_entry_ids = self._entry_point_module_ids(entry_points, graph.nodes)
+        incoming_imports = Counter(
+            edge.target for edge in graph.edges if edge.kind == "imports"
+        )
+        incoming_calls = Counter(
+            edge.target for edge in graph.edges if edge.kind == "calls"
+        )
+        outgoing_calls = Counter(
+            edge.source for edge in graph.edges if edge.kind == "calls"
+        )
+
+        scored_nodes: list[tuple[int, GraphNode]] = []
         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,
-                )
+            score = 0
+            if node.id in module_entry_ids:
+                score += 100
+            if node.kind == "module":
+                score += 20
+                score += incoming_imports[node.id] * 10
+            elif node.kind == "function":
+                score += outgoing_calls[node.id] * 20
+                score += incoming_calls[node.id] * 8
+            elif node.kind == "class":
+                score += incoming_imports[node.id] * 6
+
+            if node.path.endswith(("main.py", "index.ts", "index.js", "__main__.py")):
+                score += 20
+
+            importance = self._importance_from_score(score, node.kind)
+            scored_nodes.append((score, replace(node, importance=importance)))
+
+        scored_nodes.sort(
+            key=lambda item: (
+                -item[0],
+                0 if item[1].kind == "module" else 1,
+                item[1].path,
+                item[1].symbol or "",
             )
-        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 [node for _score, node in scored_nodes]
+
+    def _importance_from_score(self, score: int, kind: str) -> GraphImportance:
+        if score >= 40:
+            return "high"
+        if kind == "module" and score >= 20:
+            return "medium"
+        if score >= 12:
+            return "medium"
+        return "low"
+
+    def _select_medium_nodes(
+        self,
+        ranked_nodes: list[GraphNode],
+        entry_points: list[EntryPoint],
+    ) -> list[GraphNode]:
+        entry_module_ids = self._entry_point_module_ids(entry_points, ranked_nodes)
+        selected: list[GraphNode] = []
+        seen: set[str] = set()
+        for node in ranked_nodes:
+            include = node.kind == "module" or node.importance == "high"
+            if node.id in entry_module_ids:
+                include = True
+            if include and node.id not in seen:
+                seen.add(node.id)
+                selected.append(node)
+        return selected
+
+    def _expand_medium_call_targets(
+        self,
+        selected_nodes: list[GraphNode],
+        ranked_nodes: list[GraphNode],
+        edges: list[GraphEdge],
+    ) -> list[GraphNode]:
+        node_map = {node.id: node for node in ranked_nodes}
+        selected_ids = {node.id for node in selected_nodes}
+        expanded = list(selected_nodes)
+        for edge in edges:
+            if edge.kind != "calls":
+                continue
+            if edge.source in selected_ids and edge.target in node_map and edge.target not in selected_ids:
+                selected_ids.add(edge.target)
+                expanded.append(node_map[edge.target])
+        return expanded
+
+    def _collapse_high_graph(
+        self,
+        ranked_nodes: list[GraphNode],
+        edges: list[GraphEdge],
+        entry_points: list[EntryPoint],
+    ) -> tuple[list[GraphNode], list[GraphEdge]]:
+        module_nodes = [node for node in ranked_nodes if node.kind == "module"]
+        entry_module_ids = self._entry_point_module_ids(entry_points, module_nodes)
+        group_map = self._build_high_group_map(module_nodes, entry_module_ids)
+        grouped_nodes: dict[str, GraphNode] = {}
+        for node in module_nodes:
+            group_path = group_map[node.id]
+            if group_path not in grouped_nodes:
+                importance: GraphImportance = "high" if node.id in entry_module_ids else "medium"
+                grouped_nodes[group_path] = GraphNode(
+                    id=f"module:{group_path}",
+                    kind="module",
+                    language=node.language,
+                    path=group_path,
+                    display_name=group_path,
+                    workspace=node.workspace,
+                    importance=importance,
                 )
+            elif node.importance == "high":
+                grouped_nodes[group_path] = replace(
+                    grouped_nodes[group_path],
+                    importance="high",
+                )
+
+        grouped_edges: list[GraphEdge] = []
+        edge_keys: set[tuple[str, str, str, str]] = set()
+        for edge in edges:
+            if edge.kind != "imports":
+                continue
+            source_group = group_map.get(edge.source)
+            target_group = group_map.get(edge.target)
+            if source_group is None or target_group is None or source_group == target_group:
+                continue
+            grouped_edge = GraphEdge(
+                source=f"module:{source_group}",
+                target=f"module:{target_group}",
+                kind="imports",
+                confidence=edge.confidence,
+                method=edge.method,
             )
-        return ModuleGraph(
-            nodes=prefixed_nodes,
-            edges=prefixed_edges,
-            summary=replace(graph.summary),
+            self._append_edge(grouped_edges, edge_keys, grouped_edge)
+
+        return list(grouped_nodes.values()), grouped_edges
+
+    def _build_high_group_map(
+        self,
+        module_nodes: list[GraphNode],
+        entry_module_ids: set[str],
+    ) -> dict[str, str]:
+        modules_by_parent: dict[str, list[GraphNode]] = defaultdict(list)
+        for node in module_nodes:
+            parent = str(PurePosixPath(node.path).parent)
+            modules_by_parent[parent].append(node)
+
+        group_map: dict[str, str] = {}
+        for node in module_nodes:
+            parent = str(PurePosixPath(node.path).parent)
+            if parent not in {".", ""} and len(modules_by_parent[parent]) > 1 and node.id not in entry_module_ids:
+                group_map[node.id] = parent
+            else:
+                stem_path = str(PurePosixPath(node.path).with_suffix(""))
+                if stem_path.endswith("/__init__"):
+                    stem_path = stem_path[: -len("/__init__")]
+                group_map[node.id] = stem_path or node.path
+        return group_map
+
+    def _apply_budget(
+        self,
+        nodes: list[GraphNode],
+        edges: list[GraphEdge],
+        importance_by_id: dict[str, GraphImportance | None],
+        budget: int | None,
+        limitations: list[str],
+    ) -> tuple[list[GraphNode], list[GraphEdge], bool, list[str]]:
+        if budget is None or len(nodes) <= budget:
+            return nodes, edges, False, limitations
+
+        priority = {"high": 0, "medium": 1, "low": 2, None: 3}
+        trimmed_nodes = sorted(
+            nodes,
+            key=lambda node: (
+                priority[importance_by_id.get(node.id)],
+                0 if node.kind == "module" else 1,
+                node.path,
+                node.symbol or "",
+            ),
+        )[:budget]
+        kept_ids = {node.id for node in trimmed_nodes}
+        trimmed_edges = [
+            edge
+            for edge in edges
+            if edge.source in kept_ids and edge.target in kept_ids
+        ]
+        new_limitations = list(limitations)
+        new_limitations.append(f"node_budget_applied:{len(nodes)}->{budget}")
+        return trimmed_nodes, trimmed_edges, True, self._unique(new_limitations)
+
+    def _build_summary(
+        self,
+        nodes: list[GraphNode],
+        edges: list[GraphEdge],
+        *,
+        detail: GraphDetail,
+        edge_kinds: set[str],
+        budget: int | None,
+        entry_points: list[EntryPoint],
+        limitations: list[str],
+        truncated: bool,
+    ) -> ModuleGraphSummary:
+        return 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}),
+            main_flows=self._derive_main_flows(nodes, edges, entry_points),
+            layers=self._infer_layers(nodes),
+            entry_points_count=len(entry_points),
+            truncated=truncated,
+            detail=detail,
+            max_nodes_applied=budget,
+            edge_kinds=sorted(edge_kinds),
+            limitations=self._unique(limitations),
         )
 
+    def _derive_main_flows(
+        self,
+        nodes: list[GraphNode],
+        edges: list[GraphEdge],
+        entry_points: list[EntryPoint],
+    ) -> list[str]:
+        node_map = {node.id: node for node in nodes}
+        adjacency: dict[str, list[str]] = defaultdict(list)
+        for edge in edges:
+            if edge.kind not in {"imports", "calls"}:
+                continue
+            adjacency[edge.source].append(edge.target)
+
+        flows: list[str] = []
+        entry_module_ids = self._entry_point_module_ids(entry_points, nodes)
+        for source_id in sorted(entry_module_ids):
+            if source_id not in adjacency and source_id not in node_map:
+                continue
+            walk = [self._node_label(node_map[source_id])]
+            current = source_id
+            visited = {source_id}
+            for _ in range(3):
+                candidates = [
+                    target for target in adjacency.get(current, [])
+                    if target in node_map and target not in visited
+                ]
+                if not candidates:
+                    break
+                next_target = sorted(
+                    candidates,
+                    key=lambda node_id: (
+                        0 if (node_map[node_id].importance == "high") else 1,
+                        0 if node_map[node_id].kind == "module" else 1,
+                        node_map[node_id].path,
+                    ),
+                )[0]
+                visited.add(next_target)
+                walk.append(self._node_label(node_map[next_target]))
+                current = next_target
+            if len(walk) > 1:
+                flows.append(" -> ".join(walk))
+            if len(flows) >= 3:
+                break
+        return flows
+
+    def _infer_layers(self, nodes: list[GraphNode]) -> list[str]:
+        layers: list[str] = []
+        for node in nodes:
+            if node.kind != "module":
+                continue
+            parts = PurePosixPath(node.path).parts
+            if not parts:
+                continue
+            layer = parts[0] if len(parts) > 1 else PurePosixPath(node.path).stem
+            if layer not in layers:
+                layers.append(layer)
+        return layers[:10]
+
+    def _entry_point_module_ids(
+        self,
+        entry_points: list[EntryPoint],
+        nodes: list[GraphNode],
+    ) -> set[str]:
+        module_ids = {node.id for node in nodes if node.kind == "module"}
+        resolved: set[str] = set()
+        for entry_point in entry_points:
+            entry_path = entry_point.path.strip("/")
+            candidates = [f"module:{entry_path}"]
+            if "/" in entry_path:
+                parent = entry_path.rsplit("/", 1)[0]
+                candidates.extend(
+                    [
+                        f"module:{parent}/main.py",
+                        f"module:{parent}/src/main.py",
+                        f"module:{parent}/index.ts",
+                        f"module:{parent}/src/index.ts",
+                        f"module:{parent}/index.js",
+                        f"module:{parent}/src/index.js",
+                    ]
+                )
+            for candidate in candidates:
+                if candidate in module_ids:
+                    resolved.add(candidate)
+                    break
+        return resolved
+
+    def _node_label(self, node: GraphNode) -> str:
+        return node.display_name or node.symbol or node.path
+
     def _analyze_python_file(
         self,
         relative_path: str,
@@ -288,12 +708,8 @@ class GraphAnalyzer:
                 )
                 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}"
-                    )
+                    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)):
@@ -321,9 +737,7 @@ class GraphAnalyzer:
                     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
-                        )
+                        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(

sourcecode/schema.py

@@ -107,6 +107,7 @@ class GraphNode:
     symbol: Optional[str] = None
     display_name: Optional[str] = None
     workspace: Optional[str] = None
+    importance: Optional[Literal["high", "medium", "low"]] = None
 
 
 @dataclass
@@ -129,6 +130,13 @@ class ModuleGraphSummary:
     edge_count: int = 0
     languages: list[str] = field(default_factory=list)
     methods: list[str] = field(default_factory=list)
+    main_flows: list[str] = field(default_factory=list)
+    layers: list[str] = field(default_factory=list)
+    entry_points_count: int = 0
+    truncated: bool = False
+    detail: Optional[Literal["high", "medium", "full"]] = None
+    max_nodes_applied: Optional[int] = None
+    edge_kinds: list[str] = field(default_factory=list)
     limitations: list[str] = field(default_factory=list)
 
 
@@ -161,3 +169,4 @@ class SourceMap:
     dependencies: list[DependencyRecord] = field(default_factory=list)
     dependency_summary: Optional[DependencySummary] = None
     module_graph: Optional[ModuleGraph] = None
+    module_graph_summary: Optional[ModuleGraphSummary] = None

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 0.4.0
+Version: 0.5.0
 Summary: Genera un mapa de contexto estructurado de proyectos de software para agentes IA
 License: MIT
 Requires-Python: >=3.9
@@ -58,6 +58,14 @@ Include an internal module graph with imports and simple structural relations:
 sourcecode . --graph-modules
 ```
 
+Choose how much graph detail you want:
+
+```bash
+sourcecode . --graph-modules --graph-detail high
+sourcecode . --graph-modules --graph-detail medium
+sourcecode . --graph-modules --graph-detail full
+```
+
 Show the version:
 
 ```bash
@@ -70,7 +78,10 @@ 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`.
+- `--graph-modules`: include a structural graph optimized for repository reasoning.
+- `--graph-detail high|medium|full`: choose a summarized, balanced, or full-fidelity graph. Default: `high`.
+- `--max-nodes INTEGER`: cap graph size in `high` and `medium` modes.
+- `--graph-edges imports,calls,contains,extends`: override the default edge kinds for the selected detail level.
 - `--depth INTEGER`: maximum file tree depth.
 - `--no-redact`: disable secret redaction.
 
@@ -169,6 +180,7 @@ The full schema includes:
 - `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.
+- `module_graph_summary`: compact graph summary optimized for downstream LLM consumption.
 
 Example dependency block:
 
@@ -219,52 +231,52 @@ Example module graph block:
   "module_graph": {
     "nodes": [
       {
-        "id": "module:app/main.py",
+        "id": "module:app",
         "kind": "module",
         "language": "python",
-        "path": "app/main.py",
+        "path": "app",
         "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"
+        "display_name": "app",
+        "workspace": null,
+        "importance": "high"
       }
     ],
+    "edges": [],
     "summary": {
       "requested": true,
-      "node_count": 2,
-      "edge_count": 2,
+      "node_count": 1,
+      "edge_count": 0,
       "languages": ["python"],
       "methods": ["ast"],
+      "main_flows": [],
+      "layers": ["app"],
+      "entry_points_count": 1,
+      "truncated": false,
+      "detail": "high",
+      "max_nodes_applied": 80,
+      "edge_kinds": ["imports"],
       "limitations": []
     }
+  },
+  "module_graph_summary": {
+    "requested": true,
+    "node_count": 1,
+    "edge_count": 0,
+    "main_flows": [],
+    "layers": ["app"],
+    "entry_points_count": 1,
+    "truncated": false,
+    "limitations": []
   }
 }
 ```
 
+`--graph-modules` is now tiered for LLM workflows:
+
+- `high`: summarized graph, modules only, imports only, directory collapsing when useful.
+- `medium`: balanced graph with key functions and selected call edges.
+- `full`: full-fidelity graph, equivalent to the previous exhaustive behavior.
+
 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).

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

@@ -1,11 +1,11 @@
-sourcecode/__init__.py,sha256=iBHGXEsmbN21QO7wvQ3ZZhBy96xjvWrfacPsjTSGcds,99
+sourcecode/__init__.py,sha256=IMpF3qM4eqwxM-5Ikwwjo1JciPAcsosSo9qB_3jqdRY,99
 sourcecode/classifier.py,sha256=7ubGTn5vfw9z-9eosLIYDtQUu7d8dvB4XKKDxysUVSM,6910
-sourcecode/cli.py,sha256=NysuO95KIxpBEpRiwor93_WFvdMvjk0ArDRv8KPX440,10136
+sourcecode/cli.py,sha256=zpnh4NB46fWkBuP3el5vtgBH1CSmxzRmjRtR0NymR_U,12193
 sourcecode/dependency_analyzer.py,sha256=c8tSbUpug-2avKNWCP4-_e2_uhBwWl96LwL1Be8O90M,39067
-sourcecode/graph_analyzer.py,sha256=hskmEr-c5z3HjWr2S_2ccaVSMrpikYdMY-ExbAiaK60,29353
+sourcecode/graph_analyzer.py,sha256=S5z8mrGfLwN26Mt2IaCR4dOpQ_APU16cfihSp640eGQ,45241
 sourcecode/redactor.py,sha256=abSf5jH_IzYzpjF3lEN6hCwdXxvmyHs-3DHz9fd8Mic,2883
 sourcecode/scanner.py,sha256=TvcuD77m_NF8OlTj3XH1b_jO0qrto8c90fND96ecqb0,6182
-sourcecode/schema.py,sha256=h5uemXKCrPVpEslO2iM_Kw3ax-4UmpOpkfK50HgTNo4,4517
+sourcecode/schema.py,sha256=YaO1kWgWwH1iA8dUEQPJOLz2G-YRMrUEVXfkJo01xWE,4976
 sourcecode/serializer.py,sha256=hezTYOAAvZ2yPn7Te7Eu42ajbMhVCsUkuUZtqx4wjAs,3085
 sourcecode/tree_utils.py,sha256=5WHQc2L-AGqxKFfYYcQftE6hETxgUxP9MWDuaThcAUw,991
 sourcecode/workspace.py,sha256=1L4xH38gU89fLeMYSuF3ft7lSdCyTfMfJ9NQt5q4Ric,6904
@@ -28,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.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,,
+sourcecode-0.5.0.dist-info/METADATA,sha256=bAVVzEAxUwWc_PGiVzqffpiQh3r6q_Q91WJu7xEgo6M,7976
+sourcecode-0.5.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-0.5.0.dist-info/entry_points.txt,sha256=voDtdlGU2-jR3wCZpQoOls_0eUKaDVCKIfajGHFDATs,50
+sourcecode-0.5.0.dist-info/RECORD,,