Add UnknownElement fallback and table-driven parser registries (issue #19)

Stop silent data loss for unrecognized BSON $Type values. Unknown
microflow objects and workflow activities are now preserved as
UnknownElement with raw fields and inferred property kinds, instead
of being silently dropped.

- Add UnknownElement type in model/ with MicroflowObject and
  WorkflowActivity interface compliance
- Add inferPropertyKind and extractBsonArrayWithMarker helpers
- Replace switch dispatchers with table-driven registries in
  parseMicroflowObject, parseMicroflowAction, parseWorkflowActivity
- Add writer round-trip for UnknownElement in serializeMicroflowObject

Based on proposal and implementation by @engalar (engalar/mxcli@c44fe450).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ako

model/types.go

@@ -714,3 +714,35 @@ type DistributionSettings struct {
 	IsDistributable bool   `json:"isDistributable"`
 	Version         string `json:"version,omitempty"`
 }
+
+// UnknownElement is a generic fallback for BSON elements with unrecognized $Type values.
+// It preserves all raw BSON fields so developers can diagnose unimplemented types
+// without silent data loss.
+//
+// FieldKinds maps each raw field name to its inferred Mendix property kind
+// (e.g. "primitive", "part", "by-name-reference", "collection:part-primary").
+// This guides implementors in writing a proper parser without inspecting the
+// mendixmodelsdk JS source manually.
+type UnknownElement struct {
+	BaseElement
+	Position   Point             `json:"position,omitempty"`
+	Name       string            `json:"name,omitempty"`
+	Caption    string            `json:"caption,omitempty"`
+	RawFields  map[string]any    `json:"-"`
+	FieldKinds map[string]string `json:"-"`
+}
+
+// GetPosition returns the element's position (satisfies microflows.MicroflowObject).
+func (u *UnknownElement) GetPosition() Point { return u.Position }
+
+// SetPosition sets the element's position (satisfies microflows.MicroflowObject).
+func (u *UnknownElement) SetPosition(p Point) { u.Position = p }
+
+// GetName returns the element's name (satisfies workflows.WorkflowActivity).
+func (u *UnknownElement) GetName() string { return u.Name }
+
+// GetCaption returns the element's caption (satisfies workflows.WorkflowActivity).
+func (u *UnknownElement) GetCaption() string { return u.Caption }
+
+// ActivityType returns the type name (satisfies workflows.WorkflowActivity).
+func (u *UnknownElement) ActivityType() string { return u.TypeName }

sdk/mpr/parser.go

@@ -4,6 +4,7 @@ package mpr
 
 import (
 	"encoding/base64"
+	"strings"
 
 	"go.mongodb.org/mongo-driver/bson/primitive"
 )
@@ -148,3 +149,105 @@ func extractBsonSlice(v any) []any {
 	}
 	return nil
 }
+
+// BsonArrayInfo holds the extracted items and the marker from a Mendix BSON array.
+type BsonArrayInfo struct {
+	Marker int32
+	Items  []any
+}
+
+// extractBsonArrayWithMarker extracts items from a Mendix BSON array, preserving the marker.
+// Returns the marker (1, 2, or 3) and the items after the marker.
+func extractBsonArrayWithMarker(v any) BsonArrayInfo {
+	if v == nil {
+		return BsonArrayInfo{}
+	}
+
+	var slice []any
+	switch val := v.(type) {
+	case primitive.A:
+		slice = []any(val)
+	case []any:
+		slice = val
+	default:
+		return BsonArrayInfo{}
+	}
+
+	if len(slice) > 0 {
+		if marker, ok := slice[0].(int32); ok && (marker == 1 || marker == 2 || marker == 3) {
+			return BsonArrayInfo{Marker: marker, Items: slice[1:]}
+		}
+	}
+	return BsonArrayInfo{Items: slice}
+}
+
+// inferPropertyKind determines the Mendix property kind of a BSON field from its key
+// and value shape. Returns one of: "id", "type-discriminator", "by-name-reference",
+// "primitive", "part", "collection:by-name" (marker=1), "collection:part-secondary"
+// (marker=2), "collection:part-primary" (marker=3), "collection".
+// Used by UnknownElement to surface diagnostic info when an unimplemented $Type is encountered.
+func inferPropertyKind(key string, v any) string {
+	if v == nil {
+		return "primitive"
+	}
+
+	// Key-based shortcuts take priority over value shape.
+	switch key {
+	case "$ID", "$ContainerID":
+		return "id"
+	case "$Type":
+		return "type-discriminator"
+	}
+
+	switch val := v.(type) {
+	case map[string]any:
+		if _, hasType := val["$Type"]; hasType {
+			return "part"
+		}
+		if _, hasID := val["$ID"]; hasID {
+			return "part"
+		}
+		return "primitive"
+
+	case primitive.D:
+		m := val.Map()
+		if _, hasType := m["$Type"]; hasType {
+			return "part"
+		}
+		if _, hasID := m["$ID"]; hasID {
+			return "part"
+		}
+		return "primitive"
+
+	case primitive.M:
+		if _, hasType := val["$Type"]; hasType {
+			return "part"
+		}
+		if _, hasID := val["$ID"]; hasID {
+			return "part"
+		}
+		return "primitive"
+
+	case primitive.A, []any:
+		info := extractBsonArrayWithMarker(v)
+		switch info.Marker {
+		case 1:
+			return "collection:by-name"
+		case 2:
+			return "collection:part-secondary"
+		case 3:
+			return "collection:part-primary"
+		}
+		return "collection"
+
+	case string:
+		// Heuristic: qualified names like "Module.Entity" are likely by-name references.
+		if strings.Contains(val, ".") && !strings.Contains(val, " ") && !strings.Contains(val, "/") {
+			return "by-name-reference"
+		}
+		return "primitive"
+
+	default:
+		return "primitive"
+	}
+}

