feat(gradle): compile and check Lua sources

Author: dnlblasco

mawu-gradle-plugin/src/main/kotlin/net/blueva/mawu/gradle/MawuClasspath.kt

@@ -0,0 +1,102 @@
+/*
+ * Mawu
+ * https://github.com/BluevaDevelopment/Mawu
+ *
+ * Copyright (c) 2026 Blueva Development
+ *
+ * SPDX-License-Identifier: GPL-3.0-only
+ */
+package net.blueva.mawu.gradle
+
+import java.io.Closeable
+import java.io.File
+import java.net.URLClassLoader
+import java.util.zip.ZipFile
+
+/**
+ * What the host project's classpath holds, as the build sees it.
+ *
+ * Classes are asked for by loading them; packages are read off the entries,
+ * since no loader can be asked whether a package exists.
+ */
+internal class MawuClasspath(files: Collection<File>) : Closeable {
+
+    private val loader = URLClassLoader(
+        files.map { it.toURI().toURL() }.toTypedArray(),
+        ClassLoader.getPlatformClassLoader()
+    )
+
+    private val packages: Set<String> by lazy { packagesOf(files) + platformPackages() }
+
+    private val resolved = HashMap<String, Class<*>?>()
+
+    /** Whether [name] is a class here. */
+    fun hasClass(name: String): Boolean = classOf(name) != null
+
+    /** The class [name] stands for, or null. A walk asks for the same names often. */
+    fun classOf(name: String): Class<*>? = resolved.getOrPut(name) {
+        try {
+            Class.forName(name, false, loader)
+        } catch (e: ClassNotFoundException) {
+            null
+        } catch (e: LinkageError) {
+            null
+        }
+    }
+
+    /** Whether [name] is a package holding at least one class. */
+    fun hasPackage(name: String): Boolean = name in packages
+
+    override fun close() = loader.close()
+
+    private fun packagesOf(files: Collection<File>): Set<String> {
+        val found = mutableSetOf<String>()
+        for (file in files) {
+            when {
+                file.isDirectory -> file.walkTopDown()
+                    .filter { it.isFile && it.extension == "class" }
+                    .forEach { found += packageOf(it.relativeTo(file).invariantSeparatorsPath) }
+
+                file.isFile && file.extension in ARCHIVES -> readArchive(file, found)
+            }
+        }
+        return found
+    }
+
+    private fun readArchive(file: File, found: MutableSet<String>) {
+        try {
+            ZipFile(file).use { archive ->
+                for (entry in archive.entries()) {
+                    if (!entry.isDirectory && entry.name.endsWith(".class")) {
+                        found += packageOf(entry.name)
+                    }
+                }
+            }
+        } catch (e: Exception) {
+            // A jar the build cannot read says nothing about what a script named.
+        }
+    }
+
+    /** Every package of an entry path, including the prefixes leading to it. */
+    private fun packageOf(path: String): Set<String> {
+        val segments = path.substringBeforeLast('/', "").split('/').filter { it.isNotEmpty() }
+        return segments.indices.map { segments.take(it + 1).joinToString(".") }.toSet()
+    }
+
+    private operator fun MutableSet<String>.plusAssign(names: Set<String>) {
+        addAll(names)
+    }
+
+    private fun platformPackages(): Set<String> =
+        ModuleLayer.boot().modules()
+            .flatMap { it.packages }
+            .flatMap { name ->
+                val segments = name.split('.')
+                segments.indices.map { segments.take(it + 1).joinToString(".") }
+            }
+            .toSet()
+
+    private companion object {
+        val ARCHIVES = setOf("jar", "zip")
+    }
+}

mawu-gradle-plugin/src/main/kotlin/net/blueva/mawu/gradle/MawuCompile.kt

