gdharness 1.3.0 → 1.3.2

package/build/godot/operations/script_check.gd

@@ -13,17 +13,17 @@ extends RefCounted
 ## 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")
+const GdhRead = preload("reading.gd")
+const GdhLog = preload("logger.gd")
 
 ## Where the engine raises a script's compile errors from.
 const RELOAD: String = "GDScript::reload"
 
-var _log: Log
+var _log: GdhLog
 
 
 ## Every compile error the engine raises while it is attached, in order.
-class Caught:
+class GdhCaught:
 	extends Logger
 
 	var raised: Array[Dictionary] = []
@@ -50,10 +50,26 @@ class Caught:
 		)
 
 
-func _init(p_log: Log) -> void:
+func _init(p_log: GdhLog) -> void:
 	_log = p_log
 
 
+## One line for [param failure], a script [method check_scripts] answered as failing, with its
+## first error and the note the server put on it.
+static func failure_line(failure: Dictionary) -> String:
+	var errors: Array = failure.get("errors", [])
+	var said: String = "%s does not compile" % str(failure.get("path", ""))
+	if not errors.is_empty():
+		var first: Dictionary = errors[0]
+		var line: int = GdhRead.as_int(first.get("line", 0))
+		var message: String = str(first.get("message", ""))
+		said += ": line %d, %s" % [line, message] if line > 0 else ": " + message
+		if errors.size() > 1:
+			said += " (and %d more)" % (errors.size() - 1)
+	var note: String = str(failure.get("note", ""))
+	return said if note.is_empty() else "%s %s" % [said, note]
+
+
 ## 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]
@@ -62,7 +78,7 @@ func _init(p_log: Log) -> void:
 ## 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()
+	var caught: GdhCaught = GdhCaught.new()
 	OS.add_logger(caught)
 	var checked: Array[String] = []
 	var failed: Array[String] = []
@@ -80,7 +96,7 @@ func check_scripts(params: Dictionary) -> Dictionary:
 				if not at in others:
 					others.append(at)
 				continue
-			var found: Dictionary = {"line": Read.as_int(error["line"]), "message": str(error["message"])}
+			var found: Dictionary = {"line": GdhRead.as_int(error["line"]), "message": str(error["message"])}
 			if not found in errors:
 				errors.append(found)
 		if loaded == null and errors.is_empty():

package/build/godot/operations/serialisation.gd

@@ -8,7 +8,8 @@ extends RefCounted
 ## before: the same Vector2 came back three ways depending on which tool was asked, and a caller
 ## reading a property off the editor could not feed it back to the game.
 
-const Read = preload("reading.gd")
+const GdhRead = preload("reading.gd")
+const GdhShapes = preload("value_shapes.gd")
 
 # What the engine carries from one to another without complaint, which is what a value written to a
 # property or handed to a parameter may arrive as. Numbers include bool because the engine counts it
@@ -120,35 +121,6 @@ const BUILDERS: Dictionary = {
 	"Dictionary": "_build_dictionary",
 }
 
-# What each tag has to carry before it is built. A tag naming a type whose keys are not there is a
-# tag somebody wrote by mistake or wrote for a different shape, and building one out of defaults
-# answers with a Transform2D of zeros where the caller meant something else entirely. Unbuilt, it
-# comes back as it arrived, and whoever asked can read it against the type they were expecting.
-const REQUIRED: Dictionary = {
-	"Vector2": [["x", "y"]],
-	"Vector2i": [["x", "y"]],
-	"Vector3": [["x", "y", "z"]],
-	"Vector3i": [["x", "y", "z"]],
-	"Vector4": [["x", "y", "z", "w"]],
-	"Vector4i": [["x", "y", "z", "w"]],
-	"Rect2": [["position", "size"], ["x", "y", "width", "height"]],
-	"Rect2i": [["position", "size"], ["x", "y", "width", "height"]],
-	"Plane": [["normal", "d"]],
-	"Quaternion": [["x", "y", "z", "w"]],
-	"AABB": [["position", "size"]],
-	"Basis": [["x", "y", "z"]],
-	"Transform2D": [["x", "y", "origin"]],
-	"Transform3D": [["basis", "origin"]],
-	"Projection": [["x", "y", "z", "w"]],
-	"Color": [["r", "g", "b"]],
-	"NodePath": [["path"]],
-	"PackedByteArray": [["base64"]],
-	"float": [["value"]],
-	"int": [["value"]],
-	"RID": [["id"]],
-	"Dictionary": [["entries"]],
-}
-
 
 # Converts a Godot value into something JSON can carry. A type with no entry in the table
 # passes through as itself, which is what the JSON-native ones want.
