Update AGENTS guidelines (#3556)

## Summary
- clarify Codex contribution instructions
- remove `test.sh` reference and require `./gradlew build`
- add Developer Guide, AI note and translation policy

## Testing
- `./gradlew spotlessApply`
- `./gradlew build`

src/test/java/stirling/software/SPDF/service/CustomPDFDocumentFactoryTest.java

@@ -1,18 +1,17 @@
 package stirling.software.SPDF.service;
 
-import java.nio.file.Files;
 import static org.junit.jupiter.api.Assertions.*;
 import static org.mockito.Mockito.*;
 
 import java.io.*;
 import java.nio.file.*;
+import java.nio.file.Files;
 import java.util.Arrays;
 
 import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.cos.COSName;
 import org.apache.pdfbox.pdmodel.*;
 import org.apache.pdfbox.pdmodel.common.PDStream;
-import org.aspectj.lang.annotation.Before;
-import org.apache.pdfbox.cos.COSName;
 import org.junit.jupiter.api.*;
 import org.junit.jupiter.api.parallel.Execution;
 import org.junit.jupiter.api.parallel.ExecutionMode;
@@ -25,7 +24,7 @@ import stirling.software.SPDF.service.SpyPDFDocumentFactory.StrategyType;
 
 @TestInstance(TestInstance.Lifecycle.PER_CLASS)
 @TestMethodOrder(MethodOrderer.OrderAnnotation.class)
-@Execution(value = ExecutionMode.SAME_THREAD) 
+@Execution(value = ExecutionMode.SAME_THREAD)
 class CustomPDFDocumentFactoryTest {
 
     private SpyPDFDocumentFactory factory;
@@ -43,12 +42,7 @@ class CustomPDFDocumentFactoryTest {
     }
 
     @ParameterizedTest
-    @CsvSource({
-        "5,MEMORY_ONLY",
-        "20,MIXED",
-        "60,TEMP_FILE"
-       
-    })
+    @CsvSource({"5,MEMORY_ONLY", "20,MIXED", "60,TEMP_FILE"})
     void testStrategy_FileInput(int sizeMB, StrategyType expected) throws IOException {
         File file = writeTempFile(inflatePdf(basePdfBytes, sizeMB));
         try (PDDocument doc = factory.load(file)) {
@@ -57,12 +51,7 @@ class CustomPDFDocumentFactoryTest {
     }
 
     @ParameterizedTest
-    @CsvSource({
-        "5,MEMORY_ONLY",
-        "20,MIXED",
-        "60,TEMP_FILE"
-       
-    })
+    @CsvSource({"5,MEMORY_ONLY", "20,MIXED", "60,TEMP_FILE"})
     void testStrategy_ByteArray(int sizeMB, StrategyType expected) throws IOException {
         byte[] inflated = inflatePdf(basePdfBytes, sizeMB);
         try (PDDocument doc = factory.load(inflated)) {
@@ -71,12 +60,7 @@ class CustomPDFDocumentFactoryTest {
     }
 
     @ParameterizedTest
-    @CsvSource({
-        "5,MEMORY_ONLY",
-        "20,MIXED",
-        "60,TEMP_FILE"
-       
-    })
+    @CsvSource({"5,MEMORY_ONLY", "20,MIXED", "60,TEMP_FILE"})
     void testStrategy_InputStream(int sizeMB, StrategyType expected) throws IOException {
         byte[] inflated = inflatePdf(basePdfBytes, sizeMB);
         try (PDDocument doc = factory.load(new ByteArrayInputStream(inflated))) {
@@ -85,30 +69,22 @@ class CustomPDFDocumentFactoryTest {
     }
 
     @ParameterizedTest
-    @CsvSource({
-        "5,MEMORY_ONLY",
-        "20,MIXED",
-        "60,TEMP_FILE"
-       
-    })
+    @CsvSource({"5,MEMORY_ONLY", "20,MIXED", "60,TEMP_FILE"})
     void testStrategy_MultipartFile(int sizeMB, StrategyType expected) throws IOException {
         byte[] inflated = inflatePdf(basePdfBytes, sizeMB);
-        MockMultipartFile multipart = new MockMultipartFile("file", "doc.pdf", "application/pdf", inflated);
+        MockMultipartFile multipart =
+                new MockMultipartFile("file", "doc.pdf", "application/pdf", inflated);
         try (PDDocument doc = factory.load(multipart)) {
             assertEquals(expected, factory.lastStrategyUsed);
         }
     }
 
     @ParameterizedTest
-    @CsvSource({
-        "5,MEMORY_ONLY",
-        "20,MIXED",
-        "60,TEMP_FILE"
-       
-    })
+    @CsvSource({"5,MEMORY_ONLY", "20,MIXED", "60,TEMP_FILE"})
     void testStrategy_PDFFile(int sizeMB, StrategyType expected) throws IOException {
         byte[] inflated = inflatePdf(basePdfBytes, sizeMB);
-        MockMultipartFile multipart = new MockMultipartFile("file", "doc.pdf", "application/pdf", inflated);
+        MockMultipartFile multipart =
+                new MockMultipartFile("file", "doc.pdf", "application/pdf", inflated);
         PDFFile pdfFile = new PDFFile();
         pdfFile.setFileInput(multipart);
         try (PDDocument doc = factory.load(pdfFile)) {
@@ -125,14 +101,16 @@ class CustomPDFDocumentFactoryTest {
             stream.getCOSObject().setItem(COSName.TYPE, COSName.XOBJECT);
             stream.getCOSObject().setItem(COSName.SUBTYPE, COSName.IMAGE);
 
-            doc.getDocumentCatalog().getCOSObject().setItem(COSName.getPDFName("DummyBigStream"), stream.getCOSObject());
+            doc.getDocumentCatalog()
+                    .getCOSObject()
+                    .setItem(COSName.getPDFName("DummyBigStream"), stream.getCOSObject());
 
             ByteArrayOutputStream out = new ByteArrayOutputStream();
             doc.save(out);
             return out.toByteArray();
         }
     }
-    
+
     @Test
     void testLoadFromPath() throws IOException {
         File file = writeTempFile(inflatePdf(basePdfBytes, 5));
@@ -151,29 +129,29 @@ class CustomPDFDocumentFactoryTest {
     }
 
     // neeed to add password pdf
-//    @Test
-//    void testLoadPasswordProtectedPdfFromInputStream() throws IOException {
-//        try (InputStream is = getClass().getResourceAsStream("/protected.pdf")) {
-//            assertNotNull(is, "protected.pdf must be present in src/test/resources");
-//            try (PDDocument doc = factory.load(is, "test123")) {
-//                assertNotNull(doc);
-//            }
-//        }
-//    }
-//
-//    @Test
-//    void testLoadPasswordProtectedPdfFromMultipart() throws IOException {
-//        try (InputStream is = getClass().getResourceAsStream("/protected.pdf")) {
-//            assertNotNull(is, "protected.pdf must be present in src/test/resources");
-//            byte[] bytes = is.readAllBytes();
-//            MockMultipartFile file = new MockMultipartFile("file", "protected.pdf", "application/pdf", bytes);
-//            try (PDDocument doc = factory.load(file, "test123")) {
-//                assertNotNull(doc);
-//            }
-//        }
-//    }
+    //    @Test
+    //    void testLoadPasswordProtectedPdfFromInputStream() throws IOException {
+    //        try (InputStream is = getClass().getResourceAsStream("/protected.pdf")) {
+    //            assertNotNull(is, "protected.pdf must be present in src/test/resources");
+    //            try (PDDocument doc = factory.load(is, "test123")) {
+    //                assertNotNull(doc);
+    //            }
+    //        }
+    //    }
+    //
+    //    @Test
+    //    void testLoadPasswordProtectedPdfFromMultipart() throws IOException {
+    //        try (InputStream is = getClass().getResourceAsStream("/protected.pdf")) {
+    //            assertNotNull(is, "protected.pdf must be present in src/test/resources");
+    //            byte[] bytes = is.readAllBytes();
+    //            MockMultipartFile file = new MockMultipartFile("file", "protected.pdf",
+    // "application/pdf", bytes);
+    //            try (PDDocument doc = factory.load(file, "test123")) {
+    //                assertNotNull(doc);
+    //            }
+    //        }
+    //    }
 
-    
     @Test
     void testLoadReadOnlySkipsPostProcessing() throws IOException {
         PdfMetadataService mockService = mock(PdfMetadataService.class);
@@ -186,7 +164,6 @@ class CustomPDFDocumentFactoryTest {
         }
     }
 
-    
     @Test
     void testCreateNewDocument() throws IOException {
         try (PDDocument doc = factory.createNewDocument()) {
@@ -198,7 +175,7 @@ class CustomPDFDocumentFactoryTest {
     void testCreateNewDocumentBasedOnOldDocument() throws IOException {
         byte[] inflated = inflatePdf(basePdfBytes, 5);
         try (PDDocument oldDoc = Loader.loadPDF(inflated);
-             PDDocument newDoc = factory.createNewDocumentBasedOnOldDocument(oldDoc)) {
+                PDDocument newDoc = factory.createNewDocumentBasedOnOldDocument(oldDoc)) {
             assertNotNull(newDoc);
         }
     }
@@ -241,7 +218,6 @@ class CustomPDFDocumentFactoryTest {
 
     @BeforeEach
     void cleanup() {
-    	System.gc();
+        System.gc();
     }
-   
 }

src/test/java/stirling/software/SPDF/service/SpyPDFDocumentFactory.java

@@ -1,14 +1,14 @@
 package stirling.software.SPDF.service;
+
 import org.apache.pdfbox.io.RandomAccessStreamCache.StreamCacheCreateFunction;
 
-import stirling.software.SPDF.service.CustomPDFDocumentFactory;
-import stirling.software.SPDF.service.PdfMetadataService;
-
 class SpyPDFDocumentFactory extends CustomPDFDocumentFactory {
-	enum StrategyType {
-	    MEMORY_ONLY, MIXED, TEMP_FILE
-	}
-	
+    enum StrategyType {
+        MEMORY_ONLY,
+        MIXED,
+        TEMP_FILE
+    }
+
     public StrategyType lastStrategyUsed;
 
     public SpyPDFDocumentFactory(PdfMetadataService service) {
@@ -28,4 +28,4 @@ class SpyPDFDocumentFactory extends CustomPDFDocumentFactory {
         this.lastStrategyUsed = type;
         return super.getStreamCacheFunction(contentSize); // delegate to real behavior
     }
-}
+}

src/test/java/stirling/software/SPDF/utils/CustomHtmlSanitizerTest.java

@@ -27,25 +27,28 @@ class CustomHtmlSanitizerTest {
 
     private static Stream<Arguments> provideHtmlTestCases() {
         return Stream.of(
-            Arguments.of(
-                "<p>This is <strong>valid</strong> HTML with <em>formatting</em>.</p>",
-                new String[] {"<p>", "<strong>", "<em>"}
-            ),
-            Arguments.of(
-                "<p>Text with <b>bold</b>, <i>italic</i>, <u>underline</u>, "
-                        + "<em>emphasis</em>, <strong>strong</strong>, <strike>strikethrough</strike>, "
-                        + "<s>strike</s>, <sub>subscript</sub>, <sup>superscript</sup>, "
-                        + "<tt>teletype</tt>, <code>code</code>, <big>big</big>, <small>small</small>.</p>",
-                new String[] {"<b>bold</b>", "<i>italic</i>", "<em>emphasis</em>", "<strong>strong</strong>"}
-            ),
-            Arguments.of(
-                "<div>Division</div><h1>Heading 1</h1><h2>Heading 2</h2><h3>Heading 3</h3>"
-                        + "<h4>Heading 4</h4><h5>Heading 5</h5><h6>Heading 6</h6>"
-                        + "<blockquote>Blockquote</blockquote><ul><li>List item</li></ul>"
-                        + "<ol><li>Ordered item</li></ol>",
-                new String[] {"<div>", "<h1>", "<h6>", "<blockquote>", "<ul>", "<ol>", "<li>"}
-            )
-        );
+                Arguments.of(
+                        "<p>This is <strong>valid</strong> HTML with <em>formatting</em>.</p>",
+                        new String[] {"<p>", "<strong>", "<em>"}),
+                Arguments.of(
+                        "<p>Text with <b>bold</b>, <i>italic</i>, <u>underline</u>, "
+                                + "<em>emphasis</em>, <strong>strong</strong>, <strike>strikethrough</strike>, "
+                                + "<s>strike</s>, <sub>subscript</sub>, <sup>superscript</sup>, "
+                                + "<tt>teletype</tt>, <code>code</code>, <big>big</big>, <small>small</small>.</p>",
+                        new String[] {
+                            "<b>bold</b>",
+                            "<i>italic</i>",
+                            "<em>emphasis</em>",
+                            "<strong>strong</strong>"
+                        }),
+                Arguments.of(
+                        "<div>Division</div><h1>Heading 1</h1><h2>Heading 2</h2><h3>Heading 3</h3>"
+                                + "<h4>Heading 4</h4><h5>Heading 5</h5><h6>Heading 6</h6>"
+                                + "<blockquote>Blockquote</blockquote><ul><li>List item</li></ul>"
+                                + "<ol><li>Ordered item</li></ol>",
+                        new String[] {
+                            "<div>", "<h1>", "<h6>", "<blockquote>", "<ul>", "<ol>", "<li>"
+                        }));
     }
 
     @Test

src/test/java/stirling/software/SPDF/utils/PDFToFileTest.java

@@ -1,6 +1,5 @@
 package stirling.software.SPDF.utils;
 
-import io.github.pixee.security.ZipSecurity;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -29,6 +28,8 @@ import org.springframework.http.ResponseEntity;
 import org.springframework.mock.web.MockMultipartFile;
 import org.springframework.web.multipart.MultipartFile;
 
+import io.github.pixee.security.ZipSecurity;
+
 import stirling.software.SPDF.utils.ProcessExecutor.ProcessExecutorResult;
 
 /**
@@ -214,7 +215,8 @@ class PDFToFileTest {
 
             // Verify the content by unzipping it
             try (ZipInputStream zipStream =
-                    ZipSecurity.createHardenedInputStream(new java.io.ByteArrayInputStream(response.getBody()))) {
+                    ZipSecurity.createHardenedInputStream(
+                            new java.io.ByteArrayInputStream(response.getBody()))) {
                 ZipEntry entry;
                 boolean foundMdFiles = false;
                 boolean foundImage = false;
@@ -286,7 +288,8 @@ class PDFToFileTest {
 
             // Verify the content by unzipping it
             try (ZipInputStream zipStream =
-                    ZipSecurity.createHardenedInputStream(new java.io.ByteArrayInputStream(response.getBody()))) {
+                    ZipSecurity.createHardenedInputStream(
+                            new java.io.ByteArrayInputStream(response.getBody()))) {
                 ZipEntry entry;
                 boolean foundMainHtml = false;
                 boolean foundIndexHtml = false;
@@ -437,7 +440,8 @@ class PDFToFileTest {
 
             // Verify the content by unzipping it
             try (ZipInputStream zipStream =
-                    ZipSecurity.createHardenedInputStream(new java.io.ByteArrayInputStream(response.getBody()))) {
+                    ZipSecurity.createHardenedInputStream(
+                            new java.io.ByteArrayInputStream(response.getBody()))) {
                 ZipEntry entry;
                 boolean foundMainFile = false;
                 boolean foundMediaFiles = false;