refactor: consolidate duplicated fuzzy name-matching into shared utility

Extract duplicated fuzzy table-name matching logic from field-selector.ts
and select.ts into a shared name-matching.ts module. Both files now import
fuzzyFindByName from the shared utility instead of duplicating the normalize +
compare logic inline.

Also adds NOTE comments to codegen/utils.ts indicating that lcFirst, ucFirst,
toCamelCase, toPascalCase, and toScreamingSnake can be replaced with re-exports
from inflekt once version 0.4.0 is published (see dev-utils PR #71).

Author: pyramation

graphql/codegen/src/core/codegen/utils.ts

@@ -13,6 +13,9 @@ import { scalarToFilterType, scalarToTsType } from './scalars';
 
 // ============================================================================
 // String manipulation
+// NOTE: lcFirst, ucFirst already exist in inflekt; toCamelCase, toPascalCase,
+// toScreamingSnake are available in inflekt >=0.4.0.  Once that version is
+// published these can be replaced with re-exports from inflekt.
 // ============================================================================
 
 /** Lowercase first character */

graphql/query/src/generators/field-selector.ts

@@ -9,6 +9,7 @@ import type {
   FieldSelectionPreset,
   SimpleFieldSelection,
 } from '../types/selection';
+import { fuzzyFindByName } from './name-matching';
 
 const relationalFieldSetCache = new WeakMap<Table, Set<string>>();
 
@@ -293,19 +294,14 @@ function getRelatedTableScalarFields(
     return {};
   }
 
-  // Find the related table in allTables.
-  // PostGraphile v5 uses different inflections in different contexts:
-  // - table.name: PascalCase tableType (e.g., "Shipment", "DriverVehicleAssignment")
-  // - relation referencedBy.name: raw codec name (e.g., "shipments", "driverVehicleAssignments")
-  // Try exact match first, then case-insensitive match with optional trailing 's' for plural.
-  const nameLower = referencedTableName.toLowerCase().replace(/_/g, '');
-  const nameBase = nameLower.endsWith('s') ? nameLower.slice(0, -1) : nameLower;
-  const relatedTable =
-    allTables.find((t) => t.name === referencedTableName) ??
-    allTables.find((t) => {
-      const tLower = t.name.toLowerCase().replace(/_/g, '');
-      return tLower === nameLower || tLower === nameBase;
-    });
+  // Find the related table in allTables using shared fuzzy matching.
+  // Handles PascalCase table names vs snake_case/camelCase/plural codec names.
+  // TODO: replace with fuzzyFindByName from inflekt once 0.4.0 is published
+  const relatedTable = fuzzyFindByName(
+    allTables,
+    referencedTableName,
+    (t) => t.name,
+  );
   if (!relatedTable) {
     // Related table not found in schema — return fallback { __typename: true }
     // so the query remains valid (nodes need at least one subfield).

graphql/query/src/generators/name-matching.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared name-matching utilities for resolving PostGraphile v5 naming mismatches.
+ *
+ * PostGraphile v5 uses different inflection conventions in different contexts:
+ *   - Table types are PascalCase (e.g., "Shipment", "DeliveryZone")
+ *   - Relation codec names are raw snake_case or camelCase (e.g., "shipments", "deliveryZones")
+ *
+ * These helpers provide a single, shared way to normalize and compare names
+ * across those boundaries instead of duplicating fuzzy-match logic in every consumer.
+ *
+ * NOTE: These functions are also available in inflekt >=0.4.0
+ * (fuzzyFindByName, normalizeName, normalizeNameSingular, namesMatch).
+ * Once inflekt 0.4.0 is published and the dependency is bumped, the consumers
+ * can import directly from inflekt and this file can be removed.
+ */
+
+/**
+ * Normalize a name for case-insensitive, delimiter-insensitive comparison.
+ * Strips underscores and lowercases.
+ */
+function normalizeName(name: string): string {
+  return name.toLowerCase().replace(/_/g, '');
+}
+
+/**
+ * Normalize a name to its singular base form for comparison.
+ * Strips underscores, lowercases, and removes a trailing 's' when present.
+ */
+function normalizeNameSingular(name: string): string {
+  const normalized = normalizeName(name);
+  return normalized.endsWith('s') ? normalized.slice(0, -1) : normalized;
+}
+
+/**
+ * Find a matching item by name using exact match first, then fuzzy
+ * case-insensitive / plural-insensitive fallback.
+ *
+ * This is the single shared implementation for resolving relation target names
+ * to table definitions, replacing ad-hoc fuzzy matching scattered across consumers.
+ *
+ * @param items      - Array of items to search through
+ * @param targetName - The name to find (may be PascalCase, snake_case, plural, etc.)
+ * @param getName    - Accessor to extract the comparable name from each item
+ * @returns The matched item, or undefined if no match found
+ */
+export function fuzzyFindByName<T>(
+  items: T[],
+  targetName: string,
+  getName: (item: T) => string,
+): T | undefined {
+  // 1. Exact match (fast path)
+  const exact = items.find((item) => getName(item) === targetName);
+  if (exact) return exact;
+
+  // 2. Fuzzy match: case-insensitive, strip underscores, optional trailing 's'
+  const targetNormalized = normalizeName(targetName);
+  const targetBase = normalizeNameSingular(targetName);
+
+  return items.find((item) => {
+    const itemNormalized = normalizeName(getName(item));
+    return itemNormalized === targetNormalized || itemNormalized === targetBase;
+  });
+}

graphql/query/src/generators/select.ts

@@ -25,6 +25,7 @@ import type { QueryOptions } from '../types/query';
 import type { Table } from '../types/schema';
 import type { FieldSelection } from '../types/selection';
 import { convertToSelectionOptions, isRelationalField } from './field-selector';
+import { fuzzyFindByName } from './name-matching';
 import {
   normalizeInflectionValue,
   toCamelCasePlural,
@@ -787,19 +788,10 @@ function findRelatedTable(
     return null;
   }
 
-  // Find the related table in allTables
-  const exactMatch = allTables.find((tbl) => tbl.name === referencedTableName);
-  if (exactMatch) return exactMatch;
-
-  // Fuzzy match: case-insensitive, strip underscores, optional trailing 's'.
-  // Needed because relation target names from _meta use snake_case codec names
-  // (e.g. "routes", "delivery_zone") while allTables[].name is PascalCase (e.g. "Route", "DeliveryZone").
-  const nameLower = referencedTableName.toLowerCase().replace(/_/g, '');
-  const nameBase = nameLower.endsWith('s') ? nameLower.slice(0, -1) : nameLower;
-  return allTables.find((tbl) => {
-    const tLower = tbl.name.toLowerCase().replace(/_/g, '');
-    return tLower === nameLower || tLower === nameBase;
-  }) || null;
+  // Find the related table using shared fuzzy matching.
+  // Handles PascalCase table names vs snake_case/camelCase/plural codec names.
+  // TODO: replace with fuzzyFindByName from inflekt once 0.4.0 is published
+  return fuzzyFindByName(allTables, referencedTableName, (tbl) => tbl.name) ?? null;
 }
 
 /**