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

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

@@ -149,12 +149,13 @@ jobs:
       - name: Record coverage runtime
         run: uv run --locked python -m coverage --version
       - name: Execute the shared affected-file plan
-        run: uv run --locked python scripts/run_ci_tests.py -q -n 4 --durations=20 --junitxml=test-timings.xml
+        run: uv run --locked pytest-selective execute-plan -- -q -n 4 --dist=worksteal --durations=20 --junitxml=test-timings.xml
         env:
           CI_PLANNER_RESULT: ${{ needs.select-tests.result }}
           CI_TEST_MODE: ${{ needs.select-tests.outputs.mode }}
           CI_TEST_FILES: ${{ needs.select-tests.outputs.files }}
-          CI_COVERAGE: 'true'
+          # Full coverage on each OS; 3.11 retains the same compatibility tests without duplicate instrumentation.
+          CI_COVERAGE: ${{ matrix.python == '3.14' }}
           # Keep temporary Git repositories beside the checkout on the work disk.
           TMP: ${{ runner.temp }}
           TEMP: ${{ runner.temp }}
@@ -186,7 +187,7 @@ jobs:
           python-version: '3.11'
       - run: uv pip install 'pytest==8.0.0'
       - name: Execute the same file plan on minimum pytest
-        run: uv run --no-sync python scripts/run_ci_tests.py -q -n 4 --durations=20
+        run: uv run --no-sync pytest-selective execute-plan -- -q -n 4 --dist=worksteal --durations=20
         env:
           CI_PLANNER_RESULT: ${{ needs.select-tests.result }}
           CI_TEST_MODE: ${{ needs.select-tests.outputs.mode }}

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

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

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

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.2.0](https://github.com/gigaverse-app/pytest-selective/compare/v1.1.2...v1.2.0) (2026-11-09)
+
+
+### Features
+
+* **ci:** share plan execution and reduce matrix instrumentation ([1fe0f36](https://github.com/gigaverse-app/pytest-selective/commit/1fe0f36463d4354a99ea3f45406825fa728a12c2))
+
 ## [1.1.2](https://github.com/gigaverse-app/pytest-selective/compare/v1.1.1...v1.1.2) (2026-11-09)
 
 

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

@@ -79,7 +79,9 @@ split indexes and linked worktrees without modifying the user's index or HEAD.
 CI tests Python 3.11 and 3.14 on Linux, Windows, and macOS. A separate job checks
 pytest 8.0.0 on Python 3.11, the plugin's lower bound. It also checks hooks, builds both distribution
 formats, validates PyPI metadata, and installs each distribution in an isolated
-environment on both Python versions. Evidence artifacts carry coverage and tutorial output on every platform and Python version.
+environment on both Python versions. JUnit retains results and timings on every platform and Python version.
+Full runs collect coverage on Python 3.14 on all three operating systems; Python 3.11 runs the same compatibility
+tests without a duplicate instrumentation pass. Each runner uses four work-stealing workers.
 
 Use `uv lock --upgrade-package NAME` for a targeted dependency update and run the
 affected checks. Dependabot proposes weekly uv and GitHub Actions updates.
@@ -116,8 +118,8 @@ File planning derives its graph from that same lane config and merges its declar
 global execution inputs with the graph's environment inputs. Declare subprocess
 and non-import dependencies at their readers. Full plans collect whole-suite
 coverage; scoped plans produce JUnit timing evidence without presenting partial
-coverage as a whole-suite result. The small execution wrapper only consumes the
-public action's JSON file list: it does not implement another selector.
+coverage as a whole-suite result. The public [shared-plan executor](docs/shared-plan-execution.md)
+consumes the action's JSON file list without implementing another selector.
 The outer pytest process disables the selective plugin to avoid a second planner
 and a hidden dependency of every test on plugin startup. Plugin integration tests
 still load it normally in subprocesses and declare that dependency explicitly.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pytest-selective
-Version: 1.1.2
+Version: 1.2.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/
@@ -237,7 +237,7 @@ skip pytest, because invoking pytest without paths runs the whole suite.
 | --- | --- |
 | A transitive dependency | Import chains and package initialization |
 | A deleted or renamed module | Dependencies in both the base and head trees |
-| Fixtures or startup code | Ancestor conftests, plugins named by `-p` in `addopts`, and configured global modules |
+| Fixtures or startup code | Ancestor conftests, plugins named by `-p` in `addopts`, the project's own `pytest11` entry points, and configured global modules |
 | Templates, schemas, or data files | [Reader-owned declarations and YAML sidecars](docs/tutorials/sidecar-dependencies.md) |
 | A surprisingly large selection | Dependency paths, startup-floor and blast-radius explanations |
 | A large CI suite | Cached parsing, graph reuse, and duration-based shard planning |

{pytest_selective-1.1.2 → pytest_selective-1.2.0}/README.md

@@ -206,7 +206,7 @@ skip pytest, because invoking pytest without paths runs the whole suite.
 | --- | --- |
 | A transitive dependency | Import chains and package initialization |
 | A deleted or renamed module | Dependencies in both the base and head trees |
-| Fixtures or startup code | Ancestor conftests, plugins named by `-p` in `addopts`, and configured global modules |
+| Fixtures or startup code | Ancestor conftests, plugins named by `-p` in `addopts`, the project's own `pytest11` entry points, and configured global modules |
 | Templates, schemas, or data files | [Reader-owned declarations and YAML sidecars](docs/tutorials/sidecar-dependencies.md) |
 | A surprisingly large selection | Dependency paths, startup-floor and blast-radius explanations |
 | A large CI suite | Cached parsing, graph reuse, and duration-based shard planning |

{pytest_selective-1.1.2 → pytest_selective-1.2.0}/contracts/selection/conftest.py

@@ -305,7 +305,8 @@ class RepositoryDriver(SelectionDriver):
         changed = set(git_text(self.root, "diff", "--name-only", "--no-renames", base, self.head).splitlines())
         tests = self._tests(self.head)
         at_head = self._runtime(self.head, tests)
-        at_base = self._runtime(base, [test for test in tests if test in set(self._tests(base))])
+        base_tests = set(self._tests(base))
+        at_base = self._runtime(base, [test for test in tests if test in base_tests])
         needed = {test for test in tests if (at_head[test] | at_base.get(test, frozenset())) & changed}
         return {NAMES[test] for test in needed} - set(selection["selected"])
 

{pytest_selective-1.1.2 → pytest_selective-1.2.0}/contracts/selection/runtime_deps.py

@@ -9,12 +9,16 @@ Modules and sys.path are restored between test files, so each file's dependencie
 import json
 import os
 import sys
+from functools import cache
 from pathlib import Path
 
 import pytest
 
 
+@cache
 def _under(root: Path, path: str | None) -> str | None:
+    # Each process inspects one immutable exported tree. Cache path resolution,
+    # never the per-test import/open observations, which remain isolated below.
     if not path:
         return None
     try:

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

@@ -97,7 +97,7 @@ patterns to your actual inventory. Central-rule reader patterns use shell-style
 matching: here `*` also covers nested paths under `tests/`. Common lockfiles, dependency manifests and pytest configuration already belong
 to the default `global_inputs`. Keep those defaults unless you have reviewed a
 narrower environment contract; these reader-specific rules are for additional
-inputs. Other non-Python files are not automatically global inputs. Plugins named by `-p NAME` in a pytest configuration's `addopts` are global modules automatically; plugins passed only on the command line or in `PYTEST_ADDOPTS` are not visible to the planner. Use `global_modules` for those and other modules loaded by every test and
+inputs. Other non-Python files are not automatically global inputs. Plugins named by `-p NAME` in a pytest configuration's `addopts` are global modules automatically, and so are the project's own `pytest11` entry points (`[project.entry-points.pytest11]` or `[tool.poetry.plugins.pytest11]` in any tracked `pyproject.toml`) whose module is a tracked file. An entry point stays global unless every pytest configuration disables it, with `-p no:NAME` (`NAME` is the entry point's name) or `--disable-plugin-autoload` in `addopts`. Plugins passed only on the command line or in `PYTEST_ADDOPTS`, and `PYTEST_DISABLE_PLUGIN_AUTOLOAD`, are not visible to the planner. Use `global_modules` for those and other modules loaded by every test and
 `always_run` for explicit canary test paths. Retain full-suite checkpoints.
 
 ## Explain and audit
@@ -121,6 +121,49 @@ pytest-selective audit --config .github/test-impact.json --records impact-audit
 Audit results cover executed paths, not every possible execution. Declare missing
 edges at their readers. See [evidence and limitations](evidence.md).
 
+### Write the missing declarations
+
+`audit --write-declarations` writes a rule for every undeclared read into the
+reading test's sidecar, `<test>.gv-dependency.yaml`, creating it or appending to
+the one it already has:
+
+```bash
+pytest-selective audit --config .github/test-impact.json --records impact-audit   --write-declarations
+pytest-selective audit --config .github/test-impact.json --records impact-audit   --working-tree   # confirms nothing is left before you commit
+```
+
+```yaml
+dependencies:
+  - inputs:
+      - "//examples/backgrounds/**"
+      - "//examples/gold.toml"
+    kind: content
+    reason: "Read at runtime; recorded by pytest-selective audit --write-declarations."
+  - inputs:
+      - "//scripts/replay_coverage.py"
+    kind: import
+    reason: "Loaded or run outside the test's imports; recorded by pytest-selective audit --write-declarations."
+```
+
+- A Python input becomes an `import` rule: a test that runs a script in a
+  subprocess also depends on what the script imports. Any other input becomes a
+  `content` rule. Review the kind where the test only reads Python as text.
+- Several reads in one directory become `<directory>/**` only when the test read
+  every tracked file under it, so the glob claims nothing the run did not see.
+  It also covers files added there later.
+- Every pattern must match a tracked file at the audited revision. A path the
+  pattern language cannot express (for example one containing `[`) is printed as
+  `not declared` and the command exits 2.
+- Appending keeps an existing sidecar's text and comments. When the result would
+  not parse to exactly the old rules plus the new ones, the file is left alone
+  and the rules are printed for you to add by hand.
+
+The command prints each sidecar and pattern it wrote and exits 0 when every
+undeclared read was declared. The files are in the working tree, so the plain
+audit (which reads `--head`) still reports them until you commit; use
+`--working-tree` to check first. Prefer a hand-written comment or directory
+manifest where it reads better; the writer only removes the transcription step.
+
 Audit discovery uses the requested repository even when a calling Git hook exports
 location variables for another checkout. It shares repository isolation with the
 planner and expansion guard.

{pytest_selective-1.1.2 → pytest_selective-1.2.0}/docs/selection-health.md

@@ -30,7 +30,8 @@ uv run pytest-selective audit --config .github/test-impact.json --records impact
 The recorder observes real file reads in the tests you execute. The audit can
 expose a JSON fixture, template or schema that the graph did not declare. Add an
 edge at the reader using a dependency comment or YAML sidecar, then recheck the
-route. [Work through the sidecar tutorial](tutorials/sidecar-dependencies.md), or consult
+route. `audit --write-declarations` writes those sidecars for you; see
+[write the missing declarations](configuration.md#write-the-missing-declarations). [Work through the sidecar tutorial](tutorials/sidecar-dependencies.md), or consult
 [declaration syntax](configuration.md#declare-inputs-that-imports-cannot-describe).
 The audit covers observed paths; keep representative full runs for paths it has
 not seen, and explicitly model dynamic imports and external inputs.

pytest_selective-1.2.0/docs/shared-plan-execution.md

@@ -0,0 +1,43 @@
+# Plan once, execute across compatibility lanes
+
+Use `pytest-selective execute-plan` to run a file plan emitted by the public
+test-impact action. Every matrix job consumes the same plan; it does not need
+Git history or a second dependency analysis.
+
+```yaml
+- run: uv run --locked pytest-selective execute-plan -- -q -n 4 --dist=worksteal
+  env:
+    CI_PLANNER_RESULT: ${{ needs.plan.result }}
+    CI_TEST_MODE: ${{ needs.plan.outputs.mode }}
+    CI_TEST_FILES: ${{ needs.plan.outputs.files }}
+    CI_COVERAGE: 'true'
+```
+
+`files` must be the action's `test_roots_json` output. A successful `none` plan
+does not start pytest. Failed planning, malformed JSON, unknown modes or an
+empty scoped selection execute the complete roots. Roots default to `tests`;
+override with `--full-roots tests/unit tests/integration -- ...`. Paths with
+spaces remain single arguments, and pytest receives its normal exit status.
+
+`CI_COVERAGE=true` adds `--cov --cov-report=term-missing --cov-report=xml` only
+for full execution. The environment must have pytest-cov installed. Keep
+coverage thresholds in your project configuration; do not enforce a full-suite
+threshold on selected files. The outer execution disables the selective plugin
+because planning already happened. Integration tests can still load it explicitly.
+
+When lane and file selection share a graph, derive the file config:
+
+```sh
+pytest-selective file-config --lanes .github/test-lanes.json --output /tmp/test-impact.json
+```
+
+This combines the graph's global inputs with the lane config's explicit global
+inputs. Declare `global_inputs` before using it. Lane-specific `inputs` remain
+lane admission rules; they do not automatically make every test file affected.
+Declare non-import dependencies in the graph as usual.
+
+pytest-selective's own CI uses four work-stealing workers on each existing
+runner. Its full checkpoints retain all Python 3.11 and 3.14 compatibility tests
+on Linux, Windows and macOS. Coverage runs on Python 3.14 on all three systems,
+avoiding a second instrumentation pass on Python 3.11. The minimum-pytest lane,
+Quint contract and installed-distribution smoke remain independent checks.

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

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

{pytest_selective-1.1.2 → pytest_selective-1.2.0}/scripts/ci_file_config.py

@@ -4,15 +4,8 @@ import sys
 from pathlib import Path
 
 from pytest_selective.ci import LaneConfig
-from pytest_selective.impact_models import ImpactConfig
 
-
-def file_config(lanes: LaneConfig) -> ImpactConfig:
-    if lanes.global_inputs is None:
-        raise ValueError("This repository must declare its shared CI execution inputs")
-    return lanes.graph.model_copy(
-        update={"global_inputs": sorted(set(lanes.graph.global_inputs) | set(lanes.global_inputs))}
-    )
+file_config = LaneConfig.file_config
 
 
 if __name__ == "__main__":

pytest_selective-1.2.0/scripts/run_ci_tests.py

@@ -0,0 +1,8 @@
+"""Compatibility entry point for the public shared-plan executor."""
+
+import sys
+
+from pytest_selective.execution import main
+
+if __name__ == "__main__":
+    raise SystemExit(main(["--", *sys.argv[1:]]))

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

@@ -55,6 +55,14 @@ class LaneConfig(ImpactModel):
     # including after JSON serialization. Explicit declarations always win.
     global_inputs: list[str] | None = None
 
+    def file_config(self) -> ImpactConfig:
+        """File selection shares the lane graph and explicit execution-wide inputs."""
+        if self.global_inputs is None:
+            raise ValueError("Declare global_inputs before deriving a file-selection config")
+        return self.graph.model_copy(
+            update={"global_inputs": sorted(set(self.graph.global_inputs) | set(self.global_inputs))}
+        )
+
     def is_global_input(self, path: str) -> bool:
         if self.global_inputs is not None:
             return matches(path, self.global_inputs)

pytest_selective-1.1.2/scripts/run_ci_tests.py → pytest_selective-1.2.0/src/pytest_selective/execution.py

@@ -1,12 +1,17 @@
 """Execute the public action's shared file plan; this consumer does no selection."""
 
+import argparse
 import json
 import os
 import subprocess
 import sys
 
 
-def main() -> int:
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--full-roots", nargs="+", default=["tests"])
+    parser.add_argument("pytest_args", nargs=argparse.REMAINDER)
+    args = parser.parse_args(argv)
     mode = os.environ.get("CI_TEST_MODE")
     try:
         files = json.loads(os.environ.get("CI_TEST_FILES", "[]"))
@@ -24,7 +29,7 @@ def main() -> int:
         else:
             print("No affected test files; pytest was not started.")
             return 0
-    roots = ["tests"] if mode == "full" else files
+    roots = args.full_roots if mode == "full" else files
     coverage = []
     if mode == "full" and os.environ.get("CI_COVERAGE") == "true":
         coverage = ["--cov", "--cov-report=term-missing", "--cov-report=xml"]
@@ -32,7 +37,17 @@ def main() -> int:
     return subprocess.run(
         # Planning already happened. Integration tests load the plugin in their
         # subprocesses; do not make it an implicit dependency of every CI test.
-        [sys.executable, "-m", "pytest", "-p", "no:selective", *sys.argv[1:], *coverage, "--", *roots]
+        [
+            sys.executable,
+            "-m",
+            "pytest",
+            "-p",
+            "no:selective",
+            *(args.pytest_args[1:] if args.pytest_args[:1] == ["--"] else args.pytest_args),
+            *coverage,
+            "--",
+            *roots,
+        ]
     ).returncode
 
 

{pytest_selective-1.1.2 → pytest_selective-1.2.0}/src/pytest_selective/impact_audit.py

@@ -45,15 +45,20 @@ def _exempt_pairs(snapshot: Snapshot, exemptions: list[AuditExemption]) -> list[
     return pairs
 
 
-def audit(snapshot: Snapshot, records: list[AuditRecord], config: ImpactConfig) -> AuditReport:
-    """Every recorded (test, input) pair the test's dependency closure does not contain."""
-    exempt = _exempt_pairs(snapshot, config.audit_exemptions)
+def tracked_reads(snapshot: Snapshot, records: list[AuditRecord]) -> dict[str, set[str]]:
+    """Each test file's recorded reads, across every process, of files tracked in the snapshot."""
     reads: dict[str, set[str]] = {}
     for record in records:
         for test, paths in record.inputs.items():
             reads.setdefault(test, set()).update(paths)
     # Only the committed tree can be declared against: a file absent from HEAD has no edge to add.
-    reads = {test: paths & snapshot.files.keys() for test, paths in reads.items() if test in snapshot.files}
+    return {test: paths & snapshot.files.keys() for test, paths in reads.items() if test in snapshot.files}
+
+
+def audit(snapshot: Snapshot, records: list[AuditRecord], config: ImpactConfig) -> AuditReport:
+    """Every recorded (test, input) pair the test's dependency closure does not contain."""
+    exempt = _exempt_pairs(snapshot, config.audit_exemptions)
+    reads = tracked_reads(snapshot, records)
     # An always-run test is selected by every change, so no input can skip it.
     always = {test for test in reads if matches(test, config.always_run)}
     undeclared: list[UndeclaredRead] = []

pytest_selective-1.2.0/src/pytest_selective/impact_audit_declarations.py

@@ -0,0 +1,148 @@
+"""
+Write the declarations a read audit finds missing, as one sidecar per reading test file.
+
+``pytest-selective audit --write-declarations`` turns each undeclared ``test -> input`` read into a
+rule in ``<test>.gv-dependency.yaml``, the reader-owned form that states the edge's kind. A Python
+input becomes an ``import`` rule, because a test that loads or runs a script outside its imports
+(often in a subprocess) also depends on what that script imports. Any other input becomes a
+``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.
+"""
+
+import json
+from collections.abc import Iterable
+from pathlib import Path, PurePosixPath
+
+from pytest_selective.impact_audit import tracked_reads
+from pytest_selective.impact_declarations import (
+    SIDECAR_SUFFIX,
+    DependencyDeclarationError,
+    match_inputs,
+    parse_manifest,
+)
+from pytest_selective.impact_models import (
+    AuditRecord,
+    AuditReport,
+    ImpactModel,
+    ManifestDependencyRule,
+    Snapshot,
+)
+
+CONTENT_REASON = "Read at runtime; recorded by pytest-selective audit --write-declarations."
+IMPORT_REASON = "Loaded or run outside the test's imports; recorded by pytest-selective audit --write-declarations."
+
+
+class SidecarDeclarations(ImpactModel):
+    """The rules one test file's sidecar gains, and the reads each pattern stands for."""
+
+    test: str
+    rules: list[ManifestDependencyRule]
+    #: Pattern (as written, ``//``-rooted) to the undeclared reads it declares.
+    covers: dict[str, list[str]]
+
+    @property
+    def sidecar(self) -> str:
+        return self.test + SIDECAR_SUFFIX
+
+
+class DeclarationPlan(ImpactModel):
+    sidecars: list[SidecarDeclarations]
+    #: Reads no valid pattern can name (the path itself is not a valid declaration), with the reason.
+    skipped: list[str]
+
+
+def _parents(path: str) -> Iterable[str]:
+    """Each directory above ``path``, nearest first, never the repository root."""
+    for parent in PurePosixPath(path).parents:
+        if parent.as_posix() != ".":
+            yield parent.as_posix()
+
+
+def _patterns(undeclared: set[str], read: set[str], files: set[str]) -> dict[str, set[str]]:
+    """Group undeclared reads into patterns: a directory glob only when the test read all of it."""
+    patterns: dict[str, set[str]] = {}
+    for path in sorted(undeclared):
+        widest = None
+        for directory in _parents(path):
+            under = {file for file in files if file.startswith(directory + "/")}
+            if not under <= read:
+                # Every directory further up holds this one, so it cannot be fully read either.
+                break
+            if len(under & undeclared) > 1:
+                widest = directory
+        pattern = f"{widest}/**" if widest else path
+        patterns.setdefault(pattern, set()).add(path)
+    # Whether a directory qualifies does not depend on which read reached it, and every directory
+    # below a qualifying one is fully read too, so all reads under a glob chose that same glob.
+    return patterns
+
+
+def plan_declarations(report: AuditReport, snapshot: Snapshot, records: list[AuditRecord]) -> DeclarationPlan:
+    """The sidecar rules that would declare every undeclared read in ``report``."""
+    files = set(snapshot.files)
+    reads = tracked_reads(snapshot, records)
+    undeclared: dict[str, set[str]] = {}
+    for read in report.undeclared:
+        undeclared.setdefault(read.test, set()).add(read.input)
+    sidecars: list[SidecarDeclarations] = []
+    skipped: list[str] = []
+    for test, paths in sorted(undeclared.items()):
+        inputs: dict[str, list[str]] = {"content": [], "import": []}
+        covers: dict[str, list[str]] = {}
+        for pattern, covered in sorted(_patterns(paths, reads[test], files).items()):
+            try:
+                # Never write a declaration that matches no tracked file at the analysed tree.
+                matched = match_inputs(pattern, files, f"{snapshot.tree}:{test}{SIDECAR_SUFFIX}")
+            except DependencyDeclarationError as error:
+                skipped.extend(f"{test} -> {path}: {error}" for path in sorted(covered))
+                continue
+            kind = "import" if any(path.endswith(".py") for path in matched) else "content"
+            inputs[kind].append(f"//{pattern}")
+            covers[f"//{pattern}"] = sorted(covered)
+        rules = [
+            ManifestDependencyRule(inputs=patterns, kind=kind, reason=reason)
+            for kind, reason in (("content", CONTENT_REASON), ("import", IMPORT_REASON))
+            if (patterns := inputs[kind])
+        ]
+        if rules:
+            sidecars.append(SidecarDeclarations(test=test, rules=rules, covers=covers))
+    return DeclarationPlan(sidecars=sidecars, skipped=skipped)
+
+
+def render_rules(rules: list[ManifestDependencyRule]) -> str:
+    """Rules as items of a sidecar's ``dependencies`` list, every scalar quoted."""
+    lines: list[str] = []
+    for rule in rules:
+        lines.append("  - inputs:")
+        lines += [f"      - {json.dumps(pattern)}" for pattern in rule.inputs]
+        lines.append(f"    kind: {rule.kind}")
+        lines.append(f"    reason: {json.dumps(rule.reason)}")
+    return "\n".join(lines) + "\n"
+
+
+def write_sidecar(repo: Path, declarations: SidecarDeclarations) -> None:
+    """Create the test's sidecar, or append the rules to the one it already has."""
+    path = repo / declarations.sidecar
+    rendered = render_rules(declarations.rules)
+    if not path.exists():
+        # LF on every platform: the sidecar is committed beside the test.
+        text = "dependencies:\n" + rendered
+        parse_manifest(text.encode(), declarations.sidecar)
+    else:
+        existing = path.read_bytes().decode("utf-8-sig")
+        before = parse_manifest(existing.encode(), declarations.sidecar).dependencies
+        newline = "\r\n" if "\r\n" in existing else "\n"
+        text = existing + ("" if existing.endswith("\n") else newline) + rendered.replace("\n", newline)
+        # Appending is textual so the file keeps its comments; prove it parses to exactly the old
+        # rules plus the new ones, or leave the file untouched.
+        try:
+            appended = parse_manifest(text.encode(), declarations.sidecar).dependencies == before + declarations.rules
+        except DependencyDeclarationError:
+            appended = False
+        if not appended:
+            raise DependencyDeclarationError(
+                f"{declarations.sidecar}: cannot append to this sidecar's layout; add these rules by hand:\n{rendered}"
+            )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(text.encode())

{pytest_selective-1.1.2 → pytest_selective-1.2.0}/src/pytest_selective/impact_cli.py

@@ -16,6 +16,7 @@ from pathlib import Path
 
 from pytest_selective.checkpoint import full_checkpoint_reason
 from pytest_selective.impact_audit import audit, load_records, summary
+from pytest_selective.impact_audit_declarations import plan_declarations, write_sidecar
 from pytest_selective.impact_explanation import dependent_tests, explain
 from pytest_selective.impact_graph import (
     DependencyDeclarationError,
@@ -27,10 +28,13 @@ from pytest_selective.impact_graph import (
     reachable,
 )
 from pytest_selective.impact_models import (
+    AuditRecord,
+    AuditReport,
     GraphAnalysisReport,
     ImpactConfig,
     ImpactReport,
     SelectionExplanation,
+    Snapshot,
 )
 from pytest_selective.impact_selection import affected, base_snapshot
 from pytest_selective.pytest_sharding import (
@@ -200,7 +204,9 @@ def _audit(args: argparse.Namespace, config: ImpactConfig, cache: GraphCache) ->
 
     A missing or unreadable record raises, which is operational (exit 1): the audit proved nothing.
     """
-    report = audit(cache.snapshot(args.repo, args.head, config), load_records(args.records), config)
+    snapshot = cache.snapshot(args.repo, args.head, config)
+    records = load_records(args.records)
+    report = audit(snapshot, records, config)
     if args.output:
         args.output.parent.mkdir(parents=True, exist_ok=True)
         args.output.write_text(report.model_dump_json(indent=2) + "\n", encoding="utf-8")
@@ -215,9 +221,32 @@ def _audit(args: argparse.Namespace, config: ImpactConfig, cache: GraphCache) ->
         print(f"{read.test} -> {read.input}")
     for error in report.recorder_errors:
         print(f"recorder error: {error}", file=sys.stderr)
+    if args.write_declarations and report.undeclared:
+        return _write_declarations(args.repo, report, snapshot, records)
     return 2 if report.undeclared else 0
 
 
+def _write_declarations(repo: Path, report: AuditReport, snapshot: Snapshot, records: list[AuditRecord]) -> int:
+    """Write a sidecar rule for every undeclared read; exit 2 only when some read could not be declared."""
+    plan = plan_declarations(report, snapshot, records)
+    for sidecar in plan.sidecars:
+        write_sidecar(repo, sidecar)
+        print(f"wrote {sidecar.sidecar}")
+        for rule in sidecar.rules:
+            for pattern in rule.inputs:
+                covered = sidecar.covers[pattern]
+                detail = f" ({len(covered)} reads)" if len(covered) > 1 else ""
+                print(f"  {rule.kind}: {pattern}{detail}")
+    declared = sum(len(covered) for sidecar in plan.sidecars for covered in sidecar.covers.values())
+    print(
+        f"Declared {declared} of {len(report.undeclared)} undeclared reads in {len(plan.sidecars)} sidecars. "
+        "Review and commit them, then re-run audit (or audit --working-tree) to confirm."
+    )
+    for skipped in plan.skipped:
+        print(f"not declared: {skipped}", file=sys.stderr)
+    return 2 if plan.skipped else 0
+
+
 #: Files that joined the floor named in the budget error before the rest are counted.
 BUDGET_LISTED_FILES = 10
 
@@ -260,6 +289,20 @@ def _floor_budget(args: argparse.Namespace) -> int:
 
 def main(argv: list[str] | None = None) -> int:
     argv = list(sys.argv[1:] if argv is None else argv)
+    if argv[:1] == ["execute-plan"]:
+        from pytest_selective.execution import main as execute
+
+        return execute(argv[1:])
+    if argv[:1] == ["file-config"]:
+        from pytest_selective.ci import LaneConfig
+
+        config_parser = argparse.ArgumentParser(description="Derive file-selection config from explicit lane inputs")
+        config_parser.add_argument("--lanes", type=Path, required=True)
+        config_parser.add_argument("--output", type=Path, required=True)
+        config_args = config_parser.parse_args(argv[1:])
+        lanes = LaneConfig.model_validate_json(config_args.lanes.read_text(encoding="utf-8"))
+        config_args.output.write_text(lanes.file_config().model_dump_json(), encoding="utf-8")
+        return 0
     if argv[:1] == ["run"]:
         from pytest_selective.local import main as run_local
 
@@ -322,14 +365,26 @@ def main(argv: list[str] | None = None) -> int:
     # audit: the directory of pytest read records, and a markdown summary (GITHUB_STEP_SUMMARY) to append to.
     parser.add_argument("--records", type=Path, default=Path("impact-audit"))
     parser.add_argument("--summary", type=Path)
+    parser.add_argument(
+        "--write-declarations",
+        action="store_true",
+        help="audit: write a <test>.gv-dependency.yaml rule for every undeclared read",
+    )
     # floor-budget: the explanation `affected --explanation-output` wrote for this plan.
     parser.add_argument("--explanation", type=Path, default=Path("test-impact-explanation.json"))
     args = parser.parse_args(argv)
     full_reason = args.full
     args.full = full_reason is not None
     args.base = args.base or ("HEAD" if args.working_tree else "HEAD^")
-    if args.working_tree and args.command not in {"affected", "warm", "dependencies", "explain", "conftest-impact"}:
-        parser.error("--working-tree is supported for affected, warm, dependencies, explain and conftest-impact")
+    if args.working_tree and args.command not in {
+        "affected",
+        "audit",
+        "warm",
+        "dependencies",
+        "explain",
+        "conftest-impact",
+    }:
+        parser.error("--working-tree is supported for affected, audit, warm, dependencies, explain and conftest-impact")
     if args.command == "typecheck-scope":
         return _typecheck_scope(args)
     if args.command == "floor-budget":