Package codeanalyzer-java as a PyPI distribution (with pypi-release.yml)

[rahlk]

Is your feature request related to a problem? Please describe.

codeanalyzer cannot currently be consumed as a self-contained Python package. Users have to clone the repo, install GraalVM/JDK, and build the native binary themselves. The goal of this issue is to publish codeanalyzer-java as a PyPI distribution that bundles a prebuilt, JVM-free native binary, installable with a plain pip install.

The main blocker is that the GraalVM native-image reflection config (the prerequisite for producing a working native binary) is stale and incomplete:

• reflect-config.json still targets the old com.ibm.northstar.* package: 7 stale entries, 0 for the current com.ibm.cldk.* package, and 0 for JavaParser (com.github.javaparser:javaparser-symbol-solver-core:3.26.3 / javaparser-core:3.26.3, build.gradle:124-125).
• proxy-config.json is empty ([]), jni-config.json has a single entry, and resource-config.json lists only one ICU resource — none cover JavaParser.

JavaParser leans heavily on reflection (symbol solver, AST node instantiation, generated metamodel, JSON (de)serialization), so without proper registration the native binary throws reflection exceptions at runtime even though the same code runs fine under java -jar.

Describe the solution you'd like

Ship codeanalyzer-java on PyPI as a wheel that carries a prebuilt native binary, with an automated release pipeline. Work breaks into three parts:

1. (Prerequisite) Restore/regenerate a JavaParser-aware GraalVM native-image config

Regenerate config with the GraalVM tracing agent across multiple sample apps and analysis levels (merge results):

./gradlew fatJar
java -agentlib:native-image-agent=config-merge-dir=src/main/resources/META-INF/native-image-config \
  -jar build/libs/codeanalyzer-<version>.jar \
  -i src/test/resources/sample.applications/daytrader8/source -a 2 -v

Then drop stale com.ibm.northstar.* entries and register the current com.ibm.cldk.* entity classes plus JavaParser's symbol-solver/metamodel classes and any required resources/proxies.

• No com.ibm.northstar.* references remain; com.ibm.cldk.* and JavaParser are covered.
• ./gradlew nativeCompile produces a binary that runs the full sample-app suite with no reflection/JNI/proxy/resource errors.
• Native binary output matches java -jar for the integration test inputs.

2. Python packaging

• Add a Python package layout (e.g. pyproject.toml with a chosen build backend) that wraps the native binary.
• Resolve and invoke the bundled binary at runtime (locate it inside the installed package; expose a console entry point).
• Build per-platform wheels: manylinux (x86_64 + aarch64), macOS (arm64 + x86_64), and Windows (x86_64).
• Keep the wheel version in lockstep with the codeanalyzer binary version (gradle.properties).

2a. Default platform-native install (pip install codeanalyzer just works)

The point of this is that a plain pip install on a supported platform automatically pulls the correct native binary with no flags. To guarantee that, not just enable it:

• Impure, platform-tagged wheels. Each wheel must be marked non-purelib so its platform tag is concrete (…manylinux…, …macosx_…_arm64, win_amd64) — never a universal py3-none-any wheel that would ship one platform's binary everywhere.
• py3-none-<platform> tags. The binary doesn't link CPython, so wheels should target py3 / abi none (installs on any Python 3.x), not a CPython-pinned ABI — avoids needing a wheel per Python minor.
• manylinux compliance via auditwheel. Linux wheels are auditwheel repair-ed to a manylinux policy so they install across distros, not just the build image.
• musllinux coverage (Alpine): build musllinux_1_2 wheels for x86_64 (+ aarch64 if feasible), or explicitly document Alpine as unsupported.
• sdist behavior is unambiguous. Either ship no sdist, or ship an sdist whose build deliberately fails with a clear "no prebuilt codeanalyzer binary for this platform/arch" message — so pip never silently falls back to attempting a from-source GraalVM build on unsupported platforms.
• Verify auto-selection. On each supported platform, a clean pip install codeanalyzer (no --platform/--only-binary flags) resolves to the matching wheel and codeanalyzer --help runs the bundled native binary.

3. Automated release pipeline — pypi-release.yml (cargo-dist-style matrix)

Add a GitHub Actions workflow at .github/workflows/pypi-release.yml that builds native binaries for all supported architectures via a build matrix, modeled on how cargo-dist ships Rust binaries (full cross-platform/cross-arch matrix, one artifact per target, checksums, and a single coordinated release). It should:

