sourcecode 0.19.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.19.0"
+__version__ = "0.21.0"

sourcecode/cli.py

@@ -75,6 +75,11 @@ def main(
         "--graph-edges",
         help="Tipos de arista para `--graph-modules` separados por comas: imports,calls,contains,extends",
     ),
+    no_tree: bool = typer.Option(
+        False,
+        "--no-tree",
+        help="Suprimir file_tree y file_paths del output (ideal con --dependencies en proyectos grandes)",
+    ),
     no_redact: bool = typer.Option(
         False,
         "--no-redact",
@@ -151,8 +156,17 @@ def main(
         "--code-notes",
         help="Extraer anotaciones TODO/FIXME/HACK/NOTE/DEPRECATED/WARNING/BUG/XXX/OPTIMIZE con ubicacion y simbolo envolvente, y detectar ADRs en docs/decisions/, docs/adr/ y similares",
     ),
+    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",
+    ),
 ) -> 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(
@@ -221,6 +235,16 @@ 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
+    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)
+
     scanner = FileScanner(target, max_depth=effective_depth)
     raw_tree = scanner.scan_tree()
 
@@ -594,7 +618,7 @@ def main(
 
     # 4. Serializar (con o sin modo compact)
     if compact:
-        data = compact_view(sm)
+        data = compact_view(sm, no_tree=no_tree)
         # Aplicar redaccion sobre el dict del compact view
         if not no_redact:
             data = redact_dict(data)
@@ -602,6 +626,9 @@ def main(
     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)
         if not no_redact:
             raw_dict = redact_dict(raw_dict)
 
@@ -631,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/dependency_analyzer.py

@@ -34,6 +34,7 @@ class DependencyAnalyzer:
             self._analyze_go,
             self._analyze_dotnet,
             self._analyze_java,
+            self._analyze_gradle,
         ):
             handler_records, handler_limitations = handler(root)
             records.extend(replace(record, workspace=workspace) for record in handler_records)
@@ -925,6 +926,47 @@ class DependencyAnalyzer:
                 result.append(resolved)
         return self._dedupe(result)
 
+    def _parse_maven_properties(self, root_elem: ET.Element, ns: str) -> dict[str, str]:
+        properties: dict[str, str] = {}
+        props_elem = root_elem.find(f"{ns}properties")
+        if props_elem is not None:
+            for prop in props_elem:
+                tag = prop.tag.replace(ns, "") if ns else prop.tag
+                if prop.text:
+                    properties[tag] = prop.text.strip()
+        return properties
+
+    def _resolve_maven_version(self, version_raw: Optional[str], properties: dict[str, str]) -> Optional[str]:
+        if not version_raw:
+            return None
+        if not version_raw.startswith("${"):
+            return version_raw
+        prop_name = version_raw[2:-1] if version_raw.endswith("}") else None
+        if prop_name and prop_name in properties:
+            return properties[prop_name]
+        return None
+
+    def _parse_dependency_management(
+        self, root_elem: ET.Element, ns: str, properties: dict[str, str]
+    ) -> dict[str, str]:
+        dm_versions: dict[str, str] = {}
+        dm_elem = root_elem.find(f"{ns}dependencyManagement")
+        if dm_elem is None:
+            return dm_versions
+        deps_elem = dm_elem.find(f"{ns}dependencies")
+        if deps_elem is None:
+            return dm_versions
+        for dep in deps_elem.findall(f"{ns}dependency"):
+            group_id = (dep.findtext(f"{ns}groupId") or "").strip()
+            artifact_id = (dep.findtext(f"{ns}artifactId") or "").strip()
+            if not group_id or not artifact_id:
+                continue
+            version_raw = (dep.findtext(f"{ns}version") or "").strip() or None
+            resolved = self._resolve_maven_version(version_raw, properties)
+            if resolved:
+                dm_versions[f"{group_id}:{artifact_id}"] = resolved
+        return dm_versions
+
     def _analyze_java(self, root: Path) -> tuple[list[DependencyRecord], list[str]]:
         pom = root / "pom.xml"
         if not pom.exists():
@@ -938,6 +980,9 @@ class DependencyAnalyzer:
         ns_match = re.match(r"\{[^}]+\}", root_elem.tag)
         ns = ns_match.group(0) if ns_match else ""
 
+        properties = self._parse_maven_properties(root_elem, ns)
+        dm_versions = self._parse_dependency_management(root_elem, ns, properties)
+
         records: list[DependencyRecord] = []
         deps_elem = root_elem.find(f"{ns}dependencies")
         if deps_elem is None:
