sourcecode 0.26.0__py3-none-any.whl → 0.28.0__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/cli.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import time
 from pathlib import Path
 from typing import Any, Optional, cast
 
@@ -8,12 +9,173 @@ import typer
 
 from sourcecode import __version__
 
+_HELP = """\
+Deterministic codebase context for AI coding agents.
+
+[bold]Usage:[/bold]
+  sourcecode                   [dim]# analyze current directory[/dim]
+  sourcecode /path/to/repo     [dim]# analyze specific path[/dim]
+  sourcecode --agent           [dim]# structured output for AI agents[/dim]
+
+[bold]Subcommands:[/bold]
+  prepare-context TASK [PATH]  [dim]# task-specific context[/dim]
+  telemetry status|enable|disable
+  version
+  config
+"""
+
+# Known subcommand names — tokens matching these are routed as subcommands,
+# not consumed as a repository path.
+_SUBCOMMANDS: frozenset[str] = frozenset(
+    {"telemetry", "prepare-context", "version", "config", "analyze"}
+)
+
+# Mutable container holding the path extracted by _preprocess_argv().
+# Default "." means "current directory" when no path is given.
+_detected_path: list[str] = ["."]
+
+
+# Options that take a value token — their next arg must not be treated as a path.
+_OPTIONS_WITH_VALUE: frozenset[str] = frozenset({
+    "--format", "-f",
+    "--output", "-o",
+    "--graph-detail",
+    "--graph-edges",
+    "--max-nodes",
+    "--docs-depth",
+    "--depth",
+    "--git-depth",
+    "--git-days",
+    "--since",
+    "--path", "-p",
+})
+
+
+def _preprocess_args(args: list[str]) -> list[str]:
+    """Extract a repository path token from an args list and store it in _detected_path.
+
+    Returns the modified args list (path token removed).
+    Correctly skips option values (e.g. ``yaml`` in ``--format yaml``).
+    If the first non-flag, non-value positional token is a known subcommand name,
+    args are returned unchanged so Click can dispatch the subcommand.
+    """
+    result = list(args)
+    skip_next = False
+    for i, arg in enumerate(result):
+        if skip_next:
+            skip_next = False
+            continue
+        if arg.startswith("-"):
+            # Does this option consume the next token as its value?
+            flag_name = arg.split("=")[0]
+            if flag_name in _OPTIONS_WITH_VALUE and "=" not in arg:
+                skip_next = True
+            continue
+        if arg in _SUBCOMMANDS:
+            return result  # known subcommand — leave for Click to dispatch
+        # First genuine positional: treat as repository path
+        _detected_path[0] = arg
+        result.pop(i)
+        return result
+    return result
+
+
+def _preprocess_argv() -> None:
+    """Apply _preprocess_args to sys.argv in-place (used by main_entry)."""
+    import sys as _sys
+    modified = _preprocess_args(_sys.argv[1:])
+    _sys.argv = _sys.argv[:1] + modified
+
+
 app = typer.Typer(
     name="sourcecode",
-    help="Genera un mapa de contexto estructurado del proyecto para agentes IA.",
+    help=_HELP,
     add_completion=False,
+    rich_markup_mode="rich",
+    no_args_is_help=False,
 )
 