sdk/mpr/parser_microflow.go

@@ -245,37 +245,40 @@ func parseMicroflowObjectCollection(raw map[string]any) *microflows.MicroflowObj
 	return collection
 }
 
+// microflowObjectParsers maps Mendix $Type strings to their parser functions.
+// Adding support for a new type requires only one new entry here.
+// Declared as a nil var and populated in init() so that the map literal can
+// reference parseLoopedActivity, which itself calls parseMicroflowObjectCollection,
+// keeping the package-level initialization order unambiguous.
+var microflowObjectParsers map[string]func(map[string]any) microflows.MicroflowObject
+
+func init() {
+	microflowObjectParsers = map[string]func(map[string]any) microflows.MicroflowObject{
+		"Microflows$StartEvent":       func(r map[string]any) microflows.MicroflowObject { return parseStartEvent(r) },
+		"Microflows$EndEvent":         func(r map[string]any) microflows.MicroflowObject { return parseEndEvent(r) },
+		"Microflows$ErrorEvent":       func(r map[string]any) microflows.MicroflowObject { return parseErrorEvent(r) },
+		"Microflows$ActionActivity":   func(r map[string]any) microflows.MicroflowObject { return parseActionActivity(r) },
+		"Microflows$ExclusiveSplit":   func(r map[string]any) microflows.MicroflowObject { return parseExclusiveSplit(r) },
+		"Microflows$ExclusiveMerge":   func(r map[string]any) microflows.MicroflowObject { return parseExclusiveMerge(r) },
+		"Microflows$InheritanceSplit": func(r map[string]any) microflows.MicroflowObject { return parseInheritanceSplit(r) },
+		"Microflows$LoopedActivity":   func(r map[string]any) microflows.MicroflowObject { return parseLoopedActivity(r) },
+		"Microflows$BreakEvent":       func(r map[string]any) microflows.MicroflowObject { return parseBreakEvent(r) },
+		"Microflows$ContinueEvent":    func(r map[string]any) microflows.MicroflowObject { return parseContinueEvent(r) },
+		"Microflows$Annotation":       func(r map[string]any) microflows.MicroflowObject { return parseMicroflowAnnotation(r) },
+	}
+}
+
 // parseMicroflowObject parses a single microflow object based on its $Type.
