gdharness 0.13.30 → 0.13.32

package/build/godot/operations/patterns.gd

@@ -13,10 +13,74 @@ extends RefCounted
 # `engine_messages`. The empty RegEx it then returns matches nothing, which is the honest result of
 # a pattern that does not exist.
 
+# 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 = {}
+
 
 static func compiled(expression: String) -> RegEx:
+	if _compiled.has(expression):
+		var held: RegEx = _compiled[expression]
+		return held
 	var regex: RegEx = RegEx.new()
 	var built: Error = regex.compile(expression)
 	if built != OK:
 		push_error("gdharness: could not compile the pattern " + expression)
+	_compiled[expression] = regex
 	return regex
+
+
+# What a header line declares: the class name, and the base named on the same line if there is one.
+#
+# `class_name X extends Y` is one line, so a reader that takes the rest of the line as the name gets
+# `Blade extends Node2D` for the class and never sees the base at all.
+static func declared_class(line: String) -> RegExMatch:
+	return compiled("^class_name\\s+([A-Za-z_][A-Za-z0-9_]*)(?:\\s+extends\\s+(\\S+))?").search(line)
+
+
+# The annotations at the front of a line, in order, written as they are without the leading `@`.
+#
+# For anything that has to answer about the annotations rather than see past them. Splitting one on
+# whitespace loses half of it, since `@export_range(0, 10)` has a space inside the parentheses and
+# was reported as the hint `range(0,`.
+# An `Array[String]` rather than a `PackedStringArray`, because the packed one's `append` answers
+# with a bool and a project holding `return_value_discarded` at error will not compile a script that
+# throws it away, which is the whole reason `compiled` exists a few lines up.
+static func annotations_on(line: String) -> Array[String]:
+	var annotation: RegEx = compiled('^@([a-z_]+)(\\(\\s*(?:"[^"]*")?[^)]*\\))?\\s*')
+	var found: Array[String] = []
+	var rest: String = line.strip_edges()
+	var matched: RegExMatch = annotation.search(rest)
+	while matched != null:
+		found.append(matched.get_string(1) + matched.get_string(2))
+		rest = rest.substr(matched.get_end()).strip_edges()
+		matched = annotation.search(rest)
+	return found
+
+
+# A line with its leading annotations taken off, for anything reading a script's header.
+#
+# Annotations may share a line with what they annotate: `@abstract class_name X` is one line in
+# Godot 4.5 and later, and `@tool` and `@icon("res://x.svg")` sit there too. Four readers here
+# matched on `class_name` at the start of a line and so saw none of those as a declaration at all,
+# which cost a project with gdUnit4 in it 23 classes reported as declared nowhere, and put a
+# `script_edit` insertion above the `class_name` of a script whose whole header is that one line,
+# where it does not parse. The scanner that writes the class cache had its own copy of this and was
+# right, which is why only the readings were wrong.
+#
+# One home, because five spellings of the same rule is five things to remember when the language
+# adds the next annotation.
+static func without_annotations(line: String) -> String:
+	var annotation: RegEx = compiled('^@[a-z_]+(?:\\(\\s*(?:"[^"]*")?[^)]*\\))?\\s*')
+	var rest: String = line.strip_edges()
+	var found: RegExMatch = annotation.search(rest)
+	while found != null:
+		rest = rest.substr(found.get_end()).strip_edges()
+		found = annotation.search(rest)
+	return rest

package/build/index.js

@@ -10028,14 +10028,14 @@ var SERVER_VERSION = (() => {
     return "0.0.0";
   }
 })();
