Migrate from DTD to XSD validation with improved error handling

Co-authored-by: bren <bren@juanantonio.info>

Author: cursoragent

spml/pom.xml

@@ -8,7 +8,7 @@
   <version>0.1.0</version>
 
   <properties>
-    <java.version>24</java.version>
+    <java.version>21</java.version>
     <maven.version>3.9.10</maven.version>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

spml/src/main/java/info/jab/xml/CursorRuleGenerator.java

@@ -25,7 +25,7 @@
  */
 public final class CursorRuleGenerator {
 
-    private static final String DTD_FILE_NAME = "system-prompt.dtd";
+    private static final String XSD_FILE_NAME = "system-prompt.xsd";
 
     // ===============================================================
     // PUBLIC API - Entry point for cursor rule generation
@@ -68,17 +68,28 @@ private Optional<InputStream> loadResource(String fileName) {
     }
 
     /**
-     * Step 2: Creates SAXSource with custom EntityResolver.
-     * Pure function that creates immutable SAXSource using modern SAX API.
+     * Step 2: Creates SAXSource with XSD validation.
+     * Pure function that creates immutable SAXSource with schema validation.
      */
     private SAXSource createSaxSource(TransformationSources sources) {
         try {
-            // Modern approach: Use SAXParserFactory instead of deprecated XMLReaderFactory
-            XMLReader xmlReader = SAXParserFactory.newInstance().newSAXParser().getXMLReader();
-            xmlReader.setEntityResolver(new ResourceEntityResolver());
+            // Create SAX parser factory with namespace awareness and validation
+            SAXParserFactory factory = SAXParserFactory.newInstance();
+            factory.setNamespaceAware(true);
+            factory.setValidating(false); // We'll use schema validation instead
+
+            // Load XSD schema
+            Optional<Schema> schema = loadXsdSchema();
+            if (schema.isPresent()) {
+                factory.setSchema(schema.get());
+            }
+
+            XMLReader xmlReader = factory.newSAXParser().getXMLReader();
+            xmlReader.setErrorHandler(new ValidationErrorHandler());
+
             return new SAXSource(xmlReader, new InputSource(sources.xmlStream()));
         } catch (SAXException | ParserConfigurationException e) {
-            throw new RuntimeException("Failed to create SAX source with modern XMLReader API", e);
+            throw new RuntimeException("Failed to create SAX source with XSD validation", e);
         }
     }
 
@@ -129,27 +140,40 @@ private record TransformationSources(InputStream xmlStream, InputStream xslStrea
     }
 
     /**
-     * Custom EntityResolver as functional interface implementation.
-     * Used by createSaxSource to resolve DTD references.
+     * Loads XSD schema from classpath for validation.
+     * Returns Optional to handle missing schema gracefully.
      */
-    private static final class ResourceEntityResolver implements EntityResolver {
+    private Optional<Schema> loadXsdSchema() {
+        return loadResource(XSD_FILE_NAME)
+            .map(xsdStream -> {
+                try {
+                    SchemaFactory schemaFactory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
+                    return schemaFactory.newSchema(new StreamSource(xsdStream));
+                } catch (SAXException e) {
+                    throw new RuntimeException("Failed to load XSD schema: " + XSD_FILE_NAME, e);
+                }
+            });
+    }
+
+    /**
+     * Custom ErrorHandler for XSD validation errors.
+     * Provides better error reporting for validation issues.
+     */
+    private static final class ValidationErrorHandler implements ErrorHandler {
         @Override
-        public InputSource resolveEntity(String publicId, String systemId) throws SAXException {
-            // Only handle system IDs we can resolve; return null for default SAX behavior otherwise
-            return Optional.ofNullable(systemId)
-                .filter(id -> id.endsWith(DTD_FILE_NAME))
-                .flatMap(this::loadDtdFromClasspath)
-                .orElse(null); // SAX contract: null means "use default resolution"
+        public void warning(SAXParseException exception) throws SAXException {
+            // Log warning in a real application
+            System.err.println("XSD Validation Warning: " + exception.getMessage());
         }
 
-        private Optional<InputSource> loadDtdFromClasspath(String systemId) {
-            return Optional.ofNullable(
-                getClass().getClassLoader().getResourceAsStream(DTD_FILE_NAME)
-            ).map(dtdStream -> {
-                InputSource inputSource = new InputSource(dtdStream);
-                inputSource.setSystemId(systemId);
-                return inputSource;
-            });
+        @Override
+        public void error(SAXParseException exception) throws SAXException {
+            throw new SAXException("XSD Validation Error: " + exception.getMessage(), exception);
+        }
+
+        @Override
+        public void fatalError(SAXParseException exception) throws SAXException {
+            throw new SAXException("XSD Validation Fatal Error: " + exception.getMessage(), exception);
         }
     }
 }