metapathology 0.1.0__tar.gz

metapathology-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.3
+Name: metapathology
+Version: 0.1.0
+Summary: sys.meta_path diagnostics: find out who is messing with Python's import machinery
+Author: Glinte
+Author-email: Glinte <96855131+Glinte@users.noreply.github.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# metapathology
+
+**sys.meta_path diagnostics** — a tiny, stdlib-only debug tool that tells you
+*who is messing with Python's import machinery*: which finder claimed each
+import, who mutated `sys.meta_path` (and when, with a stack trace), and which
+modules were loaded in ways that bypass `sys.path_hooks`.
+
+Built for debugging **import hook contention** — the class of bug where two
+libraries (e.g. an editable-install finder and a `sys.path_hooks`-based
+instrumenter like `beartype.claw`) both want a say in how a module is loaded,
+and one silently loses. See
+[beartype#556](https://github.com/beartype/beartype/issues/556) for the
+motivating incident.
+
+## Status
+
+First working version: all three layers, CLI, and exit report are implemented
+and tested. Published to PyPI.
+
+## Usage
+
+Primary: run your program under observation, no code changes needed —
+
+```console
+$ python -m metapathology myscript.py --my-args
+$ python -m metapathology -m pytest tests/
+```
+
+A report is printed at exit. Prefer `python -m metapathology` over a bare
+`metapathology` command: it guarantees the hooks land in the same interpreter
+and venv as the code under investigation.
+
+Library API, for when a wrapper isn't possible (notebooks, embedded
+interpreters, "I can only touch `conftest.py`"):
+
+```python
+import metapathology
+
+metapathology.install()  # as early as possible
+```
+
+No dependencies, no configuration required. It's a debug tool: run it, read
+the report, remove it.
+
+## How it works
+
+Three layers, escalating in invasiveness, covering each other's blind spots:
+
+1. **Audit hook** (`sys.addaudithook`, passive, irremovable) — snapshots
+   `sys.meta_path` on every `import` event; detects wholesale reassignment
+   (`sys.meta_path = [...]`), which nothing else can catch.
+2. **Instrumented `sys.meta_path`** — a `list` subclass whose mutation methods
+   log *who* appended/inserted/removed finders, with stack traces, at mutation
+   time. Re-installed automatically if layer 1 sees it blown away.
+3. **Finder attribution** — each finder's `find_spec` is shadowed with a
+   logging wrapper in its instance dict (so third-party `isinstance` scans of
+   `sys.meta_path` still pass), recording exactly which finder claimed each
+   module.
+
+The exit report cross-references this log against `sys.modules` and a fresh
+`PathFinder.find_spec()` replay to flag modules that a meta-path finder
+short-circuited away from the standard `sys.path_hooks` chain.
+
+## Caveats
+
+- CPython only (relies on the `import` audit event and import-system
+  internals).
+- A debug tool by design: it deliberately perturbs `sys.meta_path` in
+  reversible ways. Don't ship it enabled in production.
+
+## Related search terms
+
+sys.meta_path diagnostics, import hook conflict, PEP 302 compliance, meta path
+finder debugging, sys.path_hooks bypass, editable install import hook,
+who imported this module.

metapathology-0.1.0/README.md

@@ -0,0 +1,75 @@
+# metapathology
+
+**sys.meta_path diagnostics** — a tiny, stdlib-only debug tool that tells you
+*who is messing with Python's import machinery*: which finder claimed each
+import, who mutated `sys.meta_path` (and when, with a stack trace), and which
+modules were loaded in ways that bypass `sys.path_hooks`.
+
+Built for debugging **import hook contention** — the class of bug where two
+libraries (e.g. an editable-install finder and a `sys.path_hooks`-based
+instrumenter like `beartype.claw`) both want a say in how a module is loaded,
+and one silently loses. See
+[beartype#556](https://github.com/beartype/beartype/issues/556) for the
+motivating incident.
+
+## Status
+
+First working version: all three layers, CLI, and exit report are implemented
+and tested. Published to PyPI.
+
+## Usage
+
+Primary: run your program under observation, no code changes needed —
+
+```console
+$ python -m metapathology myscript.py --my-args
+$ python -m metapathology -m pytest tests/
+```
+
+A report is printed at exit. Prefer `python -m metapathology` over a bare
+`metapathology` command: it guarantees the hooks land in the same interpreter
+and venv as the code under investigation.
+
+Library API, for when a wrapper isn't possible (notebooks, embedded
+interpreters, "I can only touch `conftest.py`"):
+
+```python
+import metapathology
+
+metapathology.install()  # as early as possible
+```
+
+No dependencies, no configuration required. It's a debug tool: run it, read
+the report, remove it.
+
+## How it works
+
+Three layers, escalating in invasiveness, covering each other's blind spots:
+
+1. **Audit hook** (`sys.addaudithook`, passive, irremovable) — snapshots
+   `sys.meta_path` on every `import` event; detects wholesale reassignment
+   (`sys.meta_path = [...]`), which nothing else can catch.
+2. **Instrumented `sys.meta_path`** — a `list` subclass whose mutation methods
+   log *who* appended/inserted/removed finders, with stack traces, at mutation
+   time. Re-installed automatically if layer 1 sees it blown away.
+3. **Finder attribution** — each finder's `find_spec` is shadowed with a
+   logging wrapper in its instance dict (so third-party `isinstance` scans of
+   `sys.meta_path` still pass), recording exactly which finder claimed each
+   module.
+
+The exit report cross-references this log against `sys.modules` and a fresh
+`PathFinder.find_spec()` replay to flag modules that a meta-path finder
+short-circuited away from the standard `sys.path_hooks` chain.
+
+## Caveats
+
+- CPython only (relies on the `import` audit event and import-system
+  internals).
+- A debug tool by design: it deliberately perturbs `sys.meta_path` in
+  reversible ways. Don't ship it enabled in production.
+
+## Related search terms
+
+sys.meta_path diagnostics, import hook conflict, PEP 302 compliance, meta path
+finder debugging, sys.path_hooks bypass, editable install import hook,
+who imported this module.

