feat: support legacy microflow call web service statement

[hjotha]

Part of #332.

Summary

• add structured call web service MDL syntax for legacy SOAP Microflows$CallWebServiceAction
• preserve unsupported SOAP action payloads through a raw base64 BSON escape hatch
• resolve known imported SOAP service and send/receive mapping IDs to Module.Document names during describe, while keeping raw IDs as fallback
• add proposal docs, quick-reference entry, doctype example, LSP completions, and skill guidance

Validation

• make build
• ./bin/mxcli check mdl-examples/doctype-tests/call_web_service.test.mdl
• make lint-go
• make test
• make test-integration

[ako]

PR #334 Review — feat: support legacy microflow call web service statement

Overview

Large but well-structured PR. Adds full MDL round-trip support for legacy SOAP CallWebServiceAction, using a dual-mode design: a structured form that resolves/emits qualified Module.Document names, and a raw base64 escape hatch for opaque byte-for-byte preservation of unsupported SOAP payloads.

Full-stack checklist

Layer	Status
Grammar (tokens + rule)	WEB, RAW, RECEIVE added; rule in keyword list
Parser regenerated	Yes
AST node	CallWebServiceStmt with all fields
Visitor	Index-based STRING_LITERAL parsing; both structured and raw forms
Builder	addCallWebServiceAction + reference resolution helpers
Formatter	formatWebServiceCallAction; ID→QName resolution; error suffix via getActionErrorHandlingType
Parser (BSON)	parseMicroflowActionValue added to preserve primitive.D ordering; parseWebServiceCallActionFromD stores RawBSON
Writer (BSON)	serializeWebServiceCallAction; RawBSON takes priority
Tests	Visitor, builder, formatter, BSON parser/writer all covered

Issues

1. Magic value ParameterMappings: bson.A{int32(2)} needs explanation or verification

In serializeWebServiceCallAction:

{Key: "ParameterMappings", Value: bson.A{int32(2)}},

A single integer 2 in a BSON array is unusual. If this comes from actual Studio Pro-generated BSON, it needs a comment explaining what the value represents. If it is a placeholder, it may cause Studio Pro to reject the document. This should be verified against a real CallWebServiceAction exported from Studio Pro.

2. canonicalRawBSON sorts keys, breaking byte-for-byte identity in the MDL text

The function sorts BSON document keys alphabetically before encoding the base64 payload in the MDL text. This means describe → exec → describe produces a different base64 string than the original if the original had non-alphabetical key order. The write path is fine (RawBSON is preserved as-is when written to disk), but the MDL text diverges from the original, which contradicts the stated goal of "lossless round-trip". A comment explaining that canonical sorting is intentional for MDL text stability (not for disk output) would help future readers.

3. Visitor index-based STRING_LITERAL parsing is fragile

literals := callCtx.AllSTRING_LITERAL()
idx := 0
// ...advances idx conditionally for each clause

This works because the grammar enforces clause ordering (OPERATION before SEND before RECEIVE), but a grammar ambiguity fix or reorder would silently break it. Consider extracting each literal by walking the specific grammar context token (e.g., using child context rather than positional index), or at minimum add a comment that the ordering depends on the grammar production order.

4. resolveWebServiceRefForWrite name fallback skips qualified-name check

if name == ref {
    return string(unit.ID)
}

This fallback (after the GetQualifiedName check) matches on bare Name without module qualification. If two modules have a web service with the same short name, the first match wins regardless of module. The fallback exists for when hierarchy is unavailable, but a comment acknowledging the ambiguity risk would help.

5. LSP completion label for RECEIVE is "REST keyword"

RECEIVE is added under the REST keyword group in lsp_completions_gen.go. It is also used for SOAP now. Not a functional issue but might mislead users browsing completions.

Nit

In addCallWebServiceAction, ErrorHandlingType is set on both the action and the activity.BaseActivity. This is consistent with the existing pattern for other actions (e.g., RestCallAction) but is worth noting as known redundancy.

Summary

The design is sound and the test coverage is thorough. The main concern before merging is the ParameterMappings: bson.A{int32(2)} value — this needs to be verified against actual Studio Pro-generated BSON and documented if it is correct. The canonical BSON sorting and index-based visitor are acceptable with added comments.

[hjotha]

Review follow-up status:

• Documented the ParameterMappings: bson.A{int32(2)} storage-list marker in the writer.
• Added comments for canonical raw-BSON output and positional STRING_LITERAL parsing.
• Documented the ambiguous bare-name fallback in resolveWebServiceRefForWrite.
• Updated the generated LSP completion category for RECEIVE from REST-only to Service keyword because it is shared by REST and legacy SOAP syntax.

Local validation on the updated head:

make build
make test
make lint-go

[ako]

Review

Moderate: doctype example won't run in CI

mdl-examples/doctype-tests/call_web_service.test.mdl uses a .test.mdl suffix, which causes TestMxCheck_DoctypeScripts to skip it (the test suite only picks up plain .mdl files). The syntax won't be exercised by the automated doctype CI pass at all.

Fix: rename to call_web_service.mdl (or add a companion plain-.mdl file that just exercises the syntax without requiring a live project).

Relevant test filter (in roundtrip_*_test.go / TestMxCheck_DoctypeScripts):

// .test.mdl and .tests.mdl files are skipped — only plain .mdl gets CI coverage

---

Moderate: STRING_LITERAL (single-quoted) for Module.Document names is inconsistent with MDL conventions

Every other MDL command that references a document uses a bare qualifiedName token:

call microflow MyModule.MF_DoSomething(...)
show page MyModule.HomePage
describe page MyModule.HomePage
grant execute on microflow MyModule.MF_DoSomething to MyModule.User

This PR introduces a new pattern where Module.Document identifiers are embedded inside STRING_LITERAL tokens (single-quoted strings):

call web service 'SampleSOAP.OrderService'
    operation 'SampleSOAP.Operation_SendOrder'
    send mapping 'SampleSOAP.RequestMapping'
    receive mapping 'SampleSOAP.ResponseMapping'

The DESCRIBE formatter calls mdlQuote(resolveWebServiceReference(...)), which always produces '...' single-quoted output. The skill and quick-reference docs faithfully reproduce this single-quote style.

Concerns:

1. Inconsistency — readers and LLMs working from examples elsewhere in the docs will expect bare Module.Document identifiers, not single-quoted strings.
2. Roundtrip brittleness — mdlQuote() escapes apostrophes as '' (Mendix expression style). A module or document name containing an apostrophe would serialize incorrectly.
3. Future friction — if the grammar is ever extended to accept qualifiedName here (for consistency), the roundtrip format changes and existing scripts break.

Recommended fix (or at minimum, document the design choice explicitly):

Option A — change the grammar to accept qualifiedName for the structured form and keep STRING_LITERAL only for the raw legacy ID fallback:

callWebServiceStatement
    : (VARIABLE EQUALS)? CALL WEB SERVICE
      (RAW STRING_LITERAL
      | qualifiedName                            -- service as Module.Document
        (OPERATION qualifiedName)?
        (SEND MAPPING qualifiedName)?
        (RECEIVE MAPPING qualifiedName)?
        (TIMEOUT expression)?)
      onErrorClause?
    ;

Option B — if STRING_LITERAL is intentional (e.g. because service names can contain characters invalid in identifiers), add a comment in the grammar and a note in the skill explaining why this departs from the convention.

---

Positive notes

• The visitor's positional STRING_LITERAL walk is correct — it uses keyword token presence (OPERATION(), SEND(), RECEIVE()) to advance the index, which safely handles optional clauses without ambiguity.
• resolveWebServiceReference / resolveWebServiceMappingReference correctly look up module-qualified names from imported service metadata, with raw-ID fallback for unresolved cases.
• The raw BSON base64 escape hatch for unsupported SOAP payload types is a pragmatic choice that avoids data loss on roundtrip.

[hjotha]

Review follow-up status:

• Renamed the doctype example to mdl-examples/doctype-tests/call_web_service.mdl so it is picked up by the doctype CI scan.
• Documented why structured SOAP references remain quoted string literals instead of bare qualifiedName tokens: unresolved legacy IDs and SOAP document names can contain text that is not a valid MDL identifier, so quoted references are the stable authoring/fallback form.
• Added comments for the storage-list marker in ParameterMappings, canonical raw BSON text stability, and the shared RECEIVE completion category.

Local validation on the updated branch:

make build
./bin/mxcli check mdl-examples/doctype-tests/call_web_service.mdl
make test

The current build-and-test failure is the repository nanoflow integration baseline fixed separately by #412; it is not specific to this PR.

[ako]

Follow-up on STRING_LITERAL justification

The updated remark says: "SOAP document names can contain text that is not a valid MDL identifier, so quoted references are the stable authoring/fallback form."

But qualifiedName already handles that case — identifierOrKeyword accepts QUOTED_IDENTIFIER (double-quoted "..." or backtick form):

qualifiedName
    : identifierOrKeyword (DOT identifierOrKeyword)*
    ;

identifierOrKeyword
    : IDENTIFIER
    | QUOTED_IDENTIFIER   // "double-quoted" or `backtick` — already in the grammar
    | keyword
    ;

So a service name with characters that aren't valid bare identifiers could be expressed as:

call web service "My Module"."My SOAP Service"
    operation "My Module"."My_Operation"

The only case where STRING_LITERAL is genuinely necessary is a raw unresolved GUID/ID like {f3a7c8b2-...} — but that's already handled by the separate RAW STRING_LITERAL path.

For the structured (resolved) form, Mendix module and document names are always valid Mendix identifiers (alphanumeric + underscore), so they would work as bare qualifiedName without quoting. The "invalid identifier characters" argument doesn't apply to the structured path, only to the raw fallback that already has its own grammar alternative.