typescript-to-gdscript 0.1.0

package/dist/config/index.d.ts

@@ -0,0 +1,142 @@
+import { GodotClassRegistry } from '../typings/godot-registry.ts';
+export interface TsToGdConfig {
+    /** Root directory (base for relative paths). Defaults to config file directory or CWD. */
+    rootDir?: string;
+    /** TypeScript source directory (relative to rootDir or absolute). Defaults to `"src"`. */
+    tsDir?: string;
+    /** GDScript output directory (relative to rootDir or absolute). Defaults to `"scripts"`. */
+    gdDir?: string;
+    /** Directory for all generated typings (globals.d.ts, scene-typings.d.ts). Relative to rootDir. Defaults to "_gdtots". */
+    typingsDir?: string;
+    /** Directory to scan for .tscn scene files (relative to rootDir). Defaults to rootDir. */
+    scenesDir?: string;
+    /** Path to tsconfig.json */
+    tsconfig?: string;
+    /** Path to Godot executable for GDScript validation */
+    godotPath?: string;
+    /** Glob patterns for files/folders to exclude from all conversions and typings generation. */
+    exclude?: string[];
+    /** Path to project.godot file (relative to rootDir). Defaults to "project.godot". */
+    projectFile?: string;
+    /** Disable Godot executable validation (CLI `convert` post-write check + the ts-plugin's async Godot pass). When false (default), an error is raised if Godot is not found. */
+    disableGodotLint?: boolean;
+    /** Cache directory. Default: `node_modules/.cache/typescript-to-gdscript` or temp dir. */
+    cacheDir?: string;
+    /** Path to Godot engine typings (classes, gd-helpers, globals). Default: `node_modules/typescript-to-gdscript/typings`. */
+    godotTypingsDir?: string;
+    /** Converter behavior tweaks. */
+    converterOptions?: ConverterOptions;
+}
+/**
+ * Knobs that change how the converter and typings generator emit code.
+ * All fields are optional; omitted fields fall back to the defaults
+ * documented per-field below.
+ */
+export interface ConverterOptions {
+    /**
+     * When true, every non-anonymous TypeScript class is emitted into the
+     * global TS scope (`declare global { class X extends ScriptClass }`),
+     * matching pre-refactor behavior. When false (default), classes are
+     * module-scoped and consumers must `import` them — this drives the
+     * TS→GD converter to emit `const X = preload("res://…")` for
+     * renamed/anonymous imports and to skip-emit imports of globally
+     * available GD classes.
+     *
+     * Addons (GD→TS conversion) always generate global types regardless
+     * of this flag — addons are consumed as a unit and need to be visible
+     * without explicit imports.
+     */
+    generateGlobalClassTypes?: boolean;
+}
+export interface ResolvedConfig {
+    rootDir: string;
+    tsDir: string;
+    gdDir: string;
+    /** Absolute path to the directory for all generated typings (globals.d.ts, scene-typings.d.ts). */
+    typingsDir: string;
+    scenesDir: string;
+    tsconfig?: string;
+    godotPath?: string;
+    /** Glob patterns for files/folders to ignore. */
+    ignore: string[];
+    /** Absolute path to project.godot file. */
+    projectFile: string;
+    /** Disable Godot executable validation. */
+    disableGodotLint: boolean;
+    /** Absolute path to cache directory. */
+    cacheDir: string;
+    /** Absolute path to Godot engine typings directory. */
+    godotTypingsDir: string;
+    /**
+     * Resolved converter knobs. Always present (defaults filled in by
+     * `resolveConfig`); see `ConverterOptions` for per-field semantics.
+     */
+    converterOptions: ResolvedConverterOptions;
+}
+/** Same shape as `ConverterOptions` but with all fields required. */
+export interface ResolvedConverterOptions {
+    generateGlobalClassTypes: boolean;
+}
+/**
+ * Loads tstogd.json and resolves all paths to absolute.
+ * CLI flags can override any field via the `overrides` parameter.
+ * Returns fully resolved config with absolute paths.
+ */
+/** CLI-only overrides that don't come from tstogd.json */
+export interface ConfigOverrides extends Partial<TsToGdConfig> {
+    /** GDScript output directory (CLI-only, not stored in tstogd.json) */
+    gdDir?: string;
+    /** Generate source maps (CLI-only flag, always true for lint + ts-plugin) */
+    sourceMap?: boolean;
+}
+export declare function resolveConfig(options?: {
+    configDir?: string;
+    overrides?: ConfigOverrides;
+}): ResolvedConfig;
+/**
+ * Tests whether a file path matches any of the ignore glob patterns.
+ * Paths are compared relative to rootDir using forward slashes.
+ */
+export declare function shouldIgnore(filePath: string, rootDir: string, patterns: string[]): boolean;
+/**
+ * Loads tstogd.json from the given directory (defaults to CWD).
+ * Returns null if not found.
+ */
+interface LoadConfigResult {
+    config: TsToGdConfig;
+    /** Absolute path to the directory containing tstogd.json */
+    configDir: string;
+}
+/**
+ * Loads tstogd.json by walking up from the given directory (defaults to CWD).
+ * Returns null if not found in any ancestor directory.
+ */
+export declare function loadConfig(dir?: string): LoadConfigResult | null;
+export interface ResolveGodotPathOptions {
+    /** Explicit path from CLI flag (highest priority) */
+    godotPath?: string;
+    /** Directory to search for tstogd.json (defaults to CWD) */
+    configDir?: string;
+}
+/**
+ * Resolves the Godot executable path with the following priority:
+ * 1. Explicit --godot-path CLI flag
+ * 2. godotPath from tstogd.json
+ * 3. GODOT_PATH environment variable
+ * 4. "godot" on system PATH
+ */
+export declare function resolveGodotPath(options?: ResolveGodotPathOptions): string;
+export interface ResolveRegistryOptions {
+    /** Explicit registry path from CLI flag (highest priority) */
+    registryPath?: string;
+    /** Directory to search for tstogd.json (defaults to CWD) */
+    configDir?: string;
+}
+/**
+ * Resolves the GodotClassRegistry with the following priority:
+ * 1. Explicit --registry CLI path
+ * 2. Bundled typings/godot-class-registry.json
+ */
+export declare function resolveRegistry(options?: ResolveRegistryOptions): GodotClassRegistry;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

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

