gdharness 1.3.4 → 1.3.5

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

@@ -4,6 +4,7 @@ extends RefCounted
 ## happened, or when the time ran out, so the caller never sleeps for a guessed length.
 
 const GdhChanges = preload("runtime_changes.gd")
+const GdhDeclared = preload("declared_values.gd")
 const GdhPaths = preload("runtime_paths.gd")
 const GdhQueries = preload("runtime_queries.gd")
 const GdhRead = preload("reading.gd")
@@ -51,6 +52,13 @@ static func _out_of_range(named: String, asked: int, least: int, most: int) -> D
 	}
 
 
+## The refusal for [param signal_name], which [param node] lacks, naming the nearest signals it has,
+## or every one when none is near: a name to send instead.
+static func _no_signal(node: Node, node_path: String, signal_name: String) -> Dictionary:
+	var said: String = "%s has no signal %s" % [node_path, signal_name]
+	return {"type": "error", "message": GdhRead.offered(said, signal_name, GdhRead.signals_of(node)) + "."}
+
+
 func wait_frames(params: Dictionary) -> Dictionary:
 	var frames: int = GdhRead.as_int(params.get("frames", 1), 1)
 	if frames < 1 or frames > MOST_FRAMES:
@@ -79,7 +87,7 @@ func wait_signal(params: Dictionary) -> Dictionary:
 		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]}
+		return _no_signal(node, node_path, signal_name)
 
 	var catcher: GdhSignalCatcher = GdhSignalCatcher.new()
 	var callable: Callable = catcher._on_fired
@@ -124,7 +132,7 @@ func watch_signal(params: Dictionary) -> Dictionary:
 		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]}
+		return _no_signal(node, node_path, signal_name)
 	var watch: GdhWatch = GdhWatch.new(node, node_path, signal_name)
 	var listening: Error = node.connect(signal_name, watch.catcher._on_fired)
 	if listening != OK:
@@ -240,7 +248,9 @@ func wait_until(params: Dictionary) -> Dictionary:
 	var current: Variant = watched["value"]
 	if compare in [">=", "<=", ">", "<"]:
 		return await _wait_in_order(node, params, current, timeout_ms)
-	var wanted: Variant = _values.fitted(params["value"], typeof(current))
+	var by_name: Array = _enum_by_name(watched, params["value"], node_path)
+	var sent: Variant = by_name[1] if not by_name.is_empty() and by_name[0] else params["value"]
+	var wanted: Variant = _values.fitted(sent, typeof(current))
 	# Read against what the property is declared as, not only against what it holds this frame: an
 	# object property holding null holds nothing typed, so any value was taken as it came and compared
 	# with null until the time ran out. #772 waited a minute for "null" that way and answered met
@@ -252,10 +262,13 @@ func wait_until(params: Dictionary) -> Dictionary:
 	var holds_objects: bool = declared == TYPE_OBJECT or untyped_object
 	if holds_objects and GdhChanges.names_no_object(wanted):
 		wanted = null
-	var refused: String = _not_comparable(current, wanted, node_path, property)
+	# A word no value of an enum is called, refused naming the values before it is compared as text.
+	var refused: String = "" if by_name.is_empty() or by_name[0] else str(by_name[1])
 	if refused.is_empty():
-		refused = _cut_to_fit(params["value"], typeof(current), node_path, property)
-	var rounded: String = GdhValues.inexact(params["value"], typeof(current))
+		refused = _not_comparable(current, wanted, node_path, property)
+	if refused.is_empty():
+		refused = _cut_to_fit(sent, typeof(current), node_path, property)
+	var rounded: String = GdhValues.inexact(sent, typeof(current))
 	if refused.is_empty() and not rounded.is_empty():
 		refused = "%s.%s holds int: %s." % [node_path, property, rounded]
 	var never_held: bool = typeof(wanted) != TYPE_NIL and typeof(wanted) != TYPE_OBJECT
