@tscomfy/codegen 0.0.0-stage → 0.1.0

package/src/export-name.ts

@@ -0,0 +1,51 @@
+// The one rule for the names generated modules export (docs/plan.md §9, §10): `generate`'s
+// schema constant and `transpile`'s workflow constant.
+
+const ASCII_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * Words an ES module can't declare as a constant (reserved words, `arguments` and `eval` in
+ * strict code) or must not shadow (`undefined`, `NaN`, `Infinity`).
+ */
+const RESERVED: ReadonlySet<string> = new Set(
+  "break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield await let static implements interface package private protected public arguments eval undefined NaN Infinity".split(
+    " ",
+  ),
+);
+
+/** What the schema module (`index.ts`) imports. */
+export const SCHEMA_MODULE_NAMES: readonly string[] = ["defineSchema", "TypedSchema", "Nodes"];
+
+/** What a transpiled module imports or binds itself. */
+export const TRANSPILED_MODULE_NAMES: readonly string[] = [
+  "workflow",
+  "Workflow",
+  "NodesOf",
+  "n",
+  "raw",
+];
+
+/**
+ * Why `name` can't be the exported constant of a generated module, or `undefined` when it can.
+ * One rule for both kinds: a schema module's export (`generate`) and a transpiled workflow's
+ * (`transpile`), which imports the schema's, so a schema named `raw` is refused when it is
+ * generated rather than when a workflow is first transpiled over it. The name must be an ASCII
+ * identifier, not a reserved word, and none of the names either module declares itself
+ * (`defineSchema`, `TypedSchema`, `Nodes`, `workflow`, `Workflow`, `NodesOf`, `n`, `raw`).
+ */
+export function exportNameProblem(name: string): string | undefined {
+  if (!ASCII_IDENTIFIER.test(name)) {
+    return "it isn't an identifier (ASCII letters, digits, _ and $, not starting with a digit)";
+  }
+  if (RESERVED.has(name)) return "JavaScript reserves it";
+  if (SCHEMA_MODULE_NAMES.includes(name) || TRANSPILED_MODULE_NAMES.includes(name)) {
+    const names = [...SCHEMA_MODULE_NAMES, ...TRANSPILED_MODULE_NAMES].join(", ");
+    return `the generated modules declare it themselves (${names})`;
+  }
+  return undefined;
+}
+
+/** Whether {@link exportNameProblem} finds nothing wrong with `name`. */
+export function isExportName(name: string): boolean {
+  return exportNameProblem(name) === undefined;
+}

package/src/expressions.ts

