Check build hints at compile time instead of shipping them inert

.github/workflows/ant.yml

@@ -46,24 +46,44 @@ jobs:
     - name: Install dependencies
       run: bash scripts/ci/apt-get-install.sh xvfb
     - name: Build with Maven (core + in-tree archetypes)
+      # Every other Maven step in this repository goes through the shared retry
+      # helper because Maven Central answers 403/429 from the runner CDN edge
+      # often enough to kill a step outright -- it dies resolving a dependency
+      # POM, before a line is compiled, so nothing about the branch is being
+      # tested when it happens. This workflow was the one that never did, and it
+      # is a required check. RETRY_ONLY_MATCHING keeps every other failure
+      # failing on the first attempt, so a re-run cannot launder a flaky test
+      # into a pass.
+      env:
+        # These two steps only download and build, so a fetch that never reached
+        # its host is retried here as well -- the skins zip comes from github.com
+        # over the same runner network, and a DNS failure there killed the branch
+        # while Ant's own <get retries> was still inside the outage. NOT added to
+        # the test step below, where retrying a network-dependent test would
+        # launder exactly the flake this repository requires to be root-caused.
+        RETRY_ONLY_MATCHING: 'status( code)?: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM|Could not collect dependencies|UnknownHostException|Unknown host|Connection timed out|Connection reset|Premature end of Content-Length|Error getting https'
       run: |
         # The cn1{app,lib}-archetype modules are part of the maven/ reactor,
         # so this single install also stages them into the local repo.
         # -Darchetype.test.skip=true keeps the build fast; the heavier
         # archetype ITs run in the release workflow.
         cd maven
-        xvfb-run -a mvn install -Plocal-dev-javase -Darchetype.test.skip=true
+        bash ../scripts/ci/retry.sh xvfb-run -a mvn install -Plocal-dev-javase -Darchetype.test.skip=true
 
     - name: Refresh archetype catalog
+      env:
+        RETRY_ONLY_MATCHING: 'status( code)?: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM|Could not collect dependencies|UnknownHostException|Unknown host|Connection timed out|Connection reset|Premature end of Content-Length|Error getting https'
       run: |
         cd maven
-        xvfb-run -a mvn archetype:update-local-catalog -Plocal-dev-javase
-        xvfb-run -a mvn archetype:crawl -Plocal-dev-javase
+        bash ../scripts/ci/retry.sh xvfb-run -a mvn archetype:update-local-catalog -Plocal-dev-javase
+        bash ../scripts/ci/retry.sh xvfb-run -a mvn archetype:crawl -Plocal-dev-javase
     - name: Run Maven Unit Tests
+      env:
+        RETRY_ONLY_MATCHING: 'status( code)?: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM|Could not collect dependencies'
       run: |
         pwd
-        xvfb-run -a bash tests/all.sh
+        bash scripts/ci/retry.sh xvfb-run -a bash tests/all.sh
         cd maven/integration-tests
-        xvfb-run -a bash all.sh
+        bash ../../scripts/ci/retry.sh xvfb-run -a bash all.sh
 
 

.github/workflows/archetype-smoke.yml

@@ -64,7 +64,7 @@ jobs:
         # before it had installed anything, one of several jobs Maven Central refused on this
         # branch in a day. A build failure in our own code still fails on the first attempt.
         env:
-          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Unresolveable build extension|Non-resolvable import POM|or one of its dependencies could not be resolved|authorization failed for https://repo\.maven\.apache\.org|Connection reset|Premature end of Content-Length'
+          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM|or one of its dependencies could not be resolved|authorization failed for https://repo\.maven\.apache\.org|Connection reset|Premature end of Content-Length'
           RETRY_ATTEMPTS: '5'
           RETRY_DELAY_SECONDS: '60'
         run: |

.github/workflows/designer.yml

@@ -86,7 +86,7 @@ jobs:
           # without it, so a test that failed once and passed on a later attempt would take
           # this gate green and hide the race that produced it. The wrapper's own docs
           # require this filter for test-running commands.
-          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Unresolveable build extension|Non-resolvable import POM|Connection reset|Premature end of Content-Length'
+          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM|Connection reset|Premature end of Content-Length'
         run: |
           cd maven
           bash $GITHUB_WORKSPACE/scripts/ci/retry.sh mvn -B -pl designer -am -DunitTests=true -Dcodename1.platform=javase \

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

@@ -8,6 +8,14 @@ on:
       - 'docs/demos/**'
       - 'scripts/developer-guide/**'
       - '.github/workflows/developer-guide-docs.yml'
+      # The build hint table is rendered from the catalog rather than committed,
+      # so a change to either the catalog or the renderer changes what this guide
+      # contains without touching a single file under docs/. While the table was
+      # checked in that edit showed up as a docs diff and triggered this workflow
+      # for free; generating it on the fly took that away, and a malformed table
+      # would then have merged and surfaced in the release documentation build.
+      - 'maven/build-hint-catalog/**'
+      - 'scripts/gen-build-hint-table.sh'
   release:
     types: [published]
   workflow_dispatch:
