sourcecode 0.21.0__tar.gz → 0.23.0__tar.gz

{sourcecode-0.21.0 → sourcecode-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 0.21.0
+Version: 0.23.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 → sourcecode-0.23.0}/docs/schema.md

@@ -81,7 +81,7 @@ Campos:
 {
   "schema_version": "1.0",
   "generated_at": "2026-04-07T19:41:05.686277+00:00",
-  "sourcecode_version": "0.21.0",
+  "sourcecode_version": "0.23.0",
   "analyzed_path": "/abs/path/to/project"
 }
 ```
@@ -645,7 +645,7 @@ Ejemplo de salida para un monorepo con web Node.js y API Python con `--dependenc
   "metadata": {
     "schema_version": "1.0",
     "generated_at": "2026-04-07T19:41:05.686277+00:00",
-    "sourcecode_version": "0.21.0",
+    "sourcecode_version": "0.23.0",
     "analyzed_path": "/abs/path/to/project"
   },
   "file_tree": {

{sourcecode-0.21.0 → sourcecode-0.23.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "0.21.0"
+version = "0.23.0"
 description = "Genera un mapa de contexto estructurado de proyectos de software para agentes IA"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-0.21.0 → sourcecode-0.23.0}/src/sourcecode/__init__.py

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

{sourcecode-0.21.0 → sourcecode-0.23.0}/src/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-0.21.0 → sourcecode-0.23.0}/src/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-0.21.0 → sourcecode-0.23.0}/src/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,29 @@ 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:
+    # Build confidence summary + analysis gaps (always runs, lightweight)
+    from sourcecode.confidence_analyzer import ConfidenceAnalyzer
+    from dataclasses import replace as _replace
+    _conf_summary, _analysis_gaps = ConfidenceAnalyzer().analyze(sm)
+    sm = _replace(sm, confidence_summary=_conf_summary, analysis_gaps=_analysis_gaps)
+
+    # 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
@@ -660,13 +672,18 @@ def main(
 def prepare_context_cmd(
     task: Optional[str] = typer.Argument(
         None,
-        help="Task: explain | fix-bug | refactor | generate-tests",
+        help="Task: explain | fix-bug | refactor | generate-tests | onboard | review-pr | delta",
     ),
     path: Path = typer.Option(
         Path("."),
         "--path", "-p",
         help="Project directory to analyze (default: current directory)",
     ),
+    since: Optional[str] = typer.Option(
+        None,
+        "--since",
+        help="Git ref for delta task: show files changed since this ref (e.g. HEAD~3, main)",
+    ),
     llm_prompt: bool = typer.Option(
         False,
         "--llm-prompt",
@@ -683,13 +700,24 @@ def prepare_context_cmd(
         help="Show what would be analyzed without running it",
     ),
 ) -> None:
-    """Prepare task-aware context optimized for LLM reasoning.
+    """Compile task-aware context for AI coding agents.
+
+    \b
+    Tasks:
+      explain        Project overview: structure, entry points, dependencies
+      fix-bug        Risk-ranked files, suspected areas, code annotations
+      refactor       Structural issues, improvement opportunities
+      generate-tests Untested source files, test gap analysis
+      onboard        Full project context for a new agent or developer
+      review-pr      PR review context: changed files + architecture
+      delta          Incremental context: git-changed files only
 
     \b
-    Note: PATH must be provided before the subcommand (default: '.'):
+    Examples:
       sourcecode . prepare-context explain
       sourcecode . prepare-context fix-bug --path /my/project
-      sourcecode . prepare-context generate-tests --llm-prompt
+      sourcecode . prepare-context delta --since main
+      sourcecode . prepare-context onboard --llm-prompt
       sourcecode . prepare-context --task-help
     """
     from sourcecode.prepare_context import TASKS, TaskContextBuilder
@@ -728,22 +756,28 @@ def prepare_context_cmd(
         typer.echo(f"path:        {target}")
         typer.echo(f"analyzers:   dependencies={'yes' if spec.enable_dependencies else 'no'}"
                    f", code_notes={'yes' if spec.enable_code_notes else 'no'}")
+        if since:
+            typer.echo(f"since:       {since}")
         typer.echo(f"output:      {spec.output_hint}")
         raise typer.Exit()
 
     from dataclasses import asdict
 
     builder = TaskContextBuilder(target)
-    output = builder.build(task)
+    output = builder.build(task, since=since)
 
     out: dict[str, Any] = {
         "task": output.task,
         "goal": output.goal,
         "project_summary": output.project_summary,
         "architecture_summary": output.architecture_summary,
+        "confidence": output.confidence,
         "relevant_files": [asdict(f) for f in output.relevant_files],
+        "why_these_files": output.why_these_files,
         "key_dependencies": output.key_dependencies,
     }
+    if output.gaps:
+        out["gaps"] = output.gaps
     if output.suspected_areas:
         out["suspected_areas"] = output.suspected_areas
     if output.improvement_opportunities:
@@ -752,6 +786,10 @@ def prepare_context_cmd(
         out["test_gaps"] = output.test_gaps
     if output.code_notes_summary:
         out["code_notes_summary"] = output.code_notes_summary
+    if output.changed_files:
+        out["changed_files"] = output.changed_files
+    if output.affected_entry_points:
+        out["affected_entry_points"] = output.affected_entry_points
     if output.limitations:
         out["limitations"] = output.limitations
     if llm_prompt:

sourcecode-0.23.0/src/sourcecode/confidence_analyzer.py

@@ -0,0 +1,190 @@
+"""confidence_analyzer.py — Builds ConfidenceSummary and AnalysisGap list from SourceMap.
+
+Analyzes detection quality post-facto:
+  - Classifies signals as hard (manifest/lockfile) vs soft (heuristic/extension)
+  - Identifies auxiliary paths that were found but correctly ignored
+  - Detects anomalies (conflicting signals, low-confidence detections)
+  - Produces structured analysis gaps for agent consumption
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sourcecode.schema import AnalysisGap, ConfidenceSummary, SourceMap
+
+if TYPE_CHECKING:
+    pass
+
+_AUXILIARY_DIR_PREFIXES = (
+    ".claude/", ".cursor/", ".vscode/", ".github/", ".idea/",
+    ".devcontainer/", ".husky/",
+)
+
+_FIXTURE_DIR_SEGMENTS = {"fixtures", "fixture", "testdata", "test_data", "__fixtures__"}
+_TEST_DIR_SEGMENTS = {"tests", "test", "spec", "specs", "__tests__"}
+_DOC_DIR_SEGMENTS = {"docs", "doc", "documentation", "wiki"}
+_GENERATED_DIR_SEGMENTS = {"dist", "build", "target", "out", "output", ".next", "__pycache__"}
+
+_HARD_SOURCES = {"manifest", "lockfile", "pyproject.toml", "package.json", "go.mod",
+                 "Cargo.toml", "pom.xml", "build.gradle"}
+_SOFT_SOURCES = {"heuristic", "code_signal", "convention"}
+
+
+class ConfidenceAnalyzer:
+    """Analyzes SourceMap quality and produces confidence + gap metadata."""
+
+    def analyze(self, sm: SourceMap) -> tuple[ConfidenceSummary, list[AnalysisGap]]:
+        hard_signals: list[str] = []
+        soft_signals: list[str] = []
+        ignored_signals: list[str] = []
+        anomalies: list[str] = []
+        gaps: list[AnalysisGap] = []
+
+        # ── Stack signals ─────────────────────────────────────────────────────
+        for stack in sm.stacks:
+            if stack.detection_method == "manifest" and stack.confidence in ("high", "medium"):
+                for manifest in stack.manifests:
+                    sig = f"stack:{stack.stack} via {manifest}"
+                    if sig not in hard_signals:
+                        hard_signals.append(sig)
+            elif stack.detection_method == "heuristic":
+                sig = f"stack:{stack.stack} (heuristic, no manifest)"
+                if sig not in soft_signals:
+                    soft_signals.append(sig)
+            elif stack.detection_method == "lockfile":
+                sig = f"stack:{stack.stack} via lockfile"
+                if sig not in hard_signals:
+                    hard_signals.append(sig)
+
+        # ── Entry point signals ───────────────────────────────────────────────
+        for ep in sm.entry_points:
+            if ep.source in _HARD_SOURCES or ep.reason == "console_script":
+                sig = f"entry:{ep.path} ({ep.reason or ep.source})"
+                if sig not in hard_signals:
+                    hard_signals.append(sig)
+            else:
+                sig = f"entry:{ep.path} ({ep.reason or ep.source})"
+                if sig not in soft_signals:
+                    soft_signals.append(sig)
+
+        # ── Ignored auxiliary paths ───────────────────────────────────────────
+        aux_dirs_found: set[str] = set()
+        for path in sm.file_paths:
+            norm = path.replace("\\", "/")
+            for prefix in _AUXILIARY_DIR_PREFIXES:
+                if norm.startswith(prefix):
+                    top = prefix.rstrip("/")
+                    aux_dirs_found.add(top)
+                    break
+
+        for aux in sorted(aux_dirs_found):
+            ignored_signals.append(f"aux_dir:{aux} (tooling, not analyzed as project source)")
+
+        # ── Anomaly: multiple stacks, ambiguous primary ───────────────────────
+        primary_stacks = [s for s in sm.stacks if s.primary]
+        heuristic_only = [s for s in sm.stacks if s.detection_method == "heuristic"]
+
+        if len(primary_stacks) == 0 and sm.stacks:
+            anomalies.append("No primary stack marked — multiple stacks detected with equal weight")
+        if len(primary_stacks) > 1:
+            names = ", ".join(s.stack for s in primary_stacks)
+            anomalies.append(f"Multiple stacks marked as primary: {names}")
+        if heuristic_only and not any(s.detection_method != "heuristic" for s in sm.stacks):
+            anomalies.append("All stacks detected via heuristic only — no manifest found")
+
+        # ── Anomaly: entry points all low-confidence ──────────────────────────
+        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)")
+
+        # ── Gaps ──────────────────────────────────────────────────────────────
+        if not sm.entry_points:
+            gaps.append(AnalysisGap(
+                area="entry_points",
+                reason="No entry point detected — project may use non-standard structure or be a library",
+                impact="high",
+            ))
+        elif all(ep.confidence == "low" for ep in sm.entry_points):
+            gaps.append(AnalysisGap(
+                area="entry_points",
+                reason="Entry points inferred from code patterns only, no manifest declaration found",
+                impact="medium",
+            ))
+
+        if not sm.stacks:
+            gaps.append(AnalysisGap(
+                area="stack",
+                reason="No stack detected — project may be infrastructure-only or use an unsupported language",
+                impact="high",
+            ))
+        elif all(s.detection_method == "heuristic" for s in sm.stacks):
+            gaps.append(AnalysisGap(
+                area="stack",
+                reason="Stack inferred from file extensions only — no manifest or lockfile found",
+                impact="medium",
+            ))
+
+        dep_summary = sm.dependency_summary
+        if dep_summary is None or not dep_summary.requested:
+            gaps.append(AnalysisGap(
+                area="dependencies",
+                reason="Dependencies not analyzed — run with --dependencies for full context",
+                impact="medium",
+            ))
+        elif dep_summary.requested and dep_summary.total_count == 0:
+            gaps.append(AnalysisGap(
+                area="dependencies",
+                reason="No dependencies found — project may have no external dependencies or manifest is non-standard",
+                impact="low",
+            ))
+
+        env_summary = sm.env_summary
+        if env_summary is None or not env_summary.requested:
+            gaps.append(AnalysisGap(
+                area="env",
+                reason="Environment variables not analyzed — run with --env-map for operational context",
+                impact="low",
+            ))
+
+        # ── Compute overall confidence ─────────────────────────────────────────
+        # Stack: use best manifest-detected stack, fall back to min
+        manifest_stacks = [s for s in sm.stacks if s.detection_method != "heuristic"]
+        stack_conf = (
+            _max_confidence([s.confidence for s in manifest_stacks])
+            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"])
+        overall = _min_confidence([stack_conf, ep_conf])
+
+        # Downgrade if gaps are severe
+        high_impact_gaps = [g for g in gaps if g.impact == "high"]
+        if high_impact_gaps:
+            overall = "low" if overall != "high" else "medium"
+
+        summary = ConfidenceSummary(
+            overall=overall,  # type: ignore[arg-type]
+            stack_confidence=stack_conf,  # type: ignore[arg-type]
+            entry_point_confidence=ep_conf,  # type: ignore[arg-type]
+            hard_signals=hard_signals,
+            soft_signals=soft_signals,
+            ignored_signals=ignored_signals,
+            anomalies=anomalies,
+        )
+        return summary, gaps
+
+
+def _min_confidence(values: list[str]) -> str:
+    rank = {"high": 2, "medium": 1, "low": 0}
+    if not values:
+        return "low"
+    return min(values, key=lambda v: rank.get(v, 0))
+
+
+def _max_confidence(values: list[str]) -> str:
+    rank = {"high": 2, "medium": 1, "low": 0}
+    if not values:
+        return "low"
+    return max(values, key=lambda v: rank.get(v, 0))