gdharness 1.3.1 → 1.3.2

package/build/godot/operations/project_config.gd

@@ -1,5 +1,6 @@
 extends RefCounted
 
+const GdhFileWalk = preload("file_walk.gd")
 const GdhRead = preload("reading.gd")
 const GdhLog = preload("logger.gd")
 const GdhProjectFile = preload("project_file.gd")
@@ -125,6 +126,12 @@ func set_project_setting(params: Dictionary) -> Dictionary:
 		if not _converts_faithfully(final_value, wanted):
 			return _log.failure(_cannot_hold(setting_path, wanted, final_value))
 		final_value = type_convert(final_value, wanted)
+	# JSON carries every number as a float and a new setting has no declared type to fit one to, so a
+	# whole number was saved as 800.0 beside an answer saying 800.
+	if not had_value and wanted == TYPE_NIL and final_value is float:
+		var number: float = final_value
+		if number == floorf(number) and absf(number) < 9.0e15:
+			final_value = int(number)
 
 	var answer: Dictionary = {
 		"setting_path": setting_path,
@@ -141,6 +148,17 @@ func set_project_setting(params: Dictionary) -> Dictionary:
 		answer["unchanged"] = true
 		return answer
 
+	var near: PackedStringArray = []
+	if not had_value:
+		near = _settings_near(setting_path)
+	if not near.is_empty():
+		answer["note"] = (
+			(
+				"No setting %s existed, so this wrote a new one, which the engine reads only where"
+				+ " something asks for it by that name. The nearest %s %s."
+			)
+			% [setting_path, "setting is" if near.size() == 1 else "settings are", ", ".join(near)]
+		)
 	ProjectSettings.set_setting(setting_path, final_value)
 	var err: Error = GdhProjectFile.save()
 	if err != OK:
@@ -148,6 +166,18 @@ func set_project_setting(params: Dictionary) -> Dictionary:
 	return answer
 
 
+# The settings in the same section as [param setting_path] named nearest it, for a new one that is
+# likely a misspelt one: a setting nothing declares is written all the same, and is never read.
+static func _settings_near(setting_path: String) -> PackedStringArray:
+	var section: String = setting_path.get_slice("/", 0) + "/"
+	var names: PackedStringArray = []
+	for info: Dictionary in ProjectSettings.get_property_list():
+		var name: String = str(info.get("name", ""))
+		if name.begins_with(section) and name != setting_path:
+			var _added: bool = names.append(name)
+	return GdhRead.nearest(setting_path, names)
+
+
 # The type a setting wants, or TYPE_NIL where the engine names none and there is nothing to go on.
 #
 # JSON carries one number type, so every number arrives as a float and an int setting was written
@@ -215,7 +245,9 @@ func add_autoload(params: Dictionary) -> Dictionary:
 	_log.info("Adding autoload: " + name + " -> " + path)
 
 	if not FileAccess.file_exists(path):
-		return _log.failure("Autoload file does not exist: " + path)
+		return _log.failure(
+			GdhFileWalk.new().with_nearest_files("Autoload file does not exist: " + path, path)
+		)
 
 	# Through ProjectSettings so the file is saved the way the editor saves it, which includes
 	# putting Godot's header back and dropping any comment somebody wrote into the file by hand.
@@ -225,7 +257,17 @@ func add_autoload(params: Dictionary) -> Dictionary:
 	# An asterisk in front of the path makes the autoload's name a global variable, the editor's
 	# "Global Variable" column. Without it the node still comes up under the root; only the name
 	# stops resolving.
-	ProjectSettings.set_setting(setting, ("*" if global else "") + path)
+	var entry: String = ("*" if global else "") + path
+	if was_updated and str(ProjectSettings.get_setting(setting)) == entry:
+		return {
+			"name": name,
+			"path": path,
+			"enabled": true,
+			"global": global,
+			"action": "unchanged",
+			"saved": false
+		}
+	ProjectSettings.set_setting(setting, entry)
 	var err: Error = GdhProjectFile.save()
 	if err != OK:
 		return _log.failure("Failed to save project.godot: " + error_string(err))
@@ -236,6 +278,7 @@ func add_autoload(params: Dictionary) -> Dictionary:
 		"enabled": true,
 		"global": global,
 		"action": "updated" if was_updated else "added",
+		"saved": true,
 	}
 
 
