Skip to content

Commit af83751

Browse files
claudeclaude
committed
feat(codegen-spring,codegen-kotlin): reverse navigation via explicit FK finders (ADR-0038)
Implement the JVM ports (Java + Kotlin) of ADR-0038 / ADR-0036 Wave 4: generate reverse 1:N navigation as explicit, typed FK finder methods instead of lazy collections (no `@OneToMany`, no Exposed `referrersOn`). For each FK an entity E holds (an `identity.reference`), E's query surface gains a finder PAIR returning the E rows matching a given target id: single: WHERE <fkColumn> = ? -> all E rows for one target batched: WHERE <fkColumn> IN (…) -> anti-N+1 load of many parents The cross-port INVARIANT is the FK-FIELD DERIVATION (PascalCase, drop a single trailing `Id`), unique within E by construction — so the shared `reverse-finders-same-pair` fixture's GameSession → Scene ×3 yields THREE DISTINCT finders (findByCurrentScene / findByLastOpeningNarrativeScene / findByTransitioningFromScene), never colliding, with NO `@reverseName` vocabulary. The method name is idiomatic per port: a Spring Data repository finder `findBy<FkField>` (Java; entity implied by the repo) and an Exposed DSL query function `<E>Table.findBy<FkField>(…): Query` (Kotlin). The value type tracks the FK column's own type (Long for Scene, String for the string-PK Player). M:N navigation is unchanged. - Java: SpringNaming.reverseFinderFkSegment/Name/InName SSOT; SpringRepositoryGenerator emits a single+batched finder per single-field identity.reference (value type via SpringTypeMapper). - Kotlin: KotlinNaming reverse-finder SSOT; KotlinRelationsGenerator now also emits `<E>Relations.kt` for FK-holding entities (eq/inList resolve inside the Exposed where{} receiver — no new imports, M:N-only files stay byte-identical). - Neither JVM port ever emitted lazy reverse collections, so this is purely additive (nothing to remove). Registry-conformance unaffected (no new vocab). - Java SpringReverseFinderCodegenTest (6) + Kotlin KotlinReverseFinderCodegenTest (7) load the shared fixture and assert the three distinct GameSession finders + single/batched shapes + no collision + not-lazy. Verified: codegen-spring 158, codegen-kotlin 265, metadata conformance 392 — all green (the shared reverse-finders-same-pair fixture loads in the JVM conformance runner). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GF9xLEQZaPus5Y6opk398n
1 parent 52d76f1 commit af83751

6 files changed

Lines changed: 496 additions & 3 deletions

File tree

‎server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinNaming.kt‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,4 +91,33 @@ object KotlinNaming {
9191

9292
/** [KotlinExtractorGenerator]: `templateShort + "Extractor"`. */
9393
fun extractorName(templateShort: String): String = templateShort + "Extractor"
94+
95+
// ---------------------------------------------------------------------
96+
// ADR-0038 — reverse-relationship navigation via explicit FK finders.
97+
//
98+
// For each FK an entity `E` holds (an `identity.reference`), `E`'s relations
99+
// file gains an Exposed query function returning the `E` rows matching a given
100+
// target id. The CROSS-PORT INVARIANT is the FK-FIELD DERIVATION (PascalCase,
101+
// drop a single trailing `Id`) — unique within an entity by construction, so
102+
// same-pair FKs (GameSession → Scene ×3) yield three DISTINCT finders, never
103+
// colliding, with no `@reverseName` vocabulary. The function name is idiomatic
104+
// (`findBy<FkField>` — the entity is the receiver table, so it is implied).
105+
// ---------------------------------------------------------------------
106+
107+
/**
108+
* The reverse-finder disambiguator segment derived from an FK field name:
109+
* PascalCase, dropping a single trailing `Id` (but never reducing a bare
110+
* `id`/`Id` to the empty string). E.g. `currentSceneId` → `CurrentScene`;
111+
* `playerId` → `Player`; `id` → `Id`.
112+
*/
113+
fun reverseFinderFkSegment(fkFieldName: String): String {
114+
val pascal = capitalizeFirst(fkFieldName)
115+
return if (pascal.length > 2 && pascal.endsWith("Id")) pascal.dropLast(2) else pascal
116+
}
117+
118+
/** [KotlinRelationsGenerator]: reverse single-value finder name `findBy<FkField>`. */
119+
fun reverseFinderName(fkFieldName: String): String = "findBy" + reverseFinderFkSegment(fkFieldName)
120+
121+
/** [KotlinRelationsGenerator]: reverse batched finder name `findBy<FkField>In`. */
122+
fun reverseFinderInName(fkFieldName: String): String = reverseFinderName(fkFieldName) + "In"
94123
}

