sourcecode 0.26.0__py3-none-any.whl → 0.27.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.27.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
 
@@ -10,10 +11,53 @@ from sourcecode import __version__
 
 app = typer.Typer(
     name="sourcecode",
-    help="Genera un mapa de contexto estructurado del proyecto para agentes IA.",
+    help="Deterministic codebase context for AI coding agents.",
     add_completion=False,
 )
 
+telemetry_app = typer.Typer(help="Manage anonymous telemetry (opt-in).")
+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"}
@@ -167,11 +211,17 @@ 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.
+    """Generate structured codebase context for AI coding agents."""
+    # First-run consent (skip for telemetry subcommand itself)
+    if ctx.invoked_subcommand != "telemetry":
+        _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(
@@ -672,7 +722,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)
 
 
@@ -804,3 +873,42 @@ 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")

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

sourcecode/telemetry/events.py

@@ -0,0 +1,78 @@
+"""Telemetry event schema.
+
+All fields are either categorical (string enum), numeric ranges (string bucket),
+or bounded scalars. No free-form text, no paths, no identifiers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Optional
+
+
+def _now_utc() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def file_count_bucket(n: int) -> str:
+    """Convert file count to anonymous range bucket."""
+    if n < 50:
+        return "tiny"
+    if n < 500:
+        return "small"
+    if n < 2000:
+        return "medium"
+    if n < 10000:
+        return "large"
+    return "huge"
+
+
+def duration_bucket(seconds: float) -> str:
+    """Approximate duration without exposing exact timing."""
+    if seconds < 1.0:
+        return "<1s"
+    if seconds < 5.0:
+        return "<5s"
+    if seconds < 15.0:
+        return "<15s"
+    if seconds < 60.0:
+        return "<60s"
+    return "60s+"
+
+
+@dataclass
+class TelemetryEvent:
+    """Minimal, privacy-safe telemetry event.
+
+    Fields:
+        event       — event name (command_executed / execution_completed / execution_failed)
+        ts          — ISO 8601 UTC timestamp
+        v           — sourcecode version
+        py          — Python major.minor (e.g. "3.11")
+        os          — OS family: linux | macos | windows | other
+        arch        — CPU architecture: x64 | arm64 | other
+        cmd         — command: analyze | prepare-context | telemetry
+        flags       — flag names only (no values)
+        output_fmt  — json | yaml
+        repo_size   — tiny | small | medium | large | huge
+        duration    — <1s | <5s | <15s | <60s | 60s+
+        success     — True/False
+        error_kind  — exception class name only (no message, no traceback)
+        session     — 8-char random hex, ephemeral, NOT persisted
+    """
+
+    event: str
+    ts: str = field(default_factory=_now_utc)
+    v: str = ""
+    py: str = ""
+    os: str = ""
+    arch: str = ""
+    cmd: str = ""
+    flags: list[str] = field(default_factory=list)
+    output_fmt: str = "json"
+    repo_size: str = "unknown"
+    duration: str = "unknown"
+    success: bool = True
+    error_kind: Optional[str] = None
+    session: str = ""

sourcecode/telemetry/filters.py

@@ -0,0 +1,140 @@
+"""Privacy filter — last line of defense before any event leaves the process.
+
+Every event is passed through this filter before transmission.
+Any field that could carry sensitive data is stripped or replaced.
+
+Rules enforced:
+  - No string longer than 64 characters
+  - No strings containing path separators (/ or \\)
+  - No strings containing whitespace (could be file contents)
+  - flags list: only known safe flag names (allowlist)
+  - error_kind: class name only, no message text
+  - All unknown/unexpected fields are dropped
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict
+from typing import Any
+
+from sourcecode.telemetry.events import TelemetryEvent
+
+# Allowlist of known-safe flag names. Only these can appear in the flags field.
+_SAFE_FLAGS: frozenset[str] = frozenset({
+    "--agent",
+    "--compact",
+    "--dependencies",
+    "--graph-modules",
+    "--graph-detail",
+    "--graph-edges",
+    "--max-nodes",
+    "--docs",
+    "--docs-depth",
+    "--full-metrics",
+    "--semantics",
+    "--architecture",
+    "--git-context",
+    "--git-depth",
+    "--git-days",
+    "--env-map",
+    "--code-notes",
+    "--format",
+    "--output",
+    "--depth",
+    "--no-tree",
+    "--tree",
+    "--no-redact",
+    "--compact",
+    "--version",
+    "--help",
+    "--llm-prompt",
+    "--since",
+    "--task-help",
+    "--dry-run",
+})
+
+_SAFE_OS: frozenset[str] = frozenset({"linux", "macos", "windows", "other"})
+_SAFE_ARCH: frozenset[str] = frozenset({"x64", "arm64", "other"})
+_SAFE_CMD: frozenset[str] = frozenset({"analyze", "prepare-context", "telemetry", "unknown"})
+_SAFE_EVENTS: frozenset[str] = frozenset({
+    "command_executed",
+    "execution_completed",
+    "execution_failed",
+    "telemetry_enabled",
+    "telemetry_disabled",
+})
+_SAFE_SIZES: frozenset[str] = frozenset({"tiny", "small", "medium", "large", "huge", "unknown"})
+_SAFE_DURATIONS: frozenset[str] = frozenset({"<1s", "<5s", "<15s", "<60s", "60s+", "unknown"})
+_SAFE_FMTS: frozenset[str] = frozenset({"json", "yaml"})
+
+# Pattern that looks like a path segment
+_PATH_PATTERN = re.compile(r"[/\\]|^\.|\.py$|\.js$|\.ts$|\.go$")
+# Any string with spaces (could be a sentence / file content)
+_SPACE_PATTERN = re.compile(r"\s")
+
+
+def _safe_str(value: str, allowed: frozenset[str], fallback: str = "other") -> str:
+    """Return value if it's in the allowlist, otherwise fallback."""
+    return value if value in allowed else fallback
+
+
+def _safe_flags(flags: list[str]) -> list[str]:
+    """Return only flags in the explicit allowlist."""
+    return sorted(f for f in flags if f in _SAFE_FLAGS)
+
+
+def _safe_error_kind(value: str | None) -> str | None:
+    """Keep only the exception class name. Drop any message text."""
+    if not value:
+        return None
+    # Exception class names are CamelCase identifiers, no spaces, no paths
+    name = value.split(":")[-1].strip()  # strip message after ':'
+    name = name.split(".")[-1].strip()   # strip module prefix
+    if len(name) > 64 or _SPACE_PATTERN.search(name) or _PATH_PATTERN.search(name):
+        return "UnknownError"
+    return name[:64] if name else None
+
+
+def _safe_session(value: str) -> str:
+    """Session ID must be a short hex string only."""
+    if re.match(r"^[0-9a-f]{1,16}$", value):
+        return value
+    return ""
+
+
+def sanitize(event: TelemetryEvent) -> dict[str, Any]:
+    """Apply privacy filter to event and return a safe dict for transmission.
+
+    This is the single choke point through which all data must pass.
+    If any field cannot be validated as safe, it is replaced with a safe default.
+    """
+    safe: dict[str, Any] = {
+        "event": _safe_str(event.event, _SAFE_EVENTS, "command_executed"),
+        "ts": event.ts[:20] if event.ts else "",  # truncate to date+time, no sub-second
+        "v": event.v[:16] if event.v else "",
+        "py": event.py[:8] if event.py else "",
+        "os": _safe_str(event.os, _SAFE_OS, "other"),
+        "arch": _safe_str(event.arch, _SAFE_ARCH, "other"),
+        "cmd": _safe_str(event.cmd, _SAFE_CMD, "unknown"),
+        "flags": _safe_flags(event.flags),
+        "output_fmt": _safe_str(event.output_fmt, _SAFE_FMTS, "json"),
+        "repo_size": _safe_str(event.repo_size, _SAFE_SIZES, "unknown"),
+        "duration": _safe_str(event.duration, _SAFE_DURATIONS, "unknown"),
+        "success": bool(event.success),
+    }
+
+    if event.error_kind:
+        safe["error_kind"] = _safe_error_kind(event.error_kind)
+
+    session = _safe_session(event.session)
+    if session:
+        safe["session"] = session
+
+    # Final validation: reject any field value that looks like a path or long string
+    for key, val in list(safe.items()):
+        if isinstance(val, str):
+            if len(val) > 64 or _PATH_PATTERN.search(val):
+                safe[key] = ""
+
+    return safe

