MTA-1289 adding new mta cli commands: Analyze and Transform

docs/cli-guide/master.adoc

@@ -33,6 +33,12 @@ include::topics/installing-web-console-or-cli-tool.adoc[leveloffset=+2]
 // Run the CLI
 include::topics/cli-run.adoc[leveloffset=+2]
 
+// Analyze application source code
+include::topics/mta-cli-analyze.adoc[leveloffset=+3]
+
+// Transform XML rules to YAML
+include::topics/mta-cli-transform.adoc[leveloffset=+3]
+
 // Use OpenRewrite recipes
 include::topics/using-openrewrite-recipes.adoc[leveloffset=+3]
 

docs/topics/mta-cli-analyze.adoc

@@ -0,0 +1,81 @@
+// Module included in the following assemblies:
+//
+// * docs/cli-guide/master.adoc
+
+:_content-type: CONCEPT
+[id="mta-cli-analyze_{context}"]
+= Performing analysis using the command line
+
+`Analyze` allows running source code and binary analysis using `analyzer-lsp`.
+
+.To run analysis on application source code, run the following command:
+
+[source,terminal,subs="attributes+"]
+----
+{mta-cli} analyze --input=<path/to/source/code> --output=<path/to/output/dir>
+----
+
+All flags:
+
+[source,terminal,subs="attributes+"]
+----
+Analyze application source code
+
+Usage:
+  {mta-cli} analyze [flags]
+
+Flags:
+      --analyze-known-libraries   analyze known open-source libraries
+  -h, --help                      help for analyze
+  -i, --input string              path to application source code or a binary
+      --json-output               create analysis and dependency output as json
+      --list-sources              list rules for available migration sources
+      --list-targets              list rules for available migration targets
+  -l, --label-selector string     run rules based on specified label selector expression
+      --maven-settings string     path to a custom maven settings file to use
+      --overwrite                 overwrite output directory
+      --skip-static-report        do not generate static report
+  -m, --mode string               analysis mode. Must be one of 'full' or 'source-only' (default "full")
+  -o, --output string             path to the directory for analysis output
+      --rules stringArray         filename or directory containing rule files
+      --skip-static-report        do not generate static report
+  -s, --source string             source technology to consider for analysis. To specify multiple sources, repeat the parameter: --source <source_1> --source <source_2> etc.
+  -t, --target string             target technology to consider for analysis. To specify multiple targets, repeat the parameter: --target <target_1> --target <target_2> etc.
+
+Global Flags:
+      --log-level uint32   log level (default 4)
+      --no-cleanup         do not cleanup temporary resources
+----
+.Usage example
+
+. Get an example application to run analysis on.
+. List available target technologies.
++
+[source,terminal,subs="attributes+"]
+----
+{mta-cli} analyze --list-targets
+----
+. Run an analysis with a specified target technology, for example `cloud-readiness`.
++
+[source,terminal,subs="attributes+"]
+----
+{mta-cli} analyze --input=<path-to/example-applications/example-1> --output=<path-to-output-dir> --target=cloud-readiness
+----
+. Several analysis reports are created in your specified output path:
++
+[source,terminal,subs="attributes+"]
+
+----
+$ ls ./output/ -1
+analysis.log
+dependencies.yaml
+dependency.log
+output.yaml
+static-report
+----
+
+`output.yaml` is the file that contains the issues report.
+
+`static-report` contains the static HTML report.
+
+`dependencies.yaml` contains a dependencies report.

docs/topics/mta-cli-transform.adoc

@@ -0,0 +1,105 @@
+// Module included in the following assemblies:
+//
+// * docs/cli-guide/master.adoc
+
+:_content-type: CONCEPT
+[id="mta-cli-transform_{context}"]
+= Performing transformation using the command line
+
+Transform has two sub commands - `openrewrite` and `rules`.
+
+[source,terminal,subs="attributes+"]
+----
+Transform application source code or {LC_PSN} XML rules
+
+Usage:
+  {mta-cli} transform [flags]
+  {mta-cli} transform [command]
+
+Available Commands:
+  openrewrite Transform application source code using OpenRewrite recipes
+  rules       Convert XML rules to YAML
+
+Flags:
+  -h, --help   help for transform
+
+Global Flags:
+      --log-level uint32   log level (default 4)
+      --no-cleanup         do not cleanup temporary resources
+
+Use "{mta-cli} transform [command] --help" for more information about a command.
+----
+
+== `OpenRewrite`
+
+The `openrewrite` sub command allows running `OpenRewrite` recipes on source code.
+[source,terminal,subs="attributes+"]
+----
+Transform application source code using OpenRewrite recipes
+
+Usage:
+  {mta-cli} transform openrewrite [flags]
+
+Flags:
+  -g, --goal string     target goal (default "dryRun")
+  -h, --help            help for openrewrite
+  -i, --input string    path to application source code directory
+  -l, --list-targets    list all available OpenRewrite recipes
+  -s, --maven-settings string   path to a custom maven settings file to use
+  -t, --target string   target openrewrite recipe to use. Run --list-targets to get a list of packaged recipes.
+
+Global Flags:
+      --log-level uint32   log level (default 4)
+      --no-cleanup         do not cleanup temporary resources
+----
+
+.To run `transform openrewrite` on application source code, run the following command:
+[source,terminal,subs="attributes+"]
+----
+{mta-cli} transform openrewrite --input=<path/to/source/code> --target=<exactly_one_target_from_the_list>
+----
+[NOTE]
+====
+You can only use a single target to run the `transform overwrite` command.
+====
+
+== `Rules`
+
+The `rules` sub command allows converting {LC_PSN} XML rules to analyzer-lsp YAML rules using `windup-shim`.
+[source,terminal,subs="attributes+"]
+----
+Convert XML rules to YAML
+
+Usage:
+  {mta-cli} transform rules [flags]
+
+Flags:
+  -h, --help                help for rules
+  -i, --input stringArray   path to XML rule file(s) or directory
+  -o, --output string       path to output directory
+
+Global Flags:
+      --log-level int   log level (default 5)
+----
+
+.To run `transform rules` on application source code, run the following:
+[source,terminal,subs="attributes+"]
+----
+{mta-cli} transform rules --input=<path/to/xmlrules> --output=<path/to/output/dir>
+----
+
+.Usage example
+. Get an example application to transform source code.
+. View the available OpenRewrite recipes.
++
+[source,terminal,subs="attributes+"]
+----
+{mta-cli} transform openrewrite --list-targets
+----
+. Run a recipe on the example application.
++
+[source,terminal,subs="attributes+"]
+----
+{mta-cli} transform openrewrite --input=<path-to/jakartaee-duke> --target=jakarta-imports
+----
+Inspect the `jakartaee-duke` application source code diff to see the transformation

docs/topics/templates/document-attributes.adoc

@@ -60,6 +60,7 @@ endif::[]
 // *******************
 :CLIName: CLI
 :CLINameTitle: CLI
+:mta-cli: mta-cli
 :MavenName: Maven plugin
 :MavenNameTitle: Maven Plugin