fix: make bpn response failures diagnosable

src/BusProNet/XmlCrawlerFactory.php

@@ -20,4 +20,38 @@ final class XmlCrawlerFactory
 
         return $crawler;
     }
+
+    /**
+     * Explains why create() returned an empty Crawler. addXmlContent() discards the
+     * libxml errors, so an empty, a malformed and a truncated payload are
+     * indistinguishable afterwards; this re-parses to recover the reason. Only worth
+     * calling on the failure path.
+     */
+    public static function diagnose(string $xml): string
+    {
+        if ('' === trim($xml)) {
+            return sprintf('empty response (%d bytes)', strlen($xml));
+        }
+
+        $previousUseErrors = libxml_use_internal_errors(true);
+        libxml_clear_errors();
+
+        try {
+            simplexml_load_string($xml);
+
+            $messages = [];
+            foreach (libxml_get_errors() as $error) {
+                $messages[] = sprintf('%s (line %d, column %d)', trim($error->message), $error->line, $error->column);
+            }
+
+            if ([] === $messages) {
+                return sprintf('unknown XML error (%d bytes)', strlen($xml));
+            }
+
+            return sprintf('%s (%d bytes)', implode('; ', array_unique($messages)), strlen($xml));
+        } finally {
+            libxml_clear_errors();
+            libxml_use_internal_errors($previousUseErrors);
+        }
+    }
 }