gdharness 0.4.1

package/build/godot/operations/dependencies.gd

@@ -0,0 +1,293 @@
+extends RefCounted
+
+const FileWalk = preload("file_walk.gd")
+const Log = preload("logger.gd")
+
+# What a dependency reference looks like in source, and how the path is read out of each form.
+const REFERENCE_PATTERNS: Array[String] = [
+	"res://[^\"'\\s\\]\\)]+",
+	'preload\\("([^"]+)"\\)',
+	'load\\("([^"]+)"\\)',
+	'ext_resource.*path="([^"]+)"',
+]
+
+var _log: Log
+var _files: FileWalk = FileWalk.new()
+
+
+# Everything one dependency walk carries: the settings it was started with, and the state it
+# accumulates as it recurses. Kept together so the recursion passes one object rather than
+# six positional arguments that have to stay in the same order at every call site.
+class DependencyWalk:
+	var max_depth: int
+	var include_built_in: bool
+	var visited: Dictionary = {}
+	var path_stack: Array[String] = []
+	var circular_references: Array
+
+	func _init(p_max_depth: int, p_include_built_in: bool, p_circular_references: Array) -> void:
+		max_depth = p_max_depth
+		include_built_in = p_include_built_in
+		circular_references = p_circular_references
+
+
+func _init(p_log: Log) -> void:
+	_log = p_log
+
+
+# Get dependencies for a resource with circular reference detection
+func get_dependencies(params: Dictionary) -> Dictionary:
+	var resource_path: String = str(params.get("resource_path", ""))
+	# No depth, or a depth of zero or less, means the whole chain; the walk stops at cycles.
+	var depth: int = int(params.get("depth", 0))
+	var max_depth: int = depth if depth > 0 else 1000
+	var include_built_in: bool = bool(params.get("include_builtin", false))
+
+	_log.info(
+		(
+			"Getting dependencies"
+			+ (" for: " + resource_path if not resource_path.is_empty() else " for all resources")
+		)
+	)
+
+	var dependencies: Dictionary = {}
+	var circular_references: Array = []
+	var total_resources: int = 0
+
+	if not resource_path.is_empty():
+		var full_path: String = resource_path
+		if not full_path.begins_with("res://"):
+			full_path = "res://" + full_path
+
+		if not FileAccess.file_exists(full_path):
+			return _log.failure("Resource file does not exist: " + full_path)
+
+		var walk: DependencyWalk = DependencyWalk.new(max_depth, include_built_in, circular_references)
+		dependencies[full_path] = _analyze_resource(full_path, 0, walk)
+		total_resources = 1
+	else:
+		var resource_extensions: Array[String] = ["tscn", "tres", "gd", "gdshader", "shader"]
+		var all_resources: Array[String] = []
+		for ext: String in resource_extensions:
+			all_resources.append_array(_files.find_files("res://", "." + ext))
+
+		# Each root gets a fresh walk so a cycle is reported from every resource it passes
+		# through, rather than only from whichever one happened to be walked first.
+		for res_path: String in all_resources:
+			var walk: DependencyWalk = DependencyWalk.new(max_depth, include_built_in, circular_references)
+			var deps: Array[Dictionary] = _analyze_resource(res_path, 0, walk)
+			if deps.size() > 0:
+				dependencies[res_path] = deps
+
+		total_resources = all_resources.size()
+
+	var dep_count: int = 0
+	for key: String in dependencies:
+		dep_count += _count_recursive(dependencies[key])
+
+	return {
+		"dependencies": dependencies,
+		"circular_references": circular_references,
+		"summary":
+		{
+			"total_resources": total_resources,
+			"total_dependencies": dep_count,
+			"circular_count": circular_references.size()
+		}
+	}
+
+
+# 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:
+	var resource_path: String = str(params.get("resource_path", ""))
+	var file_types: Array = params.get("file_types", ["tscn", "tres", "gd", "gdshader"])
+
+	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)
+
+	_log.info("Finding usages of: " + resource_path)
+
+	var class_name_declared: String = _declared_class_name(resource_path)
+	var by_path: RegEx = RegEx.new()
+	by_path.compile('"(res://)?' + _regex_escaped(resource_path.substr(6)) + '"')
+	var by_class: RegEx = null
+	if not class_name_declared.is_empty():
+		by_class = RegEx.new()
+		by_class.compile("\\b" + _regex_escaped(class_name_declared) + "\\b")
+
+	var all_files: Array[String] = []
+	for ext: Variant in file_types:
+		all_files.append_array(_files.find_files("res://", "." + str(ext)))
+
+	var usages: Array[Dictionary] = []
+	var by_kind: Dictionary = {}
+	var total: int = 0
+
+	for file_path: String in all_files:
+		if file_path == resource_path:
+			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()
+
+		var references: Array[Dictionary] = []
+		for i: int in range(lines.size()):
+			var line: String = lines[i]
+			var kind: String = ""
+			if by_path.search(line) != null:
+				kind = _path_reference_kind(line)
+			elif by_class != null and by_class.search(line) != null:
+				kind = "extends" if line.strip_edges().begins_with("extends ") else "class_name"
+			if kind.is_empty():
+				continue
+			references.append({"line": i + 1, "kind": kind, "text": line.strip_edges()})
+			by_kind[kind] = int(by_kind.get(kind, 0)) + 1
+
+		if not references.is_empty():
+			usages.append({"file": file_path, "references": references})
+			total += references.size()
+
+	var declared: Variant = null
+	if not class_name_declared.is_empty():
+		declared = class_name_declared
+	return {
+		"resource_path": resource_path,
+		"class_name": declared,
+		"usages": usages,
+		"summary":
+		{
+			"files_searched": all_files.size(),
+			"files_with_usages": usages.size(),
+			"total": total,
+			"by_kind": by_kind,
+		},
+	}
+
+
+# The class_name a script declares, or empty for a scene, a resource or a script without one.
+func _declared_class_name(path: String) -> String:
+	if not path.ends_with(".gd"):
+		return ""
+	var file: FileAccess = FileAccess.open(path, FileAccess.READ)
+	if not file:
+		return ""
+	var declaration: RegEx = RegEx.new()
+	declaration.compile("^class_name\\s+([A-Za-z_][A-Za-z0-9_]*)")
+	while not file.eof_reached():
+		var found: RegExMatch = declaration.search(file.get_line())
+		if found != null:
+			file.close()
+			return found.get_string(1)
+	file.close()
+	return ""
+
+
+# How a line that names the resource by path uses it.
+func _path_reference_kind(line: String) -> String:
+	var trimmed: String = line.strip_edges()
+	if trimmed.begins_with("extends "):
+		return "extends"
+	if trimmed.begins_with("[ext_resource"):
+		return "ext_resource"
+	if "preload(" in trimmed:
+		return "preload"
+	if "load(" in trimmed:
+		return "load"
+	return "path"
+
+
+func _regex_escaped(text: String) -> String:
+	var escaped: String = ""
+	for character: String in text:
+		if character in "\\^$.|?*+()[]{}/":
+			escaped += "\\"
+		escaped += character
+	return escaped
+
+
+func _count_recursive(deps: Array[Dictionary]) -> int:
+	var count: int = deps.size()
+	for dep: Dictionary in deps:
+		if dep.has("dependencies"):
+			count += _count_recursive(dep["dependencies"])
+	return count
+
+
+func _analyze_resource(path: String, current_depth: int, walk: DependencyWalk) -> Array[Dictionary]:
+	var deps: Array[Dictionary] = []
+
+	if current_depth >= walk.max_depth:
+		return deps
+
+	if path in walk.path_stack:
+		var cycle: Array[String] = walk.path_stack.slice(walk.path_stack.find(path))
+		cycle.append(path)
+		if not cycle in walk.circular_references:
+			walk.circular_references.append(cycle)
+		return [{"path": path, "circular": true}]
+
+	if walk.visited.has(path):
+		var cached: Array[Dictionary] = walk.visited[path]
+		return cached
+
+	walk.path_stack.append(path)
+
+	var file: FileAccess = FileAccess.open(path, FileAccess.READ)
+	if file:
+		var content: String = file.get_as_text()
+		file.close()
+
+		for pattern: String in REFERENCE_PATTERNS:
+			var regex: RegEx = RegEx.new()
+			regex.compile(pattern)
+			for m: RegExMatch in regex.search_all(content):
+				var dep_path: String = _referenced_path(m.get_string())
+
+				if not dep_path.begins_with("res://"):
+					continue
+
+				# Skip engine-internal resources unless requested. `addons/` is not one of
+				# them: it is ordinary project content, and often shipping content, so
+				# treating it as built-in dropped every dependency of anything living there.
+				if not walk.include_built_in and dep_path.begins_with("res://."):
+					continue
+
+				if dep_path == path:
+					continue
+
+				var dep_info: Dictionary = {"path": dep_path, "exists": FileAccess.file_exists(dep_path)}
+
+				if dep_info["exists"] and current_depth + 1 < walk.max_depth:
+					var sub_deps: Array[Dictionary] = _analyze_resource(dep_path, current_depth + 1, walk)
+					if sub_deps.size() > 0:
+						dep_info["dependencies"] = sub_deps
+
+				var already_added: bool = false
+				for existing: Dictionary in deps:
+					if existing.get("path", "") == dep_path:
+						already_added = true
+						break
+				if not already_added:
+					deps.append(dep_info)
+
+	walk.path_stack.pop_back()
+	walk.visited[path] = deps
+	return deps
+
+
+# The path inside a preload(), load() or ext_resource match; a bare res:// match is the path.
+func _referenced_path(matched: String) -> String:
+	var inner: RegEx = RegEx.new()
+	if "preload" in matched or "load" in matched:
+		inner.compile('"([^"]+)"')
+	elif "ext_resource" in matched:
+		inner.compile('path="([^"]+)"')
+	else:
+		return matched
+	var inner_match: RegExMatch = inner.search(matched)
+	return inner_match.get_string(1) if inner_match else matched

package/build/godot/operations/file_walk.gd

@@ -0,0 +1,55 @@
+extends RefCounted
+
+# 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
+# for the resource they belong to.
+
+
+# Files under `path` whose name ends with `extension`, which is passed with its dot.
+func find_files(path: String, extension: String) -> Array[String]:
+	var files: Array[String] = []
+	var dir: DirAccess = DirAccess.open(path)
+
+	if dir:
+		dir.list_dir_begin()
+		var file_name: String = dir.get_next()
+
+		while file_name != "":
+			if dir.current_is_dir() and not file_name.begins_with("."):
+				files.append_array(find_files(path + file_name + "/", extension))
+			elif file_name.ends_with(extension):
+				files.append(path + file_name)
+
+			file_name = dir.get_next()
+
+	return files
+
+
+# Files under `path` whose extension is in `extensions`, which are passed without their dot.
+func find_files_with_extensions(path: String, extensions: Array) -> Array[String]:
+	var files: Array[String] = []
+	var dir: DirAccess = DirAccess.open(path)
+
+	if dir:
+		dir.list_dir_begin()
+		var file_name: String = dir.get_next()
+
+		while file_name != "":
+			if file_name.begins_with("."):
+				file_name = dir.get_next()
+				continue
+
+			var full_path: String = path + file_name
+			if dir.current_is_dir():
+				files.append_array(find_files_with_extensions(full_path + "/", extensions))
+			else:
+				var ext: String = file_name.get_extension().to_lower()
+				if ext in extensions:
+					files.append(full_path)
+
+			file_name = dir.get_next()
+
+		dir.list_dir_end()
+
+	return files

