gdharness 1.3.0 → 1.3.2

package/build/godot/operations/file_reads.gd

@@ -10,9 +10,9 @@ extends RefCounted
 ## without making a node. Loading the file still does what loading does in the game: static
 ## initialisers run, and a resource with a script is made with it.
 
-const PropertyValues = preload("property_values.gd")
-const Read = preload("reading.gd")
-const Serialisation = preload("serialisation.gd")
+const GdhPropertyValues = preload("property_values.gd")
+const GdhRead = preload("reading.gd")
+const GdhSerialisation = preload("serialisation.gd")
 
 
 ## The nodes of [param scene_path] as {name, type, path, children}, with instanceOf and
@@ -42,13 +42,43 @@ static func scene_node(scene_path: String, node_path: String) -> Dictionary:
 	return {"ok": true, "name": found["name"], "type": found["type"], "properties": found["properties"]}
 
 
-## [param said], the refusal for [param node_path], which [param scene_path] does not have, with
-## where the path leaves the scene as [method Read.missing_below] says it.
-static func missing_from(said: String, scene_path: String, node_path: String) -> String:
+## The node at [param node_path] in [param scene_path] as [method scene_node] answers it, when it is
+## a [param kind]; otherwise a refusal saying what the scene has there and where its nodes of that
+## kind are, so the caller has the path to pass. The file is read once, because every load prints
+## the engine's warnings about it again.
+static func scene_node_of_kind(scene_path: String, node_path: String, kind: String) -> Dictionary:
 	var laid: Dictionary = _laid(scene_path)
 	if not laid.get("ok", false):
-		return said
+		return laid
 	var nodes: Dictionary = laid["nodes"]
+	var path: String = _joined(".", node_path)
+	var said: String = "%s not found at: %s" % [kind, node_path]
+	var found: String = ""
+	if nodes.has(path):
+		found = str(nodes[path]["type"])
+		if ClassDB.class_exists(found) and ClassDB.is_parent_class(found, kind):
+			return {
+				"ok": true,
+				"name": nodes[path]["name"],
+				"type": found,
+				"properties": nodes[path]["properties"]
+			}
+	else:
+		var hinted: String = said
+		if not nodes.has(_joined(".", node_path.get_slice("/", 0))):
+			hinted = GdhRead.from_the_root(said, node_path, str(nodes["."]["name"]))
+		said = hinted if hinted != said else _missing_in(nodes, said, node_path)
+	var held: PackedStringArray = []
+	for at: Variant in nodes:
+		var type: String = str(nodes[at]["type"])
+		if ClassDB.class_exists(type) and ClassDB.is_parent_class(type, kind):
+			var _held: bool = held.append(str(at))
+	return {"ok": false, "error": GdhRead.not_of_kind(said, node_path, found, kind, held)}
+
+
+## [param said], the refusal for [param node_path], which the scene laid as [param nodes] does not
+## have, with where the path leaves the scene as [method GdhRead.missing_below] says it.
+static func _missing_in(nodes: Dictionary, said: String, node_path: String) -> String:
 	var parts: PackedStringArray = node_path.trim_prefix("./").split("/", false)
 	var at: String = "."
 	var reached: PackedStringArray = []
@@ -64,7 +94,7 @@ static func missing_from(said: String, scene_path: String, node_path: String) ->
 	var children: Array[String] = nodes[at]["children"]
 	for child: String in children:
 		var _named: bool = names.append(str(nodes[child]["name"]))
-	return Read.missing_below(said, str(nodes["."]["name"]), reached, parts[reached.size()], names)
+	return GdhRead.missing_below(said, str(nodes["."]["name"]), reached, parts[reached.size()], names)
 
 
 ## Every node of [param scene_path] as {ok, nodes}, keyed by path, or a refusal.
@@ -77,15 +107,14 @@ static func _laid(scene_path: String) -> Dictionary:
 	if loaded == null:
 		return {"ok": false, "error": "Failed to load %s as a scene" % scene_path}
 	if not loaded is PackedScene:
-		var kind: String = loaded.get_class()
-		var sort: String = ("an " if kind.left(1).to_upper() in ["A", "E", "I", "O", "U"] else "a ") + kind
+		var sort: String = GdhRead.with_article(loaded.get_class())
 		return {
 			"ok": false,
 			"error": "%s is %s, not a scene: resource_edit read reads its properties." % [scene_path, sort]
 		}
 	var packed: PackedScene = loaded
 	var nodes: Dictionary = {}