-var UNVERSIONED = "addon from before versions were reported";
+var UNVERSIONED = "an addon from before versions were reported";
 function addonMismatch(addonVersion, serverVersion) {
   if (addonVersion === serverVersion) {
     return;
   }
   const reported = addonVersion ?? "";
-  const editor = reported === "" ? UNVERSIONED : reported;
-  const both = `The editor is running the ${editor} addon while this server ships ${serverVersion}.`;
+  const editor = reported === "" ? UNVERSIONED : `the ${reported} addon`;
+  const both = `The editor is running ${editor} while this server ships ${serverVersion}.`;
   if (reported !== "" && isNewer(reported, serverVersion)) {
     return `${both} This server is the older half: reconnect it in your harness so it spawns ${reported}.`;
   }
@@ -24781,6 +24781,7 @@ function withdrawBridge(path) {
 // src/class-cache.ts
 import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync4, statSync } from "node:fs";
 import { join as join3 } from "node:path";
+var DECLARATION = /^(?:@[a-z_]+(?:\([^)\n]*\))?\s+)*class_name\s+([A-Za-z_][A-Za-z0-9_]*)/m;
 function declaredClasses(projectPath) {
   const declared = new Map;
   const visit = (directory, prefix) => {
@@ -24795,7 +24796,7 @@ function declaredClasses(projectPath) {
       if (entry.isDirectory()) {
         visit(path, `${prefix}${entry.name}/`);
       } else if (entry.isFile() && entry.name.endsWith(".gd")) {
-        const found = /^class_name\s+([A-Za-z_][A-Za-z0-9_]*)/m.exec(readFileSync4(path, "utf8"));
+        const found = DECLARATION.exec(readFileSync4(path, "utf8"));
         if (found?.[1]) {
           declared.set(found[1], `res://${prefix}${entry.name}`);
         }
@@ -24916,7 +24917,7 @@ function heldButGone(projectPath, editorHolds) {
 }
 function unseenByEditor(projectPath, editorHolds) {
   const held = new Set(editorHolds);
-  return [...declaredClasses(projectPath)].filter(([name]) => !held.has(name)).map(([className, path]) => ({ className, path }));
+  return [...declaredClasses(projectPath)].filter(([name]) => !held.has(name)).map(([className, path]) => ({ className, path })).sort((one, other) => one.className < other.className ? -1 : one.className > other.className ? 1 : 0);
 }
 
 // src/config-pin.ts
@@ -25756,6 +25757,9 @@ var CONNECT_WINDOW_MS = 35000;
 function mayYetConnect(listeningSince, now = Date.now()) {
   return listeningSince === undefined || now - listeningSince.getTime() < CONNECT_WINDOW_MS;
 }
+function theEditorHasComeBack(status, startedAt) {
+  return status.connected && (status.connectedAt?.getTime() ?? 0) > startedAt && status.addonVersion !== undefined;
+}
 function anEditorIsStillComing(listeningSince, launchedEditorIsAlive, now = Date.now()) {
   return mayYetConnect(listeningSince, now) || launchedEditorIsAlive;
 }
@@ -28671,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: {
@@ -28941,7 +28945,7 @@ var TOOL_SPECS = [
       scriptPath: SCRIPT_PATH,
       includeInherited: {
         type: "boolean",
-        description: "structure: include inherited members. Default false."
+        description: "structure: also list what the script inherits, walking extends through the project's other scripts. Each such member carries inherited_from, the file declaring it, and the answer gains inherits_from, the chain that was walked. A name the script overrides is listed at both its lines rather than once. A native base is not walked, since it declares nothing in a file: editor_classes info answers for those. Default false."
       },
       line: { type: "number", description: "completion, hover: zero-based line." },
       character: { type: "number", description: "completion, hover: zero-based column." }
@@ -29039,7 +29043,7 @@ var TOOL_SPECS = [
       runtimeWaitMs: {
         type: "number",
         ops: ["start"],
-        description: "start: how long to wait for the game to announce its runtime before answering. Default 5000. Worth raising for a project that takes longer than that to reach its first frame, which is what leaves runtime listening false on a game whose runtime arrives a moment later. 0 does not wait at all, which is the one to pass for a scene that announces nothing by construction, such as a bench that prints and quits."
+        description: "start: how long to wait for the game to announce its runtime before answering. Default 5000. What it waits for is the first frame, so everything the game does before drawing one is inside it, including work the args just asked for: a flag that simulates six years of game time before anything is drawn makes the announcement that late, on a project that announces promptly without it. Raise it for such a run rather than reading runtime listening false as a fault. 0 does not wait at all, which is the one to pass for a scene that announces nothing by construction, such as a bench that prints and quits."
       },
       frames: {
         type: "number",
@@ -29560,7 +29564,7 @@ function runtimeVerdict(endpoint, after) {
   return {
     listening: false,
     mayYetAnnounce: after.running,
-    note: after.running ? `nothing announced itself within ${after.budgetMs}ms and the game is still running, so it may announce a moment from now: editor_status says whether it has, and editor_run start takes runtimeWaitMs to wait longer than this` : `nothing announced itself within ${after.budgetMs}ms and the game is no longer running, so nothing is going to: editor_output has what it printed on the way down`,
+    note: after.running ? `nothing announced itself within ${after.budgetMs}ms and the game is still running, so it may announce a moment from now: editor_status says whether it has, and editor_run start takes runtimeWaitMs to wait longer than this${after.withArgs ? ", which a run carrying its own arguments may well need, since whatever they ask the game to do before its first frame is inside this wait" : ""}` : `nothing announced itself within ${after.budgetMs}ms and the game is no longer running, so nothing is going to: editor_output has what it printed on the way down`,
     heldAt: null
   };
 }
@@ -31096,10 +31100,7 @@ class GodotServer {
     }
     const startedAt = before.connectedAt?.getTime() ?? 0;
     const began = Date.now();
-    const back = await this.waitForBridge(() => {
-      const status = this.godotBridge.getStatus();
-      return status.connected && (status.connectedAt?.getTime() ?? 0) > startedAt;
-    }, began + EDITOR_RESTART_TIMEOUT_MS);
+    const back = await this.waitForBridge(() => theEditorHasComeBack(this.godotBridge.getStatus(), startedAt), began + EDITOR_RESTART_TIMEOUT_MS);
     if (!back) {
       return this.createErrorResponse(`The editor was asked to restart and has not come back within ${EDITOR_RESTART_TIMEOUT_MS / 1000}s.`, [
         "It may be asking what to do about an unsaved scene: look at the editor window",
@@ -31294,7 +31295,7 @@ class GodotServer {
       transcript: started.transcript,
       refreshedClasses: refreshed.value,
       endedPreviousRun: ended ?? undefined,
-      runtime: await this.runtimeUp(project.value.path, alreadyPlaying, runtimeWaitMs),
+      runtime: await this.runtimeUp(project.value.path, alreadyPlaying, runtimeWaitMs, given.value.length > 0),
       message: `Use editor_output for what it prints and editor_run stop to end it.${spawnedInstead}${endedForThis}`
     });
   }
@@ -31303,9 +31304,9 @@ class GodotServer {
     const editorSays = run?.throughEditor === true ? (await this.editorPlayingState())?.playing ?? null : null;
     return runIsUp(run, editorSays);
   }
-  async runtimeUp(projectPath, before, budgetMs) {
+  async runtimeUp(projectPath, before, budgetMs, withArgs) {
     if (!existsSync9(join11(projectPath, RUNTIME_AUTOLOAD.path))) {
-      return runtimeVerdict(null, { addon: false, budgetMs, heldAt: null, running: false });
+      return runtimeVerdict(null, { addon: false, budgetMs, heldAt: null, running: false, withArgs });
     }
     const endpoint = await announcedSince(projectPath, before, {
       budgetMs,
@@ -31315,7 +31316,8 @@ class GodotServer {
       addon: true,
       budgetMs,
       heldAt: this.dapClient?.whereItStopped() ?? null,
-      running: await this.gameIsUp()
+      running: await this.gameIsUp(),
+      withArgs
     });
   }
   async playThroughEditor(scene, refreshedClasses, projectPath, alreadyPlaying, runtimeWaitMs, ended) {
@@ -31366,7 +31368,7 @@ class GodotServer {
       refreshedClasses,
       debugPort: readNumber(asParams(JSON.parse(answer.content[0]?.text ?? "{}")), "debugPort"),
       endedPreviousRun: ended ?? undefined,
-      runtime: await this.runtimeUp(projectPath, alreadyPlaying, runtimeWaitMs),
+      runtime: await this.runtimeUp(projectPath, alreadyPlaying, runtimeWaitMs, false),
       message: "The editor is playing it, so its debugger holds it: the debug_* tools can reach it, " + "editor_output reads its console through the debug adapter, and editor_run stop ends it." + (ended === null ? "" : ` The run that was going, pid ${ended}, was ended to start this one; its output is no longer what editor_output answers about.`)
     });
   }

package/package.json

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