AgentDemoDriftGuard.kt

    @JvmStatic
    fun main(args: Array<String>) {
        var write = false
        val only = linkedSetOf<String>()
        var cursor = 0
        while (cursor < args.size) {
            val arg = args[cursor]
            when {
                arg == "--write" -> write = true
                arg == "--only" -> {
                    require(cursor + 1 < args.size) { "--only needs a document name. $USAGE" }
                    only += splitNames(args[cursor + 1])
                    cursor++
                }

                arg.startsWith("--only=") -> only += splitNames(arg.removePrefix("--only="))
                else -> error("unrecognized argument '$arg'. $USAGE")
            }
            cursor++
        }

        val root = repoRoot()
        val demosRoot = File(root, DEMOS_REL)
        require(demosRoot.isDirectory) { "no agent demo directory at ${demosRoot.absolutePath}" }
        val demoDocuments = (demosRoot.listFiles() ?: emptyArray())
            .filter { it.isDirectory && File(it, SavingContext.METADATA_EDN).isFile }
            .sortedBy { it.name }
        require(demoDocuments.isNotEmpty()) { "no Field documents under ${demosRoot.absolutePath}" }
        // A document outside the demo corpus need not have sidecars at all; only one that has them can drift.
        val authored = AUTHORED_ROOTS.flatMap { rel ->
            (File(root, rel).listFiles() ?: emptyArray())
                .filter { File(it, SavingContext.METADATA_EDN).let { m -> m.isFile && "#afield/file-inline" in m.readText() } }
                .sortedBy { it.name }
        }
        val all = demoDocuments + authored
        val demos = select(root, all, only)
        // A demo keeps every sidecar beside it. Another document may hold a property only inline (no file
        // beside it), which is what Field then loads; with one copy there is nothing to drift.
        fun inlineOnlyAllowed(document: File) = document !in demoDocuments

        val saving = SavingContext()
        if (write) {
            // `--write` copies each loose sidecar over its inline copy, so an edit made inside
            // metadata.edn would be thrown away without a word. Refuse when metadata.edn has changed
            // against git and the sidecar it now disagrees with has not: that is a hand edit.
            val lost = demos.flatMap { demo -> handEditedInlines(root, demo, saving) }
            if (lost.isNotEmpty()) {
                System.err.println("AgentDemoDriftGuard: refusing to regenerate over edits made in metadata.edn:")
                lost.forEach { System.err.println("  - $it") }
                System.err.println("Make the edit in the named sidecar (or in Field), restore metadata.edn " +
                    "(git checkout -- <document>/metadata.edn), then regenerate.")
                exitProcess(1)
            }
            demos.forEach { demo ->
                val refreshed = saving.refreshInlineFilesFromDisk(demo.absolutePath, inlineOnlyAllowed(demo))
                println("[regenerate] ${label(root, demo)}: ${refreshed.size} inline file(s)")
            }
        }

        val problems = mutableListOf<String>()
        var inlineFiles = 0
        for (demo in demos) {
            val documentRoot = demo.canonicalFile.toPath().normalize()
            val snapshots = saving.readInlineFileSnapshots(demo.absolutePath)
            if (snapshots.isEmpty()) {
                problems += "${label(root, demo)}: metadata.edn has no #afield/file-inline properties"
                continue
            }
            inlineFiles += snapshots.size
            for (snapshot in snapshots) {
                val target = File(demo, snapshot.path).canonicalFile
                if (!target.toPath().normalize().startsWith(documentRoot)) {
                    problems += "${label(root, demo)}/${snapshot.boxId}.${snapshot.property}: path escapes the demo (${snapshot.path})"
                    continue
                }
                if (!target.isFile) {
                    if (inlineOnlyAllowed(demo)) continue
                    problems += "${label(root, demo)}/${snapshot.boxId}.${snapshot.property}: missing ${snapshot.path}"
                    continue
                }
                val loose = target.readText()
                if (loose != snapshot.inline) {
                    val inlineLines = snapshot.inline.lines()
                    val looseLines = loose.lines()
                    val at = (0 until maxOf(inlineLines.size, looseLines.size))
                        .firstOrNull { inlineLines.getOrNull(it) != looseLines.getOrNull(it) } ?: 0
                    problems += "${label(root, demo)}/${snapshot.boxId}.${snapshot.property}: ${snapshot.path} " +
                        "differs from metadata.edn at line ${at + 1} — the sidecar is the copy to edit; " +
                        "regenerating copies it into metadata.edn\n" +
                        "      metadata: ${inlineLines.getOrNull(at)}\n" +
                        "      loose:    ${looseLines.getOrNull(at)}"
                }
            }

            // The comparison above is on decoded values, so it is blind to how metadata.edn spells
            // them: a six-character « escape and a literal « decode alike, and both pass. That
            // is how logging_layer sat in a form the codec does not produce — the parser accepts the
            // escape, the printer only ever emits the character — and every `--write` came back
            // with it modified. Require the committed bytes to be the codec's own output, so a
            // regenerate on a clean tree is a no-op and a demo cannot go back to hand-spelled EDN.
            val committed = File(demo, SavingContext.METADATA_EDN).readText()
            val canonical = saving.canonicalInlineMetadata(demo.absolutePath, inlineOnlyAllowed(demo)).metadataEdn
            if (committed != canonical) {
                val at = (0 until maxOf(committed.length, canonical.length))
                    .firstOrNull { committed.getOrNull(it) != canonical.getOrNull(it) } ?: 0
                problems += "${label(root, demo)}: metadata.edn is not what Field's EDN codec writes, " +
                    "first difference at character ${at + 1}\n" +
                    "      committed: ${excerpt(committed, at)}\n" +
                    "      codec:     ${excerpt(canonical, at)}"
            }
        }

        if (problems.isNotEmpty()) {
            System.err.println("AgentDemoDriftGuard FAILED with ${problems.size} problem(s):")
            problems.forEach { System.err.println("  - $it") }
            System.err.println("Fix with: ./gradlew regenerateAgentDemos")
            exitProcess(1)
        }
        val scope = if (demos.size == all.size) "" else " of ${all.size}"
        println("AgentDemoDriftGuard ok — ${demos.size}$scope document(s), $inlineFiles inline file(s)")
    }