Add grammar checks to developer guide CI

.github/workflows/developer-guide-docs.yml

@@ -270,6 +270,52 @@ jobs:
             echo "Vale exited with status $STATUS and reported $ISSUE_COUNT issue(s). The final quality-gate step will fail the build." >&2
           fi
 
+      - name: Run paragraph capitalization check
+        run: |
+          set -euo pipefail
+          REPORT_DIR="build/developer-guide/reports"
+          REPORT_FILE="${REPORT_DIR}/paragraph-capitalization-report.json"
+          mkdir -p "$REPORT_DIR"
+          set +e
+          ruby scripts/developer-guide/check_paragraph_capitalization.rb \
+            --output "$REPORT_FILE" \
+            docs/developer-guide/developer-guide.asciidoc
+          STATUS=$?
+          set -e
+          echo "PARAGRAPH_CAP_REPORT=$REPORT_FILE" >> "$GITHUB_ENV"
+          echo "PARAGRAPH_CAP_STATUS=$STATUS" >> "$GITHUB_ENV"
+          if [ "$STATUS" -ne 0 ]; then
+            echo "Paragraph capitalization check failed. The final quality-gate step will fail the build." >&2
+          fi
+
+      - name: Set up Java 17 for LanguageTool
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
+      - name: Install language-tool-python
+        run: |
+          set -euo pipefail
+          pip install --user language-tool-python==2.9.4
+
+      - name: Run LanguageTool grammar check (advisory)
+        run: |
+          set -euo pipefail
+          REPORT_DIR="build/developer-guide/reports"
+          REPORT_FILE="${REPORT_DIR}/languagetool-report.json"
+          mkdir -p "$REPORT_DIR"
+          set +e
+          python3 scripts/developer-guide/run_languagetool.py \
+            --html build/developer-guide/html/developer-guide.html \
+            --output "$REPORT_FILE"
+          STATUS=$?
+          set -e
+          LT_COUNT="$(python3 -c 'import json,sys; d=json.load(open(sys.argv[1])); print(d.get("total",0))' "$REPORT_FILE" 2>/dev/null || echo 0)"
+          echo "LANGUAGETOOL_REPORT=$REPORT_FILE" >> "$GITHUB_ENV"
+          echo "LANGUAGETOOL_COUNT=$LT_COUNT" >> "$GITHUB_ENV"
+          echo "LanguageTool flagged ${LT_COUNT} match(es). This is advisory and does not fail the build." >&2
+
       - name: Check for unused developer guide images
         run: |
           set -euo pipefail
@@ -316,6 +362,23 @@ jobs:
             --details-key details \
             --preview-limit 10
 
+      - name: Summarize paragraph capitalization findings
+        id: summarize_paragraph_cap
+        if: always()
+        run: |
+          python3 scripts/developer-guide/summarize_reports.py paragraph-capitalization \
+            --report "${PARAGRAPH_CAP_REPORT}" \
+            --status "${PARAGRAPH_CAP_STATUS:-0}" \
+            --output "${GITHUB_OUTPUT}"
+
+      - name: Summarize LanguageTool findings
+        id: summarize_languagetool
+        if: always()
+        run: |
+          python3 scripts/developer-guide/summarize_reports.py languagetool \
+            --report "${LANGUAGETOOL_REPORT}" \
+            --output "${GITHUB_OUTPUT}"
+
       - name: Upload HTML artifact
         if: always()
         uses: actions/upload-artifact@v4
@@ -360,6 +423,22 @@ jobs:
             ${{ env.UNUSED_IMAGES_TEXT }}
           if-no-files-found: warn
 
+      - name: Upload paragraph capitalization report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: developer-guide-paragraph-capitalization
+          path: ${{ env.PARAGRAPH_CAP_REPORT }}
+          if-no-files-found: warn
+
+      - name: Upload LanguageTool report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: developer-guide-languagetool
+          path: ${{ env.LANGUAGETOOL_REPORT }}
+          if-no-files-found: warn
+
       - name: Fail build on developer guide quality issues
         if: always()
         run: |
@@ -379,6 +458,11 @@ jobs:
             echo "Either delete the orphan image or add an image:: reference for it from a developer-guide asciidoc file." >&2
             FAIL=1
           fi
+          if [ "${PARAGRAPH_CAP_STATUS:-0}" != "0" ]; then
+            echo "Paragraph capitalization check reported findings (exit status ${PARAGRAPH_CAP_STATUS}). See the developer-guide-paragraph-capitalization artifact." >&2
+            echo "Rewrite the flagged paragraph so its first prose word starts with a capital letter." >&2
+            FAIL=1
+          fi
           if [ "$FAIL" -ne 0 ]; then
             echo "Developer guide quality gates failed. Warnings from vale and asciidoctor are treated as build-breaking errors." >&2
             exit 1
@@ -393,6 +477,8 @@ jobs:
           VALE_SUMMARY: ${{ steps.summarize_vale.outputs.summary }}
           UNUSED_SUMMARY: ${{ steps.summarize_unused_images.outputs.summary }}
           UNUSED_DETAILS: ${{ steps.summarize_unused_images.outputs.details }}
