0.2.0

Korro 0.2.0

The analysis backend has been migrated from Dokka 1.x (K1 dokka-analysis) to the Kotlin Analysis API (K2, standalone). The DSL is redesigned, the task pipeline is restructured for configuration-cache and build-cache safety, diagnostics are strict by default, and .mdx is now a first-class citizen.

Note

The <!---...--> directive grammar in your markdown files is unchanged — existing .md files keep working without edits.

Highlights

• K2 Analysis API. Dokka 1.x / DokkaResolutionFacade replaced with StandaloneAnalysisAPISession at Kotlin 2.3.20.
• Two-module split. korro-gradle-plugin (thin, Gradle Plugin Portal) + korro-analysis (shadowed Analysis-API fat jar, Maven Central). The analysis jar is loaded at task-execution time via WorkerExecutor.classLoaderIsolation, so it no longer collides with your project's Kotlin Gradle plugin version.
• Configuration-cache and build-cache compatible. korroGenerate writes out-of-place to build/korro/docs/ and is fully cacheable.
• Strict-by-default diagnostics. Unresolved FUN/FUNS, unclosed //SampleStart, and non-function targets fail the build with a single formatted diagnostic table (including Levenshtein short-name hints).
• MDX support. .mdx files use JSX-expression directives, compatible with Mintlify, Docusaurus, and other MDX v2 parsers.
• FUNS directive implemented as a glob filter over FQNs.
• korroCheck task implemented for CI drift detection.

Breaking changes

DSL — nested and Property-based

Top-level container assignments (docs = fileTree(...), samples = fileTree(...), top-level outputs = ...) no longer compile — configuration now lives inside docs { } / samples { } / behavior { } / groupSamples { } blocks.

korro {
    docs {
        from(fileTree(rootDir) { include("**/*.md") })
        baseDir = rootDir                    // REQUIRED
    }
    samples {
        from(fileTree("src/test/samples"))
        outputs.from(fileTree("build/sampleOutputs"))
    }
    behavior {
        ignoreMissing = false
        rewriteAsserts = false
    }
    groupSamples {
        beforeGroup = "<tabs>\n"
        afterGroup = "</tabs>"
        beforeSample = "<tab title=\"NAME\">\n"
        afterSample = "\n</tab>"
    }
}

• docs.baseDir is mandatory — output paths are computed relative to it.
• The top-level outputs property moved inside samples { }.

Tasks

0.1.x	0.2.0
./gradlew korro (mutates source)	./gradlew korro — depends on korroGenerate and copies its output onto the source tree (implemented as Copy, never Sync, to avoid wiping unrelated files under docs.baseDir)
—	./gradlew korroGenerate — @CacheableTask, writes to build/korro/docs/, never touches source
./gradlew korroClean	Removed. Use ./gradlew clean or rm -rf build/korro/
korroCheck (previously README TODO)	Implemented. Regenerates into a temp dir, diffs against the source tree, fails with the first differing line per file. CI entry point.
korroTest (previously README TODO)	Not pursued; deferred

Every task has an @Input korroPluginVersion so cached outputs invalidate on plugin bump (and therefore on Analysis API bump).

Behavior

• Unresolved FUN fails the build. 0.1.x silently kept the stale snippet. Restore with behavior { ignoreMissing = true }.
• assertPrints / assertTrue / assertFalse / assertFails / assertFailsWith are no longer rewritten to commented println. Restore with behavior { rewriteAsserts = true }.
• Unclosed //SampleStart (no matching //SampleEnd in the same function) is now a diagnostic error. 0.1.x silently included the tail.
• Functions with no markers now emit the whole body (minus the outer { }). 0.1.x returned an empty snippet.
• Only fun declarations are valid FUN/FUNS targets. Properties, classes, top-level expressions, and .kts scripts now produce a diagnostic.

New features

FUNS — glob directive

Expands to every function matching an Ant-style glob (*, ?) over the FQNs reachable from the current IMPORT prefixes, in deterministic order (by file path, then source offset). Replaces the funSuffix("_v1") / funSuffix("_v2") pattern for most use cases.

<!---FUNS sample_v*-->
<!---END-->

MDX directives

.mdx files use a JSX-expression form (raw HTML comments are rejected by MDX v2 parsers):

{/*---IMPORT samples--*/}
{/*---FUN exampleTest--*/}
{/*---END--*/}

Selection is automatic by file extension; .md syntax is unchanged.

Other improvements

• Two-tier FQN resolution — short-name index fast-path, dummy-KDoc fallback for qualified / ambiguous names. First-import-wins preserved.
• Diagnostic hints — unresolved FQNs surface the closest short-name matches.
• Integration-test harness — GradleTestKit + golden-file fixtures under integration-tests/fixtures/ (basic, funs, strictErrors, MDX).
• GitHub Actions CI & release workflows — Maven Central + Gradle Plugin Portal publishing.

Baseline requirements

Surface	0.1.x	0.2.0
Gradle	7.0+	8.5+
JDK (build + runtime)	8	17
Bundled Kotlin / Analysis API	1.9.22 (Dokka K1)	2.3.20 (K2)
Plugin id	io.github.devcrocod.korro	unchanged
Directive syntax	<!---NAME VALUE-->	unchanged

The bundled Kotlin version is pinned inside the plugin — your consumer project can use any Kotlin Gradle plugin version.

Installation

plugins {
    id("io.github.devcrocod.korro") version "0.2.0"
}

Migration

Full upgrade guide: MIGRATION.md. A ready-to-copy consumer project lives at integration-tests/fixtures/basic/.

The 0.1.x line is frozen at 0.1.7 on the Gradle Plugin Portal — no maintenance branch.

What's Changed

• Migrate korro to K2 by @devcrocod in #14
• Add version constraints for Kotlin and JUnit dependencies in Renovate config

Full Changelog: v0.1.7...v0.2.0