@defold-typescript/transpiler 0.52.0 → 0.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "TypeScript-to-Lua build pipeline tuned for Defold's runtime.",
   "license": "MIT",
   "repository": {
@@ -35,9 +35,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/types": "0.52.0",
+    "@defold-typescript/types": "0.53.0",
     "@typescript-to-lua/language-extensions": "1.19.0",
     "typescript": "6.0.2",
     "typescript-to-lua": "^1.36.0"
+  },
+  "devDependencies": {
+    "lua-wasm-bindings": "0.5.3"
   }
 }

package/src/companion-closure.ts

@@ -1,4 +1,5 @@
 import * as ts from "typescript";
+import { findManagedBootstrap } from "./debug-bootstrap";
 import { resolvesToFactoryExport } from "./lifecycle-erasure";
 
 /**
@@ -49,6 +50,13 @@ export interface CompanionClosure {
    * companion takes its own `require` of the same module instead.
    */
   readonly importBindings: readonly string[];
+  /**
+   * The unedited `setup-debug` managed block's statements, in source order, or
+   * empty. They are exempt from the order rule because the emit runs them ahead
+   * of the companion's `require`, so the debugger starts before anything the
+   * companion loads.
+   */
+  readonly bootstrap: readonly ts.Statement[];
   /** Shapes a split cannot preserve. Empty means the source is splittable. */
   readonly violations: readonly ClosureViolation[];
 }
@@ -717,11 +725,20 @@ export function computeCompanionClosure(
     });
   }
 
+  const managed = findManagedBootstrap(sourceFile);
+  const bootstrap = managed?.canonical === true ? managed.statements : [];
+  const editedBlock = new Set(managed?.canonical === false ? managed.statements : []);
+  const exempt = new Set(bootstrap);
+
   // The companion loads as a unit, so the constraint is pairwise: any effectful
   // script statement with any closure declaration below it is reordered by the
   // split, whatever the first member's position.
   for (const statement of sourceFile.statements) {
-    if (closureStatements.has(statement) || isEffectFreeStatement(statement, checker)) {
+    if (
+      closureStatements.has(statement) ||
+      exempt.has(statement) ||
+      isEffectFreeStatement(statement, checker)
+    ) {
       continue;
     }
     const start = statement.getStart(sourceFile);
@@ -735,14 +752,18 @@ export function computeCompanionClosure(
       siteOf(statement, "runs in the script"),
       siteOf(hoisted.declaration.node, "moves into the companion"),
     ];
+    const name = hoisted.declaration.name;
     violations.push({
       kind: "initialization-order",
-      member: hoisted.declaration.name,
+      member: name,
       sites,
-      message:
-        `top-level work precedes "${hoisted.declaration.name}", which the companion would run first, ` +
-        `reversing their order (${formatSites(sites)}). ` +
-        "Move that work below the companion's declarations, or into a lifecycle hook.",
+      message: editedBlock.has(statement)
+        ? `the setup-debug managed block was edited and now runs top-level work before "${name}", ` +
+          `which the companion would run first (${formatSites(sites)}). ` +
+          "Run `defold-typescript setup-debug` to restore the block."
+        : `top-level work precedes "${name}", which the companion would run first, ` +
+          `reversing their order (${formatSites(sites)}). ` +
+          "Move that work below the companion's declarations, or into a lifecycle hook.",
     });
   }
 
@@ -756,6 +777,7 @@ export function computeCompanionClosure(
     internals: ordered
       .filter(({ symbol }) => !exportSet.has(symbol) && scriptReferences.has(symbol))
       .map(({ declaration }) => declaration.name),
+    bootstrap,
     violations,
   };
 }

package/src/companion-emit.ts

@@ -66,6 +66,8 @@ function isRuntimeScriptSource(sourceFile: ts.SourceFile, checker: ts.TypeChecke
 interface CompanionPlan {
   /** Full start of each top-level statement the companion takes over. */
   readonly closureStarts: ReadonlySet<number>;
+  /** Full start of each unedited `setup-debug` block statement. */
+  readonly bootstrapStarts: ReadonlySet<number>;
   /** Members the script reaches by bare name, which the companion must expose. */
   readonly internals: readonly string[];
   /** Import bindings the companion needs its own `require` of. */
@@ -86,6 +88,7 @@ function planFor(sourceFile: ts.SourceFile, checker: ts.TypeChecker): CompanionP
   }
   return {
     closureStarts: new Set(closure.statements.map((statement) => statement.pos)),
+    bootstrapStarts: new Set(closure.bootstrap.map((statement) => statement.pos)),
     internals: closure.internals,
     importBindings: closure.importBindings,
     requirePath: requirePathForRel(sourceFile.fileName),
@@ -466,6 +469,10 @@ interface SplitHalves {
  * first. The run stops at the first statement that reads the companion, and at
  * the first non-declaration — a lifecycle hook closes over the internals it
  * reads, so its declaration must precede the hook's.
+ *
+ * The `setup-debug` block's gate is taken out of `script` before this runs and
+ * placed immediately ahead of the `require`, so the debugger starts before any
+ * companion code does while `lldebugger` itself is still required above it.
  */
 function requireInsertionPoint(script: readonly Statement[], reads: ReadonlySet<string>): number {
   let index = 0;
@@ -524,6 +531,7 @@ export interface CompanionEmitter {
 export function createCompanionEmitPlugin(): CompanionEmitter {
   const plans = new Map<string, CompanionPlan | undefined>();
   const owned = new Map<string, Set<Statement>>();
+  const bootstraps = new Map<string, Set<Statement>>();
   const companions = new Map<string, string>();
 
   function planOf(sourceFile: ts.SourceFile, checker: ts.TypeChecker): CompanionPlan | undefined {
@@ -552,6 +560,24 @@ export function createCompanionEmitPlugin(): CompanionEmitter {
     return statements;
   }
 
+  function captureBootstrap(node: ts.IfStatement, context: TransformationContext): Statement[] {
+    const statements = context.superTransformStatements(node);
+    const sourceFile = context.sourceFile;
+    const plan = planOf(sourceFile, context.checker);
+    if (plan === undefined || !plan.bootstrapStarts.has(node.pos)) {
+      return statements;
+    }
+    let bucket = bootstraps.get(sourceFile.fileName);
+    if (bucket === undefined) {
+      bucket = new Set();
+      bootstraps.set(sourceFile.fileName, bucket);
+    }
+    for (const statement of statements) {
+      bucket.add(statement);
+    }
+    return statements;
+  }
+
   const visitors: Plugin["visitors"] = {
     [ts.SyntaxKind.VariableStatement]: capture,
     [ts.SyntaxKind.FunctionDeclaration]: capture,
@@ -561,6 +587,7 @@ export function createCompanionEmitPlugin(): CompanionEmitter {
     // because TSTL emits its `require` bindings through its own hoisting. The
     // companion takes a copy of that prelude instead — see `copiedPrelude`.
     [ts.SyntaxKind.ExportDeclaration]: capture,
+    [ts.SyntaxKind.IfStatement]: captureBootstrap,
   };
 
   let configuredNoResolvePaths: readonly string[] = [];
@@ -582,7 +609,8 @@ export function createCompanionEmitPlugin(): CompanionEmitter {
         if (plan === undefined || bucket === undefined || bucket.size === 0) {
           continue;
         }
-        emitCompanion(program, emitHost, file, sourceFile, plan, bucket, companions);
+        const bootstrap = bootstraps.get(sourceFile.fileName) ?? new Set();
+        emitCompanion(program, emitHost, file, sourceFile, plan, bucket, bootstrap, companions);
         emitted.push(plan.requirePath);
       }
       // The companion is written by the CLI, not by TSTL's emit plan, so TSTL's
@@ -606,6 +634,7 @@ function emitCompanion(
   sourceFile: ts.SourceFile,
   plan: CompanionPlan,
   owned: ReadonlySet<Statement>,
+  bootstrap: ReadonlySet<Statement>,
   companions: Map<string, string>,
 ): void {
   const luaAst = file.luaAst;
@@ -644,9 +673,11 @@ function emitCompanion(
   ];
 
   const reads = new Set([EXPORTS_NAME, ...plan.internals]);
-  const insertAt = requireInsertionPoint(halves.script, reads);
+  const rest = halves.script.filter((statement) => !bootstrap.has(statement));
+  const insertAt = requireInsertionPoint(rest, reads);
   const scriptStatements: Statement[] = [
-    ...halves.script.slice(0, insertAt),
+    ...rest.slice(0, insertAt),
+    ...halves.script.filter((statement) => bootstrap.has(statement)),
     createVariableDeclarationStatement(
       exportsIdentifier(),
       createCallExpression(createIdentifier("require"), [createStringLiteral(plan.requirePath)]),
@@ -654,7 +685,7 @@ function emitCompanion(
     ...plan.internals.map((name) =>
       createVariableDeclarationStatement(createIdentifier(name), internalsField(name)),
     ),
-    ...halves.script.slice(insertAt),
+    ...rest.slice(insertAt),
     createReturnStatement([exportsIdentifier()]),
   ];
 

package/src/debug-bootstrap.ts

@@ -0,0 +1,88 @@
+import * as ts from "typescript";
+
+// Managed-block sentinels. A re-run locates the single BEGIN…END pair and
+// refreshes the enclosed text if it drifted, so wording changes self-heal.
+// They are `//` line comments, stripped by TSTL, so they never reach the
+// emitted `.ts.script`.
+export const DEBUG_BLOCK_BEGIN =
+  "// defold-typescript:setup-debug BEGIN — managed block, do not edit";
+export const DEBUG_BLOCK_END = "// defold-typescript:setup-debug END";
+
+// The canonical managed block: import + gated start, marker-free, no
+// `declare module` (that lives in the ambient `.d.ts`). Mirrors the snippet in
+// `packages/docs/guide/debugging.md` exactly; a guide-comparison test locks the two.
+// The blank line before END keeps Biome's organizeImports assist from gluing
+// the END comment onto a following import as its leading comment (which would
+// then demand a blank line before the whole group). With blank lines on both
+// sides of END, an import injected above the user's own imports stays clean.
+export const DEBUG_MANAGED_BLOCK = `${DEBUG_BLOCK_BEGIN}
+import * as lldebugger from "lldebugger.debug";
+
+if (sys.get_engine_info().is_debug) {
+  lldebugger.start();
+}
+
+${DEBUG_BLOCK_END}`;
+
+export interface ManagedBootstrap {
+  /** The top-level statements wholly between the sentinels, in source order. */
+  readonly statements: readonly ts.Statement[];
+  /**
+   * Whether the text between the sentinels is the canonical body token for
+   * token, so line endings, quote style, comments and optional semicolons never
+   * decide it.
+   */
+  readonly canonical: boolean;
+}
+
+function occurrences(haystack: string, needle: string): number {
+  return haystack.split(needle).length - 1;
+}
+
+function bodyTokens(text: string): string[] {
+  const scanner = ts.createScanner(ts.ScriptTarget.Latest, true, ts.LanguageVariant.Standard, text);
+  const tokens: string[] = [];
+  for (let kind = scanner.scan(); kind !== ts.SyntaxKind.EndOfFileToken; kind = scanner.scan()) {
+    if (kind === ts.SyntaxKind.SemicolonToken) {
+      continue;
+    }
+    const spelling =
+      kind === ts.SyntaxKind.StringLiteral ? scanner.getTokenValue() : scanner.getTokenText();
+    tokens.push(`${kind}:${spelling}`);
+  }
+  return tokens;
+}
+
+const CANONICAL_BODY_TOKENS = bodyTokens(
+  DEBUG_MANAGED_BLOCK.slice(
+    DEBUG_BLOCK_BEGIN.length,
+    DEBUG_MANAGED_BLOCK.length - DEBUG_BLOCK_END.length,
+  ),
+);
+
+/**
+ * The `setup-debug` managed block in a source, located the way
+ * `upsertManagedBlock` locates it: exactly one BEGIN and one END, BEGIN first.
+ * Any other sentinel shape is one `setup-debug` itself refuses to edit, so it
+ * is not a managed block at all.
+ */
+export function findManagedBootstrap(sourceFile: ts.SourceFile): ManagedBootstrap | undefined {
+  const text = sourceFile.text;
+  if (occurrences(text, DEBUG_BLOCK_BEGIN) !== 1 || occurrences(text, DEBUG_BLOCK_END) !== 1) {
+    return undefined;
+  }
+  const beginAt = text.indexOf(DEBUG_BLOCK_BEGIN);
+  const endAt = text.indexOf(DEBUG_BLOCK_END);
+  if (endAt < beginAt) {
+    return undefined;
+  }
+  const bodyStart = beginAt + DEBUG_BLOCK_BEGIN.length;
+  const statements = sourceFile.statements.filter(
+    (statement) => statement.getStart(sourceFile) >= bodyStart && statement.end <= endAt,
+  );
+  const tokens = bodyTokens(text.slice(bodyStart, endAt));
+  const canonical =
+    tokens.length === CANONICAL_BODY_TOKENS.length &&
+    tokens.every((token, index) => token === CANONICAL_BODY_TOKENS[index]);
+  return { statements, canonical };
+}

package/src/index.ts

@@ -11,6 +11,13 @@ export {
   componentIdOfSameObjectAddress,
 } from "./component-animation-index";
 export { buildConfigKeyIndex, readGameProjectSetting } from "./config-key-index";
+export type { ManagedBootstrap } from "./debug-bootstrap";
+export {
+  DEBUG_BLOCK_BEGIN,
+  DEBUG_BLOCK_END,
+  DEBUG_MANAGED_BLOCK,
+  findManagedBootstrap,
+} from "./debug-bootstrap";
 export { findEmittedRequires, LUALIB_REQUIRE_NAME } from "./emitted-requires";
 export type { GuiFlipbookIndex } from "./gui-flipbook-index";
 export { buildGuiFlipbookIndex } from "./gui-flipbook-index";