sourcecode 0.9.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/architecture_summary.py

@@ -0,0 +1,248 @@
+"""Resumen arquitectonico estatico y compacto para consumo LLM."""
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+from typing import Any
+
+from sourcecode.schema import EntryPoint, SourceMap, StackDetection
+from sourcecode.tree_utils import flatten_file_tree
+
+_TOOLING_PREFIXES = (".claude/", ".vscode/", "bin/")
+_PYTHON_EXTENSIONS = {".py"}
+_NODE_EXTENSIONS = {".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"}
+_GO_EXTENSIONS = {".go"}
+
+
+class ArchitectureSummarizer:
+    """Construye un resumen arquitectonico estatico de 3-5 lineas."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    def generate(self, sm: SourceMap) -> str | None:
+        try:
+            return self._build_summary(sm)
+        except Exception:
+            return None
+
+    def _build_summary(self, sm: SourceMap) -> str | None:
+        file_paths = [
+            path for path in flatten_file_tree(sm.file_tree)
+            if not self._is_tooling_path(path)
+        ]
+        if not file_paths:
+            return None
+
+        entry_points = [
+            entry for entry in sm.entry_points
+            if not self._is_tooling_path(entry.path)
+        ]
+        if not entry_points:
+            fallback = self._infer_fallback_entry_points(file_paths, sm.stacks)
+            entry_points = fallback[:1]
+
+        if not entry_points:
+            return "Arquitectura no inferida con suficiente evidencia estatica."
+
+        entry_point = entry_points[0]
+        content = self._read_file(entry_point.path)
+        if content is None:
+            return f"Entry point principal: {entry_point.path}. Arquitectura no inferida con suficiente evidencia estatica."
+
+        lines = [self._describe_entry_point(entry_point, sm.project_type)]
+        suffix = Path(entry_point.path).suffix
+        if suffix in _PYTHON_EXTENSIONS:
+            lines.extend(self._summarize_python_entry(entry_point.path, content))
+        elif suffix in _NODE_EXTENSIONS:
+            lines.extend(self._summarize_node_entry(entry_point.path, content))
+        elif suffix in _GO_EXTENSIONS:
+            lines.extend(self._summarize_go_entry(entry_point.path, content))
+        else:
+            lines.append("Orquesta modulos internos no detallados por el analisis estatico disponible.")
+
+        unique_lines: list[str] = []
+        seen: set[str] = set()
+        for line in lines:
+            line = line.strip()
+            if not line or line in seen:
+                continue
+            seen.add(line)
+            unique_lines.append(line)
+        return "\n".join(unique_lines[:5]) if unique_lines else None
+
+    def _summarize_python_entry(self, path: str, content: str) -> list[str]:
+        try:
+            tree = ast.parse(content)
+        except SyntaxError:
+            return ["Orquesta modulos Python, pero el entry point no pudo parsearse por completo."]
+
+        package_prefix = self._python_package_prefix(path)
+        imported_modules: list[str] = []
+        optional_analyzers: list[str] = []
+        uses_serializer = False
+        uses_redactor = False
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom) and isinstance(node.module, str):
+                if package_prefix and node.module.startswith(package_prefix):
+                    imported_modules.append(node.module.rsplit(".", 1)[-1])
+                if node.module == "sourcecode.serializer":
+                    uses_serializer = True
+                if node.module == "sourcecode.redactor":
+                    uses_redactor = True
+            elif isinstance(node, ast.Assign):
+                optional = self._extract_optional_analyzer(node)
+                if optional:
+                    optional_analyzers.append(optional)
+
+        lines: list[str] = []
+        core_modules = self._format_module_list(imported_modules)
+        if core_modules:
+            lines.append(f"Orquesta modulos internos: {core_modules}.")
+        if optional_analyzers:
+            lines.append(f"Activa analisis opcionales: {', '.join(optional_analyzers)}.")
+        if uses_serializer:
+            output_line = "Produce un SourceMap serializado en JSON/YAML y una vista compacta."
+            if uses_redactor:
+                output_line = "Produce un SourceMap serializado en JSON/YAML y una vista compacta con redaccion de secretos."
+            lines.append(output_line)
+        elif not lines:
+            lines.append("Orquesta modulos Python internos sin un patron de salida claramente inferible.")
+        return lines
+
+    def _summarize_node_entry(self, path: str, content: str) -> list[str]:
+        imports = re.findall(r"""from\s+['"](\.?\.?/[^'"]+)['"]|require\(['"](\.?\.?/[^'"]+)['"]\)""", content)
+        modules = [item for pair in imports for item in pair if item]
+        lines: list[str] = []
+        if modules:
+            formatted = self._format_module_list([self._module_label(module) for module in modules])
+            if formatted:
+                lines.append(f"Orquesta modulos internos: {formatted}.")
+        lines.append("Produce la salida principal del entry point JavaScript/TypeScript detectado.")
+        return lines
+
+    def _summarize_go_entry(self, path: str, content: str) -> list[str]:
+        imports = re.findall(r'"([^"]+)"', content)
+        internal = [module for module in imports if not module.startswith(("fmt", "net/", "os", "context"))]
+        lines: list[str] = []
+        if internal:
+            formatted = self._format_module_list([self._module_label(module) for module in internal])
+            if formatted:
+                lines.append(f"Orquesta paquetes internos: {formatted}.")
+        lines.append("Produce la salida principal del binario Go detectado.")
+        return lines
+
+    def _describe_entry_point(self, entry_point: EntryPoint, project_type: str | None) -> str:
+        if entry_point.kind == "cli" or entry_point.path.endswith("cli.py"):
+            return f"Entry point principal: {entry_point.path} expone la CLI del proyecto."
+        if entry_point.kind == "web":
+            return f"Entry point principal: {entry_point.path} arranca la interfaz web."
+        if project_type == "api" or entry_point.kind == "server":
+            return f"Entry point principal: {entry_point.path} arranca el servicio principal."
+        if entry_point.kind == "binary":
+            return f"Entry point principal: {entry_point.path} arranca el binario principal."
+        return f"Entry point principal: {entry_point.path} coordina el flujo principal del proyecto."
+
+    def _extract_optional_analyzer(self, node: ast.Assign) -> str | None:
+        value = node.value
+        if not isinstance(value, ast.IfExp):
+            return None
+        if not isinstance(value.test, ast.Name):
+            return None
+        if not isinstance(value.body, ast.Call):
+            return None
+        if not isinstance(value.body.func, ast.Name):
+            return None
+        analyzer_name = value.body.func.id
+        if not analyzer_name.endswith("Analyzer"):
+            return None
+        return f"{analyzer_name} (--{value.test.id.replace('_', '-')})"
+
+    def _infer_fallback_entry_points(
+        self, file_paths: list[str], stacks: list[StackDetection]
+    ) -> list[EntryPoint]:
+        candidates: list[EntryPoint] = []
+        stack_name = stacks[0].stack if stacks else "unknown"
+        ordered_paths = sorted(file_paths, key=self._fallback_priority)
+        for path in ordered_paths:
+            if path.endswith(("cli.py", "__main__.py", "main.py")):
+                candidates.append(
+                    EntryPoint(
+                        path=path,
+                        stack=stack_name,
+                        kind="cli",
+                        source="convention",
+                        confidence="medium",
+                    )
+                )
+            elif path.endswith(("app/page.tsx", "pages/index.js", "server.js")):
+                candidates.append(
+                    EntryPoint(
+                        path=path,
+                        stack=stack_name,
+                        kind="web" if "page" in path or "pages/" in path else "server",
+                        source="convention",
+                        confidence="medium",
+                    )
+                )
+            elif path.endswith("main.go"):
+                candidates.append(
+                    EntryPoint(
+                        path=path,
+                        stack=stack_name,
+                        kind="binary",
+                        source="convention",
+                        confidence="medium",
+                    )
+                )
+        return candidates
+
+    def _fallback_priority(self, path: str) -> tuple[int, int, str]:
+        return (
+            0 if "/cli.py" in path or path.endswith("cli.py") else 1,
+            0 if path.startswith("src/") else 1,
+            path,
+        )
+
+    def _format_module_list(self, modules: list[str]) -> str:
+        normalized = [self._module_label(module) for module in modules]
+        filtered = [module for module in normalized if module and not self._is_tooling_path(module)]
+        if not filtered:
+            return ""
+        ordered: list[str] = []
+        seen: set[str] = set()
+        for module in filtered:
+            if module not in seen:
+                seen.add(module)
+                ordered.append(module)
+        return ", ".join(ordered[:8])
+
+    def _module_label(self, module: str) -> str:
+        cleaned = module.strip().strip("./")
+        if "/" in cleaned:
+            return cleaned.split("/")[-1]
+        if "." in cleaned:
+            return cleaned.rsplit(".", 1)[-1]
+        return cleaned
+
+    def _python_package_prefix(self, path: str) -> str:
+        parts = Path(path).parts
+        if len(parts) >= 3 and parts[0] == "src":
+            return f"{parts[1]}."
+        if len(parts) >= 2:
+            return f"{parts[0]}."
+        return ""
+
+    def _read_file(self, relative_path: str) -> str | None:
+        try:
+            return (self.root / relative_path).read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return None
+
+    def _is_tooling_path(self, path: str | None) -> bool:
+        if not path:
+            return False
+        normalized = path.strip().lstrip("/")
+        return normalized.startswith(_TOOLING_PREFIXES)

sourcecode/cli.py

@@ -474,6 +474,7 @@ def main(
             )
 
     # Phase 9: LLM Output Quality — poblar campos derivados
+    from sourcecode.architecture_summary import ArchitectureSummarizer
     from sourcecode.summarizer import ProjectSummarizer
     from sourcecode.tree_utils import flatten_file_tree
 
@@ -496,7 +497,8 @@ def main(
         sm.key_dependencies = sorted(direct_deps, key=_dep_sort_key)[:15]
 
     # LQN-02: resumen NL deterministico
-    sm.project_summary = ProjectSummarizer().generate(sm)
+    sm.project_summary = ProjectSummarizer(target).generate(sm)
+    sm.architecture_summary = ArchitectureSummarizer(target).generate(sm)
 
     # 4. Serializar (con o sin modo compact)
     if compact:
@@ -533,3 +535,34 @@ def main(
 
     # 5. Escribir output (CLI-04)
     write_output(content, output=output)
+
+    from sourcecode.prepare_context import ContextBuilder
+
+    @app.command("prepare-context")
+    def prepare_context_cmd(
+            task: str = typer.Argument(..., help="Descripción de la tarea"),
+            path: Path = typer.Option(".", help="Directorio del proyecto"),
+    ):
+        """
+        Prepara contexto mínimo optimizado para que un LLM modifique el código.
+        """
+        target = path.resolve()
+
+        if not target.exists() or not target.is_dir():
+            typer.echo(f"Error: '{target}' no es un directorio válido.", err=True)
+            raise typer.Exit(code=1)
+
+        builder = ContextBuilder(target)
+        result = builder.prepare(task)
+
+        output = {
+            "task": result.task,
+            "entry_points": result.entry_points,
+            "relevant_files": [f.__dict__ for f in result.relevant_files],
+            "call_flow": result.call_flow,
+            "snippets": [s.__dict__ for s in result.snippets],
+            "tests": result.tests,
+            "notes": result.notes,
+        }
+
+        typer.echo(json.dumps(output, indent=2, ensure_ascii=False))

sourcecode/detectors/go.py

@@ -39,7 +39,13 @@ class GoDetector(AbstractDetector):
         ]
         preferred = [path for path in entry_candidates if path.startswith("cmd/")] or entry_candidates
         entry_points = [
-            EntryPoint(path=path, stack="go", kind="binary", source="go.mod")
+            EntryPoint(
+                path=path,
+                stack="go",
+                kind="binary",
+                source="convention",
+                confidence="medium",
+            )
             for path in unique_strings(preferred)
         ]
         stack = StackDetection(

sourcecode/detectors/nodejs.py

@@ -77,20 +77,33 @@ class NodejsDetector(AbstractDetector):
     def _collect_entry_points(
         self, context: DetectionContext, package_json: dict[str, Any]
     ) -> list[EntryPoint]:
-        candidate_paths: list[str] = []
+        entry_points: list[EntryPoint] = []
+        seen: set[str] = set()
         main = package_json.get("main")
         if isinstance(main, str) and main.strip():
-            candidate_paths.append(main.strip())
+            path = main.strip()
+            if path_exists_in_tree(context.file_tree, path):
+                seen.add(path)
+                entry_points.append(
+                    EntryPoint(
+                        path=path,
+                        stack="nodejs",
+                        kind="server",
+                        source="package.json",
+                        confidence="high",
+                    )
+                )
 
+        convention_candidates: list[str] = []
         bin_field = package_json.get("bin")
         if isinstance(bin_field, str) and bin_field.strip():
-            candidate_paths.append(bin_field.strip())
+            convention_candidates.append(bin_field.strip())
         elif isinstance(bin_field, dict):
-            candidate_paths.extend(
+            convention_candidates.extend(
                 str(value).strip() for value in bin_field.values() if isinstance(value, str) and value.strip()
             )
 
-        candidate_paths.extend(
+        convention_candidates.extend(
             [
                 "server.js",
                 "src/index.js",
@@ -103,11 +116,17 @@ class NodejsDetector(AbstractDetector):
             ]
         )
 
-        entry_points: list[EntryPoint] = []
-        for path in unique_strings(candidate_paths):
-            if path_exists_in_tree(context.file_tree, path):
-                kind = "web" if path.startswith(("app/", "pages/")) else "server"
-                entry_points.append(
-                    EntryPoint(path=path, stack="nodejs", kind=kind, source="package.json")
+        for path in unique_strings(convention_candidates):
+            if path in seen or not path_exists_in_tree(context.file_tree, path):
+                continue
+            kind = "web" if path.startswith(("app/", "pages/")) else "server"
+            entry_points.append(
+                EntryPoint(
+                    path=path,
+                    stack="nodejs",
+                    kind=kind,
+                    source="convention",
+                    confidence="medium",
                 )
+            )
         return entry_points

sourcecode/detectors/python.py

@@ -132,7 +132,7 @@ class PythonDetector(AbstractDetector):
         return {match.lower() for match in matches}
 
     def _collect_entry_points(self, context: DetectionContext) -> list[EntryPoint]:
-        candidates: list[str] = []
+        declared_candidates: list[str] = []
         pyproject = load_toml_file(context.root / "pyproject.toml")
         if pyproject:
             project = pyproject.get("project", {})
@@ -142,16 +142,38 @@ class PythonDetector(AbstractDetector):
                     for value in scripts.values():
                         if isinstance(value, str) and ":" in value:
                             module, _callable = value.split(":", 1)
-                            candidates.append(module.replace(".", "/") + ".py")
+                            declared_candidates.append(module.replace(".", "/") + ".py")
 
-        candidates.extend(["__main__.py", "main.py", "app.py", "manage.py", "src/main.py"])
         entry_points: list[EntryPoint] = []
-        for path in unique_strings(candidates):
+        declared = set()
+        for path in unique_strings(declared_candidates):
             if path_exists_in_tree(context.file_tree, path):
-                kind = "cli" if path.endswith(("__main__.py", "main.py")) else "app"
+                declared.add(path)
+                kind = "cli" if path.endswith(("__main__.py", "main.py", "cli.py")) else "app"
                 entry_points.append(
-                    EntryPoint(path=path, stack="python", kind=kind, source="manifest")
+                    EntryPoint(
+                        path=path,
+                        stack="python",
+                        kind=kind,
+                        source="pyproject.toml",
+                        confidence="high",
+                    )
                 )
+
+        convention_candidates = ["cli.py", "__main__.py", "main.py", "app.py", "manage.py", "src/main.py"]
+        for path in unique_strings(convention_candidates):
+            if path in declared or not path_exists_in_tree(context.file_tree, path):
+                continue
+            kind = "cli" if path.endswith(("__main__.py", "main.py", "cli.py")) else "app"
+            entry_points.append(
+                EntryPoint(
+                    path=path,
+                    stack="python",
+                    kind=kind,
+                    source="convention",
+                    confidence="medium",
+                )
+            )
         return entry_points
 
     def _detect_package_manager(

sourcecode/prepare_context.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from sourcecode.semantic_analyzer import SemanticAnalyzer
+
+
+# =========================
+# Output schema (simple)
+# =========================
+
+@dataclass
+class ContextSnippet:
+    file: str
+    symbol: str
+    code: str
+    reason: str
+
+
+@dataclass
+class ContextFile:
+    path: str
+    role: str
+
+
+@dataclass
+class ContextResult:
+    task: str
+    entry_points: List[Dict[str, str]]
+    relevant_files: List[ContextFile]
+    call_flow: List[Dict[str, Any]]
+    snippets: List[ContextSnippet]
+    tests: List[Dict[str, str]]
+    notes: List[str]
+
+
+# =========================
+# Core Builder
+# =========================
+
+class ContextBuilder:
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.analyzer = SemanticAnalyzer(root)
+
+    # -------------------------
+    # Public API
+    # -------------------------
+
+    def prepare(self, task: str) -> ContextResult:
+        """
+        Entry point principal.
+        """
+        semantic = self.analyzer.analyze()
+
+        entry_points = self._detect_entrypoints(semantic)
+        relevant_files = self._select_relevant_files(task, entry_points)
+        snippets = self._extract_snippets(relevant_files)
+        tests = self._find_related_tests(relevant_files)
+        call_flow = self._build_call_flow(entry_points)
+
+        notes = self._generate_notes(task)
+
+        return ContextResult(
+            task=task,
+            entry_points=entry_points,
+            relevant_files=relevant_files,
+            call_flow=call_flow,
+            snippets=snippets,
+            tests=tests,
+            notes=notes,
+        )
+
+    # -------------------------
+    # Heurísticas básicas
+    # -------------------------
+
+    def _detect_entrypoints(self, semantic: Any) -> List[Dict[str, str]]:
+        """
+        MVP: detecta cli.py o main functions
+        """
+        entrypoints: List[Dict[str, str]] = []
+
+        for path in semantic.file_paths:
+            if path.endswith("cli.py") or path.endswith("__main__.py"):
+                entrypoints.append({
+                    "file": path,
+                    "symbol": "main",
+                    "reason": "CLI entrypoint"
+                })
+
+        return entrypoints
+
+    def _select_relevant_files(
+        self,
+        task: str,
+        entry_points: List[Dict[str, str]],
+    ) -> List[ContextFile]:
+        """
+        Heurística simple:
+        - incluir entrypoints
+        - incluir archivos con palabras clave del task
+        """
+        files: List[ContextFile] = []
+
+        for ep in entry_points:
+            files.append(ContextFile(path=ep["file"], role="entrypoint"))
+
+        keywords = task.lower().split()
+
+        for path in self.analyzer.scan.file_paths:  # fallback simple
+            if any(k in path.lower() for k in keywords):
+                files.append(ContextFile(path=path, role="matched"))
+
+        # deduplicar
+        seen = set()
+        unique = []
+        for f in files:
+            if f.path not in seen:
+                seen.add(f.path)
+                unique.append(f)
+
+        return unique[:8]
+
+    def _extract_snippets(self, files: List[ContextFile]) -> List[ContextSnippet]:
+        """
+        Extrae primeras ~30 líneas como snippet simple.
+        """
+        snippets: List[ContextSnippet] = []
+
+        for f in files:
+            abs_path = self.root / f.path
+            if not abs_path.exists():
+                continue
+
+            try:
+                content = abs_path.read_text(encoding="utf-8", errors="ignore")
+            except Exception:
+                continue
+
+            snippet = "\n".join(content.splitlines()[:30])
+
+            snippets.append(ContextSnippet(
+                file=f.path,
+                symbol="module",
+                code=snippet,
+                reason=f"contenido inicial de {f.role}"
+            ))
+
+        return snippets[:12]
+
+    def _find_related_tests(self, files: List[ContextFile]) -> List[Dict[str, str]]:
+        """
+        Busca tests por naming convention.
+        """
+        tests: List[Dict[str, str]] = []
+
+        for f in files:
+            name = Path(f.path).name
+            test_name = f"test_{name}"
+
+            test_path = self.root / "tests" / test_name
+            if test_path.exists():
+                tests.append({
+                    "file": f"tests/{test_name}",
+                    "reason": "posible test relacionado"
+                })
+
+        return tests
+
+    def _build_call_flow(self, entry_points: List[Dict[str, str]]) -> List[Dict[str, Any]]:
+        """
+        MVP: placeholder (hasta que uses call graph real)
+        """
+        flow: List[Dict[str, Any]] = []
+
+        for ep in entry_points:
+            flow.append({
+                "from": ep["symbol"],
+                "to": ["unknown"]
+            })
+
+        return flow
+
+    def _generate_notes(self, task: str) -> List[str]:
+        notes: List[str] = []
+
+        if "flag" in task or "--" in task:
+            notes.append("probablemente necesitas modificar argumentos CLI")
+        if "test" in task:
+            notes.append("asegúrate de actualizar tests relacionados")
+        if "refactor" in task:
+            notes.append("mantener compatibilidad hacia atrás")
+
+        return notes

sourcecode/schema.py

@@ -66,6 +66,7 @@ class EntryPoint:
     stack: str
     kind: str = "entry"
     source: str = "manifest"
+    confidence: Literal["high", "medium", "low"] = "high"
 
 
 @dataclass
@@ -322,6 +323,7 @@ class SourceMap:
     # Phase 9: LLM Output Quality
     file_paths: list[str] = field(default_factory=list)
     project_summary: Optional[str] = None
+    architecture_summary: Optional[str] = None
     key_dependencies: list[DependencyRecord] = field(default_factory=list)
     # Phase 10: Code Quality Metrics
     file_metrics: list[FileMetrics] = field(default_factory=list)

sourcecode/serializer.py

@@ -52,7 +52,7 @@ def compact_view(sm: SourceMap) -> dict[str, Any]:
     """Proyeccion compacta del SourceMap (~500-700 tokens).
 
     Incluye: schema_version, project_type, stacks, entry_points,
