AgentTranscriptLayoutGuard.kt

    fun audit(repo: File): AuditResult {
        val corpus = File(repo, CORPUS_REL)
        val demosDir = File(repo, DEMOS_REL)
        val problems = mutableListOf<String>()
        if (!corpus.isDirectory) {
            return AuditResult(0, 0, 0, 0, listOf("no transcript corpus at ${corpus.absolutePath}"))
        }
        // Half a corpus is not a smaller corpus, it is a different guard. The ceiling this reports
        // is stated over "every shipped box", so a demos directory that has moved or been renamed
        // must stop the run rather than shrink it.
        if (!demosDir.isDirectory) {
            return AuditResult(0, 0, 0, 0, listOf("no demo corpus at ${demosDir.absolutePath}"))
        }

        val files = corpus.walkTopDown()
            .filter { it.isFile && it.extension.lowercase() in setOf("yaml", "yml") }
            .sortedBy { it.relativeTo(corpus).invariantSeparatorsPath }
            .toList()
        val demoDocuments = demosDir.listFiles()
            ?.filter { it.isDirectory && File(it, "metadata.edn").isFile }
            ?.sortedBy { it.name }
            .orEmpty()
        val demoFrames = demoDocuments.flatMap { parseDemoFrames(it, problems) }
        val demoTranscripts = demosDir.listFiles()
            ?.filter { it.isDirectory }
            ?.mapNotNull { dir -> File(dir, "build.yaml").takeIf { it.isFile } }
            ?.sortedBy { it.parentFile.name }
            .orEmpty()
        val demoTranscriptFrames = demoTranscripts.flatMap {
            parseFrames("${it.parentFile.name}/${it.name}", it, problems)
        }
        checkDemoReplayAgreement(demoFrames, demoTranscriptFrames, problems)
        val frames = files.flatMap { parseFrames(it.relativeTo(corpus).invariantSeparatorsPath, it, problems) } +
            demoFrames + demoTranscriptFrames
        val byKey = frames.groupBy { it.key }
        byKey.filterValues { it.size > 1 }.forEach { (key, duplicates) ->
            problems.add("$key identifies ${duplicates.size} create frames; box ids must be unique within a transcript")
        }

        for (frame in frames) {
            if (!frame.x.isFinite() || !frame.y.isFinite() || !frame.width.isFinite() || !frame.height.isFinite()) {
                problems.add("${frame.source}: frame values must be finite")
                continue
            }
            if (frame.x < 0.0 || frame.y < 0.0) {
                problems.add(
                    "${frame.source}: negative position (${frame.x}, ${frame.y}); ordinary transcripts begin in " +
                        "the positive canvas near (40, 40)"
                )
            }
            if (frame.width <= 0.0 || frame.height <= 0.0) {
                problems.add("${frame.source}: frame dimensions must be positive, got ${frame.width} x ${frame.height}")
            }
        }

        val exceptions = parseExceptions(File(repo, EXCEPTIONS_REL), problems)
        // Demo transcript frames are left out here on purpose: one that agrees with its document is
        // that document's frame, already held to the ceiling under its `metadata.edn` key, and one that
        // disagrees has already been reported by checkDemoReplayAgreement.
        val demoTranscriptKeys = demoTranscriptFrames.mapTo(HashSet()) { it.key }
        val large = frames.filter { it.isLarge && it.key !in demoTranscriptKeys }
        for (frame in large) {
            if (frame.key !in exceptions) {
                problems.add(
                    "${frame.source}: ${frame.width} x ${frame.height} exceeds the ordinary " +
                        "${MAX_ORDINARY_WIDTH.toInt()} x ${MAX_ORDINARY_HEIGHT.toInt()} ceiling; compact it or add " +
                        "a reviewed `${frame.key}` reason to $EXCEPTIONS_REL"
                )
            }
        }
        for ((key, reason) in exceptions) {
            val matched = byKey[key]
            when {
                reason.length < 20 -> problems.add("$EXCEPTIONS_REL: `$key` needs a specific reason of at least 20 characters")
                matched == null -> problems.add("$EXCEPTIONS_REL: `$key` names no create frame")
                matched.none { it.isLarge } -> problems.add("$EXCEPTIONS_REL: `$key` is no longer large; remove its stale exception")
            }
        }

        return AuditResult(
            files.size, demoDocuments.size, frames.size, large.size, problems.sorted(), demoTranscripts.size,
        )
    }

    private fun parseFrames(relative: String, file: File, problems: MutableList<String>): List<Frame> {
        val loaded = runCatching { Yaml().load<Any?>(file.readText()) }.getOrElse { error ->
            problems.add("$relative: invalid YAML: ${error.message}")
            return emptyList()
        }
        val operations = when (loaded) {
            is List<*> -> loaded
            is Map<*, *> -> (loaded["operations"] as? List<*>) ?: (loaded["ops"] as? List<*>) ?: emptyList<Any?>()
            else -> emptyList()
        }
        val result = mutableListOf<Frame>()
        for ((index, rawOperation) in operations.withIndex()) {
            val operation = rawOperation as? Map<*, *> ?: continue
            val verb = operation.keys.firstOrNull()?.toString()?.lowercase() ?: continue
            if (verb !in CREATE_VERBS) continue
            val payload = operation.values.firstOrNull() as? Map<*, *>
            if (payload == null) {
                problems.add("$relative operation ${index + 1}: $verb payload is not a map")
                continue
            }
            val box = (payload["box"] ?: payload["uid"] ?: payload["id"] ?: payload["target"])
                ?.toString()?.takeIf { it.isNotBlank() }
            if (box == null) {
                problems.add("$relative operation ${index + 1}: $verb has no box id")
                continue
            }
            val source = "$relative#$box"
            val rawFrame = (payload["frame"] ?: payload["rect"]) as? Map<*, *>
            if (rawFrame == null) {
                problems.add("$source: create has no frame map; an omitted frame is an invisible Rect(0,0,0,0)")
                continue
            }
            val values = listOf("x", "y", "w", "h").associateWith { field ->
                val value = rawFrame[field]
                if (value !is Number) problems.add("$source: frame.$field must be numeric, got ${value ?: "missing"}")
                (value as? Number)?.toDouble() ?: Double.NaN
            }
            result.add(
                Frame(
                    key = source,
                    source = source,
                    x = values.getValue("x"),
                    y = values.getValue("y"),
                    width = values.getValue("w"),
                    height = values.getValue("h"),
                )
            )
        }
        return result
    }

    private fun checkDemoReplayAgreement(
        documentFrames: List<Frame>,
        transcriptFrames: List<Frame>,
        problems: MutableList<String>,
    ) {
        val documents = documentFrames.associateBy { it.key }
        for (frame in transcriptFrames) {
            val demo = frame.key.substringBefore('/')
            val box = frame.key.substringAfterLast('#')
            val document = documents["$demo/metadata.edn#$box"]
            if (document == null) {
                problems.add(
                    "${frame.source}: creates a box '$box' that $demo/metadata.edn does not carry; a demo's " +
                        "transcript and the document it rebuilds must describe the same boxes"
                )
                continue
            }
            if (!sameFrame(frame, document)) {
                problems.add(
                    "${frame.source}: create frame ${describe(frame)} does not match ${describe(document)} in " +
                        "$demo/metadata.edn; replaying this transcript would write its geometry over the " +
                        "committed document. Copy the document's frame into create.frame."
                )
            }
        }
    }

    private const val FRAME_EPSILON = 0.01

    private fun sameFrame(a: Frame, b: Frame): Boolean =
        listOf(a.x - b.x, a.y - b.y, a.width - b.width, a.height - b.height)
            .all { it.isFinite() && kotlin.math.abs(it) < FRAME_EPSILON }

    private fun describe(frame: Frame): String = "${frame.width} x ${frame.height} at (${frame.x}, ${frame.y})"

    private fun parseExceptions(file: File, problems: MutableList<String>): Map<String, String> {
        if (!file.isFile) {
            problems.add("no layout-exception registry at ${file.absolutePath}")
            return emptyMap()
        }
        val loaded = runCatching { Yaml().load<Any?>(file.readText()) }.getOrElse { error ->
            problems.add("$EXCEPTIONS_REL: invalid YAML: ${error.message}")
            return emptyMap()
        }
        val root = loaded as? Map<*, *>
        val raw = root?.get("largeFrames") as? Map<*, *>
        if (raw == null) {
            problems.add("$EXCEPTIONS_REL: expected a `largeFrames` map")
            return emptyMap()
        }
        val result = linkedMapOf<String, String>()
        raw.forEach { (rawKey, rawReason) ->
            val key = rawKey?.toString()?.trim().orEmpty()
            val reason = rawReason?.toString()?.trim().orEmpty()
            if (key.isEmpty()) problems.add("$EXCEPTIONS_REL: empty largeFrames key")
            else result[key] = reason
        }
        return result
    }

    private fun parseDemoFrames(dir: File, problems: MutableList<String>): List<Frame> {
        val edn = File(dir, "metadata.edn")
        if (!edn.isFile) return emptyList()
        val text = edn.readText()
        val relative = "${dir.name}/metadata.edn"
        // A box entry is `{"id" "…" "properties" {…}}`. Requiring the `"properties"` key keeps nested
        // maps that also carry an `"id"` (a box's persisted `_controlGroupValues`, one per slider
        // or checkbox) from being read as frameless boxes.
        val idRe = Regex("""\"id\"\s+\"([^\"]+)\"\s+\"properties\"""")
        val frameRe = Regex("""\"frame\"\s+#afield/rect\s+\[([^\]]+)\]""")
        val ids = idRe.findAll(text).toList()
        val result = mutableListOf<Frame>()
        for ((index, id) in ids.withIndex()) {
            val box = id.groupValues[1]
            val end = if (index + 1 < ids.size) ids[index + 1].range.first else text.length
            val segment = text.substring(id.range.last + 1, end)
            val rects = frameRe.findAll(segment).toList()
            if (rects.isEmpty()) {
                if (box != "root") {
                    problems.add(
                        "$relative: box '$box' has no `\"frame\" #afield/rect`; a frameless box is an " +
                            "invisible Rect(0,0,0,0), and it used to make the next box invisible to this guard too"
                    )
                }
                continue
            }
            if (rects.size > 1) {
                problems.add("$relative: box '$box' declares ${rects.size} frames; exactly one is expected")
                continue
            }
            val raw = rects.single().groupValues[1]
            val parts = raw.trim().split(Regex("\\s+")).mapNotNull { it.toDoubleOrNull() }
            if (parts.size != 4) {
                problems.add("$relative: box '$box' has an unreadable frame '$raw'")
                continue
            }
            result.add(Frame("$relative#$box", "$relative box '$box'", parts[0], parts[1], parts[2], parts[3]))
        }
        return result
    }

    private fun repoRoot(): File {
        var candidate: File? = File(System.getProperty("user.dir")).absoluteFile
        while (candidate != null) {
            if (File(candidate, "public/docs").isDirectory && File(candidate, "src/jvmMain/kotlin").isDirectory) {
                return candidate
            }
            candidate = candidate.parentFile
        }
        return File(System.getProperty("user.dir")).absoluteFile
    }
}