diff --git a/assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc b/assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc index 4132ce89..2726de40 100644 --- a/assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc +++ b/assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc @@ -18,20 +18,20 @@ endif::[] [role="_abstract"] To assess and prioritize migration and modernization efforts for applications written in different languages, analyze your applications by using the {ProductFullName} {CLINameTitle}. +{ProductShortName} CLI supports running source code and binary analysis by using `analyzer-lsp`. `analyzer-lsp` is a tool that evaluates rules by using language providers. + Depending on your scenario, you can use the {ProductShortName} CLI to perform the following actions: * Run the analysis against a single application. -* Run the analysis against multiple applications: -** In {ProductShortName} versions earlier than 7.1.0, you can enter a series of `--analyze` commands, each against an application and each generating a separate report. For more information, see xref:analyzing-single-app-wth-mta-cli_analyzing-applications-mta-cli[Running the {ProductShortName} {CLINameTitle} against an application]. -** In {ProductShortName} version 7.1.0 and later, you can use the `--bulk` option to analyze multiple applications at once and generate a single report. Note that this feature is a Developer Preview feature only. For more information, see xref:analyzing-multiple-apps-with-mta-cli_analyzing-applications-mta-cli[Analyzing multiple applications]. +* Run the analysis against multiple applications in either of the following ways: +** Enter a series of `--analyze` commands, each against an application and each generating a separate report. +** Use the `--bulk` option to analyze multiple applications at once and generate a single report. Note that this feature is a Developer Preview feature only. -[IMPORTANT] -==== -Starting from {ProductShortName} version 7.2.0, you can run the application analysis for Java applications in the containerless mode. Note that this option is set by default and is used automatically only if all requirements are met. For more information, see xref:running-the-containerless-mta-cli_analyzing-applications-mta-cli[Analyzing an application in the containerless mode]. - -However, if you want to analyze applications in languages other than Java or, for example, use xref:performing-transformation_cli-guide[transformation commands], you still need to use containers. -==== +* Run the analysis for Java applications in the containerless mode. Note that this option is set by default and is used automatically only if all requirements are met. ++ +However, if you want to analyze applications in languages other than Java or, for example, use transformation commands, you still need to use containers. +//// [NOTE] ==== The analysis output in the disconnected environment usually results in fewer incidents because a dependency analysis does not run accurately without access to Maven. @@ -47,6 +47,7 @@ include::topics/mta-cli/proc_running-the-containerless-mta-cli.adoc[leveloffset= include::topics/mta-cli/ref_mta-cli-analyze-flags.adoc[leveloffset=+1] + ifdef::parent-context-of-analyzing-applications-mta-cli[:context: {parent-context-of-analyzing-applications-mta-cli}] ifndef::parent-context-of-analyzing-applications-mta-cli[:!context:] diff --git a/assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc b/assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc index 00e39d51..f70503c1 100644 --- a/assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc +++ b/assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc @@ -24,13 +24,16 @@ You can perform the analysis in either of the following ways: * Overwrite the existing supported language provider with your own unsupported language provider, and then run the analysis on it. -IMPORTANT: Analyzing applications written in languages other than Java is only possible in container mode. You can use the containerless CLI only for Java applications. For more information, see xref:running-the-containerless-mta-cli_analyzing-applications-mta-cli[Analyzing an application in containerless mode]. +IMPORTANT: Analyzing applications written in languages other than Java is only possible in container mode. You can use the containerless CLI only for Java applications. include::topics/mta-cli/proc_analyze-selected-provider.adoc[leveloffset=+1] include::topics/mta-cli/proc_analyze-unsupported-provider.adoc[leveloffset=+1] +[role="_additional-resources"] +== Additional resources +* xref:running-the-containerless-mta-cli_analyzing-applications-mta-cli[Analyzing an application in containerless mode] ifdef::parent-context-of-analyzing-multi-language-applications[:context: {parent-context-of-analyzing-multi-language-applications}] ifndef::parent-context-of-analyzing-multi-language-applications[:!context:] diff --git a/assemblies/mta-install-title/assembly_red-hat-build-of-keycloak.adoc b/assemblies/mta-install-title/assembly_red-hat-build-of-keycloak.adoc index 3e6d368a..fb882e36 100644 --- a/assemblies/mta-install-title/assembly_red-hat-build-of-keycloak.adoc +++ b/assemblies/mta-install-title/assembly_red-hat-build-of-keycloak.adoc @@ -15,9 +15,9 @@ endif::[] :context: red-hat-build-of-keycloak [role="_abstract"] -Starting from version 7.3.0, the {ProductFullName} uses a link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0[Red Hat build of Keycloak (RHBK)] instance for user authentication and authorization. A RHBK instance is installed during the installation of the {ProductShortName} user interface. The {ProductShortName} Operator manages the RHBK instance and configures a dedicated realm with necessary roles and permissions. +The {ProductFullName} uses a Red Hat build of Keycloak (RHBK) instance for user authentication and authorization. A RHBK instance is installed during the installation of the {ProductShortName} user interface. The {ProductShortName} Operator manages the RHBK instance and configures a dedicated realm with necessary roles and permissions. -You can use the {ProductShortName}-managed RHBK instance to perform advanced RHBK configurations, such as link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/server_administration_guide/user-storage-federation#adding_a_provider[adding a provider for User Federation] or link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/server_administration_guide/identity_broker[integrating identity providers]. +You can use the {ProductShortName}-managed RHBK instance to perform advanced RHBK configurations, such as adding a provider for User Federation or integrating identity providers. include::topics/mta-install/proc_accessing-rhbk-admin-console.adoc[leveloffset=+1] diff --git a/assemblies/rules-development-guide/assembly_rule-rulesets.adoc b/assemblies/rules-development-guide/assembly_rule-rulesets.adoc index ee50eda5..c38b42fc 100644 --- a/assemblies/rules-development-guide/assembly_rule-rulesets.adoc +++ b/assemblies/rules-development-guide/assembly_rule-rulesets.adoc @@ -23,8 +23,6 @@ To use multiple rule files, you can either: * Place the rule files in a directory and add a ruleset.yaml file. {ProductShortName} treats the directory as a ruleset, and you can pass the directory path as input to the `--rules` option. * Specify multiple rules files by using the `--rules` option when you run an analysis. -Note that if you want to use the `--target` or `--source` option in the CLI, the engine will only select rules that match the label for that target. Therefore, make sure that you have added target or source labels on your rules. See xref:reserved-label_rule-yaml-metadata[Reserved labels] for more details. - include::topics/rules-development/yaml-rulesets.adoc[leveloffset=+1] ifdef::parent-context-of-rule-rulesets[:context: {parent-context-of-rule-rulesets}] diff --git a/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc b/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc index affced39..9dfb9219 100644 --- a/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc +++ b/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc @@ -20,8 +20,9 @@ You can use rule actions to generate information about the source code. The rule Rules can include the following types of actions: -* `Message`: use message action to display an informative message in the static report that contains the violation triggered by the rule. See xref:yaml-message-actions_rule-yaml-actions[Message action] for more information. -* `Tag`: use tags to categorize parts of the source code. For example, Backend=Java, where Backend is the key and Java is the value. See xref:yaml-tag-actions_rule-yaml-actions[Tag actions] for more information. +* `Message`: use message action to display an informative message in the static report that contains the violation triggered by the rule. +* `Tag`: use tags to categorize parts of the source code. For example, Backend=Java, where Backend is the key and Java is the value. + Each rule includes either one of them or both of them. include::topics/rules-development/yaml-tag-actions.adoc[leveloffset=+1] diff --git a/assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc b/assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc index b04b6456..d2badc29 100644 --- a/assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc +++ b/assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc @@ -32,17 +32,7 @@ Currently, {ProductShortName} supports the following providers: You can use the generic provider binary to create an external provider for any language that is compliant with link:https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/[LSP 3.17 specifications]. ==== -== Using the provider capability in custom rules - -In a rule, the when block is where the conditions for matching the rule are specified. Each provider offers a series of capabilities to do matching. The search query in the rule condition can contain patterns, code locations, specific dependencies to be found, and so on, to evaluate the source code and dependencies. The provider sends the LSP server a request to check the search query against the application being analyzed. When the LSP server returns a match for the search in the source code, the analyzer triggers a violation. - -The `when` block has one condition, but that condition can have multiple conditions nested under it. - ----- -when: - - ----- +include::topics/rules-development/con_provider-capability-in-custom-rules.adoc[leveloffset=+1] include::topics/rules-development/yaml-provider-conditions.adoc[leveloffset=+1] diff --git a/assemblies/rules-development-guide/assembly_rules-introduction.adoc b/assemblies/rules-development-guide/assembly_rules-introduction.adoc index f6a7328b..d4854088 100644 --- a/assemblies/rules-development-guide/assembly_rules-introduction.adoc +++ b/assemblies/rules-development-guide/assembly_rules-introduction.adoc @@ -18,8 +18,6 @@ endif::[] [role="_abstract"] This guide is intended for software engineers who want to create custom YAML-based rules for {ProductName} ({ProductShortName}) tools. -See the link:{ProductDocIntroToMTAGuideURL}[_{IntroToMTABookName}_] for an overview and the link:{ProductDocUserGuideURL}[_{UserCLIBookName}_] for details. - include::topics/rules-development/about-rules.adoc[leveloffset=+1] include::topics/rules-development/yaml-rule-structure-syntax.adoc[leveloffset=+1] diff --git a/assemblies/ui-guide/assembly_assessment-questionnaires.adoc b/assemblies/ui-guide/assembly_assessment-questionnaires.adoc index 314e52f2..7c2a5d16 100644 --- a/assemblies/ui-guide/assembly_assessment-questionnaires.adoc +++ b/assemblies/ui-guide/assembly_assessment-questionnaires.adoc @@ -15,7 +15,7 @@ endif::[] :context: assessment-questionnaires [role="_abstract"] -To determine the readiness of your portfolio for modernization, use assessment questionnaires to provide the {ProductFullName} user interface (UI) with the details required for the migration process. The {ProductFullName} uses either xref:mta-default-questionnaire_assessment-questionnaires[default] or xref:mta-custom-questionnaire_assessment-questionnaires[custom] assessment questionnaire. +To determine the readiness of your portfolio for modernization, use assessment questionnaires to provide the {ProductFullName} user interface (UI) with the details required for the migration process. The {ProductFullName} uses either the default questionnaire or a custom assessment questionnaire. include::topics/mta-ui/con_mta-default-questionnaire.adoc[leveloffset=+1] diff --git a/assemblies/ui-guide/assembly_configuring-mta-instance-environment.adoc b/assemblies/ui-guide/assembly_configuring-mta-instance-environment.adoc index b6930a32..5a809e30 100644 --- a/assemblies/ui-guide/assembly_configuring-mta-instance-environment.adoc +++ b/assemblies/ui-guide/assembly_configuring-mta-instance-environment.adoc @@ -40,11 +40,6 @@ include::topics/mta-ui/proc_configuring-proxy-settings.adoc[leveloffset=+1] include::topics/mta-ui/proc_creating-custom-migration-targets.adoc[leveloffset=+1] -== Next steps - -* xref:configuring-mta-instance_user-interface-guide[Configure a {ProductName} instance]. - - ifdef::parent-context-of-configuring-mta-instance-environment[:context: {parent-context-of-configuring-mta-instance-environment}] ifndef::parent-context-of-configuring-mta-instance-environment[:!context:] diff --git a/assemblies/ui-guide/assembly_tagging-applications.adoc b/assemblies/ui-guide/assembly_tagging-applications.adoc index ad8256c2..74aad213 100644 --- a/assemblies/ui-guide/assembly_tagging-applications.adoc +++ b/assemblies/ui-guide/assembly_tagging-applications.adoc @@ -15,9 +15,9 @@ endif::[] :context: tagging-applications [role="_abstract"] -To classify applications and instantly identify application information, for example, an application type, data center location, and technologies used within the application, attach tags to applications in the {ProductFullName} user interface (UI). You can also use tagging to associate xref:working-with-archetypes_user-interface-guide[archetypes] to applications for automatic assessment. +To classify applications and instantly identify application information, for example, an application type, data center location, and technologies used within the application, attach tags to applications in the {ProductFullName} user interface (UI). You can also use tagging to associate archetypes to applications for automatic assessment. -You can either set an xref:automatic-tagging-of-an-application_tagging-applications[automated] tagging or tag applications xref:manual-tagging-of-an-application_tagging-applications[manually]. +You can either use automated tagging or tag applications manually. NOTE: Not all tags can be assigned automatically. For example, an analysis can only tag the application based on its technologies. If you want to tag the application also with the location of the data center where it is deployed, you need to tag the application manually. diff --git a/docs/topics/about-home-var.adoc b/docs/topics/about-home-var.adoc deleted file mode 100644 index 7dc41c8d..00000000 --- a/docs/topics/about-home-var.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/rules-development-guide/master.adoc - -:_content-type: CONCEPT -[id="about-home-var_{context}"] -= Use of `<{ProductShortName}_HOME>` in this guide - -This guide uses the `<{ProductShortName}_HOME>` replaceable variable to denote the path to your {ProductShortName} installation. The installation directory is the `{ProductDistribution}` directory where you extracted the {ProductShortName} `.zip` file. - -When you encounter `<{ProductShortName}_HOME>` in this guide, replace it with the actual path to your {ProductShortName} installation. diff --git a/docs/topics/available-openrewrite-recipes.adoc b/docs/topics/available-openrewrite-recipes.adoc deleted file mode 100644 index b1832efe..00000000 --- a/docs/topics/available-openrewrite-recipes.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following module: -// -// * docs/cli-guide-mtr/master.adoc -// * docs/cli-guide/master.adoc - -[id=available-openrewrite-recipes_{context}] -= Available OpenRewrite recipes - -.Available OpenRewrite recipes -[cols="22%,26%,26%,26%", options="header"] -|==== -|Migration path -|Purpose -|rewrite.configLocation -|activeRecipes - -|Java EE to Jakarta EE -|Replace import of `javax` packages with equivalent `jakarta` packages - -Replace `javax` artifacts, declared within `pom.xml` files, with the `jakarta` equivalents - -|`<{ProductShortName}_HOME>/rules/openrewrite/jakarta \ /javax/imports/rewrite.yml` -|`org.jboss.windup.JavaxToJakarta` - -|Java EE to Jakarta EE -|Rename bootstrapping files -|`<{ProductShortName}_HOME>/rules/openrewrite/jakarta \ /javax/bootstrapping/rewrite.yml` -|`org.jboss.windup.jakarta.javax. \ BootstrappingFiles` - -|Java EE to Jakarta EE -|Transform `persistence.xml` configuration -|`<{ProductShortName}_HOME>/rules/openrewrite/jakarta \ /javax/xml/rewrite.yml` -|`org.jboss.windup.javax-jakarta. \ PersistenceXML` - -|Spring Boot to Quarkus -|Replace `spring.jpa.hibernate.ddl-auto` property within files matching `application*.properties` -|`<{ProductShortName}_HOME>/rules/openrewrite/quarkus \ /springboot/properties/rewrite.yml` -|`org.jboss.windup.sb-quarkus.Properties` -|==== diff --git a/docs/topics/cli-args.adoc b/docs/topics/cli-args.adoc deleted file mode 100644 index 7ce82c09..00000000 --- a/docs/topics/cli-args.adoc +++ /dev/null @@ -1,210 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/cli-guide/master.adoc - -:_content-type: REFERENCE -[id="cli-args_{context}"] -= About {ProductShortName} command-line arguments - -The following is a detailed description of the available {ProductShortName} command line arguments. - -[NOTE] -==== -To run the {ProductShortName} command without prompting, for example when executing from a script, you must use the following arguments: - -* `--batchMode` -* `--overwrite` -* `--input` -* `--target` -==== - -.{ProductShortName} CLI arguments -[cols="40%,60%a",options="header",] -|==== -|Argument |Description -|--additionalClassPath |A space-delimited list of additional JAR files or directories to add to the class path so that they are available for decompilation or other analysis. -|--addonDir |Add the specified directory as a custom add-on repository. -|--analyzeKnownLibraries | Flag to analyze known software artifacts embedded within your application. By default, {ProductShortName} only analyzes application code. - -[NOTE] -==== -This option may result in a longer execution time and a large number of migration issues being reported. -==== - -|--batchMode |Flag to specify that {ProductShortName} should be run in a non-interactive mode without prompting for confirmation. This mode takes the default values for any parameters not passed in to the command line. -|--debug |Flag to run {ProductShortName} in debug mode. -|--disableTattletale | Flag to disable generation of the Tattletale report. If both `enableTattletale` and `disableTattletale` are set to true, then `disableTattletale` will be ignored and the Tattletale report will still be generated. -|--discoverPackages |Flag to list all available packages in the input binary application. -|--enableClassNotFoundAnalysis |Flag to enable analysis of Java files that are not available on the class path. This should not be used if some classes will be unavailable at analysis time. -|--enableCompatibleFilesReport |Flag to enable generation of the Compatible Files report. Due to processing all files without found issues, this report may take a long time for large applications. -|--enableTattletale |Flag to enable generation of a Tattletale report for each application. This option is enabled by default when `eap` is in the included target. If both `enableTattletale` and `disableTattletale` are set to true, then `disableTattletale` will be ignored and the Tattletale report will still be generated. -|--enableTransactionAnalysis |[Technology Preview] Flag to enable generation of a Transactions report that displays the call stack, which executes operations on relational database tables. The Enable Transaction Analysis feature supports Spring Data JPA and the traditional `preparedStatement()` method for SQL statement execution. It does not support ORM frameworks, such as Hibernate. - -[NOTE] -==== -enableTransactionAnalysis is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them -in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. -==== - -|--excludePackages |A space-delimited list of packages to exclude from evaluation. For example, entering `com.mycompany.commonutilities` excludes all classes whose package names begin with `com.mycompany.commonutilities`. -|--excludeTags |A space-delimited list of tags to exclude. When specified, rules with these tags will not be processed. To see the full list of tags, use the `--listTags` argument. -|--explodedApp |Flag to indicate that the provided input directory contains source files for a single application. -|--exportCSV |Flag to export the report data to a CSV file on your local file system. {ProductShortName} creates the file in the directory specified by the `--output` argument. The CSV file can be imported into a spreadsheet program for data manipulation and analysis. -|--exportSummary |Flag to instruct {ProductShortName} to generate an `analysisSummary.json` export file in the output directory. The file contains analysis summary information for each application analyzed, including the number of incidents and story points by category, and all of the technology tags associated with the analyzed applications. -|--exportZipReport |This argument creates a `reports.zip` file in the output folder. The file contains the analysis output, typically, the reports. If requested, it can also contain the CSV export files. -|--help |Display the {ProductShortName} help message. -|--immutableAddonDir |Add the specified directory as a custom read-only add-on repository. -|--includeTags| A space-delimited list of tags to use. When specified, only rules with these tags will be processed. To see the full list of tags, use the `--listTags` argument. -|--input |A space-delimited list of the path to the file or directory containing one or more applications to be analyzed. This argument is required. -|--install |Specify add-ons to install. The syntax is `:[:]`. For example, `--install core-addon-x` or `--install org.example.addon:example:1.0.0`. -|--keepWorkDirs| Flag to instruct {ProductShortName} to not delete temporary working files, such as the graph database and extracted archive files. This is useful for debugging purposes. -|--legacyReports| Flag to instruct {ProductShortName} to generate the old format reports instead of the new format reports. -|--list| Flag to list installed add-ons. -|--listSourceTechnologies| Flag to list all available source technologies. -|--listTags| Flag to list all available tags. -|--listTargetTechnologies| Flag to list all available target technologies. -|--mavenize| Flag to create a Maven project directory structure based on the structure and content of the application. This creates `pom.xml` files using the appropriate Java EE API and the correct dependencies between project modules. See also the `--mavenizeGroupId` option. -|--mavenizeGroupId| When used with the `--mavenize` option, all generated `pom.xml` files will use the provided value for their ``. If this argument is omitted, {ProductShortName} will attempt to determine an appropriate `` based on the application, or will default to `com.mycompany.mavenized`. -|--online |Flag to allow network access for features that require it. Currently only validating XML schemas against external resources relies on Internet access. Note that this comes with a performance penalty. -|--output |Specify the path to the directory to output the report information generated by {ProductShortName}. -|--overwrite |Flag to force delete the existing output directory specified by `--output`. If you do not specify this argument and the `--output` directory exists, you are prompted to choose whether to overwrite the contents. - -[IMPORTANT] -==== -Do not overwrite a report output directory that contains important information. -==== - -|--packages| A space-delimited list of the packages to be evaluated by {ProductShortName}. It is highly recommended to use this argument. -|--remove |Remove the specified add-ons. The syntax is `:[:]`. For example, `--remove core-addon-x` or `--remove org.example.addon:example:1.0.0`. -|--skipReports |Flag to indicate that HTML reports should not be generated. A common use of this argument is when exporting report data to a CSV file using `--exportCSV`. -|--source |A space-delimited list of one or more source technologies, servers, platforms, or frameworks to migrate from. This argument, in conjunction with the `--target` argument, helps to determine which rulesets are used. Use the `--listSourceTechnologies` argument to list all available sources. -|--sourceMode |Flag to indicate that the application to be evaluated contains source files rather than compiled binaries. The sourceMode argument has been deprecated. There is no longer the need to specify it. {ProductShortName} can intuitively process any inputs that are presented to it. In addition, project source folders can be analyzed with binary inputs within the same analysis execution. -|--target |A space-delimited list of one or more target technologies, servers, platforms, or frameworks to migrate to. This argument, in conjunction with the `--source` argument, helps to determine which rulesets are used. Use the `--listTargetTechnologies` argument to list all available targets. -|--userIgnorePath |Specify a location, in addition to `${user.home}/.{LC_PSN}/ignore/`, for {ProductShortName} to identify files that should be ignored. -|--userLabelsDirectory |Specify a location for {ProductShortName} to look for custom Target Runtime Labels. The value can be a directory containing label files or a single label file. The Target Runtime Label files must use the [x-]`.windup.label.xml` suffix. The shipped Target Runtime Labels are defined within `${ProductShortName}_HOME/rules/migration-core/core.windup.label.xml`. -|--userRulesDirectory |Specify a location, in addition to `<{ProductShortName}_HOME>/rules/` and `${user.home}/.{LC_PSN}/rules/`, for {ProductShortName} to look for custom {ProductShortName} rules. The value can be a directory containing ruleset files or a single ruleset file. The ruleset files must use the [x-]`.windup.xml` suffix. -|--version |Display the {ProductShortName} version. -|--skipSourceCodeReports |This option skips generating a _Source code report_ when generating the application analysis report. Use this advanced option when concerned about source code information appearing in the application analysis. -|==== - -[id="cli-input-argument_{context}"] -== Specifying the input - -A space-delimited list of the path to the file or directory containing one or more applications to be analyzed. This argument is required. - -.Usage -[source,options="nowrap",subs="attributes+"] ----- ---input [...] ----- - -[id="cli-input-file-type-arguments_{context}"] - -Depending on whether the input file type provided to the `--input` argument is a file or directory, it will be evaluated as follows depending on the additional arguments provided. - -Directory:: -+ -[cols="1,1,1",options="header"] -|==== -| --explodedApp -| --sourceMode -| Neither Argument - -| The directory is evaluated as a single application. -| The directory is evaluated as a single application. -| Each subdirectory is evaluated as an application. -|==== - -File:: -+ -[cols="1,1,1",options="header"] -|==== -| --explodedApp -| --sourceMode -| Neither Argument - -| Argument is ignored; the file is evaluated as a single application. -| The file is evaluated as a compressed project. -| The file is evaluated as a single application. -|==== - -[id="cli-output-argument_{context}"] -== Specifying the output directory - -Specify the path to the directory to output the report information generated by {ProductShortName}. - -.Usage -[source,options="nowrap",subs="attributes+"] ----- ---output ----- - -* If omitted, the report will be generated in an `.report` directory. -* If the output directory exists, you will be prompted with the following (with a default of N). -+ -[source,options="nowrap",subs="attributes+"] ----- -Overwrite all contents of "/home/username/" (anything already in the directory will be deleted)? [y,N] ----- - -However, if you specify the `--overwrite` argument, {ProductShortName} will proceed to delete and recreate the directory. See the description of this argument for more information. - -[id="cli-source-argument_{context}"] -== Setting the source technology - -A space-delimited list of one or more source technologies, servers, platforms, or frameworks to migrate from. This argument, in conjunction with the `--target` argument, helps to determine which rulesets are used. Use the `--listSourceTechnologies` argument to list all available sources. - -.Usage -[source,options="nowrap",subs="attributes+"] ----- ---source ----- - -The `--source` argument now provides version support, which follows the link:http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html[Maven version range syntax]. This instructs {ProductShortName} to only run the rulesets matching the specified versions. For example, `--source eap:5`. - -[WARNING] -==== -When migrating to JBoss EAP, be sure to specify the version, for example, `eap:6`. Specifying only `eap` will run rulesets for all versions of JBoss EAP, including those not relevant to your migration path. - -See link:{ProductDocIntroToMTAGuideURL}/index#migration_paths_getting-started-guide[Supported migration paths] in _{IntroToMTABookName}_ for the appropriate JBoss EAP version. -==== - -[id="cli-target-argument_{context}"] -== Setting the target technology - -A space-delimited list of one or more target technologies, servers, platforms, or frameworks to migrate to. This argument, in conjunction with the `--source` argument, helps to determine which rulesets are used. If you do not specify this option, you are prompted to select a target. Use the `--listTargetTechnologies` argument to list all available targets. - -.Usage -[source,options="nowrap",subs="attributes+"] ----- ---target ----- - - -The `--target` argument now provides version support, which follows the link:http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html[Maven version range syntax]. This instructs {ProductShortName} to only run the rulesets matching the specified versions. For example, `--target eap:7`. - -[WARNING] -==== -When migrating to JBoss EAP, be sure to specify the version in the target, for example, `eap:6`. Specifying only `eap` will run rulesets for all versions of JBoss EAP, including those not relevant to your migration path. - -See link:{ProductDocIntroToMTAGuideURL}/index#migration_paths_getting-started-guide[Supported migration paths] in _{IntroToMTABookName}_ for the appropriate JBoss EAP version. -==== - -[id="cli-packages-argument_{context}"] -== Selecting packages - -A space-delimited list of the packages to be evaluated by {ProductShortName}. It is highly recommended to use this argument. - -.Usage -[source,options="nowrap",subs="attributes+"] ----- ---packages ----- - -* In most cases, you are interested only in evaluating custom application class packages and not standard Java EE or third party packages. The `` argument is a package prefix; all subpackages will be scanned. For example, to scan the packages `com.mycustomapp` and `com.myotherapp`, use `--packages com.mycustomapp com.myotherapp` argument on the command line. -* While you can provide package names for standard Java EE third party software like `org.apache`, it is usually best not to include them as they should not impact the migration effort. - -[WARNING] -==== -If you omit the `--packages` argument, every package in the application is scanned, which can impact performance. -==== diff --git a/docs/topics/developer-preview-feature.adoc b/docs/topics/developer-preview-feature.adoc deleted file mode 100644 index 84e70cfd..00000000 --- a/docs/topics/developer-preview-feature.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// DO NOT USE THIS SNIPPET. DEVELOPER PREVIEW FEATURES ARE NOT DOCUMENTED IN CORE OPENSHIFT DOCS. - -// When including this file, ensure that {FeatureName} is set immediately before the include. Otherwise it will result in an incorrect replacement. - -[IMPORTANT] -==== -[subs="attributes+"] -{FeatureName} is a Developer Preview feature only. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to upcoming product features in advance of their possible inclusion in a Red Hat product offering, enabling customers to test functionality and provide feedback during the development process. These features might not have any documentation, are subject to change or removal at any time, and testing is limited. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. -==== -// Undefine {FeatureName} attribute, so that any mistakes are easily spotted -:!FeatureName: diff --git a/docs/topics/fork-ruleset-repo.adoc b/docs/topics/fork-ruleset-repo.adoc deleted file mode 100644 index bf4ef9ab..00000000 --- a/docs/topics/fork-ruleset-repo.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/rules-development-guide/master.adoc - -:_content-type: PROCEDURE -[id="fork-ruleset-repo_{context}"] -= Forking and cloning the {ProductName} XML rules - -The {ProductName} `windup-rulesets` repository provides working examples of how to create custom Java-based rule add-ons and XML rules. You can use them as a starting point for creating your own custom rules. - -You must have the link:http://git-scm.com/[`git`] client installed on your machine. - -. Click the `Fork` link on the https://github.com/windup/windup-rulesets/[{ProductName} Rulesets] GitHub page to create the project in your own Git. The forked GitHub repository URL created by the fork should look like this: `\https://github.com//windup-rulesets.git`. -. Clone your {ProductName} rulesets repository to your local file system: -+ -[options="nowrap",subs="attributes+"] ----- -$ git clone https://github.com//windup-rulesets.git ----- -. This creates and populates a `windup-rulesets` directory on your local file system. Navigate to the newly created directory, for example -+ -[options="nowrap"] ----- -$ cd windup-rulesets/ ----- -. If you want to be able to retrieve the latest code updates, add the remote `upstream` repository so you can fetch any changes to the original forked repository. -+ -[options="nowrap"] ----- -$ git remote add upstream https://github.com/windup/windup-rulesets.git ----- -. Get the latest files from the `upstream` repository. -+ -[options="nowrap"] ----- -$ git fetch upstream ----- diff --git a/docs/topics/mta-cli/ref_contributing-to-mta-development.adoc b/docs/topics/mta-cli/ref_contributing-to-mta-development.adoc index f958d6a5..72d6414b 100644 --- a/docs/topics/mta-cli/ref_contributing-to-mta-development.adoc +++ b/docs/topics/mta-cli/ref_contributing-to-mta-development.adoc @@ -22,7 +22,7 @@ You can help with any of the following items: ** Write a {ProductName} rule to identify or automate a migration process. ** Create a test for the new rule. + -For more information, see link:{ProductDocRulesGuideURL}[_{RulesDevBookName}_]. +For more information, see link:{mta-URL}/configuring_and_using_rules_for_an_mta_analysis/index[Configuring and using rules for an MTA analysis]. * Contribute to the project source code: ** Create a core rule. ** Improve {ProductShortName} performance or efficiency. diff --git a/docs/topics/mta-install/con_mta-features.adoc b/docs/topics/mta-install/con_mta-features.adoc index 015e22ff..2851df89 100644 --- a/docs/topics/mta-install/con_mta-features.adoc +++ b/docs/topics/mta-install/con_mta-features.adoc @@ -13,7 +13,7 @@ The {ProductFullName} includes many features that simplify upgrades with multipl * *Application inventory and assessment modules* to help organizations assess applications' suitability for deployment in containers, including flagging potential risks for migration strategies. * *Integration with source code and binary repositories* to automate the applications' retrieval for analysis, along with proxy integration, including HTTP and HTTPS proxy configuration managed in the user interface. * *Improved analysis capabilities* with different analysis modes, including source and dependency modes. These modes parse repositories to gather dependencies and add these dependencies to the scope of the analysis. You can also use a simplified user experience to configure the analysis scope, including open source libraries. -* *Enhanced role-based access control (RBAC)* powered by link:https://access.redhat.com/products/red-hat-build-of-keycloak[Red Hat build of Keycloak] to define the following personas: +* *Enhanced role-based access control (RBAC)* powered by Red Hat build of Keycloak to define the following personas: ** Administrator ** Architect ** Migrator @@ -23,4 +23,9 @@ These personas have different permissions to suit the needs of each user, includ * *Administration perspective* for administrators to manage tool-wide configuration. * *Support for Red Hat OpenShift on AWS (ROSA)* * *Support for Azure Red Hat OpenShift (ARO)* -* *Support for analyzing applications written in different languages* \ No newline at end of file +* *Support for analyzing applications written in different languages* + + +[role="_additional-resources"] +.Additional resources +* link:https://access.redhat.com/products/red-hat-build-of-keycloak[Red Hat build of Keycloak] \ No newline at end of file diff --git a/docs/topics/mta-install/con_mta-rules.adoc b/docs/topics/mta-install/con_mta-rules.adoc index 6454d64a..c2215a5d 100644 --- a/docs/topics/mta-install/con_mta-rules.adoc +++ b/docs/topics/mta-install/con_mta-rules.adoc @@ -32,6 +32,9 @@ pass:[] [NOTE] ==== You can create your own custom analyzer rules. You can use custom rules to identify the use of custom libraries or other components that the provided standard migration rules might not cover. +==== + -For instructions on how to write custom rules, see link:{mta-URL}/configuring_and_using_rules_for_an_mta_analysis/index[Configuring and using rules for an MTA analysis]. -==== \ No newline at end of file +[role="_additional-resources"] +.Additional resources +link:{mta-URL}/configuring_and_using_rules_for_an_mta_analysis/index[Configuring and using rules for an MTA analysis] \ No newline at end of file diff --git a/docs/topics/mta-install/con_mta-tools.adoc b/docs/topics/mta-install/con_mta-tools.adoc index 5df9c688..dcf32f9d 100644 --- a/docs/topics/mta-install/con_mta-tools.adoc +++ b/docs/topics/mta-install/con_mta-tools.adoc @@ -17,20 +17,13 @@ By using the user interface for the {ProductName}, you can perform the following ** Assess the risks involved in containerizing an application for hybrid cloud environments on Red Hat OpenShift. ** Analyze the changes that you might need to apply to the code of an application to containerize this application. -+ -For more information about using the MTA user interface, see link:{mta-URL}/configuring_and_managing_the_migration_toolkit_for_applications_user_interface/index[Configuring and managing the {ProductName} user interface]. - * *Command-line interface (CLI)* + The CLI is a command-line tool in the {ProductName} that you can use to assess migration and modernization efforts for applications. It provides reports that highlight the analysis without using the other tools. The CLI includes a wide array of customization options. By using the CLI, you can tune {ProductShortName} analysis options or integrate with external automation tools. -+ -For more information about using the CLI, see link:{mta-URL}/using_the_migration_toolkit_for_applications_command-line_interface/index[Using the {ProductName} command-line interface]. * *{ProductFirstRef} ({ProductShortName}) Operator* + By using the {ProductShortName} Operator, you can install the user interface on OpenShift Container Platform. -+ -For more information about the prerequisites for the MTA Operator installation, see link:https://access.redhat.com/support/policy/updates/openshift_operators[OpenShift Operator Life Cycles]. * *IDE add-ons* + @@ -49,11 +42,12 @@ You can use these add-ons to perform the following tasks: ** Use the automatic code replacement, if possible -+ -For more information about using add-ons, see the following documentation: - -// ** link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/7.3/html/eclipse_plugin_guide/index[Eclipse Plugin Guide] -** link:{mta-URL}/intellij_idea_plugin_guide/index[IntelliJ IDEA Plugin Guide] -** link:{mta-URL}/configuring_and_using_the_visual_studio_code_extension_for_mta/index[Configuring and using the Visual Studio Code Extension for {ProductShortName}] +[role="_additional-resources"] +.Additional resources +* link:{mta-URL}/configuring_and_managing_the_migration_toolkit_for_applications_user_interface/index[Configuring and managing the {ProductName} user interface]. +* link:{mta-URL}/using_the_migration_toolkit_for_applications_command-line_interface/index[Using the {ProductName} command-line interface] +* link:https://access.redhat.com/support/policy/updates/openshift_operators[OpenShift Operator Life Cycles] +* link:{mta-URL}/intellij_idea_plugin_guide/index[IntelliJ IDEA Plugin Guide] +* link:{mta-URL}/configuring_and_using_the_visual_studio_code_extension_for_mta/index[Configuring and using the Visual Studio Code Extension for {ProductShortName}] diff --git a/docs/topics/mta-install/proc_accessing-rhbk-admin-console.adoc b/docs/topics/mta-install/proc_accessing-rhbk-admin-console.adoc index 045a4145..419eaeef 100644 --- a/docs/topics/mta-install/proc_accessing-rhbk-admin-console.adoc +++ b/docs/topics/mta-install/proc_accessing-rhbk-admin-console.adoc @@ -30,6 +30,7 @@ https://__/auth/admin [role="_additional-resources"] .Additional resources +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0[Red Hat build of Keycloak] * link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/server_administration_guide/user-storage-federation#ldap[Configuring LDAP and Active Directory in RHBK] * link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/server_administration_guide/red_hat_build_of_keycloak_features_and_concepts[Red Hat build of Keycloak features and concepts] diff --git a/docs/topics/mta-install/proc_installing-cli-for-docker.adoc b/docs/topics/mta-install/proc_installing-cli-for-docker.adoc index 32a5daf1..0b9b50e3 100644 --- a/docs/topics/mta-install/proc_installing-cli-for-docker.adoc +++ b/docs/topics/mta-install/proc_installing-cli-for-docker.adoc @@ -14,7 +14,7 @@ To install the {ProductShortName} CLI for use with Docker on Windows, you must c * You have a host with 64-bit Windows 11, version 21H2 or later. -* You downloaded the Docker Desktop for Windows installation program. For more details, see link:https://docs.docker.com/desktop/install/windows-install/[Install Docker Desktop on Windows]. +* You downloaded the Docker Desktop for Windows installation program. .Procedure @@ -117,3 +117,6 @@ PS C:\Users\> *$env:DOTNET_PROVIDER_IMG="quay.io/konveyor/dotnet-exte PS C:\Users\> *$env:RUNNER_IMG="quay.io/konveyor/kantra:v0.5.0"* ---- +[role="_additional-resources"] +.Additional resources +* link:https://docs.docker.com/desktop/install/windows-install/[Install Docker Desktop on Windows] diff --git a/docs/topics/mta-install/proc_installing-cli-zip.adoc b/docs/topics/mta-install/proc_installing-cli-zip.adoc index 55c72f7a..71715f3d 100644 --- a/docs/topics/mta-install/proc_installing-cli-zip.adoc +++ b/docs/topics/mta-install/proc_installing-cli-zip.adoc @@ -8,16 +8,19 @@ [role="_abstract"] You can use the {ProductFullName} command-line interface (CLI) to assess and analyze your applications to prepare these applications for the migration. -You can install the {ProductShortName} CLI by using the downloadable `.zip` file available on the link:https://developers.redhat.com/products/mta/download[official {ProductShortName} download page]. +You can install the {ProductShortName} CLI by using the downloadable `.zip` file available on the official {ProductShortName} download page. .Prerequisites -* You logged in to `registry.redhat.io`. For more details, see link:https://access.redhat.com/RegistryAuthentication[Red Hat Container Registry Authentication]. +* You logged in to `registry.redhat.io`. + +[NOTE] +==== pass:[] -NOTE: This prerequisite is not applicable for the containerless mode. -pass:[] For more information, see link:{mta-URL}/using_the_migration_toolkit_for_applications_command-line_interface/analyzing-applications-mta-cli_cli-guide#running-the-containerless-mta-cli_analyzing-applications-mta-cli[Analyzing an application in containerless mode]. +This prerequisite is not applicable for the containerless mode. +pass:[] +==== * You installed Java Development Kit (JDK) version 17 or later. * You set the `JAVA_HOME` environment variable. @@ -41,3 +44,9 @@ pass:[] For more information, see link:{mta-U + NOTE: You can place the `mta-cli` binary in any folder that included in the `$PATH` variable. You can also add a folder that contains `mta-cli` to `$PATH`. This way, you do not need to specify a full path when using the CLI. + + +[role="_additional-resources"] +.Additional resources +* link:https://access.redhat.com/RegistryAuthentication[Red Hat Container Registry Authentication] +* link:{mta-URL}/using_the_migration_toolkit_for_applications_command-line_interface/analyzing-applications-mta-cli_cli-guide#running-the-containerless-mta-cli_analyzing-applications-mta-cli[Analyzing an application in containerless mode] diff --git a/docs/topics/mta-install/ref_persistent-volume-requirements.adoc b/docs/topics/mta-install/ref_persistent-volume-requirements.adoc index 4609a468..6488c9a4 100644 --- a/docs/topics/mta-install/ref_persistent-volume-requirements.adoc +++ b/docs/topics/mta-install/ref_persistent-volume-requirements.adoc @@ -41,7 +41,7 @@ pass:[] |RWX |Maven m2 cache required if the `rwx_supported` configuration option is set to `true`. -|`kai-db` database +|`kai-db` |`5Gi` |RWO |{mta-dl-plugin} database required to run an AI-assisted code resolution. diff --git a/docs/topics/mta-intellij-plugin/what-is-the-toolkit.adoc b/docs/topics/mta-intellij-plugin/what-is-the-toolkit.adoc index 1458f553..a3e15c27 100644 --- a/docs/topics/mta-intellij-plugin/what-is-the-toolkit.adoc +++ b/docs/topics/mta-intellij-plugin/what-is-the-toolkit.adoc @@ -33,16 +33,14 @@ The {ProductName} ({ProductShortName}) is an extensible and customizable rule-ba * Migrating JBoss EAP Java applications to Azure * Migrating Spring Boot Java applications to Azure -For more information about use cases and migration paths, see the link:https://developers.redhat.com/products/{LC_PSN}/use-cases[{ProductShortName} for developers] web page. - == How does the {ProductName} simplify migration The {ProductName} looks for common resources and known trouble spots when migrating applications. It provides a high-level view of the technologies used by the application. {ProductShortName} generates a detailed report evaluating a migration or modernization path. This report can help you to estimate the effort required for large-scale projects and to reduce the work involved. -ifndef::getting-started-guide[] -== How do you learn more -See the link:{ProductDocIntroToMTAGuideURL}[Introduction to the {DocInfoProductName}] to learn more about the features, supported configurations, system requirements, and available tools in the {ProductName}. -endif::getting-started-guide[] + +[role="_additional-resources"] +.Additional resources +* link:https://developers.redhat.com/products/{LC_PSN}/use-cases[{ProductShortName} for developers] diff --git a/docs/topics/mta-ui/con_assessment-module-features.adoc b/docs/topics/mta-ui/con_assessment-module-features.adoc index 84091ea9..9bdef920 100644 --- a/docs/topics/mta-ui/con_assessment-module-features.adoc +++ b/docs/topics/mta-ui/con_assessment-module-features.adoc @@ -19,19 +19,19 @@ In {ProductShortName} 7.0, you can import and export assessment questionnaires. * Conditional questions: You can include or exclude questions based on the application or archetype if a certain tag is present on this application or archetype. * Application auto-tagging based on answers: You can define tags to be applied to applications or archetypes if a certain answer was provided. * Automated answers from tags in applications or archetypes. - -+ -For more information, see xref:mta-custom-questionnaire_assessment-questionnaires[The custom assessment questionnaire]. -NOTE: You can customize and save the default questionnaire. For more information, see xref:mta-default-questionnaire_assessment-questionnaires[The default assessment questionnaire]. ++ +NOTE: You can customize and save the default questionnaire. Multiple assessment questionnaires:: The *Assessment* module supports multiple questionnaires, relevant to one or more applications. Archetypes:: -You can group applications with similar characteristics into archetypes. This allows you to assess multiple applications at once. Each archetype has a shared taxonomy of tags, stakeholders, and stakeholder groups. All applications inherit assessment and review from their assigned archetypes. -+ -For more information, see xref:working-with-archetypes_user-interface-guide[Working with archetypes]. - +You can group applications with similar characteristics into archetypes. This allows you to assess multiple applications at once. Each archetype has a shared taxonomy of tags, stakeholders, and stakeholder groups. All applications inherit assessment and review from their assigned archetypes. +[role="_additional-resources"] +.Additional resources +* xref:mta-custom-questionnaire_assessment-questionnaires[The custom assessment questionnaire] +* xref:mta-default-questionnaire_assessment-questionnaires[The default assessment questionnaire] +* xref:working-with-archetypes_user-interface-guide[Working with archetypes] diff --git a/docs/topics/mta-web-applying-assessments-to-other-apps.adoc b/docs/topics/mta-web-applying-assessments-to-other-apps.adoc index 25fca68c..b0b43cd5 100644 --- a/docs/topics/mta-web-applying-assessments-to-other-apps.adoc +++ b/docs/topics/mta-web-applying-assessments-to-other-apps.adoc @@ -2,10 +2,11 @@ // // * docs/web-console-guide/master.adoc -:_content-type: PROCEDURE +:_mod-docs-content-type: PROCEDURE [id="mta-web-applying-assessments-to-other-apps_{context}"] = Applying assessments to other applications +[role="_abstract"] Many applications are similar enough to each other, and you might want to apply a completed assessment of one application to another application. This can save time and provide consistent answers to assessment questions for similar applications. .Procedure diff --git a/docs/topics/rules-development/about-rules.adoc b/docs/topics/rules-development/about-rules.adoc index 7ae2cf8b..c304a7f5 100644 --- a/docs/topics/rules-development/about-rules.adoc +++ b/docs/topics/rules-development/about-rules.adoc @@ -23,9 +23,14 @@ A collection of one or more rules is called a ruleset. Creating rulesets provide You can use rules or rulesets as input arguments in an analysis. You can perform a rule-based analysis in the {ProductShortName} CLI, user interface, or by using one of the IDE plugins for {ProductShortName} (Visual Studio Code or IntelliJ). -The rules can be used by {mta-dl-plugin} to generate AI-assisted code resolutions. The issue description and metadata in rules are used by the {mta-dl-plugin} to form well-defined contexts. These contexts generate AI-assisted suggestions to resolve issues in the code that are identified through an analysis. See link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/8.0/html/configuring_and_using_red_hat_developer_lightspeed_for_mta/index[Configuring and Using Red Hat Developer Lightspeed for MTA] for more information. +The rules can be used by {mta-dl-plugin} to generate AI-assisted code resolutions. The issue description and metadata in rules are used by the {mta-dl-plugin} to form well-defined contexts. These contexts generate AI-assisted suggestions to resolve issues in the code that are identified through an analysis. ifndef::rules-development-guide[] For instructions on how to write custom rules, see [_{RulesDevBookName}_]. endif::rules-development-guide[] + + +[role="_additional-resources"] +.Additional resources +* link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/8.0/html/configuring_and_using_red_hat_developer_lightspeed_for_mta/index[Configuring and using Red Hat Developer Lightspeed for MTA] diff --git a/docs/topics/rules-development/con_provider-capability-in-custom-rules.adoc b/docs/topics/rules-development/con_provider-capability-in-custom-rules.adoc new file mode 100644 index 00000000..17d451e9 --- /dev/null +++ b/docs/topics/rules-development/con_provider-capability-in-custom-rules.adoc @@ -0,0 +1,20 @@ +:_newdoc-version: 2.18.7 +:_template-generated: 2026-03-27 +:_mod-docs-content-type: CONCEPT + +[id="provider-capability-in-custom-rules_{context}"] += Provider capabilities in custom rules + +[role="_abstract"] +In a rule, the `when` block is where the conditions for matching the rule are specified. Each provider offers a series of capabilities to do matching. + +The search query in the rule condition can contain patterns, code locations, specific dependencies to be found, and so on, to evaluate the source code and dependencies. The provider sends the LSP server a request to check the search query against the application being analyzed. When the LSP server returns a match for the search in the source code, the analyzer triggers a violation. + +The syntax of the when block is as follows: it contains a single condition, but that condition might have multiple conditions nested beneath it. + +---- +when: + + +---- + diff --git a/docs/topics/rules-development/developer-preview-admonition.adoc b/docs/topics/rules-development/developer-preview-admonition.adoc deleted file mode 100644 index bb6d5863..00000000 --- a/docs/topics/rules-development/developer-preview-admonition.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// When including this file, ensure that {FeatureName} is set immediately before the include. Otherwise it will result in an incorrect replacement. -// use :FeatureName: - -[IMPORTANT] -==== -[subs="attributes+"] -{FeatureName} is a Developer Preview feature only. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to upcoming product features in advance of their possible inclusion in a Red Hat product offering, enabling customers to test functionality and provide feedback during the development process. These features might not have any documentation, are subject to change or removal at any time, and testing is limited. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. -==== -// Undefine {FeatureName} attribute, so that any mistakes are easily spotted -:!FeatureName: diff --git a/docs/topics/rules-development/rules-guide-intro.adoc b/docs/topics/rules-development/rules-guide-intro.adoc deleted file mode 100644 index 540b51ee..00000000 --- a/docs/topics/rules-development/rules-guide-intro.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/rules-development-guide/master.adoc - -:_mod-docs-content-type: CONCEPT -[id="rules-guide-intro_{context}"] -= About the {RulesDevBookName} - -[role="_abstract"] -This guide is intended for software engineers who want to create custom YAML-based rules for {ProductName} ({ProductShortName}) tools. - -See the link:{ProductDocIntroToMTAGuideURL}[_{IntroToMTABookName}_] for an overview and the link:{ProductDocUserGuideURL}[_{UserCLIBookName}_] for details. diff --git a/docs/topics/rules-development/technology-preview.adoc b/docs/topics/rules-development/technology-preview.adoc deleted file mode 100644 index 9c1acea0..00000000 --- a/docs/topics/rules-development/technology-preview.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// When including this file, ensure that {FeatureName} is set immediately before -// the include. Otherwise it will result in an incorrect replacement. - -[IMPORTANT] -==== -[subs="attributes+"] -{FeatureName} is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. - -For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope]. -==== -// Undefine {FeatureName} attribute, so that any mistakes are easily spotted -:!FeatureName: diff --git a/docs/topics/rules-development/yaml-builtin-provider.adoc b/docs/topics/rules-development/yaml-builtin-provider.adoc index e4a22cd8..e63b2487 100644 --- a/docs/topics/rules-development/yaml-builtin-provider.adoc +++ b/docs/topics/rules-development/yaml-builtin-provider.adoc @@ -7,18 +7,13 @@ = The builtin provider [role="_abstract"] -The `builtin` provider is an internal provider that can analyze various files and internal metadata generated by the engine. This provider has the following capabilities: +The `builtin` is an internal provider that can analyze various files and internal metadata generated by the engine. -* `file` -* `filecontent` -* `xml` -* `json` -* `hasTags` - -.`file` +The `builtin` provider has the following capabilities: +`file`:: By using the `file` capability, the provider searches for files in the source code that match a given pattern. - ++ [source,yaml] ---- when: @@ -26,10 +21,10 @@ when: pattern: "" ---- -.`filecontent` +`filecontent`:: By using the `filecontent` capability, the provider searches for content that matches a given pattern. - ++ [source,yaml] ---- when: @@ -38,10 +33,10 @@ when: pattern: "" ---- -.`xml` +`xml`:: The `xml` capability enables the provider to query XPath expressions on a list of provided XML files. This capability takes 2 input parameters, `xpath` and `filepaths`. - ++ [source,yaml] ---- when: @@ -54,30 +49,29 @@ when: var: http://www.springframework.org/schema/beans xpath: //*/var:bean/@class[matches(self::node(), 'org.apache.camel.util.toolbox.XsltAggregationStrategy')] ---- ++ where: - `xpath` :: must be a valid XPath expression. - `filepaths` :: is a list of files to apply the XPath query to. - `namespaces` :: define namespaces and assign them to variables. You can use the variable in the `xpath`. - -.`json` +* `xpath` is a valid XPath expression. +* `filepaths` is a list of files to apply the XPath query to. +* `namespaces` define namespaces and assign them to variables. You can use the variable in the `xpath`. +`json`:: By using the `json` capability, the provider queries XPath expressions on a list of provided JSON files. Currently, `json` only takes XPath as input and performs the search on all JSON files in the codebase. - ++ [source,yaml] ---- when: builtin.json: xpath: "" ---- -where: - - `xpath` :: must be a valid XPath expression. ++ +where `xpath` must be a valid XPath expression. -.`hasTags` +`hasTags`:: By using the `hasTags` capability, the provider queries application tags. It queries the internal data structure to check whether the application has the given tags. - ++ [source,yaml] ---- when: @@ -86,6 +80,3 @@ when: - "tag1" - "tag2" ---- -where: - - `hasTags` :: When more than one tag is given, a logical AND is implied. diff --git a/docs/topics/rules-development/yaml-condition-patterns.adoc b/docs/topics/rules-development/yaml-condition-patterns.adoc index bd36a83e..5cd9eaad 100644 --- a/docs/topics/rules-development/yaml-condition-patterns.adoc +++ b/docs/topics/rules-development/yaml-condition-patterns.adoc @@ -11,7 +11,7 @@ The Language Server used by the Java provider is Eclipse's JDTLS. Internally, th In the `pattern` element of a `java.referenced` condition, you can search through application code by using these utilities. For more details, see link:https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fjdt%2Fcore%2Fsearch%2FSearchPattern.html&anchor=createPattern[Class SearchPattern], which contains all the information for building these patterns for `createPattern(String, int, int, int)`. -.Examples +Review the following examples of condition patterns: * Search for any class under the `javax.xml` package, occurring in any location: diff --git a/docs/topics/rules-development/yaml-dotnet-provider.adoc b/docs/topics/rules-development/yaml-dotnet-provider.adoc index 5053c641..86bdf0bc 100644 --- a/docs/topics/rules-development/yaml-dotnet-provider.adoc +++ b/docs/topics/rules-development/yaml-dotnet-provider.adoc @@ -14,7 +14,7 @@ The `C#` provider uses a gRPC interface to perform a semantic analysis of an app `referenced`:: The `C#` provider supports `referenced` capability in rules to define fields such as `pattern` and `location` based on which the provider searches the code for violations. - ++ [source,yaml] ---- when: @@ -22,7 +22,8 @@ when: pattern: "" location: CLASS ---- ++ where: - `pattern` :: A regular expression pattern to match the required reference. For example, `HttpNotFound`. - `namespace` :: Specifies the namespace to search within. For example, `System.Web.Mvc`. +* `pattern` is a regular expression pattern to match the required reference, for example, `HttpNotFound`. +* `namespace` is a namespace to search within, for example, `System.Web.Mvc`. diff --git a/docs/topics/rules-development/yaml-go-provider.adoc b/docs/topics/rules-development/yaml-go-provider.adoc index 9972ddcc..8c222278 100644 --- a/docs/topics/rules-development/yaml-go-provider.adoc +++ b/docs/topics/rules-development/yaml-go-provider.adoc @@ -9,20 +9,18 @@ [role="_abstract"] The `go` provider analyzes `Go` source code. This provider's capabilities are `referenced` and `dependency`. -.`referenced` - +`referenced`:: By using the `referenced` capability, the provider finds references in the source code. - ++ [source,yaml] ---- when: go.referenced: "" ---- -.`dependency` - +`dependency`:: By using the `dependency` capability, the provider finds dependencies for a `Go` application. - ++ [source,yaml] ---- when: @@ -31,11 +29,9 @@ when: upperbound: "" lowerbound: "" ---- ++ where: - `name` :: - Name of the dependency to search for. - - `upperbound` :: Upper bound on the version of the dependency. - - `lowerbound` :: Lower bound on the version of the dependency. \ No newline at end of file +* `name` is a name of the dependency to search for. +* `upperbound` is an upper bound on the version of the dependency. +* `lowerbound` is a lower bound on the version of the dependency. \ No newline at end of file diff --git a/docs/topics/rules-development/yaml-java-provider.adoc b/docs/topics/rules-development/yaml-java-provider.adoc index a74ffe7b..92f5686f 100644 --- a/docs/topics/rules-development/yaml-java-provider.adoc +++ b/docs/topics/rules-development/yaml-java-provider.adoc @@ -11,13 +11,9 @@ The `java` provider analyzes Java source code. This provider has the following capabilities: -* `referenced` -* `dependency` - -.`referenced` - -By using the `referenced` capability, the provider finds references in the source code. This capability takes three input parameters: `pattern`, `location`, and `annotated`. - +`referenced`:: +By using the `referenced` capability, the provider finds references in the source code. This capability takes three input parameters: `pattern`, `location`, and `annotated`: ++ [source,terminal] ---- when: @@ -26,13 +22,13 @@ when: location: "" annotated: "" ---- ++ where: - `pattern` :: A regular expression pattern to match. - `location` :: Specifies the exact location where the pattern needs to be matched, for example, `IMPORT`. - `annotated` :: Checks for specific annotations and their elements, such as name and value, in the Java code by using a query. For example, the following query matches the `Bean` (URL = “http://www.example.com”) annotation in the method. - - +* `pattern` is a regular expression pattern to match. +* `location` is the exact location where the pattern needs to be matched, for example, `IMPORT`. +* `annotated` checks for specific annotations and their elements, such as name and value, in the Java code by using a query. For example, the following query matches the `Bean` (URL = “http://www.example.com”) annotation in the method. ++ [source,yaml] ---- annotated: @@ -42,14 +38,12 @@ where: value: "http://www.example.com" ---- -See xref:java-conditions-capabilities[Java condition and capabilities] for a detailed explanation on `java.referenced` capabilities. - -.`dependency` - +`dependency`:: The Java provider has `dependency` capability. The `dependency` capability enables the provider to generate a list of dependencies for a given application. ++ You can use a `dependency` condition to query this list and check whether a certain dependency, with a version range, exists for the application. The dependency can be internal or external or open source. For example, to check if a Java application has a certain dependency, you create a `java.dependency` condition: - ++ [source, yaml] ---- when: @@ -58,17 +52,21 @@ when: upperbound: 4.12.2 lowerbound: 4.4.0 ---- - ++ You can use the `dependency` capability to check if a Java application has Fabric8 Kubernetes client of version 5.0.100 or lower: - ++ [source, yaml] ---- - java.dependency: name: io.fabric8.kubernetes-client lowerbound: 5.0.100 ---- - ++ [NOTE] ==== When you use the `java` provider for an analysis, the analysis results have lower precision for projects that cannot be built. For example, when {ProductShortName} is unable to build a `Maven` project, it falls back to parsing the `pom` file to get the list of dependencies. -==== \ No newline at end of file +==== + +[role="_additional-resources"] +.Additional resources +* xref:java-conditions-capabilities[Java condition and capabilities] \ No newline at end of file diff --git a/docs/topics/rules-development/yaml-rule-actions.adoc b/docs/topics/rules-development/yaml-rule-actions.adoc deleted file mode 100644 index 0b9fe719..00000000 --- a/docs/topics/rules-development/yaml-rule-actions.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/rules-development-guide/master.adoc - -:_mod-docs-content-type: REFERENCE -[id="yaml-rule-actions_{context}"] -= Types of rule actions - -[role="_abstract"] -Rules can include the following types of actions: - -* message -* tag - -Each rule includes either one of them or both of them. - -[id="message-actions"] -.Message actions - -When a message action matches the rule, it creates an issue. The custom data that providers export can be used in the message. - - -[source,yaml] ----- -- ruleID: test-rule - when: - - message: Test rule matched. Please resolve this migration issue. ----- - -Optionally, a message can include hyperlinks to external URLs that provide relevant information about the issue or a quick fix. - -[source,yaml] ----- -links: - - url: "konveyor.io" - title: "Short title for the link" ----- - -A message can also be a template to include information about the match interpolated through custom variables on the rule. diff --git a/docs/topics/rules-development/yaml-rule-metadata.adoc b/docs/topics/rules-development/yaml-rule-metadata.adoc index ba9f5456..fd81db11 100644 --- a/docs/topics/rules-development/yaml-rule-metadata.adoc +++ b/docs/topics/rules-development/yaml-rule-metadata.adoc @@ -25,9 +25,16 @@ labels: effort: 1 category: mandatory ---- + where: - *ruleID* :: This is a unique ID for the rule. It must be unique within the ruleset. - *labels* :: A list of string labels associated with the rule. (See xref:yaml-rule-labels_rule-yaml-metadata[Labels]). - *effort* :: Effort is an integer value that indicates the level of effort needed to resolve this issue. - *category* :: Category describes the severity of the issue for migration. Values can be one of `mandatory`, `potential` or `optional`. For more details, see xref:yaml-rule-categories_rule-yaml-metadata[Rule categories]. +* `ruleID` is a unique ID for the rule. It must be unique within the ruleset. +* `labels` is a list of string labels associated with the rule. +* `effort` is an integer value that indicates the level of effort needed to resolve this issue. +* `category` is the severity of the issue for migration. Values can be one of `mandatory`, `potential` or `optional`. + + +[role="_additional-resources"] +.Additional resources +* xref:yaml-rule-labels_rule-yaml-metadata[Rule labels] +* xref:yaml-rule-categories_rule-yaml-metadata[Rule categories] \ No newline at end of file diff --git a/docs/topics/rules-development/yaml-rulesets.adoc b/docs/topics/rules-development/yaml-rulesets.adoc index 5198febf..a5bc4d3d 100644 --- a/docs/topics/rules-development/yaml-rulesets.adoc +++ b/docs/topics/rules-development/yaml-rulesets.adoc @@ -36,4 +36,8 @@ $ mta-cli analyze --input= --output= --rules * To use multiple rule files, place them in a directory and add a `ruleset.yaml` file. Then the directory is treated as a _ruleset_, and you can pass it as input to the `--rules` option. + -Note that if you want to use the `--target` or `--source` option in the CLI, the engine will only select rules that match the label for that target. Therefore, make sure that you have added target or source labels on your rules. See xref:reserved-label_rule-yaml-metadata[Reserved labels] for more details. +NOTE: If you want to use the `--target` or `--source` option in the CLI, the engine will only select rules that match the label for that target. Therefore, make sure that you have added target or source labels on your rules. + +[role="_additional-resources"] +.Additional resources +* xref:reserved-label_rule-yaml-metadata[Reserved labels] diff --git a/docs/topics/rules-important-links.adoc b/docs/topics/rules-important-links.adoc deleted file mode 100644 index ee4e5895..00000000 --- a/docs/topics/rules-important-links.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/rules-development-guide/master.adoc - -:_mod-docs-content-type: REFERENCE -[id="rules-important-links_{context}"] -= Additional resources - -[role="_abstract"] -// * {ProductShortName} Javadocs: {LinkAPI}reporting/api/src/main/java -* {ProductShortName} Jira issue tracker: {JiraWindupURL} -* {ProductShortName} mailing list: windup-eng@redhat.com diff --git a/docs/topics/templates/developer-preview.adoc b/docs/topics/templates/developer-preview.adoc deleted file mode 100644 index 4d1c868e..00000000 --- a/docs/topics/templates/developer-preview.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// When including this file, ensure that {FeatureName} is set immediately before the include. Otherwise it will result in an incorrect replacement. -// use :FeatureName: - -[subs="attributes+"] -{FeatureName} is a Developer Preview feature only. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to upcoming product features in advance of their possible inclusion in a Red Hat product offering, enabling customers to test functionality and provide feedback during the development process. These features might not have any documentation, are subject to change or removal at any time, and testing is limited. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. - -// Undefine {FeatureName} attribute, so that any mistakes are easily spotted -:!FeatureName: diff --git a/docs/topics/templates/technology-preview-admonition.adoc b/docs/topics/templates/technology-preview-admonition.adoc deleted file mode 100644 index 972b4bfa..00000000 --- a/docs/topics/templates/technology-preview-admonition.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// When including this file, ensure that {FeatureName} is set immediately before -// the include. Otherwise it will result in an incorrect replacement. -// use :FeatureName: - -[IMPORTANT] -==== -[subs="attributes+"] -{FeatureName} is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. - -For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope]. -==== -// Undefine {FeatureName} attribute, so that any mistakes are easily spotted -:!FeatureName: