sourcecode 0.8.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Genera mapas de contexto estructurado para agentes IA."""
 
-__version__ = "0.8.0"
+__version__ = "0.10.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

@@ -112,6 +112,11 @@ def main(
         "--full-metrics",
         help="Incluir metricas de calidad: LOC, simbolos, complejidad, tests y cobertura por fichero",
     ),
+    semantics: bool = typer.Option(
+        False,
+        "--semantics",
+        help="Incluir call graph semantico, linking cross-file de simbolos y resolucion avanzada de imports",
+    ),
 ) -> None:
     """Genera un mapa de contexto estructurado del proyecto en formato JSON o YAML."""
     # Validar formato
@@ -228,6 +233,9 @@ def main(
     doc_analyzer = DocAnalyzer() if docs else None
     metrics_analyzer = MetricsAnalyzer() if full_metrics else None
 
+    from sourcecode.semantic_analyzer import SemanticAnalyzer
+    semantic_analyzer = SemanticAnalyzer() if semantics else None
+
     root_manifests = [
         manifest
         for manifest in manifests
@@ -424,9 +432,51 @@ def main(
         metrics_summary=metrics_summary,
     )
 
-    # Phase 9: LLM Output Quality — poblar campos derivados
-    from sourcecode.summarizer import ProjectSummarizer
-    from sourcecode.tree_utils import flatten_file_tree
+    # Semantic analysis (--semantics flag)
+    if semantic_analyzer is not None:
+        if workspace_analysis.workspaces:
+            all_sem_calls: list[Any] = []
+            all_sem_symbols: list[Any] = []
+            all_sem_links: list[Any] = []
+            all_sem_summaries: list[Any] = []
+            for ws in workspace_analysis.workspaces:
+                ws_calls, ws_syms, ws_links, ws_sum = semantic_analyzer.analyze(
+                    target / ws.path,
+                    (
+                        filter_sensitive_files(
+                            FileScanner(target / ws.path, max_depth=depth).scan_tree()
+                        )
+                    ),
+                    workspace=ws.path,
+                )
+                all_sem_calls.extend(ws_calls)
+                all_sem_symbols.extend(ws_syms)
+                all_sem_links.extend(ws_links)
+                all_sem_summaries.append(ws_sum)
+            merged_sem = semantic_analyzer.merge_summaries(all_sem_summaries)
+            sm = replace(
+                sm,
+                semantic_calls=all_sem_calls,
+                semantic_symbols=all_sem_symbols,
+                semantic_links=all_sem_links,
+                semantic_summary=merged_sem,
+            )
+        else:
+            sem_calls, sem_syms, sem_links, sem_sum = semantic_analyzer.analyze(
+                target, file_tree
+            )
+            sm = replace(
+                sm,
+                semantic_calls=sem_calls,
+                semantic_symbols=sem_syms,
+                semantic_links=sem_links,
+                semantic_summary=sem_sum,
+            )
+
+    # 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
 
     # LQN-01: lista plana de paths del file_tree con separador forward-slash
     sm.file_paths = [
@@ -446,8 +496,9 @@ def main(
 
         sm.key_dependencies = sorted(direct_deps, key=_dep_sort_key)[:15]
 
-    # LQN-02: resumen NL deterministico
-    sm.project_summary = ProjectSummarizer().generate(sm)
+    # LQN-02: resumen NL deterministico
+    sm.project_summary = ProjectSummarizer(target).generate(sm)
+    sm.architecture_summary = ArchitectureSummarizer(target).generate(sm)
 
     # 4. Serializar (con o sin modo compact)
     if compact:

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/schema.py

@@ -66,6 +66,7 @@ class EntryPoint:
     stack: str
     kind: str = "entry"
     source: str = "manifest"
+    confidence: Literal["high", "medium", "low"] = "high"
 
 
 @dataclass
@@ -236,6 +237,66 @@ class DocSummary:
     limitations: list[str] = field(default_factory=list)
 
 
+@dataclass
+class SymbolRecord:
+    """Symbol definition found in a source file."""
+
+    symbol: str               # local name: "MyClass" or "my_func"
+    kind: str                 # "function" | "class" | "constant" | "method"
+    language: str
+    path: str                 # relative path to defining file
+    line: Optional[int] = None
+    qualified_name: Optional[str] = None  # "pkg.module.MyClass"
+    exported: bool = True     # False if name starts with _ and no __all__ override
+    workspace: Optional[str] = None
+
+
+@dataclass
+class CallRecord:
+    """A resolved call from one symbol to another, possibly across files."""
+
+    caller_path: str
+    caller_symbol: str
+    callee_path: str
+    callee_symbol: str
+    call_line: Optional[int] = None
+    confidence: Literal["high", "medium", "low"] = "medium"
+    method: Literal["ast", "heuristic", "unresolved"] = "heuristic"
+    args: list[str] = field(default_factory=list)
+    kwargs: dict[str, str] = field(default_factory=dict)
+    workspace: Optional[str] = None
+
+
+@dataclass
+class SymbolLink:
+    """A symbol imported in one file, resolved to its definition in another."""
+
+    importer_path: str
+    symbol: str
+    source_path: Optional[str] = None
+    source_line: Optional[int] = None
+    is_external: bool = False
+    confidence: Literal["high", "medium", "low"] = "high"
+    method: Literal["ast", "heuristic", "unresolved"] = "ast"
+    workspace: Optional[str] = None
+
+
+@dataclass
+class SemanticSummary:
+    """Summary of the --semantics analysis."""
+
+    requested: bool = False
+    call_count: int = 0
+    symbol_count: int = 0
+    link_count: int = 0
+    languages: list[str] = field(default_factory=list)
+    language_coverage: dict[str, str] = field(default_factory=dict)
+    files_analyzed: int = 0
+    files_skipped: int = 0
+    truncated: bool = False
+    limitations: list[str] = field(default_factory=list)
+
+
 @dataclass
 class SourceMap:
     """Schema completo del output v1.0.
@@ -262,7 +323,13 @@ 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)
     metrics_summary: Optional[MetricsSummary] = None
+    # Phase 12: Static Semantics
+    semantic_calls: list[CallRecord] = field(default_factory=list)
+    semantic_symbols: list[SymbolRecord] = field(default_factory=list)
+    semantic_links: list[SymbolLink] = field(default_factory=list)
+    semantic_summary: Optional[SemanticSummary] = None