@constructive-io/graphql-codegen 4.0.2 → 4.1.0

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

@@ -0,0 +1,462 @@
+import { buildSkillFile, formatArgType, getReadmeHeader, getReadmeFooter, gqlTypeToJsonSchemaType, } from './docs-utils';
+import { getTableNames, getScalarFields, getPrimaryKeyInfo, getListQueryHookName, getSingleQueryHookName, getCreateMutationHookName, getUpdateMutationHookName, getDeleteMutationHookName, hasValidPrimaryKey, ucFirst, lcFirst, fieldTypeToTs, } from './utils';
+function getCustomHookName(op) {
+    if (op.kind === 'query') {
+        return `use${ucFirst(op.name)}Query`;
+    }
+    return `use${ucFirst(op.name)}Mutation`;
+}
+export function generateHooksReadme(tables, customOperations) {
+    const lines = [];
+    lines.push(...getReadmeHeader('React Query Hooks'));
+    lines.push('## Setup');
+    lines.push('');
+    lines.push('```typescript');
+    lines.push("import { QueryClient, QueryClientProvider } from '@tanstack/react-query';");
+    lines.push("import { configure } from './hooks';");
+    lines.push('');
+    lines.push('configure({');
+    lines.push("  endpoint: 'https://api.example.com/graphql',");
+    lines.push("  headers: { Authorization: 'Bearer <token>' },");
+    lines.push('});');
+    lines.push('');
+    lines.push('const queryClient = new QueryClient();');
+    lines.push('');
+    lines.push('function App() {');
+    lines.push('  return (');
+    lines.push('    <QueryClientProvider client={queryClient}>');
+    lines.push('      <YourApp />');
+    lines.push('    </QueryClientProvider>');
+    lines.push('  );');
+    lines.push('}');
+    lines.push('```');
+    lines.push('');
+    lines.push('## Hooks');
+    lines.push('');
+    lines.push('| Hook | Type | Description |');
+    lines.push('|------|------|-------------|');
+    for (const table of tables) {
+        const { singularName, pluralName } = getTableNames(table);
+        lines.push(`| \`${getListQueryHookName(table)}\` | Query | List all ${pluralName} |`);
+        if (hasValidPrimaryKey(table)) {
+            lines.push(`| \`${getSingleQueryHookName(table)}\` | Query | Get one ${singularName} |`);
+        }
+        lines.push(`| \`${getCreateMutationHookName(table)}\` | Mutation | Create a ${singularName} |`);
+        if (hasValidPrimaryKey(table)) {
+            lines.push(`| \`${getUpdateMutationHookName(table)}\` | Mutation | Update a ${singularName} |`);
+            lines.push(`| \`${getDeleteMutationHookName(table)}\` | Mutation | Delete a ${singularName} |`);
+        }
+    }
+    for (const op of customOperations) {
+        lines.push(`| \`${getCustomHookName(op)}\` | ${ucFirst(op.kind)} | ${op.description || op.name} |`);
+    }
+    lines.push('');
+    if (tables.length > 0) {
+        lines.push('## Table Hooks');
+        lines.push('');
+        for (const table of tables) {
+            const { singularName, pluralName } = getTableNames(table);
+            const pk = getPrimaryKeyInfo(table)[0];
+            const scalarFields = getScalarFields(table);
+            lines.push(`### ${table.name}`);
+            lines.push('');
+            lines.push('```typescript');
+            lines.push(`// List all ${pluralName}`);
+            lines.push(`const { data, isLoading } = ${getListQueryHookName(table)}({`);
+            lines.push(`  selection: { fields: { ${scalarFields.map((f) => `${f.name}: true`).join(', ')} } },`);
+            lines.push('});');
+            lines.push('');
+            if (hasValidPrimaryKey(table)) {
+                lines.push(`// Get one ${singularName}`);
+                lines.push(`const { data: item } = ${getSingleQueryHookName(table)}({`);
+                lines.push(`  ${pk.name}: '<value>',`);
+                lines.push(`  selection: { fields: { ${scalarFields.map((f) => `${f.name}: true`).join(', ')} } },`);
+                lines.push('});');
+                lines.push('');
+            }
+            lines.push(`// Create a ${singularName}`);
+            lines.push(`const { mutate: create } = ${getCreateMutationHookName(table)}({`);
+            lines.push(`  selection: { fields: { ${pk.name}: true } },`);
+            lines.push('});');
+            lines.push(`create({ ${scalarFields.filter((f) => f.name !== pk.name && f.name !== 'nodeId' && f.name !== 'createdAt' && f.name !== 'updatedAt').map((f) => `${f.name}: '<value>'`).join(', ')} });`);
+            lines.push('```');
+            lines.push('');
+        }
+    }
+    if (customOperations.length > 0) {
+        lines.push('## Custom Operation Hooks');
+        lines.push('');
+        for (const op of customOperations) {
+            const hookName = getCustomHookName(op);
+            lines.push(`### \`${hookName}\``);
+            lines.push('');
+            lines.push(op.description || op.name);
+            lines.push('');
+            lines.push(`- **Type:** ${op.kind}`);
+            if (op.args.length > 0) {
+                lines.push('- **Arguments:**');
+                lines.push('');
+                lines.push('  | Argument | Type |');
+                lines.push('  |----------|------|');
+                for (const arg of op.args) {
+                    lines.push(`  | \`${arg.name}\` | ${formatArgType(arg)} |`);
+                }
+            }
+            else {
+                lines.push('- **Arguments:** none');
+            }
+            lines.push('');
+        }
+    }
+    lines.push(...getReadmeFooter());
+    return {
+        fileName: 'README.md',
+        content: lines.join('\n'),
+    };
+}
+export function generateHooksAgentsDocs(tables, customOperations) {
+    const lines = [];
+    lines.push('# React Query Hooks - Agent Reference');
+    lines.push('');
+    lines.push('> @generated by @constructive-io/graphql-codegen - DO NOT EDIT');
+    lines.push('> This document is structured for LLM/agent consumption.');
+    lines.push('');
+    lines.push('## OVERVIEW');
+    lines.push('');
+    lines.push('React Query hooks wrapping ORM operations for data fetching and mutations.');
+    lines.push('All query hooks return `UseQueryResult`. All mutation hooks return `UseMutationResult`.');
+    lines.push('');
+    lines.push('## SETUP');
+    lines.push('');
+    lines.push('```typescript');
+    lines.push("import { configure } from './hooks';");
+    lines.push("import { QueryClient, QueryClientProvider } from '@tanstack/react-query';");
+    lines.push('');
+    lines.push("configure({ endpoint: 'https://api.example.com/graphql' });");
+    lines.push('const queryClient = new QueryClient();');
+    lines.push('// Wrap app in <QueryClientProvider client={queryClient}>');
+    lines.push('```');
+    lines.push('');
+    lines.push('## HOOKS');
+    lines.push('');
+    for (const table of tables) {
+        const { singularName, pluralName } = getTableNames(table);
+        const pk = getPrimaryKeyInfo(table)[0];
+        const scalarFields = getScalarFields(table);
+        lines.push(`### HOOK: ${getListQueryHookName(table)}`);
+        lines.push('');
+        lines.push(`List all ${pluralName}.`);
+        lines.push('');
+        lines.push('```');
+        lines.push(`TYPE: query`);
+        lines.push(`USAGE: ${getListQueryHookName(table)}({ selection: { fields: { ... } } })`);
+        lines.push('');
+        lines.push('INPUT:');
+        lines.push('  selection: { fields: Record<string, boolean> } - Fields to select');
+        lines.push('');
+        lines.push('OUTPUT: UseQueryResult<Array<{');
+        for (const f of scalarFields) {
+            lines.push(`  ${f.name}: ${fieldTypeToTs(f.type)}`);
+        }
+        lines.push('}>>');
+        lines.push('```');
+        lines.push('');
+        if (hasValidPrimaryKey(table)) {
+            lines.push(`### HOOK: ${getSingleQueryHookName(table)}`);
+            lines.push('');
+            lines.push(`Get a single ${singularName} by ${pk.name}.`);
+            lines.push('');
+            lines.push('```');
+            lines.push(`TYPE: query`);
+            lines.push(`USAGE: ${getSingleQueryHookName(table)}({ ${pk.name}: '<value>', selection: { fields: { ... } } })`);
+            lines.push('');
+            lines.push('INPUT:');
+            lines.push(`  ${pk.name}: ${pk.tsType} (required)`);
+            lines.push('  selection: { fields: Record<string, boolean> } - Fields to select');
+            lines.push('');
+            lines.push('OUTPUT: UseQueryResult<{');
+            for (const f of scalarFields) {
+                lines.push(`  ${f.name}: ${fieldTypeToTs(f.type)}`);
+            }
+            lines.push('}>');
+            lines.push('```');
+            lines.push('');
+        }
+        lines.push(`### HOOK: ${getCreateMutationHookName(table)}`);
+        lines.push('');
+        lines.push(`Create a new ${singularName}.`);
+        lines.push('');
+        lines.push('```');
+        lines.push('TYPE: mutation');
+        lines.push(`USAGE: const { mutate } = ${getCreateMutationHookName(table)}({ selection: { fields: { ... } } })`);
+        lines.push('');
+        lines.push('OUTPUT: UseMutationResult');
+        lines.push('```');
+        lines.push('');
+        if (hasValidPrimaryKey(table)) {
+            lines.push(`### HOOK: ${getUpdateMutationHookName(table)}`);
+            lines.push('');
+            lines.push(`Update an existing ${singularName}.`);
+            lines.push('');
+            lines.push('```');
+            lines.push('TYPE: mutation');
+            lines.push(`USAGE: const { mutate } = ${getUpdateMutationHookName(table)}({ selection: { fields: { ... } } })`);
+            lines.push('');
+            lines.push('OUTPUT: UseMutationResult');
+            lines.push('```');
+            lines.push('');
+            lines.push(`### HOOK: ${getDeleteMutationHookName(table)}`);
+            lines.push('');
+            lines.push(`Delete a ${singularName}.`);
+            lines.push('');
+            lines.push('```');
+            lines.push('TYPE: mutation');
+            lines.push(`USAGE: const { mutate } = ${getDeleteMutationHookName(table)}({})`);
+            lines.push('');
+            lines.push('OUTPUT: UseMutationResult');
+            lines.push('```');
+            lines.push('');
+        }
+    }
+    if (customOperations.length > 0) {
+        lines.push('## CUSTOM OPERATION HOOKS');
+        lines.push('');
+        for (const op of customOperations) {
+            const hookName = getCustomHookName(op);
+            lines.push(`### HOOK: ${hookName}`);
+            lines.push('');
+            lines.push(op.description || op.name);
+            lines.push('');
+            lines.push('```');
+            lines.push(`TYPE: ${op.kind}`);
+            if (op.args.length > 0) {
+                if (op.kind === 'mutation') {
+                    lines.push(`USAGE: const { mutate } = ${hookName}()`);
+                    lines.push(`  mutate({ ${op.args.map((a) => `${a.name}: <value>`).join(', ')} })`);
+                }
+                else {
+                    lines.push(`USAGE: ${hookName}({ ${op.args.map((a) => `${a.name}: <value>`).join(', ')} })`);
+                }
+                lines.push('');
+                lines.push('INPUT:');
+                for (const arg of op.args) {
+                    lines.push(`  ${arg.name}: ${formatArgType(arg)}`);
+                }
+            }
+            else {
+                lines.push(`USAGE: ${hookName}()`);
+                lines.push('');
+                lines.push('INPUT: none');
+            }
+            lines.push('');
+            lines.push(`OUTPUT: ${op.kind === 'query' ? 'UseQueryResult' : 'UseMutationResult'}`);
+            lines.push('```');
+            lines.push('');
+        }
+    }
+    return {
+        fileName: 'AGENTS.md',
+        content: lines.join('\n'),
+    };
+}
+export function getHooksMcpTools(tables, customOperations) {
+    const tools = [];
+    for (const table of tables) {
+        const { singularName, pluralName } = getTableNames(table);
+        const pk = getPrimaryKeyInfo(table)[0];
+        const scalarFields = getScalarFields(table);
+        tools.push({
+            name: `hooks_${lcFirst(pluralName)}_query`,
+            description: `React Query hook to list all ${pluralName}`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    fields: {
+                        type: 'object',
+                        description: `Fields to select: { ${scalarFields.map((f) => f.name).join(', ')} }`,
+                    },
+                },
+            },
+        });
+        if (hasValidPrimaryKey(table)) {
+            tools.push({
+                name: `hooks_${lcFirst(singularName)}_query`,
+                description: `React Query hook to get a single ${singularName} by ${pk.name}`,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        [pk.name]: {
+                            type: gqlTypeToJsonSchemaType(pk.gqlType),
+                            description: `${table.name} ${pk.name}`,
+                        },
+                    },
+                    required: [pk.name],
+                },
+            });
+        }
+        tools.push({
+            name: `hooks_create_${lcFirst(singularName)}_mutation`,
+            description: `React Query mutation hook to create a ${singularName}`,
+            inputSchema: {
+                type: 'object',
+                properties: Object.fromEntries(scalarFields
+                    .filter((f) => f.name !== pk.name &&
+                    f.name !== 'nodeId' &&
+                    f.name !== 'createdAt' &&
+                    f.name !== 'updatedAt')
+                    .map((f) => [
+                    f.name,
+                    {
+                        type: gqlTypeToJsonSchemaType(f.type.gqlType),
+                        description: `${table.name} ${f.name}`,
+                    },
+                ])),
+            },
+        });
+        if (hasValidPrimaryKey(table)) {
+            tools.push({
+                name: `hooks_update_${lcFirst(singularName)}_mutation`,
+                description: `React Query mutation hook to update a ${singularName}`,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        [pk.name]: {
+                            type: gqlTypeToJsonSchemaType(pk.gqlType),
+                            description: `${table.name} ${pk.name}`,
+                        },
+                    },
+                    required: [pk.name],
+                },
+            });
+            tools.push({
+                name: `hooks_delete_${lcFirst(singularName)}_mutation`,
+                description: `React Query mutation hook to delete a ${singularName}`,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        [pk.name]: {
+                            type: gqlTypeToJsonSchemaType(pk.gqlType),
+                            description: `${table.name} ${pk.name}`,
+                        },
+                    },
+                    required: [pk.name],
+                },
+            });
+        }
+    }
+    for (const op of customOperations) {
+        const hookName = getCustomHookName(op);
+        const props = {};
+        const required = [];
+        for (const arg of op.args) {
+            const isRequired = arg.type.kind === 'NON_NULL';
+            const baseType = isRequired && arg.type.ofType ? arg.type.ofType : arg.type;
+            props[arg.name] = {
+                type: gqlTypeToJsonSchemaType(baseType.name ?? 'String'),
+                description: arg.description || arg.name,
+            };
+            if (isRequired) {
+                required.push(arg.name);
+            }
+        }
+        tools.push({
+            name: `hooks_${hookName}`,
+            description: op.description || `${ucFirst(op.kind)} hook for ${op.name}`,
+            inputSchema: {
+                type: 'object',
+                properties: props,
+                ...(required.length > 0 ? { required } : {}),
+            },
+        });
+    }
+    return tools;
+}
+export function generateHooksSkills(tables, customOperations) {
+    const files = [];
+    for (const table of tables) {
+        const { singularName, pluralName } = getTableNames(table);
+        const pk = getPrimaryKeyInfo(table)[0];
+        const scalarFields = getScalarFields(table);
+        const selectFields = scalarFields
+            .map((f) => `${f.name}: true`)
+            .join(', ');
+        files.push({
+            fileName: `skills/${lcFirst(singularName)}.md`,
+            content: buildSkillFile({
+                name: `hooks-${lcFirst(singularName)}`,
+                description: `React Query hooks for ${table.name} data operations`,
+                language: 'typescript',
+                usage: [
+                    `${getListQueryHookName(table)}({ selection: { fields: { ${selectFields} } } })`,
+                    ...(hasValidPrimaryKey(table)
+                        ? [
+                            `${getSingleQueryHookName(table)}({ ${pk.name}: '<value>', selection: { fields: { ${selectFields} } } })`,
+                        ]
+                        : []),
+                    `${getCreateMutationHookName(table)}({ selection: { fields: { ${pk.name}: true } } })`,
+                    ...(hasValidPrimaryKey(table)
+                        ? [
+                            `${getUpdateMutationHookName(table)}({ selection: { fields: { ${pk.name}: true } } })`,
+                            `${getDeleteMutationHookName(table)}({})`,
+                        ]
+                        : []),
+                ],
+                examples: [
+                    {
+                        description: `List all ${pluralName}`,
+                        code: [
+                            `const { data, isLoading } = ${getListQueryHookName(table)}({`,
+                            `  selection: { fields: { ${selectFields} } },`,
+                            '});',
+                        ],
+                    },
+                    {
+                        description: `Create a ${singularName}`,
+                        code: [
+                            `const { mutate } = ${getCreateMutationHookName(table)}({`,
+                            `  selection: { fields: { ${pk.name}: true } },`,
+                            '});',
+                            `mutate({ ${scalarFields.filter((f) => f.name !== pk.name && f.name !== 'nodeId' && f.name !== 'createdAt' && f.name !== 'updatedAt').map((f) => `${f.name}: '<value>'`).join(', ')} });`,
+                        ],
+                    },
+                ],
+            }),
+        });
+    }
+    for (const op of customOperations) {
+        const hookName = getCustomHookName(op);
+        const callArgs = op.args.length > 0
+            ? `{ ${op.args.map((a) => `${a.name}: '<value>'`).join(', ')} }`
+            : '';
+        files.push({
+            fileName: `skills/${op.name}.md`,
+            content: buildSkillFile({
+                name: `hooks-${op.name}`,
+                description: op.description ||
+                    `React Query ${op.kind} hook for ${op.name}`,
+                language: 'typescript',
+                usage: [
+                    op.kind === 'mutation'
+                        ? `const { mutate } = ${hookName}(); mutate(${callArgs});`
+                        : `${hookName}(${callArgs})`,
+                ],
+                examples: [
+                    {
+                        description: `Use ${hookName}`,
+                        code: op.kind === 'mutation'
+                            ? [
+                                `const { mutate, isLoading } = ${hookName}();`,
+                                ...(callArgs
+                                    ? [`mutate(${callArgs});`]
+                                    : ['mutate();']),
+                            ]
+                            : [
+                                `const { data, isLoading } = ${hookName}(${callArgs});`,
+                            ],
+                    },
+                ],
+            }),
+        });
+    }
+    return files;
+}

package/esm/core/codegen/orm/docs-generator.d.ts

@@ -0,0 +1,6 @@
+import type { CleanOperation, CleanTable } from '../../../types/schema';
+import type { GeneratedDocFile, McpTool } from '../docs-utils';
+export declare function generateOrmReadme(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile;
+export declare function generateOrmAgentsDocs(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile;
+export declare function getOrmMcpTools(tables: CleanTable[], customOperations: CleanOperation[]): McpTool[];
+export declare function generateOrmSkills(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile[];