@@ -295,7 +338,20 @@ func set_main_scene(params: Dictionary) -> Dictionary:
 	_log.info("Setting main scene: " + scene_path)
 
 	if not FileAccess.file_exists(scene_path):
-		return _log.failure("Scene file does not exist: " + scene_path)
+		return _log.failure(
+			GdhFileWalk.new().with_nearest_files("Scene file does not exist: " + scene_path, scene_path)
+		)
+
+	# The engine starts the game by instancing the main scene, so a script or any other resource set
+	# there was saved and answered as set, and the game then would not start.
+	if not ResourceLoader.exists(scene_path, "PackedScene"):
+		var loaded: Resource = ResourceLoader.load(scene_path, "", ResourceLoader.CACHE_MODE_IGNORE)
+		var kind: String = loaded.get_class() if loaded != null else ""
+		var said: String = (
+			"%s is %s, not a scene, and the main scene has to be one"
+			% [scene_path, "a " + kind if not kind.is_empty() else "no resource the engine loads"]
+		)
+		return _log.failure(GdhFileWalk.new().with_nearest_files(said, scene_path.get_basename() + ".tscn"))
 
 	var old_main_scene: String = str(ProjectSettings.get_setting("application/run/main_scene", ""))
 

package/build/godot/operations/project_diagnostics.gd

@@ -1,8 +1,11 @@
 extends RefCounted
 
+const GdhDependencies = preload("dependencies.gd")
 const GdhFileWalk = preload("file_walk.gd")
 const GdhImportPipeline = preload("import_pipeline.gd")
 const GdhLog = preload("logger.gd")
+const GdhRead = preload("reading.gd")
+const GdhScriptCheck = preload("script_check.gd")
 
 var _log: GdhLog
 var _files: GdhFileWalk = GdhFileWalk.new()
@@ -15,7 +18,7 @@ func _init(p_log: GdhLog) -> void:
 # Get comprehensive project health check with scoring
 func get_project_health(params: Dictionary) -> Dictionary:
 	var check_categories: Array = params.get(
-		"categories", ["structure", "resources", "scripts", "scenes", "config"]
+		"categories", ["structure", "resources", "scripts", "references", "scenes", "config"]
 	)
 
 	_log.info("Performing project health check")
@@ -87,12 +90,34 @@ func get_project_health(params: Dictionary) -> Dictionary:
 		if todo_count > 0:
 			recommendations.append("%d scripts have TODO or FIXME comments to look at" % todo_count)
 