+// Returns nil for elements with an empty $Type (corrupt or placeholder records).
 func parseMicroflowObject(raw map[string]any) microflows.MicroflowObject {
 	typeName, _ := raw["$Type"].(string)
-
-	switch typeName {
-	case "Microflows$StartEvent":
-		return parseStartEvent(raw)
-	case "Microflows$EndEvent":
-		return parseEndEvent(raw)
-	case "Microflows$ErrorEvent":
-		return parseErrorEvent(raw)
-	case "Microflows$ActionActivity":
-		return parseActionActivity(raw)
-	case "Microflows$ExclusiveSplit":
-		return parseExclusiveSplit(raw)
-	case "Microflows$ExclusiveMerge":
-		return parseExclusiveMerge(raw)
-	case "Microflows$InheritanceSplit":
-		return parseInheritanceSplit(raw)
-	case "Microflows$LoopedActivity":
-		return parseLoopedActivity(raw)
-	case "Microflows$BreakEvent":
-		return parseBreakEvent(raw)
-	case "Microflows$ContinueEvent":
-		return parseContinueEvent(raw)
-	case "Microflows$Annotation":
-		return parseMicroflowAnnotation(raw)
-	default:
-		// Unknown type - return nil or a generic object
+	if typeName == "" {
 		return nil
 	}
+	if fn, ok := microflowObjectParsers[typeName]; ok {
+		return fn(raw)
+	}
+	return newUnknownObject(typeName, raw)
 }
 
 func parseStartEvent(raw map[string]any) *microflows.StartEvent {
@@ -447,85 +450,68 @@ func parseActionActivity(raw map[string]any) *microflows.ActionActivity {
 	return activity
 }
 
-// parseMicroflowAction parses a microflow action based on its $Type.
-func parseMicroflowAction(raw map[string]any) microflows.MicroflowAction {
-	typeName, _ := raw["$Type"].(string)
-
-	switch typeName {
+// microflowActionParsers maps Mendix $Type strings to their action parser functions.
+// Storage names (e.g. CreateChangeAction) and qualified names (e.g. CreateObjectAction)
+// both map to the same parser to handle BSON format variations.
+var microflowActionParsers = map[string]func(map[string]any) microflows.MicroflowAction{
 	// Variable actions
-	case "Microflows$CreateVariableAction":
-		return parseCreateVariableAction(raw)
-	case "Microflows$ChangeVariableAction":
-		return parseChangeVariableAction(raw)
+	"Microflows$CreateVariableAction": func(r map[string]any) microflows.MicroflowAction { return parseCreateVariableAction(r) },
+	"Microflows$ChangeVariableAction": func(r map[string]any) microflows.MicroflowAction { return parseChangeVariableAction(r) },
 
 	// Object actions (storageName may differ from qualifiedName)
-	case "Microflows$CreateObjectAction", "Microflows$CreateChangeAction":
-		return parseCreateObjectAction(raw)
-	case "Microflows$ChangeObjectAction", "Microflows$ChangeAction":
-		return parseChangeObjectAction(raw)
-	case "Microflows$DeleteAction":
-		return parseDeleteAction(raw)
-	case "Microflows$CommitAction":
-		return parseCommitAction(raw)
-	case "Microflows$RollbackAction":
-		return parseRollbackAction(raw)
+	"Microflows$CreateObjectAction": func(r map[string]any) microflows.MicroflowAction { return parseCreateObjectAction(r) },
+	"Microflows$CreateChangeAction": func(r map[string]any) microflows.MicroflowAction { return parseCreateObjectAction(r) },
+	"Microflows$ChangeObjectAction": func(r map[string]any) microflows.MicroflowAction { return parseChangeObjectAction(r) },
+	"Microflows$ChangeAction":       func(r map[string]any) microflows.MicroflowAction { return parseChangeObjectAction(r) },
+	"Microflows$DeleteAction":       func(r map[string]any) microflows.MicroflowAction { return parseDeleteAction(r) },
+	"Microflows$CommitAction":       func(r map[string]any) microflows.MicroflowAction { return parseCommitAction(r) },
+	"Microflows$RollbackAction":     func(r map[string]any) microflows.MicroflowAction { return parseRollbackAction(r) },
 
 	// Retrieve actions
-	case "Microflows$RetrieveAction":
-		return parseRetrieveAction(raw)
-	case "Microflows$AggregateListAction", "Microflows$AggregateAction": // AggregateAction is storageName
-		return parseAggregateListAction(raw)
+	"Microflows$RetrieveAction":      func(r map[string]any) microflows.MicroflowAction { return parseRetrieveAction(r) },
+	"Microflows$AggregateListAction": func(r map[string]any) microflows.MicroflowAction { return parseAggregateListAction(r) },
+	"Microflows$AggregateAction":     func(r map[string]any) microflows.MicroflowAction { return parseAggregateListAction(r) },
 
 	// List actions
-	case "Microflows$CreateListAction":
-		return parseCreateListAction(raw)
-	case "Microflows$ChangeListAction":
-		return parseChangeListAction(raw)
-	case "Microflows$ListOperationAction", "Microflows$ListOperationsAction": // ListOperationsAction is storageName
-		return parseListOperationAction(raw)
+	"Microflows$CreateListAction":     func(r map[string]any) microflows.MicroflowAction { return parseCreateListAction(r) },
+	"Microflows$ChangeListAction":     func(r map[string]any) microflows.MicroflowAction { return parseChangeListAction(r) },
+	"Microflows$ListOperationAction":  func(r map[string]any) microflows.MicroflowAction { return parseListOperationAction(r) },
+	"Microflows$ListOperationsAction": func(r map[string]any) microflows.MicroflowAction { return parseListOperationAction(r) },
 
 	// Integration actions
-	case "Microflows$MicroflowCallAction":
-		return parseMicroflowCallAction(raw)
-	case "Microflows$JavaActionCallAction":
-		return parseJavaActionCallAction(raw)
-	case "Microflows$CallExternalAction":
-		return parseCallExternalAction(raw)
-
-	// Client actions
-	case "Microflows$ShowFormAction", "Microflows$ShowPageAction": // ShowFormAction is storageName
-		return parseShowPageAction(raw)
-	case "Microflows$ShowHomePageAction":
-		return parseShowHomePageAction(raw)
-	case "Microflows$CloseFormAction":
-		return parseClosePageAction(raw)
-	case "Microflows$ShowMessageAction":
-		return parseShowMessageAction(raw)
-	case "Microflows$ValidationFeedbackAction":
-		return parseValidationFeedbackAction(raw)
-	case "Microflows$DownloadFileAction":
-		return parseDownloadFileAction(raw)
+	"Microflows$MicroflowCallAction":  func(r map[string]any) microflows.MicroflowAction { return parseMicroflowCallAction(r) },
+	"Microflows$JavaActionCallAction": func(r map[string]any) microflows.MicroflowAction { return parseJavaActionCallAction(r) },
+	"Microflows$CallExternalAction":   func(r map[string]any) microflows.MicroflowAction { return parseCallExternalAction(r) },
+
+	// Client actions (ShowFormAction is storageName for ShowPageAction)
+	"Microflows$ShowFormAction":           func(r map[string]any) microflows.MicroflowAction { return parseShowPageAction(r) },
+	"Microflows$ShowPageAction":           func(r map[string]any) microflows.MicroflowAction { return parseShowPageAction(r) },
+	"Microflows$ShowHomePageAction":       func(r map[string]any) microflows.MicroflowAction { return parseShowHomePageAction(r) },
+	"Microflows$CloseFormAction":          func(r map[string]any) microflows.MicroflowAction { return parseClosePageAction(r) },
+	"Microflows$ShowMessageAction":        func(r map[string]any) microflows.MicroflowAction { return parseShowMessageAction(r) },
+	"Microflows$ValidationFeedbackAction": func(r map[string]any) microflows.MicroflowAction { return parseValidationFeedbackAction(r) },
+	"Microflows$DownloadFileAction":       func(r map[string]any) microflows.MicroflowAction { return parseDownloadFileAction(r) },
 
 	// Log action
-	case "Microflows$LogMessageAction":
-		return parseLogMessageAction(raw)
+	"Microflows$LogMessageAction": func(r map[string]any) microflows.MicroflowAction { return parseLogMessageAction(r) },
 
 	// Cast action
-	case "Microflows$CastAction":
-		return parseCastAction(raw)
+	"Microflows$CastAction": func(r map[string]any) microflows.MicroflowAction { return parseCastAction(r) },
 
 	// REST call action
-	case "Microflows$RestCallAction":
-		return parseRestCallAction(raw)
+	"Microflows$RestCallAction": func(r map[string]any) microflows.MicroflowAction { return parseRestCallAction(r) },
 
 	// Database Connector action
-	case "DatabaseConnector$ExecuteDatabaseQueryAction":
-		return parseExecuteDatabaseQueryAction(raw)
+	"DatabaseConnector$ExecuteDatabaseQueryAction": func(r map[string]any) microflows.MicroflowAction { return parseExecuteDatabaseQueryAction(r) },
+}
 
-	default:
-		// Return an unknown action placeholder with the type name
-		return &microflows.UnknownAction{TypeName: typeName}
+// parseMicroflowAction parses a microflow action based on its $Type.
+func parseMicroflowAction(raw map[string]any) microflows.MicroflowAction {
+	typeName, _ := raw["$Type"].(string)
+	if fn, ok := microflowActionParsers[typeName]; ok {
+		return fn(raw)
 	}
+	return &microflows.UnknownAction{TypeName: typeName}
 }
 
 func parseCreateVariableAction(raw map[string]any) *microflows.CreateVariableAction {

sdk/mpr/parser_unknown.go

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package mpr
+
+import "github.com/mendixlabs/mxcli/model"
+
+// newUnknownObject creates an UnknownElement that preserves raw BSON fields
+// for unrecognized $Type values, preventing silent data loss.
+// FieldKinds is populated by inferPropertyKind so callers can see the inferred
+// Mendix property kind for each field without inspecting the SDK JS source.
+func newUnknownObject(typeName string, raw map[string]any) *model.UnknownElement {
+	id := ""
+	if raw != nil {
+		id = extractBsonID(raw["$ID"])
+	}
+	elem := &model.UnknownElement{
+		BaseElement: model.BaseElement{ID: model.ID(id), TypeName: typeName},
+		RawFields:   raw,
+	}
+	if raw != nil {
+		elem.Position = parsePoint(raw["RelativeMiddlePoint"])
+		elem.Name = extractString(raw["Name"])
+		elem.Caption = extractString(raw["Caption"])
+		elem.FieldKinds = make(map[string]string, len(raw))
+		for k, v := range raw {
+			elem.FieldKinds[k] = inferPropertyKind(k, v)
+		}
+	}
+	return elem
+}