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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gd-tools-cli
-Version: 0.6.0
+Version: 0.7.0
 Summary: A modern development workflow CLI for GDScript projects in Godot 4.5+
 Author-email: mansyar <m.ansyarafi@gmail.com>
 License: MIT
@@ -74,10 +74,11 @@ One install, one config, one mental model.
 | Feature | Description |
 |---------|-------------|
 | **Unified workflow** | One install, one config (`gd-tools.toml`), one mental model for test, lint, format, and coverage. Consistent terminal output with colored markers and summary footers across all commands. |
-| **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. |
+| **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, and Cobertura reports that integrate with CI and code review tools. `# gd-tools: no cover` annotations exclude debug-only code from the numbers. `coverage run` collects coverage during manual playtest sessions, not just automated tests. |
-| **CI/CD friendly** | Exit codes, `--check` flags, machine-readable output (JSON, JUnit XML, LCOV, Cobertura), no interactive prompts in CI mode. |
+| **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. |
+| **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. |
 
 ## 3. Installation
@@ -140,13 +141,13 @@ 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. 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. 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 or JSON output. Accepts one or more file or directory paths. |
+| `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 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, and GUT when installed) in a table or JSON. |
+| `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. |
 
 ### Selecting and Filtering Tests
@@ -158,6 +159,7 @@ gd-tools test --test test_takes_damage     # one test method
 gd-tools test --tag smoke                  # suites with that class-level tag
 gd-tools test --test-timeout 30            # per-test timeout, in seconds
 gd-tools test --parallel 4                 # run suites with 4 concurrent workers
+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
 ```
@@ -168,6 +170,13 @@ worker pool (1-32 workers; bare `--parallel` means 4) while keeping results,
 JUnit XML, and merged coverage identical to a sequential run. Persist the
 choice with `parallel = 4` under `[test]` in `gd-tools.toml`.
 
+`--durations N` prints a "Slowest Tests" table after the run, sorted
+slowest-first, covering pass, fail, and skip outcomes. Bare `--durations`
+means 10; `--durations 0` lists every executed test (pytest parity). Persist
+the choice with `durations = 10` under `[test]` in `gd-tools.toml`; the flag
+overrides the config for one invocation. The table renders identically under
+`--watch` re-runs and `--parallel` runs.
+
 `--changed` selects suites from git instead of running everything: uncommitted
 changes (staged, unstaged, and untracked) map to suites by the same
 file→suite convention as `--watch` — `src/enemy.gd` selects
@@ -319,7 +328,41 @@ eval "$(gd-tools)"
 See the [User Guide](./docs/USER_GUIDE.md) for detailed per-shell
 instructions.
 
-## 7. Configuration
+## 7. Pre-commit Hooks
+
+Wire gd-tools into the [pre-commit](https://pre-commit.com) framework so
+every commit runs your format check, lint, and (optionally) your test suite:
+
+```bash
+gd-tools install-hooks
+```
+
+The command generates `.pre-commit-hooks.yaml` and merges a `repos: local:`
+entry into `.pre-commit-config.yaml`. Existing hooks — including your own —
+are preserved; re-runs update only the gd-tools entries in place.
+
+Interactive by default: confirm each hook (`format`, `lint`, `test`). For
+scripted or CI use, pass flags instead:
+
+```bash
+gd-tools install-hooks --non-interactive      # format + lint (defaults)
+gd-tools install-hooks --all                  # format + lint + test
+gd-tools install-hooks --hooks format,lint    # explicit selection
+```
+
+| Flag | Behavior |
+|---|---|
+| `--all` | Enable every hook (format, lint, test). |
+| `--hooks HOOKS` | Comma-separated selection, e.g. `--hooks format,lint`. |
+| `--non-interactive` | Never prompt; use defaults or explicit flags. |
+
+Exit codes follow the gd-tools convention: `0` installed, `1` nothing to do,
+`2` config/environment error.
+
+See the [User Guide](./docs/USER_GUIDE.md#8-pre-commit-hooks) for the
+generated file contents and per-hook details.
+
+## 8. Configuration
 
 `gd-tools` uses a single `gd-tools.toml` file as the source of truth for
 all tool configuration. `gd-tools init` generates this file with sensible
@@ -333,7 +376,6 @@ binary = ""  # Optional -- auto-detected if unset
 test_dirs = ["test", "tests"]
 prefix = "test_"
 suffix = ".gd"
-gutconfig = ".gutconfig.json"  # legacy; not read by any runtime
 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
@@ -384,7 +426,7 @@ version's config model.
 See the [User Guide](./docs/USER_GUIDE.md) for a full configuration reference
 with all keys, defaults, and examples.
 
-## 8. Documentation
+## 9. Documentation
 
 | Document | Description |
 |----------|-------------|
@@ -395,7 +437,7 @@ with all keys, defaults, and examples.
 | [Roadmap](./docs/ROADMAP.md) | Release phases and milestones. |
 | [Testing Strategy](./docs/TESTING_STRATEGY.md) | Test pyramid, coverage targets, and CI integration. |
 
-## 9. Development
+## 10. Development
 
 ```bash
 # Clone and install in editable mode with dev dependencies
