Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 45 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,8 +121,10 @@ Genmodels are not uploaded; they are generated from the metamodels. The pipeline

1. Validates the uploads (non-empty, expected extension, unique names).
2. Loads the metamodels, resolves references between them (relative, `platform:/resource`, or nsURI),
validates them with EMF, and generates matching genmodels.
3. Checks that every Reactions `import` refers to an uploaded nsURI.
validates them with EMF, rejects names whose generated Java code does not compile, and generates
matching genmodels.
3. Checks the reactions against the loaded metamodels: every `import` refers to an uploaded nsURI, and
aliases, classes, and trigger features exist and fit (see [Checks before the build](#checks-before-the-build)).
4. Generates a project following the [Methodologist Template](https://github.com/vitruv-tools/Methodologist-Template)
(`model`, `consistency`, `vsum`), with a smoke test that creates and reloads the VSUM and compiles the constraints.
5. Runs `mvn clean verify`.
Expand All @@ -144,17 +146,18 @@ contains the same as readable text:

```json
{
"errorCode": "VSUM_BUILD_FAILED",
"status": 422,
"message": "The VSUM build failed:\n\nmy.reactions:\n- line 51, column 30: 'Entitiy' cannot be resolved\n...",
"errorCode": "VSUM_REACTIONS_ERROR",
"status": 400,
"message": "The uploaded reactions do not match the uploaded metamodels:\n\nmy.reactions:\n- line 51, column 30: ...",
"problems": [
{
"source": "REACTIONS",
"file": "my.reactions",
"line": 51,
"column": 30,
"message": "'Entitiy' cannot be resolved",
"excerpt": " val entity = new model2::Entitiy\n ^"
"message": "'Entitiy' is not a class of the metamodel 'model2' (http://vitruv.tools/methodologisttemplate/model2)",
"excerpt": " val entity = new model2::Entitiy\n ^",
"hint": "Did you mean 'Entity'?"
}
]
}
Expand All @@ -167,6 +170,41 @@ but counted in `hiddenFollowUpErrors`. Problems are reported for metamodels and
the build, for Reactions compiler and Java compiler errors, and for failures of the smoke test (constraints
that cannot be evaluated, exceptions in reactions or routines while creating the VSUM).

### Checks before the build

Most mistakes are found in milliseconds, before Maven runs, and come with a suggestion:

- **Metamodels**: EMF validation, with messages naming the element (`Thing.untyped`) and a hint; names
that differ only in upper/lower case or `_` (classes, features including inherited ones, enum
literals), Java reserved words as class names (`class`, `record`, `var`), and classes named like the
generated `<Package>Package`/`<Package>Factory` interfaces. EMF escapes reserved words in feature,
literal, and package names, so these are accepted.
- **Reactions**: aliases in segment headers and before `::`, `alias::Class` (including subpackages and
`using qualified names`), `[feature]` in triggers (attribute for `after attribute`, reference for
`after element`, single-valued for `replaced at`, many-valued for `inserted in`/`removed from`, and an
element type that fits the reference), and abstract classes, interfaces, or enums in `create` blocks.

Errors only the Reactions compiler finds (syntax, Xbase expressions) are reported after the build, with a
hint from a catalog of compiler messages (`CompilerHints`).

#### Dependency on the Reactions language

The reactions checks (`ReactionsChecker`) do not use the Reactions language
(`tools.vitruv.dsls.reactions.language`); they reimplement the rules of its grammar
(`ReactionsLanguage.xtext`), scope provider (`CommonLanguageElementsScopeProvider`,
`ReactionsLanguageScopeProvider`), and validator (`ReactionsLanguageValidator`) in
[Vitruv-DSLs](https://github.com/vitruv-tools/Vitruv-DSLs), as of version 4.0.0. When
`setup.vsum.vitruv-dsls-version` is raised, compare these files with the version the checks follow and
adapt `ReactionsChecker` and `CompilerHints`. The checks only report what is certainly wrong and leave
everything else to the compiler, so a newer language can at worst make them miss a mistake; a failure of
the checker itself is logged and leaves the decision to the compiler.

The language is deliberately not a dependency of the service: it brings Xtext/Xbase, Guice, ANTLR 3,
log4j-core, and Eclipse p2 wrappers, which conflict with Spring Boot's logging and dependency versions.
Linking Xbase expressions also needs the Java classes generated from the metamodels, which exist only after
the Maven build. Parsing with the real grammar before the build would therefore run in a separate JVM on the
jars the warm-up build puts into the Maven repository of the image.

The workspaces of `503` and `500` builds are kept in the temporary directory for debugging and deleted on a
later startup once older than `setup.vsum.workspace-retention`.

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
package tools.vitruv.methodologist.setup.vsum.service.metamodel;

import java.util.List;
import java.util.Optional;
import org.eclipse.emf.common.util.Diagnostic;
import org.eclipse.emf.ecore.ENamedElement;
import org.eclipse.emf.ecore.EObject;
import org.eclipse.emf.ecore.EcorePackage;
import org.eclipse.emf.ecore.util.EcoreUtil;
import org.eclipse.emf.ecore.util.EcoreValidator;

/**
* Turns the diagnostics of EMF's {@link EcoreValidator} into problems a methodologist can act on:
* object dumps are replaced by element names, redundant diagnostics are dropped, and a hint says
* how to fix the metamodel.
*/
final class EcoreDiagnostics {

/**
* A metamodel problem found by validation.
*
* @param element the element to locate the problem at
* @param message what is wrong, without the element name
* @param hint how to fix it, or {@code null}
*/
record Finding(EObject element, String message, String hint) {}

private EcoreDiagnostics() {}

/**
* Translates a leaf diagnostic.
*
* @param diagnostic a diagnostic without children
* @return the problem, or empty if the diagnostic does not break the build or repeats another
*/
static Optional<Finding> translate(Diagnostic diagnostic) {
List<EObject> elements =
diagnostic.getData().stream()
.filter(EObject.class::isInstance)
.map(EObject.class::cast)
.filter(object -> !isEcoreMetamodel(object))
.toList();
if (diagnostic.getSeverity() == Diagnostic.WARNING && isNameClash(diagnostic)) {
return Optional.of(nameClash(diagnostic.getCode(), elements));
}
if (diagnostic.getSeverity() < Diagnostic.ERROR || isMissingTypeOfTypedElement(diagnostic)) {
return Optional.empty();
}

String message = diagnostic.getMessage();
for (EObject element : elements) {
message = message.replace(element.toString(), EcoreLocations.elementPath(element));
}
EObject element = elements.isEmpty() ? null : elements.get(0);
String hint = null;
if (EcoreValidator.DIAGNOSTIC_SOURCE.equals(diagnostic.getSource())) {
switch (diagnostic.getCode()) {
case EcoreValidator.WELL_FORMED_NAME ->
hint =
"Names must be valid Java identifiers: letters, digits and '_', not starting with"
+ " a digit";
case EcoreValidator.WELL_FORMED_INSTANCE_TYPE_NAME -> {
if (message.contains("'null'")) {
message = "the data type has no instance type name";
}
hint =
"Set the instance type name to a Java type such as java.lang.String, or use an"
+ " Ecore data type such as EString instead";
}
case EcoreValidator.VALID_TYPE ->
hint =
"Set the type, e.g. EString for an attribute or a class of the metamodels for a"
+ " reference";
case EcoreValidator.UNIQUE_FEATURE_NAMES ->
hint = "Features are inherited from the super types; rename one of them";
case EcoreValidator.UNIQUE_CLASSIFIER_NAMES,
EcoreValidator.UNIQUE_ENUMERATOR_NAMES,
EcoreValidator.UNIQUE_SUBPACKAGE_NAMES ->
hint = "Rename one of them";
case EcoreValidator.NO_CIRCULAR_SUPER_TYPES ->
hint = "Remove the super type that leads back to this class";
case EcoreValidator.INTERFACE_IS_ABSTRACT ->
hint = "Make the class abstract as well, or clear 'interface'";
case EcoreValidator.CONSISTENT_OPPOSITE_NOT_FROM_TYPE,
EcoreValidator.CONSISTENT_OPPOSITE_NOT_MATCHING ->
hint =
"Set the opposite of both references to each other; each must point to the class"
+ " that declares the other";
case EcoreValidator.CONSISTENT_OPPOSITE_BOTH_CONTAINMENT ->
hint = "Make only one of the two references a containment";
case EcoreValidator.CONSISTENT_OPPOSITE_BAD_TRANSIENT ->
hint = "Make the opposite reference transient as well";
case EcoreValidator.CONSISTENT_UNIQUE -> hint = "Set 'unique' to true";
case EcoreValidator.CONSISTENT_TYPE_CLASS_REQUIRED ->
hint = "A reference must point to a class; use an attribute for data types";
case EcoreValidator.CONSISTENT_TYPE_CLASS_NOT_PERMITTED ->
hint = "An attribute must have a data type; use a reference to point to a class";
default -> {
// the message is all there is
}
}
}
return Optional.of(new Finding(element, message, hint));
}

/** EcoreValidator warns about names that differ only in case or '_'; EMF code clashes. */
private static boolean isNameClash(Diagnostic diagnostic) {
return EcoreValidator.DIAGNOSTIC_SOURCE.equals(diagnostic.getSource())
&& (diagnostic.getCode() == EcoreValidator.UNIQUE_FEATURE_NAMES
|| diagnostic.getCode() == EcoreValidator.UNIQUE_CLASSIFIER_NAMES
|| diagnostic.getCode() == EcoreValidator.UNIQUE_ENUMERATOR_NAMES);
}

/**
* The data of a name clash is the owner (class, package, or enum) followed by the clashing
* elements; features may be inherited from super types.
*/
private static Finding nameClash(int code, List<EObject> elements) {
EObject owner = elements.get(0);
List<ENamedElement> clashing =
elements.subList(1, elements.size()).stream()
.filter(ENamedElement.class::isInstance)
.map(ENamedElement.class::cast)
.toList();
// the last clashing element declared by the owner itself, else the owner
EObject located =
clashing.stream()
.filter(element -> element.eContainer() == owner)
.map(EObject.class::cast)
.reduce((first, second) -> second)
.orElse(owner);
String message =
String.format(
"the %s %s differ only in upper/lower case or '_', so their generated Java names"
+ " clash",
clashKind(code),
String.join(
" and ", clashing.stream().map(element -> "'" + element.getName() + "'").toList()));
return new Finding(
located,
message,
code == EcoreValidator.UNIQUE_FEATURE_NAMES
? "Rename one of them; features of the super types count as well"
: "Rename one of them");
}

private static String clashKind(int code) {
switch (code) {
case EcoreValidator.UNIQUE_FEATURE_NAMES:
return "features";
case EcoreValidator.UNIQUE_ENUMERATOR_NAMES:
return "enum literals";
default:
return "classifiers";
}
}

/** "The required feature 'eAttributeType' … must be set" repeats "must have a type". */
private static boolean isMissingTypeOfTypedElement(Diagnostic diagnostic) {
return diagnostic.getData().contains(EcorePackage.Literals.EATTRIBUTE__EATTRIBUTE_TYPE)
|| diagnostic.getData().contains(EcorePackage.Literals.EREFERENCE__EREFERENCE_TYPE);
}

private static boolean isEcoreMetamodel(EObject object) {
return EcoreUtil.getRootContainer(object) == EcorePackage.eINSTANCE;
}
}
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
package tools.vitruv.methodologist.setup.vsum.service.metamodel;

import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.eclipse.emf.ecore.ENamedElement;
import org.eclipse.emf.ecore.EObject;
import tools.vitruv.methodologist.setup.vsum.service.problem.Excerpts;

/**
Expand Down Expand Up @@ -37,4 +40,33 @@ public static Integer lineOf(String text, List<String> namePath) {
}
return line;
}

/**
* Names from the root package down to the element.
*
* @param element an element of a metamodel
* @return e.g. {@code [model, Component, name]}
*/
public static List<String> namePath(EObject element) {
List<String> names = new ArrayList<>();
for (EObject current = element; current != null; current = current.eContainer()) {
if (current instanceof ENamedElement named && named.getName() != null) {
names.add(0, named.getName());
}
}
return names;
}

/**
* Readable name of an element within its metamodel.
*
* @param element an element of a metamodel
* @return e.g. {@code Component.name}; the package name only for the root package
*/
public static String elementPath(EObject element) {
List<String> names = namePath(element);
return names.size() > 1
? String.join(".", names.subList(1, names.size()))
: String.join(".", names);
}
}
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package tools.vitruv.methodologist.setup.vsum.service.metamodel;

import java.util.List;
import org.eclipse.emf.ecore.EPackage;

/**
* A metamodel that was validated and placed into the generated project, together with its generated
Expand All @@ -11,19 +12,40 @@
* @param ecoreFileName file name of the ecore inside the project's ecore directory
* @param genmodelFileName file name of the genmodel inside the project's ecore directory
* @param packages all packages EMF generates code for, including sub-packages
* @param ePackage the loaded root package, for checking the reactions against it; {@code null} if
* not available
*/
public record GeneratedMetamodel(
String name,
String nsUri,
String ecoreFileName,
String genmodelFileName,
List<GeneratedPackage> packages) {
List<GeneratedPackage> packages,
EPackage ePackage) {

/** Makes the package list immutable. */
public GeneratedMetamodel {
packages = List.copyOf(packages);
}

/**
* Describes a metamodel without its loaded package.
*
* @param name name of the root EPackage
* @param nsUri namespace URI of the root EPackage
* @param ecoreFileName file name of the ecore inside the project's ecore directory
* @param genmodelFileName file name of the genmodel inside the project's ecore directory
* @param packages all packages EMF generates code for, including sub-packages
*/
public GeneratedMetamodel(
String name,
String nsUri,
String ecoreFileName,
String genmodelFileName,
List<GeneratedPackage> packages) {
this(name, nsUri, ecoreFileName, genmodelFileName, packages, null);
}

/**
* A package for which EMF generates a {@code Package} interface.
*
Expand Down
Loading
Loading