typescript-to-gdscript 0.1.0

package/dist/converter/gd-to-ts/index.js

@@ -0,0 +1,189 @@
+import { GDScriptParser } from "../../parser/gdscript/index.js";
+import { SyntaxType } from "../../parser/gdscript/types.js";
+import { buildGlobalEnumMap, } from "./context.js";
+import { extractGdTypeName, inferExprTypeStatic } from "./type-inference.js";
+import { emitSourceFile } from "./source-emitter.js";
+/**
+ * Fix comment indentation so tree-sitter doesn't break block structure.
+ * In GDScript, comments don't affect block indentation. A comment at column 0
+ * inside an indented block shouldn't break the block. This function aligns
+ * such comments to the indentation of the next non-comment, non-empty line.
+ */
+function fixCommentIndentation(source) {
+    const lines = source.split('\n');
+    const result = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trimStart();
+        // Check if this is a comment line (# or ##)
+        if (trimmed.startsWith('#')) {
+            // tree-sitter-gdscript bug: `#"` (no space) is not parsed as a comment.
+            // Workaround: ensure a space after # or ## before non-space characters.
+            const commentPrefix = trimmed.startsWith('##') ? '##' : '#';
+            const afterPrefix = trimmed.slice(commentPrefix.length);
+            let fixedTrimmed = trimmed;
+            if (afterPrefix.length > 0 &&
+                afterPrefix[0] !== ' ' &&
+                afterPrefix[0] !== '\t') {
+                fixedTrimmed = commentPrefix + ' ' + afterPrefix;
+            }
+            // Find the next non-empty, non-comment line
+            let nextIndent = null;
+            for (let j = i + 1; j < lines.length; j++) {
+                const nextTrimmed = lines[j].trimStart();
+                if (nextTrimmed === '' || nextTrimmed.startsWith('#'))
+                    continue;
+                // Get indentation of the next code line
+                nextIndent = lines[j].substring(0, lines[j].length - nextTrimmed.length);
+                break;
+            }
+            if (nextIndent !== null) {
+                // Get current comment indentation
+                const currentIndent = line.substring(0, line.length - trimmed.length);
+                // If comment has less indentation than the next code line, re-indent it
+                if (currentIndent.length < nextIndent.length) {
+                    result.push(nextIndent + fixedTrimmed);
+                    continue;
+                }
+            }
+            if (fixedTrimmed !== trimmed) {
+                const currentIndent = line.substring(0, line.length - trimmed.length);
+                result.push(currentIndent + fixedTrimmed);
+                continue;
+            }
+        }
+        result.push(line);
+    }
+    return result.join('\n');
+}
+/**
+ * Extracts class info (class_name, extends, own members) from a GD source without full conversion.
+ *
+ * `filePath` is optional but recommended — it's stored on the resulting
+ * {@link UserClassInfo} and consumed by the GD→TS converter when it
+ * needs to emit cross-file `import { Foo } from './foo.js'` lines (the
+ * module-scoped layout used when `generateGlobalClassTypes` is `false`).
+ */
+export function parseGdClassInfo(source, registry, filePath) {
+    const parser = new GDScriptParser();
+    const root = parser.parse(fixCommentIndentation(source));
+    let className = '';
+    let extendsClass = '';
+    const members = new Set();
+    const memberTypes = new Map();
+    for (const child of root.namedChildren) {
+        if (child.type === SyntaxType.ExtendsStatement) {
+            const typeNode = child.namedChildren[0];
+            if (typeNode) {
+                extendsClass =
+                    typeNode.type === SyntaxType.Type
+                        ? (typeNode.namedChildren[0]?.text ?? typeNode.text)
+                        : typeNode.text;
+            }
+        }
+        else if (child.type === SyntaxType.ClassNameStatement) {
+            // `parseGdClassInfo` builds the user-class index keyed on the GD
+            // identifier as written in the .gd source — keep it un-escaped
+            // here so cross-file `extends Foo` lookups resolve regardless of
+            // whether the parent has a `_`-prefix.
+            className = child.childForFieldName('name')?.text ?? '';
+        }
+        else if (child.type === SyntaxType.FunctionDefinition ||
+            child.type === SyntaxType.ConstructorDefinition) {
+            const name = child.childForFieldName('name')?.text ?? '_init';
+            members.add(name === '_init' ? 'constructor' : name);
+        }
+        else if (child.type === SyntaxType.VariableStatement ||
+            child.type === SyntaxType.ExportVariableStatement ||
+            child.type === SyntaxType.OnreadyVariableStatement) {
+            const name = child.childForFieldName('name')?.text;
+            if (name) {
+                members.add(name);
+                const typeNode = child.childForFieldName('type');
+                const valueNode = child.childForFieldName('value');
+                const inferredType = typeNode
+                    ? extractGdTypeName(typeNode)
+                    : valueNode
+                        ? inferExprTypeStatic(valueNode, registry)
+                        : null;
+                if (inferredType)
+                    memberTypes.set(name, inferredType);
+            }
+        }
+        else if (child.type === SyntaxType.SignalStatement) {
+            const name = child.childForFieldName('name')?.text;
+            if (name)
+                members.add(name);
+        }
+        else if (child.type === SyntaxType.ConstStatement) {
+            const name = child.childForFieldName('name')?.text;
+            if (name)
+                members.add(name);
+        }
+    }
+    if (!className)
+        return null;
+    return {
+        name: className,
+        extends: extendsClass,
+        members,
+        memberTypes,
+        filePath,
+    };
+}
+export function convertGdToTs(options) {
+    // Build user class index from project sources. `filePath` flows
+    // through so the import-emission post-pass can compute relative
+    // import specifiers when `generateGlobalClassTypes` is disabled.
+    const userClasses = new Map();
+    if (options.projectSources) {
+        for (const ps of options.projectSources) {
+            const info = parseGdClassInfo(ps.source, options.registry, ps.filePath);
+            if (info)
+                userClasses.set(info.name, info);
+        }
+    }
+    // Also parse the current file so it's available for inner class extends resolution
+    const selfInfo = parseGdClassInfo(options.source, options.registry, options.filePath);
+    if (selfInfo)
+        userClasses.set(selfInfo.name, selfInfo);
+    const parser = new GDScriptParser();
+    const fixedSource = fixCommentIndentation(options.source);
+    const root = parser.parse(fixedSource);
+    const ctx = {
+        source: fixedSource,
+        filePath: options.filePath,
+        diagnostics: [],
+        classMembers: new Set(),
+        localVars: new Set(),
+        localVarTypes: new Map(),
+        classMemberTypes: new Map(),
+        registry: options.registry,
+        userClasses,
+        className: '',
+        staticMembers: new Set(),
+        signalHandlers: options.signalHandlers ?? new Map(),
+        globalEnumMap: buildGlobalEnumMap(options.registry),
+        classTypeNames: new Set(),
+        classEnumNames: new Set(),
+        unsafeUseAny: options.unsafeUseAny ?? false,
+        isAddon: options.isAddon ?? false,
+    };
+    const code = emitSourceFile(root, ctx);
+    // NOTE: cross-file `import { Foo } from './foo.js'` lines are NOT
+    // emitted here. They're added by `injectMissingImports` (in
+    // `./inject-imports.ts`) at the batch level, after every `.gd` in
+    // the project has been converted and written to disk. That pass
+    // builds a real TS program and uses unresolved-name diagnostics
+    // (TS code 2304/2503) to decide what to import — much more precise
+    // than a per-file regex. Single-file callers like `generateAddonTypings`
+    // pass `generateGlobalClassTypes: true`, which makes the inject pass
+    // a no-op anyway, so no change is needed there.
+    return {
+        code,
+        diagnostics: ctx.diagnostics,
+    };
+}
+// Re-export functions used by source-emitter (needed for backward compat + internal use)
+export { resolveAllInheritedMembers, resolveInheritedMemberTypes, } from "./context.js";
+//# sourceMappingURL=index.js.map

package/dist/converter/gd-to-ts/index.js.map

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

package/dist/converter/gd-to-ts/inject-imports.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Batch-level import injection for GD→TS conversion.
+ *
+ * Runs AFTER every `.gd` source has been converted and written to
+ * disk. Builds a real TS program over the generated `.ts` files,
+ * pulls semantic diagnostics, and prepends `import { Foo } from "./foo.js"`
+ * lines for every unresolved identifier that maps to a known user
+ * class. Much more precise than the previous per-file regex — names
+ * appearing only inside comments or string literals don't trigger
+ * a TS 2304/2503 diagnostic, so they don't produce phantom imports.
+ *
+ * No-op when `generateGlobalClassTypes` is `true` (the addon /
+ * legacy-global layout, where every user class is in `declare global`
+ * and no imports are required).
+ */
+import type { UserClassInfo } from './context.ts';
+import type { GodotClassRegistry } from '../../typings/godot-registry.ts';
+export interface ConvertedFile {
+    /** Absolute on-disk path of the generated `.ts` file. */
+    tsPath: string;
+    /** Absolute on-disk path of the source `.gd` file (used to skip self-imports). */
+    gdPath: string;
+}
+export interface InjectMissingImportsOptions {
+    /**
+     * When `true`, every user class is assumed to live in `declare global`
+     * and no imports are needed. The function returns immediately.
+     */
+    generateGlobalClassTypes: boolean;
+    /**
+     * Optional `tsconfig.json` to drive the diagnostic program. When
+     * unset a minimal default config (ES2022 / NodeNext-ish) is used —
+     * sufficient for identifier-resolution diagnostics, which don't
+     * depend on strictness or target.
+     */
+    tsConfigPath?: string;
+}
+/**
+ * For every `.ts` file in `files`, prepend `import { X } from "..."`
+ * lines for any TS 2304/2503 diagnostic whose name resolves to a
+ * known entry in `userClasses`. Files are rewritten in place. Files
+ * with nothing missing are left untouched.
+ */
+export declare function injectMissingImports(files: ConvertedFile[], userClasses: Map<string, UserClassInfo>, options: InjectMissingImportsOptions): void;
+/**
+ * Convenience wrapper: build the user-class index from a list of GD
+ * sources (the same shape `convertGdToTs` consumes via
+ * `projectSources`), then call {@link injectMissingImports}. Mirrors
+ * what the `initial-convert-gd-to-ts` CLI command needs to do for a full project run.
+ */
+export declare function injectMissingImportsForProject(files: ConvertedFile[], projectSources: Array<{
+    source: string;
+    filePath: string;
+}>, registry: GodotClassRegistry, options: InjectMissingImportsOptions): void;
+//# sourceMappingURL=inject-imports.d.ts.map

