typescript-to-gdscript 0.1.0 → 0.1.2

package/README.md

@@ -4,8 +4,6 @@ Write Godot 4 scripts in TypeScript. Get autocomplete and type-checking for the
 
 ![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/convert.webp)
 
-> Have an existing GDScript project? Bulk-convert it to TypeScript with [tstogd initial-convert-gd-to-ts](docs/gd-to-ts-migration.md).
-
 ## Why
 
 GDScript is great for getting things on screen, but its type system and tooling are intentionally lightweight. The bigger a project gets, the more that costs you: typos surface at runtime, refactors are risky, and autocomplete only goes so far. TypeScript was built for exactly this problem, and it has had a decade of investment poured into making large codebases safe to change.
@@ -24,13 +22,55 @@ The output is clean, idiomatic `.gd` you can read and ship — TypeScript is the
 
 - **Type-safe Godot API** — all 900+ engine classes generated as `.d.ts` from the official Godot XML docs, with nullable reference types where appropriate
 - **Live IDE diagnostics** — TypeScript language service plugin surfaces converter and Godot CLI errors as squiggles, on unsaved buffers
-- **Watch mode** — auto-convert on save, then run a debounced full-project check (TypeScript + converter + Godot CLI)
+- **Watch mode** — auto-convert on save and keep typings in sync (it watches your `.tscn` scenes and assets too), then run a debounced full-project check (TypeScript + converter + Godot CLI)
 - **Source maps** — Godot script parse errors, runtime errors and stack traces map back to your TypeScript line/column
 - **Scene and path typings** — `get_node()`, `get_parent()`, `get_child()`, `load()`, `preload()` and group queries typed from your project files
 - **`gd` namespace** — strongly-typed helpers for GDScript-only constructs (signals, decorators, match, operator overloading)
 - **Addons supported** — typings for third-party GDScript addons, consumable from TypeScript
 - **GD → TS migration** — one-shot bulk converter for existing projects
 