package/dist/config/index.js

@@ -0,0 +1,161 @@
+import { readFileSync, existsSync } from 'fs';
+import { join, resolve, dirname, relative, basename } from 'path';
+import { tmpdir } from 'os';
+import { fileURLToPath } from 'url';
+import { minimatch } from 'minimatch';
+import { GodotClassRegistry } from "../typings/godot-registry.js";
+export function resolveConfig(options) {
+    const searchDir = options?.configDir ?? process.cwd();
+    const loaded = loadConfig(searchDir);
+    const config = loaded?.config ?? null;
+    // Use the directory where tstogd.json was found (not the search start dir)
+    const baseDir = loaded?.configDir ?? searchDir;
+    const overrides = options?.overrides ?? {};
+    // Merge: CLI overrides > config > defaults
+    const rootDir = resolve(baseDir, overrides.rootDir ?? config?.rootDir ?? '.');
+    const tsDir = resolve(rootDir, overrides.tsDir ?? config?.tsDir ?? 'src');
+    const gdDir = resolve(rootDir, overrides.gdDir ?? config?.gdDir ?? 'scripts');
+    const typingsDir = resolve(rootDir, overrides.typingsDir ?? config?.typingsDir ?? '_gdtots');
+    const scenesDir = resolve(rootDir, overrides.scenesDir ?? config?.scenesDir ?? '.');
+    const ignore = overrides.exclude ?? config?.exclude ?? [];
+    const projectFile = resolve(rootDir, overrides.projectFile ?? config?.projectFile ?? 'project.godot');
+    const cacheDir = resolve(rootDir, overrides.cacheDir ??
+        config?.cacheDir ??
+        (existsSync(join(rootDir, 'node_modules'))
+            ? join('node_modules', '.cache', 'typescript-to-gdscript')
+            : join(tmpdir(), 'typescript-to-gdscript', basename(rootDir))));
+    const godotTypingsDir = config?.godotTypingsDir
+        ? resolve(baseDir, config.godotTypingsDir)
+        : (findPackageTypingsDir(rootDir) ?? getPackageTypingsDir());
+    return {
+        rootDir,
+        tsDir,
+        gdDir,
+        typingsDir,
+        scenesDir,
+        ignore,
+        projectFile,
+        tsconfig: overrides.tsconfig ??
+            config?.tsconfig ??
+            (existsSync(join(rootDir, 'tsconfig.json'))
+                ? join(rootDir, 'tsconfig.json')
+                : undefined),
+        godotPath: overrides.godotPath ?? config?.godotPath,
+        disableGodotLint: config?.disableGodotLint ?? false,
+        cacheDir,
+        godotTypingsDir,
+        converterOptions: {
+            generateGlobalClassTypes: overrides.converterOptions?.generateGlobalClassTypes ??
+                config?.converterOptions?.generateGlobalClassTypes ??
+                false,
+        },
+    };
+}
+// ─── Ignore Patterns ─────────────────────────────────────────
+/**
+ * Tests whether a file path matches any of the ignore glob patterns.
+ * Paths are compared relative to rootDir using forward slashes.
+ */
+export function shouldIgnore(filePath, rootDir, patterns) {
+    if (patterns.length === 0)
+        return false;
+    const rel = relative(rootDir, filePath).replace(/\\/g, '/');
+    return patterns.some((pattern) => minimatch(rel, pattern, { dot: true }));
+}
+const CONFIG_FILENAME = 'tstogd.json';
+/**
+ * Loads tstogd.json by walking up from the given directory (defaults to CWD).
+ * Returns null if not found in any ancestor directory.
+ */
+export function loadConfig(dir) {
+    let searchDir = resolve(dir ?? process.cwd());
+    for (;;) {
+        const configPath = join(searchDir, CONFIG_FILENAME);
+        if (existsSync(configPath)) {
+            const raw = readFileSync(configPath, 'utf-8');
+            return { config: JSON.parse(raw), configDir: searchDir };
+        }
+        const parent = dirname(searchDir);
+        if (parent === searchDir)
+            break; // filesystem root
+        searchDir = parent;
+    }
+    return null;
+}
+// ─── Registry Resolution ──────────────────────────────────────
+/**
+ * Walk up from rootDir looking for node_modules/typescript-to-gdscript/typings.
+ * Returns the path via node_modules (preserving symlink structure) or undefined.
+ */
+function findPackageTypingsDir(rootDir) {
+    let dir = rootDir;
+    for (let i = 0; i < 10; i++) {
+        const candidate = join(dir, 'node_modules', 'typescript-to-gdscript', 'typings');
+        if (existsSync(join(candidate, 'index.d.ts')))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Get the path to the package's bundled typings directory.
+ * Works whether running from src/ (ts-node) or dist/ (compiled).
+ * Resolves symlinks — use findPackageTypingsDir() for node_modules paths.
+ */
+function getPackageTypingsDir() {
+    // This file is at src/config/index.ts or dist/config/index.js
+    // Package root is two levels up
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const packageRoot = resolve(thisDir, '..', '..');
+    return join(packageRoot, 'typings');
+}
+/**
+ * Resolves the bundled registry JSON path.
+ * The registry lives directly in typings/godot-class-registry.json.
+ */
+function getBundledRegistryPath() {
+    const typingsDir = getPackageTypingsDir();
+    const registryPath = join(typingsDir, 'godot-class-registry.json');
+    if (existsSync(registryPath))
+        return registryPath;
+    return null;
+}
+/**
+ * Resolves the Godot executable path with the following priority:
+ * 1. Explicit --godot-path CLI flag
+ * 2. godotPath from tstogd.json
+ * 3. GODOT_PATH environment variable
+ * 4. "godot" on system PATH
+ */
+export function resolveGodotPath(options) {
+    if (options?.godotPath)
+        return resolve(options.godotPath);
+    const loaded = loadConfig(options?.configDir);
+    if (loaded?.config.godotPath) {
+        return resolve(loaded.configDir, loaded.config.godotPath);
+    }
+    if (process.env.GODOT_PATH)
+        return process.env.GODOT_PATH;
+    return 'godot';
+}
+/**
+ * Resolves the GodotClassRegistry with the following priority:
+ * 1. Explicit --registry CLI path
+ * 2. Bundled typings/godot-class-registry.json
+ */
+export function resolveRegistry(options) {
+    // 1. Explicit CLI path
+    if (options?.registryPath) {
+        return GodotClassRegistry.fromJsonFile(resolve(options.registryPath));
+    }
+    // 2. Bundled registry
+    const bundledPath = getBundledRegistryPath();
+    if (bundledPath)
+        return GodotClassRegistry.fromJsonFile(bundledPath);
+    throw new Error('Could not find Godot class registry. Provide --registry flag ' +
+        'or ensure typings/godot-class-registry.json exists in the package.');
+}
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

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

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

@@ -0,0 +1,169 @@
+import ts from 'typescript';
+import type { GodotClassRegistry } from '../../typings/godot-registry.ts';
+/**
+ * Pre-derived lookup sets for `in`-operator diagnostics and variant/class type
+ * checks. Built once per converter run from the Godot class registry.
+ */
+export interface DiagnosticsTypeInfo {
+    /** All variant/value type constructors (Vector2, Color, Packed*Array, Dictionary, ...). */
+    constructors: Set<string>;
+    /** Subset of {@link constructors} whose names match `Packed*Array`. */
+    packedArrayTypes: Set<string>;
+    /** Constructors banned from `in` RHS (excludes allowed containers and packed arrays). */
+    bannedInTypes: Set<string>;
+}
+/**
+ * Context passed through the transformation pipeline.
+ */
+export interface TransformContext {
+    /** TypeScript program */
+    program: ts.Program;
+    /** TypeScript type checker */
+    checker: ts.TypeChecker;
+    /** Current source file being transformed */
+    sourceFile: ts.SourceFile;
+    /** File path of the source */
+    filePath: string;
+    /** Diagnostics / warnings collected during transformation */
+    diagnostics: TransformDiagnostic[];
+    /** Pre-derived sets of Godot variant types (for `in`-operator and param diagnostics). */
+    diagInfo: DiagnosticsTypeInfo;
+    /**
+     * TypeScript source root. Used by import-resolution code to mirror
+     * relative paths into the GDScript output tree.
+     */
+    tsDir: string;
+    /** GDScript output root — sibling of {@link tsDir}. */
+    gdDir: string;
+    /**
+     * Godot project root. `res://` paths emitted by `preload(...)` and
+     * `extends "res://..."` are taken relative to this directory.
+     */
+    projectRoot: string;
+}
+/**
+ * Sentinel TS class name used for anonymous addon scripts (a `.gd`
+ * file under `addons/` with no `class_name` declaration). `$` is not
+ * a valid GDScript identifier character, so this name can never
+ * collide with a real GD class. Each addon `.ts` is its own ES
+ * module, so multiple files exporting `_$CLASS$_` don't collide
+ * either — consumers of the addon's `.gd.d.ts` see the class via the
+ * `import type { _$CLASS$_ as ScriptClass }` alias.
+ *
+ * Non-addon anonymous classes use {@link gdFilenameToAnonymousClassName}
+ * instead — the filename-derived form is friendlier when users actually
+ * read the generated TS source. Addons are auto-generated and read
+ * mostly through their `.gd.d.ts` shadows, so the sentinel is fine.
+ */
+export declare const ANONYMOUS_ADDON_CLASS_NAME = "_$CLASS$_";
+/**
+ * Derive the TS class name for a `.gd` file that has no `class_name`
+ * declaration. The convention: the leading underscore marks the class as
+ * "module-scoped / anonymous in GD", and the body is the file's basename
+ * converted to UpperCamelCase. Same on both conversion directions, so
+ * round-tripping is stable.
+ *
+ * Examples:
+ *   - `some_class.gd`  → `_SomeClass`
+ *   - `Anonym.gd`      → `_Anonym`
+ *   - `enemy.gd`       → `_Enemy`
+ *   - `nested/foo.gd`  → `_Foo`  (path is ignored — only basename matters)
+ */
+export declare function gdFilenameToAnonymousClassName(filePath: string): string;
+/**
+ * True when a class name follows the "anonymous" convention — single
+ * leading underscore that is NOT the `G_` global-class escape. Used
+ * everywhere we need to decide whether to emit `class_name` (in TS→GD)
+ * or `declare global` (in typings generation).
+ */
+export declare function isAnonymousClassName(name: string): boolean;
+/**
+ * One-way fallback applied during GD→TS conversion only: a GD
+ * `class_name _Foo` would collide with the anonymous-class convention
+ * (where `_`-prefixed TS names mean "no `class_name` in GD"), so the
+ * TS shadow class is renamed to `G_Foo`. The TS→GD direction does NOT
+ * un-escape — `G_Foo` in TS source emits `class_name G_Foo` in the
+ * generated `.gd` verbatim. The escape happens at most once, when
+ * generating addon shadows or running `initial-convert-gd-to-ts`; afterwards `G_Foo`
+ * is the canonical identifier on both sides.
+ */
+export declare function escapeUnderscoreClassName(gdClassName: string): string;
+/**
+ * Diagnostic severity levels.
+ *
+ * - `error` — conversion failure (invalid/unsupported syntax). Blocks .gd
+ *   output (unless `--emit-on-error`). Blocks Godot validation.
+ * - `type-error` — semantic/type issue, but GD emission produced valid output.
+ *   .gd IS written. Counted as an error by `convert`/`watch` and the ts-plugin.
+ *   Godot validation still runs.
+ * - `warning` — non-blocking advisory. Shown as WARN everywhere.
+ * - `info` — debug-level; filtered out in most consumers.
+ */
+export type DiagnosticSeverity = 'error' | 'type-error' | 'warning' | 'info';
+export interface TransformDiagnostic {
+    message: string;
+    severity: DiagnosticSeverity;
+    file: string;
+    /** 1-based line number (matches editor/CLI `line:col` convention). */
+    line: number;
+    /**
+     * 1-based column number. Producers that obtain a 0-based character
+     * index (TypeScript `getLineAndCharacterOfPosition`, tree-sitter
+     * `startPosition.column`) MUST add `+1` before storing here.
+     * Consumers that need a 0-based offset (e.g. TypeScript
+     * `getPositionOfLineAndCharacter` in the ts-plugin) subtract `1`
+     * on the way out.
+     */
+    column: number;
+}
+/**
+ * True for severities that should surface as lint / ts-plugin errors (exit code 1 for CLI lint, red squiggle in the IDE).
+ * Both `error` and `type-error` are user-facing errors; only `error` blocks
+ * emission/Godot validation. Use {@link isConversionErrorSeverity} for that.
+ */
+export declare function isReportableErrorSeverity(sev: DiagnosticSeverity): boolean;
+/**
+ * True only for real conversion errors — the converter could not emit valid
+ * GDScript. These block `.gd` write (unless `--emit-on-error`) AND block
+ * Godot validation (unless `--godot-validate-on-error`).
+ */
+export declare function isConversionErrorSeverity(sev: DiagnosticSeverity): boolean;
+export interface TransformResult {
+    /** Generated GDScript code */
+    code: string;
+    /** Source map JSON (if generated) */
+    sourceMap?: string;
+    /** Diagnostics from transformation */
+    diagnostics: TransformDiagnostic[];
+}
+/**
+ * Checks if a TypeScript type is the `int` alias.
+ */
+export declare function isIntType(type: ts.Type, checker: ts.TypeChecker): boolean;
+/**
+ * Checks if a TypeScript type is the `float` alias.
+ */
+export declare function isFloatType(type: ts.Type, checker: ts.TypeChecker): boolean;
+/**
+ * Converts a TypeScript type to its GDScript type annotation string.
+ * Returns null if the type should be omitted.
+ */
+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;
+/**
+ * True when `gdType` refers to a Godot class (Node, Resource, Material, user
+ * class, ...) — a type that can legitimately hold `null` in GDScript. False
+ * for primitives (int, float, bool, String), variant/value types (Vector2,
+ * Color, Packed*Array, Dictionary, Callable, Signal, StringName, NodePath, ...),
+ * typed array/dictionary syntax, enum references, and special markers
+ * (`void`, `Nil`, `Variant`, `any`, `unknown`).
+ *
+ * Reference types are candidates for `T | null` widening in the GD-to-TS
+ * converter. Value types are not — Godot does not permit assigning null to
+ * them.
+ */
+export declare function isReferenceType(gdType: string, registry: GodotClassRegistry): boolean;
+//# sourceMappingURL=index.d.ts.map

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

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