Skip to content

fix: publish IR-built hints into KLIBs on Native/wasm/JS (#105, #106, #113) - #129

Merged
arnaudgiuliani merged 1 commit into
1.2.2from
fix/klib-hints-anchor
Oct 26, 2026
Merged

arnaudgiuliani merged 1 commit into
1.2.2from
fix/klib-hints-anchor

Conversation

@arnaudgiuliani

@arnaudgiuliani arnaudgiuliani commented Oct 26, 2026 •

Copy link
Copy Markdown
Member

Problem

Compile safety reads cross-module hints (org.koin.plugin.hints.*). Most are built in IR, in a synthetic file, and registered with registerFunctionAsMetadataVisible.

On KLIB targets (Native, wasm, JS), Kotlin only serializes such a declaration for a FirFile of the FIR output:

  • strict since Kotlin 2.4.20 (KT-79565, JetBrains/kotlin@00d2669d672);
  • before that, it was a per-package append (KT-73135) that only worked when another FIR-output file shared the hints package.

A synthetic file is never part of the FIR output, so these hints were dropped. As a result:

  • false KOIN-D002 on valid code;
  • real errors silently lost (D001 / D003 / D006): builds went green with real bugs.

JVM was not affected.

Fix

  • Anchor file. On non-JVM platforms, in the root FIR session only, KoinModuleFirGenerator declares a private koin_hints_anchor() in a generated hints-package file. That file is part of the FIR output.
  • Every IR-built hint goes into it. ir/HintFiles.kt (addHintFunctions) parents every hint built in IR to the anchor's file. The helper replaces the five copy-pasted synthetic-file blocks: componentscan_, componentscanfunc_, funcreqs_, annotationincludes_, dsl_, dslincludes_, injectedparams_, callsite, and the relays. On JVM nothing changes: the old synthetic files and goldens are kept.
  • KOIN-W008. When a full-graph check is skipped because a module's definitions are not visible, the plugin now warns and names the module instead of passing silently.

Proof

All runs below use playground playground-apps/app-kmp-klib-hints, with plugin 1.2.1 as RED and this branch as GREEN.

Check 1.2.1 This PR
#105 / #106 / #113 shapes, wasmJs + iosArm64, Kotlin 2.4.0 → 2.4.20 (iOS also on 2.3.20) false D002 pass
Real missing dependency on a KLIB target, Kotlin 2.4.20 silent pass KOIN-D001
verify-wide.sh: every IR hint kind crossed once, KLIB diagnostics vs jvm KLIB reports nothing identical to jvm (D001 Tire, D003 AppOnly, D006 Greeter)
IR-built hint kinds present in the library KLIB 0 of 8 8 of 8
Dependency built with 1.2.1, app on this PR — KOIN-W008 names the module
Definition removed, rebuild without clean — caught
wasm executable run + iOS framework link (Kotlin 2.4.10, 2.4.20) — ok; no hints in the ObjC header
iOS test compilation, js() target, metadata compilation (independent review) — one anchor each, main + test link together
Stress test 0–4 on app-annotations / app-dsl — matches the playground README
JVM suite — all green; no golden changes besides cross_module_annotation_incomplete_fold_no_false_d001 (silent → W008)

wasmJs on Kotlin 2.3.20 fails on both versions with KT-82395, a known limitation of that Kotlin version, not of this change.

To rerun it yourself:

  • ./verify.sh <version> 2.3.20 2.4.0 2.4.10 2.4.20
  • ./verify-wide.sh <version>

Behavior changes (in RELEASE_NOTES_1.2.2.md)

  • Real errors now reported on Native and wasm/JS, the same as on JVM. A build that was green on these targets can now fail on a real problem.
  • New KOIN-W008 on every target, JVM included, for example for an empty @ComponentScan in a dependency. It fails builds that use allWarningsAsErrors.
  • KLIB ABI dumps of KMP libraries gain public org.koin.plugin.hints/* entries once (apiDump). The anchor itself is private and is not in the ABI.
  • On Kotlin ≤ 2.4.10, each hint gets one more metadata copy per extra file in the hints package (pre-existing KT-73135 behavior). Shown harmless: diagnostics, wasm run and iOS link are unchanged.

Not covered yet

  • No automated KLIB test in CI: the JVM suite cannot see this bug, so the proof is the playground scripts.
  • Untested layouts:
    • an empty commonMain;
    • a source set that does not depend on commonMain;
    • Android KMP.
  • The reporters' own projects have not been run against this branch.
  • CompileSafetyValidator still skips silently when the whole graph has zero definitions (low risk, since that graph is genuinely empty).

Fixes #105, fixes #106, fixes #113 (GitHub only auto-closes on merge into the default branch; close them manually when 1.2.2 ships).

…113)

KLIB metadata only serializes a plugin-registered declaration for a FirFile of the
FIR output (strict since Kotlin 2.4.20, KT-79565; per-package before that). Hints
built in IR lived in synthetic files, so on KLIB targets they were dropped: false
KOIN-D002, and real errors (D001/D003/D006) silently lost.

- FIR declares a private `koin_hints_anchor()` in a generated hints-package file
  (non-JVM, root session); every IR-built hint is parented to that file
  (ir/HintFiles.kt, shared by the five former synthetic-file sites). JVM unchanged.
- KOIN-W008: a full-graph check skipped because a module's definitions are not
  visible is now reported, naming the module, instead of passing silently.
- playground-apps/app-kmp-klib-hints: RED/GREEN matrix (verify.sh) and an
  every-hint-kind check against jvm (verify-wide.sh).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant