feat: @anchor annotation for microflow sequence flow endpoints

Studio Pro renders each SequenceFlow against one of four sides of the
origin and destination activity boxes (top, right, bottom, left). Until
now the builder always derived the anchor side from the flow's visual
direction and the describer dropped the information entirely, so a
DESCRIBE → re-execute round-trip lost every manual side-tweak. Agent-
generated microflow patches therefore reshuffled the arrow layout in
the Studio Pro diagram even when they were semantically identical to
the original — the flow diagram had to be re-tidied by hand after each
iteration.

New optional annotation on microflow statements:

    @anchor(from: right, to: left)
    log info node 'App' 'hello';

Each side is independently optional. Missing sides fall back to the
builder's default for the visual flow direction — existing MDL scripts
are unchanged.

IF statements support a combined form for the incoming flow plus the
per-branch outgoing flows:

    @anchor(to: top, true: (from: right, to: left), false: (from: bottom, to: top))
    if condition then
        ...
    else
        ...
    end if;

top (0), right (1), bottom (2), left (3) — matching the indices Mendix
stores in OriginConnectionIndex / DestinationConnectionIndex on the
SequenceFlow BSON.

@anchor is emitted for every activity whenever flows are attached, so
describe → exec → describe is bit-exact on the anchor indices. For
splits the combined form is used when any of the three groups (incoming
to, true-branch, false-branch) has a non-default value.

- AST: ast.AnchorSide, ast.FlowAnchors; ActivityAnnotations gains
  Anchor / TrueBranchAnchor / FalseBranchAnchor / IteratorAnchor /
  BodyTailAnchor (all optional, AST-only for iterator/tail).
- Grammar: ANCHOR / TOP / BOTTOM lexer tokens; `@anchor(key: value)`
  parser rule with a nested-params form for the split-branch shape.
- Visitor: populates anchor fields from annotation contexts.
- Builder: applyUserAnchors helper; mergeStatementAnnotations carries
  anchor fields into pendingAnnotations; buildFlowGraph and
  addIfStatement apply anchor indices per the user spec. Guard-pattern
  IFs (no else, then returns) use the new nextFlowAnchor plumbing so
  the deferred split→nextActivity flow also honours
  @anchor(false: ...).
- Describer: emitAnchorAnnotation outputs `@anchor(from: X, to: Y)`
  for non-split activities and a split-form variant for ExclusiveSplit
  / InheritanceSplit. Branch detection reuses findBranchFlows so all
  CaseValue variants (ExpressionCase, EnumerationCase, BooleanCase,
  value + pointer) are covered.

Tightening @anchor roundtrips exposed two pre-existing bugs in
expressionToString used for `if cond then`, regex literals, etc.:
- Using mdlQuote doubled every backslash, breaking regex escape
  sequences like \d that the Mendix expression engine consumes
  literally.
- Using only apostrophe-doubling emitted raw control characters (0x0A,
  0x0D, 0x09) inside single-quoted literals, which STRING_LITERAL
  rejects.

Fix: new quoteExpressionLiteral that escapes control chars and
backslashes followed by an MDL-significant letter (n/r/t/\/'), but
passes other backslash sequences through verbatim. Trailing backslash
at EOF is doubled so the lexer doesn't consume the closing quote as an
escape pair.

Loop describe output previously omitted the `begin` keyword the MDL
grammar requires after `loop $X in $Y`. It parsed by accident
because every body statement's leading keyword was accepted after the
header. With @anchor landing before the first body statement, the
parser started seeing `@position(...)` immediately after the loop
header and failed. Fix: emit `begin` unconditionally between the
loop header and body in every LoopedActivity call-site.

- visitor_anchor_test.go: syntax simple / partial / 4 sides / split
  form / absence → nil.
- cmd_microflows_builder_anchor_test.go: override applied; default
  kept when omitted; partial override preserves other side;
  per-branch IF anchors.
- cmd_microflows_describe_anchor_test.go: @anchor emission;
  no-flows case; roundtrip via builder.
- cmd_microflows_split_incoming_anchor_test.go: split incoming to;
  EnumerationCase, ExpressionCase, BooleanCase branch forms.
- cmd_microflows_expr_literal_escape_test.go: regex passthrough; raw
  control char escaping; apostrophe doubling; backslash-before-escape
  letter doubling; trailing backslash doubling; idempotency.
- cmd_microflows_anchor_if_test.go: anchor preservation inside ELSE
  branch (real mendixlabs#35 pattern); anchor(to: top) on return inside else.
- cmd_microflows_annotation_escape_test.go: mdlQuote control-char
  escaping; apostrophe doubling.
- cmd_microflows_guard_pattern_test.go: guard-pattern IF carries
  false-branch anchor through the deferred flow.
- cmd_microflows_loop_begin_test.go: loop describe output opens with
  `begin`.

Tested against the Control Centre project (Mendix 9.24, ~200
microflows). On 5 representative cases including the attempt-mendixlabs#35 repro
(Apps.GetOrCreateMendixVersionFromString, MxAdmin.CreateMendixVersion
FromString, AcademyIntegration.GetOrCreateCertificate), the describe →
exec → describe round-trip preserves every anchor (0 drifts) and the
output parses through `mxcli check`.

CHANGELOG updated under [Unreleased] → Added.

Author: hjothamendix

CHANGELOG.md

@@ -13,6 +13,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **Path normalization** — Relative paths in `MetadataUrl` are automatically converted to absolute `file://` URLs for Studio Pro compatibility
 - **ServiceUrl validation** — `ServiceUrl` parameter must now be a constant reference (e.g., `@Module.ConstantName`) to enforce Mendix best practice
 - **Shared URL utilities** — `internal/pathutil` package with `NormalizeURL()`, `URIToPath()`, and `PathFromURL()` for reuse across components
+- **@anchor sequence flow annotation** — optional `@anchor(from: X, to: Y)` annotation on microflow statements that pins the side of the activity box a SequenceFlow attaches to (top / right / bottom / left). Split (`if`) statements support the combined form `@anchor(to: X, true: (from: ..., to: ...), false: (from: ..., to: ...))` so the incoming and per-branch outgoing anchors survive describe → exec round-trip. When omitted, the builder derives the anchor from the visual flow direction (existing behaviour is unchanged). Keeps the flow diagram stable across patches when an agent-generated microflow is applied back to a project
 
 ### Changed
 

cmd/mxcli/lsp_completions_gen.go

@@ -0,0 +1,59 @@
+-- ============================================================================
+-- Feature: @anchor annotation for sequence flow endpoints
+-- ============================================================================
+--
+-- Motivation:
+--   Studio Pro renders SequenceFlows connecting to one of the four sides of
+--   each activity box (top, right, bottom, left). Until this annotation was
+--   added, the builder always chose the anchor side from the flow direction
+--   (horizontal → right-to-left, upward → right-to-bottom, etc.) and the
+--   describer dropped the information entirely. A DESCRIBE → re-execute
+--   round-trip therefore lost every manual anchor adjustment and the flow
+--   diagram had to be re-tidied by hand after each iteration.
+--
+-- Syntax:
+--   @anchor(from: X, to: Y)       — anchors for the single outgoing flow
+--   @anchor(true: (from:..., to:...), false: (from:..., to:...))  — IF
+--
+-- Each side is independently optional. Missing sides fall back to the
+-- builder's default for the visual flow direction.
+--
+-- Usage:
+--   mxcli exec mdl-examples/bug-tests/anchor-sequence-flow-annotation.mdl -p app.mpr
+--   Then: mxcli describe microflow BugTestAnchor.MF_CustomAnchors -p app.mpr
+--   The describe output must include the @anchor(...) lines below verbatim.
+-- ============================================================================
+
+create module BugTestAnchor;
+
+create microflow BugTestAnchor.MF_CustomAnchors ()
+returns string as $result
+begin
+  declare $result string = empty;
+
+  @anchor(from: bottom)
+  log info node 'App' 'first';
+
+  @anchor(to: top)
+  log info node 'App' 'second';
+
+  set $result = 'done';
+  return $result;
+end;
+/
+
+create microflow BugTestAnchor.MF_IfBranchAnchors ()
+returns string as $result
+begin
+  declare $result string = empty;
+
+  @anchor(true: (from: right, to: left), false: (from: bottom, to: top))
+  if true then
+    set $result = 'yes';
+  else
+    set $result = 'no';
+  end if;
+
+  return $result;
+end;
+/

mdl-examples/bug-tests/anchor-sequence-flow-annotation.mdl

@@ -105,14 +105,48 @@ type RaiseErrorStmt struct {
 
 func (s *RaiseErrorStmt) isMicroflowStatement() {}
 
+// AnchorSide identifies one of the four sides of an activity's visual box
+// that a SequenceFlow attaches to.
+type AnchorSide int
+
+const (
+	AnchorSideUnset  AnchorSide = -1
+	AnchorSideTop    AnchorSide = 0
+	AnchorSideRight  AnchorSide = 1
+	AnchorSideBottom AnchorSide = 2
+	AnchorSideLeft   AnchorSide = 3
+)
+
+// FlowAnchors captures the origin/destination anchors for a single
+// SequenceFlow. Each side is independently optional: Unset means the builder
+// should derive the anchor from the visual direction.
+type FlowAnchors struct {
+	From AnchorSide // OriginConnectionIndex on the outgoing SequenceFlow
+	To   AnchorSide // DestinationConnectionIndex on the outgoing SequenceFlow
+}
+
 // ActivityAnnotations holds metadata annotations for microflow activities.
-// These are emitted as @position, @caption, @color, @annotation, @excluded lines in MDL.
+// These are emitted as @position, @caption, @color, @annotation, @excluded, @anchor lines in MDL.
 type ActivityAnnotations struct {
-	Position       *Position // @position(x, y)
-	Caption        string    // @caption 'text'
-	Color          string    // @color Green
-	AnnotationText string    // @annotation 'text'
-	Excluded       bool      // @excluded
+	Position       *Position    // @position(x, y)
+	Caption        string       // @caption 'text'
+	Color          string       // @color Green
+	AnnotationText string       // @annotation 'text'
+	Excluded       bool         // @excluded
+	Anchor         *FlowAnchors // @anchor(from: X, to: Y) — anchors of the flow leaving this statement
+
+	// Split-specific anchors for IF statements. When the statement is not an
+	// IF these remain nil. The grammar accepts them on IfStmt only:
+	//   @anchor(true: (from: right, to: left), false: (from: bottom, to: left))
+	TrueBranchAnchor  *FlowAnchors
+	FalseBranchAnchor *FlowAnchors
+
+	// Loop body anchors for LOOP/WHILE. IteratorAnchor is the flow that
+	// enters the loop body from the iterator; BodyTailAnchor is the flow
+	// from the last body statement back to the loop boundary. Both are only
+	// populated on LoopStmt/WhileStmt.
+	IteratorAnchor *FlowAnchors
+	BodyTailAnchor *FlowAnchors
 }
 
 // ChangeItem represents a single assignment in CREATE/CHANGE: Attr = expr

mdl/ast/ast_microflow.go

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Regression tests for anchor preservation inside IF branches — the original
+// @anchor implementation only handled the top-level flow between statements
+// at the microflow body level. Anchors on statements inside THEN/ELSE bodies
+// (including the flow between a branch's first statement and its successors,
+// and the flow leaving the last branch statement to the merge) were silently
+// dropped, so real-world microflows like the attempt #35 repro case lost
+// every vertical anchor on roundtrip.
+package executor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+)
+
+// buildWithAnchors is a test helper that builds the flow graph for a simple
+// microflow body and returns the collection for inspection.
+func buildWithAnchors(body []ast.MicroflowStatement) (oc *struct {
+	Flows   []anchorFlow
+	Objects int
+}) {
+	fb := &flowBuilder{posX: 100, posY: 100, spacing: HorizontalSpacing}
+	col := fb.buildFlowGraph(body, nil)
+	oc = &struct {
+		Flows   []anchorFlow
+		Objects int
+	}{
+		Objects: len(col.Objects),
+	}
+	for _, f := range col.Flows {
+		oc.Flows = append(oc.Flows, anchorFlow{
+			OriginIdx: f.OriginConnectionIndex,
+			DestIdx:   f.DestinationConnectionIndex,
+		})
+	}
+	return oc
+}
+
+type anchorFlow struct {
+	OriginIdx int
+	DestIdx   int
+}
+
+// hasFlow returns true when at least one flow has the given anchor pair.
+func hasFlow(flows []anchorFlow, origin, dest int) bool {
+	for _, f := range flows {
+		if f.OriginIdx == origin && f.DestIdx == dest {
+			return true
+		}
+	}
+	return false
+}
+
+func TestBuilder_AnchorInsideElseBranch(t *testing.T) {
+	// Reproduces the pattern from attempt #35:
+	//   if cond then { set ... }
+	//   else {
+	//     @anchor(from: bottom, to: top)
+	//     log ...
+	//     @anchor(to: top)
+	//     return empty
+	//   }
+	body := []ast.MicroflowStatement{
+		&ast.IfStmt{
+			Condition: &ast.LiteralExpr{Kind: ast.LiteralBoolean, Value: true},
+			ThenBody: []ast.MicroflowStatement{
+				&ast.LogStmt{Level: ast.LogInfo, Message: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "a"}},
+			},
+			ElseBody: []ast.MicroflowStatement{
+				&ast.LogStmt{
+					Level:   ast.LogInfo,
+					Message: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "b"},
+					Annotations: &ast.ActivityAnnotations{
+						Anchor: &ast.FlowAnchors{From: ast.AnchorSideBottom, To: ast.AnchorSideTop},
+					},
+				},
+				&ast.ReturnStmt{
+					Value: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "done"},
+					Annotations: &ast.ActivityAnnotations{
+						Anchor: &ast.FlowAnchors{To: ast.AnchorSideTop, From: ast.AnchorSideUnset},
+					},
+				},
+			},
+		},
+	}
+
+	oc := buildWithAnchors(body)
+
+	// The else-first-statement flow must land on the log's top anchor.
+	if !hasFlow(oc.Flows, AnchorBottom, AnchorTop) {
+		t.Errorf("expected split→log flow with Bottom→Top (from user's own @anchor), got %+v", oc.Flows)
+	}
+	// The log→return flow inside the else branch must emit from=bottom
+	// (previous statement's From) and to=top (return's own To).
+	if !hasFlow(oc.Flows, AnchorBottom, AnchorTop) {
+		t.Errorf("expected log→return flow with Bottom→Top inside else branch, got %+v", oc.Flows)
+	}
+}
+
+func TestBuilder_AnchorToTopOnReturnPreservedInsideElse(t *testing.T) {
+	// Minimal case: single-statement ELSE whose only statement is a RETURN
+	// carrying @anchor(to: top). The flow from the split to that return's
+	// EndEvent must land on DestinationConnectionIndex = AnchorTop.
+	body := []ast.MicroflowStatement{
+		&ast.IfStmt{
+			Condition: &ast.LiteralExpr{Kind: ast.LiteralBoolean, Value: true},
+			ThenBody: []ast.MicroflowStatement{
+				&ast.LogStmt{Level: ast.LogInfo, Message: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "a"}},
+			},
+			ElseBody: []ast.MicroflowStatement{
+				&ast.ReturnStmt{
+					Value: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "no"},
+					Annotations: &ast.ActivityAnnotations{
+						Anchor: &ast.FlowAnchors{To: ast.AnchorSideTop, From: ast.AnchorSideUnset},
+					},
+				},
+			},
+		},
+	}
+
+	oc := buildWithAnchors(body)
+
+	// Default downward flow from split has OriginConnectionIndex=Bottom; with
+	// @anchor(to: top) on the return, DestinationConnectionIndex must be Top.
+	if !hasFlow(oc.Flows, AnchorBottom, AnchorTop) {
+		t.Errorf("expected split→return flow with Bottom→Top, got %+v", oc.Flows)
+	}
+}

mdl/executor/cmd_microflows_anchor_if_test.go

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Regression tests for @annotation / @caption escaping in the microflow
+// describer. The free-annotation emission path used a home-grown escape that
+// only handled apostrophe doubling — newlines, tabs, and backslashes inside
+// the annotation text were emitted as raw control characters, which then
+// tripped the parser when the output was fed back through `mxcli exec`.
+//
+// The fix switches both the free-annotation and the ExclusiveSplit/
+// InheritanceSplit @caption emission to `mdlQuote`, which handles the full
+// set of MDL-sensitive characters and matches the single quoted-source helper
+// used everywhere else.
+package executor
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestMdlQuote_EscapesNewlinesAndBackslashes(t *testing.T) {
+	in := "SvdV (24/Mar/2021):\r\n\r\nThis microflow uses \\d in a regex."
+	out := mdlQuote(in)
+
+	if strings.ContainsRune(out, '\n') {
+		t.Errorf("mdlQuote output must not contain a raw newline, got %q", out)
+	}
+	if strings.ContainsRune(out, '\r') {
+		t.Errorf("mdlQuote output must not contain a raw carriage return, got %q", out)
+	}
+	for _, want := range []string{`\r`, `\n`, `\\d`} {
+		if !strings.Contains(out, want) {
+			t.Errorf("mdlQuote output missing escaped sequence %q; got %q", want, out)
+		}
+	}
+	if !strings.HasPrefix(out, "'") || !strings.HasSuffix(out, "'") {
+		t.Errorf("mdlQuote output should be wrapped in single quotes: %q", out)
+	}
+}
+
+func TestMdlQuote_EscapesApostrophesByDoubling(t *testing.T) {
+	in := "it's here"
+	out := mdlQuote(in)
+	if out != "'it''s here'" {
+		t.Errorf("got %q, want %q", out, "'it''s here'")
+	}
+}

