feat(#5267): require vertical voids to precede all other attributes

Author: maxonfjvipon

eo-parser/PARSER_SPEC.md

@@ -272,6 +272,13 @@ R-3.4.5. No double space between parameter names.
 R-3.4.6. The formation line may end with one of the optional name suffixes (§3.10).
 R-3.4.7. A void attribute may also be declared **vertically** as a `? > name` body line of the formation (the `?` is the `VOID` token of §2.3). It is equivalent to listing `name` among the bracket parameters: it emits the same void child (§9.4), and `move-voids-up` hoists it among the head voids in source order, so `[name] > foo` with body lines `? > bar` and `? > test` is identical in XMIR to `[name bar test] > foo`. `? > name` is the **only** shape the `?` marker may take: the marker is not a value, so it may not appear as an argument (`foo ? bar`), a method receiver (`?.read`), or a reversed-dispatch argument (`foo. ? q`), and a bare `?` or any other trailing tokens are an error. The form requires a name suffix and is legal only as a direct child of a formation, which has no children of its own (a deeper-indent line under a void is rejected). Reverse printing canonicalises every void to the bracket form, since the two are indistinguishable in XMIR.
 R-3.4.8. In an **atom** (a formation whose head carries `/sig`), a vertical void may carry a brace-delimited forma-list — `? > name /{forma (SPACE forma)*}` — declaring the formas the atom supplies as the arguments of that error branch. Each `forma` is a dotted name (`NAME ('.' NAME)*`), optionally rooted at `Q`. The list emits as a `@types` attribute on the void's `<o>`, whose space-separated tokens are resolved exactly like an `@atom`: a leading `Q.` is promoted to `Φ.` at parse (R-9.3), then each token is alias-expanded and, when dotless and non-special, prefixed with `Φ.`. Example: `? > not-found /{string io.file-error}` emits `<o name='not-found' base='∅' types='Φ.string io.file-error'/>`. A `/{…}` forma-list on a void outside an atom is an error.
+R-3.4.9. Vertical voids must stay **on top**: every `? > name` line must precede all non-void attributes of the formation body. A void that follows a non-void child — or sits between non-void children — is an error (`a void attribute must be declared above all other attributes`). So
+```
+[] > foo
+  6 > six
+  ? > x
+```
+is rejected, whereas `? > x` above `6 > six` is accepted. (Bracket-head voids are always above the body, so the rule constrains only the relative order of body lines.)
 
 Outer kind: **`bare-formation`** (master; openness `open` for body).
 

eo-parser/src/main/java/org/eolang/parser/Kind.java

@@ -98,7 +98,13 @@ enum Kind {
     /**
      * Triple-quoted {@code """…"""} text block.
      */
-    TEXT_BLOCK;
+    TEXT_BLOCK,
+
+    /**
+     * Vertical void attribute {@code ? > name} (R-3.4.7). A closed leaf
+     * that must precede every non-void child of its formation.
+     */
+    VOID;
 
     /**
      * Whether this kind is in the horizontally-completed set.

eo-parser/src/main/java/org/eolang/parser/Level.java

@@ -78,6 +78,13 @@ final class Level {
      */
     private boolean taken;
 
+    /**
+     * True once a non-void child has been added under this entry —
+     * after which a {@link Kind#VOID} child is rejected (R-3.4.7,
+     * voids must precede every other attribute).
+     */
+    private boolean plain;
+
     /**
      * For {@link Kind#COMPACT_TUPLE}: the {@code N} count from {@code *N}.
      */
@@ -280,6 +287,27 @@ void consumeReceiver() {
         this.taken = true;
     }
 
+    /**
+     * Observe a child of the given {@code kind} being added under this
+     * entry, enforcing the void-ordering rule (R-3.4.7): a
+     * {@link Kind#VOID} child is rejected once a non-void child has
+     * appeared, and every non-void child records that fact.
+     * @param shape Kind of the child being added
+     * @param line Source line of the child (for the error)
+     * @param column Source indent of the child (for the error)
+     */
+    void observeVoid(final Kind shape, final int line, final int column) {
+        if (shape == Kind.VOID && this.plain) {
+            throw new ParseError(
+                line, column,
+                "a void attribute must be declared above all other attributes"
+            );
+        }
+        if (shape != Kind.VOID) {
+            this.plain = true;
+        }
+    }
+
     /**
      * Set the compact-tuple {@code N} count.
      * @param value N

eo-parser/src/main/java/org/eolang/parser/LnVoid.java

@@ -68,7 +68,7 @@ public void into(final Stack stack, final Globals globals, final Emit emit) {
         }
         Comments.attach(globals, emit, this.span, suffix.present());
         final Level level = new Transition(stack, this.span).apply(
-            Kind.HEAD, Openness.VERTICAL_COMPLETED, suffix.present()
+            Kind.VOID, Openness.VERTICAL_COMPLETED, suffix.present()
         );
         if (!formas.isEmpty() && !level.patom()) {
             throw new ParseError(

eo-parser/src/main/java/org/eolang/parser/Stack.java

@@ -26,7 +26,6 @@
  *
  * @since 0.1
  */
-@SuppressWarnings("PMD.UnnecessaryLocalRule")
 final class Stack {
 
     /**
@@ -189,6 +188,7 @@ Level push(
             }
             parent = under.kind();
             patom = under.atom();
+            under.observeVoid(kind, line, indent);
         }
         if (!this.levels.isEmpty()) {
             this.opener.beforeChild(this.top());
@@ -251,6 +251,7 @@ Level replace(final int line, final Kind kind, final Openness openness) {
             final Level under = this.top();
             parent = under.kind();
             patom = under.atom();
+            under.observeVoid(kind, line, indent);
             this.opener.beforeChild(under);
         }
         final Level fresh = new Level(indent, line, kind, openness, parent, patom);

eo-parser/src/test/java/org/eolang/parser/EoTest.java

@@ -214,6 +214,17 @@ void rejectsFormaListOutsideAtom() {
         );
     }
 
+    @Test
+    void rejectsVoidBelowRegularAttribute() {
+        MatcherAssert.assertThat(
+            "a void declared after a regular attribute must be rejected",
+            EoTest.render("[] > foo", "  6 > six", "  ? > x", "  5 > five", "  ? > y"),
+            XhtmlMatchers.hasXPath(
+                "/object/errors/error[contains(text(),'void attribute must be declared above')]"
+            )
+        );
+    }
+
     @Test
     void parsesAtomDeclaration() {
         MatcherAssert.assertThat(

eo-parser/src/test/resources/org/eolang/parser/eo-packs/parse/atom-void-single-alias.yaml

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: Copyright (c) 2016-2026 Objectionary.com
+# SPDX-License-Identifier: MIT
+---
+# yamllint disable rule:line-length
+sheets:
+  - /org/eolang/parser/parse/wrap-method-calls.xsl
+  - /org/eolang/parser/parse/vars-float-up.xsl
+  - /org/eolang/parser/parse/move-voids-up.xsl
+  - /org/eolang/parser/parse/build-fqns.xsl
+  - /org/eolang/parser/parse/expand-aliases.xsl
+  - /org/eolang/parser/parse/resolve-aliases.xsl
+  - /org/eolang/parser/parse/add-default-package.xsl
+  - /org/eolang/parser/parse/roll-bases.xsl
+  - /org/eolang/parser/parse/decorate.xsl
+  - /org/eolang/parser/parse/mandatory-as.xsl
+asserts:
+  - /object[not(errors)]
+  - /object/o[@name='fopen']/o[@name='e' and @base='∅' and @types='Φ.foo']
+input: |
+  +alias foo
+
+  [] > fopen /file
+    ? > e /{foo}

eo-parser/src/test/resources/org/eolang/parser/eo-packs/parse/vertical-voids.yaml

@@ -22,6 +22,6 @@ asserts:
   - /object/o[@name='foo']/o[4][@name='φ' and @base='Φ.hello']
 input: |
   [name] > foo
-    hello > @
     ? > bar
     ? > test
+    hello > @

eo-parser/src/test/resources/org/eolang/parser/eo-typos/void/as-argument.yaml

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: Copyright (c) 2016-2026 Objectionary.com
+# SPDX-License-Identifier: MIT
+---
+# yamllint disable rule:line-length
+line: 3
+message: "expected value"
+input: |
+  # No comments.
+  [] > foo
+    bar ? baz > x

eo-parser/src/test/resources/org/eolang/parser/eo-typos/void/as-reversed-argument.yaml

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: Copyright (c) 2016-2026 Objectionary.com
+# SPDX-License-Identifier: MIT
+---
+# yamllint disable rule:line-length
+line: 3
+message: "expected value"
+input: |
+  # No comments.
+  [] > foo
+    bar. ? q > m