gdharness 1.3.2 → 1.3.4

package/build/godot/operations/gdscript_analysis.gd

@@ -9,6 +9,39 @@ const GdhLog = preload("logger.gd")
 var _log: GdhLog
 ## Kept for the call, so the project's class names are read once however many bases are walked.
 var _dependencies: GdhDependencies = null
+## The script being read, which an inner class's base is resolved against.
+var _reading: String = ""
+
+
+## What one class body declares, the script's own or an inner class's.
+class GdhMembers:
+	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[Dictionary] = []
+	## The index of the last line the body holds.
+	var last: int = -1
+	## An inner class's name and the line its `class` is on.
+	var inner_name: String = ""
+	var line: int = 0
+
+	## The inner class as its entry under inner_classes, in the fields a script's own are in.
+	func as_inner() -> Dictionary:
+		return {
+			"name": inner_name,
+			"line": line,
+			"extends": extends_name,
+			"signals": signals,
+			"variables": variables,
+			"functions": functions,
+			"constants": constants,
+			"enums": enums,
+			"inner_classes": inner_classes,
+		}
 
 
 func _init(p_log: GdhLog) -> void:
@@ -41,19 +74,77 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 
 	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] = []
+	_reading = full_script_path
+	var own: GdhMembers = _members(lines, 0, "", dependencies)
+	var extends_name: String = own.extends_name
+	var functions: Array[Dictionary] = own.functions
 
+	# After the walk, because it needs the base the walk reads, and a file that declared one after
+	# its first function would otherwise be judged against the default.
+	_mark_virtuals(functions, extends_name, full_script_path)
+
+	# A script typed by its class_name is depended on as surely as one preloaded, and the answer
+	# listed only the preloads: a `var stats: Stats` left stats.gd out, while project_dependencies
+	# named it. The same reading as that tool's, so the two agree.
+	var classes_used: Array[Dictionary] = []
+	if _dependencies == null:
+		_dependencies = GdhDependencies.new(_log)
+	var declared_by: Dictionary = _dependencies.classes_declared()
+	for used: String in GdhDependencies.classes_used_in(content, declared_by):
+		var declaring: String = str(declared_by[used])
+		if declaring == full_script_path:
+			continue
+		classes_used.append({"name": used, "path": declaring})
+		if not declaring in dependencies:
+			dependencies.append(declaring)
+
+	# An autoload is named the way a class is, and its script is one this one needs to compile, but
+	# the project loads it rather than this script, so it is answered apart from dependencies.
+	var global_autoloads: Dictionary = {}
+	for property: Dictionary in ProjectSettings.get_property_list():
+		var setting: String = str(property.get("name", ""))
+		var value: String = (
+			str(ProjectSettings.get_setting(setting)) if setting.begins_with("autoload/") else ""
+		)
+		if value.begins_with("*"):
+			global_autoloads[setting.trim_prefix("autoload/")] = value.trim_prefix("*")
+	var autoloads_used: Array[Dictionary] = []
+	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])})
+
+	var answer: Dictionary = {
+		"path": script_path,
+		"full_path": full_script_path,
+		"class_name": own.declared_class_name,
+		"extends": extends_name,
+		"signals": own.signals,
+		"variables": own.variables,
+		"functions": functions,
+		"constants": own.constants,
+		"enums": own.enums,
+		"inner_classes": own.inner_classes,
+		"dependencies": dependencies,
+		"classes_used": classes_used,
+		"autoloads_used": autoloads_used,
+		"line_count": lines.size() - 1 if content.is_empty() or content.ends_with("\n") else lines.size()
+	}
+	if GdhRead.as_bool(params.get("include_inherited", false)):
+		_add_inherited(answer, [full_script_path])
+	return answer
+
+
+## What one class body declares: the script's own at the left margin, or an inner class's at the
+## indent [param margin] its body is written at, read from line [param first] to the first line
+## less indented than that. [param dependencies] collects what every line loads, bodies included.
+func _members(
+	lines: PackedStringArray, first: int, margin: String, dependencies: Array[String]
+) -> GdhMembers:
+	var own: GdhMembers = GdhMembers.new()
 	var in_multiline_string: bool = false
 
-	var i: int = -1
+	var i: int = first - 1
 	while i + 1 < lines.size():
 		i += 1
 		# The comment off first, so nothing downstream has to know about them. It was reaching the
@@ -72,6 +163,12 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 		if stripped.is_empty():
 			continue
 
+		# A line back at a shallower indent closes an inner class's body, and is the outer body's
+		# to read.
+		if not raw.begins_with(margin):
+			own.last = i - 1
+			return own
+
 		# 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.
@@ -79,10 +176,11 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 		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
+		# Only a line at this body's own margin declares one of its members. Deeper, 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"):
+		var indented: String = raw.substr(margin.length())
+		if indented.begins_with(" ") or indented.begins_with("\t"):
 			_collect_dependencies(stripped, dependencies)
 			continue
 
@@ -113,86 +211,75 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 			header = GdhPatterns.without_annotations(stripped)
 		var declaration: RegExMatch = GdhPatterns.declared_class(header)
 		if declaration != null:
-			declared_class_name = declaration.get_string(1)
+			own.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
 			# reported `Blade extends Node2D` as the class while `extends` kept its default of
 			# `RefCounted`: the name unusable and the base flatly wrong.
 			if not declaration.get_string(2).is_empty():
-				extends_name = declaration.get_string(2)
+				own.extends_name = declaration.get_string(2)
 		elif header.begins_with("extends "):
-			extends_name = header.substr(8).strip_edges()
+			own.extends_name = header.substr(8).strip_edges()
 		elif header.begins_with("signal "):
 			# `at`, not `i`: a wrapped declaration starts where it starts, and `i` is now sitting on
 			# the line that closed it.
-			signals.append(_parse_signal(header, at + 1))
+			own.signals.append(_parse_signal(header, at + 1))
 		elif header.begins_with("const "):
-			constants.append(_parse_constant(header, at + 1))
+			own.constants.append(_parse_constant(header, at + 1))
 		elif header.begins_with("enum "):
-			enums.append(_parse_enum(header, at + 1))
-		elif header.begins_with("var "):
+			own.enums.append(_parse_enum(header, at + 1))
+		elif header.begins_with("var ") or header.begins_with("static var "):
 			# The whole line here, not the header: which annotations a variable carries is the
 			# answer rather than noise in front of it, and `@export_range(0, 1)` is the hint.
-			variables.append(_parse_variable(stripped, at + 1))
+			own.variables.append(_parse_variable(stripped, at + 1))
 		elif header.begins_with("func ") or header.begins_with("static func "):
-			functions.append(_parse_function(header, at + 1, stripped))
+			own.functions.append(_parse_function(header, at + 1, stripped))
 		elif header.begins_with("class "):
-			inner_classes.append(header.substr(6).split(":")[0].split(" ")[0].strip_edges())
+			_collect_dependencies(stripped, dependencies)
+			var inner: GdhMembers = _inner_class(lines, i, margin, header, dependencies)
+			own.inner_classes.append(inner.as_inner())
+			i = inner.last
+			continue
 
 		_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, full_script_path)
-
-	# A script typed by its class_name is depended on as surely as one preloaded, and the answer
-	# listed only the preloads: a `var stats: Stats` left stats.gd out, while project_dependencies
-	# named it. The same reading as that tool's, so the two agree.
-	var classes_used: Array[Dictionary] = []
-	if _dependencies == null:
-		_dependencies = GdhDependencies.new(_log)
-	var declared_by: Dictionary = _dependencies.classes_declared()
-	for used: String in GdhDependencies.classes_used_in(content, declared_by):
-		var declaring: String = str(declared_by[used])
-		if declaring == full_script_path:
+	own.last = lines.size() - 1
+	return own
+
+
+## The inner class whose `class` line is [param at], [param header] with its annotations and
+## comment off, read with the members its body declares. Answered as a name alone, its members
+## were in no answer at all.
+func _inner_class(
+	lines: PackedStringArray, at: int, margin: String, header: String, dependencies: Array[String]
+) -> GdhMembers:
+	var signature: String = _up_to(header.substr(6), ":").strip_edges()
+	var based: String = ""
+	if " extends " in signature:
+		based = signature.get_slice(" extends ", 1).strip_edges()
+	# The body is at the indent of its first line, whatever this file indents with.
+	var body_margin: String = ""
+	for next: int in range(at + 1, lines.size()):
+		if GdhPatterns.without_comment(lines[next]).is_empty():
 			continue
-		classes_used.append({"name": used, "path": declaring})
-		if not declaring in dependencies:
-			dependencies.append(declaring)
-
-	# An autoload is named the way a class is, and its script is one this one needs to compile, but
-	# the project loads it rather than this script, so it is answered apart from dependencies.
-	var global_autoloads: Dictionary = {}
-	for property: Dictionary in ProjectSettings.get_property_list():
-		var setting: String = str(property.get("name", ""))
-		var value: String = (
-			str(ProjectSettings.get_setting(setting)) if setting.begins_with("autoload/") else ""
-		)
-		if value.begins_with("*"):
-			global_autoloads[setting.trim_prefix("autoload/")] = value.trim_prefix("*")
-	var autoloads_used: Array[Dictionary] = []
-	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])})
-
-	var answer: Dictionary = {
-		"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,
-		"classes_used": classes_used,
-		"autoloads_used": autoloads_used,
-		"line_count": lines.size() - 1 if content.is_empty() or content.ends_with("\n") else lines.size()
-	}
-	if GdhRead.as_bool(params.get("include_inherited", false)):
-		_add_inherited(answer, [full_script_path])
-	return answer
+		var indent: String = _indentation(lines[next])
+		if indent.length() > margin.length() and lines[next].begins_with(margin):
+			body_margin = indent
+		break
+	var body: GdhMembers = (
+		GdhMembers.new() if body_margin.is_empty() else _members(lines, at + 1, body_margin, dependencies)
+	)
+	if body_margin.is_empty():
+		body.last = at
+	if not based.is_empty():
+		body.extends_name = based
+	body.inner_name = signature.get_slice(" ", 0)
+	body.line = at + 1
+	_mark_virtuals(body.functions, body.extends_name, _reading)
+	return body
+
+
+static func _indentation(line: String) -> String:
+	return line.substr(0, line.length() - line.strip_edges(true, false).length())
 
 
 # Which of these functions the engine will call, asked of the engine.
@@ -340,7 +427,67 @@ func _parse_constant(line: String, line_num: int) -> Dictionary:
 	else:
 		name = const_text
 
-	return {"name": name, "value": value, "type": type_hint, "line": line_num}
+	var constant: Dictionary = {"name": name, "value": value, "type": type_hint, "line": line_num}
+	# A constant has its value's type whether or not it is written with :=.
+	if type_hint.is_empty():
+		_infer(constant, value)
+	return constant
+
+
+## Gives [param declared] the type GDScript infers from [param value], marked inferred, when the
+## value is a literal or a built-in type's constructor: `const MAX_STACK := 99` read as having no
+## type though the engine holds an int. Any other expression is left without one, since only the
+## engine's analyser knows what it gives.
+static func _infer(declared: Dictionary, value: String) -> void:
+	# A variable with a setter or getter ends its line with the colon that opens them.
+	var text: String = value.strip_edges().trim_suffix(":").strip_edges()
+	var type: String = ""
+	if text == "true" or text == "false":
+		type = "bool"
+	elif text.is_valid_int() or text.is_valid_hex_number(true):
+		type = "int"
+	elif text.is_valid_float():
+		type = "float"
+	elif text.begins_with('&"') and text.ends_with('"'):
+		type = "StringName"
+	elif text.begins_with('^"') and text.ends_with('"'):
+		type = "NodePath"
+	elif text.length() > 1 and text[0] in ['"', "'"] and text.ends_with(text[0]):
+		type = "String"
+	elif _whole(text, "[", "]"):
+		type = "Array"
+	elif _whole(text, "{", "}"):
+		type = "Dictionary"
+	else:
+		var called: String = text.get_slice("(", 0).strip_edges()
+		if _whole(text.substr(called.length()), "(", ")") and _built_in_types().has(called):
+			type = called
+	if not type.is_empty():
+		declared["type"] = type
+		declared["inferred"] = true
+
+
+## Whether [param text] is one bracketed whole, its first [param opening] closed by its last
+## character, so `[1, 2]` is a list and `[1, 2].size()` is not.
+static func _whole(text: String, opening: String, closing: String) -> bool:
+	if not text.begins_with(opening) or not text.ends_with(closing):
+		return false
+	var depth: int = 0
+	for index: int in text.length():
+		if text[index] == opening:
+			depth += 1
+		elif text[index] == closing:
+			depth -= 1
+			if depth == 0:
+				return index == text.length() - 1
+	return false
+
+
+static func _built_in_types() -> Dictionary:
+	var names: Dictionary = {}
+	for type: int in TYPE_MAX:
+		names[type_string(type)] = true
+	return names
 
 
 func _parse_enum(line: String, line_num: int) -> Dictionary:
@@ -412,15 +559,22 @@ func _parse_variable(line: String, line_num: int) -> Dictionary:
 	if "=" in var_text:
 		stated_default = default_value
 
-	return {
+	var variable: Dictionary = {
 		"name": name,
 		"type": type_hint,
 		"default_value": stated_default,
 		"is_export": is_export,
 		"export_hint": export_hint,
 		"is_onready": is_onready,
+		# One per class rather than per instance, which a caller reading a counter needs to know.
+		"is_static": GdhPatterns.without_annotations(line).begins_with("static "),
 		"line": line_num
 	}
+	# Only := types a variable by its value; one written with = alone holds any type.
+	var walrus: bool = "=" in var_text and var_text.split("=", true, 1)[0].strip_edges().ends_with(":")
+	if walrus and type_hint.is_empty():
+		_infer(variable, default_value)
+	return variable
 
 
 func _parse_function(line: String, line_num: int, annotated: String = "") -> Dictionary: