gdharness 1.3.1 → 1.3.2

package/build/godot/operations/dependencies.gd

@@ -75,7 +75,9 @@ func get_dependencies(params: Dictionary) -> Dictionary:
 			full_path = "res://" + full_path
 
 		if not FileAccess.file_exists(full_path):
-			return _log.failure("Resource file does not exist: " + full_path)
+			return _log.failure(
+				_files.with_nearest_files("Resource file does not exist: " + full_path, full_path)
+			)
 
 		var walk: GdhDependencyWalk = GdhDependencyWalk.new(max_depth, include_built_in, circular_references)
 		dependencies[full_path] = _analyze_resource(full_path, 0, walk)
@@ -100,12 +102,19 @@ func get_dependencies(params: Dictionary) -> Dictionary:
 
 	var references: int = 0
 	var distinct: Dictionary = {}
+	var missing: 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]
 		references += _count_recursive(walked)
 		_gather_paths(walked, key, distinct)
+		_gather_missing(walked, key, missing)
+	# Said in the summary as well as in the tree, where a file that is not there was one
+	# `exists: false` among the entries, which a caller reading the summary never met.
+	var missing_files: Array[Dictionary] = []
+	for path: String in missing:
+		missing_files.append({"path": path, "referenced_by": missing[path]})
 
 	return {
 		"dependencies": dependencies,
@@ -117,11 +126,54 @@ func get_dependencies(params: Dictionary) -> Dictionary:
 			# 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()
+			"circular_count": circular_references.size(),
+			"missing": missing_files
 		}
 	}
 
 
+## Every file a scene or resource of the project loads through an ext_resource that is not there,
+## by its path or its uid, each with the files loading it. Only those: a script naming a path in
+## its code may be asking whether the file exists, and the shipped addons check for files they
+## write, so every project was told its addons referred to files that are missing. A script's
+## preloads are the compile's to judge.
+func missing_references() -> Array[Dictionary]:
+	var missing: Dictionary = {}
+	for file: String in _files.find_files_with_extensions("res://", GdhResourceFiles.TEXT_RESOURCE_KINDS):
+		var content: String = FileAccess.get_file_as_string(file)
+		var moved: Dictionary = _moved_by_uid(content)
+		for line: RegExMatch in GdhPatterns.compiled("\\[ext_resource[^\\]]*\\]").search_all(content):
+			var at: RegExMatch = GdhPatterns.compiled('path="([^"]+)"').search(line.get_string())
+			if at == null or moved.has(at.get_string(1)):
+				continue
+			var path: String = _resolved(at.get_string(1), file)
+			if FileAccess.file_exists(path):
+				continue
+			var naming: Array = missing.get_or_add(path, [])
+			if not file in naming:
+				naming.append(file)
+	# Sorted, since the walk meets files in the order the filesystem lists them, which differs
+	# between platforms.
+	var paths: Array = missing.keys()
+	paths.sort()
+	var found: Array[Dictionary] = []
+	for path: String in paths:
+		var naming: Array = missing[path]
+		naming.sort()
+		found.append({"path": path, "referenced_by": naming})
+	return found
+
+
+## One line for [param entry], one of [method missing_references].
+static func missing_line(entry: Dictionary) -> String:
+	var referring: Array = entry.get("referenced_by", [])
+	var naming: PackedStringArray = PackedStringArray(referring)
+	return (
+		"%s does not exist, and %s %s to it"
+		% [str(entry.get("path", "")), ", ".join(naming), "refers" if naming.size() == 1 else "refer"]
+	)
+
+
 # What refers to a resource, and how: the scenes that instance it, the scripts that extend or
 # preload it, and for a script with a class_name, every use of that name.
 func find_resource_usages(params: Dictionary) -> Dictionary:
@@ -130,8 +182,10 @@ func find_resource_usages(params: Dictionary) -> Dictionary:
 
 	if not resource_path.begins_with("res://"):
 		resource_path = "res://" + resource_path
-	if not FileAccess.file_exists(resource_path):
-		return _log.failure("Resource file does not exist: " + resource_path)
+	# A file that is gone is searched for all the same, since what still refers to it is what a
+	# caller asks about one, and the forward walk of a scene had just named it missing. Refused only
+	# when nothing refers to it either, which is a path written wrong.
+	var exists: bool = FileAccess.file_exists(resource_path)
 
 	_log.info("Finding usages of: " + resource_path)
 
@@ -140,7 +194,8 @@ func find_resource_usages(params: Dictionary) -> Dictionary:
 	if not class_name_declared.is_empty():
 		by_class = GdhPatterns.compiled("\\b" + _regex_escaped(class_name_declared) + "\\b")
 	var target: Dictionary = {
-		"path": resource_path, "uid": str(GdhResourceFiles.uid_of(resource_path).get("uid", ""))
+		"path": resource_path,
+		"uid": str(GdhResourceFiles.uid_of(resource_path).get("uid", "")) if exists else ""
 	}
 
 	var all_files: Array[String] = _usage_files(file_types)
@@ -204,11 +259,19 @@ func find_resource_usages(params: Dictionary) -> Dictionary:
 			usages.append({"file": file_path, "references": references})
 			total += references.size()
 
+	if not exists and usages.is_empty():
+		return _log.failure(
+			_files.with_nearest_files(
+				"Resource file does not exist: %s, and nothing in the project refers to it" % resource_path,
+				resource_path
+			)
+		)
 	var declared: Variant = null
 	if not class_name_declared.is_empty():
 		declared = class_name_declared
 	return {
 		"resource_path": resource_path,
+		"exists": exists,
 		"class_name": declared,
 		"usages": usages,
 		"summary":
@@ -357,6 +420,20 @@ func _gather_paths(deps: Array[Dictionary], root: String, into: Dictionary) -> v
 			_gather_paths(deeper, root, into)
 
 
+# Each file in [param deps] that does not exist, into [param into] with the files naming it, once
+# each however often the tree reaches them; [param parent] names the entries of [param deps].
+func _gather_missing(deps: Array[Dictionary], parent: String, into: Dictionary) -> void:
+	for dep: Dictionary in deps:
+		var path: String = str(dep.get("path", ""))
+		if not dep.get("exists", true):
+			var naming: Array = into.get_or_add(path, [])
+			if not parent in naming:
+				naming.append(parent)
+		if dep.has("dependencies"):
+			var deeper: Array[Dictionary] = dep["dependencies"]
+			_gather_missing(deeper, path, 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:
@@ -404,14 +481,20 @@ func _analyze_resource(path: String, current_depth: int, walk: GdhDependencyWalk
 		# about `["res://addons/x/plugin.cfg"]` was a dependency of every project with the addon.
 		if path.get_extension() == "gd":
 			content = _code_lines(content)
+		var moved: Dictionary = _moved_by_uid(content)
 
 		for pattern: String in REFERENCE_PATTERNS:
 			var regex: RegEx = GdhPatterns.compiled(pattern)
 			for m: RegExMatch in regex.search_all(content):
 				var dep_path: String = _resolved(_referenced_path(m.get_string()), path)
+				dep_path = str(moved.get(dep_path, dep_path))
 
 				if not dep_path.begins_with("res://"):
 					continue
+				# A literal naming a directory, or the start of a path a script builds as it runs
+				# ("res://levels/" + name), names no file, and walked as one it was a missing dependency.
+				if dep_path.get_extension().is_empty():
+					continue
 
 				# Skip engine-internal resources unless requested. `addons/` is not one of
 				# them: it is ordinary project content, and often shipping content, so
@@ -503,6 +586,27 @@ static func _resolved(written: String, from: String) -> String:
 
 
 # The path inside a preload(), load() or ext_resource match; a bare res:// match is the path.
+# The ext_resource paths in [param content] that nothing is at, each with the file its uid names
+# instead. The engine loads an ext_resource by its uid first, so a file moved outside the editor
+# still loads, and the walk called it missing; every pattern reads the old path, the bare res://
+# one included, so the paths are mapped before any of them runs.
+static func _moved_by_uid(content: String) -> Dictionary:
+	var moved: Dictionary = {}
+	for line: RegExMatch in GdhPatterns.compiled("\\[ext_resource[^\\]]*\\]").search_all(content):
+		var entry: String = line.get_string()
+		var at: RegExMatch = GdhPatterns.compiled('path="([^"]+)"').search(entry)
+		var uid: RegExMatch = GdhPatterns.compiled('uid="(uid://[^"]+)"').search(entry)
+		if at == null or uid == null or FileAccess.file_exists(at.get_string(1)):
+			continue
+		var id: int = ResourceUID.text_to_id(uid.get_string(1))
+		if id == ResourceUID.INVALID_ID or not ResourceUID.has_id(id):
+			continue
+		var found: String = ResourceUID.get_id_path(id)
+		if FileAccess.file_exists(found):
+			moved[at.get_string(1)] = found
+	return moved
+
+
 func _referenced_path(matched: String) -> String:
 	var expression: String = ""
 	if "preload" in matched or "load" in matched:

package/build/godot/operations/export_presets.gd

@@ -113,17 +113,15 @@ func add_export_preset(params: Dictionary) -> Dictionary:
 	while config.has_section("preset." + str(index)):
 		var held: String = "preset." + str(index)
 		if str(config.get_value(held, "name", "")) == preset_name:
+			var path: String = str(config.get_value(held, "export_path", ""))
+			var to: String = "with no export path set" if path.is_empty() else "exporting to '%s'" % path
 			return _log.failure(
 				(
 					(
-						"There is already an export preset named '%s', for %s, exporting to '%s'. "
+						"There is already an export preset named '%s', for %s, %s. "
 						+ "project_export run exports with it; give another name to add a second."
 					)
-					% [
-						preset_name,
-						config.get_value(held, "platform", ""),
-						config.get_value(held, "export_path", "")
-					]
+					% [preset_name, config.get_value(held, "platform", ""), to]
 				)
 			)
 		index += 1

package/build/godot/operations/file_reads.gd

@@ -427,6 +427,11 @@ static func resource(res_path: String, include_defaults: bool) -> Dictionary:
 	}
 	if script != null:
 		answer["script"] = script.resource_path
+		# resourceType is the engine class under the script, which for a class the project declares
+		# is Resource whatever create was given.
+		var declared_class: String = str(script.get_global_name())
+		if not declared_class.is_empty():
+			answer["scriptClass"] = declared_class
 	return answer
 
 

package/build/godot/operations/file_walk.gd

@@ -1,5 +1,7 @@
 extends RefCounted
 
+const GdhRead = preload("reading.gd")
+
 # Two walks rather than one because they disagree about hidden entries on purpose: a suffix
 # walk descends into every visible directory and matches whole names, while the extension walk
 # skips anything beginning with a dot, including .import sidecars that would otherwise answer
@@ -30,6 +32,38 @@ static func missing_reason(path: String) -> String:
 	return "" if FileAccess.file_exists(path) else path + " does not exist"
 
 
+## [param said], the refusal for [param path], a res:// path nothing is at, with the files of its
+## extension whose names are nearest its own, or every one when there are few and none is near, so
+## the caller has a path to send instead.
+func with_nearest_files(said: String, path: String) -> String:
+	var extension: String = path.get_extension()
+	if extension.is_empty():
+		return said
+	var files: Array[String] = find_files_with_extensions("res://", [extension])
+	# The walk lists a directory in the order the filesystem keeps it, which differs between
+	# platforms, so the same project was answered with its files in another order on Linux.
+	files.sort()
+	if files.is_empty():
+		return "%s. The project holds no .%s file." % [said, extension]
+	var names: PackedStringArray = []
+	for file: String in files:
+		var _named: bool = names.append(file.get_file().get_basename())
+	var close: PackedStringArray = GdhRead.nearest(path.get_file().get_basename(), names)
+	var offered: PackedStringArray = []
+	for file: String in files:
+		if file.get_file().get_basename() in close:
+			var _offered: bool = offered.append(file)
+	if not offered.is_empty():
+		var one: bool = offered.size() == 1
+		return (
+			"%s. The nearest .%s %s %s."
+			% [said, extension, "file is" if one else "files are", ", ".join(offered)]
+		)
+	if files.size() <= GdhRead.NAMED_CHILDREN:
+		return "%s. The project's .%s files are %s." % [said, extension, ", ".join(files)]
+	return "%s. None of the project's %d .%s files is named like it." % [said, files.size(), extension]
+
+
 # A directory the engine steps over, marker file and all.
 func is_stepped_over(path: String) -> bool:
 	return FileAccess.file_exists(path + ".gdignore")

package/build/godot/operations/gdscript_analysis.gd

@@ -1,6 +1,7 @@
 extends RefCounted
 
 const GdhDependencies = preload("dependencies.gd")
+const GdhFileWalk = preload("file_walk.gd")
 const GdhPatterns = preload("patterns.gd")
 const GdhRead = preload("reading.gd")
 const GdhLog = preload("logger.gd")
@@ -25,7 +26,11 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 		full_script_path = "res://" + full_script_path
 
 	if not FileAccess.file_exists(full_script_path):
-		return _log.failure("Script file does not exist: " + full_script_path)
+		return _log.failure(
+			GdhFileWalk.new().with_nearest_files(
+				"Script file does not exist: " + full_script_path, full_script_path
+			)
+		)
 
 	var file: FileAccess = FileAccess.open(full_script_path, FileAccess.READ)
 	if not file:
@@ -183,7 +188,7 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 		"dependencies": dependencies,
 		"classes_used": classes_used,
 		"autoloads_used": autoloads_used,
-		"line_count": lines.size()
+		"line_count": lines.size() - 1 if content.is_empty() or content.ends_with("\n") else lines.size()
 	}
 	if GdhRead.as_bool(params.get("include_inherited", false)):
 		_add_inherited(answer, [full_script_path])

package/build/godot/operations/gdscript_authoring.gd

@@ -1,8 +1,10 @@
 extends RefCounted
 
+const GdhFileWalk = preload("file_walk.gd")
 const GdhRead = preload("reading.gd")
 const GdhLog = preload("logger.gd")
 const GdhPatterns = preload("patterns.gd")
+const GdhScriptCheck = preload("script_check.gd")
 
 const MODIFICATION_TYPES: Array[String] = ["add_constant", "add_variable", "add_signal", "add_function"]
 const BLANKS_AROUND_FUNCTIONS: int = 2
@@ -56,6 +58,13 @@ func create_gdscript(params: Dictionary) -> Dictionary:
 			"Script file already exists: " + full_script_path + ". script_edit modify adds to it."
 		)
 
+	# Content is left to the parse below: two scripts that name each other are written one at a time,
+	# and the first does not compile until the second exists.
+	if content.is_empty():
+		var header: String = _header_refusal(cls_name_param, extends_class)
+		if not header.is_empty():
+			return _log.failure(header + " Nothing was written.")
+
 	var dir: DirAccess = DirAccess.open("res://")
 	var script_dir: String = full_script_path.get_base_dir()
 	if script_dir != "res://" and not dir.dir_exists(script_dir.substr(6)):
@@ -111,7 +120,11 @@ func modify_gdscript(params: Dictionary) -> Dictionary:
 		full_script_path = "res://" + full_script_path
 
 	if not FileAccess.file_exists(full_script_path):
-		return _log.failure("Script file does not exist: " + full_script_path)
+		return _log.failure(
+			GdhFileWalk.new().with_nearest_files(
+				"Script file does not exist: " + full_script_path, full_script_path
+			)
+		)
 
 	var file: FileAccess = FileAccess.open(full_script_path, FileAccess.READ)
 	if not file:
@@ -122,6 +135,8 @@ func modify_gdscript(params: Dictionary) -> Dictionary:
 
 	var lines: Array[String] = []
 	lines.assign(original_content.split("\n"))
+	var before: Script = ResourceLoader.load(full_script_path, "Script", ResourceLoader.CACHE_MODE_IGNORE)
+	var parsed_before: bool = _parses(before)
 
 	# 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.
@@ -166,16 +181,99 @@ func modify_gdscript(params: Dictionary) -> Dictionary:
 	if not rewrote:
 		return _log.failure("Failed to write to script file: " + full_script_path)
 
+	var caught: GdhScriptCheck.GdhCaught = GdhScriptCheck.GdhCaught.new()
+	OS.add_logger(caught)
 	var made: Script = ResourceLoader.load(full_script_path, "Script", ResourceLoader.CACHE_MODE_IGNORE)
+	OS.remove_logger(caught)
+	var parses: bool = _parses(made)
+	# The names checked above are the script's own, and a member the base class declares, or a body
+	# that does not compile, is found only by the engine; a script left broken by an addition breaks
+	# every scene that uses it, so it goes back as it was. One already broken is written, as the
+	# addition can be what mends it.
+	if parsed_before and not parses:
+		file = FileAccess.open(full_script_path, FileAccess.WRITE)
+		var restored: bool = file != null and file.store_string(original_content)
+		if file != null:
+			file.close()
+		if not restored:
+			return _log.failure(
+				"%s would not parse with these additions, and could not be put back as it was" % script_path
+			)
+		return _log.failure(
+			(
+				"Nothing was changed: %s parses as it is and would not with these additions: %s"
+				% [script_path, _reasons(caught.raised, full_script_path)]
+			)
+		)
 	return {
 		"success": true,
 		"script_path": script_path,
 		"modifications_applied": modifications_applied,
 		"total_modifications": modifications_applied.size(),
-		"parses": _parses(made),
+		"parses": parses,
 	}
 
 
+# The engine's errors in [param raised] for [param path], each with its line, as one sentence part.
+static func _reasons(raised: Array[Dictionary], path: String) -> String:
+	var reasons: PackedStringArray = []
+	for error: Dictionary in raised:
+		var reason: String = "line %d, %s" % [GdhRead.as_int(error["line"]), str(error["message"])]
+		if str(error["path"]) == path and not reason in reasons:
+			var _added: bool = reasons.append(reason)
+	if reasons.is_empty():
+		return "the engine would not load it as a script."
+	var last: String = reasons[-1]
+	return "; ".join(reasons) + ("" if last.ends_with(".") or last.ends_with(".)") else ".")
+
+
+# Why a script with [param named] as its class_name and extending [param base] cannot be written,
+# or "". A class_name another script holds does not compile ("hides a global script class"), and nor
+# does a base no class answers to; both were written and answered as made. Classes are read off the
+# scripts as well as the class list, which a fresh clone has not written yet.
+static func _header_refusal(named: String, base: String) -> String:
+	var declared: Dictionary = _declared_classes()
+	if not named.is_empty():
+		if ClassDB.class_exists(named):
+			return "class_name %s is the name of an engine class, which a script cannot take." % named
+		if declared.has(named):
+			return (
+				(
+					"class_name %s is taken: %s declares it, and a second script of that name does not "
+					+ "compile. Give this one another class_name, or script_edit rename the first."
+				)
+				% [named, declared[named]]
+			)
+	if base.begins_with('"') or base.begins_with("'") or "." in base:
+		return ""
+	if ClassDB.class_exists(base) or declared.has(base):
+		return ""
+	var said: String = (
+		"extends names %s, which is neither an engine class nor a class_name this project declares" % base
+	)
+	var close: PackedStringArray = GdhRead.nearest(base, PackedStringArray(declared.keys()))
+	if close.is_empty():
+		close = GdhRead.nearest(base, ClassDB.get_class_list())
+	if close.is_empty():
+		return said + "."
+	return said + "; the nearest %s %s." % ["is" if close.size() == 1 else "are", ", ".join(close)]
+
+
+# The class_name each script of the project declares, by name, with its path.
+static func _declared_classes() -> Dictionary:
+	var declared: Dictionary = {}
+	for entry: Dictionary in ProjectSettings.get_global_class_list():
+		var path: String = str(entry.get("path", ""))
+		if FileAccess.file_exists(path):
+			declared[str(entry.get("class", ""))] = path
+	for path: String in GdhFileWalk.new().find_files("res://", ".gd"):
+		for line: String in FileAccess.get_file_as_string(path).split("\n"):
+			var found: RegExMatch = GdhPatterns.declared_class(GdhPatterns.without_annotations(line))
+			if found != null and not declared.has(found.get_string(1)):
+				declared[found.get_string(1)] = path
+	return declared
+
+
 # Every reason [param modifications] cannot be made as asked, each naming the entry by position.
 #
 # A name the script already declares is one of them, as is one the call adds twice. GDScript gives a