@@ -949,8 +994,9 @@ class DependencyAnalyzer:
             if not group_id or not artifact_id:
                 continue
             version_raw = (dep.findtext(f"{ns}version") or "").strip() or None
-            # Versiones interpoladas con propiedades Maven (${...}) no son resolvibles estáticamente
-            declared = version_raw if version_raw and not version_raw.startswith("${") else None
+            declared = self._resolve_maven_version(version_raw, properties)
+            if declared is None:
+                declared = dm_versions.get(f"{group_id}:{artifact_id}")
             scope_text = (dep.findtext(f"{ns}scope") or "compile").strip().lower()
             scope = "dev" if scope_text == "test" else "direct"
             records.append(
@@ -969,6 +1015,115 @@ class DependencyAnalyzer:
             limitations.append("java: pom.xml sin dependencias parseables (puede usar BOM o propiedades)")
         return records, limitations
 
+    def _analyze_gradle(self, root: Path) -> tuple[list[DependencyRecord], list[str]]:
+        for filename in ("build.gradle", "build.gradle.kts"):
+            gradle_file = root / filename
+            if gradle_file.exists():
+                try:
+                    content = gradle_file.read_text(encoding="utf-8", errors="replace")
+                except OSError:
+                    return [], [f"gradle: error al leer {filename}"]
+                props = self._parse_gradle_properties(root, content)
+                records = self._parse_gradle_dependencies(content, props, filename)
+                return records, ["gradle: sin lockfile compatible; dependencias transitivas no disponibles"]
+        return [], []
+
+    def _parse_gradle_properties(self, root: Path, content: str) -> dict[str, str]:
+        props: dict[str, str] = {}
+        # gradle.properties file (key=value format)
+        gp = root / "gradle.properties"
+        if gp.exists():
+            try:
+                for line in gp.read_text(encoding="utf-8", errors="replace").splitlines():
+                    stripped = line.strip()
+                    if stripped and not stripped.startswith("#") and "=" in stripped:
+                        k, _, v = stripped.partition("=")
+                        props[k.strip()] = v.strip()
+            except OSError:
+                pass
+        # Variables declared in the build file itself.
+        # Match: val/var/def x = "v", or bare x = "v" anywhere (ext blocks, top-level).
+        # Negative lookbehind (?<![.\w]) prevents matching mid-expression (e.g. obj.field = "v").
+        for m in re.finditer(r"""(?:(?:val|var|def)\s+)?(?<![.\w])(\w+)\s*=\s*["']([^"']+)["']""", content):
+            props.setdefault(m.group(1), m.group(2))
+        return props
+
+    def _resolve_gradle_version(self, version_raw: Optional[str], props: dict[str, str]) -> Optional[str]:
+        if not version_raw:
+            return None
+        # ${varName} — Groovy string interpolation
+        m = re.fullmatch(r"\$\{(\w+)\}", version_raw)
+        if m:
+            return props.get(m.group(1))
+        # $varName — Kotlin string interpolation
+        m = re.fullmatch(r"\$(\w+)", version_raw)
+        if m:
+            return props.get(m.group(1))
+        return version_raw
+
+    def _parse_gradle_dependencies(
+        self, content: str, props: dict[str, str], manifest_path: str
+    ) -> list[DependencyRecord]:
+        _DIRECT = frozenset({
+            "implementation", "api", "compileOnly", "runtimeOnly", "compile", "provided",
+            "compileClasspath", "runtimeClasspath",
+        })
+        _DEV = frozenset({
+            "testImplementation", "testRuntimeOnly", "testCompileOnly", "testApi",
+            "testCompile", "androidTestImplementation", "annotationProcessor", "kapt",
+            "debugImplementation", "releaseImplementation",
+        })
+        all_scopes = _DIRECT | _DEV
+        records: list[DependencyRecord] = []
+
+        # String notation: scope("group:artifact") or scope("group:artifact:version")
+        str_pat = re.compile(
+            r"""(\w+)\s*\(?\s*["']([A-Za-z][\w.\-]*:[A-Za-z][\w.\-]*)(?::([^"'\s)]+))?["']"""
+        )
+        for m in str_pat.finditer(content):
+            scope_kw = m.group(1)
+            if scope_kw not in all_scopes:
+                continue
+            parts = m.group(2).split(":")
+            if len(parts) < 2:
+                continue
+            group_id, artifact_id = parts[0].strip(), parts[1].strip()
+            if not group_id or not artifact_id:
+                continue
+            version = self._resolve_gradle_version(m.group(3), props)
+            records.append(DependencyRecord(
+                name=f"{group_id}:{artifact_id}",
+                ecosystem="java",
+                scope="dev" if scope_kw in _DEV else "direct",
+                declared_version=version,
+                source="manifest",
+                manifest_path=manifest_path,
+            ))
+
+        # Map notation: scope(group: "g", name: "a", version: "v")  — Groovy uses ':', Kotlin uses '='
+        map_pat = re.compile(
+            r"""(\w+)\s*\(?\s*group\s*[=:]\s*["']([^"']+)["']\s*,\s*name\s*[=:]\s*["']([^"']+)["']"""
+            r"""(?:\s*,\s*version\s*[=:]\s*["']([^"']+)["'])?"""
+        )
+        for m in map_pat.finditer(content):
+            scope_kw = m.group(1)
+            if scope_kw not in all_scopes:
+                continue
+            group_id, artifact_id = m.group(2).strip(), m.group(3).strip()
+            if not group_id or not artifact_id:
+                continue
+            version = self._resolve_gradle_version(m.group(4), props)
+            records.append(DependencyRecord(
+                name=f"{group_id}:{artifact_id}",
+                ecosystem="java",
+                scope="dev" if scope_kw in _DEV else "direct",
+                declared_version=version,
+                source="manifest",
+                manifest_path=manifest_path,
+            ))
+
+        return self._dedupe(records)
+
     def _load_yaml_file(self, path: Path) -> Optional[dict[str, Any]]:
         if not path.exists():
             return None

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/serializer.py

@@ -54,27 +54,31 @@ def to_yaml(sm: SourceMap) -> str:
     return stream.getvalue()
 
 
-def compact_view(sm: SourceMap) -> dict[str, Any]:
+def compact_view(sm: SourceMap, *, no_tree: bool = False) -> dict[str, Any]:
     """Proyeccion compacta del SourceMap (~500-700 tokens).
 
     Incluye: schema_version, project_type, stacks, entry_points,
     project_summary (siempre), architecture_summary (siempre),
-    dependency_summary (cuando requested=True),
-    file_tree_depth1 (backward compat).
+    dependency_summary + key_dependencies (cuando requested=True),
+    file_tree_depth1 (omitido si no_tree=True).
 
     Excluye: dependencies (lista larga), docs, module_graph.
     """
-    depth1: dict[str, Any] = {}
-    for name, value in sm.file_tree.items():
-        if isinstance(value, dict):
-            depth1[name] = {}
-        else:
-            depth1[name] = None
+    depth1: dict[str, Any] | None = None
+    if not no_tree:
+        depth1 = {}
+        for name, value in sm.file_tree.items():
+            if isinstance(value, dict):
+                depth1[name] = {}
+            else:
+                depth1[name] = None
 
     dep_summary_dict: Any = None
+    key_deps: Any = None
     if sm.dependency_summary is not None and sm.dependency_summary.requested:
         dep_summary_dict = asdict(sm.dependency_summary)
         dep_summary_dict.pop("dependencies", None)
+        key_deps = [asdict(d) for d in sm.key_dependencies]
 
     env_summary_dict: Any = None
     if sm.env_summary is not None and sm.env_summary.requested:
@@ -84,18 +88,21 @@ def compact_view(sm: SourceMap) -> dict[str, Any]:
     if sm.code_notes_summary is not None and sm.code_notes_summary.requested:
         code_notes_summary_dict = asdict(sm.code_notes_summary)
 
-    return {
+    result: dict[str, Any] = {
         "schema_version": sm.metadata.schema_version,
         "project_type": sm.project_type,
         "project_summary": sm.project_summary,
         "architecture_summary": sm.architecture_summary,
         "stacks": [asdict(stack) for stack in sm.stacks],
         "entry_points": [asdict(entry_point) for entry_point in sm.entry_points],
-        "file_tree_depth1": depth1,
         "dependency_summary": dep_summary_dict,
+        "key_dependencies": key_deps,
         "env_summary": env_summary_dict,
         "code_notes_summary": code_notes_summary_dict,
     }
+    if not no_tree:
+        result["file_tree_depth1"] = depth1
+    return result
 
 
 def normalize_source_map(sm: SourceMap) -> SourceMap:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 0.19.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
@@ -81,7 +81,7 @@ sourcecode --version
 
 ## What It Detects
 
-- Stacks: Node.js, Python, Go, Rust, Java, PHP, Ruby, and Dart.
+- Stacks: Node.js, Python, Go, Rust, Java (Maven `pom.xml` and Gradle `build.gradle`/`build.gradle.kts`), PHP, Ruby, and Dart.
 - Frameworks associated with each stack when enough signals are present.
 - `project_type`: `webapp`, `api`, `library`, `cli`, `fullstack`, `monorepo`, or `unknown`.
 - Relevant `entry_points`, such as `main.py`, `cmd/api/main.go`, or `app/page.tsx`.
@@ -111,6 +111,8 @@ sourcecode --version
 | `--env-map` | off | Map all environment variables referenced in source code: key name, required/optional status, inferred type (`string`, `int`, `bool`, `url`, `path`, `enum`), functional category (`database`, `auth`, `cache`, `storage`, `service`, `observability`, `feature_flag`, `server`, `general`), default value when present, and source file locations. Supplements with descriptions from `.env.example`, `.env.sample`, and similar reference files. |
 | `--code-notes` | off | Extract inline code annotations — `TODO`, `FIXME`, `HACK`, `NOTE`, `DEPRECATED`, `WARNING`, `XXX`, `BUG`, `OPTIMIZE` — with file path, line number, annotation text, and the nearest enclosing function or class. Also detects Architecture Decision Records (ADRs) in `docs/decisions/`, `docs/adr/`, `adr/`, and similar directories, extracting title, status, and summary. |
 | `--depth INTEGER` | `4` | Maximum file tree depth. Range: 1–20. |
+| `--no-tree` | off | Suppress `file_tree`, `file_paths` (and `file_tree_depth1` in `--compact`) from the output. Ideal with `--dependencies` on large projects to get dependency data without a multi-thousand-line file tree. |
+| `--agent` | off | Agent mode: auto-selects `--compact --dependencies --env-map --code-notes` and adds `--no-tree` automatically for Java/Gradle projects or large repositories. Prints selected flags to stderr. Can be combined with other flags (e.g. `--agent --git-context`). |
 | `--no-redact` | off | Disable secret redaction (enabled by default). |
 | `--version` | — | Show version and exit. |
 
@@ -123,8 +125,8 @@ The full schema (`SourceMap`) includes the following fields:
 | Field | Type | Description |
 |-------|------|-------------|
 | `metadata` | object | Schema version, timestamp, `sourcecode` version, and analyzed path. |
-| `file_tree` | object | Repository tree where `null` represents a file and `{}` represents a directory. |
-| `file_paths` | array | Flat list of all project paths derived from `file_tree`, with forward-slash separators. Always present; respects `--depth`. |
+| `file_tree` | object | Repository tree where `null` represents a file and `{}` represents a directory. Suppressed when `--no-tree` is active. |
+| `file_paths` | array | Flat list of all project paths derived from `file_tree`, with forward-slash separators. Respects `--depth`. Suppressed when `--no-tree` is active. |
 | `project_summary` | string\|null | Deterministic natural-language description of the project. Includes: manifest/README description when available, detected architecture pattern (`layered`, `mvc`, `hexagonal`, `fullstack`), business domain names inferred from directory structure, entry points (when no domains are detected), and dependency count. Present when stacks are detected. |
 | `architecture_summary` | string\|null | Static summary of the main execution flow, orchestrated modules, and output produced by the project. Present when enough structural evidence is available. |
 | `stacks` | array | Stack detections with confidence, frameworks, manifests, `primary`, `root`, `workspace`, and `signals`. |
@@ -223,7 +225,7 @@ ADR detection looks for Markdown files in `docs/decisions/`, `docs/adr/`, `adr/`
 
 ## Compact Mode
 
-`--compact` returns a reduced JSON view optimized for LLM prompts (~500-700 tokens). It excludes the full `dependencies` list, `docs`, and `module_graph`, while retaining the fields most useful for project orientation. When optional flags are also active, their summaries are included: `dependency_summary` (with `--dependencies`), `env_summary` (with `--env-map`), and `code_notes_summary` (with `--code-notes`).
+`--compact` returns a reduced JSON view optimized for LLM prompts. It excludes the full `dependencies` list, `docs`, and `module_graph`, while retaining the fields most useful for project orientation. When optional flags are also active, their summaries are included: `dependency_summary` + `key_dependencies` (with `--dependencies`), `env_summary` (with `--env-map`), and `code_notes_summary` (with `--code-notes`). Adding `--no-tree` further removes `file_tree_depth1`, bringing the output to ~500-800 tokens depending on how many flags are active.
 
 Real output from a Python FastAPI project:
 
@@ -266,7 +268,7 @@ Real output from a Python FastAPI project:
 }
 ```
 
-When `--compact --dependencies` is used, `dependency_summary` is populated instead of `null`.
+When `--compact --dependencies` is used, `dependency_summary` is populated and `key_dependencies` lists the top-15 direct dependencies with resolved versions. Add `--no-tree` to drop `file_tree_depth1` for the smallest possible context footprint.
 
 ## Docs Mode
 
@@ -444,15 +446,27 @@ In a monorepo, each stack includes its own `root` and `workspace`, and one of th
 
 Different modes optimize for different tradeoffs between context size and depth of information.
 
-**`--compact` — minimal context (~500-700 tokens)**
+**`--agent` — zero-config mode for AI pipelines**
+
+Best for: running `sourcecode` from inside an agent without knowing the project in advance. Auto-selects the right flag combination based on detected stack and project size.
+
+```bash
+sourcecode --agent .
+sourcecode --agent --git-context .   # add git context on top of auto-selected flags
+```
+
+On a Java/Gradle project the output is: `--compact --dependencies --env-map --code-notes --no-tree` (~800 tokens). On a Node/Python project: same without `--no-tree` (~900 tokens including depth-1 tree). Selected flags are always printed to stderr so the agent can log them.
+
+**`--compact` — minimal context**
 
 Best for: initial orientation, deciding what to explore next, fast handoffs between agents.
 
-Includes: `project_summary` (instant project description), `architecture_summary` (execution-oriented static summary), `stacks`, `entry_points`, `file_tree_depth1`, and `dependency_summary` when `--dependencies` was also requested.
+Includes: `project_summary`, `architecture_summary`, `stacks`, `entry_points`, `file_tree_depth1`, and — when the respective flags are active — `dependency_summary` + `key_dependencies`, `env_summary`, `code_notes_summary`.
 
 ```bash
 sourcecode --compact .
-sourcecode --compact --dependencies .
+sourcecode --compact --dependencies .           # + key dependencies with versions
+sourcecode --compact --dependencies --no-tree . # smallest footprint: no file tree
 ```
 
 **Full output — deep analysis**
@@ -622,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.19.0.dist-info → sourcecode-0.21.0.dist-info}/RECORD

@@ -1,22 +1,22 @@
-sourcecode/__init__.py,sha256=K3oF2tC36Se4IiYU6MvNhrg4EoK_jaLeik_nUWPID4Y,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=pB0NmyaH-gCrHCFlNxYSMfuArM6nitv6PyrMLkYKKRs,25429
+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=KITti0XLHK3RvZGqAUseWnlFLXGFyv5FqvSK5R6PB1g,41147
+sourcecode/dependency_analyzer.py,sha256=2TYBIpenhfWf_TVBZZfq3T0SHFv8xCKFIyn1XnFHG6s,48146
 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/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/serializer.py,sha256=edOfD25lUKkZ0gIjFcjqWmY4yHSnOKvudzNisvW_RYg,13456
+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
 sourcecode/workspace.py,sha256=fQlVoNx8S-fSHpKoJ0JBvEHCFkxszH0KZVJed1i3TRk,6845
@@ -39,7 +39,7 @@ sourcecode/detectors/rust.py,sha256=V23NO6Y8NsrhrUlGC2feUEcNK63hf3gc1y3jI4tes1Q,
 sourcecode/detectors/systems.py,sha256=nYaKbGDFu0EOXFcd_1doWFT3tTUdkbxc2DjHUF5TcqQ,1627
 sourcecode/detectors/terraform.py,sha256=cxORPR_zVLOJpHlh4e9JnFpkQsn_UnqMMom5yG65hZ4,1693
 sourcecode/detectors/tooling.py,sha256=hIvop80No22pqyGVJ32NKliSdjkHRePQkIRroqG01bY,1875
-sourcecode-0.19.0.dist-info/METADATA,sha256=cv1q6sPPTkTruEdpHr8JioUXmXuSec5dPAhAw9NXoW8,25900
-sourcecode-0.19.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-0.19.0.dist-info/entry_points.txt,sha256=voDtdlGU2-jR3wCZpQoOls_0eUKaDVCKIfajGHFDATs,50
-sourcecode-0.19.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,,