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

sourcecode/__init__.py

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

sourcecode/architecture_summary.py

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

sourcecode/classifier.py

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

sourcecode/cli.py

@@ -78,7 +78,12 @@ def main(
     no_tree: bool = typer.Option(
         False,
         "--no-tree",
-        help="Suprimir file_tree y file_paths del output (ideal con --dependencies en proyectos grandes)",
+        help="Suprimir file_tree y file_paths del output (ahora deprecado: el arbol ya no se incluye por defecto)",
+    ),
+    tree: bool = typer.Option(
+        False,
+        "--tree",
+        help="Incluir file_tree completo y file_paths en el output (capa deep-dive)",
     ),
     no_redact: bool = typer.Option(
         False,
@@ -114,7 +119,7 @@ def main(
     full_metrics: bool = typer.Option(
         False,
         "--full-metrics",
-        help="Incluir metricas de calidad: LOC, simbolos, complejidad, tests y cobertura por fichero",
+        help="Auditoria tecnica: LOC, simbolos, complejidad ciclomatica y cobertura por fichero. No incluido en --agent (uso: CI, code review, no context principal para agentes IA)",
     ),
     semantics: bool = typer.Option(
         False,
@@ -159,10 +164,14 @@ 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."""
+    # When a subcommand (e.g. prepare-context) is invoked, skip the main analysis.
+    if ctx.invoked_subcommand is not None:
+        return
+
     # Validar formato
     if format not in FORMAT_CHOICES:
         typer.echo(
@@ -212,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)
@@ -231,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()
@@ -558,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]
 
@@ -612,24 +623,23 @@ def main(
     for _finding in validate_cross_analyzer_consistency(sm, strict=False):
         typer.echo(f"[consistency] {_finding}", err=True)
 
-    # 4. Serializar (con o sin modo compact)
-    if compact:
+    # 4. Serializar
+    if agent:
+        data = agent_view(sm)
+        if not no_redact:
+            data = redact_dict(data)
+        content = json.dumps(data, indent=2, ensure_ascii=False)
+    elif compact:
         data = compact_view(sm, no_tree=no_tree)
-        # Aplicar redaccion sobre el dict del compact view
         if not no_redact:
             data = redact_dict(data)
         content = json.dumps(data, indent=2, ensure_ascii=False)
     else:
-        # Redactar sobre el dict serializado (SEC-01, SEC-03)
-        raw_dict = asdict(sm)
-        if no_tree:
-            raw_dict.pop("file_tree", None)
-            raw_dict.pop("file_paths", None)
+        raw_dict = standard_view(sm, include_tree=tree and not no_tree)
         if not no_redact:
             raw_dict = redact_dict(raw_dict)
 
         if format == "yaml":
-            # Para YAML, serializar el dict directamente con ruamel.yaml
             from io import StringIO
 
             from ruamel.yaml import YAML
@@ -654,31 +664,103 @@ def main(
 
 @app.command("prepare-context")
 def prepare_context_cmd(
-    task: str = typer.Argument(..., help="Descripción de la tarea"),
-    path: Path = typer.Option(".", "--path", "-p", help="Directorio del proyecto"),
+    task: Optional[str] = typer.Argument(
+        None,
+        help="Task: explain | fix-bug | refactor | generate-tests",
+    ),
+    path: Path = typer.Option(
+        Path("."),
+        "--path", "-p",
+        help="Project directory to analyze (default: current directory)",
+    ),
+    llm_prompt: bool = typer.Option(
+        False,
+        "--llm-prompt",
+        help="Append a ready-to-use LLM prompt to the output",
+    ),
+    task_help: bool = typer.Option(
+        False,
+        "--task-help",
+        help="List available tasks with descriptions and exit",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Show what would be analyzed without running it",
+    ),
 ) -> None:
-    """Prepara contexto mínimo optimizado para que un LLM modifique el código."""
-    from dataclasses import asdict
+    """Prepare task-aware context optimized for LLM reasoning.
+
+    \b
+    Note: PATH must be provided before the subcommand (default: '.'):
+      sourcecode . prepare-context explain
+      sourcecode . prepare-context fix-bug --path /my/project
+      sourcecode . prepare-context generate-tests --llm-prompt
+      sourcecode . prepare-context --task-help
+    """
+    from sourcecode.prepare_context import TASKS, TaskContextBuilder
+
+    if task_help:
+        typer.echo("Available tasks:\n")
+        for name, spec in TASKS.items():
+            typer.echo(f"  {name:<20} {spec.description}")
+            typer.echo(f"  {'':20} Output: {spec.output_hint}\n")
+        raise typer.Exit()
 
-    from sourcecode.prepare_context import ContextBuilder
+    if task is None:
+        typer.echo(
+            f"Error: task is required. Available: {', '.join(TASKS)}\n"
+            "Use --task-help for descriptions.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
 
-    target = path.resolve()
+    if task not in TASKS:
+        typer.echo(
+            f"Error: unknown task '{task}'. Available: {', '.join(TASKS)}",
+            err=True,
+        )
+        raise typer.Exit(code=1)
 
+    target = path.resolve()
     if not target.exists() or not target.is_dir():
         typer.echo(f"Error: '{target}' no es un directorio válido.", err=True)
         raise typer.Exit(code=1)
 
-    builder = ContextBuilder(target)
-    result = builder.prepare(task)
-
-    out = {
-        "task": result.task,
-        "entry_points": result.entry_points,
-        "relevant_files": [asdict(f) for f in result.relevant_files],
-        "call_flow": result.call_flow,
-        "snippets": [asdict(s) for s in result.snippets],
-        "tests": result.tests,
-        "notes": result.notes,
+    if dry_run:
+        spec = TASKS[task]
+        typer.echo(f"task:        {task}")
+        typer.echo(f"goal:        {spec.goal}")
+        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'}")
+        typer.echo(f"output:      {spec.output_hint}")
+        raise typer.Exit()
+
+    from dataclasses import asdict
+
+    builder = TaskContextBuilder(target)
+    output = builder.build(task)
+
+    out: dict[str, Any] = {
+        "task": output.task,
+        "goal": output.goal,
+        "project_summary": output.project_summary,
+        "architecture_summary": output.architecture_summary,
+        "relevant_files": [asdict(f) for f in output.relevant_files],
+        "key_dependencies": output.key_dependencies,
     }
+    if output.suspected_areas:
+        out["suspected_areas"] = output.suspected_areas
+    if output.improvement_opportunities:
+        out["improvement_opportunities"] = output.improvement_opportunities
+    if output.test_gaps:
+        out["test_gaps"] = output.test_gaps
+    if output.code_notes_summary:
+        out["code_notes_summary"] = output.code_notes_summary
+    if output.limitations:
+        out["limitations"] = output.limitations
+    if llm_prompt:
+        out["llm_prompt"] = builder.render_prompt(output)
 
     typer.echo(json.dumps(out, indent=2, ensure_ascii=False))

sourcecode/dependency_analyzer.py

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

sourcecode/detectors/base.py

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

sourcecode/detectors/heuristic.py

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

sourcecode/detectors/nodejs.py

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

sourcecode/detectors/project.py

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

sourcecode/detectors/python.py

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