fix(describe): read view-entity OQL from source document on modelsdk (11.x)

DESCRIBE of a view entity on the default (modelsdk) engine omitted the
`as (… OQL …)` clause — the describe→exec round-trip silently dropped the query.

On Mendix 11.0+ a view entity's OQL is stored ONLY in its separate
DomainModels$ViewEntitySourceDocument; the inline OqlViewEntitySource.Oql field
was removed (the writer already gates this with `if !pv.IsAtLeast(11,0)`). The
modelsdk read only read the now-empty inline field via src.Oql() and never
followed SourceDocumentRef, so OqlQuery came back empty and the describer skipped
the clause. Legacy was correct — loadViewEntityOqlQueries already joins the
source docs.

Fix: populateViewEntityOql lists the ViewEntitySourceDocument units, maps
moduleName.docName → Oql(), and fills OqlQuery for any view entity that has an
empty OqlQuery + a SourceDocumentRef. Wired into ListDomainModels and
GetDomainModel, guarded by a cheap pre-check so non-view projects pay nothing.

Verified: DESCRIBE now emits the OQL and re-execs (create or modify) cleanly, on
both the fixture and the chart example's views.

Test: TestGetDomainModel_ViewEntityOqlFromSourceDocument (round-trips via
GetDomainModel and ListDomainModels).

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

Author: ako

.claude/skills/fix-issue.md

@@ -138,6 +138,7 @@ to the symptom table below, so the next similar issue costs fewer reads.
 | A `dynamictext` contentparam (or DataGrid2 column) navigating an association still fails mxbuild **CE0402 "No value specified"** — the *actually unsolved* Bug 3 case. Reproduces only when the widget's entity context is a **specialization** of the entity that declares the association: a grid over `SpecialExpense extends Expense` with `contentparams: [{1} = Expense_Employee/Name]` (the `Expense_Employee` association is on the base `Expense`). An exact-endpoint context (grid over `Expense`) works. `describe` shows `[{1} = <unbound>]`; the binding is dropped. **Very common in real apps** (entities inherit from a base, associations on the base) — which is why the earlier fixes looked incomplete | `resolveAssociationAttributePath` → `associationDestination` matched the context against the association's FROM/TO **by exact string equality**. A subclass context equalled neither endpoint, so it returned `ok=false` and the caller fell back to the flat, unresolvable `Assoc/Attr` path → no valid AttributeRef → CE0402. Affects both engines (shared builder) and both the contentparam and Bug 7 column-attribute paths | `mdl/executor/cmd_pages_builder_v3.go` (`associationDestination`, new `entityIsOrDescendsFrom` + `entityGeneralizations`) | Match the endpoint the context **is or descends from**: walk the generalization chain (`Entity.GeneralizationRef`, qualified parent name) so an association declared on a base entity resolves from a subclass context. Diagnose association-binding drops by checking whether the widget's entity context exactly equals the association endpoint — inheritance is the usual culprit. mxbuild-verified 0 errors across grid-over-base, listview, and grid-over-subclass. Tests: `TestResolveAssociationAttributePath_InheritedContext`; bug-test `mdl-examples/bug-tests/bug3-contentparam-inherited-association.mdl`. Bug 3 (inheritance) |
 | A documented object-list widget child keyword parse-errors: `line lRevenue (...)` inside a LineChart/TimeSeries/BubbleChart, or `scalecolor scLow (...)` inside a HeatMap → `mismatched input 'line' expecting '}'`. `series` (etc.) works | The executor side was already complete — `deriveObjectListKeyword` maps `lines`→`LINE` and `scaleColors`→`SCALECOLOR`, and `buildObjectListItem` routes any object-list child generically via the widget's `.def.json`. The **grammar** just lacked the tokens: `LINE`/`SCALECOLOR` weren't lexer tokens nor `widgetTypeV3` alternatives | `mdl/grammar/MDLLexer.g4` (token) + `mdl/grammar/domains/MDLPage.g4` (`widgetTypeV3`) + `mdl/grammar/domains/MDLSettings.g4` (`keyword` rule) | Add the token, the `widgetTypeV3` alternative (alongside `SERIES`/`MARKER`), **and** the `keyword` rule entry (so a very common word like `line` stays usable as an identifier via `identifierOrKeyword`); `make grammar`. No executor/def changes needed — `deriveObjectListKeyword` already produces the singular-uppercase keyword and the def.json carries the mapping. Verify child data lands in BSON (`Lines`/`Series` array); DESCRIBE round-trip of chart object-lists is a separate pre-existing gap (SERIES has it too). Confirmed via `mdl-examples/doctype-tests/34-chart-widget-examples.test.mdl` (exec 0 errors; `line`/`scalecolor` persist) |
 | A view entity whose attribute is named after a Mendix OQL keyword — most often a date-part word like `Quarter`/`Month`/`Year` — passes `mxcli check`/`exec` but fails **MxBuild CE0174** "The 'Quarter' part is incomplete or incorrect. You could use here: … OPEN_QUOTE, or IDENTIFIER". A `Region`/`Period` column is fine | OQL reads the bare word as the keyword, not the attribute. mxcli **cannot escape it**: the OQL grammar has no quoted-identifier form (`s."Quarter"` is a parse error — `qualifiedName`/`atomicExpression` accept only `IDENTIFIER`/`keyword`, not `QUOTED_IDENTIFIER`), and adding one is high-risk (`qualifiedName` is shared by every name in the language). The OQL is a verbatim passthrough (`RawQuery` via `extractOriginalText`), so mxcli isn't mangling it — the name itself is unusable | `mdl/executor/oql_type_inference.go` (`ValidateOQLSyntax`, `oqlReservedWords`, **MDL032**) | **Don't try to fix by quoting** (grammar blast radius) — surface it at check time instead. MDL032 (warning) scans the view OQL for a reserved word in identifier position (after `.` or `as`) and tells the user to rename. Fix for the user: rename the attribute **and its source reference** (`s.Quarter as Quarter` → `s.Period as Period`) — both sides trip CE0174. Reserved set is the date-part words (not exhaustive; SQL words like SELECT are never plausible attribute names). Tests: `TestValidateOQLSyntax_ReservedWord`. (Making quoted OQL identifiers actually work is a deferred grammar change.) |
+| `DESCRIBE` of a view entity on the **default (modelsdk)** engine omits the `as (… OQL …)` clause entirely (legacy renders it) — the describe→exec round-trip silently drops the query, leaving a queryless view. Reproduces on any Mendix **11.x** project | On Mendix 11.0+ the OQL is stored **only** in the separate `DomainModels$ViewEntitySourceDocument`; the inline `OqlViewEntitySource.Oql` field was removed (see the writer's `if !pv.IsAtLeast(11,0)` gate in `serializeOqlViewEntitySource`). The modelsdk read (`entityFromGen`: `out.OqlQuery = src.Oql()`) only read the now-empty inline field and never followed the `SourceDocumentRef`. Legacy was correct — `loadViewEntityOqlQueries` in `sdk/mpr/reader_documents.go` already joins the source docs | `mdl/backend/modelsdk/domainmodel.go` (`populateViewEntityOql`, wired into `ListDomainModels` + `GetDomainModel`) | After building the domain models, list `ViewEntitySourceDocument` units (`mprread.ListUnitsWithContainer[*genDm.ViewEntitySourceDocument]`), map `moduleName.docName → Oql()`, and fill `OqlQuery` for any view entity with an empty `OqlQuery` + a `SourceDocumentRef` (mirrors the legacy join; guarded by a cheap pre-check so non-view projects pay nothing). When a view-entity read differs between engines on 11.x, suspect a field the platform moved out-of-line into a source document. Test: `TestGetDomainModel_ViewEntityOqlFromSourceDocument` (round-trips via both read paths) |
 
 ---
 

mdl/backend/modelsdk/domainmodel.go

@@ -32,12 +32,60 @@ func (b *Backend) ListDomainModels() ([]*domainmodel.DomainModel, error) {
 	for _, u := range units {
 		out = append(out, domainModelFromGen(u.Element, u.ContainerID))
 	}
+	b.populateViewEntityOql(out)
 	// The System module is virtual (not stored in the project); inject its domain
 	// model so platform entities (System.WorkflowUserTask, User, …) resolve.
 	out = append(out, buildSystemDomainModel())
 	return out, nil
 }
 
+// populateViewEntityOql fills OqlQuery for view entities from their separate
+// DomainModels$ViewEntitySourceDocument. On Mendix 11.0+ the OQL is stored ONLY
+// in that document — the writer's version gate drops the inline
+// OqlViewEntitySource.Oml field (serializeOqlViewEntitySource), so entityFromGen
+// leaves OqlQuery empty and DESCRIBE VIEW ENTITY would omit the `as (…)` clause.
+// Follow the SourceDocumentRef here. Mirrors the legacy reader's
+// loadViewEntityOqlQueries. No-op when nothing needs it (pre-11 inline OQL, or no
+// view entities).
+func (b *Backend) populateViewEntityOql(dms []*domainmodel.DomainModel) {
+	need := false
+	for _, dm := range dms {
+		for _, e := range dm.Entities {
+			if e.SourceDocumentRef != "" && e.OqlQuery == "" {
+				need = true
+			}
+		}
+	}
+	if !need {
+		return
+	}
+	units, err := mprread.ListUnitsWithContainer[*genDm.ViewEntitySourceDocument](b.reader)
+	if err != nil {
+		return
+	}
+	oqlByQN := make(map[string]string, len(units))
+	for _, u := range units {
+		name := u.Element.Name()
+		if name == "" {
+			continue
+		}
+		mi, _ := b.reader.GetModule(string(u.ContainerID))
+		if mi == nil {
+			continue
+		}
+		oqlByQN[mi.Name+"."+name] = u.Element.Oql()
+	}
+	for _, dm := range dms {
+		for _, e := range dm.Entities {
+			if e.OqlQuery == "" && e.SourceDocumentRef != "" {
+				if oql, ok := oqlByQN[e.SourceDocumentRef]; ok {
+					e.OqlQuery = oql
+				}
+			}
+		}
+	}
+}
+
 // GetDomainModel returns the domain model whose container is moduleID.
 func (b *Backend) GetDomainModel(moduleID model.ID) (*domainmodel.DomainModel, error) {
 	units, err := mprread.ListUnitsWithContainer[*genDm.DomainModel](b.reader)
@@ -46,7 +94,9 @@ func (b *Backend) GetDomainModel(moduleID model.ID) (*domainmodel.DomainModel, e
 	}
 	for _, u := range units {
 		if u.ContainerID == moduleID {
-			return domainModelFromGen(u.Element, u.ContainerID), nil
+			dm := domainModelFromGen(u.Element, u.ContainerID)
+			b.populateViewEntityOql([]*domainmodel.DomainModel{dm})
+			return dm, nil
 		}
 	}
 	// The System module is virtual — its domain model is not stored in the project,

mdl/backend/modelsdk/view_entity_oql_read_test.go

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/sdk/domainmodel"
+)
+
+// On Mendix 11.0+ a view entity's OQL query is stored ONLY in its separate
+// DomainModels$ViewEntitySourceDocument — the inline OqlViewEntitySource.Oql
+// field was removed. The modelsdk read must follow the SourceDocumentRef and
+// repopulate OqlQuery; otherwise DESCRIBE VIEW ENTITY drops the `as (…)` clause
+// and the describe→exec round-trip loses the query. (The fixture is 11.6.6.)
+func TestGetDomainModel_ViewEntityOqlFromSourceDocument(t *testing.T) {
+	proj := copyFixture(t)
+	const oql = "select s.Name as Name from MyFirstModule.Account as s"
+
+	// Author a view entity: source document + entity referencing it.
+	b := New()
+	if err := b.Connect(proj); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	mod, err := b.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v %v", mod, err)
+	}
+	dm, err := b.GetDomainModel(mod.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModel: %v", err)
+	}
+	if _, err := b.CreateViewEntitySourceDocument(mod.ID, "MyFirstModule", "VOql", oql, ""); err != nil {
+		t.Fatalf("CreateViewEntitySourceDocument: %v", err)
+	}
+	ent := &domainmodel.Entity{
+		Name:              "VOql",
+		Persistable:       true,
+		Source:            "DomainModels$OqlViewEntitySource",
+		SourceDocumentRef: "MyFirstModule.VOql",
+		OqlQuery:          oql,
+		Attributes: []*domainmodel.Attribute{{
+			Name:  "Name",
+			Type:  &domainmodel.StringAttributeType{Length: 200},
+			Value: &domainmodel.AttributeValue{ViewReference: "Name"},
+		}},
+	}
+	if err := b.CreateEntity(dm.ID, ent); err != nil {
+		t.Fatalf("CreateEntity: %v", err)
+	}
+	if err := b.Disconnect(); err != nil {
+		t.Fatalf("disconnect: %v", err)
+	}
+
+	// Reopen (fresh read, no write-side state) and confirm OqlQuery round-trips
+	// via both GetDomainModel and ListDomainModels.
+	readBack := func(t *testing.T, get func(*Backend) (*domainmodel.DomainModel, error)) {
+		t.Helper()
+		b2 := New()
+		if err := b2.Connect(proj); err != nil {
+			t.Fatalf("reconnect: %v", err)
+		}
+		defer b2.Disconnect()
+		dm2, err := get(b2)
+		if err != nil {
+			t.Fatalf("read: %v", err)
+		}
+		var got string
+		found := false
+		for _, e := range dm2.Entities {
+			if e.Name == "VOql" {
+				found, got = true, e.OqlQuery
+			}
+		}
+		if !found {
+			t.Fatal("view entity VOql not found on read-back")
+		}
+		if got != oql {
+			t.Errorf("OqlQuery = %q, want %q (read must follow SourceDocumentRef on 11.x)", got, oql)
+		}
+	}
+
+	t.Run("GetDomainModel", func(t *testing.T) {
+		readBack(t, func(b *Backend) (*domainmodel.DomainModel, error) { return b.GetDomainModel(mod.ID) })
+	})
+	t.Run("ListDomainModels", func(t *testing.T) {
+		readBack(t, func(b *Backend) (*domainmodel.DomainModel, error) {
+			dms, err := b.ListDomainModels()
+			if err != nil {
+				return nil, err
+			}
+			for _, d := range dms {
+				if d.ContainerID == mod.ID {
+					return d, nil
+				}
+			}
+			t.Fatal("domain model not found")
+			return nil, nil
+		})
+	})
+}