gdharness 1.3.6 → 1.3.8

package/build/godot/operations/gdscript_analysis.gd

@@ -23,6 +23,8 @@ class GdhMembers:
 	var constants: Array[Dictionary] = []
 	var enums: Array[Dictionary] = []
 	var inner_classes: Array[Dictionary] = []
+	## The `##` comment the class is documented with, empty when it has none.
+	var doc: String = ""
 	## 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.
@@ -43,6 +45,22 @@ class GdhMembers:
 			"inner_classes": inner_classes,
 		}
 
+	## Whether a member is declared yet, past which a `##` block no longer documents the class.
+	func declares_members() -> bool:
+		return not (
+			signals.is_empty()
+			and variables.is_empty()
+			and functions.is_empty()
+			and constants.is_empty()
+			and enums.is_empty()
+			and inner_classes.is_empty()
+		)
+
+	## [param lines] as the class's documentation, when it has none yet.
+	func take_doc(lines: Array[String]) -> void:
+		if doc.is_empty() and not lines.is_empty():
+			doc = "\n".join(PackedStringArray(lines))
+
 
 func _init(p_log: GdhLog) -> void:
 	_log = p_log
@@ -130,6 +148,8 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 		"autoloads_used": autoloads_used,
 		"line_count": lines.size() - 1 if content.is_empty() or content.ends_with("\n") else lines.size()
 	}
+	if not own.doc.is_empty():
+		answer["class_doc"] = own.doc
 	if GdhRead.as_bool(params.get("include_inherited", false)):
 		_add_inherited(answer, [full_script_path])
 	return answer
@@ -143,6 +163,7 @@ func _members(
 ) -> GdhMembers:
 	var own: GdhMembers = GdhMembers.new()
 	var in_multiline_string: bool = false
+	var doc: Array[String] = []
 
 	var i: int = first - 1
 	while i + 1 < lines.size():
