sourcecode 0.4.0__tar.gz → 0.5.0__tar.gz

{sourcecode-0.4.0 → sourcecode-0.5.0}/PKG-INFO

@@ -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 → sourcecode-0.5.0}/README.md

@@ -42,6 +42,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
@@ -54,7 +62,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.
 
@@ -153,6 +164,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:
 
@@ -203,52 +215,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 → sourcecode-0.5.0}/docs/schema.md

@@ -27,6 +27,7 @@ Campos:
 - `dependencies`: dependencias detectadas cuando se solicita `--dependencies`.
 - `dependency_summary`: resumen del analisis de dependencias o `null` si no se solicito.
 - `module_graph`: grafo estructural de codigo o `null` si no se solicito `--graph-modules`.
+- `module_graph_summary`: resumen compacto del grafo pensado para consumo rapido por LLMs.
 
 ## metadata
 
@@ -34,7 +35,7 @@ Campos:
 {
   "schema_version": "1.0",
   "generated_at": "2026-04-07T19:41:05.686277+00:00",
-  "sourcecode_version": "0.4.0",
+  "sourcecode_version": "0.5.0",
   "analyzed_path": "/abs/path/to/project"
 }
 ```
@@ -215,46 +216,30 @@ Cuando se usa `--graph-modules`, `module_graph` expone nodos, aristas y un resum
 {
   "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": []
   }
 }
@@ -271,6 +256,7 @@ Cada nodo describe un modulo o simbolo relevante:
 - `symbol`: simbolo asociado si aplica.
 - `display_name`: nombre legible para consumidores humanos.
 - `workspace`: workspace relativa cuando el nodo pertenece a un subproyecto.
+- `importance`: importancia relativa del nodo (`high`, `medium`, `low`) usada para trimming y tambien expuesta al consumidor.
 
 ### module_graph.edges
 
@@ -291,8 +277,30 @@ Resume cobertura y limites del analisis:
 - `edge_count`: numero total de aristas emitidas.
 - `languages`: lenguajes presentes en el grafo.
 - `methods`: metodos usados para construir las aristas.
+- `main_flows`: rutas principales inferidas desde entry points siguiendo cadenas de imports/calls de forma best-effort.
+- `layers`: capas o clusters inferidos desde la estructura de directorios.
+- `entry_points_count`: numero de entry points considerados al construir el resumen.
+- `truncated`: `true` si se aplico recorte por `--max-nodes`.
+- `detail`: nivel activo del grafo (`high`, `medium`, `full`).
+- `max_nodes_applied`: presupuesto de nodos aplicado en `high` o `medium`.
+- `edge_kinds`: tipos de arista incluidos finalmente en la salida.
 - `limitations`: parse errors, imports no resueltos, archivos omitidos o limites de presupuesto aplicados.
 
+## module_graph_summary
+
+`module_graph_summary` replica el resumen esencial del grafo en un bloque top-level para que consumidores con ventanas de contexto pequeñas no tengan que recorrer `module_graph` completo.
+
+Campos principales:
+
+- `requested`
+- `node_count`
+- `edge_count`
+- `main_flows`
+- `layers`
+- `entry_points_count`
+- `truncated`
+- `limitations`
+
 ## Modo compacto
 
 Con `--compact`, la salida no incluye `metadata` ni el arbol completo. Devuelve:
@@ -317,6 +325,7 @@ Campos:
 
 `--compact` no incluye `dependencies` ni `dependency_summary`, aunque se combine con `--dependencies`.
 Tampoco incluye `module_graph`, aunque se combine con `--graph-modules`.
+Tampoco incluye `module_graph_summary`.
 
 ## Ejemplo completo
 
@@ -327,7 +336,7 @@ Ejemplo real de salida para un monorepo con web Node.js y API Python:
   "metadata": {
     "schema_version": "1.0",
     "generated_at": "2026-04-07T19:41:05.686277+00:00",
-    "sourcecode_version": "0.4.0",
+    "sourcecode_version": "0.5.0",
     "analyzed_path": "/abs/path/to/project"
   },
   "file_tree": {

{sourcecode-0.4.0 → sourcecode-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "0.4.0"
+version = "0.5.0"
 description = "Genera un mapa de contexto estructurado de proyectos de software para agentes IA"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-0.4.0 → sourcecode-0.5.0}/src/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-0.4.0 → sourcecode-0.5.0}/src/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)