@@ -0,0 +1,287 @@
+/*
+ * Mawu
+ * https://github.com/BluevaDevelopment/Mawu
+ *
+ * Copyright (c) 2026 Blueva Development
+ *
+ * SPDX-License-Identifier: GPL-3.0-only
+ */
+package net.blueva.mawu.gradle
+
+import net.blueva.luak.LuaError
+import net.blueva.luak.Prototype
+import net.blueva.luak.compiler.DumpState
+import net.blueva.luak.compiler.LuaC
+import net.blueva.luak.lib.jvm.JvmPlatform
+import net.blueva.mawu.bridge.MawuJava
+import net.blueva.mawu.runtime.MawuLayout
+import org.gradle.api.DefaultTask
+import org.gradle.api.GradleException
+import org.gradle.api.file.ConfigurableFileCollection
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.FileSystemOperations
+import org.gradle.api.provider.Property
+import org.gradle.api.provider.SetProperty
+import org.gradle.api.tasks.CacheableTask
+import org.gradle.api.tasks.Classpath
+import org.gradle.api.tasks.Input
+import org.gradle.api.tasks.InputFiles
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.PathSensitive
+import org.gradle.api.tasks.PathSensitivity
+import org.gradle.api.tasks.TaskAction
+import org.gradle.work.ChangeType
+import org.gradle.work.Incremental
+import org.gradle.work.InputChanges
+import java.io.BufferedOutputStream
+import java.io.File
+import java.net.URLClassLoader
+import javax.inject.Inject
+
+/**
+ * Compiles Lua sources into Luak prototypes, laid out as resources.
+ *
+ * Nothing here emits JVM bytecode: what lands in the jar is Lua bytecode plus
+ * the index the runtime reads to find it.
+ */
+@CacheableTask
+abstract class MawuCompile : DefaultTask() {
+
+    /** Source directories holding `.lua` files. */
+    @get:InputFiles
+    @get:Incremental
+    @get:PathSensitive(PathSensitivity.RELATIVE)
+    abstract val source: ConfigurableFileCollection
+
+    /** Whether to drop line numbers and local names from the compiled output. */
+    @get:Input
+    abstract val stripDebugInfo: Property<Boolean>
+
+    /** What to do about a global a script reads that nothing defines. */
+    @get:Input
+    abstract val undefinedGlobals: Property<MawuSeverity>
+
+    /** Globals the host installs at runtime, which scripts may read freely. */
+    @get:Input
+    abstract val knownGlobals: SetProperty<String>
+
+    /** What to do about an import naming a class the classpath does not have. */
+    @get:Input
+    abstract val unknownClasses: Property<MawuSeverity>
+
+    /** Where an imported class is looked for. */
+    @get:Classpath
+    abstract val classpath: ConfigurableFileCollection
+
+    /** Resource root the compiled scripts and their index are written to. */
+    @get:OutputDirectory
+    abstract val destinationDirectory: DirectoryProperty
+
+    @get:Inject
+    protected abstract val fileSystem: FileSystemOperations
+
+    @TaskAction
+    fun compile(changes: InputChanges) {
+        val outputRoot = destinationDirectory.get().asFile
+        if (!changes.isIncremental) {
+            fileSystem.delete { it.delete(outputRoot) }
+        }
+
+        // The index needs every id either way.
+        val sources = collectSources()
+        val stale = if (changes.isIncremental) removedIds(changes) else emptySet()
+        val outdated = if (changes.isIncremental) changedIds(changes) else sources.keys
+
+        for (id in stale) {
+            outputOf(id).delete()
+        }
+
+        val failures = mutableListOf<String>()
+        val compiled = LinkedHashMap<String, Prototype>()
+        for (id in outdated) {
+            val file = sources[id] ?: continue
+            try {
+                val prototype = compile(id, file)
+                write(id, prototype)
+                compiled[id] = prototype
+            } catch (e: LuaError) {
+                failures += describe(id, file, e)
+            }
+        }
+        if (failures.isNotEmpty()) {
+            val header = if (failures.size == 1) {
+                "Lua compilation failed:"
+            } else {
+                "Lua compilation failed in ${failures.size} sources:"
+            }
+            throw GradleException(failures.joinToString("\n", prefix = "$header\n"))
+        }
+
+        val prototypes = allPrototypes(sources, compiled)
+        checkGlobals(sources, prototypes)
+        checkReferences(sources, prototypes)
+
+        if (sources.isNotEmpty()) {
+            writeIndex(outputRoot, sources.keys)
+        }
+        logger.info("Mawu compiled {} of {} Lua scripts into {}", outdated.size, sources.size, outputRoot)
+    }
+
+    /**
+     * Reports a global that nothing in this source set, the standard library
+     * or the host defines. Every script is looked at, since a global defined
+     * in one file is read in another.
+     */
+    private fun checkGlobals(sources: Map<String, File>, prototypes: Map<String, Prototype>) {
+        val severity = undefinedGlobals.get()
+        if (severity == MawuSeverity.IGNORE || prototypes.isEmpty()) return
+
+        val usages = prototypes.mapValues { MawuGlobals.of(it.value) }
+        val defined = standardGlobals() + knownGlobals.get() + usages.values.flatMap { it.writes }
+        val reported = usages.flatMap { (id, usage) ->
+            usage.reads
+                .filterNot { it.name in defined }
+                .distinct()
+                .map { "${sources.getValue(id).path}:${it.line}: undefined global '${it.name}'" }
+        }
+        report(severity, reported, "Undefined globals:")
+    }
+
+    /**
+     * Reports a class, package or member a script names that the classpath
+     * does not have. A name only known at runtime is what the severity is for.
+     */
+    private fun checkReferences(sources: Map<String, File>, prototypes: Map<String, Prototype>) {
+        val severity = unknownClasses.get()
+        if (severity == MawuSeverity.IGNORE || prototypes.isEmpty()) return
+
+        MawuClasspath(classpath.files).use { available ->
+            val reported = mutableListOf<String>()
+            for ((id, prototype) in prototypes) {
+                val path = sources.getValue(id).path
+                val references = MawuReferences.of(prototype) { available.classOf(it) }
+
+                references.classes
+                    .filterNot { available.hasClass(it.name) }
+                    .forEach { reported += "$path:${it.line}: no class named '${it.name}' on the classpath" }
+
+                references.names
+                    .filterNot { available.hasClass(it.name) || available.hasPackage(it.name) }
+                    .forEach { reported += "$path:${it.line}: no class or package named '${it.name}'" }
+
+                for (member in references.members) {
+                    val owner = available.classOf(member.owner) ?: continue
+                    if (!hasMember(owner, member.member)) {
+                        reported += "$path:${member.line}: '${member.owner}' has no member '${member.member}'"
+                    }
+                }
+            }
+            report(severity, reported, "Unknown classes:")
+        }
+    }
+
+    /** Whether Lua would find [name] on [owner], the way Luak looks for it. */
+    private fun hasMember(owner: Class<*>, name: String): Boolean =
+        name == "new" ||
+            owner.methods.any { it.name == name } ||
+            owner.fields.any { it.name == name } ||
+            owner.classes.any { it.simpleName == name }
+
+    /** Fails or warns, depending on what the build asked for. */
+    private fun report(severity: MawuSeverity, diagnostics: List<String>, header: String) {
+        if (diagnostics.isEmpty()) return
+        if (severity == MawuSeverity.ERROR) {
+            throw GradleException(diagnostics.joinToString("\n", prefix = "$header\n"))
+        }
+        diagnostics.forEach { logger.warn("w: {}", it) }
+    }
+
+    /** Every script's compiled form, parsing the ones this run did not compile. */
+    private fun allPrototypes(sources: Map<String, File>, compiled: Map<String, Prototype>): Map<String, Prototype> {
+        if (undefinedGlobals.get() == MawuSeverity.IGNORE && unknownClasses.get() == MawuSeverity.IGNORE) {
+            return emptyMap()
+        }
+        val prototypes = LinkedHashMap<String, Prototype>(compiled)
+        for ((id, file) in sources) {
+            if (id in prototypes) continue
+            prototypes[id] = try {
+                compile(id, file)
+            } catch (e: LuaError) {
+                continue
+            }
+        }
+        return prototypes
+    }
+
+    /** Every name a script finds in its environment before the host adds any. */
+    private fun standardGlobals(): Set<String> {
+        val globals = JvmPlatform.standardGlobals()
+        MawuJava.install(globals)
+        return globals.keys().mapNotNull { it?.tojstring() }.toSet() + "_ENV"
+    }
+
+    /**
+     * The compiler's message against the file it belongs to. Lua reports the
+     * chunk name; the real path in its place is a line an IDE can open.
+     */
+    private fun describe(id: String, file: File, error: LuaError): String {
+        val message = error.message ?: "failed to compile"
+        val chunk = "$id.lua:"
+        return if (message.startsWith(chunk)) {
+            "${file.path}:${message.removePrefix(chunk)}"
+        } else {
+            "${file.path}: $message"
+        }
+    }
+
+    /** Ids whose source was added or modified since the last run. */
+    private fun changedIds(changes: InputChanges): Set<String> =
+        changes.getFileChanges(source)
+            .filter { it.changeType != ChangeType.REMOVED && it.file.isFile }
+            .map { MawuLayout.idOf(it.normalizedPath) }
+            .toSet()
+
+    /** Ids whose source is gone, and whose compiled form has to go with it. */
+    private fun removedIds(changes: InputChanges): Set<String> =
+        changes.getFileChanges(source)
+            .filter { it.changeType == ChangeType.REMOVED }
+            .map { MawuLayout.idOf(it.normalizedPath) }
+            .toSet()
+
+    /** Every source file by script id, sorted so the output is reproducible. */
+    private fun collectSources(): Map<String, File> {
+        val found = sortedMapOf<String, File>()
+        source.asFileTree.matching { it.include("**/*.lua") }.visit { details ->
+            if (!details.isDirectory) {
+                val id = MawuLayout.idOf(details.relativePath.pathString)
+                val previous = found.put(id, details.file)
+                if (previous != null) {
+                    throw GradleException(
+                        "Two Lua sources compile to the same script id '$id': $previous and ${details.file}"
+                    )
+                }
+            }
+        }
+        return found
+    }
+
+    private fun compile(id: String, file: File): Prototype =
+        file.inputStream().buffered().use { LuaC.instance.compile(it, MawuLayout.chunkName(id)) }
+
+    private fun outputOf(id: String): File =
+        destinationDirectory.get().file(MawuLayout.resourcePath(id)).asFile
+
+    private fun write(id: String, prototype: Prototype) {
+        val target = outputOf(id)
+        target.parentFile.mkdirs()
+        BufferedOutputStream(target.outputStream()).use {
+            DumpState.dump(prototype, it, stripDebugInfo.get())
+        }
+    }
+
+    private fun writeIndex(outputRoot: File, ids: Collection<String>) {
+        val index = File(outputRoot, MawuLayout.INDEX)
+        index.parentFile.mkdirs()
+        index.writeText(ids.joinToString(separator = "\n", postfix = "\n"))
+    }
+}