Merge remote-tracking branch 'origin/master'

detectable/src/main/java/com/synopsys/integration/detectable/detectables/bazel/pipeline/step/HaskellCabalLibraryJsonProtoParser.java

@@ -24,7 +24,6 @@
 
 import java.util.ArrayList;
 import java.util.List;
-import java.util.Optional;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -67,17 +66,13 @@ private void extractAddDependencies(String jsonProtoString, List<NameVersion> de
                 throw new IntegrationException(String.format("Unable to parse attributes from rule inJSON proto string: %s", jsonProtoString));
             }
             List<AttributeItem> attributes = target.getRule().getAttribute();
-            Optional<NameVersion> dependency = extractDependency(attributes);
-            if (dependency.isPresent()) {
-                logger.debug(String.format("Adding dependency %s/%s", dependency.get().getName(), dependency.get().getVersion()));
-                dependencies.add(dependency.get());
-            } else {
-                logger.debug(String.format("No dependency was extractable from attributes: %s", attributes.toString()));
-            }
+            NameVersion dependency = extractDependency(attributes);
+            logger.debug(String.format("Adding dependency %s/%s", dependency.getName(), dependency.getVersion()));
+            dependencies.add(dependency);
         }
     }
 
-    private Optional<NameVersion> extractDependency(List<AttributeItem> attributes) throws IntegrationException {
+    private NameVersion extractDependency(List<AttributeItem> attributes) throws IntegrationException {
         String dependencyName = null;
         String dependencyVersion = null;
         for (AttributeItem attributeItem : attributes) {
@@ -88,7 +83,7 @@ private Optional<NameVersion> extractDependency(List<AttributeItem> attributes)
             }
             if (dependencyName != null && dependencyVersion != null) {
                 NameVersion dependencyNameVersion = new NameVersion(dependencyName, dependencyVersion);
-                return Optional.of(dependencyNameVersion);
+                return dependencyNameVersion;
             }
         }
         throw new IntegrationException(String.format("Dependency name/version not found in attribute list: %s", attributes.toString()));

docs/templates/content/30-running.ftl

@@ -49,69 +49,74 @@ Several aspects of script functionality can be configured, including:
 
 Information on how to configure the scripts is in [Shell script configuration](../advanced/script-configuration/).
 
-#### Linux or Mac (Bash)
+#### Linux or Mac
+
+On Linux or Mac, execute the ${solution_name} script (${bash_script_name}, which is a Bash script) from Bash.
 
 To download and run the latest version of ${solution_name} in a single command:
 
-    bash <(curl -s -L https://detect.synopsys.com/detect.sh)
+bash <(curl -s -L https://detect.synopsys.com/detect.sh)
 
 Append any command line arguments to the end, separated by spaces. For example:
 
-    bash <(curl -s -L https://detect.synopsys.com/detect.sh) --blackduck.url=https://blackduck.mydomain.com --blackduck.username=myusername
+bash <(curl -s -L https://detect.synopsys.com/detect.sh) --blackduck.url=https://blackduck.mydomain.com --blackduck.username=myusername
 
-#### Windows (PowerShell)
+#### Windows
+
+On Windows, execute the ${solution_name} script (${powershell_script_name}, which is a PowerShell script) from
+the [Command Prompt](https://en.wikipedia.org/wiki/Cmd.exe).
 
 To download and run the latest version of ${solution_name} in a single command:
 
-    powershell "[Net.ServicePointManager]::SecurityProtocol = 'tls12'; irm https://detect.synopsys.com/detect.ps1?$(Get-Random) | iex; detect"
+powershell "[Net.ServicePointManager]::SecurityProtocol = 'tls12'; irm https://detect.synopsys.com/detect.ps1?$(Get-Random) | iex; detect"
 
 Append any command line arguments to the end, separated by spaces. For example:
 
-    powershell "[Net.ServicePointManager]::SecurityProtocol = 'tls12'; irm https://detect.synopsys.com/detect.ps1?$(Get-Random) | iex; detect" --blackduck.url=https://blackduck.mydomain.com --blackduck.username=myusername
+powershell "[Net.ServicePointManager]::SecurityProtocol = 'tls12'; irm https://detect.synopsys.com/detect.ps1?$(Get-Random) | iex; detect" --blackduck.url=https://blackduck.mydomain.com --blackduck.username=myusername
 
 ### Running a specific version of ${solution_name}
 
 #### Linux or Mac (Bash)
 
 To run a specific version of ${solution_name}:
 
-    export DETECT_LATEST_RELEASE_VERSION={${solution_name} version}
-    bash <(curl -s -L https://detect.synopsys.com/detect.sh)
+export DETECT_LATEST_RELEASE_VERSION={${solution_name} version}
+bash <(curl -s -L https://detect.synopsys.com/detect.sh)
 
 For example, to run ${solution_name} version 5.5.0:
 
-    export DETECT_LATEST_RELEASE_VERSION=5.5.0
-    bash <(curl -s -L https://detect.synopsys.com/detect.sh)
+export DETECT_LATEST_RELEASE_VERSION=5.5.0
+bash <(curl -s -L https://detect.synopsys.com/detect.sh)
 
 #### Windows (PowerShell)
 
 To run a specific version of ${solution_name}:
 
-    $Env:DETECT_LATEST_RELEASE_VERSION = {${solution_name} version}
-    powershell "[Net.ServicePointManager]::SecurityProtocol = 'tls12'; irm https://detect.synopsys.com/detect.ps1?$(Get-Random) | iex; detect"
+$Env:DETECT_LATEST_RELEASE_VERSION = {${solution_name} version}
+powershell "[Net.ServicePointManager]::SecurityProtocol = 'tls12'; irm https://detect.synopsys.com/detect.ps1?$(Get-Random) | iex; detect"
 
 For example, to run ${solution_name} version 5.5.0:
 
-    $Env:DETECT_LATEST_RELEASE_VERSION = 5.5.0
-    powershell "[Net.ServicePointManager]::SecurityProtocol = 'tls12'; irm https://detect.synopsys.com/detect.ps1?$(Get-Random) | iex; detect"
+$Env:DETECT_LATEST_RELEASE_VERSION = 5.5.0
+powershell "[Net.ServicePointManager]::SecurityProtocol = 'tls12'; irm https://detect.synopsys.com/detect.ps1?$(Get-Random) | iex; detect"
 
 ## Running the ${solution_name} .jar
 
 Recent versions of the ${solution_name} .jar file are available for download from ${binary_repo_url_base}/${binary_repo_repo}/com/synopsys/integration/${project_name}.
 
 To run ${solution_name} by invoking the .jar file:
 
-    java -jar {path to .jar file}
+java -jar {path to .jar file}
 
 For example:
 
-    curl -O ${binary_repo_url_base}/${binary_repo_repo}/com/synopsys/integration/${project_name}/5.6.2/synopsys-detect-5.6.2.jar
-    java -jar synopsys-detect-5.6.2.jar
+curl -O ${binary_repo_url_base}/${binary_repo_repo}/com/synopsys/integration/${project_name}/5.6.2/synopsys-detect-5.6.2.jar
+java -jar synopsys-detect-5.6.2.jar
 
 You can use the ${solution_name} Bash script (${bash_script_name}) to download the ${solution_name} .jar file:
 
-    export DETECT_DOWNLOAD_ONLY=1
-    ./${bash_script_name}
+export DETECT_DOWNLOAD_ONLY=1
+./${bash_script_name}
 
 ## Including and excluding tools and detectors
 
@@ -124,11 +129,11 @@ By default, all tools are eligible to run; the set of tools that actually run
 depends on the properties you set.
 To limit the eligible tools to a given list, use:
 
-    --detect.tools={comma-separated list of tool names, all uppercase}
+--detect.tools={comma-separated list of tool names, all uppercase}
 
 To exclude specific tools, use:
 
-    --detect.tools.excluded={comma-separated list of tool names, all uppercase}
+--detect.tools.excluded={comma-separated list of tool names, all uppercase}
 
 Exclusions take precedence over inclusions.
 
@@ -142,11 +147,11 @@ By default, all detectors are eligible to run.  The set of detectors that actual
 run depends on the files existing in your project directory.
 To limit the eligible detectors to a given list, use:
 
-    --detect.included.detector.types={comma-separated list of detector names}
+--detect.included.detector.types={comma-separated list of detector names}
 
 To exclude specific detectors, use:
 
-    --detect.excluded.detector.types={comma-separated list of detector names}
+--detect.excluded.detector.types={comma-separated list of detector names}
 
 Exclusions take precedence over inclusions.
 

docs/templates/content/40-configuring.ftl

@@ -5,7 +5,15 @@ ${solution_name} is configured by assigning values to properties.
 ## On the command line
 
 One method for configuring ${solution_name} is by setting [${solution_name} property values](../properties/all-properties/) on the command line.
-When setting a property value on the command line, prefix the property name with two hyphens ("--"). For example,
+When setting a property value on the command line, prefix the property name with two hyphens (--).
+
+To add one property setting to the command line, add the following at the end:
+```
+{space}--{property name}={value}
+```
+There is a space before and between each complete property setting, but there are no spaces around the equals sign (=).
+
+For example,
 to set property *detect.project.value*:
 ```
 bash <(curl -s -L https://detect.synopsys.com/detect.sh) --detect.project.name=MyProject

docs/templates/content/advanced/script-escaping-special-characters.ftl

@@ -1,25 +1,32 @@
 # Quoting and escaping shell script arguments
 
-## Bash script (${bash_script_name})
+## Running the Bash script (${bash_script_name}) on Linux or Mac
+
+The recommended environment for running ${bash_script_name} on Linux or Mac is Bash.
 
 When an argument contains a space, you should wrap the argument with escaped quotes.
 
 For example:
 
-    detect.sh --detect.project.name=\"Project Test\"
+detect.sh --detect.project.name=\"Project Test\"
 
 When an argument contains a special character (for example, an exclamation point) you must
 escape the character with a backslash. The backslash should precede the escaped character.
 
 For example:
 
-    detect.sh --detect.project.name=Project\!Test
+detect.sh --detect.project.name=Project\!Test
+
+## Running the PowerShell script (${powershell_script_name}) on Windows
 
-## PowerShell script (${powershell_script_name})
+The recommended environment for running ${powershell_script_name} on Windows is the [Windows Command Prompt](https://en.wikipedia.org/wiki/Cmd.exe).
 
 When an argument contains a space, comma or other special character, you should escape the character with a back quote. The back quote should precede the escaped character.
 
 For example:
-
-    detect.ps1 --detect.project.name=Project` Test
-    detect.ps1 --detect.signature.scanner.paths=path1`,path2
+```
+detect.ps1 --detect.project.name=Project` Test
+```
+```
+detect.ps1 --detect.signature.scanner.paths=path1`,path2
+```

docs/templates/content/advanced/troubleshooting/general-troubleshooting.ftl

@@ -3,6 +3,15 @@
 ## Troubleshooting best practices
 
 1. Run ${solution_name} with `--logging.level.com.synopsys.integration=DEBUG` (the default logging level, INFO, is insufficient for troubleshooting) and read through the entire log for clues.
+1. ${solution_name} typically runs package manager commands or build tool commands similar to commands used in your build.
+When run by ${solution_name}, those commands (as well as the environment
+in which they run) need to be consistent with your build, and it's important to verify that they are.
+For example, the Gradle detector defaults to running
+*./gradlew dependencies* if it finds the file ./gradlew. If your build runs a different Gradle command or wrapper
+(say, /usr/local/bin/gradle), use property
+*detect.gradle.path* to tell ${solution_name} to run the same Gradle command that your build runs.
+Check a DEBUG log for the package manager commands that ${solution_name} is running, and compare
+them to the commands your build runs.
 1. For more troubleshooting information: Run ${solution_name} with `--detect.diagnostic=true`. This will generate a diagnostic zip that contains many useful intermediate files and logs, including the generated BDIO (.jsonld) files and ${blackduck_signature_scanner_name} logs.
 1. For even more troubleshooting information: Run ${solution_name} with `--detect.diagnostic.extended=true`. This will generate an extended diagnostic zip that will also include lock files and build artifacts when appropriate.
 1. See if you can reproduce the problem using the latest version of ${solution_name} with the latest version of ${blackduck_product_name}. If not, the problem may be either fixed, or due to incompatible ${solution_name} / ${blackduck_product_name} versions.
@@ -41,9 +50,9 @@ Diagnostic mode:
 * Includes any additional reports ${solution_name} might make such as dependency counts.
 
 * Additionally --detect.diagnostic or --detect.diagnostic.extended includes additional relevant files such as:
-    * Npm package locks.
-    * vendor.config.
-    * C/C++ compilation database.
+* Npm package locks.
+* vendor.config.
+* C/C++ compilation database.
 
 The property --detect.diagnostic.extended, when set to true, enables the collection of relevant files that are not generated by ${solution_name}; for example, lock files. By default, diagnostic mode only includes files generated by ${solution_name} where --detect.diagnostic.extended might include files it finds.  For example, a package.lock that is too deep for ${solution_name}'s search depth is not included, or a package.lock that was not parsed due to exclusion.
 

src/main/java/com/synopsys/integration/detect/configuration/DetectProperties.kt

@@ -520,7 +520,7 @@ class DetectProperties {
         }
         val DETECT_GRADLE_BUILD_COMMAND = NullableStringProperty("detect.gradle.build.command").apply {
             setInfo("Gradle Build Command", "3.0.0")
-            setHelp("Gradle command line arguments to add to the mvn/mvnw command line.", "By default, Detect runs the gradle (or gradlew) command with one task: dependencies. You can use this property to insert one or more additional gradle command line arguments (options or tasks) before the dependencies argument.")
+            setHelp("Gradle command line arguments to add to the gradle/gradlew command line.", "By default, Detect runs the gradle (or gradlew) command with one task: dependencies. You can use this property to insert one or more additional gradle command line arguments (options or tasks) before the dependencies argument.")
             setGroups(DetectGroup.GRADLE, DetectGroup.SOURCE_SCAN)
         }
         val DETECT_GRADLE_EXCLUDED_CONFIGURATIONS = NullableStringProperty("detect.gradle.excluded.configurations").apply {