sourcecode 0.15.1__py3-none-any.whl → 0.17.0__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/architecture_analyzer.py

@@ -33,6 +33,37 @@ _CODE_EXTENSIONS = {
 }
 _GENERIC_NAMES = {"utils", "helpers", "common", "shared", "misc", "core", "root", ""}
 
+_TEST_DIRS: frozenset[str] = frozenset({"tests", "test", "spec", "specs", "__tests__", "e2e"})
+
+# Exact file stems that signal a specific architectural layer
+_LAYER_STEM_EXACT: dict[str, str] = {
+    "cli":      "orchestration",
+    "main":     "orchestration",
+    "app":      "orchestration",
+    "server":   "orchestration",
+    "schema":   "data",
+    "model":    "data",
+    "models":   "data",
+    "config":   "data",
+    "settings": "data",
+    "store":    "data",
+}
+
+# Suffix patterns (stem == suffix OR stem ends with "_" + suffix) → layer
+_LAYER_STEM_SUFFIXES: list[tuple[str, str]] = [
+    ("analyzer",   "processing"),
+    ("processor",  "processing"),
+    ("parser",     "processing"),
+    ("detector",   "processing"),
+    ("scanner",    "processing"),
+    ("handler",    "orchestration"),
+    ("controller", "orchestration"),
+    ("repository", "data"),
+    ("repo",       "data"),
+    ("serializer", "data"),
+    ("formatter",  "data"),
+]
+
 DOMAIN_ROLES: dict[str, str] = {
     "controllers": "HTTP request handlers",
     "handlers":    "HTTP request handlers",
@@ -120,8 +151,9 @@ class ArchitectureAnalyzer:
 
         # Overall confidence
         confidence: Literal["high", "medium", "low"]
-        if len(domains) >= 3 and pattern not in (None, "unknown"):
-            confidence = "high"
+        if pattern not in (None, "unknown", "flat"):
+            # A recognised pattern was detected — at least medium confidence
+            confidence = "high" if len(domains) >= 3 else "medium"
         elif len(domains) >= 1:
             confidence = "medium"
         else:
@@ -165,7 +197,13 @@ class ArchitectureAnalyzer:
         if len(parts) == 1:
             return "root"
         first = parts[0]
-        if first in _SRC_TRANSPARENT and len(parts) >= 3:
+        if first in _SRC_TRANSPARENT:
+            if len(parts) == 2:
+                return "root"
+            if len(parts) >= 4:
+                # src/pkg/subpkg/file.py → subpkg is the meaningful module
+                return parts[2]
+            # src/pkg/file.py → pkg
             return parts[1]
         return first
 
@@ -173,6 +211,8 @@ class ArchitectureAnalyzer:
         groups: dict[str, list[str]] = {}
         for p in paths:
             seg = self._extract_domain_segment(p)
+            if seg.lower() in _TEST_DIRS:
+                continue  # tests are infrastructure, not architecture domains
             groups.setdefault(seg, []).append(p)
 
         domains: list[ArchitectureDomain] = []
@@ -191,12 +231,21 @@ class ArchitectureAnalyzer:
         return domains
 
     def _detect_layers(self, paths: list[str]) -> tuple[str, list[ArchitectureLayer]]:
+        # Exclude test paths so test directories don't skew layer scoring
+        source_paths = [
+            p for p in paths
+            if not any(part.lower() in _TEST_DIRS for part in p.replace("\\", "/").split("/"))
+        ]
+        if not source_paths:
+            return "unknown", []
+
         dir_names: set[str] = set()
-        for p in paths:
+        for p in source_paths:
             parts = p.replace("\\", "/").split("/")
             for part in parts[:-1]:
                 dir_names.add(part.lower())
 
+        # 1. Classical keyword-based pattern matching (MVC, layered, hexagonal, fullstack)
         best_pattern = ""
         best_score = 0
         best_matched: dict[str, list[str]] = {}
@@ -213,34 +262,96 @@ class ArchitectureAnalyzer:
                 best_pattern = pattern_name
                 best_matched = matched
 
-        if best_score < 2:
-            # Check depth for flat vs unknown
-            max_depth = max(
-                len(p.replace("\\", "/").split("/")) - 1
-                for p in paths
-            )
-            flat_pattern = "flat" if max_depth <= 2 else "unknown"
-            return flat_pattern, []
-
-        # Build ArchitectureLayer list
-        layer_confidence: Literal["high", "medium", "low"] = "high" if best_score >= 3 else "medium"
-        layers: list[ArchitectureLayer] = []
-        for layer_key, matched_dirs in best_matched.items():
-            matched_files = [
-                p for p in paths
-                if any(
-                    seg.lower() in matched_dirs
-                    for seg in p.replace("\\", "/").split("/")[:-1]
-                )
+        if best_score >= 2:
+            layer_confidence: Literal["high", "medium", "low"] = "high" if best_score >= 3 else "medium"
+            layers: list[ArchitectureLayer] = []
+            for layer_key, matched_dirs in best_matched.items():
+                matched_files = [
+                    p for p in source_paths
+                    if any(
+                        seg.lower() in matched_dirs
+                        for seg in p.replace("\\", "/").split("/")[:-1]
+                    )
+                ]
+                layers.append(ArchitectureLayer(
+                    name=layer_key,
+                    pattern=best_pattern,
+                    files=matched_files,
+                    confidence=layer_confidence,
+                ))
+            return best_pattern, layers
+
+        # 2. Functional file-naming heuristic: *_analyzer.py, cli.py, schema.py, …
+        func_result = self._detect_layered_functional(source_paths)
+        if func_result is not None:
+            return func_result
+
+        # 3. Modular sub-package heuristic: ≥2 distinct named sub-packages
+        modular_result = self._detect_modular(source_paths)
+        if modular_result is not None:
+            return modular_result
+
+        # 4. Fallback: flat (shallow) vs truly unknown (deep but unrecognised)
+        max_depth = max(
+            (len(p.replace("\\", "/").split("/")) - 1 for p in source_paths),
+            default=0,
+        )
+        return ("flat" if max_depth <= 2 else "unknown"), []
+
+    def _detect_layered_functional(
+        self, paths: list[str]
+    ) -> Optional[tuple[str, list[ArchitectureLayer]]]:
+        """Detect layered architecture from file-naming conventions.
+
+        Recognises three logical layers without requiring classical directory names:
+        - orchestration: cli.py, main.py, *_handler.py, *_controller.py
+        - processing:    *_analyzer.py, *_processor.py, *_parser.py, *_detector.py, *_scanner.py
+        - data:          schema.py, model.py, *_repository.py, *_serializer.py, config.py, …
+        """
+        layer_files: dict[str, list[str]] = {"orchestration": [], "processing": [], "data": []}
+        for p in paths:
+            stem = Path(p.replace("\\", "/").split("/")[-1]).stem.lower()
+            if stem in _LAYER_STEM_EXACT:
+                layer_files[_LAYER_STEM_EXACT[stem]].append(p)
+                continue
+            for suffix, layer in _LAYER_STEM_SUFFIXES:
+                if stem == suffix or stem.endswith("_" + suffix):
+                    layer_files[layer].append(p)
+                    break
+
+        non_empty = {k: v for k, v in layer_files.items() if v}
+        if len(non_empty) >= 2:
+            return "layered", [
+                ArchitectureLayer(name=k, pattern="layered", files=v, confidence="medium")
+                for k, v in non_empty.items()
             ]
-            layers.append(ArchitectureLayer(
-                name=layer_key,
-                pattern=best_pattern,
-                files=matched_files,
-                confidence=layer_confidence,
-            ))
+        return None
+
+    def _detect_modular(
+        self, paths: list[str]
+    ) -> Optional[tuple[str, list[ArchitectureLayer]]]:
+        """Detect modular architecture from ≥2 distinct named sub-packages.
 
-        return best_pattern or "unknown", layers
+        Each top-level (or first non-transparent) directory that is not a test or
+        generic name is treated as a self-contained module.
+        """
+        module_files: dict[str, list[str]] = {}
+        for p in paths:
+            parts = p.replace("\\", "/").split("/")
+            for part in parts[:-1]:
+                if (part not in _SRC_TRANSPARENT
+                        and part.lower() not in _TEST_DIRS
+                        and part.lower() not in _GENERIC_NAMES):
+                    module_files.setdefault(part, []).append(p)
+                    break
+
+        meaningful = {k: v for k, v in module_files.items() if len(v) >= 2}
+        if len(meaningful) >= 2:
+            return "modular", [
+                ArchitectureLayer(name=k, pattern="modular", files=v, confidence="medium")
+                for k, v in meaningful.items()
+            ]
+        return None
 
     def _infer_bounded_contexts(
         self,

sourcecode/architecture_summary.py

@@ -12,6 +12,7 @@ _TOOLING_PREFIXES = (".claude/", ".vscode/", "bin/")
 _PYTHON_EXTENSIONS = {".py"}
 _NODE_EXTENSIONS = {".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"}
 _GO_EXTENSIONS = {".go"}
+_JAVA_EXTENSIONS = {".java", ".kt", ".scala"}
 
 
 class ArchitectureSummarizer:
@@ -58,6 +59,8 @@ class ArchitectureSummarizer:
             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))
+        elif suffix in _JAVA_EXTENSIONS:
+            lines.extend(self._summarize_java_entry(entry_point.path, content, sm.stacks))
         else:
             lines.append("Orquesta modulos internos no detallados por el analisis estatico disponible.")
 
@@ -122,6 +125,21 @@ class ArchitectureSummarizer:
         lines.append("Produce la salida principal del entry point JavaScript/TypeScript detectado.")
         return lines
 
+    def _summarize_java_entry(self, path: str, content: str, stacks: list[StackDetection]) -> list[str]:
+        lines: list[str] = []
+        frameworks = [f.name for stack in stacks for f in stack.frameworks]
+        if frameworks:
+            lines.append(f"Frameworks detectados: {', '.join(frameworks)}.")
+        annotations = re.findall(r"@(SpringBootApplication|QuarkusMain|MicronautApplication|Application)\b", content)
+        if annotations:
+            lines.append(f"Anotacion de arranque: @{annotations[0]}.")
+        # Detect Spring Boot profile hints
+        if "@SpringBootApplication" in content:
+            lines.append("Arranca el contexto de Spring con auto-configuracion y component scan.")
+        elif not lines:
+            lines.append("Orquesta el arranque de la aplicacion JVM.")
+        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"))]
@@ -196,6 +214,16 @@ class ArchitectureSummarizer:
                         confidence="medium",
                     )
                 )
