gdharness 1.1.21 → 1.1.23

package/build/godot/operations/gdscript_authoring.gd

@@ -23,6 +23,24 @@ func create_gdscript(params: Dictionary) -> Dictionary:
 
 	_log.info("Creating GDScript: " + script_path)
 
+	# Content is the whole file, so a header written above it would be a second one: a content that
+	# starts with its own `extends` did not parse, and one without it was not the file that was sent.
+	if not content.is_empty():
+		var alongside: Array[String] = []
+		for name: String in ["class_name", "extends", "template"]:
+			if not str(params.get(name, "")).is_empty():
+				alongside.append(name)
+		if not alongside.is_empty():
+			return _log.failure(
+				(
+					"content is the whole file, so "
+					+ " and ".join(alongside)
+					+ " cannot be given with it: write "
+					+ ("them" if alongside.size() > 1 else "it")
+					+ " into content instead"
+				)
+			)
+
 	var full_script_path: String = script_path
 	if not full_script_path.begins_with("res://"):
 		full_script_path = "res://" + full_script_path
@@ -41,20 +59,16 @@ func create_gdscript(params: Dictionary) -> Dictionary:
 		if error != OK:
 			return _log.failure("Failed to create directory: " + script_dir + ", error: " + str(error))
 
-	var script_content: String = ""
-
-	if not cls_name_param.is_empty():
-		script_content += "class_name " + cls_name_param + "\n"
-
-	script_content += "extends " + extends_class + "\n\n"
-
-	if not template.is_empty():
-		script_content += _script_template(template)
-	elif not content.is_empty():
-		script_content += content
-	else:
-		script_content += "func _ready() -> void:\n"
-		script_content += "\tpass\n"
+	var script_content: String = content
+	if content.is_empty():
+		if not cls_name_param.is_empty():
+			script_content += "class_name " + cls_name_param + "\n"
+		script_content += "extends " + extends_class + "\n\n"
+		if not template.is_empty():
+			script_content += _script_template(template)
+		else:
+			script_content += "func _ready() -> void:\n"
+			script_content += "\tpass\n"
 
 	var file: FileAccess = FileAccess.open(full_script_path, FileAccess.WRITE)
 	if not file:
@@ -65,21 +79,20 @@ func create_gdscript(params: Dictionary) -> Dictionary:
 	if not stored:
 		return _log.failure("Failed to write to script file: " + full_script_path)
 
-	# Whether the engine accepts what was written, parsed under this project's own warning
-	# settings: a script that does not load is a script the caller wants to hear about now,
-	# and the reason is on stderr, which comes back with the answer.
 	var written: Script = ResourceLoader.load(full_script_path, "Script", ResourceLoader.CACHE_MODE_IGNORE)
-
-	return {
+	var answer: Dictionary = {
 		"success": true,
 		"script_path": script_path,
 		"full_path": full_script_path,
 		"absolute_path": ProjectSettings.globalize_path(full_script_path),
-		"registered": not cls_name_param.is_empty(),
-		"extends": extends_class,
 		"template_used": template if not template.is_empty() else "none",
-		"parses": written != null and written.can_instantiate(),
+		"parses": _parses(written),
 	}
+	# Read off the file as the engine parsed it rather than off the arguments, which content leaves out.
+	if written != null:
+		answer["extends"] = _base_named(written)
+		answer["class_name"] = str(written.get_global_name())
+	return answer
 
 
 # Modify an existing GDScript file by adding functions, variables, or signals
@@ -103,34 +116,40 @@ func modify_gdscript(params: Dictionary) -> Dictionary:
 	var original_content: String = file.get_as_text()
 	file.close()
 
+	# All of them checked before any is made, so a call is made whole or not at all: one skipped for a
+	# missing name used to leave the rest written and the answer saying success over an empty list.
+	var problems: Array[String] = _modification_problems(modifications)
+	if not problems.is_empty():
+		return _log.failure("Nothing was changed: " + "; ".join(problems))
+
 	var lines: Array[String] = []
 	lines.assign(original_content.split("\n"))
-	var modifications_applied: Array[Dictionary] = []
+	# 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
+	# at the moment it was placed.
+	var placed: Array[Dictionary] = []
 
 	for mod: Variant in modifications:
-		if not mod is Dictionary:
-			_log.error("Modification must be an object")
-			continue
 		var fields: Dictionary = mod
 		var mod_type: String = str(fields.get("type", ""))
-		var mod_name: String = str(fields.get("name", ""))
-
-		if mod_name.is_empty():
-			_log.error("Modification missing 'name' field")
-			continue
-
+		var at: int = -1
 		match mod_type:
 			"add_variable":
-				var line: int = _add_variable(lines, fields)
-				modifications_applied.append({"type": "add_variable", "name": mod_name, "line": line})
+				at = _add_variable(lines, fields, placed)
 			"add_signal":
-				var line: int = _add_signal(lines, fields)
-				modifications_applied.append({"type": "add_signal", "name": mod_name, "line": line})
+				at = _add_signal(lines, fields, placed)
 			"add_function":
-				var line: int = _add_function(lines, fields)
-				modifications_applied.append({"type": "add_function", "name": mod_name, "line": line})
-			_:
-				_log.error("Unknown modification type: " + mod_type)
+				at = _add_function(lines, fields, placed)
+		if at == -1:
+			return _log.failure(
+				"Nothing was changed: " + mod_type + " " + str(fields.get("name")) + " could not be placed"
+			)
+		placed.append({"type": mod_type, "name": str(fields.get("name")), "index": at})
+
+	var modifications_applied: Array[Dictionary] = []
+	for entry: Dictionary in placed:
+		var index: int = entry["index"]
+		modifications_applied.append({"type": entry["type"], "name": entry["name"], "line": index + 1})
 
 	file = FileAccess.open(full_script_path, FileAccess.WRITE)
 	if not file:
@@ -141,17 +160,75 @@ func modify_gdscript(params: Dictionary) -> Dictionary:
 	if not rewrote:
 		return _log.failure("Failed to write to script file: " + full_script_path)
 
+	var made: Script = ResourceLoader.load(full_script_path, "Script", ResourceLoader.CACHE_MODE_IGNORE)
 	return {
 		"success": true,
 		"script_path": script_path,
 		"modifications_applied": modifications_applied,
-		"total_modifications": modifications_applied.size()
+		"total_modifications": modifications_applied.size(),
+		"parses": _parses(made),
 	}
 
 
-# Inserts the declaration and answers with its one-based line number, or 0 for one that could not
-# be placed, which is a number no line has.
-func _add_variable(lines: Array[String], mod: Dictionary) -> int:
+# Every reason [param modifications] cannot be made as asked, each naming the entry by position.
+static func _modification_problems(modifications: Array) -> Array[String]:
+	var problems: Array[String] = []
+	if modifications.is_empty():
+		problems.append("modifications is empty")
+	for index: int in range(modifications.size()):
+		var mod: Variant = modifications[index]
+		var which: String = "modification " + str(index + 1)
+		if not mod is Dictionary:
+			problems.append(which + " is not an object")
+			continue
+		var fields: Dictionary = mod
+		var mod_type: String = str(fields.get("type", ""))
+		var mod_name: String = str(fields.get("name", ""))
+		if mod_type not in ["add_variable", "add_signal", "add_function"]:
+			problems.append(
+				which + " has type '" + mod_type + "', not add_variable, add_signal or add_function"
+			)
+		if mod_name.is_empty():
+			problems.append(which + " has no name")
+		elif not mod_name.is_valid_unicode_identifier():
+			problems.append(which + " is named '" + mod_name + "', which GDScript does not accept as a name")
+	return problems
+
+
+# Inserts [param new_lines] at [param at] and moves every placed line at or below it down by as many.
+static func _insert(
+	lines: Array[String], at: int, new_lines: Array[String], placed: Array[Dictionary]
+) -> bool:
+	for i: int in range(new_lines.size() - 1, -1, -1):
+		if lines.insert(at, new_lines[i]) != OK:
+			push_error("gdharness: could not place a line at " + str(at))
+			return false
+	for entry: Dictionary in placed:
+		var index: int = entry["index"]
+		if index >= at:
+			entry["index"] = index + new_lines.size()
+	return true
+
+
+# Whether the engine accepts [param script], parsed under this project's own warning settings: a
+# script that does not load is one the caller wants to hear about now, and the reason is on stderr,
+# which comes back with the answer. A script that fails to parse still loads, as one that cannot be
+# instantiated; an abstract one that parses can be, on 4.7.
+static func _parses(script: Script) -> bool:
+	return script != null and script.can_instantiate()
+
+
+# What [param script] extends: the base script by class name or path, or the native class.
+static func _base_named(script: Script) -> String:
+	var base: Script = script.get_base_script()
+	if base == null:
+		return str(script.get_instance_base_type())
+	var named: String = str(base.get_global_name())
+	return named if not named.is_empty() else base.resource_path
+
+
+# Inserts the declaration and answers with its zero-based index, or -1 for one that could not be placed.
+func _add_variable(lines: Array[String], mod: Dictionary, placed: Array[Dictionary]) -> int:
 	var var_name: String = str(mod.get("name", ""))
 	var var_type: String = str(mod.get("varType", ""))
 	var default_value: String = str(mod.get("defaultValue", ""))
@@ -186,10 +263,7 @@ func _add_variable(lines: Array[String], mod: Dictionary) -> int:
 		var_line += ": Variant"
 
 	var insert_line: int = _variable_insertion_point(lines)
-	if lines.insert(insert_line, var_line) != OK:
-		push_error("gdharness: could not place a declaration at line " + str(insert_line))
-		return 0
-	return insert_line + 1
+	return insert_line if _insert(lines, insert_line, [var_line], placed) else -1
 
 
 # The type name a constant expression evaluates to, or Variant when it is not one: a call
@@ -208,7 +282,7 @@ func _type_of_literal(expression: String) -> String:
 	return type_string(typeof(value))
 
 
-func _add_signal(lines: Array[String], mod: Dictionary) -> int:
+func _add_signal(lines: Array[String], mod: Dictionary, placed: Array[Dictionary]) -> int:
 	var signal_name: String = str(mod.get("name", ""))
 	var signal_params: String = str(mod.get("params", ""))
 
@@ -217,13 +291,11 @@ func _add_signal(lines: Array[String], mod: Dictionary) -> int:
 		signal_line += "(" + signal_params + ")"
 
 	var insert_line: int = _signal_insertion_point(lines)
-	if lines.insert(insert_line, signal_line) != OK:
-		push_error("gdharness: could not place a signal at line " + str(insert_line))
-		return 0
-	return insert_line + 1
+	return insert_line if _insert(lines, insert_line, [signal_line], placed) else -1
 
 
-func _add_function(lines: Array[String], mod: Dictionary) -> int:
+# Answers with the zero-based index of the `func` line, below the blank line that separates it.
+func _add_function(lines: Array[String], mod: Dictionary, placed: Array[Dictionary]) -> int:
 	var func_name: String = str(mod.get("name", ""))
 	var func_params: String = str(mod.get("params", ""))
 	# A function that names no return type returns nothing, and says so, for the same reason
@@ -248,12 +320,7 @@ func _add_function(lines: Array[String], mod: Dictionary) -> int:
 	if insert_line < lines.size():
 		func_lines.append("")
 
-	for i: int in range(func_lines.size() - 1, -1, -1):
-		if lines.insert(insert_line, func_lines[i]) != OK:
-			push_error("gdharness: could not place a function at line " + str(insert_line))
-			return 0
-
-	return insert_line + 1
+	return insert_line + 1 if _insert(lines, insert_line, func_lines, placed) else -1
 
 
 func _variable_insertion_point(lines: Array[String]) -> int:

package/build/godot/operations/godot_operations.gd

@@ -2,8 +2,13 @@
 extends SceneTree
 
 # The command line the server runs is `godot --headless --path <project> --script <this>
-# <operation> @file:<params.json>`, and one JSON object on stdout is the answer. Everything an
-# operation does lives in a sibling module; this file is the command table and the wire format.
+# <operation> @file:<params.json> <answer.json>`, and the one JSON object written to the answer
+# file is the answer. Everything an operation does lives in a sibling module; this file is the
+# command table and the wire format.
+#
+# A file rather than a line on stdout, because the project's autoloads run after `_init` and print
+# into the same stream: an autoload printing a dictionary in `_process` was the last JSON line out
+# and was taken as the answer. Nothing the project prints can reach the file.
 #
 # Each module is preloaded by a path relative to this script rather than a res:// one, because
 # the operations directory ships inside the server package and is handed to the engine as an
@@ -39,8 +44,9 @@ func _init() -> void:
 		return
 
 	var params_index: int = script_index + 3
-	if args.size() <= params_index:
-		_log.error("Usage: godot --headless --script godot_operations.gd <operation> <json_params>")
+	var answer_index: int = script_index + 4
+	if args.size() <= answer_index:
+		_log.error("Usage: godot_operations.gd <operation> @file:<params.json> <answer.json>")
 		_log.error("Not enough command-line arguments provided.")
 		quit(1)
 		return
@@ -65,7 +71,20 @@ func _init() -> void:
 		quit(1)
 		return
 
-	print(JSON.stringify(payload))
+	var answer_path: String = args[answer_index]
+	var answer: FileAccess = FileAccess.open(answer_path, FileAccess.WRITE)
+	if answer == null:
+		_log.error(
+			"Could not write the answer to " + answer_path + ": " + error_string(FileAccess.get_open_error())
+		)
+		quit(1)
+		return
+	var written: bool = answer.store_string(JSON.stringify(payload))
+	answer.close()
+	if not written:
+		_log.error("Could not write the answer to " + answer_path)
+		quit(1)
+		return
 	quit()
 
 

package/build/godot/operations/import_pipeline.gd

@@ -1,6 +1,7 @@
 extends RefCounted
 
 const Read = preload("reading.gd")
+const Serialisation = preload("serialisation.gd")
 const FileWalk = preload("file_walk.gd")
 const Log = preload("logger.gd")
 
@@ -37,11 +38,20 @@ const IMPORTABLE_EXTENSIONS: Array[String] = [
 	"obj",
 	"dae",
 ]
+## The format version each importer writes as `importer_version` where it is above 0, which the
+## editor reimports anything older than. Read off sidecars 4.7.2 writes: scene and animation_library
+## write 1, and the texture importers write none. A case imports one fresh and compares, so an engine
+## that raises one fails it rather than leaving this behind.
+const IMPORTER_VERSIONS: Dictionary[String, int] = {"scene": 1, "animation_library": 1}
+## The VRAM compression formats a project can ask for, each behind its
+## `rendering/textures/vram_compression/import_<format>` setting.
+const VRAM_FORMATS: Array[String] = ["s3tc_bptc", "etc2_astc"]
 const EDITOR_DIRECTORY: String = "res://.godot/editor"
 const EDITOR_CACHE_PREFIX: String = "filesystem_cache"
 
 var _log: Log
 var _files: FileWalk = FileWalk.new()
+var _values: Serialisation = Serialisation.new()
 var _sidecar_md5s: Variant = null
 
 
@@ -63,7 +73,7 @@ func get_import_status(params: Dictionary) -> Dictionary:
 
 	var resources: Array[Dictionary] = []
 	var summary: Dictionary = {
-		"total": 0, "needs_reimport": 0, "failed": 0, "up_to_date": 0, "missing_source": 0
+		"total": 0, "needs_reimport": 0, "failed": 0, "up_to_date": 0, "missing_source": 0, "not_imported": 0
 	}
 
 	if not resource_path.is_empty():
@@ -107,8 +117,7 @@ func get_import_options(params: Dictionary) -> Dictionary:
 	var import_file_path: String = resource_path + ".import"
 
 	if not FileAccess.file_exists(import_file_path):
-		_log.error("Import file does not exist: " + import_file_path)
-		return _log.failure("This resource may not have been imported yet")
+		return _log.failure(_no_sidecar(resource_path))
 
 	var config: ConfigFile = ConfigFile.new()
 	var err: Error = config.load(import_file_path)
@@ -120,11 +129,14 @@ func get_import_options(params: Dictionary) -> Dictionary:
 		"resource_path": resource_path, "import_file": import_file_path, "remap": {}, "deps": {}, "params": {}
 	}
 
+	# Through the serialiser, as every other read answers: an engine type written straight into
+	# JSON is its own text, so a Vector3 option came back as "(1, 1, 1)", and writing that back put
+	# a string in the sidecar where the importer reads a vector.
 	for section: String in ["remap", "deps", "params"]:
 		if config.has_section(section):
 			var values: Dictionary = result[section]
 			for key: String in config.get_section_keys(section):
-				values[key] = config.get_value(section, key)
+				values[key] = _values.serialize_value(config.get_value(section, key))
 
 	return result
 
@@ -142,8 +154,12 @@ func set_import_options(params: Dictionary) -> Dictionary:
 	var import_file_path: String = resource_path + ".import"
 
 	if not FileAccess.file_exists(import_file_path):
-		_log.error("Import file does not exist: " + import_file_path)
-		return _log.failure("This resource may not have been imported yet")
+		return _log.failure(_no_sidecar(resource_path))
+	# A sidecar left behind by a source that has gone takes options that nothing will ever apply.
+	if not FileAccess.file_exists(resource_path):
+		return _log.failure(
+			resource_path + " is not on disk, so there is nothing its import options apply to"
+		)
 
 	var config: ConfigFile = ConfigFile.new()
 	var err: Error = config.load(import_file_path)
@@ -151,13 +167,37 @@ func set_import_options(params: Dictionary) -> Dictionary:
 	if err != OK:
 		return _log.failure("Failed to parse import file: " + str(err))
 