package/dist/converter/gd-to-ts/inject-imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-imports.d.ts","sourceRoot":"","sources":["../../../src/converter/gd-to-ts/inject-imports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAO1E,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,wBAAwB,EAAE,OAAO,CAAC;IAClC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EAAE,EACtB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EACvC,OAAO,EAAE,2BAA2B,GACnC,IAAI,CAmDN;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,aAAa,EAAE,EACtB,cAAc,EAAE,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,EAC3D,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,2BAA2B,GACnC,IAAI,CAQN"}

package/dist/converter/gd-to-ts/inject-imports.js

@@ -0,0 +1,161 @@
+/**
+ * Batch-level import injection for GD→TS conversion.
+ *
+ * Runs AFTER every `.gd` source has been converted and written to
+ * disk. Builds a real TS program over the generated `.ts` files,
+ * pulls semantic diagnostics, and prepends `import { Foo } from "./foo.js"`
+ * lines for every unresolved identifier that maps to a known user
+ * class. Much more precise than the previous per-file regex — names
+ * appearing only inside comments or string literals don't trigger
+ * a TS 2304/2503 diagnostic, so they don't produce phantom imports.
+ *
+ * No-op when `generateGlobalClassTypes` is `true` (the addon /
+ * legacy-global layout, where every user class is in `declare global`
+ * and no imports are required).
+ */
+import ts from 'typescript';
+import { readFileSync, writeFileSync } from 'fs';
+import { dirname, relative, resolve } from 'path';
+import { createTsProgram } from "../../parser/typescript/index.js";
+import { parseGdClassInfo } from "./index.js";
+/** TS error code for "Cannot find name 'X'." */
+const TS_CANNOT_FIND_NAME = 2304;
+/** TS error code for "Cannot find namespace 'X'." */
+const TS_CANNOT_FIND_NAMESPACE = 2503;
+/**
+ * For every `.ts` file in `files`, prepend `import { X } from "..."`
+ * lines for any TS 2304/2503 diagnostic whose name resolves to a
+ * known entry in `userClasses`. Files are rewritten in place. Files
+ * with nothing missing are left untouched.
+ */
+export function injectMissingImports(files, userClasses, options) {
+    if (options.generateGlobalClassTypes)
+        return;
+    if (files.length === 0)
+        return;
+    // The TS program needs every generated file as a root file; otherwise
+    // it won't parse them and we won't see their diagnostics. `rootDir`
+    // is just used by the compiler options for moduleResolution context;
+    // the common ancestor of the generated files is a safe choice.
+    const rootDir = commonDir(files.map((f) => f.tsPath));
+    const program = createTsProgram({
+        rootDir,
+        files: files.map((f) => f.tsPath),
+        tsConfigPath: options.tsConfigPath,
+    });
+    // Build a `gdPath → tsPath` lookup so we can resolve a missing
+    // user class's *actual* on-disk TS file (not just the gd path with
+    // its extension swapped). Crucial when `cfg.gdDir != cfg.tsDir` —
+    // the gd and ts trees diverge and the TS file lives in `tsDir`,
+    // not next to the gd source. Falls back to the extension-swap for
+    // user classes whose `.gd` was outside the converted batch (rare,
+    // and the resulting import is best-effort anyway).
+    const gdToTs = new Map();
+    for (const f of files) {
+        gdToTs.set(normalizePath(f.gdPath), f.tsPath);
+    }
+    for (const file of files) {
+        const sourceFile = program.getSourceFile(file.tsPath);
+        if (!sourceFile)
+            continue;
+        const diags = program.getSemanticDiagnostics(sourceFile);
+        const missing = collectMissingClassNames(diags, userClasses, file);
+        if (missing.size === 0)
+            continue;
+        // Stable alphabetical order — matches the prior regex-based
+        // implementation and keeps diffs predictable across runs.
+        const sortedNames = Array.from(missing).sort();
+        const importLines = sortedNames.map((name) => {
+            const info = userClasses.get(name);
+            const targetTsPath = gdToTs.get(normalizePath(info.filePath)) ??
+                info.filePath.replace(/\.gd$/, '.ts');
+            const specifier = importSpecifierFor(file.tsPath, targetTsPath);
+            return `import { ${name} } from "${specifier}";`;
+        });
+        const original = readFileSync(file.tsPath, 'utf-8');
+        const updated = importLines.join('\n') + '\n\n' + original;
+        writeFileSync(file.tsPath, updated);
+    }
+}
+/**
+ * Convenience wrapper: build the user-class index from a list of GD
+ * sources (the same shape `convertGdToTs` consumes via
+ * `projectSources`), then call {@link injectMissingImports}. Mirrors
+ * what the `initial-convert-gd-to-ts` CLI command needs to do for a full project run.
+ */
+export function injectMissingImportsForProject(files, projectSources, registry, options) {
+    if (options.generateGlobalClassTypes)
+        return;
+    const userClasses = new Map();
+    for (const ps of projectSources) {
+        const info = parseGdClassInfo(ps.source, registry, ps.filePath);
+        if (info)
+            userClasses.set(info.name, info);
+    }
+    injectMissingImports(files, userClasses, options);
+}
+// ─── Helpers ────────────────────────────────────────────────
+function collectMissingClassNames(diags, userClasses, file) {
+    const out = new Set();
+    for (const d of diags) {
+        if (d.code !== TS_CANNOT_FIND_NAME && d.code !== TS_CANNOT_FIND_NAMESPACE) {
+            continue;
+        }
+        const message = ts.flattenDiagnosticMessageText(d.messageText, '\n');
+        // TS phrases both diagnostics as `Cannot find name 'X'.` /
+        // `Cannot find namespace 'X'.`. Pull the quoted identifier.
+        const m = message.match(/'([^']+)'/);
+        if (!m)
+            continue;
+        const name = m[1];
+        const info = userClasses.get(name);
+        if (!info?.filePath)
+            continue; // unknown class — not ours to fix
+        if (sameFile(info.filePath, file.gdPath))
+            continue; // self
+        out.add(name);
+    }
+    return out;
+}
+/**
+ * Build the import specifier for `import { X } from "..."` referencing
+ * `targetTs` from `currentTs`. Project default is
+ * `moduleResolution: "classic"` (set by the `tstogd init` template),
+ * which resolves bare-name specifiers via the `.ts` extension search
+ * order — so we strip the trailing `.ts` and emit no extension at all.
+ * `relative()` returns a bare filename for siblings, so we also force
+ * a leading `./` to keep TypeScript from treating the specifier as
+ * a non-relative module.
+ */
+function importSpecifierFor(currentTs, targetTs) {
+    let rel = relative(dirname(currentTs), targetTs).replace(/\\/g, '/');
+    if (!rel.startsWith('.') && !rel.startsWith('/'))
+        rel = './' + rel;
+    return rel.replace(/\.ts$/, '');
+}
+function sameFile(a, b) {
+    return normalizePath(a) === normalizePath(b);
+}
+/** Absolutize + normalize separators so paths can be used as Map keys. */
+function normalizePath(p) {
+    return resolve(p).replace(/\\/g, '/');
+}
+/**
+ * Longest common parent directory of the given absolute paths. Used
+ * as the TS program's `rootDir` so module-resolution behaves naturally
+ * for the generated tree. Returns `'/'` (or drive root on Windows)
+ * when the paths share no meaningful prefix.
+ */
+function commonDir(paths) {
+    if (paths.length === 0)
+        return '';
+    const parts = paths.map((p) => p.replace(/\\/g, '/').split('/'));
+    let i = 0;
+    while (i < parts[0].length && parts.every((p) => p[i] === parts[0][i])) {
+        i++;
+    }
+    // Drop the trailing basename component so `rootDir` is a directory.
+    const dirParts = parts[0].slice(0, Math.max(0, i));
+    return dirParts.join('/') || '/';
+}
+//# sourceMappingURL=inject-imports.js.map

