Improve smart tags for polymorphic types

[tsnobip]

Description

This PR brings a few fixes and features to improve the usage of polymorphic tables:

• fix @returnType for functions returning setof (for lists and connections)
• support @returnType for foreign key constraints
• add @foreignReturnType for the backward relation of a foreign key constraint
• add @applyToType for computed columns, so a computed column defined on a polymorphic PostgreSQL table can be exposed only on a specific concrete GraphQL type.

Performance impact

should be limited given the limited changes.

Security impact

same

Checklist

• My code matches the project's code style and yarn lint:fix passes.
• I've added tests for the new feature, and yarn test passes.
• I have detailed the new feature in the relevant documentation.
• I have added this feature to 'Pending' in the RELEASE_NOTES.md file (if one exists).
• If this is a breaking change I've explained why.

[changeset-bot]

🦋 Changeset detected

Latest commit: ba63844

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
graphile-build-pg	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[tsnobip]

@codex review

[Copilot]

Pull request overview

This PR improves PostGraphile’s smart-tag handling around polymorphic PostgreSQL tables by expanding @returnType support (including setof functions and foreign key relations), introducing @foreignReturnType for backward relation typing, and adding @applyToType to scope computed columns to specific concrete GraphQL types.

Changes:

• Extend relation generation to respect @returnType (forward) and @foreignReturnType (backward) when determining relation field and connection types.
• Add @applyToType for computed columns and update connection naming/description logic to reflect smart-tag-selected GraphQL types (fixing Int4→Int, Int8→BigInt, etc. in schema docs/descriptions).
• Add/update polymorphic test fixtures, queries, and schema snapshots to validate the new tag behaviors.

Reviewed changes

