gd-tools-cli 0.1.0__py3-none-any.whl

gd_tools/__init__.py

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

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/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/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)

gd_tools/addons/gd-tools-coverage/pre_run_hook.gd

@@ -0,0 +1,229 @@
+extends GutHookScript
+
+## Pre-run hook for GUT test runner.
+## Instruments GDScript source files with coverage tracking calls
+## before tests are executed.
+
+const TRACKER_NAME = "_GDTCoverage"
+
+var _plan: Dictionary = {}
+
+
+func run() -> void:
+	var plan_path: String = OS.get_environment("GD_TOOLS_COVERAGE_PLAN")
+	if plan_path.is_empty():
+		print("[gd-tools] [Warning] GD_TOOLS_COVERAGE_PLAN not set. Skipping instrumentation.")
+		return
+
+	_plan = _load_plan(plan_path)
+	if _plan.is_empty():
+		return
+
+	if not _validate_plan(_plan):
+		_plan = {}
+		return
+
+	var files: Array = _plan.get("files", [])
+	if files.is_empty():
+		print("[gd-tools] [Warning] Coverage plan has no files to instrument.")
+		return
+
+	var instrumented_count: int = _instrument_files()
+	if instrumented_count > 0:
+		_activate_tracker()
+
+
+func _instrument_files() -> int:
+	var files: Array = _plan.get("files", [])
+	var count: int = 0
+	for file_entry in files:
+		if _instrument_file(file_entry):
+			count += 1
+	return count
+
+
+func _instrument_file(file_entry: Dictionary) -> bool:
+	var path: String = file_entry.get("path", "")
+	var file_id: int = int(file_entry.get("file_id", -1))
+	var lines: Array = file_entry.get("lines", [])
+
+	if lines.is_empty():
+		return false
+
+	var script = load(path) as GDScript
+	if script == null:
+		_log_error(
+			"Failed to instrument script.",
+			"Cannot load script: " + path,
+			"Verify the path in the plan exists and compiles."
+		)
+		return false
+
+	var source: String = script.source_code
+	var instrumented: String = _inject_trackers(source, file_id, lines)
+	script.source_code = instrumented
+	var err: int = script.reload()
+	if err != OK:
+		_log_error(
+			"Failed to reload instrumented script.",
+			"reload() failed for: " + path,
+			"Check tracker injection logic for syntax errors."
+		)
+		return false
+
+	return true
+
+
+func _activate_tracker() -> void:
+	var tree = Engine.get_main_loop() as SceneTree
+	if tree == null:
+		_log_error(
+			"Failed to activate coverage tracker.",
+			"Cannot access SceneTree.",
+			"Ensure the hook runs in a Godot project context."
+		)
+		return
+
+	var tracker = tree.root.get_node_or_null(TRACKER_NAME)
+	if tracker == null:
+		_log_error(
+			"Failed to activate coverage tracker.",
+			"Autoload '" + TRACKER_NAME + "' not found.",
+			"Ensure the coverage addon is installed and registered as an autoload."
+		)
+		return
+
+	tracker.set_active(true)
+
+
+static func _extract_indent(line: String) -> String:
+	var indent: String = ""
+	for c in line:
+		if c == " " or c == "\t":
+			indent += c
+		else:
+			break
+	return indent
+
+
+static func _inject_trackers(source: String, file_id: int, lines: Array) -> String:
+	var source_lines: PackedStringArray = source.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:
+		var target_line_num: int = int(entry["line"])
+		var line_id: int = int(entry["id"])
+		var target_index: int = target_line_num - 1
+		if target_index < 0 or target_index >= source_lines.size():
+			continue
+		var target_line: String = source_lines[target_index]
+		var indent: String = _extract_indent(target_line)
+		var tracker_call: String = "%s%s.hit(%d, %d)" % [indent, TRACKER_NAME, file_id, line_id]
+		source_lines.insert(target_index, tracker_call)
+	return "\n".join(source_lines)
+
+
+func _load_plan(path: String) -> Dictionary:
+	if not FileAccess.file_exists(path):
+		_log_error(
+			"Failed to load coverage plan.",
+			"File not found: " + path,
+			"Ensure GD_TOOLS_COVERAGE_PLAN points to a valid plan JSON file."
+		)
+		return {}
+
+	var f = FileAccess.open(path, FileAccess.READ)
+	if f == null:
+		_log_error(
+			"Failed to load coverage plan.",
+			"Cannot open file: " + path,
+			"Check file permissions and try again."
+		)
+		return {}
+
+	var content: String = f.get_as_text()
+	f = null
+
+	var parsed = JSON.parse_string(content)
+	if not (parsed is Dictionary):
+		_log_error(
+			"Failed to parse coverage plan JSON.",
+			"Invalid JSON in file: " + path,
+			"Validate the JSON syntax and try again."
+		)
+		return {}
+
+	return parsed
+
+
+func _validate_plan(plan: Dictionary) -> bool:
+	if not plan.has("version"):
+		_log_error(
+			"Invalid coverage plan structure.",
+			"Missing 'version' key.",
+			"Ensure the plan JSON has a 'version' field."
+		)
+		return false
+
+	if not plan.has("files") or not (plan["files"] is Array):
+		_log_error(
+			"Invalid coverage plan structure.",
+			"Missing or invalid 'files' key.",
+			"Ensure the plan JSON has a 'files' array."
+		)
+		return false
+
+	for file_entry in plan["files"]:
+		if not _validate_file_entry(file_entry):
+			return false
+
+	return true
+
+
+func _validate_file_entry(file_entry: Variant) -> bool:
+	if not (file_entry is Dictionary):
+		_log_error(
+			"Invalid coverage plan structure.",
+			"File entry is not an object.",
+			"Ensure each file in 'files' is a JSON object."
+		)
+		return false
+
+	if not file_entry.has("file_id"):
+		_log_error(
+			"Invalid coverage plan structure.",
+			"File entry missing 'file_id'.",
+			"Ensure each file has a 'file_id' field."
+		)
+		return false
+
+	if not file_entry.has("path"):
+		_log_error(
+			"Invalid coverage plan structure.",
+			"File entry missing 'path'.",
+			"Ensure each file has a 'path' field."
+		)
+		return false
+
+	if not file_entry.has("lines") or not (file_entry["lines"] is Array):
+		_log_error(
+			"Invalid coverage plan structure.",
+			"Missing or invalid 'lines' key.",
+			"Ensure each file has a 'lines' array."
+		)
+		return false
+
+	for line_entry in file_entry["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.",
+				"Line entry missing 'line' or 'id' key.",
+				"Ensure each line entry has 'line' and 'id' fields."
+			)
+			return false
+
+	return true
+
+
+func _log_error(what: String, cause: String, fix: String) -> void:
+	push_error("[gd-tools] [Error] " + what + "\n\n" + "  Cause: " + cause + "\n" + "  Fix:   " + fix)