sourcecode 0.21.0__py3-none-any.whl → 0.22.0__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/architecture_summary.py

@@ -14,6 +14,20 @@ _NODE_EXTENSIONS = {".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"}
 _GO_EXTENSIONS = {".go"}
 _JAVA_EXTENSIONS = {".java", ".kt", ".scala"}
 
+_CORE_DETECTION_MODULES = {"scanner", "detectors", "classifier", "workspace"}
+
+_OPTIONAL_LABEL_MAP: dict[str, str] = {
+    "DependencyAnalyzer": "dependencias",
+    "GraphAnalyzer": "grafo de módulos",
+    "DocAnalyzer": "docs y docstrings",
+    "MetricsAnalyzer": "métricas de calidad",
+    "SemanticAnalyzer": "semántica y call graph",
+    "ArchitectureAnalyzer": "inferencia arquitectónica",
+    "GitAnalyzer": "contexto git",
+    "EnvAnalyzer": "variables de entorno",
+    "CodeNotesAnalyzer": "anotaciones de código",
+}
+
 
 class ArchitectureSummarizer:
     """Construye un resumen arquitectonico estatico de 3-5 lineas."""
@@ -51,18 +65,25 @@ class ArchitectureSummarizer:
         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))
+            lang_lines = self._summarize_python_entry(entry_point.path, content)
         elif suffix in _NODE_EXTENSIONS:
-            lines.extend(self._summarize_node_entry(entry_point.path, content))
+            lang_lines = self._summarize_node_entry(entry_point.path, content)
         elif suffix in _GO_EXTENSIONS:
-            lines.extend(self._summarize_go_entry(entry_point.path, content))
+            lang_lines = self._summarize_go_entry(entry_point.path, content)
         elif suffix in _JAVA_EXTENSIONS:
-            lines.extend(self._summarize_java_entry(entry_point.path, content, sm.stacks))
+            lang_lines = self._summarize_java_entry(entry_point.path, content, sm.stacks)
         else:
-            lines.append("Orquesta modulos internos no detallados por el analisis estatico disponible.")
+            lang_lines = []
+
+        if lang_lines:
+            # Product-level description available — no need for internal "Entry point: ..." header
+            lines = lang_lines
+        else:
+            lines = [self._describe_entry_point(entry_point, sm.project_type)]
+            if not lang_lines:
+                lines.append("Orquesta modulos internos no detallados por el analisis estatico disponible.")
 
         unique_lines: list[str] = []
         seen: set[str] = set()
@@ -78,11 +99,11 @@ class ArchitectureSummarizer:
         try:
             tree = ast.parse(content)
         except SyntaxError:
-            return ["Orquesta modulos Python, pero el entry point no pudo parsearse por completo."]
+            return []
 
         package_prefix = self._python_package_prefix(path)
         imported_modules: list[str] = []
-        optional_analyzers: list[str] = []
+        optional_class_names: list[str] = []
         uses_serializer = False
         uses_redactor = False
 
@@ -90,30 +111,58 @@ class ArchitectureSummarizer:
             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":
+                if node.module.endswith(".serializer") or "serializer" in node.module:
                     uses_serializer = True
-                if node.module == "sourcecode.redactor":
+                if node.module.endswith(".redactor") or "redactor" in node.module:
                     uses_redactor = True
             elif isinstance(node, ast.Assign):
-                optional = self._extract_optional_analyzer(node)
-                if optional:
-                    optional_analyzers.append(optional)
+                cls_name = self._extract_optional_analyzer_class_name(node)
+                if cls_name:
+                    optional_class_names.append(cls_name)
 
+        module_set = set(imported_modules)
         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)}.")
+
+        # Detection line — infer from core modules present
+        has_core = bool(module_set & _CORE_DETECTION_MODULES)
+        if has_core:
+            lines.append("Analiza el árbol del repositorio y detecta stack, entrypoints y tipo de proyecto.")
+        elif module_set:
+            lines.append("Analiza el proyecto y produce información estructurada.")
+
+        # Output line
         if uses_serializer:
-            output_line = "Produce un SourceMap serializado en JSON/YAML y una vista compacta."
+            out = "Produce un SourceMap serializable en JSON/YAML"
             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.")
+                out += " con redacción de secretos"
+            lines.append(out + ".")
+
+        # Optional capabilities line
+        opt_labels = [
+            _OPTIONAL_LABEL_MAP[cls]
+            for cls in optional_class_names
+            if cls in _OPTIONAL_LABEL_MAP
+        ]
+        if opt_labels:
+            if len(opt_labels) > 1:
+                joined = ", ".join(opt_labels[:-1]) + " y " + opt_labels[-1]
+            else:
+                joined = opt_labels[0]
+            lines.append(f"Opcionalmente añade {joined}.")
+
         return lines
 
+    def _extract_optional_analyzer_class_name(self, node: ast.Assign) -> str | None:
+        value = node.value
+        if not isinstance(value, ast.IfExp):
+            return None
+        if not isinstance(value.body, ast.Call):
+            return None
+        if not isinstance(value.body.func, ast.Name):
+            return None
+        cls_name = value.body.func.id
+        return cls_name if cls_name.endswith("Analyzer") else None
+
     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]

sourcecode/classifier.py

@@ -128,7 +128,9 @@ class TypeClassifier:
         has_api = False
         for stack in stacks:
             frameworks = {framework.name for framework in stack.frameworks}
-            if frameworks & _WEB_FRAMEWORKS or stack.stack == "nodejs":
+            if frameworks & _WEB_FRAMEWORKS:
+                has_web = True
+            elif stack.stack == "nodejs" and stack.detection_method != "heuristic":
                 has_web = True
             if frameworks & _API_FRAMEWORKS or stack.stack in _API_STACKS:
                 has_api = True

sourcecode/cli.py