Copilot reviewed 62 out of 62 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
postgraphile/website/postgraphile/smart-tags.md	Documents @returnType on constraints plus new @foreignReturnType and @applyToType tags with examples
graphile-build/graphile-build-pg/src/plugins/PgRelationsPlugin.ts	Uses returnType/foreignReturnType tags to choose relation GraphQL type/connection type names
graphile-build/graphile-build-pg/src/plugins/PgCustomTypeFieldPlugin.ts	Adds applyToType filtering for computed fields; aligns connection type naming/field descriptions with smart-tag-selected named types
graphile-build/graphile-build-pg/src/index.ts	Extends smart-tag TypeScript typings for applyToType, returnType, and foreignReturnType
postgraphile/postgraphile/tests/kitchen-sink-schema.sql	Adds polymorphic test functions/table/constraint comments exercising the new tags
postgraphile/postgraphile/tests/kitchen-sink-data.sql	Seeds data for the new polymorphic foreign-key return-type test table
postgraphile/postgraphile/tests/queries/polymorphic/return-type-foreign-key.test.graphql	New test asserting foreign key relation typing via @returnType/@foreignReturnType
postgraphile/postgraphile/tests/queries/polymorphic/return-type-foreign-key.sql	Snapshot SQL for return-type-foreign-key test
postgraphile/postgraphile/tests/queries/polymorphic/return-type-foreign-key.mermaid	Snapshot plan diagram for return-type-foreign-key test
postgraphile/postgraphile/tests/queries/polymorphic/return-type-foreign-key.json5	Snapshot result for return-type-foreign-key test
postgraphile/postgraphile/tests/queries/polymorphic/return-type-computed-column-setof.test.graphql	New test asserting @returnType affects computed-column setof list/connection typing
postgraphile/postgraphile/tests/queries/polymorphic/return-type-computed-column-setof.sql	Snapshot SQL for return-type-computed-column-setof test
postgraphile/postgraphile/tests/queries/polymorphic/return-type-computed-column-setof.mermaid	Snapshot plan diagram for return-type-computed-column-setof test
postgraphile/postgraphile/tests/queries/polymorphic/return-type-computed-column-setof.json5	Snapshot result for return-type-computed-column-setof test
postgraphile/postgraphile/tests/queries/polymorphic/apply-to-type-computed-column.test.graphql	New test asserting computed columns are only added to specified concrete types via @applyToType
postgraphile/postgraphile/tests/queries/polymorphic/apply-to-type-computed-column.sql	Snapshot SQL for apply-to-type-computed-column test
postgraphile/postgraphile/tests/queries/polymorphic/apply-to-type-computed-column.mermaid	Snapshot plan diagram for apply-to-type-computed-column test
postgraphile/postgraphile/tests/queries/polymorphic/apply-to-type-computed-column.json5	Snapshot result for apply-to-type-computed-column test
postgraphile/postgraphile/tests/schema/v5/skipNodePlugin.polymorphic.1.graphql	Updates v5 polymorphic schema snapshot for new types/fields impacted by tags
postgraphile/postgraphile/tests/schema/v5/skipNodePlugin.polymorphic.1.export.mjs	Updates v5 export snapshot reflecting new resources/relations and computed fields
postgraphile/postgraphile/tests/schema/v5/skipNodePlugin.1.graphql	Updates v5 schema snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v5/skipNodePlugin.1.export.mjs	Updates v5 export snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/skipNodePlugin.polymorphic.1.graphql	Updates v4 polymorphic schema snapshot for new types/fields impacted by tags
postgraphile/postgraphile/tests/schema/v4/skipNodePlugin.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/skipNodePlugin.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/simplePrint.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/simplePrint.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/simple-collections.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int)
postgraphile/postgraphile/tests/schema/v4/simple-collections.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int)
postgraphile/postgraphile/tests/schema/v4/relay1.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int)
postgraphile/postgraphile/tests/schema/v4/relay1.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int)
postgraphile/postgraphile/tests/schema/v4/rbac.ignore.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/rbac.ignore.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/polymorphic.1.graphql	Updates v4 polymorphic schema snapshot for new types/fields impacted by tags
postgraphile/postgraphile/tests/schema/v4/polymorphic-auto-add-types.1.graphql	Updates v4 polymorphic schema snapshot for auto-add-types scenario
postgraphile/postgraphile/tests/schema/v4/polymorphic-auto-add-types.1.export.mjs	Updates v4 export snapshot reflecting new polymorphic resources/relations and computed fields
postgraphile/postgraphile/tests/schema/v4/pgStrictFunctions.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/pgStrictFunctions.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/noDefaultMutations.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int)
postgraphile/postgraphile/tests/schema/v4/noDefaultMutations.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int)
postgraphile/postgraphile/tests/schema/v4/inflect-core.1.graphql	Updates v4 schema snapshot descriptions to use inflected/named GraphQL type (I, Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/inflect-core.1.export.mjs	Updates v4 export snapshot descriptions to use inflected/named GraphQL type (I, Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/inflect-builtin-lowercase.1.graphql	Updates v4 schema snapshot descriptions to use lowercase builtin type names consistently
postgraphile/postgraphile/tests/schema/v4/inflect-builtin-lowercase.1.export.mjs	Updates v4 export snapshot descriptions to use lowercase builtin type names consistently
postgraphile/postgraphile/tests/schema/v4/indexes.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/indexes.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/function-clash.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/function-clash.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/function-clash-with-tags-file-workaround.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/function-clash-with-tags-file-workaround.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/foreignKey-smart-tag-good.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int)
postgraphile/postgraphile/tests/schema/v4/foreignKey-smart-tag-good.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int)
postgraphile/postgraphile/tests/schema/v4/foreignKey-smart-tag-autofix.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int)
postgraphile/postgraphile/tests/schema/v4/foreignKey-smart-tag-autofix.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int)
postgraphile/postgraphile/tests/schema/v4/defaultOptions.subscriptions.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/defaultOptions.subscriptions.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/defaultOptions.1.graphql	Updates v4 schema snapshot descriptions to use GraphQL type names (Int, BigInt)
postgraphile/postgraphile/tests/schema/v4/defaultOptions.1.export.mjs	Updates v4 export snapshot descriptions to use GraphQL type names (Int, BigInt)
.changeset/strict-apes-bow.md	Changeset documenting the feature additions/fixes as a minor bump for graphile-build-pg

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[benjie]

Sorry I didn't get around to reviewing this, polymorphism changes require careful thought and I've not managed to find enough time to dedicate to this yet.