Merge remote-tracking branch 'origin/main' into ci/393-20261003-ci-ruff-check-and-mypy-do-not-cover-the-compatibility-consum

Author: codeforester

docs/integrations.md

@@ -53,6 +53,13 @@ paths, and secrets are never attached. A missing API package, invalid provider,
 or failing exporter is logged at debug level and treated as a no-op; it cannot
 change the command's exit status or cleanup behavior.
 
+The span status is `OK` for a successful invocation and `ERROR` for every
+non-success outcome. Unexpected exceptions are recorded on failed spans;
+successful `SystemExit(0)` and Click exit-control flow are not recorded as
+exceptions. Interrupts and other non-success outcomes are therefore visible as
+errors while retaining the existing `base_cli.outcome` attribute for detailed
+dashboard filtering.
+
 ## Log timestamp environment variable
 
 Set `BASE_CLI_LOG_UTC=1` to make the default text formatter use UTC

lib/python/base_cli/_app_core.py

@@ -1038,6 +1038,7 @@ def wrapper(**kwargs: Any) -> Any:
             recorder: RunRecorder | None = None
             telemetry_session: TelemetrySession | None = None
             outcome = outcome_from_exit_code(ExitCode.SUCCESS)
+            exception: BaseException | None = None
             invocation_argv: list[str] = []
             redaction_plan = self._redaction_plan
             if redaction_plan is None:
@@ -1074,6 +1075,7 @@ def wrapper(**kwargs: Any) -> Any:
                 outcome = outcome_from_exit_code(exit_code)
                 return result
             except BaseException as exc:
+                exception = exc
                 if context is not None:
                     outcome = outcome_from_exception(click, exc)
                     _record_lifecycle_diagnostic(context, outcome)
@@ -1111,6 +1113,7 @@ def wrapper(**kwargs: Any) -> Any:
                             context,
                             outcome,
                             ended_monotonic_ns=ended_monotonic_ns,