@@ -469,6 +482,20 @@ static func _not_comparable(current: Variant, wanted: Variant, node_path: String
 	return ""
 
 
+## [param sent] as the number of the value an enum property names by it, as
+## [method GdhDeclared.enum_by_name] answers, for a word waited for on what [param watched] read; []
+## when the property is no enum or the value no word.
+static func _enum_by_name(watched: Dictionary, sent: Variant, node_path: String) -> Array:
+	var declaration: Dictionary = watched["declaration"]
+	var enum_hint: bool = GdhRead.as_int(declaration.get("hint", PROPERTY_HINT_NONE)) == PROPERTY_HINT_ENUM
+	if watched["declared"] != TYPE_INT or not enum_hint or not sent is String:
+		return []
+	if not watched["holder"] is Object:
+		return []
+	var owner: Object = watched["holder"]
+	return GdhDeclared.enum_by_name(owner, declaration, str(sent), node_path)
+
+
 ## What [param property] reads as on [param node] right now, under `value`, or a `message` saying
 ## why it cannot be read.
 ##
@@ -486,18 +513,24 @@ static func _watched(node: Node, node_path: String, property: String) -> Diction
 	var missing: String = GdhPaths.nothing_under(holder, named, str(reached["called"]))
 	if not missing.is_empty():
 		return {"type": "error", "message": missing}
-	return {"value": GdhPaths.read_under(holder, named), "declared": _declared_type(holder, named)}
+	var slot: Dictionary = _declared_slot(holder, named)
+	return {
+		"value": GdhPaths.read_under(holder, named),
+		"declared": slot["type"],
+		"declaration": slot["declared"],
+		"holder": holder,
+	}
 
 
-## The type [param named] is declared with on [param holder], read the way a set reads it, so the two
-## refuse the same values: a property's declaration, or a typed list's or map's element type. Read
-## off properties alone, an element of an Array[Node] holding null declares nothing, and a wait for 5
-## on it runs out the timeout while a set of 5 on it is refused at once. TYPE_NIL for anything
-## declaring none, and for a call, whose answer nothing declares.
-static func _declared_type(holder: Variant, named: String) -> int:
+## What [param named] is declared with on [param holder], as [method GdhValues.slot_declared] answers,
+## read the way a set reads it, so the two refuse the same values: a property's declaration, or a
+## typed list's or map's element type. Read off properties alone, an element of an Array[Node] holding
+## null declares nothing, and a wait for 5 on it runs out the timeout while a set of 5 on it is refused
+## at once. TYPE_NIL for anything declaring none, and for a call, whose answer nothing declares.
+static func _declared_slot(holder: Variant, named: String) -> Dictionary:
 	if not GdhPaths.method_of(named).is_empty():
-		return TYPE_NIL
-	return GdhValues.slot_declared(holder, named)["type"]
+		return {"type": TYPE_NIL, "class": "", "script": null, "declared": {}}
+	return GdhValues.slot_declared(holder, named)
 
 
 ## Waits until something under [param node_path] has [param said] written on it.

package/build/godot/operations/classdb_queries.gd

@@ -4,6 +4,9 @@ const GdhRead = preload("reading.gd")
 const GdhLog = preload("logger.gd")
 const GdhSerialisation = preload("serialisation.gd")
 
+# How far below the closest name another may score and still be offered beside it.
+const CLOSE_TO_THE_BEST: float = 0.2
+
 # The base classes each category name stands for. Kept to the list the tool's schema offers, which
 # a case holds: the schema offered physics3d and ui, which this refused, and physics answered the 3D
 # bodies alone beside physics2d and physics3d.
@@ -114,20 +117,20 @@ func query_class_info(params: Dictionary) -> Dictionary:
 	)
 
 	if not ClassDB.class_exists(class_name_str):
-		return _not_found(class_name_str)
+		return _not_found(class_name_str, _declared_classes(params))
 
 	var member: String = str(params.get("member", ""))
 	if not member.is_empty():
 		return _member_of(class_name_str, member)
 
