gd-tools-cli 0.7.0__tar.gz → 0.9.0__tar.gz

{gd_tools_cli-0.7.0 → gd_tools_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gd-tools-cli
-Version: 0.7.0
+Version: 0.9.0
 Summary: A modern development workflow CLI for GDScript projects in Godot 4.5+
 Author-email: mansyar <m.ansyarafi@gmail.com>
 License: MIT
@@ -35,6 +35,7 @@ Requires-Dist: watchdog
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
 Requires-Dist: ruff==0.15.21; extra == "dev"
 Requires-Dist: black; extra == "dev"
 Requires-Dist: commitizen; extra == "dev"
@@ -77,7 +78,7 @@ One install, one config, one mental model.
 | **Native test runtime** | Tests extend `GdToolsTest` and run inside Godot itself. Scene and resource integration tests reach the real scene tree through an explicit context object rather than a proxy. Doubles, partial doubles, and stubbing isolate collaborators; spy assertions cover calls, argument wildcards, call order, and property values. |
 | **Snapshot testing** | `assert_snapshot(value)` pins rendered values -- including object property dumps and node trees -- against versioned, diffable `.snap` files. First run writes and passes; mismatches fail with a unified diff, and `--snapshot-update` accepts the new output. |
 | **Zero-friction bootstrap** | `gd-tools init` gets a project fully set up in under a minute -- native test and coverage addons deployed, configs generated. |
-| **Coverage gap-filling** | Production-quality line and branch coverage for GDScript -- HTML, LCOV, Cobertura, and JSON reports, plus GitHub Actions annotations that surface failures inline on pull requests. Independent line (`--min`) and branch (`--min-branch`) gates. `# gd-tools: no cover` annotations exclude debug-only code from the numbers. `coverage run` collects coverage during manual playtest sessions, not just automated tests. |
+| **Coverage gap-filling** | Production-quality line and branch coverage for GDScript -- HTML, LCOV, Cobertura, and JSON reports, plus GitHub Actions annotations that surface failures inline on pull requests. Independent line (`--min`) and branch (`--min-branch`) gates. `# gd-tools: no cover` annotations exclude debug-only code from the numbers. `coverage run` collects coverage during manual playtest sessions, not just automated tests. Patch coverage (`coverage diff --patch`) reports coverage over only the lines a pull request changes, with its own gate and inline annotations. |
 | **CI/CD friendly** | Exit codes, `--check` flags, machine-readable output (JSON, JUnit XML, LCOV, Cobertura), and GitHub Actions annotations for lint violations and coverage gates. No interactive prompts in CI mode. |
 | **Standalone compatibility** | gdlint and gdformat continue to work if invoked directly. `gd-tools` is a layer on top, not a lock-in. |
 
@@ -141,11 +142,11 @@ func test_health_starts_at_full() -> void:
 |---------|-------------|
 | `gd-tools init` | Bootstrap a Godot project -- deploy the native test and coverage addons, generate configs. |
 | `gd-tools doctor` | Diagnose the development environment -- Godot, native test addon, coverage addon, tooling; reports legacy GUT artifacts as migration advice. |
-| `gd-tools test` | Run tests with optional coverage, thresholds, and JUnit XML output. Suites must extend `GdToolsTest`; `GutTest` suites are rejected with exit 2 and migration guidance. Accepts optional path arguments to override configured test directories. `--parallel N` runs suites through a bounded worker pool. `--changed` runs only the suites mapped from git-changed files. `--watch` re-runs affected suites on `.gd` file changes. `--durations N` reports the N slowest tests after the run. Every run publishes a machine-readable artifact index under `.gd-tools/artifacts/<run_id>/`. |
+| `gd-tools test` | Run tests with optional coverage, thresholds, and JUnit XML output. Suites must extend `GdToolsTest`; `GutTest` suites are rejected with exit 2 and migration guidance. Accepts optional path arguments to override configured test directories. `--parallel N` runs suites through a bounded worker pool. `--changed` runs only the suites mapped from git-changed files. `--watch` re-runs affected suites on `.gd` file changes. `--durations N` reports the N slowest tests after the run. `--exitfirst` (`-x`) stops dispatching new suites after the first failing suite; `--shard K/N` runs one round-robin shard for CI matrix splitting; `--random-order` (with `--no-random-order` to turn a configured shuffle off) shuffles suite and test-method execution order, and `--seed N` pins the shuffle so a run can be replayed. Every run publishes a machine-readable artifact index under `.gd-tools/artifacts/<run_id>/`. |
 | `gd-tools migrate` | Guided GUT-to-native migration. Default: read-only report with unsupported-construct inventory and proposed base-class rewrites. `--apply` renames clean suites to `GdToolsTest` and translates `.gutconfig.json` into `gd-tools.toml` (merge, never clobber). `--config-only` translates config only. |
 | `gd-tools lint` | Lint GDScript files using gdlint with text, JSON, or GitHub Actions annotation output. Accepts one or more file or directory paths. |
 | `gd-tools format` | Format GDScript files using gdformat with check and diff modes. Accepts one or more file or directory paths. |
-| `gd-tools coverage` | Coverage subcommands -- `report`, `merge`, `show`, `save-baseline`, `diff` (baseline comparison for CI regression gates), and `run` (collect coverage during a manual playtest session). |
+| `gd-tools coverage` | Coverage subcommands -- `report`, `merge`, `show`, `save-baseline`, `diff` (baseline comparison for CI regression gates; with `--patch`, PR-scoped coverage over changed lines), and `run` (collect coverage during a manual playtest session). |
 | `gd-tools config` | Configuration management -- `show` (display resolved config), `validate` (check config validity), `schema` (print or write the JSON Schema for `gd-tools.toml`). |
 | `gd-tools version` | Display versions of all gd-tools components (gd-tools, Godot, gdtoolkit, Python) in a table or JSON. |
 | `gd-tools completion` | Generate shell completion scripts for bash, zsh, fish, or PowerShell. |
@@ -162,6 +163,11 @@ gd-tools test --parallel 4                 # run suites with 4 concurrent worker
 gd-tools test --durations 10               # report the 10 slowest tests
 gd-tools test --changed                    # only suites mapped from git-changed files
 gd-tools test --changed --base main        # PR/CI mode: diff from merge-base with main
+gd-tools test --exitfirst                  # stop dispatching after the first failing suite
+gd-tools test --shard 2/4                  # CI sharding: run suite shard 2 of 4
+gd-tools test --random-order               # shuffle suite and test method order
+gd-tools test --seed 42                    # --seed implies --random-order; replayable
+gd-tools test --no-random-order            # discovery order for one run, config regardless
 ```
 
 `--tag` is repeatable, and `--test-timeout` (per test) is separate from
@@ -190,6 +196,48 @@ pull-request CI. `--changed` composes with `--parallel`, `--coverage`, and
 the `--suite`/`--test`/`--tag` filters (the active filters bound the
 mapping domain); an empty change set exits 0 without launching Godot.
 
+`--exitfirst` (short form `-x`) stops dispatching **new** suites after the
+first suite whose final result is a failure — a test failure or an
+infrastructure error. In-flight suites finish and are collected; suites that
+were never started are reported as skipped (`not_run`) and summarized in a
+`Stopped early: fail-fast after suite <id> (K of M suites skipped)` line.
+Passes and skips never trigger the gate, and a suite that passes after a
+retry does not either — only final suite results decide. The exit code stays
+1 for test failures. `--exitfirst` composes with `--parallel` (the pool
+drains instead of killing workers), with `--coverage` (the report covers the
+suites that ran, labeled partial when plan targets went unmeasured), and with
+`--watch` (the gate resets for every re-run).
+
+`--shard K/N` runs only the suites assigned to shard `K` of `N` — suite *i*
+of the deterministic plan order belongs to shard `(i mod N) + 1` — for
+splitting one test run across CI jobs. Selection happens after `--changed`
+filtering and before `--parallel`, so each flag keeps exactly one job.
+`--shard 1/1` is valid and equivalent to no sharding; malformed values
+(`--shard 4/3`, `--shard 3`) exit 2 before any work. Each shard produces its
+own coverage report; merge the shards with `gd-tools coverage merge`.
+`--shard` and `--watch` are rejected together (exit 2). See the
+[sharding recipe](./docs/USER_GUIDE.md#sharding-a-test-run-across-ci-jobs)
+for a GitHub Actions matrix example.
+
+`--random-order` shuffles the execution order of the selected suites, and of
+the test methods within each suite, to surface tests that depend on a
+neighbour's side effects. The order is a pure function of the seed and the
+selected suite/test set: the run summary reports
+`Random order: seed <N> (replay with --seed <N>)` — exempt from `--quiet`,
+since a shuffled failure cannot be reproduced without its seed — and
+re-running with that
+seed reproduces the order exactly. `--seed N` pins the shuffle and implies
+`--random-order`; without it a fresh 31-bit seed is generated per run. Persist
+the choice with `random_order = true` and `seed = 42` under `[test]`, and undo
+it for one run with the paired `--no-random-order`. Shuffling
+never changes shard membership — `--shard` assigns suites from the
+deterministic plan order, so CI matrix jobs still cover every suite exactly
+once — and `--watch` resolves one seed for the whole session so successive
+re-runs stay comparable. `--verbose` lists the resolved order suite-by-suite,
+and the seed is recorded in `artifacts.json`. A seed reproduces an order for
+the same Python version, not across versions: `random.Random` is what draws
+the order and CPython may change its shuffle algorithm between releases.
+
 Repeat runs are faster: the `godot --headless --import` step is cached under
 `.gd-tools/native/import-cache/` and skipped when `project.godot`, any
 project source/resource file (scripts, scenes, import sidecars, addons), or
@@ -378,8 +426,10 @@ prefix = "test_"
 suffix = ".gd"
 runtime = "native"        # native (default); "gut" is no longer a runnable runtime
 timeout_seconds = 5.0     # default per-test timeout for async native tests
-retries = 0               # opt-in retries per native test
+retries = 0               # opt-in retries per native test; retried passes are flagged as flaky
 # parallel = 4            # opt-in parallel suite execution (1-32; unset runs sequentially)
+# random_order = true     # opt-in shuffled suite and test-method order
+# seed = 42               # pin the shuffle seed so a shuffled run is replayable
 tags = []                 # native suite tag filters
 
 [lint]

{gd_tools_cli-0.7.0 → gd_tools_cli-0.9.0}/README.md

@@ -36,7 +36,7 @@ One install, one config, one mental model.
 | **Native test runtime** | Tests extend `GdToolsTest` and run inside Godot itself. Scene and resource integration tests reach the real scene tree through an explicit context object rather than a proxy. Doubles, partial doubles, and stubbing isolate collaborators; spy assertions cover calls, argument wildcards, call order, and property values. |
 | **Snapshot testing** | `assert_snapshot(value)` pins rendered values -- including object property dumps and node trees -- against versioned, diffable `.snap` files. First run writes and passes; mismatches fail with a unified diff, and `--snapshot-update` accepts the new output. |
 | **Zero-friction bootstrap** | `gd-tools init` gets a project fully set up in under a minute -- native test and coverage addons deployed, configs generated. |
-| **Coverage gap-filling** | Production-quality line and branch coverage for GDScript -- HTML, LCOV, Cobertura, and JSON reports, plus GitHub Actions annotations that surface failures inline on pull requests. Independent line (`--min`) and branch (`--min-branch`) gates. `# gd-tools: no cover` annotations exclude debug-only code from the numbers. `coverage run` collects coverage during manual playtest sessions, not just automated tests. |
+| **Coverage gap-filling** | Production-quality line and branch coverage for GDScript -- HTML, LCOV, Cobertura, and JSON reports, plus GitHub Actions annotations that surface failures inline on pull requests. Independent line (`--min`) and branch (`--min-branch`) gates. `# gd-tools: no cover` annotations exclude debug-only code from the numbers. `coverage run` collects coverage during manual playtest sessions, not just automated tests. Patch coverage (`coverage diff --patch`) reports coverage over only the lines a pull request changes, with its own gate and inline annotations. |
 | **CI/CD friendly** | Exit codes, `--check` flags, machine-readable output (JSON, JUnit XML, LCOV, Cobertura), and GitHub Actions annotations for lint violations and coverage gates. No interactive prompts in CI mode. |
 | **Standalone compatibility** | gdlint and gdformat continue to work if invoked directly. `gd-tools` is a layer on top, not a lock-in. |
 
@@ -100,11 +100,11 @@ func test_health_starts_at_full() -> void:
 |---------|-------------|
 | `gd-tools init` | Bootstrap a Godot project -- deploy the native test and coverage addons, generate configs. |
 | `gd-tools doctor` | Diagnose the development environment -- Godot, native test addon, coverage addon, tooling; reports legacy GUT artifacts as migration advice. |
-| `gd-tools test` | Run tests with optional coverage, thresholds, and JUnit XML output. Suites must extend `GdToolsTest`; `GutTest` suites are rejected with exit 2 and migration guidance. Accepts optional path arguments to override configured test directories. `--parallel N` runs suites through a bounded worker pool. `--changed` runs only the suites mapped from git-changed files. `--watch` re-runs affected suites on `.gd` file changes. `--durations N` reports the N slowest tests after the run. Every run publishes a machine-readable artifact index under `.gd-tools/artifacts/<run_id>/`. |
+| `gd-tools test` | Run tests with optional coverage, thresholds, and JUnit XML output. Suites must extend `GdToolsTest`; `GutTest` suites are rejected with exit 2 and migration guidance. Accepts optional path arguments to override configured test directories. `--parallel N` runs suites through a bounded worker pool. `--changed` runs only the suites mapped from git-changed files. `--watch` re-runs affected suites on `.gd` file changes. `--durations N` reports the N slowest tests after the run. `--exitfirst` (`-x`) stops dispatching new suites after the first failing suite; `--shard K/N` runs one round-robin shard for CI matrix splitting; `--random-order` (with `--no-random-order` to turn a configured shuffle off) shuffles suite and test-method execution order, and `--seed N` pins the shuffle so a run can be replayed. Every run publishes a machine-readable artifact index under `.gd-tools/artifacts/<run_id>/`. |
 | `gd-tools migrate` | Guided GUT-to-native migration. Default: read-only report with unsupported-construct inventory and proposed base-class rewrites. `--apply` renames clean suites to `GdToolsTest` and translates `.gutconfig.json` into `gd-tools.toml` (merge, never clobber). `--config-only` translates config only. |
 | `gd-tools lint` | Lint GDScript files using gdlint with text, JSON, or GitHub Actions annotation output. Accepts one or more file or directory paths. |
 | `gd-tools format` | Format GDScript files using gdformat with check and diff modes. Accepts one or more file or directory paths. |
-| `gd-tools coverage` | Coverage subcommands -- `report`, `merge`, `show`, `save-baseline`, `diff` (baseline comparison for CI regression gates), and `run` (collect coverage during a manual playtest session). |
+| `gd-tools coverage` | Coverage subcommands -- `report`, `merge`, `show`, `save-baseline`, `diff` (baseline comparison for CI regression gates; with `--patch`, PR-scoped coverage over changed lines), and `run` (collect coverage during a manual playtest session). |
 | `gd-tools config` | Configuration management -- `show` (display resolved config), `validate` (check config validity), `schema` (print or write the JSON Schema for `gd-tools.toml`). |
 | `gd-tools version` | Display versions of all gd-tools components (gd-tools, Godot, gdtoolkit, Python) in a table or JSON. |
 | `gd-tools completion` | Generate shell completion scripts for bash, zsh, fish, or PowerShell. |
@@ -121,6 +121,11 @@ gd-tools test --parallel 4                 # run suites with 4 concurrent worker
 gd-tools test --durations 10               # report the 10 slowest tests
 gd-tools test --changed                    # only suites mapped from git-changed files
 gd-tools test --changed --base main        # PR/CI mode: diff from merge-base with main
+gd-tools test --exitfirst                  # stop dispatching after the first failing suite
+gd-tools test --shard 2/4                  # CI sharding: run suite shard 2 of 4
+gd-tools test --random-order               # shuffle suite and test method order
+gd-tools test --seed 42                    # --seed implies --random-order; replayable
+gd-tools test --no-random-order            # discovery order for one run, config regardless
 ```
 
 `--tag` is repeatable, and `--test-timeout` (per test) is separate from
@@ -149,6 +154,48 @@ pull-request CI. `--changed` composes with `--parallel`, `--coverage`, and
 the `--suite`/`--test`/`--tag` filters (the active filters bound the
 mapping domain); an empty change set exits 0 without launching Godot.
 
+`--exitfirst` (short form `-x`) stops dispatching **new** suites after the
+first suite whose final result is a failure — a test failure or an
+infrastructure error. In-flight suites finish and are collected; suites that
+were never started are reported as skipped (`not_run`) and summarized in a
+`Stopped early: fail-fast after suite <id> (K of M suites skipped)` line.
+Passes and skips never trigger the gate, and a suite that passes after a
+retry does not either — only final suite results decide. The exit code stays
+1 for test failures. `--exitfirst` composes with `--parallel` (the pool
+drains instead of killing workers), with `--coverage` (the report covers the
+suites that ran, labeled partial when plan targets went unmeasured), and with
+`--watch` (the gate resets for every re-run).
+
+`--shard K/N` runs only the suites assigned to shard `K` of `N` — suite *i*
+of the deterministic plan order belongs to shard `(i mod N) + 1` — for
+splitting one test run across CI jobs. Selection happens after `--changed`
+filtering and before `--parallel`, so each flag keeps exactly one job.
+`--shard 1/1` is valid and equivalent to no sharding; malformed values
+(`--shard 4/3`, `--shard 3`) exit 2 before any work. Each shard produces its
+own coverage report; merge the shards with `gd-tools coverage merge`.
+`--shard` and `--watch` are rejected together (exit 2). See the
+[sharding recipe](./docs/USER_GUIDE.md#sharding-a-test-run-across-ci-jobs)
+for a GitHub Actions matrix example.
+
+`--random-order` shuffles the execution order of the selected suites, and of
+the test methods within each suite, to surface tests that depend on a
+neighbour's side effects. The order is a pure function of the seed and the
+selected suite/test set: the run summary reports
+`Random order: seed <N> (replay with --seed <N>)` — exempt from `--quiet`,
+since a shuffled failure cannot be reproduced without its seed — and
+re-running with that
+seed reproduces the order exactly. `--seed N` pins the shuffle and implies
+`--random-order`; without it a fresh 31-bit seed is generated per run. Persist
+the choice with `random_order = true` and `seed = 42` under `[test]`, and undo
+it for one run with the paired `--no-random-order`. Shuffling
+never changes shard membership — `--shard` assigns suites from the
+deterministic plan order, so CI matrix jobs still cover every suite exactly
+once — and `--watch` resolves one seed for the whole session so successive
+re-runs stay comparable. `--verbose` lists the resolved order suite-by-suite,
+and the seed is recorded in `artifacts.json`. A seed reproduces an order for
+the same Python version, not across versions: `random.Random` is what draws
+the order and CPython may change its shuffle algorithm between releases.
+
 Repeat runs are faster: the `godot --headless --import` step is cached under
 `.gd-tools/native/import-cache/` and skipped when `project.godot`, any
 project source/resource file (scripts, scenes, import sidecars, addons), or
@@ -337,8 +384,10 @@ prefix = "test_"
 suffix = ".gd"
 runtime = "native"        # native (default); "gut" is no longer a runnable runtime
 timeout_seconds = 5.0     # default per-test timeout for async native tests
-retries = 0               # opt-in retries per native test
+retries = 0               # opt-in retries per native test; retried passes are flagged as flaky
 # parallel = 4            # opt-in parallel suite execution (1-32; unset runs sequentially)
+# random_order = true     # opt-in shuffled suite and test-method order
+# seed = 42               # pin the shuffle seed so a shuffled run is replayable
 tags = []                 # native suite tag filters
 
 [lint]

{gd_tools_cli-0.7.0 → gd_tools_cli-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gd-tools-cli"
-version = "0.7.0"
+version = "0.9.0"
 description = "A modern development workflow CLI for GDScript projects in Godot 4.5+"
 readme = "README.md"
 license = {text = "MIT"}
@@ -49,6 +49,7 @@ Documentation = "https://github.com/mansyar/gd-tools#readme"
 dev = [
     "pytest",
     "pytest-cov",
+    "pytest-xdist",
     "ruff==0.15.21",
     "black",
     "commitizen",
@@ -71,6 +72,10 @@ where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# Import gd_tools from this checkout's src/ rather than any globally
+# installed (editable) copy, so worktrees and CI checkouts always test
+# their own tree.
+pythonpath = ["src"]
 markers = [
     "unit: Unit tests for individual modules.",
     "integration: Integration tests for command flows.",
@@ -105,7 +110,7 @@ target-version = ["py310"]
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.7.0"
+version = "0.9.0"
 version_files = ["pyproject.toml:version"]
 changelog_file = "CHANGELOG.md"
 tag_format = "v$version"

{gd_tools_cli-0.7.0 → gd_tools_cli-0.9.0}/src/gd_tools/addons/gd-tools-coverage/coverage.gd

@@ -17,6 +17,28 @@ extends Node
 
 const TRACKER_NAME = "_GDTCoverage"
 
+## Every branch_type this collector knows how to measure. A plan that
+## carries anything else was produced by a newer plan generator than
+## this collector implements; instrumenting it would silently
+## mis-measure the unknown arms, so the plan is rejected instead.
+const KNOWN_BRANCH_TYPES: Array[String] = [
+	"if_true",
+	"elif_true",
+	"if_false",
+	"loop_body",
+	"match_case",
+	"ternary_true",
+	"ternary_false",
+	"and_site",
+	"and_right",
+	"and_short",
+	"or_site",
+	"or_right",
+	"or_short",
+	"assert_true",
+	"assert_false",
+]
+
 const PLAYTEST_ENV = "GD_TOOLS_COVERAGE_PLAYTEST"
 
 const PLAYTEST_INTERVAL_ENV = "GD_TOOLS_COVERAGE_PLAYTEST_INTERVAL"
@@ -24,6 +46,7 @@ const PLAYTEST_INTERVAL_ENV = "GD_TOOLS_COVERAGE_PLAYTEST_INTERVAL"
 const DEFAULT_PLAYTEST_INTERVAL: float = 5.0
 
 var _hits: Dictionary = {}
+var _derived: Dictionary = {}
 
 var _active: bool = false
 
@@ -83,12 +106,24 @@ func hit(file_id: int, line_id: int) -> void:
 func hit_ret(file_id: int, line_id: int, value: Variant) -> Variant:
 	## Record one instrumented hit and pass the tracked value through.
 	##
-	## Injected around ternary operands so each arm is measured exactly
-	## when it evaluates, without re-evaluating the condition.
+	## Injected around ternary operands and boolean-operator sites/right
+	## operands so each arm is measured exactly when it evaluates, without
+	## re-evaluating the condition.
 	hit(file_id, line_id)
 	return value
 
 
+func hit_bool(file_id: int, true_id: int, false_id: int, value: Variant) -> Variant:
+	## Record exactly one boolean-arm hit and pass the value through.
+	##
+	## Injected around assert conditions: the condition's truth decides
+	## which of the two arms is recorded, and the value continues into
+	## the assert itself. One wrapper call therefore records exactly one
+	## of assert_true / assert_false per evaluation.
+	hit(file_id, true_id if value else false_id)
+	return value
+
+
 func get_hits() -> Dictionary:
 	return _hits
 
@@ -100,6 +135,7 @@ func get_omitted() -> Array:
 
 func reset() -> void:
 	_hits.clear()
+	_derived.clear()
 	_omitted.clear()
 
 
@@ -194,6 +230,7 @@ func _build_coverage_json(hits: Dictionary, omitted: Array = []) -> Dictionary:
 	# Matches the post-run hook output contract exactly so every
 	# reporter consumes playtest sessions unchanged.
 	var files: Array = []
+	_derive_short_hits(hits)
 	for file_id in hits:
 		var file_hits: Dictionary = hits[file_id]
 		var hits_dict: Dictionary = {}
@@ -318,9 +355,57 @@ func _instrument_file(file_entry: Dictionary) -> bool:
 	# change to any percentage.
 	if not _hits.has(file_id):
 		_hits[file_id] = {}
+	_derive_short_arms(file_id, lines)
 	return true
 
 
+func _derive_short_arms(file_id: int, lines: Array) -> void:
+	## Pair each ``<op>_short`` point with its operator's site and right
+	## point ids so coverage aggregation can derive short-circuit hits.
+	##
+	## Short-circuit arms have no span of their own: the collector records
+	## the site whenever the whole expression evaluates and the right arm
+	## whenever the right operand evaluates, so ``short = site - right``
+	## counts the evaluations the operator skipped. The plan emits each
+	## right operand immediately followed by its short arm, so pairing by
+	## most recent same-operator right is exact, including for chains.
+	var site_by_operator: Dictionary = {}
+	var last_right: Dictionary = {}
+	var pairs: Dictionary = {}
+	for entry in lines:
+		var branch_type := str(entry.get("branch_type", ""))
+		if branch_type.ends_with("_site"):
+			site_by_operator[branch_type.trim_suffix("_site")] = int(entry["id"])
+		elif branch_type.ends_with("_right"):
+			last_right[branch_type.trim_suffix("_right")] = int(entry["id"])
+		elif branch_type.ends_with("_short"):
+			var operator := branch_type.trim_suffix("_short")
+			if site_by_operator.has(operator) and last_right.has(operator):
+				pairs[int(entry["id"])] = [
+					site_by_operator[operator],
+					last_right[operator],
+				]
+	if not pairs.is_empty():
+		_derived[file_id] = pairs
+
+
+func _derive_short_hits(hits: Dictionary) -> void:
+	## Fold derived short-circuit arm hits into the recorded hit counts.
+	##
+	## ``short = site - right`` clamped at zero: a negative result would
+	## mean the wrap double-fired, which is a defect, not a measurement.
+	for file_id in _derived:
+		if not hits.has(file_id):
+			continue
+		var pairs: Dictionary = _derived[file_id]
+		for short_id in pairs:
+			var site_hits := int(hits[file_id].get(pairs[short_id][0], 0))
+			var right_hits := int(hits[file_id].get(pairs[short_id][1], 0))
+			var short_hits := maxi(0, site_hits - right_hits)
+			if short_hits > 0:
+				hits[file_id][short_id] = short_hits
+
+
 static func _extract_indent(line: String) -> String:
 	var indent: String = ""
 	for c in line:
@@ -345,17 +430,22 @@ static func _detect_body_indent(source_lines: PackedStringArray, pattern_index:
 
 
 static func _inject_trackers(source: String, file_id: int, lines: Array) -> String:
-	var wrapped := _wrap_ternary_operands(source, file_id, lines)
+	var wrapped := _wrap_expression_operands(source, file_id, lines)
 	var source_lines: PackedStringArray = wrapped.split("\n")
 	var sorted_lines: Array = lines.duplicate(true)
 	sorted_lines.sort_custom(func(a, b): return int(a["line"]) > int(b["line"]))
 	for entry in sorted_lines:
-		# Ternary arms are instrumented by wrapping their operand text
-		# (see _wrap_ternary_operands); a line-inserted hit() on the
-		# shared anchor line fires both arms in lockstep and can never
-		# report an uncovered arm.
+		# Ternary and boolean-operator arms are instrumented by wrapping
+		# their operand text (see _wrap_expression_operands); a
+		# line-inserted hit() on the shared anchor line fires both arms
+		# in lockstep and can never report an uncovered arm.
 		if entry.get("operand_span") != null:
 			continue
+		# Short-circuit arms are derived at aggregation as site - right; a
+		# line-inserted hit() would fire whenever the statement runs
+		# rather than when the operator skipped its right operand.
+		if str(entry.get("branch_type", "")).ends_with("_short"):
+			continue
 		var target_line_num: int = int(entry["line"])
 		var line_id: int = int(entry["id"])
 		var target_index: int = target_line_num - 1
@@ -398,26 +488,60 @@ static func _offset_of(source: String, line: int, col: int) -> int:
 	return target
 
 
-static func _wrap_ternary_operands(source: String, file_id: int, lines: Array) -> String:
-	## Replace each ternary operand with a value-preserving tracker call.
+static func _wrap_expression_operands(source: String, file_id: int, lines: Array) -> String:
+	## Replace each tracked operand with a value-preserving tracker call.
+	##
+	## The plan records the source span of every ternary arm operand and
+	## boolean-operator site/right operand. Wrapping the operand records
+	## the arm's hit exactly when that operand evaluates, keeping values,
+	## evaluation order, and single evaluation intact. Line numbers are
+	## unchanged: a wrapper never adds or removes a newline, so the
+	## line-based insertion that follows stays valid.
 	##
-	## The plan records the source span of every ternary arm operand.
-	## Wrapping the operand records the arm's hit exactly when that arm
-	## evaluates, keeping values, evaluation order, and single evaluation
-	## intact. Line numbers are unchanged: a wrapper never adds or removes
-	## a newline, so the line-based insertion that follows stays valid.
+	## Assert conditions carry two arm ids (assert_true/assert_false)
+	## over one shared span: the pair becomes a single value-aware
+	## hit_bool wrap that records exactly one arm per evaluation.
 	var spans: Array = []
+	var assert_pairs: Dictionary = {}
 	for entry in lines:
+		var branch_type := str(entry.get("branch_type", ""))
 		var span: Variant = entry.get("operand_span")
 		if span == null:
 			continue
+		if branch_type == "assert_true" or branch_type == "assert_false":
+			var key := str(span)
+			if not assert_pairs.has(key):
+				assert_pairs[key] = {
+					"span": span,
+					"assert_true": -1,
+					"assert_false": -1,
+				}
+			assert_pairs[key][branch_type] = int(entry["id"])
+			continue
 		var start := _offset_of(source, int(span[0]), int(span[1]))
 		var end := _offset_of(source, int(span[2]), int(span[3]))
 		if start < 0 or end < 0 or start >= end or end > source.length():
 			# Fail open: an unusable span leaves the arm uninstrumented
 			# rather than corrupting the source.
 			continue
-		spans.append({"start": start, "end": end, "id": int(entry["id"])})
+		spans.append({"start": start, "end": end, "kind": "ret", "id": int(entry["id"])})
+	for key in assert_pairs:
+		var pair: Dictionary = assert_pairs[key]
+		if int(pair["assert_true"]) < 0 or int(pair["assert_false"]) < 0:
+			# Fail open: an incomplete pair leaves the assert uninstrumented.
+			continue
+		var span: Array = pair["span"]
+		var start := _offset_of(source, int(span[0]), int(span[1]))
+		var end := _offset_of(source, int(span[2]), int(span[3]))
+		if start < 0 or end < 0 or start >= end or end > source.length():
+			continue
+		spans.append({
+			"start": start,
+			"end": end,
+			"kind": "bool",
+			"true_id": int(pair["assert_true"]),
+			"false_id": int(pair["assert_false"]),
+		})
 	if spans.is_empty():
 		return source
 	spans.sort_custom(func(a, b):
@@ -460,12 +584,21 @@ static func _wrap_spans(
 			j += 1
 		result += source.substr(cursor, start - cursor)
 		var operand := _wrap_spans(source, file_id, children, 0, start, end)
-		result += "%s.hit_ret(%d, %d, %s)" % [
-			TRACKER_NAME,
-			file_id,
-			int(span["id"]),
-			operand,
-		]
+		if str(span.get("kind", "ret")) == "bool":
+			result += "%s.hit_bool(%d, %d, %d, %s)" % [
+				TRACKER_NAME,
+				file_id,
+				int(span["true_id"]),
+				int(span["false_id"]),
+				operand,
+			]
+		else:
+			result += "%s.hit_ret(%d, %d, %s)" % [
+				TRACKER_NAME,
+				file_id,
+				int(span["id"]),
+				operand,
+			]
 		cursor = end
 		i = j
 	result += source.substr(cursor, to - cursor)
@@ -562,7 +695,11 @@ func _validate_file_entry(file_entry: Variant) -> bool:
 		)
 		return false
 
-	for line_entry in file_entry["lines"]:
+	return _validate_line_entries(file_entry["lines"])
+
+
+func _validate_line_entries(lines: Array) -> bool:
+	for line_entry in lines:
 		if not (line_entry is Dictionary) or not line_entry.has("line") or not line_entry.has("id"):
 			_log_error(
 				"Invalid coverage plan structure.",
@@ -570,10 +707,36 @@ func _validate_file_entry(file_entry: Variant) -> bool:
 				"Ensure each line entry has 'line' and 'id' fields."
 			)
 			return false
+		if not _validate_branch_type(line_entry):
+			return false
 
 	return true
 
 
+func _validate_branch_type(line_entry: Dictionary) -> bool:
+	## Reject plans carrying branch types this collector cannot measure.
+	##
+	## Loud-failure handshake: instrumenting an unknown branch type would
+	## silently mis-measure the unknown arms, so the plan is rejected
+	## instead of reporting numbers that look trustworthy but are not.
+	var branch_type: Variant = line_entry.get("branch_type")
+	if branch_type == null:
+		return true
+	var type_name := str(branch_type)
+	if type_name.is_empty() or type_name in KNOWN_BRANCH_TYPES:
+		return true
+	_log_error(
+		"Unsupported coverage plan.",
+		(
+			"Branch type '%s' (point id %s) is not implemented by this "
+			+ "collector."
+		) % [type_name, str(line_entry.get("id", "?"))],
+		"Update the gd-tools addons so the collector matches the plan "
+		+ "version."
+	)
+	return false
+
+
 func _log_error(what: String, cause: String, fix: String) -> void:
 	push_error(
 		"[gd-tools] [Error] " + what + "\n\n" + "  Cause: " + cause + "\n" + "  Fix:   " + fix