+# ── Hook preprocessing into the Click command layer ───────────────────────────
+# Typer's CliRunner (and app() itself) calls typer.main.get_command(app) to
+# create a Click Group, then calls click_group.main(args=...).
+# We patch get_command so the returned Click Group always preprocesses args —
+# this covers both main_entry() (sys.argv path) and runner.invoke(app, args).
+import typer.main as _typer_main_module  # noqa: E402
+
+_orig_get_command = _typer_main_module.get_command
+
+
+def _get_command_with_preprocessing(typer_instance: Any) -> Any:
+    cmd = _orig_get_command(typer_instance)
+    if typer_instance is not app:
+        return cmd  # only wrap the root app, not telemetry_app etc.
+    _orig_cmd_main = cmd.main
+
+    def _cmd_main(args: Optional[list[str]] = None, **kwargs: Any) -> Any:
+        if args is not None:
+            # CliRunner / programmatic call: preprocess the explicit args list.
+            _detected_path[0] = "."
+            args = _preprocess_args(list(args))
+        # args=None → Click reads sys.argv; _preprocess_argv() in main_entry handled it.
+        return _orig_cmd_main(args=args, **kwargs)
+
+    cmd.main = _cmd_main
+    return cmd
+
+
+_typer_main_module.get_command = _get_command_with_preprocessing
+
+# typer.testing imports get_command as a private alias _get_command at module
+# load time; patch that reference too so CliRunner.invoke uses our version.
+try:
+    import typer.testing as _typer_testing_module
+    _typer_testing_module._get_command = _get_command_with_preprocessing  # type: ignore[attr-defined]
+except Exception:
+    pass
+
+telemetry_app = typer.Typer(help="Manage anonymous telemetry (opt-in).", rich_markup_mode="rich")
+app.add_typer(telemetry_app, name="telemetry")
+
+
+def _maybe_ask_consent() -> None:
+    """Show first-run consent prompt once, on interactive TTYs only."""
+    try:
+        from sourcecode.telemetry.config import has_been_asked, mark_asked, set_enabled
+        from sourcecode.telemetry.consent import ask_for_consent
+        if not has_been_asked():
+            enabled = ask_for_consent()
+            set_enabled(enabled)
+            if enabled:
+                typer.echo("Telemetry enabled. Thank you. Disable: sourcecode telemetry disable", err=True)
+            else:
+                typer.echo("Telemetry disabled. Enable anytime: sourcecode telemetry enable", err=True)
+    except Exception:
+        pass
+
+
+def _active_flags(
+    dependencies: bool, graph_modules: bool, docs: bool, full_metrics: bool,
+    semantics: bool, architecture: bool, git_context: bool, env_map: bool,
+    code_notes: bool, agent: bool, compact: bool, tree: bool, no_redact: bool,
+    fmt: str,
+) -> list[str]:
+    flags: list[str] = []
+    if agent: flags.append("--agent")
+    if compact: flags.append("--compact")
+    if dependencies: flags.append("--dependencies")
+    if graph_modules: flags.append("--graph-modules")
+    if docs: flags.append("--docs")
+    if full_metrics: flags.append("--full-metrics")
+    if semantics: flags.append("--semantics")
+    if architecture: flags.append("--architecture")
+    if git_context: flags.append("--git-context")
+    if env_map: flags.append("--env-map")
+    if code_notes: flags.append("--code-notes")
+    if tree: flags.append("--tree")
+    if no_redact: flags.append("--no-redact")
+    if fmt != "json": flags.append("--format")
+    return flags
+
 FORMAT_CHOICES = ["json", "yaml"]
 GRAPH_DETAIL_CHOICES = ["high", "medium", "full"]
 GRAPH_EDGE_CHOICES = {"imports", "calls", "contains", "extends"}
