@defold-typescript/cli 0.1.0

package/src/materialize.ts

@@ -0,0 +1,224 @@
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import * as path from "node:path";
+import {
+  loadApiTargetsRegistry,
+  type RegistryTarget,
+  resolveTypesPackageRoot,
+} from "./api-registry";
+import type { SelectedApiSurface } from "./api-surface";
+import { excludedModulesForKind, type ScriptKind } from "./script-kind";
+
+const MATERIALIZED_ROOT = ".defold-types";
+
+export interface MaterializeApiSurfaceOptions {
+  readonly cwd: string;
+  readonly surface: SelectedApiSurface;
+  readonly sourceGeneratedDir: string | null;
+  readonly scriptKind?: ScriptKind | null;
+}
+
+export interface MaterializeApiSurfaceResult {
+  readonly materializedDir: string | null;
+  readonly active: string | null;
+}
+
+function writeJson(filePath: string, value: unknown): void {
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function listDts(dir: string): string[] {
+  return readdirSync(dir)
+    .filter((file) => file.endsWith(".d.ts"))
+    .sort();
+}
+
+export function materializeApiSurface(
+  opts: MaterializeApiSurfaceOptions,
+): MaterializeApiSurfaceResult {
+  const { cwd, surface, sourceGeneratedDir } = opts;
+  if (!surface.available || surface.surfaceId === null || sourceGeneratedDir === null) {
+    return { materializedDir: null, active: null };
+  }
+
+  const { surfaceId } = surface;
+  const relDir = path.posix.join(MATERIALIZED_ROOT, surfaceId);
+  const absDir = path.join(cwd, MATERIALIZED_ROOT, surfaceId);
+  mkdirSync(absDir, { recursive: true });
+
+  const excluded = excludedModulesForKind(opts.scriptKind ?? null);
+  const sources = listDts(sourceGeneratedDir)
+    .filter((file) => file !== "index.d.ts")
+    .filter((file) => !excluded.has(file.replace(/\.d\.ts$/, "")));
+
+  // The `*-overloads` augmentations and the `core-types` they import live in the
+  // types package `src/` (sibling of `generated/`), not among the generated
+  // module surfaces. Mirror the per-kind entrypoints, which import them so that
+  // `msg.post`, `go.get`/`set`, etc. resolve; without this the materialized
+  // surface silently drops those globals. Skipped when the source has no
+  // sibling `src/` (e.g. synthetic test fixtures).
+  const srcDir = path.resolve(sourceGeneratedDir, "..", "src");
+  const overloads = ["msg-overloads.d.ts", "go-overloads.d.ts"].filter((file) =>
+    existsSync(path.join(srcDir, file)),
+  );
+  const coreTypesSrc = path.join(srcDir, "core-types.ts");
+  const includeCoreTypes = overloads.length > 0 && existsSync(coreTypesSrc);
+
+  const wanted = new Set(sources);
+  for (const file of overloads) {
+    wanted.add(file);
+  }
+  if (includeCoreTypes) {
+    wanted.add("core-types.d.ts");
+  }
+
+  for (const existing of readdirSync(absDir)) {
+    if (existing.endsWith(".d.ts") && existing !== "index.d.ts" && !wanted.has(existing)) {
+      rmSync(path.join(absDir, existing));
+    }
+  }
+
+  for (const file of sources) {
+    writeFileSync(
+      path.join(absDir, file),
+      readFileSync(path.join(sourceGeneratedDir, file), "utf8"),
+    );
+  }
+  if (includeCoreTypes) {
+    writeFileSync(path.join(absDir, "core-types.d.ts"), readFileSync(coreTypesSrc, "utf8"));
+  }
+  for (const file of overloads) {
+    writeFileSync(path.join(absDir, file), readFileSync(path.join(srcDir, file), "utf8"));
+  }
+
+  const modules = [...sources, ...overloads].map((file) => file.replace(/\.d\.ts$/, ""));
+  const imports = modules.map((mod) => `import "./${mod}";`).join("\n");
+  writeFileSync(path.join(absDir, "index.d.ts"), `${imports}\n\nexport {};\n`);
+
+  writeJson(path.join(absDir, "package.json"), {
+    name: `@defold-typescript/materialized-${surfaceId}`,
+    types: "index.d.ts",
+  });
+
+  return { materializedDir: relDir, active: surfaceId };
+}
+
+function ensureGitignoreLine(cwd: string, line: string): void {
+  const gitignorePath = path.join(cwd, ".gitignore");
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, `${line}\n`);
+    return;
+  }
+  const existing = readFileSync(gitignorePath, "utf8");
+  const present = new Set(existing.split("\n").map((entry) => entry.trim()));
+  if (present.has(line)) {
+    return;
+  }
+  const prefix = existing.endsWith("\n") || existing === "" ? "" : "\n";
+  writeFileSync(gitignorePath, `${existing}${prefix}${line}\n`);
+}
+
+export function ensureMaterializedReference(cwd: string, materializedDir: string | null): void {
+  if (materializedDir === null) {
+    return;
+  }
+  const surfaceId = path.posix.basename(materializedDir);
+
+  const tsconfigPath = path.join(cwd, "tsconfig.json");
+  if (existsSync(tsconfigPath)) {
+    const tsconfig = JSON.parse(readFileSync(tsconfigPath, "utf8")) as {
+      compilerOptions?: Record<string, unknown>;
+      [key: string]: unknown;
+    };
+    tsconfig.compilerOptions = {
+      ...(tsconfig.compilerOptions ?? {}),
+      typeRoots: [MATERIALIZED_ROOT],
+      types: [surfaceId],
+    };
+    writeJson(tsconfigPath, tsconfig);
+  }
+
+  ensureGitignoreLine(cwd, `${MATERIALIZED_ROOT}/`);
+}
+
+export function resolveCurrentSurfaceGeneratedDir(): string | null {
+  const root = resolveTypesPackageRoot();
+  return root === null ? null : path.join(root, "generated");
+}
+
+export interface RefDocResolveOptions {
+  readonly cacheDir?: string;
+  readonly download?: (version: string) => Promise<Uint8Array>;
+  readonly readZip?: (zipPath: string) => unknown;
+}
+
+interface MaterializeVersionedSurfaceModule {
+  readonly materializeVersionedSurface: (
+    target: unknown,
+    opts: {
+      destDir: string;
+      resolveOpts?: RefDocResolveOptions;
+      excludeModules?: readonly string[];
+    },
+  ) => Promise<void>;
+}
+
+export interface MaterializeRefDocSurfaceOptions {
+  readonly cwd: string;
+  readonly surfaceId: string;
+  readonly resolveOpts?: RefDocResolveOptions;
+  readonly scriptKind?: ScriptKind | null;
+  // Registry override (defaults to the installed types package's
+  // api-targets.json). Injected only by tests that need a multi-module ref-doc
+  // target to observe kind narrowing.
+  readonly registry?: readonly RegistryTarget[];
+}
+
+// Generate a pinned, ref-doc-sourced surface on the fly into the project's
+// `.defold-types/<id>/`. The generator (`materializeVersionedSurface`) ships in
+// the `@defold-typescript/types` tarball; it is imported by resolved path so the
+// `current` build path never pulls in its fixture-reading module side effects.
+// The faux package is made self-contained by emitting core-type imports as a
+// sibling `./core-types` and copying `core-types.d.ts` in, so the surface
+// resolves from a real `.defold-types/<id>/` regardless of dest depth.
+export async function materializeRefDocSurface(
+  opts: MaterializeRefDocSurfaceOptions,
+): Promise<MaterializeApiSurfaceResult> {
+  const { cwd, surfaceId, resolveOpts } = opts;
+  const root = resolveTypesPackageRoot();
+  if (root === null) {
+    return { materializedDir: null, active: null };
+  }
+  const registry = opts.registry ?? loadApiTargetsRegistry();
+  const target = registry.find((t) => t.id === surfaceId);
+  if (!target || target.source?.kind !== "ref-doc") {
+    return { materializedDir: null, active: null };
+  }
+  const excludeModules = [...excludedModulesForKind(opts.scriptKind ?? null)];
+
+  const relDir = path.posix.join(MATERIALIZED_ROOT, surfaceId);
+  const absDir = path.join(cwd, MATERIALIZED_ROOT, surfaceId);
+  try {
+    const mod = (await import(
+      path.join(root, "scripts", "materialize-version.ts")
+    )) as MaterializeVersionedSurfaceModule;
+    const selfContained = { ...target, coreTypesImport: "./core-types" };
+    await mod.materializeVersionedSurface(selfContained, {
+      destDir: absDir,
+      ...(resolveOpts ? { resolveOpts } : {}),
+      ...(excludeModules.length > 0 ? { excludeModules } : {}),
+    });
+    copyFileSync(path.join(root, "src", "core-types.ts"), path.join(absDir, "core-types.d.ts"));
+  } catch {
+    rmSync(absDir, { recursive: true, force: true });
+    return { materializedDir: null, active: null };
+  }
+  return { materializedDir: relDir, active: surfaceId };
+}

package/src/ref-doc-test-fixture.ts

@@ -0,0 +1,92 @@
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { RegistryTarget } from "./api-registry";
+
+const LABEL_FIXTURE = path.resolve(import.meta.dir, "../../types/fixtures/label_doc.json");
+const TYPES_FIXTURES = path.resolve(import.meta.dir, "../../types/fixtures");
+
+interface FakeZip {
+  has: (entry: string) => boolean;
+  read: (entry: string) => string;
+}
+
+// namespace -> ref-doc.zip entry for the multi-kind fixture. Mirrors the
+// types-package SYNC_MANIFEST so the fake zip serves docs under the same keys
+// `resolveTargetModules` reads.
+const MULTI_KIND_ZIP_ENTRIES: Record<string, string> = {
+  gui: "doc/gui_script.cpp_doc.json",
+  render: "doc/render-render_script.cpp_doc.json",
+  sprite: "doc/scripts-script_sprite.cpp_doc.json",
+};
+
+export const noDownload = async (): Promise<Uint8Array> => {
+  throw new Error("download should not be called");
+};
+
+// Offline ref-doc resolve options for the `defold-1.9.8` (label-only) target: a
+// seeded cache pointing at an in-memory zip that serves the committed label
+// fixture. Only `label` is resolved, so the fake zip ignores the entry key.
+export function labelRefDocResolveOpts(): {
+  cacheDir: string;
+  readZip: () => FakeZip;
+  download: typeof noDownload;
+} {
+  const version = "1.9.8";
+  const json = readFileSync(LABEL_FIXTURE, "utf8");
+  const fakeZip: FakeZip = {
+    has: () => true,
+    read: () => json,
+  };
+  const cacheDir = mkdtempSync(path.join(os.tmpdir(), "defold-typescript-ref-doc-"));
+  mkdirSync(path.join(cacheDir, version), { recursive: true });
+  writeFileSync(path.join(cacheDir, version, "ref-doc.zip"), "seeded");
+  return { cacheDir, readZip: () => fakeZip, download: noDownload };
+}
+
+// Offline ref-doc resolve options for a multi-namespace target serving a
+// restricted-pair (`gui`, `render`) plus a universal module (`sprite`), so a
+// kind-narrowed materialization can be observed (the forbidden namespace's
+// `.d.ts` drops out while the universal one stays).
+export function multiKindRefDocResolveOpts(): {
+  cacheDir: string;
+  readZip: () => FakeZip;
+  download: typeof noDownload;
+} {
+  const version = "1.9.8";
+  const docs: Record<string, string> = {};
+  for (const [namespace, zipEntry] of Object.entries(MULTI_KIND_ZIP_ENTRIES)) {
+    docs[zipEntry] = readFileSync(path.join(TYPES_FIXTURES, `${namespace}_doc.json`), "utf8");
+  }
+  const fakeZip: FakeZip = {
+    has: (entry) => entry in docs,
+    read: (entry) => {
+      const doc = docs[entry];
+      if (doc === undefined) throw new Error(`unexpected zip entry ${entry}`);
+      return doc;
+    },
+  };
+  const cacheDir = mkdtempSync(path.join(os.tmpdir(), "defold-typescript-ref-doc-"));
+  mkdirSync(path.join(cacheDir, version), { recursive: true });
+  writeFileSync(path.join(cacheDir, version, "ref-doc.zip"), "seeded");
+  return { cacheDir, readZip: () => fakeZip, download: noDownload };
+}
+
+// A registry-shaped `defold-1.9.8` ref-doc target carrying the multi-kind
+// module trio, for injecting into `materializeRefDocSurface`/`dispatch` so the
+// real (label-only) registry entry need not be mutated to prove narrowing.
+export function multiKindRefDocTarget(): RegistryTarget {
+  return {
+    id: "defold-1.9.8",
+    default: false,
+    fixturesDir: "fixtures",
+    generatedDir: "generated",
+    coreTypesImport: "../src/core-types",
+    source: { kind: "ref-doc", version: "1.9.8" },
+    modules: [
+      { namespace: "gui", fixture: "gui_doc.json", outFile: "gui.d.ts" },
+      { namespace: "render", fixture: "render_doc.json", outFile: "render.d.ts" },
+      { namespace: "sprite", fixture: "sprite_doc.json", outFile: "sprite.d.ts" },
+    ],
+  };
+}

