build.gradle

import java.util.regex.Pattern
import javax.inject.Inject

plugins {
    id 'base'
    id 'org.asciidoctor.jvm.convert' version '4.0.3'  // Plugin for HTML generation
    id 'org.asciidoctor.jvm.pdf' version '4.0.3'      // Plugin for PDF generation
    id 'java-library'  // needed for PlantUML dependency resolution

}

wrapper {
    gradleVersion = '8.11'
    distributionType = 'bin'
    distributionUrl = 'https://services.gradle.org/distributions/gradle-8.11-bin.zip'
}

// **********************************************
// * Project constants and shared configuration *
// **********************************************

ext {

    // Location of RelaxNG schema for questions - this might change in the future
    schemaFile = file('exam.rng')

    // Configuration for arc42 documentation
    docSrcDir = 'arc42-doc'
    docOutputPath = 'build/arc42-doc'
    mainDocFile = '00-arc42-main.adoc'
    tempDir = "${buildDir}/tmp/asciidoc"

    // Explicitly define files affected by ADR automation
    adrConfig = [
        sourceDir: file("${docSrcDir}/decisions"),             // Source for all ADRs
        readmeFile: file("${docSrcDir}/decisions/README.md"),  // Will be automatically updated
        arc42File: file("${docSrcDir}/09-decisions.adoc")      // Will be automatically updated
    ]
}


repositories {
    mavenCentral()
}

configurations {
    jing
    asciidoctorExtensions
    saxon
}

dependencies {
    jing 'org.relaxng:jing:20220510'
    asciidoctorExtensions 'org.asciidoctor:asciidoctorj:3.0.0'
    asciidoctorExtensions 'org.asciidoctor:asciidoctorj-pdf:2.3.19'  
    asciidoctorExtensions 'org.asciidoctor:asciidoctorj-diagram:2.3.1'
    asciidoctorExtensions 'net.sourceforge.plantuml:plantuml:1.2024.7'
    saxon 'net.sf.saxon:Saxon-HE:12.5'
}


// ****************************************
// * Tasks and code for schema validation *
// ****************************************

// This task runs XML validation using the Jing validator to ensure XML files 
// match their schema before processing

abstract class ValidationTask extends DefaultTask {
    @Inject
    abstract ExecOperations getExecOperations()  // Needed to run Jing as external process
    
    def runJingValidation(File xmlFile) {
        def stdout = new ByteArrayOutputStream()
        def stderr = new ByteArrayOutputStream() // Separate streams because validation errors go to stderr
                
        def execResult = execOperations.exec { spec ->
            spec.workingDir = project.projectDir
            spec.executable = 'java'
            spec.args = [
                '-cp',
                project.configurations.jing.asPath,
                'com.thaiopensource.relaxng.util.Driver',
                project.schemaFile.absolutePath,
                xmlFile.absolutePath
            ]
            spec.standardOutput = stdout
            spec.errorOutput = stderr
            spec.ignoreExitValue = true  // Don't throw on validation failure - we handle it ourselves
        }
        
        def error = stderr.toString().trim()
        def output = stdout.toString().trim()
        def allOutput = error.isEmpty() ? output : error // Prefer error message if present
        
        return [
            success: execResult.exitValue == 0,
            output: allOutput
        ]
    }
}

// Validates a single XML file

tasks.register('validateFile', ValidationTask) {
    description = 'Validates a single XML file against the RelaxNG schema'
    group = 'Validation'
    
    doLast {
        // Requires -Pfile parameter to specify which file to validate
        if (!project.hasProperty('file')) {
            throw new GradleException("Please provide a file path using -Pfile=path/to/file.xml")
        }
        
        def xmlFile = project.file(project.property('file'))
        if (!xmlFile.exists()) {
            throw new GradleException("File ${xmlFile.absolutePath} does not exist")
        }
        
        // Run validation and provide visual feedback
        println "Validating ${xmlFile.name} against schema ${project.schemaFile.name}"
        def result = runJingValidation(xmlFile)
        
        if (result.success) {
            println "✓ ${xmlFile.name} is valid"
        } else {
            println "✗ ${xmlFile.name} validation failed:"
            if (result.output) {
                println result.output
            }
            throw new GradleException("XML validation failed")
        }
    }
}

// Bulk validation of all XML files in specified directories

