feat!: refactor action to be CLI based

[Shurtu-gal]

Description

The PR changes the GitHub action from being just a generator to an all-in-one tool.

What's New:

• Introduced new commands: validate, convert, optimise.
• Enabled model generation by language.

Changes Made

• Removed all NodeJS files and dependencies from the GitHub Action.
• Refactored the action to expose the Command-Line Interface (CLI) functionality through the Docker container using a bash script.
• Introduced a Makefile to streamline and simplify the development process.
• Implemented a bash script that dynamically executes commands based on user inputs, transforming the action into a comprehensive interface for CLI operations.

Breaking Changes:

Previously, the parameter option was exclusive to template parameters. It has now been expanded to apply to all commands. Therefore, users must now add -p before template params for the same functionality.

Things left

• Update README
• Add tests to test various edge cases
• Write a test workflow for production tests
• Release 3.0
• Rename Repository.

Related issue(s)
Fixes #281

[github-actions]

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[derberg]

I have some questions about your decisions to do things in a specific way

config file

why did you decide to introduce a config file. You executed it perfectly, but is this really needed. In past I faced a similar design decision: should I do a config to allow multiple runs, or should I basically document how to have workflow with multiple steps that use the same action, and I choose to drop idea with config. Config adds a lot of additional maintenance effort, but also makes things harder to use. Also I think that when you look at the ecosystem of GitHub Actions, the general principle is to have a single run responsibility. Example: I have a workflow where I need to checkout 2 different repositories, and to do it, I have 2 separate steps, one to checkout repo A and one to checkout repo B - 2 separate steps, not one step with 2 checkouts. It makes future debugging much much easier, as you can clearly see what step failed.

so what I think is better workflow for any platform/devops team is when they can do:

    - name: Validating AsyncAPI document
      uses: docker://asyncapi/github-action-for-cli:3.0.0
      with:
        command: validate
        filepath: ./asyncapi.yml
    - name: Generate models
       uses: docker://asyncapi/github-action-for-cli:3.0.0
       with:
        command: generate
        language: typescript
        filepath: ./asyncapi.yml
    - name: Generating HTML
      uses: docker://asyncapi/github-action-for-cli:3.0.0
      with:
        command: generate
        filepath: ./asyncapi.yml
        template: @asyncapi/[email protected]
        output: generated-html

so you use the same action for 3 different outputs. You know what I mean? this is the best approach from someone running and debugging pipelines. And to configure anything, you only learn inputs and not inputs with config

also, in the past nobody ever requested to do a config approach.

and great stuff is that if we do above, then we will not do any breaking change except for action name change

below can still work. We can say that by default, if command is not provided, then we assume generate and rest will still work

    - name: Generating HTML from my AsyncAPI document
      uses: docker://asyncapi/github-action-for-generator:2.0.0 #always use latest tag as each is pushed to docker
      with:
        template: '@asyncapi/[email protected]'  #In case of template from npm, because of @ it must be in quotes
        filepath: docs/api/my-asyncapi.yml
        parameters: baseHref=/test-experiment/ sidebarOrganization=byTags #space separated list of key/values
        output: generated-html

and yeah, do not introduce input if it is not really needed, like type for example, if you can use other inputs, like template or language to identify if model or fromTemplate should be run - then do it. Simply validate and throw error when people use template and language at the same time. Also in docs simply clarify what these mean.

CLI version

I think we need to stick to approach that docker contains only one CLI version. With CI/CD pipelines it is all about speed, we cannot make pipeline run longer because CLI installation needs to take place first. So we for sure need to have latest there by default. If you really think cli_version is useful, like for testing pipelines with new cli without bumping version in action - then we need a script that basically removes latest and installs requested CLI version - but it also has to be documented, so people understand how that works

---

don't feel disappointed with my feedback - it is only design related, but the execution mate - docs and quality are 💯 ❤️

[Shurtu-gal]

I will take out the config approach and keep it simple. Same with cli_version too.

[derberg]

left few comments, well done 👏🏼

[Shurtu-gal]

@derberg README is also updated

[derberg]

left some comments

can you at least add commands: bundle, diff, and convert that have use case to be used in CI?

[Shurtu-gal]

@derberg The requested changes have been added.
Regarding sonarcloud hotspot, I had made the changes to fix it but it led to permission issues when making docker container for GitHub action as can be seen in the run here

[derberg]

@Shurtu-gal please bring back the user settings in dockerfile and simply silent sonar by adding https://github.com/asyncapi/cli/blob/master/.sonarcloud.properties file to this repo, just adjust it to ignore dockerfile, and add comment why we ignore it: that this docker file is for starting containers that should run only in GitHub Actions and no other environments, and running with security violation is ok

[Shurtu-gal]

Done @derberg.

[sonarqubecloud]

Quality Gate passed

Kudos, no new issues were introduced!

0 New issues
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud

[derberg]

works well on my side

because we know there is one potential breaking change in case of parameters field, and that -p needs to be used, I added ! to the title so we release this new version as new major

[derberg]

well done 👏🏼

[derberg]

/rtm

[derberg]

@allcontributors please add @Shurtu-gal for code,test,doc,ideas,maintainance

[allcontributors]

@derberg

I've put up a pull request to add @Shurtu-gal! 🎉