-		checks["scripts"] = {
+		# Compiled by the server before this runs, since an engine stops at the first script that
+		# fails, and handed in. Without it the check read only comments and said "passed" beside
+		# scripts the engine refused.
+		var compiled: Dictionary = params.get("compiled", {})
+		var failures: Array = compiled.get("failures", [])
+		for failure: Dictionary in failures:
+			details.append(GdhScriptCheck.failure_line(failure))
+			deductions += 10
+
+		var scripts: Dictionary = {
 			"name": "Scripts",
 			"passed": details.is_empty(),
 			"details": details,
 			"total_scripts": script_files.size()
 		}
+		if compiled.has("checked"):
+			scripts["compiled"] = GdhRead.as_int(compiled["checked"])
+		else:
+			scripts["not_compiled"] = str(compiled.get("not_checked", "no compile was asked for"))
+		checks["scripts"] = scripts
+
+	# 3b. References
+	if "references" in check_categories:
+		var details: Array[String] = []
+		for entry: Dictionary in GdhDependencies.new(_log).missing_references():
+			details.append(GdhDependencies.missing_line(entry))
+			deductions += 5
+		checks["references"] = {"name": "References", "passed": details.is_empty(), "details": details}
 
 	# 4. Scenes Check
 	if "scenes" in check_categories:

package/build/godot/operations/property_values.gd

@@ -14,6 +14,7 @@ extends RefCounted
 ## write accepts. What is here on top of it is the part only a property knows: the type wanted, so a
 ## dictionary shaped like a vector or a bare pair of numbers can be read as one.
 
+const GdhDeclared = preload("declared_values.gd")
 const GdhRead = preload("reading.gd")
 const GdhSerialisation = preload("serialisation.gd")
 const GdhShapes = preload("value_shapes.gd")
@@ -78,6 +79,11 @@ var _refused: String = ""
 # offsets. An answer naming only what was given leaves the caller to guess the rest.
 var _also_changed: Dictionary = {}
 
+# The values the last write_all wrote outside what their property declares, by name, as a sentence
+# saying so: a number past an export range, or one no enum value has. The engine stores either, and
+# the inspector would not have let it be entered, so a write answered as made said nothing of it.
+var _outside_declared: Dictionary = {}
+
 
 ## Turns what arrived over the wire into the Godot value a property wants.
 ##
@@ -177,23 +183,34 @@ func cannot_hold(
 ## caller returns the refusal instead of saving.
 func write_all(target: Object, properties: Dictionary) -> String:
 	_also_changed = {}
+	_outside_declared = {}
 	var named: Dictionary = {}
 	for key: Variant in properties:
 		named[str(key).get_slice(":", 0)] = true
 	var before: Dictionary = _stored(target, named)
 	var given: Dictionary = {}
+	# A refusal of one of several leaves the others unwritten too, which a refusal naming only the
+	# one it refused left a caller to guess.
+	var unwritten: String = (
+		"" if properties.size() < 2 else " None of the %d properties given was written." % properties.size()
+	)
 	for key: Variant in properties:
 		var property: String = str(key)
 		var declared: Dictionary = declaration(target, property)
 		if declared.is_empty() and ":" in property:
 			declared = _component_slot(target, property)
 			if declared.has("refused"):
-				return str(declared["refused"])
+				return str(declared["refused"]) + unwritten
+		if declared.is_empty() and target is ShaderMaterial and property.begins_with("shader_parameter/"):
+			return _no_uniform(target as ShaderMaterial, property) + unwritten
 		if declared.is_empty():
-			return "%s has no property %s" % [target.get_class(), property]
+			return "%s has no property %s." % [class_called(target), property] + unwritten
 		var value: Array = value_for(target, declared, properties[key])
 		if not value[0]:
-			return str(value[1])
+			return str(value[1]) + unwritten
+		var outside: String = GdhDeclared.outside(target, declared, value[1], shown(value[1]))
+		if not outside.is_empty():
+			_outside_declared[property] = outside
 		_write(target, property, value[1])
 		given[property] = value[1]
 
@@ -217,11 +234,32 @@ func write_all(target: Object, properties: Dictionary) -> String:
 	return ""
 
 
+## Why [param material] has no [param property]: a ShaderMaterial's parameters are its shader's
+## uniforms, so the shader is what lacks one, and "ShaderMaterial has no property" named the
+## material.
+static func _no_uniform(material: ShaderMaterial, property: String) -> String:
+	var uniform: String = property.trim_prefix("shader_parameter/")
+	if material.shader == null:
+		return "The ShaderMaterial has no shader, so it has no parameter %s yet; set shader first." % uniform
+	var shader: String = material.shader.resource_path
+	var named: String = shader if not shader.is_empty() else "Its shader"
+	var uniforms: Array = []
+	for entry: Dictionary in material.shader.get_shader_uniform_list():
+		uniforms.append(str(entry["name"]))
+	var said: String = "%s declares no uniform %s, which %s would set" % [named, uniform, property]
+	if uniforms.is_empty():
+		return said + "; it declares no uniforms."
+	return GdhRead.offered(said, uniform, uniforms) + "."
+
+
 ## Puts under alsoChanged in [param answer] each property the last [method write_all] changed
-## without being given it, as {was, now}, when there are any. A node is named by its path from
-## [param relative_to], as a scene answer names one. Called before the scene is written, since the
-## write frees the nodes these values can hold.
-func note_also_changed(answer: Dictionary, relative_to: Node = null) -> void:
+## without being given it, as {was, now}, and under outsideDeclared each value it wrote outside what
+## its property declares, when there are any. A node is named by its path from [param relative_to],
+## as a scene answer names one. Called before the scene is written, since the write frees the nodes
+## these values can hold.
+func note_write(answer: Dictionary, relative_to: Node = null) -> void:
+	if not _outside_declared.is_empty():
+		answer["outsideDeclared"] = _outside_declared.duplicate()
 	if _also_changed.is_empty():
 		return
 	var noted: Dictionary = {}
@@ -324,6 +362,18 @@ 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))
+		if chosen != null:
+			return [true, chosen]
+		if not str(raw).strip_edges().is_valid_int():
+			return [false, GdhDeclared.enum_refusal(class_called(target), property, str(raw), choices)]
 
 	# 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.
