gdtypecheck 0.2.2

Report GDScript and shader compile errors and broken references in a Godot project, without running it
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"


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] = []
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")
			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)
		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)
		if not report_warnings:
			# Warnings seen here are the ones the project itself set to "error".
			_add(file, line, "error", "gdscript", message)
		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)
	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")


# 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) -> 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
		_diagnostics.append({
			"file": file, "line": line, "severity": severity, "rule": rule, "message": message,
		})