feat(ci): restructure build-and-test workflow to reduce CI latency

[rstata]

The previous workflow had a build matrix followed by a test matrix, with
tests unable to start until every build coordinate finished (GitHub Actions
needs: is all-or-nothing across a matrix). Linting and coverage
verification were also sequenced behind the full test matrix.

The new structure shortens the critical path by:

• validate-inputs: validates workflow dispatch inputs, runs the Python CI
  script unit tests, and computes the deep coordinate and wide matrix for
  downstream jobs. CI script tests run here because validate-inputs
  executes those scripts directly — a script regression would produce
  untrustworthy outputs, so testing them first halts everything before any
  downstream job acts on bad data.

• build-deep: a single coordinate (first OS × first Java from the input
  lists, defaulting to ubuntu-latest × 17). Runs assembly and uploads a
  build artifact for downstream jobs to consume.

• test-deep: same single coordinate, depends on build-deep. Runs tests,
  coverage report generation, and coverage threshold verification via the
  new testWithCoverage Gradle task.

• docs-verify: same single coordinate, depends on build-deep, runs in
  parallel with test-deep. Generates Dokka API docs, builds the mkdocs
  site, and checks for broken links with djlint.

• test-wide: the remaining OS × Java coordinates. Each wide coordinate
  runs ./gradlew test and depends only on validate-inputs, so all wide
  jobs start immediately — they don't wait for build-deep.

• detekt / ktlint: depend only on validate-inputs (source checkout is
  sufficient), so they also run in parallel with build-deep.

• coverage-verification is eliminated as a separate job; coverage report
  generation and threshold checking are folded into test-deep via the new
  testWithCoverage Gradle task (test + testCodeCoverageReport +
  testCodeCoverageVerification).

validate_inputs.py computes and exposes the deep coordinate (coverage_os,
coverage_java) and the wide matrix (wide_matrix JSON array, has_wide flag)
as GITHUB_OUTPUT values, so the workflow never hardcodes OS or Java version
assumptions.

./gradlew clean has been removed from build-deep. On a fresh CI runner
the build directory is already empty, so clean is a no-op. More
importantly, Gradle's build cache is content-addressed: cache keys are
derived from all task inputs (source files, classpaths, JVM args), so a
cached result is only reused when the inputs are identical to a prior
passing run. We trust that mechanism to ensure correctness rather than
forcing unconditional recompilation.

[rstata]

Just pushed a fix: GRADLE_OPTS_EXTRA was silently ignored by gradlew; renamed to GRADLE_OPTS throughout.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6939b80d02

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Escape workflow outputs before writing user-provided strings

write_outputs emits coverage_os/coverage_java directly into $GITHUB_OUTPUT using raw key=value lines, but those values come from workflow inputs and are only type-validated as strings/ints. A JSON string containing a newline (for example via OS_INPUT) will be parsed successfully and then injected as extra output records, which can overwrite has_wide/wide_matrix and cause downstream jobs to run the wrong matrix or skip checks. Please reject control characters or use multiline-safe output encoding before writing these values.

Useful? React with 👍 / 👎.