@@ -39,6 +47,11 @@ jobs:
               - 'scripts/developer-guide/migrate-inline-guide-snippets.py'
               - 'scripts/developer-guide/validate-guide-snippets.py'
               - '.github/workflows/developer-guide-docs.yml'
+              # Triggering the workflow is not enough on its own: the HTML and PDF
+              # build and the steps beside it are gated on this filter, so the
+              # inputs the table is rendered from have to satisfy it too.
+              - 'maven/build-hint-catalog/**'
+              - 'scripts/gen-build-hint-table.sh'
             workflow:
               - '.github/workflows/developer-guide-docs.yml'
 
@@ -48,6 +61,15 @@ jobs:
           distribution: 'temurin'
           java-version: '17'
 
+      # Before anything that reads the guide. The build hint table is rendered
+      # from maven/build-hint-catalog rather than checked in, so the lint, the
+      # image and snippet checks, the HTML and PDF build and Vale all need it on
+      # disk -- and asciidoctor reports a missing include as an error, so getting
+      # this order wrong fails loudly rather than dropping the table quietly.
+      # Unconditional, because every one of those steps is not.
+      - name: Render the build hint table
+        run: scripts/gen-build-hint-table.sh
+
       - name: Install local Codename One Maven artifacts
         if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'
         run: |

.github/workflows/identity-stack.yml

@@ -127,7 +127,7 @@ jobs:
           # without it, so a test that failed once and passed on a later attempt would take
           # this gate green and hide the race that produced it. The wrapper's own docs
           # require this filter for test-running commands.
-          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Unresolveable build extension|Non-resolvable import POM|Connection reset|Premature end of Content-Length'
+          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM|Connection reset|Premature end of Content-Length'
         run: |
           set -euo pipefail
           # Targeted run: OidcCoreTest is the new suite; the *Connect / Login /

.github/workflows/parparvm-tests-windows.yml

@@ -229,7 +229,7 @@ jobs:
           # exists for. A blanket loop lets an intermittent product regression pass on
           # attempt two and turns a blocking gate green -- which is the opposite of what
           # a gate is for, and worse than the flake it was hiding.
-          $resolutionFailure = 'status: (403|429|50[0-9])|Could not transfer artifact|Unresolveable build extension|Non-resolvable import POM|Could not resolve dependencies'
+          $resolutionFailure = 'status: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM|Could not resolve dependencies'
           $ok = $false
           foreach ($delay in 0, 30, 90, 180, 300) {
             if ($delay -gt 0) {

.github/workflows/parparvm-tests.yml

@@ -124,7 +124,7 @@ jobs:
           retry mvn -B clean package -pl JavaAPI -am -DskipTests
           retry mvn -B test -pl tests -am -DexcludedGroups=benchmark
         env:
-          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Unresolveable build extension|Non-resolvable import POM|Connection reset|Premature end of Content-Length'
+          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM|Connection reset|Premature end of Content-Length'
           JDK_8_HOME: ${{ env.JDK_8_HOME }}
           JDK_11_HOME: ${{ env.JDK_11_HOME }}
           JDK_17_HOME: ${{ env.JDK_17_HOME }}
@@ -139,7 +139,7 @@ jobs:
           # without it, so a test that failed once and passed on a later attempt would take
           # this gate green and hide the race that produced it. The wrapper's own docs
           # require this filter for test-running commands.
-          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Unresolveable build extension|Non-resolvable import POM|Connection reset|Premature end of Content-Length'
+          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM|Connection reset|Premature end of Content-Length'
           JDK_8_HOME: ${{ env.JDK_8_HOME }}
           JDK_11_HOME: ${{ env.JDK_11_HOME }}
           JDK_17_HOME: ${{ env.JDK_17_HOME }}

.github/workflows/pr.yml

@@ -27,6 +27,16 @@ on:
       - 'scripts/ci/retry.sh'
       - 'scripts/ci/apt-get-update.sh'
       - 'scripts/ci/apt-get-install.sh'
+      # The build hint gates are run from this workflow and nowhere else, and one
+      # of them holds an empty baseline. Ignoring the whole directory meant a
+      # change that breaks a gate, or that adds a line to the baseline, could
+      # merge without the gate it weakens ever running.
+      - 'scripts/check-build-hint-catalog.sh'
+      - 'scripts/check-build-hint-catalog.py'
+      - 'scripts/build_hint_miner.py'
+      - 'scripts/build-hint-catalog-baseline.txt'
+      - 'scripts/build-hint-computed-sites.txt'
+      - 'scripts/gen-build-hint-annotations.sh'
       - '!docs/**'
       - '!**/*.md'
       - '!.github/workflows/developer-guide-docs.yml'
@@ -59,6 +69,16 @@ on:
       - 'scripts/ci/retry.sh'
       - 'scripts/ci/apt-get-update.sh'
       - 'scripts/ci/apt-get-install.sh'
+      # The build hint gates are run from this workflow and nowhere else, and one
+      # of them holds an empty baseline. Ignoring the whole directory meant a
+      # change that breaks a gate, or that adds a line to the baseline, could
+      # merge without the gate it weakens ever running.
+      - 'scripts/check-build-hint-catalog.sh'
+      - 'scripts/check-build-hint-catalog.py'
+      - 'scripts/build_hint_miner.py'
+      - 'scripts/build-hint-catalog-baseline.txt'
+      - 'scripts/build-hint-computed-sites.txt'
+      - 'scripts/gen-build-hint-annotations.sh'
       - '!docs/**'
       - '!**/*.md'
       - '!.github/workflows/developer-guide-docs.yml'
@@ -140,7 +160,7 @@ jobs:
         # RETRY_ONLY_MATCHING keeps a failing test failing on the first attempt
         # rather than letting a re-run launder a flake into a pass.
         env:
-          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Unresolveable build extension|Non-resolvable import POM'
+          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM'
         run: |
           MVN_GOAL="verify"
           MVN_ARGS=""
@@ -416,6 +436,20 @@ jobs:
       - name: Run SpotBugs for ByteCodeTranslator
         if: ${{ matrix.java-version == 8 }}
         run: mvn -B -DskipTests=true -f vm/ByteCodeTranslator/pom.xml verify
+      # A build hint is a string nothing checks: a misspelled name is accepted,
+      # never read, and silently does nothing. The catalog in
+      # maven/build-hint-catalog is what gives every hint a type, a default and a
+      # value domain, and it is what the @Ios/@Android annotations, the developer
+      # guide table and the Settings tool are generated from. These two steps keep
+      # the catalog complete and the generated files in step with it.
+      - name: Check build hint catalog
+        if: ${{ matrix.java-version == 8 }}
+        run: scripts/check-build-hint-catalog.sh
+      - name: Check generated build hint annotations
+        if: ${{ matrix.java-version == 8 }}
+        run: |
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+          scripts/gen-build-hint-annotations.sh --check
       # ParparVM's CHECKCAST is unchecked, so a failed cast does not throw
       # ClassCastException on iOS -- code written to catch it silently uses the
       # wrong object instead (issue #5531). core/android/ios are already compiled
@@ -449,7 +483,7 @@ jobs:
         # could not be resolved" before a single test had run -- a Maven Central failure, which a
         # missing plugin version fails identically on every attempt anyway.
         env:
-          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Unresolveable build extension|Non-resolvable import POM|or one of its dependencies could not be resolved|authorization failed for https://repo\.maven\.apache\.org|Connection reset|Premature end of Content-Length'
+          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM|or one of its dependencies could not be resolved|authorization failed for https://repo\.maven\.apache\.org|Connection reset|Premature end of Content-Length'
           # Five attempts a minute apart rather than three at thirty seconds: Central
           # refused two different jobs on this branch today, and a window of about a
           # minute is shorter than the incidents have been. It costs nothing on a real

.github/workflows/protocol-e2e.yml

@@ -40,7 +40,7 @@ jobs:
         # here with "Unresolveable build extension: archetype-packaging ... could not be resolved"
         # before anything was compiled, which is Maven Central rather than this repository.
         env:
-          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Unresolveable build extension|Non-resolvable import POM|or one of its dependencies could not be resolved|authorization failed for https://repo\.maven\.apache\.org|Connection reset|Premature end of Content-Length'
+          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM|or one of its dependencies could not be resolved|authorization failed for https://repo\.maven\.apache\.org|Connection reset|Premature end of Content-Length'
           # Five attempts a minute apart rather than three at thirty seconds: Central
           # refused two different jobs on this branch today, and a window of about a
           # minute is shorter than the incidents have been. It costs nothing on a real

.github/workflows/purchase-e2e.yml

@@ -104,7 +104,7 @@ jobs:
         # with "authorization failed for https://repo.maven.apache.org/maven2" against the JUnit
         # BOM and the publishing plugin -- Maven Central, not this repository.
         env:
-          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Unresolveable build extension|Non-resolvable import POM|or one of its dependencies could not be resolved|authorization failed for https://repo\.maven\.apache\.org|Connection reset|Premature end of Content-Length'
+          RETRY_ONLY_MATCHING: 'status: (403|429|50[0-9])|Could not transfer artifact|Failed to read artifact descriptor|Unresolveable build extension|Non-resolvable import POM|or one of its dependencies could not be resolved|authorization failed for https://repo\.maven\.apache\.org|Connection reset|Premature end of Content-Length'
           # Five attempts a minute apart rather than three at thirty seconds: Central
           # refused two different jobs on this branch today, and a window of about a
           # minute is shorter than the incidents have been. It costs nothing on a real