pytest-tia 1.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,230 @@
1
+ Metadata-Version: 2.4
2
+ Name: pytest-tia
3
+ Version: 1.1.0
4
+ Summary: Test Impact Analysis for pytest — run only the tests your changes affect
5
+ Requires-Python: >=3.10
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: pytest>=7
8
+ Requires-Dist: coverage>=7
9
+ Provides-Extra: s3
10
+ Requires-Dist: boto3>=1.26; extra == "s3"
11
+ Provides-Extra: gcs
12
+ Requires-Dist: google-cloud-storage>=2.0; extra == "gcs"
13
+
14
+ # tia — Test Impact Analysis for pytest
15
+
16
+ Run only the tests your changes actually affect. Big suites spend most
17
+ of their CI time re-running tests that couldn't possibly have broken;
18
+ `tia` builds a per-test coverage map once, then uses your `git diff` to
19
+ select the minimal set of tests to run.
20
+
21
+ This is the same idea Google/Meta run internally (Test Impact Analysis).
22
+
23
+ ## Honest disclosure (read this first)
24
+
25
+ Test selection has exactly one cardinal sin: skipping a test that would
26
+ have failed. A tool you can't trust on that is worse than no tool. So
27
+ before any feature list, here is where this project earned — or failed to
28
+ earn — that trust.
29
+
30
+ While benchmarking on Flask, an early run reported a **median skip rate of
31
+ 73%**. It looked great. It was a lie. coverage.py's default measurement
32
+ core on Python 3.12+ (`sysmon`) records only the *first* test to hit each
33
+ line and silently drops the rest, so any test that reused a shared helper
34
+ was never mapped — and changing that helper would have skipped them. The
35
+ high number was false negatives wearing a costume. We forced the C tracer
36
+ (`COVERAGE_CORE=ctrace`), every test mapped, and the number fell to the
37
+ truth: **median ~21% skip on Flask** (≈40% mean; cosmetic commits 99%+).
38
+ The toy demo could never have shown this — only a real codebase did.
39
+
40
+ So the Flask number is deliberately the *lower bound*: Flask is small and
41
+ tightly coupled, near the worst case for test selection. We'd rather
42
+ publish the honest floor than a cherry-picked ceiling. But a floor alone
43
+ is misleading too, so we measured the other end: on
44
+ [boltons](benchmark/RESULTS-boltons.md), a modular utility library, the
45
+ honest median skip on real logic changes is **~96%**. Same tool, same
46
+ rules — the variable is how decoupled your tests are. The truth is a
47
+ **range, ~21% (worst case) ↔ ~96% (modular)**, and both ends are measured
48
+ on real third-party suites, not toys. Per-commit tables and the "I
49
+ distrusted this number first" audits:
50
+ [Flask](benchmark/RESULTS.md) · [boltons](benchmark/RESULTS-boltons.md).
51
+
52
+ ## How it works
53
+
54
+ 1. **`tia record`** runs the full suite once with a pytest plugin that
55
+ switches coverage.py's *dynamic context* to each test's nodeid, then
56
+ maps every executed line to its enclosing function via the AST. The
57
+ result is a method-level map `{test -> {file -> {qualnames}}}` saved
58
+ to `.tia/map.json`, stamped with the git ref it was recorded at.
59
+ Because coverage is dynamic, the whole call chain a test exercises
60
+ (controller → service → repo → utils) is captured for free.
61
+ 2. **`tia run`** diffs your tree against that ref, reading the **old
62
+ side** of each hunk (same coordinate system as the map), then parses
63
+ each file *as it existed at that ref* (`git show`) to resolve changed
64
+ lines to changed functions.
65
+ 3. It selects tests by three rules (see `tia/select.py`) and runs only
66
+ those via pytest.
67
+
68
+ ## Selection rules
69
+
70
+ 1. **Function hit** — a test executed a function whose body changed.
71
+ Immune to line shifts elsewhere in the file (the whole point of
72
+ going method-level).
73
+ 2. **Module-level fallback** — a file had a module-level *modification*
74
+ (constant, import, class body). Runs every test touching that file.
75
+ Module-level *insertions* (a new function/test) are ignored so they
76
+ don't drag the whole file in.
77
+ 3. **Data dependency** — a non-`.py` file changed (config, fixture,
78
+ template). Runs every test that *opened* that file while recording.
79
+ These reads are captured with a `sys.addaudithook` on the `open`
80
+ event, so dependencies coverage can't see don't become silent
81
+ false negatives.
82
+ 4. **New test** — any collected test not in the map has never been
83
+ measured, so it always runs.
84
+
85
+ A **dynamic-safety modifier** sits on top of rules 1–2: a file flagged
86
+ at record time as using reflection (`getattr` by computed name, `eval`,
87
+ `importlib`, `__getattr__`) is widened from method-level to file-level
88
+ when it changes — coverage can't be trusted to have captured every edge
89
+ in/out of it. `--trust-dynamic` opts out. This is mitigation, not a
90
+ solution; nothing resolves dynamic dispatch precisely (it's undecidable
91
+ in general), so still run the full suite on a cadence.
92
+
93
+ A **cosmetic-change filter** sits *underneath* everything: before
94
+ selecting, a changed `.py` file whose edit is only comments, whitespace,
95
+ or docstrings is dropped entirely. The test is the AST — comments and
96
+ formatting aren't in it, docstrings are stripped before comparing — and
97
+ it compares the **old and new** trees, so uncommenting a line still
98
+ counts as real. So a "fix typo" / "add docstring" / "run black" commit on
99
+ a core file selects *nothing* instead of half the suite. `--all-changes`
100
+ opts out. Safe by construction: it only removes false positives.
101
+
102
+ The same filter also drops **type-only** edits — but only the kind that
103
+ is *provably* dead at runtime, because the common belief that "type hints
104
+ don't run" is false: `dataclasses`, `pydantic` and `attrs` all read
105
+ `__annotations__`. So it strips exactly two things: the body of an
106
+ `if TYPE_CHECKING:` block (never executed at runtime — where most hint
107
+ churn lives) and **function-local** annotations (PEP 526: never evaluated
108
+ nor stored). It deliberately *keeps* a change to a function signature or a
109
+ class/module-level annotation as real, because a dataclass field's type
110
+ genuinely changes behavior. Stripping those would be a false negative —
111
+ the one sin this tool won't commit. So "added the type hints" stops
112
+ triggering tests, without ever hiding a `dataclass` field-type change.
113
+
114
+ ## Usage
115
+
116
+ ```sh
117
+ pip install -e .
118
+
119
+ tia record [PATH] # build the map (run from the repo root)
120
+ tia run [PATH] # run only affected tests
121
+ tia run --since main # diff against another ref
122
+ tia run --list # show the selection, don't run
123
+ tia run --report - # also print a Markdown summary (see CI mode)
124
+ tia status # summarize the recorded map
125
+
126
+ tia serve --dir ./maps # run the bundled map store (zero deps)
127
+ tia push --to <dir|url> # publish the local map (for CI)
128
+ tia pull --from <dir|url> # fetch a published map
129
+ ```
130
+
131
+ Remotes for `push`/`pull`/`--remote` can be a directory, an `http(s)://`
132
+ URL (the bundled store), or native object storage: `s3://bucket/prefix`
133
+ (`pip install pytest-tia[s3]`) or `gs://bucket/prefix`
134
+ (`pytest-tia[gcs]`). The cloud SDKs are imported lazily, so the core
135
+ install stays dependency-light unless you actually use those URLs.
136
+
137
+ Run from the repository root (where `pyproject.toml` / `.git` live) so
138
+ nodeids and file paths stay consistent.
139
+
140
+ ### CI mode
141
+
142
+ The map a base-branch job builds has to reach the PR job that consumes
143
+ it. Publish it to a shared remote keyed by the git ref it was recorded
144
+ at. The remote can be a **directory** (a cache volume / artifact dir), an
145
+ **`http(s)://` URL** served by the bundled store, or a native
146
+ **`s3://` / `gs://`** bucket:
147
+
148
+ ```sh
149
+ # one zero-dependency map store for the team / CI (stdlib only)
150
+ python -m tia.server --dir ./tia-maps --port 8000 # or: tia serve ...
151
+
152
+ # base branch job
153
+ tia record && tia push --to s3://my-company-ci/tia-maps
154
+
155
+ # PR job — no local map needed; pulls by base ref, falls back to latest
156
+ tia run --remote s3://my-company-ci/tia-maps --since "$(git merge-base origin/main HEAD)"
157
+ ```
158
+
159
+ In a GitHub Actions PR job, `tia run` auto-detects `$GITHUB_STEP_SUMMARY`
160
+ and posts a Markdown table to the check page — which files changed, the
161
+ impact of each, and exactly which tests were selected and why. No flag
162
+ needed; it's the same explanation as the terminal output, rendered for
163
+ the PR. (`--report <path>`, or `--report -` for stdout, forces it
164
+ anywhere.)
165
+
166
+ A ready-to-copy GitHub Actions workflow is in
167
+ [`examples/ci/github-actions.yml`](examples/ci/github-actions.yml).
168
+
169
+ `run` resolves the diff against line→function tables **baked into the
170
+ map** at record time, so it never needs `git show` on the base blob —
171
+ which is what makes it safe under shallow clones (`clone --depth=1`),
172
+ where that blob may not be fetched. The diff itself still needs the base
173
+ *commit*; in a shallow checkout, fetch just that ref first
174
+ (`git fetch --depth=1 origin <base-sha>`).
175
+
176
+ ## Known limitations (honest list)
177
+
178
+ - **Insertion anchoring.** Appending a function/test right after an
179
+ existing one anchors on that one's last line, pulling it in as one
180
+ extra test. A bounded false positive, never a false negative.
181
+ - **Coordinate sync.** The map is stamped with the ref it was recorded
182
+ at and `run` diffs against it automatically. Re-run `tia record`
183
+ after you commit so the map stays fresh.
184
+ - **Subprocess / other-thread execution isn't traced.** We attribute a
185
+ test's setup, call, and teardown (so fixture work and fixture file
186
+ reads count), but code that runs in a child process or a non-measured
187
+ thread is invisible to coverage and can hide a dependency.
188
+ - **Needs coverage's C tracer.** On Python 3.12+ coverage defaults to the
189
+ `sysmon` core, which records only the *first* test to hit each line and
190
+ silently drops the rest — a false negative for any shared helper. tia
191
+ forces `COVERAGE_CORE=ctrace` during recording to get correct per-test
192
+ contexts; don't override it back to `sysmon`.
193
+ - **Dynamic dispatch / reflection / subprocesses** aren't traced by
194
+ coverage and can hide a real dependency. tia *detects* reflection and
195
+ degrades to file-level there (see the dynamic-safety modifier), but a
196
+ `getattr` target in one file pointing at a function in another is still
197
+ beyond it. Re-record periodically and run the full suite on a cadence.
198
+
199
+ ## Roadmap
200
+
201
+ - [x] **Method-level analysis** (AST) — done.
202
+ - [x] **Silent dependencies** — track non-`.py` files each test reads.
203
+ - [x] **CI mode** — remote map storage + shallow-clone-safe diffing.
204
+ - [x] **Static fallback** for dynamic dispatch / DI frameworks —
205
+ detect-and-degrade (mitigation, not a precise solution).
206
+ - [x] **Industrialize** — zero-dep HTTP map store (`tia serve`) + GitHub
207
+ Actions template, so adopting it is a few lines, not a project.
208
+ - [x] **Real-repo benchmark, both ends of the range** — Flask (worst
209
+ case, ~21%, [`RESULTS.md`](benchmark/RESULTS.md)) and boltons (modular,
210
+ ~96% on logic changes, [`RESULTS-boltons.md`](benchmark/RESULTS-boltons.md)).
211
+ The Flask run also caught a recorder false-negative bug (the `sysmon`
212
+ core dropping contexts).
213
+ - [x] **Cosmetic-change filter** — ignore comment/docstring/format-only
214
+ edits so they select nothing instead of a whole file.
215
+ - [x] **Type-only filter (v1.1)** — also ignore `if TYPE_CHECKING:` and
216
+ function-local annotation edits; keep signature/dataclass-field type
217
+ changes (provably-safe subset only — no false negatives).
218
+ - [x] **Native S3 / GCS remotes (v1.1)** — `s3://` / `gs://` map stores
219
+ via lazily-imported SDKs; core install stays dependency-light.
220
+ - [x] **CI step summary (v1.1)** — auto-post a Markdown impact table to
221
+ the PR via `$GITHUB_STEP_SUMMARY`.
222
+ - [ ] **Not planned: precise cross-file dynamic dispatch.** Resolving a
223
+ `getattr`/`eval` target across files is undecidable in general; the
224
+ detect-and-degrade modifier plus periodic full runs is the honest
225
+ answer, not a static call graph that drowns in edge cases.
226
+
227
+ ## Demo
228
+
229
+ `examples/calc/` is a tiny suite that proves the behavior end to end.
230
+ See the scenarios in the project history.
@@ -0,0 +1,19 @@
1
+ tia/__init__.py,sha256=t8f3Xa1iCil4t29mSj8-OzcWqGeKFX_IahgBk8aE8D0,178
2
+ tia/__main__.py,sha256=ll6TWrQpapUaiNVZqqjoKCNyjrLLKi0XqDNuxsjsY7Q,82
3
+ tia/astmap.py,sha256=Ml-PB71XYjmN1xtMHt_PbVZY7hCrljHmpJHXiIUZiE0,1439
4
+ tia/cli.py,sha256=YWUG0ylXWIdIV2UwqlWv30QwkKLs3l1378EyxEMVd-8,12739
5
+ tia/diff.py,sha256=V2qdC3ZeU1QNt5w6yUNIR-ftnriR4ke_SP-djXsvMxU,2092
6
+ tia/dynscan.py,sha256=I1LNrRBdfCqeiUFOZ9-GYy_B4D6tPxqe2v0Agg0plJ0,2371
7
+ tia/plugin.py,sha256=75lgSiOCRHg8a99-m4BWCSJ-CbKnFyXW6owEumxa-gI,5400
8
+ tia/remotestore.py,sha256=WAJ6YpGdA2-B4SBeKOILoSRLid8i1_pTiE_Q_EqdVao,7230
9
+ tia/report.py,sha256=TEPmrdT9jlAyvPCkMaLVu_nNJURkmvp4n8S9-XQbaII,3515
10
+ tia/resolve.py,sha256=IZlAWjK-H2BW6Na5g-2NugzDOM7ZYsUOhYZL1eqFkuI,2776
11
+ tia/select.py,sha256=gCfT7uDLrAPiCOJBameF6i7cY6MvfYA7R-rGRMGNCSA,2883
12
+ tia/semantic.py,sha256=KjHuDxAeRQ8RhWGz0-epaRV8mHeqKU_9cDzi94Yk2nA,5263
13
+ tia/server.py,sha256=EYVNxOCeAONtFGCx8d3D-IFEyVRYa4CzXhcKyx534vk,3198
14
+ tia/store.py,sha256=NqlNksYfvB7IsUoESUvraJbWCTAbf6BYVVygYLGBH9Q,2757
15
+ pytest_tia-1.1.0.dist-info/METADATA,sha256=wO7JduQ9eVnKZYshw2zv96_B5eAFcobME-hVhLGx6vk,11975
16
+ pytest_tia-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
17
+ pytest_tia-1.1.0.dist-info/entry_points.txt,sha256=iQCGrV5QBIGaAbSgPbxebYi2RFeMZIhR7AtxSQlKhiE,37
18
+ pytest_tia-1.1.0.dist-info/top_level.txt,sha256=6h0jGXLltqEq74_E2pMy2ii8LF_AcpE_g95jEDy0bZM,4
19
+ pytest_tia-1.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ tia = tia.cli:main
@@ -0,0 +1 @@
1
+ tia
tia/__init__.py ADDED
@@ -0,0 +1,7 @@
1
+ """tia — Test Impact Analysis for pytest.
2
+
3
+ Run only the tests affected by your code changes, using a dynamic
4
+ line-level coverage map built per test.
5
+ """
6
+
7
+ __version__ = "1.1.0"
tia/__main__.py ADDED
@@ -0,0 +1,4 @@
1
+ from tia.cli import main
2
+
3
+ if __name__ == "__main__":
4
+ raise SystemExit(main())
tia/astmap.py ADDED
@@ -0,0 +1,39 @@
1
+ """Map source lines to the qualified name of their enclosing function.
2
+
3
+ `line_to_qualname("...source...")` returns ``{lineno: "Class.method"}``.
4
+ Lines that belong to no function (module-level statements, imports,
5
+ class-body lines between methods) are simply absent from the dict — the
6
+ caller treats those as "module-level".
7
+
8
+ Decorator lines count as part of the function they decorate: changing a
9
+ decorator changes the function's behaviour.
10
+ """
11
+
12
+ import ast
13
+
14
+
15
+ def line_to_qualname(source: str) -> dict[int, str]:
16
+ tree = ast.parse(source)
17
+ mapping: dict[int, str] = {}
18
+
19
+ def visit(node: ast.AST, stack: list[str]) -> None:
20
+ for child in ast.iter_child_nodes(node):
21
+ if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
22
+ qual = ".".join(stack + [child.name])
23
+ start = min(
24
+ [child.lineno] + [d.lineno for d in child.decorator_list]
25
+ )
26
+ end = child.end_lineno or child.lineno
27
+ for ln in range(start, end + 1):
28
+ mapping[ln] = qual # outer assigned first...
29
+ visit(child, stack + [child.name]) # ...inner overwrites
30
+ else:
31
+ visit(child, stack)
32
+
33
+ visit(tree, [])
34
+ return mapping
35
+
36
+
37
+ def line_to_qualname_from_file(path: str) -> dict[int, str]:
38
+ with open(path, encoding="utf-8") as fh:
39
+ return line_to_qualname(fh.read())
tia/cli.py ADDED
@@ -0,0 +1,308 @@
1
+ """tia command line: record | run | status."""
2
+
3
+ import argparse
4
+ import os
5
+ import subprocess
6
+ import sys
7
+
8
+ import pytest
9
+
10
+ from tia import (astmap, diff, dynscan, remotestore, report, resolve, select,
11
+ semantic, server, store)
12
+ from tia.plugin import RecordPlugin
13
+
14
+
15
+ def _collect_nodeids(path: str | None) -> set[str]:
16
+ """Ask pytest which tests currently exist (no execution)."""
17
+ cmd = [sys.executable, "-m", "pytest", "--collect-only", "-q",
18
+ "-p", "no:cacheprovider"]
19
+ if path:
20
+ cmd.append(path)
21
+ out = subprocess.run(cmd, capture_output=True, text=True,
22
+ encoding="utf-8", errors="replace")
23
+ return {ln.strip() for ln in out.stdout.splitlines() if "::" in ln}
24
+
25
+
26
+ def _head_sha(cwd: str) -> str | None:
27
+ out = subprocess.run(["git", "rev-parse", "HEAD"], cwd=cwd,
28
+ capture_output=True, text=True,
29
+ encoding="utf-8", errors="replace")
30
+ return out.stdout.strip() if out.returncode == 0 else None
31
+
32
+
33
+ def _lines_to_quals(root: str, line_map: dict[str, dict[str, set[int]]]):
34
+ """Convert {test -> {file -> lines}} into {test -> {file -> qualnames}}.
35
+
36
+ Returns the converted map plus the per-file line->qualname tables we
37
+ built along the way, so they can be baked into the stored map. With
38
+ those tables, `run` resolves a diff without ever calling ``git show``
39
+ — which is what makes it safe under CI shallow clones.
40
+ """
41
+ cache: dict[str, dict[int, str]] = {}
42
+ result: dict[str, dict[str, set[str]]] = {}
43
+ for nodeid, files in line_map.items():
44
+ quals: dict[str, set[str]] = {}
45
+ for rel, lines in files.items():
46
+ l2q = cache.get(rel)
47
+ if l2q is None:
48
+ try:
49
+ l2q = astmap.line_to_qualname_from_file(os.path.join(root, rel))
50
+ except (SyntaxError, OSError):
51
+ l2q = {}
52
+ cache[rel] = l2q
53
+ quals[rel] = {l2q[ln] for ln in lines if ln in l2q}
54
+ result[nodeid] = quals
55
+ return result, cache
56
+
57
+
58
+ def _cosmetic_files(changed: dict, ref: str, root: str) -> set[str]:
59
+ """.py files in the diff whose change is non-semantic.
60
+
61
+ Comments/whitespace/docstrings, plus the provably-dead type-only edits
62
+ (``if TYPE_CHECKING:`` bodies, function-local annotations). See
63
+ ``semantic.is_semantic_change``.
64
+ """
65
+ out: set[str] = set()
66
+ for path in changed:
67
+ if not path.endswith(".py"):
68
+ continue
69
+ old = resolve._git_show(ref, path, root)
70
+ if old is None:
71
+ continue # new/unavailable at ref — let normal selection handle it
72
+ try:
73
+ with open(os.path.join(root, path), encoding="utf-8") as fh:
74
+ new = fh.read()
75
+ except OSError:
76
+ continue # deleted in the worktree — a real change
77
+ if not semantic.is_semantic_change(old, new):
78
+ out.add(path)
79
+ return out
80
+
81
+
82
+ def cmd_record(args) -> int:
83
+ root = os.getcwd()
84
+ source = args.source or root
85
+ data_file = os.path.join(store.tia_dir(root), "coverage")
86
+ os.makedirs(store.tia_dir(root), exist_ok=True)
87
+
88
+ plugin = RecordPlugin(root, data_file, source)
89
+ pytest_args = ["-q", "-p", "no:cacheprovider"]
90
+ if args.path:
91
+ pytest_args.insert(0, args.path)
92
+ code = pytest.main(pytest_args, plugins=[plugin])
93
+
94
+ quals, funcmaps = _lines_to_quals(root, plugin.result)
95
+ dynamic = _scan_dynamic(root, funcmaps)
96
+ path = store.save_map(root, quals, ref=_head_sha(root),
97
+ reads=plugin.reads, funcmaps=funcmaps, dynamic=dynamic)
98
+ n_reads = sum(len(v) for v in plugin.reads.values())
99
+ print(f"\n[tia] recorded {len(quals)} tests "
100
+ f"({n_reads} non-py read deps, {len(dynamic)} dynamic files) -> {path}")
101
+ return int(code) if code not in (0, 5) else 0
102
+
103
+
104
+ def _scan_dynamic(root: str, funcmaps: dict[str, dict[int, str]]) -> dict[str, list[str]]:
105
+ """Flag measured files that use reflection coverage can't trace fully."""
106
+ out: dict[str, list[str]] = {}
107
+ for rel in funcmaps:
108
+ try:
109
+ with open(os.path.join(root, rel), encoding="utf-8") as fh:
110
+ markers = dynscan.find_markers(fh.read())
111
+ except OSError:
112
+ continue
113
+ if markers:
114
+ out[rel] = markers
115
+ return out
116
+
117
+
118
+ def cmd_run(args) -> int:
119
+ root = os.getcwd()
120
+ # In CI the map is built elsewhere; pull it by base ref if we have none.
121
+ if getattr(args, "remote", None) and not os.path.exists(store.map_path(root)):
122
+ os.makedirs(store.tia_dir(root), exist_ok=True)
123
+ want = args.since or _head_sha(root)
124
+ got = remotestore.pull(args.remote, want, store.map_path(root))
125
+ print(f"[tia] pulled map from {got}" if got
126
+ else f"[tia] no map in remote {args.remote}", file=sys.stderr)
127
+ if not os.path.exists(store.map_path(root)):
128
+ print("[tia] no map found. Run `tia record` first.", file=sys.stderr)
129
+ return 2
130
+
131
+ tia_map = store.load_map(root)
132
+ # Default to the ref the map was recorded at, so line numbers line up.
133
+ ref = args.since or tia_map.get("ref") or "HEAD"
134
+
135
+ changed = diff.changed_lines(ref, cwd=root)
136
+ # 乙/戊: drop .py files whose change is non-semantic (comments, format,
137
+ # docstrings, or provably-dead type-only edits), unless the user opts
138
+ # out. Best-effort — needs the old blob (skipped if unavailable, e.g. a
139
+ # shallow clone without the base fetched).
140
+ cosmetic: set[str] = set()
141
+ if not args.all_changes:
142
+ cosmetic = _cosmetic_files(changed, ref, root)
143
+ for path in cosmetic:
144
+ del changed[path]
145
+
146
+ func_changes, module_files = resolve.changed_functions(
147
+ changed, ref, root, tia_map.get("funcmaps"))
148
+ data_changes = {p for p in changed if not p.endswith(".py")}
149
+ reads = tia_map.get("reads", {})
150
+
151
+ # ④ Degrade to file-level where coverage edges can't be trusted, unless
152
+ # the user explicitly opts out with --trust-dynamic.
153
+ escalated: dict[str, list[str]] = {}
154
+ if not args.trust_dynamic:
155
+ module_files, escalated = select.escalate_dynamic(
156
+ func_changes, module_files, tia_map.get("dynamic", {}))
157
+
158
+ all_nodeids = _collect_nodeids(args.path)
159
+ selected = select.select_tests(
160
+ tia_map["tests"], func_changes, module_files, all_nodeids,
161
+ data_changes, reads,
162
+ )
163
+
164
+ total = len(all_nodeids)
165
+ n = len(selected)
166
+ print(f"[tia] ref {ref[:8] if ref else '?'} | changed files: {len(changed)} | "
167
+ f"tests in suite: {total} | selected: {n}")
168
+ for path in sorted(changed):
169
+ tag = report.impact_tag(path, func_changes, module_files, escalated,
170
+ data_changes, reads)
171
+ print(f" ~ {path}: {tag}")
172
+ for path in sorted(cosmetic):
173
+ print(f" ~ {path}: comments/docstring/format/type-only - ignored")
174
+ for nodeid, reason in sorted(selected.items()):
175
+ print(f" -> {nodeid} ({reason})")
176
+
177
+ for path, markers in sorted(escalated.items()):
178
+ print(f"[tia] WARNING: {path} uses reflection ({', '.join(markers)}); "
179
+ f"widened to file-level - coverage can't trace these edges. "
180
+ f"Run the full suite periodically as a safety net.",
181
+ file=sys.stderr)
182
+
183
+ # Explainability in CI: drop a Markdown summary onto the PR check page.
184
+ # Auto-on when GitHub hands us $GITHUB_STEP_SUMMARY; --report forces it.
185
+ dest = args.report or os.environ.get("GITHUB_STEP_SUMMARY")
186
+ if dest:
187
+ md = report.render_markdown(
188
+ ref, list(changed), func_changes, module_files, escalated,
189
+ data_changes, reads, cosmetic, selected, total)
190
+ if dest == "-":
191
+ # The report is UTF-8 (it has emoji). Write raw bytes through the
192
+ # buffer so a legacy-codepage console (e.g. Windows cp950) can't
193
+ # raise UnicodeEncodeError mid-run; fall back if there's no buffer
194
+ # (e.g. stdout was replaced under capture).
195
+ buf = getattr(sys.stdout, "buffer", None)
196
+ if buf is not None:
197
+ sys.stdout.flush()
198
+ buf.write(md.encode("utf-8"))
199
+ buf.flush()
200
+ else:
201
+ sys.stdout.write(md)
202
+ else:
203
+ try:
204
+ with open(dest, "a", encoding="utf-8") as fh:
205
+ fh.write(md)
206
+ except OSError as e:
207
+ print(f"[tia] could not write report to {dest}: {e}", file=sys.stderr)
208
+
209
+ if not selected:
210
+ saved = "100%" if total else "n/a"
211
+ print(f"[tia] no affected tests - skipping {total} tests ({saved} saved).")
212
+ return 0
213
+ if total:
214
+ print(f"[tia] running {n}/{total} tests "
215
+ f"({100 * (total - n) // total}% skipped).")
216
+
217
+ if args.list:
218
+ return 0
219
+
220
+ cmd = [sys.executable, "-m", "pytest", *sorted(selected),
221
+ "-p", "no:cacheprovider"]
222
+ return subprocess.run(cmd).returncode
223
+
224
+
225
+ def cmd_push(args) -> int:
226
+ root = os.getcwd()
227
+ if not os.path.exists(store.map_path(root)):
228
+ print("[tia] no local map to push. Run `tia record` first.", file=sys.stderr)
229
+ return 2
230
+ ref = store.load_map(root).get("ref")
231
+ dst = remotestore.push(store.map_path(root), args.to, ref)
232
+ print(f"[tia] pushed map (ref {ref[:8] if ref else '?'}) -> {dst}")
233
+ return 0
234
+
235
+
236
+ def cmd_pull(args) -> int:
237
+ root = os.getcwd()
238
+ os.makedirs(store.tia_dir(root), exist_ok=True)
239
+ want = args.ref or _head_sha(root)
240
+ got = remotestore.pull(args.from_, want, store.map_path(root))
241
+ if not got:
242
+ print(f"[tia] no map found in remote {args.from_}", file=sys.stderr)
243
+ return 2
244
+ print(f"[tia] pulled map from {got} -> {store.map_path(root)}")
245
+ return 0
246
+
247
+
248
+ def cmd_serve(args) -> int:
249
+ server.serve(args.dir, args.host, args.port)
250
+ return 0
251
+
252
+
253
+ def cmd_status(args) -> int:
254
+ root = os.getcwd()
255
+ if not os.path.exists(store.map_path(root)):
256
+ print("[tia] no map recorded yet.")
257
+ return 0
258
+ m = store.load_map(root)
259
+ files = {f for t in m["tests"].values() for f in t}
260
+ print(f"[tia] map: {len(m['tests'])} tests covering {len(files)} files "
261
+ f"(recorded {m['created']}).")
262
+ return 0
263
+
264
+
265
+ def main(argv=None) -> int:
266
+ p = argparse.ArgumentParser(prog="tia", description="Test Impact Analysis for pytest")
267
+ sub = p.add_subparsers(dest="cmd", required=True)
268
+
269
+ rec = sub.add_parser("record", help="run the full suite and build the impact map")
270
+ rec.add_argument("path", nargs="?", help="test path (default: auto-discover)")
271
+ rec.add_argument("--source", help="source root to measure (default: cwd)")
272
+ rec.set_defaults(func=cmd_record)
273
+
274
+ run = sub.add_parser("run", help="run only the tests affected by current changes")
275
+ run.add_argument("path", nargs="?", help="restrict collection to this path")
276
+ run.add_argument("--since", default=None,
277
+ help="git ref to diff against (default: the ref the map was recorded at)")
278
+ run.add_argument("--list", action="store_true", help="list selected tests, don't run")
279
+ run.add_argument("--remote", help="remote dir to pull the map from if absent locally")
280
+ run.add_argument("--trust-dynamic", action="store_true",
281
+ help="don't widen reflection-heavy files to file-level (less safe)")
282
+ run.add_argument("--all-changes", action="store_true",
283
+ help="don't ignore comment/docstring/format/type-only edits")
284
+ run.add_argument("--report", metavar="PATH",
285
+ help="write a Markdown summary to PATH ('-' for stdout); "
286
+ "auto-enabled from $GITHUB_STEP_SUMMARY in CI")
287
+ run.set_defaults(func=cmd_run)
288
+
289
+ push = sub.add_parser("push", help="publish the local map to a shared remote (for CI)")
290
+ push.add_argument("--to", required=True, help="remote dir or http(s) URL to publish into")
291
+ push.set_defaults(func=cmd_push)
292
+
293
+ pull = sub.add_parser("pull", help="fetch a map from a shared remote")
294
+ pull.add_argument("--from", dest="from_", required=True, help="remote dir or http(s) URL")
295
+ pull.add_argument("--ref", help="git ref to fetch (default: HEAD, else latest)")
296
+ pull.set_defaults(func=cmd_pull)
297
+
298
+ srv = sub.add_parser("serve", help="run a tiny HTTP store for maps (zero deps)")
299
+ srv.add_argument("--dir", default="./tia-maps", help="directory to store maps in")
300
+ srv.add_argument("--host", default="127.0.0.1")
301
+ srv.add_argument("--port", type=int, default=8000)
302
+ srv.set_defaults(func=cmd_serve)
303
+
304
+ st = sub.add_parser("status", help="show map summary")
305
+ st.set_defaults(func=cmd_status)
306
+
307
+ args = p.parse_args(argv)
308
+ return args.func(args)