-    project_summary (siempre), file_paths (siempre),
+    project_summary (siempre), architecture_summary (siempre),
     dependency_summary (cuando requested=True),
     file_tree_depth1 (backward compat).
 
@@ -73,9 +73,9 @@ def compact_view(sm: SourceMap) -> dict[str, Any]:
         "schema_version": sm.metadata.schema_version,
         "project_type": sm.project_type,
         "project_summary": sm.project_summary,
+        "architecture_summary": sm.architecture_summary,
         "stacks": [asdict(stack) for stack in sm.stacks],
         "entry_points": [asdict(entry_point) for entry_point in sm.entry_points],
-        "file_paths": sm.file_paths,
         "file_tree_depth1": depth1,
         "dependency_summary": dep_summary_dict,
     }

sourcecode/summarizer.py

@@ -4,12 +4,20 @@ Sin llamadas a API — solo templates aplicados sobre SourceMap.
 """
 from __future__ import annotations
 
+from pathlib import Path
+
+from sourcecode.detectors.parsers import load_json_file, load_toml_file
 from sourcecode.schema import SourceMap
 
+_TOOLING_PREFIXES = (".claude/", ".vscode/", "bin/")
+
 
 class ProjectSummarizer:
     """Genera project_summary: string NL deterministica desde SourceMap."""
 
+    def __init__(self, root: Path | None = None) -> None:
+        self.root = root
+
     def generate(self, sm: SourceMap) -> str:
         """Retorna descripcion NL del proyecto. Nunca lanza excepcion."""
         try:
@@ -18,9 +26,14 @@ class ProjectSummarizer:
             return "Proyecto analizado."
 
     def _build_summary(self, sm: SourceMap) -> str:
+        description = self._read_project_description()
+        if description:
+            return self._merge_description_with_structure(description, sm)
+
         # Determinar stack primario
-        primary_stacks = [s for s in sm.stacks if s.primary]
-        all_stacks = primary_stacks if primary_stacks else sm.stacks
+        non_tooling_stacks = self._filter_non_tooling_stacks(sm)
+        primary_stacks = [s for s in non_tooling_stacks if s.primary]
+        all_stacks = primary_stacks if primary_stacks else non_tooling_stacks
 
         if not all_stacks:
             return "Proyecto sin stack detectado."
@@ -44,7 +57,7 @@ class ProjectSummarizer:
         fw_part = f" ({', '.join(frameworks[:3])})" if frameworks else ""
 
         # Entry points (max 3)
-        ep_paths = [ep.path for ep in sm.entry_points[:3]]
+        ep_paths = [ep.path for ep in sm.entry_points if not self._is_tooling_path(ep.path)][:3]
         ep_part = f" Entry points: {', '.join(ep_paths)}." if ep_paths else ""
 
         # Dependencias
@@ -60,9 +73,105 @@ class ProjectSummarizer:
 
         # Monorepo: variante especial
         if project_type == "monorepo":
-            stacks_desc = ", ".join(sorted({s.stack.capitalize() for s in sm.stacks}))
-            n_ws = len({s.workspace for s in sm.stacks if s.workspace})
+            stacks_desc = ", ".join(sorted({s.stack.capitalize() for s in non_tooling_stacks}))
+            n_ws = len({s.workspace for s in non_tooling_stacks if s.workspace})
             ws_part = f" con {n_ws} workspaces" if n_ws > 0 else ""
             return f"Monorepo{ws_part} en {stacks_desc}.{ep_part}{dep_part}"
 
         return f"{type_label} en {stack_name}{fw_part}.{ep_part}{dep_part}"
+
+    def _read_project_description(self) -> str | None:
+        if self.root is None:
+            return None
+        pyproject = load_toml_file(self.root / "pyproject.toml")
+        if pyproject:
+            project = pyproject.get("project", {})
+            if isinstance(project, dict):
+                description = project.get("description")
+                if isinstance(description, str) and description.strip():
+                    return description.strip()
+
+        package_json = load_json_file(self.root / "package.json")
+        if package_json:
+            description = package_json.get("description")
+            if isinstance(description, str) and description.strip():
+                return description.strip()
+
+        return self._read_readme_paragraph()
+
+    def _read_readme_paragraph(self) -> str | None:
+        if self.root is None:
+            return None
+        for name in ("README.md", "README.rst", "README.txt"):
+            path = self.root / name
+            try:
+                content = path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            paragraph = self._extract_first_useful_paragraph(content)
+            if paragraph:
+                return paragraph
+        return None
+
+    def _extract_first_useful_paragraph(self, content: str) -> str | None:
+        lines: list[str] = []
+        in_code_block = False
+        for raw_line in content.splitlines():
+            line = raw_line.strip()
+            if line.startswith("```"):
+                in_code_block = not in_code_block
+                continue
+            if in_code_block or not line or line.startswith(("#", "<!--")):
+                if lines:
+                    break
+                continue
+            lines.append(line)
+        if not lines:
+            return None
+        return " ".join(lines).strip()
+
+    def _merge_description_with_structure(self, description: str, sm: SourceMap) -> str:
+        parts = [description.rstrip(".")]
+        entry_points = [ep.path for ep in sm.entry_points if not self._is_tooling_path(ep.path)][:2]
+        if entry_points:
+            parts.append(f"Entry points: {', '.join(entry_points)}")
+
+        non_tooling_stacks = self._filter_non_tooling_stacks(sm)
+        if non_tooling_stacks:
+            primary = self._select_summary_primary_stack(non_tooling_stacks)
+            frameworks = [framework.name for framework in primary.frameworks[:2]]
+            stack_label = primary.stack.capitalize()
+            if frameworks:
+                parts.append(f"Stack principal: {stack_label} ({', '.join(frameworks)})")
+            else:
+                parts.append(f"Stack principal: {stack_label}")
+
+        return ". ".join(parts) + "."
+
+    def _filter_non_tooling_stacks(self, sm: SourceMap) -> list:
+        filtered = [
+            stack for stack in sm.stacks
+            if not self._is_tooling_path(stack.root) and not self._is_tooling_path(stack.workspace)
+        ]
+        return filtered or sm.stacks
+
+    def _select_summary_primary_stack(self, stacks: list) -> Any:
+        def score(stack: Any) -> tuple[int, int, int, int]:
+            root_manifest_hits = 0
+            if self.root is not None:
+                root_manifest_hits = sum(
+                    1 for manifest in stack.manifests
+                    if (self.root / manifest).is_file()
+                )
+            framework_hits = len(stack.frameworks)
+            primary_hint = 1 if stack.primary else 0
+            confidence = {"low": 0, "medium": 1, "high": 2}.get(stack.confidence, 0)
+            return (root_manifest_hits, framework_hits, primary_hint, confidence)
+
+        return max(stacks, key=score)
+
+    def _is_tooling_path(self, path: str | None) -> bool:
+        if not path:
+            return False
+        normalized = path.strip().lstrip("/")
+        return normalized.startswith(_TOOLING_PREFIXES)

{sourcecode-0.9.0.dist-info → sourcecode-0.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 0.9.0
+Version: 0.11.0
 Summary: Genera un mapa de contexto estructurado de proyectos de software para agentes IA
 License: MIT
 Requires-Python: >=3.9
@@ -94,7 +94,7 @@ sourcecode --version
 | `PATH` | `.` | Directory to analyze. |
 | `--format json\|yaml` | `json` | Output format. |
 | `--output PATH` | stdout | Write to a file instead of stdout. |
-| `--compact` | off | Reduced output (~500-700 tokens): `schema_version`, `project_type`, `project_summary`, `stacks`, `entry_points`, `file_paths`, `file_tree_depth1`, and `dependency_summary` when available. |
+| `--compact` | off | Reduced output (~500-700 tokens): `schema_version`, `project_type`, `project_summary`, `architecture_summary`, `stacks`, `entry_points`, `file_tree_depth1`, and `dependency_summary` when available. |
 | `--dependencies` | off | Include direct dependencies, resolved versions, and transitive relationships when lockfiles make that possible. Also populates `key_dependencies`. |
 | `--graph-modules` | off | Include a structural module graph with imports and simple relations. |
 | `--graph-detail high\|medium\|full` | `high` | Graph detail level: summarized (high), balanced (medium), or full-fidelity (full). |
@@ -118,6 +118,7 @@ The full schema (`SourceMap`) includes the following fields:
 | `file_tree` | object | Repository tree where `null` represents a file and `{}` represents a directory. |
 | `file_paths` | array | Flat list of all project paths derived from `file_tree`, with forward-slash separators. Always present; respects `--depth`. |
 | `project_summary` | string\|null | Deterministic natural-language description of the project generated from detected stacks, entry points, and dependencies. Present when stacks are detected. |
+| `architecture_summary` | string\|null | Static summary of the main execution flow, orchestrated modules, and output produced by the project. Present when enough structural evidence is available. |
 | `stacks` | array | Stack detections with confidence, frameworks, manifests, `primary`, `root`, `workspace`, and `signals`. |
 | `project_type` | string\|null | Overall project classification. |
 | `entry_points` | array | Detected entry points by stack. |
@@ -155,6 +156,7 @@ Real output from a Python FastAPI project:
   "schema_version": "1.0",
   "project_type": "api",
   "project_summary": "API en Python (FastAPI). Entry points: src/main.py. 12 dependencias (python).",
+  "architecture_summary": null,
   "stacks": [
     {
       "stack": "python",
@@ -179,7 +181,6 @@ Real output from a Python FastAPI project:
       "source": "manifest"
     }
   ],
-  "file_paths": ["pyproject.toml", "src/main.py", "src/routes.py", "tests/test_main.py"],
   "file_tree_depth1": {
     "pyproject.toml": null,
     "src": {},
@@ -371,7 +372,7 @@ Different modes optimize for different tradeoffs between context size and depth
 
 Best for: initial orientation, deciding what to explore next, fast handoffs between agents.
 
-Includes: `project_summary` (instant project description), `stacks`, `entry_points`, `file_paths` (flat path list for easy grep/reasoning), `file_tree_depth1`, and `dependency_summary` when `--dependencies` was also requested.
+Includes: `project_summary` (instant project description), `architecture_summary` (execution-oriented static summary), `stacks`, `entry_points`, `file_tree_depth1`, and `dependency_summary` when `--dependencies` was also requested.
 
 ```bash
 sourcecode --compact .
@@ -404,9 +405,9 @@ sourcecode --docs --docs-depth full .   # include methods
 - `"Aplicacion web en Node.js (Next.js, React). Entry points: app/page.tsx."`
 - `"Monorepo con 2 workspaces en Node.js, Python."`
 
-**`file_paths` field**
+**`architecture_summary` field**
 
-`file_paths` is a flat list of all project paths (forward-slash separated). It is easier for LLMs to reason about than the nested `file_tree` dict — grep it, count by extension, or identify modules by path pattern without recursive traversal.
+`architecture_summary` is a static 3-5 line summary oriented to execution flow. It answers what the main entry point does, which modules it orchestrates, and what the project produces. In compact mode it replaces the low-signal value that `file_paths` used to occupy.
 
 **`key_dependencies` field**
 

{sourcecode-0.9.0.dist-info → sourcecode-0.11.0.dist-info}/RECORD

@@ -1,17 +1,19 @@
-sourcecode/__init__.py,sha256=Zm9JrFOztIKNR75snzMqgJrHWngMW7fSSQKrDzr4KJ4,99
+sourcecode/__init__.py,sha256=R1kLSVb6MQgOcPPp7JrOi_v8YHooGoXpqDAgs0Nn_7E,100
+sourcecode/architecture_summary.py,sha256=6FCTEHmbESxx4lmc4A61x5DPvI57oJAUnaJIZ-GjRkc,10371
 sourcecode/classifier.py,sha256=7ubGTn5vfw9z-9eosLIYDtQUu7d8dvB4XKKDxysUVSM,6910
-sourcecode/cli.py,sha256=kUB3u7iXnjPpmVAqMjlBrF9sOFPHfnP8XhdsH2nZIlw,19918
+sourcecode/cli.py,sha256=_05FuIgLWiVDqq2OUbgTeX6os3vUeLDvQZpbfJw8FzE,21217
 sourcecode/coverage_parser.py,sha256=0IfE-0BNF1NxTjRnAuHnn1U0VzcB_aGBQMITR6Qsy3E,19701
 sourcecode/dependency_analyzer.py,sha256=c8tSbUpug-2avKNWCP4-_e2_uhBwWl96LwL1Be8O90M,39067
 sourcecode/doc_analyzer.py,sha256=nnTOsO1tfZvaDPy5PKjRLlg6EQZ-2ONRbXlxDeogH8o,19891
 sourcecode/graph_analyzer.py,sha256=S5z8mrGfLwN26Mt2IaCR4dOpQ_APU16cfihSp640eGQ,45241
 sourcecode/metrics_analyzer.py,sha256=zQrIPKDrGIUq4iptXbckflOj2V9897e_6vGZKEwa4b4,20124
+sourcecode/prepare_context.py,sha256=X43dEPe2cb7uMwlpQwVJMe0rQIZ0juaJ7H3F37sPbNc,5371
 sourcecode/redactor.py,sha256=abSf5jH_IzYzpjF3lEN6hCwdXxvmyHs-3DHz9fd8Mic,2883
 sourcecode/scanner.py,sha256=TvcuD77m_NF8OlTj3XH1b_jO0qrto8c90fND96ecqb0,6182
-sourcecode/schema.py,sha256=2tGbFDMvQrsIA7ZWZvUNflkPBLWhEQjAqNtHgTkJHZ0,10112
+sourcecode/schema.py,sha256=PAXaAGhJOseyjSYi24vwqOQr52ugjFfMuTe-pP6lnXs,10217
 sourcecode/semantic_analyzer.py,sha256=8loG-y_4fN7wUKmGhy9z1yAfn-xV-6yjYklFr3wxCW8,79347
-sourcecode/serializer.py,sha256=x_F2qIEGpKXrzgBHwkcN9O94It8R_QV02VfMnWdlKD0,3274
-sourcecode/summarizer.py,sha256=mNZL4uIZ_jnOYJt3_XVCqEFn2JuLR4E8LlySB1TsTxc,2567
+sourcecode/serializer.py,sha256=5_hzf-imtFgYRGjJ_ZMXuK76ZnDbgJ_RGYgVlewhMz0,3304
+sourcecode/summarizer.py,sha256=wCtD4sQ3b81qd7mnqiODJJRgeSk_AMchkaXuxJ_WRd8,7011
 sourcecode/tree_utils.py,sha256=5WHQc2L-AGqxKFfYYcQftE6hETxgUxP9MWDuaThcAUw,991
 sourcecode/workspace.py,sha256=1L4xH38gU89fLeMYSuF3ft7lSdCyTfMfJ9NQt5q4Ric,6904
 sourcecode/detectors/__init__.py,sha256=A0AACJFF6HWf_RgatNtWu3PUzstcKtIGM9f1PoFcJug,1987
@@ -19,21 +21,21 @@ sourcecode/detectors/base.py,sha256=mLqDNil8VkFRNbzwO2wPbmw_aaVg3WR_WzzRjU58xbU,
 sourcecode/detectors/dart.py,sha256=77KDgBY-xkbzLjs0Emw6c0NuQY-tQZR5PCHa9r0t2OE,1476
 sourcecode/detectors/dotnet.py,sha256=BofpMPVOJmiUpCFpkd0y7zSzzBj4jeXZkZR5AksBg8w,2017
 sourcecode/detectors/elixir.py,sha256=Aurq99BvJvZ1k9lNBiI-RGOJzi8e7maQd225IG128PE,1759
-sourcecode/detectors/go.py,sha256=oifvbih6i4yrUO2zQs3kVXEdirr6jVriiV1fJ_-NF2I,1748
+sourcecode/detectors/go.py,sha256=UAOmAX3YbpwuXSw2UBNYYDR6Mj5zJeLYK3vyNU9yb5I,1868
 sourcecode/detectors/heuristic.py,sha256=Phimturkvi5ZwNdt005TizYTrllZk1pqHpfXOkFZJbc,1943
 sourcecode/detectors/java.py,sha256=XdONBlcBb0Vo-2hvG77Fw00X41d2KlHFCPXJCuzwAl0,3547
 sourcecode/detectors/jvm_ext.py,sha256=ViHKwUzlKXjpjNNB6_wK0XptR29VUsdLobW2U-mS5BM,2665
-sourcecode/detectors/nodejs.py,sha256=rfUG2oT5SsV5nMCuXY4v99IrAWF0lL5i47m9RHOM2mM,3919
+sourcecode/detectors/nodejs.py,sha256=Epkz8vHdTscjQzCCZHuhOehMu0MrSPNXzfrQU3fHkMA,4535
 sourcecode/detectors/parsers.py,sha256=CQhhFGk8lSXruIfLe571-1HOId3W0ssnY2ioHMGtOrg,2338
 sourcecode/detectors/php.py,sha256=6l5pFlUuKrrC6XlWPSgYTEnnPm3hoFxMM4DRAnjL4nM,1920
 sourcecode/detectors/project.py,sha256=QOTt2p55Wt6FNUSo0_1P7iojM_CsVevvQqHQmLqVxYk,6022
-sourcecode/detectors/python.py,sha256=UVB5M_B8t-zQkSrIqmNQR5KD7RqDHzT8C3CcazgxEi8,6900
+sourcecode/detectors/python.py,sha256=cib7EmEpQSF8X1sI3oAaGxHqP1rg2g0RkmJIuR8VHsM,7714
 sourcecode/detectors/ruby.py,sha256=3_Hd5YqlErpTtyTRcUTPnMp1TF92hT-TnYYeclLbF1c,1625
 sourcecode/detectors/rust.py,sha256=iUz9lE4HfBy8CBaDwGhfh6kLsNIovrH2ay2v3y6qNDc,2298
 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.9.0.dist-info/METADATA,sha256=-DmATf2XsAgHJnw3Wg6S1xOjMqKVt_yr5XunJIR2Uu8,14903
-sourcecode-0.9.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-0.9.0.dist-info/entry_points.txt,sha256=voDtdlGU2-jR3wCZpQoOls_0eUKaDVCKIfajGHFDATs,50
-sourcecode-0.9.0.dist-info/RECORD,,
+sourcecode-0.11.0.dist-info/METADATA,sha256=6jKGk6co2EKF_2PuO3mg559EeI3FODtg9bXJnrFoPEc,15093
+sourcecode-0.11.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-0.11.0.dist-info/entry_points.txt,sha256=voDtdlGU2-jR3wCZpQoOls_0eUKaDVCKIfajGHFDATs,50
+sourcecode-0.11.0.dist-info/RECORD,,