Metamodel: stamp a schema in a block, or a chain

[jimador]

Answers the review note on #83: MetamodelVersion.from(dictionary).governedBy(governed).

Two entries off the class, one per language. Both take the same three inputs a stamp needs and both delegate to the existing from overloads, so every spelling produces the same stamp.

Kotlin

A receiver block, so the call site is a sequence of statements with no prefix and no chain:

val version = MetamodelVersion(dictionary) {
    governedBy("Person", "Company")
    aliases {
        type("Organisation", formerly = setOf("Company"))
        property("Person", "emailAddress", formerly = setOf("email"))
    }
}

The entry is operator fun invoke on the companion, which is how embabel-agent shapes its own configured constructors (ActionContext, OperationContext, Tool.Definition) and the same shape as Json { } and HttpClient { }. It reads as a constructor with a trailing block and stays on the class. DeclaredSchema(dictionary) { } is the same block finishing as a declaration, so both halves of a declaration come from one set of arguments and cannot disagree about what is governed. An empty block is the whole-schema stamp.

governedBy takes a selector, a set of names, or names written out. aliases { } declares renames inline through type(...) and property(...), since SchemaAliases is two levels of map and writing those literals is the least readable part of declaring a rename. Names accumulate there, so a type renamed A to B to C declares both older names, which is what a comparison across non-adjacent stamps needs.

@DslMarker scopes the two builders, so reaching the outer one from inside aliases { } is a compile error. The builders are mutable, their constructors are internal, and their lifetime is the block. What comes back is immutable.

Java

MetamodelStamping, an immutable value carrying the same three inputs, reached through MetamodelVersion.stamping(dictionary). Every step returns a new value, so a partly built stamping can be held in a field and finished more than once, as a stamp or as a declaration.

MetamodelVersion version = MetamodelVersion.stamping(dictionary)
        .governedBy(Set.of("Person", "Company"))
        .withAliases(aliases)
        .stamp();

The block entries are @JvmSynthetic, so Java sees only the chain. A receiver lambda from Java means returning Unit.INSTANCE by hand, which is why the two surfaces stay separate rather than one serving both.

Why from stays

from(dictionary) already returns a stamp, so it cannot become the entry to either form without breaking every caller compiled against it. The three MetamodelVersion.from overloads and both DeclaredSchema.from overloads are untouched. They are the short forms.

Compatibility

Additive. Two companion entries, one value type, two builders. Nothing existing moves. MetamodelStamping carries @JvmOverloads on its constructor, so Java keeps the one, two and three-argument arities; a test pins that.

Nothing is validated while chaining or inside a block. The alias rules stay with the factories, so a bad declaration fails on the terminal call, or when the block returns, with the message the three-argument form gives.

Verification

./mvnw clean install at this branch, all modules green. dice-metamodel carries 11 new tests on the block, 9 on the chain, and 16 in the Java compat suite, including one asserting the block and the chain reach the identical stamp.

[igordayen]

@jimador - looks very good, thank you

Could you please rebase?