metapathology-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "metapathology"
+version = "0.1.0"
+description = "sys.meta_path diagnostics: find out who is messing with Python's import machinery"
+readme = "README.md"
+authors = [
+    { name = "Glinte", email = "96855131+Glinte@users.noreply.github.com" }
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.31.3",
+    "hypothesis>=6.146",
+    "prek>=0.2.20",
+    "pyrefly>=0.44.0",
+    "pytest>=8.3",
+    "pytest-cov>=6.3",
+    "pytest-timeout>=2.4",
+    "ruff>=0.12.11",
+]
+
+[tool.pytest.ini_options]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+]
+filterwarnings = ["error"]
+testpaths = ["tests"]
+timeout = 30
+xfail_strict = true
+
+[tool.uv]
+exclude-newer = "7 days"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "I",
+    "UP",
+    "RUF",
+    "PT",
+    "RET",
+    "SIM",
+    "PERF",
+]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.basedpyright]
+pythonVersion = "3.10"
+pythonPlatform = "All"
+typeCheckingMode = "standard"
+include = ["src", "tests"]
+exclude = ["**/__pycache__", "**/.*"]
+strictListInference = true
+strictDictionaryInference = true
+strictSetInference = true
+deprecateTypingAliases = true
+reportMissingParameterType = "error"
+reportUnnecessaryComparison = "error"
+reportUnnecessaryContains = "error"
+
+[tool.pyrefly]
+project-includes = ["src/**/*.py", "tests/**/*.py"]
+python-version = "3.10"
+
+[tool.coverage.run]
+branch = true
+source = ["metapathology"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+
+[build-system]
+requires = ["uv_build>=0.11.13,<0.12.0"]
+build-backend = "uv_build"

metapathology-0.1.0/src/metapathology/__init__.py

@@ -0,0 +1,36 @@
+"""metapathology: sys.meta_path diagnostics.
+
+Find out who is messing with Python's import machinery: which finder claimed
+each import, who mutated ``sys.meta_path`` (with stack traces), and which
+modules were loaded in ways that bypass ``sys.path_hooks``.
+
+Preferred usage is the CLI: ``python -m metapathology <script.py>`` or
+``python -m metapathology -m <module>``. The library API below exists for
+cases where a wrapper is impossible (notebooks, conftest.py-only access).
+"""
+
+from metapathology._monitor import Monitor, get_monitor, install, render_report, report, uninstall
+from metapathology._records import (
+    FindSpecCall,
+    InternalError,
+    MetaPathMutation,
+    MetaPathReassignment,
+    MonitorEvent,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FindSpecCall",
+    "InternalError",
+    "MetaPathMutation",
+    "MetaPathReassignment",
+    "Monitor",
+    "MonitorEvent",
+    "__version__",
+    "get_monitor",
+    "install",
+    "render_report",
+    "report",
+    "uninstall",
+]

metapathology-0.1.0/src/metapathology/__main__.py

@@ -0,0 +1,92 @@
+"""Command-line entry point: run a script or module under the monitor.
+
+Mirrors the invocation style of ``python -m cProfile`` / ``python -m trace``.
+The usual runpy caveats apply: the target runs as ``__main__`` but with a
+slightly different ``__spec__`` than a direct invocation would have.
+"""
+
+import os
+import runpy
+import sys
+import traceback
+
+import metapathology
+
+_USAGE = """\
+usage: python -m metapathology <script.py> [args...]
+       python -m metapathology -m <module> [args...]
+
+Runs the target under the metapathology import-machinery monitor and writes a
+diagnostic report to stderr when the target finishes.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Parse CLI arguments and dispatch to script or module execution.
+
+    Args:
+        argv: Argument list without the program name; defaults to ``sys.argv[1:]``.
+
+    Returns:
+        The process exit code.
+    """
+    args = sys.argv[1:] if argv is None else argv
+    if not args:
+        sys.stderr.write(_USAGE)
+        return 2
+    if args[0] in ("-h", "--help"):
+        sys.stdout.write(_USAGE)
+        return 0
+    if args[0] == "-m":
+        if len(args) < 2:
+            sys.stderr.write(_USAGE)
+            return 2
+        return _run(args[1], args[2:], is_module=True)
+    return _run(args[0], args[1:], is_module=False)
+
+
+def _run(target: str, target_args: list[str], *, is_module: bool) -> int:
+    """Install the monitor, run the target via runpy, and always write the report.
+
+    Args:
+        target: Script path, or module name when ``is_module`` is true.
+        target_args: Arguments the target sees as ``sys.argv[1:]``.
+        is_module: Select ``python -m``-style execution instead of a script path.
+
+    Returns:
+        The exit code a direct invocation of the target would produce.
+    """
+    metapathology.install(report_at_exit=False)
+    exit_code = 0
+    try:
+        sys.argv = [target, *target_args]
+        if is_module:
+            # Mimic `python -m target`: cwd on sys.path; run_module fixes argv[0].
+            sys.path.insert(0, os.getcwd())
+            runpy.run_module(target, run_name="__main__", alter_sys=True)
+        else:
+            # Mimic `python target.py`: the script's directory on sys.path.
+            sys.path.insert(0, os.path.dirname(os.path.abspath(target)))
+            runpy.run_path(target, run_name="__main__")
+    except SystemExit as exc:
+        exit_code = _exit_code(exc)
+    except BaseException:
+        traceback.print_exc()
+        exit_code = 1
+    finally:
+        metapathology.report()
+    return exit_code
+
+
+def _exit_code(exc: SystemExit) -> int:
+    """Translate ``SystemExit`` into an exit code, printing string payloads the way the interpreter does."""
+    if exc.code is None:
+        return 0
+    if isinstance(exc.code, int):
+        return exc.code
+    sys.stderr.write(f"{exc.code}\n")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

metapathology-0.1.0/src/metapathology/_monitor.py

@@ -0,0 +1,570 @@
+"""Core monitor: audit hook, instrumented ``sys.meta_path`` list, finder shadowing.
+
+Hot-path rules (see CLAUDE.md): everything needed here is imported at module
+scope; recording code takes ``_record_lock`` only around plain-data appends;
+foreign objects are reduced to type names and ids at capture time.
+"""
+
+import atexit
+import contextlib
+import functools
+import sys
+import threading
+import traceback
+from typing import TYPE_CHECKING, Any, SupportsIndex, TextIO
+
+from metapathology import _report
+from metapathology._records import (
+    FindSpecCall,
+    InternalError,
+    MetaPathMutation,
+    MetaPathReassignment,
+    MonitorEvent,
+    type_name,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+    from types import FrameType
+
+    from _typeshed.importlib import MetaPathFinderProtocol
+    from typing_extensions import Self
+
+# Frames captured per event; the report trims further (and filters noise) at display time.
+_STACK_CAPTURE_LIMIT = 20
+
+
+def _capture_stack(frame: "FrameType") -> traceback.StackSummary:
+    """Capture a stack summary from ``frame`` outward without reading source lines.
+
+    ``lookup_lines=False`` keeps source reading (and any ``__loader__.get_source``
+    side effects) out of the import hot path; lines resolve at format time.
+
+    Args:
+        frame: Innermost frame to start walking from.
+    """
+    return traceback.StackSummary.extract(traceback.walk_stack(frame), limit=_STACK_CAPTURE_LIMIT, lookup_lines=False)
+
+
+class Monitor:
+    """Records import-machinery activity. Use the module-level :func:`install`."""
+
+    def __init__(self) -> None:
+        # Guards _events/_seq/_patched/_skipped. Held only around plain-data
+        # reads/writes, never across foreign code.
+        self._record_lock = threading.Lock()
+        # Serializes install/uninstall/reinstall. Lock order: _reinstall_lock
+        # may be held while taking _record_lock, never the other way around.
+        self._reinstall_lock = threading.Lock()
+        # Per-thread re-entrancy flag (.in_audit) so an import triggered from
+        # inside _audit cannot recurse back into it.
+        self._local = threading.local()
+        # One counter for all record types, so the report can interleave the
+        # different event kinds chronologically.
+        self._seq = 0
+        self._events: list[MonitorEvent] = []
+        # Master switch: hooks stay registered after uninstall() (audit hooks
+        # are irremovable) but become no-ops when this is False.
+        self._enabled = False
+        # sys.addaudithook is one-way; remember so a reinstall never stacks a second hook.
+        self._audit_installed = False
+        # Whether our atexit callback is currently registered (mirrors it for unregister).
+        self._report_at_exit = False
+        # The exact list object we last put into sys.meta_path. The audit hook
+        # compares by identity: a mismatch means someone reassigned sys.meta_path.
+        self._instrumented: _InstrumentedMetaPath | None = None
+        # Both dicts key by id(finder) and hold strong finder references, keeping ids
+        # unique for the process lifetime.
+        # id -> (finder, original find_spec). A None original marks an
+        # in-progress claim, so concurrent callers cannot double-wrap.
+        self._patched: dict[int, tuple[Any, Any]] = {}
+        # id -> (finder, human-readable reason it could not be instrumented).
+        self._skipped: dict[int, tuple[Any, str]] = {}
+        # sys.modules names at install time; the report analyzes only modules
+        # imported afterwards.
+        self._baseline_modules: frozenset[str] = frozenset()
+        # Finder display names at install time, for the report header.
+        self._initial_meta_path: tuple[str, ...] = ()
+
+    @property
+    def enabled(self) -> bool:
+        """Whether the monitor is currently observing."""
+        return self._enabled
+
+    @property
+    def initial_meta_path(self) -> tuple[str, ...]:
+        """Finder names in ``sys.meta_path`` at install time."""
+        return self._initial_meta_path
+
+    @property
+    def baseline_modules(self) -> frozenset[str]:
+        """Names present in ``sys.modules`` at install time."""
+        return self._baseline_modules
+
+    def events(self) -> list[MonitorEvent]:
+        """Return a snapshot of all recorded events, in capture order."""
+        with self._record_lock:
+            return list(self._events)
+
+    def skipped_finders(self) -> list[tuple[str, str]]:
+        """Return ``(finder name, reason)`` for meta-path entries that could not be instrumented."""
+        with self._record_lock:
+            return [(type_name(finder), reason) for finder, reason in self._skipped.values()]
+
+    def install(self, *, report_at_exit: bool = True) -> None:
+        """Instrument ``sys.meta_path`` and register the import audit hook (idempotent).
+
+        Args:
+            report_at_exit: Also register an atexit callback that writes the
+                report to stderr.
+        """
+        with self._reinstall_lock:
+            if self._enabled:
+                return
+            self._enabled = True
+            self._baseline_modules = frozenset(sys.modules)
+            current = sys.meta_path
+            self._initial_meta_path = tuple(type_name(f) for f in current)
+            instrumented = _InstrumentedMetaPath(current, self)
+            for finder in list(instrumented):
+                self._instrument_finder(finder)
+            self._instrumented = instrumented
+            sys.meta_path = instrumented
+            if not self._audit_installed:
+                # Audit hooks are irremovable; _audit goes inert when disabled.
+                sys.addaudithook(self._audit)
+                self._audit_installed = True
+        if report_at_exit and not self._report_at_exit:
+            self._report_at_exit = True
+            atexit.register(self._report_atexit)
+
+    def uninstall(self) -> None:
+        """Restore a plain ``sys.meta_path`` list and unshadow all finders (idempotent)."""
+        with self._reinstall_lock:
+            if not self._enabled:
+                return
+            self._enabled = False
+            current = sys.meta_path
+            if isinstance(current, _InstrumentedMetaPath):
+                sys.meta_path = list(current)
+            self._instrumented = None
+            for finder, _original in list(self._patched.values()):
+                with contextlib.suppress(AttributeError, KeyError, TypeError):
+                    del finder.__dict__["find_spec"]
+            with self._record_lock:
+                self._patched.clear()
+                self._skipped.clear()
+        if self._report_at_exit:
+            self._report_at_exit = False
+            atexit.unregister(self._report_atexit)
+
+    def _audit(self, event: str, args: tuple[Any, ...]) -> None:
+        """``sys.addaudithook`` callback: detect ``sys.meta_path`` reassignment on each ``import`` event.
+
+        Audit hooks are irremovable, so this must stay a cheap no-op once the
+        monitor is disabled. Exceptions are diverted into the event log because
+        an exception escaping an audit hook would abort the user's import.
+
+        Args:
+            event: Audit event name; everything but ``"import"`` is ignored.
+            args: Audit event arguments; for ``import`` the first item is the
+                name of the module being resolved.
+        """
+        if event != "import" or not self._enabled:
+            return
+        if getattr(self._local, "in_audit", False):
+            return
+        self._local.in_audit = True
+        try:
+            if sys.meta_path is self._instrumented:
+                return
+            self._reinstall(args)
+        except Exception as exc:
+            # An exception escaping an audit hook aborts the user's import.
+            self._record_internal_error("audit_hook", exc)
+        finally:
+            self._local.in_audit = False
+
+    def _reinstall(self, args: tuple[Any, ...]) -> None:
+        """Wrap a foreign ``sys.meta_path`` in fresh instrumentation and record the reassignment.
+
+        Args:
+            args: The ``import`` audit event arguments, used to attribute the
+                detection to the import that was in flight.
+        """
+        with self._reinstall_lock:
+            # Re-check: another importing thread may have reinstalled already.
+            current = sys.meta_path
+            expected = self._instrumented
+            if current is expected or expected is None or not self._enabled:
+                return
+            old_contents = tuple(type_name(f) for f in list(expected))
+            new_contents = tuple(type_name(f) for f in list(current))
+            replacement = _InstrumentedMetaPath(current, self)
+            for finder in list(replacement):
+                self._instrument_finder(finder)
+            self._instrumented = replacement
+            sys.meta_path = replacement
+        fullname = args[0] if args and isinstance(args[0], str) else "<unknown>"
+        stack = _capture_stack(sys._getframe())
+        thread_name = threading.current_thread().name
+        with self._record_lock:
+            self._seq += 1
+            self._events.append(
+                MetaPathReassignment(
+                    seq=self._seq,
+                    during_import=fullname,
+                    old_contents=old_contents,
+                    new_contents=new_contents,
+                    thread_name=thread_name,
+                    stack=stack,
+                )
+            )
+
+    def _instrument_finder(self, finder: object) -> None:
+        """Shadow ``finder.find_spec`` with a recording wrapper in the instance dict (layer 3).
+
+        Instance-dict shadowing keeps third-party ``isinstance`` scans of
+        ``sys.meta_path`` working. Entries that cannot be shadowed (classes,
+        ``__slots__`` instances, objects without ``find_spec``) are remembered
+        as skipped and attributed by elimination at report time.
+
+        Args:
+            finder: Any ``sys.meta_path`` entry; safe to pass repeatedly.
+        """
+        finder_id = id(finder)
+        with self._record_lock:
+            if finder_id in self._patched or finder_id in self._skipped:
+                return
+            # Claim the id before touching the finder so concurrent callers don't double-wrap.
+            self._patched[finder_id] = (finder, None)
+        if isinstance(finder, type):
+            # Class entries (PathFinder and friends) are shared stdlib state; never mutate them.
+            self._skip_finder(finder_id, finder, "class entry; instance-dict shadowing not applicable")
+            return
+        try:
+            original = getattr(finder, "find_spec", None)
+        except Exception as exc:
+            self._skip_finder(finder_id, finder, "find_spec lookup raised")
+            self._record_internal_error("instrument_finder", exc)
+            return
+        if not callable(original):
+            self._skip_finder(finder_id, finder, "no callable find_spec")
+            return
+        wrapper = self._make_find_spec_wrapper(finder, original)
+        try:
+            setattr(finder, "find_spec", wrapper)
+        except Exception:
+            self._skip_finder(finder_id, finder, "find_spec not settable on the instance")
+            return
+        with self._record_lock:
+            self._patched[finder_id] = (finder, original)
+
+    def _skip_finder(self, finder_id: int, finder: object, reason: str) -> None:
+        """Mark a finder as uninstrumentable, releasing any claim taken by ``_instrument_finder``.
+
+        Args:
+            finder_id: ``id(finder)``, the claim key.
+            finder: The entry itself; kept referenced so its id stays unique.
+            reason: Human-readable explanation shown in the report.
+        """
+        with self._record_lock:
+            self._patched.pop(finder_id, None)
+            self._skipped[finder_id] = (finder, reason)
+
+    def _make_find_spec_wrapper(self, finder: object, original: "Callable[..., Any]") -> "Callable[..., Any]":
+        """Build the ``find_spec`` replacement that records each call and delegates to the original.
+
+        Args:
+            finder: The finder being shadowed, for attribution.
+            original: The bound ``find_spec`` to delegate to.
+
+        Returns:
+            A plain function suitable for the finder's instance dict; functions
+            stored there are not bound, so it takes no ``self``.
+        """
+
+        @functools.wraps(original)
+        def find_spec(fullname: str, path: Any = None, target: Any = None) -> Any:
+            spec = None
+            exception_type_name: str | None = None
+            try:
+                spec = original(fullname, path, target)
+            except BaseException as exc:
+                exception_type_name = type(exc).__name__
+                raise
+            finally:
+                self._record_find_spec(finder, fullname, spec, exception_type_name)
+            return spec
+
+        return find_spec
+
+    def _record_find_spec(self, finder: object, fullname: str, spec: Any, exception_type_name: str | None) -> None:
+        """Record one ``find_spec`` call, reducing the spec to primitives before taking the lock.
+
+        Args:
+            finder: The finder that was called.
+            fullname: The module name that was probed.
+            spec: Whatever ``find_spec`` returned; ``None`` means the finder passed.
+            exception_type_name: Set when the call raised instead of returning.
+        """
+        try:
+            loader_type_name: str | None = None
+            origin: str | None = None
+            if spec is not None:
+                loader = getattr(spec, "loader", None)
+                if loader is not None:
+                    loader_type_name = type_name(loader)
+                raw_origin = getattr(spec, "origin", None)
+                if isinstance(raw_origin, str):
+                    origin = raw_origin
+            finder_type_name = type_name(finder)
+            finder_id = id(finder)
+            found = spec is not None
+            thread_name = threading.current_thread().name
+            with self._record_lock:
+                self._seq += 1
+                self._events.append(
+                    FindSpecCall(
+                        seq=self._seq,
+                        fullname=fullname,
+                        finder_type_name=finder_type_name,
+                        finder_id=finder_id,
+                        found=found,
+                        loader_type_name=loader_type_name,
+                        origin=origin,
+                        exception_type_name=exception_type_name,
+                        thread_name=thread_name,
+                    )
+                )
+        except Exception as exc:
+            self._record_internal_error("record_find_spec", exc)
+
+    def _on_meta_path_mutation(
+        self,
+        mutated: "_InstrumentedMetaPath",
+        op: str,
+        added: tuple[object, ...],
+        removed: tuple[object, ...],
+        frame: "FrameType",
+    ) -> None:
+        """Record a mutation of the instrumented list and instrument any newly added finders.
+
+        Called by every overridden mutator of ``_InstrumentedMetaPath``.
+
+        Args:
+            mutated: The list that was mutated (not necessarily the live
+                ``sys.meta_path`` anymore, after a reassignment).
+            op: Name of the mutating method, e.g. ``"insert"``.
+            added: Finders the mutation added.
+            removed: Finders the mutation removed.
+            frame: The mutator's caller, where the stack capture starts.
+        """
+        try:
+            if not self._enabled:
+                return
+            for finder in added:
+                self._instrument_finder(finder)
+            added_names = tuple(type_name(f) for f in added)
+            removed_names = tuple(type_name(f) for f in removed)
+            contents_after = tuple(type_name(f) for f in list(mutated))
+            thread_name = threading.current_thread().name
+            stack = _capture_stack(frame)
+            with self._record_lock:
+                self._seq += 1
+                self._events.append(
+                    MetaPathMutation(
+                        seq=self._seq,
+                        op=op,
+                        added=added_names,
+                        removed=removed_names,
+                        contents_after=contents_after,
+                        thread_name=thread_name,
+                        stack=stack,
+                    )
+                )
+        except Exception as exc:
+            self._record_internal_error("meta_path_mutation", exc)
+
+    def _record_internal_error(self, where: str, exc: BaseException) -> None:
+        """Record an exception raised by our own instrumentation instead of letting it escape.
+
+        Args:
+            where: Short label of the code path that failed.
+            exc: The caught exception; stringified defensively here.
+        """
+        try:
+            message = str(exc)
+        except Exception:
+            message = "<unprintable>"
+        exception_type_name = type(exc).__name__
+        with self._record_lock:
+            self._seq += 1
+            self._events.append(
+                InternalError(seq=self._seq, where=where, exception_type_name=exception_type_name, message=message)
+            )
+
+    def _report_atexit(self) -> None:
+        """Write the report to stderr from atexit without ever breaking interpreter shutdown."""
+        try:
+            _report.write_report(self, sys.stderr)
+        except Exception:
+            traceback.print_exc()
+
+
+class _InstrumentedMetaPath(list["MetaPathFinderProtocol"]):
+    """Drop-in ``sys.meta_path`` replacement that records mutations.
+
+    A real ``list`` subclass, never a proxy: third-party code that scans
+    ``sys.meta_path`` with ``isinstance``, slices it, or iterates it keeps
+    working unchanged. Mutations made from C via ``PyList_*`` bypass these
+    overrides; that is an accepted blind spot.
+    """
+
+    __slots__ = ("_monitor",)
+
+    def __init__(self, contents: "Iterable[MetaPathFinderProtocol]", monitor: Monitor) -> None:
+        """Wrap ``contents`` without recording a mutation.
+
+        Args:
+            contents: The finders to start with, typically the previous
+                ``sys.meta_path``.
+            monitor: The monitor that receives mutation callbacks.
+        """
+        super().__init__(contents)
+        self._monitor = monitor
+
+    def append(self, item: "MetaPathFinderProtocol") -> None:
+        """Delegate to ``list.append`` and record the addition."""
+        super().append(item)
+        self._monitor._on_meta_path_mutation(self, "append", (item,), (), sys._getframe(1))
+
+    def insert(self, index: SupportsIndex, item: "MetaPathFinderProtocol") -> None:
+        """Delegate to ``list.insert`` and record the addition."""
+        super().insert(index, item)
+        self._monitor._on_meta_path_mutation(self, "insert", (item,), (), sys._getframe(1))
+
+    def extend(self, items: "Iterable[MetaPathFinderProtocol]") -> None:
+        """Record an ``extend``, materializing ``items`` first so one-shot iterators can be both stored and logged."""
+        materialized = tuple(items)
+        super().extend(materialized)
+        self._monitor._on_meta_path_mutation(self, "extend", materialized, (), sys._getframe(1))
+
+    def remove(self, item: "MetaPathFinderProtocol") -> None:
+        """Delegate to ``list.remove`` and record the removal."""
+        super().remove(item)
+        self._monitor._on_meta_path_mutation(self, "remove", (), (item,), sys._getframe(1))
+
+    def pop(self, index: SupportsIndex = -1) -> "MetaPathFinderProtocol":
+        """Delegate to ``list.pop`` and record the removal.
+
+        Returns:
+            The removed finder, as ``list.pop`` would.
+        """
+        item = super().pop(index)
+        self._monitor._on_meta_path_mutation(self, "pop", (), (item,), sys._getframe(1))
+        return item
+
+    def clear(self) -> None:
+        """Record the removal of the entire contents, then delegate to ``list.clear``."""
+        removed = tuple(self)
+        super().clear()
+        self._monitor._on_meta_path_mutation(self, "clear", (), removed, sys._getframe(1))
+
+    def reverse(self) -> None:
+        """Record an order-only mutation; finder precedence changes even though membership does not."""
+        super().reverse()
+        self._monitor._on_meta_path_mutation(self, "reverse", (), (), sys._getframe(1))
+
+    def __setitem__(self, index: SupportsIndex | slice, value: Any) -> None:
+        """Record single-item or slice replacement (slice assignment is how many tools filter finders)."""
+        if isinstance(index, slice):
+            added = tuple(value)
+            removed = tuple(self[index])
+            super().__setitem__(index, added)
+        else:
+            added = (value,)
+            removed = (self[index],)
+            super().__setitem__(index, value)
+        self._monitor._on_meta_path_mutation(self, "__setitem__", added, removed, sys._getframe(1))
+
+    def __delitem__(self, index: SupportsIndex | slice) -> None:
+        """Delegate to ``list.__delitem__`` and record the removed finder(s)."""
+        removed = tuple(self[index]) if isinstance(index, slice) else (self[index],)
+        super().__delitem__(index)
+        self._monitor._on_meta_path_mutation(self, "__delitem__", (), removed, sys._getframe(1))
+
+    def __iadd__(self, items: "Iterable[MetaPathFinderProtocol]") -> "Self":
+        """Record ``+=``, which reaches ``list`` at the C level and would otherwise bypass the ``extend`` override."""
+        materialized = tuple(items)
+        super().extend(materialized)
+        self._monitor._on_meta_path_mutation(self, "__iadd__", materialized, (), sys._getframe(1))
+        return self
+
+
+# One Monitor per process: the instrumentation targets process-global state
+# (sys.meta_path, the audit hook), so multiple instances would fight each other.
+_monitor_singleton: Monitor | None = None
+_singleton_lock = threading.Lock()
+
+
+def install(*, report_at_exit: bool = True) -> Monitor:
+    """Install the import-machinery monitor (idempotent) and return it.
+
+    Call as early as possible: only imports and mutations that happen after
+    this call are observed.
+
+    Args:
+        report_at_exit: Also register an atexit callback that writes the
+            report to stderr.
+    """
+    global _monitor_singleton
+    with _singleton_lock:
+        if _monitor_singleton is None:
+            _monitor_singleton = Monitor()
+        monitor = _monitor_singleton
+    monitor.install(report_at_exit=report_at_exit)
+    return monitor
+
+
+def uninstall() -> None:
+    """Undo :func:`install`: restore a plain ``sys.meta_path`` and unshadow finders."""
+    monitor = get_monitor()
+    if monitor is not None:
+        monitor.uninstall()
+
+
+def get_monitor() -> Monitor | None:
+    """Return the process-wide monitor, or None if :func:`install` was never called."""
+    with _singleton_lock:
+        return _monitor_singleton
+
+
+def report(file: TextIO | None = None) -> None:
+    """Write the diagnostic report to ``file`` (default ``sys.stderr``).
+
+    Raises:
+        RuntimeError: If :func:`install` was never called.
+    """
+    _report.write_report(_require_monitor(), file)
+
+
+def render_report() -> str:
+    """Return the diagnostic report as text.
+
+    Raises:
+        RuntimeError: If :func:`install` was never called.
+    """
+    return _report.render_report(_require_monitor())
+
+
+def _require_monitor() -> Monitor:
+    """Return the singleton monitor.
+
+    Raises:
+        RuntimeError: If :func:`install` was never called.
+    """
+    monitor = get_monitor()
+    if monitor is None:
+        raise RuntimeError("metapathology.install() has not been called")
+    return monitor

metapathology-0.1.0/src/metapathology/_records.py

@@ -0,0 +1,134 @@
+"""Plain event records captured by the monitor.
+
+Records hold only primitive data (type names, ids, precomputed strings)
+extracted at capture time. Foreign objects are never repr()'d while an import
+may be in flight; all formatting happens at report time in ``_report``.
+"""
+
+from dataclasses import dataclass
+from traceback import StackSummary
+from typing import TypeAlias
+
+
+def type_name(obj: object) -> str:
+    """Best-effort display name: ``__name__`` for class entries (e.g. ``PathFinder``), type name otherwise."""
+    if isinstance(obj, type):
+        return obj.__name__
+    return type(obj).__name__
+
+
+@dataclass(frozen=True, slots=True)
+class MetaPathMutation:
+    """A mutating method call observed on the instrumented ``sys.meta_path`` list.
+
+    Attributes:
+        seq: Position in the monitor's single event log; one counter is shared
+            by all record types so events can be interleaved chronologically.
+        op: Name of the list method that mutated the list, e.g. ``"insert"``
+            or ``"__setitem__"``.
+        added: Display names (via :func:`type_name`) of finders the mutation
+            added; empty for pure removals and order changes.
+        removed: Display names of finders the mutation removed.
+        contents_after: Display names of the whole list right after the
+            mutation. This is the mutated list, which after a reassignment is
+            not necessarily the live ``sys.meta_path``.
+        thread_name: Name of the thread that performed the mutation.
+        stack: Caller stack at mutation time, innermost frame first, captured
+            without source lines (they are resolved at report time).
+    """
+
+    seq: int
+    op: str
+    added: tuple[str, ...]
+    removed: tuple[str, ...]
+    contents_after: tuple[str, ...]
+    thread_name: str
+    stack: StackSummary
+
+
+@dataclass(frozen=True, slots=True)
+class MetaPathReassignment:
+    """``sys.meta_path`` was replaced wholesale, detected via the ``import`` audit event.
+
+    Detection granularity is the next import after the fact, so every field
+    describes the state *at detection time*, not at the moment of reassignment.
+
+    Attributes:
+        seq: Position in the monitor's single event log (shared counter, see
+            :class:`MetaPathMutation`).
+        during_import: Name of the module whose import triggered detection.
+            The reassignment happened some time before this import.
+        old_contents: Display names of the abandoned instrumented list's
+            entries at detection time; they may have drifted since the
+            reassignment.
+        new_contents: Display names of the entries of the list that replaced
+            ours.
+        thread_name: Name of the thread whose import triggered detection.
+        stack: Stack of the triggering import, not of the reassigner (plain
+            attribute assignment raises no event, so that stack is unknowable).
+    """
+
+    seq: int
+    during_import: str
+    old_contents: tuple[str, ...]
+    new_contents: tuple[str, ...]
+    thread_name: str
+    stack: StackSummary
+
+
+@dataclass(frozen=True, slots=True)
+class FindSpecCall:
+    """One ``find_spec`` call on an instrumented meta-path finder.
+
+    Attributes:
+        seq: Position in the monitor's single event log (shared counter, see
+            :class:`MetaPathMutation`).
+        fullname: The module name that was probed.
+        finder_type_name: Display name of the finder that was asked.
+        finder_id: ``id()`` of that finder; stable because the monitor keeps a
+            strong reference, and needed to tell apart two finders of the same
+            type.
+        found: True when the finder claimed the module (returned a spec).
+        loader_type_name: Display name of ``spec.loader``'s type, or None when
+            there is no spec or no loader (e.g. namespace packages).
+        origin: ``spec.origin`` when it is a string (a file path for
+            filesystem imports), else None.
+        exception_type_name: Type name of the exception if ``find_spec``
+            raised instead of returning; ``found`` is False in that case.
+        thread_name: Name of the thread that ran the import.
+    """
+
+    seq: int
+    fullname: str
+    finder_type_name: str
+    finder_id: int
+    found: bool
+    loader_type_name: str | None
+    origin: str | None
+    exception_type_name: str | None
+    thread_name: str
+
+
+@dataclass(frozen=True, slots=True)
+class InternalError:
+    """An exception raised inside metapathology's own instrumentation.
+
+    Recorded instead of raised: an exception escaping a hook would abort the
+    user's import, which a diagnostic tool must never do.
+
+    Attributes:
+        seq: Position in the monitor's single event log (shared counter, see
+            :class:`MetaPathMutation`).
+        where: Short label of the failing code path, e.g. ``"audit_hook"``.
+        exception_type_name: Type name of the caught exception.
+        message: ``str(exc)``, or a placeholder if stringification failed too.
+    """
+
+    seq: int
+    where: str
+    exception_type_name: str
+    message: str
+
+
+# Everything the monitor records goes into one chronological log; ``seq`` orders records across types.
+MonitorEvent: TypeAlias = FindSpecCall | InternalError | MetaPathMutation | MetaPathReassignment

metapathology-0.1.0/src/metapathology/_report.py

@@ -0,0 +1,286 @@
+"""Rendering of the diagnostic report.
+
+All stringification of foreign data (specs, loaders, stack frames) happens
+here, at report time, never while an import is in flight. The report is
+typically written from an atexit callback, so nothing here may raise.
+"""
+
+import os
+import sys
+from importlib.machinery import PathFinder
+from typing import TYPE_CHECKING, TextIO
+
+from metapathology._records import (
+    FindSpecCall,
+    InternalError,
+    MetaPathMutation,
+    MetaPathReassignment,
+    type_name,
+)
+
+if TYPE_CHECKING:
+    from importlib.machinery import ModuleSpec
+    from traceback import StackSummary
+
+    from metapathology._monitor import Monitor
+
+# This package's own directory, normcased for comparison: used to drop our
+# frames from displayed stacks.
+_PACKAGE_DIR = os.path.normcase(os.path.dirname(os.path.abspath(__file__)))
+# Only claims with these origin suffixes get the bypass check; extension
+# modules, builtins, and synthetic origins have no PathFinder baseline.
+_SOURCE_SUFFIXES = (".py", ".pyc")
+# Max non-noise frames shown per stack in the report.
+_STACK_DISPLAY_FRAMES = 5
+# Max claimed modules listed per finder in the attribution section.
+_MAX_LISTED_MODULES = 25
+
+
+def write_report(monitor: "Monitor", file: TextIO | None = None) -> None:
+    """Render the report for ``monitor`` and write it to ``file`` (default ``sys.stderr``)."""
+    out = sys.stderr if file is None else file
+    out.write(render_report(monitor))
+
+
+def render_report(monitor: "Monitor") -> str:
+    """Render the full diagnostic report as text.
+
+    Never raises; on internal failure the returned text says so instead.
+    """
+    try:
+        return "\n".join(_render_lines(monitor)) + "\n"
+    except Exception as exc:  # The report must never break the host program.
+        return f"== metapathology report ==\nreport generation failed: {type(exc).__name__}: {exc}\n"
+
+
+def _render_lines(monitor: "Monitor") -> list[str]:
+    """Build the report body as a list of lines; the caller joins and appends the trailing newline."""
+    events = monitor.events()
+    mutations = [e for e in events if isinstance(e, MetaPathMutation)]
+    reassignments = [e for e in events if isinstance(e, MetaPathReassignment)]
+    calls = [e for e in events if isinstance(e, FindSpecCall)]
+    errors = [e for e in events if isinstance(e, InternalError)]
+
+    lines = ["== metapathology report =="]
+    lines.append(f"monitor enabled: {monitor.enabled}")
+    lines.append(f"initial sys.meta_path: {_names_line(monitor.initial_meta_path)}")
+    lines.append(f"current sys.meta_path: {_names_line(_current_meta_path_names())}")
+    skipped = monitor.skipped_finders()
+    if skipped:
+        lines.append("finders observed but not instrumented (attribution by elimination):")
+        lines.extend(f"    {name}: {reason}" for name, reason in skipped)
+    new_modules = _modules_since_install(monitor)
+    lines.append(f"modules imported since install: {len(new_modules)}")
+
+    lines.append("")
+    lines.append(f"-- sys.meta_path mutations ({len(mutations)}) --")
+    if not mutations:
+        lines.append("(none)")
+    for mutation in mutations:
+        lines.extend(_mutation_lines(mutation))
+
+    lines.append("")
+    lines.append(f"-- sys.meta_path reassignments ({len(reassignments)}) --")
+    if not reassignments:
+        lines.append("(none)")
+    for reassignment in reassignments:
+        lines.extend(_reassignment_lines(reassignment))
+
+    lines.append("")
+    lines.append("-- finder attribution (instrumented finders only) --")
+    lines.extend(_attribution_lines(calls))
+
+    findings = _suspicious_findings(monitor, calls)
+    lines.append("")
+    lines.append(f"-- suspicious findings ({len(findings)}) --")
+    if not findings:
+        lines.append("(none)")
+    lines.extend(findings)
+
+    lines.append("")
+    lines.append(f"-- internal errors ({len(errors)}) --")
+    if not errors:
+        lines.append("(none)")
+    lines.extend(f"#{e.seq} in {e.where}: {e.exception_type_name}: {e.message}" for e in errors)
+
+    lines.append("")
+    return lines
+
+
+def _current_meta_path_names() -> tuple[str, ...]:
+    """Name the current ``sys.meta_path`` entries, tolerating a broken interpreter state at shutdown."""
+    try:
+        return tuple(type_name(f) for f in list(sys.meta_path))
+    except Exception:
+        return ("<unavailable>",)
+
+
+def _modules_since_install(monitor: "Monitor") -> list[str]:
+    """List names added to ``sys.modules`` after the monitor was installed."""
+    baseline = monitor.baseline_modules
+    try:
+        return [name for name in list(sys.modules) if name not in baseline]
+    except Exception:
+        return []
+
+
+def _names_line(names: tuple[str, ...]) -> str:
+    """Format finder names as a bracketed, comma-separated list."""
+    return "[" + ", ".join(names) + "]"
+
+
+def _mutation_lines(mutation: MetaPathMutation) -> list[str]:
+    """Format one mutation record: op, added/removed delta, resulting contents, and user-code stack."""
+    delta_parts: list[str] = []
+    if mutation.added:
+        delta_parts.append("+" + _names_line(mutation.added))
+    if mutation.removed:
+        delta_parts.append("-" + _names_line(mutation.removed))
+    delta = " ".join(delta_parts) if delta_parts else "(order change)"
+    lines = [f"#{mutation.seq} {mutation.op} {delta} [thread {mutation.thread_name}]"]
+    lines.append(f"    meta_path after: {_names_line(mutation.contents_after)}")
+    lines.extend(_stack_lines(mutation.stack))
+    return lines
+
+
+def _reassignment_lines(reassignment: MetaPathReassignment) -> list[str]:
+    """Format one reassignment record with before/after contents and the detection stack."""
+    lines = [
+        f"#{reassignment.seq} sys.meta_path REASSIGNED, detected during import of "
+        f"'{reassignment.during_import}' [thread {reassignment.thread_name}]"
+    ]
+    lines.append(f"    before: {_names_line(reassignment.old_contents)}")
+    lines.append(f"    after:  {_names_line(reassignment.new_contents)}")
+    lines.append("    instrumentation reinstalled; stack shows the triggering import, not the reassignment itself:")
+    lines.extend(_stack_lines(reassignment.stack))
+    return lines
+
+
+def _attribution_lines(calls: list[FindSpecCall]) -> list[str]:
+    """Summarize ``find_spec`` traffic per finder: probe counts and claimed modules, capped per finder."""
+    probes: dict[tuple[str, int], int] = {}
+    wins: dict[tuple[str, int], list[str]] = {}
+    for call in calls:
+        key = (call.finder_type_name, call.finder_id)
+        probes[key] = probes.get(key, 0) + 1
+        if call.found:
+            wins.setdefault(key, []).append(call.fullname)
+    if not probes:
+        return ["(no find_spec activity recorded on instrumented finders)"]
+    lines: list[str] = []
+    for (name, finder_id), count in sorted(probes.items()):
+        claimed = wins.get((name, finder_id), [])
+        lines.append(f"{name} (id 0x{finder_id:x}): {count} find_spec calls, {len(claimed)} claimed")
+        lines.extend(f"    {module}" for module in claimed[:_MAX_LISTED_MODULES])
+        if len(claimed) > _MAX_LISTED_MODULES:
+            lines.append(f"    ... and {len(claimed) - _MAX_LISTED_MODULES} more")
+    return lines
+
+
+def _suspicious_findings(monitor: "Monitor", calls: list[FindSpecCall]) -> list[str]:
+    """Cross-reference ``sys.modules`` against recorded claims and return finding lines.
+
+    Modules claimed by an instrumented finder get the bypass check; modules
+    with no recorded claim and no ``__spec__`` are flagged as manual loads.
+    Modules that predate the monitor are ignored.
+    """
+    winners: dict[str, FindSpecCall] = {}
+    for call in calls:
+        if call.found:
+            winners[call.fullname] = call
+    findings: list[str] = []
+    baseline = monitor.baseline_modules
+    for name, module in list(sys.modules.items()):
+        if name in baseline or name == "__main__":
+            continue
+        winner = winners.get(name)
+        if winner is not None:
+            findings.extend(_bypass_findings(name, winner))
+            continue
+        try:
+            spec = getattr(module, "__spec__", None)
+        except Exception:  # sys.modules values can be arbitrarily weird objects.
+            spec = None
+        if spec is None:
+            findings.append(
+                f"[no-spec] '{name}' is in sys.modules with no __spec__ and no recorded finder claim "
+                "(manually created or exec_module-style load; invisible to all import hooks)."
+            )
+    return findings
+
+
+def _bypass_findings(name: str, winner: FindSpecCall) -> list[str]:
+    """Check one claimed source module against a fresh ``PathFinder`` replay.
+
+    Args:
+        name: The claimed module's fullname.
+        winner: The recorded ``find_spec`` call that claimed it.
+
+    Returns:
+        At most one finding line: ``[bypass]`` when the standard machinery
+        would produce a different loader or origin, ``[unfindable]`` when it
+        finds nothing at all, empty when the claim looks compliant or has no
+        filesystem source origin.
+    """
+    origin = winner.origin
+    if origin is None or not origin.endswith(_SOURCE_SUFFIXES) or winner.loader_type_name is None:
+        return []
+    replay = _replay_path_finder(name)
+    if replay is None:
+        return [
+            f"[unfindable] '{name}' (origin {origin}) was claimed by {winner.finder_type_name}, but the "
+            "standard sys.path machinery cannot find it: sys.path_hooks-based tools never see this module."
+        ]
+    replay_loader = None if replay.loader is None else type_name(replay.loader)
+    replay_origin = replay.origin if isinstance(replay.origin, str) else None
+    if replay_loader != winner.loader_type_name or not _same_path(replay_origin, origin):
+        return [
+            f"[bypass] '{name}' was claimed by {winner.finder_type_name} "
+            f"(loader {winner.loader_type_name}, origin {origin}); the standard sys.path machinery would use "
+            f"loader {replay_loader} (origin {replay_origin}). sys.path_hooks-based tools were bypassed."
+        ]
+    return []
+
+
+def _replay_path_finder(name: str) -> "ModuleSpec | None":
+    """Ask the standard ``PathFinder`` what it would do for ``name``, without importing anything.
+
+    Returns:
+        The spec the standard path machinery would produce now, or None when
+        it finds nothing or the replay is impossible (e.g. the parent package
+        is gone or has no ``__path__``).
+    """
+    parent_name, _, _ = name.rpartition(".")
+    path = None
+    if parent_name:
+        parent = sys.modules.get(parent_name)
+        path = getattr(parent, "__path__", None)
+        if path is None:
+            return None
+    try:
+        return PathFinder.find_spec(name, path)
+    except Exception:  # A broken finder chain must not break the report.
+        return None
+
+
+def _same_path(a: str | None, b: str | None) -> bool:
+    """Compare two filesystem paths after absolutization and case normalization."""
+    if a is None or b is None:
+        return a == b
+    return os.path.normcase(os.path.abspath(a)) == os.path.normcase(os.path.abspath(b))
+
+
+def _stack_lines(stack: "StackSummary") -> list[str]:
+    """Format the interesting frames of a captured stack, innermost first, noise filtered out."""
+    frames = [f for f in stack if not _is_noise_frame(f.filename)]
+    shown = frames[:_STACK_DISPLAY_FRAMES]  # walk_stack order: innermost first.
+    if not shown:
+        return ["    (no frames outside the import machinery)"]
+    return [f"    at {f.filename}:{f.lineno} in {f.name}" for f in shown]
+
+
+def _is_noise_frame(filename: str) -> bool:
+    """Return True for frames from the import machinery or from metapathology itself."""
+    if filename.startswith("<frozen importlib"):
+        return True
+    return os.path.normcase(os.path.abspath(filename)).startswith(_PACKAGE_DIR)