sourcecode 0.20.0__py3-none-any.whl → 0.21.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.21.0"

sourcecode/cli.py

@@ -163,6 +163,10 @@ def main(
     ),
 ) -> 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(
@@ -654,31 +658,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/prepare_context.py

@@ -1,197 +1,486 @@
+"""prepare_context.py — Task-aware context optimizer for LLM reasoning."""
+
 from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Optional
 
-from sourcecode.semantic_analyzer import SemanticAnalyzer
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Prompt templates
+# ─────────────────────────────────────────────────────────────────────────────
 
-# =========================
-# Output schema (simple)
-# =========================
+_EXPLAIN_PROMPT = """\
+You are an expert software engineer. Your task is to explain this project clearly.
 
-@dataclass
-class ContextSnippet:
-    file: str
-    symbol: str
-    code: str
-    reason: str
+## Project Summary
+
+{project_summary}
+
+{architecture_section}
+
+## Key Files
+
+{relevant_files_section}
+
+{dependencies_section}
+
+## Instructions
+
+1. Summarize what this project does and who it is for.
+2. Describe the main components and how they interact.
+3. Identify the primary entry point and the main execution flow.
+4. Highlight any non-obvious design decisions or constraints.
+"""
+
+_FIX_BUG_PROMPT = """\
+You are an expert debugger. Your task is to identify and fix a bug in this codebase.
+
+## Project Summary
+
+{project_summary}
+
+## Most Relevant Files
+
+{relevant_files_section}
+
+{suspected_areas_section}
+
+{code_notes_section}
+
+## Instructions
+
+1. Review the relevant files listed above, paying close attention to suspected areas.
+2. Identify the root cause of the bug.
+3. Propose a minimal, targeted fix with a concrete code patch.
+4. Explain why the fix is correct and what side effects to watch for.
+"""
+
+_REFACTOR_PROMPT = """\
+You are an expert software engineer focused on code quality. \
+Your task is to propose refactoring improvements.
+
+## Project Summary
+
+{project_summary}
+
+{architecture_section}
+
+## Files to Refactor
+
+{relevant_files_section}
+
+{improvement_opportunities_section}
+
+## Instructions
+
+1. Identify the top 3–5 most impactful refactoring opportunities.
+2. For each, describe the current problem, the proposed change, and the expected benefit.
+3. Prioritize changes that reduce complexity or improve testability.
+4. Do not suggest changes that break public APIs without noting the impact.
+"""
+
+_GENERATE_TESTS_PROMPT = """\
+You are an expert in software testing. Your task is to write tests for \
+untested or undertested areas of this codebase.
+
+## Project Summary
+
+{project_summary}
 
+## Files Needing Tests
+
+{relevant_files_section}
+
+{test_gaps_section}
+
+{dependencies_section}
+
+## Instructions
+
+1. Write unit tests for the most critical untested functions and classes.
+2. Cover edge cases and error paths, not just the happy path.
+3. Use the same testing framework already present in the project.
+4. Each test must have a clear name that describes exactly what it verifies.
+"""
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Task registry
+# ─────────────────────────────────────────────────────────────────────────────
 
 @dataclass
-class ContextFile:
+class TaskSpec:
+    name: str
+    goal: str
+    description: str
+    ranking_boosts: list[str]
+    ranking_penalties: list[str]
+    enable_code_notes: bool
+    enable_dependencies: bool
+    prompt_template: str
+    output_hint: str
+
+
+TASKS: dict[str, TaskSpec] = {
+    "explain": TaskSpec(
+        name="explain",
+        goal="Generate a comprehensive project summary for onboarding an LLM or developer.",
+        description="Analyze project structure, entry points, and key dependencies.",
+        ranking_boosts=["main", "cli", "app", "core", "index", "readme", "schema", "config"],
+        ranking_penalties=["test_", "spec_", ".min.", "__pycache__", "docs/"],
+        enable_code_notes=False,
+        enable_dependencies=True,
+        prompt_template=_EXPLAIN_PROMPT,
+        output_hint="project_summary, architecture_summary, relevant_files, key_dependencies",
+    ),
+    "fix-bug": TaskSpec(
+        name="fix-bug",
+        goal="Identify the most likely files and areas where a bug may be located.",
+        description="Rank files by annotation density, surface TODOs/FIXMEs/BUGs.",
+        ranking_boosts=["handler", "service", "middleware", "router", "controller",
+                        "processor", "parser", "validator"],
+        ranking_penalties=["test_", "spec_", ".min.", "__pycache__", "docs/"],
+        enable_code_notes=True,
+        enable_dependencies=False,
+        prompt_template=_FIX_BUG_PROMPT,
+        output_hint="relevant_files (ranked by risk), suspected_areas, code_notes_summary",
+    ),
+    "refactor": TaskSpec(
+        name="refactor",
+        goal="Highlight structural issues and improvement opportunities across the codebase.",
+        description="Surface large files, high-annotation areas, and architectural patterns.",
+        ranking_boosts=["core", "utils", "helper", "base", "common", "shared", "lib"],
+        ranking_penalties=["test_", ".min.", "__pycache__"],
+        enable_code_notes=True,
+        enable_dependencies=False,
+        prompt_template=_REFACTOR_PROMPT,
+        output_hint="relevant_files, improvement_opportunities, architecture_summary",
+    ),
+    "generate-tests": TaskSpec(
+        name="generate-tests",
+        goal="Identify untested source files and generate targeted test stubs.",
+        description="Find source files without matching test files and rank by complexity.",
+        ranking_boosts=["service", "handler", "controller", "router", "parser",
+                        "validator", "processor"],
+        ranking_penalties=[".min.", "__pycache__", "docs/"],
+        enable_code_notes=False,
+        enable_dependencies=True,
+        prompt_template=_GENERATE_TESTS_PROMPT,
+        output_hint="test_gaps, relevant_files (source without tests), key_dependencies",
+    ),
+}
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Output schema
+# ─────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class RelevantFile:
     path: str
-    role: str
+    role: str    # entrypoint | source | test
+    score: float
+    reason: str
 
 
 @dataclass
-class ContextResult:
+class TaskOutput:
     task: str
-    entry_points: List[Dict[str, str]]
-    relevant_files: List[ContextFile]
-    call_flow: List[Dict[str, Any]]
-    snippets: List[ContextSnippet]
-    tests: List[Dict[str, str]]
-    notes: List[str]
+    goal: str
+    project_summary: Optional[str]
+    architecture_summary: Optional[str]
+    relevant_files: list[RelevantFile]
+    suspected_areas: list[str]
+    improvement_opportunities: list[str]
+    test_gaps: list[str]
+    key_dependencies: list[dict[str, Any]]
+    code_notes_summary: Optional[dict[str, Any]]
+    limitations: list[str]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Builder
+# ─────────────────────────────────────────────────────────────────────────────
 
+_SOURCE_EXTENSIONS: frozenset[str] = frozenset({
+    ".py", ".js", ".ts", ".tsx", ".jsx", ".java", ".kt",
+    ".go", ".rs", ".rb", ".php", ".cs", ".dart",
+})
 
-# =========================
-# Core Builder
-# =========================
+_ALL_EXTENSIONS: frozenset[str] = _SOURCE_EXTENSIONS | frozenset({
+    ".md", ".toml", ".yaml", ".yml", ".json", ".xml",
+})
 
-class ContextBuilder:
+
+class TaskContextBuilder:
     def __init__(self, root: Path) -> None:
         self.root = root
-        self.analyzer = SemanticAnalyzer(root)
 
-    # -------------------------
-    # Public API
-    # -------------------------
+    def build(self, task_name: str) -> TaskOutput:
+        if task_name not in TASKS:
+            raise ValueError(
+                f"Unknown task '{task_name}'. Available: {', '.join(TASKS)}"
+            )
+        spec = TASKS[task_name]
+
+        # ── 1. Scan ────────────────────────────────────────────────────────
+        from sourcecode.scanner import FileScanner
+        from sourcecode.tree_utils import flatten_file_tree
+
+        scanner = FileScanner(self.root, max_depth=6)
+        file_tree = scanner.scan_tree()
+        manifests = scanner.find_manifests()
+        all_paths = [p.replace("\\", "/") for p in flatten_file_tree(file_tree)]
+
+        # ── 2. Detect stacks + entry points ───────────────────────────────
+        from sourcecode.detectors import ProjectDetector, build_default_detectors
+
+        detector = ProjectDetector(build_default_detectors())
+        stacks, entry_points, _ = detector.detect(self.root, file_tree, manifests)
+        stacks, project_type = detector.classify_results(file_tree, stacks, entry_points)
+
+        # ── 3. Summarize ───────────────────────────────────────────────────
+        from sourcecode.schema import AnalysisMetadata, SourceMap
+        from sourcecode.summarizer import ProjectSummarizer
+        from sourcecode.architecture_summary import ArchitectureSummarizer
+
+        sm = SourceMap(
+            metadata=AnalysisMetadata(analyzed_path=str(self.root)),
+            file_tree=file_tree,
+            stacks=stacks,
+            project_type=project_type,
+            entry_points=entry_points,
+        )
+        sm.file_paths = all_paths
+
+        project_summary = ProjectSummarizer(self.root).generate(sm)
+        architecture_summary = ArchitectureSummarizer(self.root).generate(sm)
+
+        # ── 4. Dependencies ────────────────────────────────────────────────
+        key_dependencies: list[dict[str, Any]] = []
+        limitations: list[str] = []
+
+        if spec.enable_dependencies:
+            from dataclasses import asdict
+            from sourcecode.dependency_analyzer import DependencyAnalyzer
+
+            dep_records, dep_summary = DependencyAnalyzer().analyze(self.root)
+            primary_eco = stacks[0].stack if stacks else ""
+            direct = [
+                d for d in dep_records
+                if d.scope != "transitive" and d.source in {"manifest", "lockfile"}
+            ]
+            direct.sort(key=lambda d: (0 if d.ecosystem == primary_eco else 1, d.name.lower()))
+            key_dependencies = [asdict(d) for d in direct[:15]]
+            limitations.extend(dep_summary.limitations)
+
+        # ── 5. Code notes ──────────────────────────────────────────────────
+        code_notes_summary: Optional[dict[str, Any]] = None
+        suspected_areas: list[str] = []
+        improvement_opportunities: list[str] = []
+
+        if spec.enable_code_notes:
+            from dataclasses import asdict
+            from sourcecode.code_notes_analyzer import CodeNotesAnalyzer
+
+            cn_notes, _cn_adrs, cn_summary = CodeNotesAnalyzer().analyze(self.root)
+            code_notes_summary = asdict(cn_summary)
+
+            if task_name == "fix-bug":
+                bug_kinds = {"FIXME", "BUG", "HACK", "XXX"}
+                counts: dict[str, int] = {}
+                for note in cn_notes:
+                    if note.kind in bug_kinds:
+                        counts[note.path] = counts.get(note.path, 0) + 1
+                suspected_areas = [
+                    f"{p} ({n} annotation{'s' if n > 1 else ''})"
+                    for p, n in sorted(counts.items(), key=lambda x: -x[1])[:8]
+                ]
+
+            elif task_name == "refactor":
+                ref_kinds = {"TODO", "DEPRECATED", "OPTIMIZE", "HACK"}
+                counts2: dict[str, int] = {}
+                for note in cn_notes:
+                    if note.kind in ref_kinds:
+                        counts2[note.path] = counts2.get(note.path, 0) + 1
+                improvement_opportunities = [
+                    f"{p}: {n} refactoring annotation{'s' if n > 1 else ''}"
+                    for p, n in sorted(counts2.items(), key=lambda x: -x[1])[:8]
+                ]
+
+        # ── 6. Rank files ──────────────────────────────────────────────────
+        entry_set = {ep.path for ep in entry_points}
+        test_set = {p for p in all_paths if self._is_test(p)}
+        source_set = {p for p in all_paths if not self._is_test(p) and self._is_source(p)}
+
+        relevant_files = self._rank_files(
+            task_name, spec, all_paths, entry_set, test_set
+        )
+
+        # ── 7. Test gaps (generate-tests only) ────────────────────────────
+        test_gaps: list[str] = []
+        if task_name == "generate-tests":
+            test_stems = {
+                Path(p).stem.removeprefix("test_").removesuffix("_test")
+                for p in test_set
+            }
+            untested = [
+                p for p in source_set
+                if Path(p).stem not in test_stems
+                and not any(pen in p for pen in spec.ranking_penalties)
+            ]
+            untested.sort(key=lambda p: (len(p.split("/")), p))
+            test_gaps = untested[:15]
+
+        return TaskOutput(
+            task=task_name,
+            goal=spec.goal,
+            project_summary=project_summary,
+            architecture_summary=architecture_summary,
+            relevant_files=relevant_files,
+            suspected_areas=suspected_areas,
+            improvement_opportunities=improvement_opportunities,
+            test_gaps=test_gaps,
+            key_dependencies=key_dependencies,
+            code_notes_summary=code_notes_summary,
+            limitations=limitations,
+        )
 
-    def prepare(self, task: str) -> ContextResult:
-        """
-        Entry point principal.
-        """
-        semantic = self.analyzer.analyze()
+    def render_prompt(self, output: TaskOutput) -> str:
+        spec = TASKS[output.task]
 
-        entry_points = self._detect_entrypoints(semantic)
-        relevant_files = self._select_relevant_files(task, entry_points)
-        snippets = self._extract_snippets(relevant_files)
-        tests = self._find_related_tests(relevant_files)
-        call_flow = self._build_call_flow(entry_points)
+        def _section(title: str, body: str) -> str:
+            return f"## {title}\n\n{body}" if body.strip() else ""
 
-        notes = self._generate_notes(task)
+        project_summary = output.project_summary or "No project summary available."
 
-        return ContextResult(
-            task=task,
-            entry_points=entry_points,
-            relevant_files=relevant_files,
-            call_flow=call_flow,
-            snippets=snippets,
-            tests=tests,
-            notes=notes,
+        architecture_section = _section(
+            "Architecture", output.architecture_summary or ""
         )
 
-    # -------------------------
-    # Heurísticas básicas
-    # -------------------------
+        relevant_files_section = "\n".join(
+            f"- `{f.path}` [{f.role}] — {f.reason}"
+            for f in output.relevant_files
+        ) or "No relevant files identified."
+
+        deps_lines = [
+            f"- {d['name']} "
+            f"{d.get('declared_version') or d.get('resolved_version') or '(unknown)'}"
+            for d in output.key_dependencies[:10]
+        ]
+        dependencies_section = _section("Key Dependencies", "\n".join(deps_lines))
+
+        suspected_areas_section = _section(
+            "Suspected Problem Areas",
+            "\n".join(f"- {a}" for a in output.suspected_areas),
+        )
 
-    def _detect_entrypoints(self, semantic: Any) -> List[Dict[str, str]]:
-        """
-        MVP: detecta cli.py o main functions
-        """
-        entrypoints: List[Dict[str, str]] = []
+        code_notes_section = ""
+        if output.code_notes_summary and output.code_notes_summary.get("total", 0) > 0:
+            by_kind = output.code_notes_summary.get("by_kind", {})
+            kinds_str = ", ".join(f"{k}: {v}" for k, v in by_kind.items() if v > 0)
+            top_files = ", ".join(output.code_notes_summary.get("top_files", [])[:5])
+            code_notes_section = _section(
+                "Code Annotations",
+                f"Total: {output.code_notes_summary['total']} ({kinds_str})\n"
+                f"Most annotated: {top_files}",
+            )
+
+        improvement_opportunities_section = _section(
+            "Improvement Opportunities",
+            "\n".join(f"- {o}" for o in output.improvement_opportunities),
+        )
 
-        for path in semantic.file_paths:
-            if path.endswith("cli.py") or path.endswith("__main__.py"):
-                entrypoints.append({
-                    "file": path,
-                    "symbol": "main",
-                    "reason": "CLI entrypoint"
-                })
+        test_gaps_section = _section(
+            "Untested Files",
+            "\n".join(f"- `{p}`" for p in output.test_gaps),
+        )
+
+        return spec.prompt_template.format(
+            project_summary=project_summary,
+            architecture_section=architecture_section,
+            relevant_files_section=relevant_files_section,
+            dependencies_section=dependencies_section,
+            suspected_areas_section=suspected_areas_section,
+            code_notes_section=code_notes_section,
+            improvement_opportunities_section=improvement_opportunities_section,
+            test_gaps_section=test_gaps_section,
+        ).strip()
 
-        return entrypoints
+    # ── Helpers ───────────────────────────────────────────────────────────────
 
-    def _select_relevant_files(
+    def _rank_files(
         self,
-        task: str,
-        entry_points: List[Dict[str, str]],
-    ) -> List[ContextFile]:
-        """
-        Heurística simple:
-        - incluir entrypoints
-        - incluir archivos con palabras clave del task
-        """
-        files: List[ContextFile] = []
-
-        for ep in entry_points:
-            files.append(ContextFile(path=ep["file"], role="entrypoint"))
-
-        keywords = task.lower().split()
-
-        for path in self.analyzer.scan.file_paths:  # fallback simple
-            if any(k in path.lower() for k in keywords):
-                files.append(ContextFile(path=path, role="matched"))
-
-        # deduplicar
-        seen = set()
-        unique = []
-        for f in files:
-            if f.path not in seen:
-                seen.add(f.path)
-                unique.append(f)
-
-        return unique[:8]
-
-    def _extract_snippets(self, files: List[ContextFile]) -> List[ContextSnippet]:
-        """
-        Extrae primeras ~30 líneas como snippet simple.
-        """
-        snippets: List[ContextSnippet] = []
-
-        for f in files:
-            abs_path = self.root / f.path
-            if not abs_path.exists():
+        task_name: str,
+        spec: TaskSpec,
+        all_paths: list[str],
+        entry_set: set[str],
+        test_set: set[str],
+    ) -> list[RelevantFile]:
+        scored: list[tuple[float, RelevantFile]] = []
+
+        for path in all_paths:
+            if Path(path).suffix.lower() not in _ALL_EXTENSIONS:
+                continue
+            if any(pen in path for pen in spec.ranking_penalties):
                 continue
 
-            try:
-                content = abs_path.read_text(encoding="utf-8", errors="ignore")
-            except Exception:
+            is_test = path in test_set
+            if is_test and task_name != "generate-tests":
                 continue
 
-            snippet = "\n".join(content.splitlines()[:30])
-
-            snippets.append(ContextSnippet(
-                file=f.path,
-                symbol="module",
-                code=snippet,
-                reason=f"contenido inicial de {f.role}"
-            ))
-
-        return snippets[:12]
-
-    def _find_related_tests(self, files: List[ContextFile]) -> List[Dict[str, str]]:
-        """
-        Busca tests por naming convention.
-        """
-        tests: List[Dict[str, str]] = []
-
-        for f in files:
-            name = Path(f.path).name
-            test_name = f"test_{name}"
-
-            test_path = self.root / "tests" / test_name
-            if test_path.exists():
-                tests.append({
-                    "file": f"tests/{test_name}",
-                    "reason": "posible test relacionado"
-                })
-
-        return tests
-
-    def _build_call_flow(self, entry_points: List[Dict[str, str]]) -> List[Dict[str, Any]]:
-        """
-        MVP: placeholder (hasta que uses call graph real)
-        """
-        flow: List[Dict[str, Any]] = []
-
-        for ep in entry_points:
-            flow.append({
-                "from": ep["symbol"],
-                "to": ["unknown"]
-            })
-
-        return flow
-
-    def _generate_notes(self, task: str) -> List[str]:
-        notes: List[str] = []
-
-        if "flag" in task or "--" in task:
-            notes.append("probablemente necesitas modificar argumentos CLI")
-        if "test" in task:
-            notes.append("asegúrate de actualizar tests relacionados")
-        if "refactor" in task:
-            notes.append("mantener compatibilidad hacia atrás")
-
-        return notes
+            score = 0.0
+            reasons: list[str] = []
+
+            if path in entry_set:
+                score += 3.0
+                reasons.append("entry point")
+
+            path_lower = path.lower()
+            for keyword in spec.ranking_boosts:
+                if keyword in path_lower:
+                    score += 1.5
+                    reasons.append(f"matches '{keyword}'")
+                    break
+
+            if is_test:
+                score += 2.0
+                reasons.append("existing test")
+            elif self._is_source(path):
+                score += 0.5
+                if not reasons:
+                    reasons.append("source file")
+
+            if score <= 0:
+                continue
+
+            role = (
+                "entrypoint" if path in entry_set
+                else ("test" if is_test else "source")
+            )
+            scored.append((score, RelevantFile(
+                path=path,
+                role=role,
+                score=round(score, 1),
+                reason=", ".join(reasons) if reasons else "source file",
+            )))
+
+        scored.sort(key=lambda x: -x[0])
+        return [f for _, f in scored[:15]]
+
+    def _is_test(self, path: str) -> bool:
+        name = Path(path).name.lower()
+        return (
+            name.startswith("test_")
+            or name.endswith("_test.py")
+            or name.endswith(".test.ts")
+            or name.endswith(".spec.ts")
+            or "/tests/" in path
+            or "/test/" in path
+            or "/spec/" in path
+        )
+
+    def _is_source(self, path: str) -> bool:
+        return Path(path).suffix.lower() in _SOURCE_EXTENSIONS

sourcecode/semantic_analyzer.py

@@ -70,12 +70,14 @@ class SemanticAnalyzer:
 
     def __init__(
         self,
+        root: Optional[Path] = None,
         *,
         max_files: int = _MAX_FILES,
         max_file_size: int = _MAX_FILE_SIZE,
         max_calls: int = _MAX_CALLS,
         max_symbols: int = _MAX_SYMBOLS,
     ) -> None:
+        self.root = root
         self.max_files = max_files
         self.max_file_size = max_file_size
         self.max_calls = max_calls

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 0.20.0
+Version: 0.21.0
 Summary: Genera un mapa de contexto estructurado de proyectos de software para agentes IA
 License: MIT
 Requires-Python: >=3.9
@@ -636,6 +636,75 @@ Combine flags for a comprehensive project handoff:
 sourcecode --compact --env-map --code-notes --git-context .
 ```
 
+## `prepare-context` — Task-aware context for LLMs
+
+`prepare-context` is a subcommand that builds a focused, task-specific context optimized for LLM reasoning. Instead of a full project dump, it returns only the data an LLM needs for a specific goal.
+
+> **Note:** Because `sourcecode` has a positional `PATH` argument, you must provide it explicitly before the subcommand:
+> ```bash
+> sourcecode . prepare-context <task>         # current directory
+> sourcecode /my/project prepare-context <task>
+> ```
+
+### Available tasks
+
+| Task | Goal | Output |
+|------|------|--------|
+| `explain` | Onboard an LLM to the project | `project_summary`, `architecture_summary`, `relevant_files`, `key_dependencies` |
+| `fix-bug` | Identify likely bug locations | `relevant_files` (ranked by risk), `suspected_areas`, `code_notes_summary` |
+| `refactor` | Surface improvement opportunities | `relevant_files`, `improvement_opportunities`, `architecture_summary` |
+| `generate-tests` | Find untested areas | `test_gaps`, `relevant_files` (source without tests), `key_dependencies` |
+
+### Usage
+
+```bash
+# List tasks with descriptions
+sourcecode . prepare-context --task-help
+
+# Explain the project
+sourcecode . prepare-context explain
+
+# Find bug areas, with a ready-to-paste LLM prompt
+sourcecode . prepare-context fix-bug --llm-prompt
+
+# Find untested files in a specific project
+sourcecode . prepare-context generate-tests --path /my/project
+
+# Preview what will be analyzed (no analysis run)
+sourcecode . prepare-context refactor --dry-run
+```
+
+### Output format
+
+```json
+{
+  "task": "fix-bug",
+  "goal": "Identify the most likely files and areas where a bug may be located.",
+  "project_summary": "CLI en Python (Typer). Entry points: src/cli.py. 4 dependencias.",
+  "architecture_summary": null,
+  "relevant_files": [
+    { "path": "src/handler.py", "role": "source", "score": 2.0, "reason": "matches 'handler'" },
+    { "path": "src/cli.py",     "role": "entrypoint", "score": 3.0, "reason": "entry point" }
+  ],
+  "suspected_areas": ["src/handler.py (2 annotations)", "src/parser.py (1 annotation)"],
+  "code_notes_summary": { "total": 5, "by_kind": { "FIXME": 3, "BUG": 2 }, "top_files": ["src/handler.py"] }
+}
+```
+
+### `--llm-prompt`
+
+Add `--llm-prompt` to include a ready-to-use prompt that you can paste directly into any LLM:
+
+```bash
+sourcecode . prepare-context explain --llm-prompt | jq -r '.llm_prompt'
+```
+
+The prompt is task-specific and includes the project context, relevant files, and concrete instructions for the LLM.
+
+### Task auto-selection with `--agent`
+
+For zero-config usage, `--agent` on the main command automatically selects the right flags for the project type. For task-aware context, use `prepare-context` explicitly with the task that matches your goal.
+
 ## Development
 
 Editable install with development dependencies:

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

@@ -1,8 +1,8 @@
-sourcecode/__init__.py,sha256=dzKShGXdjPL26nODQDz1WcEo-41T1Cel-cSD0xF9gPg,100
+sourcecode/__init__.py,sha256=Wl0aL5XpGhZsWRJOan0FtriAIMa21IHgxlCXLjVcxOI,100
 sourcecode/architecture_analyzer.py,sha256=zxgqeqn2FhIUDn06X-whjGKiXbrHFkRlzZcr2zKd0Gw,16874
 sourcecode/architecture_summary.py,sha256=r9IciS9z-7h8xpiME7DKBLhLV36xzXtSzbZ1cRDWklo,11709
 sourcecode/classifier.py,sha256=fcp2wIq198wq3Rsh_bDmZIK_W5UI6FEL5oqm1RrQfpA,6846
-sourcecode/cli.py,sha256=_FKnSNHqtLH6wJ2IA_7NR7-TUICCitildIMpSZt4IP8,26360
+sourcecode/cli.py,sha256=1ozxlC43rd2boOZbARb3l2csVpTFiBw8DRDzCtLywTI,29065
 sourcecode/code_notes_analyzer.py,sha256=rRd8bFYV0krjlxxQV0wenwE9K7pVpUQSR7KvSvUQKw4,9226
 sourcecode/coverage_parser.py,sha256=q0LeZJaX1bnntLu-ImksdBsMlpsVmk_iUfSaB4eaJGo,19702
 sourcecode/dependency_analyzer.py,sha256=2TYBIpenhfWf_TVBZZfq3T0SHFv8xCKFIyn1XnFHG6s,48146
@@ -11,11 +11,11 @@ sourcecode/env_analyzer.py,sha256=JZxBOuIxnM0xw0IaJFL6LiPJBErL848L3XoTOHGBqZI,13
 sourcecode/git_analyzer.py,sha256=S9PGt8RDasBQYQUsZh9-H_KWVlPvzwR4jgM7TKN9ZCk,7643
 sourcecode/graph_analyzer.py,sha256=cxl7Xb88aGxIVOCsatZJAE1CtgXGzIbJfqytV-9kkFs,45172
 sourcecode/metrics_analyzer.py,sha256=4uh11v-Q0gdrN87BOxuFWUym3N3AOkOuy21K5N8peB8,20126
-sourcecode/prepare_context.py,sha256=X43dEPe2cb7uMwlpQwVJMe0rQIZ0juaJ7H3F37sPbNc,5371
+sourcecode/prepare_context.py,sha256=yPRohYZ3wvX156GQSo1vYuoCDBIG3uy3G-3DdNbGHKU,19271
 sourcecode/redactor.py,sha256=xuGcadGEHaPw4qZXlMDvzMCsr4VOkdp3oBQptHyJk8c,2884
 sourcecode/scanner.py,sha256=Ga4jDRAOhkcwlRmlE2ko6cE39qKy0aI4iE1lGBWmAlk,6410
 sourcecode/schema.py,sha256=dnNdnQxJtBv0PRVWi6-xnpr16dj6IsUGbso9PeeEolA,15743
-sourcecode/semantic_analyzer.py,sha256=SRQSGJzEi4ZsGvb7U3qvnRiKHabz4hvIzCqiG92x9K8,79349
+sourcecode/semantic_analyzer.py,sha256=asQfJf-EhzYaOTA-iMuZsrVXtbW7SV2WEKCxgsxa88Y,79413
 sourcecode/serializer.py,sha256=ck0gK3PV-rY5UrAvykKh8x56Lb1135J23xzbcEsvUW8,13772
 sourcecode/summarizer.py,sha256=2Yz5xJ1bhtJLlrUpKcd74wijypRRo9GJmGT8u971EW0,11572
 sourcecode/tree_utils.py,sha256=xla45Whq24j6U9kEgTztJXkMpmOEDieAulKxP3nl89s,935
@@ -39,7 +39,7 @@ sourcecode/detectors/rust.py,sha256=V23NO6Y8NsrhrUlGC2feUEcNK63hf3gc1y3jI4tes1Q,
 sourcecode/detectors/systems.py,sha256=nYaKbGDFu0EOXFcd_1doWFT3tTUdkbxc2DjHUF5TcqQ,1627
 sourcecode/detectors/terraform.py,sha256=cxORPR_zVLOJpHlh4e9JnFpkQsn_UnqMMom5yG65hZ4,1693
 sourcecode/detectors/tooling.py,sha256=hIvop80No22pqyGVJ32NKliSdjkHRePQkIRroqG01bY,1875
-sourcecode-0.20.0.dist-info/METADATA,sha256=KzFy_Iwj3H4eEWomjdYtE_XMb94isl55ekXSIHKOQ58,27548
-sourcecode-0.20.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-0.20.0.dist-info/entry_points.txt,sha256=voDtdlGU2-jR3wCZpQoOls_0eUKaDVCKIfajGHFDATs,50
-sourcecode-0.20.0.dist-info/RECORD,,
+sourcecode-0.21.0.dist-info/METADATA,sha256=9gqiONC_cEbjYwoYox60Dx-2m8qzP3KwkNRqU8kis88,30326
+sourcecode-0.21.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-0.21.0.dist-info/entry_points.txt,sha256=voDtdlGU2-jR3wCZpQoOls_0eUKaDVCKIfajGHFDATs,50
+sourcecode-0.21.0.dist-info/RECORD,,