Skip to content

describe: end every statement with ';', never print '/' (#744) - #745

Merged
ako merged 16 commits into
mainfrom
feature/744-describe-terminators
Sep 27, 2026
Merged

ako merged 16 commits into
mainfrom
feature/744-describe-terminators

Conversation

@ako

@ako ako commented Sep 27, 2026

Copy link
Copy Markdown
Owner

Closes #744

describe now ends every statement with ; and never prints a SQL*Plus / line, for every document type, so its output means the same under mdl 0 and mdl 1 (ADR-0010 R11/R12, ADR-0011).

Base note: this branch is based on feature/734-retrieve-first-vs-limit (origin/main + #739, #737, #740). Until those merge the PR also shows their commits; only the last two commits are this change.

What changed

  • / lines removed from describe of agents, knowledge bases, consumed MCP services, models, constants, contract entities, associations, database connections, entities, enumerations, image collections, modules (describe module with and without with all), OData clients / services / external entities, published REST services, module roles, user roles, demo users, microflows, nanoflows and rules.
  • Missing ; added: pages, snippets and layouts end with };; workflows with end workflow;; a published OData service ends with ; after whichever of its property list, authentication clause or entity block comes last (}; for the block); an external entity without attributes ends );.
  • Published REST service with no resources now prints an empty { }; block. The block is mandatory in the grammar, so the bare ; it printed before did not parse even under mdl 0 (finding appended to mdl-executor.jsonl).
  • diff / diff-local render statements without the / line too (separate commit), so they stay comparable with describe.
  • Not changed: building-block describe (read-only, not a statement, already on the round-trip allowlist under Round-trip harness: untracked describe → exec losses on the Studio Pro fixture (microflows, entities, pages, snippets, menus, roles, JS actions) #721 G); testrunner generators and doc examples that still use / in authored scripts (valid under mdl 0; mdl 1: strict parsing (property keys, ';', no '/', '' escapes); trailing commas everywhere (#732) #741 owns the docs).

Tests

  • New mdl/roundtrip/TestPedAppDescribeIsValidMdl1 (integration): runs describe for every PedApp document the round trip enumerates, plus every module (with and without with all), navigation and settings. For each it checks on the parse tree that every statement ends with ; and none is followed by /, then re-parses the output under an mdl 1; header and expects no errors. TestDescribeTerminatorCheck is the control for the checker. 177 targets are checked; 64 are skipped because their output does not parse under mdl 0 either (allowlisted under Round-trip harness: untracked describe → exec losses on the Studio Pro fixture (microflows, entities, pages, snippets, menus, roles, JS actions) #721).
  • New mdl/executor/describe_terminators_test.go covers what PedApp does not contain: published OData service (properties only, authentication, block, grant) and external entity (with and without attributes), plus a control for the checker. The same assertTerminated check now also runs in every Describe*_Mock test for agent-editor documents, image collections, published REST, workflows, module/user roles and demo users, in the describe output that does not re-parse or loses data; configuration describe leaks DatabasePassword #707 reparse helper and in the OData client re-parse helper.
  • Checked that the fix is the cause: with the executor changes reverted, 21 executor tests fail and TestPedAppDescribeIsValidMdl1 fails on 124 documents.

Test plan

  • make build
  • make lint
  • go test ./mdl/executor/ ./cmd/mxcli/ -timeout 45m
  • go test -tags integration ./mdl/roundtrip/ -timeout 45m: passes. The allowlist is unchanged, since none of its entries were about /.
  • Throwaway local merge with origin/feature/732-strict-parsing (mdl 1: strict parsing (property keys, ';', no '/', '' escapes); trailing commas everywhere (#732) #741), not pushed:
    • go test -tags integration ./mdl/roundtrip/ -run 'TestPedAppListActivitiesUnderMdl1|TestPedAppRoundTrip_RetrieveRange|TestPedAppDescribeIsValidMdl1' passes.
    • The full roundtrip suite and ./mdl/executor/ pass.
    • With this PR's describe changes reverted on that merge, all three tests fail with `/` is not a statement terminator under mdl 1 (124 documents in the new test).

🤖 Generated with Claude Code

ako and others added 16 commits September 27, 2026 08:33
…t mandatory under mdl 1

Each Studio Pro List operation / Aggregate list activity is one statement
whose operand is a variable, so nesting cannot be written:

  $Open = filter $Orders by Status = M.Status.Open;
  $Big  = filter $Orders where $currentObject/Total > 1000;
  $N    = count $Open;
  $Csv  = reduce $Orders from '' as String using $currentResult + $currentObject/Name;

The statement forms parse under every version. The call forms keep
parsing: a respelling everywhere except find/contains, registered as
MDL-DEPR003 (list operations) and MDL-DEPR004 (aggregates), both building
the same AST. find(...)/contains(...) clash with the string functions, so
they, a list call after `set`, and a nested call are version-gated
(MDL-V1-LIST): kept and warned under mdl 0, refused under mdl 1, where
`set $x = find(...)` is always the string function. A reassignment without
`set` is refused under mdl 1 and warned under mdl 0 (MDL-V1-SET).

`where` is always Find/Filter by expression; `by` and the call form keep
the by-member reading when the condition is `Member = value`
(ast.IsMemberEquality, shared by visitor and flow builder).

Part of #733.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
describe writes the language of the newest frozen version, or of the
script it runs in when that is newer. While mdl 1 is a preview a plain
describe keeps the call form; inside an `mdl 1;` script it prints the
statement form, which executes back to the same microflow (PedApp test).

Part of #733.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…forms

Part of #733.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…lementIDs, Writer.UpdateRawUnitPatch)

TransplantIDs pairs elements by type and position, which re-pairs the
surviving flows of a patched microflow onto their neighbours' $IDs after a
drop. A write that started from the stored bytes skips it; elision and the
storage-GUID guard still apply.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e, replace, drop)

Splices a fragment into the raw stored unit: appends only the fragment's
objects and flows, rewires the flow around the target by its pointers and
the rewired end, moves nodes past the insertion point to make room, and
never rewrites an $ID. Save refuses a unit in which anything still points at
a removed element or two elements share an $ID. Refuses what it cannot do
safely: after a decision, before a join, inside a loop body, drop/replace of
a decision or of an activity with an error handler, and a placement that
would overlap an object. The modelsdk backend writes through
UpdateRawUnitPatch (canon.Reconcile).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…#736)

alter microflow|nanoflow M.F { insert after|before <target> { … }
replace <target> with { … } drop <target>; }. Targets are the #713 content
addresses, resolved against the stored flow before any operation runs.
Fragments are built with the create-microflow builder, seeded with the
flow's variables, and cut out of their start and end events. A fragment
variable that clashes with one the flow has, or one it reads that is not
declared upstream of the insertion point, is an error; so is dropping an
activity whose output is still read. Acceptance on PedApp VAL_Feedback:
only the new log, the two flows around it and the shifted positions differ;
an empty alter writes nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… handle

A handle has to parse as an alter target, and a target ends at the { of a
fragment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Runs the shared splice on the stored flow and sends the difference as
ped_update_document path operations in one update, after checking the live
document still matches the .mpr (PED addresses entries by index). Drop and
replace are refused: PED does not roll back a removal when an update fails.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Loop body flows are stored in the unit's Flows list, not in the loop, so
removing a Studio Pro loop with two or more body activities left them
pointing at removed objects and Save refused the unit
(TestApp ACT_ConflictedWorkflowHelper_ApplyJumpTo). mx check 11.14 on the
dropped and replaced copies gives the baseline error list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each operation was checked against the flow as stored only. Measured
with mx check 11.14 on TestApp: two fragments declaring the same
variable gave CE0111, and a fragment reading a variable a drop in the
same statement removed gave CE0109, after "Altered microflow". The
context now tracks what earlier operations declared, read and removed.
Also count a fragment loop's iterator as the fragment's own, so loop
fragments are no longer refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…dl 1

`first` is Mendix's "First object" range in every language version. Under
the mdl 1 header a bare `limit 1` is a Custom range, a list of one; without
it the alpha meaning (the object) is kept and warns MDL-V1-LIMIT1. The
visitor resolves the meaning into RetrieveStmt.First, so the writer, the
variable typing and MDL-RETRIEVE01 no longer read limit text. describe
prints the object range as `first`. `first` on an association retrieve
is refused (that source has no range).

MDL-RETRIEVE01 keys on the object range and names CE0100 for a loop, as
measured with mx check 11.13.

Tests: visitor per version, builder range per version, check per version,
describe spelling, and a PedApp round trip of both forms with a headerless
control.

Part of #734.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nder mdl 1

CLAUDE.md idiom 5, the quick reference, the syntax topic, the skills and
docs-site pages that taught `limit 1` for an object now write `first`
and say what `limit 1` means per language version. CHANGELOG entry.

Part of #734.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ADR-0010 R11/R12: describe output must mean the same under mdl 0 and
mdl 1, and mdl 1 makes `;` the only terminator. About twenty document
types printed a SQL*Plus `/` line after their statement, and pages,
snippets, layouts and some OData statements ended without `;`.

- Drop every `/` line from describe (agents, knowledge bases, MCP
  services, models, constants, contracts, associations, DB connections,
  entities, enumerations, image collections, modules, OData, published
  REST, security, microflows, nanoflows, rules).
- Pages, snippets and layouts end with `};`; a workflow with
  `end workflow;`.
- A published OData service ends with `;` after its property list,
  authentication clause or entity block, whichever is last; an external
  entity without attributes after its property list.
- A published REST service with no resources prints an empty `{ };`
  block: the block is mandatory in the grammar, so the bare `;` it
  printed before did not parse.

Tests: TestPedAppDescribeIsValidMdl1 checks the terminators of every
PedApp document type (plus each module, with and without `with all`,
navigation and settings) on the parse tree and re-parses the output under
an `mdl 1;` header; executor tests cover the types PedApp does not
contain, and every Describe*_Mock / #707 re-parse test now asserts the
same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`diff` and `diff-local` render MDL for the compared side; with describe
no longer printing `/`, keeping it here would show a spurious line on
every statement and render text that is invalid under mdl 1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ako
ako merged commit b1ce656 into main Sep 27, 2026
17 checks passed
ako added a commit that referenced this pull request Sep 27, 2026
…forms

On top of #740/#745/#741/#738, `fmt --upgrade --header` refused almost every
example script: those PRs gated new constructs on the header without a
rewrite. Each construct with a mechanical, meaning-preserving rewrite now has
one, computed from the parse tree by the visitor that records it (ast.Fix,
rune-offset edits, mdl/visitor/visitor_upgrade_fixes.go):

- MDL-V1-SEMI: add the missing `;`. MDL-V1-SLASH: delete the `/` line.
- MDL-V1-ESCAPE: write the literal's mdl 0 value with '' as the only escape;
  no edit inside an expression stored as written (mdl 0 already passed the
  backslash through); an escaped line break in a re-rendered expression is
  reported, since writing it into the literal changes what the builder
  stores (measured: a log message becomes a `{1}` template parameter).
- MDL-V1-LIMIT1: `limit 1` -> `first`. MDL-V1-SET: add `set`.
- MDL-DEPR003/004 and MDL-V1-LIST: call form -> statement form; find and
  contains on a declared String keep the call and gain `set`; a nested call,
  or an operand whose type the script does not state, is reported.
- MDL-V1-REPLACE02: `create or replace user role|demo user` -> `create`.

MDL-V1-PROP, MDL-V1-PROPVALUE and MDL-V1-REPLACE01 have no mechanical
rewrite; they are listed in `unrewritable` (may only shrink) and block the
header with HeaderBlockedError, which names each construct and why.
TestGatedRegistryIsComplete holds every visitor.LanguageChanges() code to
exactly one of the two lists.

The examples test lists the two corpus scripts that keep mdl 0
(keepsItsVersion) and the two whose AST differs but whose model is the same
(buildsTheSameModelNotTheSameAST), both may only shrink. The execute-both
property test upgrades a blocked script without the header, and by default
skips scripts whose only edits are the header and terminators, which never
reach the AST: 249 scripts execute (6 min); MXCLI_UPGRADE_ALL=1 runs all 701,
587 of them executing to the same model.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

describe ends every statement with ';' and never emits '/' (valid under mdl 0 and mdl 1)

1 participant