fix: SNIPPETCALL on parameterized snippets no longer corrupts model

Closes #291. Two failure modes fixed:

1. Parameterless SNIPPETCALL against a snippet with declared parameters
   now returns a clear validation error instead of writing a null-Variable
   PageParameterMapping that crashes Studio Pro on load.

2. The Params: syntax is now fully wired end-to-end so callers can supply
   the required mappings:
     SNIPPETCALL sc (Snippet: Mod.MySnippet, Params: {Asset: $Asset})
     SNIPPETCALL sc (Snippet: Mod.MySnippet, Params: {$Asset: $Asset})
   Both bare-identifier and $-prefixed forms are accepted, including param
   names that are grammar keywords (Agent, Customer, Order, etc.).

Changes:
- Grammar: add PARAMS COLON snippetCallParamListV3 to widgetPropertyV3;
  param names use identifierOrKeyword so keywords are accepted
- AST: add SnippetCallParam type and GetSnippetParams() on WidgetV3
- Visitor: parse Params: block; buildSnippetCallParamListV3 helper
- Model: add SnippetParamMapping + ParameterMappings to SnippetCallWidget
- Parser: parseSnippet now reads Parameters from BSON so ListSnippets
  returns snippets with their declared parameters
- Executor: buildSnippetCallParams validates all declared params are
  supplied before writing BSON; error names the missing parameter
- BSON writer: replace hardcoded empty ParameterMappings array with
  real Forms$PageParameterMapping entries matching Studio Pro format
- Tests: visitor parse tests, executor unit tests (missing param, happy
  path, no-param snippet, keyword param name), doctype test in
  03-page-examples.mdl, bug-test script for issue reproduction

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ako

mdl-examples/bug-tests/snippetcall-missing-params.mdl

@@ -0,0 +1,27 @@
+-- Bug test: SNIPPETCALL on a parameterized snippet without Params should error.
+-- Issue #291: mxcli silently wrote a corrupt PageParameterMapping with null Variable.
+-- After the fix: mxcli returns a validation error when Params are omitted.
+--
+-- This script is intentionally invalid and must produce a parse/validation error.
+-- Run with: mxcli check snippetcall-missing-params.mdl
+--
+-- The correct call is:
+--   SNIPPETCALL call1 (Snippet: Mod.MySnippet, Params: {Asset: $Asset})
+
+CREATE SNIPPET Mod.MySnippet (
+  Params: { $Asset: Mod.Asset },
+  Folder: 'Snippets'
+) {
+  DYNAMICTEXT txt1 (Content: 'Hello')
+};
+
+-- The following page would previously produce a corrupt model.
+-- After fix, mxcli must reject this with:
+--   snippet Mod.MySnippet requires parameter $Asset — add Params: {Asset: $<variable>} to the SNIPPETCALL
+ALTER PAGE Mod.MyPage {
+  INSERT AFTER someWidget {
+    DATAVIEW dv1 (DataSource: $Asset) {
+      SNIPPETCALL call1 (Snippet: Mod.MySnippet)
+    }
+  }
+};

mdl-examples/doctype-tests/03-page-examples.mdl

@@ -1187,6 +1187,66 @@ create page PgTest.P016_Page_With_Snippet
   }
 }
 
+/**
+ * Page that calls a parameterized snippet with Params: mapping.
+ * Demonstrates fix for issue #291: SNIPPETCALL with Params syntax.
+ *
+ * Two forms are accepted:
+ *   Params: {Customer: $Customer}   -- bare parameter name (keywords OK)
+ *   Params: {$Customer: $Customer}  -- dollar-prefixed parameter name
+ */
+create or replace page PgTest.P017_SnippetCall_With_Params
+(
+  title: 'Customer Detail with Snippet',
+  layout: Atlas_Core.Atlas_Default,
+  params: {
+    $Customer: PgTest.Customer
+  },
+  url: 'p017_snippet_with_params',
+  folder: 'Snippets'
+)
+{
+  layoutgrid mainGrid {
+    row row1 {
+      column col1 (desktopwidth: 8) {
+        -- Call CustomerInfo snippet — bare parameter name form
+        snippetcall customerInfoSnippet (
+          snippet: PgTest.CustomerInfo,
+          params: {Customer: $Customer}
+        )
+      }
+      column col2 (desktopwidth: 4) {
+        -- Call CustomerSidebar snippet — dollar-prefixed parameter name form
+        snippetcall sidebarSnippet (
+          snippet: PgTest.CustomerSidebar,
+          params: {$Customer: $Customer}
+        )
+      }
+    }
+  }
+}
+
+-- MARK: Snippet call keyword param name
+-- Issue #291: param names that are grammar keywords (e.g. Agent, Customer) must
+-- also be accepted in bare form. Verified against test3.mpr.
+-- create or replace page AgentCommons.Test_SnippetCallParams (
+--   title: 'Snippet Params Test',
+--   layout: Atlas_Core.Atlas_Default,
+--   params: { $Agent: AgentCommons.Agent },
+--   folder: 'Private/Pages/Agent'
+-- ) {
+--   layoutgrid mainGrid {
+--     row row1 {
+--       column col1 (desktopwidth: 6) {
+--         snippetcall s1 (snippet: AgentCommons.Snippet_AgentTypeBadge, params: {$Agent: $Agent})
+--       }
+--       column col2 (desktopwidth: 6) {
+--         snippetcall s2 (snippet: AgentCommons.Snippet_AgentTypeBadge, params: {Agent: $Agent})
+--       }
+--     }
+--   }
+-- }
+
 
 
 -- MARK: Master-Detail