@@ -341,6 +439,11 @@ func _add_variable(lines: Array[String], mod: Dictionary, placed: Array[Dictiona
 		var_line += ": Variant"
 
 	var insert_line: int = _variable_insertion_point(lines)
+	# The first variable below the header or the signals is set apart from them by a blank line, as
+	# the style guide and gdformat lay a script out.
+	var above: String = lines[insert_line - 1].strip_edges() if insert_line > 0 else ""
+	if not above.is_empty() and not GdhPatterns.without_annotations(above).begins_with("var "):
+		return insert_line + 1 if _insert(lines, insert_line, ["", var_line], placed) else -1
 	return insert_line if _insert(lines, insert_line, [var_line], placed) else -1
 
 

package/build/godot/operations/godot_operations.gd

@@ -277,6 +277,8 @@ func _run(operation: String, params: Dictionary) -> Dictionary:
 			payload = GdhInputActions.new(_log).add_input_action(params)
 		"remove_input_action":
 			payload = GdhInputActions.new(_log).remove_input_action(params)
+		"list_input_actions":
+			payload = GdhInputActions.new(_log).list_input_actions(params)
 
 		# Audio
 		"create_audio_bus":

package/build/godot/operations/import_pipeline.gd

@@ -1,6 +1,8 @@
 extends RefCounted
 
+const GdhDependencies = preload("dependencies.gd")
 const GdhExportPresets = preload("export_presets.gd")
+const GdhScriptCheck = preload("script_check.gd")
 const GdhRead = preload("reading.gd")
 const GdhSerialisation = preload("serialisation.gd")
 const GdhFileWalk = preload("file_walk.gd")
@@ -85,6 +87,14 @@ func get_import_status(params: Dictionary) -> Dictionary:
 		if not full_path.begins_with("res://"):
 			full_path = "res://" + full_path
 
+		# missing_source is a sidecar whose source has gone; with neither, the path names nothing the
+		# engine ever imported, and answering it as a lost source sent a caller to restore a file.
+		if not FileAccess.file_exists(full_path) and not FileAccess.file_exists(full_path + ".import"):
+			return _log.failure(
+				_files.with_nearest_files(
+					"Nothing is at %s, and no import sidecar names it" % full_path, full_path
+				)
+			)
 		var status: Dictionary = _import_status_of(full_path, full_path + ".import")
 		resources.append(status)
 		_tally(summary, status)
@@ -457,6 +467,35 @@ func validate_project(params: Dictionary) -> Dictionary:
 			if "pass # TODO" in content:
 				script_issues.append({"path": script_path, "issue": "Contains unimplemented functions"})
 
+	# Compiled by the server and handed in, as for the health check: a script the engine refuses
+	# stops the export's game at the first scene using it, which the comment check above never saw.
+	var compiled: Dictionary = params.get("compiled", {})
+	if compiled.has("checked"):
+		checks_performed.append("compiles")
+	var failures: Array = compiled.get("failures", [])
+	for failure: Dictionary in failures:
+		issues.append(
+			_finding(
+				"error",
+				"compiles",
+				GdhScriptCheck.failure_line(failure),
+				"script_diagnostics gives every error in it with its line",
+				include_suggestions
+			)
+		)
+
+	checks_performed.append("references")
+	for entry: Dictionary in GdhDependencies.new(_log).missing_references():
+		issues.append(
+			_finding(
+				"error",
+				"references",
+				GdhDependencies.missing_line(entry),
+				"Restore the file, or point the reference at the file that replaced it",
+				include_suggestions
+			)
+		)
+
 	if script_issues.size() > 0:
 		var warning: Dictionary = _finding(
 			"warning",

package/build/godot/operations/input_actions.gd

@@ -111,6 +111,24 @@ func add_input_action(params: Dictionary) -> Dictionary:
 	var deadzone: float = GdhRead.as_float(params.get("deadzone", 0.5), 0.5)
 
 	_log.info("Adding input action: " + action_name)
+	# The editor's Input Map refuses these, since project.godot keys an action by its name and
+	# the characters below are its own syntax there; a name holding one is written escaped and
+	# reads back as a name nobody typed.
+	for index: int in action_name.length():
+		var code: int = action_name.unicode_at(index)
+		if code < 32 or action_name[index] in ["/", ":", "=", "\\", '"']:
+			return (
+				_log
+				. failure(
+					(
+						(
+							"%s is not an action name the engine's Input Map takes: a name cannot hold / : = \\ "
+							+ "or a double quote, or a control character. jump, move_left or ui_menu are names it takes."
+						)
+						% JSON.stringify(action_name)
+					)
+				)
+			)
 	_log.debug("Events: " + JSON.stringify(events))
 	_log.debug("Deadzone: " + str(deadzone))
 
@@ -130,7 +148,7 @@ func add_input_action(params: Dictionary) -> Dictionary:
 					return _log.failure("A key event needs keycode")
 				var key_value: int = _keycode_value(keycode)
 				if key_value == KEY_NONE:
-					return _log.failure("Unknown key: " + keycode)
+					return _log.failure(_unknown_key(keycode))
 
 				var event_config: Dictionary = {"class_name": "InputEventKey", "keycode": key_value}
 				if fields.get("ctrl", false):
@@ -229,6 +247,42 @@ static func _shaped(event: InputEvent) -> Dictionary:
 	return shaped
 
 
+## The input actions project.godot holds, each with its deadzone and events in the form
+## add_input_action answers with. An engine ui_ action is listed only when the project rebinds it,
+## as engineAction, since the engine's own eighty are there in every project.
+func list_input_actions(_params: Dictionary) -> Dictionary:
+	var actions: Array[Dictionary] = []
+	for info: Dictionary in ProjectSettings.get_property_list():
+		var setting: String = str(info.get("name", ""))
+		if not setting.begins_with("input/"):
+			continue
+		var engine_default: Variant = ProjectSettings.property_get_revert(setting)
+		var held: Variant = ProjectSettings.get_setting(setting)
+		if engine_default != null and held == engine_default:
+			continue
+		var action: Dictionary = held if held is Dictionary else {}
+		var events: Array[Dictionary] = []
+		var listed: Variant = action.get("events", [])
+		if listed is Array:
+			var bound: Array = listed
+			for event: Variant in bound:
+				if event is InputEvent:
+					var shaped: InputEvent = event
+					events.append(_shaped(shaped))
+		(
+			actions
+			. append(
+				{
+					"name": setting.trim_prefix("input/"),
+					"deadzone": GdhRead.as_float(action.get("deadzone", 0.5), 0.5),
+					"events": events,
+					"engineAction": engine_default != null,
+				}
+			)
+		)
+	return {"actions": actions, "count": actions.size()}
+
+
 # Remove an input action the project defines, which add_input_action had no way back from.
 func remove_input_action(params: Dictionary) -> Dictionary:
 	var action_name: String = str(params.get("action_name", ""))
@@ -305,6 +359,24 @@ func build_input_action(deadzone: float, events: Array) -> Dictionary:
 
 
 # The keycode for a key name as the tool spells it, or KEY_NONE for a name the table lacks.
+## The refusal for [param key_name], which names no key: the names nearest it, then every name taken,
+## since a name the caller has to guess at is the same guess again.
+static func _unknown_key(key_name: String) -> String:
+	var every: PackedStringArray = []
+	var named: PackedStringArray = []
+	for name: String in KEY_NAMES:
+		var _every: bool = every.append(name)
+		if name.length() > 1 and not (name.begins_with("F") and name.substr(1).is_valid_int()):
+			var _named: bool = named.append(name)
+	var nearest: PackedStringArray = GdhRead.nearest(key_name, every)
+	var said: String = "Unknown key: %s." % key_name
+	if nearest.size() == 1:
+		said += " The nearest key name is %s." % nearest[0]
+	elif not nearest.is_empty():
+		said += " The nearest key names are %s." % ", ".join(nearest)
+	return said + " A key is named by its letter, its digit, F1 to F12, or one of: %s." % ", ".join(named)
+
+
 func _keycode_value(key_name: String) -> int:
 	var wanted: String = key_name.to_lower()
 	for name: String in KEY_NAMES: