gdharness 1.3.8 → 1.3.10

package/build/godot/operations/project_validation.gd

@@ -0,0 +1,266 @@
+extends RefCounted
+
+## Whether a project is ready to run and export: its settings, main scene, imports, presets,
+## scripts, references and signal connections, each named under checks_performed.
+
+const GdhDependencies = preload("dependencies.gd")
+const GdhExportPresets = preload("export_presets.gd")
+const GdhFileWalk = preload("file_walk.gd")
+const GdhImportPipeline = preload("import_pipeline.gd")
+const GdhLog = preload("logger.gd")
+const GdhRead = preload("reading.gd")
+const GdhSceneConnections = preload("scene_connections.gd")
+const GdhScriptCheck = preload("script_check.gd")
+const CONNECTION_FIX: String = (
+	"Write the method or signal, or point the connection at the one that replaced it with" + " scene_signal"
+)
+
+var _log: GdhLog
+var _files: GdhFileWalk = GdhFileWalk.new()
+
+
+func _init(p_log: GdhLog) -> void:
+	_log = p_log
+
+
+func validate_project(params: Dictionary) -> Dictionary:
+	var preset_name: String = str(params.get("preset", ""))
+	var include_suggestions: bool = GdhRead.as_bool(params.get("include_suggestions", true), true)
+
+	_log.info("Validating project" + (" for preset: " + preset_name if not preset_name.is_empty() else ""))
+
+	var issues: Array[Dictionary] = []
+	var warnings: Array[Dictionary] = []
+	var checks_performed: Array[String] = []
+
+	checks_performed.append("project_file")
+	if not FileAccess.file_exists("res://project.godot"):
+		issues.append(
+			_finding(
+				"error",
+				"project_file",
+				"project.godot not found",
+				"Ensure you are running this from a valid Godot project directory",
+				include_suggestions
+			)
+		)
+
+	checks_performed.append("main_scene")
+	var main_scene: String = str(ProjectSettings.get_setting("application/run/main_scene", ""))
+	if main_scene.is_empty():
+		issues.append(
+			_finding(
+				"error",
+				"main_scene",
+				"No main scene set",
+				"Set a main scene in Project Settings > Application > Run > Main Scene",
+				include_suggestions
+			)
+		)
+	elif not GdhFileWalk.missing_reason(main_scene).is_empty():
+		issues.append(
+			_finding(
+				"error",
+				"main_scene",
+				"Main scene " + GdhFileWalk.missing_reason(main_scene),
+				"Update the main scene setting or create the missing scene file",
+				include_suggestions
+			)
+		)
+
+	# A file never imported is on disk, so the reference checks pass it, and still nothing loads it:
+	# a scene using one fails to load in a run or an export.
+	checks_performed.append("imports")
+	var never: Array[String] = []
+	for path: String in _files.find_files_with_extensions("res://", GdhImportPipeline.IMPORTABLE_EXTENSIONS):
+		if not FileAccess.file_exists(path + ".import"):
+			never.append(path)
+	if not never.is_empty():
+		never.sort()
+		warnings.append(
+			_finding(
+				"warning",
+				"imports",
+				GdhImportPipeline.never_imported_line(never),
+				"Run project_import reimport, or open the project in the editor, whose scan imports them",
+				include_suggestions
+			)
+		)
+
+	checks_performed.append("export_presets")
+	if not FileAccess.file_exists("res://export_presets.cfg"):
+		warnings.append(
+			_finding(
+				"warning",
+				"export_presets",
+				"No export presets configured",
+				"Add a preset with project_export add_preset, or in the editor: Project > Export",
+				include_suggestions
+			)
+		)
+
+	# The preset asked about is looked for rather than only logged: validating "for" a preset that
+	# does not exist answered valid, as though it had been checked.
+	if not preset_name.is_empty():
+		checks_performed.append("export_preset")
+		var named: Array[String] = GdhExportPresets.names()
+		if preset_name not in named:
+			issues.append(
+				_finding(
+					"error",
+					"export_preset",
+					(
+						"No export preset is named "
+						+ preset_name
+						+ (
+							": the project has none"
+							if named.is_empty()
+							else ": the presets are " + ", ".join(named)
+						)
+					),
+					"Pass one of the preset names, or add the preset with project_export add_preset",
+					include_suggestions
+				)
+			)
+		else:
+			var gone: Array[String] = GdhExportPresets.missing_named(preset_name)
+			if not gone.is_empty():
+				warnings.append(
+					_finding(
+						"warning",
+						"export_preset_files",
+						"The preset %s names files that are not there: %s" % [preset_name, "; ".join(gone)],
+						"Add the files, or point the options at others with project_export set_preset",
+						include_suggestions
+					)
+				)
+
+	checks_performed.append("icon")
+	var icon_path: String = str(ProjectSettings.get_setting("application/config/icon", ""))
+	if icon_path.is_empty():
+		warnings.append(
+			_finding(
+				"warning",
+				"icon",
+				"No application icon set",
+				"Set an icon in Project Settings > Application > Config > Icon",
+				include_suggestions
+			)
+		)
+	elif not FileAccess.file_exists(icon_path):
+		warnings.append(
+			_finding(
+				"warning",
+				"icon",
+				"Icon file does not exist: " + icon_path,
+				"Update the icon path or add the missing icon file",
+				include_suggestions
+			)
+		)
+
+	checks_performed.append("project_name")
+	var project_name: String = str(ProjectSettings.get_setting("application/config/name", ""))
+	if project_name.is_empty():
+		warnings.append(
+			_finding(
+				"warning",
+				"project_name",
+				"No project name set",
+				"Set a project name in Project Settings > Application > Config > Name",
+				include_suggestions
+			)
+		)
+
+	checks_performed.append("scripts")
+	var script_files: Array[String] = _files.find_files_with_extensions("res://", ["gd"])
+	var scripts_checked: int = 0
+	var script_issues: Array[Dictionary] = []
+
+	# A hundred scripts is enough to say whether the project is tidy without a large one
+	# turning validation into a full read of its source tree.
+	for script_path: String in script_files.slice(0, 100):
+		scripts_checked += 1
+		var file: FileAccess = FileAccess.open(script_path, FileAccess.READ)
+		if file:
+			var content: String = file.get_as_text()
+			file.close()
+
+			if "# TODO" in content or "# FIXME" in content:
+				script_issues.append({"path": script_path, "issue": "Contains TODO/FIXME comments"})
+			if "pass # TODO" in content:
+				script_issues.append({"path": script_path, "issue": "Contains unimplemented functions"})
+
+	# Compiled by the server and handed in, as for the health check: a script the engine refuses
+	# stops the export's game at the first scene using it, which the comment check above never saw.
+	var compiled: Dictionary = params.get("compiled", {})
+	if compiled.has("checked"):
+		checks_performed.append("compiles")
+	var failures: Array = compiled.get("failures", [])
+	for failure: Dictionary in failures:
+		issues.append(
+			_finding(
+				"error",
+				"compiles",
+				GdhScriptCheck.failure_line(failure),
+				"script_diagnostics gives every error in it with its line",
+				include_suggestions
+			)
+		)
+
+	checks_performed.append("references")
+	for entry: Dictionary in GdhDependencies.new(_log).missing_references():
+		issues.append(
+			_finding(
+				"error",
+				"references",
+				GdhDependencies.missing_line(entry),
+				"Restore the file, or point the reference at the file that replaced it",
+				include_suggestions
+			)
+		)
+
+	# A connection whose method or signal is not there loads without a word and fails only once the
+	# game runs, on every emission or not at all; the references check sees files, not members.
+	checks_performed.append("connections")
+	for entry: Dictionary in GdhSceneConnections.new(_log).broken():
+		warnings.append(
+			_finding(
+				"warning",
+				"connections",
+				GdhSceneConnections.broken_line(entry),
+				CONNECTION_FIX,
+				include_suggestions
+			)
+		)
+
+	if script_issues.size() > 0:
+		var warning: Dictionary = _finding(
+			"warning",
+			"scripts",
+			str(script_issues.size()) + " script issues found",
+			"Review and resolve TODO/FIXME items before release",
+			include_suggestions
+		)
+		warning["details"] = script_issues.slice(0, 5)
+		warnings.append(warning)
+
+	return {
+		"valid": issues.is_empty(),
+		"issues": issues,
+		"warnings": warnings,
+		"checks_performed": checks_performed,
+		"scripts_checked": scripts_checked,
+		# Said beside the count, so a project of four hundred scripts is not read as checked whole.
+		"scripts_total": script_files.size(),
+		"issue_count": issues.size(),
+		"warning_count": warnings.size()
+	}
+
+
+func _finding(
+	type: String, check: String, message: String, suggestion: String, include_suggestion: bool
+) -> Dictionary:
+	var finding: Dictionary = {"type": type, "check": check, "message": message}
+	if include_suggestion:
+		finding["suggestion"] = suggestion
+	return finding

package/build/godot/operations/property_paths.gd

@@ -26,38 +26,109 @@ static func declared_on(target: Object, property: String) -> Dictionary:
 ## start with the name of one holding a resource built into it, then a slash and a key of that
 ## resource: "sources/0/0:0/0/probability" is the probability of tile 0:0 in the atlas source a
 ## TileSet keeps as sources/0. A colon path cannot reach it, since the tile's own name holds colons.
-## A resource kept in a file of its own is not reached, nor, given the file [param home] that
-## [param target] is saved in, one built into another file, since writing it here would leave that
-## file as it was.
+## A list of resources is stepped into by an element's index: "lines/1/text" is the text of the
+## second resource in lines. A resource kept in a file of its own is not reached, nor, given the
+## file [param home] that [param target] is saved in, one built into another file, since writing it
+## here would leave that file as it was.
 static func holder_of(target: Object, key: String, home: String = "") -> Array:
 	var through: Array[Resource] = []
 	var holder: Object = target
 	var name: String = key
 	while declared_on(holder, name).is_empty():
 		var reached: Resource = null
+		var rest: int = -1
 		var at: int = name.find("/")
 		while at > 0:
-			var held: Resource = built_in_at(holder, name.left(at), home)
-			if held != null:
+			var stepped: Array = _stepped(holder, name, at)
+			var held: Resource = stepped[0]
+			if held != null and _built_into(held, home):
 				reached = held
+				rest = GdhRead.as_int(stepped[1])
 				break
 			at = name.find("/", at + 1)
 		if reached == null:
 			break
 		through.append(reached)
 		holder = reached
-		name = name.substr(at + 1)
+		name = name.substr(rest)
 	return [holder, name, through]
 
 
-## The resource [param target] holds under [param property] when it is built into a file, or null;
-## given [param home], only one built into that file or into none yet.
-static func built_in_at(target: Object, property: String, home: String = "") -> Resource:
-	var held: Resource = held_at(target, property)
-	if held == null or not held.is_built_in():
-		return null
+## The resource the part of [param name] before the slash at [param at] reaches on [param target],
+## as [resource, where the rest of [param name] starts], or [null, -1]: the one held under that key,
+## or the element of the list held there that the step after the slash indexes.
+static func _stepped(target: Object, name: String, at: int) -> Array:
+	var head: String = name.left(at)
+	var held: Resource = held_at(target, head)
+	if held != null:
+		return [held, at + 1]
+	var end: int = name.find("/", at + 1)
+	if end < 0 or declared_on(target, head).is_empty():
+		return [null, -1]
+	var index: String = name.substr(at + 1, end - at - 1)
+	var listed: Variant = target.get(head)
+	if not listed is Array or not index.is_valid_int():
+		return [null, -1]
+	var items: Array = listed
+	var place: int = index.to_int()
+	if place < 0 or place >= items.size() or not items[place] is Resource:
+		return [null, -1]
+	return [items[place], end + 1]
+
+
+## The refusal for [param name], which [param target] does not declare, when a step of it indexes a
+## list [param target] holds and names no resource in it; or "".
+static func unlisted(target: Object, name: String) -> String:
+	var at: int = name.find("/")
+	while at > 0:
+		var head: String = name.left(at)
+		var listed: Variant = null if declared_on(target, head).is_empty() else target.get(head)
+		if listed is Array:
+			var items: Array = listed
+			return _unlisted_in(items, "%s.%s" % [class_called(target), head], name, at)
+		at = name.find("/", at + 1)
+	return ""
+
+
+static func _unlisted_in(items: Array, called: String, name: String, at: int) -> String:
+	var head: String = name.left(at)
+	var end: int = name.find("/", at + 1)
+	var index: String = name.substr(at + 1) if end < 0 else name.substr(at + 1, end - at - 1)
+	if items.is_empty():
+		return "%s holds no elements, so %s names none: give %s a whole list first." % [called, name, head]
+	var last: int = items.size() - 1
+	if not index.is_valid_int():
+		return (
+			"%s is a list, so the step after it is the index of one of its elements, from 0 to %d, not %s."
+			% [called, last, index]
+		)
+	var place: int = index.to_int()
+	if place < 0 or place > last:
+		return (
+			"%s holds %d element%s, so %s names none: an index goes from 0 to %d."
+			% [called, items.size(), "" if items.size() == 1 else "s", name, last]
+		)
+	if not items[place] is Resource:
+		return (
+			"%s/%d holds %s, which has no properties to write: give %s a whole list instead."
+			% [head, place, type_string(typeof(items[place])), head]
+		)
+	if end < 0:
+		return (
+			(
+				"%s/%d is an element of %s, which a path does not replace alone: give %s a whole list, or "
+				+ "write a property of the element, as %s/%d/<property>."
+			)
+			% [head, place, called, head, head, place]
+		)
+	return ""
+
+
+static func _built_into(held: Resource, home: String) -> bool:
+	if not held.is_built_in():
+		return false
 	var file: String = held.resource_path.get_slice("::", 0)
-	return held if home.is_empty() or file.is_empty() or file == home else null
+	return home.is_empty() or file.is_empty() or file == home
 
 
 ## The file [param target] is saved in: its scene's for a node, as the nodes of an instance are
@@ -184,9 +255,11 @@ static func class_called(target: Object) -> String:
 static func held_elsewhere(target: Object, name: String, home: String) -> String:
 	var at: int = name.find("/")
 	while at > 0:
-		var head: String = name.left(at)
-		var rest: String = name.substr(at + 1)
-		var held: Resource = held_at(target, head)
+		var stepped: Array = _stepped(target, name, at)
+		var held: Resource = stepped[0]
+		var past: int = GdhRead.as_int(stepped[1])
+		var head: String = "" if held == null else name.left(past - 1)
+		var rest: String = "" if held == null else name.substr(past)
 		var file: String = "" if held == null else held.resource_path.get_slice("::", 0)
 		if held != null and not held.is_built_in():
 			return (