fix(describe): emit workflow annotations as comments, not statements (mendixlabs/mxcli#1007)

[ako]

Fixes mendixlabs/mxcli#1007. Stacked on #348 (same function, formatAnnotation) — base is fix/workflow-describe-quote-doubling; retarget to main once that merges.

DESCRIBE WORKFLOW emitted annotation '<text>'; — the exact construct MDL-WF04 exists to refuse, and that execCreateWorkflow refuses again. So the describer produced output mxcli's own checker rejects: 13 MDL-WF04 errors from one unmodified describe of a 23-activity workflow.

Two parts of the tree disagreed, in comments

the emitter: "The annotation is emitted as a parseable MDL statement so it survives round-trips."

the validator: it "produces a model Mendix cannot load (the annotation is placed in the activity flow, which accepts only flow elements) — Studio Pro will not open the project"

The emitter's comment was the stale one.

One correction to the issue's framing, and it changes the fix

The report reads these as canvas annotations. They aren't: formatAnnotation is called at 10 sites, always with an activity's attached Annotation, and the describer converted attached → standalone, which is the refused form.

That matters, because the issue's option 2 ("support writing annotations, relax MDL-WF04") needs a grammar change: MDLWorkflow.g4 has only the standalone workflowAnnotationStmt, so no MDL input can express an attached annotation today — even though the write path stores one (addActivityBaseFields). Commenting it out therefore loses nothing that was reachable, which is what makes option 1 honest rather than a concession.

Worth knowing: the microflow domain already solved this

MDLMicroflow.g4 has @annotation 'text' as an activity prefix and round-trips it properly. Giving workflow activities the same prefix is the non-lossy fix — the annotation would survive a rebuild instead of being commented out. That's a grammar change across every workflow activity rule, so it's a feature, deliberately not bundled here. Happy to open it as a follow-up.

Two traps in the implementation

• A -- comment runs to end of line, so a multi-line annotation must be prefixed per line, or the tail becomes stray tokens — the same failure the statement form had.
• The standalone branch must set isComment, or the terminator logic appends ; to a comment line.

Tests

Four, verified against the old emitter:

--- FAIL: TestDescribeWorkflow_AttachedAnnotationPassesOwnCheck
    describe output still trips MDL-WF04
--- FAIL: TestDescribeWorkflow_StandaloneAnnotationPassesOwnCheck
    describe output still trips MDL-WF04
--- FAIL: TestDescribeWorkflow_MultiLineAnnotationCommentsEveryLine

Each asserts the emitted MDL parses, passes ValidateWorkflow, and still contains the text — the last because dropping the annotation entirely would satisfy the first two. The fourth test (NoAnnotationEmitsNoComment) passes both before and after, on purpose: it's the control that the change adds no stray comment lines.

🤖 Generated with Claude Code