bug(#708): formation-without-comment lint (#729)

* bug(#708): formation-without-comment

* bug(#708): typos, clean for yamllint

* bug(#708): no errors

* bug(#708): start-with

Author: h1alexbel

src/main/resources/org/eolang/lints/comments/formation-without-comment.xsl

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * SPDX-FileCopyrightText: Copyright (c) 2016-2025 Objectionary.com
+ * SPDX-License-Identifier: MIT
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:eo="https://www.eolang.org" id="formation-without-comment" version="2.0">
+  <xsl:import href="/org/eolang/parser/_funcs.xsl"/>
+  <xsl:import href="/org/eolang/funcs/lineno.xsl"/>
+  <xsl:import href="/org/eolang/funcs/escape.xsl"/>
+  <xsl:import href="/org/eolang/funcs/defect-context.xsl"/>
+  <xsl:output encoding="UTF-8" method="xml"/>
+  <xsl:template match="/">
+    <xsl:variable name="min" select="32"/>
+    <defects>
+      <xsl:for-each select="//o[eo:abstract(.) and @name and not(starts-with(@name, 'a🌵')) and not(eo:test-attr(.)) and @line]">
+        <xsl:variable name="line" select="eo:lineno(@line)"/>
+        <xsl:if test="not(/object/comments/comment[@line = $line])">
+          <xsl:element name="defect">
+            <xsl:attribute name="line">
+              <xsl:value-of select="$line"/>
+            </xsl:attribute>
+            <xsl:if test="$line = '0'">
+              <xsl:attribute name="context">
+                <xsl:value-of select="eo:defect-context(.)"/>
+              </xsl:attribute>
+            </xsl:if>
+            <xsl:attribute name="severity">
+              <xsl:text>warning</xsl:text>
+            </xsl:attribute>
+            <xsl:text>The formation </xsl:text>
+            <xsl:value-of select="eo:escape(@name)"/>
+            <xsl:text> does not have a comment</xsl:text>
+          </xsl:element>
+        </xsl:if>
+      </xsl:for-each>
+    </defects>
+  </xsl:template>
+</xsl:stylesheet>

src/main/resources/org/eolang/motives/comments/formation-without-comment.md

@@ -0,0 +1,18 @@
+# Formation Without Comments
+
+Each named formation should have comment on top of it.
+
+Incorrect:
+
+```eo
+[] > main
+  42 > @
+```
+
+Correct:
+
+```eo
+# This is main.
+[] > main
+  42 > @
+```

src/test/resources/org/eolang/lints/packs/single/formation-without-comment/allows-anonymous-formation-without-comment.yaml

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: Copyright (c) 2016-2025 Objectionary.com
+# SPDX-License-Identifier: MIT
+---
+sheets:
+  - /org/eolang/lints/comments/formation-without-comment.xsl
+asserts:
+  - /defects[count(defect)=0]
+input: |
+  # Top object.
+  [args] > main
+    start > @
+      []
+        42 > i

src/test/resources/org/eolang/lints/packs/single/formation-without-comment/allows-auto-named-formation-without-comment.yaml

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: Copyright (c) 2016-2025 Objectionary.com
+# SPDX-License-Identifier: MIT
+---
+sheets:
+  - /org/eolang/lints/comments/formation-without-comment.xsl
+asserts:
+  - /defects[count(defect)=0]
+input: |
+  # Top object.
+  [args] > main
+    start > @
+      [i] >>
+        i.plus 2 > x

src/test/resources/org/eolang/lints/packs/single/formation-without-comment/allows-formation-with-comment.yaml

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: Copyright (c) 2016-2025 Objectionary.com
+# SPDX-License-Identifier: MIT
+---
+sheets:
+  - /org/eolang/lints/comments/formation-without-comment.xsl
+asserts:
+  - /defects[count(defect)=0]
+input: |
+  # Top object.
+  [args] > main
+    # Nested object.
+    [] > f
+      42 > @

src/test/resources/org/eolang/lints/packs/single/formation-without-comment/allows-test-without-comment.yaml

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: Copyright (c) 2016-2025 Objectionary.com
+# SPDX-License-Identifier: MIT
+---
+sheets:
+  - /org/eolang/lints/comments/formation-without-comment.xsl
+asserts:
+  - /defects[count(defect)=0]
+input: |
+  # Top object.
+  [] > f
+    [] +> checks-data
+      eq. > @
+        42
+        42

src/test/resources/org/eolang/lints/packs/single/formation-without-comment/catches-formation-without-comment.yaml

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: Copyright (c) 2016-2025 Objectionary.com
+# SPDX-License-Identifier: MIT
+---
+sheets:
+  - /org/eolang/lints/comments/formation-without-comment.xsl
+asserts:
+  - /defects[count(defect[@severity='warning'])=1]
+  - /defects/defect[@line='1']
+input: |
+  [args] > main
+    42 > @

src/test/resources/org/eolang/lints/packs/single/formation-without-comment/catches-nested-formation-without-comment.yaml

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: Copyright (c) 2016-2025 Objectionary.com
+# SPDX-License-Identifier: MIT
+---
+# yamllint disable rule:line-length
+sheets:
+  - /org/eolang/lints/comments/formation-without-comment.xsl
+asserts:
+  - /defects[count(defect[@severity='warning'])=1]
+  - /defects/defect[@line='7']
+  - /defects/defect[normalize-space()='The formation "s" does not have a comment']
+input: |
+  # Top object.
+  [args] > main
+    # Nested object.
+    [] > f
+      # One more nested object.
+      [] > a
+        [] > s
+          42 > @