gdharness 1.2.31 → 1.2.32

package/build/godot/operations/file_reads.gd

@@ -0,0 +1,237 @@
+extends RefCounted
+
+## Scenes and resources read from their files, by the editor's tools and by a headless engine with
+## none connected, so a read answers the same either way.
+##
+## A scene is read off its SceneState rather than instantiated. Instantiating outside the editor
+## runs every script's member initialisers and _init (measured on 4.7.2, with or without -e), so a
+## read with no editor would have run the game's code on every node; the editor gets placeholders
+## and runs none. The state holds everything the file says, and the scenes it instances theirs,
+## 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")
+
+
+## The nodes of [param scene_path] as {name, type, path, children}, with instanceOf on a node that
+## instances another scene and every stored property when [param include_properties] is set, the
+## file's value or the default where it sets none. [param depth] -1 reads every level.
+static func scene_tree(scene_path: String, depth: int, include_properties: bool) -> Dictionary:
+	if not FileAccess.file_exists(scene_path):
+		return {"ok": false, "error": "Scene not found: " + scene_path}
+	# Loaded without naming the type, so a resource handed in by mistake loads as what it is and the
+	# refusal can say so, where asking for a PackedScene printed the loader's error and a backtrace.
+	var loaded: Resource = ResourceLoader.load(scene_path, "", ResourceLoader.CACHE_MODE_IGNORE)
+	if loaded == null:
+		return {"ok": false, "error": "Failed to load %s as a scene" % scene_path}
+	if not loaded is PackedScene:
+		return {
+			"ok": false,
+			"error":
+			(
+				"%s is a %s, not a scene: resource_edit read reads its properties."
+				% [scene_path, loaded.get_class()]
+			)
+		}
+	var packed: PackedScene = loaded
+	var nodes: Dictionary = {}
+	var refused: String = _lay(packed.get_state(), ".", nodes, [scene_path])
+	if not refused.is_empty():
+		return {"ok": false, "error": refused}
+	if not nodes.has("."):
+		return {"ok": false, "error": "%s holds no nodes" % scene_path}
+	return {"ok": true, "tree": _entry(nodes, ".", include_properties, depth, 0)}
+
+
+## Lays the nodes of [param state] into [param nodes] under [param prefix], keyed by their path
+## from the outermost root, each instanced scene laid where it is instanced and the instancing
+## file's own entries for it applied over it. Answers a refusal, or "".
+##
+## [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:
+	var base: SceneState = state.get_base_scene_state()
+	if base != null and not nodes.has(prefix):
+		var refused: String = _lay(base, prefix, nodes, within)
+		if not refused.is_empty():
+			return refused
+	for index: int in state.get_node_count():
+		var path: String = _joined(prefix, str(state.get_node_path(index)))
+		var fresh: bool = not nodes.has(path)
+		if fresh:
+			var instance: PackedScene = state.get_node_instance(index)
+			if instance != null:
+				if within.has(instance.resource_path):
+					return "%s instances %s, which holds it" % [within.back(), instance.resource_path]
+				var refused: String = _lay(
+					instance.get_state(), path, nodes, within + [instance.resource_path]
+				)
+				if not refused.is_empty():
+					return refused
+				if not nodes.has(path):
+					return "%s holds no nodes" % instance.resource_path
+				nodes[path]["instanceOf"] = instance.resource_path
+			elif state.is_node_instance_placeholder(index):
+				nodes[path] = _made("InstancePlaceholder")
+				nodes[path]["instanceOf"] = state.get_node_instance_placeholder(index)
+			elif str(state.get_node_type(index)).is_empty():
+				# An entry for a node of an instance that no longer has it, which the engine skips too.
+				continue
+			else:
+				nodes[path] = _made(str(state.get_node_type(index)))
+		# The name is the state's even for an entry laid already, since an inherited scene names its
+		# root itself; a root instanced inside another scene is renamed by that scene once laid.
+		nodes[path]["name"] = str(state.get_node_name(index))
+		if fresh:
+			# The root of what is laid here is placed by whoever instanced it.
+			if path != prefix:
+				_place(
+					nodes,
+					_joined(prefix, str(state.get_node_path(index, true))),
+					path,
+					state.get_node_index(index)
+				)
+		var held: Dictionary = nodes[path]["properties"]
+		for property: int in state.get_node_property_count(index):
+			held[str(state.get_node_property_name(index, property))] = state.get_node_property_value(
+				index, property
+			)
+	return ""
+
+
+static func _made(type: String) -> Dictionary:
+	var children: Array[String] = []
+	return {"name": "", "type": type, "properties": {}, "children": children}
+
+
+## Puts [param path] among [param parent]'s children, at [param at] when the file says where (a node
+## added inside an instance) and last when it does not.
+static func _place(nodes: Dictionary, parent: String, path: String, at: int) -> void:
+	if not nodes.has(parent):
+		return
+	var children: Array[String] = nodes[parent]["children"]
+	if at >= 0 and at < children.size():
+		var _placed: int = children.insert(at, path)
+	else:
+		children.append(path)
+
+
+## [param given], a path as a SceneState gives it ("." or "./Body/Tail"), under [param prefix].
+static func _joined(prefix: String, given: String) -> String:
+	var relative: String = given.trim_prefix("./")
+	if relative == "." or relative.is_empty():
+		return prefix
+	if prefix == ".":
+		return relative
+	return prefix + "/" + relative
+
+
+static func _entry(
+	nodes: Dictionary, path: String, include_properties: bool, depth: int, current_depth: int
+) -> Dictionary:
+	var node: Dictionary = nodes[path]
+	var children: Array[Dictionary] = []
+	var data: Dictionary = {"name": node["name"], "type": node["type"], "path": path, "children": children}
+	# The root's file is the scene being read, so only another node's names a second scene.
+	if path != "." and node.has("instanceOf"):
+		data["instanceOf"] = node["instanceOf"]
+	if include_properties:
+		var given: Dictionary = node["properties"]
+		data["properties"] = _stored(str(node["type"]), given)
+	if depth >= 0 and current_depth >= depth:
+		return data
+	for child: String in node["children"]:
+		children.append(_entry(nodes, child, include_properties, depth, current_depth + 1))
+	return data
+
+
+## Every property a node of [param type] stores, with the value [param given] sets or the default,
+## read as a node holding those values would answer them.
+##
+## The engine's half is read off a bare node of the class with the file's values set on it, which
+## runs no script: what a node lists depends on its values (a thread group's settings appear only
+## once it has one) and some setters set others (a Control's anchors preset sets how it grows), so
+## the class's defaults and the file's entries alone answered neither. The script's half is its
+## declared defaults under the file's values.
+static func _stored(type: String, given: Dictionary) -> Dictionary:
+	var attached: Variant = given.get("script")
+	var script: Script = attached if attached is Script else null
+	var scripted: 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:
+				scripted[property] = script.get_property_default_value(property)
+	var values: Dictionary = {}
+	if ClassDB.class_exists(type) and ClassDB.can_instantiate(type):
+		var bare: Object = ClassDB.instantiate(type)
+		for property: Variant in given:
+			if property != "script" and not scripted.has(property):
+				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:
+				values[property] = bare.get(property)
+		if bare is Node:
+			bare.free()
+	for property: String in scripted:
+		values[property] = scripted[property]
+	# 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 answered: Dictionary = {}
+	for property: Variant in values:
+		answered[property] = serialiser.serialize_value(values[property])
+	return answered
+
+
+## What a resource file holds, in the form modify takes, so a value read here can be written back.
+## Read from the file rather than a cached copy, since the file is what the writes change and what
+## the project loads.
+static func resource(res_path: String, include_defaults: bool) -> Dictionary:
+	if not FileAccess.file_exists(res_path):
+		return {"ok": false, "error": "No resource at " + res_path}
+	var loaded: Resource = ResourceLoader.load(res_path, "", ResourceLoader.CACHE_MODE_IGNORE)
+	if loaded == null:
+		return {"ok": false, "error": "%s did not load as a resource." % res_path}
+	# A scene's own properties are its packed bundle, which says nothing a caller can use.
+	if loaded is PackedScene:
+		return {
+			"ok": false,
+			"error":
+			"%s is a scene: scene_tree reads its nodes, and scene_node get one node's properties." % res_path
+		}
+
+	var script: Script = loaded.get_script()
+	var scripted: 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 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):
+			continue
+		var value: Variant = loaded.get(property)
+		if not include_defaults:
+			var default: Variant = (
+				script.get_property_default_value(property)
+				if scripted.has(property)
+				else ClassDB.class_get_property_default_value(loaded.get_class(), property)
+			)
+			if PropertyValues.same(value, default):
+				continue
+		properties[property] = serialiser.serialize_value(value)
+	var answer: Dictionary = {
+		"ok": true, "resourcePath": res_path, "resourceType": loaded.get_class(), "properties": properties
+	}
+	if script != null:
+		answer["script"] = script.resource_path
+	return answer

package/build/godot/operations/gdscript_authoring.gd

@@ -4,6 +4,9 @@ const Read = preload("reading.gd")
 const Log = preload("logger.gd")
 const Patterns = preload("patterns.gd")
 
+const MODIFICATION_TYPES: Array[String] = ["add_constant", "add_variable", "add_signal", "add_function"]
+const BLANKS_AROUND_FUNCTIONS: int = 2
+
 var _log: Log
 
 
@@ -49,7 +52,9 @@ func create_gdscript(params: Dictionary) -> Dictionary:
 		return _log.failure("Script path must end with .gd extension")
 
 	if FileAccess.file_exists(full_script_path):
-		return _log.failure("Script file already exists: " + full_script_path)
+		return _log.failure(
+			"Script file already exists: " + full_script_path + ". script_edit modify adds to it."
+		)
 
 	var dir: DirAccess = DirAccess.open("res://")
 	var script_dir: String = full_script_path.get_base_dir()
@@ -115,14 +120,14 @@ func modify_gdscript(params: Dictionary) -> Dictionary:
 	var original_content: String = file.get_as_text()
 	file.close()
 
+	var lines: Array[String] = []
+	lines.assign(original_content.split("\n"))
+
 	# 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.
-	var problems: Array[String] = _modification_problems(modifications)
+	var problems: Array[String] = _modification_problems(modifications, _declared(lines))
 	if not problems.is_empty():
 		return _log.failure("Nothing was changed: " + "; ".join(problems))