@@ -246,8 +218,8 @@ func deserialize_value(value: Variant) -> Variant:
 	# under the target project's warning levels, so one such project lost every headless call.
 	var tag: String = str(fields["_type"])
 	var builder: String = BUILDERS.get(tag, "")
-	var needed: Array = REQUIRED.get(tag, [])
-	if builder.is_empty() or not _carries(fields, needed):
+	var spare: Array = GdhShapes.spare(fields, tag)
+	if builder.is_empty() or not spare.any(func(left: Array) -> bool: return left.is_empty()):
 		return fields
 	if tag == "float" and str(fields["value"]) not in ["inf", "-inf", "nan"]:
 		return fields
@@ -430,9 +402,18 @@ func fitted(value: Variant, type: int) -> Variant:
 	if rebuilt is Array and LIST_TYPES.has(type):
 		return type_convert(rebuilt, type)
 
+	# The inspector and every colour picker give a colour as its html code. Anything else stays the
+	# text it is, for the refusal to name.
+	if type == TYPE_COLOR and rebuilt is String and Color.html_is_valid(str(rebuilt)):
+		return Color.html(str(rebuilt))
+
 	var simple: Array[int] = [TYPE_BOOL, TYPE_INT, TYPE_FLOAT, TYPE_STRING]
 	if not simple.has(type) or not simple.has(typeof(rebuilt)):
 		return rebuilt
+	# A number or a truth value stays as sent where text is wanted, for the refusal to name. Converted,
+	# 1 arrived as the double it is in JSON and was saved as "1.0", which is not the text anyone sends.
+	if type == TYPE_STRING and not rebuilt is String:
+		return rebuilt
 
 	# Digits are read as digits, since read as JSON they become a double and one past 2^53 a
 	# neighbour of the number written.
@@ -441,7 +422,7 @@ func fitted(value: Variant, type: int) -> Variant:
 
 	if rebuilt is String and type != TYPE_STRING:
 		var text: String = rebuilt
-		var parsed: Variant = Read.json_or_null(text)
+		var parsed: Variant = GdhRead.json_or_null(text)
 		# A string that does not read as the type wanted is handed back as the string it is, so
 		# whoever asked can refuse it. type_convert answers 0 for "not an index" and true for any
 		# text at all, and a caller who sent a word got back a number they never sent: get_child
@@ -461,7 +442,7 @@ func fitted(value: Variant, type: int) -> Variant:
 static func inexact(given: Variant, type: int) -> String:
 	if type != TYPE_INT or (typeof(given) != TYPE_FLOAT and typeof(given) != TYPE_INT):
 		return ""
-	var number: float = Read.as_float(given)
+	var number: float = GdhRead.as_float(given)
 	if not is_finite(number) or absf(number) < EXACT:
 		return ""
 	return (
@@ -474,34 +455,6 @@ static func inexact(given: Variant, type: int) -> String:
 	)
 
 
-## How a value of [param type] is written to be read as one, for a refusal to name, or empty for a
-## type that is not built from fields. A refusal naming only the two types left a caller to find
-## the shape in the description of another op.
-static func written_as(type: int) -> String:
-	var tag: String = type_string(type)
-	var alternatives: Array = REQUIRED.get(tag, [])
-	if alternatives.is_empty() or tag in ["float", "int", "Dictionary"]:
-		return ""
-	var keys: Array = alternatives[0]
-	var parts: Array[String] = []
-	for key: Variant in keys:
-		parts.append('"%s": ...' % key)
-	return "{%s}" % ", ".join(parts)
-
-
-## Whether [param fields] carries every key of any one of [param alternatives].
-##
-## More than one spelling because a rectangle has two: the two corners it is answered with, and the
-## four numbers the editor's own tools answered with before the serialisers were made one, which a
-## caller may have kept.
-func _carries(fields: Dictionary, alternatives: Array) -> bool:
-	for alternative: Variant in alternatives:
-		var keys: Array = alternative
-		if keys.all(func(key: Variant) -> bool: return fields.has(key)):
-			return true
-	return false
-
-
 func _serialize_nil(_value: Variant) -> Variant:
 	return null
 
