gdharness 1.1.21 → 1.1.23

package/build/godot/operations/class_cache.gd

@@ -21,7 +21,8 @@ func _init(p_log: Log) -> void:
 
 
 func refresh_class_cache(_params: Dictionary) -> Dictionary:
-	var before: Dictionary = _entries_by_class(_read_cache())
+	var cached: Array = _read_cache()
+	var before: Dictionary = _entries_by_class(cached)
 
 	var entries: Array = []
 	var skipped: Array[Dictionary] = []
@@ -29,6 +30,18 @@ func refresh_class_cache(_params: Dictionary) -> Dictionary:
 		var entry: Dictionary = _entry_for(path, skipped)
 		if not entry.is_empty():
 			entries.append(entry)
+	# Another language's classes are kept while their files are there. Only GDScript is read here and
+	# the list is written whole, so a C# project's global classes were dropped from it and answered as
+	# removed, and nothing started next could resolve them.
+	var carried: Array[String] = []
+	for entry: Variant in cached:
+		if not entry is Dictionary:
+			continue
+		var listed: Dictionary = entry
+		var language: String = str(listed.get("language", "GDScript"))
+		if language != "GDScript" and FileAccess.file_exists(str(listed.get("path", ""))):
+			entries.append(listed)
+			carried.append(str(listed.get("class", "")))
 	# By name as text: StringName's own order is by identity, not by spelling.
 	entries.sort_custom(func(a: Dictionary, b: Dictionary) -> bool: return str(a["class"]) < str(b["class"]))
 
@@ -56,7 +69,7 @@ func refresh_class_cache(_params: Dictionary) -> Dictionary:
 		if not after.has(name):
 			removed.append(name)
 
-	return {
+	var answer: Dictionary = {
 		"path": CACHE_PATH,
 		"classes": entries.size(),
 		"added": added,
@@ -64,6 +77,9 @@ func refresh_class_cache(_params: Dictionary) -> Dictionary:
 		"changed": changed,
 		"skipped": skipped,
 	}
+	if not carried.is_empty():
+		answer["carried"] = carried
+	return answer
 
 
 # The cache entry for one script, or empty for a script with no class_name.

package/build/godot/operations/classdb_queries.gd

@@ -3,18 +3,22 @@ extends RefCounted
 const Read = preload("reading.gd")
 const Log = preload("logger.gd")
 
-# The base class each category name stands for.
+# The base classes each category name stands for. Kept to the list the tool's schema offers, which
+# a case holds: the schema offered physics3d and ui, which this refused, and physics answered the 3D
+# bodies alone beside physics2d and physics3d.
 const CATEGORY_BASES: Dictionary = {
-	"node": "Node",
-	"node2d": "Node2D",
-	"node3d": "Node3D",
-	"control": "Control",
-	"resource": "Resource",
-	"physics": "PhysicsBody3D",
-	"physics2d": "PhysicsBody2D",
-	"audio": "AudioStream",
-	"visual": "VisualInstance3D",
-	"animation": "AnimationMixer",
+	"node": ["Node"],
+	"node2d": ["Node2D"],
+	"node3d": ["Node3D"],
+	"control": ["Control"],
+	"ui": ["Control"],
+	"resource": ["Resource"],
+	"physics": ["PhysicsBody2D", "PhysicsBody3D"],
+	"physics2d": ["PhysicsBody2D"],
+	"physics3d": ["PhysicsBody3D"],
+	"audio": ["AudioStream"],
+	"visual": ["VisualInstance3D"],
+	"animation": ["AnimationMixer"],
 }
 
 var _log: Log
@@ -24,6 +28,14 @@ func _init(p_log: Log) -> void:
 	_log = p_log
 
 
+static func _under_any(name: String, bases: Array) -> bool:
+	for base: Variant in bases:
+		var base_name: String = str(base)
+		if name == base_name or ClassDB.is_parent_class(name, base_name):
+			return true
+	return false
+
+
 # Query available classes from ClassDB with optional filtering
 func query_classes(params: Dictionary) -> Dictionary:
 	var filter: String = str(params.get("filter", ""))
@@ -42,10 +54,10 @@ func query_classes(params: Dictionary) -> Dictionary:
 		)
 	)
 
