[Refactor] Single responsibility principle (#42)

The purpose of the refactor was to split current code into files and
functions where each file/function is responsible for a single concern.
See the design docs in this commit for details. No tests were touched

## File-SRP
- ✅ Step 2 complete: introduced `src/logging.rs` for one-time logger
initialisation and migrated tracing session lifecycle (`start_tracing`,
`stop_tracing`, `is_tracing`, `flush_tracing`, `ACTIVE` flag) into
`src/session.rs`, with `src/lib.rs` now limited to PyO3 wiring and
re-exports.
- ✅ Step 3 complete: added `src/runtime/mod.rs` with focused
`activation`, `value_encoder`, and `output_paths` submodules;
`RuntimeTracer` now delegates activation gating, value encoding, and
writer initialisation through the façade consumed by `session.rs`.
- ✅ Step 4 complete: introduced `src/monitoring/mod.rs` for
sys.monitoring types/caches and `src/monitoring/tracer.rs` for the
tracer trait plus callback dispatch; rewired `lib.rs`, `session.rs`, and
`runtime/mod.rs`, and kept a top-level `tracer` re-export for API
stability.
- ✅ Step 5 complete: split the Python package into dedicated
`formats.py`, `session.py`, and `auto_start.py` modules, trimmed
`api.py` to a thin façade, and moved the environment auto-start hook
into `__init__.py`.
- ✅ Step 6 complete: resolved outstanding Rust TODOs (format validation,
argv handling, function id stability), expanded module documentation so
`cargo doc` reflects the architecture, and re-ran `just test` to confirm
the refactor remains green.
- ✅ Test baseline: `just test` (nextest + pytest) passes with the UV
cache scoped to the workspace; direct `cargo test` still requires
CPython development symbols.

## Function-SRP

## Stage 0 – Baseline & Guardrails
- ✅ `just test` (Rust + Python suites) passes; captured run via the
top-level recipe.
- ✅ Generated JSON and binary reference traces from
`examples/value_capture_all.py`; outputs stored in
`artifacts/stage0/value-capture-json/` and
`artifacts/stage0/value-capture-binary/`.
- ⏳ Summarise current `ActivationController` behaviour and frame
traversal notes for reviewer context.

## Stage 1 – Session Start-Up Decomposition
- ✅ Step 1 (Rust): Introduced `session::bootstrap` helpers and
refactored `start_tracing` to delegate directory validation, format
resolution, and program metadata collection. Tests remain green.
- ✅ Step 2 (Python): Extracted `_coerce_format`, `_validate_trace_path`,
and `_normalize_activation_path` helpers; added tests covering invalid
formats and conflicting paths.

## Stage 2 – Frame Inspection & Activation Separation
- ✅ Step 1: Added `runtime::frame_inspector::capture_frame` to
encapsulate frame lookup, locals/globals materialisation, and reference
counting; `on_line` now delegates to the helper while preserving
behaviour.
- ✅ Step 2: Extended `ActivationController` with
`should_process_event`/`handle_return_event`, updated callbacks to rely
on them, and removed direct state juggling from `RuntimeTracer`.

## Stage 3 – Value Capture Layer
- ✅ Step 1: Introduced `runtime::value_capture::capture_call_arguments`;
`on_py_start` now delegates to it, keeping the function focused on
orchestration while reusing frame inspectors.
- ✅ Step 2: Added `record_visible_scope` helper and refactored `on_line`
to delegate locals/globals registration through it.

## Stage 4 – Return Handling & Logging Harmonisation
- ✅ Added `runtime::logging::log_event` to consolidate callback logging
across start, line, and return handlers.
- ✅ Exposed `record_return_value` in `runtime::value_capture` and
refactored `RuntimeTracer::on_py_return` to orchestrate activation
checks, logging, and value recording.
- ✅ Extended runtime tests with explicit return capture coverage and
activation deactivation assertions.

## Stage 5 – Cleanup & Regression Sweep
- ✅ Audited runtime modules for obsolete inline comments or TODOs
introduced pre-refactor; none remained after helper extraction.
- ✅ Documented the helper module map in
`design-docs/function-level-srp-refactor-plan.md` for contributor
onboarding.
- ✅ Re-ran `just test` (Rust `cargo nextest` + Python `pytest`) to
confirm post-cleanup parity.

Author: tzanko-matev

.gitignore

@@ -6,4 +6,6 @@
 build
 *~
 .idea/
-.cargo/
+.cargo/
+
+**/*.egg-info/

codetracer-python-recorder/codetracer_python_recorder/__init__.py

@@ -9,5 +9,8 @@
 
 from . import api as _api
 from .api import *  # re-export public API symbols
+from .auto_start import auto_start_from_env
+
+auto_start_from_env()
 
 __all__ = _api.__all__

codetracer-python-recorder/codetracer_python_recorder/api.py

@@ -1,142 +1,12 @@
-"""High-level tracing API built on a Rust backend.
-
-This module exposes a minimal interface for starting and stopping
-runtime traces. The heavy lifting is delegated to the
-`codetracer_python_recorder` Rust extension which hooks
-into `runtime_tracing` and `sys.monitoring`.
-"""
+"""High-level tracing API built on a Rust backend."""
 from __future__ import annotations
 
-import contextlib
-import os
-from pathlib import Path
-from typing import Iterator, Optional
-
-from .codetracer_python_recorder import (
-    flush_tracing as _flush_backend,
-    is_tracing as _is_tracing_backend,
-    start_tracing as _start_backend,
-    stop_tracing as _stop_backend,
-)
-
-TRACE_BINARY: str = "binary"
-TRACE_JSON: str = "json"
-DEFAULT_FORMAT: str = TRACE_BINARY
-
-_active_session: Optional["TraceSession"] = None
-
-
-def start(
-    path: os.PathLike | str,
-    *,
-    format: str = DEFAULT_FORMAT,
-    start_on_enter: os.PathLike | str | None = None,
-) -> "TraceSession":
-    """Start a global trace session.
-
-    - ``path``: Target directory where trace files will be written.
-      Files created: ``trace.json``/``trace.bin``, ``trace_metadata.json``, ``trace_paths.json``.
-    - ``format``: Either ``binary`` or ``json`` (controls events file name/format).
-    - ``start_on_enter``: Optional file path; when provided, tracing remains
-      paused until the tracer observes execution entering this file. Useful to
-      avoid recording interpreter and import startup noise when launching a
-      script via the CLI.
-
-    The current implementation records trace data through a Rust backend.
-    """
-    global _active_session
-    if _is_tracing_backend():
-        raise RuntimeError("tracing already active")
-
-    trace_path = Path(path)
-    _start_backend(
-        str(trace_path),
-        format,
-        str(Path(start_on_enter)) if start_on_enter is not None else None,
-    )
-    session = TraceSession(path=trace_path, format=format)
-    _active_session = session
-    return session
-
-
-def stop() -> None:
-    """Stop the active trace session if one is running."""
-    global _active_session
-    if not _is_tracing_backend():
-        return
-    _stop_backend()
-    _active_session = None
-
-
-def is_tracing() -> bool:
-    """Return ``True`` when a trace session is active."""
-    return _is_tracing_backend()
-
-
-def flush() -> None:
-    """Flush buffered trace data.
+from typing import Iterable
 
-    With the current placeholder implementation this is a no-op but the
-    function is provided to match the planned public API.
-    """
-    if _is_tracing_backend():
-        _flush_backend()
+from .formats import DEFAULT_FORMAT, TRACE_BINARY, TRACE_JSON
+from .session import TraceSession, flush, is_tracing, start, stop, trace
 
-
-@contextlib.contextmanager
-def trace(
-    path: os.PathLike | str,
-    *,
-    format: str = DEFAULT_FORMAT,
-) -> Iterator["TraceSession"]:
-    """Context manager helper for scoped tracing."""
-    session = start(
-        path,
-        format=format,
-    )
-    try:
-        yield session
-    finally:
-        session.stop()
-
-
-class TraceSession:
-    """Handle representing a live tracing session."""
-
-    path: Path
-    format: str
-
-    def __init__(self, path: Path, format: str) -> None:
-        self.path = path
-        self.format = format
-
-    def stop(self) -> None:
-        """Stop this trace session."""
-        if _active_session is self:
-            stop()
-
-    def flush(self) -> None:
-        """Flush buffered trace data for this session."""
-        flush()
-
-    def __enter__(self) -> "TraceSession":
-        return self
-
-    def __exit__(self, exc_type, exc, tb) -> None:  # pragma: no cover - thin wrapper
-        self.stop()
-
-
-def _auto_start_from_env() -> None:
-    path = os.getenv("CODETRACER_TRACE")
-    if not path:
-        return
-    fmt = os.getenv("CODETRACER_FORMAT", DEFAULT_FORMAT)
-    start(path, format=fmt)
-
-
-_auto_start_from_env()
-
-__all__ = [
+__all__: Iterable[str] = (
     "TraceSession",
     "DEFAULT_FORMAT",
     "TRACE_BINARY",
@@ -146,4 +16,4 @@ def _auto_start_from_env() -> None:
     "is_tracing",
     "trace",
     "flush",
-]
+)

codetracer-python-recorder/codetracer_python_recorder/auto_start.py

@@ -0,0 +1,40 @@
+"""Environment-driven trace auto-start helper."""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Iterable
+
+from .formats import DEFAULT_FORMAT
+
+ENV_TRACE_PATH = "CODETRACER_TRACE"
+ENV_TRACE_FORMAT = "CODETRACER_FORMAT"
+
+log = logging.getLogger(__name__)
+
+
+def auto_start_from_env() -> None:
+    """Start tracing automatically when the relevant environment variables are set."""
+    path = os.getenv(ENV_TRACE_PATH)
+    if not path:
+        return
+
+    # Delay import to avoid boot-time circular dependencies.
+    from . import session
+
+    if session.is_tracing():
+        log.debug("codetracer auto-start skipped: tracing already active")
+        return
+
+    fmt = os.getenv(ENV_TRACE_FORMAT, DEFAULT_FORMAT)
+    log.debug(
+        "codetracer auto-start triggered", extra={"trace_path": path, "format": fmt}
+    )
+    session.start(path, format=fmt)
+
+
+__all__: Iterable[str] = (
+    "ENV_TRACE_FORMAT",
+    "ENV_TRACE_PATH",
+    "auto_start_from_env",
+)

codetracer-python-recorder/codetracer_python_recorder/formats.py

@@ -0,0 +1,37 @@
+"""Trace format constants and helpers."""
+from __future__ import annotations
+
+from typing import Iterable
+
+TRACE_BINARY: str = "binary"
+TRACE_JSON: str = "json"
+DEFAULT_FORMAT: str = TRACE_BINARY
+SUPPORTED_FORMATS: frozenset[str] = frozenset({TRACE_BINARY, TRACE_JSON})
+
+
+def normalize_format(value: str | None) -> str:
+    """Normalise user-provided strings to the format names recognised by the backend.
+
+    The runtime currently accepts ``"binary"`` (plus legacy aliases handled
+    on the Rust side) and ``"json"``. Unknown formats fall back to the
+    lower-cased input so the backend can decide how to react; callers can
+    choose to guard against unsupported values by checking ``SUPPORTED_FORMATS``.
+    """
+    if value is None:
+        return DEFAULT_FORMAT
+    return value.lower()
+
+
+def is_supported(value: str) -> bool:
+    """Return ``True`` if *value* is one of the officially supported formats."""
+    return value.lower() in SUPPORTED_FORMATS
+
+
+__all__: Iterable[str] = (
+    "DEFAULT_FORMAT",
+    "TRACE_BINARY",
+    "TRACE_JSON",
+    "SUPPORTED_FORMATS",
+    "is_supported",
+    "normalize_format",
+)

codetracer-python-recorder/codetracer_python_recorder/session.py

@@ -0,0 +1,130 @@
+"""Tracing session management helpers."""
+from __future__ import annotations
+
+import contextlib
+from pathlib import Path
+from typing import Iterator, Optional
+
+from .codetracer_python_recorder import (
+    flush_tracing as _flush_backend,
+    is_tracing as _is_tracing_backend,
+    start_tracing as _start_backend,
+    stop_tracing as _stop_backend,
+)
+from .formats import DEFAULT_FORMAT, SUPPORTED_FORMATS, is_supported, normalize_format
+
+_active_session: Optional["TraceSession"] = None
+
+
+class TraceSession:
+    """Handle representing a live tracing session."""
+
+    path: Path
+    format: str
+
+    def __init__(self, path: Path, format: str) -> None:
+        self.path = path
+        self.format = format
+
+    def stop(self) -> None:
+        """Stop this trace session."""
+        if _active_session is self:
+            stop()
+
+    def flush(self) -> None:
+        """Flush buffered trace data for this session."""
+        flush()
+
+    def __enter__(self) -> "TraceSession":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:  # pragma: no cover - thin wrapper
+        self.stop()
+
+
+def start(
+    path: str | Path,
+    *,
+    format: str = DEFAULT_FORMAT,
+    start_on_enter: str | Path | None = None,
+) -> TraceSession:
+    """Start a new global trace session."""
+    global _active_session
+    if _is_tracing_backend():
+        raise RuntimeError("tracing already active")
+
+    trace_path = _validate_trace_path(Path(path))
+    normalized_format = _coerce_format(format)
+    activation_path = _normalize_activation_path(start_on_enter)
+
+    _start_backend(str(trace_path), normalized_format, activation_path)
+    session = TraceSession(path=trace_path, format=normalized_format)
+    _active_session = session
+    return session
+
+
+def stop() -> None:
+    """Stop the active trace session if one is running."""
+    global _active_session
+    if not _is_tracing_backend():
+        return
+    _stop_backend()
+    _active_session = None
+
+
+def is_tracing() -> bool:
+    """Return ``True`` when a trace session is active."""
+    return _is_tracing_backend()
+
+
+def flush() -> None:
+    """Flush buffered trace data."""
+    if _is_tracing_backend():
+        _flush_backend()
+
+
+@contextlib.contextmanager
+def trace(
+    path: str | Path,
+    *,
+    format: str = DEFAULT_FORMAT,
+) -> Iterator[TraceSession]:
+    """Context manager helper for scoped tracing."""
+    session = start(path, format=format)
+    try:
+        yield session
+    finally:
+        session.stop()
+
+
+def _coerce_format(value: str) -> str:
+    normalized = normalize_format(value)
+    if not is_supported(normalized):
+        supported = ", ".join(sorted(SUPPORTED_FORMATS))
+        raise ValueError(
+            f"unsupported trace format '{value}'. Expected one of: {supported}"
+        )
+    return normalized
+
+
+def _validate_trace_path(path: Path) -> Path:
+    path = path.expanduser()
+    if path.exists() and not path.is_dir():
+        raise ValueError("trace path exists and is not a directory")
+    return path
+
+
+def _normalize_activation_path(value: str | Path | None) -> str | None:
+    if value is None:
+        return None
+    return str(Path(value).expanduser())
+
+
+__all__ = (
+    "TraceSession",
+    "flush",
+    "is_tracing",
+    "start",
+    "stop",
+    "trace",
+)

codetracer-python-recorder/src/code_object.rs

@@ -1,3 +1,5 @@
+//! Shared code-object caching utilities for sys.monitoring callbacks.
+
 use dashmap::DashMap;
 use once_cell::sync::OnceCell;
 use pyo3::prelude::*;
@@ -148,7 +150,8 @@ impl CodeObjectRegistry {
         self.map
             .entry(id)
             .or_insert_with(|| Arc::new(CodeObjectWrapper::new(py, code)))
-            .clone() //AI? Why do we need to clone here?
+            // Clone the `Arc` so each caller receives its own reference-counted handle.
+            .clone()
     }
 
     /// Remove the wrapper for a given code id, if present.