gdharness 0.13.31 → 0.13.32

package/build/cli.js

@@ -15593,7 +15593,7 @@ var init_tool_definitions = __esm(() => {
         direction: {
           type: "string",
           enum: ["forward", "reverse"],
-          description: "forward: what this resource loads, with cycles reported. reverse: every file that refers to it and how, a scene instancing it, a script extending, preloading or loading it, and for a script with a class_name every use of that name. Default forward."
+          description: "forward: what this resource loads, with cycles reported. reverse: every file that refers to it and how, a scene instancing it, a script extending, preloading or loading it, and for a script with a class_name every use of that name. Each reference carries a kind, and two of them are mentions rather than uses: doc is a name inside a ## documentation comment, which renaming would break in the generated docs, and comment is one in ordinary prose, which it would only make stale. summary.in_code is the count with both of those left out, which is the number to read when the question is whether anything still uses this. Default forward."
         },
         depth: { type: "number", description: "forward: how many levels to follow. Default unlimited." },
         includeBuiltin: {

package/build/godot/operations/dependencies.gd

@@ -128,6 +128,7 @@ func find_resource_usages(params: Dictionary) -> Dictionary:
 	var usages: Array[Dictionary] = []
 	var by_kind: Dictionary = {}
 	var total: int = 0
+	var in_code: int = 0
 
 	for file_path: String in all_files:
 		if file_path == resource_path:
@@ -141,16 +142,32 @@ func find_resource_usages(params: Dictionary) -> Dictionary:
 		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:
+				continue
+			var trimmed: String = line.strip_edges()
 			var kind: String = ""
-			if by_path.search(line) != null:
+			# A mention in a comment is not a use, and both were answered as one. The question a
+			# reverse walk is asked is whether anything still uses a class, and a project that
+			# documents itself names its collaborators in `##` links: four references to one class,
+			# 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("##"):
+				kind = "doc"
+			elif trimmed.begins_with("#"):
+				kind = "comment"
+			elif by_its_path:
 				kind = _path_reference_kind(line)
-			elif by_class != null and by_class.search(line) != null:
-				var bare: String = Patterns.without_annotations(line)
-				kind = "extends" if bare.begins_with("extends ") else "class_name"
-			if kind.is_empty():
-				continue
-			references.append({"line": i + 1, "kind": kind, "text": line.strip_edges()})
+			else:
+				kind = (
+					"extends" if Patterns.without_annotations(line).begins_with("extends ") else "class_name"
+				)
+			references.append({"line": i + 1, "kind": kind, "text": trimmed})
 			by_kind[kind] = Read.as_int(by_kind.get(kind, 0)) + 1
+			if kind != "doc" and kind != "comment":
+				in_code += 1
 
 		if not references.is_empty():
 			usages.append({"file": file_path, "references": references})
@@ -168,6 +185,9 @@ func find_resource_usages(params: Dictionary) -> Dictionary:
 			"files_searched": all_files.size(),
 			"files_with_usages": usages.size(),
 			"total": total,
+			# The arithmetic done here rather than left to the caller, because the caller who most
+			# needs it is the one asking whether a class is dead, and that caller reads one number.
+			"in_code": in_code,
 			"by_kind": by_kind,
 		},
 	}

package/build/godot/operations/gdscript_analysis.gd

@@ -80,6 +80,10 @@ func get_gdscript_info(params: Dictionary) -> Dictionary:
 		# Only a declaration, because an unbalanced line anywhere else is a file mid-edit and
 		# joining from one swallows the rest of it: a body holding `print(` with nothing closing it
 		# took every declaration below it, which is the state an agent is most likely to ask about.
+		# `header` rather than `stripped`: an annotation in front pushes the keyword off the start
+		# of the line, so asking the raw line whether it can wrap says no to every annotated
+		# declaration that does. Held by the combined case, which nothing else in the fixture
+		# reaches: the single-feature cases each carry one of these and never a second.
 		if _can_wrap(header):
 			while _bracket_depth(stripped) > 0 and i + 1 < lines.size():
 				i += 1
@@ -479,6 +483,12 @@ func _up_to(text: String, needle: String) -> String:
 
 
 # The line with any trailing comment taken off, quote-aware so a `#` inside a string stays.
+#
+# The only one of these scanners that does not count brackets, on purpose: a `#` starts a comment
+# wherever it is, and there is no depth at which it does not. Giving this one the depth its
+# neighbours have puts the comment into the value of `var table := {  # keyed by name`, because the
+# brace opens before the `#` and closes on a later line. Held by a case, since the argument for the
+# difference is not visible from the code and reads like an oversight beside its neighbours.
 func _without_comment(line: String) -> String:
 	var quote: String = ""
 	for i: int in range(line.length()):
@@ -510,9 +520,9 @@ func _closing_paren(text: String, from: int) -> int:
 		if ch == '"' or ch == "'":
 			quote = ch
 			continue
-		if ch == "(":
+		if ch == "(" or ch == "[" or ch == "{":
 			depth += 1
-		elif ch == ")":
+		elif ch == ")" or ch == "]" or ch == "}":
 			depth -= 1
 			if depth == 0:
 				return i

package/build/godot/operations/patterns.gd

@@ -16,6 +16,11 @@ extends RefCounted
 # Kept, because the readers below call these per line of every script in a project and a fresh
 # compile each time is the whole cost of the scan. The patterns are literals in this repository, so
 # the set is bounded by the source rather than by anything a caller passes.
+#
+# Held by `test/support/gd/patterns_cache.gd`, with `is_same` rather than `==`: two RegEx built from
+# one pattern match the same text and compare equal on everything else, so identity is the only
+# question that separates a cache from a recompile. Without that case, taking the cache away would
+# have broken no answer anywhere and failed nothing, which is the argued-and-unheld shape.
 static var _compiled: Dictionary = {}
 
 

package/build/index.js

@@ -28675,7 +28675,7 @@ var TOOL_SPECS = [
       direction: {
         type: "string",
         enum: ["forward", "reverse"],
-        description: "forward: what this resource loads, with cycles reported. reverse: every file that refers to it and how, a scene instancing it, a script extending, preloading or loading it, and for a script with a class_name every use of that name. Default forward."
+        description: "forward: what this resource loads, with cycles reported. reverse: every file that refers to it and how, a scene instancing it, a script extending, preloading or loading it, and for a script with a class_name every use of that name. Each reference carries a kind, and two of them are mentions rather than uses: doc is a name inside a ## documentation comment, which renaming would break in the generated docs, and comment is one in ordinary prose, which it would only make stale. summary.in_code is the count with both of those left out, which is the number to read when the question is whether anything still uses this. Default forward."
       },
       depth: { type: "number", description: "forward: how many levels to follow. Default unlimited." },
       includeBuiltin: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "0.13.31",
+  "version": "0.13.32",
   "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",