exp: using ustable tsgo generator for Integration.

Author: RobinTail

PLAN-jsdoc-text-generation.md

@@ -0,0 +1,286 @@
+# Plan: Text-Based JSDoc for `onObject` in zts.ts
+
+## Goal
+
+Make JSDoc comments (`@deprecated`, `@desc`, `@default`, `@example`) appear in the
+TypeScript types generated by `onObject` in `zts.ts`.
+
+## Problem
+
+`makeInterfaceProp` attaches JSDoc via `addJsDoc`, which is a noop in tsgo:
+
+```typescript
+/** @todo this one is effectively noop, doesn't work and no alternative yet */
+const addJsDoc = <T extends Node>(node: T, text: string) => {
+  const jsdoc = f.createJSDoc([f.createJSDocText(text)]);
+  return Object.assign(node, { jsDoc: [jsdoc] });
+};
+```
+
+The JSDoc IS attached to the AST (`node.jsDoc` exists and has content), but tsgo's
+emitter strips it from ALL nodes — both individual nodes AND full interfaces parsed
+via virtual FS. This was confirmed by testing:
+
+```
+# Parsed from virtual FS, printed via emitter:
+interface Foo {
+    one: string;    // JSDoc stripped
+    two?: number;   // JSDoc stripped
+}
+```
+
+The `parseTypeLiteral` approach (parse text → get AST → printNode) **does not work**
+because `printNode` ignores JSDoc regardless of how the node was created.
+
+## Constraint
+
+`zodToTs()` returns `TypeNode`. The `Producer` type and `ZTSContext.makeAlias`
+interface cannot change. The `brandHandling` public API accepts callbacks returning
+`TypeNode`.
+
+## Solution: Store Text Alongside AST
+
+Build type literal text (with JSDoc) during `onObject` processing, store it in a
+WeakMap, and use it instead of `printNode` when outputting the type.
+
+Key insight: `next()` is called depth-first. By the time we build the outer type
+literal's text, inner type literals' texts are already stored.
+
+---
+
+## Phase 1: Add `typeTextRegistry` to `zts.ts`
+
+### 1.1 New export
+
+Add a WeakMap that maps `TypeNode` to its pre-built text (with JSDoc):
+
+```typescript
+/** @internal stores pre-built text for TypeNodes that need JSDoc in output */
+export const typeTextRegistry = new WeakMap<TypeNode, string>();
+```
+
+### 1.2 Add helper to build property text
+
+```typescript
+const safePropRegex = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+const buildPropText = (
+  key: string | number,
+  typeNode: TypeNode,
+  {
+    isOptional,
+    hasUndefined,
+    isDeprecated,
+    comment,
+  }: {
+    isOptional?: boolean;
+    hasUndefined?: boolean;
+    isDeprecated?: boolean;
+    comment?: string;
+  },
+): string => {
+  const keyText = safePropRegex.test(String(key)) ? String(key) : `"${key}"`;
+  const opt = isOptional ? "?" : "";
+  const typeText = typeTextRegistry.get(typeNode) ?? printNode(typeNode);
+  const undef = hasUndefined ? " | undefined" : "";
+  const lines: string[] = [];
+  if (isDeprecated) lines.push("/** @deprecated */");
+  if (comment) lines.push(`/** @desc ${comment} */`);
+  lines.push(`  ${keyText}${opt}: ${typeText}${undef};`);
+  return lines.join("\n");
+};
+```
+
+This naturally handles nesting: inner objects' texts are already in
+`typeTextRegistry` (processed depth-first via `next()`), so they appear with
+JSDoc. Non-object types fall back to `printNode`.
+
+---
+
+## Phase 2: Convert `onObject` to dual output
+
+### 2.1 Modified `onObject`
+
+```typescript
+const onObject: Producer = (
+  obj: z.core.$ZodObject,
+  { isResponse, next, makeAlias },
+) => {
+  const produce = () => {
+    const entries = Object.entries(obj._zod.def.shape);
+    const propTexts: string[] = [];
+    const members = entries.map<TypeElement>(([key, value]) => {
+      const { description: comment, deprecated: isDeprecated } =
+        globalRegistry.get(value) || {};
+      const isOptional =
+        (isResponse ? value._zod.optout : value._zod.optin) === "optional";
+      const hasUndefined =
+        isOptional && !(value instanceof z.core.$ZodExactOptional);
+      const typeNode = next(value);
+      propTexts.push(
+        buildPropText(key, typeNode, {
+          isOptional,
+          hasUndefined,
+          isDeprecated,
+          comment,
+        }),
+      );
+      return makeInterfaceProp(key, typeNode, { isOptional, hasUndefined });
+    });
+    const typeNode = f.createTypeLiteralNode(members);
+    const text = `{\n${propTexts.join("\n")}\n}`;
+    typeTextRegistry.set(typeNode, text);
+    return typeNode;
+  };
+  return hasCycle(obj, { io: isResponse ? "output" : "input" })
+    ? makeAlias(obj, produce)
+    : produce();
+};
+```
+
+### 2.2 How it works
+
+1. For each property, `next(value)` processes the type recursively (depth-first)
+2. If the property type is also an object, `onObject` runs recursively, stores
+   text in `typeTextRegistry`, and returns a `TypeLiteralNode`
+3. `buildPropText` checks `typeTextRegistry` for the type text, falls back to
+   `printNode` for non-object types
+4. All property texts are joined into a type literal body with JSDoc
+5. The text is stored in `typeTextRegistry` keyed by the `TypeLiteralNode`
+
+---
+
+## Phase 3: Use stored text in `integration.ts`
+
+### 3.1 Modify `#makeAlias`
+
+```typescript
+#makeAlias(key: object, produce: () => TypeNode): TypeNode {
+  let name = this.#aliases.get(key);
+  if (!name) {
+    name = `Type${this.#aliases.size + 1}`;
+    this.#aliases.set(key, name);
+    const node = produce();
+    const stored = typeTextRegistry.get(node);
+    this.#program.push(
+      stored
+        ? `type ${name} = ${stored};`
+        : (opts) => `type ${name} = ${printNode(node, opts)};`,
+    );
+  }
+  return ensureTypeNode(name);
+}
+```
+
+### 3.2 Modify `onEndpoint` type alias generation
+
+```typescript
+const inputTypeNode = zodToTs(inputSchema, ctxIn);
+const inputText = typeTextRegistry.get(inputTypeNode);
+this.#program.push(
+  inputText
+    ? `/** ${request} */\ntype ${inputTypeName} = ${inputText};`
+    : (opts) =>
+        `/** ${request} */\ntype ${inputTypeName} = ${printNode(inputTypeNode, opts)};`,
+);
+```
+
+Same pattern for variant type nodes.
+
+### 3.3 Import `typeTextRegistry`
+
+```typescript
+import { typeTextRegistry } from "./zts";
+```
+
+---
+
+## Phase 4: Simplify `makeInterfaceProp`
+
+### 4.1 Remove JSDoc handling
+
+`makeInterfaceProp` no longer needs `comment` or `isDeprecated` options since
+`onObject` handles JSDoc via text. The `addJsDoc` function can be removed.
+
+### 4.2 Remove unused imports
+
+After removing `addJsDoc`'s `R.reject(R.isNil, ...)` call, check if `ramda` is
+still used in `typescript-api.ts`. Remove if not.
+
+### 4.3 Keep `makeInterfaceProp` signature compatible
+
+Since `makeInterfaceProp` is only used by `onObject`, the extra options can be
+removed without breaking the public API.
+
+---
+
+## Phase 5: Update tests
+
+### 5.1 Snapshot updates
+
+Run `pnpm -F express-zod-api test -- --run zts` and update snapshots. The output
+now includes JSDoc comments that were previously lost.
+
+### 5.2 Key test cases
+
+- **`z.object()` tests** (zts.spec.ts ~line 233-293): Properties with descriptions
+  and deprecated metadata should now show JSDoc in output
+- **`z.optional()` tests**: isOptional/hasUndefined behavior unchanged
+- **`Issue #2352` tests**: Intersection dedup still works (members are still AST
+  nodes; only the text representation is new)
+- **Integration snapshot**: Type aliases now contain JSDoc for object properties
+
+### 5.3 Verify no regression
+
+All 1062 tests must pass. Snapshots that change should only gain JSDoc comments,
+not lose any existing output.
+
+---
+
+## Edge Cases
+
+### `intersect` helper
+
+The `intersect` helper in `zts.ts` merges `TypeLiteralNode` members. After
+merging, a new `TypeLiteralNode` is created. This node won't have stored text
+in `typeTextRegistry`. Two options:
+
+1. **Accept the limitation**: JSDoc on intersected object types is lost. This is
+   rare (`z.intersection()` of two objects) and matches current behavior.
+2. **Build merged text**: Extract JSDoc from source texts and merge them. Complex
+   and fragile — defer to a future phase if needed.
+
+### Cyclic types
+
+When `makeAlias` is used (cyclic schemas), the text is stored in `typeTextRegistry`
+and used directly in `#makeAlias`'s push. JSDoc is preserved.
+
+### Nested objects
+
+Handled naturally by depth-first processing. When building the outer object's text,
+inner objects' texts are already in `typeTextRegistry`.
+
+---
+
+## Risks
+
+- **Formatting difference**: Text built manually may differ from `printNode` output.
+  `printNode` uses tsgo's formatter. Manual text uses our formatting. Snapshots
+  will capture any differences.
+
+- **`intersect` text loss**: JSDoc on intersected object types is lost. Matches
+  current behavior — not a regression.
+
+- **Future tsgo fix**: If tsgo fixes the emitter to include JSDoc, we could
+  revert to AST-only approach. The `typeTextRegistry` is additive and can be
+  removed.
+
+---
+
+## Execution Order
+
+1. Phase 1: Add `typeTextRegistry` and `buildPropText` to `zts.ts`
+2. Phase 2: Convert `onObject` to dual output (text + AST)
+3. Phase 3: Use stored text in `integration.ts`
+4. Phase 4: Simplify `makeInterfaceProp` (remove JSDoc handling)
+5. Phase 5: Update tests and snapshots