package/dist/converter/gd-to-ts/inject-imports.js.map

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

package/dist/converter/gd-to-ts/members.d.ts

@@ -0,0 +1,15 @@
+import { type SyntaxNode } from '../../parser/gdscript/types.ts';
+import type { GdToTsContext } from './context.ts';
+/** Convert a triple-quoted GDScript string to a JS block comment */
+export declare function emitBlockComment(text: string, indent: string): string;
+export declare function emitComment(node: SyntaxNode): string;
+export declare function emitCommentInline(node: SyntaxNode): string;
+export declare function emitSignal(node: SyntaxNode, ctx: GdToTsContext): string;
+export declare function emitSignalParamTypes(paramsNode: SyntaxNode, ctx: GdToTsContext): string;
+export declare function emitEnum(node: SyntaxNode, ctx: GdToTsContext): string;
+export declare function emitClassVariable(node: SyntaxNode, ctx: GdToTsContext): string;
+export declare function emitLocalVariable(node: SyntaxNode, ctx: GdToTsContext, indent: string): string;
+export declare function emitTypeAnnotation(typeNode: SyntaxNode, ctx: GdToTsContext): string;
+export declare function getAnnotations(node: SyntaxNode): SyntaxNode[];
+export declare function emitAnnotationAsDecorator(node: SyntaxNode, ctx: GdToTsContext): string;
+//# sourceMappingURL=members.d.ts.map

package/dist/converter/gd-to-ts/members.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"members.d.ts","sourceRoot":"","sources":["../../../src/converter/gd-to-ts/members.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAalD,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAsBrE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAUpD;AAID,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAQ1D;AAID,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,aAAa,GAAG,MAAM,CAUvE;AAED,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,UAAU,EACtB,GAAG,EAAE,aAAa,GACjB,MAAM,CAcR;AAID,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,aAAa,GAAG,MAAM,CA0BrE;AAID,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,aAAa,GACjB,MAAM,CAoCR;AA8QD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,GACb,MAAM,CAoBR;AAID,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,UAAU,EACpB,GAAG,EAAE,aAAa,GACjB,MAAM,CAuBR;AAID,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,EAAE,CAY7D;AAED,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,aAAa,GACjB,MAAM,CAoBR"}