@constructive-io/graphql-codegen 4.5.3 → 4.6.1

package/esm/core/codegen/orm/custom-ops-generator.js

@@ -5,10 +5,10 @@
  * like login, register, currentUser, etc.
  */
 import * as t from '@babel/types';
-import { generateCode } from '../babel-ast';
+import { addJSDocComment, generateCode } from '../babel-ast';
 import { NON_SELECT_TYPES, getSelectTypeName } from '../select-helpers';
 import { getTypeBaseName, isTypeRequired, scalarToTsType, typeRefToTsType, } from '../type-resolver';
-import { getGeneratedFileHeader, ucFirst } from '../utils';
+import { getGeneratedFileHeader, stripSmartComments, ucFirst } from '../utils';
 /**
  * Collect all input type names used by operations
  * Includes Input, Filter, OrderBy, and Condition types
@@ -67,7 +67,7 @@ function createImportDeclaration(moduleSpecifier, namedImports, typeOnly = false
     decl.importKind = typeOnly ? 'type' : 'value';
     return decl;
 }
-function createVariablesInterface(op) {
+function createVariablesInterface(op, comments = true) {
     if (op.args.length === 0)
         return null;
     const varTypeName = `${ucFirst(op.name)}Variables`;
@@ -75,10 +75,19 @@ function createVariablesInterface(op) {
         const optional = !isTypeRequired(arg.type);
         const prop = t.tsPropertySignature(t.identifier(arg.name), t.tsTypeAnnotation(parseTypeAnnotation(typeRefToTsType(arg.type))));
         prop.optional = optional;
+        const argDescription = stripSmartComments(arg.description, comments);
+        if (argDescription) {
+            addJSDocComment(prop, argDescription.split('\n'));
+        }
         return prop;
     });
     const interfaceDecl = t.tsInterfaceDeclaration(t.identifier(varTypeName), null, null, t.tsInterfaceBody(props));
-    return t.exportNamedDeclaration(interfaceDecl);
+    const exportDecl = t.exportNamedDeclaration(interfaceDecl);
+    const opDescription = stripSmartComments(op.description, comments);
+    if (opDescription) {
+        addJSDocComment(exportDecl, [`Variables for ${op.name}`, opDescription]);
+    }
+    return exportDecl;
 }
 function parseTypeAnnotation(typeStr) {
     if (typeStr === 'string')
@@ -250,7 +259,7 @@ function buildOperationMethod(op, operationType) {
 /**
  * Generate the query/index.ts file for custom query operations
  */
-export function generateCustomQueryOpsFile(operations) {
+export function generateCustomQueryOpsFile(operations, comments = true) {
     const statements = [];
     // Collect all input type names and payload type names
     const inputTypeNames = collectInputTypeNamesFromOps(operations);
@@ -278,7 +287,7 @@ export function generateCustomQueryOpsFile(operations) {
     statements.push(createImportDeclaration('../input-types', ['connectionFieldsMap']));
     // Generate variable interfaces
     for (const op of operations) {
-        const varInterface = createVariablesInterface(op);
+        const varInterface = createVariablesInterface(op, comments);
         if (varInterface)
             statements.push(varInterface);
     }
@@ -300,7 +309,7 @@ export function generateCustomQueryOpsFile(operations) {
 /**
  * Generate the mutation/index.ts file for custom mutation operations
  */
-export function generateCustomMutationOpsFile(operations) {
+export function generateCustomMutationOpsFile(operations, comments = true) {
     const statements = [];
     // Collect all input type names and payload type names
     const inputTypeNames = collectInputTypeNamesFromOps(operations);
@@ -328,7 +337,7 @@ export function generateCustomMutationOpsFile(operations) {
     statements.push(createImportDeclaration('../input-types', ['connectionFieldsMap']));
     // Generate variable interfaces
     for (const op of operations) {
-        const varInterface = createVariablesInterface(op);
+        const varInterface = createVariablesInterface(op, comments);
         if (varInterface)
             statements.push(varInterface);
     }

package/esm/core/codegen/orm/docs-generator.js

@@ -224,7 +224,7 @@ export function getOrmMcpTools(tables, customOperations) {
         const editableFields = getEditableFields(table);
         tools.push({
             name: `orm_${lcFirst(singularName)}_findMany`,
-            description: `List all ${table.name} records via ORM`,
+            description: table.description || `List all ${table.name} records via ORM`,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -241,7 +241,7 @@ export function getOrmMcpTools(tables, customOperations) {
         });
         tools.push({
             name: `orm_${lcFirst(singularName)}_findOne`,
-            description: `Get a single ${table.name} record by ${pk.name}`,
+            description: table.description || `Get a single ${table.name} record by ${pk.name}`,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -262,7 +262,7 @@ export function getOrmMcpTools(tables, customOperations) {
         }
         tools.push({
             name: `orm_${lcFirst(singularName)}_create`,
-            description: `Create a new ${table.name} record`,
+            description: table.description || `Create a new ${table.name} record`,
             inputSchema: {
                 type: 'object',
                 properties: createProps,
@@ -283,7 +283,7 @@ export function getOrmMcpTools(tables, customOperations) {
         }
         tools.push({
             name: `orm_${lcFirst(singularName)}_update`,
-            description: `Update an existing ${table.name} record`,
+            description: table.description || `Update an existing ${table.name} record`,
             inputSchema: {
                 type: 'object',
                 properties: updateProps,
@@ -292,7 +292,7 @@ export function getOrmMcpTools(tables, customOperations) {
         });
         tools.push({
             name: `orm_${lcFirst(singularName)}_delete`,
-            description: `Delete a ${table.name} record by ${pk.name}`,
+            description: table.description || `Delete a ${table.name} record by ${pk.name}`,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -350,7 +350,7 @@ export function generateOrmSkills(tables, customOperations) {
             fileName: `skills/${lcFirst(singularName)}.md`,
             content: buildSkillFile({
                 name: `orm-${lcFirst(singularName)}`,
-                description: `ORM operations for ${table.name} records`,
+                description: table.description || `ORM operations for ${table.name} records`,
                 language: 'typescript',
                 usage: [
                     `db.${lcFirst(singularName)}.findMany({ select: { id: true } }).execute()`,

package/esm/core/codegen/orm/index.js

@@ -8,6 +8,7 @@ import { generateAllModelFiles } from './model-generator';
  */
 export function generateOrm(options) {
     const { tables, customOperations, sharedTypesPath } = options;
+    const commentsEnabled = options.config.codegen?.comments !== false;
     const files = [];
     // Use shared types when a sharedTypesPath is provided (unified output mode)
     const useSharedTypes = !!sharedTypesPath;
@@ -65,7 +66,7 @@ export function generateOrm(options) {
                 }
             }
         }
-        const inputTypesFile = generateInputTypesFile(typeRegistry ?? new Map(), usedInputTypes, tables, usedPayloadTypes);
+        const inputTypesFile = generateInputTypesFile(typeRegistry ?? new Map(), usedInputTypes, tables, usedPayloadTypes, commentsEnabled);
         files.push({
             path: inputTypesFile.fileName,
             content: inputTypesFile.content,
@@ -73,11 +74,11 @@ export function generateOrm(options) {
     }
     // 5. Generate custom operations (if any)
     if (hasCustomQueries && customOperations?.queries) {
-        const queryOpsFile = generateCustomQueryOpsFile(customOperations.queries);
+        const queryOpsFile = generateCustomQueryOpsFile(customOperations.queries, commentsEnabled);
         files.push({ path: queryOpsFile.fileName, content: queryOpsFile.content });
     }
     if (hasCustomMutations && customOperations?.mutations) {
-        const mutationOpsFile = generateCustomMutationOpsFile(customOperations.mutations);
+        const mutationOpsFile = generateCustomMutationOpsFile(customOperations.mutations, commentsEnabled);
         files.push({
             path: mutationOpsFile.fileName,
             content: mutationOpsFile.content,

package/esm/core/codegen/orm/input-types-generator.d.ts

@@ -18,4 +18,4 @@ export declare function collectPayloadTypeNames(operations: Array<{
 /**
  * Generate comprehensive input-types.ts file using Babel AST
  */
-export declare function generateInputTypesFile(typeRegistry: TypeRegistry, usedInputTypes: Set<string>, tables?: CleanTable[], usedPayloadTypes?: Set<string>): GeneratedInputTypesFile;
+export declare function generateInputTypesFile(typeRegistry: TypeRegistry, usedInputTypes: Set<string>, tables?: CleanTable[], usedPayloadTypes?: Set<string>, comments?: boolean): GeneratedInputTypesFile;

package/esm/core/codegen/orm/input-types-generator.js

@@ -12,10 +12,10 @@
  */
 import * as t from '@babel/types';
 import { pluralize } from 'inflekt';
-import { addLineComment, generateCode } from '../babel-ast';
+import { addJSDocComment, addLineComment, generateCode } from '../babel-ast';
 import { SCALAR_NAMES, scalarToFilterType, scalarToTsType } from '../scalars';
 import { getTypeBaseName } from '../type-resolver';
-import { getCreateInputTypeName, getConditionTypeName, getFilterTypeName, getGeneratedFileHeader, getOrderByTypeName, getPrimaryKeyInfo, getTableNames, isRelationField, lcFirst, } from '../utils';
+import { getCreateInputTypeName, getConditionTypeName, getFilterTypeName, getGeneratedFileHeader, getOrderByTypeName, getPrimaryKeyInfo, getTableNames, isRelationField, lcFirst, stripSmartComments, } from '../utils';
 // ============================================================================
 // Constants
 // ============================================================================
@@ -117,19 +117,26 @@ function parseTypeString(typeStr) {
 /**
  * Create an interface property signature
  */
-function createPropertySignature(name, typeStr, optional) {
+function createPropertySignature(name, typeStr, optional, description) {
     const prop = t.tsPropertySignature(t.identifier(name), t.tsTypeAnnotation(parseTypeString(typeStr)));
     prop.optional = optional;
+    if (description) {
+        addJSDocComment(prop, description.split('\n'));
+    }
     return prop;
 }
 /**
  * Create an exported interface declaration
  */
-function createExportedInterface(name, properties) {
-    const props = properties.map((p) => createPropertySignature(p.name, p.type, p.optional));
+function createExportedInterface(name, properties, description) {
+    const props = properties.map((p) => createPropertySignature(p.name, p.type, p.optional, p.description));
     const body = t.tsInterfaceBody(props);
     const interfaceDecl = t.tsInterfaceDeclaration(t.identifier(name), null, null, body);
-    return t.exportNamedDeclaration(interfaceDecl);
+    const exportDecl = t.exportNamedDeclaration(interfaceDecl);
+    if (description) {
+        addJSDocComment(exportDecl, description.split('\n'));
+    }
+    return exportDecl;
 }
 /**
  * Create an exported type alias declaration
@@ -310,7 +317,7 @@ function collectEnumTypesFromTables(tables, typeRegistry) {
 /**
  * Generate enum type statements
  */
-function generateEnumTypes(typeRegistry, enumTypeNames) {
+function generateEnumTypes(typeRegistry, enumTypeNames, comments = true) {
     if (enumTypeNames.size === 0)
         return [];
     const statements = [];
@@ -320,7 +327,12 @@ function generateEnumTypes(typeRegistry, enumTypeNames) {
             continue;
         const unionType = createStringLiteralUnion(typeInfo.enumValues);
         const typeAlias = t.tsTypeAliasDeclaration(t.identifier(typeName), null, unionType);
-        statements.push(t.exportNamedDeclaration(typeAlias));
+        const exportDecl = t.exportNamedDeclaration(typeAlias);
+        const enumDescription = stripSmartComments(typeInfo.description, comments);
+        if (enumDescription) {
+            addJSDocComment(exportDecl, enumDescription.split('\n'));
+        }
+        statements.push(exportDecl);
     }
     if (statements.length > 0) {
         addSectionComment(statements, 'Enum Types');
@@ -380,6 +392,7 @@ function buildEntityProperties(table) {
             name: field.name,
             type: isNullable ? `${tsType} | null` : tsType,
             optional: isNullable,
+            description: field.description,
         });
     }
     return properties;
@@ -391,7 +404,7 @@ function generateEntityTypes(tables) {
     const statements = [];
     for (const table of tables) {
         const { typeName } = getTableNames(table);
-        statements.push(createExportedInterface(typeName, buildEntityProperties(table)));
+        statements.push(createExportedInterface(typeName, buildEntityProperties(table), table.description));
     }
     if (statements.length > 0) {
         addSectionComment(statements, 'Entity Types');
@@ -962,7 +975,7 @@ function buildTableCrudTypeNames(tables) {
 /**
  * Generate custom input type statements from TypeRegistry
  */
-function generateCustomInputTypes(typeRegistry, usedInputTypes, tableCrudTypes) {
+function generateCustomInputTypes(typeRegistry, usedInputTypes, tableCrudTypes, comments = true) {
     const statements = [];
     const generatedTypes = new Set();
     const typesToGenerate = new Set(Array.from(usedInputTypes));
@@ -998,7 +1011,12 @@ function generateCustomInputTypes(typeRegistry, usedInputTypes, tableCrudTypes)
             for (const field of typeInfo.inputFields) {
                 const optional = !isRequired(field.type);
                 const tsType = typeRefToTs(field.type);
-                properties.push({ name: field.name, type: tsType, optional });
+                properties.push({
+                    name: field.name,
+                    type: tsType,
+                    optional,
+                    description: stripSmartComments(field.description, comments),
+                });
                 // Follow nested Input types
                 const baseType = getTypeBaseName(field.type);
                 if (baseType &&
@@ -1007,12 +1025,17 @@ function generateCustomInputTypes(typeRegistry, usedInputTypes, tableCrudTypes)
                     typesToGenerate.add(baseType);
                 }
             }
-            statements.push(createExportedInterface(typeName, properties));
+            statements.push(createExportedInterface(typeName, properties, stripSmartComments(typeInfo.description, comments)));
         }
         else if (typeInfo.kind === 'ENUM' && typeInfo.enumValues) {
             const unionType = createStringLiteralUnion(typeInfo.enumValues);
             const typeAlias = t.tsTypeAliasDeclaration(t.identifier(typeName), null, unionType);
-            statements.push(t.exportNamedDeclaration(typeAlias));
+            const enumExportDecl = t.exportNamedDeclaration(typeAlias);
+            const enumDescription = stripSmartComments(typeInfo.description, comments);
+            if (enumDescription) {
+                addJSDocComment(enumExportDecl, enumDescription.split('\n'));
+            }
+            statements.push(enumExportDecl);
         }
         else {
             // Add comment for unsupported type kind
@@ -1046,7 +1069,7 @@ export function collectPayloadTypeNames(operations) {
 /**
  * Generate payload/return type statements
  */
-function generatePayloadTypes(typeRegistry, usedPayloadTypes, alreadyGeneratedTypes) {
+function generatePayloadTypes(typeRegistry, usedPayloadTypes, alreadyGeneratedTypes, comments = true) {
     const statements = [];
     const generatedTypes = new Set(alreadyGeneratedTypes);
     const typesToGenerate = new Set(Array.from(usedPayloadTypes));
@@ -1094,6 +1117,7 @@ function generatePayloadTypes(typeRegistry, usedPayloadTypes, alreadyGeneratedTy
                 name: field.name,
                 type: isNullable ? `${tsType} | null` : tsType,
                 optional: isNullable,
+                description: stripSmartComments(field.description, comments),
             });
             // Follow nested OBJECT types
             if (baseType &&
@@ -1105,7 +1129,7 @@ function generatePayloadTypes(typeRegistry, usedPayloadTypes, alreadyGeneratedTy
                 }
             }
         }
-        statements.push(createExportedInterface(typeName, interfaceProps));
+        statements.push(createExportedInterface(typeName, interfaceProps, stripSmartComments(typeInfo.description, comments)));
         // Build Select type
         const selectMembers = [];
         for (const field of typeInfo.fields) {
@@ -1186,7 +1210,7 @@ function generateConnectionFieldsMap(tables, tableByName) {
 /**
  * Generate comprehensive input-types.ts file using Babel AST
  */
-export function generateInputTypesFile(typeRegistry, usedInputTypes, tables, usedPayloadTypes) {
+export function generateInputTypesFile(typeRegistry, usedInputTypes, tables, usedPayloadTypes, comments = true) {
     const statements = [];
     const tablesList = tables ?? [];
     const hasTables = tablesList.length > 0;
@@ -1198,7 +1222,7 @@ export function generateInputTypesFile(typeRegistry, usedInputTypes, tables, use
     // 1. Scalar filter types
     statements.push(...generateScalarFilterTypes());
     // 2. Enum types used by table fields
-    statements.push(...generateEnumTypes(typeRegistry, enumTypes));
+    statements.push(...generateEnumTypes(typeRegistry, enumTypes, comments));
     // 2b. Unknown/custom scalar aliases for schema-specific scalars
     statements.push(...generateCustomScalarTypes(customScalarTypes));
     // 3. Entity and relation types (if tables provided)
@@ -1222,7 +1246,7 @@ export function generateInputTypesFile(typeRegistry, usedInputTypes, tables, use
     statements.push(...generateConnectionFieldsMap(tablesList, tableByName));
     // 7. Custom input types from TypeRegistry
     const tableCrudTypes = tables ? buildTableCrudTypeNames(tables) : undefined;
-    statements.push(...generateCustomInputTypes(typeRegistry, usedInputTypes, tableCrudTypes));
+    statements.push(...generateCustomInputTypes(typeRegistry, usedInputTypes, tableCrudTypes, comments));
     // 8. Payload/return types for custom operations
     if (usedPayloadTypes && usedPayloadTypes.size > 0) {
         const alreadyGeneratedTypes = new Set();
@@ -1232,7 +1256,7 @@ export function generateInputTypesFile(typeRegistry, usedInputTypes, tables, use
                 alreadyGeneratedTypes.add(typeName);
             }
         }
-        statements.push(...generatePayloadTypes(typeRegistry, usedPayloadTypes, alreadyGeneratedTypes));
+        statements.push(...generatePayloadTypes(typeRegistry, usedPayloadTypes, alreadyGeneratedTypes, comments));
     }
     // Generate code with file header
     const header = getGeneratedFileHeader('GraphQL types for ORM client');

package/esm/core/codegen/queries.js

@@ -94,8 +94,9 @@ export function generateListQueryHook(table, options = {}) {
     };
     // Hook
     if (reactQueryEnabled) {
+        const descLine = table.description || `Query hook for fetching ${typeName} list`;
         const docLines = [
-            `Query hook for fetching ${typeName} list`,
+            descLine,
             '',
             '@example',
             '```tsx',
@@ -167,7 +168,7 @@ export function generateListQueryHook(table, options = {}) {
         ]);
         const f1Decl = exportAsyncDeclareFunction(fetchFnName, createSTypeParam(selectTypeName), [createFunctionParam('params', f1ParamType)], typeRef('Promise', [listResultTypeAST(sRef())]));
         addJSDocComment(f1Decl, [
-            `Fetch ${typeName} list without React hooks`,
+            table.description || `Fetch ${typeName} list without React hooks`,
             '',
             '@example',
             '```ts',
@@ -209,7 +210,7 @@ export function generateListQueryHook(table, options = {}) {
             createFunctionParam('params', p1ParamType),
         ], typeRef('Promise', [t.tsVoidKeyword()]));
         addJSDocComment(p1Decl, [
-            `Prefetch ${typeName} list for SSR or cache warming`,
+            table.description || `Prefetch ${typeName} list for SSR or cache warming`,
             '',
             '@example',
             '```ts',
@@ -245,9 +246,9 @@ export function generateListQueryHook(table, options = {}) {
             createFunctionParam('params', pImplParamType),
         ], pBody, typeRef('Promise', [t.tsVoidKeyword()])));
     }
-    const headerText = reactQueryEnabled
+    const headerText = table.description || (reactQueryEnabled
         ? `List query hook for ${typeName}`
-        : `List query functions for ${typeName}`;
+        : `List query functions for ${typeName}`);
     return {
         fileName: getListQueryFileName(table),
         content: generateHookFileCode(headerText, statements),
@@ -331,8 +332,9 @@ export function generateSingleQueryHook(table, options = {}) {
     };
     // Hook
     if (reactQueryEnabled) {
+        const singleDescLine = table.description || `Query hook for fetching a single ${typeName}`;
         const docLines = [
-            `Query hook for fetching a single ${typeName}`,
+            singleDescLine,
             '',
             '@example',
             '```tsx',
@@ -409,7 +411,7 @@ export function generateSingleQueryHook(table, options = {}) {
         ]);
         const f1Decl = exportAsyncDeclareFunction(fetchFnName, createSTypeParam(selectTypeName), [createFunctionParam('params', f1ParamType)], typeRef('Promise', [singleResultTypeAST(sRef())]));
         addJSDocComment(f1Decl, [
-            `Fetch a single ${typeName} without React hooks`,
+            table.description || `Fetch a single ${typeName} without React hooks`,
             '',
             '@example',
             '```ts',
@@ -451,7 +453,7 @@ export function generateSingleQueryHook(table, options = {}) {
             createFunctionParam('params', p1ParamType),
         ], typeRef('Promise', [t.tsVoidKeyword()]));
         addJSDocComment(p1Decl, [
-            `Prefetch a single ${typeName} for SSR or cache warming`,
+            table.description || `Prefetch a single ${typeName} for SSR or cache warming`,
             '',
             '@example',
             '```ts',
@@ -489,9 +491,9 @@ export function generateSingleQueryHook(table, options = {}) {
             createFunctionParam('params', pImplParamType),
         ], pBody, typeRef('Promise', [t.tsVoidKeyword()])));
     }
-    const headerText = reactQueryEnabled
+    const headerText = table.description || (reactQueryEnabled
         ? `Single item query hook for ${typeName}`
-        : `Single item query functions for ${typeName}`;
+        : `Single item query functions for ${typeName}`);
     return {
         fileName: getSingleQueryFileName(table),
         content: generateHookFileCode(headerText, statements),

package/esm/core/codegen/schema-types-generator.d.ts

@@ -22,6 +22,8 @@ export interface GeneratedSchemaTypesFile {
 export interface GenerateSchemaTypesOptions {
     typeRegistry: TypeRegistry;
     tableTypeNames: Set<string>;
+    /** Include descriptions as JSDoc comments. @default true */
+    comments?: boolean;
 }
 export interface PayloadTypesResult {
     statements: t.Statement[];

package/esm/core/codegen/schema-types-generator.js

@@ -12,10 +12,10 @@
  * Uses Babel AST for robust code generation.
  */
 import * as t from '@babel/types';
-import { generateCode } from './babel-ast';
+import { addJSDocComment, generateCode } from './babel-ast';
 import { BASE_FILTER_TYPE_NAMES, SCALAR_NAMES, scalarToTsType, } from './scalars';
 import { getTypeBaseName } from './type-resolver';
-import { getGeneratedFileHeader } from './utils';
+import { getGeneratedFileHeader, stripSmartComments } from './utils';
 const SKIP_TYPES = new Set([
     ...SCALAR_NAMES,
     'Query',
@@ -79,7 +79,7 @@ function generateCustomScalarTypes(customScalarTypes) {
     }
     return statements;
 }
-function generateEnumTypes(typeRegistry, tableTypeNames) {
+function generateEnumTypes(typeRegistry, tableTypeNames, comments = true) {
     const statements = [];
     const generatedTypes = new Set();
     for (const [typeName, typeInfo] of typeRegistry) {
@@ -91,12 +91,17 @@ function generateEnumTypes(typeRegistry, tableTypeNames) {
             continue;
         const unionType = t.tsUnionType(typeInfo.enumValues.map((v) => t.tsLiteralType(t.stringLiteral(v))));
         const typeAlias = t.tsTypeAliasDeclaration(t.identifier(typeName), null, unionType);
-        statements.push(t.exportNamedDeclaration(typeAlias));
+        const exportDecl = t.exportNamedDeclaration(typeAlias);
+        const enumDescription = stripSmartComments(typeInfo.description, comments);
+        if (enumDescription) {
+            addJSDocComment(exportDecl, enumDescription.split('\n'));
+        }
+        statements.push(exportDecl);
         generatedTypes.add(typeName);
     }
     return { statements, generatedTypes };
 }
-function generateInputObjectTypes(typeRegistry, tableTypeNames, alreadyGenerated) {
+function generateInputObjectTypes(typeRegistry, tableTypeNames, alreadyGenerated, comments = true) {
     const statements = [];
     const generatedTypes = new Set(alreadyGenerated);
     const typesToGenerate = new Set();
@@ -128,6 +133,10 @@ function generateInputObjectTypes(typeRegistry, tableTypeNames, alreadyGenerated
                 const tsType = typeRefToTs(field.type);
                 const prop = t.tsPropertySignature(t.identifier(field.name), t.tsTypeAnnotation(t.tsTypeReference(t.identifier(tsType))));
                 prop.optional = optional;
+                const fieldDescription = stripSmartComments(field.description, comments);
+                if (fieldDescription) {
+                    addJSDocComment(prop, fieldDescription.split('\n'));
+                }
                 properties.push(prop);
                 const baseType = getTypeBaseName(field.type);
                 if (baseType &&
@@ -141,11 +150,16 @@ function generateInputObjectTypes(typeRegistry, tableTypeNames, alreadyGenerated
             }
         }
         const interfaceDecl = t.tsInterfaceDeclaration(t.identifier(typeName), null, null, t.tsInterfaceBody(properties));
-        statements.push(t.exportNamedDeclaration(interfaceDecl));
+        const exportDecl = t.exportNamedDeclaration(interfaceDecl);
+        const inputDescription = stripSmartComments(typeInfo.description, comments);
+        if (inputDescription) {
+            addJSDocComment(exportDecl, inputDescription.split('\n'));
+        }
+        statements.push(exportDecl);
     }
     return { statements, generatedTypes };
 }
-function generateUnionTypes(typeRegistry, tableTypeNames, alreadyGenerated) {
+function generateUnionTypes(typeRegistry, tableTypeNames, alreadyGenerated, comments = true) {
     const statements = [];
     const generatedTypes = new Set(alreadyGenerated);
     for (const [typeName, typeInfo] of typeRegistry) {
@@ -159,7 +173,12 @@ function generateUnionTypes(typeRegistry, tableTypeNames, alreadyGenerated) {
             continue;
         const unionType = t.tsUnionType(typeInfo.possibleTypes.map((pt) => t.tsTypeReference(t.identifier(pt))));
         const typeAlias = t.tsTypeAliasDeclaration(t.identifier(typeName), null, unionType);
-        statements.push(t.exportNamedDeclaration(typeAlias));
+        const exportDecl = t.exportNamedDeclaration(typeAlias);
+        const unionDescription = stripSmartComments(typeInfo.description, comments);
+        if (unionDescription) {
+            addJSDocComment(exportDecl, unionDescription.split('\n'));
+        }
+        statements.push(exportDecl);
         generatedTypes.add(typeName);
     }
     return { statements, generatedTypes };
@@ -187,7 +206,7 @@ function collectReturnTypesFromRootTypes(typeRegistry, tableTypeNames) {
         processFields(mutationType.fields);
     return returnTypes;
 }
-function generatePayloadObjectTypes(typeRegistry, tableTypeNames, alreadyGenerated) {
+function generatePayloadObjectTypes(typeRegistry, tableTypeNames, alreadyGenerated, comments = true) {
     const statements = [];
     const generatedTypes = new Set(alreadyGenerated);
     const referencedTableTypes = new Set();
@@ -220,6 +239,10 @@ function generatePayloadObjectTypes(typeRegistry, tableTypeNames, alreadyGenerat
                 const finalType = isNullable ? `${tsType} | null` : tsType;
                 const prop = t.tsPropertySignature(t.identifier(field.name), t.tsTypeAnnotation(t.tsTypeReference(t.identifier(finalType))));
                 prop.optional = isNullable;
+                const fieldDescription = stripSmartComments(field.description, comments);
+                if (fieldDescription) {
+                    addJSDocComment(prop, fieldDescription.split('\n'));
+                }
                 properties.push(prop);
                 if (baseType && tableTypeNames.has(baseType)) {
                     referencedTableTypes.add(baseType);
@@ -235,22 +258,28 @@ function generatePayloadObjectTypes(typeRegistry, tableTypeNames, alreadyGenerat
             }
         }
         const interfaceDecl = t.tsInterfaceDeclaration(t.identifier(typeName), null, null, t.tsInterfaceBody(properties));
-        statements.push(t.exportNamedDeclaration(interfaceDecl));
+        const exportDecl = t.exportNamedDeclaration(interfaceDecl);
+        const payloadDescription = stripSmartComments(typeInfo.description, comments);
+        if (payloadDescription) {
+            addJSDocComment(exportDecl, payloadDescription.split('\n'));
+        }
+        statements.push(exportDecl);
     }
     return { statements, generatedTypes, referencedTableTypes };
 }
 export function generateSchemaTypesFile(options) {
     const { typeRegistry, tableTypeNames } = options;
+    const comments = options.comments !== false;
     const allStatements = [];
     let generatedTypes = new Set();
     const customScalarTypes = collectCustomScalarTypes(typeRegistry);
-    const enumResult = generateEnumTypes(typeRegistry, tableTypeNames);
+    const enumResult = generateEnumTypes(typeRegistry, tableTypeNames, comments);
     generatedTypes = new Set([...generatedTypes, ...enumResult.generatedTypes]);
-    const unionResult = generateUnionTypes(typeRegistry, tableTypeNames, generatedTypes);
+    const unionResult = generateUnionTypes(typeRegistry, tableTypeNames, generatedTypes, comments);
     generatedTypes = new Set([...generatedTypes, ...unionResult.generatedTypes]);
-    const inputResult = generateInputObjectTypes(typeRegistry, tableTypeNames, generatedTypes);
+    const inputResult = generateInputObjectTypes(typeRegistry, tableTypeNames, generatedTypes, comments);
     generatedTypes = new Set([...generatedTypes, ...inputResult.generatedTypes]);
-    const payloadResult = generatePayloadObjectTypes(typeRegistry, tableTypeNames, generatedTypes);
+    const payloadResult = generatePayloadObjectTypes(typeRegistry, tableTypeNames, generatedTypes, comments);
     const referencedTableTypes = Array.from(payloadResult.referencedTableTypes).sort();
     const baseFilterImports = Array.from(BASE_FILTER_TYPE_NAMES).sort();
     const allTypesImports = [...referencedTableTypes, ...baseFilterImports];

package/esm/core/codegen/shared/index.js

@@ -27,6 +27,7 @@ function exportAllFrom(modulePath) {
  */
 export function generateSharedTypes(options) {
     const { tables, customOperations } = options;
+    const commentsEnabled = options.config.codegen?.comments !== false;
     const files = [];
     // Collect table type names for import path resolution
     const tableTypeNames = new Set(tables.map((t) => getTableNames(t).typeName));
@@ -38,6 +39,7 @@ export function generateSharedTypes(options) {
         const schemaTypesResult = generateSchemaTypesFile({
             typeRegistry: customOperations.typeRegistry,
             tableTypeNames,
+            comments: commentsEnabled,
         });
         // Only include if there's meaningful content
         if (schemaTypesResult.content.split('\n').length > 10) {

package/esm/core/codegen/utils.d.ts

@@ -179,6 +179,20 @@ export declare function hasValidPrimaryKey(table: CleanTable): boolean;
  * e.g., "cars" for list queries, "car" for detail queries
  */
 export declare function getQueryKeyPrefix(table: CleanTable): string;
+/**
+ * Strip PostGraphile smart comments and boilerplate from a description string.
+ *
+ * Smart comments are lines starting with `@` (e.g., `@omit`, `@name newName`).
+ * Boilerplate descriptions are generic PostGraphile-generated text that repeats
+ * on every mutation input, clientMutationId field, etc.
+ *
+ * This returns only the meaningful human-readable portion of the comment,
+ * or undefined if the result is empty or boilerplate.
+ *
+ * @param description - Raw description from GraphQL introspection
+ * @returns Cleaned description, or undefined if empty/boilerplate
+ */
+export declare function stripSmartComments(description: string | null | undefined, enabled?: boolean): string | undefined;
 /**
  * Generate a doc comment header for generated files
  */