@constructive-io/graphql-codegen 4.5.2 → 4.6.0

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
  */

package/esm/core/codegen/utils.js

@@ -323,6 +323,92 @@ export function getQueryKeyPrefix(table) {
     return lcFirst(table.name);
 }
 // ============================================================================
+// Smart Comment Utilities
+// ============================================================================
+/**
+ * PostGraphile smart comment tags that should be stripped from descriptions.
+ * Smart comments start with `@` and control PostGraphile behavior
+ * (e.g., `@omit`, `@name`, `@foreignKey`, etc.)
+ *
+ * A PostgreSQL COMMENT may contain both human-readable text and smart comments:
+ *   COMMENT ON TABLE users IS 'User accounts for the application\n@omit delete';
+ *
+ * PostGraphile's introspection already separates these: the GraphQL `description`
+ * field contains only the human-readable part. So in most cases, the description
+ * we receive from introspection is already clean.
+ *
+ * However, as a safety measure, this utility strips any remaining `@`-prefixed
+ * lines that may have leaked through.
+ */
+/**
+ * PostGraphile auto-generated boilerplate descriptions that add no value.
+ * These are generic descriptions PostGraphile puts on every mutation input,
+ * clientMutationId field, etc. We filter them out to keep generated code clean.
+ */
+const POSTGRAPHILE_BOILERPLATE = [
+    'The exclusive input argument for this mutation.',
+    'An arbitrary string value with no semantic meaning.',
+    'The exact same `clientMutationId` that was provided in the mutation input,',
+    'The output of our',
+    'All input for the',
+    'A cursor for use in pagination.',
+    'An edge for our',
+    'Information to aid in pagination.',
+    'Reads and enables pagination through a set of',
+    'A list of edges which contains the',
+    'The count of *all* `',
+    'A list of `',
+    'Our root query field',
+    'Reads a single',
+    'The root query type',
+    'The root mutation type',
+];
+/**
+ * Check if a description is generic PostGraphile boilerplate that should be suppressed.
+ */
+function isBoilerplateDescription(description) {
+    const trimmed = description.trim();
+    return POSTGRAPHILE_BOILERPLATE.some((bp) => trimmed.startsWith(bp));
+}
+/**
+ * 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 function stripSmartComments(description, enabled = true) {
+    if (!enabled)
+        return undefined;
+    if (!description)
+        return undefined;
+    // Check if entire description is boilerplate
+    if (isBoilerplateDescription(description))
+        return undefined;
+    const lines = description.split('\n');
+    const cleanLines = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip lines that start with @ (smart comment directives)
+        if (trimmed.startsWith('@'))
+            continue;
+        cleanLines.push(line);
+    }
+    const result = cleanLines.join('\n').trim();
+    if (result.length === 0)
+        return undefined;
+    // Re-check after stripping smart comments
+    if (isBoilerplateDescription(result))
+        return undefined;
+    return result;
+}
+// ============================================================================
 // Code generation helpers
 // ============================================================================
 /**

package/esm/core/introspect/infer-tables.d.ts

@@ -25,6 +25,11 @@ export interface InferTablesOptions {
      * Custom pattern overrides (for non-standard PostGraphile configurations)
      */
     patterns?: Partial<typeof PATTERNS>;
+    /**
+     * Include PostgreSQL COMMENT descriptions on tables and fields.
+     * @default true
+     */
+    comments?: boolean;
 }
 /**
  * Infer CleanTable[] from GraphQL introspection by recognizing PostGraphile patterns