gdharness 1.2.30 → 1.2.31

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

@@ -4,6 +4,7 @@ extends RefCounted
 ## run off the game the node keeps. Every op that reads, writes, calls or waits on a game's state
 ## walks the same way, so the walk and what it says when a step is not there live in one place.
 
+const Serialisation = preload("serialisation.gd")
 const Values = preload("runtime_values.gd")
 
 ## The calls a path makes on a list or a map: those that take no arguments and change nothing.
@@ -95,7 +96,7 @@ const READS_ONLY: String = ", and a path, which a wait reads every frame, only c
 ##
 ## A step into a vector, a colour, a rectangle or a transform reads one of its components,
 ## "size:x" or "global_transform:origin:y", by the names GDScript gives them; see
-## [method Values.components_of].
+## [method Serialisation.components_of].
 ##
 ## Answers with a `message` instead when a step along the way is not there or holds something that
 ## is not an object, naming the step rather than the whole path: "/root/Main:_game has no property
@@ -184,7 +185,7 @@ static func can_hold(value: Variant) -> bool:
 ## Whether [param value] is read by its components, a vector or a colour or a transform, and is a
 ## copy wherever it is read from.
 static func composite(value: Variant) -> bool:
-	return not Values.components_of(value).is_empty()
+	return not Serialisation.components_of(value).is_empty()
 
 
 ## Whether [param value] is a packed list. Stepped into the way a list is, by index, and a write into
@@ -234,7 +235,7 @@ static func can_read(holder: Variant, named: String) -> bool:
 			return args.is_empty() and method in MAP_CALLS
 		return not _key_in(map, named).is_empty()
 	if composite(holder):
-		return method.is_empty() and named in Values.components_of(holder)
+		return method.is_empty() and named in Serialisation.components_of(holder)
 	if holder is Object:
 		var object: Object = holder
 		if not method.is_empty():
@@ -586,7 +587,7 @@ static func nothing_there(holder: Variant, named: String, called_as: String) ->
 	if composite(holder):
 		var kind: String = type_string(typeof(holder))
 		var sort: String = ("an " if kind.left(1) in ["A", "E", "I", "O", "U"] else "a ") + kind