@@ -769,42 +722,44 @@ func _describe_object(value: Object) -> Dictionary:
 
 
 func _build_vector2(fields: Dictionary) -> Vector2:
-	return Vector2(Read.as_float(fields.get("x", 0)), Read.as_float(fields.get("y", 0)))
+	return Vector2(GdhRead.as_float(fields.get("x", 0)), GdhRead.as_float(fields.get("y", 0)))
 
 
 func _build_vector2i(fields: Dictionary) -> Vector2i:
-	return Vector2i(Read.as_int(fields.get("x", 0)), Read.as_int(fields.get("y", 0)))
+	return Vector2i(GdhRead.as_int(fields.get("x", 0)), GdhRead.as_int(fields.get("y", 0)))
 
 
 func _build_vector3(fields: Dictionary) -> Vector3:
 	return Vector3(
-		Read.as_float(fields.get("x", 0)),
-		Read.as_float(fields.get("y", 0)),
-		Read.as_float(fields.get("z", 0))
+		GdhRead.as_float(fields.get("x", 0)),
+		GdhRead.as_float(fields.get("y", 0)),
+		GdhRead.as_float(fields.get("z", 0))
 	)
 
 
 func _build_vector3i(fields: Dictionary) -> Vector3i:
 	return Vector3i(
-		Read.as_int(fields.get("x", 0)), Read.as_int(fields.get("y", 0)), Read.as_int(fields.get("z", 0))
+		GdhRead.as_int(fields.get("x", 0)),
+		GdhRead.as_int(fields.get("y", 0)),
+		GdhRead.as_int(fields.get("z", 0))
 	)
 
 
 func _build_vector4(fields: Dictionary) -> Vector4:
 	return Vector4(
-		Read.as_float(fields.get("x", 0)),
-		Read.as_float(fields.get("y", 0)),
-		Read.as_float(fields.get("z", 0)),
-		Read.as_float(fields.get("w", 0))
+		GdhRead.as_float(fields.get("x", 0)),
+		GdhRead.as_float(fields.get("y", 0)),
+		GdhRead.as_float(fields.get("z", 0)),
+		GdhRead.as_float(fields.get("w", 0))
 	)
 
 
 func _build_vector4i(fields: Dictionary) -> Vector4i:
 	return Vector4i(
-		Read.as_int(fields.get("x", 0)),
-		Read.as_int(fields.get("y", 0)),
-		Read.as_int(fields.get("z", 0)),
-		Read.as_int(fields.get("w", 0))
+		GdhRead.as_int(fields.get("x", 0)),
+		GdhRead.as_int(fields.get("y", 0)),
+		GdhRead.as_int(fields.get("z", 0)),
+		GdhRead.as_int(fields.get("w", 0))
 	)
 
 
@@ -813,10 +768,10 @@ func _build_vector4i(fields: Dictionary) -> Vector4i:
 func _build_rect2(fields: Dictionary) -> Rect2:
 	if not fields.has("position"):
 		return Rect2(
-			Read.as_float(fields.get("x", 0)),
-			Read.as_float(fields.get("y", 0)),
-			Read.as_float(fields.get("width", 0)),
-			Read.as_float(fields.get("height", 0))
+			GdhRead.as_float(fields.get("x", 0)),
+			GdhRead.as_float(fields.get("y", 0)),
+			GdhRead.as_float(fields.get("width", 0)),
+			GdhRead.as_float(fields.get("height", 0))
 		)
 	return Rect2(_vector2_at(fields, "position"), _vector2_at(fields, "size"))
 
