diffcone 0.1.0__py3-none-any.whl

diffcone/testing.py

@@ -0,0 +1,200 @@
+"""Helpers for writing scenario tests against diffcone.
+
+A scenario is a throwaway git repository built from dicts of file contents,
+committed as before/after snapshots, planned, and then checked for exact
+target sets and reasons. These helpers are what diffcone's own acceptance
+tests use; projects integrating diffcone can use them the same way.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import cast
+
+from diffcone.cache import IndexCache
+from diffcone.evidence import Evidence
+from diffcone.manifest import Manifest, Target, parse_manifest
+from diffcone.planner import Plan, Reason, plan
+from diffcone.report import to_dict
+
+# A hermetic git environment: no user config, deterministic identity.
+GIT_ENV = {
+    "GIT_AUTHOR_NAME": "fixture",
+    "GIT_AUTHOR_EMAIL": "fixture@example.invalid",
+    "GIT_COMMITTER_NAME": "fixture",
+    "GIT_COMMITTER_EMAIL": "fixture@example.invalid",
+    "GIT_CONFIG_GLOBAL": "/dev/null",
+    "GIT_CONFIG_NOSYSTEM": "1",
+    "HOME": "/nonexistent",
+}
+
+
+class FixtureRepo:
+    """A throwaway git repository built from dicts of file contents.
+
+    With ``check_cache`` (diffcone's own suite turns it on) every ``plan``
+    call is also planned through a cold and a warm cache in ``cache_dir``
+    (default: ``.fixture-cache`` beside the repository) and the reports are
+    asserted equal, which triples its cost."""
+
+    def __init__(
+        self, path: Path, *, check_cache: bool = False, cache_dir: Path | None = None
+    ) -> None:
+        self.path = Path(path)
+        self.path.mkdir(parents=True, exist_ok=True)
+        self.check_cache = check_cache
+        self.cache_dir = Path(cache_dir) if cache_dir else self.path.parent / ".fixture-cache"
+        self.git("init", "-q", "-b", "main")
+
+    def try_git(self, *args: str) -> subprocess.CompletedProcess[str]:
+        """Run git and return the completed process, whatever its exit code."""
+        return subprocess.run(
+            ["git", *args], cwd=self.path, env=GIT_ENV, capture_output=True, text=True
+        )
+
+    def git(self, *args: str) -> str:
+        """Run git and return stripped stdout; raises on a non-zero exit."""
+        proc = self.try_git(*args)
+        if proc.returncode != 0:
+            raise RuntimeError(proc.stderr)
+        return proc.stdout.strip()
+
+    def commit(self, files: dict[str, str | bytes | None], message: str = "snapshot") -> str:
+        """Write (or delete, for ``None``) files and commit. Returns the sha.
+        ``bytes`` content is written as given, for a file whose encoding is
+        the point (a PEP 263 coding cookie)."""
+        for rel, content in files.items():
+            target = self.path / rel
+            if content is None:
+                target.unlink()
+            else:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                if isinstance(content, bytes):
+                    target.write_bytes(content)
+                else:
+                    target.write_text(content, "utf-8")
+        self.git("add", "-A")
+        self.git("commit", "-q", "--allow-empty", "-m", message)
+        return self.git("rev-parse", "HEAD")
+
+    def plan(
+        self,
+        base: str,
+        head: str,
+        targets: list[Target] | list[dict],
+        source_roots: list[str] | None = None,
+        **kwargs,
+    ) -> Plan:
+        manifest = (
+            parse_manifest(targets)
+            if targets and isinstance(targets[0], dict)
+            else Manifest(cast(list[Target], list(targets)))
+        )
+        result = plan(self.path, base, head, manifest, source_roots=source_roots, **kwargs)
+        if self.check_cache and "cache" not in kwargs:
+            self._check_cache_invisible(result, base, head, manifest, source_roots, kwargs)
+        return result
+
+    def _check_cache_invisible(self, result, base, head, manifest, source_roots, kwargs) -> None:
+        """The caches are an optimisation only: a plan served cold (module
+        facts and resolution computed and stored) and one served warm (every
+        module's facts and resolution loaded, whole-index entries removed so
+        the module cache is what answers) must equal the uncached plan."""
+        directory = self.cache_dir
+        shutil.rmtree(directory, ignore_errors=True)
+        expected = json.dumps(to_dict(result), sort_keys=True)
+        for warm in (False, True):
+            if warm:
+                shutil.rmtree(directory / "index", ignore_errors=True)
+            cache = IndexCache(directory)
+            again = plan(
+                self.path, base, head, manifest, source_roots=source_roots, cache=cache, **kwargs
+            )
+            got = json.dumps(to_dict(again), sort_keys=True)
+            assert got == expected, f"{'warm' if warm else 'cold'} cached plan differs"
+
+    def collect(
+        self,
+        rev: str | None = None,
+        *,
+        source_roots: list[str] | None = None,
+        reverse_check: bool = False,
+        command: str | None = None,
+        extra: list[str] | None = None,
+        env_variables: list[str] | None = None,
+    ) -> Evidence:
+        """Record execution evidence (``diffcone collect``) at ``rev`` (default:
+        the clean checkout), running the suite with this interpreter's pytest."""
+        from diffcone.execution import collect_evidence  # runs project code
+
+        return collect_evidence(
+            self.path,
+            command=command or f"{sys.executable} -m pytest",
+            source_roots=source_roots or ["."],
+            rev=rev,
+            reverse_check=reverse_check,
+            extra=extra,
+            env_variables=env_variables,
+        ).evidence
+
+    def write_manifest(self, targets: list[dict], name: str = "targets.json") -> Path:
+        path = self.path.parent / name
+        path.write_text(json.dumps({"targets": targets}), "utf-8")
+        return path
+
+
+def py_target(runner_id: str, entry: str, *deps: str) -> Target:
+    return Target("pytest", runner_id, entry, tuple(deps))
+
+
+def asv_target(runner_id: str, entry: str, *deps: str) -> Target:
+    return Target("asv", runner_id, entry, tuple(deps))
+
+
+def selected(plan: Plan) -> set[str]:
+    return {d.target.runner_id for d in plan.decisions if d.selected}
+
+
+def unselected(plan: Plan) -> set[str]:
+    return {d.target.runner_id for d in plan.decisions if not d.selected}
+
+
+def rules(plan: Plan, runner_id: str) -> set[str]:
+    for d in plan.decisions:
+        if d.target.runner_id == runner_id:
+            return {r.rule for r in d.reasons}
+    raise KeyError(runner_id)
+
+
+def reason(plan: Plan, runner_id: str, rule: str = "dependency") -> Reason:
+    for d in plan.decisions:
+        if d.target.runner_id == runner_id:
+            for r in d.reasons:
+                if r.rule == rule:
+                    return r
+    raise KeyError((runner_id, rule))
+
+
+def path_ids(reason: Reason) -> list[str]:
+    """Node ids along a reason's dependency path, source first."""
+    if not reason.path:
+        return []
+    return [reason.path[0].source] + [s.target for s in reason.path]
+
+
+def executed(evidence: Evidence, test_id: str) -> set[str]:
+    """The symbols a test executed in the evidence run."""
+    return evidence.executed(evidence.tests[test_id])
+
+
+def touched(evidence: Evidence, test_id: str) -> set[str]:
+    """The repository paths a test opened, stat'ed or listed in the evidence run."""
+    return evidence.touched(evidence.tests[test_id])
+
+
+def changes(plan: Plan) -> dict[str, tuple[str, ...]]:
+    return {c.id: c.changes for c in plan.changes}

diffcone-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: diffcone
+Version: 0.1.0
+Summary: Static-first, function-level change-impact engine for Python: which tests and benchmarks a change can affect, and why
+Keywords: test selection,test impact analysis,change impact,pytest,asv,ci
+Author: Bearing Research
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/bearing-research/diffcone
+Project-URL: Documentation, https://bearing-research.github.io/diffcone/
+Project-URL: Repository, https://github.com/bearing-research/diffcone
+Project-URL: Issues, https://github.com/bearing-research/diffcone/issues
+Project-URL: Changelog, https://github.com/bearing-research/diffcone/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# diffcone
+
+[![CI](https://github.com/bearing-research/diffcone/actions/workflows/ci.yml/badge.svg)](https://github.com/bearing-research/diffcone/actions/workflows/ci.yml)
+[![Docs](https://github.com/bearing-research/diffcone/actions/workflows/docs.yml/badge.svg)](https://bearing-research.github.io/diffcone/)
+
+**Run the tests your change can affect, and know why each one was picked.**
+
+diffcone compares two versions of a Python repository, finds the functions,
+methods and classes that changed, and follows the code's dependencies back
+to the tests and benchmarks that can observe them. Each selected test comes
+with the reason it was selected.
+
+```console
+$ diffcone plan --base main --head WORKTREE --discover pytest \
+    --source-root src --source-root . --format text
+...
+changed symbols (1):
+  calc.ops.mul [function] body_changed
+
+selected targets (2):
+  pytest: tests/test_calc.py::test_mul
+    - dependency: calc.ops.mul body_changed
+  pytest: tests/test_calc.py::test_square
+    - dependency: calc.ops.mul body_changed
+
+unselected targets (1):
+  pytest: tests/test_calc.py::test_add
+```
+
+- **Every selection is explained:** the report shows the chain of calls and
+  references from each test to the change.
+- **It errs on the side of running more:** when diffcone can't tell what a
+  change reaches, it selects more tests and says why.
+- **It never runs your code to plan:** planning reads files and git history
+  only.
+- **pytest and ASV:** tests and benchmarks are found from your
+  configuration and source, the way each runner collects them.
+- **Execution evidence:** for large codebases where nearly everything
+  imports everything, record once what each test ran and plan from that.
+
+## Install
+
+Python 3.11 or later and git; no other dependencies.
+
+```bash
+uv tool install diffcone    # or: pipx install diffcone, pip install diffcone
+```
+
+## Use
+
+```bash
+# Which tests can my uncommitted changes affect?
+diffcone plan --base main --head WORKTREE --discover pytest --format text
+
+# Run only those tests (arguments after -- go to pytest)
+diffcone run --base main --head WORKTREE --discover pytest --command "uv run pytest" -- -x
+
+# Record what each test runs, then plan from the recording (Python 3.12+)
+diffcone collect --command "uv run pytest" -- -n 8
+diffcone plan --base main --head HEAD --discover pytest --evidence auto -o plan.json
+
+# Did the plan select every test that failed in a full run?
+diffcone check --plan plan.json --full full.xml
+```
+
+For a `src` layout, add `--source-root src --source-root .` so modules get
+their import names.
+
+## Documentation
+
+Read the documentation at
+**[bearing-research.github.io/diffcone](https://bearing-research.github.io/diffcone/)**:
+
+- [Getting started](https://bearing-research.github.io/diffcone/latest/getting-started/)
+- [How it works](https://bearing-research.github.io/diffcone/latest/concepts/)
+- Guides: [planning](https://bearing-research.github.io/diffcone/latest/guides/planning/),
+  [running and checking](https://bearing-research.github.io/diffcone/latest/guides/running/),
+  [execution evidence](https://bearing-research.github.io/diffcone/latest/guides/evidence/),
+  [CI with GitHub Actions](https://bearing-research.github.io/diffcone/latest/ci/)
+- [Command reference](https://bearing-research.github.io/diffcone/latest/reference/cli/)
+  and [limitations](https://bearing-research.github.io/diffcone/latest/limitations/)
+
+## Status
+
+diffcone is alpha software. Its selections have been checked against the
+full test suites of 34 open-source projects. See the
+[changelog](https://github.com/bearing-research/diffcone/blob/main/CHANGELOG.md)
+for what each release contains.
+
+## Contributing
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests scripts && uv run ruff format --check src tests scripts
+uv run ty check
+```
+
+See the [development guide](https://bearing-research.github.io/diffcone/latest/development/)
+and [AGENTS.md](https://github.com/bearing-research/diffcone/blob/main/AGENTS.md).
+
+## License
+
+MIT; see [LICENSE](https://github.com/bearing-research/diffcone/blob/main/LICENSE).

diffcone-0.1.0.dist-info/RECORD

@@ -0,0 +1,39 @@
+diffcone/__init__.py,sha256=qbazijAQfmvdP791Jriky0uZL6VMvS-qABvBK5QMBMM,477
+diffcone/cache.py,sha256=ktkJKneiz4IDispcWoi9XCwoCLS5HgXUUqHvpHefne8,20828
+diffcone/check.py,sha256=BqV4LAIweJfzMjcPfNgjPjbXw7hpjt9JdahBvN2o0Bs,14614
+diffcone/classify.py,sha256=u4FMKNl-dhRBfb16ASqFhtXRO_XHCS8lKhPyiLNfPVQ,11283
+diffcone/cli.py,sha256=tnYzvjJI0bW4-reHehlPH_szEWHTfQpGTIZDXhIFIZI,37202
+diffcone/collect.py,sha256=v5b4j969hMuBH6qZjcAI0zy-MM6jGns2lCtkf4EC5ug,31346
+diffcone/cython.py,sha256=nBuP7E1wEjkcBMu0sQX-JU01ryrNHvDwKBIeowVY5L8,30796
+diffcone/declarations.py,sha256=x_A9B2zcHN5sc5BHrHxMVeUClgWAufitmJxCl1H-4cM,4392
+diffcone/discovery/__init__.py,sha256=19K0VkGMyXogobN6EVSQRitKwxqcN7SELMBLgOUcc7c,4325
+diffcone/discovery/asv_static.py,sha256=jT0w2wInSMtmnEW9VCQrquAabsRDWRA8FL2RrrMgk88,21186
+diffcone/discovery/common.py,sha256=Km1jOQZBziVDFgpSLaLkt4Nw0CB8cqbOUARejij56Jg,4609
+diffcone/discovery/pytest_static.py,sha256=A9Yu6xotz4f7IJTTYdglJ-ignXerBC40KVZE75bPEOk,114194
+diffcone/evidence.py,sha256=p5fzQVzLlkNs0WSioGaW6fMc9_ZFqm-rKxA34qgpGcY,31677
+diffcone/evidence_plan.py,sha256=ZplypghCuEJQdz-_4Oj2a4X0452micT1ojNq_f71Lmw,65291
+diffcone/execution.py,sha256=aUU8Wqo_meAzl9YWCKxEpUqvvuJu_d8J3RcYpl8UOTA,68854
+diffcone/indexer/__init__.py,sha256=Xn4Ryd1kXnv-xSYoAFWlO07xwgN3GDwv5_-F8N9fn90,1803
+diffcone/indexer/core.py,sha256=YfpHteoZg8JZtqXVa5Whb3GzLJd0LhQwpwz4KnpoMKc,13870
+diffcone/indexer/definitions.py,sha256=KdvixZbN_MuQ-HyEqzCRZQ5Kmr7Q6TXUO0s3wtkOYl8,12213
+diffcone/indexer/dynamics.py,sha256=tgFwuVET0S9h7D1I3RyV-jgfxSo4R75VrEFqbc-YwMc,18549
+diffcone/indexer/facts.py,sha256=ADPGaFPP0U71Ow1OHbO-1Q2RhOcT9fFQYYIQUA0Iyws,15445
+diffcone/indexer/literals.py,sha256=VtT_oq2uva66gU2RC1-Vc6eqpGXUMZtSpXbtvuMFBwY,15149
+diffcone/indexer/references.py,sha256=SnKp_-UnTFvxutoirSfRcNB4CT5ONqsr6l42_r-Y1qU,40764
+diffcone/indexer/resolver.py,sha256=YH0V7lXKgoKEFOIgIiT9f4e7NWbLJKK7127SVWGXzjE,47786
+diffcone/indexer/scopes.py,sha256=EmgLdevc6wonGpSmM1lBeZLj1xnwfsoxHhbHs7jj33w,11965
+diffcone/indexer/state.py,sha256=bhwAVtfiyiG5m6F8N3o-_sOvVfjRs_DBZjFsjLexKwg,3656
+diffcone/indexer/symbols.py,sha256=hwgs_OjCbykwKu7E2lIuIdoyOnVMzuL-w090xTJFcD0,19548
+diffcone/indexer/syntax.py,sha256=X6e6zISgrXmJyPiQEW4c88KqxtyCfW9pDBqmJhxlxzw,5834
+diffcone/manifest.py,sha256=fK-uslZe8hemg55tKwM8AFNsT-tXXB6YYvK0EQmtonA,6294
+diffcone/model.py,sha256=y1Cy1JjG9OcI6XrurLgGj3F2bVOg9bEqMwGeFDQvi_c,8053
+diffcone/planner.py,sha256=eEbNrbOm0UrkXLw2xzv0U3YJXIH0GRmsJ4qhe9XDsVw,59740
+diffcone/report.py,sha256=8LY7MYeQ9zHnmHcvz4V0uwjncbj13u66A38fQbNnnf8,10174
+diffcone/selection.py,sha256=n8jQPf2qzsSwwa20aKiJ7oCqs3ND8OfC4fapzGF3gWA,5560
+diffcone/snapshot.py,sha256=LGHBT9jJZKXbH_0rry4Fyt_F4JJJDwLnaskVtRTA3jE,29371
+diffcone/testing.py,sha256=THE6CT65nY_LewL1pFZgxrYbtN805abvdWxHKcFKsho,7588
+diffcone-0.1.0.dist-info/licenses/LICENSE,sha256=jX-OPRzCDHug3I-cqFfFZqbcCFPNSc9Y9E5c7xcobf4,1073
+diffcone-0.1.0.dist-info/WHEEL,sha256=cmC5s21ojypbVslldL7IJq3hjZH-tINy4rziKePFsG0,81
+diffcone-0.1.0.dist-info/entry_points.txt,sha256=8egIaUvWcHazoYp6jTI0MLzpDqKtDRJju-07DXTayYg,48
+diffcone-0.1.0.dist-info/METADATA,sha256=Rn5wKkqRAh3ltN8y47G1tiyhBfW8CChxN5MnIgAzwEU,5475
+diffcone-0.1.0.dist-info/RECORD,,

diffcone-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.23
+Root-Is-Purelib: true
+Tag: py3-none-any

diffcone-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+diffcone = diffcone.cli:main
+

diffcone-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bearing Research
+
+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.