@constructive-io/graphql-codegen 4.5.2 → 4.6.0

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

@@ -115,7 +115,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) {
@@ -127,12 +127,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 = (0, utils_1.stripSmartComments)(typeInfo.description, comments);
+        if (enumDescription) {
+            (0, babel_ast_1.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();
@@ -164,6 +169,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 = (0, utils_1.stripSmartComments)(field.description, comments);
+                if (fieldDescription) {
+                    (0, babel_ast_1.addJSDocComment)(prop, fieldDescription.split('\n'));
+                }
                 properties.push(prop);
                 const baseType = (0, type_resolver_1.getTypeBaseName)(field.type);
                 if (baseType &&
@@ -177,11 +186,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 = (0, utils_1.stripSmartComments)(typeInfo.description, comments);
+        if (inputDescription) {
+            (0, babel_ast_1.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) {
@@ -195,7 +209,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 = (0, utils_1.stripSmartComments)(typeInfo.description, comments);
+        if (unionDescription) {
+            (0, babel_ast_1.addJSDocComment)(exportDecl, unionDescription.split('\n'));
+        }
+        statements.push(exportDecl);
         generatedTypes.add(typeName);
     }
     return { statements, generatedTypes };
@@ -223,7 +242,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();
@@ -256,6 +275,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 = (0, utils_1.stripSmartComments)(field.description, comments);
+                if (fieldDescription) {
+                    (0, babel_ast_1.addJSDocComment)(prop, fieldDescription.split('\n'));
+                }
                 properties.push(prop);
                 if (baseType && tableTypeNames.has(baseType)) {
                     referencedTableTypes.add(baseType);
@@ -271,22 +294,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 = (0, utils_1.stripSmartComments)(typeInfo.description, comments);
+        if (payloadDescription) {
+            (0, babel_ast_1.addJSDocComment)(exportDecl, payloadDescription.split('\n'));
+        }
+        statements.push(exportDecl);
     }
     return { statements, generatedTypes, referencedTableTypes };
 }
 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(scalars_1.BASE_FILTER_TYPE_NAMES).sort();
     const allTypesImports = [...referencedTableTypes, ...baseFilterImports];

package/core/codegen/shared/index.js

@@ -64,6 +64,7 @@ function exportAllFrom(modulePath) {
  */
 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) => (0, utils_1.getTableNames)(t).typeName));
@@ -75,6 +76,7 @@ function generateSharedTypes(options) {
         const schemaTypesResult = (0, schema_types_generator_1.generateSchemaTypesFile)({
             typeRegistry: customOperations.typeRegistry,
             tableTypeNames,
+            comments: commentsEnabled,
         });
         // Only include if there's meaningful content
         if (schemaTypesResult.content.split('\n').length > 10) {

package/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/core/codegen/utils.js

@@ -37,6 +37,7 @@ exports.getPrimaryKeyInfo = getPrimaryKeyInfo;
 exports.getPrimaryKeyFields = getPrimaryKeyFields;
 exports.hasValidPrimaryKey = hasValidPrimaryKey;
 exports.getQueryKeyPrefix = getQueryKeyPrefix;
+exports.stripSmartComments = stripSmartComments;
 exports.getGeneratedFileHeader = getGeneratedFileHeader;
 exports.indent = indent;
 /**
@@ -364,6 +365,92 @@ 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
+ */
+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/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

package/core/introspect/infer-tables.js

@@ -16,6 +16,7 @@ exports.inferTablesFromIntrospection = inferTablesFromIntrospection;
  * - Mutation operations: create{Name}, update{Name}, delete{Name}
  */
 const inflekt_1 = require("inflekt");
+const utils_1 = require("../codegen/utils");
 const introspection_1 = require("../../types/introspection");
 // ============================================================================
 // Pattern Matching Constants
@@ -84,6 +85,7 @@ function isInternalType(name) {
 function inferTablesFromIntrospection(introspection, options = {}) {
     const { __schema: schema } = introspection;
     const { types, queryType, mutationType } = schema;
+    const commentsEnabled = options.comments !== false;
     // Build lookup maps for efficient access
     const typeMap = buildTypeMap(types);
     const { entityNames, entityToConnection, connectionToEntity } = buildEntityConnectionMaps(types, typeMap);
@@ -98,7 +100,7 @@ function inferTablesFromIntrospection(introspection, options = {}) {
         if (!entityType)
             continue;
         // Infer all metadata for this entity
-        const { table, hasRealOperation } = buildCleanTable(entityName, entityType, typeMap, queryFields, mutationFields, entityToConnection, connectionToEntity);
+        const { table, hasRealOperation } = buildCleanTable(entityName, entityType, typeMap, queryFields, mutationFields, entityToConnection, connectionToEntity, commentsEnabled);
         // Only include tables that have at least one real operation
         if (hasRealOperation) {
             tables.push(table);
@@ -172,9 +174,9 @@ function resolveEntityNameFromConnectionType(connectionType, typeMap) {
 /**
  * Build a complete CleanTable from an entity type
  */
-function buildCleanTable(entityName, entityType, typeMap, queryFields, mutationFields, entityToConnection, connectionToEntity) {
+function buildCleanTable(entityName, entityType, typeMap, queryFields, mutationFields, entityToConnection, connectionToEntity, commentsEnabled) {
     // Extract scalar fields from entity type
-    const fields = extractEntityFields(entityType, typeMap, entityToConnection);
+    const fields = extractEntityFields(entityType, typeMap, entityToConnection, commentsEnabled);
     // Infer relations from entity fields
     const relations = inferRelations(entityType, entityToConnection, connectionToEntity);
     // Match query and mutation operations
@@ -202,9 +204,12 @@ function buildCleanTable(entityName, entityType, typeMap, queryFields, mutationF
         delete: mutationOps.delete,
         patchFieldName,
     };
+    // Extract description from entity type (PostgreSQL COMMENT), strip smart comments
+    const description = commentsEnabled ? (0, utils_1.stripSmartComments)(entityType.description) : undefined;
     return {
         table: {
             name: entityName,
+            ...(description ? { description } : {}),
             fields,
             relations,
             inflection,
@@ -221,7 +226,7 @@ function buildCleanTable(entityName, entityType, typeMap, queryFields, mutationF
  * Extract scalar fields from an entity type
  * Excludes relation fields (those returning other entity types or connections)
  */
-function extractEntityFields(entityType, typeMap, entityToConnection) {
+function extractEntityFields(entityType, typeMap, entityToConnection, commentsEnabled) {
     const fields = [];
     if (!entityType.fields)
         return fields;
@@ -239,8 +244,10 @@ function extractEntityFields(entityType, typeMap, entityToConnection) {
             }
         }
         // Include scalar, enum, and other non-relation fields
+        const fieldDescription = commentsEnabled ? (0, utils_1.stripSmartComments)(field.description) : undefined;
         fields.push({
             name: field.name,
+            ...(fieldDescription ? { description: fieldDescription } : {}),
             type: convertToCleanFieldType(field.type),
         });
     }

package/core/pipeline/index.js

@@ -30,7 +30,8 @@ async function runCodegenPipeline(options) {
     const { introspection } = await source.fetch();
     // 2. Infer tables from introspection (replaces _meta)
     log('Inferring table metadata from schema...');
-    let tables = (0, infer_tables_1.inferTablesFromIntrospection)(introspection);
+    const commentsEnabled = config.codegen?.comments !== false;
+    let tables = (0, infer_tables_1.inferTablesFromIntrospection)(introspection, { comments: commentsEnabled });
     const totalTables = tables.length;
     log(`  Found ${totalTables} tables`);
     // 3. Filter tables by config (combine exclude and systemExclude)

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

@@ -37,14 +37,14 @@ export function generateHooksReadme(tables, customOperations) {
     lines.push('|------|------|-------------|');
     for (const table of tables) {
         const { singularName, pluralName } = getTableNames(table);
-        lines.push(`| \`${getListQueryHookName(table)}\` | Query | List all ${pluralName} |`);
+        lines.push(`| \`${getListQueryHookName(table)}\` | Query | ${table.description || `List all ${pluralName}`} |`);
         if (hasValidPrimaryKey(table)) {
-            lines.push(`| \`${getSingleQueryHookName(table)}\` | Query | Get one ${singularName} |`);
+            lines.push(`| \`${getSingleQueryHookName(table)}\` | Query | ${table.description || `Get one ${singularName}`} |`);
         }
-        lines.push(`| \`${getCreateMutationHookName(table)}\` | Mutation | Create a ${singularName} |`);
+        lines.push(`| \`${getCreateMutationHookName(table)}\` | Mutation | ${table.description || `Create a ${singularName}`} |`);
         if (hasValidPrimaryKey(table)) {
-            lines.push(`| \`${getUpdateMutationHookName(table)}\` | Mutation | Update a ${singularName} |`);
-            lines.push(`| \`${getDeleteMutationHookName(table)}\` | Mutation | Delete a ${singularName} |`);
+            lines.push(`| \`${getUpdateMutationHookName(table)}\` | Mutation | ${table.description || `Update a ${singularName}`} |`);
+            lines.push(`| \`${getDeleteMutationHookName(table)}\` | Mutation | ${table.description || `Delete a ${singularName}`} |`);
         }
     }
     for (const op of customOperations) {
@@ -145,7 +145,7 @@ export function generateHooksAgentsDocs(tables, customOperations) {
         const scalarFields = getScalarFields(table);
         lines.push(`### HOOK: ${getListQueryHookName(table)}`);
         lines.push('');
-        lines.push(`List all ${pluralName}.`);
+        lines.push(`${table.description || `List all ${pluralName}`}.`);
         lines.push('');
         lines.push('```');
         lines.push(`TYPE: query`);
@@ -164,7 +164,7 @@ export function generateHooksAgentsDocs(tables, customOperations) {
         if (hasValidPrimaryKey(table)) {
             lines.push(`### HOOK: ${getSingleQueryHookName(table)}`);
             lines.push('');
-            lines.push(`Get a single ${singularName} by ${pk.name}.`);
+            lines.push(`${table.description || `Get a single ${singularName} by ${pk.name}`}.`);
             lines.push('');
             lines.push('```');
             lines.push(`TYPE: query`);
@@ -184,7 +184,7 @@ export function generateHooksAgentsDocs(tables, customOperations) {
         }
         lines.push(`### HOOK: ${getCreateMutationHookName(table)}`);
         lines.push('');
-        lines.push(`Create a new ${singularName}.`);
+        lines.push(`${table.description || `Create a new ${singularName}`}.`);
         lines.push('');
         lines.push('```');
         lines.push('TYPE: mutation');
@@ -196,7 +196,7 @@ export function generateHooksAgentsDocs(tables, customOperations) {
         if (hasValidPrimaryKey(table)) {
             lines.push(`### HOOK: ${getUpdateMutationHookName(table)}`);
             lines.push('');
-            lines.push(`Update an existing ${singularName}.`);
+            lines.push(`${table.description || `Update an existing ${singularName}`}.`);
             lines.push('');
             lines.push('```');
             lines.push('TYPE: mutation');
@@ -207,7 +207,7 @@ export function generateHooksAgentsDocs(tables, customOperations) {
             lines.push('');
             lines.push(`### HOOK: ${getDeleteMutationHookName(table)}`);
             lines.push('');
-            lines.push(`Delete a ${singularName}.`);
+            lines.push(`${table.description || `Delete a ${singularName}`}.`);
             lines.push('');
             lines.push('```');
             lines.push('TYPE: mutation');
@@ -267,7 +267,7 @@ export function getHooksMcpTools(tables, customOperations) {
         const scalarFields = getScalarFields(table);
         tools.push({
             name: `hooks_${lcFirst(pluralName)}_query`,
-            description: `React Query hook to list all ${pluralName}`,
+            description: table.description || `React Query hook to list all ${pluralName}`,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -281,7 +281,7 @@ export function getHooksMcpTools(tables, customOperations) {
         if (hasValidPrimaryKey(table)) {
             tools.push({
                 name: `hooks_${lcFirst(singularName)}_query`,
-                description: `React Query hook to get a single ${singularName} by ${pk.name}`,
+                description: table.description || `React Query hook to get a single ${singularName} by ${pk.name}`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -296,7 +296,7 @@ export function getHooksMcpTools(tables, customOperations) {
         }
         tools.push({
             name: `hooks_create_${lcFirst(singularName)}_mutation`,
-            description: `React Query mutation hook to create a ${singularName}`,
+            description: table.description || `React Query mutation hook to create a ${singularName}`,
             inputSchema: {
                 type: 'object',
                 properties: Object.fromEntries(scalarFields
@@ -316,7 +316,7 @@ export function getHooksMcpTools(tables, customOperations) {
         if (hasValidPrimaryKey(table)) {
             tools.push({
                 name: `hooks_update_${lcFirst(singularName)}_mutation`,
-                description: `React Query mutation hook to update a ${singularName}`,
+                description: table.description || `React Query mutation hook to update a ${singularName}`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -330,7 +330,7 @@ export function getHooksMcpTools(tables, customOperations) {
             });
             tools.push({
                 name: `hooks_delete_${lcFirst(singularName)}_mutation`,
-                description: `React Query mutation hook to delete a ${singularName}`,
+                description: table.description || `React Query mutation hook to delete a ${singularName}`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -384,7 +384,7 @@ export function generateHooksSkills(tables, customOperations) {
             fileName: `skills/${lcFirst(singularName)}.md`,
             content: buildSkillFile({
                 name: `hooks-${lcFirst(singularName)}`,
-                description: `React Query hooks for ${table.name} data operations`,
+                description: table.description || `React Query hooks for ${table.name} data operations`,
                 language: 'typescript',
                 usage: [
                     `${getListQueryHookName(table)}({ selection: { fields: { ${selectFields} } } })`,

package/esm/core/codegen/mutations.js

@@ -76,7 +76,7 @@ export function generateCreateMutationHook(table, options = {}) {
     ]);
     const o1 = exportDeclareFunction(hookName, createSTypeParam(selectTypeName), [createFunctionParam('params', o1ParamType)], useMutationResultType(resultType(sRef()), createVarType));
     addJSDocComment(o1, [
-        `Mutation hook for creating a ${typeName}`,
+        table.description || `Mutation hook for creating a ${typeName}`,
         '',
         '@example',
         '```tsx',
@@ -129,7 +129,7 @@ export function generateCreateMutationHook(table, options = {}) {
     statements.push(exportFunction(hookName, null, [createFunctionParam('params', implParamType)], body));
     return {
         fileName: getCreateMutationFileName(table),
-        content: generateHookFileCode(`Create mutation hook for ${typeName}`, statements),
+        content: generateHookFileCode(table.description || `Create mutation hook for ${typeName}`, statements),
     };
 }
 export function generateUpdateMutationHook(table, options = {}) {
@@ -185,7 +185,7 @@ export function generateUpdateMutationHook(table, options = {}) {
     ]);
     const o1 = exportDeclareFunction(hookName, createSTypeParam(selectTypeName), [createFunctionParam('params', o1ParamType)], useMutationResultType(resultType(sRef()), updateVarType));
     addJSDocComment(o1, [
-        `Mutation hook for updating a ${typeName}`,
+        table.description || `Mutation hook for updating a ${typeName}`,
         '',
         '@example',
         '```tsx',
@@ -256,7 +256,7 @@ export function generateUpdateMutationHook(table, options = {}) {
     statements.push(exportFunction(hookName, null, [createFunctionParam('params', implParamType)], body));
     return {
         fileName: getUpdateMutationFileName(table),
-        content: generateHookFileCode(`Update mutation hook for ${typeName}`, statements),
+        content: generateHookFileCode(table.description || `Update mutation hook for ${typeName}`, statements),
     };
 }
 export function generateDeleteMutationHook(table, options = {}) {
@@ -309,7 +309,7 @@ export function generateDeleteMutationHook(table, options = {}) {
     ]);
     const o1 = exportDeclareFunction(hookName, createSTypeParam(selectTypeName), [createFunctionParam('params', o1ParamType)], useMutationResultType(resultType(sRef()), deleteVarType));
     addJSDocComment(o1, [
-        `Mutation hook for deleting a ${typeName} with typed selection`,
+        table.description || `Mutation hook for deleting a ${typeName} with typed selection`,
         '',
         '@example',
         '```tsx',
@@ -374,7 +374,7 @@ export function generateDeleteMutationHook(table, options = {}) {
     statements.push(exportFunction(hookName, null, [createFunctionParam('params', implParamType)], body));
     return {
         fileName: getDeleteMutationFileName(table),
-        content: generateHookFileCode(`Delete mutation hook for ${typeName}`, statements),
+        content: generateHookFileCode(table.description || `Delete mutation hook for ${typeName}`, statements),
     };
 }
 export function generateAllMutationHooks(tables, options = {}) {

package/esm/core/codegen/orm/custom-ops-generator.d.ts

@@ -6,8 +6,8 @@ export interface GeneratedCustomOpsFile {
 /**
  * Generate the query/index.ts file for custom query operations
  */
-export declare function generateCustomQueryOpsFile(operations: CleanOperation[]): GeneratedCustomOpsFile;
+export declare function generateCustomQueryOpsFile(operations: CleanOperation[], comments?: boolean): GeneratedCustomOpsFile;
 /**
  * Generate the mutation/index.ts file for custom mutation operations
  */
-export declare function generateCustomMutationOpsFile(operations: CleanOperation[]): GeneratedCustomOpsFile;
+export declare function generateCustomMutationOpsFile(operations: CleanOperation[], comments?: boolean): GeneratedCustomOpsFile;

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);
     }