tasks.register('validate', ValidationTask) {
    description = 'Validates all XML files in predefined directories against the RelaxNG schema'
    group = 'Validation'
    
    doLast {
        def directories = ['mock/questions']  // Add more directories as needed
        
        // Track stats for summary report
        def failures = []
        def validCount = 0
        def totalCount = 0
        
        // Progress indicators: . for success, F for failure
        directories.each { dirName ->
            def directory = project.file(dirName)
            if (!directory.exists() || !directory.isDirectory()) {
                println "Warning: Directory ${directory.absolutePath} does not exist"
                return
            }
            
            def xmlFiles = project.fileTree(directory).include('**/*.xml')
            
            xmlFiles.each { xmlFile ->
                totalCount++
                def result = runJingValidation(xmlFile)
                
                if (result.success) {
                    validCount++
                    print "."
                } else {
                    failures << [file: xmlFile.name, output: result.output]
                    print "F"
                }
            }
        }
        
        // Print summary and fail build if any validation failed

        println "\n\nValidation Summary:"
        println "✓ ${validCount}/${totalCount} files are valid"
        
        if (failures) {
            println "\nFailed validations:"
            failures.each { failure ->
                println "\n✗ ${failure.file} failed validation:"
                println failure.output
                println "-" * 80  // Separator line
            }
            throw new GradleException("${failures.size()} file(s) failed validation")
        }
    }
}


// *****************************************************
// * Tasks and code for arc42 documentation generation *
// *****************************************************

// Task provided by org.asciidoctor.jvm.convert plugin
// Converts AsciiDoc to HTML output
tasks.named('asciidoctor') {
    group = 'documentation'
    description = 'Converts AsciiDoc documentation to HTL format (output in dist/html)'
    configurations 'asciidoctorExtensions'
    baseDirFollowsSourceFile()
    sourceDir docSrcDir
    sources {
        include mainDocFile
    }
    outputDir file("${docOutputPath}/html")
    forkOptions {
        jvmArgs += [
            '--add-opens', 'java.base/sun.nio.ch=ALL-UNNAMED',
            '--add-opens', 'java.base/java.io=ALL-UNNAMED'
        ]
    }
    
    attributes = [
        'source-highlighter': 'rouge',
        'toc': 'left',
        'toclevels': '2',
        'sectlinks': '',
        'sectanchors': '',
        'numbered': '',
        'imagesdir': 'images',
        'plantuml-format': 'svg',
        'diagram-svg-type': 'inline'
    ]

    asciidoctorj {
        requires('asciidoctor-diagram')
        modules {
            diagram.use()
        }
    }
}

// Task provided by org.asciidoctor.jvm.pdf plugin
// Converts AsciiDoc to PDF output
tasks.named('asciidoctorPdf') {
    group = 'documentation'
    description = 'Converts AsciiDoc documentation to PDF format (output in dist/pdf)'
    configurations 'asciidoctorExtensions'  
    baseDirFollowsSourceFile()
    sourceDir docSrcDir
    sources {
        include mainDocFile
    }
    outputDir file("${docOutputPath}/pdf")
    // For unknown reasons asciidoctorPdf sometimes guzzles up heap like there's no tomorrow
    forkOptions {
        maxHeapSize = "2g"
        jvmArgs += [
            '--add-opens', 'java.base/sun.nio.ch=ALL-UNNAMED',
            '--add-opens', 'java.base/java.io=ALL-UNNAMED',
            '-XX:+UseG1GC',              // Use G1 garbage collector
            '-XX:+HeapDumpOnOutOfMemoryError'  // Help diagnose issues
        ]
    }
    
    attributes = [
        'pdf-stylesdir': 'themes',
        'pdf-style': 'basic',
        'toc': '',
        'toclevels': '2',
        'numbered': '',
        'imagesdir': 'images',
        'plantuml-format': 'svg',
        'diagram-svg-type': 'inline'
    ]

    asciidoctorj {
        requires('asciidoctor-diagram')
        modules {
            diagram.use()
        }
    }

}

// Clean tasks
tasks.register('cleanDoc', Delete) {
    group = 'documentation'
    description = 'Cleans the distribution directory for the documentation (dist)'
    delete docOutputPath
}


// Main documentation build task
tasks.register('buildDocs') {
    group = 'documentation'
    description = 'Generates complete documentation in all formats (HTML and PDF) after cleaning the output directory'
    dependsOn 'cleanDoc', 'asciidoctor', 'asciidoctorPdf'
}

// Ensure proper task ordering - clean must complete before generation starts
tasks.named('asciidoctor') {
    mustRunAfter 'cleanDoc'
    inputs.dir(docSrcDir)
    outputs.dir(file("${docOutputPath}/html"))
}

tasks.named('asciidoctorPdf') {
    mustRunAfter 'cleanDoc'
    inputs.dir(docSrcDir)
    outputs.dir(file("${docOutputPath}/pdf"))

}

