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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gd-tools-cli
-Version: 0.5.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
@@ -63,9 +63,9 @@ coverage for GDScript that no existing tool provides.
 Tests are written against `GdToolsTest`, a native GDScript base class that runs
 inside your Godot project, so a test can touch the real scene tree, await real
 signals, and assert on real engine objects without leaving the engine. Existing
-suites that `extend GutTest` run through the built-in compatibility bridge --
-no GUT addon required -- while projects migrate. The bridge is deprecated as of
-v0.5.0 and will be removed in v0.6.0.
+suites that `extend GutTest` are no longer runnable -- the GUT compatibility
+bridge was removed in v0.6.0; run `gd-tools migrate` to move them onto
+`GdToolsTest`.
 
 One install, one config, one mental model.
 
@@ -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. |
-| **Zero-friction bootstrap** | `gd-tools init` gets a project fully set up in under a minute -- native test and coverage addons deployed, configs generated. Existing `GutTest` suites run through the built-in compatibility bridge with no addon install. |
-| **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. |
-| **CI/CD friendly** | Exit codes, `--check` flags, machine-readable output (JSON, JUnit XML, LCOV, Cobertura), no interactive prompts in CI mode. |
+| **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. |
+| **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
@@ -119,11 +120,11 @@ directory. The command is idempotent -- safe to re-run. If you've modified
 coverage addon files, they are automatically backed up to
 `addons/gd-tools-coverage/.backups/` before being overwritten.
 
-The legacy GUT runtime has been replaced by the built-in compatibility bridge:
-suites extending `GutTest` run on the native runtime with no GUT addon
-installed. The bridge is deprecated as of v0.5.0 and will be removed in
-v0.6.0. See the [migration guide](./docs/gut-migration.md) for the
-supported subset and the steps to move fully onto `GdToolsTest`.
+The GUT compatibility bridge was removed in v0.6.0: suites extending `GutTest`
+are no longer runnable -- `gd-tools test` rejects them with exit 2 and
+migration guidance. Run `gd-tools migrate` and see the
+[migration guide](./docs/gut-migration.md) for the steps to move fully onto
+`GdToolsTest`.
 
 A test suite is any class extending `GdToolsTest`:
 
@@ -139,14 +140,14 @@ func test_health_starts_at_full() -> void:
 | Command | Description |
 |---------|-------------|
 | `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, bridge-eligible GUT suites, coverage addon, tooling. |
-| `gd-tools test` | Run tests with optional coverage, thresholds, and JUnit XML output. Suites extending `GdToolsTest` and `GutTest` are detected and routed automatically (`GutTest` suites run through the compatibility bridge). Accepts optional path arguments to override configured test directories. `--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 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 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`, and `diff` (baseline comparison for CI regression gates). |
-| `gd-tools config` | Configuration management -- `show` (display resolved config), `validate` (check config validity). |
-| `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 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) in a table or JSON. |
 | `gd-tools completion` | Generate shell completion scripts for bash, zsh, fish, or PowerShell. |
 
 ### Selecting and Filtering Tests
