[Feature]: Adopt Kotlin’s default Multiplatform hierarchy template

[michalharakal]

🧠 D: DOCUMENT — Problem & Opportunity

Some SKaiNET Kotlin Multiplatform modules manually recreate source-set relationships already provided by Kotlin’s default hierarchy template.

Examples include:

• skainet-backend-api
• skainet-backend-cpu

These modules manually create and connect source sets such as:

commonMain
└── nativeMain
    ├── appleMain
    │   ├── iosMain
    │   └── macosMain
    └── linuxMain

skainet-backend-cpu also explicitly disables the default template:

kotlin.mpp.applyDefaultHierarchyTemplate=false

This duplicates Kotlin Gradle Plugin behavior and makes the hierarchy harder to maintain. It also prevents modules from automatically receiving newer hierarchy changes, such as the shared webMain source set for JS and WasmJS targets.

The repository already contains a better pattern in skainet-io-core: apply the default hierarchy first, then add only genuinely custom source sets such as native64Main.

Relevant files:

• https://github.com/SKaiNET-developers/SKaiNET/blob/develop/skainet-backends/skainet-backend-api/build.gradle.kts
• https://github.com/SKaiNET-developers/SKaiNET/blob/develop/skainet-backends/skainet-backend-cpu/build.gradle.kts
• https://github.com/SKaiNET-developers/SKaiNET/blob/develop/skainet-backends/skainet-backend-cpu/gradle.properties
• https://github.com/SKaiNET-developers/SKaiNET/blob/develop/skainet-io/skainet-io-core/build.gradle.kts

Summary:

Replace manually duplicated standard Kotlin Multiplatform hierarchy wiring with the default hierarchy template, while preserving documented custom source-set relationships where required.

---

🔍 A: ASSESS — Feasibility & Impact

✔️ Feasibility

The migration should be straightforward for modules whose manual hierarchy matches Kotlin’s standard hierarchy.

The existing source directories should continue to work because source sets such as nativeMain, appleMain, iosMain, macosMain, and linuxMain are provided by the default template when matching targets are declared.

Modules with special requirements must be assessed separately. For example, skainet-backend-native-cpu may require custom wiring because of native cinterop commonization.

✔️ Expected Impact

• Reduce duplicated Gradle configuration.
• Automatically inherit future Kotlin hierarchy improvements.
• Enable the standard webMain hierarchy for JS and WasmJS targets.
• Reduce hierarchy-related Gradle warnings.
• Make custom source sets easier to identify and understand.
• Reduce maintenance when targets are added or removed.

✔️ Risks / Constraints

• Published Gradle metadata must remain compatible.
• Native cinterop source sets may require custom target grouping.
• Custom groups such as native64Main must not be removed.
• Compilation and publication tasks must be checked across all supported targets.
• Moving dependencies into webMain should be handled separately unless required by the migration.

✔️ Dependencies

No new dependency is required.

The migration depends on the Kotlin Gradle Plugin already used by the project.

Relevant documentation:

• https://kotlinlang.org/docs/multiplatform/multiplatform-hierarchy.html
• https://kotlinlang.org/docs/whatsnew2220.html#shared-source-set-for-js-and-wasmjs-targets

---

📚 R: RESEARCH — What Must Be Understood First?

Research Tasks

• Identify every module that disables the default hierarchy template.
• Identify standard source sets manually created with dependsOn.
• Confirm which modules are fully covered by the default template.
• Confirm that webMain and webTest are generated for JS and WasmJS targets.
• Compare the resolved source-set hierarchy before and after migration.
• Check whether published metadata changes.
• Assess native cinterop modules separately.
• Document why any module must continue using custom hierarchy wiring.

Open Questions

• Should shared JS and WasmJS dependencies be moved into webMain as part of this issue?
• Does any downstream consumer rely on the existing published source-set metadata?
• Can skainet-backend-native-cpu use the default linuxMain hierarchy?
• Should the default hierarchy policy be enforced through a convention plugin?

---

🛠️ C: CODE — Implementation Plan

Development Tasks

• Remove kotlin.mpp.applyDefaultHierarchyTemplate=false where it is no longer required.
• Remove manual standard hierarchy wiring from skainet-backend-api.
• Remove manual standard hierarchy wiring from skainet-backend-cpu.
• Use source sets generated by the default hierarchy template.
• Verify that webMain and webTest are created where applicable.
• Audit other modules for duplicated standard hierarchy configuration.
• Preserve custom source sets such as native64Main.
• Document all hierarchy configurations that must remain custom.
• Run compilation and publication checks for affected modules.
• Submit a PR referencing this issue.

Acceptance Criteria

• Standard source-set hierarchies are no longer recreated manually.
• Unnecessary hierarchy-template opt-outs are removed.
• JS and WasmJS targets use the standard webMain hierarchy.
• Custom source sets remain functional and documented.
• Existing source files compile for the same intended targets.
• Relevant JVM, Android, JS, Wasm, iOS, macOS, and Linux tasks pass.
• Publication and metadata tasks complete successfully.
• No hierarchy-related regressions are introduced.
• The implementation is reviewed and approved by maintainers.

---

💬 Additional Notes

The migration should distinguish between:

1. Standard hierarchy duplicated manually
   Remove the manual wiring and use Kotlin’s default template.

2. Genuinely custom hierarchy
   Apply the default template first, then add only the custom source sets or relationships required by SKaiNET.

skainet-io-core already demonstrates this approach by using the default hierarchy together with the custom native64Main and native64Test source sets.