Fix/schema add jsdoc descriptions (#1762)

* schema-generator: propagate JSDoc descriptions to JSON Schema

- Port behavior from old js-runtime transformer (branch fix/ast-add-descriptions-to-schema):
  - Attach property descriptions from JSDoc (merging/conflict note for intersections)
  - Attach index signature descriptions to additionalProperties
  - Attach root-level descriptions when present on the type symbol
- Add doc-utils with robust extraction from declarations and symbols
- Add fixture: descriptions-basic to verify behavior

No changes to existing fixtures; behavior is additive only when JSDoc exists.

* schema-generator: remove stray _doc file from commit

* schema-generator: add full JSDoc description parity and fixtures

- Property docs across all types (primitives, arrays, unions, wrappers)
- Root-level descriptions from interface/type alias docs
- Intersection conflicts: keep first, add , warn
- Inheritance (extends) preserves property and root docs
- Index signatures: string/number → additionalProperties.description; conflict comment
- Preserve multiline/markdown text
- Improve array detection to avoid misclassifying map-like types
- Add comprehensive fixtures (no auto-gen):
  descriptions-basic, -index, -index-ambiguous, -intersection-same,
  -intersection-conflict, -extends, -union-literals, -array-doc,
  -wrappers, -recursive

* schema-generator: add parity fixtures and alias-root doc handling

- Add fixtures: descriptions-root-alias, -record-alias, -optional-union,
  -root-with-tags, -nested (Doc/ChildNode)
- Improve root description extraction to also consider underlying symbol when
  the root is a type alias (use target doc if alias has none)

* schema-generator: switch conflict logging to getLogger and add multiline property doc fixture; remove try/catch swallowing; fix logger optional-level assignment for exactOptionalPropertyTypes

* add back warning for intersection property merge

* fix issue with not recognizing typescript's NonPrimitive generic object type in objectformatter; return basic permissive schema in that case

* use isRecord to improve code and reduce 'as any' casts

* address code review simplification suggestions

Author: mathpirate

packages/schema-generator/src/doc-utils.ts

@@ -0,0 +1,82 @@
+import ts from "typescript";
+
+/**
+ * Extract plain-text JSDoc from a symbol. Filters out tag lines starting with
+ * '@'. Returns undefined when no useful text is present.
+ */
+export function getSymbolDoc(
+  symbol: ts.Symbol | undefined,
+  checker: ts.TypeChecker,
+): string | undefined {
+  if (!symbol) return undefined;
+  const parts = symbol.getDocumentationComment(checker);
+  // @ts-ignore - displayPartsToString exists on the TS namespace
+  const text = ts.displayPartsToString(parts) || "";
+  if (!text) return undefined;
+  const lines = text.split(/\r?\n/).filter((l) => !l.trim().startsWith("@"));
+  const cleaned = lines.join("\n").trim();
+  return cleaned || undefined;
+}
+
+/**
+ * Extract JSDoc comments from a declaration node (if available), filtering out
+ * lines starting with '@'. Returns all distinct comment texts.
+ */
+export function getDeclDocs(decl: ts.Declaration): string[] {
+  const docs: string[] = [];
+  const jsDocs = (decl as any).jsDoc as Array<ts.JSDoc> | undefined;
+  if (jsDocs && jsDocs.length > 0) {
+    for (const d of jsDocs) {
+      const comment = (d as any).comment as unknown;
+      let text = "";
+      if (typeof comment === "string") {
+        text = comment;
+      } else if (Array.isArray(comment)) {
+        text = comment
+          .map((c) => (typeof c === "string" ? c : (c as any).text ?? ""))
+          .join("");
+      }
+      if (!text) continue;
+      const lines = String(text).split(/\r?\n/).filter((l) =>
+        !l.trim().startsWith("@")
+      );
+      const cleaned = lines.join("\n").trim();
+      if (cleaned && !docs.includes(cleaned)) docs.push(cleaned);
+    }
+  }
+  return docs;
+}
+
+/**
+ * Extract merged doc from symbol declarations and the symbol itself, preferring
+ * declaration-attached comments from non-declaration files. Returns the first
+ * doc text (if any) and the set of all distinct docs discovered.
+ */
+export function extractDocFromSymbolAndDecls(
+  symbol: ts.Symbol | undefined,
+  checker: ts.TypeChecker,
+): { text?: string; all: string[] } {
+  const all: string[] = [];
+  if (symbol) {
+    const decls = symbol.declarations ?? [];
+    for (const decl of decls) {
+      const sf = decl.getSourceFile();
+      if (!sf.isDeclarationFile) {
+        for (const s of getDeclDocs(decl)) if (!all.includes(s)) all.push(s);
+      }
+    }
+  }
+
+  // Only include symbol-level docs if there is a non-declaration-file declaration
+  const hasUserDecl = (symbol?.declarations ?? []).some((d) =>
+    !d.getSourceFile().isDeclarationFile
+  );
+  if (hasUserDecl) {
+    const symText = getSymbolDoc(symbol, checker);
+    if (symText && !all.includes(symText)) all.push(symText);
+  }
+
+  const result: { text?: string; all: string[] } = { all };
+  if (all[0]) result.text = all[0];
+  return result;
+}

packages/schema-generator/src/formatters/intersection-formatter.ts

@@ -5,6 +5,10 @@ import type {
   TypeFormatter,
 } from "../interface.ts";
 import type { SchemaGenerator } from "../schema-generator.ts";
+import { getLogger } from "@commontools/utils/logger";
+import { isRecord } from "@commontools/utils/types";
+
+const logger = getLogger("schema-generator.intersection");
 
 export class IntersectionFormatter implements TypeFormatter {
   constructor(private schemaGenerator: SchemaGenerator) {}
@@ -88,14 +92,36 @@ export class IntersectionFormatter implements TypeFormatter {
         // Merge properties from this part
         if (schema.properties) {
           for (const [key, value] of Object.entries(schema.properties)) {
-            if (mergedProps[key] && mergedProps[key] !== value) {
-              // Property conflict - could improve this with more sophisticated merging
-              console.warn(
-                `Intersection property conflict for key '${key}' - using first definition`,
+            const existing = mergedProps[key];
+            if (existing) {
+              // If both are object schemas, check description conflicts
+              if (isRecord(existing) && isRecord(value)) {
+                const aDesc = typeof existing.description === "string"
+                  ? (existing.description as string)
+                  : undefined;
+                const bDesc = typeof value.description === "string"
+                  ? (value.description as string)
+                  : undefined;
+                if (aDesc && bDesc && aDesc !== bDesc) {
+                  const priorComment = typeof existing.$comment === "string"
+                    ? (existing.$comment as string)
+                    : undefined;
+                  (existing as Record<string, unknown>).$comment =
+                    priorComment ??
+                      "Conflicting docs across intersection constituents; using first";
+                  logger.warn(() =>
+                    `Intersection doc conflict for '${key}'; using first`
+                  );
+                }
+              }
+              // Prefer the first definition by default; emit debug for visibility
+              logger.debug(() =>
+                `Intersection kept first definition for '${key}'`
               );
-            } else {
-              mergedProps[key] = value;
+              // Keep existing
+              continue;
             }
+            mergedProps[key] = value as SchemaDefinition;
           }
         }
 

packages/schema-generator/src/formatters/object-formatter.ts

@@ -6,6 +6,14 @@ import type {
 } from "../interface.ts";
 import { safeGetPropertyType } from "../type-utils.ts";
 import type { SchemaGenerator } from "../schema-generator.ts";
+import { extractDocFromSymbolAndDecls, getDeclDocs } from "../doc-utils.ts";
+import { getLogger } from "@commontools/utils/logger";
+import { isRecord } from "@commontools/utils/types";
+
+const logger = getLogger("schema-generator.object", {
+  enabled: true,
+  level: "warn",
+});
 
 /**
  * Formatter for object types (interfaces, type literals, etc.)
@@ -15,12 +23,23 @@ export class ObjectFormatter implements TypeFormatter {
 
   supportsType(type: ts.Type, context: GenerationContext): boolean {
     // Handle object types (interfaces, type literals, classes)
-    return (type.flags & ts.TypeFlags.Object) !== 0;
+    const flags = type.flags;
+    if ((flags & ts.TypeFlags.Object) !== 0) return true;
+    // Also claim the exact TypeScript `object` type via string check.
+    return context.typeChecker.typeToString(type) === "object";
   }
 
   formatType(type: ts.Type, context: GenerationContext): SchemaDefinition {
     const checker = context.typeChecker;
 
+    // If this is the TS `object` type (unknown object shape), emit a permissive
+    // object schema instead of attempting to enumerate properties.
+    // This avoids false "no formatter" errors for unions containing `object`.
+    const typeName = checker.typeToString(type);
+    if (typeName === "object") {
+      return { type: "object", additionalProperties: true };
+    }
+
     // Special-case Date to a string with date-time format (match old behavior)
     if (type.symbol?.name === "Date" && type.symbol?.valueDeclaration) {
       // Check if this is the built-in Date type (not a user-defined type named "Date")
@@ -75,10 +94,73 @@ export class ObjectFormatter implements TypeFormatter {
         context,
         propTypeNode,
       );
+      // Attach property description from JSDoc (if any)
+      const { text, all } = extractDocFromSymbolAndDecls(prop, checker);
+      if (text && isRecord(generated)) {
+        const conflicts = all.filter((s) => s && s !== text);
+        (generated as Record<string, unknown>).description = text;
+        if (conflicts.length > 0) {
+          const comment = typeof generated.$comment === "string"
+            ? (generated.$comment as string)
+            : undefined;
+          (generated as Record<string, unknown>).$comment = comment
+            ? comment
+            : "Conflicting docs across declarations; using first";
+          // Warning only
+          logger.warn(() =>
+            `JSDoc conflict for property '${propName}'; using first doc`
+          );
+        }
+      }
       properties[propName] = generated;
     }
 
     const schema: SchemaDefinition = { type: "object", properties };
+
+    // Handle string/number index signatures → additionalProperties with description
+    const stringIndex = checker.getIndexTypeOfType(type, ts.IndexKind.String);
+    const numberIndex = checker.getIndexTypeOfType(type, ts.IndexKind.Number);
+    const chosenIndex = stringIndex ?? numberIndex;
+    if (chosenIndex) {
+      const apSchema = this.schemaGenerator.formatChildType(
+        chosenIndex,
+        context,
+        undefined,
+      );
+      // Attempt to read JSDoc from index signature declarations
+      const sym = type.getSymbol?.();
+      const foundDocs: string[] = [];
+      if (sym) {
+        for (const decl of sym.declarations ?? []) {
+          if (ts.isInterfaceDeclaration(decl) || ts.isTypeLiteralNode(decl)) {
+            for (const member of decl.members) {
+              if (ts.isIndexSignatureDeclaration(member)) {
+                const docs = getDeclDocs(member);
+                for (const d of docs) {
+                  if (!foundDocs.includes(d)) foundDocs.push(d);
+                }
+              }
+            }
+          }
+        }
+      }
+      if (foundDocs.length > 0 && isRecord(apSchema)) {
+        (apSchema as Record<string, unknown>).description = foundDocs[0]!;
+        if (foundDocs.length > 1) {
+          const comment = typeof apSchema.$comment === "string"
+            ? (apSchema.$comment as string)
+            : undefined;
+          (apSchema as Record<string, unknown>).$comment = comment
+            ? comment
+            : "Conflicting docs for index signatures; using first";
+          logger.warn(() =>
+            "JSDoc conflict for index signatures; using first doc"
+          );
+        }
+      }
+      (schema as Record<string, unknown>).additionalProperties =
+        apSchema as SchemaDefinition;
+    }
     if (required.length > 0) schema.required = required;
 
     return schema;

packages/schema-generator/src/schema-generator.ts

@@ -17,6 +17,8 @@ import {
   safeGetIndexTypeOfType,
   safeGetTypeOfSymbolAtLocation,
 } from "./type-utils.ts";
+import { extractDocFromSymbolAndDecls } from "./doc-utils.ts";
+import { isRecord } from "@commontools/utils/types";
 
 /**
  * Main schema generator that uses a chain of formatters
@@ -61,7 +63,10 @@ export class SchemaGenerator implements ISchemaGenerator {
     };
 
     // Generate the root schema
-    const rootSchema = this.formatType(type, context, true);
+    let rootSchema = this.formatType(type, context, true);
+
+    // Attach root-level description from JSDoc if available
+    rootSchema = this.attachRootDescription(rootSchema, type, context);
 
     // Build final schema with definitions if needed
     return this.buildFinalSchema(rootSchema, type, context, typeNode);
@@ -342,4 +347,45 @@ export class SchemaGenerator implements ISchemaGenerator {
     if (checker) visit(type);
     return { types: cycles, names: cycleNames };
   }
+
+  /**
+   * Attach a root-level description from JSDoc on the type symbol when
+   * available and when the root schema is an object that does not already have
+   * a description.
+   */
+  private attachRootDescription(
+    schema: SchemaDefinition,
+    type: ts.Type,
+    context: GenerationContext,
+  ): SchemaDefinition {
+    if (typeof schema !== "object") return schema;
+
+    // Consider both alias symbol (for type aliases) and the underlying
+    // symbol (for interfaces/classes). Prefer alias doc when present; fall
+    // back to underlying.
+    const aliasSym = type.aliasSymbol;
+    const directSym = type.getSymbol?.() || (type as any).symbol;
+
+    const pickDoc = (sym?: ts.Symbol): string | undefined => {
+      if (!sym) return undefined;
+      const hasUserDecl = (sym.declarations ?? []).some((d) =>
+        !d.getSourceFile().isDeclarationFile
+      );
+      if (!hasUserDecl) return undefined;
+      const { text } = extractDocFromSymbolAndDecls(
+        sym,
+        context.typeChecker,
+      );
+      return text;
+    };
+
+    const aliasDoc = pickDoc(aliasSym);
+    const directDoc = pickDoc(directSym);
+    const chosen = aliasDoc ?? directDoc;
+
+    if (chosen && isRecord(schema) && !("description" in schema)) {
+      (schema as Record<string, unknown>).description = chosen;
+    }
+    return schema;
+  }
 }

packages/schema-generator/src/type-utils.ts

@@ -271,6 +271,25 @@ export function getArrayElementInfo(
     if (elementType) return { elementType };
   }
 
+  // If the type also has a string index signature, prefer treating it as an
+  // object map (not an array). This avoids misclassifying dictionary types
+  // like `{ [k: string]: T; [n: number]: T }` as arrays.
+  const stringIndex = safeGetIndexTypeOfType(
+    checker,
+    type,
+    ts.IndexKind.String,
+    "array/map disambiguation string index",
+  );
+  const numberIndex = safeGetIndexTypeOfType(
+    checker,
+    type,
+    ts.IndexKind.Number,
+    "array/map disambiguation number index",
+  );
+  if (stringIndex && numberIndex) {
+    return undefined;
+  }
+
   // Use numeric index type as fallback (for tuples/array-like objects)
   const elementType = safeGetIndexTypeOfType(
     checker,

packages/schema-generator/test/fixtures/schema/descriptions-array-doc.expected.json

@@ -0,0 +1,16 @@
+{
+  "properties": {
+    "tags": {
+      "description": "tags of the item",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "tags"
+  ],
+  "type": "object"
+}
+

packages/schema-generator/test/fixtures/schema/descriptions-array-doc.input.ts

@@ -0,0 +1,5 @@
+interface SchemaRoot {
+  /** tags of the item */
+  tags: string[];
+}
+

packages/schema-generator/test/fixtures/schema/descriptions-basic.expected.json

@@ -0,0 +1,13 @@
+{
+  "properties": {
+    "name": {
+      "description": "Name doc",
+      "type": "string"
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "description": "Root doc",
+  "type": "object"
+}

packages/schema-generator/test/fixtures/schema/descriptions-basic.input.ts

@@ -0,0 +1,5 @@
+/** Root doc */
+interface SchemaRoot {
+  /** Name doc */
+  name: string;
+}