+          PARAGRAPH_CAP_SUMMARY: ${{ steps.summarize_paragraph_cap.outputs.summary }}
+          LANGUAGETOOL_SUMMARY: ${{ steps.summarize_languagetool.outputs.summary }}
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -448,6 +534,12 @@ jobs:
             if (artifactLinks.has('developer-guide-unused-images')) {
               links.push(`- [Unused image report](${artifactLinks.get('developer-guide-unused-images')})`);
             }
+            if (artifactLinks.has('developer-guide-paragraph-capitalization')) {
+              links.push(`- [Paragraph capitalization report](${artifactLinks.get('developer-guide-paragraph-capitalization')})`);
+            }
+            if (artifactLinks.has('developer-guide-languagetool')) {
+              links.push(`- [LanguageTool report (advisory)](${artifactLinks.get('developer-guide-languagetool')})`);
+            }
 
             if (!links.length) {
               console.log('No artifacts found to report.');
@@ -458,16 +550,26 @@ jobs:
             const asciiSummary = process.env.ASCII_SUMMARY?.trim();
             const valeSummary = process.env.VALE_SUMMARY?.trim();
             const unusedSummary = process.env.UNUSED_SUMMARY?.trim();
+            const paragraphCapSummary = process.env.PARAGRAPH_CAP_SUMMARY?.trim();
+            const languagetoolSummary = process.env.LANGUAGETOOL_SUMMARY?.trim();
             const asciiLink = artifactLinks.get('developer-guide-asciidoc-lint');
             const valeLink = artifactLinks.get('developer-guide-vale-report');
             const unusedLink = artifactLinks.get('developer-guide-unused-images');
+            const paragraphCapLink = artifactLinks.get('developer-guide-paragraph-capitalization');
+            const languagetoolLink = artifactLinks.get('developer-guide-languagetool');
 
             if (asciiSummary) {
               qualityLines.push(`- AsciiDoc linter: ${asciiSummary}${asciiLink ? ` ([report](${asciiLink}))` : ''}`);
             }
             if (valeSummary) {
               qualityLines.push(`- Vale: ${valeSummary}${valeLink ? ` ([report](${valeLink}))` : ''}`);
             }
+            if (paragraphCapSummary) {
+              qualityLines.push(`- Paragraph capitalization: ${paragraphCapSummary}${paragraphCapLink ? ` ([report](${paragraphCapLink}))` : ''}`);
+            }
+            if (languagetoolSummary) {
+              qualityLines.push(`- LanguageTool (advisory): ${languagetoolSummary}${languagetoolLink ? ` ([report](${languagetoolLink}))` : ''}`);
+            }
             if (unusedSummary) {
               qualityLines.push(`- Image references: ${unusedSummary}${unusedLink ? ` ([report](${unusedLink}))` : ''}`);
             }

docs/developer-guide/.vale.ini

@@ -68,6 +68,16 @@ Packages = https://github.com/errata-ai/packages/releases/download/v0.2.0/Micros
 #   does not equal "the same" (it allows different representations), etc.
 #   The rule's substitutions damage precision.
 #
+# write-good.ThereIs
+#   Flags any sentence that starts with "There is/are/was/were". The rule's
+#   premise — that sentences are stronger led by the subject — is reasonable
+#   in marketing copy but routinely wrong for technical reference. Existential
+#   "There are" is the natural way to introduce a count or set
+#   ("There are two ways to animate..."), and the rule's recommended rewrite
+#   ("Two ways to animate exist...") is awkward and harder to read. This rule
+#   also blocked the documented fix to a previous PR-5000-class bug, which is
+#   the situation our new paragraph-capitalization check is meant to catch.
+#
 # Microsoft.GeneralURL
 #   Suggests "address" instead of "URL" "for a general audience". Our audience
 #   is developers wiring up HTTP requests; "URL" is the term every other API
@@ -173,6 +183,7 @@ Microsoft.Passive = NO
 write-good.E-Prime = NO
 write-good.Weasel = NO
 write-good.TooWordy = NO
+write-good.ThereIs = NO
 Microsoft.GeneralURL = NO
 Microsoft.HeadingAcronyms = NO
 Microsoft.Terms = NO

docs/developer-guide/Advanced-Theming.asciidoc

@@ -751,7 +751,7 @@ The type is omitted for the default unselected type, and may be one of _sel_ (se
 *	`backgroundType` - a `Byte` object containing one of the constants for the background type defined in https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html[Style] under BACKGROUND_*.
 *	`backgroundGradient` - contains an `Object` array containing 2 integers for the colors of the gradient. If the gradient is radial it contains 3 floating points defining the x, y & size of the gradient.
 
-to set the foreground color of a selected button to red, a theme will define a property like:
+To set the foreground color of a selected button to red, a theme will define a property like:
 
 `Button.sel#fgColor=ff0000`
 
@@ -1118,7 +1118,7 @@ include::../demos/common/src/main/java/com/codenameone/developerguide/advancedth
 
 ==== Styling the UI
 
-the code above is most of the work but you still need to put everything together using the theme. This is what you've so far:
+The code above is most of the work but you still need to put everything together using the theme. This is what you've so far:
 
 .Before applying the changes to the theme this is what you've
 image::img/psd2app-image15.png[Before applying the changes to the theme this is what you've,scaledwidth=20%]