@@ -425,15 +467,14 @@ See [Testing Strategy](./docs/TESTING_STRATEGY.md) for the full testing
 guide and [Contributing Guide](./docs/CONTRIBUTING.md) for development
 setup details.
 
-## 10. License
+## 11. License
 
 MIT
 
-## 11. Acknowledgements
+## 12. Acknowledgements
 
-`gd-tools` stands on the shoulders of two excellent community tools. It
-wraps them; it does not replace them. Full credit to their authors for the
-hard parts.
+`gd-tools` stands on the shoulders of excellent community tools, past and
+present. Full credit to their authors for the hard parts.
 
 - **[GUT (Godot Unit Test)](https://github.com/bitwes/Gut)** by
   [bitwes](https://github.com/bitwes): the GDScript test framework whose

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

@@ -33,10 +33,11 @@ One install, one config, one mental model.
 | Feature | Description |
 |---------|-------------|
 | **Unified workflow** | One install, one config (`gd-tools.toml`), one mental model for test, lint, format, and coverage. Consistent terminal output with colored markers and summary footers across all commands. |
-| **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. |
+| **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, and Cobertura reports that integrate with CI and code review tools. `# gd-tools: no cover` annotations exclude debug-only code from the numbers. `coverage run` collects coverage during manual playtest sessions, not just automated tests. |
-| **CI/CD friendly** | Exit codes, `--check` flags, machine-readable output (JSON, JUnit XML, LCOV, Cobertura), no interactive prompts in CI mode. |
+| **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. |
+| **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. |
 
 ## 3. Installation
@@ -99,13 +100,13 @@ 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. 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. 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 or JSON output. Accepts one or more file or directory paths. |
+| `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 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, and GUT when installed) in a table or JSON. |
+| `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. |
 
 ### Selecting and Filtering Tests
@@ -117,6 +118,7 @@ gd-tools test --test test_takes_damage     # one test method
 gd-tools test --tag smoke                  # suites with that class-level tag
 gd-tools test --test-timeout 30            # per-test timeout, in seconds
 gd-tools test --parallel 4                 # run suites with 4 concurrent workers
+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
 ```
@@ -127,6 +129,13 @@ worker pool (1-32 workers; bare `--parallel` means 4) while keeping results,
 JUnit XML, and merged coverage identical to a sequential run. Persist the
 choice with `parallel = 4` under `[test]` in `gd-tools.toml`.
 
+`--durations N` prints a "Slowest Tests" table after the run, sorted
+slowest-first, covering pass, fail, and skip outcomes. Bare `--durations`
+means 10; `--durations 0` lists every executed test (pytest parity). Persist
+the choice with `durations = 10` under `[test]` in `gd-tools.toml`; the flag
+overrides the config for one invocation. The table renders identically under
+`--watch` re-runs and `--parallel` runs.
+
 `--changed` selects suites from git instead of running everything: uncommitted
 changes (staged, unstaged, and untracked) map to suites by the same
 file→suite convention as `--watch` — `src/enemy.gd` selects
@@ -278,7 +287,41 @@ eval "$(gd-tools)"
 See the [User Guide](./docs/USER_GUIDE.md) for detailed per-shell
 instructions.
 
-## 7. Configuration
+## 7. Pre-commit Hooks
+
+Wire gd-tools into the [pre-commit](https://pre-commit.com) framework so
+every commit runs your format check, lint, and (optionally) your test suite:
+
+```bash
+gd-tools install-hooks
+```
+
+The command generates `.pre-commit-hooks.yaml` and merges a `repos: local:`
+entry into `.pre-commit-config.yaml`. Existing hooks — including your own —
+are preserved; re-runs update only the gd-tools entries in place.
+
+Interactive by default: confirm each hook (`format`, `lint`, `test`). For
+scripted or CI use, pass flags instead:
+
+```bash
+gd-tools install-hooks --non-interactive      # format + lint (defaults)
+gd-tools install-hooks --all                  # format + lint + test
+gd-tools install-hooks --hooks format,lint    # explicit selection
+```
+
+| Flag | Behavior |
+|---|---|
+| `--all` | Enable every hook (format, lint, test). |
+| `--hooks HOOKS` | Comma-separated selection, e.g. `--hooks format,lint`. |
+| `--non-interactive` | Never prompt; use defaults or explicit flags. |
+
+Exit codes follow the gd-tools convention: `0` installed, `1` nothing to do,
+`2` config/environment error.
+
+See the [User Guide](./docs/USER_GUIDE.md#8-pre-commit-hooks) for the
+generated file contents and per-hook details.
+
+## 8. Configuration
 
 `gd-tools` uses a single `gd-tools.toml` file as the source of truth for
 all tool configuration. `gd-tools init` generates this file with sensible
@@ -292,7 +335,6 @@ binary = ""  # Optional -- auto-detected if unset
 test_dirs = ["test", "tests"]
 prefix = "test_"
 suffix = ".gd"
-gutconfig = ".gutconfig.json"  # legacy; not read by any runtime
 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
@@ -343,7 +385,7 @@ version's config model.
 See the [User Guide](./docs/USER_GUIDE.md) for a full configuration reference
 with all keys, defaults, and examples.
 
-## 8. Documentation
+## 9. Documentation
 
 | Document | Description |
 |----------|-------------|
@@ -354,7 +396,7 @@ with all keys, defaults, and examples.
 | [Roadmap](./docs/ROADMAP.md) | Release phases and milestones. |
 | [Testing Strategy](./docs/TESTING_STRATEGY.md) | Test pyramid, coverage targets, and CI integration. |
 
-## 9. Development
+## 10. Development
 
 ```bash
 # Clone and install in editable mode with dev dependencies
@@ -384,15 +426,14 @@ See [Testing Strategy](./docs/TESTING_STRATEGY.md) for the full testing
 guide and [Contributing Guide](./docs/CONTRIBUTING.md) for development
 setup details.
 
-## 10. License
+## 11. License
 
 MIT
 
-## 11. Acknowledgements
+## 12. Acknowledgements
 
-`gd-tools` stands on the shoulders of two excellent community tools. It
-wraps them; it does not replace them. Full credit to their authors for the
-hard parts.
+`gd-tools` stands on the shoulders of excellent community tools, past and
+present. Full credit to their authors for the hard parts.
 
 - **[GUT (Godot Unit Test)](https://github.com/bitwes/Gut)** by
   [bitwes](https://github.com/bitwes): the GDScript test framework whose

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gd-tools-cli"
-version = "0.6.0"
+version = "0.7.0"
 description = "A modern development workflow CLI for GDScript projects in Godot 4.5+"
 readme = "README.md"
 license = {text = "MIT"}
@@ -105,7 +105,7 @@ target-version = ["py310"]
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.6.0"
+version = "0.7.0"
 version_files = ["pyproject.toml:version"]
 changelog_file = "CHANGELOG.md"
 tag_format = "v$version"

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

@@ -80,6 +80,15 @@ func hit(file_id: int, line_id: int) -> void:
 	_hits[file_id][line_id] += 1
 
 
+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.
+	hit(file_id, line_id)
+	return value
+
+
 func get_hits() -> Dictionary:
 	return _hits
 
@@ -336,10 +345,17 @@ static func _detect_body_indent(source_lines: PackedStringArray, pattern_index:
 
 
 static func _inject_trackers(source: String, file_id: int, lines: Array) -> String:
-	var source_lines: PackedStringArray = source.split("\n")
+	var wrapped := _wrap_ternary_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.
+		if entry.get("operand_span") != null:
+			continue
 		var target_line_num: int = int(entry["line"])
 		var line_id: int = int(entry["id"])
 		var target_index: int = target_line_num - 1
@@ -368,6 +384,94 @@ static func _inject_trackers(source: String, file_id: int, lines: Array) -> Stri
 	return "\n".join(source_lines)
 
 
+static func _offset_of(source: String, line: int, col: int) -> int:
+	## Absolute character offset of a 1-based line/column position, or -1.
+	var source_lines := source.split("\n")
+	if line < 1 or line > source_lines.size() or col < 1:
+		return -1
+	var offset := 0
+	for i in range(line - 1):
+		offset += source_lines[i].length() + 1
+	var target := offset + (col - 1)
+	if target > source.length():
+		return -1
+	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.
+	##
+	## 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.
+	var spans: Array = []
+	for entry in lines:
+		var span: Variant = entry.get("operand_span")
+		if span == null:
+			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"])})
+	if spans.is_empty():
+		return source
+	spans.sort_custom(func(a, b):
+		if int(a["start"]) != int(b["start"]):
+			return int(a["start"]) < int(b["start"])
+		return int(a["end"]) > int(b["end"])
+	)
+	return _wrap_spans(source, file_id, spans, 0, 0, source.length())
+
+
+static func _wrap_spans(
+		source: String,
+		file_id: int,
+		spans: Array,
+		index: int,
+		from: int,
+		to: int
+) -> String:
+	## Emit source[from:to] with spans[index..] wrapped in place.
+	##
+	## Spans are sorted ascending by start (outer span before inner on a
+	## tie), so a span's children are the following entries fully contained
+	## in it; they are wrapped recursively inside the operand text.
+	var result := ""
+	var cursor := from
+	var i := index
+	while i < spans.size():
+		var span: Dictionary = spans[i]
+		var start := int(span["start"])
+		var end := int(span["end"])
+		if start >= to or end > to:
+			break
+		if start < cursor:
+			i += 1
+			continue
+		var children: Array = []
+		var j := i + 1
+		while j < spans.size() and int(spans[j]["end"]) <= end:
+			children.append(spans[j])
+			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,
+		]
+		cursor = end
+		i = j
+	result += source.substr(cursor, to - cursor)
+	return result
+
+
 func _load_plan(path: String) -> Dictionary:
 	if not FileAccess.file_exists(path):
 		_log_error(

{gd_tools_cli-0.6.0 → gd_tools_cli-0.7.0}/src/gd_tools/addons/gd-tools-test/gd_tools_mock.gd

@@ -71,14 +71,35 @@ func calls_super(method: String, args: Array) -> bool:
 ##
 ## Unstubbed doubles answer null (GUT semantics); the [method coerce] layer
 ## adapts that to typed returns. A matched stub registered with
-## `to_return()` supplies its value here.
+## `to_return()` supplies its value here; `to_return_seq()` answers with its
+## values in order and repeats the final one once exhausted; `to_fail()`
+## records a failure through the suite's normal failure path at call time
+## and answers null, which [method coerce] adapts to the return type's zero
+## value so the script under test keeps executing.
 func respond(method: String, args: Array) -> Variant:
 	if _suite != null:
 		var entry: Dictionary = _suite._gd_tools_stub_find(
 				_target_id, method, args
 		)
-		if not entry.is_empty() and entry["action"] == "return":
-			return entry["value"]
+		if not entry.is_empty():
+			if entry["action"] == "return":
+				return entry["value"]
+			if entry["action"] == "return_seq":
+				var values: Array = entry["value"]
+				if values.is_empty():
+					return null
+				var position := int(entry.get("position", 0))
+				var answer: Variant = (
+					values[position] if position < values.size() else values.back()
+				)
+				entry["position"] = position + 1
+				return answer
+			if entry["action"] == "fail":
+				_suite._gd_tools_record_failure(
+						"stub",
+						'Stub for "%s" recorded a failure: %s' % [method, entry["value"]]
+				)
+				return null
 	return null
 
 
@@ -214,6 +235,32 @@ class StubBuilder:
 		)
 		return self
 
+	## Answer successive matching calls with the given values in order.
+	##
+	## Once the sequence is exhausted, its final value repeats so late calls
+	## never hand null to the script under test.
+	func to_return_seq(values: Array) -> StubBuilder:
+		if _disabled:
+			return self
+		_suite._gd_tools_stub_register(
+				_double_id, _method, _args, "return_seq", values.duplicate()
+		)
+		return self
+
+	## Record a test failure through the normal failure path every time a
+	## matching call happens.
+	##
+	## GDScript has no exceptions: the call still answers (the return type's
+	## zero value after [method coerce]) so the script under test keeps
+	## executing and later calls still reach the recorder.
+	func to_fail(message: String) -> StubBuilder:
+		if _disabled:
+			return self
+		_suite._gd_tools_stub_register(
+				_double_id, _method, _args, "fail", message
+		)
+		return self
+
 	## Forward every matching call to the real implementation.
 	func to_call_super() -> StubBuilder:
 		if _disabled:

{gd_tools_cli-0.6.0 → gd_tools_cli-0.7.0}/src/gd_tools/addons/gd-tools-test/gd_tools_native_coverage.gd

@@ -57,6 +57,15 @@ static func hit(file_id: int, line_id: int) -> void:
 	_hits[file_id][line_id] += 1
 
 
+static 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.
+	hit(file_id, line_id)
+	return value
+
+
 static func write() -> bool:
 	## Write collected hits using the existing coverage JSON schema.
 	if not _active or _output_path.is_empty():
@@ -178,10 +187,17 @@ static func _inject_trackers(
 		file_id: int,
 		lines: Array
 ) -> String:
-	var source_lines: PackedStringArray = source.split("\n")
+	var wrapped := _wrap_ternary_operands(source, file_id, lines)
+	var source_lines: PackedStringArray = wrapped.split("\n")
 	var entries: Array = lines.duplicate(true)
 	entries.sort_custom(func(a, b): return int(a["line"]) > int(b["line"]))
 	for entry in entries:
+		# 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.
+		if entry.get("operand_span") != null:
+			continue
 		var target_index := int(entry["line"]) - 1
 		if target_index < 0 or target_index >= source_lines.size():
 			continue
@@ -201,6 +217,97 @@ static func _inject_trackers(
 	return "\n".join(source_lines)
 
 
+static func _offset_of(source: String, line: int, col: int) -> int:
+	## Absolute character offset of a 1-based line/column position, or -1.
+	var source_lines := source.split("\n")
+	if line < 1 or line > source_lines.size() or col < 1:
+		return -1
+	var offset := 0
+	for i in range(line - 1):
+		offset += source_lines[i].length() + 1
+	var target := offset + (col - 1)
+	if target > source.length():
+		return -1
+	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.
+	##
+	## 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.
+	var spans: Array = []
+	for entry in lines:
+		var span: Variant = entry.get("operand_span")
+		if span == null:
+			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"])})
+	if spans.is_empty():
+		return source
+	spans.sort_custom(func(a, b):
+		if int(a["start"]) != int(b["start"]):
+			return int(a["start"]) < int(b["start"])
+		return int(a["end"]) > int(b["end"])
+	)
+	return _wrap_spans(source, file_id, spans, 0, 0, source.length())
+
+
+static func _wrap_spans(
+		source: String,
+		file_id: int,
+		spans: Array,
+		index: int,
+		from: int,
+		to: int
+) -> String:
+	## Emit source[from:to] with spans[index..] wrapped in place.
+	##
+	## Spans are sorted ascending by start (outer span before inner on a
+	## tie), so a span's children are the following entries fully contained
+	## in it; they are wrapped recursively inside the operand text.
+	var result := ""
+	var cursor := from
+	var i := index
+	while i < spans.size():
+		var span: Dictionary = spans[i]
+		var start := int(span["start"])
+		var end := int(span["end"])
+		if start >= to or end > to:
+			break
+		if start < cursor:
+			i += 1
+			continue
+		var children: Array = []
+		var j := i + 1
+		while j < spans.size() and int(spans[j]["end"]) <= end:
+			children.append(spans[j])
+			j += 1
+		result += source.substr(cursor, start - cursor)
+		var operand := _wrap_spans(source, file_id, children, 0, start, end)
+		result += "GdToolsNativeCoverage.hit_ret(%d, %d, %s)" % [
+			file_id,
+			int(span["id"]),
+			operand,
+		]
+		cursor = end
+		i = j
+	result += source.substr(cursor, to - cursor)
+	return result
+
+
 static func _extract_indent(line: String) -> String:
 	var indent := ""
 	for character in line: