Release 0.5.1: 4 adoption-surfaced formatter defects + comment-loss data fix

CHANGELOG.md

@@ -10,6 +10,75 @@ and this project adheres to
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-06-24
+
+Bug-fix release addressing four formatter defects (five
+code-level fixes) surfaced during the 0.5.0 adoption pass
+across `senzing-commons-java` and `sz-sdk-java`. All changes
+are formatter output fixes; no spec changes.
+
+### Fixed
+
+- **Mid-statement line comments dropped in
+  `variable_declarator`.** Comments positioned between `=`
+  and the value RHS (e.g. javadoc `// @highlight region="x"`
+  snippet markers on text-block assignments) were silently
+  dropped by the AST walk, breaking `mvn javadoc:javadoc`
+  under JDK 21 when the unpaired `@end region` closers
+  failed validation. Fix: source-preserve the `= ...` region
+  verbatim when mid-statement comments are detected,
+  matching the 0.5.0 treatment of comments inside arg lists.
+- **Trailing whitespace bypassed `Emitter.newline()`'s
+  `rstrip` in source-preserve paths.** `write_raw_lines`
+  intentionally preserves trailing whitespace for text-block
+  content but had no opt-in for source-preserved CODE.
+  Fix: added `strip_trailing_ws` parameter; all
+  source-preserve-code call sites (conditions, arg lists,
+  formal parameters, non-javadoc block comments) pass `True`.
+- **Array initializer missing space before `{`.** Produced
+  `new Type[]{ X }` instead of canonical `new Type[] { X }`
+  for some inputs; idempotent on both forms, so the file
+  accumulated mixed styles. Fix: emit a single space before
+  `array_initializer` children of
+  `array_creation_expression`.
+- **Item-8 invariant not enforced for multi-arg arg lists.**
+  Calls of the shape
+  `assertEquals(arg1, longCallThatWraps(...), msg)` jammed
+  the third argument onto the wrapped second argument's
+  tail line. The 0.5.0 spec described this as
+  "width-gate handles it implicitly" but the gate misses
+  cases where the line happens to fit under 80 chars by
+  coincidence. Fix: explicit
+  "previous-arg-multi-row → break before next arg" check in
+  both `emit_p1` and `emit_p2_greedy`.
+- **Binary positional arg ignored arg-start column.** When
+  a multi-arg call's positional argument was a
+  `binary_expression`, the binary's continuation operators
+  landed at `block + 4` instead of paren-aligning under the
+  argument's first operand column. Fix: set
+  `paren_align_col` to the arg's start column for the
+  duration of a binary-typed positional arg's emit. Narrow
+  to direct `binary_expression` (no paren unwrap) to avoid
+  the idempotency drift that originally narrowed 0.5.0
+  item 10 to single-arg.
+
+### Verification
+
+- 656 formatter tests pass (was 645 at 0.5.0; +10 new
+  fixtures across `comment_preservation/`, `arg_list_wrap/`,
+  and `array_initializer/`). The first 6 lock the headline
+  fixes; the remaining 4 cover edge cases surfaced during the
+  PR review pass (block-comment between `=` and value,
+  array initializer without `new`, last-arg-multi-row in arg
+  lists, idempotency lock for the P4 paren-aligned shape).
+- `senzing-commons-java` reformat: 2151 / 2151 tests pass,
+  `mvn -Pcheckstyle validate` BUILD SUCCESS, idempotent on
+  2nd pass, zero trailing whitespace in source, array
+  initializers normalized.
+- The sz-sdk-java demo files containing javadoc `@snippet`
+  markers no longer lose their `// @highlight` openers;
+  `mvn javadoc:javadoc` under JDK 21 succeeds.
+
 ## [0.5.0] - 2026-06-23
 
 Expands the formatter from the

docs/faqs/building/consumer-trial-checklist.md

@@ -0,0 +1,171 @@
+# Consumer Trial Checklist (Before Tagging a Standards Release)
+
+## Overview
+
+When preparing to tag a new release of `java-coding-standards`,
+trial the candidate against each known adopter before the tag
+lands. The shallow gate that 0.5.0 used (`mvn -Pcheckstyle
+validate` only) missed a silent data-loss bug because checkstyle
+doesn't validate that javadoc snippet markup survives
+reformatting. The full gate below catches that class of issue.
+
+## The five gates
+
+A consumer trial PASSES only when ALL five gates pass:
+
+### 1. Checkstyle
+
+```bash
+mvn -Pcheckstyle validate
+```
+
+Must report `BUILD SUCCESS` with zero LineLength or style
+violations. If the consumer has source files that overflow at
+the canonical column under the new spec's no-fallback policy,
+the developer manually splits the long literal before this
+gate goes green.
+
+### 2. Tests
+
+```bash
+mvn test
+```
+
+Must report `BUILD SUCCESS` with zero failures, zero errors.
+A formatter change that breaks tests is a semantic regression
+(rare but possible — e.g. annotation arg order, string
+escapes).
+
+### 3. Javadoc — never skip
+
+```bash
+mvn javadoc:javadoc       # adopt the consumer's default profile
+```
+
+Must report `BUILD SUCCESS`. **Run this with the consumer's
+default profile, NOT a profile that strips javadoc snippet
+markup.**
+
+The sz-sdk-java `java-17` profile sets
+`<placement>x</placement>` on the
+`maven-javadoc-plugin`, which strips `@snippet` tags entirely
+under JDK 17 — useful for back-compat, but masks the entire
+class of bug where the formatter drops `// @highlight` /
+`// @end` snippet markers. The 0.5.0 release went out with a
+real data-loss bug because the trial only ran the JDK-17
+profile.
+
+For consumers that target JDK 17+ for javadoc, run the gate
+under the profile that DOES include snippet markup (typically
+`java-18+`, `java-21`, or no profile at all). Pre-JDK-18 consumers
+can use a plain javadoc invocation — the gate is checking
+that the formatter didn't drop tokens, not that the resulting
+javadoc renders correctly under every JDK.
+
+### 4. Token round-trip
+
+Count source tokens that the formatter could plausibly drop,
+pre- and post-format. Counts must match:
+
+```bash
+# Snippet markers (javadoc @snippet markup)
+grep -cE '(@highlight|@end|@start|@link|@replace)' \
+    src/main/java -r > /tmp/pre-counts.txt
+grep -cE '(@highlight|@end|@start|@link|@replace)' \
+    src/demo/java -r > /tmp/pre-demo-counts.txt
+
+# Trailing whitespace (forbidden per spec)
+grep -rl ' $' src/main/java > /tmp/pre-trailing.txt
+
+# Format, then re-count
+python3 .java-coding-standards/tooling/scripts/format_file.py \
+    src/main/java src/test/java src/demo/java
+grep -cE '(@highlight|@end|@start|@link|@replace)' \
+    src/main/java -r > /tmp/post-counts.txt
+grep -cE '(@highlight|@end|@start|@link|@replace)' \
+    src/demo/java -r > /tmp/post-demo-counts.txt
+grep -rl ' $' src/main/java > /tmp/post-trailing.txt
+
+diff /tmp/pre-counts.txt /tmp/post-counts.txt              # must be empty
+diff /tmp/pre-demo-counts.txt /tmp/post-demo-counts.txt    # must be empty
+diff /tmp/post-trailing.txt /dev/null                      # must be empty
+```
+
+If any diff is non-empty: the formatter is dropping or
+introducing tokens — file a regression before tagging.
+
+### 5. Idempotency
+
+```bash
+python3 .java-coding-standards/tooling/scripts/format_file.py \
+    src/main/java src/test/java src/demo/java
+```
+
+Second invocation must report `0 modified`. A formatter that
+produces different output on the second pass is non-idempotent
+— file the case as a regression and don't tag.
+
+## What changed in 0.5.0 → 0.5.1
+
+0.5.0's pre-release trial against sz-sdk-java ran ONLY gate 1
+(checkstyle). 0.5.0 shipped with a bug that:
+
+- Silently dropped `// @highlight region="..."` line comments
+  positioned between `=` and a text-block opener on assignment
+  statements (e.g. `String x = // @highlight\n"""...""";`).
+- Was idempotent on the broken output (so the data loss was
+  unrecoverable by re-running the formatter).
+- Was invisible to checkstyle (no rule covers token
+  preservation).
+- Was invisible to `mvn javadoc:javadoc` under the consumer's
+  `java-17` profile (snippet tags were stripped by the profile
+  anyway).
+- Surfaced when CI ran the `java-21` profile, which doesn't
+  strip snippets — javadoc validation failed on unpaired
+  `@end region` markers.
+
+Gates 3 and 4 above are designed to catch this and similar
+data-loss bugs at consumer-trial time, before the standards
+release is tagged. Run them.
+
+## Workflow
+
+```bash
+# Setup: clone consumer with the candidate standards pin
+cd /path/to/consumer
+git checkout -b standards-trial-X.Y.Z
+git -C .java-coding-standards fetch <candidate-remote> <candidate-branch>
+git -C .java-coding-standards checkout FETCH_HEAD
+
+# Run all five gates
+mvn -Pcheckstyle validate                                  # gate 1
+mvn test                                                   # gate 2
+mvn javadoc:javadoc -P <profile-with-snippets-enabled>     # gate 3
+
+# Pre-format snapshot
+grep -cE '(@highlight|@end|@start|@link|@replace)' \
+    $(find src -name '*.java') > /tmp/pre-tokens.txt
+
+# Format
+python3 .java-coding-standards/tooling/scripts/format_file.py \
+    src/main/java src/test/java src/demo/java
+
+# Gate 4 — token round-trip
+grep -cE '(@highlight|@end|@start|@link|@replace)' \
+    $(find src -name '*.java') > /tmp/post-tokens.txt
+diff /tmp/pre-tokens.txt /tmp/post-tokens.txt              # must be empty
+
+# Gate 5 — idempotency
+python3 .java-coding-standards/tooling/scripts/format_file.py \
+    src/main/java src/test/java src/demo/java
+# Must report "0 modified"
+```
+
+If any gate fails, file the case as a regression PR against
+the standards repo and re-run the trial after the fix. Don't
+tag until every trial passes every gate.
+
+## See also
+
+- [Java formatting standards](java-formatting-standards.md)
+- [Javadoc reflow conventions](javadoc-reflow-conventions.md)