mdl/ast/ast_page_v3.go

@@ -254,6 +254,20 @@ func (w *WidgetV3) GetSnippet() string {
 	return w.GetStringProp("Snippet")
 }
 
+// SnippetCallParam represents one parameter mapping in a SNIPPETCALL Params: block.
+type SnippetCallParam struct {
+	ParamName string // Parameter name as written (may include leading $)
+	Variable  string // Variable being passed, always includes leading $
+}
+
+// GetSnippetParams returns the Params mappings for a SNIPPETCALL widget, or nil.
+func (w *WidgetV3) GetSnippetParams() []SnippetCallParam {
+	if v, ok := w.Properties["Params"].([]SnippetCallParam); ok {
+		return v
+	}
+	return nil
+}
+
 // GetSelection returns the Selection mode or empty string.
 func (w *WidgetV3) GetSelection() string {
 	return w.GetStringProp("Selection")

mdl/executor/cmd_pages_builder_v3_widgets.go

@@ -766,13 +766,19 @@ func (pb *pageBuilder) buildSnippetCallV3(w *ast.WidgetV3) (*pages.SnippetCallWi
 	}
 
 	// Handle Snippet property - resolve snippet and store both ID and name
-	if snippetName := w.GetSnippet(); snippetName != "" {
+	snippetName := w.GetSnippet()
+	if snippetName != "" {
 		snippetID, err := pb.resolveSnippetRef(snippetName)
 		if err != nil {
 			return nil, mdlerrors.NewBackend(fmt.Sprintf("resolve snippet %s", snippetName), err)
 		}
 		sc.SnippetID = snippetID
 		sc.SnippetName = snippetName // Store qualified name for BY_NAME_REFERENCE serialization
+
+		// Validate and wire up parameter mappings.
+		if err := pb.buildSnippetCallParams(sc, snippetName, w.GetSnippetParams()); err != nil {
+			return nil, err
+		}
 	}
 
 	if err := pb.registerWidgetName(w.Name, sc.ID); err != nil {
@@ -782,6 +788,52 @@ func (pb *pageBuilder) buildSnippetCallV3(w *ast.WidgetV3) (*pages.SnippetCallWi
 	return sc, nil
 }
 
+// buildSnippetCallParams validates the supplied param mappings against the
+// snippet's declared parameters and populates sc.ParameterMappings.
+func (pb *pageBuilder) buildSnippetCallParams(sc *pages.SnippetCallWidget, snippetQName string, supplied []ast.SnippetCallParam) error {
+	snippets, err := pb.backend.ListSnippets()
+	if err != nil {
+		return err
+	}
+
+	// Find the target snippet to read its declared parameters.
+	var targetSnippet *pages.Snippet
+	for _, s := range snippets {
+		if s.Name != "" && (s.Name == snippetQName || strings.HasSuffix(snippetQName, "."+s.Name)) {
+			targetSnippet = s
+			break
+		}
+	}
+	if targetSnippet == nil || len(targetSnippet.Parameters) == 0 {
+		// Snippet has no declared parameters — nothing to validate or map.
+		return nil
+	}
+
+	// Build a lookup of supplied mappings by parameter name (strip leading $).
+	suppliedByName := make(map[string]string, len(supplied))
+	for _, p := range supplied {
+		name := strings.TrimPrefix(p.ParamName, "$")
+		suppliedByName[name] = p.Variable
+	}
+
+	// Validate that every declared parameter has a mapping, then build the list.
+	for _, declared := range targetSnippet.Parameters {
+		argument, ok := suppliedByName[declared.Name]
+		if !ok {
+			return mdlerrors.NewValidationf(
+				"snippet %s requires parameter $%s — add Params: {%s: $<variable>} to the SNIPPETCALL",
+				snippetQName, declared.Name, declared.Name,
+			)
+		}
+		sc.ParameterMappings = append(sc.ParameterMappings, pages.SnippetParamMapping{
+			ParamName: declared.Name,
+			Argument:  argument,
+		})
+	}
+
+	return nil
+}
+
 // buildTemplateV3 creates a Container to hold template content.
 func (pb *pageBuilder) buildTemplateV3(w *ast.WidgetV3) (*pages.Container, error) {
 	container := &pages.Container{

mdl/executor/cmd_snippetcall_params_test.go

@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/backend/mock"
+	"github.com/mendixlabs/mxcli/mdl/types"
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/pages"
+)
+
+// mkSnippetWithParam creates a snippet that declares one entity-typed parameter.
+func mkSnippetWithParam(containerID model.ID, snippetName, paramName string) *pages.Snippet {
+	snp := mkSnippet(containerID, snippetName)
+	snp.Parameters = []*pages.SnippetParameter{
+		{
+			BaseElement: model.BaseElement{ID: nextID("sp")},
+			ContainerID: snp.ID,
+			Name:        paramName,
+			EntityName:  "Mod.Asset",
+		},
+	}
+	return snp
+}
+
+// newPageBuilder returns a pageBuilder wired to the given mock backend and hierarchy.
+func newPageBuilder(mb *mock.MockBackend, h *ContainerHierarchy, moduleName string) *pageBuilder {
+	var modID model.ID
+	for id, name := range h.moduleNames {
+		if name == moduleName {
+			modID = id
+			break
+		}
+	}
+	cache := &executorCache{hierarchy: h}
+	return &pageBuilder{
+		backend:          mb,
+		moduleID:         modID,
+		moduleName:       moduleName,
+		widgetScope:      make(map[string]model.ID),
+		paramScope:       make(map[string]model.ID),
+		paramEntityNames: make(map[string]string),
+		execCache:        cache,
+		widgetBackend:    mb,
+	}
+}
+
+// TestSnippetCall_MissingParam_ReturnsError verifies that placing a SNIPPETCALL
+// without the required Params yields a validation error (issue #291 — guard).
+func TestSnippetCall_MissingParam_ReturnsError(t *testing.T) {
+	mod := mkModule("Mod")
+	snp := mkSnippetWithParam(mod.ID, "MySnippet", "Asset")
+
+	h := mkHierarchy(mod)
+	withContainer(h, snp.ContainerID, mod.ID)
+
+	mb := &mock.MockBackend{
+		IsConnectedFunc:  func() bool { return true },
+		ListModulesFunc:  func() ([]*model.Module, error) { return []*model.Module{mod}, nil },
+		ListFoldersFunc:  func() ([]*types.FolderInfo, error) { return nil, nil },
+		ListSnippetsFunc: func() ([]*pages.Snippet, error) { return []*pages.Snippet{snp}, nil },
+	}
+
+	pb := newPageBuilder(mb, h, "Mod")
+	w := &ast.WidgetV3{
+		Type:       "SNIPPETCALL",
+		Name:       "sc1",
+		Properties: map[string]any{"Snippet": "Mod.MySnippet"},
+	}
+
+	_, err := pb.buildSnippetCallV3(w)
+	if err == nil {
+		t.Fatal("expected validation error for missing snippet parameter, got nil")
+	}
+	if !strings.Contains(err.Error(), "Asset") {
+		t.Errorf("error should mention missing parameter 'Asset', got: %v", err)
+	}
+}
+
+// TestSnippetCall_WithParam_Succeeds verifies that a SNIPPETCALL with correct
+// Params mapping passes validation and produces a SnippetCallWidget with mappings.
+func TestSnippetCall_WithParam_Succeeds(t *testing.T) {
+	mod := mkModule("Mod")
+	snp := mkSnippetWithParam(mod.ID, "MySnippet", "Asset")
+
+	h := mkHierarchy(mod)
+	withContainer(h, snp.ContainerID, mod.ID)
+
+	mb := &mock.MockBackend{
+		IsConnectedFunc:  func() bool { return true },
+		ListModulesFunc:  func() ([]*model.Module, error) { return []*model.Module{mod}, nil },
+		ListFoldersFunc:  func() ([]*types.FolderInfo, error) { return nil, nil },
+		ListSnippetsFunc: func() ([]*pages.Snippet, error) { return []*pages.Snippet{snp}, nil },
+	}
+
+	pb := newPageBuilder(mb, h, "Mod")
+	w := &ast.WidgetV3{
+		Type: "SNIPPETCALL",
+		Name: "sc1",
+		Properties: map[string]any{
+			"Snippet": "Mod.MySnippet",
+			"Params":  []ast.SnippetCallParam{{ParamName: "Asset", Variable: "$Asset"}},
+		},
+	}
+
+	sc, err := pb.buildSnippetCallV3(w)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(sc.ParameterMappings) != 1 {
+		t.Fatalf("ParameterMappings: want 1, got %d", len(sc.ParameterMappings))
+	}
+	if sc.ParameterMappings[0].ParamName != "Asset" {
+		t.Errorf("ParamName: want Asset, got %q", sc.ParameterMappings[0].ParamName)
+	}
+	if sc.ParameterMappings[0].Argument != "$Asset" {
+		t.Errorf("Argument: want $Asset, got %q", sc.ParameterMappings[0].Argument)
+	}
+}
+
+// TestSnippetCall_NoParam_NoSnippetParams_Succeeds verifies that a parameterless
+// snippet call against a snippet with no declared parameters works (no regression).
+func TestSnippetCall_NoParam_NoSnippetParams_Succeeds(t *testing.T) {
+	mod := mkModule("Mod")
+	snp := mkSnippet(mod.ID, "Footer") // no parameters declared
+
+	h := mkHierarchy(mod)
+	withContainer(h, snp.ContainerID, mod.ID)
+
+	mb := &mock.MockBackend{
+		IsConnectedFunc:  func() bool { return true },
+		ListModulesFunc:  func() ([]*model.Module, error) { return []*model.Module{mod}, nil },
+		ListFoldersFunc:  func() ([]*types.FolderInfo, error) { return nil, nil },
+		ListSnippetsFunc: func() ([]*pages.Snippet, error) { return []*pages.Snippet{snp}, nil },
+	}
+
+	pb := newPageBuilder(mb, h, "Mod")
+	w := &ast.WidgetV3{
+		Type:       "SNIPPETCALL",
+		Name:       "sc1",
+		Properties: map[string]any{"Snippet": "Mod.Footer"},
+	}
+
+	sc, err := pb.buildSnippetCallV3(w)
+	if err != nil {
+		t.Fatalf("unexpected error for parameterless snippet: %v", err)
+	}
+	if len(sc.ParameterMappings) != 0 {
+		t.Errorf("expected empty ParameterMappings, got %d", len(sc.ParameterMappings))
+	}
+}
+
+// TestSnippetCall_DollarPrefixParam_Succeeds verifies that param names with $
+// prefix (as the user might write $Asset: $var) are matched correctly.
+func TestSnippetCall_DollarPrefixParam_Succeeds(t *testing.T) {
+	mod := mkModule("Mod")
+	snp := mkSnippetWithParam(mod.ID, "MySnippet", "Asset")
+
+	h := mkHierarchy(mod)
+	withContainer(h, snp.ContainerID, mod.ID)
+
+	mb := &mock.MockBackend{
+		IsConnectedFunc:  func() bool { return true },
+		ListModulesFunc:  func() ([]*model.Module, error) { return []*model.Module{mod}, nil },
+		ListFoldersFunc:  func() ([]*types.FolderInfo, error) { return nil, nil },
+		ListSnippetsFunc: func() ([]*pages.Snippet, error) { return []*pages.Snippet{snp}, nil },
+	}
+
+	pb := newPageBuilder(mb, h, "Mod")
+	// User writes $Asset: $Asset (dollar-prefixed param name)
+	w := &ast.WidgetV3{
+		Type: "SNIPPETCALL",
+		Name: "sc1",
+		Properties: map[string]any{
+			"Snippet": "Mod.MySnippet",
+			"Params":  []ast.SnippetCallParam{{ParamName: "$Asset", Variable: "$Asset"}},
+		},
+	}
+
+	sc, err := pb.buildSnippetCallV3(w)
+	if err != nil {
+		t.Fatalf("unexpected error with $-prefixed param name: %v", err)
+	}
+	if len(sc.ParameterMappings) != 1 {
+		t.Fatalf("ParameterMappings: want 1, got %d", len(sc.ParameterMappings))
+	}
+	if sc.ParameterMappings[0].ParamName != "Asset" {
+		t.Errorf("ParamName: want Asset (stripped), got %q", sc.ParameterMappings[0].ParamName)
+	}
+}