-	var refused: String = _lay(packed.get_state(), ".", nodes, [scene_path])
+	var refused: String = _lay(packed.get_state(), ".", nodes, [scene_path], packed)
 	if not refused.is_empty():
 		return {"ok": false, "error": refused}
 	if not nodes.has("."):
@@ -99,8 +128,11 @@ static func _laid(scene_path: String) -> Dictionary:
 ##
 ## [param within] is the files being laid, outermost first, so a scene that instances one of them
 ## is refused rather than laid forever; the engine refuses to load such a scene, so this is only
-## reached through a state built some other way.
-static func _lay(state: SceneState, prefix: String, nodes: Dictionary, within: Array) -> String:
+## reached through a state built some other way. [param loaded] is the scene [param state] is read
+## from, when the caller has it loaded already.
+static func _lay(
+	state: SceneState, prefix: String, nodes: Dictionary, within: Array, loaded: PackedScene = null
+) -> String:
 	var base: SceneState = state.get_base_scene_state()
 	if base != null and not nodes.has(prefix):
 		var refused: String = _lay(base, prefix, nodes, within)
@@ -164,7 +196,7 @@ static func _lay(state: SceneState, prefix: String, nodes: Dictionary, within: A
 	# Only the scene being read and the scenes it inherits share its root, the owner whose editable
 	# instances a write here sets; a file instanced below makes its own owner's editable.
 	if prefix == ".":
-		for editable: String in _editable_in(state.get_path()):
+		for editable: String in _editable_in(state.get_path(), loaded):
 			var at: String = _joined(prefix, editable)
 			var marked: Dictionary = nodes.get(at, {})
 			if marked.has("editableChildren"):
@@ -173,10 +205,13 @@ static func _lay(state: SceneState, prefix: String, nodes: Dictionary, within: A
 
 
 ## The paths of the instances [param scene_path] gives editable children, from its root. SceneState
-## does not give them to a script, so they are read off the scene's bundle.
-static func _editable_in(scene_path: String) -> PackedStringArray:
+## does not give them to a script, so they are read off the scene's bundle: [param given_scene]'s,
+## when the caller has the file loaded, since loading it again prints its warnings again.
+static func _editable_in(scene_path: String, given_scene: PackedScene = null) -> PackedStringArray:
 	var found: PackedStringArray = []
-	var loaded: Resource = ResourceLoader.load(scene_path, "", ResourceLoader.CACHE_MODE_IGNORE)
+	var loaded: Resource = given_scene
+	if loaded == null:
+		loaded = ResourceLoader.load(scene_path, "", ResourceLoader.CACHE_MODE_IGNORE)
 	if not loaded is PackedScene:
 		return found
 	var given: Variant = loaded.get("_bundled")
@@ -236,7 +271,7 @@ static func _by_id(nodes: Dictionary, owner: String, id: int) -> String:
 		if path == owner or not (owner == "." or path.begins_with(owner + "/")):
 			continue
 		var entry: Dictionary = nodes[path]
-		if Read.as_int(entry.get("uniqueId", -1), -1) != id:
+		if GdhRead.as_int(entry.get("uniqueId", -1), -1) != id:
 			continue
 		var above: String = "." if not path.contains("/") else path.get_base_dir()
 		if _owner_of(nodes, above, owner) == owner:
@@ -311,7 +346,7 @@ static func _stored(type: String, given: Dictionary) -> Dictionary:
 	if script != null:
 		for declared: Dictionary in script.get_script_property_list():
 			var property: String = str(declared.get("name", ""))
-			if not property.is_empty() and Read.as_int(declared.get("usage", 0)) & PROPERTY_USAGE_STORAGE:
+			if not property.is_empty() and GdhRead.as_int(declared.get("usage", 0)) & PROPERTY_USAGE_STORAGE:
 				scripted[property] = script.get_property_default_value(property)
 	var values: Dictionary = {}
 	if ClassDB.class_exists(type) and ClassDB.can_instantiate(type):
@@ -321,7 +356,7 @@ static func _stored(type: String, given: Dictionary) -> Dictionary:
 				bare.set(str(property), given[property])
 		for declared: Dictionary in bare.get_property_list():
 			var property: String = str(declared.get("name", ""))
-			if not property.is_empty() and Read.as_int(declared.get("usage", 0)) & PROPERTY_USAGE_STORAGE:
+			if not property.is_empty() and GdhRead.as_int(declared.get("usage", 0)) & PROPERTY_USAGE_STORAGE:
 				values[property] = bare.get(property)
 		if bare is Node:
 			bare.free()
@@ -330,7 +365,7 @@ static func _stored(type: String, given: Dictionary) -> Dictionary:
 	# Given last, which keeps what a bare node cannot hold: the script itself, and a path to a node
 	# for a property that holds the node once it is in a tree.
 	values.merge(given, true)
-	var serialiser: Serialisation = Serialisation.new()
+	var serialiser: GdhSerialisation = GdhSerialisation.new()
 	var answered: Dictionary = {}
 	for property: Variant in values:
 		answered[property] = serialiser.serialize_value(values[property])
@@ -369,13 +404,13 @@ static func resource(res_path: String, include_defaults: bool) -> Dictionary:
 	if script != null:
 		for declared: Dictionary in script.get_script_property_list():
 			scripted[str(declared.get("name", ""))] = true
-	var serialiser: Serialisation = Serialisation.new()
+	var serialiser: GdhSerialisation = GdhSerialisation.new()
 	var properties: Dictionary = {}
 	for p: Dictionary in loaded.get_property_list():
 		var property: String = str(p.get("name", ""))
 		if property.is_empty() or property == "script":
 			continue
-		if not (Read.as_int(p.get("usage", 0)) & PROPERTY_USAGE_STORAGE):
+		if not (GdhRead.as_int(p.get("usage", 0)) & PROPERTY_USAGE_STORAGE):
 			continue
 		var value: Variant = loaded.get(property)
 		if not include_defaults:
@@ -384,7 +419,7 @@ static func resource(res_path: String, include_defaults: bool) -> Dictionary:
 				if scripted.has(property)
 				else ClassDB.class_get_property_default_value(loaded.get_class(), property)
 			)
-			if PropertyValues.same(value, default):
+			if GdhPropertyValues.same(value, default):
 				continue
 		properties[property] = serialiser.serialize_value(value)
 	var answer: Dictionary = {
@@ -392,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
 
 
@@ -412,7 +452,7 @@ static func _kept_in(value: Variant, file: String, id: String, seen: Dictionary)
 		if held.resource_scene_unique_id == id:
 			return held
 		for p: Dictionary in held.get_property_list():
-			if Read.as_int(p.get("usage", 0)) & PROPERTY_USAGE_STORAGE:
+			if GdhRead.as_int(p.get("usage", 0)) & PROPERTY_USAGE_STORAGE:
 				var found: Resource = _kept_in(held.get(str(p.get("name", ""))), file, id, seen)
 				if found != null:
 					return found

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,16 +1,17 @@
 extends RefCounted
 
-const Dependencies = preload("dependencies.gd")
-const Patterns = preload("patterns.gd")
-const Read = preload("reading.gd")
-const Log = preload("logger.gd")
+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")
 
-var _log: Log
+var _log: GdhLog
 ## Kept for the call, so the project's class names are read once however many bases are walked.
-var _dependencies: Dependencies = null
+var _dependencies: GdhDependencies = null
 
 
-func _init(p_log: Log) -> void:
+func _init(p_log: GdhLog) -> void:
 	_log = p_log
 
 
@@ -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:
@@ -62,7 +67,7 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 			if _triple_quotes(raw) % 2 == 1:
 				in_multiline_string = false
 			continue
-		var stripped: String = Patterns.without_comment(raw)
+		var stripped: String = GdhPatterns.without_comment(raw)
 
 		if stripped.is_empty():
 			continue
@@ -85,7 +90,7 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 		# on the line with them off. `@abstract class_name X` was reported as no declared class,
 		# and `@abstract func x()` and `@warning_ignore("...") func x()` as no function at all:
 		# gdUnit4 alone declares 248 methods that way and this answered with none of them.
-		var header: String = Patterns.without_annotations(stripped)
+		var header: String = GdhPatterns.without_annotations(stripped)
 
 		var at: int = i
 		# A declaration wrapped across lines is one declaration, and reading the first line alone
@@ -104,9 +109,9 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 		if _can_wrap(header):
 			while _bracket_depth(stripped) > 0 and i + 1 < lines.size():
 				i += 1
-				stripped = (stripped + " " + Patterns.without_comment(lines[i])).strip_edges()
-			header = Patterns.without_annotations(stripped)
-		var declaration: RegExMatch = Patterns.declared_class(header)
+				stripped = (stripped + " " + GdhPatterns.without_comment(lines[i])).strip_edges()
+			header = GdhPatterns.without_annotations(stripped)
+		var declaration: RegExMatch = GdhPatterns.declared_class(header)
 		if declaration != null:
 			declared_class_name = declaration.get_string(1)
 			# `class_name X extends Y` is also one line, and taking the rest of it as the name
@@ -144,9 +149,9 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 	# named it. The same reading as that tool's, so the two agree.
 	var classes_used: Array[Dictionary] = []
 	if _dependencies == null:
-		_dependencies = Dependencies.new(_log)
+		_dependencies = GdhDependencies.new(_log)
 	var declared_by: Dictionary = _dependencies.classes_declared()
-	for used: String in Dependencies.classes_used_in(content, declared_by):
+	for used: String in GdhDependencies.classes_used_in(content, declared_by):
 		var declaring: String = str(declared_by[used])
 		if declaring == full_script_path:
 			continue
@@ -165,7 +170,7 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 		if value.begins_with("*"):
 			global_autoloads[setting.trim_prefix("autoload/")] = value.trim_prefix("*")
 	var autoloads_used: Array[Dictionary] = []
-	for used: String in Dependencies.classes_used_in(content, global_autoloads):
+	for used: String in GdhDependencies.classes_used_in(content, global_autoloads):
 		if str(global_autoloads[used]) != full_script_path:
 			autoloads_used.append({"name": used, "path": str(global_autoloads[used])})
 
@@ -183,9 +188,9 @@ 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 Read.as_bool(params.get("include_inherited", false)):
+	if GdhRead.as_bool(params.get("include_inherited", false)):
 		_add_inherited(answer, [full_script_path])
 	return answer
 
@@ -202,7 +207,7 @@ func _mark_virtuals(functions: Array[Dictionary], extends_name: String, from_pat
 	var virtuals: Dictionary = {}
 	if not native.is_empty():
 		for m: Dictionary in ClassDB.class_get_method_list(native, false):
-			var flags: int = Read.as_int(m.get("flags", 0))
+			var flags: int = GdhRead.as_int(m.get("flags", 0))
 			if flags & METHOD_FLAG_VIRTUAL:
 				virtuals[str(m.get("name", ""))] = true
 	for one: Dictionary in functions:
@@ -366,7 +371,7 @@ func _parse_variable(line: String, line_num: int) -> Dictionary:
 
 	# From the annotations themselves rather than from where they sit. `@onready @export var x` put
 	# the export second and so read as not exported, and a hint with a space in it was cut at it.
-	for one: String in Patterns.annotations_on(line):
+	for one: String in GdhPatterns.annotations_on(line):
 		if one.begins_with("export"):
 			is_export = true
 			var after: String = one.substr(6)
@@ -457,7 +462,7 @@ func _parse_function(line: String, line_num: int, annotated: String = "") -> Dic
 		"is_static": is_static,
 		# Said rather than left to be inferred: an abstract method has no body, so a caller that
 		# saw only the declaration would otherwise take it for one whose body it failed to read.
-		"is_abstract": "abstract" in Patterns.annotations_on(annotated),
+		"is_abstract": "abstract" in GdhPatterns.annotations_on(annotated),
 		"line": line_num
 	}
 
@@ -624,7 +629,7 @@ static func _triple_quotes(line: String) -> int:
 
 func _extract_dependencies(line: String) -> Array[String]:
 	var deps: Array[String] = []
-	var regex: RegEx = Patterns.compiled("(?:preload|load)\\s*\\(\\s*[\"']([^\"']+)[\"']\\s*\\)")
+	var regex: RegEx = GdhPatterns.compiled("(?:preload|load)\\s*\\(\\s*[\"']([^\"']+)[\"']\\s*\\)")
 
 	for m: RegExMatch in regex.search_all(line):
 		deps.append(m.get_string(1))

package/build/godot/operations/gdscript_authoring.gd

@@ -1,16 +1,18 @@
 extends RefCounted
 
-const Read = preload("reading.gd")
-const Log = preload("logger.gd")
-const Patterns = preload("patterns.gd")
+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
 
-var _log: Log
+var _log: GdhLog
 
 
-func _init(p_log: Log) -> void:
+func _init(p_log: GdhLog) -> void:
 	_log = p_log
 
 
@@ -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
@@ -231,14 +329,14 @@ static func _modification_problems(modifications: Array, declared: Dictionary) -
 # one: variables, constants, signals, functions, enums and inner classes, which share one namespace.
 static func _declared(lines: Array[String]) -> Dictionary:
 	var found: Dictionary = {}
-	var declaration: RegEx = Patterns.compiled(
+	var declaration: RegEx = GdhPatterns.compiled(
 		"^(?:static\\s+)?(var|const|signal|func|enum|class)\\s+([A-Za-z_][A-Za-z0-9_]*)"
 	)
 	for i: int in range(lines.size()):
 		var raw: String = lines[i]
 		if raw.is_empty() or raw[0] == "\t" or raw[0] == " ":
 			continue
-		var matched: RegExMatch = declaration.search(Patterns.without_annotations(raw))
+		var matched: RegExMatch = declaration.search(GdhPatterns.without_annotations(raw))
 		if matched != null and not found.has(matched.get_string(2)):
 			found[matched.get_string(2)] = {"kind": matched.get_string(1), "line": i + 1}
 	return found
@@ -286,7 +384,7 @@ func _add_constant(lines: Array[String], mod: Dictionary, placed: Array[Dictiona
 	var const_line: String = "const %s: %s = %s" % [str(mod.get("name", "")), declared_type, value]
 	var after: int = 0
 	for i: int in range(lines.size()):
-		var line: String = Patterns.without_annotations(lines[i])
+		var line: String = GdhPatterns.without_annotations(lines[i])
 		if (
 			line.begins_with("extends ")
 			or line.begins_with("class_name ")
@@ -310,9 +408,9 @@ func _add_variable(lines: Array[String], mod: Dictionary, placed: Array[Dictiona
 	var var_name: String = str(mod.get("name", ""))
 	var var_type: String = str(mod.get("varType", ""))
 	var default_value: String = str(mod.get("defaultValue", ""))
-	var is_export: bool = Read.as_bool(mod.get("isExport", false))
+	var is_export: bool = GdhRead.as_bool(mod.get("isExport", false))
 	var export_hint: String = str(mod.get("exportHint", ""))
-	var is_onready: bool = Read.as_bool(mod.get("isOnready", false))
+	var is_onready: bool = GdhRead.as_bool(mod.get("isOnready", false))
 
 	var var_line: String = ""
 
@@ -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
 
 
@@ -433,7 +536,7 @@ func _variable_insertion_point(lines: Array[String]) -> int:
 		# takes the new line above the `class_name`, where it does not parse; one that declares
 		# `extends` first takes it between the two, which does not parse either. Stripping also
 		# turns `@export var x` into `var x`, which is why the annotation names are gone below.
-		var line: String = Patterns.without_annotations(lines[i])
+		var line: String = GdhPatterns.without_annotations(lines[i])
 		if line.begins_with("extends ") or line.begins_with("class_name "):
 			after_header = i + 1
 		elif line.begins_with("signal "):
@@ -443,7 +546,7 @@ func _variable_insertion_point(lines: Array[String]) -> int:
 			break
 
 	for i: int in range(after_header, before_func):
-		if Patterns.without_annotations(lines[i]).begins_with("var "):
+		if GdhPatterns.without_annotations(lines[i]).begins_with("var "):
 			after_header = i + 1
 
 	return after_header
@@ -455,7 +558,7 @@ func _signal_insertion_point(lines: Array[String]) -> int:
 	for i: int in range(lines.size()):
 		# As above: the annotations come off before the line is read, so an abstract class has a
 		# header to find and `@export var x` reads as the var it is.
-		var line: String = Patterns.without_annotations(lines[i])
+		var line: String = GdhPatterns.without_annotations(lines[i])
 		if line.begins_with("extends ") or line.begins_with("class_name "):
 			after_header = i + 1
 		elif line.begins_with("signal "):
@@ -485,7 +588,7 @@ func _line_after_function(lines: Array[String], prefix: String) -> int:
 		# ends of this. An annotated `_ready` was never found, so `after_ready` placed the new
 		# function at the end of the file, and an annotated function after `_ready` was not the
 		# boundary it is, so the new one went in after whichever later function was plain.
-		var line: String = Patterns.without_annotations(lines[i])
+		var line: String = GdhPatterns.without_annotations(lines[i])
 		if line.begins_with(prefix):
 			inside = true
 		elif inside and (line.begins_with("func ") or line.begins_with("static func ")):
@@ -502,7 +605,9 @@ static func _start_of_declaration(lines: Array[String], at: int) -> int:
 	var start: int = at
 	while start > 0 and _indentation(lines[start - 1]) == indent:
 		var above: String = lines[start - 1].strip_edges()
-		var annotation_only: bool = above.begins_with("@") and Patterns.without_annotations(above).is_empty()
+		var annotation_only: bool = (
+			above.begins_with("@") and GdhPatterns.without_annotations(above).is_empty()
+		)
 		if not above.begins_with("#") and not annotation_only:
 			break
 		start -= 1