feat: add graphile-pg-trgm-plugin for pg_trgm fuzzy text matching

[pyramation]

Summary

This PR adds graphile-pg-trgm-plugin, a new PostGraphile v5 plugin that provides pg_trgm trigram-based fuzzy text matching capabilities to the connection filter system. It's the 7th plugin type integrated into the ConstructivePreset, joining tsvector, BM25, pgvector, PostGIS, relation filters, and scalar filters.

New Package: graphile-pg-trgm-plugin

• similarTo / wordSimilarTo operators on StringFilter for fuzzy matching with configurable thresholds
• trgm<Column> filter fields directly on connection filter types (e.g., trgmName, trgmDescription)
• <column>Similarity computed fields returning match quality scores (0-1 range, null when no trgm filter active)
• SIMILARITY_<COLUMN>_ASC/DESC orderBy enum values for ranking by match quality
• connectionFilterTrgmRequireIndex option (default: false) — optionally restrict trgm operators to GIN-indexed columns only
• 14 dedicated tests covering operators, score fields, composability, and NULL semantics

Integration:

• Wired into ConstructivePreset via TrgmSearchPreset()
• Added pg_trgm extension + GIN trigram index to integration test seed SQL
• Updated mega query test to include trgmName filter as 7th plugin type — now exercises all 7 filter plugin types in a single GraphQL query

Plugin Architecture:

• Follows the same pattern as graphile-pg-textsearch-plugin (BM25)
• Uses Grafast meta system (setMeta/getMeta) to pass similarity score indices between filter apply and computed field plan phases
• Registers operators via addConnectionFilterOperator API from graphile-connection-filter
• Auto-discovers text columns and registers filter fields + computed fields dynamically

Updates since last revision

• Multi-signal orderBy added to mega query test — the mega query now uses orderBy: [BM25_BODY_SCORE_ASC, SIMILARITY_NAME_DESC] to demonstrate combining multiple scoring signals in a single query, with an assertion verifying BM25 ASC ordering.
• Comprehensive JSDoc documentation added to the mega query test (~80 lines) explaining all 7 plugin types, the 2-phase meta system for orderBy, and score field semantics.
• Documented an important ordering subtlety: ORDER BY priority in multi-signal queries follows the schema's internal field processing order (which filter apply runs first), not the orderBy array order. The array determines which signals are active and their direction (ASC/DESC), but the SQL clause sequence depends on which filter plugin's apply function executes first during schema evaluation. This is inherent to the 2-phase meta architecture and is thoroughly documented in the test comments.
• Schema snapshots updated in graphql/test and graphql/server-test — the trgm plugin adds similarTo/wordSimilarTo to every StringFilter, *Similarity computed fields to every type with text columns, and SIMILARITY_* orderBy enums.
• CI is 42/42 green.

---

Review & Testing Checklist for Human

⚠️ Dependency Chain: This PR is based on PR #807, which builds on #797 → #801 → #804 → #805 → #806. The cumulative diff includes all those changes, but the core new work in this PR is the graphile-pg-trgm-plugin package and its integration into the mega query.

• Schema bloat from auto-discovery: The plugin adds similarTo/wordSimilarTo to StringFilter (global) and <col>Similarity computed fields + trgm<Col> filter fields + SIMILARITY_* orderBy enums to every table with text columns. Review whether this level of auto-discovery is appropriate or if it should be gated by a behavior flag (e.g., attributeTrgmSimilarity). The updated snapshots show the full extent of schema additions.

• Multi-signal orderBy semantics: The mega query demonstrates combining BM25 + pg_trgm orderBy signals, but note the documented subtlety: the orderBy array order does NOT determine SQL ORDER BY priority. Instead, priority follows the schema's internal field processing order (which filter apply runs first). Review whether this behavior is acceptable or if the 2-phase meta system should be redesigned to respect array order. Test by running queries with different orderBy array orders and verifying SQL generation.

• Meta system correctness: Verify trgm-search.ts correctly uses setMeta / getMeta to pass similarity score indices. Check that concurrent queries with multiple trgm filters don't collide (e.g., filtering on both name and description in the same query).

• Performance impact: The default connectionFilterTrgmRequireIndex: false means any text column can be fuzzy-matched without a GIN index. On large tables, this could be slow. Review whether the default should be true for production.

Recommended Test Plan:

# 1. Run dedicated pg_trgm tests
eval $(pgpm env) && cd graphile/graphile-pg-trgm-plugin && npx jest

# 2. Run integration tests (includes mega query with multi-signal orderBy)
cd ../graphile-settings && npx jest preset-integration

# 3. (Optional) Manually verify multi-signal orderBy behavior via GraphiQL
# Run queries with different orderBy array orders and inspect the SQL to
# confirm ORDER BY clause sequence follows schema field processing order
# rather than array order.

Notes

• CI: 42/42 checks passing ✅
• All 14 dedicated tests + all 35 integration tests pass locally
• Mega query test now includes multi-signal orderBy with thorough documentation
• Session: https://app.devin.ai/sessions/cf88f3fd383b4421a5169ed01612899d
• 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