@gusnips/sdkgen 0.1.0

package/src/contract.ts

@@ -0,0 +1,249 @@
+/**
+ * Copying the API's own type declarations into its SDK, with their comments.
+ *
+ * A published SDK cannot depend on the API's workspace, so the types it answers with have to
+ * travel inside it. A `.d.ts` emit would carry the types and drop the prose, and the prose is most
+ * of what makes an SDK pleasant to hold, so this reads each declaration as it is written at home
+ * and copies it whole. Five generators did this with one hand-written reader, and each copy had
+ * fixed something the others had not:
+ * - a property KEY is not a reference (`VALIDATION_ERROR: 400` names no type);
+ * - an `export function` is a braced block, like an interface;
+ * - `(typeof X)[number]` can be written as its literal union, where the array would be dead.
+ * And all five broke what the reader rests on, that the blanked text matches the original line for
+ * line: an escaped newline in a string moved every later line, a backslash at the end of a `//`
+ * comment blanked the next line, a `/*` followed by `/` closed on its own star, and a one-line
+ * `{}` block ran on into the next declaration.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { BUILTIN } from "./types.ts";
+
+export interface LiftOptions {
+  /** The directory `sources` are relative to, usually the repo root. */
+  root: string;
+  /** The files a public type may come from. They are written out in this order. */
+  sources: readonly string[];
+  /** The names the SDK needs. Everything they mention comes along. */
+  roots: readonly string[];
+  /**
+   * Write `(typeof X)[number]` as its literal union, and leave the array out. Off by default: an SDK
+   * that re-exports its contract publishes that array, so dropping it is a breaking change, and
+   * each member's doc comment goes with it.
+   */
+  inlineTuples?: boolean;
+  /**
+   * Keep `export` on the roots only. What they mention is still written, without it, so the SDK's
+   * public names are exactly the ones listed. Off by default: everything written is exported.
+   */
+  exportOnlyRoots?: boolean;
+}
+
+interface Block {
+  name: string;
+  /** The declaration with its doc comment, as it reads at home. */
+  source: string;
+  /** The names it mentions, followed so nothing lands half-defined. */
+  refs: string[];
+}
+
+/**
+ * The source with every comment and string body blanked, one character for one character and a
+ * newline for a newline, so structure can be read off it while the ORIGINAL lines are what gets
+ * copied. Without it a `;` inside a sentence ends a declaration early, and every capitalized word
+ * in the prose looks like a type. `keepStrings` blanks the comments only, for reading the strings
+ * themselves: an apostrophe in a comment is not a quote.
+ *
+ * ponytail: a regex literal is read as code, so a quote inside one (`/"/`) opens a string that
+ * runs to the next quote. Contract files are declarations, where that does not come up; one that
+ * needs it would need a real tokenizer here.
+ */
+export function blankCommentsAndStrings(source: string, { keepStrings = false } = {}): string {
+  let out = "";
+  let state: "code" | "line" | "block" | '"' | "'" | "`" = "code";
+  const blank = (c: string | undefined) => (c === "\n" ? "\n" : c === undefined ? "" : " ");
+  const inString = (c: string | undefined) => (keepStrings ? (c ?? "") : blank(c));
+  for (let i = 0; i < source.length; i++) {
+    const c = source[i] ?? "";
+    const next = source[i + 1];
+    if (state === "code") {
+      if (c === "/" && (next === "/" || next === "*")) {
+        // Both characters of the opener, so the `*` of `/*/` cannot also close it.
+        state = next === "/" ? "line" : "block";
+        out += "  ";
+        i++;
+      } else if (c === '"' || c === "'" || c === "`") {
+        state = c;
+        out += inString(c);
+      } else out += c;
+      continue;
+    }
+    if (state === "line" || state === "block") {
+      if (state === "block" && c === "*" && next === "/") {
+        state = "code";
+        out += "  ";
+        i++;
+        continue;
+      }
+      if (c === "\n" && state === "line") state = "code";
+      out += blank(c);
+      continue;
+    }
+    if (c === "\\") {
+      // An escape never closes a string, and the character it escapes may be a newline.
+      out += inString(c) + inString(next);
+      i++;
+      continue;
+    }
+    if (c === state) state = "code";
+    out += inString(c);
+  }
+  return out;
+}
+
+/** Split one file into its exported top-level declarations. */
+function readBlocks(text: string): Block[] {
+  const lines = text.split("\n");
+  const clean = blankCommentsAndStrings(text).split("\n");
+  const blocks: Block[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = /^export (interface|type|const|function) (\w+)/.exec(clean[i] ?? "");
+    if (!match?.[2]) continue;
+    const name = match[2];
+
+    // Back over the doc comment sitting on top of the declaration.
+    let start = i;
+    while (start > 0) {
+      const above = (lines[start - 1] ?? "").trim();
+      if (!above || (!above.startsWith("*") && !above.startsWith("/*"))) break;
+      start--;
+    }
+
+    // Forward to its end: the first `;` outside every bracket, since a mapped type carries one on
+    // an inner line, or for an interface or a function, the line that closes its brackets. That
+    // can be its first (`export interface Empty {}`); waiting for a lone `}`, as every copy did,
+    // swallowed the declaration after it.
+    const braced = match[1] === "interface" || match[1] === "function";
+    let end = i;
+    let depth = 0;
+    outer: for (; end < lines.length; end++) {
+      for (const char of clean[end] ?? "") {
+        if ("{[(".includes(char)) depth++;
+        else if ("}])".includes(char)) depth--;
+        else if (char === ";" && depth === 0) break outer;
+      }
+      if (braced && depth === 0) break;
+    }
+
+    const body = clean
+      .slice(i, end + 1)
+      .join("\n")
+      // A property KEY is not a reference: `VALIDATION_ERROR: 400` names a member, not a type.
+      .replace(/\b[A-Z][A-Za-z0-9_]*(?=\s*\??:)/g, " ");
+    const refs = [...new Set(body.match(/\b[A-Z][A-Za-z0-9_]*\b/g) ?? [])].filter(
+      // ponytail: a short name is taken for a type parameter (`T`, `K`). A wrong guess is loud,
+      // not silent: a skipped name that WAS needed leaves the SDK missing a type, and it stops
+      // compiling.
+      (ref) => ref !== name && ref.length > 2 && !BUILTIN.has(ref),
+    );
+    blocks.push({ name, source: lines.slice(start, end + 1).join("\n"), refs });
+    i = end;
+  }
+  return blocks;
+}
+
+/**
+ * With `inlineTuples`, `export type Plan = (typeof PLANS)[number];` becomes
+ * `export type Plan = "free" | "pro";`, and the array is left out. Only a tuple of plain string
+ * literals qualifies; anything else throws, because guessing a union into a published type is
+ * worse than stopping.
+ */
+function inlineTupleUnions(index: Map<string, Block>): void {
+  for (const block of index.values()) {
+    const alias = /export type (\w+) = \(?typeof (\w+)\)?\[number\];/.exec(block.source);
+    if (!alias?.[2]) continue;
+    const tuple = index.get(alias[2]);
+    if (tuple === undefined) continue; // reported as missing below
+    // Comments out first, strings kept: a member's doc comment can hold an apostrophe.
+    const code = blankCommentsAndStrings(tuple.source, { keepStrings: true });
+    const literal = /=\s*\[([\s\S]*?)\]\s*as const\s*;/.exec(code);
+    const members = literal?.[1]?.match(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g) ?? [];
+    const rest = literal?.[1]?.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g, "");
+    if (literal === null || rest === undefined || /[^\s,]/.test(rest)) {
+      throw new Error(
+        `${alias[2]} must be a tuple of string literals \`as const\` for ${block.name} to be written as a union.`,
+      );
+    }
+    const union = members.map((member) => {
+      let unreadable = false;
+      const text = member.slice(1, -1).replace(/\\([\s\S])/g, (_escape, char: string) => {
+        unreadable ||= !`"'\\`.includes(char);
+        return char;
+      });
+      // ponytail: only a quote or a backslash is unescaped. Any other escape (`\n`, `\u00e9`)
+      // needs the language's whole table, so it stops rather than write a wrong member.
+      if (unreadable) {
+        throw new Error(
+          `${alias[2]} has a member with an escape this cannot read: ${member}. Write it without one, or leave inlineTuples off.`,
+        );
+      }
+      return JSON.stringify(text);
+    });
+    block.source = block.source.replace(
+      alias[0],
+      `export type ${block.name} = ${union.join(" | ") || "never"};`,
+    );
+    block.refs = [];
+  }
+}
+
+/**
+ * Every declaration the roots need, in source order, as one file's text. A name nobody declares
+ * throws with the list of files searched: a contract with a dangling reference does not compile,
+ * and finding out here beats finding out at publish.
+ */
+export function liftContract({
+  root,
+  sources,
+  roots,
+  inlineTuples = false,
+  exportOnlyRoots = false,
+}: LiftOptions): string {
+  const files = sources.map((file) => ({
+    file,
+    blocks: readBlocks(readFileSync(join(root, file), "utf8")),
+  }));
+  const index = new Map<string, Block>();
+  for (const { blocks } of files) for (const block of blocks) index.set(block.name, block);
+  if (inlineTuples) inlineTupleUnions(index);
+
+  const needed = new Set<string>();
+  const missing = new Set<string>();
+  const visit = (name: string): void => {
+    if (needed.has(name)) return;
+    const block = index.get(name);
+    if (block === undefined) {
+      missing.add(name);
+      return;
+    }
+    needed.add(name);
+    block.refs.forEach(visit);
+  };
+  roots.forEach(visit);
+  if (missing.size > 0) {
+    throw new Error(
+      `No declaration found for ${[...missing].join(", ")}. Export it from one of:\n  ${sources.join("\n  ")}`,
+    );
+  }
+
+  const chunks: string[] = [];
+  for (const { file, blocks } of files) {
+    const wanted = blocks.filter((b) => needed.has(b.name));
+    if (wanted.length === 0) continue;
+    chunks.push(`// ── from ${file} ${"─".repeat(Math.max(0, 60 - file.length))}\n`);
+    const text = (b: Block) =>
+      exportOnlyRoots && !roots.includes(b.name) ? b.source.replace(/^export /m, "") : b.source;
+    chunks.push(wanted.map(text).join("\n\n"));
+  }
+  return chunks.join("\n");
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+export { liftContract, type LiftOptions } from "./contract.ts";
+export {
+  camelCase,
+  docComment,
+  fieldsOf,
+  inputJsonSchema,
+  paramsInterface,
+  pascalCase,
+  typeNames,
+  typeOf,
+  wrapLines,
+  type JsonObject,
+  type SchemaSource,
+  type StandardJsonSchema,
+} from "./types.ts";
+export {
+  writeGenerated,
+  type GeneratedFiles,
+  type WriteOptions,
+  type WriteResult,
+} from "./write.ts";

package/src/readme.test.ts

@@ -0,0 +1,24 @@
+/**
+ * The README's examples, run. Every literal below is what the README prints beside the call, and a
+ * snippet nobody executes rots quietly.
+ */
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { camelCase, fieldsOf, inputJsonSchema, pascalCase, typeNames, typeOf } from "./index.ts";
+
+describe("README", () => {
+  it("prints what the README says", () => {
+    expect(typeOf({ type: ["string", "null"] })).toBe("string | null");
+    expect(fieldsOf(inputJsonSchema(z.object({ to: z.string().describe("Who gets it.") })))).toBe(
+      "    /** Who gets it. */\n    to: string;\n",
+    );
+    expect(typeNames("Page<Job>[]")).toEqual(["Page", "Job"]);
+    expect([camelCase("send_message"), pascalCase("send_message")]).toEqual([
+      "sendMessage",
+      "SendMessage",
+    ]);
+    expect(
+      fieldsOf({ type: "object", properties: { "content-type": { type: "string" } } }, ""),
+    ).toBe('"content-type"?: string;\n');
+  });
+});

package/src/types.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import {
+  camelCase,
+  docComment,
+  fieldsOf,
+  inputJsonSchema,
+  paramsInterface,
+  pascalCase,
+  typeNames,
+  typeOf,
+  wrapLines,
+} from "./types.ts";
+
+describe("typeOf", () => {
+  it.each([
+    [{ type: "string" }, "string"],
+    [{ type: "integer" }, "number"],
+    [{ type: "boolean" }, "boolean"],
+    [{ enum: ["qr", "code", null] }, '"qr" | "code" | null'],
+    [{ const: 5 }, "5"],
+    [{ type: ["number", "null"] }, "number | null"],
+    [{ anyOf: [{ type: "string" }, { type: "null" }] }, "string | null"],
+    [{ type: "array", items: { enum: ["a", "b"] } }, '("a" | "b")[]'],
+    [{ type: "array", items: { type: "string" } }, "string[]"],
+    [{ type: "array" }, "unknown[]"],
+    [{ type: "array", prefixItems: [{ type: "number" }, { type: "string" }] }, "[number, string]"],
+    [
+      { type: "array", prefixItems: [{ type: "number" }], items: { type: "boolean" } },
+      "[number, ...boolean[]]",
+    ],
+    [{ type: "object", additionalProperties: { type: "string" } }, "Record<string, string>"],
+    [{ type: "object" }, "Record<string, unknown>"],
+    [{}, "unknown"],
+    [{ description: "Anything at all." }, "unknown"],
+  ])("writes %j as %s", (schema, type) => {
+    expect(typeOf(schema)).toBe(type);
+  });
+
+  it("reads a boolean schema", () => {
+    expect(typeOf(true)).toBe("unknown");
+    expect(typeOf(false)).toBe("never");
+  });
+
+  it("writes an inline object one level in", () => {
+    expect(
+      typeOf({ type: "object", properties: { a: { type: "string" } }, required: ["a"] }, "    "),
+    ).toBe("{\n        a: string;\n    }");
+  });
+
+  it("refuses a schema it would have to guess at", () => {
+    expect(() => typeOf({ allOf: [{ type: "string" }] })).toThrow(/Cannot write this JSON Schema/);
+    expect(() => typeOf({ $ref: "#/$defs/X" })).toThrow(/Cannot write this JSON Schema/);
+    expect(() => typeOf({ type: "array", items: 5 })).toThrow(/Not a JSON Schema: 5/);
+  });
+});
+
+describe("fieldsOf", () => {
+  it("keeps each description, marks the optional ones, and quotes a name that needs it", () => {
+    const schema = inputJsonSchema(
+      z.object({
+        to: z.string().describe("Who gets it."),
+        "reply-to": z.string().optional(),
+      }),
+    );
+    expect(fieldsOf(schema)).toBe(
+      '    /** Who gets it. */\n    to: string;\n    "reply-to"?: string;\n',
+    );
+  });
+
+  it("leaves out the fields it is told to", () => {
+    const schema = { type: "object", properties: { a: { type: "string" }, b: { type: "string" } } };
+    expect(fieldsOf(schema, "    ", ["a"])).toBe("    b?: string;\n");
+  });
+});
+
+describe("paramsInterface", () => {
+  const schema = inputJsonSchema(
+    z.object({ id: z.string(), type: z.enum(["image"]), caption: z.string().optional() }),
+  );
+
+  it("is optional when every field left is optional", () => {
+    expect(paramsInterface("SendParams", schema, ["id", "type"])).toEqual({
+      source: "export interface SendParams {\n    caption?: string;\n}\n",
+      optional: true,
+    });
+    expect(paramsInterface("SendParams", schema)?.optional).toBe(false);
+  });
+
+  it("is nothing when no field is left", () => {
+    expect(paramsInterface("NoParams", { type: "object", properties: {} })).toBeNull();
+  });
+});
+
+describe("docComment", () => {
+  it("wraps under the opener, the way the generated files already read", () => {
+    const text = Array.from({ length: 30 }, (_, i) => `word${i}`).join(" ");
+    const out = docComment(text, "    ");
+    expect(out.startsWith("    /** word0 ")).toBe(true);
+    expect(out).toContain("\n     *  word");
+    expect(out.endsWith(" */\n")).toBe(true);
+    expect(out.split("\n").every((line) => line.length <= 100)).toBe(true);
+  });
+
+  it("gives the bare lines, for a comment laid out another way", () => {
+    expect(wrapLines("a */ b", "")).toEqual(["a *\\/ b"]);
+    expect(wrapLines("one two three", " ".repeat(86))).toEqual(["one two", "three"]);
+  });
+
+  it("cannot be closed early by the text", () => {
+    expect(docComment("Matches /files/*/ only.", "")).toBe("/** Matches /files/*\\/ only. */\n");
+  });
+});
+
+describe("typeNames", () => {
+  it("finds the names inside a generic, once, without TypeScript's own", () => {
+    expect(typeNames("V1ListPage<JobDto>[] | Record<string, JobDto> | null")).toEqual([
+      "V1ListPage",
+      "JobDto",
+    ]);
+  });
+});
+
+describe("names", () => {
+  it("turns a tool name into a method name and a type name", () => {
+    expect(camelCase("send_media_image")).toBe("sendMediaImage");
+    expect(pascalCase("send_media")).toBe("SendMedia");
+  });
+});
+
+describe("inputJsonSchema", () => {
+  it("says what to upgrade when a schema cannot describe itself", () => {
+    expect(() => inputJsonSchema({ "~standard": { vendor: "zod" } })).toThrow(/zod does from 4\.4/);
+  });
+
+  it("stops on a zod type JSON Schema cannot hold, rather than writing it as any value", () => {
+    expect(() => inputJsonSchema(z.object({ at: z.date() }))).toThrow(/Date cannot be represented/);
+  });
+
+  it("takes JSON Schema as it is", () => {
+    const schema = { type: "object" };
+    expect(inputJsonSchema(schema)).toBe(schema);
+  });
+});

package/src/types.ts

@@ -0,0 +1,250 @@
+/**
+ * Writing a JSON Schema as a TypeScript type, with each field's description kept as its doc
+ * comment.
+ *
+ * Five generators each wrote this, and the fixes were spread across them: `type: [..., "null"]`
+ * in three, `{}` as `unknown` and a record as `Record<string, T>` in two, a boolean schema and a
+ * tuple in one. The rule all five kept is the one that matters most: **never guess a type into a
+ * published SDK.** A schema node this does not understand throws; it never becomes `unknown`.
+ */
+
+export type JsonObject = Record<string, unknown>;
+
+/** The part of the Standard JSON Schema interface this module calls: zod 4.4 and later. */
+export interface StandardJsonSchema {
+  "~standard": {
+    vendor: string;
+    jsonSchema?: {
+      input(options: { target: "draft-2020-12"; libraryOptions?: JsonObject }): JsonObject;
+      output(options: { target: "draft-2020-12"; libraryOptions?: JsonObject }): JsonObject;
+    };
+  };
+}
+
+/** A schema: a Standard JSON Schema such as a zod object, or JSON Schema itself. */
+export type SchemaSource = StandardJsonSchema | JsonObject;
+
+/** The schema as JSON Schema, describing what a caller SENDS. */
+export function inputJsonSchema(source: SchemaSource): JsonObject {
+  if (!isStandard(source)) return source;
+  const standard = source["~standard"];
+  if (standard.jsonSchema === undefined) {
+    throw new Error(
+      `This ${standard.vendor} schema cannot describe itself as JSON Schema. zod does from 4.4.`,
+    );
+  }
+  return standard.jsonSchema.input({ target: "draft-2020-12" });
+}
+
+function isStandard(source: SchemaSource): source is StandardJsonSchema {
+  return "~standard" in source;
+}
+
+/** Keywords that describe a value without constraining it, so `{ description }` is still `{}`. */
+const ANNOTATIONS = new Set([
+  "$schema",
+  "$comment",
+  "title",
+  "description",
+  "default",
+  "examples",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+]);
+
+/** Names TypeScript itself provides, so a mention of one is not a declaration to find. */
+export const BUILTIN = new Set([
+  "Array",
+  "ArrayBuffer",
+  "Awaited",
+  "Blob",
+  "Capitalize",
+  "Date",
+  "Error",
+  "Exclude",
+  "Extract",
+  "Lowercase",
+  "Map",
+  "NonNullable",
+  "Omit",
+  "Parameters",
+  "Partial",
+  "Pick",
+  "Promise",
+  "Readonly",
+  "ReadonlyArray",
+  "ReadonlyMap",
+  "ReadonlySet",
+  "Record",
+  "RegExp",
+  "Required",
+  "ReturnType",
+  "Set",
+  "URL",
+  "Uint8Array",
+  "Uncapitalize",
+  "Uppercase",
+]);
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A schema that is `true`, `false` or an object; anything else is not a schema. */
+function asSchema(value: unknown): JsonObject | boolean {
+  if (typeof value === "boolean" || isObject(value)) return value;
+  throw new Error(`Not a JSON Schema: ${JSON.stringify(value)}`);
+}
+
+/**
+ * The TypeScript type for one schema. `indent` is where the enclosing line starts, so an inline
+ * object's fields land one level in.
+ */
+export function typeOf(schema: JsonObject | boolean, indent = ""): string {
+  if (typeof schema === "boolean") return schema ? "unknown" : "never";
+  const { enum: members, const: constant, type } = schema;
+  if (Array.isArray(members)) return members.map((v) => JSON.stringify(v)).join(" | ");
+  if (constant !== undefined) return JSON.stringify(constant);
+  const union = schema["anyOf"] ?? schema["oneOf"];
+  if (Array.isArray(union)) return union.map((s) => typeOf(asSchema(s), indent)).join(" | ");
+  // `type: ["number", "null"]`: each member carries the rest of the node, such as its items.
+  if (Array.isArray(type))
+    return type.map((t) => typeOf({ ...schema, type: t }, indent)).join(" | ");
+  // The EMPTY schema, `{}`, is "any value": what zod writes for `z.unknown()`. There is no
+  // narrower type to give it, so this is a shape understood, not a guess.
+  if (Object.keys(schema).every((key) => ANNOTATIONS.has(key))) return "unknown";
+
+  switch (type) {
+    case "string":
+      return "string";
+    case "number":
+    case "integer":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "null":
+      return "null";
+    case "array": {
+      const items = schema["items"];
+      // Fixed positions, each with its own type: `[number, number]`, never `number[]`, which
+      // would accept one.
+      const fixed = schema["prefixItems"] ?? (Array.isArray(items) ? items : undefined);
+      if (Array.isArray(fixed)) {
+        const rest =
+          Array.isArray(items) || items === undefined || items === false
+            ? ""
+            : `, ...${typeOf(asSchema(items), indent)}[]`;
+        return `[${fixed.map((m) => typeOf(asSchema(m), indent)).join(", ")}${rest}]`;
+      }
+      const item = items === undefined ? "unknown" : typeOf(asSchema(items), indent);
+      // `("a" | "b")[]`: without the parens the union swallows the array, and only the last
+      // member becomes one.
+      return item.includes(" | ") ? `(${item})[]` : `${item}[]`;
+    }
+    case "object": {
+      const fields = fieldsOf(schema, `${indent}    `);
+      if (fields) return `{\n${fields}${indent}}`;
+      const values = schema["additionalProperties"];
+      // A record, such as headers: no named fields, one type for every value.
+      return isObject(values)
+        ? `Record<string, ${typeOf(values, indent)}>`
+        : "Record<string, unknown>";
+    }
+    default:
+      throw new Error(`Cannot write this JSON Schema as a type: ${JSON.stringify(schema)}`);
+  }
+}
+
+/**
+ * An object schema's fields, one per line, each description kept as a doc comment. `skip` leaves
+ * fields out, such as the ones a route fills in itself.
+ */
+export function fieldsOf(
+  schema: JsonObject,
+  indent = "    ",
+  skip: readonly string[] = [],
+): string {
+  const properties = isObject(schema["properties"]) ? schema["properties"] : {};
+  const required = new Set(Array.isArray(schema["required"]) ? schema["required"] : []);
+  let out = "";
+  for (const [name, raw] of Object.entries(properties)) {
+    if (skip.includes(name)) continue;
+    const field = asSchema(raw);
+    const description = typeof field === "object" ? field["description"] : undefined;
+    if (typeof description === "string") out += docComment(description, indent);
+    // A name that is not an identifier, such as `content-type`, has to be quoted.
+    const key = /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+    out += `${indent}${key}${required.has(name) ? "" : "?"}: ${typeOf(field, indent)};\n`;
+  }
+  return out;
+}
+
+/**
+ * `export interface SendMessageParams { … }`, or `null` when the schema has no fields left. The
+ * interface is `optional` when no remaining field is required, so the method's argument can be.
+ */
+export function paramsInterface(
+  name: string,
+  schema: JsonObject,
+  skip: readonly string[] = [],
+): { source: string; optional: boolean } | null {
+  const fields = fieldsOf(schema, "    ", skip);
+  if (!fields) return null;
+  const required = Array.isArray(schema["required"]) ? schema["required"] : [];
+  return {
+    source: `export interface ${name} {\n${fields}}\n`,
+    optional: !required.some((field) => typeof field === "string" && !skip.includes(field)),
+  };
+}
+
+/**
+ * Prose broken into lines of at most `96 - indent.length` characters, to sit inside a comment at
+ * that indent. Every caller puts them in one, so a star-slash is broken up here: it would end the
+ * comment early and turn the rest of the sentence into code.
+ *
+ * ```ts
+ * wrapLines(op.description, "    ").join("\n     * ");
+ * ```
+ */
+export function wrapLines(text: string, indent = "    "): string[] {
+  const width = 96 - indent.length;
+  const lines: string[] = [];
+  let line = "";
+  for (const word of text.replace(/\*\//g, "*\\/").split(/\s+/).filter(Boolean)) {
+    if (line && line.length + word.length + 1 > width) {
+      lines.push(line);
+      line = word;
+    } else line = line ? `${line} ${word}` : word;
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
+/**
+ * `/** text *\/`, with continuation lines under the opener: the format all five generators wrote
+ * for a field, byte for byte.
+ */
+export function docComment(text: string, indent = "    "): string {
+  return `${indent}/** ${wrapLines(text, indent).join(`\n${indent} *  `)} */\n`;
+}
+
+/**
+ * The declared names a type expression mentions: `"V1ListPage<JobDto>[] | null"` needs
+ * `V1ListPage` and `JobDto`. Splitting on `|` alone, as one generator did, misses what sits
+ * inside the generic.
+ */
+export function typeNames(expression: string): string[] {
+  const names = expression.match(/\b[A-Z][A-Za-z0-9_]*\b/g) ?? [];
+  return [...new Set(names)].filter((name) => !BUILTIN.has(name));
+}
+
+/** `send_message` → `sendMessage`. */
+export const camelCase = (name: string): string =>
+  name.replace(/[_-](\w)/g, (_m, c: string) => c.toUpperCase());
+
+/** `send_message` → `SendMessage`. */
+export const pascalCase = (name: string): string => {
+  const camel = camelCase(name);
+  return camel.charAt(0).toUpperCase() + camel.slice(1);
+};