@@ -339,12 +389,12 @@ func value_for(target: Object, declared: Dictionary, raw: Variant) -> Array:
 			return [false, _fraction_refusal(target, property, raw)]
 		var rounded: String = GdhSerialisation.inexact(raw, expected_type)
 		if not rounded.is_empty():
-			return [false, "%s.%s holds int: %s." % [target.get_class(), property, rounded]]
+			return [false, "%s.%s holds int: %s." % [class_called(target), property, rounded]]
 		_refused = ""
 		value = parse(raw, expected_type, elements)
 		if not _refused.is_empty():
 			return [false, _refused]
-		var refusal: String = cannot_hold(target.get_class(), property, value, expected_type, elements)
+		var refusal: String = cannot_hold(class_called(target), property, value, expected_type, elements)
 		if not refusal.is_empty():
 			return [false, refusal]
 	if value is Object:
@@ -489,10 +539,43 @@ func _fraction_refusal(target: Object, property: String, raw: Variant) -> String
 			"%s.%s holds whole numbers, and %s would be cut to fit. Setting it would save a different "
 			+ "value than the one asked for."
 		)
-		% [target.get_class(), property, shown(raw)]
+		% [class_called(target), property, shown(raw)]
 	)
 
 
+## [param raw] as a colour, read as a property write reads one, as [true, Color] or [false, why]:
+## fields from 0 to 1 with a optional, or an html code. [param named] is what the refusal calls it.
+func colour_from(raw: Variant, named: String) -> Array:
+	_refused = ""
+	var value: Variant = parse(raw, TYPE_COLOR)
+	if not _refused.is_empty():
+		return [false, _refused]
+	if value is Color:
+		return [true, value]
+	return [
+		false,
+		(
+			(
+				'%s is {"r": .., "g": .., "b": .., "a": ..} from 0 to 1, a optional, or an html code such as '
+				+ '"#ff8000" or "#ff800080"; %s is neither.'
+			)
+			% [named, JSON.stringify(raw)]
+		)
+	]
+
+
+## What [param target] is called in a refusal: the class_name its script declares, or else its
+## engine class. A resource made as a project class is a Resource to the engine, and "Resource.kind"
+## named a property no Resource has.
+static func class_called(target: Object) -> String:
+	var attached: Variant = target.get_script()
+	if attached is Script:
+		var script: Script = attached
+		if not str(script.get_global_name()).is_empty():
+			return str(script.get_global_name())
+	return target.get_class()
+
+
 ## The resource [param path] names, as [found, resource or why not].
 ##
 ## The project boundary is enforced here as well as on the server, because only the engine knows
@@ -516,6 +599,19 @@ func _resource_at(path: String, property: String) -> Array:
 			)
 		]
 	if not ResourceLoader.exists(path):
