Build from Source

Single module:

Output: skainet-lang/skainet-lang-core/build/dokka/html/

Aggregated (all modules):

Output: build/dokka/html/index.html

The sk.ainet.dokka precompiled script plugin (build-logic/convention/src/main/kotlin/sk.ainet.dokka.gradle.kts) applies org.jetbrains.dokka and configures:

The plugin is applied to 21 library modules:

Excluded: skainet-bom (no source), skainet-apps/*, skainet-test/*, benchmarks, and skainet-lang-ksp-processor (internal).

The root build.gradle.kts applies the Dokka plugin directly (not apply false) and declares dokka(project(…​)) dependencies for all 21 modules. Running ./gradlew dokkaGenerate at the root produces a unified API reference that includes every module under a single SKaiNET namespace. The root README.md is included as the landing page.

skainet-lang-core and skainet-lang-dag use KSP to generate source code. Their build files include:

This ensures KSP-generated sources are available before Dokka runs.

The workflow .github/workflows/dokka-pages.yml runs on push to main (and manually via workflow_dispatch). It:

Prerequisite: The repository must have Pages configured to deploy from GitHub Actions (Settings > Pages > Source: "GitHub Actions").

The existing operator documentation pipeline (./gradlew generateDocs) is unrelated to Dokka and continues to work as before.

The default target set is jvm, js, wasmJs, wasmWasi, apple (iosArm64, iosSimulatorArm64, macosArm64) and linux (linuxX64, linuxArm64). Android is not a flag — the AGP plugin has to be applied in plugins { }, and the convention plugin fills in its body once it sees it.

Which platforms a module builds comes from the skainet.targets Gradle property, not from skainet { }:

Accepted values are jvm, js, wasmJs, wasmWasi, apple, linux, androidNative, or none. There is also skainet.wasmJs.executable=true.

This split is not cosmetic. Kotlin targets must exist before the module’s own kotlin { } block runs, because the source-set convention accessors (jvmMain, iosArm64Main, …) create source sets on access and KGP then refuses to attach a compilation to a source set that already exists:

A skainet { } block is part of the build script, so anything declared there is only known once it is too late to create targets. Gradle properties are readable while the plugin is being applied. Everything non-structural — namespace, androidJvmTarget, explicitApi, expectActualClasses, kotlinTestInCommonTest — stays in the skainet { } DSL.

The name appears in two places, deliberately: there is one SKaiNET namespace to look for wherever you are. The types behind it differ, because the concerns do.

Applying sk.ainet.multiplatform to the root project is not supported and fails with a message saying so: the root project is not a library module, and its skainet { } block means something else.

Yarn writes a lockfile entry for every resolutions key, whether or not that dependency graph actually requests the package. An unscoped pin for a package that only the JS graph uses therefore adds it — and everything it depends on — to kotlin-js-store/wasm/yarn.lock, where nothing imports it. For webpack that is roughly 76 extra packages the Wasm build would download and install for nothing, and which Dependabot would then report against a lockfile that never uses them.

Pass an NpmPinTarget when a package lives in only one graph:

Check which graph holds a package before deciding:

verifyNpmPins checks each lockfile against its own pin map, so a scoped pin is never reported as missing from the lockfile it was never meant to reach.

verifyNpmPins re-reads the committed lockfiles and fails if any pinned package resolved elsewhere. It is wired into check and runs on the js-wasm leg of .github/workflows/build.yml.

The root plugin is not optional for web modules: sk.ainet.multiplatform fails at configuration time if a module builds js/wasmJs while the root project does not apply sk.ainet.npm-pins. Without it no resolutions are written and verifyNpmPins does not exist to notice — a silent security regression rather than a build error.

The package name is written out rather than derived from the catalog alias, so names a catalog alias cannot spell need nothing special — pin("socket.io", …), pin("@types/node", …). Versions must be exact: a range such as ^8.21.1 is rejected at configuration time, because verifyNpmPins compares the lockfile’s resolved version for equality and a range could never match.

resolutionStrategy only reaches a project’s own configurations — it cannot touch a Gradle plugin’s own classpath (the Android Gradle Plugin, Dokka, KSP, and so on). Those classpaths are resolved before any project’s configurations exist, through a separate mechanism entirely. A high-severity CVE in a transitive dependency of a plugin — not the app — cannot be closed with a mavenPins pin, no matter how the coordinate is spelled.

This came up concretely in issue #1046: 22 high-severity Dependabot alerts (Netty, Jackson, jose4j, jdom2) turned out to be transitive to AGP’s and Dokka’s own plugin classpaths, not the app’s dependency graph — confirmed with ./gradlew buildEnvironment, which prints the classpath used to resolve a project’s plugins. None of those packages are reachable via mavenPins, and none are present in anything SKaiNET publishes to Maven Central, so consumers of the library never load them. The alerts were dismissed as tolerable risk rather than pinned. For a plugin-classpath CVE that genuinely needs fixing, the options are: upgrade the plugin to a version that no longer pulls the vulnerable transitive dependency, or (confirmed to work, but not currently used anywhere in this build) add a buildscript { configurations.classpath { resolutionStrategy { ... } } } block directly to the affected script — mavenPins cannot express this because a build-logic-supplied plugin only runs after the script’s own plugins { } block has already resolved.