gdtypecheck 0.2.5

Report GDScript and shader compile errors and broken references in a Godot project, without running it
Documentation
extends SceneTree

# Loads a project's scripts in a headless Godot and reports what the GDScript
# compiler and the project's resource files say is wrong. See README.md.
#
# load() cannot be used to detect errors: it returns a non-null script even when
# the script fails to parse. Errors are collected from Godot's logger instead,
# which also provides their file and line.
#
# Everything happens in _init, before Godot creates the project's autoloads, and
# the process is then killed so that they are never created. That keeps the
# project's own code from running during a check. Static variable initializers
# of the loaded scripts are the one exception, as they run when a script loads.
#
# A project's warning settings apply to this script too, so everything is typed
# explicitly: it has to compile under the strictest of them. The list of warnings
# differs between Godot versions, which rules out @warning_ignore.

const WARNINGS_PREFIX: String = "debug/gdscript/warnings/"
const WARNING_SUFFIX: String = " (Warning treated as error.)"
const LEVEL_WARN: int = 1
const SKIPPED_ROOT_DIRS: Array[String] = ["addons"]
const RESOURCE_EXTENSIONS: Array[String] = ["tscn", "tres", "scn", "res"]
const UNSAFE_MARKER: String = "may be present on a subtype"
# Godot's warning messages, with the name of the warning each one comes from
# (debug/gdscript/warnings/<name>), in kebab-case. Godot reports a warning by its
# message only, so this is how a finding gets its code. Taken from Godot 4.7; a
# message from another version that matches none is reported without a code.
const WARNING_MESSAGES: Array[Array] = [
	["unassigned-variable", "The variable \"%s\" is used before being assigned a value."],
	["unassigned-variable-op-assign", "The variable \"%s\" is modified with the compound-assignment operator \"%s=\" but was not previously initialized."],
	["unused-variable", "The local variable \"%s\" is declared but never used in the block. If this is intended, prefix it with an underscore: \"_%s\"."],
	["unused-local-constant", "The local constant \"%s\" is declared but never used in the block. If this is intended, prefix it with an underscore: \"_%s\"."],
	["unused-private-class-variable", "The class variable \"%s\" is declared but never used in the class."],
	["unused-parameter", "The parameter \"%s\" is never used in the function \"%s()\". If this is intended, prefix it with an underscore: \"_%s\"."],
	["unused-signal", "The signal \"%s\" is declared but never explicitly used in the class."],
	["shadowed-variable", "The local %s \"%s\" is shadowing an already-declared %s at line %s in the current class."],
	["shadowed-variable-base-class", "The local %s \"%s\" is shadowing an already-declared %s at line %s in the base class \"%s\"."],
	["shadowed-variable-base-class", "The local %s \"%s\" is shadowing an already-declared %s in the base class \"%s\"."],
	["shadowed-global-identifier", "The %s \"%s\" has the same name as a %s."],
	["unreachable-code", "Unreachable code (statement after return) in function \"%s()\"."],
	["unreachable-pattern", "Unreachable pattern (pattern after wildcard or bind)."],
	["standalone-expression", "Standalone expression (the line may have no effect)."],
	["standalone-ternary", "Standalone ternary operator (the return value is being discarded)."],
	["incompatible-ternary", "Values of the ternary operator are not mutually compatible."],
	["untyped-declaration", "%s \"%s()\" has no static return type."],
	["untyped-declaration", "%s \"%s\" has no static type."],
	["inferred-declaration", "%s \"%s\" has an implicitly inferred static type."],
	["unsafe-property-access", "The property \"%s\" is not present on the inferred type \"%s\" (but may be present on a subtype)."],
	["unsafe-method-access", "The method \"%s()\" is not present on the inferred type \"%s\" (but may be present on a subtype)."],
	["unsafe-cast", "Casting \"Variant\" to \"%s\" is unsafe."],
	["unsafe-call-argument", "The argument %s of the %s \"%s()\" requires the subtype \"%s\" but the supertype \"%s\" was provided."],
	["unsafe-void-return", "The method \"%s()\" returns \"void\" but it's trying to return a call to \"%s()\" that can't be ensured to also be \"void\"."],
	["return-value-discarded", "The function \"%s()\" returns a value that will be discarded if not used."],
	["static-called-on-instance", "The function \"%s()\" is a static function but was called from an instance. Instead, it should be directly called from the type: \"%s.%s()\"."],
	["missing-tool", "The base class script has the \"@tool\" annotation, but this script does not have it."],
	["redundant-static-unload", "The \"@static_unload\" annotation is redundant because the file does not have a class with static variables."],
	["redundant-await", "\"await\" keyword is unnecessary because the expression isn't a coroutine nor a signal."],
	["missing-await", "\"await\" keyword might be desired because the expression is a coroutine."],
	["assert-always-true", "Assert statement is redundant because the expression is always true."],
	["assert-always-false", "Assert statement will raise an error because the expression is always false."],
	["integer-division", "Integer division. Decimal part will be discarded."],
	["narrowing-conversion", "Narrowing conversion (float is converted to int and loses precision)."],
	["int-as-enum-without-cast", "Integer used when an enum value is expected. If this is intended, cast the integer to the enum type using the \"as\" keyword."],
	["int-as-enum-without-match", "Cannot %s %s as Enum \"%s\": no enum member has matching value."],
	["enum-variable-without-default", "The variable \"%s\" has an enum type and does not set an explicit default value. The default will be set to \"0\"."],
	["empty-file", "Empty script file."],
	["deprecated-keyword", "The \"%s\" keyword is deprecated and will be removed in a future release. Please replace it with \"%s\"."],
	["confusable-identifier", "The identifier \"%s\" has misleading characters and might be confused with something else."],
	["confusable-local-declaration", "The %s \"%s\" is declared below in the parent block."],
	["confusable-local-usage", "The identifier \"%s\" will be shadowed below in the block."],
	["confusable-capture-reassignment", "Reassigning lambda capture does not modify the outer local variable \"%s\"."],
	["confusable-temporary-modification", "The built-in property \"%s\" will not be modified as a result of calling the method \"%s()\". Consider assigning the desired value to the property instead, or check the \"%s\" class for a specialized API."],
	["confusable-temporary-modification", "The built-in property \"%s\" will not be modified in the assignment chain. Consider using a temporary variable and assigning it back instead, or check the \"%s\" class for a specialized API."],
	["inference-on-variant", "The %s type is being inferred from a Variant value, so it will be typed as Variant."],
	["native-method-override", "The method \"%s()\" overrides a method from native class \"%s\". This won't be called by the engine and may not work as expected."],
	["get-node-default-without-onready", "The default value uses \"%s\" which won't return nodes in the scene tree before \"_ready()\" is called. Use the \"@onready\" annotation to solve this."],
	["onready-with-export", "\"@onready\" will set the default value after \"@export\" takes effect and will override it."],
]


