gdharness 1.2.35 → 1.2.36

package/build/godot/addons/gdharness_runtime/runtime_waits.gd

@@ -26,8 +26,13 @@ const LOOKS_APART: int = 9
 ## two looks and a wait for 32 never sees it.
 const COMPARES: Array[String] = ["==", "!=", ">=", "<=", ">", "<"]
 
+## The most signal watches kept at once; arming one past this lets the oldest go.
+const MOST_WATCHES: int = 16
+
 var _host: Node
 var _values: Values
+var _watches: Dictionary[int, Watch] = {}
+var _next_watch: int = 1
 
 
 func _init(host: Node, values: Values) -> void:
@@ -56,13 +61,16 @@ func wait_frames(params: Dictionary) -> Dictionary:
 	return {"type": "waited", "frames": frames, "elapsed_ms": Time.get_ticks_msec() - started}
 
 
-## Waits for a signal to fire, and answers with what it carried, or that the time ran out.
+## Waits for a signal to fire, and answers with what it carried, or that the time ran out. Given a
+## watch, collects that instead: see [method watch_signal].
 func wait_signal(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var signal_name: String = str(params.get("signal", ""))
 	var timeout_ms: int = Read.as_int(params.get("timeout_ms", 5000), 5000)
 	if timeout_ms < 1 or timeout_ms > CEILING_MSEC:
 		return _out_of_range("timeout_ms", timeout_ms, 1, CEILING_MSEC)
+	if params.has("watch"):
+		return await _collect(Read.as_int(params["watch"], 0), timeout_ms)
 	if node_path.is_empty() or signal_name.is_empty():
 		return {"type": "error", "message": "Node path and signal name required"}
 
@@ -84,7 +92,7 @@ func wait_signal(params: Dictionary) -> Dictionary:
 	if not catcher.fired and is_instance_valid(node) and node.is_connected(signal_name, callable):
 		node.disconnect(signal_name, callable)
 
-	return {
+	var answer: Dictionary = {
 		"type": "signal",
 		"path": node_path,
 		"signal": signal_name,
@@ -92,6 +100,90 @@ func wait_signal(params: Dictionary) -> Dictionary:
 		"args": _values.serialize(catcher.args),
 		"elapsed_ms": Time.get_ticks_msec() - started,
 	}
+	if not catcher.fired:
+		answer["note"] = (
+			"If a call meant to set the signal off was sent beside this wait, it may have run only after"
+			+ " the wait answered, as a client can run its calls in turn: arm runtime_wait watch first,"
+			+ " make the call, then wait with signal and that watch"
+		)
+	return answer
+
+
+## Starts recording a signal and answers at once with the watch to collect it by.
+##
+## A wait sent beside the call meant to set its signal off does not see it when the client runs the
+## two in turn: Claude Code ran a key press only after the signal wait beside it had answered, so the
+## wait ran out and the press landed after it. A watch is armed before the call and collected after.
+func watch_signal(params: Dictionary) -> Dictionary:
+	var node_path: String = str(params.get("path", ""))
+	var signal_name: String = str(params.get("signal", ""))
+	if node_path.is_empty() or signal_name.is_empty():
+		return {"type": "error", "message": "Node path and signal name required"}
+	var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+	if standing.has("message"):
+		return standing
+	var node: Node = standing["node"]
+	if not node.has_signal(signal_name):
+		return {"type": "error", "message": "%s has no signal %s" % [node_path, signal_name]}
+	var watch: Watch = Watch.new(node, node_path, signal_name)
+	var listening: Error = node.connect(signal_name, watch.catcher._on_fired)
+	if listening != OK:
+		return {"type": "error", "message": "Could not listen to signal: " + signal_name}
+	while _watches.size() >= MOST_WATCHES:
+		var oldest: int = _watches.keys().min()
+		_let_go(oldest)
+	var id: int = _next_watch
+	_next_watch += 1
+	_watches[id] = watch
+	return {"type": "watching", "watch": id, "path": node_path, "signal": signal_name}
+
+
+## Answers at once with the first emission recorded since watch [param id] was armed, otherwise
+## waits for the next until the time runs out. The watch goes either way.
+func _collect(id: int, timeout_ms: int) -> Dictionary:
+	if not _watches.has(id):
+		return {
+			"type": "error",
+			"message":
+			(
+				(
+					"No watch %d is armed in this game: it was collected already, %d armed after it let it"
+					+ " go, or the game started again since"
+				)
+				% [id, MOST_WATCHES]
+			),
+		}
+	var watch: Watch = _watches[id]
+	var started: int = Time.get_ticks_msec()
+	var before: bool = watch.catcher.fired
+	while not watch.catcher.fired and Time.get_ticks_msec() - started < timeout_ms:
+		await _host.get_tree().process_frame
+	_let_go(id)
+	var answer: Dictionary = {
+		"type": "signal",
+		"path": watch.node_path,
+		"signal": watch.signal_name,
+		"watch": id,
+		"fired": watch.catcher.fired,
+		"times": watch.catcher.times,
+		"args": _values.serialize(watch.catcher.args),
+		"elapsed_ms": Time.get_ticks_msec() - started,
+	}
+	if before:
+		answer["fired_before_wait"] = true
+	return answer
+
+
+func _let_go(id: int) -> void:
+	var watch: Watch = _watches.get(id)
+	var _gone: bool = _watches.erase(id)
+	if watch == null:
+		return
+	var held: Object = watch.node.get_ref()
+	var node: Node = held as Node
+	var callable: Callable = watch.catcher._on_fired
+	if node != null and node.is_connected(watch.signal_name, callable):
+		node.disconnect(watch.signal_name, callable)
 
 
 ## Waits until a property reads as the value given, or until something under the path says what
@@ -492,8 +584,26 @@ func _anything_says(node_path: String, said: String, include_hidden: bool) -> bo
 class SignalCatcher:
 	extends RefCounted
 	var fired: bool = false
+	## How many times it fired; [member args] holds what the first carried.
+	var times: int = 0
 	var args: Array = []
 
 	func _on_fired(...carried: Array) -> void:
+		if not fired:
+			args = carried
 		fired = true
-		args = carried
+		times += 1
+
+
+## A signal recorded from when it was armed until it is collected.
+class Watch:
+	extends RefCounted
+	var node: WeakRef
+	var node_path: String
+	var signal_name: String
+	var catcher: SignalCatcher = SignalCatcher.new()
+
+	func _init(watched: Node, path: String, named: String) -> void:
+		node = weakref(watched)
+		node_path = path
+		signal_name = named

package/build/godot/operations/classdb_queries.gd

@@ -21,6 +21,17 @@ const CATEGORY_BASES: Dictionary = {
 	"visual": ["VisualInstance3D"],
 	"animation": ["AnimationMixer"],
 }
+## The engine's MethodFlags, each by the name an answer gives it.
+const METHOD_FLAG_NAMES: Dictionary[int, String] = {
+	METHOD_FLAG_NORMAL: "normal",
+	METHOD_FLAG_EDITOR: "editor",
+	METHOD_FLAG_CONST: "const",
+	METHOD_FLAG_VIRTUAL: "virtual",
+	METHOD_FLAG_VARARG: "vararg",
+	METHOD_FLAG_STATIC: "static",
+	METHOD_FLAG_OBJECT_CORE: "object_core",
+	METHOD_FLAG_VIRTUAL_REQUIRED: "virtual_required",
+}
 
 var _log: Log
 var _values: Serialisation = Serialisation.new()
@@ -333,6 +344,7 @@ func _methods_of(class_name_str: String, include_inherited: bool) -> Array[Dicti
 						"class_name": return_info.get("class_name", "")
 					},
 					"flags": m.get("flags", 0),
+					"flag_names": _flag_names(Read.as_int(m.get("flags", 0))),
 					# As values, tagged the way every other answer tags one: JSON writes a Vector2i it is
 					# handed as its text, so TileMapLayer.set_cell's default atlas coords read "(-1, -1)".
 					"default_args": _values.serialize_value(m.get("default_args", []))
@@ -343,6 +355,16 @@ func _methods_of(class_name_str: String, include_inherited: bool) -> Array[Dicti
 	return methods
 
 
+# The MethodFlags set in [param flags] by name, beside the number the engine reports, which reads as
+# nothing without its enum: 1 is normal, and a const method is 5.
+static func _flag_names(flags: int) -> Array[String]:
+	var named: Array[String] = []
+	for flag: int in METHOD_FLAG_NAMES:
+		if flags & flag:
+			named.append(METHOD_FLAG_NAMES[flag])
+	return named
+
+
 # What [param info]'s type is called: its class for an object of one, and otherwise the engine's own
 # name for the type, beside the number the engine reports, which reads as nothing without its enum.
 # Nil is a value that can be anything when the usage says so, and [param nil_name] otherwise: void

package/build/godot/operations/dependencies.gd

@@ -23,6 +23,11 @@ const REFERENCE_PATTERNS: Array[String] = [
 
 var _log: Log
 var _files: FileWalk = FileWalk.new()
+## The project's class names and the scripts declaring them, read the first time a script is walked
+## and kept for the call: walking every resource starts a walk per root, and each reading every
+## script again made the whole-project answer quadratic in the number of scripts.
+var _classes_declared: Dictionary = {}
+var _classes_read: bool = false
 
 
 # Everything one dependency walk carries: the settings it was started with, and the state it
@@ -91,12 +96,14 @@ func get_dependencies(params: Dictionary) -> Dictionary:
 
 		total_resources = all_resources.size()
 
-	var dep_count: int = 0
+	var references: int = 0
+	var distinct: Dictionary = {}
 	for key: String in dependencies:
 		# Through a typed local: what comes out of a Dictionary is Variant, and a project that
 		# errors on handing one to a typed parameter will not compile this script at all.
 		var walked: Array[Dictionary] = dependencies[key]
-		dep_count += _count_recursive(walked)
+		references += _count_recursive(walked)
+		_gather_paths(walked, key, distinct)
 
 	return {
 		"dependencies": dependencies,
@@ -104,7 +111,10 @@ func get_dependencies(params: Dictionary) -> Dictionary:
 		"summary":
 		{
 			"total_resources": total_resources,
-			"total_dependencies": dep_count,
+			# The files depended on, each once. The tree names a file again under everything that
+			# loads it, and counting its entries answered 11 for a scene with six dependencies.
+			"total_dependencies": distinct.size(),
+			"total_references": references,
 			"circular_count": circular_references.size()
 		}
 	}
@@ -332,9 +342,24 @@ func _regex_escaped(text: String) -> String:
 	return escaped
 
 
+# [param root] is left out: a cycle leads back to it, and it is not one of its own dependencies.
+func _gather_paths(deps: Array[Dictionary], root: String, into: Dictionary) -> void:
+	for dep: Dictionary in deps:
+		var path: String = str(dep.get("path", ""))
+		if path != root:
+			into[path] = true
+		if dep.has("dependencies"):
+			var deeper: Array[Dictionary] = dep["dependencies"]
+			_gather_paths(deeper, root, into)
+
+
+# A circular entry is not counted: it marks that the entry holding it was reached again, which that
+# entry already counts as one reference.
 func _count_recursive(deps: Array[Dictionary]) -> int:
-	var count: int = deps.size()
+	var count: int = 0
 	for dep: Dictionary in deps:
+		if not dep.get("circular", false):
+			count += 1
 		if dep.has("dependencies"):
 			var deeper: Array[Dictionary] = dep["dependencies"]
 			count += _count_recursive(deeper)
@@ -390,29 +415,74 @@ func _analyze_resource(path: String, current_depth: int, walk: DependencyWalk) -
 				if not walk.include_built_in and dep_path.begins_with("res://."):
 					continue
 
-				if dep_path == path:
-					continue
-
-				var dep_info: Dictionary = {"path": dep_path, "exists": FileAccess.file_exists(dep_path)}
-
-				if dep_info["exists"] and current_depth + 1 < walk.max_depth:
-					var sub_deps: Array[Dictionary] = _analyze_resource(dep_path, current_depth + 1, walk)
-					if sub_deps.size() > 0:
-						dep_info["dependencies"] = sub_deps
+				_depend(deps, path, dep_path, "", current_depth, walk)
 
-				var already_added: bool = false
-				for existing: Dictionary in deps:
-					if existing.get("path", "") == dep_path:
-						already_added = true
-						break
-				if not already_added:
-					deps.append(dep_info)
+		# A script uses another by its class_name as surely as by a preload, and only the reverse walk
+		# looked for that: asked what a script depends on, the answer left out the script it typed a
+		# variable with, while asking what used that script named this one.
+		if path.get_extension() == "gd":
+			var classes: Dictionary = classes_declared()
+			for used: String in classes_used_in(content, classes):
+				_depend(deps, path, str(classes[used]), used, current_depth, walk)
 
 	walk.path_stack.pop_back()
 	walk.visited[path] = {"deps": deps, "remaining": remaining}
 	return deps
 
 
+# Adds [param dep_path] to [param deps], what [param path] depends on, walked as far as the depth left
+# allows, once however many times it is named. [param by_class] is the class name it was named by,
+# or empty for a path.
+func _depend(
+	deps: Array[Dictionary],
+	path: String,
+	dep_path: String,
+	by_class: String,
+	current_depth: int,
+	walk: DependencyWalk
+) -> void:
+	if dep_path == path:
+		return
+	for existing: Dictionary in deps:
+		if existing.get("path", "") == dep_path:
+			return
+	var dep_info: Dictionary = {"path": dep_path, "exists": FileAccess.file_exists(dep_path)}
+	if not by_class.is_empty():
+		dep_info["by_class"] = by_class
+	if dep_info["exists"] and current_depth + 1 < walk.max_depth:
+		var sub_deps: Array[Dictionary] = _analyze_resource(dep_path, current_depth + 1, walk)
+		if sub_deps.size() > 0:
+			dep_info["dependencies"] = sub_deps
+	deps.append(dep_info)
+
+
+## Every class_name the project's scripts declare, with the script declaring it.
+func classes_declared() -> Dictionary:
+	if _classes_read:
+		return _classes_declared
+	_classes_read = true
+	for script: String in _files.find_files("res://", ".gd"):
+		var declared: String = _declared_class_name(script)
+		if not declared.is_empty():
+			_classes_declared[declared] = script
+	return _classes_declared
+
+
+## The names in [param classes] that the code in [param content] uses, in the order first used: words
+## outside strings and comments, so a class named in prose or in a message is not a use of it.
+static func classes_used_in(content: String, classes: Dictionary) -> Array[String]:
+	var used: Array[String] = []
+	if classes.is_empty():
+		return used
+	var word: RegEx = Patterns.compiled("[A-Za-z_][A-Za-z0-9_]*")
+	for line: String in content.split("\n"):
+		for m: RegExMatch in word.search_all(_code_of(line)):
+			var name: String = m.get_string()
+			if classes.has(name) and not name in used:
+				used.append(name)
+	return used
+
+
 # [param written] as the res:// path the engine would load from [param from]: a uid:// by what the
 # project's uid cache says it names, and a relative path against the referring file's directory.
 # Both were passed over as not being res:// paths, so a script's `preload("sibling.gd")` was no

package/build/godot/operations/gdscript_analysis.gd

@@ -1,10 +1,13 @@
 extends RefCounted
 
+const Dependencies = preload("dependencies.gd")
 const Patterns = preload("patterns.gd")
 const Read = preload("reading.gd")
 const Log = preload("logger.gd")
 
 var _log: Log
+## Kept for the call, so the project's class names are read once however many bases are walked.
+var _dependencies: Dependencies = null
 
 
 func _init(p_log: Log) -> void:
@@ -136,6 +139,21 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 	# its first function would otherwise be judged against the default.
 	_mark_virtuals(functions, extends_name, full_script_path)
 
+	# A script typed by its class_name is depended on as surely as one preloaded, and the answer
+	# listed only the preloads: a `var stats: Stats` left stats.gd out, while project_dependencies
+	# named it. The same reading as that tool's, so the two agree.
+	var classes_used: Array[Dictionary] = []
+	if _dependencies == null:
+		_dependencies = Dependencies.new(_log)
+	var declared_by: Dictionary = _dependencies.classes_declared()
+	for used: String in Dependencies.classes_used_in(content, declared_by):
+		var declaring: String = str(declared_by[used])
+		if declaring == full_script_path:
+			continue
+		classes_used.append({"name": used, "path": declaring})
+		if not declaring in dependencies:
+			dependencies.append(declaring)
+
 	var answer: Dictionary = {
 		"path": script_path,
 		"full_path": full_script_path,
@@ -148,6 +166,7 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 		"enums": enums,
 		"inner_classes": inner_classes,
 		"dependencies": dependencies,
+		"classes_used": classes_used,
 		"line_count": lines.size()
 	}
 	if Read.as_bool(params.get("include_inherited", false)):

package/build/godot/operations/godot_operations.gd

@@ -32,6 +32,7 @@ const ProjectDiagnostics = preload("project_diagnostics.gd")
 const Read = preload("reading.gd")
 const RenameChecks = preload("rename_checks.gd")
 const ResourceFiles = preload("resource_files.gd")
+const ScriptCheck = preload("script_check.gd")
 
 ## Printed once the answer is written, after which the engine runs the project's autoloads. Kept in
 ## step with `ANSWERED` in src/headless.ts.
@@ -218,7 +219,7 @@ func _run(operation: String, params: Dictionary) -> Dictionary:
 		"names_taken":
 			payload = RenameChecks.new(_log).names_taken(params)
 		"check_scripts":
-			payload = RenameChecks.new(_log).check_scripts(params)
+			payload = ScriptCheck.new(_log).check_scripts(params)
 
 		# Plugins and input
 		"list_plugins":

package/build/godot/operations/rename_checks.gd

@@ -1,6 +1,5 @@
 extends RefCounted
 
-const GdscriptAuthoring = preload("gdscript_authoring.gd")
 const Log = preload("logger.gd")
 
 var _log: Log
@@ -63,21 +62,3 @@ static func _named(entries: Array[Dictionary], name: String) -> bool:
 		if str(entry.get("name", "")) == name:
 			return true
 	return false
-
-
-# Whether each script compiles in a fresh engine, which reads the class cache as it starts and so
-# resolves every class the cache lists. The engine's reasons go to stderr and come back with the
-# answer. It names the scripts it checked rather than counting them, since a caller told one was
-# checked could not say which.
-func check_scripts(params: Dictionary) -> Dictionary:
-	var paths: Array = params.get("paths", [])
-	var checked: Array[String] = []
-	var failed: Array[String] = []
-	for value: Variant in paths:
-		var path: String = str(value)
-		checked.append(path)
-		var script: Script = ResourceLoader.load(path, "Script", ResourceLoader.CACHE_MODE_IGNORE)
-		if not GdscriptAuthoring._parses(script):
-			_log.error("Does not compile: " + path)
-			failed.append(path)
-	return {"checked": checked, "failed": failed}

package/build/godot/operations/script_check.gd

@@ -0,0 +1,98 @@
+extends RefCounted
+
+## Compiles scripts the way the engine does when it loads them, and answers what it raised.
+##
+## The engine reports a script that does not compile as errors raised from GDScript::reload, each
+## naming the file and line, and they reach a Logger as well as stderr. Measured on 4.7.2: a script
+## whose dependency does not compile reports the dependency's errors at the dependency's path and one
+## of its own at line 0, "Compile Error: Failed to compile depended scripts", and is still handed
+## back as a script that can_instantiate() calls instantiable. Warnings are not among them: the engine
+## sends those only to an editor or a debugger.
+##
+## A script that failed stays failed in the engine's script cache, which no ResourceLoader cache mode
+## reaches, and every script loaded after it that depends on it compiles in silence, reload() and all.
+## So a run ends at the first script that raised anything, and the rest go to a fresh engine.
+
+const Read = preload("reading.gd")
+const Log = preload("logger.gd")
+
+## Where the engine raises a script's compile errors from.
+const RELOAD: String = "GDScript::reload"
+
+var _log: Log
+
+
+## Every compile error the engine raises while it is attached, in order.
+class Caught:
+	extends Logger
+
+	var raised: Array[Dictionary] = []
+
+	func _log_message(_message: String, _error: bool) -> void:
+		pass
+
+	# The engine's own signature for a Logger, eight parameters and not this project's to shape.
+	# gdlint:ignore = function-arguments-number
+	func _log_error(
+		function: String,
+		file: String,
+		line: int,
+		code: String,
+		rationale: String,
+		_editor_notify: bool,
+		_error_type: int,
+		_script_backtraces: Array[ScriptBacktrace],
+	) -> void:
+		if function != RELOAD:
+			return
+		raised.append(
+			{"path": file, "line": line, "message": rationale if not rationale.is_empty() else code}
+		)
+
+
+func _init(p_log: Log) -> void:
+	_log = p_log
+
+
+## Whether the scripts in [code]paths[/code] compile in a fresh engine, which reads the class cache
+## as it starts and so resolves every class the cache lists, up to and including the first that
+## raised an error. [code]checked[/code] names the scripts read, in order, and [code]failed[/code]
+## those that did not compile; [code]scripts[/code] holds each failed one with the errors raised in
+## its own file, and the other scripts that failed to compile while it was loaded. Read past the
+## resource cache, so a script loaded for an earlier one is compiled again for its own entry.
+func check_scripts(params: Dictionary) -> Dictionary:
+	var asked: Array = params.get("paths", [])
+	var caught: Caught = Caught.new()
+	OS.add_logger(caught)
+	var checked: Array[String] = []
+	var failed: Array[String] = []
+	var scripts: Array[Dictionary] = []
+	for entry: Variant in asked:
+		var path: String = str(entry)
+		checked.append(path)
+		caught.raised.clear()
+		var loaded: Resource = ResourceLoader.load(path, "", ResourceLoader.CACHE_MODE_IGNORE)
+		var errors: Array[Dictionary] = []
+		var others: Array[String] = []
+		for error: Dictionary in caught.raised:
+			var at: String = str(error["path"])
+			if at != path:
+				if not at in others:
+					others.append(at)
+				continue
+			var found: Dictionary = {"line": Read.as_int(error["line"]), "message": str(error["message"])}
+			if not found in errors:
+				errors.append(found)
+		if loaded == null and errors.is_empty():
+			errors.append({"line": 0, "message": "The engine could not load it as a script."})
+		if errors.is_empty() and others.is_empty():
+			continue
+		if not errors.is_empty():
+			failed.append(path)
+			var one: Dictionary = {"path": path, "errors": errors}
+			if not others.is_empty():
+				one["dependencies_with_errors"] = others
+			scripts.append(one)
+		break
+	OS.remove_logger(caught)
+	return {"checked": checked, "failed": failed, "scripts": scripts}