Profile resolution how-to readmes (usnistgov#1666)

* Profile resolution how-to readmes
Fixes usnistgov#1178

* Delete old `resolver-2018` folder

* Update resolver-pipeline readme.md with more generic instructions on running the pipeline

Co-authored-by: A.J. Stein <alexander.stein@nist.gov>

* Remove notice to only use Saxon 10 in line with previous feedback

* Added instructions for the wrapper script

---------

Co-authored-by: A.J. Stein <alexander.stein@nist.gov>

src/utils/util/resolver-pipeline/README.md

@@ -0,0 +1,66 @@
+# Profile Resolver Pipeline
+
+Profile resolution is implemented here as a sequence of XSLT transformations. The sequence applies to defined inputs (a **source profile** with imported **catalog** sources) and produces defined outputs (a **profile resolution result** in the form of a catalog). The word **baseline** also refers to a particular profile in application, whether in its unprocessed form or its resolved, serialized form.
+
+The sequence of XSLT transformations reflects and roughly corresponds to the steps in profile resolution described for OSCAL in the [Profile Resolution Specification](https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/):
+
+- **selection**: importing catalogs or profiles, and selecting controls from them
+
+- **organization (merging)**: organizing the selected controls for the output representation
+
+- **modification**: setting parameters and potentially supplementing, amending or editing control text
+
+## Usage
+
+The entry point for the transformation pipeline is `oscal-profile-RESOLVE.xsl`, which invokes the transformation steps in sequence, taking the source profile document as primary input.
+
+The following additional parameters can be used to modify the transformation pipeline's behavior:
+
+| Name                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                           | Default                                      |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `hide-source-profile-uri` | If `true`, the output catalog's metadata does not record the source profile's URI.                                                                                                                                                                                                                                                                                                                                                    | `false`                                      |
+| `path-to-source`          | Path from output catalog to location of source profile.                                                                                                                                                                                                                                                                                                                                                                               | None                                         |
+| `top-uuid`                | UUID value for top-level element in output catalog, if `uuid-method` is `user-provided`.                                                                                                                                                                                                                                                                                                                                              | None                                         |
+| `uuid-method`             | Method for computing UUID of top-level element in output catalog. Valid values are: `random-xslt`, in which case the `random-number-generator` XPath function must be available; `random-java`, in which case the `java.util.UUID.randomUUID()` Java method must be available; `user-provided`, in which case you must specify the `top-uuid` parameter; `web-service`, referring to the `uuid-service` parameter value; and `fixed`. | `fixed`                                      |
+| `uuid-service`            | URI for a web service that produces a UUID, if `uuid-method` is `web-service`.                                                                                                                                                                                                                                                                                                                                                        | `https://www.uuidgenerator.net/api/version4` |
+| `trace`                   | If set to `on`, additional debug information will be printed to the console and `opr:ERROR`, `opr:WARNING` messages will be retained in the output document.                                                                                                                                                                                                                                                                          | None                                         |
+
+Note that URIs (addresses) given in a profile document must link correctly as absolute or relative paths to their imported catalogs, as demonstrated in [examples](../../../specifications/profile-resolution/profile-resolution-examples).
+
+A serialized output of profile resolution takes the form of an OSCAL catalog. Assuming inputs are correctly formed, the output is valid to the catalog schema.
+
+## Invoking the Pipeline
+
+The profile resolver and other utilities in this repo rely on open-source libraries and utilities developed by third parties. To review the software version used by this project, please review [the `build` directory for manifests of software and the specific versions](../../../../build) we recommend for running utilities from this repo, specifically the recommended [version of Saxon XSLT processor defined in the pom.xml manifest](../../../../build/pom.xml).
+
+### Using Saxon Manually From the Command Line
+
+Before you begin:
+
+- Install the Java runtime using your preferred method.
+- Download a compatible version of [Saxon Java Home Edition](https://www.saxonica.com/download/java.xml) and extract the `saxon-he` jar file.
+
+Invoke Saxon with your document and the profile resolution stylesheet as follows:
+
+```
+$ java -jar /path/to/saxon-he-10.x.jar -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml
+```
+
+Saxon allows users to specify additional parameters (such as the ones specified [above](#usage)) by adding arguments with the format `name=value` to the end of the above command. As an example, see the command:
+
+```bash
+$ java -jar /path/to/saxon-he-10.x.jar -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml uuid-method=random-xslt hide-source-profile-uri=true
+```
+
+### Using the `oscal-profile-resolve.sh` Wrapper Script
+
+The [`oscal-profile-resolve.sh`](./oscal-profile-resolve.sh) wrapper script only requires [Maven](https://maven.apache.org/) to be installed.
+It manages external dependencies, and can be invoked from other directories.
+
+The syntax for invoking the wrapper script is as follows:
+
+```bash
+$ ./oscal-profile-resolve.sh YOUR_PROFILE_DOCUMENT.xml YOUR_RESULT_BASELINE.xml [additional arguments]
+```
+
+Additional arguments are passed into Saxon verbatim and should be in the same `name=value` format described [above](#using-saxon-manually-from-the-command-line).

src/utils/util/resolver-pipeline/TESTING.md

@@ -0,0 +1,7 @@
+# Profile Resolver Pipeline Tests
+
+The `testing/*` folders contain XSpec tests that indicate expected interim results of each XSLT transformation in the sequence.
+
+Note that these interim results are _not necessarily valid to any OSCAL schema_, although they are quite close to OSCAL profile and catalog syntax.
+
+The files in `testing/*` are only for this implementation. Implementation-independent tests and sample files for profile resolution are [with the specification](../../../specifications/profile-resolution).

src/utils/util/resolver-pipeline/oscal-profile-resolve.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# OSCAL Profile Resolution Pipeline Wrapper
+
+set -Eeuo pipefail
+
+usage() {
+    cat <<EOF
+Usage: $(basename "${BASH_SOURCE[0]}") TARGET_PROFILE OUTPUT_BASELINE [ADDITIONAL_ARGS]
+
+Runs the OSCAL Profile Resolution Pipeline on the TARGET_PROFILE.
+
+Additional arguments should be specified in the `key=value` format.
+EOF
+}
+
+if ! [ -x "$(command -v mvn)" ]; then
+  echo 'Error: Maven (mvn) is not in the PATH, is it installed?' >&2
+  exit 1
+fi
+
+[[ -z "${1-}" ]] && { echo "Error: TARGET_PROFILE not specified"; usage; exit 1; }
+TARGET_PROFILE=$1
+[[ -z "${2-}" ]] && { echo "Error: OUTPUT_BASELINE not specified"; usage; exit 1; }
+OUTPUT_BASELINE=$2
+
+ADDITIONAL_ARGS=$(shift 2; echo $@)
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd)"
+OSCAL_DIR="${SCRIPT_DIR}/../../../.."
+POM_FILE="${OSCAL_DIR}/build/pom.xml"
+ENTRY_STYLESHEET="${SCRIPT_DIR}/oscal-profile-RESOLVE.xsl"
+
+mvn \
+    -f $POM_FILE \
+    exec:java \
+    -Dexec.mainClass="net.sf.saxon.Transform" \
+    -Dexec.args="-t -s:$TARGET_PROFILE -xsl:$ENTRY_STYLESHEET -o:$OUTPUT_BASELINE $ADDITIONAL_ARGS"