@@ -157,10 +158,47 @@ gd-tools test --suite PlayerTests          # one suite, by class name
 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
 ```
 
 `--tag` is repeatable, and `--test-timeout` (per test) is separate from
-`--timeout` (per suite process).
+`--timeout` (per suite process). `--parallel` dispatches suites to a bounded
+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
+`tests/test_enemy.gd` or `tests/enemy_test.gd`. A change that maps to no
+suite (e.g. `project.godot` or a scene file) falls back to the full suite
+with an explicit notice, so the selection is safe for CI. The summary line
+reports how many suites were selected; per-file mapping detail prints under
+`--verbose`. Add `--base <ref>` to diff committed changes from
+`merge-base(<ref>, HEAD)` instead of the working tree — the form to use on
+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.
+
+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
+the Godot version is unchanged. The integration preflight is likewise cached
+under `.gd-tools/native/preflight-cache/` and skipped when the suites, test
+files, `project.godot`, Godot version, and bundled addons are unchanged. Cache
+hit/miss reasons are reported under `--verbose`; `--no-cache` bypasses the
+import, preflight, and coverage plan caches, and `gd-tools clean --cache`
+removes the cache directory.
 
 Each run writes a machine-readable artifact index under
 `.gd-tools/artifacts/<run_id>/`, listing the manifest, result, event stream,
@@ -182,49 +220,33 @@ suite by convention — `src/enemy.gd` re-runs `tests/test_enemy.gd` or
 `tests/enemy_test.gd` — with a full-suite fallback (announced explicitly)
 when no suite matches. Rapid successive saves are coalesced into a single
 re-run, and a save during a running suite queues exactly one follow-up run.
+The same file→suite mapping powers the non-interactive `gd-tools test
+--changed` selection (see [Selecting and Filtering
+Tests](#selecting-and-filtering-tests)).
 
 - Native runtime only: the removed legacy GUT runtime (`--runtime gut`) is
-  rejected with exit 2; `GutTest` suites run through the compatibility bridge.
+  rejected with exit 2; `GutTest` suites must be migrated (`gd-tools migrate`).
 - Interactive only: `--watch` combined with `CI=true` exits 2.
 - The terminal is cleared between runs; the banner shows how many files are
-  watched, and `Ctrl+C` always exits 0.
+  watched. While idle, `Ctrl+C` exits 0; interrupting an in-flight run kills
+  its Godot processes and exits 130.
 - Positional path arguments are not supported with `--watch`; the watched
   scope is the project root minus standard excludes (`.godot/`, `.gd-tools/`,
   `.git/`, and the gd-tools addons).
 
-### Native Runtime vs. GUT Compatibility Bridge
-
-The native runtime is the default and the forward path. Suites extending
-`GutTest` run through the built-in compatibility bridge on the same native
-runner; the bridge is deprecated as of v0.5.0 and will be removed in v0.6.0.
-
-| Capability | Native runtime (`GdToolsTest`) | Bridge (`GutTest`) |
-|------------|----------------|--------------|
-| Base class | `GdToolsTest` extends `Node` | `GutTest`, provided by gd-tools (no GUT addon) |
-| Discovery | `test_*` methods, by directory or exact file selector | Same; routed automatically per file |
-| Lifecycle hooks | `before_all`, `after_all`, `before_each`, `after_each` | Same, plus `prerun_setup` and `postrun_teardown` |
-| Assertions | Full native assertion set plus `fail()`, `skip_test()`, `pending_test()` | Documented GUT core subset -- unsupported constructs fail at preflight |
-| Async waits | `wait_process_frame`, `wait_physics_frames`, `wait_seconds`, `wait_for_signal(signal, timeout)` | GUT helper family, incl. `wait_until`, `wait_while`, `yield_*` |
-| Tags | Class-level tags, filtered with `--tag` | Same |
-| Test selectors | `--suite`, `--test`, `--test-timeout` | Same |
-| Scene and resource integration | `const INTEGRATION` plus `GdToolsTestContext` for scene root, node lookup, named resources, and bounded signal waits | Not wired into the bridge shim |
-| Retries | Configurable per test (`[test].retries`) | Same |
-| Line and branch coverage | Yes | Yes |
-| JUnit XML output | Yes | Yes |
-| Mocking and stubbing | `double()`, `partial_double()`, `stub()` (`.to_return`/`.to_call_super`), `assert_called*` family | Same -- inherited from `GdToolsTest` with identical semantics |
-| Parameterized tests | `parameterize()` in `before_all`, values injected via `use_parameters` | Not supported -- preflight rejects `parameterize()` |
-| Skipping a test at runtime | `skip_test()` and `pending_test()` | Yes |
-| Parallel execution | Not yet -- suites run sequentially | Same |
-| Editor plugin | Not yet | Not applicable |
-
-**Known limitations.** Parameterized tests are native-only -- the bridge
-deliberately refuses `parameterize()` at preflight rather than mis-running
-them, so such suites must migrate to `GdToolsTest`. Suites run sequentially;
-parallel execution is planned but not yet available. The bridge itself is
-deprecated as of v0.5.0 and will be removed in v0.6.0. See the
-[migration guide](./docs/gut-migration.md) for the bridge's supported subset,
-[User Guide](./docs/USER_GUIDE.md#34-test) for the full flag reference, and
-[Roadmap](./docs/ROADMAP.md#8-temporary-native-test-runtime-migration-roadmap)
+### Migrating Legacy GUT Suites
+
+The GUT compatibility bridge was removed in v0.6.0; the native runtime
+(`GdToolsTest`) is the only supported runtime. Suites extending `GutTest` are
+rejected by `gd-tools test` with exit 2 and migration guidance, and
+`--runtime gut` is rejected the same way. Run `gd-tools migrate` and see the
+[migration guide](./docs/gut-migration.md) to move legacy suites onto the
+native runtime.
+
+**Known limitations.** Parallel execution is opt-in and off by default
+(`--parallel N` / `[test].parallel`); suites run sequentially without it. See
+the [User Guide](./docs/USER_GUIDE.md#34-test) for the full flag reference and
+[Roadmap](./docs/ROADMAP.md#native-runtime-transition-completed-foundation)
 for what is planned.
 
 ### Verbosity Control
@@ -306,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
@@ -320,10 +376,10 @@ binary = ""  # Optional -- auto-detected if unset
 test_dirs = ["test", "tests"]
 prefix = "test_"
 suffix = ".gd"
-gutconfig = ".gutconfig.json"  # legacy; not read by the native runtime or the bridge
 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
+# parallel = 4            # opt-in parallel suite execution (1-32; unset runs sequentially)
 tags = []                 # native suite tag filters
 
 [lint]
@@ -341,10 +397,36 @@ exclude = ["addons", ".godot", ".gd-tools", ".git"]
 test_dirs = ["test", "tests"]
 ```
 
