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

[pyramation]

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

Summary

Ensures PostgreSQL COMMENT ON statements flow through GraphQL introspection and are rendered as JSDoc comments in all generated TypeScript code. Also adds a safety-net utility to strip PostGraphile smart comments (lines starting with @) from descriptions, and filters out generic PostGraphile boilerplate descriptions that add noise rather than value.

JSDoc comments are configurable via codegen.comments (default: true). When set to false, all JSDoc comment generation is suppressed.

Table-level descriptions are threaded everywhere. When a table has a COMMENT ON TABLE description, it replaces the generic text (e.g., "List query hook for X") in hook JSDoc, ORM MCP tools, skills docs, README, and AGENTS.md. When no table description exists, the generic fallback is used. This applies to all generators: queries, mutations, hooks docs, and ORM docs.

Codegen changes (graphql/codegen/):

• types/config.ts: Added comments?: boolean option to codegen config section (default: true)
• types/schema.ts: Added optional description field to CleanTable and CleanField interfaces
• core/codegen/utils.ts: New stripSmartComments() utility with enabled parameter — removes @-prefixed lines, filters PostGraphile boilerplate, and respects the comments config flag
• core/introspect/infer-tables.ts: Populates description on tables and fields from introspection data, gated by comments option via InferTablesOptions
• core/pipeline/index.ts: Reads config.codegen?.comments and passes it through to inferTablesFromIntrospection
• core/codegen/orm/index.ts: ORM orchestrator reads comments from config and passes to all generators
• core/codegen/shared/index.ts: Shared orchestrator passes comments through to generateSchemaTypesFile
• core/codegen/orm/input-types-generator.ts: Emits JSDoc on entity types, entity fields, enum types, custom input types/fields, and payload types/fields — all gated by comments param
• core/codegen/schema-types-generator.ts: Emits JSDoc on enums, input objects, unions, and payload object types — all gated by comments param via GenerateSchemaTypesOptions
• core/codegen/orm/custom-ops-generator.ts: Emits JSDoc on operation variable interfaces and their argument properties — gated by comments param
• core/codegen/queries.ts: Uses table.description (with generic fallback) for list/single query hooks, fetch functions, and prefetch functions
• core/codegen/mutations.ts: Uses table.description (with generic fallback) for create/update/delete mutation hooks and file headers
• core/codegen/hooks-docs-generator.ts: Uses table.description (with generic fallback) in README tables, AGENTS.md hook descriptions, MCP tool descriptions, and skills files
• core/codegen/orm/docs-generator.ts: Uses table.description (with generic fallback) in MCP tool descriptions and skills files
• core/generate.ts: Added explicit GraphQLSDKConfigTarget type annotation to baseConfig in generateMulti

SDK regeneration (sdk/constructive-sdk/src/):

• Ran pnpm generate in sdk/constructive-sdk/ to regenerate the SDK using the updated codegen
• Meaningful JSDoc comments added across admin, auth, objects, and public schemas
• Skills docs now use table descriptions where available (e.g., store.md → "A store represents an isolated object repository within a database." instead of "ORM operations for Store records")

New @constructive-io/react package

Added sdk/constructive-react/ — a new package that generates React Query hooks (v5) + ORM client from the same schema files used by constructive-sdk. This package verifies that JSDoc comments propagate correctly through:

• React Query hook functions and their JSDoc (now using table descriptions)
• Operation variable interfaces
• README documentation (now using table descriptions in hook tables)
• Skills documentation (now using table descriptions)

Package structure:

• package.json — declares @tanstack/react-query v5, @0no-co/graphql.web, and workspace deps
• scripts/generate-react.ts — mirrors constructive-sdk's generation script with reactQuery: true and orm: true, now with explicit GraphQLSDKConfigTarget type annotation
• src/{admin,auth,objects,public}/ — generated targets with hooks/ and orm/ subdirectories
• src/index.ts — barrel exports all targets (uses public_ for the public schema to avoid reserved word)

Generated output includes:

• React Query hooks for all table CRUD operations and custom queries/mutations
• ORM client for direct GraphQL operations
• Skills documentation (.md files) for each operation
• README files with setup instructions and examples

PostGraphile boilerplate filtering

stripSmartComments() suppresses generic PostGraphile-generated descriptions using startsWith prefix matching. This handles curly apostrophe variants PostGraphile may produce. Filtered prefixes:

• "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"
• "The count of *all* \"`
• "A list of \"`
• "Our root query field"
• "Reads a single"
• "The root query type"
• "The root mutation type"

Updates since last revision

• Type safety improvement: Added explicit GraphQLSDKConfigTarget type annotations to baseConfig objects in generation scripts (generate-react.ts, generate-sdk.ts) and internal generate.ts to improve type safety and IDE support.

Review & Testing Checklist for Human

• Verify table descriptions appear correctly in generated code: Open the regenerated SDK and React package files in an IDE. Hover over hook functions (e.g., useStoresQuery, useCreateCommitMutation) and verify that table descriptions appear in JSDoc tooltips when available. Check that generic fallback text appears for tables without descriptions.
• Spot-check skills docs for table descriptions: Review files like sdk/constructive-sdk/src/public/orm/skills/store.md and verify they show meaningful table descriptions (e.g., "A store represents an isolated object repository within a database.") instead of generic text.
• Boilerplate filter may be too aggressive: The startsWith matching on short prefixes like "Reads a single", "A list of \", "The output of our"could suppress a legitimate custom PostgreSQLCOMMENT` that happens to begin with those phrases. Consider whether exact-match or longer prefixes would be safer.
• Inconsistent edge description filtering: Some PostGraphile edge descriptions use format "An edge for our \User`. May be used by Relay 1."(filtered) while others use"A `User` edge in the connection."` (NOT filtered). The latter format still appears in generated code (visible in the diff). Verify whether this is acceptable or if additional patterns need filtering.
• comments: false path is untested: The PR only verified that comments: true (default) produces the expected output. The comments: false path has not been tested end-to-end. Recommend testing with a config that sets codegen: { comments: false } to verify all JSDoc is suppressed.

Notes

• All pre-existing TypeScript errors (unrelated missing module declarations) remain; no new errors were introduced.
• No unit tests were added for stripSmartComments, boilerplate filtering, JSDoc output verification, table description threading, or the comments: false path.
• Local pnpm build passes. All 42 CI checks passed on all commits.
• The @constructive-io/react package adds ~1,000 generated files to the repo. This mirrors the pattern used by constructive-sdk.
• Table descriptions use JS falsy coalescing (table.description || generic), so empty string descriptions would also fall back to generic text.
• Some table descriptions contain typos from the original PostgreSQL comments (e.g., "maually" in appAchievement description) — these are not codegen bugs but reflect the source data.

Link to Devin run: https://app.devin.ai/sessions/a23198fb88394660869ebbbe14cc8f39
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.