-	var updated_keys: Array[String] = []
+	# Every option checked before any is written, so a refused one leaves the sidecar as it was.
+	var fitted_values: Dictionary = {}
+	var refused: Array[String] = []
 	for key: Variant in options:
 		var name: String = str(key)
-		var value: Variant = _as_option(options[key], config.get_value("params", name, null))
-		config.set_value("params", name, value)
+		var held: Variant = config.get_value("params", name, null)
+		var given: Variant = _values.deserialize_value(options[key])
+		var value: Variant = _as_option(_values.fitted(options[key], typeof(held)), held)
+		# A number the option cannot hold whole is refused rather than truncated: 2.5 fitted to an
+		# enum option became 2, which is another setting.
+		var lossy: bool = (
+			(given is int or given is float)
+			and (value is int or value is float)
+			and type_convert(value, typeof(given)) != given
+		)
+		if held != null and (lossy or not Serialisation.acceptable(value, typeof(held))):
+			var held_type: String = type_string(typeof(held))
+			var article: String = "an" if held_type.to_lower()[0] in "aeiou" else "a"
+			refused.append(
+				"%s holds %s %s, and %s is not one" % [name, article, held_type, JSON.stringify(options[key])]
+			)
+			continue
+		fitted_values[name] = value
+	if not refused.is_empty():
+		return _log.failure("Nothing was written: " + "; ".join(refused))
+
+	var updated_keys: Array[String] = []
+	for name: String in fitted_values:
+		config.set_value("params", name, fitted_values[name])
 		updated_keys.append(name)
-		_log.debug("Set " + name + " = " + str(value))
+		_log.debug("Set " + name + " = " + str(fitted_values[name]))
 
 	err = config.save(import_file_path)
 	if err != OK:
@@ -178,6 +218,19 @@ static func _as_option(given: Variant, held: Variant) -> Variant:
 	return given
 
 
+# The names of the project's export presets, in the order export_presets.cfg holds them.
+static func _preset_names() -> Array[String]:
+	var names: Array[String] = []
+	var config: ConfigFile = ConfigFile.new()
+	if config.load("res://export_presets.cfg") != OK:
+		return names
+	var index: int = 0
+	while config.has_section("preset." + str(index)):
+		names.append(str(config.get_value("preset." + str(index), "name", "")))
+		index += 1
+	return names
+
+
 # List export presets
 func list_export_presets(_params: Dictionary) -> Dictionary:
 	_log.info("Listing export presets")
@@ -257,12 +310,12 @@ func validate_project(params: Dictionary) -> Dictionary:
 				include_suggestions
 			)
 		)
-	elif not FileAccess.file_exists(main_scene):
+	elif not FileWalk.missing_reason(main_scene).is_empty():
 		issues.append(
 			_finding(
 				"error",
 				"main_scene",
-				"Main scene file does not exist: " + main_scene,
+				"Main scene " + FileWalk.missing_reason(main_scene),
 				"Update the main scene setting or create the missing scene file",
 				include_suggestions
 			)
@@ -280,6 +333,30 @@ func validate_project(params: Dictionary) -> Dictionary:
 			)
 		)
 
