From 723097ed080309f07faccedd1faa6dfa3aa9fa0e Mon Sep 17 00:00:00 2001 From: Prabha Kylasamiyer Sundara Rajan Date: Fri, 17 Apr 2026 15:53:18 +0530 Subject: [PATCH 1/4] NTA-6826, 6827, 6828 CQA April work for rules development guide Signed-off-by: Prabha Kylasamiyer Sundara Rajan --- .../assembly_creating-rule.adoc | 6 +- .../assembly_java-conditions-detailed.adoc | 11 +- ...bly_logical-chaining-custom-variables.adoc | 7 +- .../assembly_rule-rulesets.adoc | 5 +- .../assembly_rule-yaml-actions.adoc | 4 +- .../assembly_rule-yaml-conditions.adoc | 16 +-- .../assembly_rule-yaml-metadata.adoc | 7 +- .../assembly_rules-introduction.adoc | 6 +- docs/rules-development-guide/master.adoc | 9 -- .../topics/rules-development/about-rules.adoc | 20 ++- .../con_external_providers.adoc | 26 ++++ ...n_provider-capability-in-custom-rules.adoc | 6 +- .../create-basic-yaml-rule-template.adoc | 44 ------ .../create-csharp-custom-rule.adoc | 24 ++-- .../create-first-yaml-rule.adoc | 69 +++++----- .../create-go-custom-rule.adoc | 4 +- .../create-nodejs-custom-rule.adoc | 4 +- .../create-python-custom-rule.adoc | 6 +- .../rules-development/yaml-and-condition.adoc | 4 +- .../yaml-annotation-inspection.adoc | 4 +- .../yaml-builtin-provider.adoc | 8 +- .../yaml-chaining-condition-variables.adoc | 14 +- .../yaml-chaining-java-provider.adoc | 4 +- .../yaml-condition-patterns.adoc | 8 +- .../yaml-custom-variables.adoc | 6 +- .../yaml-dotnet-provider.adoc | 12 +- .../rules-development/yaml-go-provider.adoc | 2 +- .../yaml-java-locations.adoc | 44 +++--- .../rules-development/yaml-java-provider.adoc | 14 +- .../yaml-message-actions.adoc | 8 +- .../yaml-nested-condition.adoc | 2 +- .../rules-development/yaml-or-condition.adoc | 2 +- .../yaml-provider-conditions.adoc | 126 ++++++++---------- .../yaml-rule-categories.adoc | 6 +- .../yaml-rule-condition-complexity.adoc | 15 +++ .../yaml-rule-conditions.adoc | 14 -- .../yaml-rule-hyperlinks.adoc | 4 +- .../rules-development/yaml-rule-labels.adoc | 6 +- .../rules-development/yaml-rule-metadata.adoc | 9 +- .../yaml-rule-structure-syntax.adoc | 24 +++- .../rules-development/yaml-rulesets.adoc | 16 ++- .../rules-development/yaml-tag-actions.adoc | 4 +- .../topics/templates/document-attributes.adoc | 2 +- 43 files changed, 308 insertions(+), 324 deletions(-) create mode 100644 docs/topics/rules-development/con_external_providers.adoc delete mode 100644 docs/topics/rules-development/create-basic-yaml-rule-template.adoc create mode 100644 docs/topics/rules-development/yaml-rule-condition-complexity.adoc delete mode 100644 docs/topics/rules-development/yaml-rule-conditions.adoc diff --git a/assemblies/rules-development-guide/assembly_creating-rule.adoc b/assemblies/rules-development-guide/assembly_creating-rule.adoc index 9b868110..dfbbc68f 100644 --- a/assemblies/rules-development-guide/assembly_creating-rule.adoc +++ b/assemblies/rules-development-guide/assembly_creating-rule.adoc @@ -16,11 +16,7 @@ endif::[] :context: creating-rule [role="_abstract"] -You can refer to example rules that describe how to create a YAML rule. This assumes that you already have MTA installed. See the MTA CLI Guide for installation instructions. - -//This section describes how to create a {ProductShortName} YAML rule. This assumes that you already have {ProductShortName} installed. See the {ProductShortName} {ProductDocUserGuideURL}[_{UserCLIBookName}_] for installation instructions.// - -include::topics/rules-development/create-basic-yaml-rule-template.adoc[leveloffset=+1] +To analyze applications in `Python`, `Node.js`, `Go`, and `C#`, the Architect must create a custom rule. A custom rule includes conditions and patterns that describe an issue. You must resolve issues when refactoring applications before migrating them to a target platform. include::topics/rules-development/create-first-yaml-rule.adoc[leveloffset=+1] diff --git a/assemblies/rules-development-guide/assembly_java-conditions-detailed.adoc b/assemblies/rules-development-guide/assembly_java-conditions-detailed.adoc index 02e8a718..34df0aa1 100644 --- a/assemblies/rules-development-guide/assembly_java-conditions-detailed.adoc +++ b/assemblies/rules-development-guide/assembly_java-conditions-detailed.adoc @@ -1,10 +1,8 @@ :_newdoc-version: 2.18.3 :_template-generated: 2025-05-28 - -ifdef::context[:parent-context-of-java-conditions-capabilities: {context}] - :_mod-docs-content-type: ASSEMBLY +ifdef::context[:parent-context-of-java-conditions-capabilities: {context}] ifndef::context[] [id="java-conditions-capabilities"] endif::[] @@ -16,13 +14,8 @@ endif::[] :context: java-conditions-capabilities [role="_abstract"] -The `java.referenced` capability in the when condition for Java rules can define search queries for the following fields in the source code: - -* Locations - such as the classes, methods, packages and so on -* Annotations -* Patterns +As an Architect, you can create custom rules to analyze the `Java` source code for problematic patterns before migration. The `Java` provider uses Eclipse Java Development Tools Language Server (JDTLS) that depends on the Eclipse Java Development Toolkit for utilities to search the source code. -You can refer to this section for a detailed explanation on the Locations, Annotations, and Patterns. include::topics/rules-development/yaml-java-locations.adoc[leveloffset=+1] diff --git a/assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc b/assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc index ee3c4339..be64ff6c 100644 --- a/assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc +++ b/assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc @@ -16,12 +16,9 @@ endif::[] :context: logical-chaining-custom-variables [role="_abstract"] -You can create complex conditions in rules by using the following: +When you create a rule, you can limit the search query in the source code by using logical conditions, condition chaining, nested conditions, and custom variables. You can narrow the search to specific files, a pattern, or a combination of conditions. -* Logical conditions inform the provider how to handle more than one condition in a when block. The analyzer provides the logical conditions, `and` and `or`, that you can use to aggregate results of other conditions. -* Condition chaining uses the output of one condition as the input in another condition of the when block. Assign the output to a variable in one condition and reuse it in other conditions in the when block. -* Nested conditions to create conditions that depend on the evaluation of other conditions. -* Custom variables to capture specific information from the code that is evaluated by a rule. You can use the custom variable in the message displayed for the code if it contains a violation defined by the rule. +include::topics/rules-development/yaml-rule-condition-complexity.adoc[leveloffset=+1] include::topics/rules-development/yaml-and-condition.adoc[leveloffset=+1] diff --git a/assemblies/rules-development-guide/assembly_rule-rulesets.adoc b/assemblies/rules-development-guide/assembly_rule-rulesets.adoc index c38b42fc..e34cc88d 100644 --- a/assemblies/rules-development-guide/assembly_rule-rulesets.adoc +++ b/assemblies/rules-development-guide/assembly_rule-rulesets.adoc @@ -18,10 +18,7 @@ endif::[] [role="_abstract"] A set of rules forms a ruleset. {ProductShortName} does not require every rule file to belong to a ruleset, but you can use rulesets to group multiple rules that achieve a common goal and to pass the rules to the rules engine. -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. +The `ruleset.yaml` file stores the metadata of the ruleset. You can group multiple similar custom rules and create a ruleset for them. include::topics/rules-development/yaml-rulesets.adoc[leveloffset=+1] diff --git a/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc b/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc index 9dfb9219..dada3fc6 100644 --- a/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc +++ b/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc @@ -21,9 +21,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. -* `Tag`: use tags to categorize parts of the source code. For example, Backend=Java, where Backend is the key and Java is the value. +* `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. +Each rule includes either one action tag or both. 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 d2badc29..03d11a2e 100644 --- a/assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc +++ b/assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc @@ -16,21 +16,9 @@ endif::[] :context: rules-prov-cond [role="_abstract"] -The providers are the modular components in charge of analyzing a given language. The external providers, except `C#`, are able to analyze code by leveraging the Language Server Protocol (LSP). Through the LSP, all code analysis is abstracted away from the analysis engine and left to the specific LSP server to run the search query defined in the rule on the source code. +Providers are the modular components that work with the analysis engine and the Language Server Protocol (LSP) server to analyze the application source code. They run search queries on the source code based on rule patterns to scan for issues. -Additionally, {ProductShortName} provides a built-in provider with abilities such as XML parsing, running regular expressions on files, and so on. - -Currently, {ProductShortName} supports the following providers: - -* builtin -* Java -* C# -* External providers (for `Python`, `Go`, and `Node.js` applications) initialized by the generic provider binary - -[NOTE] -==== -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]. -==== +include::topics/rules-development/con_external_providers.adoc[leveloffset=+1] include::topics/rules-development/con_provider-capability-in-custom-rules.adoc[leveloffset=+1] diff --git a/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc b/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc index 3a50b94c..3b1534f0 100644 --- a/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc +++ b/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc @@ -16,12 +16,7 @@ endif::[] :context: rule-yaml-metadata [role="_abstract"] -The rule metadata contains information about the migration defined by the Architect. You can use rule metadata to: - -* Estimate the total migration effort. -* Prioritize issues that must be resolved based on the effort. -* Evaluate if a resolution is mandatory through rule category before migrating the applications to the target technologies or platforms. -* Define labels used by {ProductShortName} to filter rules for an analysis. +As an Architect, you include information about effort in the rule metadata. Effort is a numerical value that accounts for the complexity in resolving the issue described in the rule. In the metadata, you can add category and label that guides Migrators when they resolve issues in the code. include::topics/rules-development/yaml-rule-metadata.adoc[leveloffset=+1] diff --git a/assemblies/rules-development-guide/assembly_rules-introduction.adoc b/assemblies/rules-development-guide/assembly_rules-introduction.adoc index d4854088..afaa5797 100644 --- a/assemblies/rules-development-guide/assembly_rules-introduction.adoc +++ b/assemblies/rules-development-guide/assembly_rules-introduction.adoc @@ -16,13 +16,13 @@ endif::[] :context: rules-introduction [role="_abstract"] -This guide is intended for software engineers who want to create custom YAML-based rules for {ProductName} ({ProductShortName}) tools. +As an Architect, see the following sections to understand rules and rule syntax so that, you can create custom YAML-based rules for {ProductName} ({ProductShortName}) tools. include::topics/rules-development/about-rules.adoc[leveloffset=+1] include::topics/rules-development/yaml-rule-structure-syntax.adoc[leveloffset=+1] -ifdef::parent-context-of-getting-started[:context: {parent-context-of-rules-introduction}] -ifndef::parent-context-of-getting-started[:!context:] +ifdef::parent-context-of-rules-introduction[:context: {parent-context-of-rules-introduction}] +ifndef::parent-context-of-rules-introduction[:!context:] :!rules-introduction: \ No newline at end of file diff --git a/docs/rules-development-guide/master.adoc b/docs/rules-development-guide/master.adoc index 83db9845..36ff7ae4 100644 --- a/docs/rules-development-guide/master.adoc +++ b/docs/rules-development-guide/master.adoc @@ -11,27 +11,18 @@ include::topics/templates/document-attributes.adoc[] [id="rules-development-guide"] = Configuring and using rules for an {ProductShortName} analysis - //Inclusive language statement include::topics/making-open-source-more-inclusive.adoc[] include::assemblies/rules-development-guide/assembly_rules-introduction.adoc[leveloffset=+1] - include::assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc[leveloffset=+1] - include::assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc[leveloffset=+1] - include::assemblies/rules-development-guide/assembly_java-conditions-detailed.adoc[leveloffset=+1] - include::assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc[leveloffset=+1] - include::assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc[leveloffset=+1] - include::assemblies/rules-development-guide/assembly_creating-rule.adoc[leveloffset=+1] - include::assemblies/rules-development-guide/assembly_rule-rulesets.adoc[leveloffset=+1] - [id="_additional-resources"] == Additional resources diff --git a/docs/topics/rules-development/about-rules.adoc b/docs/topics/rules-development/about-rules.adoc index c304a7f5..85b9f4f0 100644 --- a/docs/topics/rules-development/about-rules.adoc +++ b/docs/topics/rules-development/about-rules.adoc @@ -8,29 +8,27 @@ = The {ProductShortName} rules [role="_abstract"] -The {ProductFullName} contains the analyzer that uses pluggable providers and rules to analyze static code, dependencies, and other files in your application. +{ProductFullName} analyzes the application source code to find issues based on user-generated rule and default rule definitions. You can fix issues in an analysis report before migrating the code to a target platform. You can view the rule syntax information to create a new rule or a ruleset. -The analyzer works with providers to detect issues that cause problems when you migrate the application to target technologies. The rule definition contains metadata description and condition patterns that describe a violation. +A ruleset is a collection of one or more rules. An Architect can create rulesets to organize one or more rules that analyze the source code for a specific target platform. -The analyzer runs a search query on the source code to match the violation described in the rule definition. The rule definition also contains a message that MTA displays when triggering an issue because of the violation. The analyzer uses default and user-provided (custom) rules during an analysis to identify issues. +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). -[NOTE] -==== -An {ProductShortName} Architect can create custom rules. You can use custom rules to identify the use of custom libraries or other components in the source code that might not be covered by the standard migration rules. -==== +{mta-dl-plugin} uses rules to generate AI-assisted code resolutions. {mta-dl-plugin} uses the issue description and metadata in rules to form well-defined contexts. These contexts generate AI-assisted suggestions to resolve issues in the code that {ProductShortName} identified through an analysis. -A collection of one or more rules is called a ruleset. Creating rulesets provides a way of organizing multiple rules that analyze the source code for a specific target platform. +== How {ProductShortName} performs an analysis -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). +{ProductFirstRef} contains the analyzer that uses pluggable providers and rules to analyze static code, dependencies, and other files in your application. -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. +The analyzer works with providers to detect issues that cause problems when you migrate the application to target technologies. The rule definition contains metadata description and condition patterns that describe a violation. + +The analyzer runs a search query on the source code to match the violation described in the rule definition. The rule definition also contains a message that {ProductShortName} displays when triggering an issue because of the violation. The analyzer uses default and user-provided (custom) rules during an analysis to identify issues. 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_external_providers.adoc b/docs/topics/rules-development/con_external_providers.adoc new file mode 100644 index 00000000..3b03fdb0 --- /dev/null +++ b/docs/topics/rules-development/con_external_providers.adoc @@ -0,0 +1,26 @@ +:_newdoc-version: 2.18.7 +:_template-generated: 2026-03-27 +:_mod-docs-content-type: CONCEPT + +[id="external-providers_{context}"] += Provider capabilities in custom rules + +[role="_abstract"] +The external providers, except `C#`, use the Language Server Protocol (LSP) server to perform an analysis. The provider forms a search query and sends it to the LSP server to check against the application. When the LSP server returns a match for the search in the source code, the analyzer triggers a violation. + +Currently, {ProductShortName} supports the following providers: + +* `builtin` +* `Java` +* `C#` +* External providers (for `Python`, `Go`, and `Node.js` applications) initialized by the generic provider binary + +[NOTE] +==== +You can use the generic provider binary to create an external provider for any language that is compliant with LSP specifications. +==== + +.Additional resources + +* link:https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/[LSP 3.17 specifications] + 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 index 17d451e9..fb07462f 100644 --- a/docs/topics/rules-development/con_provider-capability-in-custom-rules.adoc +++ b/docs/topics/rules-development/con_provider-capability-in-custom-rules.adoc @@ -6,11 +6,9 @@ = 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. +As an Architect, you define conditions and patterns in custom rules that {ProductShortName} uses to match against the source code and dependencies in an analysis. You can specify the conditions in the `when` block of the rule. Each provider offers capabilities to match rule patterns. -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. +The `when` block contains a single condition, but that condition might have one or more conditions nested under it. ---- when: diff --git a/docs/topics/rules-development/create-basic-yaml-rule-template.adoc b/docs/topics/rules-development/create-basic-yaml-rule-template.adoc deleted file mode 100644 index 76eb33d7..00000000 --- a/docs/topics/rules-development/create-basic-yaml-rule-template.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/rules-development-guide/master.adoc - -:_mod-docs-content-type: PROCEDURE -[id="create-basic-yaml-rule-template_{context}"] -= Creating a YAML rule template - -[role="_abstract"] -{ProductShortName} YAML-based rules have the following basic structure: - -[source,terminal] ----- -when(condition) - message(message) - tag(tags) ----- - -.Procedure - -. Create a file containing the basic syntax for YAML rules as follows: -+ -[source,terminal] ----- -- category: mandatory - description: - - - effort: - labels: - - konveyor.io/source= - - konveyor.io/target= - links: - - url: - title: - message: - tag: - - - - - ruleID: - when: - ----- - diff --git a/docs/topics/rules-development/create-csharp-custom-rule.adoc b/docs/topics/rules-development/create-csharp-custom-rule.adoc index 2643c0ce..4d63436e 100644 --- a/docs/topics/rules-development/create-csharp-custom-rule.adoc +++ b/docs/topics/rules-development/create-csharp-custom-rule.adoc @@ -7,14 +7,14 @@ = Creating a custom C# rule [role="_abstract"] -You can create custom rules to analyze `C#` applications by using the {ProductShortName} CLI, user interface, or IDE extension. The following example shows how to run a CLI analysis for a C# application. +You can create custom rules to analyze `C#` applications by using the {ProductShortName} CLI, user interface, or IDE extension. The following example shows how to run a CLI analysis for a `C#` application. You can use a custom rule to check if {ProductShortName} triggers an incident when it detects the `WebMatrix.WebData.WebSecurity` class in a `C#` example project. .Prerequisites * You installed the `ilspycmd` and `paket` dependencies. -* You installed the `dotnet tools` and exported the `dotnet tools` path by using the `export PATH="$PATH:_ -o __* *--overwrite --run-local=false --enable-default-rulesets=false --mode* *source-only --rules ~/csharp-rule.yaml* ---- + [NOTE] ==== -Add the `--overwrite` option if you want to use the same directory for the report when you run subsequent tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you ran. +Add the `--overwrite` option if you want to use the same directory for the report when you run more tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you ran. ==== -. Open the static report at _path_to_report_ in your browser. +. Open the static report at __ in your browser. -. Navigate to the issues to verify the *`WebMatrix.WebData.WebSecurity` is not available in `.NET Core`* issue. +. Navigate to the issues to verify the *`WebMatrix.WebData.WebSecurity` is not available in `.NET`* issue. diff --git a/docs/topics/rules-development/create-first-yaml-rule.adoc b/docs/topics/rules-development/create-first-yaml-rule.adoc index b4fb2f43..2647edfa 100644 --- a/docs/topics/rules-development/create-first-yaml-rule.adoc +++ b/docs/topics/rules-development/create-first-yaml-rule.adoc @@ -7,24 +7,39 @@ = Creating a YAML rule [role="_abstract"] -You can create and test your first {ProductShortName} YAML-based rule by completing the following procedure. This assumes that you have already installed {ProductShortName}. See link:{ProductDocUserGuideURL}/index#installing_and_running_the_cli[Installing and running the CLI] in the _{UserCLIBookName}_ for installation instructions. +You can create a YAML-based rule to discover instances where an application defines a `jboss-web.xml` file containing a `` element and to provide a link to the documentation that describes how to migrate the code. -In this example, you will create a rule to discover instances where an application defines a `jboss-web.xml` file containing a `` element and to provide a link to the documentation that describes how to migrate the code. + +.Prerequisites + +* You installed {ProductShortName}. See link:{ProductDocUserGuideURL}/index#installing_and_running_the_cli[Installing and running the CLI] in the _{UserCLIBookName}_. .Procedure -. Create a YAML file for the rule. In the following example, the rule is created in your `$HOME` directory. +. Create a YAML file for the rule. In the following example, find the rule in your `$HOME` directory. + [options="nowrap",subs="attributes+"] ---- $ mkdir /home//rule.yaml ---- -. Create `jboss-web.xml` and `pom.xml` files in a directory: +. Create a `data` directory: + [options="nowrap",subs="attributes+"] ---- mkdir /home//data/ +---- + +. Create a `jboss-web.xml` file in the `data` directory: ++ +[options="nowrap",subs="attributes+"] +---- touch /home//data/jboss-web.xml +---- + +. Create a `pom.xml` file in the `data` directory: ++ +[options="nowrap",subs="attributes+"] +---- touch /home//data/pom.xml ---- @@ -69,15 +84,16 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xs + [options="nowrap",subs="attributes+"] ---- -- ruleID: - description: +- ruleID: jboss5-web-class-loading + description: Find class loading element in JBoss XML file. when: - - message: - labels: - effort: + builtin.xml: + xpath: /jboss-web/class-loading + message: The class-loading element is no longer valid in the jboss-web.xml file. + effort: 3 links: - - + - url: https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6 + title: Create or Modify Files That Control Class Loading in JBoss EAP 6 ---- + where: @@ -95,7 +111,8 @@ when: ---- + -`message` :: Helpful message explaining the migration issue. The message is generated in the report when the rule matches. For example: +`message` :: Helpful message explaining the migration issue. {ProductShortName} includes the message in the report when the rule matches. For example: ++ [source, yaml] ---- @@ -105,6 +122,7 @@ message: The class-loading element is no longer valid in the jboss-web.xml file. `labels` :: List of string labels for the rule. `effort` :: Number of expected story points to resolve this issue. `links` :: One or more hyperlinks pointing to documentation around the migration issues that you find. ++ [options="nowrap",subs="attributes+"] ---- @@ -112,22 +130,14 @@ message: The class-loading element is no longer valid in the jboss-web.xml file. - url: https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6 title: Create or Modify Files That Control Class Loading in JBoss EAP 6 ---- ++ -The rule is now complete and looks similar to the following: +The rule is now complete. -[options="nowrap",subs="attributes+"] ----- -- ruleID: jboss5-web-class-loading - description: Find class loading element in JBoss XML file. - when: - builtin.xml: - xpath: /jboss-web/class-loading - message: The class-loading element is no longer valid in the jboss-web.xml file. - effort: 3 - links: - - url: https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6 - title: Create or Modify Files That Control Class Loading in JBoss EAP 6 ----- + +.Verification + +To verify that the rule works: . Point the CLI to the rule file you created: + @@ -136,7 +146,7 @@ The rule is now complete and looks similar to the following: –rules /home//rules.yaml ---- -. To test the rule, point the input to the test data you created and pass the rule using the rules option in MTA CLI: +. Pass the rule by using the rules option in MTA CLI: + [options="nowrap",subs="attributes+"] ---- @@ -155,9 +165,8 @@ INFO[0066] Static report created. Access it at this URL: URL="file:/home/ + Open `/home//output/static-report/index.html` in a web browser. . Navigate to the *Issues* tab in the left menu. -. Verify that the rule is executed: -.. In the *Issues* table, type `JBoss XML` in the search bar. -.. Verify that the issue with the title `Find class loading element in JBoss XML file` is present in the table. +. In the *Issues* table, type `JBoss XML` in the search bar. +. Verify that the issue with the title `Find class loading element in JBoss XML file` is present in the table. . Click the *jboss-web.xml* link to open the affected file. diff --git a/docs/topics/rules-development/create-go-custom-rule.adoc b/docs/topics/rules-development/create-go-custom-rule.adoc index 1b4e477f..50322735 100644 --- a/docs/topics/rules-development/create-go-custom-rule.adoc +++ b/docs/topics/rules-development/create-go-custom-rule.adoc @@ -62,9 +62,11 @@ __ [NOTE] ==== -Add the `--overwrite` option if you want to use the same directory for the report when you run subsequent tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you run. +Add the `--overwrite` option if you want to use the same directory for the report when you run more tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you run. ==== +.Verification + . Open the static report at `/home//output/static-report/` in your browser. . Navigate to the issues to verify the `golang apiextensions/v1/customresourcedefinitions found` issue. diff --git a/docs/topics/rules-development/create-nodejs-custom-rule.adoc b/docs/topics/rules-development/create-nodejs-custom-rule.adoc index b3f8de2c..1519c06b 100644 --- a/docs/topics/rules-development/create-nodejs-custom-rule.adoc +++ b/docs/topics/rules-development/create-nodejs-custom-rule.adoc @@ -55,9 +55,11 @@ $ ./mta-cli analyze -i ~/test-nodejs/ -o \ [NOTE] ==== -Add the `--overwrite` option if you want to use the same directory for the report when you run subsequent tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you run. +Add the `--overwrite` option if you want to use the same directory for the report when you run more tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you run. ==== +.Verification + . Open the static report at `~/test-nodejs/report/static-report/index.html` in your browser. . Click the __ to open the Dashboard. diff --git a/docs/topics/rules-development/create-python-custom-rule.adoc b/docs/topics/rules-development/create-python-custom-rule.adoc index f1a015ea..ee6383f9 100644 --- a/docs/topics/rules-development/create-python-custom-rule.adoc +++ b/docs/topics/rules-development/create-python-custom-rule.adoc @@ -11,8 +11,8 @@ You must create custom rules to analyze `Python` applications by using {ProductS The following example uses two custom rules: -* The first rule checks if `bad_method` is specified. -* The second rule checks if `hello_world` is specified in `file_a.py` in your project. +* The first rule checks if `bad_method` is present. +* The second rule checks if `hello_world` is present in `file_a.py` in your project. .Procedure . Create the directory `test-python`. @@ -83,7 +83,7 @@ $ ./mta-cli analyze -i ~/test-python/ -o \ [NOTE] ==== -Add the `--overwrite` option if you want to use the same directory for the report when you run subsequent tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you run. +Add the `--overwrite` option if you want to use the same directory for the report when you run more tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you run. ==== . Open the static report at `~/test-python/report/static-report/index.html` in your browser. diff --git a/docs/topics/rules-development/yaml-and-condition.adoc b/docs/topics/rules-development/yaml-and-condition.adoc index 06e139d5..b4563b75 100644 --- a/docs/topics/rules-development/yaml-and-condition.adoc +++ b/docs/topics/rules-development/yaml-and-condition.adoc @@ -2,7 +2,7 @@ // // * docs/rules-development-guide/master.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="yaml-and-condition_{context}"] = AND condition @@ -17,7 +17,7 @@ when: - ---- -For example: +For an example rule condition, see: [source,yaml] ---- diff --git a/docs/topics/rules-development/yaml-annotation-inspection.adoc b/docs/topics/rules-development/yaml-annotation-inspection.adoc index a08dac0a..4b0eb900 100644 --- a/docs/topics/rules-development/yaml-annotation-inspection.adoc +++ b/docs/topics/rules-development/yaml-annotation-inspection.adoc @@ -7,7 +7,9 @@ = Annotation inspection [role="_abstract"] -You can add a query to match against specific annotations and their elements, for example: +You can use the `annotated` filed in the rule condition to match against specific `Java` annotations and their elements in the source code. + +The following example matches against a specific annotation and its elements: [source,yaml] ---- diff --git a/docs/topics/rules-development/yaml-builtin-provider.adoc b/docs/topics/rules-development/yaml-builtin-provider.adoc index 8d0d50cb..acd08a25 100644 --- a/docs/topics/rules-development/yaml-builtin-provider.adoc +++ b/docs/topics/rules-development/yaml-builtin-provider.adoc @@ -2,14 +2,14 @@ // // * docs/rules-development-guide/master.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="yaml-builtin-provider_{context}"] -= The builtin provider += The `builtin` provider [role="_abstract"] -The `builtin` is an internal provider that can analyze various files and internal metadata generated by the engine. +The `builtin` is an internal provider that can analyze files and internal metadata generated by the rule engine. The `builtin` provider can parse XML, run regular expressions on files, and scan for application tags. -The `builtin` provider has the following capabilities: +The `builtin` provider offers the following capabilities: `file`:: By using the `file` capability, the provider searches for files in the source code that match a given pattern. diff --git a/docs/topics/rules-development/yaml-chaining-condition-variables.adoc b/docs/topics/rules-development/yaml-chaining-condition-variables.adoc index 024d4d36..dd4d763b 100644 --- a/docs/topics/rules-development/yaml-chaining-condition-variables.adoc +++ b/docs/topics/rules-development/yaml-chaining-condition-variables.adoc @@ -2,13 +2,14 @@ // // * docs/rules-development-guide/master.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="yaml-chaining-condition-variables_{context}"] = Chaining condition variables [role="_abstract"] -You can use the output of one condition as the input for filtering another one in the `and` and `or` conditions. This is called *condition chaining*. +You can use condition chaining, where the pattern of one condition becomes the template variable for filtering in another condition. Use condition chaining to scope down the search query to look for a pattern in a subset of files. +For example, you can search for one or more `pom.xml` files and find dependencies in those subset of `pom` files and not any other file in your project. You can use logical `and` and `or` for chaining conditions. [source,yaml] ---- @@ -24,7 +25,7 @@ when: ignore: true ---- -In the above example, the output of the `builtin.file` condition is saved as `poms`: +In the earlier example, {ProductShortName} saves the output of the `builtin.file` condition in `poms`: [source,yaml] ---- @@ -33,7 +34,7 @@ In the above example, the output of the `builtin.file` condition is saved as `po [...] ---- -The variables of `builtin.file` can then be used in the `builtin.xml` condition, by writing `from` and then using link:https://mustache.github.io/mustache.5.html[Mustache templates] in the `provider_ condition` block. +You can use the variables of `builtin.file` in the `builtin.xml` condition, by writing `from` and then using Mustache templates in the `provider_ condition` block. This is how the condition knows how to use the variable set to the name `poms`. @@ -58,7 +59,7 @@ any of the inputs to the _provider_ condition. ==== If you only want to use the values of a condition as a chain, you can set `ignore: true`. -This will tell the engine not to use this condition to determine whether the rule has been violated or not: +This will tell the engine not to use this condition to find a rule violation: [source,yaml] ---- @@ -67,3 +68,6 @@ This will tell the engine not to use this condition to determine whether the rul [...] ---- ==== + +.Additional resources +* link:https://mustache.github.io/mustache.5.html[Mustache templates] \ No newline at end of file diff --git a/docs/topics/rules-development/yaml-chaining-java-provider.adoc b/docs/topics/rules-development/yaml-chaining-java-provider.adoc index 8b7c0cf8..6def7ac0 100644 --- a/docs/topics/rules-development/yaml-chaining-java-provider.adoc +++ b/docs/topics/rules-development/yaml-chaining-java-provider.adoc @@ -7,7 +7,9 @@ = Chaining in the Java provider [role="_abstract"] -In the `java` provider, the `Filepaths` variable must be capitalized, for example: +When you use the `filepaths` variable in a Java rule chained condition, the rule writer must capitalize the variable. + +For example: [source,yaml] ---- diff --git a/docs/topics/rules-development/yaml-condition-patterns.adoc b/docs/topics/rules-development/yaml-condition-patterns.adoc index 5cd9eaad..e57afdc7 100644 --- a/docs/topics/rules-development/yaml-condition-patterns.adoc +++ b/docs/topics/rules-development/yaml-condition-patterns.adoc @@ -7,9 +7,9 @@ = Condition patterns [role="_abstract"] -The Language Server used by the Java provider is Eclipse's JDTLS. Internally, the JDTLS uses the Eclipse Java Development Toolkit, which includes utilities for searching code in projects. +In the `pattern` field of a `java.referenced` condition, the analyzer can search through application code by using the Java Development Kit (JDK) utilities. You can use a wildcard or a specific string to locate classes and methods to refine what the analyzer searches for in the source code. -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)`. +For more details on the JDK utilities, see Class SearchPattern documentation, which contains all the information for building these patterns for `createPattern(String, int, int, int)`. Review the following examples of condition patterns: @@ -49,3 +49,7 @@ java.referenced: location: IMPLEMENTS_TYPE pattern: java.util.List ---- + +.Additional resources + +* 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] \ No newline at end of file diff --git a/docs/topics/rules-development/yaml-custom-variables.adoc b/docs/topics/rules-development/yaml-custom-variables.adoc index 8e8f1665..b4ecc700 100644 --- a/docs/topics/rules-development/yaml-custom-variables.adoc +++ b/docs/topics/rules-development/yaml-custom-variables.adoc @@ -7,7 +7,9 @@ = Custom variables [role="_abstract"] -Provider conditions can have associated custom variables. You can use custom variables to capture relevant information from the matched line in the source code. The values of these variables are interpolated with data matched in the source code. These values can be used to generate detailed template messages in a rule's action (see xref:yaml-message-actions_rule-yaml-actions[Message actions]). They can be added to a rule in the `customVariables` field: +You can create custom variables in provider conditions. You can use custom variables to capture relevant information from a line in the source code that violates the rule. {ProductShortName} interpolates the values of these variables with the piece of data in the source code. You can add variables to a rule in the `customVariables` field. + +You can use the custom variable values to generate detailed template messages in a rule's action (see xref:yaml-message-actions_rule-yaml-actions[Message actions]). [source,yaml] ---- @@ -24,6 +26,6 @@ Provider conditions can have associated custom variables. You can use custom var ---- where: - `pattern` :: A regular expression pattern that is matched on the source code line when a match is found. + `pattern` :: A regular expression pattern that {ProductShortName} uses to find a match on the source code line. `name` :: The name of the variable that can be used in templates. `message` :: A template for a message by using a custom variable. diff --git a/docs/topics/rules-development/yaml-dotnet-provider.adoc b/docs/topics/rules-development/yaml-dotnet-provider.adoc index 74f49db8..155be0d4 100644 --- a/docs/topics/rules-development/yaml-dotnet-provider.adoc +++ b/docs/topics/rules-development/yaml-dotnet-provider.adoc @@ -2,18 +2,18 @@ // // * docs/rules-development-guide/master.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="yaml-dotnet-provider_{context}"] -= Csharp provider += C# provider [role="_abstract"] -The `csharp` provider is an external provider used to analyze `.NET Core` and `C#` source code. Currently, the provider supports the `referenced` capability. +The `C#` provider can analyze `.NET` and `C#` application source code. by using the `referenced` capability. The `C#` provider uses a gRPC interface to perform a semantic analysis of an application source code in the `source-only` mode. -The `csharp` provider uses a gRPC interface to perform a semantic analysis of an application source code in the `source-only` mode. The provider parses the source code by using tree-sitter and uses stack graph for the analysis to find references to types, methods, classes, and fields. Based on the custom rule definition, the analyzer identifies violations in your code that you must resolve before the application migration. +The provider parses the source code by using tree-sitter and uses stack graph for the analysis to find references to types, methods, classes, and fields. Based on the custom rule definition, the analyzer identifies violations in the source code that Migrators must resolve before the application migration. -== `referenced` +`referenced`:: -The `csharp` provider supports the `referenced` capability in rules to define fields such as `pattern` and `location`. The provider uses these patterns to search the source code for violations. +The `C#` provider supports the `referenced` capability in rules to define fields such as `pattern` and `location`. The provider uses these patterns to search the source code for violations. [source,yaml] ---- diff --git a/docs/topics/rules-development/yaml-go-provider.adoc b/docs/topics/rules-development/yaml-go-provider.adoc index 8c222278..ab290ba4 100644 --- a/docs/topics/rules-development/yaml-go-provider.adoc +++ b/docs/topics/rules-development/yaml-go-provider.adoc @@ -7,7 +7,7 @@ = Go provider [role="_abstract"] -The `go` provider analyzes `Go` source code. This provider's capabilities are `referenced` and `dependency`. +The `go` provider offers `referenced` and `dependency` capabilities to analyze `Go` source code. `referenced`:: By using the `referenced` capability, the provider finds references in the source code. diff --git a/docs/topics/rules-development/yaml-java-locations.adoc b/docs/topics/rules-development/yaml-java-locations.adoc index 139f9935..737a12e2 100644 --- a/docs/topics/rules-development/yaml-java-locations.adoc +++ b/docs/topics/rules-development/yaml-java-locations.adoc @@ -8,10 +8,17 @@ = Java locations [role="_abstract"] -The `java` provider allows scoping the search down to certain source code locations. +By using the fields in the `referenced` capability that Java provider supports, you can enable the provider to scope the search down to certain source code locations. -* *IMPORT*: IMPORT allows for searches on class imports. It can either -be used with Fully Qualified Names (FQNs) or an asterisk to allow for wider matches: +You can use the `java.referenced` capability in the `when` condition of the `Java` rules to search for the following fields: + +* Locations such as the classes, methods, packages and so on +* Annotations +* Patterns + +.Example + +*IMPORT*: IMPORT allows for searches on class imports. You can use it either with Fully Qualified Names (FQNs) or an asterisk to allow for wider matches: [source,yaml] ---- @@ -60,7 +67,7 @@ public class Test { |=== |Location |Description |Rule condition example -|TYPE|Matches against all types, including classes, interfaces, enums, and annotation types that appear anywhere. +|`TYPE`|Matches against all types, including classes, interfaces, `enums`, and annotation types that appear anywhere. a|The following example looks for occurrences of `java.util.List`. [source, yaml] ---- @@ -69,7 +76,7 @@ a|The following example looks for occurrences of `java.util.List`. location: TYPE pattern: java.util.List ---- -|ANNOTATION|Matches against annotations. +|`ANNOTATION`|Matches against annotations. a|The following example matches the `@org.framework.Bean(url = "http://www.example.com")` annotation in the source code. [source, yaml] ---- @@ -82,7 +89,7 @@ when: - name: url value: "http://www.example.com" ---- -|IMPLEMENTS_TYPE|Matches against any type implementing the given type. +|`IMPLEMENTS_TYPE`|Matches against any type implementing the given type. a|The following example looks for a class that implements `java.util.ArrayList`. [source, yaml] ---- @@ -91,7 +98,7 @@ a|The following example looks for a class that implements `java.util.ArrayList`. location: IMPLEMENTS_TYPE pattern: java.util.ArrayList ---- -|RETURN_TYPE|Matches against a type being returned by a method. +|`RETURN_TYPE`|Matches against a type that a method returns. a|The following example searches for `@PersistenceContext` annotation for injecting data sources and `@Produces` annotation on the `EntityManager`. These annotations are not required when you target migrating the source code to `Quarkus`. [source, yaml] ---- @@ -102,8 +109,8 @@ when: annotated: pattern: javax.enterprise.inject.Produces ---- -|VARIABLE_DECLARATION|Matches against a type being declared as a variable -a|The following example searches for `QueueConnectionFactory` that was used to obtain a connection to JMS queues appearing as a variable declaration. Replace the string `QueueConnectionFactory` with `ConnectionFactory`. +|`VARIABLE_DECLARATION`|Matches against a type declared as a variable +a|The following example searches for `QueueConnectionFactory` appearing as a variable declaration. Replace the string `QueueConnectionFactory` with `ConnectionFactory`. [source, yaml] ---- when: @@ -111,10 +118,10 @@ when: location: VARIABLE_DECLARATION pattern: javax.jms.QueueConnectionFactory ---- -|FIELD|Matches against a type appearing in a field +|`FIELD`|Matches against a type appearing in a field declaration. It can be coupled with an annotation match happening on the field. See xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection] -a|The following example searches if `QueueConnectionFactory` appears in a field declaration and is used to obtain connection to JMS queues. Replace the string `QueueConnectionFactory` with `ConnectionFactory`. +a|The following example searches if `QueueConnectionFactory` appears in a field declaration. Replace the string `QueueConnectionFactory` with `ConnectionFactory`. [source, yaml] ---- when: @@ -122,8 +129,7 @@ when: location: FIELD_DECLARATION pattern: javax.jms.QueueConnectionFactory ---- -|METHOD|Matches against a given method declaration. It can be coupled -with an annotation match. See +|`METHOD`|Matches against a given method declaration. You can couple it with an annotation match. See xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection] a|The following example finds declarations of methods named `method` that accept `java.lang.String` and return `org.konveyor.ExtendedString`. @@ -134,7 +140,7 @@ when: location: METHOD pattern: 'method(java.lang.String) org.konveyor.ExtendedString' ---- -|METHOD_CALL|Matches against the method call in the source code. +|`METHOD_CALL`|Matches against the method call in the source code. a|The following example matches the `getConnection` method call of the `java.sql.DriverManager` class with three parameters of type `String`. [source, yaml] ---- @@ -143,7 +149,7 @@ when: location: METHOD_CALL pattern: java.sql.DriverManager.getConnection(java.lang.String, java.lang.String, java.lang.String) ---- -|CLASS (declaration)|Matches against a given method declaration. Can be coupled with an annotation match. See xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection]. +|`CLASS` (declaration)|Matches against a given class declaration. You can couple it with an annotation match. See xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection]. a|The following example locates all classes under the `javax.xml` package occurring in all locations of the source code. [source, yaml] ---- @@ -151,7 +157,7 @@ when: java.referenced: pattern: javax.xml.* ---- -|CONSTRUCTOR_CALL|Matches against constructor calls in the source code. +|`CONSTRUCTOR_CALL`|Matches against constructor calls in the source code. a|The following example matches the `FileOutputStream` constructor call that takes a String and a boolean value as input parameters. [source, yaml] ---- @@ -160,7 +166,7 @@ when: location: CONSTRUCTOR_CALL pattern: java.io.FileOutputStream(java.lang.String, boolean) ---- -|IMPORT|Matches against class imports. You can use it with FQNs or an asterisk (*) to allow for wider matches. +|`IMPORT`|Matches against class imports. You can use it with FQNs or an asterisk (*) to allow for wider matches. a|The following example matches with the imports of `org.apache.lucene.search` package and subpackages in the source code. [source, yaml] ---- @@ -169,7 +175,7 @@ when: pattern: org.apache.lucene.search.* location: IMPORT ---- -|PACKAGE|Matches on any usage of a package, be it in an import or used as part of a fully qualified name in the code. +|`PACKAGE`|Matches on any usage of a package, be it in an import or used as part of a fully qualified name in the code. a|The following example matches all occurrences of `org.jboss` package and its subpackages in the source code. [source, yaml] ---- @@ -178,7 +184,7 @@ when: location: PACKAGE pattern: org.jboss.* ---- -|INHERITANCE|Matches against a class inheriting from a given type. +|`INHERITANCE`|Matches against a class inheriting from a given type. a|The following example searches for interfaces that extend the `org.jboss.system.ServiceMBeanSupport` class. [source, yaml] diff --git a/docs/topics/rules-development/yaml-java-provider.adoc b/docs/topics/rules-development/yaml-java-provider.adoc index 92f5686f..1f449c51 100644 --- a/docs/topics/rules-development/yaml-java-provider.adoc +++ b/docs/topics/rules-development/yaml-java-provider.adoc @@ -2,17 +2,15 @@ // // * docs/rules-development-guide/master.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="yaml-java-provider_{context}"] = Java provider [role="_abstract"] -The `java` provider analyzes Java source code. - -This provider has the following capabilities: +The `java` provider offers `referenced` and `dependency` capabilities to analyze Java source code. `referenced`:: -By using the `referenced` capability, the provider finds references in the source code. This capability takes three input parameters: `pattern`, `location`, and `annotated`: +The `referenced` capability takes three input parameters: `pattern`, `location`, and `annotated`: + [source,terminal] ---- @@ -26,7 +24,7 @@ when: where: * `pattern` is a regular expression pattern to match. -* `location` is the exact location where the pattern needs to be matched, for example, `IMPORT`. +* `location` is the exact source code location where {ProductShortName} matches the pattern, 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] @@ -41,7 +39,7 @@ where: `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. +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 and external or open source. For example, to check if a Java application has a certain dependency, you create a `java.dependency` condition: + [source, yaml] @@ -69,4 +67,4 @@ When you use the `java` provider for an analysis, the analysis results have lowe [role="_additional-resources"] .Additional resources -* xref:java-conditions-capabilities[Java condition and capabilities] \ No newline at end of file +* xref:java-conditions-capabilities_rules-development-guide[Java condition and capabilities] \ No newline at end of file diff --git a/docs/topics/rules-development/yaml-message-actions.adoc b/docs/topics/rules-development/yaml-message-actions.adoc index 88a3f5ec..354dac9c 100644 --- a/docs/topics/rules-development/yaml-message-actions.adoc +++ b/docs/topics/rules-development/yaml-message-actions.adoc @@ -7,7 +7,7 @@ = Message action [role="_abstract"] -A message action is used to generate an issue with the specified message when a rule condition matches the source code, for example: +{ProductFullName} uses a message action to generate an issue with the specified message when a rule condition matches the source code. [source,yaml] ---- @@ -26,8 +26,7 @@ links: title: "Short title for the link" ---- -You can also create a template message to include information about the match that has been interpolated through xref:yaml-custom-variables_logical-chaining-custom-variables[custom variables] in the rule. -// link link:#custom-variables[Custom Variables]): +You can also create a template message to include information about the match by using custom variables in the rule. [source,yaml] ---- @@ -39,3 +38,6 @@ You can also create a template message to include information about the match th when: ---- + +.Additional resources +* xref:yaml-custom-variables_logical-chaining-custom-variables[custom variables] \ No newline at end of file diff --git a/docs/topics/rules-development/yaml-nested-condition.adoc b/docs/topics/rules-development/yaml-nested-condition.adoc index bebdf0c4..6b7b3986 100644 --- a/docs/topics/rules-development/yaml-nested-condition.adoc +++ b/docs/topics/rules-development/yaml-nested-condition.adoc @@ -7,7 +7,7 @@ = Nested conditions [role="_abstract"] -Conditions can also be nested within other conditions. +As an Architect, you can create nested conditions in a rule to make the analyzer evaluate different levels of conditions. You can combine the logical `and` and `or` conditions in a nested condition. [source,yaml] ---- diff --git a/docs/topics/rules-development/yaml-or-condition.adoc b/docs/topics/rules-development/yaml-or-condition.adoc index 1be35f48..593fd4ea 100644 --- a/docs/topics/rules-development/yaml-or-condition.adoc +++ b/docs/topics/rules-development/yaml-or-condition.adoc @@ -2,7 +2,7 @@ // // * docs/rules-development-guide/master.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="yaml-or-condition_{context}"] = OR condition diff --git a/docs/topics/rules-development/yaml-provider-conditions.adoc b/docs/topics/rules-development/yaml-provider-conditions.adoc index 29fd84b4..4a84b646 100644 --- a/docs/topics/rules-development/yaml-provider-conditions.adoc +++ b/docs/topics/rules-development/yaml-provider-conditions.adoc @@ -4,14 +4,12 @@ :_mod-docs-content-type: REFERENCE [id="yaml-provider-conditions_{context}"] -= Provider condition += Rule condition [role="_abstract"] -The analyzer engine enables multi-language source code analysis by using *providers*. The source code of a technology is analyzed by the provider. +In the rule condition, the Architect defines the patterns that {ProductShortName} searches for in the source code to trigger an issue. The condition you can define to search an application written in a programming language depends on the capabilities that providers offer. -The provider publishes what they can do with the source code in terms of capabilities. - -The provider condition instructs the analyzer to use a specific provider and one of its capabilities. In general, it follows the `.` pattern. +A rule condition instructs the analyzer to use a specific provider and one of its capabilities. A condition follows the `.` pattern. [source,terminal] ---- @@ -20,7 +18,7 @@ when: ---- -The analyzer currently supports the following `provider` conditions: +The analyzer currently supports the following providers: * `builtin` * `java` @@ -29,11 +27,11 @@ The analyzer currently supports the following `provider` conditions: * `python` * `csharp` -:FeatureName: csharp, python, and nodejs providers +:FeatureName: `csharp`, `python`, and `nodejs` providers [IMPORTANT] ==== [subs="attributes+"] -{FeatureName} are Developer Preview features 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. +{FeatureName} are Developer Preview features 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 Service Level Agreement (SLA). ==== :!FeatureName: @@ -59,14 +57,6 @@ a| * `csharp` |=== -//Some providers have *dependency_ capability*. The dependency_capability means that the provider generates 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. - -//For example, to check if a Java application has a certain dependency, you create a `java.dependency` condition: - - The following table summarizes all the providers and their capabilities: @@ -76,7 +66,7 @@ capabilities: |Provider Name |Capabilities |Description .2+|`java` -|referenced +|`referenced` a|Find references of a pattern with an optional code location for detailed searches. For example, [source,yaml] @@ -85,7 +75,7 @@ when: java.referenced: ---- -|dependency +|`dependency` a|Check whether the application has a given dependency. For example, @@ -97,12 +87,12 @@ when: ---- .5+|`builtin` -|xml -|Search XML files using xpath queries. +|`xml` +|Search XML files using XPath queries. -|json -a|Search JSON files using `jsonpath` queries. +|`json` +a|Search JSON files using JSONPath queries. For example, [source, yaml] ---- @@ -111,7 +101,7 @@ when: ---- -|filecontent +|`filecontent` a|Search content in regular files using regular expression patterns. For example, [source, yaml] @@ -122,7 +112,7 @@ when: ---- -|file +|`file` a|Find files with names matching a given pattern. For example, [source, yaml] @@ -132,8 +122,8 @@ when: ---- -|hasTags -a|Check whether a tag is created for the application using a tagging rule. +|`hasTags` +a|Check whether you created a tag for the application using a tagging rule. For example, [source, yaml] ---- @@ -143,7 +133,7 @@ when: ---- .2+|`go` -|referenced +|`referenced` a|Find references to a pattern. For example, [source,yaml] @@ -153,7 +143,7 @@ when: ---- -|dependency +|`dependency` a|Check whether the application has a given dependency. For example, [source,yaml] @@ -164,7 +154,7 @@ when: ---- |`csharp` -|referenced +|`referenced` a|Find references to a pattern. For example, [source,yaml] @@ -193,16 +183,16 @@ when: Depending on the _provider_ and the _capability_, there will be different `` in the condition. ==== -The following table summarizes available providers, their capabilities and all of their fields: +The following table summarizes available providers, their capabilities and their fields: .Summary of providers, their capabilities, and their fields [width="100%",cols="10%,10%,10%,10%,60%",options="header",] |=== |Provider |Capability |Fields |Required |Description -.7+|xref:yaml-java-provider_rules-prov-cond[java] -.3+|referenced -|pattern +.7+|xref:yaml-java-provider_rules-prov-cond[`java`] +.3+|`referenced` +|`pattern` |Yes a|Regular expression pattern. For example, @@ -214,7 +204,7 @@ when: pattern: org.jboss.* ---- -|location +|`location` |No a|Source code location. See xref:yaml-java-locations_java-conditions-capabilities[Java locations]. For example, @@ -226,7 +216,7 @@ when: location: IMPORT ---- -|annotated +|`annotated` |No a|Additional query to inspect annotations. See xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection]. For example, @@ -238,8 +228,8 @@ when: pattern: javax.ejb.Singleton ---- -.4+|dependency -|name +.4+|`dependency` +|`name` |Yes a|Name of the dependency. For example, @@ -250,11 +240,11 @@ when: name: junit.junit ---- -|nameregex +|`nameregex` |No |Regular expression pattern to match the name. -|upperbound +|`upperbound` |No a|Match versions lower than or equal to. For example, @@ -266,7 +256,7 @@ when: upperbound: 4.12.2 ---- -|lowerbound +|`lowerbound` |No a|Match versions greater than or equal to. For example, @@ -279,11 +269,11 @@ when: lowerbound: 4.4.0 ---- -.9+|xref:yaml-builtin-provider_rules-prov-cond[builtin] -.3+|xml -|xpath +.9+|xref:yaml-builtin-provider_rules-prov-cond[`builtin`] +.3+|`xml` +|`xpath` |Yes -a|Xpath query +a|an XPath query [source, yaml] ---- when: @@ -291,7 +281,7 @@ when: xpath: "//dependencies/dependency" ---- -|namespaces +|`namespaces` |No a|A map to scope down query to namespaces. [source, yaml] @@ -305,7 +295,7 @@ when: xpath: /b:beans ---- -|filepaths +|`filepaths` |No a|Optional list of files to scope down search. [source, yaml] @@ -322,10 +312,10 @@ when: ignore: true ---- -.2+|json -|xpath +.2+|`json` +|`xpath` |Yes -a|Xpath query +a|an XPath query For example, [source, yaml] ---- @@ -335,7 +325,7 @@ when: xpath: //inclusionTestNode ---- -|filepaths +|`filepaths` |No a|Optional list of files to scope down search. For example, @@ -348,8 +338,8 @@ when: filepaths: "{{incTest.filepaths}}" ---- -.2+|filecontent -|pattern +.2+|`filecontent` +|`pattern` |Yes a|Regular expression pattern to match in content. For example, @@ -361,7 +351,7 @@ when: pattern: "import.*React" ---- -|filePattern +|`filePattern` |No a|Only search in files with names matching this pattern. For example, @@ -374,8 +364,8 @@ when: filePattern: "\\.tsx$" ---- -|file -|pattern +|`file` +|`pattern` |Yes a|Find files with names matching this pattern. For example, @@ -386,7 +376,7 @@ when: pattern: "*.go" ---- -|hasTags +|`hasTags` | | a|This is an inline list of string tags. See xref:yaml-tag-actions_rule-yaml-actions[Tag action] @@ -401,9 +391,9 @@ when: - Kubernetes ---- -.5+|xref:yaml-go-provider_rules-prov-cond[go] -|referenced -|pattern +.5+|xref:yaml-go-provider_rules-prov-cond[`go`] +|`referenced` +|`pattern` |Yes a|Regular expression pattern. For example, @@ -414,8 +404,8 @@ when: pattern: "v1beta1.CustomResourceDefinition" ---- -.4+|dependency -|name +.4+|`dependency` +|`name` |Yes a|Name of the dependency. For example, @@ -426,11 +416,11 @@ when: name: sigs.k8s.io/structured-merge-diff/v4 ---- -|nameregex +|`nameregex` |No |Regular expression pattern to match the name. -|upperbound +|`upperbound` |No a|Match versions lower than or equal to. For example, @@ -442,7 +432,7 @@ when: upperbound: v4.2.2 ---- -|lowerbound +|`lowerbound` |No a|Match versions greater than or equal to. For example, @@ -454,13 +444,13 @@ when: lowerbound: v4.2.0 ---- -.2+|xref:yaml-dotnet-provider_rules-prov-cond[Csharp] -.2+|referenced -|pattern +.2+|xref:yaml-dotnet-provider_rules-prov-cond[`csharp`] +.2+|`referenced` +|`pattern` |Yes |Regular expression to match a reference in the source code. For example, `System.Web.Mvc.*`. -|location +|`location` |Yes a|Specify one of the following for which {ProductShortName} runs a search query: diff --git a/docs/topics/rules-development/yaml-rule-categories.adoc b/docs/topics/rules-development/yaml-rule-categories.adoc index fb5523c1..aa768413 100644 --- a/docs/topics/rules-development/yaml-rule-categories.adoc +++ b/docs/topics/rules-development/yaml-rule-categories.adoc @@ -2,15 +2,15 @@ // // * docs/rules-development-guide/master.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="yaml-rule-categories_{context}"] = Rule categories [role="_abstract"] -Rule categories are applied per rule. The Architect assigns one of the following rule categories to indicate the risk associated with not resolving an issue. +{ProductFullName} applies rule categories per rule. The Architect assigns one of the following rule categories to indicate the risk associated with not resolving an issue. * `mandatory`: You must resolve the issue for a successful migration. If you do not make the changes, the resulting application will not build or run successfully. Examples include the replacement of proprietary APIs that are not supported in the target platform. -* `optional`: If you do not resolve the issue, the application should work, but the results might not be optimal. If you do not make the change at the time of migration, it is recommended to include it on the schedule soon after your migration is completed. +* `optional`: If you do not resolve the issue, the application should work, but the results might not be optimal. If you do not make the change at the time of migration, it is recommended that you include it on the schedule soon after you complete the migration. * `potential`: You need to examine the issue during the migration process, but there is not enough detailed information to determine if the task is mandatory for the migration to succeed. An example of such an issue is migrating a third-party proprietary type when there is no directly compatible type on the target platform. diff --git a/docs/topics/rules-development/yaml-rule-condition-complexity.adoc b/docs/topics/rules-development/yaml-rule-condition-complexity.adoc new file mode 100644 index 00000000..de5e5a5d --- /dev/null +++ b/docs/topics/rules-development/yaml-rule-condition-complexity.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: CONCEPT +[id="rule-condition-complexity_{context}"] += Rule condition complexity + +[role="_abstract"] +You can create complex rules to combine conditions, use the output of one rule as an input to another, and chain conditions. + +* Logical conditions inform the provider how to handle more than one condition in a when block. The analyzer provides the logical conditions, `and` and `or`, that you can use to combine results of many conditions. +* Condition chaining uses the output of one condition as the input in another condition of the when block. Assign the output to a variable in one condition and reuse it in other conditions in the when block. +* Nested conditions create conditions that depend on the evaluation of other conditions. +* Custom variables capture specific information from the code. You can use the custom variable in the message displayed for the code if it contains a violation defined by the rule. diff --git a/docs/topics/rules-development/yaml-rule-conditions.adoc b/docs/topics/rules-development/yaml-rule-conditions.adoc deleted file mode 100644 index 1226b9dc..00000000 --- a/docs/topics/rules-development/yaml-rule-conditions.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/rules-development-guide/master.adoc - -:_mod-docs-content-type: REFERENCE -[id="yaml-rule-conditions_{context}"] -= Rule conditions - -[role="_abstract"] -{ProductShortName} supports the following types of conditions: - -* `provider` -* `and` -* `or` diff --git a/docs/topics/rules-development/yaml-rule-hyperlinks.adoc b/docs/topics/rules-development/yaml-rule-hyperlinks.adoc index 52819200..72387413 100644 --- a/docs/topics/rules-development/yaml-rule-hyperlinks.adoc +++ b/docs/topics/rules-development/yaml-rule-hyperlinks.adoc @@ -7,12 +7,10 @@ = Hyperlinks [role="_abstract"] -Hyperlinks can be provided along with a `message` or `tag` action to provide relevant information about the issue that has been discovered: +As a rule author, you can configure external hyperlinks along with a `message` or `tag` action. Hyperlinks provide relevant documentation that helps you to resolve the issue that {ProductShortName} discovered: [source,yaml] ---- -# links point to external hyperlinks -# rule authors are expected to provide # relevant hyperlinks for quick fixes, docs, and so on. links:   - url: "konveyor.io" diff --git a/docs/topics/rules-development/yaml-rule-labels.adoc b/docs/topics/rules-development/yaml-rule-labels.adoc index b4011de9..ff9bc216 100644 --- a/docs/topics/rules-development/yaml-rule-labels.adoc +++ b/docs/topics/rules-development/yaml-rule-labels.adoc @@ -1,6 +1,6 @@ :_newdoc-version: 2.18.5 :_template-generated: 2025-12-05 -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="yaml-rule-labels_{context}"] = Rule labels @@ -13,7 +13,7 @@ For dependencies, a provider adds the labels to the dependencies when retrieving Label format:: -Labels are specified under the `labels` field as a list of strings in `key=val` format as follows: +You can enter Labels under the `labels` field as a list of strings in `key=val` format as follows: [source,yaml] ---- @@ -38,7 +38,7 @@ labels: - "konveyor.io/key=" ---- -The value of a label can be omitted. In that case, it is treated as an empty value: +You can omit the value of a label. In that case, {ProductShortName} treats it as an empty value: [source,yaml] ---- diff --git a/docs/topics/rules-development/yaml-rule-metadata.adoc b/docs/topics/rules-development/yaml-rule-metadata.adoc index fd81db11..1fca14dc 100644 --- a/docs/topics/rules-development/yaml-rule-metadata.adoc +++ b/docs/topics/rules-development/yaml-rule-metadata.adoc @@ -8,7 +8,14 @@ = Rule metadata structure [role="_abstract"] -Rule metadata contains a unique rule ID, labels, effort, and category. +In rule metadata, define a unique rule ID, labels, effort, and category so that the analyzer can select the rules for an analysis and compute the total effort to resolve the issues detected in the source code. + +You can use rule metadata to: + +* Estimate the total migration effort. +* Prioritize issues for resolution based on the effort. +* Evaluate if a resolution is mandatory through rule category before migrating the applications to the target technologies or platforms. +* Define labels that {ProductShortName} uses to filter rules for an analysis. [source,yaml] ---- diff --git a/docs/topics/rules-development/yaml-rule-structure-syntax.adoc b/docs/topics/rules-development/yaml-rule-structure-syntax.adoc index 3fd9d329..81e95781 100644 --- a/docs/topics/rules-development/yaml-rule-structure-syntax.adoc +++ b/docs/topics/rules-development/yaml-rule-structure-syntax.adoc @@ -9,7 +9,7 @@ [role="_abstract"] Rules instruct the analyzer to take the specified actions when the given conditions match. In {ProductShortName}, a rule file contains one or more rules. -Rules are written in YAML. They consist of: +You can write rules in YAML. They consist of: * metadata * conditions @@ -19,11 +19,18 @@ Rules are written in YAML. They consist of: [source, yaml] ---- -ruleID: -labels: -category: -effort: +ruleID: +category: mandatory +effort: description: + + +labels: + - konveyor.io/source= + - konveyor.io/target= +links: + - url: + title: when: message: "message" @@ -31,3 +38,10 @@ tag: - tag_1, tag_2, tag_3 - key_1="value_1, value_2" ---- +where: + +`ruleID` :: A unique id for the rule within the ruleset +`category` :: Severity level of an issue that the rule triggers can be `severe`, `mandatory`, or `optional`. +`effort` :: An integer value that represents the level of effort needed to fix the issue. +`description` :: A short sentence or a title that summarizes the issue. +`labels` :: diff --git a/docs/topics/rules-development/yaml-rulesets.adoc b/docs/topics/rules-development/yaml-rulesets.adoc index 3068b22e..3c243013 100644 --- a/docs/topics/rules-development/yaml-rulesets.adoc +++ b/docs/topics/rules-development/yaml-rulesets.adoc @@ -7,9 +7,12 @@ = Creating and using a custom ruleset [role="_abstract"] -You can create a ruleset by placing one or more custom rules in a directory and creating a `ruleset.yaml` file at the directory root. When you perform an analysis, you pass this directory as input to the {ProductShortName} {CLIName} by using the `--rules` option. All rules in this directory are treated as a part of the ruleset defined by the `ruleset.yaml` file. +You can create a ruleset by placing one or more custom rules in a directory and creating a `ruleset.yaml` file at the directory root. When you perform an analysis, you pass this directory as input to the {ProductShortName} {CLIName} by using the `--rules` option. {ProductShortName} treats all rules in this directory as a part of the ruleset defined by the `ruleset.yaml` file. -The `ruleset.yaml` file stores the metadata of the ruleset. You can group multiple similar custom rules and create a ruleset for them. When you pass this directory as input to the {ProductShortName} {CLIName} using the `--rules` option, {ProductShortName} treats all the files in the directory as belonging to the ruleset defined in the `ruleset.yaml` file. +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. [source,yaml] ---- @@ -23,7 +26,7 @@ where: `name` :: The name must be unique within the provided rulesets. `labels` :: Ruleset labels are inherited by all rules that belong to the ruleset. -To perform any application analysis, enter: +To perform any application analysis: [source,terminal] ---- @@ -33,7 +36,10 @@ $ mta-cli analyze --input= --output= --rules * Replace `` with the name of your application. * Replace `` with the directory of your choice. * Replace `` with the custom rule file. -* 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. +* To use multiple rule files, place them in a directory and add a `ruleset.yaml` file. Then {ProductShortName} treats the directory 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 analyzer will only select rules that match the label for that target. Therefore, make sure that you have added target or source labels in your rules. See xref:reserved-label_rule-yaml-metadata[Reserved labels] for more details. +Note that if you want to use the `--target` or `--source` option in the CLI, the analyzer will only select rules that match the label for that target. Therefore, make sure that you have added reserved labels in your rules. + +.Additional resources +* xref:reserved-label_rule-yaml-metadata[Reserved labels] for more details. diff --git a/docs/topics/rules-development/yaml-tag-actions.adoc b/docs/topics/rules-development/yaml-tag-actions.adoc index 69733f68..87192870 100644 --- a/docs/topics/rules-development/yaml-tag-actions.adoc +++ b/docs/topics/rules-development/yaml-tag-actions.adoc @@ -7,7 +7,7 @@ = Tag actions [role="_abstract"] -A tag action instructs the analyzer to generate one or more tags for the application when a match is found. Each string in the `tag` field can be a comma-separated list of tags. Optionally, you can assign categories to tags. +A tag action instructs the analyzer to generate one or more tags for the application when it finds a match. Each string in the `tag` field can be a comma-separated list of tags. Optionally, you can assign categories to tags. [source,yaml] ---- @@ -29,7 +29,7 @@ _Example_ - Source Code ---- -A tag can be a string or a `key=val` pair, where the key is treated as a tag category in {ProductShortName}. Any rule that has a tag action is referred to as a “tagging rule” in this document. +A tag can be a string or a `key=val` pair, where {ProductShortName} treats the key as a tag category. You can consider any rule that has a tag action as a “tagging rule” in this document. [NOTE] ==== diff --git a/docs/topics/templates/document-attributes.adoc b/docs/topics/templates/document-attributes.adoc index d33554bc..86b7cd97 100644 --- a/docs/topics/templates/document-attributes.adoc +++ b/docs/topics/templates/document-attributes.adoc @@ -18,7 +18,7 @@ ifdef::mta[] :DocInfoProductNumber: 8.1 :ProductShortName: MTA :ProductShortNameLower: mta -:ProductFullName: migration toolkit for applications (MTA) +:ProductFullName: Migration toolkit for applications (MTA) :ProductFirstRef: Migration toolkit for applications :LC_PSN: mta :mta-cli: mta-cli From a0f1478f2d5cfc389a14292b6f0dc14669c910c7 Mon Sep 17 00:00:00 2001 From: Prabha Kylasamiyer Sundara Rajan Date: Mon, 25 May 2026 17:26:17 +0530 Subject: [PATCH 2/4] Added label definition in call out Signed-off-by: Prabha Kylasamiyer Sundara Rajan --- docs/topics/rules-development/yaml-rule-structure-syntax.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/rules-development/yaml-rule-structure-syntax.adoc b/docs/topics/rules-development/yaml-rule-structure-syntax.adoc index 81e95781..659fd64d 100644 --- a/docs/topics/rules-development/yaml-rule-structure-syntax.adoc +++ b/docs/topics/rules-development/yaml-rule-structure-syntax.adoc @@ -44,4 +44,4 @@ where: `category` :: Severity level of an issue that the rule triggers can be `severe`, `mandatory`, or `optional`. `effort` :: An integer value that represents the level of effort needed to fix the issue. `description` :: A short sentence or a title that summarizes the issue. -`labels` :: +`labels` :: A key-value pair of source and target technology. You can also add filter in the label to always include or exclude this rule during an analysis. From 9fc21eca38d5093263cf74cb771b68adb98525a5 Mon Sep 17 00:00:00 2001 From: Prabha Kylasamiyer Sundara Rajan Date: Tue, 26 May 2026 13:49:37 +0530 Subject: [PATCH 3/4] Made formatting changes Signed-off-by: Prabha Kylasamiyer Sundara Rajan --- .../assembly_rule-yaml-metadata.adoc | 1 - ...n_provider-capability-in-custom-rules.adoc | 7 +- .../create-first-yaml-rule.adoc | 6 +- .../rules-development/yaml-and-condition.adoc | 6 +- .../yaml-annotation-inspection.adoc | 1 + .../yaml-chaining-condition-variables.adoc | 1 + .../yaml-custom-variables.adoc | 6 +- .../yaml-java-locations.adoc | 14 ++-- .../yaml-message-actions.adoc | 8 +-- .../rules-development/yaml-or-condition.adoc | 6 +- .../yaml-provider-conditions.adoc | 71 +++++++++++-------- .../yaml-rule-categories.adoc | 2 +- .../rules-development/yaml-rule-labels.adoc | 53 ++++++++++---- .../rules-development/yaml-rule-metadata.adoc | 8 +-- .../yaml-rule-structure-syntax.adoc | 22 +++--- .../rules-development/yaml-rulesets.adoc | 14 ++-- .../rules-development/yaml-tag-actions.adoc | 10 +-- 17 files changed, 139 insertions(+), 97 deletions(-) diff --git a/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc b/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc index 3b1534f0..c725b821 100644 --- a/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc +++ b/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc @@ -18,7 +18,6 @@ endif::[] [role="_abstract"] As an Architect, you include information about effort in the rule metadata. Effort is a numerical value that accounts for the complexity in resolving the issue described in the rule. In the metadata, you can add category and label that guides Migrators when they resolve issues in the code. - include::topics/rules-development/yaml-rule-metadata.adoc[leveloffset=+1] include::topics/rules-development/yaml-rule-labels.adoc[leveloffset=+1] 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 index fb07462f..597f98af 100644 --- a/docs/topics/rules-development/con_provider-capability-in-custom-rules.adoc +++ b/docs/topics/rules-development/con_provider-capability-in-custom-rules.adoc @@ -6,13 +6,14 @@ = Provider capabilities in custom rules [role="_abstract"] -As an Architect, you define conditions and patterns in custom rules that {ProductShortName} uses to match against the source code and dependencies in an analysis. You can specify the conditions in the `when` block of the rule. Each provider offers capabilities to match rule patterns. +As an Architect, you define conditions and patterns in custom rules that {ProductShortName} uses to match against the source code and dependencies in an analysis. You can specify the conditions in the `when` block of the rule. You can use capabilities available in each provider to match rule patterns. The `when` block contains a single condition, but that condition might have one or more conditions nested under it. +[subs="+quotes"] ---- when: - - + __ + __ ---- diff --git a/docs/topics/rules-development/create-first-yaml-rule.adoc b/docs/topics/rules-development/create-first-yaml-rule.adoc index 2647edfa..db4a1ebd 100644 --- a/docs/topics/rules-development/create-first-yaml-rule.adoc +++ b/docs/topics/rules-development/create-first-yaml-rule.adoc @@ -153,17 +153,13 @@ To verify that the rule works: mta-cli analyze --input /home//data/ --output /home//output/ --rules /home//rules.yaml ---- -. Review the report to be sure that it provides the expected results. -+ - -Once the analysis is complete, the command outputs the path to the HTML report: +. Open `/home//output/static-report/index.html` in a web browser. + [options="nowrap",subs="attributes+"] ---- INFO[0066] Static report created. Access it at this URL: URL="file:/home//output/static-report/index.html" ---- + -Open `/home//output/static-report/index.html` in a web browser. . Navigate to the *Issues* tab in the left menu. . In the *Issues* table, type `JBoss XML` in the search bar. . Verify that the issue with the title `Find class loading element in JBoss XML file` is present in the table. diff --git a/docs/topics/rules-development/yaml-and-condition.adoc b/docs/topics/rules-development/yaml-and-condition.adoc index b4563b75..cd93cd25 100644 --- a/docs/topics/rules-development/yaml-and-condition.adoc +++ b/docs/topics/rules-development/yaml-and-condition.adoc @@ -9,12 +9,12 @@ [role="_abstract"] The `and` condition performs a logical AND operation on the results of an array of conditions. The condition matches when _all_ of its child conditions match, for example: -[source,yaml] +[source,yaml, subs="+quotes"] ---- when: and: - - - - + - __ + - __ ---- For an example rule condition, see: diff --git a/docs/topics/rules-development/yaml-annotation-inspection.adoc b/docs/topics/rules-development/yaml-annotation-inspection.adoc index 4b0eb900..5d1e1506 100644 --- a/docs/topics/rules-development/yaml-annotation-inspection.adoc +++ b/docs/topics/rules-development/yaml-annotation-inspection.adoc @@ -65,6 +65,7 @@ when: - name: url value: "http://www.example.com" ---- + [NOTE] ==== The only element specified with a `pattern` is the annotation itself. diff --git a/docs/topics/rules-development/yaml-chaining-condition-variables.adoc b/docs/topics/rules-development/yaml-chaining-condition-variables.adoc index dd4d763b..23c5b47b 100644 --- a/docs/topics/rules-development/yaml-chaining-condition-variables.adoc +++ b/docs/topics/rules-development/yaml-chaining-condition-variables.adoc @@ -69,5 +69,6 @@ This will tell the engine not to use this condition to find a rule violation: ---- ==== +[role="_additional-resources"] .Additional resources * link:https://mustache.github.io/mustache.5.html[Mustache templates] \ No newline at end of file diff --git a/docs/topics/rules-development/yaml-custom-variables.adoc b/docs/topics/rules-development/yaml-custom-variables.adoc index b4ecc700..5859ca24 100644 --- a/docs/topics/rules-development/yaml-custom-variables.adoc +++ b/docs/topics/rules-development/yaml-custom-variables.adoc @@ -9,7 +9,7 @@ [role="_abstract"] You can create custom variables in provider conditions. You can use custom variables to capture relevant information from a line in the source code that violates the rule. {ProductShortName} interpolates the values of these variables with the piece of data in the source code. You can add variables to a rule in the `customVariables` field. -You can use the custom variable values to generate detailed template messages in a rule's action (see xref:yaml-message-actions_rule-yaml-actions[Message actions]). +You can use the custom variable values to generate detailed template messages in a rule's action (see Message actions). [source,yaml] ---- @@ -29,3 +29,7 @@ where: `pattern` :: A regular expression pattern that {ProductShortName} uses to find a match on the source code line. `name` :: The name of the variable that can be used in templates. `message` :: A template for a message by using a custom variable. + +[role="_additional-resources"] +.Additional resources +* xref:yaml-message-actions_rule-yaml-actions[Message actions] \ No newline at end of file diff --git a/docs/topics/rules-development/yaml-java-locations.adoc b/docs/topics/rules-development/yaml-java-locations.adoc index 737a12e2..55f9bbb2 100644 --- a/docs/topics/rules-development/yaml-java-locations.adoc +++ b/docs/topics/rules-development/yaml-java-locations.adoc @@ -119,8 +119,7 @@ when: pattern: javax.jms.QueueConnectionFactory ---- |`FIELD`|Matches against a type appearing in a field -declaration. It can be coupled with an annotation match happening on the field. See -xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection] +declaration. It can be coupled with an annotation match happening on the field. See Annotation inspection. a|The following example searches if `QueueConnectionFactory` appears in a field declaration. Replace the string `QueueConnectionFactory` with `ConnectionFactory`. [source, yaml] ---- @@ -129,8 +128,7 @@ when: location: FIELD_DECLARATION pattern: javax.jms.QueueConnectionFactory ---- -|`METHOD`|Matches against a given method declaration. You can couple it with an annotation match. See -xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection] +|`METHOD`|Matches against a given method declaration. You can couple it with an annotation match. See Annotation inspection. a|The following example finds declarations of methods named `method` that accept `java.lang.String` and return `org.konveyor.ExtendedString`. [source, yaml] @@ -149,7 +147,7 @@ when: location: METHOD_CALL pattern: java.sql.DriverManager.getConnection(java.lang.String, java.lang.String, java.lang.String) ---- -|`CLASS` (declaration)|Matches against a given class declaration. You can couple it with an annotation match. See xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection]. +|`CLASS` (declaration)|Matches against a given class declaration. You can couple it with an annotation match. See Annotation inspection. a|The following example locates all classes under the `javax.xml` package occurring in all locations of the source code. [source, yaml] ---- @@ -194,4 +192,8 @@ a|The following example searches for interfaces that extend the `org.jboss.syste pattern: 'org.jboss.system.ServiceMBeanSupport' location: INHERITANCE ---- -|=== \ No newline at end of file +|=== + +[role="_additional-resources"] +.Additional resources +* xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection] \ No newline at end of file diff --git a/docs/topics/rules-development/yaml-message-actions.adoc b/docs/topics/rules-development/yaml-message-actions.adoc index 354dac9c..339ebe8d 100644 --- a/docs/topics/rules-development/yaml-message-actions.adoc +++ b/docs/topics/rules-development/yaml-message-actions.adoc @@ -9,12 +9,12 @@ [role="_abstract"] {ProductFullName} uses a message action to generate an issue with the specified message when a rule condition matches the source code. -[source,yaml] +[source,yaml, subs="+quotes"] ---- - ruleID: test-rule message: Test rule matched. Please resolve this migration issue. when: - + __ ---- Optionally, a message can include hyperlinks to external URLs that provide relevant information about the issue or a quick fix. @@ -28,7 +28,7 @@ links: You can also create a template message to include information about the match by using custom variables in the rule. -[source,yaml] +[source,yaml, subs="+quotes"] ---- - ruleID: lang-ref-004 customVariables: @@ -36,7 +36,7 @@ You can also create a template message to include information about the match by name: VariableName message: "Found generic call - {{ VariableName }}" when: - + __ ---- .Additional resources diff --git a/docs/topics/rules-development/yaml-or-condition.adoc b/docs/topics/rules-development/yaml-or-condition.adoc index 593fd4ea..dc0dca5b 100644 --- a/docs/topics/rules-development/yaml-or-condition.adoc +++ b/docs/topics/rules-development/yaml-or-condition.adoc @@ -9,12 +9,12 @@ [role="_abstract"] The `or` condition performs a logical OR operation on the results of an array of conditions. The condition matches when _any_ of its child conditions match, for example: -[source,yaml] +[source,yaml, subs="+quotes"] ---- when: or: - - - - + - __ + - __ ---- For example: diff --git a/docs/topics/rules-development/yaml-provider-conditions.adoc b/docs/topics/rules-development/yaml-provider-conditions.adoc index 4a84b646..f0b20a0e 100644 --- a/docs/topics/rules-development/yaml-provider-conditions.adoc +++ b/docs/topics/rules-development/yaml-provider-conditions.adoc @@ -11,11 +11,11 @@ In the rule condition, the Architect defines the patterns that {ProductShortName A rule condition instructs the analyzer to use a specific provider and one of its capabilities. A condition follows the `.` pattern. -[source,terminal] +[source,yaml, subs="+quotes"] ---- when: - . - + __.__ + __ ---- The analyzer currently supports the following providers: @@ -69,21 +69,21 @@ capabilities: |`referenced` a|Find references of a pattern with an optional code location for detailed searches. For example, -[source,yaml] +[source,yaml, subs="+quotes"] ---- when: java.referenced: - + __ ---- |`dependency` a|Check whether the application has a given dependency. For example, -[source,yaml] +[source,yaml, subs="+quotes"] ---- when: java.dependency: - + __ ---- .5+|`builtin` @@ -94,74 +94,74 @@ when: |`json` a|Search JSON files using JSONPath queries. For example, -[source, yaml] +[source, yaml, subs="+quotes"] ---- when: builtin.json: - + __ ---- |`filecontent` a|Search content in regular files using regular expression patterns. For example, -[source, yaml] +[source, yaml, subs="+quotes"] ---- when: builtin.filecontent: - + __ ---- |`file` a|Find files with names matching a given pattern. For example, -[source, yaml] +[source, yaml, subs="+quotes"] ---- when: builtin.file: - + __ ---- |`hasTags` a|Check whether you created a tag for the application using a tagging rule. For example, -[source, yaml] +[source, yaml, subs="+quotes"] ---- when: builtin.hasTags: - + __ ---- .2+|`go` |`referenced` a|Find references to a pattern. For example, -[source,yaml] +[source,yaml, subs="+quotes"] ---- when: go.referenced: - + __ ---- |`dependency` a|Check whether the application has a given dependency. For example, -[source,yaml] +[source,yaml, subs="+quotes"] ---- when: go.dependency: - + __ ---- |`csharp` |`referenced` a|Find references to a pattern. For example, -[source,yaml] +[source,yaml, subs="+quotes"] ---- when: csharp.referenced: - + __ ---- |=== @@ -171,11 +171,11 @@ Following the example in the previous table, you can create the first part of th To create a `java` provider condition that uses the `referenced` capability: -[source,yaml] +[source,yaml, subs="+quotes"] ---- when: java.referenced: - + __ ---- [NOTE] @@ -190,7 +190,7 @@ The following table summarizes available providers, their capabilities and their |=== |Provider |Capability |Fields |Required |Description -.7+|xref:yaml-java-provider_rules-prov-cond[`java`] +.7+|`java` .3+|`referenced` |`pattern` |Yes @@ -206,7 +206,7 @@ when: |`location` |No -a|Source code location. See xref:yaml-java-locations_java-conditions-capabilities[Java locations]. +a|Source code location. See Java locations. For example, [source, yaml] ---- @@ -218,7 +218,7 @@ when: |`annotated` |No -a|Additional query to inspect annotations. See xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection]. +a|Additional query to inspect annotations. See Annotation inspection. For example, [source, yaml] ---- @@ -269,7 +269,7 @@ when: lowerbound: 4.4.0 ---- -.9+|xref:yaml-builtin-provider_rules-prov-cond[`builtin`] +.9+|`builtin` .3+|`xml` |`xpath` |Yes @@ -379,7 +379,7 @@ when: |`hasTags` | | -a|This is an inline list of string tags. See xref:yaml-tag-actions_rule-yaml-actions[Tag action] +a|This is an inline list of string tags. See Tag action. For example, [source, yaml] @@ -391,7 +391,7 @@ when: - Kubernetes ---- -.5+|xref:yaml-go-provider_rules-prov-cond[`go`] +.5+|`go` |`referenced` |`pattern` |Yes @@ -444,7 +444,7 @@ when: lowerbound: v4.2.0 ---- -.2+|xref:yaml-dotnet-provider_rules-prov-cond[`csharp`] +.2+|`csharp` .2+|`referenced` |`pattern` |Yes @@ -504,3 +504,14 @@ a|Specify one of the following for which {ProductShortName} runs a search query: * `ALL` - You can also specify `ALL` as `location` to run a search query on any location in the code, including namespaces, structure types, and interfaces. |=== + +[role="_additional-resources"] +* xref:yaml-java-provider_rules-prov-cond[`Java`] +* xref:yaml-java-locations_java-conditions-capabilities[Java locations] +* xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection] +* xref:yaml-tag-actions_rule-yaml-actions[Tag action] +* xref:yaml-go-provider_rules-prov-cond[`Go`] +* xref:yaml-dotnet-provider_rules-prov-cond[`Csharp`] + + + diff --git a/docs/topics/rules-development/yaml-rule-categories.adoc b/docs/topics/rules-development/yaml-rule-categories.adoc index aa768413..8de2546f 100644 --- a/docs/topics/rules-development/yaml-rule-categories.adoc +++ b/docs/topics/rules-development/yaml-rule-categories.adoc @@ -11,6 +11,6 @@ * `mandatory`: You must resolve the issue for a successful migration. If you do not make the changes, the resulting application will not build or run successfully. Examples include the replacement of proprietary APIs that are not supported in the target platform. -* `optional`: If you do not resolve the issue, the application should work, but the results might not be optimal. If you do not make the change at the time of migration, it is recommended that you include it on the schedule soon after you complete the migration. +* `optional`: If you do not resolve the issue, the application should work, but the results might not be optimal. If you do not make the change at the time of migration, include it on the schedule soon after you complete the migration. * `potential`: You need to examine the issue during the migration process, but there is not enough detailed information to determine if the task is mandatory for the migration to succeed. An example of such an issue is migrating a third-party proprietary type when there is no directly compatible type on the target platform. diff --git a/docs/topics/rules-development/yaml-rule-labels.adoc b/docs/topics/rules-development/yaml-rule-labels.adoc index ff9bc216..2158047a 100644 --- a/docs/topics/rules-development/yaml-rule-labels.adoc +++ b/docs/topics/rules-development/yaml-rule-labels.adoc @@ -15,19 +15,19 @@ Label format:: You can enter Labels under the `labels` field as a list of strings in `key=val` format as follows: -[source,yaml] +[source,yaml, subs="+quotes"] ---- labels: -- "key1=val1" -- "key2=val2" +- "key1=__" +- "key2=__" ---- The key of a label can be subdomain-prefixed: -[source,yaml] +[source,yaml, subs="+quotes"] ---- labels: -- "konveyor.io/key1=val1" +- "konveyor.io/key1=__" ---- The value of a label can be empty: @@ -65,27 +65,45 @@ _Examples:_ * To filter-in all rules that have a label with the key `konveyor.io/source` and value `eap6`: + -`--label-selector="konveyor.io/source=eap6"` +[subs="+quotes"] +---- +--label-selector="konveyor.io/source=eap6" +---- * To filter-in all rules that have a label with the key `konveyor.io/source` and any value: + -`--label-selector="konveyor.io/source"` +[subs="+quotes"] +---- +--label-selector="konveyor.io/source" +---- * To perform logical AND operations on matches of multiple rules by using the `&&` operator: + -`--label-selector="key1=val1 && key2"` +[subs="+quotes"] +---- +--label-selector="key1=__ && key2" +---- * To perform logical OR operations on matches of multiple rules by using the `||` operator: + -`--label-selector="key1=val1 || key2"` +[subs="+quotes"] +---- +--label-selector="key1=__ || key2" +---- * To perform a NOT operation to filter-out rules that have `key1=val1` label set by using the `!` operator: + -`--label-selector="!key1=val1"` +[subs="+quotes"] +---- +--label-selector="!key1=__" +---- * To group sub-expressions and control precedence by using AND: + -`--label-selector="(key1=val1 || key2=val2) && !val3"` +[subs="+quotes"] +---- +--label-selector="(key1=__ || key2=__) && !__" +---- == Dependency labels @@ -108,10 +126,19 @@ For example, the analyzer adds a `konveyor.io/dep-source` label to dependencies To exclude incidents for all such open source dependencies, you can use `--dep-label-selector` as follows: +[subs="+quotes"] +---- `$ mta-cli ... --dep-label-selector !konveyor.io/dep-source=open-source` +---- The Java provider in the analyzer can also add an exclude label to a list of packages. To exclude all such packages, you can use `--dep-label-selector` and the `!` operator as follows: -`konveyor-analyzer ... --dep-label-selector !konveyor.io/exclude` +[subs="+quotes"] +---- +$ `mta-cli ... --dep-label-selector !konveyor.io/exclude` +---- -`mta-cli ... --dep-label-selector !konveyor.io/exclude` +[subs="+quotes"] +---- +$ `mta-cli ... --dep-label-selector !konveyor.io/exclude` +---- \ No newline at end of file diff --git a/docs/topics/rules-development/yaml-rule-metadata.adoc b/docs/topics/rules-development/yaml-rule-metadata.adoc index 1fca14dc..581fb7fe 100644 --- a/docs/topics/rules-development/yaml-rule-metadata.adoc +++ b/docs/topics/rules-development/yaml-rule-metadata.adoc @@ -17,18 +17,18 @@ You can use rule metadata to: * Evaluate if a resolution is mandatory through rule category before migrating the applications to the target technologies or platforms. * Define labels that {ProductShortName} uses to filter rules for an analysis. -[source,yaml] +[source,yaml, subs="+quotes"] ---- -ruleID: "unique_id" +ruleID: "__" labels: # key=value pair - - "label1=val1" + - "label1=__" # valid label with value omitted - "label2" # valid label with empty value - "label3=" # subdomain prefixed key - - "konveyor.io/label1=val1" + - "konveyor.io/label1=__" effort: 1 category: mandatory ---- diff --git a/docs/topics/rules-development/yaml-rule-structure-syntax.adoc b/docs/topics/rules-development/yaml-rule-structure-syntax.adoc index 659fd64d..8c101de9 100644 --- a/docs/topics/rules-development/yaml-rule-structure-syntax.adoc +++ b/docs/topics/rules-development/yaml-rule-structure-syntax.adoc @@ -17,26 +17,26 @@ You can write rules in YAML. They consist of: {ProductShortName} analyzer rules have the following pattern: -[source, yaml] +[source, yaml, subs="+quotes"] ---- -ruleID: +ruleID: __ category: mandatory -effort: +effort: __ description: - - + __ + __ labels: - - konveyor.io/source= - - konveyor.io/target= + - konveyor.io/source=__ + - konveyor.io/target=__ links: - - url: - title: + - url: __ + title: __ when: message: "message" tag: - - tag_1, tag_2, tag_3 - - key_1="value_1, value_2" + - __, __, __ + - key_1="__, __" ---- where: diff --git a/docs/topics/rules-development/yaml-rulesets.adoc b/docs/topics/rules-development/yaml-rulesets.adoc index 3c243013..44c8d57e 100644 --- a/docs/topics/rules-development/yaml-rulesets.adoc +++ b/docs/topics/rules-development/yaml-rulesets.adoc @@ -24,22 +24,22 @@ labels: where: `name` :: The name must be unique within the provided rulesets. - `labels` :: Ruleset labels are inherited by all rules that belong to the ruleset. + `labels` :: Rules that belong to the ruleset inherit the ruleset labels. To perform any application analysis: -[source,terminal] +[source,terminal, subs="+quotes"] ---- -$ mta-cli analyze --input= --output= --rules= --enable-default-rulesets=false +$ mta-cli analyze --input=__ --output=__ --rules=__ --enable-default-rulesets=false ---- -* Replace `` with the name of your application. -* Replace `` with the directory of your choice. -* Replace `` with the custom rule file. +* Replace __ with the name of your application. +* Replace __ with the directory of your choice. +* Replace __ with the custom rule file. * To use multiple rule files, place them in a directory and add a `ruleset.yaml` file. Then {ProductShortName} treats the directory 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 analyzer will only select rules that match the label for that target. Therefore, make sure that you have added reserved labels in your rules. +Note that if you want to use the `--target` or `--source` option in the CLI, the analyzer will only select rules that match the label for that target. Therefore, you must add reserved labels in your rules. .Additional resources * xref:reserved-label_rule-yaml-metadata[Reserved labels] for more details. diff --git a/docs/topics/rules-development/yaml-tag-actions.adoc b/docs/topics/rules-development/yaml-tag-actions.adoc index 87192870..4d2a5c8c 100644 --- a/docs/topics/rules-development/yaml-tag-actions.adoc +++ b/docs/topics/rules-development/yaml-tag-actions.adoc @@ -9,20 +9,20 @@ [role="_abstract"] A tag action instructs the analyzer to generate one or more tags for the application when it finds a match. Each string in the `tag` field can be a comma-separated list of tags. Optionally, you can assign categories to tags. -[source,yaml] +[source,yaml, subs="+quotes"] ---- tag: - - "tag1,tag2,tag3" - - "Category=tag4,tag5" + - "__,__,__" + - "Category=__,__" ---- _Example_ -[source,yaml] +[source,yaml, subs="+quotes"] ---- - ruleID: test-rule when: - + __ tag: - Language=Golang - Env=production From d58a155adba1f204a3848e4d9cf6d1b263e4f68e Mon Sep 17 00:00:00 2001 From: Prabha Kylasamiyer Sundara Rajan Date: Fri, 29 May 2026 10:44:11 +0530 Subject: [PATCH 4/4] Made minor formatting changes Signed-off-by: Prabha Kylasamiyer Sundara Rajan --- docs/topics/rules-development/create-first-yaml-rule.adoc | 8 ++++---- docs/topics/rules-development/yaml-message-actions.adoc | 2 +- .../rules-development/yaml-provider-conditions.adoc | 6 +++--- docs/topics/rules-development/yaml-rulesets.adoc | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/topics/rules-development/create-first-yaml-rule.adoc b/docs/topics/rules-development/create-first-yaml-rule.adoc index db4a1ebd..f9268865 100644 --- a/docs/topics/rules-development/create-first-yaml-rule.adoc +++ b/docs/topics/rules-development/create-first-yaml-rule.adoc @@ -12,7 +12,7 @@ You can create a YAML-based rule to discover instances where an application defi .Prerequisites -* You installed {ProductShortName}. See link:{ProductDocUserGuideURL}/index#installing_and_running_the_cli[Installing and running the CLI] in the _{UserCLIBookName}_. +* You installed {ProductShortName}. See Installing and running the CLI. .Procedure . Create a YAML file for the rule. In the following example, find the rule in your `$HOME` directory. @@ -165,9 +165,9 @@ INFO[0066] Static report created. Access it at this URL: URL="file:/home/ . Verify that the issue with the title `Find class loading element in JBoss XML file` is present in the table. . Click the *jboss-web.xml* link to open the affected file. - - - +[role="_additional-resources"] +.Additional resources +* link:{ProductDocUserGuideURL}/index#installing_and_running_the_cli[Installing and running the CLI] in the _{UserCLIBookName}_ diff --git a/docs/topics/rules-development/yaml-message-actions.adoc b/docs/topics/rules-development/yaml-message-actions.adoc index 339ebe8d..6ab1774e 100644 --- a/docs/topics/rules-development/yaml-message-actions.adoc +++ b/docs/topics/rules-development/yaml-message-actions.adoc @@ -40,4 +40,4 @@ You can also create a template message to include information about the match by ---- .Additional resources -* xref:yaml-custom-variables_logical-chaining-custom-variables[custom variables] \ No newline at end of file +* xref:yaml-custom-variables_logical-chaining-custom-variables[Custom variables] \ No newline at end of file diff --git a/docs/topics/rules-development/yaml-provider-conditions.adoc b/docs/topics/rules-development/yaml-provider-conditions.adoc index f0b20a0e..ca94021d 100644 --- a/docs/topics/rules-development/yaml-provider-conditions.adoc +++ b/docs/topics/rules-development/yaml-provider-conditions.adoc @@ -506,12 +506,12 @@ a|Specify one of the following for which {ProductShortName} runs a search query: |=== [role="_additional-resources"] -* xref:yaml-java-provider_rules-prov-cond[`Java`] +* xref:yaml-java-provider_rules-prov-cond[Java] * xref:yaml-java-locations_java-conditions-capabilities[Java locations] * xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection] * xref:yaml-tag-actions_rule-yaml-actions[Tag action] -* xref:yaml-go-provider_rules-prov-cond[`Go`] -* xref:yaml-dotnet-provider_rules-prov-cond[`Csharp`] +* xref:yaml-go-provider_rules-prov-cond[Go] +* xref:yaml-dotnet-provider_rules-prov-cond[Csharp] diff --git a/docs/topics/rules-development/yaml-rulesets.adoc b/docs/topics/rules-development/yaml-rulesets.adoc index 44c8d57e..cb0cc6f5 100644 --- a/docs/topics/rules-development/yaml-rulesets.adoc +++ b/docs/topics/rules-development/yaml-rulesets.adoc @@ -42,4 +42,4 @@ $ mta-cli analyze --input=__ --output=__ --r Note that if you want to use the `--target` or `--source` option in the CLI, the analyzer will only select rules that match the label for that target. Therefore, you must add reserved labels in your rules. .Additional resources -* xref:reserved-label_rule-yaml-metadata[Reserved labels] for more details. +* xref:reserved-label_rule-yaml-metadata[Reserved labels]