‎server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinRelationsGenerator.kt‎

Lines changed: 64 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ package com.metaobjects.generator.kotlin
33
import com.metaobjects.generator.GeneratorIOWriter
44
import com.metaobjects.generator.direct.MultiFileDirectGeneratorBase
55
import com.metaobjects.identity.MetaIdentity
6+
import com.metaobjects.identity.ReferenceIdentity
67
import com.metaobjects.loader.MetaDataLoader
78
import com.metaobjects.`object`.MetaObject
89
import com.metaobjects.relationship.CompositionRelationship
@@ -78,16 +79,20 @@ open class KotlinRelationsGenerator : MultiFileDirectGeneratorBase<MetaObject>()
7879
// FR-018: M:N navs (any subtype, @cardinality:"many" + @through). Derived
7980
// junction FK fields via the cross-port SSOT (KotlinM2mSupport → M2MFields).
8081
val m2mNavs = KotlinM2mSupport.resolve(entity, loader)
81-
if (manyRels.isEmpty() && m2mNavs.isEmpty()) continue
82+
// ADR-0038: reverse navigation — one finder pair per FK this entity holds
83+
// (each single-field identity.reference).
84+
val reverseFks = reverseFksFor(entity)
85+
if (manyRels.isEmpty() && m2mNavs.isEmpty() && reverseFks.isEmpty()) continue
8286

83-
emit(entity, manyRels, m2mNavs, outRoot, loader)
87+
emit(entity, manyRels, m2mNavs, reverseFks, outRoot, loader)
8488
}
8589
}
8690

8791
protected open fun emit(
8892
entity: MetaObject,
8993
manyRels: List<MetaRelationship>,
9094
m2mNavs: List<KotlinM2mSupport.M2mNav>,
95+
reverseFks: List<ReverseFk>,
9196
outRoot: Path,
9297
loader: MetaDataLoader,
9398
) {
@@ -110,7 +115,7 @@ open class KotlinRelationsGenerator : MultiFileDirectGeneratorBase<MetaObject>()
110115
val relShort = rel.shortName ?: rel.name
111116
Helper(relShort, targetShort + "Table")
112117
}
113-
if (helpers.isEmpty() && m2mNavs.isEmpty()) return
118+
if (helpers.isEmpty() && m2mNavs.isEmpty() && reverseFks.isEmpty()) return
114119

115120
val source = buildString {
116121
if (pkg.isNotEmpty()) {
@@ -180,13 +185,69 @@ open class KotlinRelationsGenerator : MultiFileDirectGeneratorBase<MetaObject>()
180185
append(" .where { ${nav.junctionTableObj}.${nav.sourceField} eq sourceId }\n")
181186
}
182187
}
188+
189+
// ADR-0038 reverse navigation — one finder PAIR per FK this entity holds
190+
// (each single-field identity.reference). The referenced entity T navigates to
191+
// its referencing E rows by calling these with a T id. The fn name derives from
192+
// the FK FIELD (PascalCased, trailing `Id` dropped), unique within E by
193+
// construction — so same-pair FKs (GameSession → Scene ×3) yield DISTINCT finders
194+
// (findByCurrentScene / findByLastOpeningNarrativeScene /
195+
// findByTransitioningFromScene), never colliding, with no @reverseName vocabulary.
196+
// NOT a lazy Exposed `referrersOn` reverse collection (N+1 + needs an open
197+
// transaction): each is a plain single indexed query (WHERE fk = ?), with a
198+
// batched variant (WHERE fk IN (…)) for anti-N+1 loading of many parents. The
199+
// returned Query stays compositional (chain .orderBy/.limit before materialising).
200+
for (fk in reverseFks) {
201+
if (!first) append("\n")
202+
first = false
203+
val col = KotlinNaming.safeColumnProperty(fk.fkField)
204+
val single = KotlinNaming.reverseFinderName(fk.fkField)
205+
val batched = KotlinNaming.reverseFinderInName(fk.fkField)
206+
append("/** Reverse nav: the $ownerShort rows whose `${fk.fkField}` FK points at the given ${fk.targetShortName} id (single indexed query). */\n")
207+
append("fun $ownerTable.$single(${fk.fkField}: ${fk.valueType}): Query =\n")
208+
append(" $ownerTable.selectAll().where { $ownerTable.$col eq ${fk.fkField} }\n")
209+
append("\n")
210+
append("/** Reverse nav (batched, anti-N+1): the $ownerShort rows whose `${fk.fkField}` FK is IN the given ${fk.targetShortName} ids. */\n")
211+
append("fun $ownerTable.$batched(${fk.fkField}s: List<${fk.valueType}>): Query =\n")
212+
append(" $ownerTable.selectAll().where { $ownerTable.$col inList ${fk.fkField}s }\n")
213+
}
183214
}
184215

185216
val outFile = outRoot.resolve(pkg.replace('.', '/')).resolve(ownerShort + "Relations.kt")
186217
outFile.parent?.let { Files.createDirectories(it) }
187218
Files.writeString(outFile, source)
188219
}
189220

221+
/**
222+
* One reverse FK an entity holds (ADR-0038), derived from an `identity.reference`:
223+
* the FK field name, the target entity short name, and the Kotlin value type of the
224+
* FK (the type a `findBy<FkField>` arg / element takes — the FK column's own Kotlin type).
225+
*/
226+
protected data class ReverseFk(val fkField: String, val targetShortName: String, val valueType: String)
227+
228+
/**
229+
* Collect every reverse FK [entity] declares, in declaration order — one per
230+
* single-field [ReferenceIdentity] child. Compound references (multi-field FKs) are
231+
* skipped (no single-column finder shape). The value type is the FK field's own Kotlin
232+
* simple type via [KotlinTypeMapper.kotlinTypeName], falling back to `Long`.
233+
*/
234+
protected open fun reverseFksFor(entity: MetaObject): List<ReverseFk> {
235+
val out = mutableListOf<ReverseFk>()
236+
for (child in entity.children) {
237+
if (child !is ReferenceIdentity) continue
238+
val fields = child.fields
239+
if (fields.size != 1) continue // single-column FKs only
240+
val fkField = fields.first()
241+
val targetShort = child.targetEntity?.let { PackageMapping.splitFqn(it).second } ?: ""
242+
val valueType = entity.metaFields.firstOrNull { it.name == fkField }?.let { f ->
243+
runCatching { KotlinTypeMapper.kotlinTypeName(f).toString().substringAfterLast('.') }
244+
.getOrDefault("Long")
245+
} ?: "Long"
246+
out.add(ReverseFk(fkField, targetShort, valueType))
247+
}
248+
return out
249+
}
250+
190251
/**
191252
* Resolve the Kotlin type of [entity]'s primary key. Falls back to [LONG] when
192253
* the primary identity is missing, multi-field, or its field can't be resolved

‎server/java/codegen-kotlin/src/test/kotlin/com/metaobjects/generator/kotlin/KotlinReverseFinderCodegenTest.kt‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
package com.metaobjects.generator.kotlin
2+
3+
import com.metaobjects.metadata.ktx.loadString
4+
import java.nio.file.Files
5+
import kotlin.test.Test
6+
import kotlin.test.assertEquals
7+
import kotlin.test.assertFalse
8+
import kotlin.test.assertTrue
9+
10+
/**
11+
* ADR-0038 — reverse-relationship navigation via explicit FK finders, Kotlin port:
12+
* Exposed DSL query functions on the entity HOLDING the FK, emitted into
13+
* `<Entity>Relations.kt` by [KotlinRelationsGenerator].
14+
*
15+
* Loads the shared `reverse-finders-same-pair` model (inlined): `GameSession` holds
16+
* THREE FKs to `Scene` plus one string-PK FK to `Player`. Asserts the three same-pair
17+
* Scene FKs yield THREE DISTINCT finder pairs (`findByCurrentScene` /
18+
* `findByLastOpeningNarrativeScene` / `findByTransitioningFromScene`), each with a
19+
* single (WHERE fk = ?) + batched (WHERE fk IN (…)) shape — and that this is NOT a
20+
* lazy Exposed `referrersOn` reverse collection.
21+
*/
22+
class KotlinReverseFinderCodegenTest {
23+
24+
/** The shared reverse-finders-same-pair model, inlined (3 FKs to Scene + 1 to Player). */
25+
private val fixture = """{
26+
"metadata.root": { "package": "game", "children": [
27+
{ "object.entity": { "name": "Scene", "children": [
28+
{ "source.rdb": { "@table": "scenes" } },
29+
{ "field.long": { "name": "id" } },
30+
{ "field.string": { "name": "title" } },
31+
{ "identity.primary": { "name": "id", "@fields": "id", "@generation": "increment" } }
32+
] } },
33+
{ "object.entity": { "name": "Player", "children": [
34+
{ "source.rdb": { "@table": "players" } },
35+
{ "field.string": { "name": "id" } },
36+
{ "field.string": { "name": "name" } },
37+
{ "identity.primary": { "name": "id", "@fields": "id", "@generation": "assigned" } }
38+
] } },
39+
{ "object.entity": { "name": "GameSession", "children": [
40+
{ "source.rdb": { "@table": "game_sessions" } },
41+
{ "field.long": { "name": "id" } },
42+
{ "field.long": { "name": "currentSceneId" } },
43+
{ "field.long": { "name": "lastOpeningNarrativeSceneId" } },
44+
{ "field.long": { "name": "transitioningFromSceneId" } },
45+
{ "field.string": { "name": "playerId" } },
46+
{ "relationship.association": { "name": "currentScene", "@cardinality": "one", "@objectRef": "Scene" } },
47+
{ "relationship.association": { "name": "player", "@cardinality": "one", "@objectRef": "Player" } },
48+
{ "identity.primary": { "name": "id", "@fields": "id", "@generation": "increment" } },
49+
{ "identity.reference": { "name": "fkCurrentScene", "@fields": "currentSceneId", "@references": "Scene" } },
50+
{ "identity.reference": { "name": "fkLastOpeningNarrativeScene", "@fields": "lastOpeningNarrativeSceneId", "@references": "Scene" } },
51+
{ "identity.reference": { "name": "fkTransitioningFromScene", "@fields": "transitioningFromSceneId", "@references": "Scene" } },
52+
{ "identity.reference": { "name": "fkPlayer", "@fields": "playerId", "@references": "Player" } }
53+
] } }
54+
] }
55+
}""".trimIndent()
56+
57+
private fun generate(): String {
58+
val outDir = Files.createTempDirectory("krev-")
59+
val gen = KotlinRelationsGenerator()
60+
gen.setArgs(mapOf("outputDir" to outDir.toString()))
61+
gen.execute(loadString("reverse-finders", fixture))
62+
val emitted = outDir.resolve("game/GameSessionRelations.kt")
63+
assertTrue(Files.exists(emitted), "expected $emitted; files=${Files.walk(outDir).toList()}")
64+
return Files.readString(emitted)
65+
}
66+
67+
@Test fun `same-pair three scenes yield three distinct finders`() {
68+
val src = generate()
69+
assertTrue("fun GameSessionTable.findByCurrentScene(currentSceneId: Long): Query" in src,
70+
"expected findByCurrentScene; saw:\n$src")
71+
assertTrue("fun GameSessionTable.findByLastOpeningNarrativeScene(lastOpeningNarrativeSceneId: Long): Query" in src,
72+
"expected findByLastOpeningNarrativeScene; saw:\n$src")
73+
assertTrue("fun GameSessionTable.findByTransitioningFromScene(transitioningFromSceneId: Long): Query" in src,
74+
"expected findByTransitioningFromScene; saw:\n$src")
75+
}
76+
77+
@Test fun `single finder is an indexed WHERE-eq query`() {
78+
val src = generate()
79+
assertTrue(
80+
"GameSessionTable.selectAll().where { GameSessionTable.currentSceneId eq currentSceneId }" in src,
81+
"expected single indexed WHERE eq body; saw:\n$src")
82+
}
83+
84+
@Test fun `batched finder is a WHERE-IN query (anti-N+1)`() {
85+
val src = generate()
86+
assertTrue("fun GameSessionTable.findByCurrentSceneIn(currentSceneIds: List<Long>): Query" in src,
87+
"expected batched findByCurrentSceneIn; saw:\n$src")
88+
assertTrue(
89+
"GameSessionTable.selectAll().where { GameSessionTable.currentSceneId inList currentSceneIds }" in src,
90+
"expected batched WHERE inList body; saw:\n$src")
91+
}
92+
93+
@Test fun `string-PK FK uses String value type`() {
94+
val src = generate()
95+
assertTrue("fun GameSessionTable.findByPlayer(playerId: String): Query" in src,
96+
"expected findByPlayer(String); saw:\n$src")
97+
assertTrue("fun GameSessionTable.findByPlayerIn(playerIds: List<String>): Query" in src,
98+
"expected findByPlayerIn(List<String>); saw:\n$src")
99+
}
100+
101+
@Test fun `not a lazy referrersOn reverse collection`() {
102+
val src = generate()
103+
assertFalse("referrersOn" in src,
104+
"reverse nav must be explicit query fns, not lazy referrersOn; saw:\n$src")
105+
assertFalse("backReferencedOn" in src,
106+
"must not use lazy backReferencedOn; saw:\n$src")
107+
}
108+
109+
@Test fun `referenced entity emits no relations file`() {
110+
val outDir = Files.createTempDirectory("krev-")
111+
val gen = KotlinRelationsGenerator()
112+
gen.setArgs(mapOf("outputDir" to outDir.toString()))
113+
gen.execute(loadString("reverse-finders", fixture))
114+
// Scene + Player hold no FKs (no identity.reference, no to-many) → no relations file.
115+
assertFalse(Files.exists(outDir.resolve("game/SceneRelations.kt")),
116+
"Scene holds no FK/to-many → no SceneRelations.kt")
117+
assertFalse(Files.exists(outDir.resolve("game/PlayerRelations.kt")),
118+
"Player holds no FK/to-many → no PlayerRelations.kt")
119+
}
120+
121+
@Test fun `fk segment derivation drops trailing Id`() {
122+
assertEquals("CurrentScene", KotlinNaming.reverseFinderFkSegment("currentSceneId"))
123+
assertEquals("Player", KotlinNaming.reverseFinderFkSegment("playerId"))
124+
assertEquals("findByCurrentScene", KotlinNaming.reverseFinderName("currentSceneId"))
125+
assertEquals("findByCurrentSceneIn", KotlinNaming.reverseFinderInName("currentSceneId"))
126+
assertEquals("Id", KotlinNaming.reverseFinderFkSegment("id"))
127+
}
128+
}

‎server/java/codegen-spring/src/main/java/com/metaobjects/generator/spring/SpringNaming.java‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,4 +149,48 @@ public static String parserName(String templateShort) {
149149
public static String traceHelperName(String shortName) {
150150
return shortName + "TraceHelper";
151151
}
152+
153+
// ---------------------------------------------------------------------
154+
// ADR-0038 — reverse-relationship navigation via explicit FK finders.
155+
//
156+
// For each FK relationship (entity {@code E} references {@code T} via an
157+
// {@code identity.reference} FK field), {@code E}'s repository gains a finder
158+
// returning the {@code E} rows matching a given {@code T} id. Two variants:
159+
// a single-value finder and a batched (anti-N+1) {@code …In} finder.
160+
//
161+
// The CROSS-PORT INVARIANT is the FK-FIELD DERIVATION (not a verbatim
162+
// cross-port method name): the disambiguator segment is the FK field name,
163+
// PascalCased, with a single trailing {@code Id} dropped. Because FK field
164+
// names are unique within an entity, the segment — and so the finder — is
165+
// unique by construction. Three same-pair FKs (GameSession → Scene ×3) yield
166+
// three distinct finders ({@code findByCurrentScene} /
167+
// {@code findByLastOpeningNarrativeScene} / {@code findByTransitioningFromScene}),
168+
// never colliding. The repository method name is idiomatic Spring Data
169+
// ({@code findBy<FkField>} — the entity is implied by the repository), matching
170+
// the shape a JVM adopter hand-writes; the TS port spells it
171+
// {@code find<EPlural>By<FkField>} (the entity is NOT implied there).
172+
// ---------------------------------------------------------------------
173+
174+
/**
175+
* The reverse-finder disambiguator segment derived from an FK field name:
176+
* PascalCase, dropping a single trailing {@code Id} (but never reducing a bare
177+
* {@code "id"}/{@code "Id"} to the empty string). E.g. {@code currentSceneId} →
178+
* {@code CurrentScene}; {@code playerId} → {@code Player}; {@code id} → {@code Id}.
179+
*/
180+
public static String reverseFinderFkSegment(String fkFieldName) {
181+
String pascal = capitalize(fkFieldName);
182+
return pascal.length() > 2 && pascal.endsWith("Id")
183+
? pascal.substring(0, pascal.length() - 2)
184+
: pascal;
185+
}
186+
187+
/** {@code SpringRepositoryGenerator}: reverse single-value finder name {@code findBy<FkField>}. */
188+
public static String reverseFinderName(String fkFieldName) {
189+
return "findBy" + reverseFinderFkSegment(fkFieldName);
190+
}
191+
192+
/** {@code SpringRepositoryGenerator}: reverse batched finder name {@code findBy<FkField>In}. */
193+
public static String reverseFinderInName(String fkFieldName) {
194+
return reverseFinderName(fkFieldName) + "In";
195+
}
152196
}

0 commit comments

Comments
 (0)