// ADR management task to update the ADR index in README.md
tasks.register('updateAdrIndex') {
    group = 'documentation'
    description = 'Updates ADR indices in README.md and architecture documentation'
    
    inputs.dir(adrConfig.sourceDir)
    outputs.files(adrConfig.readmeFile, adrConfig.arc42File)
    
    def ADR_START_MARKER_MD = '<!-- BEGIN-ADR-INDEX - autogenerated, manual edits will be lost -->'
    def ADR_END_MARKER_MD = '<!-- END-ADR-INDEX -->'
    def ADR_START_MARKER_ADOC = '// BEGIN-ADR-INDEX - autogenerated, manual edits will be lost'
    def ADR_END_MARKER_ADOC = '// END-ADR-INDEX'
    // Execute during configuration phase since asciidoctor needs the results
    def adrs = []
    adrConfig.sourceDir.eachFile { file ->
        if (file.name =~ /^\d{3}-.+\.adoc$/) {
            def content = file.text
            def titleMatch = content =~ /= ADR\d{3} - (.+)/
            def statusMatch = content =~ /== Status\n\n(\w+)/
            
            if (titleMatch) {
                adrs << [
                    id: file.name[0..2],
                    file: file.name,
                    title: titleMatch[0][1],
                    status: statusMatch ? statusMatch[0][1] : 'Unknown'
                ]
            }
        }
    }
    adrs.sort { it.id }
    
    // If no ADRs exist, use placeholder entry
    if (adrs.isEmpty()) {
        adrs << [
            id: '042',
            file: '042-no-adrs-yet.adoc',
            title: 'No ADRs yet, you might want to add some',
            status: 'Proposed'
        ]
    }
    
    // Update README.md
    def readmeContent = generateMarkdownTable(adrs)
    updateFileSection(adrConfig.readmeFile, ADR_START_MARKER_MD, ADR_END_MARKER_MD, readmeContent)
    
    // Update architecture documentation
    def arc42Content = generateAsciiDocTable(adrs)
    updateFileSection(adrConfig.arc42File, ADR_START_MARKER_ADOC, ADR_END_MARKER_ADOC, arc42Content)
}

def generateMarkdownTable(adrs) {
    def content = '| ADR | Status | Title |\n|--|--|-------|\n'
    adrs.each { adr ->
        content += "| [${adr.id}](${adr.file}) | ${adr.status} | ${adr.title} |\n"
    }
    content
}

def generateAsciiDocTable(adrs) {
    def content = '.Architectural Decision Records\n[options="header",cols="1,2,4"]\n|===\n|ADR |Status |Title\n\n'
    adrs.each { adr ->
        content += "|<<${adr.file},${adr.id}>> |${adr.status} |${adr.title}\n"
    }
    content += '|===\n'
    content
}

def updateFileSection(file, sectionStart, sectionEnd, newContent) {
    def text = file.text
    def pattern = Pattern.compile("${Pattern.quote(sectionStart)}.*${Pattern.quote(sectionEnd)}", Pattern.DOTALL)
    file.text = text.replaceAll(pattern, "${sectionStart}\n${newContent}${sectionEnd}")
    println "Updated ${file.name}"
}

// Make documentation tasks depend on ADR index update
tasks.named('asciidoctor') {
    dependsOn 'updateAdrIndex'
}

tasks.named('asciidoctorPdf') {
    dependsOn 'updateAdrIndex'
}

tasks.named('buildDocs') {
    dependsOn 'updateAdrIndex'
}


// **********************************************************
// * Tasks and code for preparing LLM context for claude.ai *
// **********************************************************

// Task for collecting context for question authoring
tasks.register('collectClaudeContextQuestions') {
    description 'Collects files relevant for question authoring into a single directory for Claude context'
    group 'Documentation'

    doFirst {
        def claudeContextDir = new File(buildDir, 'claude-context-questions')
        claudeContextDir.deleteDir()
        claudeContextDir.mkdirs()
    }

    doLast {
        def claudeContextDir = new File(buildDir, 'claude-context-questions')
        def fileMapping = [:] 

        def relevantFiles = [
            // Question examples and schema
            'mock/**/*.xml',
            'exam.rng',
            
            // Curricula
            'llm-context/curricula/*.html',
            
            // Base configuration
            'build.gradle',
            'README.adoc'
        ]

        def excludedPatterns = [
            '**/build/**',
            '**/bin/**',
            '**/arc42-doc/**',
            '**/code/**'
        ]

        // Copy files
        project.fileTree(projectDir) {
            relevantFiles.each { include it }
            excludedPatterns.each { exclude it }
        }.each { sourceFile ->
            def targetFile = new File(claudeContextDir, sourceFile.name)
            if (sourceFile.isFile()) {
                def relPath = project.relativePath(sourceFile)
                fileMapping[sourceFile.name] = relPath
                
                // Copy content and add location comment
                def extension = sourceFile.name.toLowerCase().tokenize('.').last()
                def locationComment = getLocationComment(extension, relPath)
                targetFile.text = locationComment + '\n' + sourceFile.text
            }
        }

        createManifest(claudeContextDir, fileMapping)
    }
}

