gd-tools-cli 0.1.0__tar.gz

gd_tools_cli-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: gd-tools-cli
+Version: 0.1.0
+Summary: A modern development workflow CLI for GDScript projects in Godot 4.5+
+Author-email: mansyar <m.ansyarafi@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mansyar/gd-tools
+Project-URL: Repository, https://github.com/mansyar/gd-tools
+Project-URL: Documentation, https://github.com/mansyar/gd-tools#readme
+Project-URL: Bug Tracker, https://github.com/mansyar/gd-tools/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: gdtoolkit
+Requires-Dist: click
+Requires-Dist: junitparser
+Requires-Dist: jinja2
+Requires-Dist: rich
+Requires-Dist: pyyaml
+Requires-Dist: tomli; python_version < "3.11"
+Requires-Dist: tomli_w
+Requires-Dist: pydantic>=2.0
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: black; extra == "dev"
+
+# gd-tools
+
+A modern development workflow CLI for GDScript projects in Godot 4.5+.
+
+[![CI](https://github.com/mansyar/gd-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/mansyar/gd-tools/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/mansyar/gd-tools/branch/main/graph/badge.svg)](https://codecov.io/gh/mansyar/gd-tools)
+[![PyPI version](https://img.shields.io/pypi/v/gd-tools.svg)](https://pypi.org/project/gd-tools/)
+[![Python versions](https://img.shields.io/pypi/pyversions/gd-tools.svg)](https://pypi.org/project/gd-tools/)
+[![Godot version](https://img.shields.io/badge/Godot-4.5%2B-blue.svg)](https://godotengine.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 1. Overview
+
+`gd-tools` brings professional development tooling to GDScript -- test, lint,
+format, and code coverage in a single CLI. It wraps mature, community-trusted
+tools (GUT for testing, gdtoolkit for linting and formatting) and fills the
+remaining gap with a custom hybrid coverage system -- production-quality line
+and branch coverage for GDScript that no existing tool provides.
+
+One install, one config, one mental model.
+
+## 2. Features
+
+| Feature | Description |
+|---------|-------------|
+| **Unified workflow** | One install, one config (`gd-tools.toml`), one mental model for test, lint, format, and coverage. |
+| **Zero-friction bootstrap** | `gd-tools init` gets a project fully set up in under a minute -- GUT installed, coverage addon 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. |
+| **CI/CD friendly** | Exit codes, `--check` flags, machine-readable output (JSON, JUnit XML, LCOV, Cobertura), no interactive prompts in CI mode. |
+| **Standalone compatibility** | gdlint, gdformat, and GUT continue to work if invoked directly. `gd-tools` is a layer on top, not a lock-in. |
+
+## 3. Installation
+
+```bash
+pip install gd-tools-cli
+```
+
+`gd-tools` requires Python 3.10+ and a Godot 4.5+ binary on your system.
+The Godot binary is auto-detected from configuration, environment variables
+(`GODOT_BIN`, `GODOT4_BIN`, `GODOT_PATH`), `PATH`, or common install locations.
+
+## 4. Quick Start
+
+```bash
+# 1. Install
+pip install gd-tools-cli
+
+# 2. Bootstrap your Godot project
+cd your-godot-project
+gd-tools init
+
+# 3. Run your tests
+gd-tools test
+
+# 4. Run tests with coverage
+gd-tools test --coverage --min 80
+```
+
+`gd-tools init` installs GUT, deploys the coverage addon, generates
+`gd-tools.toml`, and creates per-tool config files (`.gutconfig.json`,
+`gdlintrc`, `gdformatrc`). The command is idempotent -- safe to re-run.
+
+## 5. CLI Command Summary
+
+| Command | Description |
+|---------|-------------|
+| `gd-tools init` | Bootstrap a Godot project -- install GUT, deploy coverage addon, generate configs. |
+| `gd-tools doctor` | Diagnose the development environment -- Godot, GUT, coverage addon, tooling. |
+| `gd-tools test` | Run GUT tests with optional coverage, thresholds, JUnit XML output. |
+| `gd-tools lint` | Lint GDScript files using gdlint with text or JSON output. |
+| `gd-tools format` | Format GDScript files using gdformat with check and diff modes. |
+| `gd-tools coverage` | Coverage subcommands -- `report`, `merge`, `show`. |
+
+See the [User Guide](./docs/USER_GUIDE.md) for full command reference,
+flags, examples, and exit codes.
+
+## 6. 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
+defaults.
+
+```toml
+[godot]
+binary = ""  # Optional -- auto-detected if unset
+
+[test]
+test_dirs = ["test", "tests"]
+prefix = "test_"
+suffix = ".gd"
+gutconfig = ".gutconfig.json"
+
+[lint]
+exclude = ["addons", ".godot", ".gd-tools", ".git"]
+
+[format]
+exclude = ["addons", ".godot", ".gd-tools", ".git"]
+
+[coverage]
+enabled = false
+min_percent = 0
+format = "html"  # html, lcov, cobertura, text
+output_dir = ".gd-tools/coverage"
+exclude = ["addons", ".godot", ".gd-tools", ".git"]
+test_dirs = ["test", "tests"]
+```
+
+See the [User Guide](./docs/USER_GUIDE.md) for a full configuration reference
+with all keys, defaults, and examples.
+
+## 7. Documentation
+
+| Document | Description |
+|----------|-------------|
+| [User Guide](./docs/USER_GUIDE.md) | Complete CLI reference -- all commands, flags, examples, and troubleshooting. |
+| [Contributing Guide](./docs/CONTRIBUTING.md) | Development setup, code style, testing requirements, and PR process. |
+| [Architecture](./docs/ARCHITECTURE.md) | Coverage system architecture -- hybrid instrumentation design and data flows. |
+| [Product Requirements](./docs/PRD.md) | Full product specification -- features, design decisions, technical detail. |
+| [Roadmap](./docs/ROADMAP.md) | Release phases and milestones. |
+| [Testing Strategy](./docs/TESTING_STRATEGY.md) | Test pyramid, coverage targets, and CI integration. |
+
+## 8. Development
+
+```bash
+# Clone and install in editable mode with dev dependencies
+git clone https://github.com/mansyar/gd-tools.git
+cd gd-tools
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+Unit tests run without Godot. Integration tests require a Godot 4.5+
+binary -- configure via `.env` (see `.env.example`):
+
+```bash
+cp .env.example .env
+# Edit .env: set GODOT_BIN to your Godot binary path
+
+# Run all tests with coverage
+pytest --cov=src/gd_tools --cov-report=term-missing
+```
+
+See [Testing Strategy](./docs/TESTING_STRATEGY.md) for the full testing
+guide and [Contributing Guide](./docs/CONTRIBUTING.md) for development
+setup details.
+
+## 9. License
+
+MIT

gd_tools_cli-0.1.0/README.md

@@ -0,0 +1,152 @@
+# gd-tools
+
+A modern development workflow CLI for GDScript projects in Godot 4.5+.
+
+[![CI](https://github.com/mansyar/gd-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/mansyar/gd-tools/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/mansyar/gd-tools/branch/main/graph/badge.svg)](https://codecov.io/gh/mansyar/gd-tools)
+[![PyPI version](https://img.shields.io/pypi/v/gd-tools.svg)](https://pypi.org/project/gd-tools/)
+[![Python versions](https://img.shields.io/pypi/pyversions/gd-tools.svg)](https://pypi.org/project/gd-tools/)
+[![Godot version](https://img.shields.io/badge/Godot-4.5%2B-blue.svg)](https://godotengine.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 1. Overview
+
+`gd-tools` brings professional development tooling to GDScript -- test, lint,
+format, and code coverage in a single CLI. It wraps mature, community-trusted
+tools (GUT for testing, gdtoolkit for linting and formatting) and fills the
+remaining gap with a custom hybrid coverage system -- production-quality line
+and branch coverage for GDScript that no existing tool provides.
+
+One install, one config, one mental model.
+
+## 2. Features
+
+| Feature | Description |
+|---------|-------------|
+| **Unified workflow** | One install, one config (`gd-tools.toml`), one mental model for test, lint, format, and coverage. |
+| **Zero-friction bootstrap** | `gd-tools init` gets a project fully set up in under a minute -- GUT installed, coverage addon 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. |
+| **CI/CD friendly** | Exit codes, `--check` flags, machine-readable output (JSON, JUnit XML, LCOV, Cobertura), no interactive prompts in CI mode. |
+| **Standalone compatibility** | gdlint, gdformat, and GUT continue to work if invoked directly. `gd-tools` is a layer on top, not a lock-in. |
+
+## 3. Installation
+
+```bash
+pip install gd-tools-cli
+```
+
+`gd-tools` requires Python 3.10+ and a Godot 4.5+ binary on your system.
+The Godot binary is auto-detected from configuration, environment variables
+(`GODOT_BIN`, `GODOT4_BIN`, `GODOT_PATH`), `PATH`, or common install locations.
+
+## 4. Quick Start
+
+```bash
+# 1. Install
+pip install gd-tools-cli
+
+# 2. Bootstrap your Godot project
+cd your-godot-project
+gd-tools init
+
+# 3. Run your tests
+gd-tools test
+
+# 4. Run tests with coverage
+gd-tools test --coverage --min 80
+```
+
+`gd-tools init` installs GUT, deploys the coverage addon, generates
+`gd-tools.toml`, and creates per-tool config files (`.gutconfig.json`,
+`gdlintrc`, `gdformatrc`). The command is idempotent -- safe to re-run.
+
+## 5. CLI Command Summary
+
+| Command | Description |
+|---------|-------------|
+| `gd-tools init` | Bootstrap a Godot project -- install GUT, deploy coverage addon, generate configs. |
+| `gd-tools doctor` | Diagnose the development environment -- Godot, GUT, coverage addon, tooling. |
+| `gd-tools test` | Run GUT tests with optional coverage, thresholds, JUnit XML output. |
+| `gd-tools lint` | Lint GDScript files using gdlint with text or JSON output. |
+| `gd-tools format` | Format GDScript files using gdformat with check and diff modes. |
+| `gd-tools coverage` | Coverage subcommands -- `report`, `merge`, `show`. |
+
+See the [User Guide](./docs/USER_GUIDE.md) for full command reference,
+flags, examples, and exit codes.
+
+## 6. 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
+defaults.
+
+```toml
+[godot]
+binary = ""  # Optional -- auto-detected if unset
+
+[test]
+test_dirs = ["test", "tests"]
+prefix = "test_"
+suffix = ".gd"
+gutconfig = ".gutconfig.json"
+
+[lint]
+exclude = ["addons", ".godot", ".gd-tools", ".git"]
+
+[format]
+exclude = ["addons", ".godot", ".gd-tools", ".git"]
+
+[coverage]
+enabled = false
+min_percent = 0
+format = "html"  # html, lcov, cobertura, text
+output_dir = ".gd-tools/coverage"
+exclude = ["addons", ".godot", ".gd-tools", ".git"]
+test_dirs = ["test", "tests"]
+```
+
+See the [User Guide](./docs/USER_GUIDE.md) for a full configuration reference
+with all keys, defaults, and examples.
+
+## 7. Documentation
+
+| Document | Description |
+|----------|-------------|
+| [User Guide](./docs/USER_GUIDE.md) | Complete CLI reference -- all commands, flags, examples, and troubleshooting. |
+| [Contributing Guide](./docs/CONTRIBUTING.md) | Development setup, code style, testing requirements, and PR process. |
+| [Architecture](./docs/ARCHITECTURE.md) | Coverage system architecture -- hybrid instrumentation design and data flows. |
+| [Product Requirements](./docs/PRD.md) | Full product specification -- features, design decisions, technical detail. |
+| [Roadmap](./docs/ROADMAP.md) | Release phases and milestones. |
+| [Testing Strategy](./docs/TESTING_STRATEGY.md) | Test pyramid, coverage targets, and CI integration. |
+
+## 8. Development
+
+```bash
+# Clone and install in editable mode with dev dependencies
+git clone https://github.com/mansyar/gd-tools.git
+cd gd-tools
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+Unit tests run without Godot. Integration tests require a Godot 4.5+
+binary -- configure via `.env` (see `.env.example`):
+
+```bash
+cp .env.example .env
+# Edit .env: set GODOT_BIN to your Godot binary path
+
+# Run all tests with coverage
+pytest --cov=src/gd_tools --cov-report=term-missing
+```
+
+See [Testing Strategy](./docs/TESTING_STRATEGY.md) for the full testing
+guide and [Contributing Guide](./docs/CONTRIBUTING.md) for development
+setup details.
+
+## 9. License
+
+MIT

gd_tools_cli-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gd-tools-cli"
+version = "0.1.0"
+description = "A modern development workflow CLI for GDScript projects in Godot 4.5+"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "mansyar", email = "m.ansyarafi@gmail.com"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "gdtoolkit",
+    "click",
+    "junitparser",
+    "jinja2",
+    "rich",
+    "pyyaml",
+    "tomli; python_version < '3.11'",
+    "tomli_w",
+    "pydantic >= 2.0",
+    "requests",
+]
+
+[project.urls]
+Homepage = "https://github.com/mansyar/gd-tools"
+Repository = "https://github.com/mansyar/gd-tools"
+Documentation = "https://github.com/mansyar/gd-tools#readme"
+"Bug Tracker" = "https://github.com/mansyar/gd-tools/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "ruff",
+    "black",
+]
+
+[project.scripts]
+gd-tools = "gd_tools.cli:cli"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"gd_tools.addons" = ["gd-tools-coverage/*.gd"]
+"gd_tools.coverage" = ["templates/*.html"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "unit: Unit tests for individual modules.",
+    "integration: Integration tests for command flows.",
+    "e2e: End-to-end tests for full workflows.",
+    "slow: Tests that take a long time to run.",
+]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "--cov=gd_tools",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+]
+
+[tool.coverage.run]
+source = ["gd_tools"]
+omit = ["*/tests/*", "*/addons/*"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+
+[tool.ruff]
+line-length = 80
+target-version = "py310"
+
+[tool.black]
+line-length = 80
+target-version = ["py310"]

gd_tools_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gd_tools_cli-0.1.0/src/gd_tools/__init__.py

@@ -0,0 +1,3 @@
+"""gd-tools: A modern development workflow CLI for GDScript projects."""
+
+__version__ = "0.1.0"

gd_tools_cli-0.1.0/src/gd_tools/__main__.py

@@ -0,0 +1,31 @@
+"""Module entry point for gd-tools.
+
+Allows running gd-tools via ``python -m gd_tools``.
+"""
+
+import sys
+
+from .cli import cli
+from .errors import GdToolsError
+
+
+def main() -> None:
+    """Run the gd-tools CLI.
+
+    Calls the Click CLI group and catches any :class:`GdToolsError`,
+    printing the error message to stderr and exiting with the
+    exception's ``exit_code``.
+
+    Raises:
+        SystemExit: When the CLI exits or a :class:`GdToolsError` is
+            caught.
+    """
+    try:
+        cli()
+    except GdToolsError as e:
+        print(str(e), file=sys.stderr)
+        sys.exit(e.exit_code)
+
+
+if __name__ == "__main__":
+    main()

gd_tools_cli-0.1.0/src/gd_tools/addons/gd-tools-coverage/coverage.gd

@@ -0,0 +1,43 @@
+extends Node
+
+# Coverage tracker autoload for gd-tools.
+# Records line hit counts during GUT test execution.
+# Activated via the GD_TOOLS_COVERAGE_ACTIVE environment variable.
+
+var _hits: Dictionary = {}
+
+var _active: bool = false
+
+
+func _ready() -> void:
+	# Active only when GD_TOOLS_COVERAGE_ACTIVE is "1" or "true".
+	var env_val: String = OS.get_environment("GD_TOOLS_COVERAGE_ACTIVE")
+	env_val = env_val.to_lower()
+	_active = env_val == "1" or env_val == "true"
+
+
+func hit(file_id: int, line_id: int) -> void:
+	# Single bool check for minimal overhead when inactive.
+	if not _active:
+		return
+	if not _hits.has(file_id):
+		_hits[file_id] = {}
+	if not _hits[file_id].has(line_id):
+		_hits[file_id][line_id] = 0
+	_hits[file_id][line_id] += 1
+
+
+func get_hits() -> Dictionary:
+	return _hits
+
+
+func reset() -> void:
+	_hits.clear()
+
+
+func set_active(active: bool) -> void:
+	_active = active
+
+
+func is_active() -> bool:
+	return _active

gd_tools_cli-0.1.0/src/gd_tools/addons/gd-tools-coverage/post_run_hook.gd

@@ -0,0 +1,113 @@
+extends GutHookScript
+
+## Post-run hook for GUT test runner.
+## Collects coverage data from the _GDTCoverage tracker and
+## writes it to a JSON file after tests have executed.
+
+const TRACKER_NAME = "_GDTCoverage"
+
+
+func run() -> void:
+	var tracker = _get_tracker()
+	if tracker == null:
+		return
+
+	if not tracker.is_active():
+		return
+
+	var hits: Dictionary = tracker.get_hits()
+	var data: Dictionary = _build_coverage_json(hits)
+
+	var output_path: String = OS.get_environment("GD_TOOLS_COVERAGE_OUTPUT")
+	if output_path.is_empty():
+		_log_error(
+			"Cannot write coverage output.",
+			"GD_TOOLS_COVERAGE_OUTPUT environment variable is not set.",
+			"Set GD_TOOLS_COVERAGE_OUTPUT to a writable file path."
+		)
+		return
+
+	if not _write_json(output_path, data):
+		return
+
+	_log_summary(hits, output_path)
+
+
+func _get_tracker() -> Node:
+	var tree = Engine.get_main_loop() as SceneTree
+	if tree == null:
+		_log_error(
+			"Cannot access coverage tracker.",
+			"SceneTree is not available.",
+			"Ensure the hook runs in a Godot project context."
+		)
+		return null
+
+	var tracker = tree.root.get_node_or_null(TRACKER_NAME)
+	if tracker == null:
+		_log_error(
+			"Cannot access coverage tracker.",
+			"Autoload '" + TRACKER_NAME + "' not found.",
+			"Ensure the coverage addon is installed and registered as an autoload."
+		)
+		return null
+
+	return tracker
+
+
+func _build_coverage_json(hits: Dictionary) -> Dictionary:
+	var files: Array = []
+	for file_id in hits:
+		var file_hits: Dictionary = hits[file_id]
+		var hits_dict: Dictionary = {}
+		for line_id in file_hits:
+			hits_dict[str(line_id)] = file_hits[line_id]
+		files.append({"file_id": int(file_id), "hits": hits_dict})
+	return {
+		"version": 1,
+		"generated_at": Time.get_datetime_string_from_system(true, false) + "Z",
+		"files": files
+	}
+
+
+func _write_json(path: String, data: Dictionary) -> bool:
+	var dir_path: String = path.get_base_dir()
+	if not dir_path.is_empty() and not DirAccess.dir_exists_absolute(dir_path):
+		var err: int = DirAccess.make_dir_recursive_absolute(dir_path)
+		if err != OK:
+			_log_error(
+				"Cannot create output directory.",
+				"Failed to create directory: " + dir_path,
+				"Check permissions and path validity."
+			)
+			return false
+
+	var file = FileAccess.open(path, FileAccess.WRITE)
+	if file == null:
+		_log_error(
+			"Cannot write coverage output.",
+			"Cannot open file for writing: " + path,
+			"Check file permissions and path validity."
+		)
+		return false
+
+	file.store_string(JSON.stringify(data, "  "))
+	file = null
+	return true
+
+
+func _log_summary(hits: Dictionary, output_path: String) -> String:
+	var total_files: int = hits.size()
+	var total_lines: int = 0
+	for file_id in hits:
+		total_lines += hits[file_id].size()
+	var summary: String = (
+		"[gd-tools] Coverage summary: %d files, %d lines tracked, output: %s"
+		% [total_files, total_lines, output_path]
+	)
+	print(summary)
+	return summary
+
+
+func _log_error(what: String, cause: String, fix: String) -> void:
+	push_error("[gd-tools] [Error] " + what + "\n\n" + "  Cause: " + cause + "\n" + "  Fix:   " + fix)