+		# An image or a sound nobody has imported is a file the engine has no loader for, and "No
+		# resource at" sent a caller looking for a file that was there.
+		if path.begins_with("res://") and FileAccess.file_exists(path):
+			return [
+				false,
+				(
+					(
+						"%s is there, but it has never been imported, so the engine has no resource to load"
+						+ " from it for %s. project_import reimport with resourcePath %s imports it."
+					)
+					% [path, property, path]
+				)
+			]
 		return [false, "No resource at %s for %s" % [path, property]]
 	return [true, load(path)]
 

package/build/godot/operations/reading.gd

@@ -164,6 +164,43 @@ static func not_of_kind(
 	return told + " The scene's %ss are at %s." % [kind, shown]
 
 
+## Up to three of [param names] closest to [param word], closest first, ignoring case: the names a
+## refusal offers for one that is not there, as a typo usually is one of them.
+static func nearest(word: String, names: PackedStringArray) -> PackedStringArray:
+	var wanted: String = word.to_lower()
+	var close: Array[String] = []
+	for name: String in names:
+		if name.to_lower().similarity(wanted) >= 0.5:
+			close.append(name)
+	close.sort_custom(
+		func(a: String, b: String) -> bool:
+			return a.to_lower().similarity(wanted) > b.to_lower().similarity(wanted)
+	)
+	return PackedStringArray(close.slice(0, 3))
+
+
+## [param said], the refusal for [param word], which is not among [param names], with those nearest
+## it when any are, or else every one of them, so the caller has a name to send instead.
+static func offered(said: String, word: String, names: Array) -> String:
+	var every: PackedStringArray = PackedStringArray(names)
+	var close: PackedStringArray = nearest(word, every)
+	if close.is_empty():
+		return "%s; it has %s" % [said, ", ".join(every)]
+	return "%s; the nearest it has %s %s" % [said, "is" if close.size() == 1 else "are", ", ".join(close)]
+
+
+## The signals [param object] has that a caller can connect, its own class's first: the engine
+## lists them from Object down, which puts a Button's pressed after thirty a Control has, and names
+## starting with an underscore are the engine's own.
+static func signals_of(object: Object) -> Array:
+	var names: Array = []
+	for entry: Dictionary in object.get_signal_list():
+		var name: String = str(entry["name"])
+		if not name.begins_with("_"):
+			names.push_front(name)
+	return names
+
+
 ## [param word] after the article it takes, "an AnimationTree" or "a Node2D".
 static func with_article(word: String) -> String:
 	return ("an " if word.left(1).to_upper() in ["A", "E", "I", "O", "U"] else "a ") + word

package/build/godot/operations/resource_files.gd

@@ -1,5 +1,6 @@
 extends RefCounted
 
+const GdhFileWalk = preload("file_walk.gd")
 const GdhLog = preload("logger.gd")
 const GdhPatterns = preload("patterns.gd")
 
@@ -29,7 +30,9 @@ func get_uid(params: Dictionary) -> Dictionary:
 
 	var absolute_path: String = ProjectSettings.globalize_path(file_path)
 	if not FileAccess.file_exists(file_path):
-		return _log.failure("File does not exist: " + file_path)
+		return _log.failure(
+			GdhFileWalk.new().with_nearest_files("File does not exist: " + file_path, file_path)
+		)
 
 	var answer: Dictionary = {"file": file_path, "absolute_path": absolute_path}
 	var found: Dictionary = uid_of(file_path)

package/build/godot/operations/script_check.gd

@@ -54,6 +54,22 @@ 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]

package/build/godot/operations/serialisation.gd

@@ -410,6 +410,10 @@ func fitted(value: Variant, type: int) -> Variant:
 	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.

package/build/godot/operations/value_shapes.gd

@@ -82,6 +82,13 @@ static func spare(fields: Dictionary, tag: String) -> Array:
 ##
 ## 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 ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "1.3.1",
+  "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",