pytest-selective 1.2.0__tar.gz → 1.3.0__tar.gz

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/.github/workflows/ci.yml

@@ -6,8 +6,6 @@ on:
     types: [opened, synchronize, reopened]
   workflow_dispatch:
   workflow_call:
-  schedule:
-    - cron: '13 3 * * 1'
 permissions:
   contents: read
 concurrency:

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/.github/workflows/pr-title.yml

@@ -2,7 +2,8 @@ name: PR title
 
 # Squash merges use this checked title as the Conventional Commit header.
 on:
-  pull_request_target:
+  # Metadata reads need no privileged target event or repository secrets.
+  pull_request:
     types: [opened, edited, synchronize, reopened, ready_for_review]
 
 permissions:

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/.github/workflows/public-actions.yml

@@ -4,8 +4,6 @@ on:
   push:
     branches: [main]
   workflow_dispatch:
-  schedule:
-    - cron: '33 3 * * 1'
 permissions:
   contents: read
 jobs:

pytest_selective-1.3.0/.github/workflows/weekly-checkpoint.yml

@@ -0,0 +1,21 @@
+name: Weekly full checkpoint
+'on':
+  schedule:
+  - cron: 13 3 * * 1
+  workflow_dispatch: null
+permissions:
+  contents: read
+  actions: write
+concurrency:
+  group: weekly-full-checkpoint
+  cancel-in-progress: false
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+    - uses: gigaverse-app/ci-esta/actions/weekly-checkpoint@v1
+      with:
+        workflows: '["ci.yml", "public-actions.yml"]'
+        ref: ''
+        workflow-inputs: '{}'

