Install open-java-format 2.98.0.5 and add JBang to the library rules

2.98.0.5 leaves a JBang script's first line and its directives, such as
//DEPS, exactly as written when they come before the first line of code
(openjavaformat/open-java-format#24). Until then the formatter put a
space after the slashes, so JBang dropped the dependencies and a shell
could no longer run the file.

The new JBang page under Library rules follows the Flogger page: the
header of a picocli script as the released native binaries of 2.98.0.4
and 2.98.0.5 format it, then where the rule applies. It also says that
2.98.0.5 does not take out spaces an earlier run added, which the same
binaries confirm. The index now covers rules that go by directive names,
and says that a rule fixing a bug can come before 3.0.

The exclude example on the GitHub Action page gave JBang scripts as its
reason, because the formatter rewrote their //DEPS. It now shows copied
third-party code instead.

Migrate stays as it is: code that palantir-java-format has already
formatted has "// DEPS", and 2.98.0.5 leaves that alone.

Author: abashev

docs/get-started/github-actions.md

@@ -55,8 +55,8 @@ root. Every line that is not empty and not a comment is a git pathspec, and a Ja
 one is skipped.
 
 ``` gitignore title=".open-java-format-exclude"
-# Standalone jbang scripts: the formatter would rewrite their //DEPS directives
-samples/**
+# Code copied from another project, kept as it came
+third_party/**
 
 # Generated sources
 **/build/generated/**

docs/library-rules/index.md

@@ -1,15 +1,18 @@
 # Library rules
 
 open-java-format has one style and no options. A few libraries are written so that a chain of calls
-reads as one phrase, and the general rule of one call per line cuts that phrase apart. For those
-libraries the formatter carries a rule of its own.
+reads as one phrase, and the general rule of one call per line cuts that phrase apart. Some tools read
+instructions from comments in the code, and the general rule of a space after `//` hides them. For
+those the formatter carries a rule of its own.
 
-A library rule is built in, so there is nothing to configure. It goes by method names, because the
-formatter sees syntax and not types, and it leaves alone any code that does not match.
+A library rule is built in, so there is nothing to configure. It goes by names, of methods or of
+directives, because the formatter sees syntax and not types, and it leaves alone any code that does
+not match.
 
 | Library | What the rule does |
 | --- | --- |
 | [Flogger](flogger.md) | Keeps the logger and its fluent calls on one line in front of `log(` |
+| [JBang](jbang.md) | Keeps `//DEPS` and the other directives at the top of a script as written |
 
 ## Proposing a rule
 
@@ -18,4 +21,5 @@ piece of code as it is formatted today, and the way it should look. The proposal
 [Mutiny](https://github.com/openjavaformat/open-java-format/issues/25) shows what that takes.
 
 A new rule changes how existing code is formatted, so it ships only in a release that is allowed to
-change output.
+change output. The exception is a rule that fixes a bug: the JBang rule came in 2.98.0.5, because
+until then the formatter broke those scripts.

docs/library-rules/jbang.md

@@ -0,0 +1,50 @@
+# JBang
+
+A [JBang](https://www.jbang.dev/) script keeps its first line and its directives, such as `//DEPS`,
+exactly as written: no space after the slashes and no wrapping.
+
+``` java title="Default rules"
+/// usr/bin/env jbang "$0" "$@" ; exit $?
+// JAVA 21+
+// DEPS info.picocli:picocli:4.7.6
+
+import picocli.CommandLine;
+```
+
+``` java title="With the JBang rule"
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//JAVA 21+
+//DEPS info.picocli:picocli:4.7.6
+
+import picocli.CommandLine;
+```
+
+JBang reads a directive only when its name comes right after the slashes. Under the default rules it
+drops the Java version and the dependency, so the script no longer compiles, and a shell that runs
+the file takes `///` for the command and fails.
+
+## When it applies
+
+Only in the comments at the top of the file, before the first line of code, which is where
+[JBang's documentation](https://www.jbang.dev/documentation/jbang/latest/script-directives.html)
+puts directives. After the `package` declaration, an import or a class, the same text is an ordinary
+comment and gets its space.
+
+Two kinds of line stay as written there:
+
+- A directive: one of JBang's names right after the slashes, followed by a space or the end of the
+  line. The names are `CDS`, `COMPILE_OPTIONS`, `DEPS`, `DESCRIPTION`, `DOCS`, `FILES`, `GAV`,
+  `GROOVY`, `JAVA`, `JAVAAGENT`, `JAVAC_OPTIONS`, `JAVA_OPTIONS`, `KOTLIN`, `MAIN`, `MANIFEST`,
+  `MODULE`, `NATIVE_OPTIONS`, `NOINTEGRATIONS`, `PREVIEW`, `REPOS`, `RUNTIME_OPTIONS` and `SOURCES`.
+  A name behind an integration's prefix, such as Quarkus's `//Q:CONFIG`, counts as well.
+- The first line of the file, when its first word is a path, as in `///usr/bin/env jbang` or
+  `//usr/bin/env jbang`.
+
+Other comments there, such as `//deps` or `//TODO`, get their space as before.
+
+A script that was formatted before 2.98.0.5, or with palantir-java-format or google-java-format,
+already has the spaces, and the formatter does not take them out. Remove them by hand once.
+
+The rule is our own and came in 2.98.0.5
+([#24](https://github.com/openjavaformat/open-java-format/issues/24)). In google-java-format the same
+request is still open as [#1217](https://github.com/google/google-java-format/issues/1217).

zensical.toml

@@ -31,6 +31,7 @@ nav = [
   { "Library rules" = [
     "library-rules/index.md",
     { "Flogger" = "library-rules/flogger.md" },
+    { "JBang" = "library-rules/jbang.md" },
   ] },
   { "Migrate" = "migrate.md" },
   { "Manifesto" = "manifesto.md" },
@@ -106,7 +107,7 @@ toggle.name = "Switch to system preference"
 # plugin puts it in before the Markdown is rendered, so it lands in code blocks too. The key is not
 # extra.version: the theme reads that one as the switch for a version selector.
 [project.extra]
-ojf_version = "2.98.0.4"
+ojf_version = "2.98.0.5"
 # The Maven plugin is released from its own repository, openjavaformat/fmt-maven-plugin, with version
 # numbers of its own. Bump it on each release of the plugin.
 maven_plugin_version = "2.27.0.1"