Mps Aspect Dataflow
Developmentmps-aspect-dataflowMps Aspect Dataflow is an Agent Skill for development published in the JetBrains/MPS repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when defining or debugging MPS dataflow builders for a concept — control/data flow declarations that drive reachability analysis and variable-use checking. Covers DataFlowBuilderDeclaration, BuilderBlock, emit instructions (code for, jump, ifjump, label, read, write, ret, mayBeUnreachable), positions (AfterPosition, BeforePosition, LabelPosition), the jetbrains.mps.lang.dataFlow language, the NodeParameter implicit, BL+smodel usage inside builder bodies, and IBuilderMode for advanced analyses such as nullable/non-null tracking.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/JetBrains/MPS/blob/HEAD/.claude/skills/mps-aspect-dataflow/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/mps-aspect-dataflow, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
MPS Dataflow Aspect
The dataflow aspect (jetbrains.mps.lang.dataFlow, l:7fa12e9c-b949-4976-b4fa-19accbc320b4) lets a language describe how control and data flow through nodes of a concept. MPS uses that information for reachability analysis, uninitialised-variable checks, and (via IBuilderMode) richer flow analyses such as nullable tracking.
Mental Model
Each DataFlowBuilderDeclaration answers: given a node of concept X, in what order might execution visit its children, and which variables are read or written?
The builder body is a BL StatementList (inside a BuilderBlock). You use normal BL control flow (if, foreach, local variables) to compute which emit instructions to output at runtime. The node implicit parameter (concept NodeParameter) is always in scope — its type is the concept referenced by conceptDeclaration, giving smodel-typed access to children and references.
The MPS dataflow engine builds a control-flow graph from the emitted instructions, then runs analyses (unreachable code, uninitialised variable reads) on that graph. The engine only traces the paths you declare; if no builder exists for a concept, MPS falls back to delegating all children in declaration order.
Critical Directives
code foris delegation, not a call. Never usejumpfor child delegation. UseEmitCodeForStatementto inline a child's own builder at this point.ifjumpsemantics: the jump is taken when the condition is FALSE. Use it aftercode for node.conditionto model branching.- Labels are node references, not string lookups.
EmitLabelStatement.nameis display-only; jumps reference the label node viaLabelPosition.label. Two labels with the same string are still distinct targets. - Always null-guard
0..1children with BLif (node.child != null)before emittingcode for node.child. write nodevswrite node.link: usewrite node(justNodeParameteras the variable expression) when the concept node is the variable being declared. Usewrite node.link(viaSLinkAccess) when the node merely references the variable being written.- Leaf concepts need no builder. The engine treats unbuilt concepts as no-ops, or for ordinary parents delegates to children in declaration order.
- Do not hand-edit serialized
.mpsdataflow files. Use MPS MCP node tools.
Common-Path Workflow
- Create the dataflow model with
mps_mcp_create_modelandmodelName: "<lang>.dataFlow"if absent. The aspect ID isdataFlow— camelCase, case-sensitive, no@suffix; spelling itdataflow(lowercase) produces a utility model that MPS will not recognise. See aspect-model-stereotypes.md. Addjetbrains.mps.lang.dataFlow(and transitivelyjetbrains.mps.baseLanguage) as used languages on the model. - Create a
DataFlowBuilderDeclarationroot node; setconceptDeclarationto the concept being described; give it aname. - Add a
BuilderBlockchild with abody(BLStatementList). - Emit instructions: delegate to children with
EmitCodeForStatement; model branches withEmitIfJumpStatement+EmitLabelStatement; record variable use withEmitReadStatement/EmitWriteStatement; mark exits withEmitRetStatement. - For loops, use
BeforePosition/AfterPositionto encode loop-back/exit edges; wrap potentially-unreachable instructions inEmitMayBeUnreachable. - Validate with
mps_mcp_check_root_node_problems. For tricky cases, inspect an existing baseLanguage builder viamps_mcp_print_nodewithdeep: true.
Related Skills
mps-model-manipulation— BL + smodel code inside builder bodies (DotExpression,SLinkAccess,NodeParameter, behavior method calls).mps-aspect-behavior— for behavior methods called from builders to compute target nodes (e.g.getLoopOrSwitch,getReturnJumpTarget).mps-aspect-typesystem— when the dataflow you emit must agree with type checks.mps-node-editing— generic JSON-blueprint node creation/replacement workflow.
Reference Index
- Concept catalog — open when you need exact concept names, properties, children, cardinalities, or abstract bases for
DataFlowBuilderDeclaration,BuilderBlock, every emit statement, every position type, and the abstract bases. See references/concept-catalog.md. - Verified JSON patterns — open when constructing or editing a builder as JSON for
mps_mcp_*tools. Includes variable read, single-child delegation, return-with-finally, if/elsif/else, while loop, assignment, variable declaration, break to ancestor, and a custom inverted-condition statement. See references/json-patterns.md. - Rules and pitfalls — open when a builder validates but the engine reports surprising reachability or variable-use results, when choosing between
AfterPositionandLabelPosition, or before usingmodes/IBuilderMode. See references/rules-and-pitfalls.md. - Language setup and engine invocation — open when wiring a new dataflow model, or when debugging "why is my builder not being called". See references/setup-and-engine.md.
- BaseLanguage builder index — open when you want to study a known-good builder for
IfStatement,WhileStatement,ReturnStatement,BreakStatement,VariableDeclaration,TryFinallyStatement,SwitchStatement,ForStatement, etc. Lists builder names and persistent nodeReferences inr:00000000-0000-4000-0000-011c895902c2. See references/baselanguage-builder-index.md. - Sample language reference — open when looking for a minimal complete builder for a custom language (
UnlessStatement_DataFlow). See references/sample-language-reference.md.