MPS BaseLanguage (Java) Authoring

jetbrains.mps.baseLanguage is MPS's Java-equivalent language. You edit it as an AST, not as text. Two authoring paths exist: the Java parser (mps_mcp_parse_java_and_insert) for plain Java, and JSON AST blueprints (mps_mcp_insert_root_node_from_json / mps_mcp_update_root_node_from_json / mps_mcp_update_node) for everything else — especially code that uses BaseLanguage extensions (jetbrains.mps.lang.smodel, jetbrains.mps.baseLanguage.closures, jetbrains.mps.baseLanguage.collections) or needs stable persistent member references.

Critical Directives

• Node equality: always use :eq: and :ne: (concepts NPEEqualsExpression / NPENotEqualsExpression). Never == or .equals() between SNode references.
• Constructor return type: ConstructorDeclaration.returnType MUST be a VoidType node. Leaving it empty fails validation.
• ClassCreator wiring: ClassCreator.baseMethodDeclaration points at the constructor declaration, not the class. InstanceMethodCallOperation.baseMethodDeclaration points at the method declaration.
• Inherited methods: use the declaring class ref for baseMethodDeclaration, not the subclass that calls the method. E.g. addActionListener is declared on AbstractButton, so use the AbstractButton class ref.
• Expressions in statement lists: any Expression must be wrapped in ExpressionStatement to be valid inside a StatementList.
• Variable declarations: in method bodies wrap LocalVariableDeclaration in LocalVariableDeclarationStatement. In ForStatement.variable use LocalVariableDeclaration directly, no wrapper.
• Prefer primitives: use string (StringType) over String (ClassifierType) where possible; same for int, boolean, etc.
• Compatibility: BaseLanguage core is Java 7 (including generics). When building AST directly (JSON blueprints), there is no lambda/record syntax — use the jetbrains.mps.baseLanguage.closures extension for closures. The Java parser (mps_mcp_parse_java_and_insert) additionally accepts the Java 8+ syntax MPS recognizes — most notably lambdas, which it maps to closures ClosureLiterals (auto-imported when postProcess.importUsedLanguages is on); a lambda only type-checks against a matching functional-type target. Constructs the parser does not recognize (e.g. records) still fail to parse. See references/parse-java-tips.md.
• Surgical edits: when a single child changes prefer mps_mcp_update_node over rewriting the whole root — full-root rewrites churn persistent IDs and break incoming refs.

Choose Your Path

Pick the right authoring tool before you start:

• mps_mcp_parse_java_and_insert — use for plain Java skeletons or bodies (classes, methods, statements, expressions), including the current MPS Console input (insert.mode: "console" to replace the console command, or mode: "child"/"replace" with a parentRef/targetRef inside the current console command for nested edits). Fastest path when no BaseLanguage extension is required.
• JSON AST blueprints — use when the parser is unavailable, when the code uses BaseLanguage extensions (smodel, closures, collections), or when stable persistent references to members are required for downstream consumers.
• Mixed — use the parser for the skeleton with placeholders (e.g. IntegerConstant, StringLiteral, IntegerType, StringType), then JSON-edit the placeholders to swap in extension-specific subtrees.

Common Workflow

1. Scope: call mps_mcp_get_current_editor_root_node to know where you are inserting (method body, field initializer, root, …).
2. Resolve dependencies: confirm the containing model imports the right languages (jetbrains.mps.baseLanguage plus any extensions). Models for referenced nodes must also be imported.
3. Skeleton first: for any non-trivial root, insert a placeholder skeleton (mps_mcp_create_root_node + mps_mcp_update_root_node_from_json or the parser) before filling member bodies.
4. Harvest references: for own members, run mps_mcp_print_node on the skeleton to read persistent refs of constructors, methods, and fields. For JDK / library stubs, derive refs from the class ref using the URL-encoded signature formula (see references).
5. Apply bodies: edit one subtree at a time with mps_mcp_update_node, or bulk-rewrite via mps_mcp_update_root_node_from_json.
6. Auto-resolution: for unambiguous local refs (a parameter, a local variable, a unique method name), pass the plain name as target — MPS resolves it after insertion. For overloaded or stub members, use a persistent ref.
7. Validate in three gates:
   • dryRun: true on insert tools — catches structural / assignability errors before mutation
   • mps_mcp_check_root_node_problems — semantic checking
   • mps_mcp_alter_nodes MAKE — generation + compilation
8. Repair: if a few refs are broken after insert, run mps_mcp_alter_nodes FIX_REFERENCES rather than re-harvesting all of them.

Related Skills

• mps-node-editing — general node mutation tools (mps_mcp_update_node, etc.). Load first if you have not seen them.
• mps-aspect-structure-concepts — defines what concepts exist and what roles they expose. Read when authoring a brand-new language whose concepts extend BaseLanguage.
• mps-quotations — light/quoted SNode literals embedded in BaseLanguage code (e.g. inside behavior or generator bodies).
• mps-model-manipulation — smodel + collections + closures patterns layered on top of BaseLanguage; load when manipulating MPS nodes from BaseLanguage.
• mps-aspect-behavior, mps-aspect-typesystem, mps-aspect-constraints — each owns a language whose function bodies are BaseLanguage; reach for those skills when the surrounding aspect matters.

Reference Index

• Open references/concept-mapping.md when you need the Java-syntax → MPS-concept lookup table and the key role names (statements, expressions, types, declarations).
• Open references/json-patterns.md when you need ready-to-paste JSON blueprints for common constructs (local variable, node-equality, instance-method call, anonymous class, array creation, super-constructor call, empty class template).
• Open references/critical-rules.md when something fails validation and you want the rulebook on ExpressionStatement, ClassCreator, anonymous classes, mandatory bodies, FieldReferenceOperation, etc.
• Open references/parse-java-tips.md when using mps_mcp_parse_java_and_insert and you need binary-expression priority handling, placeholder strategy, or post-insert verification steps.
• Open references/stub-references.md when you need to point a baseMethodDeclaration at a JDK or library member — covers ref derivation, URL encoding, inherited-method handling, and the GET_ASSIGNABLE_REFERENCES fallback.
• Open references/json-ast-workflow.md when authoring a non-trivial BaseLanguage root via JSON AST — covers staged skeleton → harvest → patch → validate, plus the ClassCreator vs InstanceMethodCallOperation ref distinction.
• Open references/troubleshooting.md when you hit dryRun errors, broken-ref symptoms in generated Java (new (), ???()), stale-ref errors, or "model checks pass but MAKE fails".