Analyze architecture

Turn composition into a dependency report, then use verification to find proven missing Canvas bindings. Analysis is optional: the runtime works without it. It supports the exact Kotlin/JVM toolchain boundary.

Install the plugin

Add Maven Central to plugin and dependency repositories. For a supported Kotlin/JVM application:

build.gradle.kts

import org.buildmosaic.gradle.MosaicAnalysisEnforcement
import org.buildmosaic.gradle.MosaicAnalysisRole

plugins {
  kotlin("jvm") version "2.4.20"
  id("org.buildmosaic.analysis") version "0.6.0"
}

repositories { mavenCentral() }

mosaicAnalysis {
  role = MosaicAnalysisRole.APPLICATION
  enforcement = MosaicAnalysisEnforcement.STANDARD
}

In settings.gradle.kts, include mavenCentral() in pluginManagement.repositories alongside gradlePluginPortal(). Add runtime dependencies separately; the analysis plugin does not install Mosaic core or apply Kotlin for you.

Generate the graph

./gradlew mosaicGraph

Open build/reports/mosaic-analysis/graph.md. The Markdown contains Mermaid relationships for Tiles, MultiTiles, Canvas requirements, bindings, and selected dependency contracts. APPLICATION reports also focus on each analysis root and include analyzer findings.

This order graph is derived from real mosaicGraph output. It shows possible static dependencies. It does not show runtime order, duration, execution counts, cache occupancy, or exact MultiTile batches. Use tracing for work that actually executed.

The graph overview makes no verification claim. Unknown and missing requirements remain visible without making graph generation fail; invalid roots, summaries, and conflicting declaration owners fail. You can commit a generated Markdown snapshot for a team’s architecture discussion.

Verify bindings

./gradlew verifyMosaic

Verification also participates in check. Read build/reports/mosaic-analysis/main.txt, including warnings and root status.

Role / enforcement	Behavior
APPLICATION / STANDARD	Fail proven missing obligations; warn on unverifiable boundaries
APPLICATION / STRICT	Fail proven missing obligations and unverifiable boundaries
LIBRARY / either	Validate and export contracts; no application verification

A STANDARD pass with warnings remains UNVERIFIED on uncertain paths. It is not proof of every lookup. Malformed, partial, incompatible, or integrity-invalid summaries are artifact errors and fail in both enforcement modes.

Choose entry contexts

With no explicit roots, APPLICATION discovers the outermost safe execution contexts from selected contracts. If automatic selection cannot establish a safe root, use callable IDs to select your intended entry contexts:

mosaicAnalysis {
  roots.add("app.entry()")
}

Explicit roots replace discovery exactly; they do not add to it. Reports explain selection and any concrete receiver. Unsupported lifecycle callbacks and unresolved virtual dispatch are not silently treated as verified.

A library exports contracts for consuming applications:

mosaicAnalysis {
  role = MosaicAnalysisRole.LIBRARY
}

Libraries omit roots. A library with configured roots fails configuration.

What runs during the build

The compiler extracts source-relative internal shards inside normal main Kotlin compilation. extractMosaicMain assembles current-source shards into one complete summary; it does not run another compiler. With no Kotlin sources, it produces an explicit empty complete summary. The JAR packages that summary at META-INF/mosaic-analysis/v1/summary.json.

Dependency summary changes can rerun verification independently of unchanged source compilation. Incremental, clean, and cache-restored builds must yield the same summary and verification result.

The Gradle plugin documentation owns task wiring, publication, and the full project boundary. The compiler guide owns extraction fidelity; the analysis-core guide owns evaluator and metadata semantics. These provisional build-tooling interfaces are separate from the runtime API and BOM.