class ErrorCollector extends Logger:
	var _mutex: Mutex = Mutex.new()
	var entries: Array[Dictionary] = []

	func _log_error(
		_function: String,
		file: String,
		line: int,
		code: String,
		rationale: String,
		_editor_notify: bool,
		error_type: int,
		_script_backtrace: Array[ScriptBacktrace]
	) -> void:
		if error_type != ERROR_TYPE_SCRIPT and error_type != ERROR_TYPE_SHADER:
			return
		_mutex.lock()
		entries.append({
			"file": file,
			"line": line,
			"message": rationale if rationale != "" else code,
			"is_shader": error_type == ERROR_TYPE_SHADER,
		})
		_mutex.unlock()


var _diagnostics: Array[Dictionary] = []
# [code, RegEx] for each of WARNING_MESSAGES, built when first needed.
var _warning_patterns: Array[Array] = []
var _seen: Dictionary = {}


func _init() -> void:
	var request_path: String = OS.get_cmdline_user_args()[0]
	var request: Dictionary = JSON.parse_string(FileAccess.get_file_as_string(request_path))

	var scripts: Array[String] = []
	var resources: Array[String] = []
	var shaders: Array[String] = []
	for target: String in request["targets"]:
		_collect_files(target, scripts, resources, shaders)

	var report_warnings: bool = request["pass"] == "warnings"

	var collector: ErrorCollector = ErrorCollector.new()
	OS.add_logger(collector)
	if not report_warnings:
		# Before the scripts: a shader they preload would compile only once.
		_check_shaders(shaders, collector)
	var unloadable: Array[String] = _load_scripts(scripts)
	OS.remove_logger(collector)
	_report_script_errors(collector.entries, unloadable, report_warnings)

	if not report_warnings:
		_check_string_references(scripts)
		_check_resources(resources)
		if request["whole_project"]:
			_check_project_settings()

	var output_path: String = request["output"]
	var output: FileAccess = FileAccess.open(output_path, FileAccess.WRITE)
	var _written: Variant = output.store_string(JSON.stringify({
		"files_checked": scripts.size(),
		"diagnostics": _diagnostics,
		"warning_settings": _warning_settings(),
	}))
	output.close()
	var _killed: Variant = OS.kill(OS.get_process_id())


