@defold-typescript/library-types 0.20.8 → 0.21.1

package/scripts/sync-luals-types.ts

@@ -1,7 +1,9 @@
 import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { emitLibraryDeclarations } from "./emit-library-dts";
+import { lowerLibraryModel } from "./lower-api-doc";
 import { buildFidelityReport, type FidelityReport } from "./luals-fidelity";
-import { mergeLibraryModels, parseLualsSource } from "./parse-luals";
+import { type LibraryModel, mergeLibraryModels, parseLualsSource } from "./parse-luals";
 
 /**
  * The LuaLS ingestion front-end pins its source per-entry: a druid-style library
@@ -17,6 +19,9 @@ export interface LualsTarget {
   namespace: string;
   typeRenames: Record<string, string>;
   ignore: string[];
+  // SPDX-style license id, surfaced by the docs-site provenance block. Optional
+  // in the config; the docs-site defaults an absent value to "".
+  license?: string;
 }
 
 export interface LualsTargets {
@@ -51,6 +56,7 @@ export function readLualsTargets(packageRoot: string): LualsTarget[] {
       namespace: entry.namespace as string,
       typeRenames: entry.typeRenames ?? {},
       ignore: entry.ignore ?? [],
+      ...(entry.license !== undefined ? { license: entry.license } : {}),
     };
   });
 }
@@ -110,6 +116,9 @@ export type ListLualsTree = (repo: string, ref: string) => Promise<string[]>;
 /** Fetch the raw text at a URL. Network seam — mirrors `sync-library-types.ts`. */
 export type FetchText = (url: string) => Promise<string>;
 
+/** Recursively enumerate a fixture directory's entries. Filesystem seam. */
+export type ReadFixtureDir = (root: string) => string[];
+
 /**
  * A GitHub repo URL reduced to the bare `<owner>/<repo>` slug used to address
  * raw content. Mirrors `repoSlug` in the ts-defold front-end.
@@ -151,17 +160,43 @@ export async function fetchLualsFixtures(
  * the `--fidelity` CLI arm and its round-trip test drive the exact same path and
  * agree byte-for-byte. Fixture files are read in sorted order for determinism,
  * mirroring the parse snapshot.
+ *
+ * Interfaces and aliases come from the full merge — the module's own signatures
+ * reference cross-file classes — but module functions are scoped to the module's
+ * own `.lua` file (`moduleId` dotted to a path, e.g. `druid.druid` →
+ * `druid/druid.lua`). Merging every file's free functions would export every
+ * library file's functions from the one module. A `moduleId` with no matching
+ * fixture is a loud misconfiguration, not a silently empty surface.
  */
-export function buildTargetFidelity(packageRoot: string, target: LualsTarget): FidelityReport {
+export function buildTargetModel(
+  packageRoot: string,
+  target: LualsTarget,
+  seams: { readDir?: ReadFixtureDir } = {},
+): LibraryModel {
+  const readDir = seams.readDir ?? ((r) => readdirSync(r, { recursive: true }).map(String));
   const root = join(packageRoot, "fixtures/luals", target.namespace);
-  const files = readdirSync(root, { recursive: true })
-    .map((entry) => String(entry))
+  const files = readDir(root)
+    .map((entry) => entry.replace(/\\/g, "/"))
     .filter((entry) => entry.endsWith(".lua"))
     .sort();
-  const model = mergeLibraryModels(
-    files.map((rel) => parseLualsSource(readFileSync(join(root, rel), "utf8"))),
+  const ownFile = `${target.moduleId.replace(/\./g, "/")}.lua`;
+  if (!files.includes(ownFile)) {
+    throw new Error(
+      `buildTargetModel: module "${target.moduleId}" expects fixture "${ownFile}" under fixtures/luals/${target.namespace}, but it is not among the ${files.length} fixture .lua files.`,
+    );
+  }
+  const parsed = new Map<string, LibraryModel>();
+  for (const rel of files) parsed.set(rel, parseLualsSource(readFileSync(join(root, rel), "utf8")));
+  const merged = mergeLibraryModels([...parsed.values()]);
+  return { ...merged, moduleFunctions: parsed.get(ownFile)?.moduleFunctions ?? [] };
+}
+
+export function buildTargetFidelity(packageRoot: string, target: LualsTarget): FidelityReport {
+  return buildFidelityReport(
+    target.namespace,
+    buildTargetModel(packageRoot, target),
+    target.typeRenames,
   );
-  return buildFidelityReport(target.namespace, model, target.typeRenames);
 }
 
 /**
@@ -237,4 +272,32 @@ if (import.meta.main) {
       );
     }
   }
+  if (argv.includes("--emit")) {
+    const targets = readLualsTargets(root);
+    for (const target of targets) {
+      const model = buildTargetModel(root, target);
+      const declarations = emitLibraryDeclarations(model, {
+        moduleId: target.moduleId,
+        typeRenames: target.typeRenames,
+      });
+      const dest = join(root, "generated", `${target.namespace}.d.ts`);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, declarations);
+      console.log(`emitted ${target.moduleId} -> generated/${target.namespace}.d.ts`);
+    }
+  }
+  if (argv.includes("--api-doc")) {
+    const targets = readLualsTargets(root);
+    for (const target of targets) {
+      const model = buildTargetModel(root, target);
+      const lowered = lowerLibraryModel(model, {
+        namespace: target.namespace,
+        typeRenames: target.typeRenames,
+      });
+      const dest = join(root, "api-doc", `${target.namespace}.json`);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, `${JSON.stringify(lowered, null, 2)}\n`);
+      console.log(`lowered ${target.moduleId} -> api-doc/${target.namespace}.json`);
+    }
+  }
 }