wherewent 0.1.0__tar.gz

wherewent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Habiba Faisal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wherewent-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: wherewent
+Version: 0.1.0
+Summary: Zero-config SQL flight recorder that answers 'why did this Python batch job take so long?'
+Author-email: Habiba Faisal <habibafaisal8@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/habibafaisal/wherewent
+Project-URL: Repository, https://github.com/habibafaisal/wherewent
+Project-URL: Issues, https://github.com/habibafaisal/wherewent/issues
+Project-URL: Changelog, https://github.com/habibafaisal/wherewent/blob/main/CHANGELOG.md
+Keywords: profiling,performance,sqlalchemy,postgresql,sql,observability,batch,n+1,orm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: psutil
+Requires-Dist: psutil; extra == "psutil"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: sqlalchemy>=2.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# wherewent
+
+### Where did the time go? Find out in one command.
+
+**A zero-config recorder that answers "why did this Python batch job take so long?"**
+
+[![PyPI version](https://img.shields.io/pypi/v/wherewent.svg)](https://pypi.org/project/wherewent/)
+[![Python versions](https://img.shields.io/pypi/pyversions/wherewent.svg)](https://pypi.org/project/wherewent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/habibafaisal/wherewent/actions/workflows/ci.yml/badge.svg)](https://github.com/habibafaisal/wherewent/actions/workflows/ci.yml)
+
+```bash
+wherewent run python your_job.py
+```
+
+</div>
+
+---
+
+## The 0.4ms query that costs you 5 minutes
+
+A query can be individually fast — `0.4ms` — and still sink your job, because it's
+called **500,000 times from a single line of code**. Your app burns 300 seconds on
+round-trips while Postgres itself only worked for 80. Every profiler you've tried shows
+you *"time spent in psycopg"* and stops there.
+
+**wherewent shows you the calling pattern.** It groups queries by shape, counts how
+often each shape ran, sums the wall time, and points at the exact `file:line` in *your*
+code that fired it — then tells you, in plain English with the arithmetic shown, what to
+do about it.
+
+```
+====================================================================================================
+wherewent — SQL flight recorder
+----------------------------------------------------------------------------------------------------
+wall: 26.15s   cpu: 25.41s (97% CPU busy)   queries: 20,004   commits: 20,001   rollbacks: 1
+in-DB time: 5.46s (20.9% of wall; app-observed: includes network+driver+server)
+commit time: 9.06s   total rows: 20,000
+recording added ~1.81s (~6.9% of wall)
+====================================================================================================
+QUERY GROUP                                         CALLS     TOTAL     MEDIAN  CALL SITE
+----------------------------------------------------------------------------------------------------
+INSERT INTO events (name, value) VALUES (?, ?)     20,000     5.46s     0.24ms  demo/naive_job.py:65 in main
+SELECT count(*) AS count_1 FROM events                  1     0.00s     0.16ms  demo/naive_job.py:71 in main
+====================================================================================================
+FINDINGS
+----------------------------------------------------------------------------------------------------
+1. [R1+R2] commit-per-row loop
+   20,000 calls x 0.24ms median ~= 5.5s = 21% of 26.1s wall, at demo/naive_job.py:65. Batch it.
+   20,001 commits for 20,000 rows (1.0 rows/commit), 9.1s in commit = 35% of wall. Batch to 1,000+ rows/txn.
+   ~= 14.5s attributable
+====================================================================================================
+```
+
+## Why it's different
+
+| | Sampling profilers | APM / tracing | **wherewent** |
+|---|:---:|:---:|:---:|
+| Zero code changes | ✅ | ❌ | ✅ |
+| Groups queries by shape | ❌ | ⚠️ | ✅ |
+| Blames *your* call site | ⚠️ | ⚠️ | ✅ |
+| Tells you the fix | ❌ | ❌ | ✅ |
+| Runs anywhere, no server | ✅ | ❌ | ✅ |
+| Works on a Ctrl-C'd partial run | ❌ | ⚠️ | ✅ |
+
+## Install
+
+```bash
+pip install wherewent
+```
+
+That's it — the recorder is **pure standard library**. You only need SQLAlchemy
+because *your job* already uses it.
+
+## Use it
+
+Wrap any command. Your script runs **completely unmodified** — no imports, no decorators,
+no config:
+
+```bash
+wherewent run python your_job.py --some arg
+wherewent run python -m your_package
+wherewent run --save run.json python your_job.py   # also dump machine-readable JSON
+```
+
+- The report prints to **stderr** at exit; your job's own stdout/stderr pass through untouched.
+- **Ctrl-C still produces a report.** Sampling the first 5 minutes of a 14-hour job is the
+  main use case — partial data is the point.
+- **It can never crash or corrupt your job.** Every hook body is wrapped so the recorder
+  fails silent rather than taking your run down with it.
+- **It never records your data.** Only query *shapes* and *counts* are kept — literal
+  values and bind parameters are stripped before anything is stored.
+
+### Try the built-in demo
+
+```bash
+git clone https://github.com/habibafaisal/wherewent && cd wherewent
+pip install -e ".[dev]"
+wherewent run python demo/naive_job.py     # watch the R1+R2 finding fire
+python demo/benchmark.py                    # naive vs fixed, with the overhead gate
+```
+
+## How it works
+
+1. **Injects itself** into the target process via a `PYTHONPATH` sitecustomize shim — no
+   changes to your code, no wrapper imports.
+2. **Listens at the class level** — `event.listen(sqlalchemy.engine.Engine, ...)` — so
+   *every* engine your app creates is captured automatically, config-free.
+3. **Normalizes each statement** into a query *group*: literals, bind params, `IN`-lists
+   and multi-row `VALUES` collapse, so a million distinct inserts become one honest row.
+4. **Resolves the call site** by walking the stack past library frames to the first line
+   of *your* code — cheaply: cached by filename, full stacks only for the first 5 samples
+   per group, so the hot path stays cheap enough to hit its overhead budget.
+5. **Fires deterministic findings** from three rules, each showing its arithmetic.
+
+### The findings engine
+
+| Rule | Fires when | Tells you |
+|---|---|---|
+| **R1 — chatty group** | > 1,000 calls, > 10% of wall, median < 5ms | A fast query is called too many times — batch it (`executemany` / `IN`-list / `JOIN`). |
+| **R2 — commit-per-row** | > 100 commits, < 10 rows/commit, > 5% of wall in commit | You're committing per row — batch to 1,000+ rows per transaction. |
+| **R3 — DB-wait bound** | in-DB time > 60% of wall, CPU busy < 30% | The job is round-trip bound, not compute bound. |
+
+Findings that share a root cause **merge** (e.g. `R1+R2`), everything under 5% of wall is
+suppressed, and at most the top 3 are shown — ranked by seconds attributable.
+
+**Every number is honest.** Query times are labelled *app-observed* (they include network,
+driver, and server time — not just Postgres). Anything that can't be measured prints `—`,
+never a guess. wherewent even times *its own hooks* and reports the overhead it added.
+
+## Roadmap — help wanted 🙌
+
+wherewent is built to grow **beyond SQLAlchemy**. Seven of its eight modules —
+normalization, call-site resolution, the stats model, the rules engine, the report, the
+CLI, and the injection shim — are already **framework-agnostic**. They operate on a plain
+`RunSnapshot` of query events. Only `recorder.py`, which binds SQLAlchemy's event system,
+is framework-specific.
+
+**That means a new backend is a well-contained contribution:** capture query
+start/end/rowcount/txn events from another driver, feed the same `RunSnapshot`, and the
+entire findings-and-report pipeline works for free. Good first backends:
+
+- [ ] **Raw `psycopg` / `psycopg2`** — cursor subclass or connection factory hook
+- [ ] **`asyncpg` / async SQLAlchemy** — the async execution path
+- [ ] **Django ORM** — via `connection.execute_wrapper`
+- [ ] **Generic DB-API 2.0** — a monkeypatch-free `Cursor` proxy
+- [ ] New findings rules (N+1 `SELECT` detection, lock-wait, seq-scan heuristics)
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the backend contract and the **< 15% overhead
+gate** that every capture path must pass.
+
+## Limitations (today)
+
+- SQLAlchemy **2.x, synchronous** only (1.4 may work; async does not yet).
+- Single process — no multiprocessing or async fan-out.
+- Query times are app-observed (network + driver + server), by design.
+- Commit timing is obtained by wrapping the dialect's commit; if that wrap fails it prints `—`.
+
+These are the honest edges of a validation prototype, not permanent walls — see the roadmap.
+
+## Contributing
+
+Contributions are very welcome — new backends, new rules, docs, bug reports. Start with
+[`CONTRIBUTING.md`](CONTRIBUTING.md), open an issue to discuss anything substantial, and
+run `pytest && python demo/benchmark.py` before you push.
+
+## License
+
+[MIT](LICENSE) © 2026 Habiba Faisal

wherewent-0.1.0/README.md

@@ -0,0 +1,171 @@
+<div align="center">
+
+# wherewent
+
+### Where did the time go? Find out in one command.
+
+**A zero-config recorder that answers "why did this Python batch job take so long?"**
+
+[![PyPI version](https://img.shields.io/pypi/v/wherewent.svg)](https://pypi.org/project/wherewent/)
+[![Python versions](https://img.shields.io/pypi/pyversions/wherewent.svg)](https://pypi.org/project/wherewent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/habibafaisal/wherewent/actions/workflows/ci.yml/badge.svg)](https://github.com/habibafaisal/wherewent/actions/workflows/ci.yml)
+
+```bash
+wherewent run python your_job.py
+```
+
+</div>
+
+---
+
+## The 0.4ms query that costs you 5 minutes
+
+A query can be individually fast — `0.4ms` — and still sink your job, because it's
+called **500,000 times from a single line of code**. Your app burns 300 seconds on
+round-trips while Postgres itself only worked for 80. Every profiler you've tried shows
+you *"time spent in psycopg"* and stops there.
+
+**wherewent shows you the calling pattern.** It groups queries by shape, counts how
+often each shape ran, sums the wall time, and points at the exact `file:line` in *your*
+code that fired it — then tells you, in plain English with the arithmetic shown, what to
+do about it.
+
+```
+====================================================================================================
+wherewent — SQL flight recorder
+----------------------------------------------------------------------------------------------------
+wall: 26.15s   cpu: 25.41s (97% CPU busy)   queries: 20,004   commits: 20,001   rollbacks: 1
+in-DB time: 5.46s (20.9% of wall; app-observed: includes network+driver+server)
+commit time: 9.06s   total rows: 20,000
+recording added ~1.81s (~6.9% of wall)
+====================================================================================================
+QUERY GROUP                                         CALLS     TOTAL     MEDIAN  CALL SITE
+----------------------------------------------------------------------------------------------------
+INSERT INTO events (name, value) VALUES (?, ?)     20,000     5.46s     0.24ms  demo/naive_job.py:65 in main
+SELECT count(*) AS count_1 FROM events                  1     0.00s     0.16ms  demo/naive_job.py:71 in main
+====================================================================================================
+FINDINGS
+----------------------------------------------------------------------------------------------------
+1. [R1+R2] commit-per-row loop
+   20,000 calls x 0.24ms median ~= 5.5s = 21% of 26.1s wall, at demo/naive_job.py:65. Batch it.
+   20,001 commits for 20,000 rows (1.0 rows/commit), 9.1s in commit = 35% of wall. Batch to 1,000+ rows/txn.
+   ~= 14.5s attributable
+====================================================================================================
+```
+
+## Why it's different
+
+| | Sampling profilers | APM / tracing | **wherewent** |
+|---|:---:|:---:|:---:|
+| Zero code changes | ✅ | ❌ | ✅ |
+| Groups queries by shape | ❌ | ⚠️ | ✅ |
+| Blames *your* call site | ⚠️ | ⚠️ | ✅ |
+| Tells you the fix | ❌ | ❌ | ✅ |
+| Runs anywhere, no server | ✅ | ❌ | ✅ |
+| Works on a Ctrl-C'd partial run | ❌ | ⚠️ | ✅ |
+
+## Install
+
+```bash
+pip install wherewent
+```
+
+That's it — the recorder is **pure standard library**. You only need SQLAlchemy
+because *your job* already uses it.
+
+## Use it
+
+Wrap any command. Your script runs **completely unmodified** — no imports, no decorators,
+no config:
+
+```bash
+wherewent run python your_job.py --some arg
+wherewent run python -m your_package
+wherewent run --save run.json python your_job.py   # also dump machine-readable JSON
+```
+
+- The report prints to **stderr** at exit; your job's own stdout/stderr pass through untouched.
+- **Ctrl-C still produces a report.** Sampling the first 5 minutes of a 14-hour job is the
+  main use case — partial data is the point.
+- **It can never crash or corrupt your job.** Every hook body is wrapped so the recorder
+  fails silent rather than taking your run down with it.
+- **It never records your data.** Only query *shapes* and *counts* are kept — literal
+  values and bind parameters are stripped before anything is stored.
+
+### Try the built-in demo
+
+```bash
+git clone https://github.com/habibafaisal/wherewent && cd wherewent
+pip install -e ".[dev]"
+wherewent run python demo/naive_job.py     # watch the R1+R2 finding fire
+python demo/benchmark.py                    # naive vs fixed, with the overhead gate
+```
+
+## How it works
+
+1. **Injects itself** into the target process via a `PYTHONPATH` sitecustomize shim — no
+   changes to your code, no wrapper imports.
+2. **Listens at the class level** — `event.listen(sqlalchemy.engine.Engine, ...)` — so
+   *every* engine your app creates is captured automatically, config-free.
+3. **Normalizes each statement** into a query *group*: literals, bind params, `IN`-lists
+   and multi-row `VALUES` collapse, so a million distinct inserts become one honest row.
+4. **Resolves the call site** by walking the stack past library frames to the first line
+   of *your* code — cheaply: cached by filename, full stacks only for the first 5 samples
+   per group, so the hot path stays cheap enough to hit its overhead budget.
+5. **Fires deterministic findings** from three rules, each showing its arithmetic.
+
+### The findings engine
+
+| Rule | Fires when | Tells you |
+|---|---|---|
+| **R1 — chatty group** | > 1,000 calls, > 10% of wall, median < 5ms | A fast query is called too many times — batch it (`executemany` / `IN`-list / `JOIN`). |
+| **R2 — commit-per-row** | > 100 commits, < 10 rows/commit, > 5% of wall in commit | You're committing per row — batch to 1,000+ rows per transaction. |
+| **R3 — DB-wait bound** | in-DB time > 60% of wall, CPU busy < 30% | The job is round-trip bound, not compute bound. |
+
+Findings that share a root cause **merge** (e.g. `R1+R2`), everything under 5% of wall is
+suppressed, and at most the top 3 are shown — ranked by seconds attributable.
+
+**Every number is honest.** Query times are labelled *app-observed* (they include network,
+driver, and server time — not just Postgres). Anything that can't be measured prints `—`,
+never a guess. wherewent even times *its own hooks* and reports the overhead it added.
+
+## Roadmap — help wanted 🙌
+
+wherewent is built to grow **beyond SQLAlchemy**. Seven of its eight modules —
+normalization, call-site resolution, the stats model, the rules engine, the report, the
+CLI, and the injection shim — are already **framework-agnostic**. They operate on a plain
+`RunSnapshot` of query events. Only `recorder.py`, which binds SQLAlchemy's event system,
+is framework-specific.
+
+**That means a new backend is a well-contained contribution:** capture query
+start/end/rowcount/txn events from another driver, feed the same `RunSnapshot`, and the
+entire findings-and-report pipeline works for free. Good first backends:
+
+- [ ] **Raw `psycopg` / `psycopg2`** — cursor subclass or connection factory hook
+- [ ] **`asyncpg` / async SQLAlchemy** — the async execution path
+- [ ] **Django ORM** — via `connection.execute_wrapper`
+- [ ] **Generic DB-API 2.0** — a monkeypatch-free `Cursor` proxy
+- [ ] New findings rules (N+1 `SELECT` detection, lock-wait, seq-scan heuristics)
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the backend contract and the **< 15% overhead
+gate** that every capture path must pass.
+
+## Limitations (today)
+
+- SQLAlchemy **2.x, synchronous** only (1.4 may work; async does not yet).
+- Single process — no multiprocessing or async fan-out.
+- Query times are app-observed (network + driver + server), by design.
+- Commit timing is obtained by wrapping the dialect's commit; if that wrap fails it prints `—`.
+
+These are the honest edges of a validation prototype, not permanent walls — see the roadmap.
+
+## Contributing
+
+Contributions are very welcome — new backends, new rules, docs, bug reports. Start with
+[`CONTRIBUTING.md`](CONTRIBUTING.md), open an issue to discuss anything substantial, and
+run `pytest && python demo/benchmark.py` before you push.
+
+## License
+
+[MIT](LICENSE) © 2026 Habiba Faisal

wherewent-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wherewent"
+version = "0.1.0"
+description = "Zero-config SQL flight recorder that answers 'why did this Python batch job take so long?'"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Habiba Faisal", email = "habibafaisal8@gmail.com" }]
+keywords = [
+    "profiling",
+    "performance",
+    "sqlalchemy",
+    "postgresql",
+    "sql",
+    "observability",
+    "batch",
+    "n+1",
+    "orm",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: System :: Monitoring",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+]
+# The recorder itself is pure stdlib; SQLAlchemy is only needed by the job you record.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/habibafaisal/wherewent"
+Repository = "https://github.com/habibafaisal/wherewent"
+Issues = "https://github.com/habibafaisal/wherewent/issues"
+Changelog = "https://github.com/habibafaisal/wherewent/blob/main/CHANGELOG.md"
+
+[project.scripts]
+wherewent = "wherewent.cli:main"
+
+[project.optional-dependencies]
+# Optional CPU-accounting backend; the recorder falls back to os.times() without it.
+psutil = ["psutil"]
+# Everything needed to run the test suite and the demo benchmark.
+dev = ["pytest", "sqlalchemy>=2.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

wherewent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wherewent-0.1.0/src/wherewent/__init__.py

@@ -0,0 +1,3 @@
+"""wherewent — a zero-config SQL flight recorder for SQLAlchemy 2.x batch jobs."""
+
+__version__ = "0.1.0"

wherewent-0.1.0/src/wherewent/_shim/__init__.py

@@ -0,0 +1,2 @@
+"""Shim package. Its directory is placed on the child's PYTHONPATH so Python
+auto-imports the adjacent sitecustomize.py at interpreter startup."""

wherewent-0.1.0/src/wherewent/_shim/sitecustomize.py

@@ -0,0 +1,18 @@
+"""Auto-imported by Python at startup (this dir is on the child's PYTHONPATH).
+
+Only acts when the CLI marked the environment. Any failure is swallowed so the
+job runs exactly as it would without wherewent.
+
+TODO: chaining the site's original sitecustomize is out of scope for this
+prototype (if the environment already shipped one, it is shadowed here).
+"""
+
+import os
+
+if os.environ.get("WHEREWENT_ACTIVE") == "1":
+    try:
+        from wherewent.recorder import install_from_env
+
+        install_from_env()
+    except Exception:
+        pass

wherewent-0.1.0/src/wherewent/callsite.py

@@ -0,0 +1,99 @@
+"""Call-site resolution — find the user-code frame that issued a query.
+
+This runs on the hot path (once per execution), so is_library_file is memoized
+and the full stack capture is reserved for the first few samples of each group.
+"""
+
+import os
+import sys
+import sysconfig
+
+# memoization cache for is_library_file (keyed by raw filename string)
+_LIB_CACHE: "dict[str, bool]" = {}
+
+# directory of the installed wherewent package itself (its frames are "library")
+_WHEREWENT_DIR = os.path.dirname(os.path.abspath(__file__))
+
+# stdlib / install-tree prefixes computed once
+_STDLIB_PREFIXES = set()
+for _key in ("stdlib", "platstdlib", "purelib", "platlib"):
+    try:
+        _p = sysconfig.get_paths().get(_key)
+        if _p:
+            _STDLIB_PREFIXES.add(os.path.abspath(_p))
+    except Exception:
+        pass
+for _p in (getattr(sys, "prefix", None), getattr(sys, "base_prefix", None)):
+    if _p:
+        _STDLIB_PREFIXES.add(os.path.abspath(_p))
+_STDLIB_PREFIXES = tuple(_STDLIB_PREFIXES)
+
+
+def _compute_is_library(filename: str) -> bool:
+    # frozen / built-in / <string> / <stdin> pseudo-files are never user code
+    if not filename or filename.startswith("<"):
+        return True
+    path = os.path.abspath(filename)
+    sep = os.sep
+    if "site-packages" in path or "dist-packages" in path:
+        return True
+    if sep + "sqlalchemy" + sep in path:
+        return True
+    if path.startswith(_WHEREWENT_DIR):
+        return True
+    for prefix in _STDLIB_PREFIXES:
+        if path.startswith(prefix):
+            return True
+    return False
+
+
+def is_library_file(filename: str) -> bool:
+    """True if *filename* belongs to a library/stdlib/wherewent (memoized)."""
+    cached = _LIB_CACHE.get(filename)
+    if cached is not None:
+        return cached
+    result = _compute_is_library(filename)
+    _LIB_CACHE[filename] = result
+    return result
+
+
+def _short(filename: str) -> str:
+    """A compact display name: path relative to cwd, else basename."""
+    try:
+        rel = os.path.relpath(filename, os.getcwd())
+        if not rel.startswith(".."):
+            return rel
+    except Exception:
+        pass
+    return os.path.basename(filename)
+
+
+def resolve_call_site(skip: int = 1) -> "tuple[str, int, str] | None":
+    """Walk up the stack and return the first user-code frame.
+
+    Returns (short_file, lineno, function) or None if only library frames exist.
+    """
+    try:
+        frame = sys._getframe(skip)
+    except ValueError:
+        return None
+    while frame is not None:
+        filename = frame.f_code.co_filename
+        if not is_library_file(filename):
+            return (_short(filename), frame.f_lineno, frame.f_code.co_name)
+        frame = frame.f_back
+    return None
+
+
+def capture_stack(limit: int = 30) -> "list[str]":
+    """Return up to *limit* frames (user + library) as 'file:line in func'."""
+    frames = []
+    try:
+        frame = sys._getframe(1)
+    except ValueError:
+        return frames
+    while frame is not None and len(frames) < limit:
+        code = frame.f_code
+        frames.append(f"{_short(code.co_filename)}:{frame.f_lineno} in {code.co_name}")
+        frame = frame.f_back
+    return frames

wherewent-0.1.0/src/wherewent/cli.py

@@ -0,0 +1,90 @@
+"""Console entry point: `wherewent run [--save PATH] <command...>`.
+
+Launches the target command in a subprocess whose PYTHONPATH is arranged so
+Python auto-imports our sitecustomize shim, which installs the recorder before
+the job's own code runs. Zero changes to the job itself.
+"""
+
+import os
+import signal
+import subprocess
+import sys
+
+USAGE = (
+    "usage: wherewent run [--save PATH] <command...>\n"
+    "  e.g. wherewent run python job.py\n"
+    "       wherewent run --save out.json python -m mypkg\n"
+    "       wherewent run job.py            (bare script uses this interpreter)\n"
+)
+
+
+def _usage():
+    sys.stderr.write(USAGE)
+
+
+def _child_env(save):
+    import wherewent
+    import wherewent._shim as shim
+
+    # Directory that literally contains sitecustomize.py (so Python auto-imports it).
+    shim_dir = os.path.dirname(os.path.abspath(shim.__file__))
+    # Directory that contains the `wherewent` package, so the child can import it.
+    pkg_parent = os.path.dirname(os.path.dirname(os.path.abspath(wherewent.__file__)))
+
+    env = os.environ.copy()
+    existing = env.get("PYTHONPATH", "")
+    parts = [shim_dir, pkg_parent]
+    if existing:
+        parts.append(existing)
+    env["PYTHONPATH"] = os.pathsep.join(parts)
+    env["WHEREWENT_ACTIVE"] = "1"
+    env["WHEREWENT_SAVE"] = save or ""
+    return env
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] != "run":
+        _usage()
+        return 2
+
+    args = argv[1:]
+    save = None
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--save":
+            if i + 1 >= len(args):
+                _usage()
+                return 2
+            save = args[i + 1]
+            i += 2
+            continue
+        break  # first non-option token starts the command
+    command = args[i:]
+
+    if not command:
+        _usage()
+        return 2
+
+    # A bare `script.py` runs under this interpreter.
+    if command[0].endswith(".py"):
+        command = [sys.executable] + command
+
+    env = _child_env(save)
+
+    # While the child runs, the parent ignores Ctrl-C so the SIGINT goes to the
+    # child (which finalizes and prints the report); we exit with its code.
+    prev = signal.signal(signal.SIGINT, signal.SIG_IGN)
+    try:
+        proc = subprocess.run(command, env=env)
+    except FileNotFoundError:
+        sys.stderr.write(f"wherewent: command not found: {command[0]}\n")
+        return 127
+    finally:
+        signal.signal(signal.SIGINT, prev)
+    return proc.returncode
+
+
+if __name__ == "__main__":
+    sys.exit(main())