+            elif path.endswith("Application.java") or path.endswith("Main.java"):
+                candidates.append(
+                    EntryPoint(
+                        path=path,
+                        stack="java",
+                        kind="application",
+                        source="convention",
+                        confidence="medium",
+                    )
+                )
         return candidates
 
     def _fallback_priority(self, path: str) -> tuple[int, int, str]:

sourcecode/cli.py

@@ -202,12 +202,26 @@ def main(
         SourceMap,
         StackDetection,
     )
-    from sourcecode.serializer import compact_view, write_output
+    from sourcecode.serializer import compact_view, normalize_source_map, validate_cross_analyzer_consistency, validate_source_map, write_output
     from sourcecode.workspace import WorkspaceAnalyzer
 
     # 1. Escanear el directorio (SCAN-01 a SCAN-05)
     redactor = SecretRedactor(enabled=not no_redact)
-    scanner = FileScanner(target, max_depth=depth)
+
+    # Detectar manifests antes del scan para ajustar depth.
+    # find_manifests() solo mira profundidad 0-1, no necesita el arbol.
+    _pre_scanner = FileScanner(target, max_depth=1)
+    manifests = _pre_scanner.find_manifests()
+
+    # Maven usa src/main/java/<groupId>/<artifactId>/<module>/ (profundidad 7+).
+    # Con depth=4 los ficheros .java son invisibles y todos los analizadores fallan.
+    # Necesitamos al menos 8: src(1)+main(2)+java(3)+com(4)+co(5)+app(6)+module(7)+file.
+    _java_manifest_names = {"pom.xml", "build.gradle", "build.gradle.kts"}
+    _is_java = any(Path(m).name in _java_manifest_names for m in manifests)
+    _java_min_depth = 8
+    effective_depth = max(depth, _java_min_depth) if _is_java and depth < _java_min_depth else depth
+
+    scanner = FileScanner(target, max_depth=effective_depth)
     raw_tree = scanner.scan_tree()
 
     # 2. Filtrar del arbol las entradas de .env y *.secret (SEC-02, todos los niveles)