-		var has: String = ", ".join(Values.components_of(holder))
+		var has: String = ", ".join(Serialisation.components_of(holder))
 		if not container_call.is_empty():
 			return (
 				"%s is %s, which a path reads by its components, %s, and makes no call on"

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

@@ -189,52 +189,6 @@ func parameter_class(object: Object, method: String, index: int) -> String:
 	return ""
 
 
-## The components a path reads off [param value], by the names GDScript gives them, or none for a
-## value that has none: a vector's axes, a colour's channels, a rectangle's corners and size, a
-## transform's basis and origin. A value of one of these is a copy wherever it is read, so a write
-## into a component is a write into the copy until it is put back where it was read from.
-static func components_of(value: Variant) -> PackedStringArray:
-	match typeof(value):
-		TYPE_VECTOR2, TYPE_VECTOR2I:
-			return PackedStringArray(["x", "y"])
-		TYPE_VECTOR3, TYPE_VECTOR3I:
-			return PackedStringArray(["x", "y", "z"])
-		TYPE_VECTOR4, TYPE_VECTOR4I, TYPE_QUATERNION:
-			return PackedStringArray(["x", "y", "z", "w"])
-		TYPE_COLOR:
-			return PackedStringArray(
-				[
-					"r",
-					"g",
-					"b",
-					"a",
-					"r8",
-					"g8",
-					"b8",
-					"a8",
-					"h",
-					"s",
-					"v",
-					"ok_hsl_h",
-					"ok_hsl_s",
-					"ok_hsl_l"
-				]
-			)
-		TYPE_RECT2, TYPE_RECT2I, TYPE_AABB:
-			return PackedStringArray(["position", "size", "end"])
-		TYPE_PLANE:
-			return PackedStringArray(["normal", "x", "y", "z", "d"])
-		TYPE_BASIS:
-			return PackedStringArray(["x", "y", "z"])
-		TYPE_TRANSFORM2D:
-			return PackedStringArray(["x", "y", "origin"])
-		TYPE_TRANSFORM3D:
-			return PackedStringArray(["basis", "origin"])
-		TYPE_PROJECTION:
-			return PackedStringArray(["x", "y", "z", "w"])
-	return PackedStringArray()
-
-
 ## What the slot [param named] on [param holder] declares it holds, as `{"type": int, "class":
 ## String, "script": Script or null}`: a property's declaration, or the element type of a typed list
 ## or the value type of a typed map. TYPE_NIL when nothing is declared, which is also what a
@@ -250,7 +204,7 @@ static func components_of(value: Variant) -> PackedStringArray:
 static func slot_declared(holder: Variant, named: String) -> Dictionary:
 	# A component holds one kind of value and no other: a vector's axis is a number, its integer
 	# form's an integer, a rectangle's size a vector of the same form.
-	if named in components_of(holder):
+	if named in Serialisation.components_of(holder):
 		var component: Variant = holder[named]
 		return {"type": typeof(component), "class": "", "script": null}
 	if holder is Array:

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

@@ -246,6 +246,52 @@ func deserialize_value(value: Variant) -> Variant:
 	return call(builder, fields)
 
 
+## The components a path reads off [param value], by the names GDScript gives them, or none for a
+## value that has none: a vector's axes, a colour's channels, a rectangle's corners and size, a
+## transform's basis and origin. A value of one of these is a copy wherever it is read, so a write
+## into a component is a write into the copy until it is put back where it was read from.
+static func components_of(value: Variant) -> PackedStringArray:
+	match typeof(value):
+		TYPE_VECTOR2, TYPE_VECTOR2I:
+			return PackedStringArray(["x", "y"])
+		TYPE_VECTOR3, TYPE_VECTOR3I:
+			return PackedStringArray(["x", "y", "z"])
+		TYPE_VECTOR4, TYPE_VECTOR4I, TYPE_QUATERNION:
+			return PackedStringArray(["x", "y", "z", "w"])
+		TYPE_COLOR:
+			return PackedStringArray(
+				[
+					"r",
+					"g",
+					"b",
+					"a",
+					"r8",
+					"g8",
+					"b8",
+					"a8",
+					"h",
+					"s",
+					"v",
+					"ok_hsl_h",
+					"ok_hsl_s",
+					"ok_hsl_l"
+				]
+			)
+		TYPE_RECT2, TYPE_RECT2I, TYPE_AABB:
+			return PackedStringArray(["position", "size", "end"])
+		TYPE_PLANE:
+			return PackedStringArray(["normal", "x", "y", "z", "d"])
+		TYPE_BASIS:
+			return PackedStringArray(["x", "y", "z"])
+		TYPE_TRANSFORM2D:
+			return PackedStringArray(["x", "y", "origin"])
+		TYPE_TRANSFORM3D:
+			return PackedStringArray(["basis", "origin"])
+		TYPE_PROJECTION:
+			return PackedStringArray(["x", "y", "z", "w"])
+	return PackedStringArray()
+
+
 ## Whether [param entries] is a list of [key, value] pairs, as a Dictionary tag carries them.
 static func pairs(entries: Variant) -> bool:
 	if not entries is Array:

package/build/godot/operations/audio_buses.gd

@@ -83,7 +83,20 @@ func get_audio_buses(_params: Dictionary) -> Dictionary:
 	var buses: Array[Dictionary] = []
 	for i: int in range(AudioServer.bus_count):
 		buses.append(_bus(i))
-	return {"bus_count": AudioServer.bus_count, "buses": buses, "layout": _layout_path()}
+	var layout: String = _layout_path()
+	var answer: Dictionary = {"bus_count": AudioServer.bus_count, "buses": buses, "layout": layout}
+	# The setting names a path whether or not anything is there, and a project that never changed a
+	# bus has no file: the path alone read as a layout the project keeps.
+	if not FileAccess.file_exists(layout):
+		answer["layout_on_disk"] = false
+		answer["note"] = (
+			(
+				"Nothing is at %s, so these are the engine's default buses; the first change to a bus "
+				+ "writes the layout there."
+			)
+			% layout
+		)
+	return answer
 
 
 func set_audio_bus_effect(params: Dictionary) -> Dictionary:

package/build/godot/operations/class_cache.gd

@@ -93,13 +93,13 @@ func _entry_for(path: String, skipped: Array[Dictionary]) -> Dictionary:
 	if declared.is_empty():
 		return {}
 
-	var base: String = _base_of(path, header, skipped)
-	if base.is_empty():
+	var base: Variant = _base_of(path, header, skipped)
+	if base == null:
 		return {}
 
 	# The field order is the editor's, so a rebuilt file reads as one the editor wrote.
 	return {
-		"base": StringName(base),
+		"base": StringName(str(base)),
 		"class": StringName(declared),
 		"icon": str(header.get("icon", "")),
 		"is_abstract": Read.as_bool(header.get("abstract", false)),
@@ -109,46 +109,157 @@ func _entry_for(path: String, skipped: Array[Dictionary]) -> Dictionary:
 	}
 
 
-# What the editor records as the base: the nearest ancestor with a class_name, else the native
-# class at the top of the chain. A script that extends by path is followed to its own header.
-func _base_of(path: String, header: Dictionary, skipped: Array[Dictionary]) -> String:
-	var visited: Array[String] = [path]
-	var current: Dictionary = header
+# What the editor records as the base, worked out as the engine's own class scan works it out,
+# measured on 4.7.2 against `--import`, so a rebuilt list is the one the editor would write and a
+# rebuild over a current list changes nothing:
+#
+# - nothing extended: RefCounted;
+# - one name, a global class or a native one: that name, unresolved;
+# - a dotted name, `Heard.Named`, an inner class of a global class: nothing, as the scan does not
+#   look names up;
+# - a path: what that script's class records, after walking into the inner classes named after
+#   the path, `"res://heard.gd".Named`, so a parent with a class_name is passed over for its own
+#   base. A path the engine cannot open records nothing, and it opens a relative one from the
+#   project root rather than from the script's folder.
+#
+# Null for a script that extends itself, which is left out of the list and named in [param skipped].
+func _base_of(path: String, header: Dictionary, skipped: Array[Dictionary]) -> Variant:
+	var visited: Array[String] = [path + ":"]
+	var extends_what: Variant = header.get("extends", null)
 	while true:
-		var extends_what: String = str(current.get("extends", ""))
-		if extends_what.is_empty():
+		if extends_what == null:
 			return "RefCounted"
-		if not (extends_what.begins_with('"') or extends_what.begins_with("'")):
-			return extends_what
-		var parent_path: String = extends_what.substr(1, extends_what.length() - 2)
-		if not parent_path.begins_with("res://"):
-			parent_path = visited[visited.size() - 1].get_base_dir().path_join(parent_path)
-		if not FileAccess.file_exists(parent_path):
-			skipped.append({"path": path, "reason": "extends a script that does not exist: " + parent_path})
+		var parts: Dictionary = _extends_parts(str(extends_what))
+		var parent_path: String = parts["path"]
+		var names: Array[String] = parts["names"]
+		if parent_path.is_empty():
+			return names[0] if names.size() == 1 else ""
+		var opened: String = _as_the_engine_opens(parent_path)
+		if not FileAccess.file_exists(opened):
 			return ""
-		if parent_path in visited:
+		var reached: String = opened + ":" + ".".join(PackedStringArray(names))
+		if reached in visited:
 			skipped.append({"path": path, "reason": "extends itself through " + parent_path})
+			return null
+		visited.append(reached)
+		var lines: PackedStringArray = FileAccess.get_file_as_string(opened).split("\n")
+		if names.is_empty():
+			extends_what = _header_in(lines).get("extends", null)
+			continue
+		var inner: Dictionary = _inner_class(lines, names)
+		if inner.is_empty():
 			return ""
-		visited.append(parent_path)
-		current = _header_of(parent_path)
-		var parent_name: String = str(current.get("class_name", ""))
-		if not parent_name.is_empty():
-			return parent_name
+		extends_what = inner.get("extends", null)
 	return ""
 
 
-# The declarations at the top of a script: class_name, what it extends (a class name, or a
-# quoted path), and the @tool, @abstract and @icon annotations. Reading stops at the first
-# statement that is none of those, which is where the body begins.
+# The path and the class names an `extends` names, from the text after the keyword:
+# `"res://heard.gd".Named` is the path and ["Named"], `Heard.Named` no path and two names. The
+# reading stops at whatever follows, a colon or a comment.
+static func _extends_parts(text: String) -> Dictionary:
+	var rest: String = text.strip_edges()
+	var path: String = ""
+	if rest.begins_with('"') or rest.begins_with("'"):
+		var closing: int = rest.find(rest[0], 1)
+		if closing == -1:
+			return {"path": "", "names": [] as Array[String]}
+		path = rest.substr(1, closing - 1)
+		rest = rest.substr(closing + 1)
+	var names: Array[String] = []
+	var name_at: RegEx = Patterns.compiled("^([A-Za-z_][A-Za-z0-9_]*)")
+	var dotted: bool = not path.is_empty()
+	while true:
+		if dotted:
+			if not rest.begins_with("."):
+				break
+			rest = rest.substr(1)
+		dotted = true
+		var found: RegExMatch = name_at.search(rest)
+		if found == null:
+			break
+		names.append(found.get_string(1))
+		rest = rest.substr(found.get_end())
+	return {"path": path, "names": names}
+
+
+# The file the engine's class scan reads for an `extends` path. It opens the path as written, and
+# the engine runs from the project root, so a relative path is read from there.
+static func _as_the_engine_opens(path: String) -> String:
+	if path.is_absolute_path():
+		return path
+	var absolute: String = ProjectSettings.globalize_path("res://").path_join(path).simplify_path()
+	return ProjectSettings.localize_path(absolute)
+
+
+# The inner class [param names] reaches in a script of [param lines], one class inside the
+# previous, as {"found": true, "extends": the text after its keyword} with no "extends" for one that
+# extends nothing, or {} when one of them is not there.
+func _inner_class(lines: PackedStringArray, names: Array[String]) -> Dictionary:
+	var class_line: RegEx = Patterns.compiled("^class\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*(.*)$")
+	var inline_extends: RegEx = Patterns.compiled("^extends\\s+(.*)$")
+	var start: int = 0
+	var end: int = lines.size()
+	var depth: int = 0
+	var found: Dictionary = {}
+	for name: String in names:
+		var at: int = -1
+		found = {"found": true}
+		for index: int in range(start, end):
+			var text: String = lines[index].strip_edges()
+			if text.is_empty() or text.begins_with("#") or _indent(lines[index]) != depth:
+				continue
+			var declared: RegExMatch = class_line.search(text)
+			if declared == null or declared.get_string(1) != name:
+				continue
+			at = index
+			var inline: RegExMatch = inline_extends.search(declared.get_string(2).strip_edges())
+			if inline != null:
+				found["extends"] = inline.get_string(1)
+			break
+		if at == -1:
+			return {}
+		start = at + 1
+		var body_end: int = start
+		var body_depth: int = -1
+		for index: int in range(start, end):
+			var text: String = lines[index].strip_edges()
+			if not text.is_empty() and not text.begins_with("#"):
+				var width: int = _indent(lines[index])
+				if width <= depth:
+					break
+				if body_depth == -1:
+					body_depth = width
+			body_end = index + 1
+		end = body_end
+		depth = body_depth
+		if not found.has("extends"):
+			var body: Dictionary = _header_in(lines.slice(start, end))
+			if body.has("extends"):
+				found["extends"] = body["extends"]
+	return found
+
+
+static func _indent(line: String) -> int:
+	return line.length() - line.lstrip(" \t").length()
+
+
 func _header_of(path: String) -> Dictionary:
+	if not FileAccess.file_exists(path):
+		return {}
+	return _header_in(FileAccess.get_file_as_string(path).split("\n"))
+
+
+# The declarations at the top of a script: class_name, what it extends (the text after the
+# keyword, a class name or a quoted path, either followed by inner class names), and the @tool,
+# @abstract and @icon annotations. Reading stops at the first statement that is none of those,
+# which is where the body begins.
+func _header_in(lines: PackedStringArray) -> Dictionary:
 	var header: Dictionary = {}
-	var file: FileAccess = FileAccess.open(path, FileAccess.READ)
-	if not file:
-		return header
 	var annotation: RegEx = Patterns.compiled('^@([a-z_]+)(?:\\(\\s*(?:"([^"]*)")?[^)]*\\))?\\s*')
-	var extends_line: RegEx = Patterns.compiled("^extends\\s+(\\S+)")
-	while not file.eof_reached():
-		var rest: String = file.get_line().strip_edges()
+	var extends_line: RegEx = Patterns.compiled("^extends\\s+(.*)$")
+	var same_line: RegEx = Patterns.compiled("^\\s+extends\\s+(.*)$")
+	for line: String in lines:
+		var rest: String = line.strip_edges()
 		# Annotations may share a line with what they annotate, as in `@abstract class_name X`.
 		var annotated: RegExMatch = annotation.search(rest)
 		while annotated != null:
@@ -167,15 +278,15 @@ func _header_of(path: String) -> Dictionary:
 			var declared: RegExMatch = Patterns.declared_class(rest)
 			if declared != null:
 				header["class_name"] = declared.get_string(1)
-				if not declared.get_string(2).is_empty():
-					header["extends"] = declared.get_string(2)
+				var after: RegExMatch = same_line.search(rest.substr(declared.get_end(1)))
+				if after != null:
+					header["extends"] = after.get_string(1)
 		elif rest.begins_with("extends"):
 			var parent: RegExMatch = extends_line.search(rest)
 			if parent != null:
 				header["extends"] = parent.get_string(1)
 		else:
 			break
-	file.close()
 	return header
 
 

package/build/godot/operations/classdb_queries.gd

@@ -2,6 +2,7 @@ extends RefCounted
 
 const Read = preload("reading.gd")
 const Log = preload("logger.gd")
+const Serialisation = preload("serialisation.gd")
 
 # 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
@@ -22,6 +23,7 @@ const CATEGORY_BASES: Dictionary = {
 }
 
 var _log: Log
+var _values: Serialisation = Serialisation.new()
 
 
 func _init(p_log: Log) -> void:
@@ -318,19 +320,24 @@ func _methods_of(class_name_str: String, include_inherited: bool) -> Array[Dicti
 				}
 			)
 		var return_info: Dictionary = m.get("return", {})