@@ -0,0 +1,201 @@
+// Expression layout, as oxfmt prints it (Prettier's rules for calls, objects and arrays), and
+// the layout of the transpiled module's declaration.
+
+import { type InputValue, isOutputRef, type JsonValue } from "@tscomfy/core";
+import {
+  type Doc,
+  fill,
+  group,
+  groupId,
+  hardline,
+  ifBreak,
+  indent,
+  indentIfBreak,
+  join,
+  line,
+  PRINT_WIDTH,
+  softline,
+  textWidth,
+} from "./doc.ts";
+import { propertyKey, quote } from "./names.ts";
+import { isList } from "./values.ts";
+
+/** The names a transpiled module's declaration is written with. */
+export interface DeclarationNames {
+  /** The exported constant. */
+  readonly name: string;
+  /** The schema module's export. */
+  readonly schemaName: string;
+}
+
+/**
+ * How `export const <name>: Workflow<…> = workflow(<schema>, <build> <block>);` is laid out, as
+ * Prettier lays out an assignment whose right side is a call with a function last: the function
+ * hugs the call while the line up to its `{` fits (with `});` for an empty block), else each
+ * argument takes a line of its own; the right side moves below `=` when that makes the call's
+ * first line fit.
+ */
+export type Layout = "hug" | "expand" | "belowHug" | "belowExpand";
+
+/** The column the build function's statements start at, per layout. */
+export const STATEMENT_INDENT: Record<Layout, number> = {
+  hug: 2,
+  expand: 4,
+  belowHug: 4,
+  belowExpand: 6,
+};
+
+export function declarationLayout(
+  options: DeclarationNames,
+  build: string,
+  empty: boolean,
+): Layout {
+  const left = declarationLeft(options);
+  const hug = `workflow(${options.schemaName}, ${build} ${empty ? "{});" : "{"}`;
+  if (textWidth(`${left} ${hug}`) <= PRINT_WIDTH) return "hug";
+  if (textWidth(`${left} workflow(`) <= PRINT_WIDTH) return "expand";
+  return textWidth(`  ${hug}`) <= PRINT_WIDTH ? "belowHug" : "belowExpand";
+}
+
+export function declarationLeft(options: DeclarationNames): string {
+  return `export const ${options.name}: Workflow<NodesOf<typeof ${options.schemaName}>> =`;
+}
+
+export function declarationDoc(
+  options: DeclarationNames,
+  build: string,
+  block: Doc,
+  layout: Layout,
+): Doc {
+  const { schemaName } = options;
+  const left = declarationLeft(options);
+  const hugged: Doc = [`workflow(${schemaName}, `, build, " ", block, ");"];
+  const expanded: Doc = [
+    "workflow(",
+    indent([hardline, schemaName, ",", hardline, build, " ", block, ","]),
+    hardline,
+    ");",
+  ];
+  switch (layout) {
+    case "hug":
+      return [left, " ", hugged];
+    case "expand":
+      return [left, " ", expanded];
+    case "belowHug":
+      return [left, indent([hardline, hugged])];
+    case "belowExpand":
+      return [left, indent([hardline, expanded])];
+  }
+}
+
+/** A call: arguments on one line, or one per line. */
+export function callDoc(callee: string, args: readonly Doc[]): Doc {
+  return group([
+    callee,
+    "(",
+    indent([softline, join([",", line], args)]),
+    ifBreak(","),
+    softline,
+    ")",
+  ]);
+}
+
+/** `const x = …;`, breaking inside the call rather than after `=`. */
+export function statementDoc(left: string, call: Doc): Doc {
+  const id = groupId("statement");
+  return group([left, " =", group(indent(line), id), indentIfBreak([call, ";"], id)]);
+}
+
+export function objectDoc(properties: readonly Doc[]): Doc {
+  if (properties.length === 0) return "{}";
+  return group(["{", indent([line, join([",", line], properties)]), ifBreak(","), line, "}"]);
+}
+
+/**
+ * An array. Prettier always breaks an array of two or more objects or arrays that each have
+ * more than one element.
+ */
+export function arrayDoc(items: readonly Doc[], breaks = false): Doc {
+  if (items.length === 0) return "[]";
+  if (breaks) return ["[", indent([hardline, join([",", hardline], items)]), ",", hardline, "]"];
+  return group(["[", indent([softline, join([",", line], items)]), ifBreak(","), softline, "]"]);
+}
+
+/** `key: value`; a scalar stays on the key's line, anything else may move below it. */
+export function propertyDoc(key: string, value: Doc): Doc {
+  // Prettier never breaks after a key narrower than five columns (tab width plus three).
+  const short = textWidth(key) < 5;
+  if (short || (typeof value === "string" && !value.startsWith('"') && !value.startsWith("'"))) {
+    return [key, ": ", value];
+  }
+  const id = groupId("property");
+  return group([key, ":", group(indent(line), id), indentIfBreak(value, id)]);
+}
+
+/** A number literal as Prettier writes it: exponents without `+` (`1e21`, not `1e+21`). */
+function numberText(value: number): string {
+  return Object.is(value, -0) ? "-0" : String(value).replace("e+", "e");
+}
+
+export function scalarDoc(value: string | number | bigint | boolean | null): Doc {
+  if (typeof value === "string") return quote(value);
+  if (typeof value === "bigint") return `${String(value)}n`;
+  if (typeof value === "number") return numberText(value);
+  return String(value);
+}
+
+/** "object" or "array" for an element with more than one entry. */
+function many(item: InputValue | JsonValue): "object" | "array" | undefined {
+  if (isList(item)) return item.length > 1 ? "array" : undefined;
+  if (typeof item === "object" && item !== null && !isOutputRef(item)) {
+    return Object.keys(item).length > 1 ? "object" : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Whether Prettier breaks an array whatever its width: two or more elements, all objects with
+ * more than one key or all arrays with more than one element.
+ */
+export function breaksArray(items: readonly (InputValue | JsonValue)[]): boolean {
+  const first = items[0] === undefined ? undefined : many(items[0]);
+  return items.length > 1 && first !== undefined && items.every((item) => many(item) === first);
+}
+
+/** A JSON value as an expression. */
+export function jsonDoc(value: JsonValue): Doc {
+  if (isList(value)) {
+    return isNumberList(value)
+      ? numbersDoc(value)
+      : arrayDoc(value.map(jsonDoc), breaksArray(value));
+  }
+  if (typeof value === "object" && value !== null) {
+    return objectDoc(
+      Object.entries(value).map(([key, item]) => propertyDoc(objectKey(key), jsonDoc(item))),
+    );
+  }
+  return scalarDoc(value);
+}
+
+/** A list of two or more numbers, which Prettier prints concisely, as many per line as fit. */
+export function isNumberList(
+  value: readonly (InputValue | JsonValue)[],
+): value is readonly number[] {
+  return value.length > 1 && value.every((item) => typeof item === "number");
+}
+
+export function numbersDoc(values: readonly number[]): Doc {
+  const items = values.map((value, index) =>
+    index < values.length - 1 ? `${numberText(value)},` : numberText(value),
+  );
+  // The trailing comma belongs to the last item, so the last line's fit counts it.
+  return group(["[", indent([softline, fill(items, ",")]), softline, "]"]);
+}
+
+/**
+ * A key for an object literal. `__proto__` is computed, since a plain `__proto__:` would set
+ * the prototype rather than make a property.
+ */
+export function objectKey(name: string): string {
+  return name === "__proto__" ? '["__proto__"]' : propertyKey(name);
+}

package/src/generate.ts

@@ -0,0 +1,59 @@
+import { type Diagnostic, hashSchema, type Schema } from "@tscomfy/core";
+import { emitSchemaModule } from "./emit-schema-module.ts";
+import { emitTypes } from "./emit-types.ts";
+
+/** The version written into generated headers. A test keeps it equal to package.json. */
+export const CODEGEN_VERSION = "0.1.0";
+
+/** A file to write, as data: codegen never touches the filesystem. */
+export interface GeneratedFile {
+  /** Relative to the output directory. */
+  readonly path: string;
+  readonly contents: string;
+}
+
+/** Options for {@link generate}. */
+export interface GenerateOptions {
+  /** The exported schema constant, e.g. `local`: one `exportNameProblem` finds nothing wrong with. */
+  readonly exportName: string;
+  /**
+   * The extension `index.ts` uses to import `nodes.ts`: `.js` (the default) works under
+   * `nodenext` and `bundler` resolution; `.ts` needs `allowImportingTsExtensions` or
+   * `rewriteRelativeImportExtensions`.
+   */
+  readonly importExtension?: ".js" | ".ts";
+  /** The command that regenerates the files, recorded in their headers. */
+  readonly command?: string;
+}
+
+/** The result of {@link generate}. */
+export interface GenerateResult {
+  /** `nodes.ts` and `index.ts`. */
+  readonly files: readonly GeneratedFile[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+/**
+ * Generates the files for one schema: `nodes.ts` (types only) and
+ * `index.ts` (the typed runtime schema). Pure and deterministic. Throws a `TypeError` for an
+ * export name `exportNameProblem` refuses.
+ */
+export function generate(schema: Schema, options: GenerateOptions): GenerateResult {
+  const header = [
+    `Generated by @tscomfy/codegen ${CODEGEN_VERSION}. Do not edit: regenerate instead.`,
+    `Schema ${hashSchema(schema)}${schema.comfyVersion === undefined ? "" : `, ComfyUI ${schema.comfyVersion}`}.`,
+    ...(options.command === undefined ? [] : [`Regenerate with: ${options.command}`]),
+  ];
+  const types = emitTypes(schema, header);
+  const nodesModule = `./nodes${options.importExtension ?? ".js"}`;
+  return {
+    files: [
+      { path: "nodes.ts", contents: types.contents },
+      {
+        path: "index.ts",
+        contents: emitSchemaModule(schema, options.exportName, nodesModule, header),
+      },
+    ],
+    diagnostics: types.diagnostics,
+  };
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @module @tscomfy/codegen
+ *
+ * Turns a normalized tscomfy schema into generated TypeScript (node types and
+ * the runtime schema module) and transpiles workflows to code. Pure: returns
+ * files as data and never touches the filesystem.
+ */
+
+export {
+  CODEGEN_VERSION,
+  generate,
+  type GeneratedFile,
+  type GenerateOptions,
+  type GenerateResult,
+} from "./generate.ts";
+export { exportNameProblem } from "./export-name.ts";
+export {
+  transpile,
+  transpileNameProblem,
+  type TranspileOptions,
+  type TranspileResult,
+} from "./transpile.ts";

package/src/names.ts

@@ -0,0 +1,89 @@
+// Identifiers and literal text for generated code. ComfyUI names (class types, input names,
+// option keys) are arbitrary strings: 328 class names in a real dump are not identifiers. They
+// stay exact as property keys and are sanitized only where TypeScript needs an identifier.
+
+// ECMAScript IdentifierName, which oxfmt leaves unquoted as a key (`café`, `日本`).
+const IDENTIFIER = /^[\p{ID_Start}$_][\p{ID_Continue}$\u200c\u200d]*$/u;
+
+/** A property key: the name itself when it is an identifier, else a string literal. */
+export function propertyKey(name: string): string {
+  return IDENTIFIER.test(name) ? name : quote(name);
+}
+
+/**
+ * A string literal as oxfmt writes it: double quotes, unless the text holds more double quotes
+ * than single ones, then single quotes. Other escapes are `JSON.stringify`'s.
+ */
+export function quote(text: string): string {
+  const doubled = JSON.stringify(text);
+  const doubles = text.split('"').length - 1;
+  const singles = text.split("'").length - 1;
+  if (doubles <= singles) return doubled;
+  const inner = doubled.slice(1, -1).replaceAll('\\"', '"').replaceAll("'", "\\'");
+  return `'${inner}'`;
+}
+
+const LINE_TERMINATOR = /\r\n|[\r\n\u2028\u2029]/;
+
+/**
+ * Lines of server text for a comment: split at every line terminator (which a comment can't
+ * hold raw without oxfmt rewriting it) and with `*\/` escaped, so no name or tooltip can close
+ * the comment and inject code.
+ */
+export function commentLines(text: string): string[] {
+  return text.split(LINE_TERMINATOR).map((each) => each.replaceAll("*/", "*\\/").trimEnd());
+}
+
+/** Server text for a one-line comment. */
+export function commentText(text: string): string {
+  return commentLines(text).join(" ");
+}
+
+/** `//` comment lines; line terminators in the text can't end the comment early. */
+export function headerLines(header: readonly string[]): string[] {
+  return header.map((text) => `// ${commentText(text)}`);
+}
+
+/**
+ * A PascalCase identifier part from an arbitrary name: the runs of letters and digits, each
+ * capitalized (`sampler_name` → `SamplerName`, `easy kSampler` → `EasyKSampler`). Never empty
+ * and never starts with a digit.
+ */
+export function pascal(name: string, fallback: string): string {
+  const words = name.match(/[A-Za-z0-9]+/g) ?? [];
+  const joined = words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+  if (joined === "") return fallback;
+  return /^[0-9]/.test(joined) ? `${fallback}${joined}` : joined;
+}
+
+/**
+ * Hands out unique names in one namespace, in call order. A taken base gets the first free
+ * numeric suffix (`Mode`, `Mode2`, …), so names are stable for a given schema.
+ */
+export class NameRegistry {
+  readonly #taken = new Set<string>();
+  /** Per base, the first suffix not yet tried: names are never given back, so none below is free. */
+  readonly #next = new Map<string, number>();
+
+  constructor(reserved: readonly string[] = []) {
+    for (const name of reserved) this.#taken.add(name);
+  }
+
+  /** A fresh name based on `base`, now taken. */
+  claim(base: string): string {
+    let suffix = this.#next.get(base) ?? 1;
+    let name = suffix === 1 ? base : `${base}${String(suffix)}`;
+    while (this.#taken.has(name)) {
+      suffix++;
+      name = `${base}${String(suffix)}`;
+    }
+    this.#next.set(base, suffix + 1);
+    this.#taken.add(name);
+    return name;
+  }
+
+  /** Whether `name` is taken. */
+  has(name: string): boolean {
+    return this.#taken.has(name);
+  }
+}

package/src/rules.ts

@@ -0,0 +1,86 @@
+// Input rules the generated types are written with (docs/plan.md §6.2, §7.2), shared by the type
+// emitter, which writes them, and the transpiler, which must decide by the same rules whether
+// the types can express a node.
+
+import { type InputDef, sendsInputValue } from "@tscomfy/core";
+
+/**
+ * Whether a property named `name` must be required: TypeScript checks an optional property
+ * against the `Object` member of that name, which every object literal has.
+ */
+export function isObjectMember(name: string): boolean {
+  return OBJECT_MEMBERS.has(name);
+}
+
+/** Members of TypeScript's `Object` interface, which every object type has. */
+const OBJECT_MEMBERS: ReadonlySet<string> = new Set([
+  "constructor",
+  "toString",
+  "toLocaleString",
+  "valueOf",
+  "hasOwnProperty",
+  "isPrototypeOf",
+  "propertyIsEnumerable",
+]);
+
+/**
+ * The field a DynamicGroup row's type requires beyond the required ones (§7.2): a row is counted
+ * only when one of its keys is sent, so when no field is required or has a default, the first
+ * one must be given, or `{}` would send no row at all.
+ */
+export function forcedRowField(fields: readonly InputDef[]): InputDef | undefined {
+  const sendable = fields.filter(sendsInputValue);
+  return sendable.some((field) => isRequired(field) || hasDefault(field)) ? undefined : sendable[0];
+}
+
+/**
+ * Whether an input must be given: the backend requires it and no default fills it in.
+ * Autogrow and DynamicGroup are required by their minimum alone: the backend enforces it even
+ * when the input itself is optional. An input named after a member of `Object` is always
+ * required: TypeScript checks an optional property against the member every object literal
+ * has (`constructor: Function`), so leaving it out would fail to compile.
+ */
+export function isRequired(input: InputDef): boolean {
+  if (isObjectMember(input.name)) return true;
+  switch (input.kind) {
+    case "autogrow":
+      return input.template.required && input.min > 0 && input.slots.length > 0;
+    case "dynamicGroup":
+      return input.min > 0;
+    case "combo":
+      // A forceInput combo has no widget, so nothing fills its default in.
+      return input.required && (input.default === undefined || input.forceInput === true);
+    case "int":
+    case "float":
+    case "string":
+    case "boolean":
+    case "value":
+      return input.required && input.default === undefined;
+    case "socket":
+    case "dynamicCombo":
+    case "matchType":
+    case "unknown":
+      return input.required;
+  }
+}
+
+/** Whether the exporter sends a value for the input when none is given. */
+export function hasDefault(input: InputDef): boolean {
+  switch (input.kind) {
+    case "combo":
+      return input.default !== undefined && input.forceInput !== true;
+    case "int":
+    case "float":
+    case "string":
+    case "boolean":
+    case "value":
+      return input.default !== undefined;
+    case "socket":
+    case "autogrow":
+    case "dynamicCombo":
+    case "dynamicGroup":
+    case "matchType":
+    case "unknown":
+      return false;
+  }
+}