+	# 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] = _preset_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 in the editor: Project > Export",
+					include_suggestions
+				)
+			)
+
 	checks_performed.append("icon")
 	var icon_path: String = str(ProjectSettings.get_setting("application/config/icon", ""))
 	if icon_path.is_empty():
@@ -323,11 +400,8 @@ func validate_project(params: Dictionary) -> 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:
+	for script_path: String in script_files.slice(0, 100):
 		scripts_checked += 1
-		if scripts_checked > 100:
-			break
-
 		var file: FileAccess = FileAccess.open(script_path, FileAccess.READ)
 		if file:
 			var content: String = file.get_as_text()
@@ -355,6 +429,8 @@ func validate_project(params: Dictionary) -> Dictionary:
 		"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()
 	}
@@ -389,10 +465,14 @@ func _import_status_of(resource_path: String, import_file_path: String) -> Dicti
 
 	var import_file_exists: bool = FileAccess.file_exists(import_file_path)
 	if not import_file_exists:
+		# A file with no sidecar has not been imported only if it is something the engine imports.
+		# A scene answered as needing an import, and a reimport of it ran a pass and then reported
+		# the scene as not reimported, which reads as the import failing.
+		var never: String = _never_imported(resource_path)
 		return {
 			"path": resource_path,
-			"status": "needs_reimport",
-			"reason": "it has not been imported",
+			"status": "needs_reimport" if never.is_empty() else "not_imported",
+			"reason": "it has not been imported" if never.is_empty() else never,
 			"import_file_exists": false,
 			"source_exists": true
 		}
@@ -402,7 +482,9 @@ func _import_status_of(resource_path: String, import_file_path: String) -> Dicti
 	}
 
 	# The checks are the ones EditorFileSystem::_test_for_reimport makes, in its order, so a resource
-	# reads as needing an import exactly when the editor's next scan would import it.
+	# reads as needing an import when the editor's next scan would import it. The importer's own two
+	# cannot be asked here, where no importer is loaded, so they are made from what was measured of
+	# the built-in ones; an importer a plugin adds is judged by its files alone.
 	var sidecar: ConfigFile = ConfigFile.new()
 	var stale: Dictionary = (
 		_stale("its import file cannot be read")
@@ -416,6 +498,41 @@ func _import_status_of(resource_path: String, import_file_path: String) -> Dicti
 	return status
 
 
+# Why [param resource_path] has no import file, with what to do about it where anything can be done.
+func _no_sidecar(resource_path: String) -> String:
+	if not FileAccess.file_exists(resource_path):
+		return resource_path + " is not on disk"
+	var never: String = _never_imported(resource_path)
+	if not never.is_empty():
+		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"
+	)
+
+
+# Why the engine will never import [param resource_path], or empty when it would.
+func _never_imported(resource_path: String) -> String:
+	var folder: String = resource_path.get_base_dir()
+	while folder.begins_with("res://"):
+		if _files.is_stepped_over(folder if folder.ends_with("/") else folder + "/"):
+			return "a .gdignore in " + folder + " keeps the engine from importing anything under it"
+		if folder == "res://":
+			break
+		folder = folder.get_base_dir()
+	var extension: String = resource_path.get_extension().to_lower()
+	if extension in IMPORTABLE_EXTENSIONS:
+		return ""
+	# Loadable without a sidecar is what a scene, a script or a saved resource is: read as it is.
+	if ResourceLoader.exists(resource_path):
+		return "the engine loads ." + extension + " files as they are, without importing them"
+	return (
+		"no importer built into the engine takes ."
+		+ extension
+		+ " files; one added by a plugin or an extension is known only to the editor, whose scan imports them"
+	)
+
+
 static func _stale(reason: String) -> Dictionary:
 	return {"status": "needs_reimport", "reason": reason}
 