@@ -824,24 +779,24 @@ func _build_rect2(fields: Dictionary) -> Rect2:
 func _build_rect2i(fields: Dictionary) -> Rect2i:
 	if not fields.has("position"):
 		return Rect2i(
-			Read.as_int(fields.get("x", 0)),
-			Read.as_int(fields.get("y", 0)),
-			Read.as_int(fields.get("width", 0)),
-			Read.as_int(fields.get("height", 0))
+			GdhRead.as_int(fields.get("x", 0)),
+			GdhRead.as_int(fields.get("y", 0)),
+			GdhRead.as_int(fields.get("width", 0)),
+			GdhRead.as_int(fields.get("height", 0))
 		)
 	return Rect2i(_vector2i_at(fields, "position"), _vector2i_at(fields, "size"))
 
 
 func _build_plane(fields: Dictionary) -> Plane:
-	return Plane(_vector3_at(fields, "normal"), Read.as_float(fields.get("d", 0)))
+	return Plane(_vector3_at(fields, "normal"), GdhRead.as_float(fields.get("d", 0)))
 
 
 func _build_quaternion(fields: Dictionary) -> Quaternion:
 	return Quaternion(
-		Read.as_float(fields.get("x", 0)),
-		Read.as_float(fields.get("y", 0)),
-		Read.as_float(fields.get("z", 0)),
-		Read.as_float(fields.get("w", 0))
+		GdhRead.as_float(fields.get("x", 0)),
+		GdhRead.as_float(fields.get("y", 0)),
+		GdhRead.as_float(fields.get("z", 0)),
+		GdhRead.as_float(fields.get("w", 0))
 	)
 
 
@@ -881,10 +836,10 @@ func _build_projection(fields: Dictionary) -> Projection:
 
 func _build_color(fields: Dictionary) -> Color:
 	return Color(
-		Read.as_float(fields.get("r", 0)),
-		Read.as_float(fields.get("g", 0)),
-		Read.as_float(fields.get("b", 0)),
-		Read.as_float(fields.get("a", 1), 1.0)
+		GdhRead.as_float(fields.get("r", 0)),
+		GdhRead.as_float(fields.get("g", 0)),
+		GdhRead.as_float(fields.get("b", 0)),
+		GdhRead.as_float(fields.get("a", 1), 1.0)
 	)
 
 
@@ -897,7 +852,7 @@ func _build_bytes(fields: Dictionary) -> PackedByteArray:
 
 
 func _build_float(fields: Dictionary) -> float:
-	return Read.as_float(fields)
+	return GdhRead.as_float(fields)
 
 
 func _build_int(fields: Dictionary) -> int:

package/build/godot/operations/value_shapes.gd