@@ -244,7 +258,6 @@ def main(
         return pruned
 
     file_tree = filter_sensitive_files(raw_tree)
-    manifests = scanner.find_manifests()
     detector = ProjectDetector(build_default_detectors())
     workspace_analysis = WorkspaceAnalyzer().analyze(target, manifests)
     dependency_analyzer = DependencyAnalyzer() if dependencies else None
@@ -557,6 +570,20 @@ def main(
         cn_notes, cn_adrs, cn_summary = CodeNotesAnalyzer().analyze(target)
         sm = replace(sm, code_notes=cn_notes, code_adrs=cn_adrs, code_notes_summary=cn_summary)
 
+    # Normalize optional analyzer outputs → validate schema contracts.
+    # normalize_source_map fills None fields with typed empty defaults so that
+    # consumers never need to null-check architecture or module_graph.
+    # validate_source_map then asserts the contracts hold; it raises here
+    # (pre-serialization) rather than silently producing invalid JSON.
+    sm = normalize_source_map(sm)
+    validate_source_map(sm)
+
+    # Cross-analyzer semantic consistency (non-blocking: warnings to stderr).
+    # strict=False so a mismatched dependency or orphan semantic link never
+    # aborts a run — findings are informational until the team decides to harden.
+    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:
         data = compact_view(sm)

sourcecode/code_notes_analyzer.py

@@ -5,6 +5,11 @@ from collections import Counter
 from pathlib import Path
 from typing import Optional
 
+# Schema imports are hoisted here (not lazily inside _scan_source_file) so that
+# a stale .pyc / editable-install mismatch is caught at import time rather than
+# silently dropping notes mid-scan on the first failed late-import.
+from sourcecode.schema import AdrRecord, CodeNote, CodeNotesSummary
+
 _MAX_NOTES = 500
 _MAX_NOTES_PER_FILE = 30
 _MAX_ADRS = 50
@@ -103,7 +108,6 @@ def _scan_source_file(
         line_num = content.count("\n", 0, m.start()) + 1
         symbol = _find_nearby_symbol(lines, line_num - 1)
 
-        from sourcecode.schema import CodeNote
         notes.append(CodeNote(
             kind=kind,
             path=rel_path,
@@ -121,8 +125,6 @@ def _parse_adr(path: Path, rel_path: str) -> Optional[object]:
     except OSError:
         return None
 
-    from sourcecode.schema import AdrRecord
-
     title: Optional[str] = None
     status: Optional[str] = None
     summary_lines: list[str] = []
@@ -167,15 +169,13 @@ def _parse_adr(path: Path, rel_path: str) -> Optional[object]:
     if not title:
         title = path.stem
 
-    return AdrRecord(path=rel_path, title=title, status=status, summary=summary)
+    return AdrRecord(path=rel_path, title=title, status=status, summary=summary)  # noqa: RET504
 
 
 class CodeNotesAnalyzer:
     """Extrae notas de código (TODO/FIXME/HACK/etc.) y ADRs del proyecto."""
 
     def analyze(self, root: Path) -> tuple[list, list, object]:
-        from sourcecode.schema import CodeNotesSummary
-
         notes: list = []
         adrs: list = []
         limitations: list[str] = []
@@ -186,9 +186,19 @@ class CodeNotesAnalyzer:
         if total_count[0] >= _MAX_NOTES:
             limitations.append(f"notes_truncated_at:{_MAX_NOTES}")
 
+        # Explicit canonical sort guarantees identical output for identical input
+        # regardless of filesystem traversal order or OS/platform differences.
+        # Without this, output order depended on sorted(Path.iterdir()) which
+        # varies across Python versions, APFS vs ext4, and future walk refactors.
+        notes.sort(key=lambda n: (n.path, n.line))
+        adrs.sort(key=lambda a: a.path)
+
         kind_counts: Counter = Counter(n.kind for n in notes)
         file_counts: Counter = Counter(n.path for n in notes)
-        top_files = [f for f, _ in file_counts.most_common(5)]
+        # Secondary sort by path makes top_files stable when counts are tied.
+        top_files = [
+            f for f, _ in sorted(file_counts.items(), key=lambda x: (-x[1], x[0]))[:5]
+        ]
 
         summary = CodeNotesSummary(
             requested=True,
@@ -211,7 +221,10 @@ class CodeNotesAnalyzer:
     ) -> None:
         try:
             entries = sorted(current.iterdir())
-        except PermissionError:
+        except OSError:
+            # Catches PermissionError, EMFILE (too many open files), and other
+            # OS-level errors that previously aborted the entire walk mid-scan,
+            # returning an empty or partial list depending on when the error hit.
             return
 
         for entry in entries:
@@ -237,5 +250,8 @@ class CodeNotesAnalyzer:
                                 adrs.append(adr)
                         continue
 
-                if suffix in _CODE_EXTENSIONS and total_count[0] < _MAX_NOTES:
+                # The quota check lives inside _scan_source_file; the pre-check
+                # here was redundant and caused files to be silently skipped when
+                # traversal order varied (different files filled the quota first).
+                if suffix in _CODE_EXTENSIONS:
                     _scan_source_file(entry, rel, notes, total_count)

sourcecode/dependency_analyzer.py

@@ -33,6 +33,7 @@ class DependencyAnalyzer:
             self._analyze_rust,
             self._analyze_go,
             self._analyze_dotnet,
+            self._analyze_java,
         ):
             handler_records, handler_limitations = handler(root)
             records.extend(replace(record, workspace=workspace) for record in handler_records)
@@ -920,6 +921,50 @@ class DependencyAnalyzer:
                 result.append(resolved)
         return self._dedupe(result)
 
+    def _analyze_java(self, root: Path) -> tuple[list[DependencyRecord], list[str]]:
+        pom = root / "pom.xml"
+        if not pom.exists():
+            return [], []
+        try:
+            tree = ET.parse(pom)
+        except (ET.ParseError, OSError):
+            return [], ["java: error al parsear pom.xml"]
+
+        root_elem = tree.getroot()
+        ns_match = re.match(r"\{[^}]+\}", root_elem.tag)
+        ns = ns_match.group(0) if ns_match else ""
+
+        records: list[DependencyRecord] = []
+        deps_elem = root_elem.find(f"{ns}dependencies")
+        if deps_elem is None:
+            return [], ["java: pom.xml sin bloque <dependencies>"]
+
+        for dep in deps_elem.findall(f"{ns}dependency"):
+            group_id = (dep.findtext(f"{ns}groupId") or "").strip()
+            artifact_id = (dep.findtext(f"{ns}artifactId") or "").strip()
+            if not group_id or not artifact_id:
+                continue
+            version_raw = (dep.findtext(f"{ns}version") or "").strip() or None
+            # Versiones interpoladas con propiedades Maven (${...}) no son resolvibles estáticamente
+            declared = version_raw if version_raw and not version_raw.startswith("${") else None
+            scope_text = (dep.findtext(f"{ns}scope") or "compile").strip().lower()
+            scope = "dev" if scope_text == "test" else "direct"
+            records.append(
+                DependencyRecord(
+                    name=f"{group_id}:{artifact_id}",
+                    ecosystem="java",
+                    scope=scope,
+                    declared_version=declared,
+                    source="manifest",
+                    manifest_path="pom.xml",
+                )
+            )
+
+        limitations: list[str] = []
+        if not records:
+            limitations.append("java: pom.xml sin dependencias parseables (puede usar BOM o propiedades)")
+        return records, limitations
+
     def _load_yaml_file(self, path: Path) -> Optional[dict[str, Any]]:
         if not path.exists():
             return None

sourcecode/scanner.py

@@ -128,6 +128,10 @@ class FileScanner:
 
             # Agregar ficheros al nodo (null = fichero segun D-02)
             for fname in filenames:
+                # Skip flag-shaped names (e.g. "-o", "--format") — shell redirect artifacts.
+                # No legitimate source file starts with "-".
+                if fname.startswith("-"):
+                    continue
                 fpath = current / fname
                 # SCAN-03: no incluir symlinks de fichero
                 if fpath.is_symlink():

sourcecode/serializer.py

@@ -10,12 +10,17 @@ Patrones criticos:
 
 import json
 import sys
-from dataclasses import asdict, is_dataclass
+from dataclasses import asdict, dataclass, is_dataclass, replace
 from io import StringIO
 from pathlib import Path
 from typing import Any, Optional
 
-from sourcecode.schema import SourceMap
+from sourcecode.schema import (
+    ArchitectureAnalysis,
+    ModuleGraph,
+    ModuleGraphSummary,
+    SourceMap,
+)
 
 
 def to_json(sm: SourceMap | dict[str, Any], indent: int = 2) -> str:
@@ -92,6 +97,246 @@ def compact_view(sm: SourceMap) -> dict[str, Any]:
     }
 
 
+def normalize_source_map(sm: SourceMap) -> SourceMap:
+    """Fill in typed empty defaults for optional analyzer fields.
+
+    Fields controlled by flags (--architecture, --graph-modules) are None when
+    the flag is absent.  Downstream consumers and tests then need null-checks
+    everywhere.  This layer converts None → a well-typed default so the output
+    schema is always structurally complete.
+
+    The ``requested=False`` sentinel on each default tells consumers the
+    analysis was not requested, without forcing them to branch on None.
+    """
+    changes: dict[str, Any] = {}
+
+    # architecture: always an ArchitectureAnalysis, never None
+    if sm.architecture is None:
+        changes["architecture"] = ArchitectureAnalysis(requested=False)
+
+    # module_graph: always a ModuleGraph (possibly empty), never None.
+    # module_graph_summary is kept in sync as a convenience field.
+    if sm.module_graph is None:
+        empty_graph = ModuleGraph(summary=ModuleGraphSummary(requested=False))
+        changes["module_graph"] = empty_graph
+        if sm.module_graph_summary is None:
+            changes["module_graph_summary"] = empty_graph.summary
+    elif sm.module_graph_summary is None:
+        # graph exists but summary was never set — sync it
+        changes["module_graph_summary"] = sm.module_graph.summary
+
+    # dependencies is already list[DependencyRecord] by default_factory, but
+    # guard against any future refactor that could accidentally set it to None
+    if sm.dependencies is None:  # type: ignore[comparison-overlap]
+        changes["dependencies"] = []
+
+    return replace(sm, **changes) if changes else sm
+
+
+def validate_source_map(sm: SourceMap) -> None:
+    """Assert structural schema contracts on a (already normalised) SourceMap.
+
+    Call this *after* normalize_source_map() so that the checks below catch
+    bugs in the normaliser itself or in code that bypasses it.
+
+    Raises:
+        ValueError: listing every violated contract, never just the first.
+    """
+    errors: list[str] = []
+
+    # --- architecture ---
+    if sm.architecture is None:
+        errors.append("architecture must not be null (call normalize_source_map first)")
+    else:
+        if not isinstance(sm.architecture.domains, list):
+            errors.append(
+                f"architecture.domains must be list, got {type(sm.architecture.domains).__name__}"
+            )
+        if sm.architecture.confidence not in ("high", "medium", "low"):
+            errors.append(
+                f"architecture.confidence must be high|medium|low, "
+                f"got {sm.architecture.confidence!r}"
+            )
+
+    # --- module_graph ---
+    if sm.module_graph is None:
+        errors.append("module_graph must not be null (call normalize_source_map first)")
+    else:
+        if not isinstance(sm.module_graph.nodes, list):
+            errors.append(
+                f"module_graph.nodes must be list, got {type(sm.module_graph.nodes).__name__}"
+            )
+        if not isinstance(sm.module_graph.edges, list):
+            errors.append(
+                f"module_graph.edges must be list, got {type(sm.module_graph.edges).__name__}"
+            )
+
+    # --- dependencies ---
+    if not isinstance(sm.dependencies, list):
+        errors.append(
+            f"dependencies must be list, got {type(sm.dependencies).__name__}"
+        )
+
+    if errors:
+        bullet = "\n  - "
+        raise ValueError(
+            f"SourceMap schema violations ({len(errors)}):{bullet}"
+            + bullet.join(errors)
+        )
+
+
+_GRAPH_CODE_EXTENSIONS: frozenset[str] = frozenset({
+    ".py", ".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs",
+    ".go", ".rs", ".java", ".kt", ".rb",
+})
+
+
+def _rule_dependency_graph(
+    sm: SourceMap,
+    known_paths: set[str],
+    findings: list[str],
+) -> None:
+    """Rule 1 — dependency/graph consistency.
+
+    Sub-rule 1a: every GraphNode whose path ends with a code extension must
+    exist in file_tree.  A mismatch means the graph references phantom files
+    the scanner never found.
+
+    Sub-rule 1b: if the graph has *external*-looking edge targets (package
+    names without path separators), every non-transitive dependency should
+    appear in those targets.  This rule is intentionally skipped when the
+    graph only tracks internal module-to-module edges, avoiding false
+    positives for projects whose graph_analyzer does not emit external imports.
+    """
+    if not sm.module_graph.summary.requested:
+        return
+
+    # 1a — graph node paths must be in file_tree
+    for node in sm.module_graph.nodes:
+        p = node.path
+        if Path(p).suffix.lower() in _GRAPH_CODE_EXTENSIONS and p not in known_paths:
+            findings.append(
+                f"[dependency_graph] graph node '{node.id}' path '{p}' "
+                f"not found in file_tree"
+            )
+
+    # 1b — dep names should appear in external-facing edge targets
+    if sm.dependency_summary is None or not sm.dependency_summary.requested:
+        return
+    if not sm.module_graph.edges:
+        return
+
+    # Only apply when the graph contains at least one package-like target
+    # (no path separator, no code extension) — signals external import tracking.
+    pkg_targets = {
+        e.target.lower()
+        for e in sm.module_graph.edges
+        if "/" not in e.target
+        and not Path(e.target).suffix.lower() in _GRAPH_CODE_EXTENSIONS
+    }
+    if not pkg_targets:
+        return  # graph has only internal file edges; dep↔edge check not applicable
+
+    for dep in sm.dependencies:
+        if dep.scope == "transitive":
+            continue
+        name = dep.name.lower().replace("-", "_")
+        if not any(name in t.replace("-", "_") for t in pkg_targets):
+            sample = ", ".join(sorted(pkg_targets)[:3])
+            findings.append(
+                f"[dependency_graph] dependency '{dep.name}' declared in manifest "
+                f"but absent from module_graph external edges (visible: {sample})"
+            )
+
+
+def _rule_semantic_file_tree(
+    sm: SourceMap,
+    known_paths: set[str],
+    findings: list[str],
+) -> None:
+    """Rule 2 — semantic_links paths must exist in file_tree.
+
+    Both the importer and the source (when not external) must be files the
+    scanner actually found.  An orphan path means the semantic_analyzer
+    resolved a symbol to a file that does not belong to the project.
+    """
+    for link in sm.semantic_links:
+        if link.importer_path not in known_paths:
+            findings.append(
+                f"[semantic_file_tree] semantic_link importer "
+                f"'{link.importer_path}' not in file_tree"
+            )
+        if link.source_path is not None and not link.is_external:
+            if link.source_path not in known_paths:
+                findings.append(
+                    f"[semantic_file_tree] semantic_link source "
+                    f"'{link.source_path}' not in file_tree (is_external=False)"
+                )
+
+
+def _rule_architecture_graph(
+    sm: SourceMap,
+    known_paths: set[str],
+    findings: list[str],
+) -> None:
+    """Rule 3 — architecture domain files must be a subset of file_tree.
+
+    The architecture_analyzer clusters files into domains.  Every file it
+    assigns to a domain should be a file the scanner found.  A mismatch
+    means the architecture_analyzer is referencing phantom paths, likely
+    from a stale file_paths list or a mis-configured root.
+    """
+    if not sm.architecture.requested:
+        return
+    for domain in sm.architecture.domains:
+        for path in domain.files:
+            if path not in known_paths:
+                findings.append(
+                    f"[architecture_graph] domain '{domain.name}' "
+                    f"references '{path}' not in file_tree"
+                )
+
+
+def validate_cross_analyzer_consistency(
+    sm: SourceMap,
+    *,
+    strict: bool = False,
+) -> list[str]:
+    """Check semantic alignment across analyzer outputs.
+
+    Applies three rules (see helpers above):
+      Rule 1 — dependency/graph: graph node paths and external edge targets
+               must be consistent with declared dependencies and file_tree.
+      Rule 2 — semantic/file_tree: SymbolLink paths must exist in file_tree.
+      Rule 3 — architecture/graph: domain files must exist in file_tree.
+
+    Args:
+        sm:     A SourceMap that has already been normalised and structurally
+                validated (call normalize_source_map + validate_source_map first).
+        strict: If True, raises ValueError listing all findings.
+                If False (default), returns the findings list so the caller
+                can log warnings without aborting the pipeline.
+
+    Returns:
+        List of human-readable finding strings (empty when all rules pass).
+    """
+    findings: list[str] = []
+    known = set(sm.file_paths)
+
+    _rule_dependency_graph(sm, known, findings)
+    _rule_semantic_file_tree(sm, known, findings)
+    _rule_architecture_graph(sm, known, findings)
+
+    if strict and findings:
+        bullet = "\n  - "
+        raise ValueError(
+            f"Cross-analyzer consistency violations ({len(findings)}):{bullet}"
+            + bullet.join(findings)
+        )
+
+    return findings
+
+
 def write_output(content: str, output: Optional[Path]) -> None:
     """Escribe el contenido a stdout o a un fichero.
 

{sourcecode-0.15.1.dist-info → sourcecode-0.17.0.dist-info}/METADATA

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

{sourcecode-0.15.1.dist-info → sourcecode-0.17.0.dist-info}/RECORD

@@ -1,11 +1,11 @@
-sourcecode/__init__.py,sha256=n-wyn6TNs_1x2XIHKzIOJuR_1TOoKl4bOn-vGS_HZV0,100
-sourcecode/architecture_analyzer.py,sha256=tGOoOpgYnjLuaMg3wobjhs_wvTphYhGoJwQ88rlj-qY,12171
-sourcecode/architecture_summary.py,sha256=wq7y0RKm77_bt0n1qJaIivOQ_V0itllr5e6363df0XE,10304
+sourcecode/__init__.py,sha256=kGV-7biOu1jEQzo70FiCy-DkYFbItVMEkqxy37z-zJ8,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=TOyyOGfjVDhMS7zoOoU_NvpAdAdRQKNg3h1ucZlOIvk,23535
-sourcecode/code_notes_analyzer.py,sha256=RUGWBJPHwz-ZuN4p2zWyYFkfdsObqf-0WH3FaWuUyL0,8068
+sourcecode/cli.py,sha256=_ihMuJjjwTr50M77kMafOVX0kY9hqrdvl8NUQ_h0cbc,25178
+sourcecode/code_notes_analyzer.py,sha256=rRd8bFYV0krjlxxQV0wenwE9K7pVpUQSR7KvSvUQKw4,9226
 sourcecode/coverage_parser.py,sha256=q0LeZJaX1bnntLu-ImksdBsMlpsVmk_iUfSaB4eaJGo,19702
-sourcecode/dependency_analyzer.py,sha256=Mv86FBto4KNiQBK5p9GZEN2lpe8FPJBeIJlrD9PRKDg,39004
+sourcecode/dependency_analyzer.py,sha256=9BEAyLoBAS2R0twYkprJj_e0c83pzz9QPMRWKfinNn4,40948
 sourcecode/doc_analyzer.py,sha256=Ec3orx6vBKsh5cNM3-F4y2Got2KuKx8w3dErwtdtM-A,19891
 sourcecode/env_analyzer.py,sha256=_UTkAzHNxDgJVpSMviWcn9e2V5o-SAV_oF6xsLHDxfI,12206
 sourcecode/git_analyzer.py,sha256=S9PGt8RDasBQYQUsZh9-H_KWVlPvzwR4jgM7TKN9ZCk,7643
@@ -13,10 +13,10 @@ sourcecode/graph_analyzer.py,sha256=cxl7Xb88aGxIVOCsatZJAE1CtgXGzIbJfqytV-9kkFs,
 sourcecode/metrics_analyzer.py,sha256=4uh11v-Q0gdrN87BOxuFWUym3N3AOkOuy21K5N8peB8,20126
 sourcecode/prepare_context.py,sha256=X43dEPe2cb7uMwlpQwVJMe0rQIZ0juaJ7H3F37sPbNc,5371
 sourcecode/redactor.py,sha256=xuGcadGEHaPw4qZXlMDvzMCsr4VOkdp3oBQptHyJk8c,2884
-sourcecode/scanner.py,sha256=BA53UAxbNXsBYQI0SrZkj_HycItpPoHznt1nSugf874,6183
+sourcecode/scanner.py,sha256=Ga4jDRAOhkcwlRmlE2ko6cE39qKy0aI4iE1lGBWmAlk,6410
 sourcecode/schema.py,sha256=93IrVRLAbzksVfFzr6_FhFSPpKJVwgVoTBcov-jTVo8,15669
 sourcecode/semantic_analyzer.py,sha256=SRQSGJzEi4ZsGvb7U3qvnRiKHabz4hvIzCqiG92x9K8,79349
-sourcecode/serializer.py,sha256=25OyUXKkvVR0tns-cCSuik4cdK7V-xqHSu0kJbC0tMU,3839
+sourcecode/serializer.py,sha256=IMU4lmr0FTDSTocws47abpJL01HH1cBK2UMGSUv00yo,13404
 sourcecode/summarizer.py,sha256=2Yz5xJ1bhtJLlrUpKcd74wijypRRo9GJmGT8u971EW0,11572
 sourcecode/tree_utils.py,sha256=xla45Whq24j6U9kEgTztJXkMpmOEDieAulKxP3nl89s,935
 sourcecode/workspace.py,sha256=fQlVoNx8S-fSHpKoJ0JBvEHCFkxszH0KZVJed1i3TRk,6845
@@ -39,7 +39,7 @@ sourcecode/detectors/rust.py,sha256=V23NO6Y8NsrhrUlGC2feUEcNK63hf3gc1y3jI4tes1Q,
 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.15.1.dist-info/METADATA,sha256=uNHGPWoTdXnkpo2dmI0R_fLZJcABcHxQUY4rYGpRf0E,25900
-sourcecode-0.15.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-0.15.1.dist-info/entry_points.txt,sha256=voDtdlGU2-jR3wCZpQoOls_0eUKaDVCKIfajGHFDATs,50
-sourcecode-0.15.1.dist-info/RECORD,,
+sourcecode-0.17.0.dist-info/METADATA,sha256=sbwLpqrcDu_SkhDmPOqsq5YIT4wPn8V00GF1DRRohoI,25900
+sourcecode-0.17.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-0.17.0.dist-info/entry_points.txt,sha256=voDtdlGU2-jR3wCZpQoOls_0eUKaDVCKIfajGHFDATs,50
+sourcecode-0.17.0.dist-info/RECORD,,