func _collect_files(target: String, scripts: Array[String], resources: Array[String], shaders: Array[String]) -> void:
	if FileAccess.file_exists(target):
		if target.get_extension() == "gd":
			scripts.append(target)
		elif target.get_extension() in RESOURCE_EXTENSIONS:
			resources.append(target)
		elif target.get_extension() == "gdshader":
			shaders.append(target)
		return
	for dir_name: String in DirAccess.get_directories_at(target):
		var path: String = target.path_join(dir_name)
		if dir_name.begins_with(".") or (target == "res://" and dir_name in SKIPPED_ROOT_DIRS):
			continue
		# Like the editor, treat a folder with its own project.godot as another project.
		if not FileAccess.file_exists(path.path_join(".gdignore")) \
				and not FileAccess.file_exists(path.path_join("project.godot")):
			_collect_files(path, scripts, resources, shaders)
	for file_name: String in DirAccess.get_files_at(target):
		_collect_files(target.path_join(file_name), scripts, resources, shaders)


# The warnings set to "warn". Godot only reports warnings outside the editor when
# they are errors, and only reads these settings at startup, so the CLI promotes
# them through a temporary override.cfg and runs a second pass.
func _warning_settings() -> Array[String]:
	var settings: Array[String] = []
	for property: Dictionary in ProjectSettings.get_property_list():
		var name: String = property["name"]
		if name.begins_with(WARNINGS_PREFIX):
			var value: Variant = ProjectSettings.get_setting(name)
			if value is int and value == LEVEL_WARN:
				settings.append(name.trim_prefix("debug/"))
	return settings


# Shaders compile on first use, even with the dummy renderer of a headless run.
# Godot reports errors in the shader itself without a file, and errors in an
# included file with that file's path.
func _check_shaders(shaders: Array[String], collector: ErrorCollector) -> void:
	for path: String in shaders:
		if _has_missing_include(path):
			continue
		var shader: Shader = load(path) as Shader
		if shader == null:
			_add(path, 0, "error", "shader", "the shader could not be loaded", "shader-error")
			continue
		var _uniforms: Variant = shader.get_shader_uniform_list()
		for entry: Dictionary in collector.entries:
			if entry["is_shader"]:
				var file: String = entry["file"]
				var line: int = entry["line"]
				var message: String = entry["message"]
				_add(file if file != "" else path, line, "error", "shader", message, "shader-error")
		collector.entries.clear()


# Godot reports a missing include as an unknown character at the "#", so it is
# looked for first to report the actual cause.
func _has_missing_include(path: String) -> bool:
	var pattern: RegEx = RegEx.create_from_string("^\\s*#include\\s+\"([^\"]+)\"")
	var lines: PackedStringArray = FileAccess.get_file_as_string(path).split("\n")
	var is_missing: bool = false
	for index: int in lines.size():
		var found: RegExMatch = pattern.search(lines[index])
		if found != null:
			var include: String = found.get_string(1)
			var resolved: String = include if include.begins_with("res://") else path.get_base_dir().path_join(include)
			if not _resource_exists(resolved):
				_add(path, index + 1, "error", "missing-resource", "\"%s\" does not exist" % include)
				is_missing = true
	return is_missing


func _load_scripts(scripts: Array[String]) -> Array[String]:
	var unloadable: Array[String] = []
	for path: String in scripts:
		var script: GDScript = load(path) as GDScript
		if script == null or not script.can_instantiate():
			unloadable.append(path)
	return unloadable


func _report_script_errors(entries: Array[Dictionary], unloadable: Array[String], report_warnings: bool) -> void:
	var autoloads: Dictionary = _autoload_names()
	var explained: Dictionary = {}
	for entry: Dictionary in entries:
		if entry["is_shader"]:
			continue
		var message: String = entry["message"]
		var file: String = entry["file"]
		var line: int = entry["line"]
		explained[file] = true
		# The failure this refers to is reported on the script that caused it.
		if message.ends_with("Failed to compile depended scripts."):
			continue
		# Autoloads are not created yet, so the compile stage cannot find them.
		# The analyzer, which runs first, has already checked their use.
		if _is_missing_autoload_error(message, autoloads):
			continue
		var is_warning: bool = message.ends_with(WARNING_SUFFIX)
		message = message.trim_prefix("Parse Error: ").trim_prefix("Compile Error: ").trim_suffix(WARNING_SUFFIX)
		var code: String = _warning_code(message) if is_warning else ""
		if not report_warnings:
			# Warnings seen here are the ones the project itself set to "error".
			# Godot gives its errors no names, and calls type errors "Parse Error"
			# too, so they all get one code.
			if not is_warning:
				code = "gdscript-error"
			_add(file, line, "error", "gdscript", message, code)
		elif not is_warning:
			continue
		elif UNSAFE_MARKER in message:
			if _names_project_class(message):
				_add(file, line, "warning", "unsafe-access", message)
		else:
			_add(file, line, "warning", "gdscript-warning", message, code)
	if report_warnings:
		return
	for path: String in unloadable:
		if not explained.has(path):
			_add(path, 0, "error", "gdscript", "the script could not be loaded", "load-error")