package/build/godot/operations/gdscript_analysis.gd

@@ -0,0 +1,288 @@
+extends RefCounted
+
+const Log = preload("logger.gd")
+
+var _log: Log
+
+
+func _init(p_log: Log) -> void:
+	_log = p_log
+
+
+# Analyze a GDScript file and return its structure
+func get_gdscript_info(params: Dictionary) -> Dictionary:
+	var script_path: String = str(params.get("script_path", ""))
+
+	_log.info("Analyzing GDScript: " + script_path)
+
+	var full_script_path: String = script_path
+	if not full_script_path.begins_with("res://"):
+		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)
+
+	var file: FileAccess = FileAccess.open(full_script_path, FileAccess.READ)
+	if not file:
+		return _log.failure("Failed to open script file: " + full_script_path)
+
+	var content: String = file.get_as_text()
+	file.close()
+
+	var lines: PackedStringArray = content.split("\n")
+
+	var declared_class_name: Variant = null
+	var extends_name: String = "RefCounted"
+	var signals: Array[Dictionary] = []
+	var variables: Array[Dictionary] = []
+	var functions: Array[Dictionary] = []
+	var constants: Array[Dictionary] = []
+	var enums: Array[Dictionary] = []
+	var inner_classes: Array[String] = []
+	var dependencies: Array[String] = []
+
+	var in_multiline_string: bool = false
+
+	for i: int in range(lines.size()):
+		var stripped: String = lines[i].strip_edges()
+
+		if stripped.is_empty() or stripped.begins_with("#"):
+			continue
+
+		if '"""' in stripped or "'''" in stripped:
+			in_multiline_string = not in_multiline_string
+			continue
+
+		if in_multiline_string:
+			continue
+
+		if stripped.begins_with("class_name "):
+			declared_class_name = stripped.substr(11).strip_edges()
+		elif stripped.begins_with("extends "):
+			extends_name = stripped.substr(8).strip_edges()
+		elif stripped.begins_with("signal "):
+			signals.append(_parse_signal(stripped, i + 1))
+		elif stripped.begins_with("const "):
+			constants.append(_parse_constant(stripped, i + 1))
+		elif stripped.begins_with("enum "):
+			enums.append(_parse_enum(stripped, i + 1))
+		elif (
+			stripped.begins_with("var ")
+			or stripped.begins_with("@export")
+			or stripped.begins_with("@onready")
+		):
+			variables.append(_parse_variable(stripped, i + 1))
+		elif stripped.begins_with("func ") or stripped.begins_with("static func "):
+			functions.append(_parse_function(stripped, i + 1))
+		elif stripped.begins_with("class "):
+			inner_classes.append(stripped.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)
+
+	return {
+		"path": script_path,
+		"full_path": full_script_path,
+		"class_name": declared_class_name,
+		"extends": extends_name,
+		"signals": signals,
+		"variables": variables,
+		"functions": functions,
+		"constants": constants,
+		"enums": enums,
+		"inner_classes": inner_classes,
+		"dependencies": dependencies,
+		"line_count": lines.size()
+	}
+
+
+func _parse_signal(line: String, line_num: int) -> Dictionary:
+	var signal_text: String = line.substr(7).strip_edges()
+	var signal_name: String = ""
+	var params: Array[Dictionary] = []
+
+	if "(" in signal_text:
+		var parts: PackedStringArray = signal_text.split("(")
+		signal_name = parts[0].strip_edges()
+		if parts.size() > 1:
+			var params_text: String = parts[1].replace(")", "").strip_edges()
+			if not params_text.is_empty():
+				for p: String in params_text.split(","):
+					params.append(_parse_param(p.strip_edges()))
+	else:
+		signal_name = signal_text
+
+	return {"name": signal_name, "params": params, "line": line_num}
+
+
+func _parse_constant(line: String, line_num: int) -> Dictionary:
+	var const_text: String = line.substr(6).strip_edges()
+	var name: String = ""
+	var value: String = ""
+	var type_hint: String = ""
+
+	if "=" in const_text:
+		var parts: PackedStringArray = const_text.split("=", true, 1)
+		var name_part: String = parts[0].strip_edges()
+		value = parts[1].strip_edges() if parts.size() > 1 else ""
+
+		if ":" in name_part:
+			var type_parts: PackedStringArray = name_part.split(":")
+			name = type_parts[0].strip_edges()
+			type_hint = type_parts[1].strip_edges()
+		else:
+			name = name_part
+	else:
+		name = const_text
+
+	return {"name": name, "value": value, "type": type_hint, "line": line_num}
+
+
+func _parse_enum(line: String, line_num: int) -> Dictionary:
+	var enum_text: String = line.substr(5).strip_edges()
+	var enum_name: String = ""
+	var values: Array[String] = []
+
+	if "{" in enum_text:
+		var parts: PackedStringArray = enum_text.split("{")
+		enum_name = parts[0].strip_edges()
+		if parts.size() > 1:
+			var values_text: String = parts[1].replace("}", "").strip_edges()
+			if not values_text.is_empty():
+				for v: String in values_text.split(","):
+					var val: String = v.strip_edges()
+					if not val.is_empty():
+						values.append(val)
+	else:
+		enum_name = enum_text
+
+	return {"name": enum_name, "values": values, "line": line_num}
+
+
+func _parse_variable(line: String, line_num: int) -> Dictionary:
+	var is_export: bool = line.begins_with("@export")
+	var is_onready: bool = "@onready" in line
+	var export_hint: String = ""
+
+	if is_export:
+		var export_match: int = line.find("@export")
+		var hint_end: int = line.find("var ")
+		if hint_end > export_match:
+			var hint_part: String = line.substr(export_match + 7, hint_end - export_match - 7).strip_edges()
+			if hint_part.begins_with("_"):
+				export_hint = hint_part.substr(1).split(" ")[0]
+
+	var var_pos: int = line.find("var ")
+	if var_pos == -1:
+		return {"name": "", "line": line_num}
+
+	var var_text: String = line.substr(var_pos + 4).strip_edges()
+	var name: String = ""
+	var type_hint: String = ""
+	var default_value: String = ""
+
+	if "=" in var_text:
+		var parts: PackedStringArray = var_text.split("=", true, 1)
+		var name_part: String = parts[0].strip_edges()
+		default_value = parts[1].strip_edges() if parts.size() > 1 else ""
+
+		if ":" in name_part:
+			var type_parts: PackedStringArray = name_part.split(":")
+			name = type_parts[0].strip_edges()
+			type_hint = type_parts[1].strip_edges()
+		else:
+			name = name_part
+	elif ":" in var_text:
+		var type_parts: PackedStringArray = var_text.split(":")
+		name = type_parts[0].strip_edges()
+		type_hint = type_parts[1].strip_edges()
+	else:
+		name = var_text.split(" ")[0].strip_edges()
+
+	return {
+		"name": name,
+		"type": type_hint,
+		"default_value": default_value,
+		"is_export": is_export,
+		"export_hint": export_hint,
+		"is_onready": is_onready,
+		"line": line_num
+	}
+
+
+func _parse_function(line: String, line_num: int) -> Dictionary:
+	var is_static: bool = line.begins_with("static ")
+	var func_text: String = line
+
+	if is_static:
+		func_text = line.substr(7).strip_edges()
+
+	func_text = func_text.substr(5).strip_edges()
+
+	var name: String = ""
+	var params: Array[Dictionary] = []
+	var return_type: String = ""
+
+	if "(" in func_text:
+		var paren_start: int = func_text.find("(")
+		name = func_text.substr(0, paren_start).strip_edges()
+
+		var paren_end: int = func_text.rfind(")")
+		if paren_end > paren_start:
+			var params_text: String = func_text.substr(paren_start + 1, paren_end - paren_start - 1)
+			if not params_text.is_empty():
+				for p: String in params_text.split(","):
+					params.append(_parse_param(p.strip_edges()))
+
+		var after_paren: String = func_text.substr(paren_end + 1).strip_edges()
+		if after_paren.begins_with("->"):
+			return_type = after_paren.substr(2).replace(":", "").strip_edges()
+
+	return {
+		"name": name,
+		"params": params,
+		"return_type": return_type,
+		"is_virtual": name.begins_with("_"),
+		"is_static": is_static,
+		"line": line_num
+	}
+
+
+func _parse_param(param_text: String) -> Dictionary:
+	var name: String = ""
+	var type_hint: String = ""
+	var default_value: String = ""
+
+	if "=" in param_text:
+		var parts: PackedStringArray = param_text.split("=", true, 1)
+		var name_part: String = parts[0].strip_edges()
+		default_value = parts[1].strip_edges() if parts.size() > 1 else ""
+
+		if ":" in name_part:
+			var type_parts: PackedStringArray = name_part.split(":")
+			name = type_parts[0].strip_edges()
+			type_hint = type_parts[1].strip_edges()
+		else:
+			name = name_part
+	elif ":" in param_text:
+		var type_parts: PackedStringArray = param_text.split(":")
+		name = type_parts[0].strip_edges()
+		type_hint = type_parts[1].strip_edges()
+	else:
+		name = param_text
+
+	return {"name": name, "type": type_hint, "default": default_value}
+
+
+func _extract_dependencies(line: String) -> Array[String]:
+	var deps: Array[String] = []
+	var regex: RegEx = RegEx.new()
+
+	regex.compile("(?:preload|load)\\s*\\(\\s*[\"']([^\"']+)[\"']\\s*\\)")
+
+	for m: RegExMatch in regex.search_all(line):
+		deps.append(m.get_string(1))
+
+	return deps