R2 part 3: menus, property maps and database connections take ( ) properties and { } children (#754)

[ako]

Closes #754 (phase 3.4, R2). This is the third and last PR for the issue, after #771 (flow blocks) and #776 (integration documents). It covers what #776 listed as the remainder:

• navigation and menus;
• the property maps;
• database connections;
• the REST header list R2 part 2: integration documents take ( ) properties and { } children; alter microflow fragments are begin … end (#754) #776 left alone.

What changes

Construct	Canonical (new)	Old spelling, still parses	Code
REST operation headers	Headers: ('Accept': 'application/json')	('Accept' = 'application/json')	MDL-DEPR120
Menu children	navigation P home page M.H { menu item … menu 'X' { … } }, create menu M.M { … }	menu ( item; … ), create menu M.M ( … ), menu 'X' ( … );, and a ; after an item	MDL-DEPR121
Menu item action and icon	menu item 'Home' ( OnClick: show page M.P, Icon: I ), ( OnClick: call microflow M.F ), ( OnClick: sign out ), menu 'X' ( Icon: I ) { … }	menu item 'Home' page M.P icon I, microflow M.F, sign out, menu 'X' icon I (	MDL-DEPR122
Page and snippet header maps	Params: ( $Order: M.Order ), Variables: ( $show: Boolean = 'true' )	{ … }	MDL-DEPR123
Text-template parameters	ContentParams: ({1} = Name), also CaptionParams and <Name>Params	[{1} = Name]	MDL-DEPR124
Design properties	DesignProperties: ('Spacing': ('margin-top': 'Large'), 'Full width': on)	['Spacing': ['margin-top': 'Large'], …]	MDL-DEPR125
Snippet call arguments	Params: (Asset = $Asset)	{$Asset: $Asset} / {Asset: $Asset}	MDL-DEPR126
Database connection	create database connection M.Db ( Type: 'PostgreSQL', ConnectionString: @M.Url, Username: @M.U, Password: @M.P ) { query Q ( Sql: $$…$$, Parameters: ( p: Integer default '0', q: String null ), Returns: M.E, Map: ( Attr = column ) ) }	type '…' connection string @… username … password … begin query Q sql … parameter … returns … map (column as Attr); end	MDL-DEPR127

• The two spellings build the same AST. This is checked in three ways:

  • the registry's Example/CanonicalExample equality test;
  • a per-case reflect.DeepEqual test;
  • a check that applying the recorded rewrite reaches the canonical form.

  No BSON writer changed.

• Snippet call parameter name. The one visible AST normalisation is that a snippet call's parameter name is now stored without its $ for both spellings. $Asset and Asset used to be stored as written, and the page builder stripped the $ anyway, so written BSON is unchanged.

• Warnings and rewrites. Each old form is a registered alias marked /* @alias MDL-DEPR12x */ in the grammar. It warns under both mdl 0 and mdl 1. fmt --upgrade rewrites it structurally from the parse tree, replacing clause words and inserting punctuation, so every value, string and SQL body stays where it is. That means the gated string-escape rewrite can never overlap it.

  • sign_out inside a menu item keeps MDL-DEPR020's token rewrite. The DEPR122 rewrite inserts around that word instead of replacing it.
  • Warnings are one per statement per code, as in R2 part 2: integration documents take ( ) properties and { } children; alter microflow fragments are begin … end (#754) #776.

• describe prints the canonical forms. That covers navigation, menus, page and snippet headers, widget template parameters and design properties, REST headers and database connections. describe navigation now puts the { … } menu block after on sync error and sync ( … ). The clauses are order-free, so the old output and the new one build the same statement.

• New syntax is strict. The database connection's property list and the query properties refuse an unknown key or a value of the wrong kind. A menu item's OnClick: takes only the three actions an item can carry.

• Docs are moved to the canonical forms:

  • skills, then make sync-skills;
  • docs-site, MDL_QUICK_REFERENCE.md, the language reference and mxcli syntax entries;
  • the mxcli help text, the layout scaffold, validator hints, mdl-examples, CHANGELOG, and a "Decided in R2: three brackets, three meanings — integration documents, navigation/menus, on error, while (3.4) #754" note in the proposal.

  The .mdl files and the parseable markdown blocks were converted by applying only the visitor's own DEPR120–127 rewrites. Syntax patterns and prose were edited by hand.

Design choices the ADRs did not settle

• A navigation profile's menu items are its own { } children, as in the proposal's after-example, not menu { … }.
  • The block is parsed anywhere among the clauses, which are order-free. That is what makes the rewrite a local one: menu ( becomes {, and the block is not moved. describe writes it last.
  • The profile's clauses stay clauses: home page … [for Role], login page, not found page, on sync error and sync ( sync M.E all; … ). The proposal's ( HomePage: … ) header needs a design for role-based home pages. The sync rules would need a child shape, sync M.E ( Mode: … ). Both are left out (see follow-ups).
• The separator comes from R3/R4, not from the bracket. The proposal's "maps become ( key: value )" reads against R3 for two of the maps:
  • Params, Variables, DesignProperties and Headers set properties with :.
  • Text-template parameters bind values with =, as with ({1} = …) does (ADR-0010 R4). So ContentParams: ({1} = e) is a bracket swap only.
  • A snippet call is a call site, so its arguments are (P = $v), without the $ (R4).
• Database queries.
  • Parameters: ( name: Type [default '…' | null] ) keeps the old test-value tail as written. There is no $, because the SQL references {name}.
  • The column map is Map: ( Attr = column ). It binds the attribute the way a REST mapping side does (Attr = jsonField), which puts the two in the opposite order to the old column as Attr.
  • Type: stays a string ('PostgreSQL'), since the stored value is written verbatim and 'BYOD' is also valid. The proposal's example wrote a bare postgresql.
  • The old clause form does not mix with the new one. A connection is one form or the other.
• Design-property toggle values stay on/off. The proposal's R3 example writes 'Full width': true. That is a value change, not a bracket change, so it is not part of this PR.
• A ; after an item is still read inside either block, with a MDL-DEPR121 warning, so a half-converted menu parses.
• Codes 120–127 are from the block assigned to this item.

Test plan (what I ran)

• make build
• go test ./mdl/... ./api/... ./sdk/... ./cmd/mxcli/...: all ok.
• New tests:

  • mdl/visitor/r2_rest_test.go: 10 cases, one old spelling each: REST headers, navigation menu block, menu document, menu item clauses, page header maps, snippet header maps, template parameters, design properties (nested and empty), snippet call arguments, and database connection (two queries, default and null parameters, map). Each checks:

    • the canonical form under mdl 0 and mdl 1 with no warning;
    • the old form records its code once, only that code, and builds a DeepEqual statement;
    • the recorded rewrite reaches a script that records nothing and builds the same statement.

    Also covered: exact rewrite text for mixed menu, navigation, snippet call and database-connection forms; unknown and mistyped database-connection keys; and a menu item refusing OnClick: save changes.

  • mdl/upgrade/r2_rest_test.go: TestUpgrade_R2NavigationMapsAndDatabaseConnection. It runs one script with every old spelling mixed in single statements, in both letter cases, with a comment inside the menu. It checks the exact output, the rewrite counts, and that a second upgrade is a no-op.

  • mdl/executor/r2_rest_describe_test.go: describe output for a navigation profile, a menu, a database connection, REST headers, widget maps and a page header (mock backend). Each output re-parses with zero deprecations, and the navigation and database-connection statements round-trip field by field. Controls: a profile with no menu gains no block, and a connection with no queries ends at its property list.

  • Registry examples for DEPR120–127 are checked by TestRegistryExamplesRecordTheirCode and TestUpgrade_EveryRegistryExample.

• make test-integration-roundtrip (PedApp + TestApp): ok. No allowlist entry changed; the menu entries are Round-trip harness: untracked describe → exec losses on the Studio Pro fixture (microflows, entities, pages, snippets, menus, roles, JS actions) #721's nested-items class and still fail.
• make test-integration-upgrade (execute-both property test over the converted mdl-examples): ok.
• make check-skill-mdl: all checkable blocks pass.
• make lint: passed.

Revert checks

• Walk disabled (r2RestUse(n, use) commented out). These fail:
  • TestR2Rest_OldFormIsADeprecatedAlias
  • TestR2Rest_RewriteText
  • TestRegistryExamplesRecordTheirCode
  • TestUpgrade_R2NavigationMapsAndDatabaseConnection
  • TestUpgrade_EveryRegistryExample
• The six describe emitters restored from origin/main: all seven new describe tests fail, each reporting the matching code (DEPR121/122 for navigation and menu, 127 for both connection tests, 120 for headers, 124/125 for widget maps, 123 for the page header).

Not verified in Studio Pro: no BSON writer changed, and both spellings build the same statement. The equality tests and the execute-both property test show that.

Follow-ups (not needed to close #754's bracket rule)

• A navigation profile's header as a property list (( HomePage: …, LoginPage: …, NotFoundPage: … )), with a design for role-based home pages.
• Offline sync ( sync M.E all; … ) rules as { } children (sync M.E ( Mode: … )).
• Design-property toggle values true/false instead of on/off, as the proposal's R3 example writes them.
• An image collection's export level / comment clauses as ( … ) properties, left over from R2 part 2: integration documents take ( ) properties and { } children; alter microflow fragments are begin … end (#754) #776.

🤖 Generated with Claude Code