pytest_selective-1.3.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.3.0"
+}

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.3.0](https://github.com/gigaverse-app/pytest-selective/compare/v1.2.0...v1.3.0) (2026-11-09)
+
+
+### Features
+
+* **audit:** show how many tests each written declaration selects ([#124](https://github.com/gigaverse-app/pytest-selective/issues/124)) ([b660301](https://github.com/gigaverse-app/pytest-selective/commit/b660301be82aefb04fdc79202dc83067c28d7eb1))
+
+
+### Bug fixes
+
+* agent setup round 3, from a third adoption trial ([#127](https://github.com/gigaverse-app/pytest-selective/issues/127)) ([a82bea9](https://github.com/gigaverse-app/pytest-selective/commit/a82bea9f607abcb3ed68009571202ad8b7726c7e))
+* **selection:** keep every module a pytest11 entry-point name maps to ([#122](https://github.com/gigaverse-app/pytest-selective/issues/122)) ([acb6649](https://github.com/gigaverse-app/pytest-selective/commit/acb66492c6440621387e0506c1d0071a5a48979c))
+* **selection:** plan a pull request against its merge commit's actual base ([#119](https://github.com/gigaverse-app/pytest-selective/issues/119)) ([276cec8](https://github.com/gigaverse-app/pytest-selective/commit/276cec84f65c889a1820fd5a001a3a4aca8b7e0d))
+
 ## [1.2.0](https://github.com/gigaverse-app/pytest-selective/compare/v1.1.2...v1.2.0) (2026-11-09)
 
 

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/CONTRIBUTING.md

@@ -199,14 +199,19 @@ history or failed planning must execute the full affected lanes and fail the
 required planning gate. Ordinary PRs and pushes use selection; manual/release/scheduled/full overrides
 remain complete checkpoints.
 
-CI and public-action smoke run full checkpoints every Monday. Ordinary runs keep
+The **Weekly full checkpoint** workflow dispatches CI and public-action smoke
+every Monday using [CI-esta's shared action](https://github.com/gigaverse-app/ci-esta/blob/main/docs/weekly-checkpoints.md).
+Its small wrapper is generated by `ci-esta checkpoint init`; the source guide
+documents schedule, workflow, ref and input overrides. Ordinary runs keep
 the shared affected-file plan across all six OS/Python combinations and minimum
 pytest. `tests/test_tutorial.py` owns the end-to-end tutorial execution and follows
 that plan; there is no second tutorial invocation in each matrix job. JUnit retains
 its test result and timing, and full plans also upload whole-suite coverage.
 
-To run a complete checkpoint after a CI change, select **CI** in GitHub Actions
-and choose **Run workflow**. Retrying an ordinary PR run preserves its selection;
+To run both complete checkpoints after a CI change, select **Weekly full checkpoint**
+in GitHub Actions and choose **Run workflow**, then inspect the dispatched CI and
+public-action results. A green dispatcher means both requests were accepted.
+You can also dispatch either target directly. Retrying an ordinary PR run preserves its selection;
 use the manual checkpoint when you need full-suite coverage evidence.
 
 ## Duplication

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pytest-selective
-Version: 1.2.0
+Version: 1.3.0
 Summary: Explainable Python test impact analysis: select affected pytest files from Git changes
 Project-URL: Homepage, https://github.com/gigaverse-app/pytest-selective
 Project-URL: Documentation, https://pytest-selective.readthedocs.io/en/latest/

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/action.yml

@@ -14,6 +14,11 @@ inputs:
   head:
     description: Exact checked-out commit.
     default: HEAD
+  pr-head:
+    description: The pull request's head. When the checkout is GitHub's merge of it (refs/pull/N/merge), changes are measured
+      from that merge's base-branch parent, so commits that landed on the base branch after `base` are not counted as the
+      PR's. Empty (any other event) keeps `base`.
+    default: ${{ github.event.pull_request.head.sha }}
   full-roots:
     description: Space-separated complete test roots used if planning cannot prove a narrower scope.
     required: true
@@ -100,6 +105,7 @@ runs:
       config: ${{ inputs.config }}
       base: ${{ inputs.base }}
       head: ${{ inputs.head }}
+      pr-head: ${{ inputs.pr-head }}
       full-roots: ${{ inputs.full-roots }}
       full: ${{ inputs.full }}
       extra-files: ${{ inputs.extra-files }}

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/actions/plan-lanes/action.yml

@@ -7,6 +7,12 @@ inputs:
   base:
     description: Base commit containing the complete change set.
     default: ${{ github.event.pull_request.base.sha || github.event.before }}
+  pr-head:
+    description: >-
+      The pull request's head. When the checkout is GitHub's merge of it (refs/pull/N/merge), changes are measured from
+      that merge's base-branch parent, so commits that landed on the base branch after `base` are not counted as the PR's.
+      Empty (any other event) keeps `base`.
+    default: ${{ github.event.pull_request.head.sha }}
   full:
     description: 'auto preserves selection on PR/push reruns and runs full for manual/scheduled/release checkpoints or test:full. Override with true or false.'
     default: auto
@@ -40,10 +46,12 @@ runs:
         SELECTIVE_CONFIG: ${{ inputs.config }}
         SELECTIVE_BASE: ${{ inputs.base }}
         SELECTIVE_FULL: ${{ inputs.full }}
+        SELECTIVE_PR_HEAD: ${{ inputs.pr-head }}
       run: |
         export PYTHONPATH="$SELECTIVE_ACTION/../../src${PYTHONPATH:+:$PYTHONPATH}"
         args=(--config "$SELECTIVE_CONFIG" --base "$SELECTIVE_BASE" --github-output "$GITHUB_OUTPUT")
         args+=(--full "$SELECTIVE_FULL")
+        if [ -n "$SELECTIVE_PR_HEAD" ]; then args+=(--pr-head "$SELECTIVE_PR_HEAD"); fi
         uv run --no-project --python 3.14 --with pydantic==2.13.4 --with pyyaml==6.0.3 \
           python -m pytest_selective.ci "${args[@]}" | tee test-lanes.json
         {

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/actions/test-impact/action.yml

@@ -13,6 +13,12 @@ inputs:
   head:
     description: Exact checked-out commit.
     default: HEAD
+  pr-head:
+    description: >-
+      The pull request's head. When the checkout is GitHub's merge of it (refs/pull/N/merge), changes are measured from
+      that merge's base-branch parent, so commits that landed on the base branch after `base` are not counted as the PR's.
+      Empty (any other event) keeps `base`.
+    default: ${{ github.event.pull_request.head.sha }}
   full-roots:
     description: Space-separated complete test roots used if planning cannot prove a narrower scope.
     required: true
@@ -114,6 +120,7 @@ runs:
         IMPACT_CONFIG: ${{ inputs.config }}
         IMPACT_BASE: ${{ inputs.base }}
         IMPACT_HEAD: ${{ inputs.head }}
+        IMPACT_PR_HEAD: ${{ inputs.pr-head }}
         IMPACT_FULL: ${{ inputs.full }}
         IMPACT_EXTRA: ${{ inputs.extra-files }}
         IMPACT_ALTERNATE_BASE: ${{ inputs.alternate-base }}
@@ -147,6 +154,7 @@ runs:
         # A reused workspace must not upload a previous plan's explanation.
         rm -f test-impact-explanation.json
         args+=(--full "$IMPACT_FULL")
+        if [ -n "${IMPACT_PR_HEAD:-}" ]; then args+=(--pr-head "$IMPACT_PR_HEAD"); fi
         if [ -n "$IMPACT_EXTRA" ]; then args+=(--extra-files "$IMPACT_EXTRA"); fi
         if [ -n "${IMPACT_GRAPH_BASE:-}" ]; then args+=(--graph-base "$IMPACT_GRAPH_BASE"); fi
         # Optional: an unfetchable alternate only forgoes a smaller selection.

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/docs/ci.md

@@ -64,6 +64,14 @@ controls the test interpreter. `full-roots` must contain the complete roots, not
 the previous selection. `base` defaults to the PR base or the push's previous
 commit. Override it only when you have validated a different comparison base.
 
+On a pull request, GitHub checks out a merge of the PR head into the base
+branch's current tip, which can be newer than the PR's recorded base. Both
+actions pass the PR head (`pr-head`) so the planner measures changes from that
+merge's base-branch parent. Commits that landed on the base branch after the PR
+was opened, such as a release's version bump, are then not counted as the PR's
+own. A shallow checkout or any other event keeps `base`. Check out with
+`fetch-depth: 0` to get the narrower plan.
+
 Both file and lane actions default to `full: auto`:
 
 | Trigger | Default |

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/docs/configuration.md

@@ -22,6 +22,11 @@ select. The default filenames are `test_*.py`, `*_test.py`, `*_tests.py`, and
 `tests.py`; configure
 `test_patterns` for a different collection policy.
 
+Every `--config` (`affected`, `explain`, `fingerprints`, `audit`, `run` and the rest) also accepts a
+[lane config](ci.md) such as `.github/test-lanes.json`: it uses the lane config's `graph`, with its
+top-level `global_inputs` when declared. Pass the lane config itself rather than a copy of its graph,
+so a later `graph.pytest_policy` refresh is always the one in use.
+
 ## Review and record collection policy
 
 If your repository has `pyproject.toml`, `pytest.ini`, a `tox.ini` with a `[pytest]`
@@ -61,6 +66,9 @@ fixture example, directory manifests, dependency comments, and dynamic Python in
 
 A read that names a tracked file by literal path, such as `open("data/prices.json")` or
 `(Path(__file__).parent / "prices.json").read_text()`, is followed automatically as a content read.
+A string that only names a tracked file, such as a routing test's `("bench.py", ...)` row, adds no
+edge: a dotted string is followed as a possible module name (a patch target, a plugin) only when it
+names no tracked file, from the repository root or beside its reader.
 For a path that is computed, or built from several parts, add a reader-owned comment:
 
 ```python

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytest-selective"
-version = "1.2.0"
+version = "1.3.0"
 description = "Explainable Python test impact analysis: select affected pytest files from Git changes"
 readme = "README.md"
 requires-python = ">=3.11"

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/skills/pytest-selective/SKILL.md

@@ -56,7 +56,10 @@ A fresh fork has no runs yet. Read the typical jobs and durations from UPSTREAM
 
 Record:
 
-- **Conventions**: commit and PR title style, changelog rules, AI policy, pre-commit hooks.
+- **Conventions**: commit and PR title style, changelog rules, AI policy, pre-commit hooks. When the pull request
+  template names a CONTRIBUTING, CODE_OF_CONDUCT or security file the repository lacks, read the owner's organization
+  default from its `.github` repository (in a fork, the upstream owner's):
+  `gh api "repos/OWNER/.github/contents/CONTRIBUTING.md" --jq .content | base64 -d`.
 - **Packaging tool**: uv project, Poetry, PDM, Hatch with tox or nox, or plain pip requirements/extras. It decides how
   you run the planner locally and how routing tests install (step 6). CI planning itself installs nothing in the
   project: the actions bring their own Python 3.14 planner.
@@ -66,7 +69,11 @@ Record:
   its matrix size, services, coverage floors and typical duration (`gh run view RUN --repo "$REPO" --json jobs`).
 - **Publish paths**: jobs that publish or deploy (PyPI, Test PyPI, Pages, containers, releases) and every job they
   `needs:`, directly or transitively. Step 4.4 keeps these paths unchanged.
-- **Triggers**: whether `push` runs for every branch, and any `branches:`/`paths:` filters.
+- **Test workflows**: the file name of each workflow that runs tests (`test.yml`, `tests.yaml`, `ci.yml`, ...).
+  Below, `test.yml` stands for `<the repo's test workflow>`: write the real names in the config, the routing test and
+  the report.
+- **Triggers**: whether `push` runs for every branch, and any `branches:`, `paths:` or `paths-ignore:` filters (4.3
+  removes path filters from gated workflows).
 - **Existing gate**: an aggregate job (`all-green`, `alls-green`, `check`) and the required check names.
 
 If CI already finishes in a couple of minutes, or nearly every change touches source code, say so in your report:
@@ -84,7 +91,9 @@ VERSION=${TAG#v}
 ```
 
 Local commands use `pytest-selective==$VERSION`; the routing-test job (step 6) installs `pytest-selective>=$VERSION,<2`,
-so it follows the same major version as `@v1`.
+so it follows the same major version as `@v1`. uv caches the package index, so a release published minutes ago can
+be missing (`No solution found`, `pytest-selective==X.Y.Z` unsatisfiable): the local commands below pass
+`--refresh-package pytest-selective`. With pip, add `--no-cache-dir`.
 
 Only when the repository's tooling rejects tags (zizmor's `unpinned-uses`, a `pinact` hook, or an all-SHA policy its
 CI enforces) pin the release instead: `@$SHA # $TAG` on every action, with
@@ -122,7 +131,7 @@ line or a nox `session.install`). CI does not need this.
     "global_inputs": ["pyproject.toml", "tox.ini", "requirements/tests.txt"]
   },
   "lanes": {
-    "tests": {"roots": ["tests"]},
+    "tests": {"roots": ["tests"], "inputs": ["src/toy/*.c", "src/toy/*.pyi"]},
     "bench": {"roots": ["tests/benchmarks"]},
     "package": {"inputs": ["src/**", "pyproject.toml", "README.md", "LICENSE"]},
     "routing": {"roots": ["ci_tests"]}
@@ -143,6 +152,11 @@ Adapt every path; this is a shape, not an inventory. The rules:
   `dir/**/*.py` matches `dir/x.py` and `dir/a/x.py`. Name execution files; never a directory that also holds prose
   (`examples/**` runs the lane for an example's README; use `examples/**/*.py`). A lane without roots runs only on its
   inputs, on global inputs, or when a change reaches every test.
+- **Non-Python sources are not imports.** A C extension (`_speedups.c`), Cython (`.pyx`, `.pxd`), type stubs
+  (`.pyi`), templates or data files the tests read: the graph does not see them unless a test opens them by literal
+  path. Add each as an input of the lanes that build or test it, as exact globs
+  (`"tests": {"roots": ["tests"], "inputs": ["src/pkg/*.c", "src/pkg/*.pyi"]}`) or the package directory (`src/**`)
+  when every file there matters, and give each a routing row (step 6).
 - **`graph.global_inputs`** are the environment files whose change can affect every test, and the only place to narrow
   them. Omitted, the built-in list applies: `pyproject.toml`, `setup.cfg`, `setup.py`, `tox.ini`, `pytest.ini`,
   `pytest.toml`, `uv.lock`, `poetry.lock`, `pdm.lock`, `pixi.lock`, `Pipfile`, `Pipfile.lock`, `*requirements*.txt`,
@@ -166,30 +180,39 @@ Add `.test-impact/` to `.gitignore`: the planner keeps its graph cache there.
 
 **Collection policy.** If pytest configuration exists (`pyproject.toml`, `pytest.ini`, `pytest.toml`, a `tox.ini`
 with `[pytest]`, a `setup.cfg` with `[tool:pytest]`), the planner runs every lane until you record its fingerprints
-(`full-suite fallback: pytest configuration changed; review collection policy and refresh its fingerprints`). Review
+(`full-suite fallback: pytest configuration changed (pyproject.toml); review collection policy and refresh its
+fingerprints: ...`). Review
 the pytest settings and collection hooks, commit the config, then:
 
 ```bash
-mkdir -p .test-impact
-python -c "import json; print(json.dumps(json.load(open('.github/test-lanes.json'))['graph']))" > .test-impact/graph.json
-uv run --no-project --with "pytest-selective==$VERSION" \
-  pytest-selective fingerprints --config .test-impact/graph.json --head HEAD
+uv run --refresh-package pytest-selective --no-project --with "pytest-selective==$VERSION" \
+  pytest-selective fingerprints --config .github/test-lanes.json --head HEAD
 ```
 
-Copy the printed object into `graph.pytest_policy` and commit. Releases up to 1.1.1 also print a `tox.ini` or
+Copy the printed object into `graph.pytest_policy` and commit. Every `pytest-selective` command (`fingerprints`,
+`explain`, `affected`, `run`) takes the lane config itself as `--config`, so the policy you record is the one in use.
+Releases up to 1.2.0 need a derived file instead: `pytest-selective file-config --lanes .github/test-lanes.json
+--output .test-impact/graph.json` (it needs top-level `global_inputs`), passed as `--config .test-impact/graph.json`.
+Re-run it after every lane-config change, recording `pytest_policy` included, or `explain` keeps failing with
+`pytest configuration changed`. Releases up to 1.1.1 also print a `tox.ini` or
 `setup.cfg` that has no pytest section (pytest ignores it); keeping that entry is harmless. Without uv, run the same
 commands in a virtual environment after `python -m pip install "pytest-selective==$VERSION"`. When pytest settings
 change later, the planner falls back to every lane until someone reviews and refreshes the fingerprints.
 
 ### Prove the config locally
 
-On a throwaway branch, commit one probe edit at a time and plan it against the default branch:
+On a throwaway branch made from the adoption branch, after committing the lane config, commit one probe edit at a
+time and plan it against its parent:
 
 ```bash
-uv run --no-project --with "pytest-selective==$VERSION" \
-  python -m pytest_selective.ci --config .github/test-lanes.json --base origin/DEFAULT --head HEAD
+uv run --refresh-package pytest-selective --no-project --with "pytest-selective==$VERSION" \
+  python -m pytest_selective.ci --config .github/test-lanes.json --base HEAD^ --head HEAD
 ```
 
+Do not plan against `origin/DEFAULT` before the merge: DEFAULT lacks `.github/test-lanes.json`, a global input, so
+every probe would report `global input: .github/test-lanes.json` and select every lane. The parent commit already has
+the config, so the plan sees only the probe edit.
+
 Expected: JSON with `lanes` (one boolean per lane), `reason` and `lane_reasons`. A README edit gives every lane
 `false` (or only `package`, when the build embeds the README) with `no affected tests or changed inputs`; a source
 edit selects the lanes of the tests that import it (`affected test: tests/test_x.py`); a lockfile or workflow edit
@@ -241,6 +264,10 @@ The action also uploads its plan as a `test-lane-selection` artifact, which
           fromJSON(needs.select-tests.outputs.lanes).tests) }}
 ```
 
+A skipped matrix job is listed under its unevaluated name (for example `${{ matrix.name || matrix.python }}`),
+because the matrix never expands. Mention it in the report, or give the job a name that also reads well unexpanded,
+such as `name: tests (${{ matrix.python }})`.
+
 `always()` lets the condition run when the planner failed, and the failed-planner branch then runs the job: a broken
 plan must never become a green skip. The condition applies before the matrix expands, so the whole matrix skips
 together. A job with other needs must check them itself, because `always()` also ignores their failure:
@@ -259,6 +286,10 @@ together. A job with other needs must check them itself, because `always()` also
   control at the probe head (step 8), so keep them; cancel the source probe's push runs as soon as they start
   (`gh run cancel RUN --repo "$REPO"`) and judge that probe by its `pull_request` runs. The cost ends once the
   adoption merges.
+- **`paths:` and `paths-ignore:` filters.** Remove them from every workflow that gets a gate; the lanes replace
+  them. A required gate in a workflow that a filter skipped never reports, so a docs-only pull request would wait on
+  it forever. This is a behavior change: a change the filter skipped (say `docs/**`) now starts the planner, the
+  unconditional jobs and the gate. Say so in the report, with its cost (step 10, net effect).
 - **`branches:` filters.** A probe pull request opened against your adoption branch does not start workflows filtered
   to `pull_request: branches: [main]`. Prove those workflows with routing tests and local plans, and say in the report
   that their hosted probe waits for the merge.
@@ -365,6 +396,7 @@ ROOT = Path(__file__).resolve().parents[1]
 CONFIG = LaneConfig.model_validate_json((ROOT / ".github/test-lanes.json").read_text(encoding="utf-8"))
 EVERY = dict.fromkeys(CONFIG.lanes, True)
 NONE = dict.fromkeys(CONFIG.lanes, False)
+# <the repo's test workflow>: tests.yaml, ci.yml, ...
 WORKFLOW = ROOT / ".github/workflows/test.yml"
 PLANNER = "select-tests"
 # The gate job's id. Keep an existing aggregate job's id, for example "success".
@@ -406,6 +438,8 @@ def repo(tmp_path: Path) -> Path:
         ("requirements-mypy.txt", NONE),
         ("tests/test_other.py", {**NONE, "tests": True}),
         ("src/toy/other.py", {**NONE, "tests": True, "package": True}),
+        # Non-Python sources the tests exercise (a C extension, stubs), declared as lane inputs.
+        ("src/toy/_speedups.c", {**NONE, "tests": True, "package": True}),
         ("tests/benchmarks/test_bench.py", {**NONE, "tests": True, "bench": True}),
         ("tox.ini", EVERY),
         (".github/test-lanes.json", EVERY),
@@ -446,12 +480,12 @@ def test_the_gate_guards_every_job_and_lane_jobs_run_when_planning_fails() -> No
         assert all(f"fromJSON(needs.{PLANNER}.outputs.lanes).{lane}" in condition for lane in lanes), job
 ```
 
-Add a row for every directory you narrowed, every requirements file, each workflow and each lane, using real tracked
-paths. A row appends a comment; a `<workflow>#<job>` input ignores comments, so edit the job itself in that row. With
+Add a row for every directory you narrowed, every requirements file, each non-Python source input, each workflow and
+each lane, using real tracked paths. A row only names its path; it does not make this test depend on that file. A row appends a comment; a `<workflow>#<job>` input ignores comments, so edit the job itself in that row. With
 several workflows, repeat the gate test per workflow with its own `GATE`. Make the file pass the repository's own
 linters, formatter and type checker before committing: for example, ruff's `required-imports` may demand
 `from __future__ import annotations` (the template has it), and black or `ruff format` with a shorter line length
-reflows it. Run it locally with `uv run --no-project --with "pytest-selective==$VERSION" pytest ci_tests -q` and
+reflows it. Run it locally with `uv run --refresh-package pytest-selective --no-project --with "pytest-selective==$VERSION" pytest ci_tests -q` and
 commit it.
 
 ## 7. Prove it on hosted CI
@@ -487,8 +521,12 @@ Compare a selected run with a full control **at the same head**:
   gh workflow run WORKFLOW --repo "$REPO" --ref PROBE_BRANCH      # once per workflow
   ```
 
-  GitHub dispatches only workflows whose file exists on DEFAULT, and may read the trigger from there: if a workflow
-  gains `workflow_dispatch:` only in your adoption and the dispatch is refused, measure after the merge. A rerun is
+  Dispatch only the workflows this adoption gates. A workflow without `workflow_dispatch:` returns HTTP 422
+  (`Workflow does not have 'workflow_dispatch' trigger`); do not add the trigger to workflows you otherwise leave
+  alone. Leave such workflows out of both sides and say the comparison covers only the gated workflows. GitHub
+  dispatches only workflows whose file exists on DEFAULT, and may read the trigger from DEFAULT's copy rather than the
+  branch's: if a workflow gains `workflow_dispatch:` only in your adoption and the dispatch is refused, measure after
+  the merge. A rerun is
   not a control: it keeps the selection. Do not wait on a `test:full` label; creating one is the human's step 9.
 
 Both sides then share a head SHA: a `pull_request` run records the branch head as its `head_sha`, although it checks
@@ -541,6 +579,15 @@ pytest-selective vX.Y.Z: actions at `@v1` (or `@<sha> # vX.Y.Z` where tags are r
 | Elapsed seconds | | |
 
 Runs: [full](https://github.com/OWNER/NAME/actions/runs/RUN_ID), [selected](https://github.com/OWNER/NAME/actions/runs/RUN_ID). One pair, not an average or a bill.
+Workflows compared: ... (and any left out, such as one without `workflow_dispatch:`).
+
+### Net effect
+- Docs-only pull requests: before ... runner-seconds (0 where a removed `paths-ignore` skipped them), after ....
+- Code changes: lane jobs now wait for the planner, about N s.
+- Changes that now skip tests: ... (prose and tooling the old filters did not cover).
+
+### Trigger changes (behavior change)
+- Removed `paths-ignore: [...]` from `<the repo's test workflow>`; added `workflow_dispatch:` ... (or "none").
 
 ### Evidence
 - N routing tests: docs, requirements, source, tests, benchmarks, workflows, missing history, full checkpoint.
@@ -551,9 +598,15 @@ Runs: [full](https://github.com/OWNER/NAME/actions/runs/RUN_ID), [selected](http
 - Label `test:full`; trigger change; scheduled full run.
 
 ### Not done or not verified
+- Skipped matrix jobs show their unevaluated name (`matrix.name || matrix.python`), if kept.
 - ...
 ```
 
+The net effect and trigger changes are required. Write them honestly: when CI was already cheap, or a `paths-ignore`
+already skipped docs, say the adoption saves little, what it costs (planner latency on code changes; docs-only runs
+going from 0 to about N runner-seconds), and what it buys (a gate that can be required, and skips for changes the old
+filters missed).
+
 For depth: [configuration reference](https://pytest-selective.readthedocs.io/en/latest/docs/configuration/),
 [CI guide](https://pytest-selective.readthedocs.io/en/latest/docs/ci/),
 [documentation-only audit](https://pytest-selective.readthedocs.io/en/latest/docs/tutorials/skip-unrelated-ci/),

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/src/pytest_selective/ci.py

@@ -12,6 +12,7 @@ import yaml
 from pydantic import Field, field_validator, model_validator
 
 from pytest_selective.checkpoint import full_checkpoint_reason
+from pytest_selective.git_operations import pull_request_merge_base
 from pytest_selective.impact_graph import DependencyDeclarationError, GraphCache, git, matches, within
 from pytest_selective.impact_models import ImpactConfig, ImpactModel
 from pytest_selective.impact_selection import affected
@@ -63,6 +64,20 @@ class LaneConfig(ImpactModel):
             update={"global_inputs": sorted(set(self.graph.global_inputs) | set(self.global_inputs))}
         )
 
+    @classmethod
+    def file_config_at(cls, path: Path) -> ImpactConfig:
+        """The file-selection config at `path`, which may also be a lane config such as `.github/test-lanes.json`.
+
+        A lane config gives its graph, with its explicit global inputs when it declares them. Reading
+        it directly means no derived copy can miss a later `graph.pytest_policy` refresh.
+        """
+        text = path.read_text(encoding="utf-8")
+        data = json.loads(text)
+        if not isinstance(data, dict) or "lanes" not in data:
+            return ImpactConfig.model_validate_json(text)
+        lanes = cls.model_validate(data)
+        return lanes.graph if lanes.global_inputs is None else lanes.file_config()
+
     def is_global_input(self, path: str) -> bool:
         if self.global_inputs is not None:
             return matches(path, self.global_inputs)
@@ -254,6 +269,8 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--repo", type=Path, default=Path("."))
     parser.add_argument("--base", required=True)
     parser.add_argument("--head", default="HEAD")
+    # A pull request's head: when `--head` is GitHub's merge of it, plan against the merge's actual base.
+    parser.add_argument("--pr-head", default="")
     parser.add_argument(
         "--full", nargs="?", const="true", default="false", type=full_checkpoint_reason, metavar="auto|true|false"
     )
@@ -261,7 +278,13 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
     try:
         config = LaneConfig.model_validate_json(args.config.read_text(encoding="utf-8"))
-        result = plan(args.repo, config, args.base, args.head, full=args.full is not None)
+        base = pull_request_merge_base(args.repo, args.base, args.head, args.pr_head)
+        if base != args.base:
+            print(
+                f"Planning against the tested merge's base {base}; the event's base {args.base} is behind it.",
+                file=sys.stderr,
+            )
+        result = plan(args.repo, config, base, args.head, full=args.full is not None)
         if args.full is not None:
             result.reason = args.full
     except (ValueError, OSError, DependencyDeclarationError) as error:

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/src/pytest_selective/git_operations.py

@@ -47,3 +47,26 @@ def git(repo: Path, *args: str, data: bytes | None = None, index: Path | None =
 def git_text(repo: Path, *args: str, index: Path | None = None) -> str:
     """UTF-8 text with universal newlines, independent of the Windows locale."""
     return git(repo, *args, index=index).decode("utf-8").replace("\r\n", "\n").replace("\r", "\n")
+
+
+def pull_request_merge_base(repo: Path, base: str, head: str, pr_head: str) -> str:
+    """
+    The base a pull request's merge commit was built on, or `base` when that is not provable.
+
+    GitHub checks out `refs/pull/N/merge`: the PR head merged into the base branch's current tip.
+    The event's `pull_request.base.sha` can be older, so commits that landed on the base branch
+    since would read as the PR's own changes: a release's version bump then selects every test.
+    When `head` is that merge (two parents, the second the PR head) and `base` is an ancestor of
+    the first parent, the first parent is the tested base. A push, a shallow history or any other
+    shape keeps `base`, which is never narrower than the truth.
+    """
+    if not pr_head:
+        return base
+    try:
+        parents = git_text(repo, "rev-list", "--parents", "-n", "1", head).split()[1:]
+        if len(parents) != 2 or parents[1] != git_text(repo, "rev-parse", f"{pr_head}^{{commit}}").strip():
+            return base
+        git(repo, "merge-base", "--is-ancestor", base, parents[0])
+    except subprocess.CalledProcessError:
+        return base
+    return parents[0]

{pytest_selective-1.2.0 → pytest_selective-1.3.0}/src/pytest_selective/impact_audit_declarations.py

@@ -8,6 +8,10 @@ input becomes an ``import`` rule, because a test that loads or runs a script out
 ``content`` rule. Reads under one directory collapse into ``<directory>/**`` only when the test read
 every tracked file under it, so the glob claims no input the run did not see. Every pattern is
 checked against the analysed tree before anything is written.
+
+A declaration selects every test that depends on its reader, not only the reader. Each sidecar
+records how many tests that is, so a reader that every test reaches (a test module another test
+imports, or one that registers session plugins) is visible before the declaration is committed.
 """
 
 import json
@@ -21,6 +25,7 @@ from pytest_selective.impact_declarations import (
     match_inputs,
     parse_manifest,
 )
+from pytest_selective.impact_explanation import dependent_tests
 from pytest_selective.impact_models import (
     AuditRecord,
     AuditReport,
@@ -40,6 +45,8 @@ class SidecarDeclarations(ImpactModel):
     rules: list[ManifestDependencyRule]
     #: Pattern (as written, ``//``-rooted) to the undeclared reads it declares.
     covers: dict[str, list[str]]
+    #: Test files a change to any declared input selects: the reader and every test depending on it.
+    selects: int
 
     @property
     def sidecar(self) -> str:
@@ -48,6 +55,8 @@ class SidecarDeclarations(ImpactModel):
 
 class DeclarationPlan(ImpactModel):
     sidecars: list[SidecarDeclarations]
+    #: Test files in the analysed tree, the scale ``SidecarDeclarations.selects`` is read against.
+    total_tests: int
     #: Reads no valid pattern can name (the path itself is not a valid declaration), with the reason.
     skipped: list[str]
 
@@ -82,6 +91,7 @@ def plan_declarations(report: AuditReport, snapshot: Snapshot, records: list[Aud
     """The sidecar rules that would declare every undeclared read in ``report``."""
     files = set(snapshot.files)
     reads = tracked_reads(snapshot, records)
+    reach = dependent_tests(snapshot)
     undeclared: dict[str, set[str]] = {}
     for read in report.undeclared:
         undeclared.setdefault(read.test, set()).add(read.input)
@@ -106,8 +116,9 @@ def plan_declarations(report: AuditReport, snapshot: Snapshot, records: list[Aud
             if (patterns := inputs[kind])
         ]
         if rules:
-            sidecars.append(SidecarDeclarations(test=test, rules=rules, covers=covers))
-    return DeclarationPlan(sidecars=sidecars, skipped=skipped)
+            selects = max(reach.get(test, 0).bit_count(), 1)
+            sidecars.append(SidecarDeclarations(test=test, rules=rules, covers=covers, selects=selects))
+    return DeclarationPlan(sidecars=sidecars, skipped=skipped, total_tests=len(snapshot.tests))
 
 
 def render_rules(rules: list[ManifestDependencyRule]) -> str: