Merge pull request #266 from hjotha/submit/microflow-describe-rule-split-and-free-annotations

fix: preserve rule split describer output and free annotations

Author: ako

mdl/executor/cmd_microflows_builder_control.go

@@ -127,8 +127,10 @@ func (fb *flowBuilder) addIfStatement(s *ast.IfStmt) model.ID {
 			}
 		}
 
-		// Connect THEN body to merge only if it doesn't end with RETURN
-		if !thenReturns {
+		// Connect THEN body to merge only if it doesn't end with RETURN and a merge exists.
+		// When needMerge=false, the continuing branch is wired up by the parent via
+		// nextConnectionPoint/nextFlowCase, so we must not emit a dangling flow here.
+		if !thenReturns && needMerge {
 			if lastThenID != "" {
 				fb.flows = append(fb.flows, newHorizontalFlow(lastThenID, mergeID))
 			} else {
@@ -163,8 +165,10 @@ func (fb *flowBuilder) addIfStatement(s *ast.IfStmt) model.ID {
 			}
 		}
 
-		// Connect ELSE body to merge only if it doesn't end with RETURN
-		if !elseReturns {
+		// Connect ELSE body to merge only if it doesn't end with RETURN and a merge exists.
+		// When needMerge=false, the continuing branch is handled by the parent; emitting
+		// a flow with an empty mergeID would create an orphan SequenceFlow.
+		if !elseReturns && needMerge {
 			if lastElseID != "" {
 				fb.flows = append(fb.flows, newUpwardFlow(lastElseID, mergeID))
 			}
@@ -206,8 +210,10 @@ func (fb *flowBuilder) addIfStatement(s *ast.IfStmt) model.ID {
 			}
 		}
 
-		// Connect THEN body to merge only if it doesn't end with RETURN
-		if !thenReturns {
+		// Connect THEN body to merge only if it doesn't end with RETURN and a merge exists.
+		// With no ELSE + thenReturns, needMerge=false and the FALSE path is threaded through
+		// the parent — any flow emitted here would dangle with mergeID="".
+		if !thenReturns && needMerge {
 			if lastThenID != "" {
 				fb.flows = append(fb.flows, newUpwardFlow(lastThenID, mergeID))
 			} else {

mdl/executor/cmd_microflows_format_action.go

@@ -39,12 +39,7 @@ func formatActivity(
 		return formatAction(ctx, activity.Action, entityNames, microflowNames)
 
 	case *microflows.ExclusiveSplit:
-		condition := "true"
-		if activity.SplitCondition != nil {
-			if exprCond, ok := activity.SplitCondition.(*microflows.ExpressionSplitCondition); ok {
-				condition = exprCond.Expression
-			}
-		}
+		condition := formatSplitCondition(activity.SplitCondition)
 		return fmt.Sprintf("if %s then", condition)
 
 	case *microflows.ExclusiveMerge:
@@ -1159,3 +1154,42 @@ func (e *Executor) formatListOperation(op microflows.ListOperation, outputVar st
 func (e *Executor) formatRestCallAction(a *microflows.RestCallAction) string {
 	return formatRestCallAction(e.newExecContext(context.Background()), a)
 }
+
+// formatSplitCondition renders an ExclusiveSplit's condition as an MDL expression.
+// ExpressionSplitCondition is emitted verbatim. RuleSplitCondition is rendered as
+// a rule call expression using the rule's qualified name — Mendix expressions
+// allow calling a rule the same way as a microflow, so this is re-parseable.
+// Unknown or nil conditions fall back to "true" so the describer still produces
+// valid MDL; callers should rely on the original Caption (emitted via @caption)
+// to preserve human-readable intent.
+func formatSplitCondition(cond microflows.SplitCondition) string {
+	switch c := cond.(type) {
+	case *microflows.ExpressionSplitCondition:
+		expr := strings.TrimRight(c.Expression, " \t\n\r")
+		if expr == "" {
+			return "true"
+		}
+		return expr
+	case *microflows.RuleSplitCondition:
+		name := c.RuleQualifiedName
+		if name == "" {
+			return "true"
+		}
+		args := make([]string, 0, len(c.ParameterMappings))
+		for _, pm := range c.ParameterMappings {
+			paramName := pm.ParameterName
+			if idx := strings.LastIndex(paramName, "."); idx >= 0 {
+				paramName = paramName[idx+1:]
+			}
+			arg := strings.TrimRight(pm.Argument, " \t\n\r")
+			if paramName != "" {
+				args = append(args, fmt.Sprintf("%s = %s", paramName, arg))
+			} else {
+				args = append(args, arg)
+			}
+		}
+		return fmt.Sprintf("%s(%s)", name, strings.Join(args, ", "))
+	default:
+		return "true"
+	}
+}

mdl/executor/cmd_microflows_show.go

@@ -276,6 +276,15 @@ func describeMicroflow(ctx *ExecContext, name ast.QualifiedName) error {
 	// Generate activities
 	if targetMf.ObjectCollection != nil && len(targetMf.ObjectCollection.Objects) > 0 {
 		activityLines := formatMicroflowActivities(ctx, targetMf, entityNames, microflowNames)
+		freeAnnots := collectFreeAnnotations(targetMf.ObjectCollection)
+		if len(freeAnnots) > 0 && len(activityLines) > 0 {
+			prefix := make([]string, 0, len(freeAnnots))
+			for _, text := range freeAnnots {
+				escaped := strings.ReplaceAll(text, "'", "''")
+				prefix = append(prefix, fmt.Sprintf("@annotation '%s'", escaped))
+			}
+			activityLines = append(prefix, activityLines...)
+		}
 		for _, line := range activityLines {
 			lines = append(lines, "  "+line)
 		}
@@ -533,6 +542,15 @@ func renderMicroflowMDL(
 		} else {
 			activityLines = formatMicroflowActivities(ctx, mf, entityNames, microflowNames)
 		}
+		freeAnnots := collectFreeAnnotations(mf.ObjectCollection)
+		if len(freeAnnots) > 0 && len(activityLines) > 0 {
+			prefix := make([]string, 0, len(freeAnnots))
+			for _, text := range freeAnnots {
+				escaped := strings.ReplaceAll(text, "'", "''")
+				prefix = append(prefix, fmt.Sprintf("@annotation '%s'", escaped))
+			}
+			activityLines = append(prefix, activityLines...)
+		}
 		for _, line := range activityLines {
 			lines = append(lines, "  "+line)
 		}

mdl/executor/cmd_microflows_show_helpers.go

@@ -84,6 +84,15 @@ func emitObjectAnnotations(obj microflows.MicroflowObject, lines *[]string, inde
 		}
 	}
 
+	if split, ok := obj.(*microflows.ExclusiveSplit); ok && split.Caption != "" {
+		escapedCaption := strings.ReplaceAll(split.Caption, "'", "''")
+		*lines = append(*lines, indentStr+fmt.Sprintf("@caption '%s'", escapedCaption))
+	}
+	if split, ok := obj.(*microflows.InheritanceSplit); ok && split.Caption != "" {
+		escapedCaption := strings.ReplaceAll(split.Caption, "'", "''")
+		*lines = append(*lines, indentStr+fmt.Sprintf("@caption '%s'", escapedCaption))
+	}
+
 	// @annotation (attached Annotation objects)
 	if annotationsByTarget != nil {
 		for _, caption := range annotationsByTarget[currentID] {

sdk/mpr/writer_core.go

@@ -15,6 +15,10 @@ import (
 // idToBsonBinary converts a UUID string to BSON Binary format.
 // For invalid or empty UUIDs (e.g. test placeholders), generates a random ID
 // to maintain backward compatibility with existing serialization paths.
+//
+// WARNING: an empty id here is almost always a bug (e.g. an unset pointer on a
+// SequenceFlow) and produces a random UUID that references nothing — which
+// Studio Pro surfaces as "KeyNotFoundException". Fix callers to pass a real ID.
 func idToBsonBinary(id string) primitive.Binary {
 	blob := types.UUIDToBlob(id)
 	if blob == nil || len(blob) != 16 {