@@ -29,7 +191,6 @@ def version_callback(value: bool) -> None:
 @app.callback(invoke_without_command=True)
 def main(
     ctx: typer.Context,
-    path: Path = typer.Argument(Path("."), help="Directorio a analizar (default: directorio actual)"),
     format: str = typer.Option(
         "json",
         "--format",
@@ -167,11 +328,25 @@ def main(
         help="Modo agente: output estructurado y sin ruido para consumo por IA. Incluye identidad, entrypoints, arquitectura, dependencias clave, señales operacionales y gaps. Sin arbol de ficheros ni secciones vacias.",
     ),
 ) -> None:
-    """Genera un mapa de contexto estructurado del proyecto en formato JSON o YAML."""
-    # When a subcommand (e.g. prepare-context) is invoked, skip the main analysis.
+    """Analyze a repository and produce structured context for AI coding agents.
+
+    \b
+    Examples:
+      sourcecode                        analyze current directory
+      sourcecode /path/to/repo          analyze specific path
+      sourcecode --agent                agent-optimized output
+      sourcecode --agent --git-context  include git activity signals
+    """
+    # First-run consent (skip for telemetry/version/config subcommands)
+    if ctx.invoked_subcommand not in ("telemetry", "version", "config"):
+        _maybe_ask_consent()
+
+    # When a subcommand is invoked, skip the main analysis.
     if ctx.invoked_subcommand is not None:
         return
 
+    _t0 = time.monotonic()
+
     # Validar formato
     if format not in FORMAT_CHOICES:
         typer.echo(
@@ -192,13 +367,13 @@ def main(
         )
         raise typer.Exit(code=1)
 
-    # Resolver y validar path
-    target = path.resolve()
+    # Path was extracted from argv by _preprocess_argv() before Click ran.
+    target = Path(_detected_path[0]).resolve()
     if not target.exists():
-        typer.echo(f"Error: el directorio '{target}' no existe.", err=True)
+        typer.echo(f"Error: directory '{target}' does not exist.", err=True)
         raise typer.Exit(code=1)
     if not target.is_dir():
-        typer.echo(f"Error: '{target}' no es un directorio.", err=True)
+        typer.echo(f"Error: '{target}' is not a directory.", err=True)
         raise typer.Exit(code=1)
 
     # --- Importar modulos de logica ---
@@ -672,7 +847,26 @@ def main(
         else:
             content = json.dumps(raw_dict, indent=2, ensure_ascii=False)
 
-    # 5. Escribir output (CLI-04)
+    # 5. Telemetry (fire-and-forget, never blocks)
+    try:
+        from sourcecode import telemetry as _tel
+        _tel.record(
+            "execution_completed",
+            cmd="analyze",
+            flags=_active_flags(
+                dependencies, graph_modules, docs, full_metrics,
+                semantics, architecture, git_context, env_map,
+                code_notes, agent, compact, tree, no_redact, format,
+            ),
+            output_fmt=format,
+            file_count=len(sm.file_paths),
+            duration_s=time.monotonic() - _t0,
+            success=True,
+        )
+    except Exception:
+        pass
+
+    # 6. Escribir output (CLI-04)
     write_output(content, output=output)
 
 
@@ -682,15 +876,14 @@ def prepare_context_cmd(
         None,
         help="Task: explain | fix-bug | refactor | generate-tests | onboard | review-pr | delta",
     ),
-    path: Path = typer.Option(
+    path: Path = typer.Argument(
         Path("."),
-        "--path", "-p",
-        help="Project directory to analyze (default: current directory)",
+        help="Repository path to analyze (default: current directory)",
     ),
     since: Optional[str] = typer.Option(
         None,
         "--since",
-        help="Git ref for delta task: show files changed since this ref (e.g. HEAD~3, main)",
+        help="Git ref for delta task (e.g. HEAD~3, main)",
     ),
     llm_prompt: bool = typer.Option(
         False,
@@ -708,25 +901,26 @@ def prepare_context_cmd(
         help="Show what would be analyzed without running it",
     ),
 ) -> None:
-    """Compile task-aware context for AI coding agents.
+    """Task-specific context for AI coding agents.
 
     \b
     Tasks:
-      explain        Project overview: structure, entry points, dependencies
-      fix-bug        Risk-ranked files, suspected areas, code annotations
+      explain        Architecture, entry points, key dependencies
+      fix-bug        Risk-ranked files, suspected areas, annotations
       refactor       Structural issues, improvement opportunities
       generate-tests Untested source files, test gap analysis
-      onboard        Full project context for a new agent or developer
-      review-pr      PR review context: changed files + architecture
+      onboard        Full project context for new agents/developers
+      review-pr      Changed files + architectural impact
       delta          Incremental context: git-changed files only
 
     \b
     Examples:
-      sourcecode . prepare-context explain
-      sourcecode . prepare-context fix-bug --path /my/project
-      sourcecode . prepare-context delta --since main
-      sourcecode . prepare-context onboard --llm-prompt
-      sourcecode . prepare-context --task-help
+      sourcecode prepare-context explain
+      sourcecode prepare-context explain /path/to/repo
+      sourcecode prepare-context fix-bug
+      sourcecode prepare-context delta --since main
+      sourcecode prepare-context onboard --llm-prompt
+      sourcecode prepare-context --task-help
     """
     from sourcecode.prepare_context import TASKS, TaskContextBuilder
 
@@ -804,3 +998,96 @@ def prepare_context_cmd(
         out["llm_prompt"] = builder.render_prompt(output)
 
     typer.echo(json.dumps(out, indent=2, ensure_ascii=False))
+
+
+# ── Telemetry commands ────────────────────────────────────────────────────────
+
+@telemetry_app.command("status")
+def telemetry_status() -> None:
+    """Show current telemetry setting."""
+    from sourcecode.telemetry.config import config_file_path, has_been_asked, is_enabled
+    enabled = is_enabled()
+    asked = has_been_asked()
+    status = "enabled" if enabled else "disabled"
+    typer.echo(f"Telemetry: {status}")
+    if not asked:
+        typer.echo("  (consent not yet shown — will prompt on next run)")
+    typer.echo(f"  Config: {config_file_path()}")
+    typer.echo("  Disable permanently: sourcecode telemetry disable")
+    typer.echo("  Or set env var:      SOURCECODE_TELEMETRY=0")
+
+
+@telemetry_app.command("enable")
+def telemetry_enable() -> None:
+    """Opt in to anonymous telemetry."""
+    from sourcecode.telemetry.config import set_enabled
+    from sourcecode import telemetry as _tel
+    set_enabled(True)
+    typer.echo("Telemetry enabled. Thank you — this helps improve sourcecode.")
+    typer.echo("What is collected: version, OS, commands, flags, duration, repo size range, errors.")
+    typer.echo("What is never collected: source code, paths, secrets, or any output content.")
+    typer.echo("Disable at any time: sourcecode telemetry disable")
+    _tel.record("telemetry_enabled", cmd="telemetry")
+
+
+@telemetry_app.command("disable")
+def telemetry_disable() -> None:
+    """Opt out of anonymous telemetry."""
+    from sourcecode.telemetry.config import set_enabled
+    set_enabled(False)
+    typer.echo("Telemetry disabled. No data will be collected or sent.")
+    typer.echo("Re-enable at any time: sourcecode telemetry enable")
+
+
+# ── version ───────────────────────────────────────────────────────────────────
+
+@app.command("version")
+def version_cmd() -> None:
+    """Show version and exit."""
+    typer.echo(f"sourcecode {__version__}")
+
+
+# ── config ────────────────────────────────────────────────────────────────────
+
+@app.command("config")
+def config_cmd() -> None:
+    """Show current configuration."""
+    from sourcecode.telemetry.config import config_file_path, is_enabled
+    typer.echo(f"sourcecode {__version__}")
+    typer.echo(f"Config:    {config_file_path()}")
+    typer.echo(f"Telemetry: {'enabled' if is_enabled() else 'disabled'}")
+    typer.echo("")
+    typer.echo("Manage telemetry:")
+    typer.echo("  sourcecode telemetry enable")
+    typer.echo("  sourcecode telemetry disable")
+    typer.echo("  sourcecode telemetry status")
+
+
+# ── analyze (legacy alias) ────────────────────────────────────────────────────
+
+@app.command("analyze", hidden=True)
+def analyze_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path to analyze"),
+) -> None:
+    """[deprecated] Use: sourcecode [PATH]"""
+    typer.echo(
+        "Warning: 'analyze' subcommand is deprecated.\n"
+        "Use:  sourcecode .\n"
+        "      sourcecode /path/to/repo",
+        err=True,
+    )
+    raise typer.Exit(code=1)
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+def main_entry() -> None:
+    """CLI entry point.
+
+    Calls _preprocess_argv() before Typer/Click parses sys.argv so that
+    repository path tokens are extracted before Click's Group callback
+    can consume them as positional arguments (which would prevent subcommand
+    routing for tokens like 'version' or 'config').
+    """
+    _preprocess_argv()
+    app()

sourcecode/telemetry/__init__.py

@@ -0,0 +1,111 @@
+"""sourcecode telemetry — opt-in anonymous usage metrics.
+
+Public API:
+    is_enabled()          → bool
+    record(event, **kw)   → None  (fire-and-forget)
+    session_id()          → str   (ephemeral 8-char hex, new each process)
+
+Telemetry is strictly opt-in. It is disabled by default and can be disabled
+at any time via `sourcecode telemetry disable` or SOURCECODE_TELEMETRY=0.
+
+Nothing sensitive (code, paths, secrets, output) is ever collected.
+See docs/privacy.md for full details.
+"""
+
+from __future__ import annotations
+
+import platform
+import sys
+import uuid
+from typing import Any, Optional
+
+from sourcecode.telemetry.config import is_enabled
+from sourcecode.telemetry.events import (
+    TelemetryEvent,
+    duration_bucket,
+    file_count_bucket,
+)
+from sourcecode.telemetry.filters import sanitize
+from sourcecode.telemetry.transport import send
+
+# Ephemeral session identifier — new random value each process start.
+# 8 hex chars, never persisted, used only to correlate events within one run.
+_SESSION: str = uuid.uuid4().hex[:8]
+
+
+def session_id() -> str:
+    return _SESSION
+
+
+def _platform_os() -> str:
+    system = platform.system().lower()
+    if system == "darwin":
+        return "macos"
+    if system in ("linux", "windows"):
+        return system
+    return "other"
+
+
+def _platform_arch() -> str:
+    machine = platform.machine().lower()
+    if machine in ("x86_64", "amd64", "i386", "i686"):
+        return "x64"
+    if machine in ("arm64", "aarch64", "armv8l"):
+        return "arm64"
+    return "other"
+
+
+def _python_version() -> str:
+    return f"{sys.version_info.major}.{sys.version_info.minor}"
+
+
+def _sourcecode_version() -> str:
+    try:
+        from sourcecode import __version__
+        return __version__
+    except Exception:
+        return "unknown"
+
+
+def record(
+    event: str,
+    *,
+    cmd: str = "analyze",
+    flags: Optional[list[str]] = None,
+    output_fmt: str = "json",
+    file_count: Optional[int] = None,
+    duration_s: Optional[float] = None,
+    success: bool = True,
+    error_kind: Optional[str] = None,
+) -> None:
+    """Record a telemetry event. Fire-and-forget — never blocks or raises.
+
+    All data is privacy-filtered before transmission. If telemetry is disabled,
+    this function returns immediately without doing anything.
+    """
+    if not is_enabled():
+        return
+
+    try:
+        ev = TelemetryEvent(
+            event=event,
+            v=_sourcecode_version(),
+            py=_python_version(),
+            os=_platform_os(),
+            arch=_platform_arch(),
+            cmd=cmd,
+            flags=flags or [],
+            output_fmt=output_fmt,
+            repo_size=file_count_bucket(file_count) if file_count is not None else "unknown",
+            duration=duration_bucket(duration_s) if duration_s is not None else "unknown",
+            success=success,
+            error_kind=error_kind,
+            session=_SESSION,
+        )
+        payload = sanitize(ev)
+        send(payload)
+    except Exception:
+        pass  # telemetry must never affect the main process
+
+
+__all__ = ["is_enabled", "record", "session_id"]

sourcecode/telemetry/config.py

@@ -0,0 +1,67 @@
+"""Persistent telemetry configuration.
+
+Config file: ~/.config/sourcecode/config.json
+Env override: SOURCECODE_TELEMETRY=0 (disable) or =1 (enable)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+_ENV_VAR = "SOURCECODE_TELEMETRY"
+_CONFIG_FILE = Path.home() / ".config" / "sourcecode" / "config.json"
+
+
+def _load() -> dict[str, Any]:
+    try:
+        return json.loads(_CONFIG_FILE.read_text(encoding="utf-8"))  # type: ignore[no-any-return]
+    except Exception:
+        return {}
+
+
+def _save(data: dict[str, Any]) -> None:
+    try:
+        _CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+        _CONFIG_FILE.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    except Exception:
+        pass  # config write failure is non-fatal
+
+
+def is_enabled() -> bool:
+    """True only when telemetry is explicitly opted in.
+
+    Env var takes absolute precedence over config file.
+    Default is always disabled — telemetry is strictly opt-in.
+    """
+    env = os.environ.get(_ENV_VAR, "").strip()
+    if env == "0":
+        return False
+    if env == "1":
+        return True
+    return bool(_load().get("telemetry", {}).get("enabled", False))
+
+
+def has_been_asked() -> bool:
+    """True if the consent prompt has already been shown."""
+    return bool(_load().get("telemetry", {}).get("asked", False))
+
+
+def set_enabled(value: bool) -> None:
+    data = _load()
+    data.setdefault("telemetry", {})["enabled"] = value
+    data["telemetry"]["asked"] = True
+    _save(data)
+
+
+def mark_asked() -> None:
+    """Record that the consent prompt was shown (regardless of answer)."""
+    data = _load()
+    data.setdefault("telemetry", {})["asked"] = True
+    _save(data)
+
+
+def config_file_path() -> Path:
+    return _CONFIG_FILE

sourcecode/telemetry/consent.py

@@ -0,0 +1,63 @@
+"""First-run consent prompt.
+
+Shown exactly once, only on interactive TTYs, only when the user hasn't been
+asked before. Default answer is NO — the user must explicitly type 'y' to opt in.
+
+Prompt is written to stderr so it doesn't pollute stdout output.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+_PROMPT = """\
+\033[2m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  sourcecode — optional anonymous telemetry
+
+  Help improve sourcecode by sharing anonymous usage metrics.
+
+  Collected: tool version, Python version, OS, commands used,
+  flags used, approximate repo size, execution duration, errors.
+
+  Never collected: source code, file paths, file names, secrets,
+  tokens, environment variables, or any repository content.
+
+  You can change this at any time:
+    sourcecode telemetry disable
+    export SOURCECODE_TELEMETRY=0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\033[0m
+"""
+
+
+def _is_interactive() -> bool:
+    """True when running in an interactive terminal (not CI, not piped)."""
+    if not sys.stdin.isatty() or not sys.stderr.isatty():
+        return False
+    # Common CI environment variables
+    ci_vars = {
+        "CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "CIRCLECI",
+        "TRAVIS", "JENKINS_URL", "BUILDKITE", "GITLAB_CI", "TF_BUILD",
+        "TEAMCITY_VERSION", "DRONE", "SEMAPHORE",
+    }
+    return not any(os.environ.get(v) for v in ci_vars)
+
+
+def ask_for_consent() -> bool:
+    """Show the consent prompt and return the user's choice.
+
+    Returns True if the user opted in, False otherwise.
+    Never raises. Default (Enter / non-y input) is False.
+    """
+    if not _is_interactive():
+        return False
+
+    try:
+        sys.stderr.write(_PROMPT)
+        sys.stderr.write("  Enable anonymous telemetry? [y/N]: ")
+        sys.stderr.flush()
+        answer = sys.stdin.readline().strip().lower()
+        sys.stderr.write("\n")
+        return answer == "y"
+    except Exception:
+        return False