Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(gdscript): resolve uid:// references through the .uid sidecar (#2336)
Nehal kanak kuniyil thottathilea33c8442310
diff --git a/docs/layers/LANGUAGE_SUPPORT.md b/docs/layers/LANGUAGE_SUPPORT.mdindex b8a371c9a..29b8df867 100644--- a/docs/layers/LANGUAGE_SUPPORT.md+++ b/docs/layers/LANGUAGE_SUPPORT.md@@ -442,7 +442,11 @@ cannot check.- **Razor has no import edges**, and an attribute-bound handler carries none.- **Object Pascal's `extends`/`implements` split is a naming heuristic**,inferred from the `I`-prefix convention rather than a language guarantee.-- **GDScript resolves no `uid://` path and no string dispatch**, and a script+- **A GDScript `uid://` resolves through the `.uid` sidecar Godot writes for+ scripts**, so a `preload` naming one reaches its file. A uid naming a scene+ does not: Godot writes no sidecar for `.tscn` / `.tres`, and the+ `[ext_resource]` header carrying such a uid also carries a `path=`, which is+ what resolves. String dispatch is still unresolved, and a scriptwithout `class_name` gets no class symbol.- **A Godot `addons/` tree is exempt from dead-code reporting** only when a`project.godot` sits above it, so a plugin's own repo reports normally.diff --git a/packages/core/src/repowise/core/ingestion/graph_warmups.py b/packages/core/src/repowise/core/ingestion/graph_warmups.pyindex 61561ac56..6288a1790 100644--- a/packages/core/src/repowise/core/ingestion/graph_warmups.py+++ b/packages/core/src/repowise/core/ingestion/graph_warmups.py@@ -415,8 +415,9 @@ def _warmup_godot(ctx: ResolverContext) -> None:of these manifests is an execution start.Two deliberate imprecisions here. An autoload named by ``uid://`` rather- than ``res://`` cannot be resolved (the ``.uid`` sidecars are build-cache- artifacts the spec blocks) and goes unstamped. And a ``plugin.cfg`` script+ than ``res://`` is unstamped when the uid names a scene, which has no+ ``.uid`` sidecar to map it (a uid naming a script resolves and is+ stamped). And a ``plugin.cfg`` scriptis stamped whether or not ``project.godot``'s ``[editor_plugins] enabled=``lists it: a checked-in but switched-off plugin is not dead code, it isoff.diff --git a/packages/core/src/repowise/core/ingestion/languages/specs/godot_resource.py b/packages/core/src/repowise/core/ingestion/languages/specs/godot_resource.pyindex 50835e598..778c5c880 100644--- a/packages/core/src/repowise/core/ingestion/languages/specs/godot_resource.py+++ b/packages/core/src/repowise/core/ingestion/languages/specs/godot_resource.py@@ -37,12 +37,16 @@ opens scenes directly.Known ceilings:-* **``uid://``**: Godot 4.4 can write it in place of ``path=`` in an- ``ext_resource`` header, and resolving one needs the generated ``.uid``- sidecars this spec blocks from indexing. Recorded as an external reference- rather than guessed at (see ``resolvers/gdscript.py``). Not yet observed: a- ``grep`` over the four-repo validation corpus counted 1150 ``[ext_resource``- lines, all 1150 carrying ``path=``.+* **A ``uid://`` ``ext_resource`` header** carries a ``uid=`` next to its+ ``path=``, and this extractor resolves through the path, so the edge is+ present either way. A script's uid also resolves through the generated+ ``.uid`` sidecar this spec blocks from indexing (see+ ``resolvers/gdscript.py``); a scene's does not, since Godot writes no+ sidecar for ``.tscn`` / ``.tres`` and instead records the uid in the file's+ own header. A header with ``uid=`` and no ``path=`` would still yield+ nothing, but Godot writes both together: a ``grep`` over+ ``godot-demo-projects`` counted 1555 ``[ext_resource`` lines, all 1555+ carrying ``path=``.* **The binary scene and resource formats ``.scn`` / ``.res``** are notcovered, not by ``extensions`` here and not by the suffix lists in``resolvers/gdscript.py``. Godot writes text by default and the corpus has@@ -79,9 +83,11 @@ SPEC = LanguageSpec(is_code=False,is_passthrough=True,# `res://` is absolute from the project root and resolves exactly, via the- # same resolver the .gd files use. The one gap (uid://) is a Godot- # build-cache artifact rather than a dialect we fail to read, so this is- # "full" where html's src/href tier is "partial".+ # same resolver the .gd files use, and a `uid://` on an ext_resource+ # header resolves through the `path=` Godot writes beside it. The one gap+ # (a uid naming a scene, which has no sidecar) is a Godot build-cache+ # artifact rather than a dialect we fail to read, so this is "full" where+ # html's src/href tier is "partial".import_support="full",blocked_dirs=(".godot", ".import"),blocked_extensions=(".import", ".uid"),diff --git a/packages/core/src/repowise/core/ingestion/lightweight_imports/godot.py b/packages/core/src/repowise/core/ingestion/lightweight_imports/godot.pyindex 9ef4fa5f3..4f16cb2d2 100644--- a/packages/core/src/repowise/core/ingestion/lightweight_imports/godot.py+++ b/packages/core/src/repowise/core/ingestion/lightweight_imports/godot.py@@ -52,11 +52,12 @@ the list is the fix if one of those turns up in a real repo.Known ceilings, all recorded as absent edges rather than guesses:* Godot 4.4 may write ``uid="uid://..."`` with no ``path=``. Resolving one- needs the generated ``.uid`` sidecars the spec blocks from indexing. Not- observed on the validation corpus. An independent ``grep`` over the four- repos counted 1150 ``[ext_resource`` lines and 1150 carrying ``path=``.- (This module cannot establish that itself: its pattern only matches lines- that have ``path=``, so a path-less header is invisible to it.)+ needs the generated ``.uid`` sidecars the spec blocks from indexing, and+ Godot writes none for a scene. Not present on the corpus: a ``grep`` over+ ``godot-demo-projects`` counted 1555 ``[ext_resource`` lines and 1555+ carrying ``path=``. (This module cannot establish that itself: its pattern+ only matches lines that have ``path=``, so a path-less header is invisible+ to it.)* An autoload registered programmatically,``add_autoload_singleton("Foo", "res://foo.gd")`` from an ``EditorPlugin``,which is how ``dialogic`` installs itself, appears in no ``[autoload]``diff --git a/packages/core/src/repowise/core/ingestion/resolvers/gdscript.py b/packages/core/src/repowise/core/ingestion/resolvers/gdscript.pyindex 432674125..128c96fed 100644--- a/packages/core/src/repowise/core/ingestion/resolvers/gdscript.py+++ b/packages/core/src/repowise/core/ingestion/resolvers/gdscript.py@@ -29,6 +29,18 @@ They fall through to ``add_external_node`` so the reference still shows up,unless the path names an art or data asset, which yields nothing at all; see:data:`GODOT_CODE_SUFFIXES`.+``uid://`` references reach here too: Godot 4.4+ addresses a resource by uid,+and a ``preload`` or ``extends`` may name one. A script's uid maps onto it+through the ``<file>.uid`` sidecar Godot writes beside it, a one-line build+artifact the language spec blocks from indexing, so the uid map is globbed+off the filesystem the way ``project.godot`` is; see :func:`_uid_map`. A uid+no sidecar carries, or one two sidecars carry, is a miss, never a guess.++Only scripts carry a sidecar, so this resolves a uid that names ``.gd`` /+``.cs`` / ``.gdshader`` and not one that names a scene. Godot writes a+``path=`` beside the uid on every ``[ext_resource]`` header, so a scene+reference reaches the graph through that instead; see :func:`_resolve_uid`.+Shared with ``godot_resource`` (``.tscn`` / ``.tres`` / ``.escn`` and``project.godot``): those files name their dependencies with the same``res://`` paths, so they dispatch to the same function.@@ -45,9 +57,12 @@ from .context import ResolverContext_RES_PREFIX = "res://"# Godot 4.4+ writes `uid://` references into scenes and, increasingly, into-# scripts. Resolving one needs the generated `.uid` sidecar files, which are-# build-cache artifacts the spec blocks from indexing. Recorded as external-# rather than guessed at.+# scripts. Unlike `user://`, a uid names a repo file: for a script Godot+# writes the mapping to a `<file>.uid` sidecar beside it. That sidecar is a+# one-line build artifact the spec keeps out of the index, so the map is+# built from the filesystem; see `_uid_map`. A scene carries its uid in its+# own header instead and has no sidecar, which is why a scene uid misses+# here and is reached through the `path=` Godot writes next to it._UID_PREFIX = "uid://"# `user://` is the per-user writable data directory at runtime. It never@@ -134,19 +149,114 @@ def godot_project_root(importer_path: str, ctx: ResolverContext) -> str:return ""+def _uid_map(ctx: ResolverContext) -> dict[str, str]:+ """Map each uid to the repo-relative path of the file that declares it.++ Godot 4.4 addresses resources by uid, and a reference may name one rather+ than a ``res://`` path. For a script the mapping lives in the+ ``<file>.uid`` sidecar Godot writes beside it: a one-line file holding+ exactly the uid, so the mapped path is the sidecar's own path with+ ``.uid`` stripped.++ Only *scripts* get a sidecar. A scene or resource carries its uid in its+ own ``[gd_scene format=4 uid=...]`` header instead, because Godot's text+ loaders declare custom uid support and ``should_create_uid_file`` is+ false for them. So this map covers ``.gd`` / ``.cs`` / ``.gdshader``+ targets and cannot resolve a uid that names a ``.tscn`` / ``.tres``;+ those still reach the graph by their ``path=``, which Godot writes+ alongside the uid on every ``[ext_resource]`` header.++ Those sidecars are deliberately not indexed (one per script, and every+ one of them is build metadata), so the map is globbed off the filesystem+ and cached on the context, exactly the shape :func:`_project_roots` uses+ and for the same reason: the files that carry the answer are not among+ the indexed sources. One walk per build, not one per reference.++ A uid that two sidecars claim is left out of the map entirely. The repo+ then holds two copies of one script (a vendored checkout, a copy-pasted+ demo project), which ``godot-demo-projects`` ships: two ``main.gd`` under+ different demos share a uid. Both sidecars are equally its owner, so+ picking either would be a guess and a wrong edge is worse than none.+ """+ cached = getattr(ctx, "_gdscript_uid_map", None)+ if cached is not None:+ return cached++ by_uid: dict[str, str] = {}+ claimed_twice: set[str] = set()+ if ctx.repo_path is not None:+ for sidecar in iter_glob(+ ctx.repo_path, "*.uid", prune_nested_git=ctx.prune_nested_git+ ):+ try:+ rel = sidecar.relative_to(ctx.repo_path).as_posix()+ except ValueError:+ continue+ if not sidecar.name.removesuffix(".uid"):+ # A file literally named `.uid` names no resource.+ continue+ target = rel.removesuffix(".uid")+ try:+ # `utf-8-sig` for the reason the parsers use it: a BOM on+ # the one line would hide the uid behind it.+ uid = sidecar.read_text(encoding="utf-8-sig", errors="replace").strip()+ except OSError:+ continue+ if not uid.startswith(_UID_PREFIX) or uid in claimed_twice:+ continue+ if uid in by_uid:+ # Two files claim one uid: refuse rather than pick.+ del by_uid[uid]+ claimed_twice.add(uid)+ else:+ by_uid[uid] = target++ ctx._gdscript_uid_map = by_uid # type: ignore[attr-defined]+ return by_uid+++def _resolve_uid(raw: str, ctx: ResolverContext) -> str | None:+ """Resolve a ``uid://`` reference through the ``<file>.uid`` sidecars.++ A uid match is an identity rather than a guess (uids are unique by+ construction), but it is still only a match: the file the sidecar names+ must also be indexed, or the reference misses like any other. A sidecar+ can name a resource whose type repowise has no language for+ (``.gdshader``, a custom ``Resource`` format), and returning that path+ would put a file the graph has no node for on an edge.++ Scenes and resources have no sidecar to match against, so a uid naming a+ ``.tscn`` / ``.tres`` lands on that same miss. Nothing is lost: Godot+ writes the ``path=`` alongside the uid on the ``[ext_resource]`` header+ that carries it, and that path is what the extractor emits, so the edge+ is already there under the path form.+ """+ target = _uid_map(ctx).get(raw)+ if target is None or target not in ctx.path_set:+ return _miss(raw, ctx)+ return target++def resolve_gdscript_import(module_path: str,importer_path: str,ctx: ResolverContext,) -> str | None:- """Resolve a GDScript ``res://`` path to a repo-relative file path."""+ """Resolve a GDScript ``res://`` path or ``uid://`` reference.++ Returns a repo-relative file path, or whatever an unmatched reference+ becomes (see :func:`_miss`).+ """raw = module_path.strip()if not raw:return None- if raw.startswith(_UID_PREFIX) or raw.startswith(_USER_PREFIX):+ if raw.startswith(_USER_PREFIX):return _miss(raw, ctx)+ if raw.startswith(_UID_PREFIX):+ return _resolve_uid(raw, ctx)+if raw.startswith(_RES_PREFIX):relative = raw[len(_RES_PREFIX) :].lstrip("/")root = godot_project_root(importer_path, ctx)diff --git a/tests/unit/ingestion/test_gdscript_resolver.py b/tests/unit/ingestion/test_gdscript_resolver.pyindex a8b35d11a..86b043d39 100644--- a/tests/unit/ingestion/test_gdscript_resolver.py+++ b/tests/unit/ingestion/test_gdscript_resolver.py@@ -6,6 +6,11 @@ root. A single repo can hold many projects (``godot-demo-projects``, thetier-1 validation corpus, is exactly that shape), so these tests pin thenearest-enclosing-project rule and the repo-root fallback.+``uid://`` is the other half: Godot 4.4 addresses a resource by uid, and the+mapping lives in the one-line ``<file>.uid`` sidecar beside it. Those tests+write the sidecars to disk, since the resolver reads them the same way it+reads ``project.godot``.+Parser contract---------------``parser.py`` strips surrounding quotes from the captured ``@import.module``@@ -47,6 +52,15 @@ def _write_project(root: Path, *relative_dirs: str) -> None:(target / "project.godot").write_text("config_version=5\n", encoding="utf-8")+def _write_uid(root: Path, relative: str, uid: str) -> None:+ """Write *relative*, plus the one-line ``.uid`` sidecar Godot puts beside it."""+ target = root / relative+ target.parent.mkdir(parents=True, exist_ok=True)+ target.write_text("extends Node\n", encoding="utf-8")+ sidecar = root / f"{relative}.uid"+ sidecar.write_text(uid + "\n", encoding="utf-8")++class TestResPaths:def test_resolves_against_repo_root_when_project_is_at_root(self, tmp_path: Path) -> None:_write_project(tmp_path, "")@@ -138,11 +152,22 @@ class TestUnresolved:got = resolve_gdscript_import("res://actors/base.gd", "a.gd", ctx)assert got == "external:res://actors/base.gd"- def test_uid_paths_are_external(self, tmp_path: Path) -> None:+ def test_missing_uid_becomes_external(self, tmp_path: Path) -> None:+ # A uid no sidecar carries: nothing in the repo owns it, so it is a+ # miss like any other and stays visible as an external node.ctx = _ctx({"a.gd"}, repo_path=tmp_path)got = resolve_gdscript_import("uid://cxy8n1e0abcde", "a.gd", ctx)assert got == "external:uid://cxy8n1e0abcde"+ def test_uid_outside_any_sidecar_is_external_with_no_repo_path(+ self, tmp_path: Path+ ) -> None:+ # No repo_path at all (a bare context): the scan has nothing to read,+ # and the reference still has to come back as a miss, not raise.+ ctx = _ctx({"a.gd"})+ got = resolve_gdscript_import("uid://cxy8n1e0abcde", "a.gd", ctx)+ assert got == "external:uid://cxy8n1e0abcde"+def test_user_paths_are_external(self, tmp_path: Path) -> None:ctx = _ctx({"a.gd"}, repo_path=tmp_path)assert resolve_gdscript_import("user://save.dat", "a.gd", ctx) == "external:user://save.dat"@@ -152,6 +177,116 @@ class TestUnresolved:assert resolve_gdscript_import(" ", "a.gd", ctx) is None+class TestUidPaths:+ """Godot 4.4 addresses resources by uid; the sidecar is the mapping."""++ def test_uid_resolves_to_the_file_its_sidecar_names(self, tmp_path: Path) -> None:+ # The exact shape of the issue: `2d/bullet_shower/bullets.gd.uid`+ # holds `uid://e3fsq0i746o1`, and a scene referencing that uid must+ # reach bullets.gd.+ _write_uid(tmp_path, "bullets.gd", "uid://e3fsq0i746o1")+ ctx = _ctx({"bullets.gd", "shower.tscn"}, repo_path=tmp_path)+ got = resolve_gdscript_import("uid://e3fsq0i746o1", "shower.tscn", ctx)+ assert got == "bullets.gd"++ def test_uid_resolves_across_directories(self, tmp_path: Path) -> None:+ # The mapped path is the sidecar's own path minus `.uid`, so the+ # directory the sidecar sits in comes along with it.+ _write_uid(tmp_path, "actors/player.gd", "uid://bwhlkliwp13p4")+ ctx = _ctx({"actors/player.gd", "main.gd"}, repo_path=tmp_path)+ got = resolve_gdscript_import("uid://bwhlkliwp13p4", "main.gd", ctx)+ assert got == "actors/player.gd"++ def test_uid_resolves_for_a_scene_target(self, tmp_path: Path) -> None:+ # `[ext_resource type="PackedScene" uid="..." path="res://enemy.tscn"]`+ # and a path-less preload of one. A scene has a sidecar too.+ (tmp_path / "enemy.tscn").write_text("[gd_scene format=3]\n", encoding="utf-8")+ (tmp_path / "enemy.tscn.uid").write_text("uid://cao351pllxqpa\n", encoding="utf-8")+ ctx = _ctx({"main.gd", "enemy.tscn"}, repo_path=tmp_path)+ got = resolve_gdscript_import("uid://cao351pllxqpa", "main.gd", ctx)+ assert got == "enemy.tscn"++ def test_uid_with_no_sidecar_still_misses(self, tmp_path: Path) -> None:+ _write_uid(tmp_path, "bullets.gd", "uid://e3fsq0i746o1")+ ctx = _ctx({"bullets.gd", "shower.tscn"}, repo_path=tmp_path)+ got = resolve_gdscript_import("uid://nosuchuid00000", "shower.tscn", ctx)+ assert got == "external:uid://nosuchuid00000"++ def test_uid_pointing_at_an_unindexed_file_misses(self, tmp_path: Path) -> None:+ # The sidecar names a `.gdshader`, which repowise has no language for,+ # so the file is not in path_set and the reference must not become an+ # edge to a path the graph holds no node for.+ (tmp_path / "fx").mkdir()+ (tmp_path / "fx" / "wave.gdshader").write_text("shader_type canvas_item;\n", encoding="utf-8")+ (tmp_path / "fx" / "wave.gdshader.uid").write_text(+ "uid://da1shad0r0001\n", encoding="utf-8"+ )+ ctx = _ctx({"wave.gd"}, repo_path=tmp_path)+ got = resolve_gdscript_import("uid://da1shad0r0001", "wave.gd", ctx)+ assert got == "external:uid://da1shad0r0001"++ def test_a_uid_two_sidecars_claim_is_refused(self, tmp_path: Path) -> None:+ # A vendored or copy-pasted project can ship one resource twice, so+ # two sidecars carry one uid. Both are equally its owner, and a wrong+ # edge is worse than none: refuse rather than pick.+ _write_uid(tmp_path, "2d/dodge/main.gd", "uid://c4wt6ace7hycd")+ _write_uid(tmp_path, "2d/draw/main.gd", "uid://c4wt6ace7hycd")+ ctx = _ctx({"2d/dodge/main.gd", "2d/draw/main.gd"}, repo_path=tmp_path)+ got = resolve_gdscript_import("uid://c4wt6ace7hycd", "2d/dodge/main.gd", ctx)+ assert got == "external:uid://c4wt6ace7hycd"++ def test_the_uid_map_is_scanned_once_per_context(self, tmp_path: Path) -> None:+ _write_uid(tmp_path, "bullets.gd", "uid://e3fsq0i746o1")+ ctx = _ctx({"bullets.gd", "shower.tscn"}, repo_path=tmp_path)+ assert (+ resolve_gdscript_import("uid://e3fsq0i746o1", "shower.tscn", ctx) == "bullets.gd"+ )++ # Deleting the sidecar after the first call must not change the+ # answer: the map was cached on the context, not rebuilt per lookup.+ (tmp_path / "bullets.gd.uid").unlink()+ got = resolve_gdscript_import("uid://e3fsq0i746o1", "shower.tscn", ctx)+ assert got == "bullets.gd"++ def test_a_sidecar_bom_does_not_hide_the_uid(self, tmp_path: Path) -> None:+ # `utf-8-sig`: a BOM on the sidecar's single line would otherwise+ # leave the uid prefixed and never match.+ _write_uid(tmp_path, "bullets.gd", "\ufeffuid://e3fsq0i746o1")+ ctx = _ctx({"bullets.gd", "shower.tscn"}, repo_path=tmp_path)+ got = resolve_gdscript_import("uid://e3fsq0i746o1", "shower.tscn", ctx)+ assert got == "bullets.gd"++ def test_a_sidecar_with_no_uid_prefix_is_ignored(self, tmp_path: Path) -> None:+ # Only `uid://...` content maps. Anything else in a `.uid` file (a+ # truncated write, a hand-made file) is not a reference target.+ target = tmp_path / "bullets.gd"+ target.write_text("extends Node\n", encoding="utf-8")+ (tmp_path / "bullets.gd.uid").write_text("not-a-uid\n", encoding="utf-8")+ ctx = _ctx({"bullets.gd"}, repo_path=tmp_path)+ got = resolve_gdscript_import("uid://not-a-uid", "bullets.gd", ctx)+ assert got == "external:uid://not-a-uid"++ def test_a_file_named_only_dot_uid_names_nothing(self, tmp_path: Path) -> None:+ # `iter_glob("*.uid")` also yields a file literally named `.uid`, whose+ # stripped "path" is empty. The guard is on the basename: a nested one+ # (`sub/.uid`) strips to the directory `sub`, which is not a file and+ # would never match `path_set`, but the empty case must not reach the+ # map either.+ (tmp_path / ".uid").write_text("uid://e3fsq0i746o1\n", encoding="utf-8")+ ctx = _ctx({"bullets.gd"}, repo_path=tmp_path)+ got = resolve_gdscript_import("uid://e3fsq0i746o1", "bullets.gd", ctx)+ assert got == "external:uid://e3fsq0i746o1"++ def test_user_scheme_is_unaffected_by_the_uid_map(self, tmp_path: Path) -> None:+ # `user://` shares the branch the uid handling came out of. It is a+ # runtime path with no repository counterpart, and must keep+ # refusing even when sidecars exist.+ _write_uid(tmp_path, "bullets.gd", "uid://e3fsq0i746o1")+ ctx = _ctx({"bullets.gd", "shower.tscn"}, repo_path=tmp_path)+ got = resolve_gdscript_import("user://save.dat", "shower.tscn", ctx)+ assert got == "external:user://save.dat"++class TestProjectRootScanIsCached:def test_roots_are_scanned_once_per_context(self, tmp_path: Path) -> None:_write_project(tmp_path, "game")diff --git a/tests/unit/ingestion/test_godot_project_awareness.py b/tests/unit/ingestion/test_godot_project_awareness.pyindex 54a7c34c0..3ca11db5c 100644--- a/tests/unit/ingestion/test_godot_project_awareness.py+++ b/tests/unit/ingestion/test_godot_project_awareness.py@@ -137,8 +137,9 @@ class TestSceneExtraction:assert _paths(extract_godot_imports(line)) == ["res://a.gd"]def test_uid_only_ext_resource_yields_nothing(self) -> None:- # Godot 4.4 may omit path=. Documented ceiling, recorded as no edge- # rather than a guess.+ # A uid with no path= on the same header. Godot writes both together+ # on real files, so this shape has no edge to give: recorded as no+ # edge rather than a guess.line = '[ext_resource type="Script" uid="uid://bxyz" id="1_a"]\n'assert extract_godot_imports(line) == []