+### Editor Autocomplete & Validation
+
+`gd-tools` publishes a JSON Schema for `gd-tools.toml` at
+[`docs/gd-tools.schema.json`](./docs/gd-tools.schema.json). Add a
+`"$schema"` key to your config to enable autocomplete and inline
+validation in editors that support TOML schemas:
+
+```toml
+"$schema" = "https://raw.githubusercontent.com/mansyar/gd-tools/main/docs/gd-tools.schema.json"
+```
+
+The key is accepted and ignored by the CLI — it carries no runtime
+meaning.
+
+- **VS Code** (with [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)):
+  the `"$schema"` key above is picked up automatically. Alternatively,
+  associate the schema by filename in your settings:
+  `"even-better-toml.schema.associations": {"gd-tools.toml": "https://raw.githubusercontent.com/mansyar/gd-tools/main/docs/gd-tools.schema.json"}`
+- **taplo** (CLI / LSP): the `"$schema"` key works out of the box, or
+  add a `schema` entry to your `taplo.toml` pointing at the URL above.
+
+The schema is regenerated with
+`gd-tools config schema --output docs/gd-tools.schema.json`;
+a unit test keeps the checked-in snapshot in sync with the installed
+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 |
 |----------|-------------|
@@ -355,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
@@ -385,20 +467,18 @@ 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
-  core API the built-in compatibility bridge reproduces while projects
-  migrate to the native runtime.
+  core API informed the native runtime's assertion surface.
 - **[gdtoolkit](https://github.com/Scony/godot-gdscript-toolkit)** by
   [Scony](https://github.com/Scony): provides `gdlint` and `gdformat`, which
   `gd-tools lint` and `gd-tools format` wrap.