-		methods.append(
-			{
-				"name": m.get("name", ""),
-				"args": args,
-				"return":
+		(
+			methods
+			. append(
 				{
-					"type": return_info.get("type", 0),
-					"type_name": _type_name(return_info, "void"),
-					"class_name": return_info.get("class_name", "")
-				},
-				"flags": m.get("flags", 0),
-				"default_args": m.get("default_args", [])
-			}
+					"name": m.get("name", ""),
+					"args": args,
+					"return":
+					{
+						"type": return_info.get("type", 0),
+						"type_name": _type_name(return_info, "void"),
+						"class_name": return_info.get("class_name", "")
+					},
+					"flags": 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", []))
+				}
+			)
 		)
 
 	return methods

package/build/godot/operations/project_config.gd

@@ -117,12 +117,7 @@ func set_project_setting(params: Dictionary) -> Dictionary:
 	var wanted: int = _wanted_type(setting_path, old_value if had_value else null)
 	if wanted > TYPE_NIL and final_value != null and typeof(final_value) != wanted:
 		if not _converts_faithfully(final_value, wanted):
-			return _log.failure(
-				(
-					"%s is declared as %s, and %s (%s) cannot be written as that without losing something."
-					% [setting_path, type_string(wanted), str(final_value), type_string(typeof(final_value))]
-				)
-			)
+			return _log.failure(_cannot_hold(setting_path, wanted, final_value))
 		final_value = type_convert(final_value, wanted)
 
 	var answer: Dictionary = {
@@ -174,6 +169,21 @@ func _converts_faithfully(value: Variant, to: int) -> bool:
 	return type_convert(type_convert(value, to), typeof(value)) == value
 
 
+# Why [param value] cannot be written to a setting declared as [param wanted], in the words the
+# editor's property writes use for the same two cases. One sentence for both read "without losing
+# something" about a word given for a number, where nothing would be lost: it cannot become one.
+static func _cannot_hold(setting_path: String, wanted: int, value: Variant) -> String:
+	var numbers: Array[int] = [TYPE_INT, TYPE_FLOAT]
+	var declared: String = "%s is declared as %s" % [setting_path, type_string(wanted)]
+	var cost: String = " Setting it would save a different value than the one asked for."
+	if wanted == TYPE_INT and typeof(value) == TYPE_FLOAT:
+		return "%s, which holds whole numbers, and %s would be cut to fit.%s" % [declared, str(value), cost]
+	if wanted in numbers and typeof(value) in numbers:
+		return "%s, and %s is not the same number as one.%s" % [declared, str(value), cost]
+	var given: String = type_string(typeof(value))
+	return "%s, and %s (%s) cannot become one." % [declared, JSON.stringify(value), given]
+
+
 # Add an autoload singleton
 func add_autoload(params: Dictionary) -> Dictionary:
 	var name: String = str(params.get("name", ""))

package/build/godot/operations/serialisation.gd

@@ -246,6 +246,52 @@ func deserialize_value(value: Variant) -> Variant:
 	return call(builder, fields)
 
 
+## The components a path reads off [param value], by the names GDScript gives them, or none for a
+## value that has none: a vector's axes, a colour's channels, a rectangle's corners and size, a
+## transform's basis and origin. A value of one of these is a copy wherever it is read, so a write
+## into a component is a write into the copy until it is put back where it was read from.
+static func components_of(value: Variant) -> PackedStringArray:
+	match typeof(value):
+		TYPE_VECTOR2, TYPE_VECTOR2I:
+			return PackedStringArray(["x", "y"])
+		TYPE_VECTOR3, TYPE_VECTOR3I:
+			return PackedStringArray(["x", "y", "z"])
+		TYPE_VECTOR4, TYPE_VECTOR4I, TYPE_QUATERNION:
+			return PackedStringArray(["x", "y", "z", "w"])
+		TYPE_COLOR:
+			return PackedStringArray(
+				[
+					"r",
+					"g",
+					"b",
+					"a",
+					"r8",
+					"g8",
+					"b8",
+					"a8",
+					"h",
+					"s",
+					"v",
+					"ok_hsl_h",
+					"ok_hsl_s",
+					"ok_hsl_l"
+				]
+			)
+		TYPE_RECT2, TYPE_RECT2I, TYPE_AABB:
+			return PackedStringArray(["position", "size", "end"])
+		TYPE_PLANE:
+			return PackedStringArray(["normal", "x", "y", "z", "d"])
+		TYPE_BASIS:
+			return PackedStringArray(["x", "y", "z"])
+		TYPE_TRANSFORM2D:
+			return PackedStringArray(["x", "y", "origin"])
+		TYPE_TRANSFORM3D:
+			return PackedStringArray(["basis", "origin"])
+		TYPE_PROJECTION:
+			return PackedStringArray(["x", "y", "z", "w"])
+	return PackedStringArray()
+
+
 ## Whether [param entries] is a list of [key, value] pairs, as a Dictionary tag carries them.
 static func pairs(entries: Variant) -> bool:
 	if not entries is Array: