@defold-typescript/library-types 0.23.0 → 0.25.0

package/scripts/parse-openapi-api.ts

@@ -0,0 +1,313 @@
+/**
+ * The OpenAPI/proto ingestion front-end's parser: a fifth `library-types` corpus
+ * source beside the LuaLS annotations (`parse-luals.ts`), the typed `.script_api`
+ * (`scriptApiToFixtureJson`), the README markdown (`parse-markdown-api.ts`), and
+ * the authored `.d.ts` lane. It reads a structured REST swagger (JSON) plus the
+ * realtime `.proto` message list — the machine-readable source a codegen'd Lua
+ * client (nakama-defold) is generated from — and produces the same ref-doc `doc`
+ * shape those front-ends feed the shared emitter (`generateModuleDeclaration`), so
+ * the OpenAPI path reuses the exact emit + fidelity machinery.
+ *
+ * The surface mirrors the client codegen's naming, not the raw wire schema:
+ *
+ * - a swagger `paths` operation (`operationId` `Nakama_AuthenticateCustom`) becomes
+ *   a client RPC function `authenticate_custom` (service prefix stripped, snake);
+ * - a swagger `definitions` object (`apiAccountCustom`) becomes a constructor
+ *   `create_api_account_custom`;
+ * - a realtime proto `message ChannelMessageSend` becomes a realtime message
+ *   constructor `create_channel_message_send_message`.
+ *
+ * Scope is a **flat signature surface**, not deep schema modelling (a PRD
+ * non-goal): swagger scalar types and `$ref`/object/array types collapse to the
+ * emitter's token vocabulary (`string`/`number`/`boolean`/`table`), and proto
+ * scalars/messages likewise. Every parameter and return slot carries at least one
+ * resolvable token — a slot is never left type-empty (the "no silent swallow"
+ * contract the fidelity gate depends on).
+ */
+
+/** A single ref-doc parameter or return slot. `is_optional` mirrors the consumer
+ * contract's string flag (`"True"`); it is present only when set. */
+export interface OpenApiParam {
+  name: string;
+  doc: string;
+  types: string[];
+  is_optional?: "True";
+}
+
+export interface OpenApiElement {
+  type: "FUNCTION";
+  name: string;
+  description: string;
+  parameters: OpenApiParam[];
+  returnvalues: OpenApiParam[];
+}
+
+/** The ref-doc `doc` shape `generateModuleDeclaration` consumes. `info.namespace`
+ * is empty here — the swagger/proto source names no publish alias — and the
+ * front-end retargets the bare element names onto the pinned namespace. */
+export interface OpenApiDoc {
+  info: { namespace: string; brief: string; description: string };
+  elements: OpenApiElement[];
+}
+
+/** camelCase / PascalCase -> snake_case, splitting acronym runs on the trailing
+ * capitalised word (`HTTPStatus` -> `http_status`). */
+function snake(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    .toLowerCase();
+}
+
+/** Map a swagger schema type keyword to a resolvable emitter token. Object,
+ * array, and `$ref` shapes all collapse to `table` (a Lua table), the faithful
+ * shape a Lua client marshals them as. */
+function swaggerType(type: string | undefined, hasRef: boolean): string {
+  if (hasRef) return "table";
+  switch (type) {
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "string":
+      return "string";
+    default:
+      // `object`, `array`, and anything unrecognised marshal as a table.
+      return "table";
+  }
+}
+
+interface SwaggerSchema {
+  type?: string;
+  $ref?: string;
+  items?: SwaggerSchema;
+  properties?: Record<string, SwaggerSchema>;
+  required?: string[];
+  additionalProperties?: unknown;
+}
+
+interface SwaggerParameter {
+  name: string;
+  in: string;
+  required?: boolean;
+  type?: string;
+  schema?: SwaggerSchema;
+  description?: string;
+}
+
+interface SwaggerOperation {
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  parameters?: SwaggerParameter[];
+  responses?: Record<string, { schema?: SwaggerSchema; description?: string }>;
+}
+
+interface SwaggerRoot {
+  paths?: Record<string, Record<string, SwaggerOperation>>;
+  definitions?: Record<string, SwaggerSchema>;
+}
+
+/** Strip a leading `Service_` prefix from an operationId, then snake the rest. */
+function operationName(operationId: string): string {
+  const underscore = operationId.indexOf("_");
+  const bare = underscore >= 0 ? operationId.slice(underscore + 1) : operationId;
+  return snake(bare);
+}
+
+function schemaToken(schema: SwaggerSchema): string {
+  return swaggerType(schema.type, typeof schema.$ref === "string");
+}
+
+function swaggerParamSlot(param: SwaggerParameter): OpenApiParam {
+  const token =
+    param.in === "body" && param.schema !== undefined
+      ? schemaToken(param.schema)
+      : swaggerType(param.type, false);
+  const slot: OpenApiParam = {
+    name: param.name,
+    doc: (param.description ?? "").trim(),
+    types: [token],
+  };
+  if (param.required !== true) slot.is_optional = "True";
+  return slot;
+}
+
+function swaggerReturnSlots(op: SwaggerOperation): OpenApiParam[] {
+  const schema = op.responses?.["200"]?.schema;
+  if (schema === undefined) return [];
+  return [{ name: "result", doc: "", types: [schemaToken(schema)] }];
+}
+
+function parseSwaggerOperations(root: SwaggerRoot): OpenApiElement[] {
+  const elements: OpenApiElement[] = [];
+  for (const methods of Object.values(root.paths ?? {})) {
+    for (const op of Object.values(methods)) {
+      if (typeof op.operationId !== "string") continue;
+      elements.push({
+        type: "FUNCTION",
+        name: operationName(op.operationId),
+        description: (op.summary ?? op.description ?? "").trim(),
+        parameters: (op.parameters ?? []).map(swaggerParamSlot),
+        returnvalues: swaggerReturnSlots(op),
+      });
+    }
+  }
+  return elements;
+}
+
+function parseSwaggerDefinitions(root: SwaggerRoot): OpenApiElement[] {
+  const elements: OpenApiElement[] = [];
+  for (const [name, schema] of Object.entries(root.definitions ?? {})) {
+    // Only object definitions become constructors; enum/scalar definitions carry
+    // no properties and would emit a meaningless zero-argument builder.
+    if (schema.type !== "object" || schema.properties === undefined) continue;
+    const required = new Set(schema.required ?? []);
+    const parameters = Object.entries(schema.properties).map(([propName, propSchema]) => {
+      const slot: OpenApiParam = { name: propName, doc: "", types: [schemaToken(propSchema)] };
+      if (!required.has(propName)) slot.is_optional = "True";
+      return slot;
+    });
+    elements.push({
+      type: "FUNCTION",
+      name: `create_${snake(name)}`,
+      description: (root.definitions?.[name] as { description?: string }).description?.trim() ?? "",
+      parameters,
+      returnvalues: [{ name: "result", doc: "", types: ["table"] }],
+    });
+  }
+  return elements;
+}
+
+/** Map a proto field type to a resolvable emitter token. Scalar numerics and
+ * `bytes` collapse per Lua marshalling; message/enum/`map`/`repeated` types are
+ * tables. */
+function protoType(rawType: string): string {
+  const type = rawType.trim();
+  if (type.startsWith("map<") || type.startsWith("repeated ")) return "table";
+  switch (type) {
+    case "double":
+    case "float":
+    case "int32":
+    case "int64":
+    case "uint32":
+    case "uint64":
+    case "sint32":
+    case "sint64":
+    case "fixed32":
+    case "fixed64":
+    case "sfixed32":
+    case "sfixed64":
+      return "number";
+    case "bool":
+      return "boolean";
+    case "string":
+    case "bytes":
+      return "string";
+    default:
+      // A message- or enum-typed field marshals as a table.
+      return "table";
+  }
+}
+
+// A proto field line: an optional `repeated`, a type (`map<...>` allowed), a field
+// name, `=`, a tag, `;`. Reserved lines, `oneof`, options, and nested blocks are
+// ignored by requiring the `= <tag>;` tail.
+const PROTO_FIELD = /^\s*(map<[^>]+>|repeated\s+[\w.]+|[\w.]+)\s+([a-z_]\w*)\s*=\s*\d+\s*;/;
+const PROTO_MESSAGE_OPEN = /^message\s+([A-Za-z_]\w*)\s*\{/;
+// A `oneof` groups alternatives that are the enclosing message's own fields; any
+// other block (`message`/`enum`) owns its fields and must not leak them upward, so
+// non-`oneof` openers default to an isolating `other` frame.
+const PROTO_ONEOF_OPEN = /^\s*oneof\s+[A-Za-z_]\w*\s*\{/;
+
+function parseProtoMessages(protoText: string): OpenApiElement[] {
+  const elements: OpenApiElement[] = [];
+  const lines = protoText.split("\n");
+  let current: { name: string; parameters: OpenApiParam[] } | null = null;
+  // Block-kind frames nested inside the current message, excluding the message
+  // root (which `current !== null` represents). Integer depth cannot tell a
+  // `oneof` alternative (a parent field) from a nested-`message` field (not one);
+  // the frame kinds carry that distinction.
+  let frames: Array<"oneof" | "other"> = [];
+
+  const emit = () => {
+    if (current === null) return;
+    elements.push({
+      type: "FUNCTION",
+      name: `create_${snake(current.name)}_message`,
+      description: "",
+      parameters: current.parameters,
+      returnvalues: [],
+    });
+    current = null;
+    frames = [];
+  };
+
+  // Account one message-body segment (a whole line, or the tail of the open line
+  // after its header brace): count a field only when the frames above the root
+  // are empty or all `oneof`, then apply the segment's braces — a `}` that finds
+  // no nested frame closes the message root.
+  const processBody = (body: string): void => {
+    if (current === null) return;
+    const field = PROTO_FIELD.exec(body);
+    if (field !== null && frames.every((f) => f === "oneof")) {
+      const slot: OpenApiParam = {
+        name: field[2] as string,
+        doc: "",
+        types: [protoType(field[1] as string)],
+      };
+      if (frames.includes("oneof")) slot.is_optional = "True";
+      current.parameters.push(slot);
+    }
+    const openKind: "oneof" | "other" = PROTO_ONEOF_OPEN.test(body) ? "oneof" : "other";
+    for (let i = 0; i < (body.match(/\{/g) ?? []).length; i++) frames.push(openKind);
+    for (let i = 0; i < (body.match(/\}/g) ?? []).length; i++) {
+      if (frames.length > 0) {
+        frames.pop();
+      } else {
+        emit();
+        return;
+      }
+    }
+  };
+
+  for (const line of lines) {
+    if (current === null) {
+      const open = PROTO_MESSAGE_OPEN.exec(line);
+      if (open !== null) {
+        current = { name: open[1] as string, parameters: [] };
+        frames = [];
+        // Process the same line's remainder so `message Ping {}` closes here
+        // instead of swallowing every following top-level message.
+        processBody(line.slice(open[0].length));
+      }
+      continue;
+    }
+    processBody(line);
+  }
+  return elements;
+}
+
+/**
+ * Parse the pinned swagger JSON and realtime `.proto` into the shared ref-doc
+ * `doc` shape. Swagger operations, swagger object definitions, and proto messages
+ * each contribute one element; the first occurrence of a codegen'd name wins so a
+ * definition and a like-named operation never emit a duplicate member.
+ */
+export function parseOpenApi(swaggerText: string, protoText: string): OpenApiDoc {
+  const root = JSON.parse(swaggerText) as SwaggerRoot;
+  const all = [
+    ...parseSwaggerOperations(root),
+    ...parseSwaggerDefinitions(root),
+    ...parseProtoMessages(protoText),
+  ];
+  const seen = new Set<string>();
+  const elements: OpenApiElement[] = [];
+  for (const element of all) {
+    if (seen.has(element.name)) continue;
+    seen.add(element.name);
+    elements.push(element);
+  }
+  return { info: { namespace: "", brief: "", description: "" }, elements };
+}

package/scripts/sync-authored-types.ts

@@ -0,0 +1,249 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { extractApiDoc } from "./extract-api-doc";
+import { type ApiDocElement, importUpstreamDocs } from "./import-upstream-docs";
+import { type LuaMember, parseLuaSurface } from "./parse-lua-surface";
+
+/**
+ * The authored/forked front-end: a fourth `library-types` corpus mode beside the
+ * LuaLS (`sync-luals-types.ts`), `.script_api` (`sync-script-api-types.ts`), and
+ * markdown (`sync-markdown-types.ts`) lanes. The other three ingest a *non-*`.d.ts`
+ * primary source and generate a declaration; this one is for a library whose
+ * upstream has no usable structured source, so its `.d.ts` is hand-authored or
+ * forked from the retired ts-defold `generated/` golden and vendored under
+ * `fixtures/authored/<moduleId>.d.ts`.
+ *
+ * A vendored authored `.d.ts` is already target-form — a `declare module
+ * '<moduleId>'` ambient — so the lane is light: it emits the vendored source
+ * verbatim as the `generated/<namespace>.d.ts` golden and runs
+ * `extractApiDoc` for the `api-doc/<namespace>.json` the docs-site consumes. The
+ * api-doc alone carries one thing the fork does not: where a target vendors its
+ * upstream `.lua` and the fork documents a member nowhere, upstream's own LuaDoc
+ * summary is lowered in, marked `docSource: "upstream"` (see
+ * `import-upstream-docs.ts`). The *emitted* surface is still the vendored authored
+ * source untouched, so the go/no-go gate is a
+ * forked-vs-generated identity diff (see the golden loop) — emission fidelity.
+ * There is no *type* coverage comparison because upstream declares no types; the
+ * *surface* is another matter, and a target that vendors its upstream `.lua` under
+ * `upstreamLua` is measured on member names and arity by `authored-parity.ts`.
+ * Beyond that, a corrected fork's accuracy rests on its manual audit against
+ * upstream plus the per-library shape assertions in the sibling test.
+ */
+/**
+ * Why a target's surface cannot be measured against upstream. A closed set: the
+ * alternative to `upstreamLua` has to be a *chosen* category, because free prose
+ * would let "nobody looked yet" and "looked, and it is genuinely unmeasurable"
+ * read the same in the config.
+ *
+ * - `unresolved-path` — the `moduleId`-derived path does not resolve at the
+ *   pinned `ref` (including a repository that no longer exists there).
+ * - `no-module-file` — the upstream resolves but declares no single module file
+ *   this target could be measured against.
+ * - `unparseable-shape` — the module file exists but closes in a way
+ *   `parseLuaSurface` refuses, such as a metatable that could delegate members
+ *   no column-0 scan would find.
+ */
+export const PARITY_VERDICT_REASONS = [
+  "no-module-file",
+  "unresolved-path",
+  "unparseable-shape",
+] as const;
+
+export type ParityVerdictReason = (typeof PARITY_VERDICT_REASONS)[number];
+
+export interface ParityVerdict {
+  reason: ParityVerdictReason;
+  note: string;
+}
+
+export interface AuthoredTarget {
+  repo: string;
+  ref: string;
+  // Package-relative path of the vendored authored/forked `.d.ts`
+  // (`fixtures/authored/<moduleId>.d.ts`).
+  authored: string;
+  moduleId: string;
+  namespace: string;
+  generated: string;
+  apiDoc: string;
+  // Defaults to `fidelity/<namespace>.json` when omitted. A fork carries no
+  // fidelity artifact — there is no primary source to measure against, and the
+  // emit is lossless by construction — but the field mirrors the sibling lanes
+  // so a future hand-authored target can record one.
+  fidelity: string;
+  // SPDX-style license id, surfaced by the docs-site provenance block. Optional
+  // in the config; defaults to "".
+  license: string;
+  // Package-relative paths of the vendored upstream `.lua` sources this target's
+  // surface is measured against (`authored-parity.ts`). Optional and defaulted to
+  // `[]`: a target with no vendored upstream is simply unmeasured, which is why it
+  // must not join `REQUIRED_FIELDS`.
+  upstreamLua: string[];
+  // Why this target vendors no upstream `.lua`. Mutually exclusive with a
+  // non-empty `upstreamLua`, and one of the two is mandatory: neither field is
+  // required on its own, but the *disjunction* is, so a target cannot land
+  // unexamined and read as measured-and-clean. Absent on a measured target.
+  parityVerdict?: ParityVerdict;
+}
+
+export interface AuthoredTargets {
+  targets: AuthoredTarget[];
+}
+
+const REQUIRED_FIELDS = [
+  "repo",
+  "ref",
+  "authored",
+  "moduleId",
+  "namespace",
+  "generated",
+  "apiDoc",
+] as const;
+
+/** Validate the parity declaration: exactly one of a non-empty `upstreamLua` and
+ * a well-formed `parityVerdict`. Enforced here rather than through
+ * `REQUIRED_FIELDS` because neither field is required on its own — the bijection
+ * between them is the gate. */
+function validateParityDeclaration(
+  label: string,
+  upstreamLua: string[],
+  verdict: ParityVerdict | undefined,
+): void {
+  if (upstreamLua.length > 0 && verdict !== undefined) {
+    throw new Error(
+      `authored-targets.json: entry ${label} declares both upstreamLua and parityVerdict — a measured target carries no verdict.`,
+    );
+  }
+  if (upstreamLua.length === 0 && verdict === undefined) {
+    throw new Error(
+      `authored-targets.json: entry ${label} declares neither upstreamLua nor parityVerdict — vendor its upstream .lua, or record a parityVerdict saying why it cannot be measured.`,
+    );
+  }
+  if (verdict === undefined) return;
+  if (!(PARITY_VERDICT_REASONS as readonly string[]).includes(verdict.reason)) {
+    throw new Error(
+      `authored-targets.json: entry ${label} has parityVerdict reason "${verdict.reason}", which is not one of ${PARITY_VERDICT_REASONS.join(", ")}.`,
+    );
+  }
+  if (typeof verdict.note !== "string" || verdict.note.trim() === "") {
+    throw new Error(
+      `authored-targets.json: entry ${label} has a parityVerdict with an empty note — say what was looked at and why it could not be measured.`,
+    );
+  }
+}
+
+/**
+ * Read `authored-targets.json`, validate every required field per entry, and fill
+ * optional defaults (`fidelity` → `fidelity/<namespace>.json`, `license` → "",
+ * `upstreamLua` → []).
+ * Throws on the first missing field naming both the field and the offending entry
+ * (its `moduleId`, or its index when `moduleId` itself is absent) — the loud-fail
+ * discipline `readMarkdownTargets`/`readScriptApiTargets`/`readLualsTargets` use.
+ * Also throws when an entry's parity declaration is missing, doubled, or
+ * malformed (see `validateParityDeclaration`).
+ */
+export function readAuthoredTargets(packageRoot: string): AuthoredTarget[] {
+  const parsed = JSON.parse(readFileSync(join(packageRoot, "authored-targets.json"), "utf8")) as {
+    targets: Partial<AuthoredTarget>[];
+  };
+  return parsed.targets.map((entry, index) => {
+    const label = typeof entry.moduleId === "string" ? entry.moduleId : `index ${index}`;
+    for (const field of REQUIRED_FIELDS) {
+      if (entry[field] === undefined) {
+        throw new Error(
+          `authored-targets.json: entry ${label} is missing required field "${field}".`,
+        );
+      }
+    }
+    const upstreamLua = entry.upstreamLua ?? [];
+    validateParityDeclaration(label, upstreamLua, entry.parityVerdict);
+    return {
+      repo: entry.repo as string,
+      ref: entry.ref as string,
+      authored: entry.authored as string,
+      moduleId: entry.moduleId as string,
+      namespace: entry.namespace as string,
+      generated: entry.generated as string,
+      apiDoc: entry.apiDoc as string,
+      fidelity: entry.fidelity ?? `fidelity/${entry.namespace as string}.json`,
+      license: entry.license ?? "",
+      upstreamLua,
+      ...(entry.parityVerdict === undefined ? {} : { parityVerdict: entry.parityVerdict }),
+    };
+  });
+}
+
+function readAuthoredSource(packageRoot: string, target: AuthoredTarget): string {
+  return readFileSync(join(packageRoot, target.authored), "utf8");
+}
+
+/**
+ * The `generated/<namespace>.d.ts` golden, under whatever stem the entry pins —
+ * a bare segment or the dotted `moduleId`. The vendored authored
+ * `.d.ts` is already a `declare module '<moduleId>'` ambient, so the emit is the
+ * source verbatim — the vendored surface passes through unchanged, which is what
+ * makes the emission lossless. It says nothing about how that vendored surface
+ * compares to upstream.
+ */
+export function emitAuthoredDeclaration(packageRoot: string, target: AuthoredTarget): string {
+  return readAuthoredSource(packageRoot, target);
+}
+
+/** The pinned upstream members by name, the way `authored-parity.ts` builds them:
+ * a later definition of a name wins, matching Lua. Empty for a target that vendors
+ * no upstream `.lua`, which is then never parsed. */
+function upstreamMembers(packageRoot: string, target: AuthoredTarget): Map<string, LuaMember> {
+  const members = new Map<string, LuaMember>();
+  for (const relative of target.upstreamLua) {
+    for (const member of parseLuaSurface(readFileSync(join(packageRoot, relative), "utf8")).members)
+      members.set(member.name, member);
+  }
+  return members;
+}
+
+/**
+ * `extractApiDoc` the vendored `.d.ts` under the pinned publish namespace, plus
+ * upstream's own LuaDoc for the members the fork documents nowhere, pretty-printed
+ * as the `api-doc/<namespace>.json` golden.
+ *
+ * The api-doc is therefore the fork *plus* imported upstream prose, and it is the
+ * only artifact that is: the emitted `generated/<namespace>.d.ts` stays the vendored
+ * source verbatim, so the identity diff still proves the emit is lossless. An
+ * imported element carries `docSource: "upstream"` through to the docs-site, which
+ * marks it rather than presenting it as first-party. See `import-upstream-docs.ts`
+ * for the merge rules.
+ */
+export function lowerAuthoredApiDoc(packageRoot: string, target: AuthoredTarget): string {
+  // `extractApiDoc` returns `unknown`; the merge needs the element list, and
+  // overwriting the existing `elements` key by spread keeps it in place, so the
+  // golden's key order is unchanged.
+  const doc = extractApiDoc(readAuthoredSource(packageRoot, target), target.namespace) as Record<
+    string,
+    unknown
+  > & { elements: ApiDocElement[] };
+  const elements = importUpstreamDocs(doc.elements, upstreamMembers(packageRoot, target));
+  return `${JSON.stringify({ ...doc, elements }, null, 2)}\n`;
+}
+
+if (import.meta.main) {
+  const root = join(import.meta.dir, "..");
+  const argv = process.argv.slice(2);
+  if (argv.includes("--emit")) {
+    for (const target of readAuthoredTargets(root)) {
+      const contents = emitAuthoredDeclaration(root, target);
+      const dest = join(root, target.generated);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, contents);
+      console.log(`emitted ${target.moduleId} -> ${target.generated}`);
+    }
+  }
+  if (argv.includes("--api-doc")) {
+    for (const target of readAuthoredTargets(root)) {
+      const json = lowerAuthoredApiDoc(root, target);
+      const dest = join(root, target.apiDoc);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, json);
+      console.log(`lowered ${target.moduleId} -> ${target.apiDoc}`);
+    }
+  }
+}

package/scripts/sync-library-types.ts

@@ -2,6 +2,11 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import ts from "typescript";
 import { extractApiDoc } from "./extract-api-doc";
+import { readAuthoredTargets } from "./sync-authored-types";
+import { readLualsTargets } from "./sync-luals-types";
+import { readMarkdownTargets } from "./sync-markdown-types";
+import { readOpenApiTargets } from "./sync-openapi-types";
+import { readScriptApiTargets } from "./sync-script-api-types";
 
 /**
  * ts-defold/library core-type references -> the @defold-typescript/types surface.
@@ -330,6 +335,65 @@ export function classifyLibraryDirs(
     .sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0));
 }
 
+/**
+ * The union every maintained-here lane contributes: authored `moduleId`s, and
+ * the `namespace`s of the LuaLS, script_api, OpenAPI and markdown front-ends.
+ * Namespaces are matched in both forms because the lanes use both — druid-style
+ * libraries register a bare `tweener`, while `defold-saver` registers the dotted
+ * `saver.saver` / `saver.storage`.
+ */
+export interface MaintainedHereRegistry {
+  moduleIds: ReadonlySet<string>;
+  namespaces: ReadonlySet<string>;
+}
+
+/**
+ * The subset of `modules` this repo maintains itself rather than sourcing from
+ * ts-defold/library. A live `library-targets.json` row always wins, so a module
+ * registered on a maintained-here lane *and* still vendored stays
+ * ts-defold-sourced and keeps its dir classified `already-vendored`. The
+ * registry is empty today, so no committed module takes that branch; it is what
+ * a returning row would take.
+ */
+export function maintainedHereModules(
+  modules: readonly string[],
+  registry: MaintainedHereRegistry,
+  liveModules: ReadonlySet<string>,
+): Set<string> {
+  return new Set(
+    modules.filter(
+      (m) =>
+        !liveModules.has(m) &&
+        (registry.moduleIds.has(m) ||
+          registry.namespaces.has(m) ||
+          registry.namespaces.has(m.split(".")[0] as string)),
+    ),
+  );
+}
+
+/**
+ * The upstream dirs this repo has severed onto a maintained-here lane. Severance
+ * deletes a library's `library-targets.json` row, but its dir still exists
+ * upstream — so a regen would re-add it under whatever its module shape implies
+ * unless it is filtered out first. The registries give an exact derivation with
+ * no hand-maintained list: a dir is severed iff it has at least one module and
+ * every module is maintained here. A dir mixing maintained-here and live modules
+ * is still upstream-sourced and stays classified — `nakama-defold` was the last
+ * such dir, and severed whole once its live row went.
+ */
+export function severedDirsFromModules(
+  modulesByDir: Map<string, string[]>,
+  registry: MaintainedHereRegistry,
+  liveModules: ReadonlySet<string>,
+): Set<string> {
+  const severed = new Set<string>();
+  for (const [dir, modules] of modulesByDir) {
+    const maintained = maintainedHereModules(modules, registry, liveModules);
+    if (modules.length > 0 && maintained.size === modules.length) severed.add(dir);
+  }
+  return severed;
+}
+
 interface GithubTreeResponse {
   tree?: { path: string }[];
 }
