sourcecode 0.28.0__py3-none-any.whl → 0.29.0__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/architecture_analyzer.py

@@ -12,6 +12,10 @@ from sourcecode.schema import (
     SourceMap,
 )
 
+_WORKSPACE_CONFIG_FILES: frozenset[str] = frozenset({
+    "turbo.json", "nx.json", "pnpm-workspace.yaml", "lerna.json", "rush.json",
+})
+
 _TOOLING_PREFIXES = (
     ".claude/",
     ".vscode/",
@@ -34,6 +38,18 @@ _CODE_EXTENSIONS = {
 _GENERIC_NAMES = {"utils", "helpers", "common", "shared", "misc", "core", "root", ""}
 
 _TEST_DIRS: frozenset[str] = frozenset({"tests", "test", "spec", "specs", "__tests__", "e2e"})
+_BENCHMARK_DIRS: frozenset[str] = frozenset({
+    "benchmark", "benchmarks", "bench",
+    "example", "examples",
+    "demo", "demos",
+    "playground", "playgrounds",
+    "fixture", "fixtures",
+    "sandbox",
+})
+_DOCS_DIRS: frozenset[str] = frozenset({"docs", "doc", "documentation", "wiki"})
+_TOOLING_DIRS: frozenset[str] = frozenset({"scripts", "script", "tools", "tool", "ci"})
+# All dirs that are not part of the runtime source architecture
+_NON_SOURCE_DIRS: frozenset[str] = _TEST_DIRS | _BENCHMARK_DIRS | _DOCS_DIRS | _TOOLING_DIRS
 
 # Exact file stems that signal a specific architectural layer
 _LAYER_STEM_EXACT: dict[str, str] = {
@@ -177,15 +193,35 @@ class ArchitectureAnalyzer:
             elif pattern == "unknown":
                 limitations.append("Patron de capas no reconocido: estructura de directorios sin senales claras")
 
+        # Step 3b: monorepo override — workspace config is hard evidence
+        if self._has_workspace_config(sm.file_paths) and pattern not in (
+            "monorepo", "cqrs", "clean", "onion", "hexagonal"
+        ):
+            mono_layers = self._detect_monorepo_packages(filtered)
+            if mono_layers or pattern in (None, "unknown", "flat", "modular", "layered"):
+                pattern = "monorepo"
+                layers = mono_layers
+                limitations.append(
+                    "Workspace config detectado — arquitectura refleja topologia de paquetes"
+                )
+
         # Step 4: bounded context inference
         bounded_contexts = self._infer_bounded_contexts(domains, graph)
 
-        # Overall confidence
+        # Overall confidence — based on domain quality, not raw count
         confidence: Literal["high", "medium", "low"]
+        strong_domains = [d for d in domains if d.confidence in ("high", "medium")]
+        all_layers_weak = layers and all(l.confidence == "low" for l in layers)
         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:
+            if all_layers_weak:
+                # Layers came from file-naming heuristic only, not directory structure
+                confidence = "medium"
+                limitations.append(
+                    "Patron inferido de nombres de archivo — sin estructura de directorios confirmatoria"
+                )
+            else:
+                confidence = "high" if len(strong_domains) >= 3 else "medium"
+        elif len(strong_domains) >= 1:
             confidence = "medium"
         else:
             confidence = "low"
@@ -217,6 +253,10 @@ class ArchitectureAnalyzer:
             norm = p.replace("\\", "/")
             if self._is_tooling(norm):
                 continue
+            # Exclude non-source dirs at every path segment (benchmarks, docs, tests, scripts…)
+            parts = norm.split("/")
+            if any(part.lower() in _NON_SOURCE_DIRS for part in parts[:-1]):
+                continue
             ext = Path(norm).suffix.lower()
             if ext not in _CODE_EXTENSIONS:
                 continue
@@ -250,6 +290,8 @@ class ArchitectureAnalyzer:
         for name, files in groups.items():
             if len(files) < 2:
                 continue
+            if name.lower() in _NON_SOURCE_DIRS:
+                continue
             role = DOMAIN_ROLES.get(name, "")
             domain_confidence: Literal["high", "medium", "low"]
             if name in DOMAIN_ROLES:
@@ -262,10 +304,10 @@ 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
+        # Exclude non-source paths (tests, benchmarks, docs, tooling) from 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 any(part.lower() in _NON_SOURCE_DIRS for part in p.replace("\\", "/").split("/"))
         ]
         if not source_paths:
             return "unknown", []
@@ -360,7 +402,7 @@ class ArchitectureAnalyzer:
             parts = p.replace("\\", "/").split("/")
             if len(parts) >= 2 and parts[-1].lower() in _ENTRY_FILES:
                 top = parts[0]
-                if top.lower() not in _SRC_TRANSPARENT and top.lower() not in _TEST_DIRS:
+                if top.lower() not in _SRC_TRANSPARENT and top.lower() not in _NON_SOURCE_DIRS:
                     entry_dirs.setdefault(top, []).append(p)
         if len(entry_dirs) >= 4:
             return "microservices", [
@@ -394,7 +436,7 @@ class ArchitectureAnalyzer:
         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")
+                ArchitectureLayer(name=k, pattern="layered", files=v, confidence="low")
                 for k, v in non_empty.items()
             ]
         return None
@@ -412,19 +454,42 @@ class ArchitectureAnalyzer:
             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 _NON_SOURCE_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}
+        meaningful = {k: v for k, v in module_files.items() if len(v) >= 3}
         if len(meaningful) >= 2:
             return "modular", [
-                ArchitectureLayer(name=k, pattern="modular", files=v, confidence="medium")
+                ArchitectureLayer(name=k, pattern="modular", files=v, confidence="low")
                 for k, v in meaningful.items()
             ]
         return None
 
+    def _has_workspace_config(self, file_paths: list[str]) -> bool:
+        for path in file_paths:
+            parts = path.replace("\\", "/").split("/")
+            if len(parts) == 1 and parts[0] in _WORKSPACE_CONFIG_FILES:
+                return True
+        return False
+
+    def _detect_monorepo_packages(self, paths: list[str]) -> list[ArchitectureLayer]:
+        """Find workspace packages (packages/*, apps/*, libs/*) in a monorepo."""
+        _WORKSPACE_ROOTS = {"packages", "apps", "libs", "applications"}
+        groups: dict[str, list[str]] = {}
+        for p in paths:
+            parts = p.replace("\\", "/").split("/")
+            if len(parts) >= 2 and parts[0].lower() in _WORKSPACE_ROOTS:
+                key = f"{parts[0]}/{parts[1]}"
+                groups.setdefault(key, []).append(p)
+        result = [
+            ArchitectureLayer(name=k, pattern="monorepo", files=v, confidence="medium")
+            for k, v in groups.items()
+            if len(v) >= 2
+        ]
+        return result[:16]
+
     def _infer_bounded_contexts(
         self,
         domains: list[ArchitectureDomain],

sourcecode/cli.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 import json
 import time
 from pathlib import Path
@@ -9,6 +10,146 @@ import typer
 
 from sourcecode import __version__
 
+
+# ---------------------------------------------------------------------------
+# Analyzer fingerprints — short hashes of each analyzer's key rule constants.
+# A change in heuristics, filter lists, or pattern maps changes the hash,
+# making it immediately visible that two runs used different rule versions
+# even if the semver string is the same.
+# ---------------------------------------------------------------------------
+
+def _fingerprint(*objects: object) -> str:
+    raw = json.dumps([repr(o) for o in objects], sort_keys=True)
+    return hashlib.sha256(raw.encode()).hexdigest()[:8]
+
+
+def _compute_analyzer_fingerprints() -> dict[str, str]:
+    from sourcecode.detectors.heuristic import (
+        _AUXILIARY_DIRS as _HEUR_AUX,
+        _ENTRYPOINT_NAMES,
+        _EXTENSION_MAP,
+    )
+    from sourcecode.detectors.nodejs import _FRAMEWORK_MAP, NodejsDetector
+    from sourcecode.confidence_analyzer import (
+        _AUXILIARY_DIR_PREFIXES,
+        _HARD_SOURCES,
+        _SOFT_SOURCES,
+    )
+    from sourcecode.architecture_analyzer import (
+        _BENCHMARK_DIRS,
+        _NON_SOURCE_DIRS,
+        LAYER_PATTERNS,
+    )
+
+    return {
+        "heuristic": _fingerprint(_EXTENSION_MAP, _ENTRYPOINT_NAMES, sorted(_HEUR_AUX)),
+        "nodejs": _fingerprint(_FRAMEWORK_MAP, sorted(NodejsDetector._AUXILIARY_DIRS)),
+        "confidence": _fingerprint(sorted(_AUXILIARY_DIR_PREFIXES), sorted(_HARD_SOURCES), sorted(_SOFT_SOURCES)),
+        "architecture": _fingerprint(sorted(_BENCHMARK_DIRS), sorted(_NON_SOURCE_DIRS), list(LAYER_PATTERNS.keys())),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Pipeline trace collector
+# ---------------------------------------------------------------------------
+
+class _TraceCollector:
+    """Lightweight collector for pipeline trace events."""
+
+    def __init__(self, enabled: bool = False) -> None:
+        self._enabled = enabled
+        self._events: list[dict[str, Any]] = []
+
+    def emit(
+        self,
+        stage: str,
+        component: str,
+        action: str,
+        target: Optional[str] = None,
+        reason: Optional[str] = None,
+    ) -> None:
+        if not self._enabled:
+            return
+        self._events.append({
+            "stage": stage,
+            "component": component,
+            "action": action,
+            **({"target": target} if target else {}),
+            **({"reason": reason} if reason else {}),
+        })
+
+    def build_trace(self) -> "PipelineTrace":
+        from sourcecode.schema import PipelineEvent, PipelineTrace
+        events = [
+            PipelineEvent(
+                stage=e["stage"],
+                component=e["component"],
+                action=e["action"],
+                target=e.get("target"),
+                reason=e.get("reason"),
+            )
+            for e in self._events
+        ]
+        return PipelineTrace(requested=True, events=events)
+
+
+# ---------------------------------------------------------------------------
+# E2E pipeline coherence check
+# ---------------------------------------------------------------------------
+
+def _check_pipeline_coherence(sm: "SourceMap") -> list[str]:  # type: ignore[name-defined]
+    """Verify no contradictory states exist between analyzers.
+
+    Returns a list of human-readable violation strings (empty when clean).
+    These are emitted to stderr as [coherence] warnings — never abort a run.
+    """
+    issues: list[str] = []
+    cs = sm.confidence_summary
+
+    if cs is not None:
+        # overall:high requires at least one manifest-detected stack
+        if cs.overall == "high":
+            manifest_stacks = [s for s in sm.stacks if s.detection_method != "heuristic"]
+            if not manifest_stacks:
+                issues.append(
+                    "[coherence] overall=high but all stacks are heuristic — "
+                    "downgrade not applied; check confidence_analyzer"
+                )
+
+        # overall:high requires at least one production entry point
+        if cs.overall == "high":
+            prod_eps = [
+                ep for ep in sm.entry_points
+                if ep.entrypoint_type in ("production", None)
+            ]
+            if not prod_eps and sm.entry_points:
+                issues.append(
+                    "[coherence] overall=high but no production entry points exist — "
+                    "all detected EPs are auxiliary (benchmark/example/dev)"
+                )
+
+        # entry_point_confidence must not be high when entry_points is empty
+        if cs.entry_point_confidence == "high" and not sm.entry_points:
+            issues.append(
+                "[coherence] entry_point_confidence=high but entry_points is empty"
+            )
+
+    # Contradictory EP classification: EPs with entrypoint_type=benchmark must not
+    # appear in agent_view output (checked post-facto via produced_by + type)
+    benchmark_eps = [
+        ep for ep in sm.entry_points
+        if ep.entrypoint_type in ("benchmark", "example")
+    ]
+    if benchmark_eps and sm.entry_points and all(
+        ep.entrypoint_type in ("benchmark", "example") for ep in sm.entry_points
+    ):
+        issues.append(
+            f"[coherence] all {len(sm.entry_points)} entry point(s) are benchmark/example — "
+            "no production entry detected; analysis_gaps should reflect impact=high"
+        )
+
+    return issues
+
 _HELP = """\
 Deterministic codebase context for AI coding agents.
 
@@ -327,6 +468,11 @@ def main(
         "--agent",
         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.",
     ),
+    trace_pipeline: bool = typer.Option(
+        False,
+        "--trace-pipeline",
+        help="Modo trazabilidad: incluye pipeline_trace con candidatos, filtros, descartes y origen de cada dato. Para diagnóstico de contaminación de resultados.",
+    ),
 ) -> None:
     """Analyze a repository and produce structured context for AI coding agents.
 
@@ -672,7 +818,18 @@ def main(
     )
 
     # 3. Construir el schema
-    metadata = AnalysisMetadata(analyzed_path=str(target))
+    # Compute analyzer fingerprints: short hashes of each analyzer's key rule
+    # constants so that a rule change is always visible in the output, regardless
+    # of whether the semver was bumped.
+    try:
+        _fingerprints = _compute_analyzer_fingerprints()
+    except Exception:
+        _fingerprints = {}
+
+    metadata = AnalysisMetadata(
+        analyzed_path=str(target),
+        analyzer_fingerprints=_fingerprints,
+    )
     sm = SourceMap(
         metadata=metadata,
         file_tree=file_tree,
@@ -812,6 +969,51 @@ def main(
     _conf_summary, _analysis_gaps = ConfidenceAnalyzer().analyze(sm)
     sm = _replace(sm, confidence_summary=_conf_summary, analysis_gaps=_analysis_gaps)
 
+    # E2E pipeline coherence check — emits [coherence] warnings to stderr.
+    # Catches contradictory states that can survive individual-analyzer validation.
+    for _issue in _check_pipeline_coherence(sm):
+        typer.echo(_issue, err=True)
+
+    # Build pipeline trace when --trace-pipeline is set.
+    if trace_pipeline:
+        _trace = _TraceCollector(enabled=True)
+        _trace.emit("scan", "scanner", "complete",
+                    reason=f"{len(sm.file_paths)} files, {len(manifests)} manifests")
+        for _s in sm.stacks:
+            _trace.emit("detect", _s.produced_by or "unknown", "emit_stack",
+                        target=_s.stack,
+                        reason=f"method={_s.detection_method} confidence={_s.confidence}")
+        for _ep in sm.entry_points:
+            _trace.emit("detect", _ep.produced_by or "unknown", "emit_ep",
+                        target=_ep.path,
+                        reason=f"type={_ep.entrypoint_type} confidence={_ep.confidence} reason={_ep.reason}")
+        # Record EPs filtered from agent_view (benchmark/example with path-auxiliary parts)
+        _aux_parts = frozenset({
+            "benchmark", "benchmarks", "bench", "demo", "demos",
+            "example", "examples", "docs", "doc", "fixtures", "fixture",
+        })
+        for _ep in sm.entry_points:
+            _ep_type = _ep.entrypoint_type
+            _path_parts = _ep.path.replace("\\", "/").lower().split("/")
+            _filtered = (
+                _ep_type in ("benchmark", "example")
+                or any(p in _aux_parts for p in _path_parts)
+            )
+            if _filtered:
+                _trace.emit("output", "agent_view", "filter_ep",
+                            target=_ep.path,
+                            reason=f"entrypoint_type={_ep_type} (auxiliary)")
+        if sm.confidence_summary is not None:
+            _cs = sm.confidence_summary
+            _trace.emit("confidence", "confidence_analyzer", "computed",
+                        reason=(
+                            f"overall={_cs.overall} "
+                            f"stack={_cs.stack_confidence} "
+                            f"ep={_cs.entry_point_confidence} "
+                            f"anomalies={len(_cs.anomalies)}"
+                        ))
+        sm = _replace(sm, pipeline_trace=_trace.build_trace())
+
     # 4. Serializar
     if agent:
         data = agent_view(sm)

sourcecode/confidence_analyzer.py

@@ -98,6 +98,31 @@ class ConfidenceAnalyzer:
         if sm.entry_points and all(ep.confidence == "low" for ep in sm.entry_points):
             anomalies.append("All entry points are low-confidence (heuristic/code_signal only)")
 
+        # ── Anomaly: all production EPs are convention-only (no manifest evidence) ──
+        production_eps_check = [
+            ep for ep in sm.entry_points
+            if ep.entrypoint_type in ("production", None)
+        ]
+        if production_eps_check and all(
+            ep.source in ("convention", "heuristic") or ep.reason in ("convention", "entry_file_pattern")
+            for ep in production_eps_check
+        ):
+            anomalies.append(
+                "All production entry points inferred from filename conventions only — "
+                "no package.json scripts, bin declaration, or manifest reference found"
+            )
+
+        # ── Anomaly: no production entry points ───────────────────────────────
+        if sm.entry_points:
+            production_eps = [
+                ep for ep in sm.entry_points
+                if ep.entrypoint_type in ("production", None)
+            ]
+            if not production_eps:
+                anomalies.append(
+                    "No production entry points — all detected entries are dev/benchmark/example"
+                )
+
         # ── Gaps ──────────────────────────────────────────────────────────────
         if not sm.entry_points:
             gaps.append(AnalysisGap(
@@ -105,6 +130,19 @@ class ConfidenceAnalyzer:
                 reason="No entry point detected — project may use non-standard structure or be a library",
                 impact="high",
             ))
+        elif all(
+            ep.entrypoint_type in ("benchmark", "example", "development")
+            for ep in sm.entry_points
+        ):
+            gaps.append(AnalysisGap(
+                area="entry_points",
+                reason=(
+                    "All detected entry points are auxiliary (benchmark/example/dev) — "
+                    "no production entry point found. Verify project has a 'start'/'serve' "
+                    "script or production binary."
+                ),
+                impact="high",
+            ))
         elif all(ep.confidence == "low" for ep in sm.entry_points):
             gaps.append(AnalysisGap(
                 area="entry_points",
@@ -155,10 +193,24 @@ class ConfidenceAnalyzer:
             if manifest_stacks
             else _min_confidence([s.confidence for s in sm.stacks] or ["low"])
         )
-        # Entry points: use best available (highest-confidence EP wins)
-        ep_conf = _max_confidence([ep.confidence for ep in sm.entry_points] or ["low"])
+        # Entry points: only consider production EPs for confidence scoring.
+        # Benchmark/example/dev-only entries are not evidence of production readiness.
+        production_eps = [
+            ep for ep in sm.entry_points
+            if ep.entrypoint_type in ("production", None)
+        ]
+        ep_conf = _max_confidence([ep.confidence for ep in production_eps] or ["low"])
         overall = _min_confidence([stack_conf, ep_conf])
 
+        # Factor in architecture confidence when available
+        arch = sm.architecture
+        if arch is not None and arch.requested:
+            overall = _min_confidence([overall, arch.confidence])
+            if arch.pattern in (None, "unknown"):
+                # Architecture could not be inferred — don't let stack alone push to high
+                if overall == "high":
+                    overall = "medium"
+
         # Downgrade if gaps are severe
         high_impact_gaps = [g for g in gaps if g.impact == "high"]
         if high_impact_gaps:

sourcecode/detectors/heuristic.py

@@ -26,11 +26,27 @@ _EXTENSION_MAP = {
 _ENTRYPOINT_NAMES = {
     "main.py": ("python", "script"),
     "app.py": ("python", "app"),
-    "index.js": ("nodejs", "server"),
+    # index.js excluded: ambiguous (library export vs server); nodejs detector handles it
     "main.go": ("go", "binary"),
     "main.rs": ("rust", "binary"),
 }
 
+_AUXILIARY_DIRS: frozenset[str] = frozenset({
+    "benchmark", "benchmarks", "bench",
+    "example", "examples",
+    "demo", "demos",
+    "playground", "playgrounds",
+    "fixture", "fixtures", "mock", "mocks",
+    "sandbox", "e2e", "docs", "doc", "documentation",
+    "test", "tests", "spec", "specs", "__tests__",
+    "scripts", "script", "tools", "tool", "tooling", "ci",
+})
+
+
+def _is_auxiliary_path(path: str) -> bool:
+    parts = path.replace("\\", "/").split("/")
+    return any(p.lower() in _AUXILIARY_DIRS for p in parts)
+
 
 class HeuristicDetector(AbstractDetector):
     name = "heuristic"
@@ -62,6 +78,8 @@ class HeuristicDetector(AbstractDetector):
 
         entry_points: list[EntryPoint] = []
         for path in paths:
+            if _is_auxiliary_path(path):
+                continue
             filename = path.rsplit("/", 1)[-1]
             if filename in _ENTRYPOINT_NAMES:
                 stack, kind = _ENTRYPOINT_NAMES[filename]

sourcecode/detectors/nodejs.py

@@ -187,17 +187,22 @@ class NodejsDetector(AbstractDetector):
         if isinstance(main, str) and main.strip():
             path = main.strip()
             if path not in seen and 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",
-                    entrypoint_type="production",
-                ))
+                if not self._is_auxiliary_path(path):
+                    seen.add(path)
+                    entry_points.append(EntryPoint(
+                        path=path,
+                        stack="nodejs",
+                        kind="module",
+                        source="package.json",
+                        confidence="high",
+                        reason="main",
+                        evidence="declared in package.json main field",
+                        entrypoint_type="production",
+                    ))
 
         # Priority 4: filename conventions (last resort — penalize auxiliary dirs)
+        is_monorepo = bool(self._detect_monorepo_signals(context, package_json))
+        _INDEX_PATHS = {"src/index.js", "src/index.ts", "index.js", "index.ts"}
         for path in [
             "server.js", "server.ts",
             "src/index.js", "src/index.ts",
@@ -206,14 +211,19 @@ class NodejsDetector(AbstractDetector):
         ]:
             if path in seen or not path_exists_in_tree(context.file_tree, path):
                 continue
+            # In monorepos, root/src index files are package exports, not run targets
+            if is_monorepo and path in _INDEX_PATHS:
+                continue
             ep_type = self._path_entrypoint_type(path)
-            kind = "web" if path.startswith(("app/", "pages/")) else "server"
+            is_index = path.split("/")[-1] in ("index.js", "index.ts")
+            kind = "module" if is_index else ("web" if path.startswith(("app/", "pages/")) else "server")
+            confidence = "low"  # convention only — no script or bin declaration
             entry_points.append(EntryPoint(
                 path=path,
                 stack="nodejs",
                 kind=kind,
                 source="convention",
-                confidence="medium",
+                confidence=confidence,
                 reason="convention",
                 entrypoint_type=ep_type,
             ))

sourcecode/detectors/project.py

@@ -48,6 +48,12 @@ class ProjectDetector:
                 continue
 
             stacks, entry_points = detector.detect(context)
+            # Stamp provenance: every emitted stack and EP knows which detector produced it
+            for item in stacks:
+                item.produced_by = detector.name
+            for item in entry_points:
+                item.produced_by = detector.name
+
             for stack in stacks:
                 existing = merged_stacks.get(stack.stack)
                 if existing is None:
@@ -103,6 +109,7 @@ class ProjectDetector:
             root=stack.root,
             workspace=stack.workspace,
             signals=list(stack.signals),
+            produced_by=stack.produced_by,
         )
 
     def _merge_stack(self, current: StackDetection, incoming: StackDetection) -> StackDetection:

sourcecode/env_analyzer.py

@@ -31,6 +31,14 @@ _SPRING_CONF_PROFILE_RE = re.compile(r'^application-[a-z0-9_-]+\.(properties|ya?
 # Matches ${ENV_VAR} or ${ENV_VAR:default} where ENV_VAR is UPPER_SNAKE_CASE
 _SPRING_ENV_REF_RE = re.compile(r'\$\{([A-Z][A-Z0-9_]*)(?::[^}]*)?\}')
 
+# Patterns where absence of the variable causes a hard runtime error (not just None/null).
+# py_environ_bracket → os.environ["KEY"] raises KeyError
+# java_spring_value   → Spring fails to start if ${KEY} has no default
+_HARD_REQUIRED_PATTERNS: frozenset[str] = frozenset({
+    "py_environ_bracket",
+    "java_spring_value",
+})
+
 # (pattern_id, compiled_regex)
 # Grupos de captura: group(1)=key, group(2)=default si existe
 _PATTERNS: list[tuple[str, re.Pattern]] = [
@@ -132,9 +140,9 @@ def _infer_type_hint(key: str) -> str:
 def _scan_file(
     path: Path,
     rel_path: str,
-    findings: dict[str, list[tuple[str, Optional[str]]]],
+    findings: dict[str, list[tuple[str, Optional[str], bool]]],
 ) -> None:
-    """Escanea un fichero de código y acumula hallazgos en findings[key] = [(file_ref, default)]."""
+    """Escanea un fichero y acumula hallazgos en findings[key] = [(file_ref, default, is_hard)]."""
     try:
         size = path.stat().st_size
         if size > _MAX_FILE_SIZE:
@@ -143,8 +151,8 @@ def _scan_file(
     except OSError:
         return
 
-    lines = content.splitlines()
-    for _pattern_id, regex in _PATTERNS:
+    for pattern_id, regex in _PATTERNS:
+        is_hard = pattern_id in _HARD_REQUIRED_PATTERNS
         for m in regex.finditer(content):
             key = m.group(1)
             if not key:
@@ -158,10 +166,9 @@ def _scan_file(
             except IndexError:
                 pass
 
-            # Compute 1-based line number
             line_num = content.count("\n", 0, m.start()) + 1
             file_ref = f"{rel_path}:{line_num}"
-            findings[key].append((file_ref, default))
+            findings[key].append((file_ref, default, is_hard))
 
 
 def _parse_env_example(
@@ -211,7 +218,8 @@ def _parse_spring_config(
     for m in _SPRING_ENV_REF_RE.finditer(content):
         key = m.group(1)
         line_num = content.count("\n", 0, m.start()) + 1
-        findings[key].append((f"{rel_path}:{line_num}", None))
+        # Spring fails to start if a referenced env var has no default → hard required
+        findings[key].append((f"{rel_path}:{line_num}", None, True))
 
 
 class EnvAnalyzer:
@@ -224,8 +232,8 @@ class EnvAnalyzer:
     ) -> tuple[list, object]:
         from sourcecode.schema import EnvSummary, EnvVarRecord
 
-        # findings[key] = list of (file_ref, default_or_None)
-        findings: dict[str, list[tuple[str, Optional[str]]]] = defaultdict(list)
+        # findings[key] = list of (file_ref, default_or_None, is_hard_required)
+        findings: dict[str, list[tuple[str, Optional[str], bool]]] = defaultdict(list)
         example_entries: list[tuple[str, Optional[str], Optional[str]]] = []
         example_files_found: list[str] = []
         limitations: list[str] = []
@@ -240,12 +248,16 @@ class EnvAnalyzer:
             if len(records) >= _MAX_KEYS:
                 limitations.append(f"key_limit_reached:{_MAX_KEYS}")
                 break
-            defaults = [d for _, d in refs if d is not None]
-            required = len(defaults) == 0
+            defaults = [d for _, d, _ in refs if d is not None]
+            # required only when access pattern causes a hard runtime error if missing:
+            # os.environ["KEY"] (KeyError) or Spring @Value/${KEY} without default.
+            # os.getenv("KEY") / os.environ.get("KEY") return None — not hard required.
+            has_hard_access = any(is_hard for _, _, is_hard in refs)
+            required = has_hard_access and not defaults
             default_val = defaults[0] if defaults else None
             unique_files: list[str] = []
             seen: set[str] = set()
-            for file_ref, _ in refs:
+            for file_ref, _, _ in refs:
                 if file_ref not in seen:
                     seen.add(file_ref)
                     unique_files.append(file_ref)
@@ -271,7 +283,7 @@ class EnvAnalyzer:
                     break
                 records[key] = EnvVarRecord(
                     key=key,
-                    required=example_default is None,
+                    required=False,  # .env.example documents presence; hard required needs a code access pattern
                     default=example_default,
                     type_hint=_infer_type_hint(key),
                     category=_infer_category(key),

sourcecode/git_analyzer.py

@@ -12,6 +12,34 @@ _MAX_CONTRIBUTORS = 20
 
 _DATE_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}T")
 
+_RELEASE_COMMIT_RE = re.compile(
+    r"^(?:chore(?:\(release\))?[:\s]|release[:\s]|bump[:\s]|version[:\s]"
+    r"|Merge pull request\s|Bumps?\s\w"
+    r"|v?\d+\.\d+\.\d+)",
+    re.IGNORECASE,
+)
+# Matches version-bump phrases anywhere in the commit subject (multilingual)
+_RELEASE_COMMIT_CONTAINS_RE = re.compile(
+    r"subiendo a v?[\d.]"          # Spanish: "subiendo a v.0.28.0"
+    r"|bumping to v?[\d.]"
+    r"|preparing (?:v|release)[\d. ]"
+    r"|releasing v?[\d.]"
+    r"|cut v?[\d.]"
+    r"|\bv\d+\.\d+\.\d+\b",       # bare version tag in middle of message
+    re.IGNORECASE,
+)
+
+# Files changed by release bots / version bumps — exclude from semantic hotspots
+_HOTSPOT_ADMIN_FILENAMES: frozenset[str] = frozenset({
+    "CHANGELOG.md", "CHANGELOG", "CHANGES.md", "CHANGES", "HISTORY.md",
+    "RELEASE.md", "RELEASES.md", "RELEASE_NOTES.md", "CHANGELOG.rst", "NEWS.md", "NEWS.rst",
+    "VERSION", "VERSION.txt", "version.txt", ".version",
+    "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "bun.lockb",
+    "Cargo.lock", "poetry.lock", "Pipfile.lock", "composer.lock",
+    "go.sum", "Gemfile.lock",
+})
+_HOTSPOT_ADMIN_SUFFIXES: tuple[str, ...] = (".lock", ".snap", ".min.js", ".min.css")
+
 
 def _run_git(args: list[str], cwd: Path, timeout: int = 15) -> tuple[str, int]:
     result = subprocess.run(
@@ -87,7 +115,7 @@ class GitAnalyzer:
                     "log",
                     f"--since={days} days ago",
                     "--name-only",
-                    "--pretty=format:%aI",
+                    "--pretty=format:__HOTSPOT__|%aI|%s",
                 ],
                 path,
                 timeout=30,
@@ -162,23 +190,45 @@ def _parse_commits(output: str) -> list:
     return commits
 
 
+def _is_hotspot_admin(path: str) -> bool:
+    """True for files that are noisy from release/bot commits, not semantic changes."""
+    filename = path.rsplit("/", 1)[-1]
+    if filename in _HOTSPOT_ADMIN_FILENAMES:
+        return True
+    for suffix in _HOTSPOT_ADMIN_SUFFIXES:
+        if filename.endswith(suffix):
+            return True
+    return False
+
+
 def _parse_hotspots(output: str) -> list:
     from sourcecode.schema import ChangeHotspot
 
     file_counts: Counter = Counter()
     file_last_date: dict[str, str] = {}
     current_date = ""
+    skip_commit = False
 
     for line in output.splitlines():
         line = line.strip()
         if not line:
             continue
-        if _DATE_PATTERN.match(line):
-            current_date = line[:10]
-        else:
-            file_counts[line] += 1
-            if line not in file_last_date and current_date:
-                file_last_date[line] = current_date
+        if line.startswith("__HOTSPOT__|"):
+            parts = line.split("|", 2)
+            current_date = parts[1][:10] if len(parts) > 1 else ""
+            subject = parts[2] if len(parts) > 2 else ""
+            skip_commit = (
+                bool(_RELEASE_COMMIT_RE.match(subject))
+                or bool(_RELEASE_COMMIT_CONTAINS_RE.search(subject))
+            )
+            continue
+        if skip_commit:
+            continue
+        if _is_hotspot_admin(line):
+            continue
+        file_counts[line] += 1
+        if line not in file_last_date and current_date:
+            file_last_date[line] = current_date
 
     return [
         ChangeHotspot(

sourcecode/schema.py

@@ -33,6 +33,7 @@ class AnalysisMetadata:
     generated_at: str = field(default_factory=_now_utc)
     sourcecode_version: str = field(default_factory=_sourcecode_version)
     analyzed_path: str = ""
+    analyzer_fingerprints: dict[str, str] = field(default_factory=dict)
 
 
 @dataclass
@@ -59,6 +60,7 @@ class StackDetection:
     root: Optional[str] = None
     workspace: Optional[str] = None
     signals: list[str] = field(default_factory=list)
+    produced_by: Optional[str] = None  # which detector emitted this
 
 
 @dataclass
@@ -73,6 +75,7 @@ class EntryPoint:
     reason: Optional[str] = None   # console_script | entry_file_pattern | main_guard | typer_app | heuristic | convention
     evidence: Optional[str] = None  # brief evidence string
     entrypoint_type: Optional[Literal["production", "development", "benchmark", "example"]] = None
+    produced_by: Optional[str] = None  # which detector emitted this
 
 
 @dataclass
@@ -462,6 +465,27 @@ class ContextSummary:
     coupling_notes: list[str] = field(default_factory=list)  # "2 import cycles", "hub: schema.py"
 
 
+# --- Pipeline Trace ---
+
+@dataclass
+class PipelineEvent:
+    """Single event in the pipeline trace."""
+
+    stage: str       # "scan" | "detect" | "merge" | "confidence" | "output"
+    component: str   # detector name or analyzer name
+    action: str      # "emit_stack" | "emit_ep" | "filter_ep" | "discard_ep" | "computed"
+    target: Optional[str] = None   # path or stack name
+    reason: Optional[str] = None   # human-readable explanation
+
+
+@dataclass
+class PipelineTrace:
+    """Full trace of what each pipeline stage produced or discarded."""
+
+    requested: bool = False
+    events: list[PipelineEvent] = field(default_factory=list)
+
+
 # --- Confidence & Explainability ---
 
 @dataclass
@@ -585,3 +609,5 @@ class SourceMap:
     context_summary: Optional[ContextSummary] = None
     # Runtime architecture (v0.26.0)
     monorepo_packages: list[MonorepoPackageInfo] = field(default_factory=list)
+    # Pipeline trace (v0.29.0) — populated only when --trace-pipeline is passed
+    pipeline_trace: Optional[PipelineTrace] = None

sourcecode/serializer.py

@@ -410,7 +410,9 @@ def agent_view(sm: SourceMap) -> dict[str, Any]:
 
     result: dict[str, Any] = {"project": project}
 
-    # ── 2. Entry points: production/runtime first, benchmark/example excluded ──
+    # ── 2. Entry points: production/runtime first; benchmark/example always excluded ──
+    # Never fall back to auxiliary-only EPs — when no operational EP exists the
+    # confidence_summary anomaly and analysis_gaps explain the gap instead.
     if sm.entry_points:
         _ep_skip = {"workspace"}
         _aux_parts = frozenset({
@@ -435,7 +437,10 @@ def agent_view(sm: SourceMap) -> dict[str, Any]:
         ]
         all_ep.sort(key=_ep_priority)
         operational_ep = [ep for ep in all_ep if _ep_priority(ep) < 5]
-        result["entry_points"] = operational_ep if operational_ep else all_ep
+        if operational_ep:
+            result["entry_points"] = operational_ep
+        # When operational_ep is empty: omit key entirely.
+        # confidence_summary.anomalies + analysis_gaps carry the explanation.
 
     # ── 3. Architecture ───────────────────────────────────────────────────────
     if sm.architecture_summary:
@@ -619,6 +624,9 @@ def standard_view(sm: SourceMap, *, include_tree: bool = False) -> dict[str, Any
         result["file_tree"] = sm.file_tree
         result["file_paths"] = sm.file_paths
 
+    if sm.pipeline_trace is not None and sm.pipeline_trace.requested:
+        result["pipeline_trace"] = asdict(sm.pipeline_trace)
+
     return result
 
 

{sourcecode-0.28.0.dist-info → sourcecode-0.29.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 0.28.0
+Version: 0.29.0
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004

{sourcecode-0.28.0.dist-info → sourcecode-0.29.0.dist-info}/RECORD

@@ -1,16 +1,16 @@
-sourcecode/__init__.py,sha256=AudH3rLCq_czFEvKZLk75Ofj-c3VkR7PkHcP8mAHIiY,100
-sourcecode/architecture_analyzer.py,sha256=h81uQuSlxAorHve7M4jzXLT2PStOaGRMTlEPgW9zvxo,19741
+sourcecode/__init__.py,sha256=n13VPZwhm9Du2TeJhJzTRI5m_7dP6mgpjdq-5NmlVIw,100
+sourcecode/architecture_analyzer.py,sha256=SBRMWJN70M2qeNLkm9oCG_1rw2UOVuNgikyeAHJsXKw,22859
 sourcecode/architecture_summary.py,sha256=qolHmn6MWUIQHzY9WeHcfN41EJkQdnPQ5F_Z8pqQasA,20251
 sourcecode/classifier.py,sha256=Ft_RfYS-KOe0t7vjgUx04OoCJd1-DXK7k9-I0CFDSnU,6934
-sourcecode/cli.py,sha256=VwYcYdiXFLcBdaZoRPNToG0KRjdBJ8X_7pnZVegQIGY,42561
+sourcecode/cli.py,sha256=4yXSF9UkQsMWU26ySO4-7Zs0B224AxbrdYGr2Urag1k,51120
 sourcecode/code_notes_analyzer.py,sha256=rRd8bFYV0krjlxxQV0wenwE9K7pVpUQSR7KvSvUQKw4,9226
-sourcecode/confidence_analyzer.py,sha256=gvQ92XCeGsACskSGU-GWTB7OqU1tT0eTgV-A7XA_lGs,8968
+sourcecode/confidence_analyzer.py,sha256=pzWeHTMz9ZYCuogYcTagpIJuLY-1SOSPTjsiE77rPek,11336
 sourcecode/context_summarizer.py,sha256=CiQrfBEzun949bWvmLabWoj2HhPn6Lw62ofqnsy0FlQ,6503
 sourcecode/coverage_parser.py,sha256=q0LeZJaX1bnntLu-ImksdBsMlpsVmk_iUfSaB4eaJGo,19702
 sourcecode/dependency_analyzer.py,sha256=Exq0BfInvfS5iAg9xAr6WI2uPNuotkIudTKcYJcRhB8,52757
 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
+sourcecode/env_analyzer.py,sha256=slvq-eT24RVMNczLNDlZbe0hU8JXIIPxybqubvrrnSQ,14409
+sourcecode/git_analyzer.py,sha256=saI5wtHBEOXBhdk7SrVR7ArSM6MFkyGgukvGRuD9WRc,9638
 sourcecode/graph_analyzer.py,sha256=hMOsLLz9B0UnQ4xwbHdgr3bFvqpw0bQ8kN-xmEn3Krk,64156
 sourcecode/metrics_analyzer.py,sha256=4uh11v-Q0gdrN87BOxuFWUym3N3AOkOuy21K5N8peB8,20126
 sourcecode/prepare_context.py,sha256=--lD2dhNkBYI8kwb14d1DlFmEN8XF1Ygtf0Qk7-Y1Bs,30911
@@ -18,9 +18,9 @@ sourcecode/redactor.py,sha256=xuGcadGEHaPw4qZXlMDvzMCsr4VOkdp3oBQptHyJk8c,2884
 sourcecode/relevance_scorer.py,sha256=2yvxDFnz9YGrHEJubgx9soiVIDZHKv_pntOtTARtKow,5928
 sourcecode/runtime_classifier.py,sha256=zWX3r3HCKHc-qtIobErOa8aKMmaoPYREtJKvPcBGPjQ,14792
 sourcecode/scanner.py,sha256=aM3h9-DCQ3xKpeHpHYdo2vX6T5P95HA_YwZbkAVNwmo,8288
-sourcecode/schema.py,sha256=c2ADsc0MDtsCJ6TIFqEfjhkCsSeFhIY0XhXc8BqfrrQ,19208
+sourcecode/schema.py,sha256=yCBhYKbF6axqMgl6F1XGk7xLl6uDJNZafwSSNMtxSa8,20222
 sourcecode/semantic_analyzer.py,sha256=asQfJf-EhzYaOTA-iMuZsrVXtbW7SV2WEKCxgsxa88Y,79413
-sourcecode/serializer.py,sha256=k8ffuXNkjkBSU8RNad3lv_89FdRbJ7qdEmhD988X_Sw,26756
+sourcecode/serializer.py,sha256=ZTnMbVnLSdplLK-NOdqH6GSi4v6zLgxm5i69VR9vS2Q,27199
 sourcecode/summarizer.py,sha256=YfBixsN1zWHHXdOEqaf793BylbJrsj75ST7FN6jcqRU,15424
 sourcecode/tree_utils.py,sha256=Fj9OIuUksBvgibNd3feog0sMDjVypJzPexp5lvMoYWI,1424
 sourcecode/workspace.py,sha256=fQlVoNx8S-fSHpKoJ0JBvEHCFkxszH0KZVJed1i3TRk,6845
@@ -31,14 +31,14 @@ sourcecode/detectors/dart.py,sha256=QbqaL5v18-_ort75HihVBt8MsKUfOcFDF8IpWFLiXpI,
 sourcecode/detectors/dotnet.py,sha256=oi8zq3AfUItlK3h_qM81vOe1ZVTIU9LBKIlIrRDuqOs,6864
 sourcecode/detectors/elixir.py,sha256=jCpvt5Yi6jvplc80ovRtWh17q-11ZGo9qX7o8b57TJE,1713
 sourcecode/detectors/go.py,sha256=2r66uRQfeTWsqxr4HDhT6vExZErby0t46QXLHVBRv9w,2782
-sourcecode/detectors/heuristic.py,sha256=JWb_dXNI1YDxk9a3DFeXTbKYfAGOFqV6jVxxqouWSiA,2238
+sourcecode/detectors/heuristic.py,sha256=Hab_Uiuxtq-WBs_wCnzETBS5hhaxeEtf-GOGMH63cv0,2887
 sourcecode/detectors/hybrid.py,sha256=IGFRUVsAZ1ooRlFdznCeJAV6vy1yVDx-VyghvLtddXc,9101
 sourcecode/detectors/java.py,sha256=cZvB13cqJ76zHDncEG-TOCuK8gJjJN2mZGS2DGEcZy8,7715
 sourcecode/detectors/jvm_ext.py,sha256=EgHJ5W8EE-ZTN9V607mVzohyKgZE8Mc2jCi-DF8RAZU,2616
-sourcecode/detectors/nodejs.py,sha256=BOGaghCC0nAZRvsib9Tptvr3-dJOzASnDPicXHez80c,10550
+sourcecode/detectors/nodejs.py,sha256=cqLw3SJ1UcImZD5_DVobByacWRD4ftIlep_mYo9z-n8,11260
 sourcecode/detectors/parsers.py,sha256=ugPg8yNUf0Ai1gA7Fnn6wAkYGFjTxRodSP3IeViYJJ4,2290
 sourcecode/detectors/php.py,sha256=W_AQD0WMVDdWHa9h_ilX6W8XSpz0X4ctpMK2WXfXf1I,1887
-sourcecode/detectors/project.py,sha256=YCynNC8drJutPMiDGPutlYaL49IO8M-1Ms_RwVY09ss,6221
+sourcecode/detectors/project.py,sha256=egFUnHC93xFfb-ikGCIOSkRdyP52qytDx9W7pGkX0MY,6525
 sourcecode/detectors/python.py,sha256=i2_Wtk_p0BJx5R8gBQ8NaQByzJ8zEfZkw9NNpKlvOYM,10486
 sourcecode/detectors/ruby.py,sha256=Q4B5ePAw6-T4DLfanKJiuLHLqUigTPVrzylcXJMei3M,1591
 sourcecode/detectors/rust.py,sha256=Tij1vz8BFZ332GEvVkL6vyMli2OMHJfHyDAppWfe66c,3557
@@ -51,8 +51,8 @@ sourcecode/telemetry/consent.py,sha256=wLMvGNJeSSyZoNkQXpoUioY6mMv4Qdvuw7S9jAEWn
 sourcecode/telemetry/events.py,sha256=oEvvulfsv5GIDWG2174gSS6tNB95w38AIYiYeifGKlE,2294
 sourcecode/telemetry/filters.py,sha256=Asa71oRl7q3Wt_FMwuufIZJFzSYdgRNKS8LHCIyFeYE,4805
 sourcecode/telemetry/transport.py,sha256=KJeIPCPWMdmbCP3ySGs2iUlia34U6vWne2dZsUezesw,1560
-sourcecode-0.28.0.dist-info/METADATA,sha256=GZbo1PkdXBdkNOySSJnfZWMtX4x6Z0qL3zJt1HgwtmQ,25020
-sourcecode-0.28.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-0.28.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-0.28.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-0.28.0.dist-info/RECORD,,
+sourcecode-0.29.0.dist-info/METADATA,sha256=FeC2-4TQTNZRw7iXfUDelfEv7Art515YgQkW4ZB68AA,25020
+sourcecode-0.29.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-0.29.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-0.29.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-0.29.0.dist-info/RECORD,,