+### Showcase
+
+<details>
+<summary>Scene and path type hints</summary>
+
+Given this scene structure:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_scene.png)
+
+You get type hints for this:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_hint_1.png)
+
+…or this:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_hint_2.png)
+
+…or even this:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_hint_3.png)
+
+`preload()` is typed too:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_preload.png)
+
+</details>
+
+<details>
+<summary>GDScript and converter errors in TypeScript code</summary>
+
+GDScript doesn't allow a static and an instance member to share the same name — though TypeScript does. Your IDE surfaces the GDScript error at the exact spot in your `.ts`:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_gdscript_error.png)
+
+For edge cases — like using the result of `&&` as a value — you get a converter error instead, because logical operations in GDScript always return a boolean:
+
+![](https://raw.githubusercontent.com/nnn3d/typescript-to-gdscript/HEAD/docs/assets/showcase_converter_error.png)
+
+You also get all of these errors (along with the TypeScript errors themselves) from the `convert` CLI command.
+
+</details>
+
 ## Quick start
 
 ```bash
@@ -41,10 +81,12 @@ tstogd init # interactive: writes tstogd.json + tsconfig.json + installs typescr
 Then:
 
 1. Write a `.ts` class in your TS source dir (default `src/`).
-2. `tstogd convert` — emits `.gd` files into your output dir (default `scripts/`).
+2. `tstogd convert` — emits `.gd` into your output dir (default `scripts/`), regenerates all typings, and runs a full diagnostic check.
 3. Attach the `.gd` file in Godot as you normally would. Configure Godot's external editor to point at your IDE for TS language server and one-click jump-to-source ([guide](docs/ide-integration.md)).
 
-Use `tstogd watch` during development for auto-conversion plus live diagnostics.
+That's the whole loop — `convert` and `watch` are the only commands you need in normal use. Each one converts your code _and_ regenerates every typing (scene, script, resource, addon) in the same pass, so `get_node()` paths, `res://` references, and group queries stay in sync without any extra step. Most projects never run another CLI command.
+
+For day-to-day work, run **`tstogd watch`**: it auto-converts on save, watches your `.tscn` scenes and assets so scene typings refresh the instant you change the tree in Godot, and runs a debounced full-project check feeding live IDE diagnostics.
 
 ### Requirements
 
@@ -56,19 +98,32 @@ Use `tstogd watch` during development for auto-conversion plus live diagnostics.
 
 Setup `tstogd.json` and `tsconfig.json` in your project - for full template and field reference see [docs/configuration.md](docs/configuration.md).
 
+### Migration from existing GDScript
+
+Have an existing GDScript project? Bulk-convert it to TypeScript with [tstogd initial-convert-gd-to-ts](docs/gd-to-ts-migration.md).
+
 ## CLI
 
+In everyday use you only need these three:
+
+```bash
+tstogd init                # one-time interactive scaffold (tsconfig + tstogd.json + ts-plugin)
+tstogd convert             # convert TS → GD + regenerate all typings + full diagnostic check
+tstogd watch               # the same, continuously: auto-convert on save, live diagnostics
+```
+
+> **Note:** `watch` self-heals — when an edit causes new errors in other files, those files are reconverted automatically. For a guaranteed full refresh of every `.gd`, run `tstogd convert` after a `watch` session.
+
+`convert` and `watch` already regenerate every typing (scene, script, resource, addon) as part of the run — there is no separate "generate typings" step to remember. The commands below cover one-off or advanced situations, and most projects never touch them:
+
 ```bash
-tstogd init                # interactive scaffold (tsconfig + tstogd.json + ts-plugin)
-tstogd convert             # convert TS → GD (cached, with diagnostic check)
-tstogd watch               # auto-convert on change + debounced full check
-tstogd generate-typings    # generate scene + script typings
-tstogd clear-cache         # clear conversion cache
+tstogd generate-typings    # regenerate typings standalone (convert/watch do this for you)
+tstogd clear-cache         # clear the conversion cache (e.g. after upgrading the converter)
 ```
 
 Full reference in [docs/cli.md](docs/cli.md). Specialized commands:
 
-- [`initial-convert-gd-to-ts`](docs/gd-to-ts-migration.md) — bulk migration of an existing GDScript project to TypeScript
+- [`initial-convert-gd-to-ts`](docs/gd-to-ts-migration.md) — one-shot bulk migration of an existing GDScript project to TypeScript
 - [`generate-gdscript-global-typings`](docs/typings.md#tstogd-generate-gdscript-global-typings), [`generate-addon-typings`](docs/typings.md#tstogd-generate-addon-typings) — typings generation
 - [`open-editor`](docs/ide-integration.md#tstogd-open-editor) — Godot external-editor integration
 
@@ -84,125 +139,116 @@ Each `.ts` file must contain exactly one class. Named classes (`class Foo`) are
 - `bool` — alias for `boolean`, also a cast: `bool(x)` → GDScript `bool(x)`. Same for `String(x)`.
 - `Dictionary<K, V>` — generic, with typed `get` / `set` / `keys` / `values`. `{}` literals keep dictionary methods via the `Object` interface. Untyped `Dictionary` is `<unknown, unknown>`.
 - `let` and `const` both convert to GDScript `var`. **Use `let`** — TS `var` is restricted (GDScript `var` ≈ TS `let`, not TS `var`).
-- `undefined` is restricted — use `null`. Optional property access (`obj.foo` where the type includes `undefined`) auto-converts to `obj.get("foo")`. Same for `obj["key"]` with an undefined type. Class-field access stays direct.
+- `undefined` is restricted — use `null`. Plain objects (interfaces, object literals) are Dictionaries in GDScript: member reads convert to `obj.get("foo")`, which returns `null` for a missing key instead of crashing. Writes and class-instance access stay direct.
 - `TSOnly<T>` — type-level wrapper, stripped at conversion.
+- Only types GDScript actually has get an annotation. Godot classes/value types and your own `class_name` classes (including ones imported from another file) keep their type; plain `interface`s, `object`, `type` aliases, and unknown/unresolved names have the annotation **omitted** (bare untyped `var x` / `func f(x)`) rather than emitting a bogus GD type. See [docs/transform-rules.md#type-annotations--what-gets-emitted](docs/transform-rules.md#type-annotations--what-gets-emitted).
 
 For comments, async, `this` / `self`, logical operators, and constructor mapping, see [docs/transform-rules.md](docs/transform-rules.md).
 
 ## Cheat sheet
 
-Cheat sheet with all basics to write scripts, with comments showing the generated GDScript. For advanced helpers and deep dive, see the [**full cheat sheet** in docs/transform-rules.md](docs/transform-rules.md#full-cheat-sheet).
+Basics for writing scripts For advanced helpers and the deep dive, see the [**full cheat sheet** in docs/transform-rules.md](docs/transform-rules.md#full-cheat-sheet).
 
 ```typescript
-// ── Inner classes, class-level constants & enums (namespace merging) ──
-// A `namespace Player { ... }` block paired with the same-named class
-// lifts each `export`ed member into the class as a nested member.
-// Put constants and enums INSIDE the namespace — that's how GD
-// class-level `const` and `enum` are declared.
+// Use imports instead of global classes for better DX
+// Can be changed by `converterOptions.generateGlobalClassTypes` config option
+import { PlayerSprite, type PlayerSpriteState } from './PlayerSprite';
+
+// Inner classes, class-level constants & enums.
+// A `namespace Player` merged with class `Player`
+// lifts each exported member onto the class.
 export namespace Player {
-  export const MAX_HP = 100; // → const MAX_HP = 100   (on Player)
+  export const MAX_HP = 100;
 
   export enum State {
     IDLE,
     RUNNING,
-  } // → enum State { ... }   (on Player)
+  }
 
   export class Bullet extends Node2D {
-    // → class Bullet extends Node2D:
-    damage: int = 10; //       var damage: int = 10
+    damage: int = 10;
   }
 }
 
 export class Player extends CharacterBody2D {
-  // ── Statics (mutable) — for constants, use the namespace block above ──
-  static MAX_INSTANCES = 8; // → static var MAX_INSTANCES = 8
-  // `readonly` is a TS-only contract — emits a plain `var` on GD.
-
-  // ── Field decorators ─────────────────────────────────────────────
-  // Every Godot annotation works as a decorator.
-  // `@exports` is the only special alias:
-  // `@export` is a TS reserved word, so the plural form emits
-  @exports speed: float = 200.0; // → @export var speed: float = 200.0
-  @export_range(0, 100) health: int = 100; // → @export_range(0, 100) var health: int = 100
-  @onready sprite: Sprite2D; // → @onready var sprite: Sprite2D
-
-  // ── Signals — named tuple labels become GD arg names ─────────────
-  health_changed = gd.signal<[from: int, to: int]>(); // → signal health_changed(from: int, to: int)
-  died = gd.signal(); // → signal died
-
-  // ── Constructor → _init ──────────────────────────────────────────
+  // Statics (mutable); for constants use the namespace
+  static MAX_INSTANCES = 8;
+
+  // Field decorators. `@exports` aliases `@export`
+  // (a TS reserved word); other annotations are 1:1
+  @exports speed: float = 200.0;
+  @export_range(0, 100) health: int = 100;
+  @onready sprite: PlayerSprite = this.get_node('Sprite');
+  @onready sprite_state: PlayerSpriteState = this.sprite.get_state();
+
+  // Signals; tuple labels become GD arg names
+  health_changed = gd.signal<[from: int, to: int]>();
+  died = gd.signal();
+
+  // Constructor replaces _init
   constructor(speed: float = 200.0) {
-    // → func _init(speed: float = 200.0):
-    this.speed = speed; //       self.speed = speed
+    this.speed = speed;
   }
 
-  // ── Getters / setters — native TS accessors ──────────────────────
+  // Getters / setters (native TS accessors)
   get score(): int {
     return this.score;
-  } // → var score: int:
+  }
   set score(v: int) {
     this.score = v;
-  } //       get: return score
-  //       set(value): score = value
+  }
 
-  // ── Async / await — Promise<T> unwraps to T on the GD side ───────
+  // Async / await; Promise<T> unwraps to T
   async long_task(): Promise<int> {
-    // → func long_task() -> int:
     await this.get_tree().create_timer(1).timeout;
     return 42;
   }
 
   _process(delta: float) {
-    // → func _process(delta: float):
-    // ── Operators ──────────────────────────────────────────────────
-    let eq = this.health === 0; // → var eq      = self.health == 0
-    let ternary = eq ? 1 : 2; // → var ternary = 1 if eq else 2
+    // Operators
+    let eq = this.health === 0;
+    let ternary = eq ? 1 : 2;
 
-    // ── Math on value types (Vector2, Color, …) needs gd.ops ───────
-    let pos = gd.ops.add(this.position, Vector2(1, 0)); // → var pos = (self.position + Vector2(1, 0))
-    // Available: add, sub, mul, div, rem, eq, ne, gt, gte, lt, lte, plus (unary), minus (unary)
+    // Math on value types (Vector2, Color, …) needs gd.ops
+    let pos = gd.ops.add(this.position, Vector2(1, 0));
+    // Also available: add, sub, mul, div, rem, eq, ne, gt, gte, lt, lte, plus (unary), minus (unary)
 
-    // ── Type casting / checking ────────────────────────────────────
-    let body = gd.as(this.get_node('Body'), CharacterBody2D); // → var body = self.get_node("Body") as CharacterBody2D
+    // Type casting / checking
+    // self.get_node("Body") as CharacterBody2D
+    let body = gd.as(this.get_node('Body'), CharacterBody2D);
     if (body instanceof CharacterBody2D) {
-      /* class check */
-    } // → if body is CharacterBody2D:
+      /* body is CharacterBody2D */
+    }
     if (gd.is(this.health, int)) {
-      /* primitive   */
-    } // → if self.health is int:
+      /* health is int */
+    }
 
-    // ── Object construction ────────────────────────────────────────
-    let bullet = new Player.Bullet(); // → var bullet = Bullet.new()
+    // Object construction instead of Player.Bullet.new()
+    let bullet = new Player.Bullet();
 
-    // ── Dictionaries (string keys — for non-string keys use gd.dict) ──
-    let stats = { name: 'Hero', hp: 100 }; // → var stats = { "name": "Hero", "hp": 100 }
+    // Dictionaries (other keys: gd.dict)
+    let stats = { name: 'Hero', hp: 100 };
 
-    // ── Strings, StringName, NodePath ──────────────────────────────
-    let greet = `Hi ${this.name}!`; // → var greet = "Hi " + str(self.name) + "!"
-    let path = NodePath('Body/Sprite'); // → var path  = ^"Body/Sprite"
-    let sig = StringName('died'); // → var sig   = &"died"
+    // Strings, StringName, NodePath
+    let greet = `Hi ${this.name}!`;
+    let path = NodePath('Body/Sprite');
+    let sig = StringName('died');
 
-    // ── Control flow ───────────────────────────────────────────────
-    for (let s of range(3)) print(s); // → for s in range(3): print(s)
+    // Control flow
+    for (let s of range(3)) print(s);
 
-    // ── Match — native TS switch round-trips with GD `match` ───────
-    switch (
-      this.health // → match self.health:
-    ) {
+    // Match (TS switch round-trips with GD match)
+    switch (this.health) {
       case 0:
         this.died.emit();
-        break; //       0: self.died.emit()
       default:
         print('alive');
-        break; //       _: print("alive")
     }
   }
 
   _ready() {
-    // → func _ready():
-    // Signals — emit and connect
-    this.health_changed.emit(0, 100); // → self.health_changed.emit(0, 100)
     this.health_changed.connect(this._on_health_changed);
+    this.health_changed.emit(0, 100);
   }
 
   _on_health_changed(from: int, to: int) {
@@ -214,35 +260,117 @@ export class Player extends CharacterBody2D {
 }
 ```
 
-#### Useful global types
-
-Each interface is a map from a string literal (a `res://` path or a group name) to the typed entity that path resolves to. You index them directly to get the typed value:
+<details>
+<summary>Result gdscript:</summary>
+
+```gdscript
+extends CharacterBody2D
+class_name Player
+
+const MAX_HP = 100
+
+enum State { IDLE, RUNNING }
+
+class Bullet extends Node2D:
+	var damage: int = 10
+
+# Statics (mutable); for constants use the namespace
+static var MAX_INSTANCES = 8
+# Field decorators. `@exports` aliases `@export`
+# (a TS reserved word); other annotations are 1:1
+@export
+var speed: float = 200.0
+@export_range(0, 100)
+var health: int = 100
+@onready
+var sprite: PlayerSprite = self.get_node("Sprite")
+@onready
+var spriteState = self.sprite.get_state()
+# Signals; tuple labels become GD arg names
+signal health_changed(from: int, to: int)
+signal died
+
+# Constructor replaces _init
+func _init(speed: float = 200.0):
+	self.speed = speed
+
+var score: int:
+	get:
+		return score
+	set(v):
+		score = v
+
+# Async / await; Promise<T> unwraps to T
+func long_task() -> int:
+	await self.get_tree().create_timer(1).timeout
+	return 42
+
+func _process(delta: float):
+	# Operators
+	var eq = self.health == 0
+	var ternary = 1 if eq else 2
+	# Math on value types (Vector2, Color, …) needs gd.ops
+	var pos = (self.position + Vector2(1, 0))
+	# Also available: add, sub, mul, div, rem, eq, ne, gt, gte, lt, lte, plus (unary), minus (unary)
+	# Type casting / checking
+	# self.get_node("Body") as CharacterBody2D
+	var body = self.get_node("Body") as CharacterBody2D
+	if body is CharacterBody2D:
+		pass
+	if self.health is int:
+		pass
+	# Object construction instead of Player.Bullet.new()
+	var bullet = self.Bullet.new()
+	# Dictionaries (other keys: gd.dict)
+	var stats = {
+		"name": "Hero",
+		"hp": 100,
+	}
+	# Strings, StringName, NodePath
+	var greet = "Hi " + str(self.name) + "!"
+	var path = NodePath("Body/Sprite")
+	var sig = StringName("died")
+	# Control flow
+	for s in range(3):
+		print(s)
+	# Match (TS switch round-trips with GD match)
+	match self.health:
+		0:
+			self.died.emit()
+		_:
+			print("alive")
+
+func _ready():
+	self.health_changed.connect(self._on_health_changed)
+	self.health_changed.emit(0, 100)
+
+func _on_health_changed(from: int, to: int):
+	pass
+
+func die():
+	pass
+```
 
-| Interface          | Keys                                                         | Values                                                                                                                                            | Example                                                          |
-| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| `GodotResources`   | every asset path (`.tscn`, `.gd`, `.tres`, images, audio, …) | The resource type the path resolves to — `PackedScene<Root>` for scenes, `typeof Class` for scripts, the concrete `Resource` subclass for `.tres` | `let mat: GodotResources["res://player_material.tres"]`          |
-| `GodotScripts`     | `.gd` script paths                                           | `typeof <Class>` — the class constructor for the script                                                                                           | `const GameManager: GodotScripts["res://GameManager.gd"]`        |
-| `GodotScenes`      | `.tscn` paths                                                | The **root node** type of the scene (with full tree attached)                                                                                     | `let root: GodotScenes["res://Level.tscn"]`                      |
-| `GodotSceneTrees`  | `.tscn` paths                                                | The **tree** type — used when you need to index descendants directly                                                                              | `type Tree = GodotSceneTrees["res://Player.tscn"]`               |
-| `GodotGroups`      | group names declared in `.tscn` files                        | `{ [scenePath]: union of node types in that group }`                                                                                              | `GodotGroups["enemies"]["res://Level.tscn"]` → `Goblin \| Slime` |
-| `GodotConnections` | scene paths that have `[connection]` entries                 | `{ "Node.signal": _GDSignalConnection<…> }` — connection metadata                                                                                 | `GodotConnections["res://UI.tscn"]["Button.pressed"]`            |
+</details>
 
-The Godot-typed `load()`, `preload()`, `get_node()`, and autoload singletons all index these interfaces under the hood.
+#### Useful global types
 
-#### The `*Name` key-union aliases
+Each interface maps a string literal (a `res://` path or group name) to the type it resolves to — index it directly, e.g. `GodotResources["res://player.tres"]` or `GodotScripts["res://player.gd"]`:
 
-Each base interface has a parallel alias defined as `keyof <Interface>`, so you can constrain a function argument to **only paths/names that exist in the project**:
+- **`GodotResources`** — any asset path → its resource type (`PackedScene<Root>`, `typeof Class`, or the concrete `Resource` subclass)
+  - **`GodotResourceName`** (= `keyof GodotResources`) — any `res://…` asset
+- **`GodotScripts`** — `.gd` path → `typeof <Class>` (the script constructor)
+  - **`GodotScriptName`** (= `keyof GodotScripts`) — a `.gd` path
+- **`GodotScenes`** — `.tscn` path → the scene's **root node** type
+  - **`GodotSceneName`** (= `keyof GodotScenes`) — a `.tscn` path
+- **`GodotSceneTrees`** — `.tscn` path → the **tree** type, for indexing descendants directly
+  - **`GodotSceneTreeName`** (= `keyof GodotSceneTrees`) — same set as `GodotSceneName`, for the tree rather than the root
+- **`GodotGroups`** — group name → union of the node types in that group
+  - **`GodotGroupName`** (= `keyof GodotGroups`) — a group identifier (`"enemies"`, …)
 
-| Alias                      | Equivalent to            | Typical use                                                             |
-| -------------------------- | ------------------------ | ----------------------------------------------------------------------- |
-| `GodotResourceName`        | `keyof GodotResources`   | `res://…` to any asset                                                  |
-| `GodotSceneName`           | `keyof GodotScenes`      | `res://…` to a `.tscn`                                                  |
-| `GodotSceneTreeName`       | `keyof GodotSceneTrees`  | Same set as `GodotSceneName`; pick when you want the tree, not the root |
-| `GodotScriptName`          | `keyof GodotScripts`     | `res://…` to a `.gd`                                                    |
-| `GodotGroupName`           | `keyof GodotGroups`      | Group identifier (`"enemies"`, `"entities"`, …)                         |
-| `GodotConnectionSceneName` | `keyof GodotConnections` | Scene paths that have `[connection]` entries                            |
+The Godot-typed `load()`, `preload()`, `get_node()`, and autoload singletons all index these under the hood.
 
-`keyof` is resolved lazily, so each alias automatically picks up new entries as more files are converted. Typos in resource paths or group names become compile-time errors instead of silent runtime failures:
+That types are resolved lazily, so each alias automatically picks up new entries as more files are converted. Typos in resource paths or group names become compile-time errors instead of silent runtime failures:
 
 ```typescript
 class AssetLoader extends Node {
@@ -256,9 +384,9 @@ class AssetLoader extends Node {
 
   _ready() {
     this.preload_asset('res://Player.tscn'); // ✅ typed
-    this.preload_asset('res://does_not_exist.png'); // ❌ TS2345
+    this.preload_asset('res://does_not_exist.png'); // ❌ error
     this.count_in_group('enemies'); // ✅ typed
-    this.count_in_group('typo'); // ❌ TS2345
+    this.count_in_group('typo'); // ❌ error
   }
 }
 ```

package/dist/cli/convert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../src/cli/convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBzC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiN7D"}
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../src/cli/convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBzC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgO7D"}

package/dist/cli/convert.js

@@ -11,6 +11,8 @@ export function registerConvertCommand(program) {
     program
         .command('convert')
         .description('Convert TypeScript file(s) to GDScript. If no files given, converts all .ts files in tsDir. ' +
+        'Converts every file fresh by default — correct even when types in other files changed; ' +
+        'pass --use-cache to skip content-unchanged files (faster, may serve stale output). ' +
         'After writing, runs full diagnostic check (TS + converter + Godot) unless --no-check is set.')
         .argument('[files...]', 'TypeScript files or glob patterns to convert')
         .option('--ts-dir <dir>', 'TypeScript source directory')
@@ -19,7 +21,10 @@ export function registerConvertCommand(program) {
         .option('--tsconfig <path>', 'Path to tsconfig.json')
         .option('--godot-path <path>', 'Path to Godot executable (enables GDScript validation)')
         .option('--project-root <dir>', 'Godot project root for validation')
-        .option('--no-cache', 'Disable cache (force full reconversion)')
+        .option('--use-cache', 'Skip conversion for files with a fresh cache entry. Fast, but can keep ' +
+        'stale .gd output when types in imported files or global typings changed ' +
+        '(freshness is judged by file content only)', false)
+        .option('--no-cache', 'Disable cache entirely (no reads, no writes)')
         .option('--emit-on-error', 'Emit output files even when conversion errors occur', false)
         .option('--no-emit', 'Dry-run: convert in memory, check for stale outputs, do not write files')
         .option('--no-check', 'Skip the post-convert diagnostic check (TS + Godot)')
@@ -41,8 +46,13 @@ export function registerConvertCommand(program) {
         // commander: --no-emit sets opts.emit = false, --no-check sets opts.check = false
         const noEmit = opts.emit === false;
         const noCheck = opts.check === false;
-        const useCache = opts.cache !== false;
-        const cache = useCache ? new ProjectCache(cfg.cacheDir) : null;
+        // Cache is write-only by default: every run converts fresh (correct even
+        // when types in OTHER files changed — content hashes can't see that),
+        // but results are still recorded so the watcher / ts-plugin / check
+        // phase can reuse them. `--use-cache` opts into the read-side skip;
+        // `--no-cache` disables the cache entirely.
+        const cache = opts.cache !== false ? new ProjectCache(cfg.cacheDir) : null;
+        const useCacheReads = opts.useCache === true && cache !== null;
         debugLog(`${noEmit ? 'Checking' : 'Converting'} ${resolvedFiles.length} file(s)...`);
         // Build the ts.Program once and share it across the write loop and the
         // post-convert checker — avoids re-parsing every .ts file twice.
@@ -59,12 +69,12 @@ export function registerConvertCommand(program) {
             for (const filePath of resolvedFiles) {
                 const relPath = relative(cfg.tsDir, filePath);
                 const outputPath = resolve(cfg.gdDir, relPath.replace(/\.ts$/, '.gd'));
-                if (cache?.isTsToGdFresh(filePath, outputPath)) {
+                if (useCacheReads && cache?.isTsToGdFresh(filePath, outputPath)) {
                     debugLog(`Skipped (cache): ${outputPath}`);
                     skipped++;
                     continue;
                 }
-                if (cache && cache.hasFreshCachedGd(filePath)) {
+                if (useCacheReads && cache?.hasFreshCachedGd(filePath)) {
                     const promoted = cache.promoteCachedGd(filePath, outputPath);
                     if (promoted && cache.isTsToGdFresh(filePath, outputPath)) {
                         debugLog(`Promoted (cache-folder): ${outputPath}`);

package/dist/cli/convert.js.map

@@ -1 +1 @@
-{"version":3,"file":"convert.js","sourceRoot":"","sources":["../../src/cli/convert.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"convert.js","sourceRoot":"","sources":["../../src/cli/convert.ts"],"names":[],"mappings":"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"}

package/dist/converter/common/index.d.ts

@@ -40,6 +40,15 @@ export interface TransformContext {
      * `extends "res://..."` are taken relative to this directory.
      */
     projectRoot: string;
+    /**
+     * Godot class registry. Used to recognise Godot built-in types (classes,
+     * value-type constructors, global enums) by name when classifying TS type
+     * annotations — see {@link tsTypeNodeToGdType}. May be `undefined` when the
+     * registry could not be resolved, in which case classification can only
+     * emit types it proves are classes/enums via the checker and drops every
+     * other name (Godot built-ins can no longer be recognised by name).
+     */
+    registry?: GodotClassRegistry;
 }
 /**
  * Sentinel TS class name used for anonymous addon scripts (a `.gd`
@@ -147,12 +156,19 @@ export declare function isFloatType(type: ts.Type, checker: ts.TypeChecker): boo
 /**
  * Converts a TypeScript type to its GDScript type annotation string.
  * Returns null if the type should be omitted.
+ *
+ * NOTE: unlike {@link tsTypeNodeToGdType}, this `ts.Type`-based variant does
+ * NOT classify reference types — it returns the symbol name verbatim for any
+ * class-like type, so an `object`/`interface`/unknown type would leak a bogus
+ * annotation. It is currently unused for emission (kept only for its own
+ * recursion). Do not wire it into an emit path without adding the same
+ * class/enum/registry classification `classifyTypeReferenceName` applies.
  */
 export declare function tsTypeToGdType(type: ts.Type, checker: ts.TypeChecker): string | null;
 /**
  * Converts a TypeScript type annotation node to GDScript type string.
  */
-export declare function tsTypeNodeToGdType(typeNode: ts.TypeNode | undefined, checker: ts.TypeChecker, sourceFile: ts.SourceFile, className?: string): string | null;
+export declare function tsTypeNodeToGdType(typeNode: ts.TypeNode | undefined, checker: ts.TypeChecker, sourceFile: ts.SourceFile, className?: string, registry?: GodotClassRegistry): string | null;
 /**
  * True when `gdType` refers to a Godot class (Node, Resource, Material, user
  * class, ...) — a type that can legitimately hold `null` in GDScript. False

package/dist/converter/common/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/converter/common/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/converter/common/index.ts"],"names":[],"mappings":"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"}