-	var methods: Array[Dictionary] = _methods_of(class_name_str, include_inherited)
-	var properties: Array[Dictionary] = _properties_of(class_name_str, include_inherited)
-	var signals: Array[Dictionary] = _signals_of(class_name_str, include_inherited)
+	var methods: Array[Dictionary] = _methods_of(class_name_str)
+	var properties: Array[Dictionary] = _properties_of(class_name_str)
+	var signals: Array[Dictionary] = _signals_of(class_name_str)
 
 	var enums: Dictionary = {}
-	for e: String in ClassDB.class_get_enum_list(class_name_str, not include_inherited):
+	for e: String in ClassDB.class_get_enum_list(class_name_str, true):
 		var enum_values: Dictionary = {}
-		for c: String in ClassDB.class_get_enum_constants(class_name_str, e, not include_inherited):
+		for c: String in ClassDB.class_get_enum_constants(class_name_str, e, true):
 			enum_values[c] = ClassDB.class_get_integer_constant(class_name_str, c)
 		enums[e] = enum_values
 
@@ -143,7 +146,7 @@ func query_class_info(params: Dictionary) -> Dictionary:
 		)
 	)
 
-	return {
+	var answer: Dictionary = {
 		"class_name": class_name_str,
 		"parent_class": ClassDB.get_parent_class(class_name_str),
 		"can_instantiate": ClassDB.can_instantiate(class_name_str),
@@ -156,43 +159,99 @@ func query_class_info(params: Dictionary) -> Dictionary:
 		"signals": signals,
 		"enums": enums
 	}
+	if include_inherited:
+		answer["inherited"] = _inherited_names(class_name_str)
+	return answer
+
+
+# What [param class_name_str] inherits, by name under the ancestor declaring it, nearest first. In
+# full, CharacterBody2D's inherited members ran to two hundred thousand characters, more than a
+# client takes in one answer, and any one of them is read in full by asking for it as member.
+func _inherited_names(class_name_str: String) -> Array[Dictionary]:
+	var inherited: Array[Dictionary] = []
+	var current: String = ClassDB.get_parent_class(class_name_str)
+	while not current.is_empty():
+		(
+			inherited
+			. append(
+				{
+					"class": current,
+					"methods": _names(_methods_of(current)),
+					"properties": _names(_properties_of(current)),
+					"signals": _names(_signals_of(current)),
+					"enums": Array(ClassDB.class_get_enum_list(current, true)),
+				}
+			)
+		)
+		current = ClassDB.get_parent_class(current)
+	return inherited
+
+
+static func _names(members: Array[Dictionary]) -> Array[String]:
+	var names: Array[String] = []
+	for each: Dictionary in members:
+		names.append(str(each["name"]))
+	return names
+
+
+static func _declared_classes(params: Dictionary) -> Dictionary:
+	var given: Variant = params.get("project_classes", {})
+	if given is Dictionary:
+		var declared: Dictionary = given
+		return declared
+	return {}
 
 
-# One member of a class by name, wherever in its ancestry it is declared.
-#
-# The question a member is asked by name for is "does this engine have it, and what does it take":
-# the whole class in answer to that ran to seventy thousand characters for Control, and the member
-# is as often an ancestor's as the class's own, so the ancestry is walked without being asked. Each
-# match says which class declares it. Nothing found names the members whose names contain the one
-# asked for, since the usual miss is a spelling.
 ## Why [param wanted] has no answer here. A class_name a project script declares is not in ClassDB,
-## and "Class not found" for one read as though the project had no such class.
-func _not_found(wanted: String) -> Dictionary:
-	for entry: Dictionary in ProjectSettings.get_global_class_list():
-		if str(entry.get("class", "")) == wanted:
-			return (
-				_log
-				. failure(
-					(
-						(
-							"%s is not an engine class: it is the class_name %s declares, and editor_classes reads "
-							+ "the engine's ClassDB only. script_info structure on that script, with "
-							+ "includeInherited, answers what it declares and what it inherits."
-						)
-						% [wanted, str(entry.get("path", ""))]
-					)
+## and "Class not found" for one read as though the project had no such class. [param declared] is
+## what the project's scripts declare on disk, class to path, rather than the engine's list, which is
+## the class cache: that lags the scripts, and a class written a moment ago was refused as declared
+## nowhere.
+func _not_found(wanted: String, declared: Dictionary) -> Dictionary:
+	if declared.has(wanted):
+		return _log.failure(
+			(
+				(
+					"%s is not an engine class: it is the class_name %s declares, and editor_classes reads "
+					+ "the engine's ClassDB only. script_info structure on that script, with "
+					+ "includeInherited, answers what it declares and what it inherits."
 				)
+				% [wanted, str(declared[wanted])]
 			)
-	# The usual miss is a spelling, one letter off a class the engine has.
-	var close: PackedStringArray = GdhRead.nearest(wanted, ClassDB.get_class_list())
+		)
+	# The usual miss is a spelling, one letter off a class the engine has or one the project declares.
+	# Ranked as one pool and kept near the best, since a project class a letter off came behind three
+	# engine classes that shared only "Texture" with it.
+	var pool: PackedStringArray = ClassDB.get_class_list()
+	pool.append_array(PackedStringArray(declared.keys()))
+	var close: PackedStringArray = GdhRead.nearest(wanted, pool)
+	var best: float = 0.0 if close.is_empty() else close[0].to_lower().similarity(wanted.to_lower())
+	var engine: Array[String] = []
+	var own: Array[String] = []
+	for name: String in close:
+		if name.to_lower().similarity(wanted.to_lower()) < best - CLOSE_TO_THE_BEST:
+			continue
+		if declared.has(name):
+			own.append(name)
+		else:
+			engine.append(name)
 	var offered: String = (
 		""
-		if close.is_empty()
+		if engine.is_empty()
 		else (
 			" The nearest engine %s %s."
-			% ["class is" if close.size() == 1 else "classes are", ", ".join(close)]
+			% ["class is" if engine.size() == 1 else "classes are", ", ".join(engine)]
 		)
 	)
+	if not own.is_empty():
+		offered += (
+			" The nearest %s a project script declares %s %s, which script_info structure reads."
+			% [
+				"class" if own.size() == 1 else "classes",
+				"is" if own.size() == 1 else "are",
+				", ".join(own),
+			]
+		)
 	return _log.failure(
 		(
 			(
@@ -204,17 +263,24 @@ func _not_found(wanted: String) -> Dictionary:
 	)
 
 
+# One member of a class by name, wherever in its ancestry it is declared.
+#
+# The question a member is asked by name for is "does this engine have it, and what does it take":
+# the whole class in answer to that ran to seventy thousand characters for Control, and the member
+# is as often an ancestor's as the class's own, so the ancestry is walked without being asked. Each
+# match says which class declares it. Nothing found names the members whose names contain the one
+# asked for, since the usual miss is a spelling.
 func _member_of(class_name_str: String, member: String) -> Dictionary:
 	var found: Array[Dictionary] = []
 	var current: String = class_name_str
 	while not current.is_empty():
-		for m: Dictionary in _methods_of(current, false):
+		for m: Dictionary in _methods_of(current):
 			if m["name"] == member:
 				found.append({"kind": "method", "declared_in": current, "member": m})
-		for p: Dictionary in _properties_of(current, false):
+		for p: Dictionary in _properties_of(current):
 			if p["name"] == member:
 				found.append({"kind": "property", "declared_in": current, "member": p})
-		for s: Dictionary in _signals_of(current, false):
+		for s: Dictionary in _signals_of(current):
 			if s["name"] == member:
 				found.append({"kind": "signal", "declared_in": current, "member": s})
 		for e: String in ClassDB.class_get_enum_list(current, true):
@@ -251,15 +317,15 @@ func _members_alike(class_name_str: String, member: String) -> Array[String]:
 	var wanted: String = member.to_lower()
 	var current: String = class_name_str
 	while not current.is_empty():
-		for m: Dictionary in _methods_of(current, false):
+		for m: Dictionary in _methods_of(current):
 			var name: String = m["name"]
 			if name.to_lower().contains(wanted) and not alike.has(name):
 				alike.append(name)
-		for p: Dictionary in _properties_of(current, false):
+		for p: Dictionary in _properties_of(current):
 			var name: String = p["name"]
 			if name.to_lower().contains(wanted) and not alike.has(name):
 				alike.append(name)
-		for s: Dictionary in _signals_of(current, false):
+		for s: Dictionary in _signals_of(current):
 			var name: String = s["name"]
 			if name.to_lower().contains(wanted) and not alike.has(name):
 				alike.append(name)
@@ -275,7 +341,7 @@ func inspect_inheritance(params: Dictionary) -> Dictionary:
 	_log.info("Inspecting inheritance for: " + class_name_str)
 
 	if not ClassDB.class_exists(class_name_str):
-		return _not_found(class_name_str)
+		return _not_found(class_name_str, _declared_classes(params))
 
 	var ancestors: Array[String] = []
 	var current: String = class_name_str
@@ -324,10 +390,10 @@ func inspect_inheritance(params: Dictionary) -> Dictionary:
 	}
 
 
-func _methods_of(class_name_str: String, include_inherited: bool) -> Array[Dictionary]:
+func _methods_of(class_name_str: String) -> Array[Dictionary]:
 	var methods: Array[Dictionary] = []
 
-	for m: Dictionary in ClassDB.class_get_method_list(class_name_str, not include_inherited):
+	for m: Dictionary in ClassDB.class_get_method_list(class_name_str, true):
 		var args: Array[Dictionary] = []
 		var declared_args: Array = m.get("args", [])
 		for a: Dictionary in declared_args:
@@ -389,10 +455,10 @@ static func _type_name(info: Dictionary, nil_name: String) -> String:
 	return type_string(type)
 
 
-func _properties_of(class_name_str: String, include_inherited: bool) -> Array[Dictionary]:
+func _properties_of(class_name_str: String) -> Array[Dictionary]:
 	var properties: Array[Dictionary] = []
 
-	for p: Dictionary in ClassDB.class_get_property_list(class_name_str, not include_inherited):
+	for p: Dictionary in ClassDB.class_get_property_list(class_name_str, true):
 		# A category, group or subgroup is an editor heading rather than a property.
 		var usage: int = GdhRead.as_int(p.get("usage", 0))
 		if usage & PROPERTY_USAGE_CATEGORY or usage & PROPERTY_USAGE_GROUP or usage & PROPERTY_USAGE_SUBGROUP:
@@ -412,10 +478,10 @@ func _properties_of(class_name_str: String, include_inherited: bool) -> Array[Di
 	return properties
 
 
-func _signals_of(class_name_str: String, include_inherited: bool) -> Array[Dictionary]:
+func _signals_of(class_name_str: String) -> Array[Dictionary]:
 	var signals: Array[Dictionary] = []
 
-	for s: Dictionary in ClassDB.class_get_signal_list(class_name_str, not include_inherited):
+	for s: Dictionary in ClassDB.class_get_signal_list(class_name_str, true):
 		var sig_args: Array[Dictionary] = []
 		var declared_args: Array = s.get("args", [])
 		for a: Dictionary in declared_args:

package/build/godot/operations/declared_values.gd

@@ -85,6 +85,30 @@ static func engine_constants(target: Object, property: String) -> Dictionary:
 	return values
 
 
+## [param word] as the number of the value the enum property [param declared] of [param target]
+## names by it, as [true, number], or [false, why] naming the values, with [param holder] naming the
+## target in the refusal. [false, ""] for a word that is a number, which converts as one.
+##
+## An enum is written by the name of a value as well as its number, since the name is what the script
+## and the inspector show and the number is only where the value happens to sit. Tried as the script
+## spells it, then as the hint does, then as the engine's constant.
+static func enum_by_name(target: Object, declared: Dictionary, word: String, holder: String) -> Array:
+	var property: String = str(declared.get("name", ""))
+	var choices: Dictionary = enum_of(target, declared)
+	var chosen: Variant = enum_named(choices, word)
+	if chosen == null:
+		chosen = enum_named(enum_values(str(declared.get("hint_string", ""))), word)
+	var constants: Dictionary = {}
+	if chosen == null:
+		constants = engine_constants(target, property)
+		chosen = enum_named(constants, word)
+	if chosen != null:
+		return [true, chosen]
+	if word.strip_edges().is_valid_int():
+		return [false, ""]
+	return [false, enum_refusal(holder, property, word, choices, constants)]
+
+
 static func enum_refusal(
 	holder: String, property: String, word: String, choices: Dictionary, constants: Dictionary = {}
 ) -> String:

package/build/godot/operations/gdscript_authoring.gd

@@ -191,9 +191,13 @@ func modify_gdscript(params: Dictionary) -> Dictionary:
 
 	# All of them checked before any is made, so a call is made whole or not at all: one skipped for a
 	# missing name used to leave the rest written and the answer saying success over an empty list.
-	var problems: Array[String] = _modification_problems(modifications, _declared(lines))
+	var declared: Dictionary = _declared(lines)
+	var problems: Array[String] = _modification_problems(modifications, declared)
 	if not problems.is_empty():
-		return _log.failure("Nothing was changed: " + "; ".join(problems))
+		var refusal: String = "Nothing was changed: " + "; ".join(problems)
+		if _redeclares(modifications, declared):
+			refusal += ". modify only adds, so a member the script declares already is changed in the file itself"
+		return _log.failure(refusal)
 	# Each placed line as a zero-based index that moves down whenever a later insertion lands above
 	# it, so the numbers answered are where the lines are in the file written, not where each went
 	# at the moment it was placed.
@@ -414,6 +418,15 @@ static func _modification_problems(modifications: Array, declared: Dictionary) -
 	return problems
 
 
+static func _redeclares(modifications: Array, declared: Dictionary) -> bool:
+	for mod: Variant in modifications:
+		if mod is Dictionary:
+			var fields: Dictionary = mod
+			if declared.has(str(fields.get("name", ""))):
+				return true
+	return false
+
+
 # The members [param lines] declares at the top level, by name, as {"kind", "line"} counted from
 # one: variables, constants, signals, functions, enums and inner classes, which share one namespace.
 static func _declared(lines: Array[String]) -> Dictionary:

package/build/godot/operations/property_values.gd

@@ -420,25 +420,12 @@ func value_for(target: Object, declared: Dictionary, raw: Variant) -> Array:
 	var hint: int = GdhRead.as_int(declared.get("hint", PROPERTY_HINT_NONE))
 	if expected_type == TYPE_OBJECT and hint == PROPERTY_HINT_NODE_TYPE:
 		return _node_reference(target, property, raw)
-	# An enum is written by the name of a value as well as its number, since the name is what the
-	# script and the inspector show and the number is only where the value happens to sit.
 	if expected_type == TYPE_INT and hint == PROPERTY_HINT_ENUM and typeof(raw) == TYPE_STRING:
-		var choices: Dictionary = GdhDeclared.enum_of(target, declared)
-		var chosen: Variant = GdhDeclared.enum_named(choices, str(raw))
-		if chosen == null:
-			var hinted: Dictionary = GdhDeclared.enum_values(str(declared.get("hint_string", "")))
-			chosen = GdhDeclared.enum_named(hinted, str(raw))
-		var constants: Dictionary = {}
-		if chosen == null:
-			constants = GdhDeclared.engine_constants(target, property)
-			chosen = GdhDeclared.enum_named(constants, str(raw))
-		if chosen != null:
-			return [true, chosen]
-		if not str(raw).strip_edges().is_valid_int():
-			var why: String = GdhDeclared.enum_refusal(
-				GdhPropertyPaths.class_called(target), property, str(raw), choices, constants
-			)
-			return [false, why]
+		var by_name: Array = GdhDeclared.enum_by_name(
+			target, declared, str(raw), GdhPropertyPaths.class_called(target)
+		)
+		if by_name[0] or not str(by_name[1]).is_empty():
+			return by_name
 
 	# A resource-valued property takes the path of one, which is how a caller names a TileSet,
 	# a material or a theme: there is no other way to hand a tool a Resource.