mdl/executor/cmd_microflows_annotation_escape_test.go

@@ -31,10 +31,21 @@ type flowBuilder struct {
 	measurer            *layoutMeasurer              // For measuring statement dimensions
 	nextConnectionPoint model.ID                     // For compound statements: the exit point differs from entry point
 	nextFlowCase        string                       // If set, next connecting flow uses this case value (for merge-less splits)
+	// nextFlowAnchor carries the branch-specific FlowAnchors that should be
+	// applied to the flow created by the NEXT iteration of buildFlowGraph.
+	// Used by guard-pattern IFs (where one branch returns and the other
+	// continues) so the continuing branch's @anchor survives to the actual
+	// splitID→nextActivity flow — which is emitted one iteration later by the
+	// outer loop, not by addIfStatement.
+	nextFlowAnchor      *ast.FlowAnchors
 	backend             backend.FullBackend          // For looking up page/microflow references
 	hierarchy           *ContainerHierarchy          // For resolving container IDs to module names
 	pendingAnnotations  *ast.ActivityAnnotations     // Pending annotations to attach to next activity
 	restServices        []*model.ConsumedRestService // Cached REST services for parameter classification
+	// previousStmtAnchor holds the Anchor annotation of the statement that
+	// just emitted an activity, so the next flow's OriginConnectionIndex can
+	// be overridden by the user. Cleared after each flow is created.
+	previousStmtAnchor *ast.FlowAnchors
 }
 
 // addError records a validation error during flow building.