@@ -0,0 +1,118 @@
+extends RefCounted
+
+## How each engine type built from fields is written: the fields it needs, the ones it reads when
+## they are there, and what a refusal says about a value that is not one.
+##
+## This file is the one beside the operations, and `bun run sync:gd` copies it into each addon.
+
+# What each tag has to carry before it is built. A tag naming a type whose keys are not there is a
+# tag somebody wrote by mistake or wrote for a different shape, and building one out of defaults
+# answers with a Transform2D of zeros where the caller meant something else entirely. Unbuilt, it
+# comes back as it arrived, and whoever asked can read it against the type they were expecting.
+const REQUIRED: Dictionary = {
+	"Vector2": [["x", "y"]],
+	"Vector2i": [["x", "y"]],
+	"Vector3": [["x", "y", "z"]],
+	"Vector3i": [["x", "y", "z"]],
+	"Vector4": [["x", "y", "z", "w"]],
+	"Vector4i": [["x", "y", "z", "w"]],
+	"Rect2": [["position", "size"], ["x", "y", "width", "height"]],
+	"Rect2i": [["position", "size"], ["x", "y", "width", "height"]],
+	"Plane": [["normal", "d"]],
+	"Quaternion": [["x", "y", "z", "w"]],
+	"AABB": [["position", "size"]],
+	"Basis": [["x", "y", "z"]],
+	"Transform2D": [["x", "y", "origin"]],
+	"Transform3D": [["basis", "origin"]],
+	"Projection": [["x", "y", "z", "w"]],
+	"Color": [["r", "g", "b"]],
+	"NodePath": [["path"]],
+	"PackedByteArray": [["base64"]],
+	"float": [["value"]],
+	"int": [["value"]],
+	"RID": [["id"]],
+	"Dictionary": [["entries"]],
+}
+## The fields a builder reads when they are there and does without when not.
+const OPTIONAL: Dictionary = {
+	"Color": ["a"],
+	"PackedByteArray": ["size"],
+}
+
+
+## How a value of [param type] is written to be read as one, for a refusal to name, or empty for a
+## type that is not built from fields. A refusal naming only the two types leaves a caller to find
+## the shape in the description of another op.
+static func written_as(type: int) -> String:
+	var tag: String = type_string(type)
+	var alternatives: Array = REQUIRED.get(tag, [])
+	if alternatives.is_empty() or tag in ["float", "int", "Dictionary"]:
+		return ""
+	var keys: Array = alternatives[0]
+	var optional: Array = OPTIONAL.get(tag, [])
+	var parts: Array[String] = []
+	for key: Variant in keys + optional:
+		parts.append('"%s": ...' % key)
+	var shape: String = "{%s}" % ", ".join(parts)
+	if type == TYPE_COLOR:
+		return shape + ' or as its html code, "#ff8000"'
+	return shape
+
+
+## The keys of [param fields] that a [param tag] built from them would not read, one list for each
+## spelling of its fields carried whole. A rectangle has two: its corners, and four numbers.
+##
+## A builder drops a key it does not know without a word, so {"x": 1, "y": 2, "z": 3} for a Vector2
+## would be written as (1, 2) and answered as written: a value is built only when a list is empty.
+static func spare(fields: Dictionary, tag: String) -> Array:
+	var optional: Array = OPTIONAL.get(tag, [])
+	var lists: Array = []
+	var alternatives: Array = REQUIRED.get(tag, [])
+	for alternative: Variant in alternatives:
+		var keys: Array = alternative
+		if keys.all(func(key: Variant) -> bool: return fields.has(key)):
+			var over: Callable = func(key: Variant) -> bool:
+				return str(key) != "_type" and not keys.has(key) and not optional.has(key)
+			lists.append(fields.keys().filter(over))
+	return lists
+
+
+## The sentences a refusal of [param value] where a [param type] goes ends with: which of its keys
+## kept it from being read as one, and how one is written. Empty for a type not built from fields.
+##
+## The refusal names only the two types, and the key is what the caller has to take out.
+static func remedy(value: Variant, type: int) -> String:
+	if type == TYPE_STRING and typeof(value) in [TYPE_BOOL, TYPE_INT, TYPE_FLOAT]:
+		var number: Variant = value
+		if value is float:
+			var whole: float = value
+			if is_finite(whole) and whole == floorf(whole):
+				number = int(whole)
+		return ' Text is sent in quotes, as "%s".' % str(number)
+	var shape: String = written_as(type)
+	if shape.is_empty():
+		return ""
+	return _unread(value, type) + " A %s is sent as %s." % [type_string(type), shape]
+
+
+static func _unread(value: Variant, type: int) -> String:
+	if not value is Dictionary:
+		return ""
+	var fields: Dictionary = value
+	var tag: String = type_string(type)
+	var lists: Array = spare(fields, tag)
+	var built: bool = lists.any(func(over: Array) -> bool: return over.is_empty())
+	if lists.is_empty() or built or str(fields.get("_type", tag)) != tag:
+		return ""
+	lists.sort_custom(func(a: Array, b: Array) -> bool: return a.size() < b.size())
+	var left: Array = lists[0]
+	var named: PackedStringArray = []
+	for key: Variant in left:
+		var _named: bool = named.append('"%s"' % key)
+	var fields_called: String = "field called" if named.size() == 1 else "fields called"
+	var note: String = (
+		" A %s has no %s %s, so the value is not read as one" % [tag, fields_called, " or ".join(named)]
+	)
+	if left.has("type") and not fields.has("_type"):
+		return note + ': a value names its type under "_type".'
+	return note + "."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "mcpName": "io.github.Aureliolo/gdharness",
   "description": "A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.",
   "type": "module",