@defold-typescript/types 0.41.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -64,6 +64,7 @@
     "fixtures/messages_doc.json",
     "fixtures/defold-*",
     "!fixtures/defold-*/engine-bindings",
+    "!fixtures/defold-*/annotations",
     "examples/translations.json",
     "!src/**/*.test.ts",
     "!scripts/**/*.test.ts",
@@ -82,7 +83,11 @@
     "!scripts/engine-binding-verdicts.ts",
     "!scripts/engine-binding-verdicts.json",
     "!scripts/lua-kind.ts",
-    "!scripts/index-slot-scan.ts"
+    "!scripts/index-slot-scan.ts",
+    "!scripts/lua-annotations.ts",
+    "!scripts/lua-annotation-diff.ts",
+    "!scripts/lua-annotation-verdicts.ts",
+    "!scripts/lua-annotation-verdicts.json"
   ],
   "publishConfig": {
     "access": "public"

package/scripts/import-defold-release.ts

@@ -5,6 +5,8 @@ import { refDocCacheDir, resolveRefDoc } from "./doc-source";
 import {
   apiElementIdentity,
   EDITOR_MANIFEST,
+  type ExtractedFixture,
+  extractAnnotationFixtures,
   IGNORED_UPSTREAM,
   mergeApiDocs,
   readZip,
@@ -153,6 +155,9 @@ export interface ReleaseImportManifest {
     readonly unknownTypes: UnknownTypeBlocker[];
     readonly unmappedFunctionNamespaces: UnmappedNamespaceBlocker[];
   };
+  // The file names vendored under `annotations/`, which `loadAnnotations` holds
+  // the directory to. Empty before 1.13.2; absent from manifests written earlier.
+  readonly annotationFiles: readonly string[];
   readonly snapshots: Array<{
     readonly namespace: string;
     readonly fixture: string;
@@ -164,6 +169,8 @@ export interface ReleaseImportManifest {
 export type ReleaseImportPlan = Omit<ReleaseImportManifest, "snapshots"> & {
   readonly manifest: ReleaseImportManifest;
   readonly snapshots: ReleaseImportSnapshot[];
+  // The release's LuaLS annotation files, vendored verbatim. Empty before 1.13.2.
+  readonly annotations: ExtractedFixture[];
 };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -259,7 +266,9 @@ function unknownTypeBlockers(
   return out;
 }
 
-function reportWithoutSnapshots(plan: Omit<ReleaseImportPlan, "manifest">): ReleaseImportManifest {
+function reportWithoutSnapshots(
+  plan: Omit<ReleaseImportPlan, "manifest" | "annotations">,
+): ReleaseImportManifest {
   return {
     version: plan.version,
     baseline: plan.baseline,
@@ -269,6 +278,7 @@ function reportWithoutSnapshots(plan: Omit<ReleaseImportPlan, "manifest">): Rele
     moved: plan.moved,
     symbols: plan.symbols,
     blockers: plan.blockers,
+    annotationFiles: plan.annotationFiles,
     snapshots: plan.snapshots.map(({ namespace, fixture, sourceEntries, symbolSources }) => ({
       namespace,
       fixture,
@@ -417,6 +427,7 @@ export function buildReleaseImportPlan(input: {
     (a, b) => a.namespace.localeCompare(b.namespace) || a.symbol.localeCompare(b.symbol),
   );
   const ready = unknownTypes.length === 0 && unmappedFunctionNamespaces.length === 0;
+  const annotations = extractAnnotationFixtures(input.zip);
   const planBase = {
     version: input.version,
     baseline: input.baseline.id,
@@ -426,10 +437,11 @@ export function buildReleaseImportPlan(input: {
     moved,
     symbols,
     blockers: { unknownTypes, unmappedFunctionNamespaces },
+    annotationFiles: annotations.map((annotation) => annotation.namespace).sort(),
     snapshots,
   };
   const manifest = reportWithoutSnapshots(planBase);
-  return { ...planBase, manifest };
+  return { ...planBase, manifest, annotations };
 }
 
 export function releaseImportReportJson(plan: ReleaseImportPlan): string {
@@ -448,6 +460,13 @@ export function applyReleaseImport(plan: ReleaseImportPlan, packageRoot = PACKAG
     writeFileSync(path, `${JSON.stringify(snapshot.doc, null, 2)}\n`);
     written.push(relative);
   }
+  for (const annotation of plan.annotations) {
+    const relative = `${relativeRoot}/${annotation.fixture}`;
+    const path = resolve(packageRoot, relative);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, annotation.contents);
+    written.push(relative);
+  }
   // The prefixless builtins (`hash`, `pprint`, ...) are hand-vendored rather than
   // generated, so no upstream snapshot carries them. Seeding the canonical copy
   // here is what keeps a newly imported target from being born without a globals

package/scripts/sync-api-docs.ts

@@ -1,6 +1,6 @@
-import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { type ApiModule, parseDefoldApiDoc } from "../src/api-doc";
 import { DEFOLD_TYPE_MAP } from "../src/core-types";
 import { parseScriptApi } from "../src/script-api";
@@ -404,6 +404,21 @@ export function extractFixtures(
   });
 }
 
+// Since 1.13.2 the ref-doc zip ships LuaLS annotation files beside the JSON:
+// `doc/<namespace>.lua` for the game runtime and `doc/<namespace>.editor_script`
+// for the editor VM. They are vendored verbatim, never parsed at sync time.
+const ANNOTATION_ENTRY = /^doc\/([^/]+\.(?:lua|editor_script))$/;
+
+export function extractAnnotationFixtures(zip: ZipAccessor): ExtractedFixture[] {
+  const out: ExtractedFixture[] = [];
+  for (const zipEntry of [...zip.entries()].sort()) {
+    const file = ANNOTATION_ENTRY.exec(zipEntry)?.[1];
+    if (file === undefined) continue;
+    out.push({ namespace: file, fixture: `annotations/${file}`, contents: zip.read(zipEntry) });
+  }
+  return out;
+}
+
 export type FixtureSyncStatus = "clean" | "drift" | "created";
 
 export interface FixtureSyncResult {
@@ -442,7 +457,8 @@ export function syncFixtures(zip: ZipAccessor, options: SyncOptions = {}): Fixtu
 
 // Compare/write a set of already-extracted fixtures against disk. Shared by
 // the core (zip) and extension (`.script_api`) sync paths so both honor the
-// identical created/clean/drift + format-on-write semantics.
+// identical created/clean/drift + format-on-write semantics. A non-JSON fixture
+// (a vendored annotation file) compares and writes byte-for-byte.
 export function syncExtractedFixtures(
   items: readonly ExtractedFixture[],
   options: Omit<SyncOptions, "manifest"> = {},
@@ -453,15 +469,21 @@ export function syncExtractedFixtures(
   const results: FixtureSyncResult[] = [];
   for (const item of items) {
     const path = resolve(root, item.fixture);
+    const json = item.fixture.endsWith(".json");
     const existing = readFixtureOrNull(path);
     const status: FixtureSyncStatus =
       existing === null
         ? "created"
-        : canonicalJson(existing) === canonicalJson(item.contents)
+        : (
+              json
+                ? canonicalJson(existing) === canonicalJson(item.contents)
+                : existing === item.contents
+            )
           ? "clean"
           : "drift";
     if (!check && status !== "clean") {
-      writeFileSync(path, format(item.contents));
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, json ? format(item.contents) : item.contents);
     }
     results.push({ namespace: item.namespace, fixture: item.fixture, status });
   }
@@ -641,11 +663,16 @@ if (import.meta.main) {
   const luaStdlibFixtures = extractFixtures(zip, LUA_STDLIB_MANIFEST);
   const editorFixtures = extractFixtures(zip, EDITOR_MANIFEST);
   const editorVmFixtures = extractFixtures(zip, EDITOR_VM_MANIFEST);
+  const annotationFixtures = extractAnnotationFixtures(zip);
   const results = [
     ...syncExtractedFixtures(coreFixtures, { check }),
     ...syncExtractedFixtures(luaStdlibFixtures, { check }),
     ...syncExtractedFixtures(editorFixtures, { check }),
     ...syncExtractedFixtures(editorVmFixtures, { check }),
+    ...syncExtractedFixtures(annotationFixtures, {
+      check,
+      fixturesRoot: resolve(PACKAGE_ROOT, `fixtures/defold-${DEFOLD_VERSION}`),
+    }),
   ];
   const syncedDocs = coreFixtures.map((f) => ({
     namespace: f.namespace,