// Task for collecting context for system development
tasks.register('collectClaudeContextDev') {
    description 'Collects files relevant for system development into a single directory for Claude context'
    group 'Documentation'

    doFirst {
        def claudeContextDir = new File(buildDir, 'claude-context-dev')
        claudeContextDir.deleteDir()
        claudeContextDir.mkdirs()
    }

    doLast {
        def claudeContextDir = new File(buildDir, 'claude-context-dev')
        def fileMapping = [:]

        def relevantFiles = [
            // Architecture documentation
            'arc42-doc/**/*.adoc',
            'arc42-doc/decisions/**/*.adoc',
            
            // Core system files
            'exam.rng',
            'build.gradle',
            'settings.gradle',
            'gradle.properties',
            
            // Sample questions (limit to a few examples)
            'mock/mock-01.xml',
            'mock/mock-02.xml',
            'mock/mock-03.xml',
            'mock/mock-04.xml',
            'mock/mock-05.xml',
            
            // Project documentation
            'README.adoc',
            'docs/**/*.pdf',


            // Previewgeneration
            'src/preview/**/*.xsl',     // Preview templates
            'src/preview/**/*.css'     // Preview styles

        ]

        def excludedPatterns = [
            '**/build/**',
            '**/bin/**',
            '**/curricula/**',
            'arc42-doc/images/**'
        ]

        // Copy files
        project.fileTree(projectDir) {
            relevantFiles.each { include it }
            excludedPatterns.each { exclude it }
        }.each { sourceFile ->
            def targetFile = new File(claudeContextDir, sourceFile.name)
            if (sourceFile.isFile()) {
                def relPath = project.relativePath(sourceFile)
                fileMapping[sourceFile.name] = relPath
                
                // Copy content and add location comment
                def extension = sourceFile.name.toLowerCase().tokenize('.').last()
                def locationComment = getLocationComment(extension, relPath)
                targetFile.text = locationComment + '\n' + sourceFile.text
            }
        }

        createManifest(claudeContextDir, fileMapping)
    }
}

// Helper method to get appropriate comment syntax based on file extension
def getLocationComment(extension, path) {
    switch (extension) {
        case ['java', 'gradle']:
            return "// Source location: ${path}"
        case ['xml', 'rng', 'adoc', 'md']:
            return "<!-- Source location: ${path} -->"
        case 'properties':
            return "# Source location: ${path}"
        default:
            return "# Source location: ${path}"
    }
}

// Helper method to create manifest file
def createManifest(claudeContextDir, fileMapping) {
    def manifestFile = new File(claudeContextDir, 'claude-context-manifest.md')
    manifestFile.text = """# Claude Context Manifest
Generated on: ${new Date()}

## Project Files
The following files have been collected for Claude context:

"""
    claudeContextDir.listFiles().each { file ->
        if (file.isFile()) {
            def size = file.length()
            def sizeStr = size < 1024 ? "${size}B" :
                         size < 1024*1024 ? "${(size/1024 as double).round(1)}KB" :
                         "${(size/1024/1024 as double).round(1)}MB"
            manifestFile << "- `${file.name}` (${sizeStr})\n"
        }
    }

    manifestFile << "\n## File Location Mapping\n\n"
    fileMapping.each { flatName, originalPath ->
        manifestFile << "- `${flatName}` -> Original location: `${originalPath}`\n"
    }

    println "Claude context files collected in: ${claudeContextDir.absolutePath}"
    println "A manifest file has been created at: ${manifestFile.absolutePath}"
}











tasks.register('preview') {
    group = 'documentation'
    description = 'Generates HTML previews for exam questions'
    
    doFirst {
        mkdir("${buildDir}/preview")
    }
    
    doLast {
        fileTree('mock/questions').include('**/*.xml').each { File xmlFile ->
            def relPath = project.rootDir.toPath().relativize(xmlFile.parentFile.toPath())
            def outDir = file("${buildDir}/preview/${relPath}")
            outDir.mkdirs()
            
            def outFile = new File(outDir, xmlFile.name.replace('.xml', '.html'))
            
            javaexec {
                classpath = configurations.saxon
                mainClass = 'net.sf.saxon.Transform'
                args = [
                    '-s:' + xmlFile.absolutePath,
                    '-xsl:src/main/preview/question-preview.xsl',
                    '-o:' + outFile.absolutePath,
                    "css-file=" + file('src/main/preview/styles/preview.css').absolutePath
                ]
            }
        }
    }
}