-	var base_class: String = ""
+	var bases: Array = []
 	if not category.is_empty():
-		base_class = CATEGORY_BASES.get(category.to_lower(), "")
-		if base_class.is_empty():
+		bases = CATEGORY_BASES.get(category.to_lower(), [])
+		if bases.is_empty():
 			return _log.failure("Unknown category: " + category + ". Valid: " + str(CATEGORY_BASES.keys()))
 
 	var all_classes: PackedStringArray = ClassDB.get_class_list()
@@ -60,9 +72,8 @@ func query_classes(params: Dictionary) -> Dictionary:
 		if not filter.is_empty() and not class_name_str.to_lower().contains(filter.to_lower()):
 			continue
 
-		if not base_class.is_empty():
-			if not ClassDB.is_parent_class(class_name_str, base_class) and class_name_str != base_class:
-				continue
+		if not bases.is_empty() and not _under_any(class_name_str, bases):
+			continue
 
 		filtered_classes.append(class_name_str)
 

package/build/godot/operations/dependencies.gd

@@ -4,6 +4,14 @@ const Patterns = preload("patterns.gd")
 const Read = preload("reading.gd")
 const FileWalk = preload("file_walk.gd")
 const Log = preload("logger.gd")
+const ResourceFiles = preload("resource_files.gd")
+
+## What a reverse search reads unless told otherwise: the resource and code files, and the settings
+## files that name resources, "godot" for project.godot, "cfg" for plugin.cfg and export_presets.cfg,
+## and "import" for the sidecars that name import scripts and external materials.
+const DEFAULT_USAGE_KINDS: Array[String] = ["tscn", "tres", "gd", "gdshader", "godot", "cfg", "import"]
+## One string literal of either quote, its contents captured by the one it opened with.
+const STRING_LITERAL: String = "\"((?:[^\"\\\\]|\\\\.)*)\"|'((?:[^'\\\\]|\\\\.)*)'"
 
 # What a dependency reference looks like in source, and how the path is read out of each form.
 const REFERENCE_PATTERNS: Array[String] = [
@@ -106,7 +114,7 @@ func get_dependencies(params: Dictionary) -> Dictionary:
 # preload it, and for a script with a class_name, every use of that name.
 func find_resource_usages(params: Dictionary) -> Dictionary:
 	var resource_path: String = str(params.get("resource_path", ""))
-	var file_types: Array = params.get("file_types", ["tscn", "tres", "gd", "gdshader"])
+	var file_types: Array = params.get("file_types", DEFAULT_USAGE_KINDS)
 
 	if not resource_path.begins_with("res://"):
 		resource_path = "res://" + resource_path
@@ -116,14 +124,14 @@ func find_resource_usages(params: Dictionary) -> Dictionary:
 	_log.info("Finding usages of: " + resource_path)
 
 	var class_name_declared: String = _declared_class_name(resource_path)
-	var by_path: RegEx = Patterns.compiled('"(res://)?' + _regex_escaped(resource_path.substr(6)) + '"')
 	var by_class: RegEx = null
 	if not class_name_declared.is_empty():
 		by_class = Patterns.compiled("\\b" + _regex_escaped(class_name_declared) + "\\b")
+	var target: Dictionary = {
+		"path": resource_path, "uid": str(ResourceFiles.uid_of(resource_path).get("uid", ""))
+	}
 
-	var all_files: Array[String] = []
-	for ext: Variant in file_types:
-		all_files.append_array(_files.find_files("res://", "." + str(ext)))
+	var all_files: Array[String] = _usage_files(file_types)
 
 	var usages: Array[Dictionary] = []
 	var by_kind: Dictionary = {}
@@ -131,20 +139,29 @@ func find_resource_usages(params: Dictionary) -> Dictionary:
 	var in_code: int = 0
 
 	for file_path: String in all_files:
-		if file_path == resource_path:
+		# Its own sidecar names it as the file it was imported from, which is not a use of it.
+		if file_path == resource_path or file_path == resource_path + ".import":
 			continue
 		var file: FileAccess = FileAccess.open(file_path, FileAccess.READ)
 		if not file:
 			continue
 		var lines: PackedStringArray = file.get_as_text().split("\n")
 		file.close()
+		# A class is used by name only in code. In a scene or a resource the same word is a node's
+		# name or a caption, and each was counted as a use of the class.
+		var code: bool = file_path.get_extension() in ["gd", "gdshader"]
 
 		var references: Array[Dictionary] = []
 		for i: int in range(lines.size()):
 			var line: String = lines[i]
-			var by_its_path: bool = by_path.search(line) != null
-			var by_its_name: bool = not by_its_path and by_class != null and by_class.search(line) != null
-			if not by_its_path and not by_its_name:
+			var by_its_path: bool = _names_target(line, file_path, target)
+			var by_its_name: bool = false
+			var name_in_comment: bool = false
+			if not by_its_path and code and by_class != null:
+				# Strings are text, so a class named in one is not a use of it.
+				by_its_name = by_class.search(_code_of(line)) != null
+				name_in_comment = not by_its_name and by_class.search(_comment_of(line)) != null
+			if not by_its_path and not by_its_name and not name_in_comment:
 				continue
 			var trimmed: String = line.strip_edges()
 			var kind: String = ""
@@ -154,12 +171,12 @@ func find_resource_usages(params: Dictionary) -> Dictionary:
 			# three of them prose, all counted as code. The more carefully a project is documented
 			# the worse that ratio gets. `##` and `#` are kept apart because renaming the class
 			# breaks Godot's generated documentation and leaves the prose merely stale.
-			if trimmed.begins_with("##"):
+			if code and trimmed.begins_with("##"):
 				kind = "doc"
-			elif trimmed.begins_with("#"):
+			elif (code and trimmed.begins_with("#")) or name_in_comment:
 				kind = "comment"
 			elif by_its_path:
-				kind = _path_reference_kind(line)
+				kind = _path_reference_kind(line, file_path)
 			else:
 				kind = (
 					"extends" if Patterns.without_annotations(line).begins_with("extends ") else "class_name"
@@ -210,8 +227,81 @@ func _declared_class_name(path: String) -> String:
 	return ""
 
 
+# The files a reverse search reads, for the kinds asked for. The settings files are kinds of their
+# own because what they name is used as surely as a preload is: an autoload script, the main scene
+# and a plugin's script are named only in project.godot and plugin.cfg, and a search that left those
+# out answered that each was used by nothing, which is the answer a caller deletes a file on.
+func _usage_files(kinds: Array) -> Array[String]:
+	var found: Array[String] = []
+	for kind: Variant in kinds:
+		match str(kind):
+			"godot":
+				found.append("res://project.godot")
+			"cfg":
+				found.append_array(_files.find_files("res://", "plugin.cfg"))
+				if FileAccess.file_exists("res://export_presets.cfg"):
+					found.append("res://export_presets.cfg")
+			_:
+				found.append_array(_files.find_files("res://", "." + str(kind)))
+	return found
+
+
+# Whether [param line], in [param file_path], names the target by path or by UID. Every string on the
+# line is read as a path the way the engine reads it: a res:// path as it is, a uid:// by what it
+# names, and anything else relative to the file it is in, which is how `preload("sibling.gd")` and a
+# plugin.cfg's `script="plugin.gd"` name their files. Only the quoted form of the project path was
+# looked for, so neither of those was found, and nor was a scene named by its UID.
+func _names_target(line: String, file_path: String, target: Dictionary) -> bool:
+	var path: String = target["path"]
+	var uid: String = target["uid"]
+	for quoted: String in _string_literals(line):
+		# An autoload is written "*res://path" when its name is global.
+		var literal: String = quoted.trim_prefix("*")
+		if not uid.is_empty() and literal == uid:
+			return true
+		if literal.get_extension() != path.get_extension():
+			continue
+		var resolved: String = literal
+		if not literal.begins_with("res://"):
+			resolved = file_path.get_base_dir().path_join(literal).simplify_path()
+		if resolved == path:
+			return true
+	return false
+
+
+# The contents of each string literal on [param line], of either quote.
+static func _string_literals(line: String) -> Array[String]:
+	var literals: Array[String] = []
+	for m: RegExMatch in Patterns.compiled(STRING_LITERAL).search_all(line):
+		literals.append(m.get_string(1) if not m.get_string(1).is_empty() else m.get_string(2))
+	return literals
+
+
+# [param line] with its strings emptied and its comment taken off: the part a class can be used in.
+static func _code_of(line: String) -> String:
+	var bare: String = Patterns.compiled(STRING_LITERAL).sub(line, '""', true)
+	var mark: int = bare.find("#")
+	return bare if mark == -1 else bare.substr(0, mark)
+
+
+# The comment on [param line], strings emptied first so a # inside one does not start it.
+static func _comment_of(line: String) -> String:
+	var bare: String = Patterns.compiled(STRING_LITERAL).sub(line, '""', true)
+	var mark: int = bare.find("#")
+	return "" if mark == -1 else bare.substr(mark)
+
+
 # How a line that names the resource by path uses it.
-func _path_reference_kind(line: String) -> String:
+func _path_reference_kind(line: String, file_path: String) -> String:
+	match file_path.get_file():
+		"project.godot":
+			return "setting"
+		"plugin.cfg":
+			return "plugin"
+		"export_presets.cfg":
+			return "export_preset"
+	if file_path.ends_with(".import"):
+		return "import"
 	var trimmed: String = Patterns.without_annotations(line)
 	if trimmed.begins_with("extends "):
 		return "extends"
@@ -255,9 +345,15 @@ func _analyze_resource(path: String, current_depth: int, walk: DependencyWalk) -
 			walk.circular_references.append(cycle)
 		return [{"path": path, "circular": true}]
 
+	# Reused only when it was walked with as much depth left as now. A resource first reached deep in
+	# the walk has a list cut short at the limit, and handing that to a nearer reach answered with a
+	# chain that stopped where nothing stopped it.
+	var remaining: int = walk.max_depth - current_depth
 	if walk.visited.has(path):
-		var cached: Array[Dictionary] = walk.visited[path]
-		return cached
+		var cached: Dictionary = walk.visited[path]
+		if Read.as_int(cached["remaining"]) == remaining:
+			var cached_deps: Array[Dictionary] = cached["deps"]
+			return cached_deps
 
 	walk.path_stack.append(path)
 
@@ -269,7 +365,7 @@ func _analyze_resource(path: String, current_depth: int, walk: DependencyWalk) -
 		for pattern: String in REFERENCE_PATTERNS:
 			var regex: RegEx = Patterns.compiled(pattern)
 			for m: RegExMatch in regex.search_all(content):
-				var dep_path: String = _referenced_path(m.get_string())
+				var dep_path: String = _resolved(_referenced_path(m.get_string()), path)
 
 				if not dep_path.begins_with("res://"):
 					continue
@@ -299,10 +395,25 @@ func _analyze_resource(path: String, current_depth: int, walk: DependencyWalk) -
 					deps.append(dep_info)
 
 	walk.path_stack.pop_back()
-	walk.visited[path] = deps
+	walk.visited[path] = {"deps": deps, "remaining": remaining}
 	return deps
 
 
+# [param written] as the res:// path the engine would load from [param from]: a uid:// by what the
+# project's uid cache says it names, and a relative path against the referring file's directory.
+# Both were passed over as not being res:// paths, so a script's `preload("sibling.gd")` was no
+# dependency at all.
+static func _resolved(written: String, from: String) -> String:
+	if written.begins_with("res://"):
+		return written
+	if written.begins_with("uid://"):
+		var id: int = ResourceUID.text_to_id(written)
+		return ResourceUID.get_id_path(id) if ResourceUID.has_id(id) else written
+	if written.contains("://"):
+		return written
+	return from.get_base_dir().path_join(written).simplify_path()
+
+
 # The path inside a preload(), load() or ext_resource match; a bare res:// match is the path.
 func _referenced_path(matched: String) -> String:
 	var expression: String = ""

package/build/godot/operations/file_walk.gd

@@ -10,6 +10,26 @@ extends RefCounted
 # every caller files the engine will never answer for.
 
 
+# Why [param path], a res:// or uid:// path a setting names, is not a file the engine can load, or
+# empty when it is. A uid:// path resolves through the project's uid cache, which the import writes,
+# so one that does not resolve is a file that has gone or a project not imported yet, and saying
+# only that the file does not exist sent a caller looking for a scene that was there.
+static func missing_reason(path: String) -> String:
+	if path.begins_with("uid://"):
+		var id: int = ResourceUID.text_to_id(path)
+		if id == ResourceUID.INVALID_ID or not ResourceUID.has_id(id):
+			return (
+				path
+				+ " does not resolve: no file in the project's uid cache has it, so the file has gone or the"
+				+ " project has not been imported yet (project_import refresh_uids imports it)"
+			)
+		var resolved: String = ResourceUID.get_id_path(id)
+		return (
+			"" if FileAccess.file_exists(resolved) else path + " names " + resolved + ", which does not exist"
+		)
+	return "" if FileAccess.file_exists(path) else path + " does not exist"
+
+
 # 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

@@ -52,16 +52,30 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 		# answer: a `var x: int = 5  # note` carried `5  # note` as its default, and correcting the
 		# end of a parameter list put the comment into the return type, where `rfind(")")` had been
 		# hiding it by stopping inside the comment instead.
-		var stripped: String = _without_comment(lines[i])
-
-		if stripped.is_empty():
+		var raw: String = lines[i]
+		# Inside a string the raw line is counted, because a `#` in it is text and taking it for a
+		# comment would cut off the quotes that close the string.
+		if in_multiline_string:
+			if _triple_quotes(raw) % 2 == 1:
+				in_multiline_string = false
 			continue
+		var stripped: String = _without_comment(raw)
 
-		if '"""' in stripped or "'''" in stripped:
-			in_multiline_string = not in_multiline_string
+		if stripped.is_empty():
 			continue
 
-		if in_multiline_string:
+		# An odd count opens a string that runs on; an even one is a string that closed on the line
+		# it opened on. Toggling on any count lost `const HELP := """Usage"""`, and everything after
+		# it up to the next triple quote, with the state inverted from there to the end of the file.
+		# The line that opens one is still read: it can be the declaration the string belongs to.
+		if _triple_quotes(stripped) % 2 == 1:
+			in_multiline_string = true
+
+		# Only a line at the left margin declares one of the script's own members. Indented, it is a
+		# function's local or an inner class's member, and each was answered as the script's own:
+		# every `var` in every body, and an inner class's `extends` taken for the script's base.
+		if raw.begins_with(" ") or raw.begins_with("\t"):
+			_collect_dependencies(stripped, dependencies)
 			continue
 
 		# Annotations may share the line with anything they annotate, so every branch below decides
@@ -116,14 +130,11 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 		elif header.begins_with("class "):
 			inner_classes.append(header.substr(6).split(":")[0].split(" ")[0].strip_edges())
 
-		if "preload(" in stripped or "load(" in stripped:
-			for dep: String in _extract_dependencies(stripped):
-				if dep not in dependencies:
-					dependencies.append(dep)
+		_collect_dependencies(stripped, dependencies)
 
 	# After the loop, because it needs the base the loop reads, and a file that declared one after
 	# its first function would otherwise be judged against the default.
-	_mark_virtuals(functions, extends_name)
+	_mark_virtuals(functions, extends_name, full_script_path)
 
 	var answer: Dictionary = {
 		"path": script_path,
@@ -151,8 +162,8 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 # with a private helper in it. The virtuals are the ones the native ancestor declares with
 # `METHOD_FLAG_VIRTUAL`, which is a question `ClassDB` answers exactly, and `class_has_method` does
 # not: it says false for `_ready` on `Node`, so the method list is what has to be walked.
-func _mark_virtuals(functions: Array[Dictionary], extends_name: String) -> void:
-	var native: String = _native_ancestor(extends_name)
+func _mark_virtuals(functions: Array[Dictionary], extends_name: String, from_path: String) -> void:
+	var native: String = _native_ancestor(extends_name, from_path)
 	var virtuals: Dictionary = {}
 	if not native.is_empty():
 		for m: Dictionary in ClassDB.class_get_method_list(native, false):
@@ -168,11 +179,12 @@ func _mark_virtuals(functions: Array[Dictionary], extends_name: String) -> void:
 # A base named by a script is followed; a base that is neither a script nor a class the engine knows
 # leaves nothing to ask, and then no function is called virtual rather than every underscore being
 # guessed at.
-func _native_ancestor(base: String) -> String:
+func _native_ancestor(base: String, from_path: String) -> String:
 	var seen: Array[String] = []
 	var current: String = base
+	var declared_in: String = from_path
 	while true:
-		var path: String = _script_named(current)
+		var path: String = _script_named(current, declared_in)
 		if path.is_empty():
 			break
 		if path in seen:
@@ -182,6 +194,7 @@ func _native_ancestor(base: String) -> String:
 		if above.is_empty():
 			return ""
 		current = str(above.get("extends", ""))
+		declared_in = path
 	return current if ClassDB.class_exists(current) else ""
 
 
@@ -196,8 +209,9 @@ func _native_ancestor(base: String) -> String:
 func _add_inherited(answer: Dictionary, seen: Array[String]) -> void:
 	var inherits_from: Array[String] = []
 	var base: String = str(answer.get("extends", ""))
+	var declared_in: String = str(answer.get("full_path", ""))
 	while true:
-		var base_path: String = _script_named(base)
+		var base_path: String = _script_named(base, declared_in)
 		if base_path.is_empty() or base_path in seen:
 			break
 		seen.append(base_path)
@@ -216,16 +230,28 @@ func _add_inherited(answer: Dictionary, seen: Array[String]) -> void:
 				carried["inherited_from"] = base_path
 				mine.append(carried)
 		base = str(above.get("extends", ""))
+		declared_in = base_path
 	answer["inherits_from"] = inherits_from
 
 
 # The file a base names, whether it named a path or a class, or empty for a native class.
-func _script_named(base: String) -> String:
+#
+# A quoted path is resolved the way the engine resolves it: `extends "base.gd"` is relative to the
+# script [param declared_in], and asking whether `base.gd` exists asked about nothing, so such a
+# script had no ancestor and none of its engine callbacks were virtual.
+func _script_named(base: String, declared_in: String) -> String:
 	if base.is_empty():
 		return ""
-	if base.begins_with('"') and base.ends_with('"'):
-		var quoted: String = base.substr(1, base.length() - 2)
-		return quoted if FileAccess.file_exists(quoted) else ""
+	var quoted: String = ""
+	if base.length() >= 2 and (base[0] == '"' or base[0] == "'") and base.ends_with(base[0]):
+		quoted = base.substr(1, base.length() - 2)
+	if not quoted.is_empty():
+		if quoted.begins_with("uid://"):
+			var id: int = ResourceUID.text_to_id(quoted)
+			quoted = ResourceUID.get_id_path(id) if ResourceUID.has_id(id) else ""
+		elif not quoted.begins_with("res://"):
+			quoted = declared_in.get_base_dir().path_join(quoted).simplify_path()
+		return quoted if not quoted.is_empty() and FileAccess.file_exists(quoted) else ""
 	for entry: Dictionary in ProjectSettings.get_global_class_list():
 		if str(entry.get("class", "")) == base:
 			var path: String = str(entry.get("path", ""))
@@ -562,6 +588,19 @@ func _parse_param(param_text: String) -> Dictionary:
 	return {"name": name, "type": type_hint, "default": default_value, "is_rest": is_rest}
 
 
+func _collect_dependencies(line: String, into: Array[String]) -> void:
+	if "load(" not in line:
+		return
+	for dep: String in _extract_dependencies(line):
+		if dep not in into:
+			into.append(dep)
+
+
+# How many triple quotes of either kind [param line] holds.
+static func _triple_quotes(line: String) -> int:
+	return line.count('"""') + line.count("'''")
+
+
 func _extract_dependencies(line: String) -> Array[String]:
 	var deps: Array[String] = []
 	var regex: RegEx = Patterns.compiled("(?:preload|load)\\s*\\(\\s*[\"']([^\"']+)[\"']\\s*\\)")