express-zod-api/src/integration.ts

@@ -9,7 +9,13 @@ import { IntegrationBase, interfaces } from "./integration-base";
 import { shouldHaveContent, makeCleanId } from "./common-helpers";
 import { loadPeer } from "./peer-helpers";
 import type { Routing } from "./routing";
-import { ensureTypeNode, printNode, ts } from "./typescript-api";
+import {
+  ensureTypeNode,
+  printNode,
+  type TypeNode,
+  type PrintNodeOptions,
+  type DeferredCode,
+} from "./typescript-api";
 import { walkRouting, withHead, type OnEndpoint } from "./routing-walker";
 import type { HandlingRules } from "./schema-walker";
 import { zodToTs } from "./zts";
@@ -55,7 +61,7 @@ interface IntegrationParams {
    * @example { MyBrand: (schema: typeof myBrandSchema, { next }) => createKeywordTypeNode(SyntaxKind.AnyKeyword)
    * @link https://www.npmjs.com/package/@express-zod-api/zod-plugin
    */
-  brandHandling?: HandlingRules<ts.TypeNode, ZTSContext>;
+  brandHandling?: HandlingRules<TypeNode, ZTSContext>;
   /**
    * @desc Whether the server supports credentials in cross-origin requests.
    * @desc It sets `credentials: "include"` in Client default Implementation and `withCredentials` in Subscription.
@@ -68,7 +74,7 @@ interface IntegrationParams {
 
 interface FormattedPrintingOptions {
   /** @desc Typescript printer options */
-  printerOptions?: ts.PrinterOptions;
+  printerOptions?: PrintNodeOptions;
   /**
    * @desc Typescript code formatter
    * @default prettier.format | oxfmt.format
@@ -77,12 +83,11 @@ interface FormattedPrintingOptions {
 }
 
 export class Integration extends IntegrationBase {
-  readonly #program: Array<string | ((opts?: ts.PrinterOptions) => string)> =
-    [];
+  readonly #program: Array<string | DeferredCode> = [];
   readonly #aliases = new Map<object, string>();
   #usage?: string;
 
-  #makeAlias(key: object, produce: () => ts.TypeNode): ts.TypeNode {
+  #makeAlias(key: object, produce: () => TypeNode): TypeNode {
     let name = this.#aliases.get(key);
     if (!name) {
       name = `Type${this.#aliases.size + 1}`;
@@ -205,7 +210,7 @@ export class Integration extends IntegrationBase {
     );
   }
 
-  public print(printerOptions?: ts.PrinterOptions) {
+  public print(printerOptions?: PrintNodeOptions) {
     const parts = this.#program.map((entry) =>
       typeof entry === "function" ? entry(printerOptions) : entry,
     );