@defold-typescript/types 0.34.0 → 0.36.0

package/scripts/regen.ts

@@ -191,15 +191,6 @@ const DEFAULT_TARGET = API_TARGETS.find((t) => t.default === true) as ApiTarget;
 
 export const MODULE_MANIFEST: readonly ModuleManifestEntry[] = loadTargetModules(DEFAULT_TARGET);
 
-// The fidelity audit runs over the promoted default surface (the `default: true`
-// target) so the 1.13-only modules (b2d.*, compute, material) and the 1.13 model
-// additions are audited too — auditing the older 1.12.4 target left them unseen,
-// which is how the promoted surface shipped opaque `Record` fallbacks while the
-// gate read `recordTables: 0`.
-const FIDELITY_BASELINE_TARGET = DEFAULT_TARGET;
-export const FIDELITY_BASELINE_MANIFEST: readonly ModuleManifestEntry[] =
-  loadTargetModules(FIDELITY_BASELINE_TARGET);
-
 // Handle tokens the editor VM alone exposes. `transaction_step[` is what
 // upstream literally emits for `transaction_step[]` — the ref-doc's own type
 // string loses the closing bracket — so it is repaired here, per entry, rather
@@ -544,16 +535,29 @@ export function kindStdlibReferences(entry: KindManifestEntry): string {
   return `${LUA_51_REFERENCE}${entry.jit === false ? "" : LUA_JIT_ONLY_REFERENCE}`;
 }
 
-const UNIVERSAL_EXTRA_IMPORTS: readonly string[] = [
-  "../builtin-messages",
-  "../../src/custom-messages",
-  "../../src/engine-globals",
-  "../../src/msg-overloads",
-  "../../src/message-guard",
-  "../../src/window-event-guard",
-  "../../src/scene-addresses",
-  "../../src/go-overloads",
-  "../../src/vmath-overloads",
+// One augmentation a complete script surface imports. `restrictedTo` names the
+// kind-restricted namespace the augmentation re-opens: such an entry belongs on
+// that namespace's kind index alone, or it would re-open a wall the kind closes.
+// The marker is declared rather than parsed out of the `.d.ts`, so
+// `generateKindIndex` stays pure; `srcAugmentationScopingViolations` in
+// `./augmentation-namespaces` is what catches a future restricted augmentation
+// added without one, by reading the namespaces each file really re-opens.
+interface UniversalExtraImport {
+  readonly specifier: string;
+  readonly restrictedTo?: string;
+}
+
+const UNIVERSAL_EXTRA_IMPORTS: readonly UniversalExtraImport[] = [
+  { specifier: "../builtin-messages" },
+  { specifier: "../../src/custom-messages" },
+  { specifier: "../../src/engine-globals" },
+  { specifier: "../../src/msg-overloads" },
+  { specifier: "../../src/message-guard" },
+  { specifier: "../../src/window-event-guard" },
+  { specifier: "../../src/scene-addresses" },
+  { specifier: "../../src/go-overloads" },
+  { specifier: "../../src/render-overloads", restrictedTo: "render" },
+  { specifier: "../../src/vmath-overloads" },
 ];
 
 const SRC_IMPORT_PREFIX = "../../src/";
@@ -561,9 +565,18 @@ const SRC_IMPORT_PREFIX = "../../src/";
 // The hand-authored `src/*` augmentations a complete script surface needs,
 // derived from the one declaration the generated kind index renders from so a
 // new augmentation reaches every materialization path with no second edit.
-export const SRC_AUGMENTATION_MODULES: readonly string[] = UNIVERSAL_EXTRA_IMPORTS.filter(
-  (specifier) => specifier.startsWith(SRC_IMPORT_PREFIX),
-).map((specifier) => specifier.slice(SRC_IMPORT_PREFIX.length));
+export const SRC_AUGMENTATION_MODULES: readonly string[] = UNIVERSAL_EXTRA_IMPORTS.filter((entry) =>
+  entry.specifier.startsWith(SRC_IMPORT_PREFIX),
+).map((entry) => entry.specifier.slice(SRC_IMPORT_PREFIX.length));
+
+// The `src/*` augmentations bound to a kind-restricted namespace, as
+// `<module name> -> <namespace>`. Exported so the CLI's materialization scopes
+// them the same way the in-repo kind indexes do, from one declaration.
+export const RESTRICTED_SRC_AUGMENTATIONS: Readonly<Record<string, string>> = Object.fromEntries(
+  UNIVERSAL_EXTRA_IMPORTS.filter(
+    (entry) => entry.restrictedTo !== undefined && entry.specifier.startsWith(SRC_IMPORT_PREFIX),
+  ).map((entry) => [entry.specifier.slice(SRC_IMPORT_PREFIX.length), entry.restrictedTo as string]),
+);
 
 // Read those augmentations as surface-root files. Mirrors
 // `loadTargetEditorModules`: a missing file throws with its path rather than
@@ -664,9 +677,14 @@ export function generateKindIndex(kind: string, target: ApiTarget = DEFAULT_TARG
   const universalNamespaces = MODULE_MANIFEST.filter(
     (m) => !Object.hasOwn(RESTRICTED_NAMESPACES, m.namespace),
   ).map((m) => `../${m.outFile.replace(/\.d\.ts$/, "")}`);
+  // An augmentation bound to a restricted namespace rides only that namespace's
+  // kind index; every unmarked entry stays universal.
+  const extraImports = UNIVERSAL_EXTRA_IMPORTS.filter(
+    (extra) => extra.restrictedTo === undefined || extra.restrictedTo === entry.restricted,
+  ).map((extra) => extra.specifier);
   const modules = (
     entry.only === undefined
-      ? [...new Set([...universalNamespaces.sort(), ...[...UNIVERSAL_EXTRA_IMPORTS].sort()])]
+      ? [...new Set([...universalNamespaces.sort(), ...extraImports.sort()])]
       : [...editorKindModules(target), ...(entry.extraModules ?? [])]
   ).map((path) => retargetSrcPath(path, srcPrefix));
   const lines = modules.map((path) => `import "${path}";`);
@@ -687,8 +705,10 @@ export function generateKindIndex(kind: string, target: ApiTarget = DEFAULT_TARG
 export function generateVersionIndex(
   versionId: string,
   manifest: readonly VersionedModuleManifestEntry[] = VERSIONED_MODULE_MANIFEST,
-  // Bare names appended after the module imports. A materialized surface carries
-  // the `src/*` augmentations beside its modules; the in-repo emit does not.
+  // Names appended after the module imports. A materialized surface carries the
+  // `src/*` augmentations beside its modules and names them bare; the in-repo
+  // emit reaches back into the package and passes an already-relative specifier,
+  // which is kept verbatim rather than re-anchored to the surface directory.
   extraImports: readonly string[] = [],
 ): string {
   const imports = [
@@ -698,7 +718,7 @@ export function generateVersionIndex(
       .sort(),
     ...extraImports,
   ]
-    .map((module) => `import "./${module}";`)
+    .map((module) => `import "${module.startsWith(".") ? module : `./${module}`}";`)
     .join("\n");
   // A pinned consumer names this surface in `types` and never loads the
   // package entrypoint, so the stdlib directives have to lead here too. A
@@ -706,6 +726,16 @@ export function generateVersionIndex(
   return `${LUA_STDLIB_REFERENCES}${imports}\n\nexport {};\n`;
 }
 
+// The authored augmentations a committed per-version index imports, addressed
+// back into the package's `src/`. The in-repo surface has no copies beside its
+// modules, so a skipped symbol would otherwise be declared on no versioned
+// surface at all. Derived from `SRC_AUGMENTATION_MODULES`, so a new augmentation
+// reaches the pinned surfaces on the same edit that reaches the materialized ones.
+export function versionSrcAugmentationImports(target: ApiTarget): string[] {
+  const srcPrefix = target.coreTypesImport.slice(0, -"core-types".length);
+  return SRC_AUGMENTATION_MODULES.map((name) => `${srcPrefix}${name}`);
+}
+
 // The `src/`-relative prefix a kind index living in `<generatedDir>/kinds/` needs
 // to reach the package's hand-authored modules. The target's own
 // `coreTypesImport` already measures its generated dir's depth; the kind index
@@ -732,7 +762,37 @@ export function targetKindManifest(target: ApiTarget): readonly KindManifestEntr
   return [...RUNTIME_KIND_MANIFEST, ...KIND_MODULE_MANIFEST.filter((e) => e.only !== undefined)];
 }
 
+// Every `src/*` augmentation bound to a kind-restricted namespace carries its
+// `restrictedTo` marker, and every marker names a namespace its file re-opens.
+// Exported so a test can reach the guard the entry point runs; never called on
+// import, so the dynamic import below stays unreached from an installed package.
+export async function assertSrcAugmentationScoping(
+  packageRoot: string = PACKAGE_ROOT,
+): Promise<number> {
+  // Imported here rather than at module scope: it imports the devDependency
+  // `typescript`, and `resolve` loads this module from an installed package.
+  const { srcAugmentationScopingViolations } = await import("./augmentation-namespaces");
+  const files = loadSrcAugmentations(packageRoot);
+  const violations = srcAugmentationScopingViolations(
+    files,
+    RESTRICTED_SRC_AUGMENTATIONS,
+    RESTRICTED_NAMESPACES,
+  );
+  if (violations.length > 0) {
+    throw new Error(`src augmentation scoping violations:\n${violations.join("\n")}`);
+  }
+  return files.length;
+}
+
 if (import.meta.main) {
+  // Ordering contract: `regen-entrypoint.test.ts` reads this line's prefix to
+  // prove the guard runs before the first write. The count comes from the guard's
+  // own return value so the marker cannot be printed without a completed guard
+  // run — do not simplify it back to `SRC_AUGMENTATION_MODULES.length`, which
+  // would let the guard be deleted or reordered with the line still intact.
+  const checked = await assertSrcAugmentationScoping();
+  console.log(`src augmentation scoping checked: ${checked} file(s)`);
+
   const generated = resolve(import.meta.dir, "..", "generated");
   mkdirSync(resolve(generated, "editor-vm"), { recursive: true });
   for (const entry of [
@@ -752,6 +812,21 @@ if (import.meta.main) {
   writeFileSync(messagesOut, generateBuiltinMessagesDeclaration(MESSAGES_MANIFEST));
   console.log(`wrote ${messagesOut}`);
 
+  // Imported here rather than at module scope: its fixtures are not published,
+  // and `resolve` loads this module from an installed package.
+  const { EXTENSION_GOLDENS_DIR, EXTENSION_GOLDEN_MANIFEST } = await import("./extension-goldens");
+  const goldens = resolve(PACKAGE_ROOT, EXTENSION_GOLDENS_DIR);
+  mkdirSync(goldens, { recursive: true });
+  for (const entry of EXTENSION_GOLDEN_MANIFEST) {
+    const { contents, dropped } = generateModuleDeclaration(entry);
+    if (dropped.length > 0) {
+      console.log(`note: dropped skipped member(s) from ${entry.namespace}: ${dropped.join(", ")}`);
+    }
+    const out = resolve(goldens, entry.outFile);
+    writeFileSync(out, contents);
+    console.log(`wrote ${out}`);
+  }
+
   // The target's own `generatedDir` is where a version lands, so a declaring
   // target's editor surface (and its `editor-vm/` subdirectory) rides the same
   // destination rule as its runtime modules rather than a second convention.
@@ -778,7 +853,14 @@ if (import.meta.main) {
   for (const target of versionedTargets) {
     const indexOut = resolve(versionDirOf(target.id), "index.d.ts");
     mkdirSync(dirname(indexOut), { recursive: true });
-    writeFileSync(indexOut, generateVersionIndex(target.id));
+    writeFileSync(
+      indexOut,
+      generateVersionIndex(
+        target.id,
+        VERSIONED_MODULE_MANIFEST,
+        versionSrcAugmentationImports(target),
+      ),
+    );
     console.log(`wrote ${indexOut}`);
 
     const editorKinds = targetKindManifest(target).filter((entry) => entry.only !== undefined);

package/scripts/signature-store-fs.ts

@@ -24,6 +24,7 @@ export const SOCKET_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures
 export const VMATH_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "vmath.json");
 export const GO_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "go.json");
 export const MSG_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "msg.json");
+export const RENDER_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "render.json");
 
 export function loadSignatureFile(path: string): SignatureStore {
   let raw: string;

package/scripts/sync-api-docs.ts

@@ -109,9 +109,9 @@ export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
   entry("zlib", "doc/src-script_zlib.cpp_doc.json"),
 ];
 
-// Checklist namespaces with no machine-readable doc anywhere (neither core
-// ref-doc.zip nor a published extension `.script_api`). Currently empty: the
-// four extension-only surfaces are wired via EXTENSION_MANIFEST below.
+// Checklist namespaces with no machine-readable doc anywhere in core
+// ref-doc.zip. Currently empty: extension namespaces are not engine surfaces;
+// they are typed through `resolve` from each extension's own `.script_api`.
 export const UNMAPPED: ReadonlyMap<string, string> = new Map();
 
 // A Lua script namespace is a lowercase, dot-separated identifier (`sys`,
@@ -211,53 +211,18 @@ function entry(
   return { namespace, zipEntry, fixture, ...(mergeEntries ? { mergeEntries } : {}) };
 }
 
-export interface ExtensionManifestEntry {
-  readonly namespace: string;
-  readonly repo: string;
-  readonly tag: string;
-  readonly path: string;
-  readonly fixture: string;
-}
-
-// Extension-only namespaces: each ships a single `.script_api` (YAML) doc in
-// its own repo rather than appearing in core ref-doc.zip. Pinned to a release
-// tag and converted to the core ref-doc JSON shape via parseScriptApi so they
-// flow through MODULE_MANIFEST and the drift guard like every core namespace.
-export const EXTENSION_MANIFEST: readonly ExtensionManifestEntry[] = [
-  ext("iac", "defold/extension-iac", "1.4.0", "extension-iac/api/iac.script_api"),
-  ext("iap", "defold/extension-iap", "8.4.0", "extension-iap/api/iap.script_api"),
-  ext("push", "defold/extension-push", "4.1.0", "extension-push/api/push.script_api"),
-  ext("webview", "defold/extension-webview", "1.5.0", "webview/api/webview.script_api"),
-];
-
-function ext(namespace: string, repo: string, tag: string, path: string): ExtensionManifestEntry {
-  return {
-    namespace,
-    repo,
-    tag,
-    path,
-    fixture: `fixtures/defold-1.13.1/${namespace}_doc.json`,
-  };
-}
-
 // Every vendored fixture set the coverage report audits, and the namespaces it
 // counts as reached from upstream. Composed once here so the `--check` run and
 // the guard over it cannot disagree about which sets are in scope.
 export const COVERAGE_MANIFEST: readonly { readonly namespace: string }[] = [
   ...SYNC_MANIFEST,
-  ...EXTENSION_MANIFEST,
   ...EDITOR_MANIFEST,
 ];
 
 export const UPSTREAM_MAPPED_NAMESPACES: ReadonlySet<string> = new Set(
-  [...SYNC_MANIFEST, ...EXTENSION_MANIFEST, ...LUA_STDLIB_MANIFEST, ...EDITOR_MANIFEST].map(
-    (e) => e.namespace,
-  ),
+  [...SYNC_MANIFEST, ...LUA_STDLIB_MANIFEST, ...EDITOR_MANIFEST].map((e) => e.namespace),
 );
 
-export const extensionRawUrl = (e: ExtensionManifestEntry): string =>
-  `https://raw.githubusercontent.com/${e.repo}/${e.tag}/${e.path}`;
-
 // Convert a raw `.script_api` YAML doc to the core ref-doc JSON string written
 // to fixtures/<ns>_doc.json. The result is byte-compared by the same drift
 // semantics core fixtures use.
@@ -492,25 +457,6 @@ export function syncExtractedFixtures(
   return results;
 }
 
-export async function downloadExtensionFixtures(
-  manifest: readonly ExtensionManifestEntry[] = EXTENSION_MANIFEST,
-): Promise<ExtractedFixture[]> {
-  const out: ExtractedFixture[] = [];
-  for (const e of manifest) {
-    const url = extensionRawUrl(e);
-    const res = await fetch(url);
-    if (!res.ok) {
-      throw new Error(`extension doc download failed: ${url} -> ${res.status} ${res.statusText}`);
-    }
-    out.push({
-      namespace: e.namespace,
-      fixture: e.fixture,
-      contents: scriptApiToFixtureJson(await res.text()),
-    });
-  }
-  return out;
-}
-
 function readFixtureOrNull(path: string): string | null {
   try {
     return readFileSync(path, "utf8");
@@ -681,18 +627,16 @@ if (import.meta.main) {
   const zip = zipPath ? readZip(zipPath) : await downloadZip();
 
   const coreFixtures = extractFixtures(zip);
-  const extensionFixtures = await downloadExtensionFixtures();
   const luaStdlibFixtures = extractFixtures(zip, LUA_STDLIB_MANIFEST);
   const editorFixtures = extractFixtures(zip, EDITOR_MANIFEST);
   const editorVmFixtures = extractFixtures(zip, EDITOR_VM_MANIFEST);
   const results = [
     ...syncExtractedFixtures(coreFixtures, { check }),
-    ...syncExtractedFixtures(extensionFixtures, { check }),
     ...syncExtractedFixtures(luaStdlibFixtures, { check }),
     ...syncExtractedFixtures(editorFixtures, { check }),
     ...syncExtractedFixtures(editorVmFixtures, { check }),
   ];
-  const syncedDocs = [...coreFixtures, ...extensionFixtures].map((f) => ({
+  const syncedDocs = coreFixtures.map((f) => ({
     namespace: f.namespace,
     doc: JSON.parse(f.contents),
   }));