@@ -443,6 +560,27 @@ func _sidecar_staleness(resource_path: String, import_file_path: String, sidecar
 ## Whether the import itself is still the one its sidecar and source describe: an answer for a
 ## stale resource, empty for a current one.
 static func _import_staleness(resource_path: String, sidecar: ConfigFile) -> Dictionary:
+	# The importer is asked first, as the editor asks it: whether it still writes this format, and
+	# whether the settings the import was made under still hold. Both are true of an import whose
+	# files are all current, so they were answered as up to date while the editor's next scan
+	# imported them again: every scene after an engine upgrade raised the importer's version, and
+	# every VRAM texture once the project asked for another compression format.
+	var importer: String = str(sidecar.get_value("remap", "importer", ""))
+	var version: int = Read.as_int(sidecar.get_value("remap", "importer_version", 0))
+	var current: int = Read.as_int(IMPORTER_VERSIONS.get(importer, 0))
+	if current > version:
+		return _stale(
+			(
+				"it was imported at version %d of the %s importer, and this engine imports at version %d"
+				% [version, importer, current]
+			)
+		)
+	var lacking: Array[String] = _vram_formats_lacking(sidecar.get_value("remap", "metadata", {}))
+	if not lacking.is_empty():
+		return _stale(
+			"the project now asks for " + ", ".join(lacking) + " textures, and this import did not write them"
+		)
+
 	if not sidecar.has_section_key("remap", "uid"):
 		return _stale("its import file has no uid, which the import writes")
 
@@ -505,6 +643,28 @@ static func _import_staleness(resource_path: String, sidecar: ConfigFile) -> Dic
 	return built
 
 
+## The VRAM formats the project asks textures to be imported in that an import recorded in
+## [param metadata] did not write, as the texture importers judge whether their settings still hold.
+## Measured on 4.7.2 for the texture and texture array importers: turning a format on reimports every
+## VRAM texture without it, and turning one off reimports nothing.
+static func _vram_formats_lacking(metadata: Variant) -> Array[String]:
+	var lacking: Array[String] = []
+	if not metadata is Dictionary:
+		return lacking
+	var meta: Dictionary = metadata
+	if not Read.as_bool(meta.get("vram_texture", false)):
+		return lacking
+	var written: Variant = meta.get("imported_formats", [])
+	var formats: Array = written if written is Array else []
+	for format: String in VRAM_FORMATS:
+		var asked: bool = Read.as_bool(
+			ProjectSettings.get_setting("rendering/textures/vram_compression/import_" + format, false)
+		)
+		if asked and format not in formats:
+			lacking.append(format)
+	return lacking
+
+
 ## The hashes [param resource_path]'s last import recorded, [code]source_md5[/code] of its source
 ## and [code]dest_md5[/code] of its outputs, empty when there is no record: the editor keeps them
 ## beside the outputs, under the same base name with [code].md5[/code].

package/build/godot/operations/logger.gd

@@ -1,7 +1,7 @@
 extends RefCounted
 
-# The server reads one JSON object off stdout and everything else as diagnostics, so the
-# prefixes are what let a human tell the two apart in a log without parsing it.
+# Everything printed is diagnostics; the answer goes to a file. The server reads `[ERROR]` lines as
+# the operation's own errors, and the prefixes let a human read the rest without parsing it.
 #
 # Every module preloads this as `Log`. `Logger` is a native class from Godot 4.5 on, and a
 # constant of that name is a parse error rather than a shadowing warning.