• Trigger on a tagged release (and support manual workflow_dispatch).
• Run a matrix build across native runners so each target compiles on its own OS/arch (no fragile cross-compiling where avoidable), covering at minimum:
  • x86_64-unknown-linux-gnu (manylinux) and aarch64-unknown-linux-gnu
  • x86_64-apple-darwin and aarch64-apple-darwin
  • x86_64-pc-windows-msvc
• On each matrix leg: set up GraalVM, run ./gradlew nativeCompile, and produce the platform-specific codeanalyzer binary.
• Package each binary into the correctly-tagged wheel (platform/arch wheel tags) and also build the sdist.
• Emit per-artifact SHA256 checksums (cargo-dist-style) and upload all binaries + wheels + checksums to the GitHub Release for the tag.
• Run a smoke test on each wheel (install it, run codeanalyzer against a sample app) so a broken native config can't ship.
• Fan-in: a final job that gathers all matrix artifacts and publishes the full set to PyPI in one step (prefer Trusted Publishing / OIDC over a long-lived PYPI_API_TOKEN); optionally publish to TestPyPI first.

Describe alternatives you've considered

• Ship the fat JAR and require a JVM — defeats the purpose of a self-contained PyPI install; end users would need GraalVM/JDK.
• Hand-maintain reflect-config.json — brittle and already the source of this drift; the tracing-agent regeneration is far more robust.
• Switch off JavaParser's reflective paths — not feasible without forking the dependency.
• Manual/local publishing instead of pypi-release.yml — error-prone and unreproducible; an automated, tested workflow is required so releases are repeatable and can't ship a broken binary.

Additional context

• Relevant files: build.gradle:188-208 (graalvmNative), build.gradle:124-125 (JavaParser deps), src/main/resources/META-INF/native-image-config/*, gradle.properties (version), README §3 + FAQ, existing .github/workflows/release.yml (reference for the new pypi-release.yml).
• Historical reference config: commit f09e014 ("Update codeanalyzer to use graalvm") has the original reflect-config.json.

[rahlk]

Aligning this with the CLDK codeanalyzer-<lang> packaging standard

This issue already matches the CLDK distribution model (thin PyPI wheel carrying a JVM-free native binary, tag-triggered release pipeline) — and in several respects it's more rigorous than our reference (codeanalyzer-ts): auditwheel manylinux repair, musllinux coverage, per-artifact SHA256 checksums, per-wheel smoke tests, and OIDC over a long-lived token. We're folding those back into the standard. Three things to reconcile so it stays consistent with codeanalyzer-python / codeanalyzer-typescript and the SDKs:

1. Package name → codeanalyzer-java, not codeanalyzer.
The body uses pip install codeanalyzer / codeanalyzer --help. Every backend ships under codeanalyzer-<lang> (codeanalyzer-python, codeanalyzer-typescript), and the Python SDK imports the matching codeanalyzer_java module. Publishing as bare codeanalyzer breaks the convention and the SDK linkage. For full consistency, rename the console entry point to codeanalyzer-java as well, so the distribution name, the import package (codeanalyzer_java), and the CLI command all line up.

2. Expose bin_path() and wire the SDK consumption.
The wheel should expose codeanalyzer_java.bin_path() -> Path (resolve the bundled binary via importlib.resources, restore the POSIX exec bit, raise a clear error if no binary shipped) — not only a console entry point. The Python SDK's JCodeanalyzer resolves in priority order analysis_backend_path → $CODEANALYZER_JAVA_BIN → codeanalyzer_java.bin_path() → in-tree fallback, so this is what lets the SDK drop its bundled JAR. Companion follow-ups (separate PRs in python-sdk): add codeanalyzer-java==<ver> to dependencies, update [tool.backend-versions], and migrate the Java facade off the bundled-JAR path. Keep the version in lockstep across gradle.properties ↔ packaging pyproject/__version__ ↔ python-sdk pins ↔ the TS SDK's pinned release tag.

3. Add release notes to the tagged release.
Tag vX.Y.Z with real notes modeled on codeanalyzer-python's GitHub Releases: a curated Keep a Changelog block (Added / Changed — mark BREAKING — / Fixed) plus the auto-generated "Detailed Changes" PR list. Sourced from a CHANGELOG.md; no empty-body releases.

Nothing above changes the GraalVM/native-image or matrix approach — that native-runner matrix is exactly right (GraalVM can't cross-compile, unlike our Bun-based TS analyzer), and we've corrected the skill to say so.