@@ -78,7 +78,12 @@ def main(
     no_tree: bool = typer.Option(
         False,
         "--no-tree",
-        help="Suprimir file_tree y file_paths del output (ideal con --dependencies en proyectos grandes)",
+        help="Suprimir file_tree y file_paths del output (ahora deprecado: el arbol ya no se incluye por defecto)",
+    ),
+    tree: bool = typer.Option(
+        False,
+        "--tree",
+        help="Incluir file_tree completo y file_paths en el output (capa deep-dive)",
     ),
     no_redact: bool = typer.Option(
         False,
@@ -114,7 +119,7 @@ def main(
     full_metrics: bool = typer.Option(
         False,
         "--full-metrics",
-        help="Incluir metricas de calidad: LOC, simbolos, complejidad, tests y cobertura por fichero",
+        help="Auditoria tecnica: LOC, simbolos, complejidad ciclomatica y cobertura por fichero. No incluido en --agent (uso: CI, code review, no context principal para agentes IA)",
     ),
     semantics: bool = typer.Option(
         False,
@@ -159,7 +164,7 @@ def main(
     agent: bool = typer.Option(
         False,
         "--agent",
-        help="Modo agente: selecciona automaticamente --compact --dependencies --env-map --code-notes y activa --no-tree en proyectos Java/Gradle o grandes",
+        help="Modo agente: output estructurado y sin ruido para consumo por IA. Incluye identidad, entrypoints, arquitectura, dependencias clave, señales operacionales y gaps. Sin arbol de ficheros ni secciones vacias.",
     ),
 ) -> None:
     """Genera un mapa de contexto estructurado del proyecto en formato JSON o YAML."""
@@ -216,7 +221,7 @@ def main(
         SourceMap,
         StackDetection,
     )
-    from sourcecode.serializer import compact_view, normalize_source_map, validate_cross_analyzer_consistency, validate_source_map, write_output
+    from sourcecode.serializer import agent_view, compact_view, normalize_source_map, standard_view, validate_cross_analyzer_consistency, validate_source_map, write_output
     from sourcecode.workspace import WorkspaceAnalyzer
 
     # 1. Escanear el directorio (SCAN-01 a SCAN-05)
@@ -235,15 +240,13 @@ def main(
     _java_min_depth = 8
     effective_depth = max(depth, _java_min_depth) if _is_java and depth < _java_min_depth else depth
 
-    # --agent: auto-select flags based on project characteristics
+    # --agent: enable signal analyzers; output via agent_view (not compact)
     if agent:
-        compact = True
-        if _is_java:
-            no_tree = True
-        _agent_flags = ["--compact", "--dependencies", "--env-map", "--code-notes"]
-        if no_tree:
-            _agent_flags.append("--no-tree")
-        typer.echo(f"[agent] {' '.join(_agent_flags)}", err=True)
+        dependencies = True
+        env_map = True
+        code_notes = True
+        no_tree = True  # agents never need the raw file tree
+        typer.echo("[agent] dependencies env-map code-notes (no-tree)", err=True)
 
     scanner = FileScanner(target, max_depth=effective_depth)
     raw_tree = scanner.scan_tree()
@@ -562,16 +565,20 @@ def main(
         p.replace("\\", "/") for p in flatten_file_tree(sm.file_tree)
     ]
 
-    # LQN-05: top-15 dependencias directas de manifest/lockfile
+    # LQN-05: top-15 dependencias directas de manifest/lockfile, ordenadas por rol
     if dependency_analyzer is not None:
+        from sourcecode.dependency_analyzer import _ROLE_PRIORITY
+
         primary_ecosystem = sm.stacks[0].stack if sm.stacks else ""
         direct_deps = [
             d for d in sm.dependencies
             if d.scope != "transitive" and d.source in {"manifest", "lockfile"}
         ]
 
-        def _dep_sort_key(d: Any) -> tuple[int, str]:
-            return (0 if d.ecosystem == primary_ecosystem else 1, d.name.lower())
+        def _dep_sort_key(d: Any) -> tuple[int, int, str]:
+            role_order = _ROLE_PRIORITY.get(d.role or "runtime", 5)
+            eco_order = 0 if d.ecosystem == primary_ecosystem else 1
+            return (role_order, eco_order, d.name.lower())
 
         sm.key_dependencies = sorted(direct_deps, key=_dep_sort_key)[:15]
 
@@ -616,24 +623,23 @@ def main(
     for _finding in validate_cross_analyzer_consistency(sm, strict=False):
         typer.echo(f"[consistency] {_finding}", err=True)
 
-    # 4. Serializar (con o sin modo compact)
-    if compact:
+    # 4. Serializar
+    if agent:
+        data = agent_view(sm)
+        if not no_redact:
+            data = redact_dict(data)
+        content = json.dumps(data, indent=2, ensure_ascii=False)
+    elif compact:
         data = compact_view(sm, no_tree=no_tree)
-        # Aplicar redaccion sobre el dict del compact view
         if not no_redact:
             data = redact_dict(data)
         content = json.dumps(data, indent=2, ensure_ascii=False)
     else:
-        # Redactar sobre el dict serializado (SEC-01, SEC-03)
-        raw_dict = asdict(sm)
-        if no_tree:
-            raw_dict.pop("file_tree", None)
-            raw_dict.pop("file_paths", None)
+        raw_dict = standard_view(sm, include_tree=tree and not no_tree)
         if not no_redact:
             raw_dict = redact_dict(raw_dict)
 
         if format == "yaml":
-            # Para YAML, serializar el dict directamente con ruamel.yaml
             from io import StringIO
 
             from ruamel.yaml import YAML

sourcecode/dependency_analyzer.py

@@ -12,6 +12,77 @@ from ruamel.yaml import YAML
 from sourcecode.detectors.parsers import load_json_file, load_toml_file, read_text_lines
 from sourcecode.schema import DependencyRecord, DependencySummary
 
+# ── Role inference ────────────────────────────────────────────────────────────
+
+_PY_TESTTOOLS: frozenset[str] = frozenset({
+    "pytest", "unittest2", "hypothesis", "nose", "nose2", "coverage", "tox",
+    "factory-boy", "faker", "responses", "moto", "freezegun", "httpretty",
+    "respx", "pytest-cov", "pytest-mock", "pytest-asyncio", "pytest-xdist",
+})
+_PY_DEVTOOLS: frozenset[str] = frozenset({
+    "mypy", "ruff", "flake8", "black", "pylint", "bandit", "isort",
+    "pre-commit", "sphinx", "mkdocs", "pyright", "pyflakes", "autopep8",
+    "pycodestyle", "pydocstyle", "vulture",
+})
+_PY_SERIALIZATION: frozenset[str] = frozenset({
+    "ruamel.yaml", "pyyaml", "orjson", "msgpack", "ujson", "simplejson",
+    "cbor2", "tomli", "tomllib", "toml",
+})
+_PY_PARSING: frozenset[str] = frozenset({
+    "pathspec", "gitpython", "lxml", "beautifulsoup4", "html5lib",
+    "regex", "pyparsing",
+})
+
+_NODE_TESTTOOLS: frozenset[str] = frozenset({
+    "jest", "@jest/globals", "mocha", "jasmine", "chai", "karma",
+    "cypress", "playwright", "@playwright/test", "vitest", "@vitest/ui",
+    "sinon", "nock", "supertest",
+})
+_NODE_DEVTOOLS: frozenset[str] = frozenset({
+    "eslint", "prettier", "typescript", "@types/node", "webpack", "rollup",
+    "parcel", "@babel/core", "husky", "lint-staged", "nodemon", "ts-node", "tsx",
+})
+
+_DEV_SCOPES: frozenset[str] = frozenset({"dev", "optional"})
+
+_ROLE_PRIORITY: dict[str, int] = {
+    "runtime": 0,
+    "parsing": 1,
+    "serialization": 2,
+    "testtool": 3,
+    "devtool": 4,
+}
+
+
+def _infer_role(name: str, ecosystem: str, scope: str) -> str:
+    """Infer dependency role: runtime | parsing | serialization | devtool | testtool."""
+    n = name.lower()
+    is_dev = scope in _DEV_SCOPES or scope.startswith(("optional:", "group:"))
+
+    if ecosystem == "python":
+        if n in _PY_TESTTOOLS or n.startswith("pytest-"):
+            return "testtool"
+        if n in _PY_DEVTOOLS:
+            return "devtool"
+        if is_dev:
+            return "devtool"
+        if n in _PY_SERIALIZATION:
+            return "serialization"
+        if n in _PY_PARSING:
+            return "parsing"
+        return "runtime"
+
+    if ecosystem == "nodejs":
+        if n in _NODE_TESTTOOLS or n.startswith("@testing-library/"):
+            return "testtool"
+        if n in _NODE_DEVTOOLS:
+            return "devtool"
+        if is_dev:
+            return "devtool"
+        return "runtime"
+
+    return "devtool" if is_dev else "runtime"
+
 
 class DependencyAnalyzer:
     """Resuelve dependencias desde manifests y lockfiles sin ejecutar toolchains."""
@@ -41,6 +112,10 @@ class DependencyAnalyzer:
             limitations.extend(handler_limitations)
 
         deduped = self._dedupe(records)
+        deduped = [
+            replace(r, role=_infer_role(r.name, r.ecosystem, r.scope))
+            for r in deduped
+        ]
         return deduped, self._build_summary(deduped, limitations)
 
     def merge_summaries(self, summaries: Iterable[DependencySummary]) -> DependencySummary:

sourcecode/detectors/base.py

@@ -15,6 +15,8 @@ class DetectionContext:
     root: Path
     file_tree: dict[str, Any]
     manifests: list[str] = field(default_factory=list)
+    manifest_types: dict[str, str] = field(default_factory=dict)
+    # manifest_types: {filename → "application"|"workspace"|"auxiliary"|"config"}
 
 
 class AbstractDetector(ABC):

sourcecode/detectors/heuristic.py

@@ -43,6 +43,8 @@ class HeuristicDetector(AbstractDetector):
         paths = flatten_file_tree(context.file_tree)
         counts: Counter[str] = Counter()
         for path in paths:
+            if path.startswith("."):
+                continue
             for extension, stack in _EXTENSION_MAP.items():
                 if path.endswith(extension):
                     counts[stack] += 1

sourcecode/detectors/nodejs.py

@@ -28,7 +28,12 @@ class NodejsDetector(AbstractDetector):
     priority = 20
 
     def can_detect(self, context: DetectionContext) -> bool:
-        return "package.json" in context.manifests
+        if "package.json" not in context.manifests:
+            return False
+        if not path_exists_in_tree(context.file_tree, "package.json"):
+            return False
+        manifest_type = context.manifest_types.get("package.json", "application")
+        return manifest_type not in {"auxiliary", "config"}
 
     def detect(self, context: DetectionContext) -> tuple[list[StackDetection], list[EntryPoint]]:
         package_json = load_json_file(context.root / "package.json")

sourcecode/detectors/project.py

@@ -7,6 +7,7 @@ from typing import Any
 from sourcecode.classifier import TypeClassifier
 from sourcecode.detectors.base import AbstractDetector, DetectionContext
 from sourcecode.detectors.tooling import collect_tooling_signals, infer_package_manager
+from sourcecode.scanner import classify_manifest
 from sourcecode.schema import EntryPoint, FrameworkDetection, StackDetection
 
 _CONFIDENCE_RANK = {"low": 0, "medium": 1, "high": 2}
@@ -30,7 +31,15 @@ class ProjectDetector:
         manifests: Sequence[str],
     ) -> tuple[list[StackDetection], list[EntryPoint], str | None]:
         manifest_names = [Path(manifest).name for manifest in manifests]
-        context = DetectionContext(root=root, file_tree=file_tree, manifests=manifest_names)
+        manifest_types = {
+            Path(m).name: classify_manifest(m, root) for m in manifests
+        }
+        context = DetectionContext(
+            root=root,
+            file_tree=file_tree,
+            manifests=manifest_names,
+            manifest_types=manifest_types,
+        )
         merged_stacks: dict[str, StackDetection] = {}
         merged_entry_points: dict[str, EntryPoint] = {}
 

sourcecode/detectors/python.py

@@ -12,7 +12,7 @@ from sourcecode.detectors.base import (
 )
 from sourcecode.detectors.parsers import load_toml_file, read_text_lines, unique_strings
 from sourcecode.schema import FrameworkDetection
-from sourcecode.tree_utils import path_exists_in_tree
+from sourcecode.tree_utils import find_files_by_name, path_exists_in_tree
 
 _FRAMEWORK_MAP = {
     "fastapi": "FastAPI",
@@ -146,35 +146,84 @@ class PythonDetector(AbstractDetector):
         entry_points: list[EntryPoint] = []
         declared = set()
         for path in unique_strings(declared_candidates):
-            if path_exists_in_tree(context.file_tree, path):
-                declared.add(path)
-                kind = "cli" if path.endswith(("__main__.py", "main.py", "cli.py")) else "app"
+            actual = path
+            if not path_exists_in_tree(context.file_tree, path):
+                src_path = f"src/{path}"
+                if path_exists_in_tree(context.file_tree, src_path):
+                    actual = src_path
+                else:
+                    continue
+            declared.add(actual)
+            kind = "cli" if actual.endswith(("__main__.py", "main.py", "cli.py")) else "app"
+            entry_points.append(
+                EntryPoint(
+                    path=actual,
+                    stack="python",
+                    kind=kind,
+                    source="pyproject.toml",
+                    confidence="high",
+                )
+            )
+
+        _CONVENTION_NAMES = {"cli.py", "__main__.py", "main.py", "app.py", "manage.py"}
+        seen_paths = set(declared)
+        for fname in _CONVENTION_NAMES:
+            for path in find_files_by_name(context.file_tree, fname):
+                if path in seen_paths or self._is_tooling_path(path):
+                    continue
+                seen_paths.add(path)
+                kind = "cli" if fname in ("cli.py", "__main__.py", "main.py") else "app"
                 entry_points.append(
                     EntryPoint(
                         path=path,
                         stack="python",
                         kind=kind,
-                        source="pyproject.toml",
-                        confidence="high",
+                        source="convention",
+                        confidence="medium",
                     )
                 )
 
-        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):
+        # code signal: scan Python files for if __name__ == "__main__" guard
+        for py_path in self._find_main_guard_files(context):
+            if py_path in seen_paths:
                 continue
-            kind = "cli" if path.endswith(("__main__.py", "main.py", "cli.py")) else "app"
+            seen_paths.add(py_path)
             entry_points.append(
                 EntryPoint(
-                    path=path,
+                    path=py_path,
                     stack="python",
-                    kind=kind,
-                    source="convention",
-                    confidence="medium",
+                    kind="script",
+                    source="code_signal",
+                    confidence="low",
                 )
             )
+
         return entry_points
 
+    _MAIN_GUARD_RE = re.compile(r"^if __name__\s*==\s*['\"]__main__['\"]", re.MULTILINE)
+
+    def _find_main_guard_files(self, context: DetectionContext) -> list[str]:
+        from sourcecode.tree_utils import flatten_file_tree
+        results: list[str] = []
+        for path in flatten_file_tree(context.file_tree):
+            if not path.endswith(".py") or self._is_tooling_path(path):
+                continue
+            try:
+                content = (context.root / path).read_text(encoding="utf-8", errors="replace")
+                if self._MAIN_GUARD_RE.search(content):
+                    results.append(path)
+            except OSError:
+                continue
+        return results
+
+    def _is_tooling_path(self, path: str) -> bool:
+        parts = path.split("/")
+        return any(
+            part.startswith(".")
+            or part in {"tests", "test", "__pycache__", "node_modules", "venv", ".venv"}
+            for part in parts[:-1]
+        )
+
     def _detect_package_manager(
         self, context: DetectionContext, *, pyproject: dict[str, Any] | None
     ) -> str:

sourcecode/scanner.py

@@ -48,6 +48,57 @@ MANIFEST_NAMES: frozenset[str] = frozenset({
 })
 
 
+# Manifest types: application | library | tooling | workspace | config | auxiliary
+_APPLICATION_MANIFESTS: frozenset[str] = frozenset({
+    "pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile",
+    "package.json", "go.mod", "Cargo.toml", "pom.xml", "build.gradle",
+    "build.gradle.kts", "composer.json", "Gemfile", "pubspec.yaml",
+})
+
+_CONFIG_MANIFESTS: frozenset[str] = frozenset({
+    ".npmrc", ".yarnrc", ".yarnrc.yml", "renovate.json", ".renovaterc",
+    "dependabot.yml",
+})
+
+
+def classify_manifest(manifest_path: str, root: Path) -> str:
+    """Classify a manifest as application | workspace | auxiliary | config | tooling.
+
+    Rules (in priority order):
+    1. In a hidden directory (.claude/, .vscode/, etc.) → auxiliary
+    2. In a known editor/agent config dir → auxiliary
+    3. At root level with a known manifest name → application
+    4. One level deep in a non-hidden dir → workspace
+    5. Otherwise → auxiliary
+    """
+    try:
+        rel = Path(manifest_path).resolve().relative_to(root.resolve())
+    except ValueError:
+        rel = Path(manifest_path)
+
+    parts = rel.parts
+    if not parts:
+        return "auxiliary"
+
+    # Any hidden directory in the path → auxiliary tooling
+    if any(p.startswith(".") for p in parts[:-1]):
+        return "auxiliary"
+
+    name = parts[-1]
+
+    if len(parts) == 1:
+        if name in _CONFIG_MANIFESTS:
+            return "config"
+        if name in _APPLICATION_MANIFESTS:
+            return "application"
+        return "application"  # unknown root manifest → treat as application
+
+    if len(parts) == 2:
+        return "workspace"  # depth-1 sub-package
+
+    return "auxiliary"
+
+
 class FileScanner:
     """Escanea un directorio de proyecto y produce un arbol de ficheros filtrado.
 
@@ -172,10 +223,15 @@ class FileScanner:
             candidate = self.root / name
             if candidate.exists() and not candidate.is_symlink():
                 manifests.append(str(candidate))
-        # Profundidad 1: primer nivel
+        # Profundidad 1: primer nivel (excluir directorios ocultos — son tooling, no proyecto)
         try:
             for child in self.root.iterdir():
-                if child.is_dir() and not child.is_symlink() and child.name not in self._excludes:
+                if (
+                    child.is_dir()
+                    and not child.is_symlink()
+                    and child.name not in self._excludes
+                    and not child.name.startswith(".")
+                ):
                     for name in MANIFEST_NAMES:
                         candidate = child / name
                         if candidate.exists() and not candidate.is_symlink():

sourcecode/schema.py

@@ -83,6 +83,7 @@ class DependencyRecord:
     parent: Optional[str] = None
     manifest_path: Optional[str] = None
     workspace: Optional[str] = None
+    role: Optional[str] = None  # runtime | parsing | serialization | devtool | testtool
 
 
 @dataclass

sourcecode/serializer.py

@@ -345,6 +345,193 @@ def validate_cross_analyzer_consistency(
     return findings
 
 
+def agent_view(sm: SourceMap) -> dict[str, Any]:
+    """Opinionated output for AI agents — structured, noise-free, gap-aware.
+
+    Output order:
+        project   → what it is and what stack it uses
+        entry_points → where execution starts
+        architecture → how it's structured
+        key_dependencies → what runtime dependencies matter (when analyzed)
+        signals   → compact operational signals (env, notes, tests)
+        gaps      → what's uncertain or missing
+
+    Never includes: file_tree, file_paths, schema internals, empty sections,
+    null fields, raw dependency lists, or low-signal metadata.
+    """
+    # ── 1. Identity ──────────────────────────────────────────────────────────
+    primary = next((s for s in sm.stacks if s.primary), sm.stacks[0] if sm.stacks else None)
+
+    project: dict[str, Any] = {
+        "type": sm.project_type,
+        "summary": sm.project_summary,
+    }
+    if primary:
+        project["primary_stack"] = primary.stack
+        if primary.frameworks:
+            project["frameworks"] = [f.name for f in primary.frameworks]
+        if primary.package_manager:
+            project["package_manager"] = primary.package_manager
+        if primary.root and primary.root != ".":
+            project["root"] = primary.root
+
+    secondary = [s for s in sm.stacks if not s.primary and s.stack != (primary.stack if primary else "")]
+    if secondary:
+        project["secondary_stacks"] = sorted({s.stack for s in secondary})
+
+    result: dict[str, Any] = {"project": project}
+
+    # ── 2. Entry points ───────────────────────────────────────────────────────
+    if sm.entry_points:
+        result["entry_points"] = [
+            {k: v for k, v in asdict(ep).items() if v is not None and v != ""}
+            for ep in sm.entry_points
+        ]
+
+    # ── 3. Architecture ───────────────────────────────────────────────────────
+    if sm.architecture_summary:
+        result["architecture"] = sm.architecture_summary
+
+    # ── 4. Key dependencies (role-sorted, already computed) ───────────────────
+    if sm.dependency_summary and sm.dependency_summary.requested and sm.key_dependencies:
+        _skip = {"parent", "manifest_path", "workspace", "source", "ecosystem"}
+        result["key_dependencies"] = [
+            {k: v for k, v in asdict(d).items() if v is not None and k not in _skip}
+            for d in sm.key_dependencies
+        ]
+
+    # ── 5. Signals — compact operational context ─────────────────────────────
+    signals: dict[str, Any] = {}
+
+    if sm.env_summary and sm.env_summary.requested and sm.env_summary.total > 0:
+        signals["env_vars"] = {
+            "total": sm.env_summary.total,
+            "required": sm.env_summary.required_count,
+        }
+        if sm.env_summary.categories:
+            signals["env_vars"]["categories"] = sm.env_summary.categories
+
+    if sm.code_notes_summary and sm.code_notes_summary.requested and sm.code_notes_summary.total > 0:
+        by_kind = {k: v for k, v in sm.code_notes_summary.by_kind.items() if v > 0}
+        if by_kind:
+            signals["code_notes"] = {"total": sm.code_notes_summary.total, "by_kind": by_kind}
+        if sm.code_notes_summary.adr_count > 0:
+            signals["adrs"] = sm.code_notes_summary.adr_count
+
+    has_tests = any(
+        "/test" in p or "/tests" in p or "/spec" in p or p.startswith("test")
+        for p in sm.file_paths
+    )
+    if has_tests:
+        signals["has_tests"] = True
+
+    if signals:
+        result["signals"] = signals
+
+    # ── 6. Gaps — what's uncertain or missing ────────────────────────────────
+    gaps: list[str] = []
+
+    if not sm.entry_points:
+        gaps.append("No entry point detected — project structure may be non-standard")
+
+    if primary and primary.confidence == "low":
+        gaps.append(f"Low-confidence stack detection for '{primary.stack}' — no manifest found")
+
+    heuristic_stacks = [s for s in sm.stacks if s.detection_method == "heuristic"]
+    if heuristic_stacks:
+        gaps.append(
+            f"Heuristic-only detection (no manifest): {', '.join(s.stack for s in heuristic_stacks)}"
+        )
+
+    if sm.dependency_summary and sm.dependency_summary.requested:
+        for limitation in sm.dependency_summary.limitations[:3]:
+            gaps.append(limitation)
+    elif not sm.dependency_summary or not sm.dependency_summary.requested:
+        gaps.append("Dependencies not analyzed — add --dependencies for full context")
+
+    if gaps:
+        result["gaps"] = gaps
+
+    return result
+
+
+def standard_view(sm: SourceMap, *, include_tree: bool = False) -> dict[str, Any]:
+    """Default output — three signal layers.
+
+    Layer A (always):
+        metadata, project_type, project_summary, architecture_summary,
+        stacks, entry_points.
+
+    Layer B (when the corresponding flag was passed):
+        dependency_summary + key_dependencies, env_summary + env_map,
+        code_notes_summary + code_notes, git_context.
+
+    Layer C (only when the flag was explicitly passed, checked via *.requested):
+        module_graph, docs, semantic_*, file_metrics, architecture inference.
+
+    file_tree / file_paths only when include_tree=True.
+    Full dependencies list is never included — use key_dependencies instead.
+    Empty unrequested analyzer fields are omitted entirely.
+    """
+    result: dict[str, Any] = {
+        "metadata": asdict(sm.metadata),
+        "project_type": sm.project_type,
+        "project_summary": sm.project_summary,
+        "architecture_summary": sm.architecture_summary,
+        "stacks": [asdict(s) for s in sm.stacks],
+        "entry_points": [asdict(ep) for ep in sm.entry_points],
+    }
+
+    # Layer B — signals (only when the corresponding analyzer ran)
+    if sm.dependency_summary is not None and sm.dependency_summary.requested:
+        dep_dict = asdict(sm.dependency_summary)
+        dep_dict.pop("dependencies", None)  # avoid duplication with key_dependencies
+        result["dependency_summary"] = dep_dict
+        result["key_dependencies"] = [asdict(d) for d in sm.key_dependencies]
+
+    if sm.env_summary is not None and sm.env_summary.requested:
+        result["env_summary"] = asdict(sm.env_summary)
+        result["env_map"] = [asdict(e) for e in sm.env_map]
+
+    if sm.code_notes_summary is not None and sm.code_notes_summary.requested:
+        result["code_notes_summary"] = asdict(sm.code_notes_summary)
+        if sm.code_notes:
+            result["code_notes"] = [asdict(n) for n in sm.code_notes]
+        if sm.code_adrs:
+            result["code_adrs"] = [asdict(a) for a in sm.code_adrs]
+
+    if sm.git_context is not None and sm.git_context.requested:
+        result["git_context"] = asdict(sm.git_context)
+
+    # Layer C — deep-dive (flag must have been explicitly passed)
+    if sm.module_graph is not None and sm.module_graph.summary.requested:
+        result["module_graph"] = asdict(sm.module_graph)
+        result["module_graph_summary"] = asdict(sm.module_graph.summary)
+
+    if sm.doc_summary is not None and sm.doc_summary.requested:
+        result["doc_summary"] = asdict(sm.doc_summary)
+        result["docs"] = [asdict(d) for d in sm.docs]
+
+    if sm.semantic_summary is not None and sm.semantic_summary.requested:
+        result["semantic_summary"] = asdict(sm.semantic_summary)
+        result["semantic_calls"] = [asdict(c) for c in sm.semantic_calls]
+        result["semantic_symbols"] = [asdict(s) for s in sm.semantic_symbols]
+        result["semantic_links"] = [asdict(lnk) for lnk in sm.semantic_links]
+
+    if sm.metrics_summary is not None and sm.metrics_summary.requested:
+        result["metrics_summary"] = asdict(sm.metrics_summary)
+        result["file_metrics"] = [asdict(m) for m in sm.file_metrics]
+
+    if sm.architecture is not None and sm.architecture.requested:
+        result["architecture"] = asdict(sm.architecture)
+
+    if include_tree:
+        result["file_tree"] = sm.file_tree
+        result["file_paths"] = sm.file_paths
+
+    return result
+
+
 def write_output(content: str, output: Optional[Path]) -> None:
     """Escribe el contenido a stdout o a un fichero.
 

sourcecode/summarizer.py

@@ -174,29 +174,44 @@ class ProjectSummarizer:
             return None
         return " ".join(lines).strip()
 
+    _TYPE_LABELS: dict[str, str] = {
+        "cli": "CLI",
+        "api": "API",
+        "webapp": "Aplicación web",
+        "library": "Librería",
+        "monorepo": "Monorepo",
+        "fullstack": "Proyecto fullstack",
+    }
+
     def _merge_description_with_structure(self, description: str, sm: SourceMap) -> str:
-        parts = [description.rstrip(".")]
+        project_type = sm.project_type or ""
+        type_label = self._TYPE_LABELS.get(project_type, "")
 
-        arch_pattern = self._detect_architecture_pattern(sm.file_paths)
-        domains = self._extract_business_domains(sm.file_paths)
+        desc = description.rstrip(".")
+        # Prepend type label when description doesn't already open with it
+        if type_label and not desc.upper().startswith(type_label.upper()):
+            lead = f"{type_label}: {desc}" if desc else type_label
+        else:
+            lead = desc
 
+        parts = [lead]
+
+        # Stack with frameworks — keep brief, skip internal module listings
         non_tooling_stacks = self._filter_non_tooling_stacks(sm)
         if non_tooling_stacks:
             primary = self._select_summary_primary_stack(non_tooling_stacks)
             frameworks = [fw.name for fw in primary.frameworks[:2]]
-            stack_label = primary.stack.capitalize()
+            arch_pattern = self._detect_architecture_pattern(sm.file_paths)
             arch_str = f" con arquitectura {arch_pattern}" if arch_pattern else ""
             if frameworks:
-                parts.append(f"Stack: {stack_label} ({', '.join(frameworks)}){arch_str}")
+                parts.append(f"Stack: {primary.stack.capitalize()} ({', '.join(frameworks)}){arch_str}")
             else:
-                parts.append(f"Stack: {stack_label}{arch_str}")
+                parts.append(f"Stack: {primary.stack.capitalize()}{arch_str}")
 
+        # Business domains only — skip entry_points (too technical for product summary)
+        domains = self._extract_business_domains(sm.file_paths)
         if domains:
             parts.append(f"Dominios: {', '.join(domains)}")
-        else:
-            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)}")
 
         return ". ".join(parts) + "."
 

sourcecode/tree_utils.py

@@ -14,6 +14,20 @@ def flatten_file_tree(file_tree: dict[str, Any], prefix: str = "") -> list[str]:
     return paths
 
 
+def find_files_by_name(
+    file_tree: dict[str, Any], filename: str, prefix: str = ""
+) -> list[str]:
+    """Return all paths in the tree whose filename matches `filename`."""
+    paths: list[str] = []
+    for key, value in file_tree.items():
+        current = f"{prefix}/{key}" if prefix else key
+        if isinstance(value, dict):
+            paths.extend(find_files_by_name(value, filename, current))
+        elif key == filename:
+            paths.append(current)
+    return paths
+
+
 def path_exists_in_tree(file_tree: dict[str, Any], target: str) -> bool:
     """Comprueba si un path relativo existe en el file_tree."""
     normalized = target.strip("/").split("/")

{sourcecode-0.21.0.dist-info → sourcecode-0.22.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 0.21.0
+Version: 0.22.0
 Summary: Genera un mapa de contexto estructurado de proyectos de software para agentes IA
 License: MIT
 Requires-Python: >=3.9

{sourcecode-0.21.0.dist-info → sourcecode-0.22.0.dist-info}/RECORD

@@ -1,11 +1,11 @@
-sourcecode/__init__.py,sha256=Wl0aL5XpGhZsWRJOan0FtriAIMa21IHgxlCXLjVcxOI,100
+sourcecode/__init__.py,sha256=fj7lPtxQ0hLFlBv6uWwpvAPQdgoXjKNjaM1Tpn2SFKg,100
 sourcecode/architecture_analyzer.py,sha256=zxgqeqn2FhIUDn06X-whjGKiXbrHFkRlzZcr2zKd0Gw,16874
-sourcecode/architecture_summary.py,sha256=r9IciS9z-7h8xpiME7DKBLhLV36xzXtSzbZ1cRDWklo,11709
-sourcecode/classifier.py,sha256=fcp2wIq198wq3Rsh_bDmZIK_W5UI6FEL5oqm1RrQfpA,6846
-sourcecode/cli.py,sha256=1ozxlC43rd2boOZbARb3l2csVpTFiBw8DRDzCtLywTI,29065
+sourcecode/architecture_summary.py,sha256=rr-Q2LLe6bXZ27NuV2pYb0_LZyEFn3sngKMdXCZSGbE,13263
+sourcecode/classifier.py,sha256=Ft_RfYS-KOe0t7vjgUx04OoCJd1-DXK7k9-I0CFDSnU,6934
+sourcecode/cli.py,sha256=x_ZjTyy9IaBqCFXOLxwTvopB3OeHVCv2mk1s1E2Hc_g,29446
 sourcecode/code_notes_analyzer.py,sha256=rRd8bFYV0krjlxxQV0wenwE9K7pVpUQSR7KvSvUQKw4,9226
 sourcecode/coverage_parser.py,sha256=q0LeZJaX1bnntLu-ImksdBsMlpsVmk_iUfSaB4eaJGo,19702
-sourcecode/dependency_analyzer.py,sha256=2TYBIpenhfWf_TVBZZfq3T0SHFv8xCKFIyn1XnFHG6s,48146
+sourcecode/dependency_analyzer.py,sha256=C-G2paetrBUCMTA2KlWrD04fl9Y4q75sk4X0M0utzpE,50863
 sourcecode/doc_analyzer.py,sha256=Ec3orx6vBKsh5cNM3-F4y2Got2KuKx8w3dErwtdtM-A,19891
 sourcecode/env_analyzer.py,sha256=JZxBOuIxnM0xw0IaJFL6LiPJBErL848L3XoTOHGBqZI,13554
 sourcecode/git_analyzer.py,sha256=S9PGt8RDasBQYQUsZh9-H_KWVlPvzwR4jgM7TKN9ZCk,7643
@@ -13,33 +13,33 @@ sourcecode/graph_analyzer.py,sha256=cxl7Xb88aGxIVOCsatZJAE1CtgXGzIbJfqytV-9kkFs,
 sourcecode/metrics_analyzer.py,sha256=4uh11v-Q0gdrN87BOxuFWUym3N3AOkOuy21K5N8peB8,20126
 sourcecode/prepare_context.py,sha256=yPRohYZ3wvX156GQSo1vYuoCDBIG3uy3G-3DdNbGHKU,19271
 sourcecode/redactor.py,sha256=xuGcadGEHaPw4qZXlMDvzMCsr4VOkdp3oBQptHyJk8c,2884
-sourcecode/scanner.py,sha256=Ga4jDRAOhkcwlRmlE2ko6cE39qKy0aI4iE1lGBWmAlk,6410
-sourcecode/schema.py,sha256=dnNdnQxJtBv0PRVWi6-xnpr16dj6IsUGbso9PeeEolA,15743
+sourcecode/scanner.py,sha256=aM3h9-DCQ3xKpeHpHYdo2vX6T5P95HA_YwZbkAVNwmo,8288
+sourcecode/schema.py,sha256=YJhzdn5C9_S1OPWoMgn7gdtY9jgWfiESN-m9znBTjIg,15833
 sourcecode/semantic_analyzer.py,sha256=asQfJf-EhzYaOTA-iMuZsrVXtbW7SV2WEKCxgsxa88Y,79413
-sourcecode/serializer.py,sha256=ck0gK3PV-rY5UrAvykKh8x56Lb1135J23xzbcEsvUW8,13772
-sourcecode/summarizer.py,sha256=2Yz5xJ1bhtJLlrUpKcd74wijypRRo9GJmGT8u971EW0,11572
-sourcecode/tree_utils.py,sha256=xla45Whq24j6U9kEgTztJXkMpmOEDieAulKxP3nl89s,935
+sourcecode/serializer.py,sha256=Yqn-AOZL0kSFwfY0U72yOvVuYi7quPjyq6xXHbW_vc0,22462
+sourcecode/summarizer.py,sha256=YdIA5gGEc0XSctPgmTnFnuZI72bprrOYhkJNoDmvHwM,12114
+sourcecode/tree_utils.py,sha256=Fj9OIuUksBvgibNd3feog0sMDjVypJzPexp5lvMoYWI,1424
 sourcecode/workspace.py,sha256=fQlVoNx8S-fSHpKoJ0JBvEHCFkxszH0KZVJed1i3TRk,6845
 sourcecode/detectors/__init__.py,sha256=A0AACJFF6HWf_RgatNtWu3PUzstcKtIGM9f1PoFcJug,1987
-sourcecode/detectors/base.py,sha256=0juJTZO8Krtphg8V00n_2xhsaoY6nP-EW-OAZCzm9Js,1019
+sourcecode/detectors/base.py,sha256=C2EqfZudQ1ITK4DID4M70nPxqoh9bl1zn_ta6XRaGWs,1168
 sourcecode/detectors/dart.py,sha256=QbqaL5v18-_ort75HihVBt8MsKUfOcFDF8IpWFLiXpI,1432
 sourcecode/detectors/dotnet.py,sha256=UC-74VW850r3admcl36R-rl3M0-nBFXw8ph5e9RSas8,1978
 sourcecode/detectors/elixir.py,sha256=jCpvt5Yi6jvplc80ovRtWh17q-11ZGo9qX7o8b57TJE,1713
 sourcecode/detectors/go.py,sha256=KehAyvC3H_s8zwwqFM0bAbztQbbUBDjpNbGvM2kQlk8,1836
-sourcecode/detectors/heuristic.py,sha256=GvniuNzeCOzmKyY5Sd88_bmBnVrJE5O9cbs4NoEPBKY,1891
+sourcecode/detectors/heuristic.py,sha256=253JB1iD0IXC72AdGRivQtZNgGziyOJOJrJeztOzdJs,1953
 sourcecode/detectors/java.py,sha256=qFVpMy5mu490ENhutO1LV2Gidms4ZZUfNX5Qv5Qxh2I,7188
 sourcecode/detectors/jvm_ext.py,sha256=EgHJ5W8EE-ZTN9V607mVzohyKgZE8Mc2jCi-DF8RAZU,2616
-sourcecode/detectors/nodejs.py,sha256=cCK50aY7RERQUQ7FK2UmqVTVFAW3VksDxN6rYADtsC0,4498
+sourcecode/detectors/nodejs.py,sha256=qNJ1m0E_TsPiR_iNcSgK4igb4mm99h-HDKE7C8gME6o,4762
 sourcecode/detectors/parsers.py,sha256=ugPg8yNUf0Ai1gA7Fnn6wAkYGFjTxRodSP3IeViYJJ4,2290
 sourcecode/detectors/php.py,sha256=W_AQD0WMVDdWHa9h_ilX6W8XSpz0X4ctpMK2WXfXf1I,1887
-sourcecode/detectors/project.py,sha256=26q8aIDam0Wo96F9DIIsdOW9X9Msg6sONj5c00bpD2M,5973
-sourcecode/detectors/python.py,sha256=NfQY6KXpJWCeHk-8JP4Gmump_6b4yprYDP_VLfu-Ghw,7678
+sourcecode/detectors/project.py,sha256=YCynNC8drJutPMiDGPutlYaL49IO8M-1Ms_RwVY09ss,6221
+sourcecode/detectors/python.py,sha256=EGhHxvgjSVAZujOswdrK7awuKj79bfYRKXI38pqpJs8,9504
 sourcecode/detectors/ruby.py,sha256=Q4B5ePAw6-T4DLfanKJiuLHLqUigTPVrzylcXJMei3M,1591
 sourcecode/detectors/rust.py,sha256=V23NO6Y8NsrhrUlGC2feUEcNK63hf3gc1y3jI4tes1Q,2264
 sourcecode/detectors/systems.py,sha256=nYaKbGDFu0EOXFcd_1doWFT3tTUdkbxc2DjHUF5TcqQ,1627
 sourcecode/detectors/terraform.py,sha256=cxORPR_zVLOJpHlh4e9JnFpkQsn_UnqMMom5yG65hZ4,1693
 sourcecode/detectors/tooling.py,sha256=hIvop80No22pqyGVJ32NKliSdjkHRePQkIRroqG01bY,1875
-sourcecode-0.21.0.dist-info/METADATA,sha256=9gqiONC_cEbjYwoYox60Dx-2m8qzP3KwkNRqU8kis88,30326
-sourcecode-0.21.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-0.21.0.dist-info/entry_points.txt,sha256=voDtdlGU2-jR3wCZpQoOls_0eUKaDVCKIfajGHFDATs,50
-sourcecode-0.21.0.dist-info/RECORD,,
+sourcecode-0.22.0.dist-info/METADATA,sha256=R7dNRAnWzgeRSNAnDT78YOaThzkojXX0eKZXkyVD6Pw,30326
+sourcecode-0.22.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-0.22.0.dist-info/entry_points.txt,sha256=voDtdlGU2-jR3wCZpQoOls_0eUKaDVCKIfajGHFDATs,50
+sourcecode-0.22.0.dist-info/RECORD,,