@@ -158,9 +179,25 @@ func _members(
 			if _triple_quotes(raw) % 2 == 1:
 				in_multiline_string = false
 			continue
+		# A `##` block documents what it sits directly above: the class when that is its class_name
+		# or extends line, or when a blank line follows it before any member, and otherwise the next
+		# member. One at a shallower indent is the outer body's, for what follows this inner class.
+		var trimmed: String = raw.strip_edges()
+		if trimmed.begins_with("##"):
+			if not raw.begins_with(margin):
+				own.last = i - 1
+				return own
+			if _indentation(raw).length() <= margin.length():
+				var said: String = trimmed.substr(2)
+				doc.append(said.substr(1) if said.begins_with(" ") else said)
+			continue
 		var stripped: String = GdhPatterns.without_comment(raw)
 
 		if stripped.is_empty():
+			if trimmed.is_empty() and not doc.is_empty():
+				if not own.declares_members():
+					own.take_doc(doc)
+				doc.clear()
 			continue
 
 		# A line back at a shallower indent closes an inner class's body, and is the outer body's
@@ -210,6 +247,7 @@ func _members(
 				stripped = (stripped + " " + GdhPatterns.without_comment(lines[i])).strip_edges()
 			header = GdhPatterns.without_annotations(stripped)
 		var declaration: RegExMatch = GdhPatterns.declared_class(header)
+		var entry: Dictionary = {}
 		if declaration != null:
 			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
@@ -217,29 +255,47 @@ func _members(
 			# `RefCounted`: the name unusable and the base flatly wrong.
 			if not declaration.get_string(2).is_empty():
 				own.extends_name = declaration.get_string(2)
+			own.take_doc(doc)
 		elif header.begins_with("extends "):
 			own.extends_name = header.substr(8).strip_edges()
+			own.take_doc(doc)
 		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.
-			own.signals.append(_parse_signal(header, at + 1))
+			entry = _parse_signal(header, at + 1)
+			own.signals.append(entry)
 		elif header.begins_with("const "):
-			own.constants.append(_parse_constant(header, at + 1))
+			entry = _parse_constant(header, at + 1)
+			own.constants.append(entry)
 		elif header.begins_with("enum "):
-			own.enums.append(_parse_enum(header, at + 1))
+			entry = _parse_enum(header, at + 1)
+			own.enums.append(entry)
 		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.
-			own.variables.append(_parse_variable(stripped, at + 1))
+			entry = _parse_variable(stripped, at + 1)
+			own.variables.append(entry)
 		elif header.begins_with("func ") or header.begins_with("static func "):
-			own.functions.append(_parse_function(header, at + 1, stripped))
+			entry = _parse_function(header, at + 1, stripped)
+			own.functions.append(entry)
 		elif header.begins_with("class "):
 			_collect_dependencies(stripped, dependencies)
 			var inner: GdhMembers = _inner_class(lines, i, margin, header, dependencies)
-			own.inner_classes.append(inner.as_inner())
+			entry = inner.as_inner()
+			if not doc.is_empty():
+				entry["doc"] = "\n".join(PackedStringArray(doc))
+			doc.clear()
+			own.inner_classes.append(entry)
 			i = inner.last
 			continue
 
+		if not entry.is_empty() and not doc.is_empty():
+			entry["doc"] = "\n".join(PackedStringArray(doc))
+		# A line of annotations alone, `@tool` or `@export` above its variable, is between a comment
+		# and what it documents rather than after it.
+		if not header.is_empty():
+			doc.clear()
+
 		_collect_dependencies(stripped, dependencies)
 
 	own.last = lines.size() - 1

package/build/godot/operations/gdscript_authoring.gd

@@ -196,7 +196,10 @@ func modify_gdscript(params: Dictionary) -> Dictionary:
 	if not problems.is_empty():
 		var refusal: String = "Nothing was changed: " + "; ".join(problems)
 		if _redeclares(modifications, declared):
-			refusal += ". modify only adds, so a member the script declares already is changed in the file itself"
+			refusal += (
+				". modify only adds members; to change one the script declares already,"
+				+ " edit its lines in the file"
+			)
 		return _log.failure(refusal)
 	# 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

package/build/godot/operations/godot_operations.gd

@@ -237,6 +237,8 @@ func _run(operation: String, params: Dictionary) -> Dictionary:
 			payload = GdhDependencies.new(_log).get_dependencies(params)
 		"find_resource_usages":
 			payload = GdhDependencies.new(_log).find_resource_usages(params)
+		"list_script_classes":
+			payload = GdhDependencies.new(_log).list_script_classes(params)
 		"get_project_health":
 			payload = GdhProjectDiagnostics.new(_log).get_project_health(params)
 

package/build/godot/operations/import_pipeline.gd

@@ -227,6 +227,7 @@ func set_import_options(params: Dictionary) -> Dictionary:
 	# One already holding the value given changes nothing, and listing it as updated said it had.
 	var updated_keys: Array[String] = []
 	var unchanged_keys: Array[String] = []
+	var changes: Dictionary = {}
 	for name: String in fitted_values:
 		var held: Variant = config.get_value("params", name, null)
 		var value: Variant = fitted_values[name]
@@ -235,6 +236,10 @@ func set_import_options(params: Dictionary) -> Dictionary:
 			continue
 		config.set_value("params", name, value)
 		updated_keys.append(name)
+		changes[name] = {
+			"was": null if held == null else _values.serialize_value(held),
+			"now": _values.serialize_value(value),
+		}
 		_log.debug("Set " + name + " = " + str(value))
 
 	if not updated_keys.is_empty():
@@ -244,6 +249,8 @@ func set_import_options(params: Dictionary) -> Dictionary:
 
 	# The reimport that applies them is the server's, through the editor or the engine's import.
 	var answer: Dictionary = {"resource_path": resource_path, "updated_options": updated_keys}
+	if not changes.is_empty():
+		answer["changed"] = changes
 	if not unchanged_keys.is_empty():
 		answer["unchanged_options"] = unchanged_keys
 	return answer
@@ -387,6 +394,25 @@ func validate_project(params: Dictionary) -> Dictionary:
 			)
 		)
 
+	# 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://", IMPORTABLE_EXTENSIONS):
+		if not FileAccess.file_exists(path + ".import"):
+			never.append(path)
+	if not never.is_empty():
+		never.sort()
+		warnings.append(
+			_finding(
+				"warning",
+				"imports",
+				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(
@@ -602,7 +628,25 @@ func _no_sidecar(resource_path: String) -> String:
 		return resource_path + " has no import options: " + never
 	return (
 		resource_path
-		+ " has not been imported yet, so it has no import file: project_import reimport imports it"
+		+ " has not been imported yet, so it has no import file: project_import reimport imports"
+		+ " it with the importer's defaults and writes that file"
+	)
+
+
+## [param paths], files the engine imports and never has, as health and validation say it: at most
+## five named, since a project never opened in an editor has every one of its assets here.
+static func never_imported_line(paths: Array[String]) -> String:
+	var named: String = ", ".join(paths.slice(0, 5))
+	if paths.size() > 5:
+		named += " and %d more" % (paths.size() - 5)
+	if paths.size() == 1:
+		return (
+			named
+			+ " has never been imported, so nothing can load it until project_import reimport imports it"
+		)
+	return (
+		"%d files have never been imported, so nothing can load them until project_import reimport imports them: %s"
+		% [paths.size(), named]
 	)
 
 

package/build/godot/operations/project_diagnostics.gd

@@ -50,14 +50,15 @@ func get_project_health(params: Dictionary) -> Dictionary:
 			"res://", GdhImportPipeline.IMPORTABLE_EXTENSIONS
 		)
 
-		var missing_imports: int = 0
+		var missing_imports: Array[String] = []
 		for res: String in resources:
 			if not FileAccess.file_exists(res + ".import"):
-				missing_imports += 1
+				missing_imports.append(res)
 
-		if missing_imports > 0:
-			details.append(str(missing_imports) + " resources may need reimporting")
-			deductions += missing_imports
+		if not missing_imports.is_empty():
+			missing_imports.sort()
+			details.append(GdhImportPipeline.never_imported_line(missing_imports))
+			deductions += missing_imports.size()
 
 		checks["resources"] = {
 			"name": "Resources",

package/build/godot/operations/reading.gd

@@ -152,7 +152,7 @@ static func not_of_kind(
 	if not found.is_empty():
 		told += ' The node at "%s" is %s, not %s.' % [node_path, with_article(found), with_article(kind)]
 	if holders.is_empty():
-		return told + " The scene holds no %s." % kind
+		return told + " The scene holds no %s; scene_node add with nodeType %s puts one in it." % [kind, kind]
 	var quoted: PackedStringArray = []
 	for holder: String in holders.slice(0, NAMED_CHILDREN):
 		var _quoted: bool = quoted.append('"%s"' % holder)

package/build/godot/tests/listed.gd

@@ -218,12 +218,14 @@ static func argument_after(args: PackedStringArray, flag: String) -> String:
 
 
 ## The errors each of [param suites] declares it expects, by suite path and then case name, read off
-## the compiled suite's constants so a declaration is whatever the engine made of it. A suite
-## declaring none is left out.
+## the compiled suite's constants so a declaration is whatever the engine made of it. A directory
+## listed is walked for its scripts, as gdUnit4 walks it for suites. Only a script whose source names
+## the constant is loaded: gdUnit4 stops on a suite that does not load only when its own load is the
+## one that fails, so a broken suite loaded here first let the rest of its directory run.
 static func expected_by_suite(suites: PackedStringArray) -> Dictionary:
 	var expected: Dictionary = {}
-	for path: String in suites:
-		if not path.ends_with(".gd") or not ResourceLoader.exists(path):
+	for path: String in scripts_in(suites):
+		if not FileAccess.file_exists(path) or not FileAccess.get_file_as_string(path).contains(EXPECTED):
 			continue
 		var suite: Script = load(path)
 		var declared: Variant = suite.get_script_constant_map().get(EXPECTED)
@@ -232,6 +234,26 @@ static func expected_by_suite(suites: PackedStringArray) -> Dictionary:
 	return expected
 
 
+## The scripts [param paths] names: each script, and every script under each directory.
+static func scripts_in(paths: PackedStringArray) -> PackedStringArray:
+	var found: PackedStringArray = []
+	var pending: PackedStringArray = []
+	for path: String in paths:
+		if path.ends_with(".gd"):
+			var _script: bool = found.append(path)
+		else:
+			var _directory: bool = pending.append(path.trim_suffix("/"))
+	while not pending.is_empty():
+		var directory: String = pending[pending.size() - 1]
+		pending.remove_at(pending.size() - 1)
+		for file: String in DirAccess.get_files_at(directory):
+			if file.ends_with(".gd"):
+				var _file: bool = found.append("%s/%s" % [directory, file])
+		for inner: String in DirAccess.get_directories_at(directory):
+			var _inner: bool = pending.append("%s/%s" % [directory, inner])
+	return found
+
+
 static func write_expected(path: String, suites: PackedStringArray) -> void:
 	var file: FileAccess = FileAccess.open(path, FileAccess.WRITE)
 	if file == null:

package/build/keeper.js

@@ -703,6 +703,8 @@ function readMessage(body) {
 // src/game-debugger.ts
 var PAUSE_MS = 30000;
 var STEP_MS = 1e4;
+var ADDON_STEP_MS = 5000;
+var RUNTIME_ADDON = "res://addons/gdharness_runtime/";
 var READ_MS = 5000;
 var REPLIES = new Set([
   "debug_enter",
@@ -1085,9 +1087,29 @@ class GameDebugger {
         };
       }
     }
+    let frames = await this.stack();
+    const stepping = Date.now();
+    while (frames !== null && this.held !== null && (frames[0]?.script.startsWith(RUNTIME_ADDON) ?? false) && Date.now() - stepping < ADDON_STEP_MS) {
+      this.forget("debug_enter");
+      this.send("step", [], this.held.thread);
+      if (await this.next(GameDebugger.named("debug_enter"), STEP_MS) === null) {
+        return {
+          paused: false,
+          note: `The game stopped in gdharness's runtime addon and was stepped on to reach its own script, and did not stop again within ${STEP_MS / 1000}s. It stops at the next line of script it runs; debug_state stack reads it then.`
+        };
+      }
+      frames = await this.stack();
+    }
     this.stoppedBy("Paused");
-    const frames = await this.stack();
-    return { paused: true, held: this.heldState(), stack: frames ?? [] };
+    const stack = frames ?? [];
+    return {
+      paused: true,
+      held: this.heldState(),
+      stack,
+      ...stack[0]?.script.startsWith(RUNTIME_ADDON) === true ? {
+        note: `The game is held in gdharness's runtime addon, whose _process runs first in every frame: ${ADDON_STEP_MS / 1000}s of stepping reached no line of the game's own script, so it runs none from frame to frame. A breakpoint in the game's script stops it there.`
+      } : {}
+    };
   }
   stoppedBy(cause) {
     if (this.held !== null) {
@@ -1108,7 +1130,7 @@ class GameDebugger {
       return await exited === null ? { refused: `The game did not say it had gone on within ${READ_MS / 1000}s.` } : { continued: true };
     }
     this.forget("debug_enter");
-    this.send(how, [], held.thread);
+    this.send(held.hasStack ? how : "step", [], held.thread);
     const entered = await this.next(GameDebugger.named("debug_enter"), STEP_MS);
     if (entered === null) {
       return {
@@ -1646,6 +1668,7 @@ function emptyRecord() {
 // src/project-scan.ts
 var SKIPPED = new Set(["node_modules"]);
 var SCENE_EXTENSIONS = new Set(["tscn", "scn"]);
+var SIDECAR_EXTENSIONS = new Set(["import", "uid"]);
 var ASSET_EXTENSIONS = new Set([
   "png",
   "jpg",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "mcpName": "io.github.Aureliolo/gdharness",
   "description": "A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.",
   "type": "module",