-
-	var lines: Array[String] = []
-	lines.assign(original_content.split("\n"))
 	# Each placed line as a zero-based index that moves down whenever a later insertion lands above
 	# it, so the numbers answered are where the lines are in the file written, not where each went
 	# at the moment it was placed.
@@ -133,6 +138,8 @@ func modify_gdscript(params: Dictionary) -> Dictionary:
 		var mod_type: String = str(fields.get("type", ""))
 		var at: int = -1
 		match mod_type:
+			"add_constant":
+				at = _add_constant(lines, fields, placed)
 			"add_variable":
 				at = _add_variable(lines, fields, placed)
 			"add_signal":
@@ -170,10 +177,15 @@ func modify_gdscript(params: Dictionary) -> Dictionary:
 
 
 # Every reason [param modifications] cannot be made as asked, each naming the entry by position.
-static func _modification_problems(modifications: Array) -> Array[String]:
+#
+# A name the script already declares is one of them, as is one the call adds twice. GDScript gives a
+# class one namespace for its members, so a second `maximum` does not parse; and the engine reports
+# only the first error it meets, so a second `func damage` behind it was written with nothing said.
+static func _modification_problems(modifications: Array, declared: Dictionary) -> Array[String]:
 	var problems: Array[String] = []
 	if modifications.is_empty():
 		problems.append("modifications is empty")
+	var added: Dictionary = {}
 	for index: int in range(modifications.size()):
 		var mod: Variant = modifications[index]
 		var which: String = "modification " + str(index + 1)
@@ -183,17 +195,55 @@ static func _modification_problems(modifications: Array) -> Array[String]:
 		var fields: Dictionary = mod
 		var mod_type: String = str(fields.get("type", ""))
 		var mod_name: String = str(fields.get("name", ""))
-		if mod_type not in ["add_variable", "add_signal", "add_function"]:
+		if mod_type not in MODIFICATION_TYPES:
 			problems.append(
-				which + " has type '" + mod_type + "', not add_variable, add_signal or add_function"
+				(
+					which
+					+ " has type '"
+					+ mod_type
+					+ "', not add_constant, add_variable, add_signal or add_function"
+				)
 			)
+		if mod_type == "add_constant" and str(fields.get("defaultValue", "")).is_empty():
+			problems.append(which + " is a constant with no defaultValue, and a constant needs a value")
 		if mod_name.is_empty():
 			problems.append(which + " has no name")
-		elif not mod_name.is_valid_unicode_identifier():
+			continue
+		if not mod_name.is_valid_unicode_identifier():
 			problems.append(which + " is named '" + mod_name + "', which GDScript does not accept as a name")
+			continue
+		if declared.has(mod_name):
+			var existing: Dictionary = declared[mod_name]
+			problems.append(
+				(
+					"%s adds %s, and the script already declares %s %s on line %d"
+					% [which, mod_name, existing["kind"], mod_name, existing["line"]]
+				)
+			)
+		elif added.has(mod_name):
+			problems.append("%s adds %s, which modification %d adds too" % [which, mod_name, added[mod_name]])
+		else:
+			added[mod_name] = index + 1
 	return problems
 
 
+# The members [param lines] declares at the top level, by name, as {"kind", "line"} counted from
+# 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(
+		"^(?: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))
+		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
+
+
 # Inserts [param new_lines] at [param at] and moves every placed line at or below it down by as many.
 static func _insert(
 	lines: Array[String], at: int, new_lines: Array[String], placed: Array[Dictionary]
@@ -226,6 +276,35 @@ static func _base_named(script: Script) -> String:
 	return named if not named.is_empty() else base.resource_path
 
 
+# A constant, typed as a variable is and placed after the header, the signals and the constants
+# already there, which is where the style guide puts them. Its zero-based index, or -1.
+func _add_constant(lines: Array[String], mod: Dictionary, placed: Array[Dictionary]) -> int:
+	var value: String = str(mod.get("defaultValue", ""))
+	var declared_type: String = str(mod.get("varType", ""))
+	if declared_type.is_empty():
+		declared_type = _type_of_literal(value)
+	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])
+		if (
+			line.begins_with("extends ")
+			or line.begins_with("class_name ")
+			or line.begins_with("signal ")
+			or line.begins_with("const ")
+		):
+			after = i + 1
+		elif (
+			line.begins_with("var ")
+			or line.begins_with("func ")
+			or line.begins_with("static ")
+			or line.begins_with("enum ")
+			or line.begins_with("class ")
+		):
+			break
+	return after if _insert(lines, after, [const_line], placed) else -1
+
+
 # Inserts the declaration and answers with its zero-based index, or -1 for one that could not be placed.
 func _add_variable(lines: Array[String], mod: Dictionary, placed: Array[Dictionary]) -> int:
 	var var_name: String = str(mod.get("name", ""))
