feat(#65): add docs to README + get motives at runtime

Author: Marat-Tim

.github/motives.groovy

@@ -0,0 +1,29 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2016-2025 Objectionary.com
+ * SPDX-License-Identifier: MIT
+ */
+package org.eolang.lints
+
+/**
+ * This script is run using gplus in the script motives.sh.
+ * This script saves a file with the lint name and extension .md to the tmp folder.
+ * The motive of this lint is preserved as content.
+ * These files are saved for all active lints in the project.
+ * @todo #65:15min after fixing this problem with creation of groovy folder
+ * https://github.com/jcabi/jcabi-parent/issues/586,
+ * move this script to the src/main/groovy folder in package org.eolang.lints
+ * @todo #65:15min after moving motives.groovy into src/main/groovy we should add test,
+ * that verifies that this script correctly saves a list of all lint motifs to the tmp folder
+ */
+
+static def saveLint(Lint<?> lint) {
+    new File("tmp/${lint.name()}.md").text = lint.motive()
+}
+
+new PkMono().forEach {
+    saveLint(it)
+}
+
+new PkWpa().forEach {
+    saveLint(it)
+}

.github/motives.sh

@@ -41,12 +41,15 @@ tail() {
   printf '</article></section></body></html>'
 }
 
+mkdir tmp
+mvn clean compile gplus:execute
+
 while IFS= read -r f; do
   n=$(basename "${f}" .md)
   html=gh-pages/${tag}/${n}.html
   ( head && pandoc "${f}" && tail ) > "${html}"
   echo "${n} -> $(du -b "${html}" | cut -f1) bytes"
-done < <(find src/main/resources/org/eolang/motives -name '*.md' | sort)
+done < <(find tmp -name '*.md' | sort)
 
 (
   head

README.md

@@ -17,6 +17,8 @@ This Java package is a collection of "lints" (aka "checkers") for
 formatting. This is about best practices and readiness of code
 for successful compilation and execution.
 
+You can find the current full list of rules [here][lints-list].
+
 We use this package as a dependency in the
 [EO-to-Java compiler][EO]:
 
@@ -171,3 +173,4 @@ If you want the code to be checked using
 [XMIR]: https://news.eolang.org/2022-11-25-xmir-guide.html
 [EO]: https://www.eolang.org
 [benchmark-gha]: https://github.com/objectionary/lints/actions/runs/14713088694
+[lints-list]: https://www.objectionary.com/lints/

pom.xml

@@ -576,6 +576,23 @@
           </execution>
         </executions>
       </plugin>
+      <plugin>
+        <groupId>org.codehaus.gmavenplus</groupId>
+        <artifactId>gmavenplus-plugin</artifactId>
+        <version>4.1.1</version>
+        <configuration>
+          <scripts>
+            <script>./.github/motives.groovy</script>
+          </scripts>
+        </configuration>
+        <dependencies>
+          <dependency>
+            <groupId>org.apache.groovy</groupId>
+            <artifactId>groovy</artifactId>
+            <version>4.0.26</version>
+          </dependency>
+        </dependencies>
+      </plugin>
     </plugins>
   </build>
 </project>

src/main/java/org/eolang/lints/LtByXsl.java

@@ -11,7 +11,9 @@
 import com.jcabi.xml.XMLDocument;
 import com.jcabi.xml.XSL;
 import com.jcabi.xml.XSLDocument;
+import io.github.secretx33.resourceresolver.DefaultResourceLoader;
 import java.io.IOException;
+import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Optional;
@@ -40,9 +42,9 @@ final class LtByXsl implements Lint<XML> {
     private final XSL sheet;
 
     /**
-     * Motive document.
+     * Path to motive document.
      */
-    private final Input doc;
+    private final String doc;
 
     /**
      * Ctor.
@@ -54,20 +56,18 @@ final class LtByXsl implements Lint<XML> {
             new ResourceOf(
                 String.format("org/eolang/lints/%s.xsl", xsl)
             ),
-            new ResourceOf(
-                String.format("org/eolang/motives/%s.md", xsl)
-            )
+            String.format("org/eolang/motives/%s.md", xsl)
         );
     }
 
     /**
      * Ctor.
-     * @param xsl Relative path of XSL
-     * @param motive Relative path of a motive document
+     * @param xsl Absolute path of XSL
+     * @param motive Absolute path of a motive document
      * @throws IOException If fails
      */
     @SuppressWarnings("PMD.ConstructorOnlyInitializesOrCallOtherConstructors")
-    LtByXsl(final Input xsl, final Input motive) throws IOException {
+    LtByXsl(final Input xsl, final String motive) throws IOException {
         final XML xml = new XMLDocument(new IoCheckedText(new TextOf(xsl)).asString());
         this.rule = new Xnav(xml.toString())
             .element("xsl:stylesheet")
@@ -117,7 +117,9 @@ public Collection<Defect> defects(final XML xmir) {
 
     @Override
     public String motive() throws IOException {
-        return new IoCheckedText(new TextOf(this.doc)).asString();
+        return new DefaultResourceLoader()
+            .getResource(this.doc)
+            .getContentAsString(StandardCharsets.UTF_8);
     }
 
     /**

src/main/java/org/eolang/lints/PkByXsl.java

@@ -54,13 +54,11 @@ private static Iterable<Lint<XML>> all() {
                     res ->
                         new LtByXsl(
                             new InputOf(res.getInputStream()),
-                            new InputOf(
-                                PkByXsl.XSL_PATTERN.matcher(
-                                    PkByXsl.LINTS_PATH.matcher(
-                                        res.getURL().toString()
-                                    ).replaceAll("eolang/motives")
-                                ).replaceAll(".md")
-                            )
+                            PkByXsl.XSL_PATTERN.matcher(
+                                PkByXsl.LINTS_PATH.matcher(
+                                    res.getURL().toString()
+                                ).replaceAll("eolang/motives")
+                            ).replaceAll(".md")
                         ),
                     Arrays.asList(
                         new PathMatchingResourcePatternResolver().getResources(