# Calling something Node or Variant does not declare is everyday dynamic GDScript,
# so it says little. On one of the project's own classes, it is usually a mistake.
func _names_project_class(message: String) -> bool:
	const PREFIX: String = "inferred type \""
	var start: int = message.find(PREFIX)
	if start == -1:
		return false
	var type: String = message.substr(start + PREFIX.length()).get_slice("\"", 0)
	return type != "Variant" and not ClassDB.class_exists(type)


func _is_missing_autoload_error(message: String, autoloads: Dictionary) -> bool:
	const PREFIX: String = "Compile Error: Identifier not found: "
	return message.begins_with(PREFIX) and autoloads.has(message.trim_prefix(PREFIX).strip_edges())


func _autoload_names() -> Dictionary:
	var names: Dictionary = {}
	for property: Dictionary in ProjectSettings.get_property_list():
		var name: String = property["name"]
		if name.begins_with("autoload/"):
			names[name.trim_prefix("autoload/")] = true
	return names


# A load() of a literal path only fails when the line runs, so the compiler says
# nothing about it.
func _check_string_references(scripts: Array[String]) -> void:
	var pattern: RegEx = RegEx.create_from_string(
		"\\b(?:load|change_scene_to_file|ResourceLoader\\.load)\\(\\s*\"(res://[^\"]+)\""
	)
	for path: String in scripts:
		var lines: PackedStringArray = FileAccess.get_file_as_string(path).split("\n")
		for index: int in lines.size():
			var line: String = lines[index]
			var comment: int = line.find("#")
			for found: RegExMatch in pattern.search_all(line):
				if comment != -1 and comment < found.get_start():
					continue
				if not _resource_exists(found.get_string(1)):
					_add(path, index + 1, "error", "missing-resource", "\"%s\" does not exist" % found.get_string(1))


func _check_resources(resources: Array[String]) -> void:
	for path: String in resources:
		for dependency: String in ResourceLoader.get_dependencies(path):
			# Entries look like "uid://abc::Type::res://path" or just a path.
			var target: String = dependency.get_slice("::", 2) if "::" in dependency else dependency
			# A UID that still resolves wins over the path saved next to it, which
			# goes stale when a file moves.
			var uid: String = dependency.get_slice("::", 0) if "::" in dependency else ""
			if uid.begins_with("uid://") and _resource_exists(uid):
				continue
			if target != "" and not _resource_exists(target):
				_add(path, 0, "error", "missing-resource", "references \"%s\", which does not exist" % target)


func _check_project_settings() -> void:
	for property: Dictionary in ProjectSettings.get_property_list():
		var name: String = property["name"]
		if name.begins_with("autoload/"):
			var target: String = str(ProjectSettings.get_setting(name)).trim_prefix("*")
			if not _resource_exists(target):
				_add("res://project.godot", 0, "error", "missing-resource",
					"autoload %s points to \"%s\", which does not exist" % [name.trim_prefix("autoload/"), target])
	var main_scene: String = ProjectSettings.get_setting("application/run/main_scene", "")
	if main_scene != "" and not _resource_exists(main_scene):
		_add("res://project.godot", 0, "error", "missing-resource",
			"main scene \"%s\" does not exist" % main_scene)


func _resource_exists(path: String) -> bool:
	if path.begins_with("uid://"):
		return ResourceUID.has_id(ResourceUID.text_to_id(path))
	return FileAccess.file_exists(path) or ResourceLoader.exists(path)


func _add(file: String, line: int, severity: String, rule: String, message: String, code: String = "") -> void:
	# Godot often explains one mistake twice on the same line.
	var key: String = "%s:%d:%s" % [file, line, rule if rule != "missing-resource" else message]
	if not _seen.has(key):
		_seen[key] = true
		var diagnostic: Dictionary = {
			"file": file, "line": line, "severity": severity, "rule": rule, "message": message,
		}
		if code != "":
			diagnostic["code"] = code
		_diagnostics.append(diagnostic)


# The name of the Godot warning `message` comes from, or "" when it is unknown.
func _warning_code(message: String) -> String:
	if _warning_patterns.is_empty():
		for pair: Array in WARNING_MESSAGES:
			var code: String = pair[0]
			var template: String = pair[1]
			_warning_patterns.append([code, RegEx.create_from_string(_pattern(template))])
	for pair: Array in _warning_patterns:
		var code: String = pair[0]
		var regex: RegEx = pair[1]
		if regex.search(message) != null:
			return code
	return ""


# A regular expression matching a message made from `template`, whose "%s" can
# be anything.
func _pattern(template: String) -> String:
	var escaped: String = ""
	for index: int in template.length():
		var character: String = template[index]
		escaped += "\\" + character if character in "\\^$.|?*+()[]{}" else character
	return "^" + escaped.replace("%s", ".*?") + "$"