Introduce new 'docker run' validation command

docker/docker-entrypoint.sh

@@ -45,6 +45,12 @@ elif [ "$1" = "start-worker" ] ; then
   php artisan storage:mkdirs
   php -d memory_limit=-1 artisan queue:work --verbose --max-time=3600 --memory=${WORKER_MEMORY_LIMIT:-256}
 
+elif [ "$1" = "validate-xml" ] ; then
+  for i in `ls /tmp/validate`; do
+   FILE_LIST="$FILE_LIST /tmp/validate/$i";
+  done
+  php artisan submission:validate $FILE_LIST
+
 # Otherwise, throw an error...
 else
   echo "Unknown argument(s) provided: $*"

docs/validation.md

@@ -0,0 +1,69 @@
+# Validating XML files for CDash
+
+CDash maintains a set of schema files for the expected structure of
+the incoming XML files that will be parsed.  Normally, this is not a
+problem as CTest writes properly formatted files.
+
+In the rare case that the XML files are not being created by the CTest process,
+we have a few opportunities for the user to be informed that there are problems
+with the XML files that are uploaded
+
+1. Prior to Submission
+
+The CDash Docker container has an entry-point which will look for files within
+a directory which has been mounted to the container.  The directory of files
+should be mounted to `/tmp/validate`.  This entry point called `validate-xml`
+should be executed via the `run` command.
+
+For example:
+```bash
+
+CDash$ sudo docker run -v /home/softhat/Work/LANL/py_example/clang_build/Testing/20260504-1334:/tmp/validate kitware/cdash validate-xml
+Validated file: /tmp/validate/Build.xml.
+Validated file: /tmp/validate/Configure.xml.
+Validated file: /tmp/validate/Coverage.xml.
+Validated file: /tmp/validate/CoverageLog-0.xml.
+Validated file: /tmp/validate/Done.xml.
+Validated file: /tmp/validate/Test.xml.
+```
+Here we mount the absolute path of our directory of files to `/tmp/validate`
+using the `-v` flag and supply the `validate-xml` command.
+
+Failures in each file will be printed to the screen and the error code is 
+non-zero as expected:
+
+```bash
+CDash$ sudo docker run --env-file .env.dev -v /home/softhat/Work/LANL/py_example/clang_build/Testing/20260504-1334:/tmp/validate kitware/cdash:testing validate-xml
+WARNING: Element 'Site': The attribute 'Name' is required but missing.
+ in /tmp/validate/Build.xml, line: 25, column: 0
+Validated file: /tmp/validate/Configure.xml.
+Validated file: /tmp/validate/Coverage.xml.
+Validated file: /tmp/validate/CoverageLog-0.xml.
+Validated file: /tmp/validate/Done.xml.
+Validated file: /tmp/validate/Test.xml.
+FAILED: Some XML file checks did not pass!
+CDash$ echo $?
+1
+
+```
+
+2. During Submission
+
+For validation during the submission process, CDash will look at the
+`VALIDATE_SUBMISSIONS` environment variable.  The value of the variable
+determines how strict CDash will be when accepting XML files that may be
+invalid.
+
+* `SILENT`
+  * CDash will log a message to it's log file about the failures it finds,
+    but will continue to process the content of the file.
+  * This is the default value.
+* `WARN`
+  * CDash will log a message to it's log file about the failures it finds.
+    It will also send the failure results in the `message` attribute of the
+    response from the HTTP request but will attempt to continue processing
+    the content of the file. 
+* `REJECT`
+  * CDash will log a message to it's log file about the failures it finds.
+    It will also halt processing the file, returning a 400 response code and
+    informing the user the failure results