Check build hints at compile time instead of shipping them inert

.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

.github/workflows/release-on-maven-central.yml

@@ -113,12 +113,13 @@ jobs:
           # "Deployment failed while publishing" even when the bundle was
           # actually accepted and published. As a safety net for that
           # false-positive case, poll Maven Central for the key artifacts:
-          # the codenameone-maven-plugin (proxy for the core release), its
-          # platform-feature-catalog dependency, and both archetypes. The
-          # catalog is a separate reactor artifact used by the local builders
-          # for built-in platform dependency selection, so confirming only the
-          # plugin could leave a released plugin with an unavailable runtime
-          # dependency. Skipped when the deploy already reported success (the
+          # the codenameone-maven-plugin (proxy for the core release), the two
+          # catalogs it depends on at runtime, and both archetypes. Each catalog
+          # is a separate reactor artifact -- platform-feature-catalog for
+          # built-in platform dependency selection, build-hint-catalog for the
+          # build hint table the plugin reads -- so confirming only the plugin
+          # could leave a released plugin whose own dependency will not resolve.
+          # Skipped when the deploy already reported success (the
           # artifacts may still be propagating from Sonatype Central to repo1;
           # that propagation can take 30+ minutes and isn't worth blocking on).
           set +e
@@ -127,16 +128,19 @@ jobs:
               "https://repo1.maven.org/maven2/com/codenameone/codenameone-maven-plugin/${GITHUB_REF_NAME}/codenameone-maven-plugin-${GITHUB_REF_NAME}.pom")
             catalog_code=$(curl -s -o /dev/null -w "%{http_code}" \
               "https://repo1.maven.org/maven2/com/codenameone/codenameone-platform-feature-catalog/${GITHUB_REF_NAME}/codenameone-platform-feature-catalog-${GITHUB_REF_NAME}.pom")
+            hints_code=$(curl -s -o /dev/null -w "%{http_code}" \
+              "https://repo1.maven.org/maven2/com/codenameone/codenameone-build-hint-catalog/${GITHUB_REF_NAME}/codenameone-build-hint-catalog-${GITHUB_REF_NAME}.pom")
             app_code=$(curl -s -o /dev/null -w "%{http_code}" \
               "https://repo1.maven.org/maven2/com/codenameone/cn1app-archetype/${GITHUB_REF_NAME}/cn1app-archetype-${GITHUB_REF_NAME}.pom")
             lib_code=$(curl -s -o /dev/null -w "%{http_code}" \
               "https://repo1.maven.org/maven2/com/codenameone/cn1lib-archetype/${GITHUB_REF_NAME}/cn1lib-archetype-${GITHUB_REF_NAME}.pom")
             if [ "$plugin_code" = "200" ] && [ "$catalog_code" = "200" ] && \
+               [ "$hints_code" = "200" ] && \
                [ "$app_code" = "200" ] && [ "$lib_code" = "200" ]; then
-              echo "Confirmed plugin + platform-feature-catalog + cn1{app,lib}-archetype ${GITHUB_REF_NAME} on Maven Central"
+              echo "Confirmed plugin + platform-feature-catalog + build-hint-catalog + cn1{app,lib}-archetype ${GITHUB_REF_NAME} on Maven Central"
               exit 0
             fi
-            echo "[$i/90] Waiting on Maven Central (plugin=$plugin_code, catalog=$catalog_code, cn1app=$app_code, cn1lib=$lib_code)"
+            echo "[$i/90] Waiting on Maven Central (plugin=$plugin_code, catalog=$catalog_code, hints=$hints_code, cn1app=$app_code, cn1lib=$lib_code)"
             sleep 20
           done
           echo "Artifacts ${GITHUB_REF_NAME} did not appear on Maven Central within 30 minutes"
@@ -153,6 +157,7 @@ jobs:
           # this keeps the release green even if that rule is ever removed.
           set -e
           for artifact in codenameone-core codenameone-maven-plugin codenameone-platform-feature-catalog \
+                          codenameone-build-hint-catalog \
                           cn1app-archetype cn1lib-archetype; do
             url="${R2_BASE_URL}/com/codenameone/${artifact}/${GITHUB_REF_NAME}/${artifact}-${GITHUB_REF_NAME}.pom?cb=${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
             code=$(curl -s -o /dev/null -w "%{http_code}" "$url")

.github/workflows/windows-cross-build-run.yml

@@ -213,7 +213,7 @@ jobs:
           # translation failure that came and went would have passed on attempt two and taken
           # the gate green with it -- laundering exactly the kind of intermittent product bug
           # this job exists to catch. The unit test workflow narrows it for the same reason.
-          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 vm
           # Through the retry wrapper: this resolves plugins from Maven Central and the runner

.github/workflows/windows-cross-compile.yml

@@ -121,7 +121,7 @@ jobs:
           # retries reuse the previous attempt's target directories, so a partial output
           # can decide the result. Matching the output keeps a real failure terminal on
           # its first occurrence, and the retry starts from clean.
-          resolution='status: (403|429|50[0-9])|Could not transfer artifact|Unresolveable build extension|Non-resolvable import POM|Could not resolve dependencies'
+          resolution='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'
           goal=install
           for delay in 30 120 300 0; do
             # PIPESTATUS, not the pipeline's status: tee succeeds even when mvn does not,