✨ Add new command to run YAML tests

.github/workflows/testing.yaml

@@ -12,7 +12,11 @@ jobs:
         run: |
           podman build -t localhost/kantra:latest -f Dockerfile .
           go build -o kantra main.go
-
+
+      - name: Run unit tests
+        run: |
+          RUNNER_IMG=localhost/kantra:latest go test ./...
+
       - name: Fetch sample applications
         run: |
           git clone https://github.com/konveyor/example-applications
@@ -22,6 +26,7 @@ jobs:
         run: |
           RUNNER_IMG=localhost/kantra:latest ./kantra analyze --input $(pwd)/example-applications/example-1/ --output ./output/ --rules ./test-data/jni-native-code-test.windup.xml --target cloud-readiness
 
+      # TODO (pgaikwad): Change this to a yaml test and run `kantra test`
       - name: Fail if analysis output does not match expected
         run: |
           expected_file=./test-data/analysis-output.yaml

Dockerfile

@@ -22,6 +22,7 @@ RUN go mod download
 # Copy the go source
 COPY main.go main.go
 COPY cmd/ cmd/
+COPY pkg/ pkg/
 
 # Build
 ARG VERSION

README.md

@@ -3,115 +3,95 @@
 Kantra is a CLI that unifies analysis and transformation capabilities of Konveyor.
 
 ## Installation
-The easiest way to install Kantra is to get it via the container image. To download latest container image, run:
 
