feat(codegen): render PostgreSQL comments as JSDoc + add @constructive-io/react package

graphql/codegen/src/core/codegen/hooks-docs-generator.ts

@@ -66,22 +66,22 @@ export function generateHooksReadme(
   for (const table of tables) {
     const { singularName, pluralName } = getTableNames(table);
     lines.push(
-      `| \`${getListQueryHookName(table)}\` | Query | List all ${pluralName} |`,
+      `| \`${getListQueryHookName(table)}\` | Query | ${table.description || `List all ${pluralName}`} |`,
     );
     if (hasValidPrimaryKey(table)) {
       lines.push(
-        `| \`${getSingleQueryHookName(table)}\` | Query | Get one ${singularName} |`,
+        `| \`${getSingleQueryHookName(table)}\` | Query | ${table.description || `Get one ${singularName}`} |`,
       );
     }
     lines.push(
-      `| \`${getCreateMutationHookName(table)}\` | Mutation | Create a ${singularName} |`,
+      `| \`${getCreateMutationHookName(table)}\` | Mutation | ${table.description || `Create a ${singularName}`} |`,
     );
     if (hasValidPrimaryKey(table)) {
       lines.push(
-        `| \`${getUpdateMutationHookName(table)}\` | Mutation | Update a ${singularName} |`,
+        `| \`${getUpdateMutationHookName(table)}\` | Mutation | ${table.description || `Update a ${singularName}`} |`,
       );
       lines.push(
-        `| \`${getDeleteMutationHookName(table)}\` | Mutation | Delete a ${singularName} |`,
+        `| \`${getDeleteMutationHookName(table)}\` | Mutation | ${table.description || `Delete a ${singularName}`} |`,
       );
     }
   }
@@ -220,7 +220,7 @@ export function generateHooksAgentsDocs(
 
     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`);
@@ -244,7 +244,7 @@ export function generateHooksAgentsDocs(
     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`);
@@ -269,7 +269,7 @@ export function generateHooksAgentsDocs(
 
     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');
@@ -284,7 +284,7 @@ export function generateHooksAgentsDocs(
     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');
@@ -298,7 +298,7 @@ export function generateHooksAgentsDocs(
 
       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');
@@ -374,7 +374,7 @@ export function getHooksMcpTools(
 
     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: {
@@ -389,7 +389,7 @@ export function getHooksMcpTools(
     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: {
@@ -405,7 +405,7 @@ export function getHooksMcpTools(
 
     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(
@@ -431,7 +431,7 @@ export function getHooksMcpTools(
     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: {
@@ -446,7 +446,7 @@ export function getHooksMcpTools(
 
       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: {
@@ -511,7 +511,7 @@ export function generateHooksSkills(
       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} } } })`,

graphql/codegen/src/core/codegen/mutations.ts

@@ -202,7 +202,7 @@ export function generateCreateMutationHook(
     useMutationResultType(resultType(sRef()), createVarType),
   );
   addJSDocComment(o1, [
-    `Mutation hook for creating a ${typeName}`,
+    table.description || `Mutation hook for creating a ${typeName}`,
     '',
     '@example',
     '```tsx',
@@ -314,7 +314,7 @@ export function generateCreateMutationHook(
   return {
     fileName: getCreateMutationFileName(table),
     content: generateHookFileCode(
-      `Create mutation hook for ${typeName}`,
+      table.description || `Create mutation hook for ${typeName}`,
       statements,
     ),
   };
@@ -433,7 +433,7 @@ export function generateUpdateMutationHook(
     useMutationResultType(resultType(sRef()), updateVarType),
   );
   addJSDocComment(o1, [
-    `Mutation hook for updating a ${typeName}`,
+    table.description || `Mutation hook for updating a ${typeName}`,
     '',
     '@example',
     '```tsx',
@@ -574,7 +574,7 @@ export function generateUpdateMutationHook(
   return {
     fileName: getUpdateMutationFileName(table),
     content: generateHookFileCode(
-      `Update mutation hook for ${typeName}`,
+      table.description || `Update mutation hook for ${typeName}`,
       statements,
     ),
   };
@@ -686,7 +686,7 @@ export function generateDeleteMutationHook(
     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',
@@ -821,7 +821,7 @@ export function generateDeleteMutationHook(
   return {
     fileName: getDeleteMutationFileName(table),
     content: generateHookFileCode(
-      `Delete mutation hook for ${typeName}`,
+      table.description || `Delete mutation hook for ${typeName}`,
       statements,
     ),
   };

graphql/codegen/src/core/codegen/orm/custom-ops-generator.ts

@@ -7,15 +7,15 @@
 import * as t from '@babel/types';
 
 import type { CleanArgument, CleanOperation } from '../../../types/schema';
-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';
 
 export interface GeneratedCustomOpsFile {
   fileName: string;
@@ -109,6 +109,7 @@ function createImportDeclaration(
 
 function createVariablesInterface(
   op: CleanOperation,
+  comments: boolean = true,
 ): t.ExportNamedDeclaration | null {
   if (op.args.length === 0) return null;
 
@@ -120,6 +121,10 @@ function createVariablesInterface(
       t.tsTypeAnnotation(parseTypeAnnotation(typeRefToTsType(arg.type))),
     );
     prop.optional = optional;
+    const argDescription = stripSmartComments(arg.description, comments);
+    if (argDescription) {
+      addJSDocComment(prop, argDescription.split('\n'));
+    }
     return prop;
   });
 
@@ -129,7 +134,12 @@ function createVariablesInterface(
     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: string): t.TSType {
@@ -400,6 +410,7 @@ function buildOperationMethod(
  */
 export function generateCustomQueryOpsFile(
   operations: CleanOperation[],
+  comments: boolean = true,
 ): GeneratedCustomOpsFile {
   const statements: t.Statement[] = [];
 
@@ -444,7 +455,7 @@ export function generateCustomQueryOpsFile(
 
   // Generate variable interfaces
   for (const op of operations) {
-    const varInterface = createVariablesInterface(op);
+    const varInterface = createVariablesInterface(op, comments);
     if (varInterface) statements.push(varInterface);
   }
 
@@ -482,6 +493,7 @@ export function generateCustomQueryOpsFile(
  */
 export function generateCustomMutationOpsFile(
   operations: CleanOperation[],
+  comments: boolean = true,
 ): GeneratedCustomOpsFile {
   const statements: t.Statement[] = [];
 
@@ -526,7 +538,7 @@ export function generateCustomMutationOpsFile(
 
   // Generate variable interfaces
   for (const op of operations) {
-    const varInterface = createVariablesInterface(op);
+    const varInterface = createVariablesInterface(op, comments);
     if (varInterface) statements.push(varInterface);
   }
 

graphql/codegen/src/core/codegen/orm/docs-generator.ts

@@ -320,7 +320,7 @@ export function getOrmMcpTools(
 
     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: {
@@ -338,7 +338,7 @@ export function getOrmMcpTools(
 
     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: {
@@ -360,7 +360,7 @@ export function getOrmMcpTools(
     }
     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,
@@ -382,7 +382,7 @@ export function getOrmMcpTools(
     }
     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,
@@ -392,7 +392,7 @@ export function getOrmMcpTools(
 
     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: {
@@ -461,7 +461,7 @@ export function generateOrmSkills(
       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()`,

graphql/codegen/src/core/codegen/orm/index.ts

@@ -65,6 +65,7 @@ export interface GenerateOrmResult {
  */
 export function generateOrm(options: GenerateOrmOptions): GenerateOrmResult {
   const { tables, customOperations, sharedTypesPath } = options;
+  const commentsEnabled = options.config.codegen?.comments !== false;
   const files: GeneratedFile[] = [];
 
   // Use shared types when a sharedTypesPath is provided (unified output mode)
@@ -138,6 +139,7 @@ export function generateOrm(options: GenerateOrmOptions): GenerateOrmResult {
       usedInputTypes,
       tables,
       usedPayloadTypes,
+      commentsEnabled,
     );
     files.push({
       path: inputTypesFile.fileName,
@@ -147,13 +149,14 @@ export function generateOrm(options: GenerateOrmOptions): GenerateOrmResult {
 
   // 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,
+      commentsEnabled,
     );
     files.push({
       path: mutationOpsFile.fileName,