package/src/scan.ts

@@ -0,0 +1,10 @@
+import { globSync, statSync } from "node:fs";
+import * as path from "node:path";
+
+// `Bun.Glob` is undefined when the published bin runs under plain node, so the
+// scaffold/build path must use the cross-runtime `node:fs` glob instead. Bun's
+// `globSync` does not support `withFileTypes`, so directories are filtered out
+// with a stat to preserve the original `onlyFiles` contract.
+export function scanFilesSync(cwd: string, pattern: string): string[] {
+  return globSync(pattern, { cwd }).filter((rel) => statSync(path.join(cwd, rel)).isFile());
+}

package/src/script-kind.ts

@@ -0,0 +1,68 @@
+import { scanFilesSync } from "./scan";
+
+export type ScriptKind = "script" | "gui-script" | "render-script";
+
+export const DEFAULT_TYPES_ENTRYPOINT = "@defold-typescript/types";
+
+const KIND_BY_EXT: Record<string, ScriptKind> = {
+  ".script": "script",
+  ".gui_script": "gui-script",
+  ".render_script": "render-script",
+};
+
+const SKIP_SEGMENTS = new Set(["node_modules", ".defold-types", "build"]);
+
+export function isSkipped(relPath: string): boolean {
+  return relPath.split(/[/\\]/).some((segment) => SKIP_SEGMENTS.has(segment));
+}
+
+export function isComponentPath(relPath: string): boolean {
+  return Object.keys(KIND_BY_EXT).some((ext) => relPath.endsWith(ext));
+}
+
+export function detectScriptKinds(cwd: string): Set<ScriptKind> {
+  const kinds = new Set<ScriptKind>();
+  for (const [ext, kind] of Object.entries(KIND_BY_EXT)) {
+    for (const match of scanFilesSync(cwd, `**/*${ext}`)) {
+      if (!isSkipped(match)) {
+        kinds.add(kind);
+        break;
+      }
+    }
+  }
+  return kinds;
+}
+
+export function selectScriptKind(kinds: Set<ScriptKind>): ScriptKind | null {
+  if (kinds.size !== 1) {
+    return null;
+  }
+  for (const kind of kinds) {
+    return kind;
+  }
+  return null;
+}
+
+export function selectScriptKindEntrypoint(kinds: Set<ScriptKind>): string {
+  const kind = selectScriptKind(kinds);
+  return kind === null ? DEFAULT_TYPES_ENTRYPOINT : `${DEFAULT_TYPES_ENTRYPOINT}/${kind}`;
+}
+
+// The one restricted namespace each kind allows; mirrors `regen.ts`'s
+// RESTRICTED_NAMESPACES (gui -> gui_script, render -> render_script). `script`
+// allows neither.
+const RESTRICTED_MODULES: Record<ScriptKind, string> = {
+  script: "",
+  "gui-script": "gui",
+  "render-script": "render",
+};
+
+const ALL_RESTRICTED_MODULES: readonly string[] = ["gui", "render"];
+
+export function excludedModulesForKind(kind: ScriptKind | null): Set<string> {
+  if (kind === null) {
+    return new Set();
+  }
+  const allowed = RESTRICTED_MODULES[kind];
+  return new Set(ALL_RESTRICTED_MODULES.filter((mod) => mod !== allowed));
+}

