Anvil
Explanation

The profile-binding contract

profile.runtime carries the typed API that every profile binding sits on: ProfileReference, StereotypeReference, the two tag references, EnumerationReference and the Generated marker. A plugin author calls it directly, and generated code is written against it, which makes it the one package here whose signatures a change cannot be reasoned about locally.

This page explains that contract and what guards it. Anvil: use profile bindings states how a plugin author calls the API.

The binding resolves, and holds nothing

Every operation on a StereotypeReference resolves the live Stereotype from the element's own project and caches nothing. Three properties of CATIA Magic force that.

A binding is a compile-time object, and a Stereotype is a model element belonging to one project. A cached instance would be wrong the moment a second project opened, and stale the moment a module reloaded. Resolution is therefore a per-call read from Project.getProject(element), which also means a binding is safe to declare as a top-level object.

The profile URI is the resolution key, and the profile's name is carried for diagnostics alone. A profile can be renamed, imported under a different label, or shipped twice; the URI is what a project matches. The same reasoning runs one level down for enumeration literals, which are matched on XMI id first and on name second, because an id survives a rename.

Resolution failure is an error naming both halves — the reference and what was missing — rather than a null. A profile that is not loaded in a project and a stereotype that is not defined in a profile are two different mistakes, and a binding that answered null for both would push the diagnosis onto the caller.

The guards state what the Open API does not

The Open API does not block a write to an element that cannot take one, so the binding does. Every mutating operation runs three checks in a fixed order — disposed, read-only, proxy into an unloaded module — and applyTo adds a fourth, that the stereotype's metaclass fits the element.

Every mutating operation also asserts an open session first. A model write outside a session fails silently and leaves no undo entry, which is the failure mode a resource author is least equipped to notice, so the assertion converts it into an exception at the call that caused it.

applyTo seeds tagged values through TagDefaults, and it removes now-redundant parent stereotypes after applying. A tag write goes through setStereotypePropertyValue with setAnotherEnd = true, so a tag that is one end of a bidirectional association keeps its far end consistent; that argument is inert on a tag with no association, which is why every write can take it.

The generator lives in Forge

The .mdzip-to-Kotlin generator is not in this repository. Forge runs it from its generateProfileBindings task during a consuming project's build, and writes the emitted sources into that consumer's own profile package.

The split is a dependency decision. Forge builds Anvil, so an Anvil that compiled against Forge would close a cycle. What crosses between them is a source-level contract instead: Forge's KotlinBindingEmitter writes code against these signatures, and this repository publishes the signatures that code compiles against.

The consequence is that profile.runtime is a published contract two repositories deep. A signature change here can compile cleanly, pass every test here, and break the sources Forge emits into every consumer at their next build.

Main.kt is what puts the runtime where generated code can reach it

The sources Forge emits into a consumer are compiled against profile.runtime, and at run time they have to find it. They find this installed copy, because Main.kt loads from it.

gradle.properties sets com.mbseconsulting.forge.plugin.ownClassloader=false and com.mbseconsulting.forge.plugin.classLookup=GlobalFirst, so the jar carrying the plugin entry class enters CATIA Magic's shared class loader rather than a private one of its own. Once Main loads, every type beside it in that jar is resolvable by any other plugin in the session.

No line in the class does this. The class installs the diagram image export and nothing more; its existence is what gets its jar loaded into the shared space at all. A consumer therefore bundles no copy of profile.runtime, and every consumer in a session resolves the same one.

The marker keeps generated code out of the coverage gate

Emitted code carries @Generated from profile.runtime. JaCoCo 0.8.2 and later drop every class and method carrying an annotation whose simple name contains "Generated" and whose retention reaches the class file, so the marker is what keeps generated bindings out of a consumer's coverage report and out of the coverage gate Forge wires into check. The number that gate reads then measures the code the consumer wrote.

Both halves of the JaCoCo rule are load-bearing. Renaming the annotation, or retaining it at source level, disables the filter silently — and in the consumer's build rather than in this repository's tests. Retention is RUNTIME where BINARY would also satisfy JaCoCo, so that GeneratedTest can read the retention back off the compiled annotation with getAnnotation instead of parsing bytecode.

Hand-written bindings carry no marker and stay measured. They are the author's code, and the author's tests are what a coverage report is measuring.

The witness fails this build instead of a consumer's

src/test/kotlin/.../witness/EmittedShapeWitness.kt is the guard on the contract. It is the emitter's verbatim output for a fixture profile, compiled by compileTestKotlin and never executed, so it carries no @Test. A profile.runtime signature change that the emitted shape depends on fails this repository's own build, rather than a consumer's generated sources a release later.

Two rules follow from what the file is:

  • Re-copy it from the emitter when the emitted shape changes. Never hand-edit it to clear a compile error, because an edited witness still compiles and witnesses nothing.
  • Nothing in it is hand-written. Everything from @file:Generated down is byte-identical to Forge's golden resource, and Spotless stamps the licence header above that line. The licenseHeader step stops at the @file: delimiter, so the header needs no hand edit, and the file carries no explanatory comment: the step replaces whatever sits above that delimiter, and this page holds the explanation instead. build.gradle.kts suppresses one ktlint rule for this path, enum-entry-name-case, which the emitted entries _1, _2 and _3 break. Every other step runs over the file and leaves the emitter's layout untouched.

Forge holds the other half of the guard. Its EmittedShapeGoldenTest pins that body, byte for byte, as src/test/resources/golden/EmittedShapeWitness.kt.txt, so an emitter change that alters the emitted shape fails there first, in Forge's own build. That test compares the emitter's output against the golden file alone and cannot see this witness, so keeping the two in step once the golden changes is a manual step: copy the regenerated golden over the witness, then run spotlessApply to stamp the licence header back on.

Dassault's own profiles take the adapter path

A profile Dassault ships — SysML, MagicDraw, Standard, Validation — generates like any other profile. A dedicated adapter layer over Dassault's own typed wrappers is the intended path for that case instead. Prefer the adapter once it exists, rather than generating bindings for a profile Anvil does not own.

On this page