Skip to content

Commit

Permalink
✨ Add new command to run YAML tests (#166)
Browse files Browse the repository at this point in the history 
* ✨ move container utils to a package

Signed-off-by: Pranav Gaikwad <pgaikwad@redhat.com>

* ✨ add testing API and schemas

Signed-off-by: Pranav Gaikwad <pgaikwad@redhat.com>

* ✨ add test parser, runner and result printer

Signed-off-by: Pranav Gaikwad <pgaikwad@redhat.com>

* ✨ add examples

Signed-off-by: Pranav Gaikwad <pgaikwad@redhat.com>

* ✨ add test runner to CLI

Signed-off-by: Pranav Gaikwad <pgaikwad@redhat.com>

* 📓 update docs

Signed-off-by: Pranav Gaikwad <pgaikwad@redhat.com>

* 👻 dockerfile changes

Signed-off-by: Pranav Gaikwad <pgaikwad@redhat.com>

* address feedback

Signed-off-by: Pranav Gaikwad <pgaikwad@redhat.com>

* 👻 use tab printer

Signed-off-by: Pranav Gaikwad <pgaikwad@redhat.com>

---------

Signed-off-by: Pranav Gaikwad <pgaikwad@redhat.com>
  • Loading branch information
@pranavgaikwad
pranavgaikwad committed Mar 18, 2024
1 parent 483bb01 commit 8cbeb54
Show file tree
Hide file tree
Showing 48 changed files with 3,441 additions and 192 deletions.
7 changes: 6 additions & 1 deletion .github/workflows/testing.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
1 change: 1 addition & 0 deletions Dockerfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
236 changes: 105 additions & 131 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).
Loading

0 comments on commit 8cbeb54

Please sign in to comment.