@@ -293,7 +372,12 @@ func _add_signal(lines: Array[String], mod: Dictionary, placed: Array[Dictionary
 	return insert_line if _insert(lines, insert_line, [signal_line], placed) else -1
 
 
-# Answers with the zero-based index of the `func` line, below the blank line that separates it.
+# Answers with the zero-based index of the `func` line, below the blank lines that separate it.
+#
+# Two blank lines on each side, counting those already there, because that is the spacing GDScript's
+# style guide gives functions and the one gdformat writes and gdlint checks: one blank line passed
+# the engine and failed every project gating on either. A function last in the file ends it with a
+# newline, which the file is written with only when its last line is empty.
 func _add_function(lines: Array[String], mod: Dictionary, placed: Array[Dictionary]) -> int:
 	var func_name: String = str(mod.get("name", ""))
 	var func_params: String = str(mod.get("params", ""))
@@ -305,21 +389,34 @@ func _add_function(lines: Array[String], mod: Dictionary, placed: Array[Dictiona
 	var body: String = str(mod.get("body", "pass"))
 	var position: String = str(mod.get("position", "end"))
 
+	var insert_line: int = _function_insertion_point(lines, position)
 	var func_lines: Array[String] = []
-	var func_decl: String = "func " + func_name + "(" + func_params + ") -> " + return_type + ":"
-	func_lines.append("")
-	func_lines.append(func_decl)
+	for i: int in range(_blank_run(lines, insert_line - 1, -1), BLANKS_AROUND_FUNCTIONS):
+		func_lines.append("")
+	var declared_at: int = insert_line + func_lines.size()
+	func_lines.append("func " + func_name + "(" + func_params + ") -> " + return_type + ":")
 
 	for bl: String in body.split("\n"):
 		func_lines.append("\t" + bl)
 
-	var insert_line: int = _function_insertion_point(lines, position)
-	# A separator on the far side too when something follows, since `after_ready` and `after_init`
-	# put the new function immediately above an existing one and left the two declarations touching.
-	if insert_line < lines.size():
+	var below: int = _blank_run(lines, insert_line, 1)
+	if insert_line + below < lines.size():
+		for i: int in range(below, BLANKS_AROUND_FUNCTIONS):
+			func_lines.append("")
+	elif below == 0:
 		func_lines.append("")
 
-	return insert_line + 1 if _insert(lines, insert_line, func_lines, placed) else -1
+	return declared_at if _insert(lines, insert_line, func_lines, placed) else -1
+
+
+# How many blank lines run from [param from] on in the direction of [param step], 1 or -1.
+static func _blank_run(lines: Array[String], from: int, step: int) -> int:
+	var count: int = 0
+	var at: int = from
+	while at >= 0 and at < lines.size() and lines[at].strip_edges().is_empty():
+		count += 1
+		at += step
+	return count
 
 
 func _variable_insertion_point(lines: Array[String]) -> int:
@@ -389,10 +486,30 @@ func _line_after_function(lines: Array[String], prefix: String) -> int:
 		if line.begins_with(prefix):
 			inside = true
 		elif inside and (line.begins_with("func ") or line.begins_with("static func ")):
-			return i
+			return _start_of_declaration(lines, i)
 	return lines.size()
 
 
+# The first line belonging to the declaration on [param at]: the comments and the lines holding only
+# annotations directly above it, at its indentation. A function placed on [param at] itself takes the
+# next function's doc comment, which then documents the wrong one, and its `@rpc` line, which then
+# annotates it. A comment indented further is the end of the body above, and stays with it.
+static func _start_of_declaration(lines: Array[String], at: int) -> int:
+	var indent: String = _indentation(lines[at])
+	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()
+		if not above.begins_with("#") and not annotation_only:
+			break
+		start -= 1
+	return start
+
+
+static func _indentation(line: String) -> String:
+	return line.substr(0, line.length() - line.strip_edges(true, false).length())
+
+
 func _script_template(template_name: String) -> String:
 	match template_name:
 		"singleton":

package/build/godot/operations/godot_operations.gd

@@ -18,6 +18,7 @@ const AudioBuses = preload("audio_buses.gd")
 const ClassCache = preload("class_cache.gd")
 const ClassDbQueries = preload("classdb_queries.gd")
 const Dependencies = preload("dependencies.gd")
+const FileReads = preload("file_reads.gd")
 const GdscriptAnalysis = preload("gdscript_analysis.gd")
 const GdscriptAuthoring = preload("gdscript_authoring.gd")
 const ImportPipeline = preload("import_pipeline.gd")
@@ -26,6 +27,7 @@ const Log = preload("logger.gd")
 const Plugins = preload("plugins.gd")
 const ProjectConfig = preload("project_config.gd")
 const ProjectDiagnostics = preload("project_diagnostics.gd")
+const Read = preload("reading.gd")
 const RenameChecks = preload("rename_checks.gd")
 const ResourceFiles = preload("resource_files.gd")
 
@@ -137,6 +139,20 @@ func _run(operation: String, params: Dictionary) -> Dictionary:
 			payload = ResourceFiles.new(_log).get_uid(params)
 		"refresh_class_cache":
 			payload = ClassCache.new(_log).refresh_class_cache(params)
+		"read_scene_tree":
+			payload = _read(
+				FileReads.scene_tree(
+					str(params.get("scene_path", "")),
+					Read.as_int(params.get("depth", -1), -1),
+					Read.as_bool(params.get("include_properties", false))
+				)
+			)
+		"read_resource":
+			payload = _read(
+				FileReads.resource(
+					str(params.get("resource_path", "")), Read.as_bool(params.get("include_defaults", false))
+				)
+			)
 
 		# Import and export pipeline
 		"get_import_status":
@@ -220,3 +236,11 @@ func _run(operation: String, params: Dictionary) -> Dictionary:
 			_log.error("Unknown operation: " + operation)
 
 	return payload
+
+
+## A read the editor answers too, in the shape an operation answers: its refusal as the run's error.
+func _read(read: Dictionary) -> Dictionary:
+	if not read.get("ok", false):
+		return _log.failure(str(read.get("error", "the read failed")))
+	var _answered: bool = read.erase("ok")
+	return read