-### Linux
-
-```sh
-podman cp $(podman create --name kantra-download quay.io/konveyor/kantra:latest):/usr/local/bin/kantra . && podman rm kantra-download
-```
-
-### MacOS
-
-**Note:** There is a known [issue](https://github.com/containers/podman/issues/16106)
-with limited number of open files in mounted volumes on MacOS, which may affect kantra performance.
-
-Prior to starting your podman machine, run:
-
-```sh
-ulimit -n unlimited
-```
-
- - This must be run after each podman machine reboot.
-
-In order to correctly mount volumes, your podman machine must contain options:
-
-```sh
-podman machine init <vm_name> -v $HOME:$HOME -v /private/tmp:/private/tmp -v /var/folders/:/var/folders/
-```
-
-Increase podman resources:
-
-```sh
-podman machine set <vm_name> --cpus 4 --memory 4096
-```
-
-
-Ensure that we use the connection to the VM `<vm_name>` we created earlier by default:
-
-```sh
-podman system connection default <vm_name>
-```
-
-```sh
-podman pull quay.io/konveyor/kantra:latest && podman run --name kantra-download quay.io/konveyor/kantra:latest 1> /dev/null 2> /dev/null && podman cp kantra-download:/usr/local/bin/darwin-kantra kantra && podman rm kantra-download
-```
-
-### Windows
-
-```sh
-podman pull quay.io/konveyor/kantra:latest && podman run --name kantra-download quay.io/konveyor/kantra:latest 1> /dev/null 2> /dev/null && podman cp kantra-download:/usr/local/bin/windows-kantra kantra && podman rm kantra-download
-```
-
----
-
-The above will copy the binary into your current directory. Move it to PATH for system-wide use:
-
-```sh
-sudo mv ./kantra /usr/local/bin/
-```
-
-To confirm Kantra is installed, run:
-
-```sh
-kantra --help
-```
-
-This should display the help message.
+The easiest way to install Kantra is to get it via the container image.
+
+1. To download latest container image using _podman_, follow instructions for your operating system:
+
+  * For Linux, run:
+
+    ```sh
+    podman cp $(podman create --name kantra-download quay.io/konveyor/kantra:latest):/usr/local/bin/kantra . && podman rm kantra-download
+    ```
+
+  * For MacOS
+
+    Prior to starting your podman machine, run:
+
+    ```sh
+    ulimit -n unlimited
+    ```
+    > This must be run after each podman machine reboot.
+
+    Init your _podman_ machine :
+
+    ```sh
+    podman machine init <vm_name> -v $HOME:$HOME -v /private/tmp:/private/tmp -v /var/folders/:/var/folders/
+    ```
+
+    Increase podman resources:
+
+    ```sh
+    podman machine set <vm_name> --cpus 4 --memory 4096
+    ```
+
+    Ensure that we use the connection to the VM `<vm_name>` we created earlier by default:
+
+    ```sh
+    podman system connection default <vm_name>
+    ```
+
+    Finally, run:
+
+    ```sh
+    podman pull quay.io/konveyor/kantra:latest && podman run --name kantra-download quay.io/konveyor/kantra:latest 1> /dev/null 2> /dev/null && podman cp kantra-download:/usr/local/bin/darwin-kantra kantra && podman rm kantra-download
+    ```
+
+  * For Windows, run: 
+
+    ```sh
+    podman pull quay.io/konveyor/kantra:latest && podman run --name kantra-download quay.io/konveyor/kantra:latest 1> /dev/null 2> /dev/null && podman cp kantra-download:/usr/local/bin/windows-kantra kantra && podman rm kantra-download
+    ```
+
+2. The above will copy the binary into your current directory. Move it to PATH for system-wide use:
+
+    ```sh
+    sudo mv ./kantra /usr/local/bin/
+    ```
+
+3. To confirm Kantra is installed, run:
+
+    ```sh
+    kantra --help
+    ```
+
+    This should display the help message.
 
 ## Usage
 
-Kantra has two subcommands - `analyze` and `transform`:
+Kantra has three subcommands:
 
+1. _analyze_: This subcommand allows running source code analysis on input source code or a binary.
 
-```sh
-A cli tool for analysis and transformation of applications
-
-Usage:
-  kantra [command]
-
-Available Commands:
-  analyze     Analyze application source code
-  completion  Generate the autocompletion script for the specified shell
-  help        Help about any command
-  transform   Transform application source code or windup XML rules
-
-Flags:
-  -h, --help            help for kantra
-      --log-level int   log level (default 5)
-
-Use "kantra [command] --help" for more information about a command.
-```
+2. _transform_: This subcommand allows - converting XML rules to YAML, and running OpenRewrite recipes on source code.
 
+3. _test_: This subcommand allows testing YAML rules.
 
 ### Analyze
 
-Analyze allows running source code and binary analysis using [analyzer-lsp](https://github.com/konveyor/analyzer-lsp)
+_analyze_ subcommand allows running source code and binary analysis using [analyzer-lsp](https://github.com/konveyor/analyzer-lsp)
 
 To run analysis on application source code, run:
 
 ```sh
 kantra analyze --input=<path/to/source/code> --output=<path/to/output/dir>
 ```
 
+_--input_ must point to a source code directory or a binary file, _--output_ must point to a directory to contain analysis results. 
+
 All flags:
 
 ```sh
-Analyze application source code
-
-Usage:
-  kantra analyze [flags]
-
 Flags:
       --analyze-known-libraries   analyze known open-source libraries
   -h, --help                      help for analyze
@@ -125,90 +105,84 @@ Flags:
       --skip-static-report        do not generate static report
   -s, --source stringArray        source technology to consider for analysis. Use multiple times for additional sources: --source <source1> --source <source2> ...
   -t, --target stringArray        target technology to consider for analysis. Use multiple times for additional targets: --target <target1> --target <target2> ...
-
-Global Flags:
-      --log-level int   log level (default 5)
 ```
 
 ### Transform
 
-Transform has two subcommands - `openrewrite` and `rules`.
+Transform has two subcommands:
 
-```sh
-Transform application source code or windup XML rules
+1. _openrewrite_: This subcommand allows running one or more available OpenRewrite recipes on input source code.  
 
-Usage:
-  kantra transform [flags]
-  kantra transform [command]
+2. _rules_: This sucommand allows converting Windup XML rules into the analyzer-lsp YAML format.
 
-Available Commands:
-  openrewrite Transform application source code using OpenRewrite recipes
-  rules       Convert XML rules to YAML
+#### OpenRewrite
 
-Flags:
-  -h, --help   help for transform
+_openrewrite_ subcommand allows running [OpenRewrite](https://docs.openrewrite.org/) recipes on source code.
 
-Global Flags:
-      --log-level int   log level (default 5)
+To transform applications using OpenRewrite, run:
 
-Use "kantra transform [command] --help" for more information about a command.
+```sh
+kantra transform openrewrite --input=<path/to/source/code> --target=<exactly_one_target_from_the_list>
 ```
 
-#### OpenRewrite
-
-`openrewrite` subcommand allows running [OpenRewrite](https://docs.openrewrite.org/) recipes on source code.
-
+The value of _--target_ option must be one of the available OpenRewrite recipes. To list all available recipes, run: 
 
 ```sh
-Transform application source code using OpenRewrite recipes
+kantra transform --list-targets
+```
 
-Usage:
-  kantra transform openrewrite [flags]
+All flags:
 
+```sh
 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 int   log level (default 5)
 ```
 
-To run `transform openrewrite` on application source code, run:
+#### Rules
+
+_rules_ subcommand allows converting Windup XML rules to analyzer-lsp YAML rules using [windup-shim](https://github.com/konveyor/windup-shim)
+
+To convert Windup XML rules to the analyzer-lsp YAML format, run:
 
 ```sh
-kantra transform openrewrite --input=<path/to/source/code> --target=<exactly_one_target_from_the_list>
+kantra transform rules --input=<path/to/xmlrules> --output=<path/to/output/dir>
 ```
 
-#### Rules
+_--input_ flag should point to a file or a directory containing XML rules, _--output_ should point to an output directory for YAML rules.
 
-`rules` subcommand allows converting Windup XML rules to analyzer-lsp YAML rules using [windup-shim](https://github.com/konveyor/windup-shim)
+All flags:
 
 ```sh
-Convert XML rules to YAML
-
-Usage:
-  kantra 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:
+### Test
+
+_test_ subcommand allows running tests on YAML rules written for analyzer-lsp. 
+
+The input to test runner will be one or more test files and / or directories containing tests written in YAML.
 
 ```sh
-kantra transform rules --input=<path/to/xmlrules> --output=<path/to/output/dir>
+kantra test /path/to/a/single/tests/file.test.yaml
 ```
 
-### analyze and transform [examples](./docs/example.md)
+The output of tests is printed on the console.
+
+See different ways to run the test command in the [test runner doc](./docs/testrunner.md#running-tests)
+
+## References 
+
+- [Example usage scenarios](./docs/examples.md)
+- [Test runner for YAML rules](./docs/testrunner.md)
 
 ## Code of Conduct
+
 Refer to Konveyor's Code of Conduct [here](https://github.com/konveyor/community/blob/main/CODE_OF_CONDUCT.md).