+                            exception=exception,
                         )
                         _finish_run_recorder(
                             recorder,

lib/python/base_cli/_attach.py

@@ -71,6 +71,7 @@ def __init__(
         self.context: Context[Any, Any, Any] | None = None
         self.invocation: _AttachedInvocation | None = None
         self.telemetry_session: TelemetrySession | None = None
+        self.exception: BaseException | None = None
         self.context_token: Any = None
         self.invocation_token: Any = None
         self.original_click_exit: Callable[..., Any] | None = None
@@ -164,11 +165,16 @@ def record_result(self, _result: Any) -> None:
             state.attached_completion = True
 
     def record_exception(self, exc: BaseException) -> None:
+        outcome = outcome_from_exception(self.click, exc)
+        # Click represents a successful ``Context.exit(0)`` as an exception so
+        # it can unwind the context stack. It is control flow, not a failed
+        # command, and must not be exported as a span exception.
+        self.exception = None if str(outcome.status) == "ok" else exc
         state = _INVOCATION_STATE.get()
         if state is not None and state.owner_app is self.attachment.app:
             state.attached_completion = False
         if self.context is not None:
-            self.outcome = outcome_from_exception(self.click, exc)
+            self.outcome = outcome
             _record_lifecycle_diagnostic(self.context, self.outcome)
 
     def __exit__(
@@ -239,6 +245,7 @@ def _finalize(self) -> None:
             context,
             self.outcome,
             ended_monotonic_ns=ended_monotonic_ns,
+            exception=self.exception,
         )
         try:
             context.cleanup()

lib/python/base_cli/_lifecycle_install.py

@@ -93,7 +93,10 @@ def _capture_lifecycle_option(
 ) -> Any:
     source = click_context.get_parameter_source(parameter.name)
     captures = click_context.meta.setdefault(_LIFECYCLE_CAPTURE_META_KEY, {})
-    context_values = captures.setdefault(id(click_context), {})
+    # Keep the context object itself as the key. ``id(context)`` values can be
+    # reused after Click releases a context, which could associate a later
+    # invocation with stale lifecycle values.
+    context_values = captures.setdefault(click_context, {})
     context_values[key] = _RawLifecycleValue(
         value=value,
         source=source,
@@ -537,11 +540,15 @@ def _resolve_lifecycle_values(
         _LIFECYCLE_RESOLUTION_META_KEY,
         {},
     )
+    # These maps live in Click's invocation-shared metadata and retain one
+    # context-keyed entry per context until the root invocation closes. That
+    # bounded, per-invocation retention is deliberate: it prevents id reuse
+    # without retaining state across invocations.
     parent = getattr(click_context, "parent", None)
-    parent_resolution = resolution_map.get(id(parent)) if parent is not None else None
+    parent_resolution = resolution_map.get(parent) if parent is not None else None
     raw = dict(parent_resolution.raw) if isinstance(parent_resolution, _LifecycleResolution) else {}
     captures = click_context.meta.get(_LIFECYCLE_CAPTURE_META_KEY, {})
-    context_captures = captures.get(id(click_context), {})
+    context_captures = captures.get(click_context, {})
     depth = _context_depth(click_context)
 
     for key, binding in bindings.items():
@@ -576,7 +583,7 @@ def _resolve_lifecycle_values(
         values=_normalize_lifecycle_values(click, raw),
         raw=raw,
     )
-    resolution_map[id(click_context)] = resolution
+    resolution_map[click_context] = resolution
     click_context.meta[LIFECYCLE_META_KEY] = resolution.values
     return resolution
 

lib/python/base_cli/integrations.py

@@ -130,6 +130,7 @@ def finish_telemetry(
     outcome: Any,
     *,
     ended_monotonic_ns: int | None = None,
+    exception: BaseException | None = None,
 ) -> None:
     """Finish a lifecycle span without allowing exporters to affect teardown."""
 
@@ -148,6 +149,9 @@ def finish_telemetry(
         }
         for key, value in attributes.items():
             _safe_span_call(session.span, "set_attribute", key, value)
+        if exception is not None and str(getattr(outcome, "status", "error")) != "ok":
+            _safe_span_call(session.span, "record_exception", exception)
+        _set_span_status(session.span, outcome)
         _safe_span_call(
             session.span,
             "add_event",
@@ -173,6 +177,19 @@ def _start_attributes(context: Any) -> dict[str, Any]:
     }
 
 
+def _set_span_status(span: Any, outcome: Any) -> None:
+    """Set an OpenTelemetry status while remaining compatible with test spans."""
+
+    is_success = str(getattr(outcome, "status", "error")) == "ok"
+    try:
+        from opentelemetry.trace import Status, StatusCode
+
+        status: Any = Status(StatusCode.OK if is_success else StatusCode.ERROR)
+    except Exception:  # pragma: no cover - optional dependency boundary
+        status = "ok" if is_success else "error"
+    _safe_span_call(span, "set_status", status)
+
+
 def _safe_span_call(span: Any, method: str, *args: Any, **kwargs: Any) -> None:
     try:
         callback = getattr(span, method, None)

tests/test_click_tree_attachment.py

@@ -12,6 +12,7 @@
 from unittest import mock
 
 import base_cli
+from base_cli import _lifecycle_install
 from base_cli._runtime import RuntimeDirectoryError
 from base_cli.testing import invoke
 
@@ -63,6 +64,105 @@ def count_cleanup() -> None:
 
 @unittest.skipUnless(importlib.util.find_spec("click"), "Click is not installed")
 class ClickTreeAttachmentTests(unittest.TestCase):
+    def test_lifecycle_metadata_is_keyed_by_context_identity(self) -> None:
+        class FakeContext:
+            def __init__(self) -> None:
+                self.meta: dict[object, Any] = {}
+
+            def get_parameter_source(self, name: str) -> None:
+                del name
+                return None
+
+        first = FakeContext()
+        second = FakeContext()
+        parameter = type("Parameter", (), {"name": "environment"})()
+
+        _lifecycle_install._capture_lifecycle_option(first, parameter, "first", key="environment")
+        _lifecycle_install._capture_lifecycle_option(second, parameter, "second", key="environment")
+
+        captures = first.meta[next(key for key in first.meta if key is not None)]
+        self.assertIn(first, captures)
+        self.assertNotIn(id(first), captures)
+        self.assertEqual(captures[first]["environment"].value, "first")
+        second_captures = second.meta[next(key for key in second.meta if key is not None)]
+        self.assertIn(second, second_captures)
+        self.assertEqual(second_captures[second]["environment"].value, "second")
+
+    def test_chained_click_contexts_keep_lifecycle_values_through_teardown(self) -> None:
+        import click
+
+        observed: list[tuple[str, str | None, int]] = []
+        closed: list[str] = []
+
+        def capture_environment(click_context: Any, parameter: Any, value: Any) -> Any:
+            return _lifecycle_install._capture_lifecycle_option(
+                click_context,
+                parameter,
+                value,
+                key="environment",
+            )
+
+        @click.group(name="pipeline", chain=True)
+        def pipeline() -> None:
+            pass
+
+        @pipeline.command(name="first")
+        @click.option("--environment", callback=capture_environment)
+        def first(environment: str | None) -> None:
+            del environment
+            click_context = click.get_current_context()
+            captures = click_context.meta[_lifecycle_install._LIFECYCLE_CAPTURE_META_KEY]
+            observed.append(
+                (
+                    "first",
+                    captures[click_context]["environment"].value,
+                    len(captures),
+                )
+            )
+            click_context.call_on_close(lambda: closed.append("first"))
+
+        @pipeline.command(name="second")
+        @click.option("--environment", callback=capture_environment)
+        def second(environment: str | None) -> None:
+            del environment
+            click_context = click.get_current_context()
+            captures = click_context.meta[_lifecycle_install._LIFECYCLE_CAPTURE_META_KEY]
+            observed.append(
+                (
+                    "second",
+                    captures[click_context]["environment"].value,
+                    len(captures),
+                )
+            )
+            self.assertEqual(closed, ["first"])
+            click_context.call_on_close(lambda: closed.append("second"))
+
+        app = base_cli.App(name="pipeline", log_to_file=False)
+        app.attach(pipeline)
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = invoke(
+                app,
+                [
+                    "first",
+                    "--environment",
+                    "first-env",
+                    "second",
+                    "--environment",
+                    "second-env",
+                ],
+                home=Path(tmpdir),
+            )
+
+        self.assertEqual(result.exit_code, 0, result.output)
+        self.assertEqual(
+            [(name, value) for name, value, _capture_count in observed],
+            [("first", "first-env"), ("second", "second-env")],
+        )
+        self.assertGreaterEqual(observed[0][2], 2)
+        self.assertEqual(observed[0][2], observed[1][2])
+        self.assertEqual(closed, ["first", "second"])
+
     def test_prebuilt_single_command_preserves_click_contract_and_lifecycle(self) -> None:
         import click
 

tests/test_integrations.py

@@ -17,6 +17,8 @@ def __init__(self) -> None:
         self.attributes: dict[str, object] = {}
         self.events: list[tuple[str, dict[str, object]]] = []
         self.ended = False
+        self.status: object | None = None
+        self.exceptions: list[BaseException] = []
 
     def set_attribute(self, key: str, value: object) -> None:
         self.attributes[key] = value
@@ -27,6 +29,12 @@ def add_event(self, name: str, *, attributes: dict[str, object]) -> None:
     def end(self) -> None:
         self.ended = True
 
+    def set_status(self, status: object) -> None:
+        self.status = status
+
+    def record_exception(self, exception: BaseException) -> None:
+        self.exceptions.append(exception)
+
 
 class _Tracer:
     def __init__(self) -> None:
@@ -118,6 +126,28 @@ def main(ctx: base_cli.Context) -> None:
             ["base_cli.run.started", "base_cli.run.finished"],
         )
         self.assertIn("base_cli.duration_ms", tracer.span.attributes)
+        self.assertEqual(tracer.span.exceptions, [])
+        self.assertIsNotNone(tracer.span.status)
+
+    def test_telemetry_marks_failures_and_records_exception(self) -> None:
+        tracer = _Tracer()
+        app = base_cli.App(
+            name="telemetry-error",
+            log_to_file=False,
+            telemetry=base_cli.TelemetryOptions(tracer=tracer),
+        )
+
+        @app.command()
+        def main(ctx: base_cli.Context) -> None:
+            del ctx
+            raise RuntimeError("boom")
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = invoke(app, [], home=Path(tmpdir))
+
+        self.assertNotEqual(result.exit_code, 0)
+        self.assertEqual(len(tracer.span.exceptions), 1)
+        self.assertIsNotNone(tracer.span.status)
 
     def test_missing_or_broken_telemetry_never_changes_completion(self) -> None:
         app = base_cli.App(