sourcecode/telemetry/transport.py

@@ -0,0 +1,52 @@
+"""Fire-and-forget HTTP transport for telemetry events.
+
+Design principles:
+  - Never blocks the main thread (daemon thread)
+  - Never raises or prints errors to the user
+  - Short timeout (3s) — drop and move on
+  - No retries — a missed event is fine
+  - Endpoint configurable via SOURCECODE_TELEMETRY_ENDPOINT env var
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from typing import Any
+
+_DEFAULT_ENDPOINT = "https://t.sourcecode.dev/v1/event"
+_TIMEOUT_S = 3
+
+
+def _endpoint() -> str:
+    return os.environ.get("SOURCECODE_TELEMETRY_ENDPOINT", _DEFAULT_ENDPOINT)
+
+
+def _send_blocking(payload: dict[str, Any]) -> None:
+    """Blocking send — runs inside a daemon thread only."""
+    try:
+        import urllib.request
+
+        data = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+        req = urllib.request.Request(
+            _endpoint(),
+            data=data,
+            headers={
+                "Content-Type": "application/json",
+                "User-Agent": f"sourcecode/{payload.get('v', 'unknown')}",
+            },
+            method="POST",
+        )
+        urllib.request.urlopen(req, timeout=_TIMEOUT_S)
+    except Exception:
+        pass  # always silent — a missed event is not an error
+
+
+def send(payload: dict[str, Any]) -> None:
+    """Dispatch payload to the telemetry endpoint in a background daemon thread.
+
+    Returns immediately. The main process can exit without waiting.
+    """
+    t = threading.Thread(target=_send_blocking, args=(payload,), daemon=True)
+    t.start()