package/src/watch.ts

@@ -0,0 +1,185 @@
+import { existsSync, watch as fsWatch } from "node:fs";
+import * as path from "node:path";
+import { toPosix } from "./build-output";
+import { type BuildSession, createBuildSession } from "./build-session";
+import { isComponentPath, isSkipped } from "./script-kind";
+
+export interface WatchEvent {
+  readonly kind: "change" | "rename";
+  readonly path: string;
+}
+
+export interface Watcher {
+  close(): void;
+}
+
+export type WatcherFactory = (srcDir: string, onEvent: (e: WatchEvent) => void) => Watcher;
+
+export interface RunWatchOptions {
+  readonly cwd: string;
+  readonly stdout: NodeJS.WritableStream;
+  readonly stderr: NodeJS.WritableStream;
+  readonly debounceMs?: number;
+  readonly watcherFactory?: WatcherFactory;
+  readonly syncSurface?: () => void;
+  readonly componentWatcherFactory?: WatcherFactory;
+}
+
+export interface RunWatchHandle {
+  readonly stop: () => void;
+  readonly done: Promise<number>;
+  readonly waitForIdle: () => Promise<void>;
+}
+
+const DEFAULT_DEBOUNCE_MS = 50;
+
+export const recursiveWatcherFactory: WatcherFactory = (srcDir, onEvent) => {
+  const w = fsWatch(srcDir, { recursive: true }, (eventType, filename) => {
+    onEvent({
+      kind: eventType === "rename" ? "rename" : "change",
+      path: filename ?? "",
+    });
+  });
+  return { close: () => w.close() };
+};
+
+function formatBuildLine(written: readonly string[]): string {
+  return `defold-typescript build: wrote ${written.length} files: ${written.join(", ")}\n`;
+}
+
+function rewrapInitError(err: unknown): Error {
+  const message = err instanceof Error ? err.message : String(err);
+  return new Error(message.replace(/^defold-typescript build:/, "defold-typescript watch:"));
+}
+
+export function runWatch(opts: RunWatchOptions): RunWatchHandle {
+  const { cwd, stdout, stderr } = opts;
+  const debounceMs = opts.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const factory = opts.watcherFactory ?? recursiveWatcherFactory;
+
+  let resolveDone!: (code: number) => void;
+  let rejectDone!: (err: Error) => void;
+  const done = new Promise<number>((res, rej) => {
+    resolveDone = res;
+    rejectDone = rej;
+  });
+
+  let session: BuildSession;
+  try {
+    opts.syncSurface?.();
+    session = createBuildSession({ cwd });
+    const { written } = session.buildAll();
+    stdout.write(formatBuildLine(written));
+  } catch (err) {
+    rejectDone(rewrapInitError(err));
+    return {
+      stop: () => {},
+      done,
+      waitForIdle: () => Promise.resolve(),
+    };
+  }
+
+  const srcDir = path.join(cwd, "src");
+
+  let scheduled: ReturnType<typeof setTimeout> | null = null;
+  let syncScheduled: ReturnType<typeof setTimeout> | null = null;
+  let rebuildBusy = false;
+  let syncBusy = false;
+  let stopped = false;
+  let idleResolvers: Array<() => void> = [];
+  const pending = new Set<string>();
+
+  function notifyIdle(): void {
+    if (rebuildBusy || syncBusy) return;
+    const resolvers = idleResolvers;
+    idleResolvers = [];
+    for (const resolve of resolvers) resolve();
+  }
+
+  function rebuild(): void {
+    scheduled = null;
+    const drained = [...pending];
+    pending.clear();
+    const changed: string[] = [];
+    const removed: string[] = [];
+    for (const rel of drained) {
+      const key = `src/${toPosix(rel)}`;
+      if (existsSync(path.join(srcDir, rel))) {
+        changed.push(key);
+      } else {
+        removed.push(key);
+      }
+    }
+    try {
+      const { written } = session.applyEvents(changed, removed);
+      stdout.write(formatBuildLine(written));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      stderr.write(`${message}\n`);
+    }
+    rebuildBusy = false;
+    notifyIdle();
+  }
+
+  function onEvent(e: WatchEvent): void {
+    if (stopped) return;
+    rebuildBusy = true;
+    if (e.path) pending.add(e.path);
+    if (scheduled) clearTimeout(scheduled);
+    scheduled = setTimeout(rebuild, debounceMs);
+  }
+
+  const watcher = factory(srcDir, onEvent);
+
+  function runSync(): void {
+    syncScheduled = null;
+    try {
+      opts.syncSurface?.();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      stderr.write(`${message}\n`);
+    }
+    syncBusy = false;
+    notifyIdle();
+  }
+
+  function onComponentEvent(e: WatchEvent): void {
+    if (stopped) return;
+    if (!e.path || isSkipped(e.path) || !isComponentPath(e.path)) return;
+    syncBusy = true;
+    if (syncScheduled) clearTimeout(syncScheduled);
+    syncScheduled = setTimeout(runSync, debounceMs);
+  }
+
+  const componentWatcher = opts.componentWatcherFactory
+    ? opts.componentWatcherFactory(cwd, onComponentEvent)
+    : null;
+
+  function stop(): void {
+    if (stopped) return;
+    stopped = true;
+    if (scheduled) {
+      clearTimeout(scheduled);
+      scheduled = null;
+    }
+    if (syncScheduled) {
+      clearTimeout(syncScheduled);
+      syncScheduled = null;
+    }
+    watcher.close();
+    componentWatcher?.close();
+    rebuildBusy = false;
+    syncBusy = false;
+    notifyIdle();
+    resolveDone(0);
+  }
+
+  function waitForIdle(): Promise<void> {
+    if (!rebuildBusy && !syncBusy) return Promise.resolve();
+    return new Promise<void>((resolve) => {
+      idleResolvers.push(resolve);
+    });
+  }
+
+  return { stop, done, waitForIdle };
+}