@@ -376,8 +440,28 @@ export type ListTree = (source: LibrarySource) => Promise<string[]>;
 const defaultListTree: ListTree = (source) => githubTreePaths(repoSlug(source.repo), source.commit);
 
 /**
- * Enumerate every ts-defold/library dir at the pin, classify each by its
- * module-name shape, and write `library-classification.json`. The `listTree`
+ * Read every maintained-here registry off the package root and union them.
+ * Each reader `readFileSync`s unconditionally and throws on a missing required
+ * field — deliberately no absent-file fallback, so a lane added without its
+ * fixture fails loudly rather than silently un-severing that lane's dirs.
+ */
+export function readMaintainedHereRegistry(packageRoot: string): MaintainedHereRegistry {
+  return {
+    moduleIds: new Set(readAuthoredTargets(packageRoot).map((t) => t.moduleId)),
+    namespaces: new Set([
+      ...readLualsTargets(packageRoot).map((t) => t.namespace),
+      ...readScriptApiTargets(packageRoot).map((t) => t.namespace),
+      ...readOpenApiTargets(packageRoot).map((t) => t.namespace),
+      ...readMarkdownTargets(packageRoot).map((t) => t.namespace),
+    ]),
+  };
+}
+
+/**
+ * Enumerate every ts-defold/library dir at the pin, drop the dirs severed onto
+ * a maintained-here lane, classify each survivor by its module-name shape, and write
+ * `library-classification.json`. Filtering happens here, not in
+ * `classifyLibraryDirs`, so that pass stays a pure map-and-sort. The `listTree`
  * seam keeps the pass offline-testable; only the CLI wires the real call, and it
  * stays out of CI (mirrors `--check`). The manifest pins the same `source` as
  * `library-targets.json`.
@@ -392,9 +476,21 @@ export async function writeClassification(
     targets.map((t) => t.path.split("/")[1]).filter((d): d is string => d !== undefined),
   );
   const coveredByGoalDirs = new Set(["defold-lldebugger", "defold-xmath"]);
+  const liveModules = new Set(targets.map((t) => t.module));
+
+  const registry = readMaintainedHereRegistry(packageRoot);
 
   const modulesByDir = libraryModulesFromTree(await listTree(source));
-  const dirs = [...modulesByDir].map(([dir, modules]) => ({ dir, modules }));
+  const severedDirs = severedDirsFromModules(modulesByDir, registry, liveModules);
+  const dirs = [...modulesByDir]
+    // Vendored wins: a stale maintained-here entry can never erase a live ts-defold row.
+    .filter(([dir]) => !severedDirs.has(dir) || vendoredDirs.has(dir))
+    // A survivor records only its ts-defold-sourced remainder as evidence, so its
+    // written shape agrees with its own `modules` array.
+    .map(([dir, modules]) => {
+      const maintained = maintainedHereModules(modules, registry, liveModules);
+      return { dir, modules: modules.filter((m) => !maintained.has(m)) };
+    });
   const entries = classifyLibraryDirs(dirs, { vendoredDirs, coveredByGoalDirs });
   writeFileSync(
     join(packageRoot, "library-classification.json"),