sourcecode 0.20.0__tar.gz → 0.21.0__tar.gz

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

@@ -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 → sourcecode-0.21.0}/README.md

@@ -620,6 +620,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 → sourcecode-0.21.0}/docs/schema.md

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

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

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

{sourcecode-0.20.0 → sourcecode-0.21.0}/src/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-0.20.0 → sourcecode-0.21.0}/src/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))