Skip to content

Commit d2a1df2

Browse files
pyramationpyramation
committed
feat: thread table descriptions into hook and ORM function JSDoc
Use table.description (from COMMENT ON TABLE) when available, fall back to generic text otherwise. Applied consistently across: - queries.ts: list/single query hooks, fetch functions, prefetch functions - mutations.ts: create/update/delete mutation hooks - hooks-docs-generator.ts: README, AGENTS.md, MCP tools, skills - orm/docs-generator.ts: MCP tools, skills Regenerated both SDK and React packages with updated output.
1 parent aabe85e commit d2a1df2

151 files changed

Lines changed: 436 additions & 434 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -66,22 +66,22 @@ export function generateHooksReadme(
6666
for (const table of tables) {
6767
const { singularName, pluralName } = getTableNames(table);
6868
lines.push(
69-
`| \`${getListQueryHookName(table)}\` | Query | List all ${pluralName} |`,
69+
`| \`${getListQueryHookName(table)}\` | Query | ${table.description || `List all ${pluralName}`} |`,
7070
);
7171
if (hasValidPrimaryKey(table)) {
7272
lines.push(
73-
`| \`${getSingleQueryHookName(table)}\` | Query | Get one ${singularName} |`,
73+
`| \`${getSingleQueryHookName(table)}\` | Query | ${table.description || `Get one ${singularName}`} |`,
7474
);
7575
}
7676
lines.push(
77-
`| \`${getCreateMutationHookName(table)}\` | Mutation | Create a ${singularName} |`,
77+
`| \`${getCreateMutationHookName(table)}\` | Mutation | ${table.description || `Create a ${singularName}`} |`,
7878
);
7979
if (hasValidPrimaryKey(table)) {
8080
lines.push(
81-
`| \`${getUpdateMutationHookName(table)}\` | Mutation | Update a ${singularName} |`,
81+
`| \`${getUpdateMutationHookName(table)}\` | Mutation | ${table.description || `Update a ${singularName}`} |`,
8282
);
8383
lines.push(
84-
`| \`${getDeleteMutationHookName(table)}\` | Mutation | Delete a ${singularName} |`,
84+
`| \`${getDeleteMutationHookName(table)}\` | Mutation | ${table.description || `Delete a ${singularName}`} |`,
8585
);
8686
}
8787
}
@@ -220,7 +220,7 @@ export function generateHooksAgentsDocs(
220220

221221
lines.push(`### HOOK: ${getListQueryHookName(table)}`);
222222
lines.push('');
223-
lines.push(`List all ${pluralName}.`);
223+
lines.push(`${table.description || `List all ${pluralName}`}.`);
224224
lines.push('');
225225
lines.push('```');
226226
lines.push(`TYPE: query`);
@@ -244,7 +244,7 @@ export function generateHooksAgentsDocs(
244244
if (hasValidPrimaryKey(table)) {
245245
lines.push(`### HOOK: ${getSingleQueryHookName(table)}`);
246246
lines.push('');
247-
lines.push(`Get a single ${singularName} by ${pk.name}.`);
247+
lines.push(`${table.description || `Get a single ${singularName} by ${pk.name}`}.`);
248248
lines.push('');
249249
lines.push('```');
250250
lines.push(`TYPE: query`);
@@ -269,7 +269,7 @@ export function generateHooksAgentsDocs(
269269

270270
lines.push(`### HOOK: ${getCreateMutationHookName(table)}`);
271271
lines.push('');
272-
lines.push(`Create a new ${singularName}.`);
272+
lines.push(`${table.description || `Create a new ${singularName}`}.`);
273273
lines.push('');
274274
lines.push('```');
275275
lines.push('TYPE: mutation');
@@ -284,7 +284,7 @@ export function generateHooksAgentsDocs(
284284
if (hasValidPrimaryKey(table)) {
285285
lines.push(`### HOOK: ${getUpdateMutationHookName(table)}`);
286286
lines.push('');
287-
lines.push(`Update an existing ${singularName}.`);
287+
lines.push(`${table.description || `Update an existing ${singularName}`}.`);
288288
lines.push('');
289289
lines.push('```');
290290
lines.push('TYPE: mutation');
@@ -298,7 +298,7 @@ export function generateHooksAgentsDocs(
298298

299299
lines.push(`### HOOK: ${getDeleteMutationHookName(table)}`);
300300
lines.push('');
301-
lines.push(`Delete a ${singularName}.`);
301+
lines.push(`${table.description || `Delete a ${singularName}`}.`);
302302
lines.push('');
303303
lines.push('```');
304304
lines.push('TYPE: mutation');
@@ -374,7 +374,7 @@ export function getHooksMcpTools(
374374

375375
tools.push({
376376
name: `hooks_${lcFirst(pluralName)}_query`,
377-
description: `React Query hook to list all ${pluralName}`,
377+
description: table.description || `React Query hook to list all ${pluralName}`,
378378
inputSchema: {
379379
type: 'object',
380380
properties: {
@@ -389,7 +389,7 @@ export function getHooksMcpTools(
389389
if (hasValidPrimaryKey(table)) {
390390
tools.push({
391391
name: `hooks_${lcFirst(singularName)}_query`,
392-
description: `React Query hook to get a single ${singularName} by ${pk.name}`,
392+
description: table.description || `React Query hook to get a single ${singularName} by ${pk.name}`,
393393
inputSchema: {
394394
type: 'object',
395395
properties: {
@@ -405,7 +405,7 @@ export function getHooksMcpTools(
405405

406406
tools.push({
407407
name: `hooks_create_${lcFirst(singularName)}_mutation`,
408-
description: `React Query mutation hook to create a ${singularName}`,
408+
description: table.description || `React Query mutation hook to create a ${singularName}`,
409409
inputSchema: {
410410
type: 'object',
411411
properties: Object.fromEntries(
@@ -431,7 +431,7 @@ export function getHooksMcpTools(
431431
if (hasValidPrimaryKey(table)) {
432432
tools.push({
433433
name: `hooks_update_${lcFirst(singularName)}_mutation`,
434-
description: `React Query mutation hook to update a ${singularName}`,
434+
description: table.description || `React Query mutation hook to update a ${singularName}`,
435435
inputSchema: {
436436
type: 'object',
437437
properties: {
@@ -446,7 +446,7 @@ export function getHooksMcpTools(
446446

447447
tools.push({
448448
name: `hooks_delete_${lcFirst(singularName)}_mutation`,
449-
description: `React Query mutation hook to delete a ${singularName}`,
449+
description: table.description || `React Query mutation hook to delete a ${singularName}`,
450450
inputSchema: {
451451
type: 'object',
452452
properties: {
@@ -511,7 +511,7 @@ export function generateHooksSkills(
511511
fileName: `skills/${lcFirst(singularName)}.md`,
512512
content: buildSkillFile({
513513
name: `hooks-${lcFirst(singularName)}`,
514-
description: `React Query hooks for ${table.name} data operations`,
514+
description: table.description || `React Query hooks for ${table.name} data operations`,
515515
language: 'typescript',
516516
usage: [
517517
`${getListQueryHookName(table)}({ selection: { fields: { ${selectFields} } } })`,

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,7 @@ export function generateCreateMutationHook(
202202
useMutationResultType(resultType(sRef()), createVarType),
203203
);
204204
addJSDocComment(o1, [
205-
`Mutation hook for creating a ${typeName}`,
205+
table.description || `Mutation hook for creating a ${typeName}`,
206206
'',
207207
'@example',
208208
'```tsx',
@@ -314,7 +314,7 @@ export function generateCreateMutationHook(
314314
return {
315315
fileName: getCreateMutationFileName(table),
316316
content: generateHookFileCode(
317-
`Create mutation hook for ${typeName}`,
317+
table.description || `Create mutation hook for ${typeName}`,
318318
statements,
319319
),
320320
};
@@ -433,7 +433,7 @@ export function generateUpdateMutationHook(
433433
useMutationResultType(resultType(sRef()), updateVarType),
434434
);
435435
addJSDocComment(o1, [
436-
`Mutation hook for updating a ${typeName}`,
436+
table.description || `Mutation hook for updating a ${typeName}`,
437437
'',
438438
'@example',
439439
'```tsx',
@@ -574,7 +574,7 @@ export function generateUpdateMutationHook(
574574
return {
575575
fileName: getUpdateMutationFileName(table),
576576
content: generateHookFileCode(
577-
`Update mutation hook for ${typeName}`,
577+
table.description || `Update mutation hook for ${typeName}`,
578578
statements,
579579
),
580580
};
@@ -686,7 +686,7 @@ export function generateDeleteMutationHook(
686686
useMutationResultType(resultType(sRef()), deleteVarType),
687687
);
688688
addJSDocComment(o1, [
689-
`Mutation hook for deleting a ${typeName} with typed selection`,
689+
table.description || `Mutation hook for deleting a ${typeName} with typed selection`,
690690
'',
691691
'@example',
692692
'```tsx',
@@ -821,7 +821,7 @@ export function generateDeleteMutationHook(
821821
return {
822822
fileName: getDeleteMutationFileName(table),
823823
content: generateHookFileCode(
824-
`Delete mutation hook for ${typeName}`,
824+
table.description || `Delete mutation hook for ${typeName}`,
825825
statements,
826826
),
827827
};

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -320,7 +320,7 @@ export function getOrmMcpTools(
320320

321321
tools.push({
322322
name: `orm_${lcFirst(singularName)}_findMany`,
323-
description: `List all ${table.name} records via ORM`,
323+
description: table.description || `List all ${table.name} records via ORM`,
324324
inputSchema: {
325325
type: 'object',
326326
properties: {
@@ -338,7 +338,7 @@ export function getOrmMcpTools(
338338

339339
tools.push({
340340
name: `orm_${lcFirst(singularName)}_findOne`,
341-
description: `Get a single ${table.name} record by ${pk.name}`,
341+
description: table.description || `Get a single ${table.name} record by ${pk.name}`,
342342
inputSchema: {
343343
type: 'object',
344344
properties: {
@@ -360,7 +360,7 @@ export function getOrmMcpTools(
360360
}
361361
tools.push({
362362
name: `orm_${lcFirst(singularName)}_create`,
363-
description: `Create a new ${table.name} record`,
363+
description: table.description || `Create a new ${table.name} record`,
364364
inputSchema: {
365365
type: 'object',
366366
properties: createProps,
@@ -382,7 +382,7 @@ export function getOrmMcpTools(
382382
}
383383
tools.push({
384384
name: `orm_${lcFirst(singularName)}_update`,
385-
description: `Update an existing ${table.name} record`,
385+
description: table.description || `Update an existing ${table.name} record`,
386386
inputSchema: {
387387
type: 'object',
388388
properties: updateProps,
@@ -392,7 +392,7 @@ export function getOrmMcpTools(
392392

393393
tools.push({
394394
name: `orm_${lcFirst(singularName)}_delete`,
395-
description: `Delete a ${table.name} record by ${pk.name}`,
395+
description: table.description || `Delete a ${table.name} record by ${pk.name}`,
396396
inputSchema: {
397397
type: 'object',
398398
properties: {
@@ -461,7 +461,7 @@ export function generateOrmSkills(
461461
fileName: `skills/${lcFirst(singularName)}.md`,
462462
content: buildSkillFile({
463463
name: `orm-${lcFirst(singularName)}`,
464-
description: `ORM operations for ${table.name} records`,
464+
description: table.description || `ORM operations for ${table.name} records`,
465465
language: 'typescript',
466466
usage: [
467467
`db.${lcFirst(singularName)}.findMany({ select: { id: true } }).execute()`,

‎graphql/codegen/src/core/codegen/queries.ts‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -237,8 +237,9 @@ export function generateListQueryHook(
237237

238238
// Hook
239239
if (reactQueryEnabled) {
240+
const descLine = table.description || `Query hook for fetching ${typeName} list`;
240241
const docLines = [
241-
`Query hook for fetching ${typeName} list`,
242+
descLine,
242243
'',
243244
'@example',
244245
'```tsx',
@@ -379,7 +380,7 @@ export function generateListQueryHook(
379380
typeRef('Promise', [listResultTypeAST(sRef())]),
380381
);
381382
addJSDocComment(f1Decl, [
382-
`Fetch ${typeName} list without React hooks`,
383+
table.description || `Fetch ${typeName} list without React hooks`,
383384
'',
384385
'@example',
385386
'```ts',
@@ -462,7 +463,7 @@ export function generateListQueryHook(
462463
typeRef('Promise', [t.tsVoidKeyword()]),
463464
);
464465
addJSDocComment(p1Decl, [
465-
`Prefetch ${typeName} list for SSR or cache warming`,
466+
table.description || `Prefetch ${typeName} list for SSR or cache warming`,
466467
'',
467468
'@example',
468469
'```ts',
@@ -551,9 +552,9 @@ export function generateListQueryHook(
551552
);
552553
}
553554

554-
const headerText = reactQueryEnabled
555+
const headerText = table.description || (reactQueryEnabled
555556
? `List query hook for ${typeName}`
556-
: `List query functions for ${typeName}`;
557+
: `List query functions for ${typeName}`);
557558

558559
return {
559560
fileName: getListQueryFileName(table),
@@ -719,8 +720,9 @@ export function generateSingleQueryHook(
719720

720721
// Hook
721722
if (reactQueryEnabled) {
723+
const singleDescLine = table.description || `Query hook for fetching a single ${typeName}`;
722724
const docLines = [
723-
`Query hook for fetching a single ${typeName}`,
725+
singleDescLine,
724726
'',
725727
'@example',
726728
'```tsx',
@@ -849,7 +851,7 @@ export function generateSingleQueryHook(
849851
typeRef('Promise', [singleResultTypeAST(sRef())]),
850852
);
851853
addJSDocComment(f1Decl, [
852-
`Fetch a single ${typeName} without React hooks`,
854+
table.description || `Fetch a single ${typeName} without React hooks`,
853855
'',
854856
'@example',
855857
'```ts',
@@ -923,7 +925,7 @@ export function generateSingleQueryHook(
923925
typeRef('Promise', [t.tsVoidKeyword()]),
924926
);
925927
addJSDocComment(p1Decl, [
926-
`Prefetch a single ${typeName} for SSR or cache warming`,
928+
table.description || `Prefetch a single ${typeName} for SSR or cache warming`,
927929
'',
928930
'@example',
929931
'```ts',
@@ -1010,9 +1012,9 @@ export function generateSingleQueryHook(
10101012
);
10111013
}
10121014

1013-
const headerText = reactQueryEnabled
1015+
const headerText = table.description || (reactQueryEnabled
10141016
? `Single item query hook for ${typeName}`
1015-
: `Single item query functions for ${typeName}`;
1017+
: `Single item query functions for ${typeName}`);
10161018

10171019
return {
10181020
fileName: getSingleQueryFileName(table),

‎sdk/constructive-react/src/admin/hooks/README.md‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -42,11 +42,11 @@ function App() {
4242
| `useCreateOrgPermissionMutation` | Mutation | Create a orgPermission |
4343
| `useUpdateOrgPermissionMutation` | Mutation | Update a orgPermission |
4444
| `useDeleteOrgPermissionMutation` | Mutation | Delete a orgPermission |
45-
| `useAppLevelRequirementsQuery` | Query | List all appLevelRequirements |
46-
| `useAppLevelRequirementQuery` | Query | Get one appLevelRequirement |
47-
| `useCreateAppLevelRequirementMutation` | Mutation | Create a appLevelRequirement |
48-
| `useUpdateAppLevelRequirementMutation` | Mutation | Update a appLevelRequirement |
49-
| `useDeleteAppLevelRequirementMutation` | Mutation | Delete a appLevelRequirement |
45+
| `useAppLevelRequirementsQuery` | Query | Requirements to achieve a level |
46+
| `useAppLevelRequirementQuery` | Query | Requirements to achieve a level |
47+
| `useCreateAppLevelRequirementMutation` | Mutation | Requirements to achieve a level |
48+
| `useUpdateAppLevelRequirementMutation` | Mutation | Requirements to achieve a level |
49+
| `useDeleteAppLevelRequirementMutation` | Mutation | Requirements to achieve a level |
5050
| `useOrgMembersQuery` | Query | List all orgMembers |
5151
| `useOrgMemberQuery` | Query | Get one orgMember |
5252
| `useCreateOrgMemberMutation` | Mutation | Create a orgMember |
@@ -102,16 +102,16 @@ function App() {
102102
| `useCreateAppLimitMutation` | Mutation | Create a appLimit |
103103
| `useUpdateAppLimitMutation` | Mutation | Update a appLimit |
104104
| `useDeleteAppLimitMutation` | Mutation | Delete a appLimit |
105-
| `useAppAchievementsQuery` | Query | List all appAchievements |
106-
| `useAppAchievementQuery` | Query | Get one appAchievement |
107-
| `useCreateAppAchievementMutation` | Mutation | Create a appAchievement |
108-
| `useUpdateAppAchievementMutation` | Mutation | Update a appAchievement |
109-
| `useDeleteAppAchievementMutation` | Mutation | Delete a appAchievement |
110-
| `useAppStepsQuery` | Query | List all appSteps |
111-
| `useAppStepQuery` | Query | Get one appStep |
112-
| `useCreateAppStepMutation` | Mutation | Create a appStep |
113-
| `useUpdateAppStepMutation` | Mutation | Update a appStep |
114-
| `useDeleteAppStepMutation` | Mutation | Delete a appStep |
105+
| `useAppAchievementsQuery` | Query | This table represents the users progress for particular level requirements, tallying the total count. This table is updated via triggers and should not be updated maually. |
106+
| `useAppAchievementQuery` | Query | This table represents the users progress for particular level requirements, tallying the total count. This table is updated via triggers and should not be updated maually. |
107+
| `useCreateAppAchievementMutation` | Mutation | This table represents the users progress for particular level requirements, tallying the total count. This table is updated via triggers and should not be updated maually. |
108+
| `useUpdateAppAchievementMutation` | Mutation | This table represents the users progress for particular level requirements, tallying the total count. This table is updated via triggers and should not be updated maually. |
109+
| `useDeleteAppAchievementMutation` | Mutation | This table represents the users progress for particular level requirements, tallying the total count. This table is updated via triggers and should not be updated maually. |
110+
| `useAppStepsQuery` | Query | The user achieving a requirement for a level. Log table that has every single step ever taken. |
111+
| `useAppStepQuery` | Query | The user achieving a requirement for a level. Log table that has every single step ever taken. |
112+
| `useCreateAppStepMutation` | Mutation | The user achieving a requirement for a level. Log table that has every single step ever taken. |
113+
| `useUpdateAppStepMutation` | Mutation | The user achieving a requirement for a level. Log table that has every single step ever taken. |
114+
| `useDeleteAppStepMutation` | Mutation | The user achieving a requirement for a level. Log table that has every single step ever taken. |
115115
| `useClaimedInvitesQuery` | Query | List all claimedInvites |
116116
| `useClaimedInviteQuery` | Query | Get one claimedInvite |
117117
| `useCreateClaimedInviteMutation` | Mutation | Create a claimedInvite |
@@ -147,11 +147,11 @@ function App() {
147147
| `useCreateOrgMembershipDefaultMutation` | Mutation | Create a orgMembershipDefault |
148148
| `useUpdateOrgMembershipDefaultMutation` | Mutation | Update a orgMembershipDefault |
149149
| `useDeleteOrgMembershipDefaultMutation` | Mutation | Delete a orgMembershipDefault |
150-
| `useAppLevelsQuery` | Query | List all appLevels |
151-
| `useAppLevelQuery` | Query | Get one appLevel |
152-
| `useCreateAppLevelMutation` | Mutation | Create a appLevel |
153-
| `useUpdateAppLevelMutation` | Mutation | Update a appLevel |
154-
| `useDeleteAppLevelMutation` | Mutation | Delete a appLevel |
150+
| `useAppLevelsQuery` | Query | Levels for achievement |
151+
| `useAppLevelQuery` | Query | Levels for achievement |
152+
| `useCreateAppLevelMutation` | Mutation | Levels for achievement |
153+
| `useUpdateAppLevelMutation` | Mutation | Levels for achievement |
154+
| `useDeleteAppLevelMutation` | Mutation | Levels for achievement |
155155
| `useInvitesQuery` | Query | List all invites |
156156
| `useInviteQuery` | Query | Get one invite |
157157
| `useCreateInviteMutation` | Mutation | Create a invite |

‎sdk/constructive-react/src/admin/hooks/mutations/useCreateAppAchievementMutation.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
* Create mutation hook for AppAchievement
2+
* This table represents the users progress for particular level requirements, tallying the total count. This table is updated via triggers and should not be updated maually.
33
* @generated by @constructive-io/graphql-codegen
44
* DO NOT EDIT - changes will be overwritten
55
*/
@@ -23,7 +23,7 @@ export type {
2323
CreateAppAchievementInput,
2424
} from '../../orm/input-types';
2525
/**
26-
* Mutation hook for creating a AppAchievement
26+
* This table represents the users progress for particular level requirements, tallying the total count. This table is updated via triggers and should not be updated maually.
2727
*
2828
* @example
2929
* ```tsx

0 commit comments

Comments
 (0)