diff --git a/assemblies/rules-development-guide/assembly_creating-rule.adoc b/assemblies/rules-development-guide/assembly_creating-rule.adoc new file mode 100644 index 00000000..6134785a --- /dev/null +++ b/assemblies/rules-development-guide/assembly_creating-rule.adoc @@ -0,0 +1,37 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +ifdef::context[:parent-context-of-creating-rule: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="creating-rule"] +endif::[] +ifdef::context[] +[id="creating-rule_{context}"] +endif::[] += Creating custom rules + +: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] + +include::topics/rules-development/create-first-yaml-rule.adoc[leveloffset=+1] + +include::topics/rules-development/create-go-custom-rule.adoc[leveloffset=+1] + +include::topics/rules-development/create-nodejs-custom-rule.adoc[leveloffset=+1] + +include::topics/rules-development/create-python-custom-rule.adoc[leveloffset=+1] + + +ifdef::parent-context-of-creating-rule[:context: {parent-context-of-creating-rule}] +ifndef::parent-context-of-creating-rule[:!context:] + +:!creating-rule: \ No newline at end of file diff --git a/assemblies/rules-development-guide/assembly_java-conditions-detailed.adoc b/assemblies/rules-development-guide/assembly_java-conditions-detailed.adoc new file mode 100644 index 00000000..02e8a718 --- /dev/null +++ b/assemblies/rules-development-guide/assembly_java-conditions-detailed.adoc @@ -0,0 +1,36 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +ifdef::context[:parent-context-of-java-conditions-capabilities: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="java-conditions-capabilities"] +endif::[] +ifdef::context[] +[id="java-conditions-capabilities_{context}"] +endif::[] += Java condition and capabilities + +: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 + +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] + +include::topics/rules-development/yaml-annotation-inspection.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-condition-patterns.adoc[leveloffset=+1] + +ifdef::parent-context-of-rule-java-conditions-capabilities[:context: {parent-context-of-rule-java-conditions-capabilities}] +ifndef::parent-context-of-rule-java-conditions-capabilities[:!context:] + +:!java-conditions-capabilities: \ No newline at end of file diff --git a/assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc b/assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc new file mode 100644 index 00000000..e95aa466 --- /dev/null +++ b/assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc @@ -0,0 +1,43 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +ifdef::context[:parent-context-of-logical-chaining-custom-variables: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="logical-chaining-custom-variables"] +endif::[] +ifdef::context[] +[id="logical-chaining-custom-variables_{context}"] +endif::[] += Logical conditions, condition chaining, and custom variables + +:context: logical-chaining-custom-variables + +[role="_abstract"] +You can create complex conditions in rules by using the following: + +* Logical conditions inform the provider how to handle more than one condition in a when block. You can aggregate or filter conditions using logical operations. +* 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-logical-conditions.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-and-condition.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-or-condition.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-chaining-condition-variables.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-chaining-java-provider.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-nested-condition.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-custom-variables.adoc[leveloffset=+1] + +ifdef::parent-context-of-rule-logical-chaining-custom-variables[:context: {parent-context-of-rule-logical-chaining-custom-variables}] +ifndef::parent-context-of-rule-logical-chaining-custom-variables[:!context:] + +:!logical-chaining-custom-variables: \ No newline at end of file diff --git a/assemblies/rules-development-guide/assembly_rule-rulesets.adoc b/assemblies/rules-development-guide/assembly_rule-rulesets.adoc new file mode 100644 index 00000000..9910ee76 --- /dev/null +++ b/assemblies/rules-development-guide/assembly_rule-rulesets.adoc @@ -0,0 +1,29 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +ifdef::context[:parent-context-of-rule-rulesets: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="rule-rulesets"] +endif::[] +ifdef::context[] +[id="rule-rulesets_{context}"] +endif::[] += Rulesets + +:context: rule-rulesets + +[role="_abstract"] +A set of rules forms a ruleset. MTA 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 need to place them in a directory and to add a ruleset.yaml file. Then the directory is treated as a ruleset, and you can pass it as input to the `--rules` option. +Note that if you want to use the `--target` or `--source` option in the CLI, the engine will only select rules that match the label for that target. Therefore, make sure that you have added target or source labels on your rules. See xref:reserved-label_rule-yaml-metadata[Reserved labels] for more details. + +include::topics/rules-development/yaml-rulesets.adoc[leveloffset=+1] + +ifdef::parent-context-of-rule-rulesets[:context: {parent-context-of-rule-rulesets}] +ifndef::parent-context-of-rule-rulesets[:!context:] + +:!rule-rulesets: \ No newline at end of file diff --git a/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc b/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc new file mode 100644 index 00000000..affced39 --- /dev/null +++ b/assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc @@ -0,0 +1,36 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +ifdef::context[:parent-context-of-rule-yaml-actions: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="rule-yaml-actions"] +endif::[] +ifdef::context[] +[id="rule-yaml-actions_{context}"] +endif::[] += Rule actions + +:context: rule-yaml-actions + +[role="_abstract"] +You can use rule actions to generate information about the source code. The rule action information can be included in a violation or used to categorize the source code. + +Rules can include the following types of actions: + +* `Message`: use message action to display an informative message in the static report that contains the violation triggered by the rule. See xref:yaml-message-actions_rule-yaml-actions[Message action] for more information. +* `Tag`: use tags to categorize parts of the source code. For example, Backend=Java, where Backend is the key and Java is the value. See xref:yaml-tag-actions_rule-yaml-actions[Tag actions] for more information. +Each rule includes either one of them or both of them. + +include::topics/rules-development/yaml-tag-actions.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-message-actions.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-rule-hyperlinks.adoc[leveloffset=+1] + +ifdef::parent-context-of-rule-yaml-actions[:context: {parent-context-of-rule-yaml-actions}] +ifndef::parent-context-of-rule-yaml-actions[:!context:] + +:!rule-yaml-actions: \ No newline at end of file diff --git a/assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc b/assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc new file mode 100644 index 00000000..c97fbefe --- /dev/null +++ b/assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc @@ -0,0 +1,60 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +ifdef::context[:parent-context-of-rule-provider-conditions: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="rule-provider-conditions"] +endif::[] +ifdef::context[] +[id="rule-provider-conditions_{context}"] +endif::[] += Providers and rule conditions + +:context: rule-provider-conditions + +[role="_abstract"] +The providers are the modular components in charge of analyzing a given language. Providers 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. + +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 +* Go +* External providers (for `Python`, `Dotnet` 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]. +==== + +.Using the provider capability in custom rules + +In a rule, the when block is where the conditions for matching the rule are specified. Each provider offers a series of capabilities to do matching.. The search query in the rule condition can contain patterns, code locations, specific dependencies to be found, etc, 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 for the when block is as follows: contains one condition, but that condition can have multiple conditions nested under it. + +---- +when: + + +---- + +include::topics/rules-development/yaml-provider-conditions.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-builtin-provider.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-java-provider.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-go-provider.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-dotnet-provider.adoc[leveloffset=+1] + +ifdef::parent-context-of-rule-provider-conditions[:context: {parent-context-of-rule-provider-conditions}] +ifndef::parent-context-of-rule-provider-conditions[:!context:] + +:!rule-provider-conditions: \ No newline at end of file diff --git a/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc b/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc new file mode 100644 index 00000000..5ec3b0af --- /dev/null +++ b/assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc @@ -0,0 +1,36 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +ifdef::context[:parent-context-of-rule-yaml-metadata: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="rule-yaml-metadata"] +endif::[] +ifdef::context[] +[id="rule-yaml-metadata_{context}"] +endif::[] += Rule metadata + +: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 for which {ProductShortName} filters rules to trigger a violation. + + +include::topics/rules-development/yaml-rule-metadata.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-rule-labels.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-rule-categories.adoc[leveloffset=+1] + +ifdef::parent-context-of-rule-yaml-metadata[:context: {parent-context-of-rule-yaml-metadata}] +ifndef::parent-context-of-rule-yaml-metadata[:!context:] + +:!rule-yaml-metadata: \ No newline at end of file diff --git a/assemblies/rules-development-guide/assembly_rules-introduction.adoc b/assemblies/rules-development-guide/assembly_rules-introduction.adoc new file mode 100644 index 00000000..f6a7328b --- /dev/null +++ b/assemblies/rules-development-guide/assembly_rules-introduction.adoc @@ -0,0 +1,30 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +ifdef::context[:parent-context-of-rules-introduction: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="rules-introduction"] +endif::[] +ifdef::context[] +[id="rules-introduction_{context}"] +endif::[] += Introduction to rules + +:context: rules-introduction + +[role="_abstract"] +This guide is intended for software engineers who want to create custom YAML-based rules for {ProductName} ({ProductShortName}) tools. + +See the link:{ProductDocIntroToMTAGuideURL}[_{IntroToMTABookName}_] for an overview and the link:{ProductDocUserGuideURL}[_{UserCLIBookName}_] for details. + +include::topics/rules-development/about-rules.adoc[leveloffset=+1] + +include::topics/rules-development/yaml-rule-structure-syntax.adoc[leveloffset=+1] + +ifdef::parent-context-of-getting-started[:context: {parent-context-of-rules-introduction}] +ifndef::parent-context-of-getting-started[:!context:] + +:!rules-introduction: \ No newline at end of file diff --git a/assemblies/rules-development-guide/topics b/assemblies/rules-development-guide/topics new file mode 120000 index 00000000..8eec97a3 --- /dev/null +++ b/assemblies/rules-development-guide/topics @@ -0,0 +1 @@ +../../docs/topics/ \ No newline at end of file diff --git a/docs/rules-development-guide/assemblies b/docs/rules-development-guide/assemblies new file mode 120000 index 00000000..51bb5102 --- /dev/null +++ b/docs/rules-development-guide/assemblies @@ -0,0 +1 @@ +../../assemblies/ \ No newline at end of file diff --git a/docs/rules-development-guide/master.adoc b/docs/rules-development-guide/master.adoc index 64efa4b5..beb2b17e 100644 --- a/docs/rules-development-guide/master.adoc +++ b/docs/rules-development-guide/master.adoc @@ -7,100 +7,30 @@ include::topics/templates/document-attributes.adoc[] :imagesdir: topics/images :context: rules-development-guide :rules-development-guide: -:_mod-docs-content-type: ASSEMBLY +:_mod-content-type: ASSEMBLY [id="rules-development-guide"] -= Rules Development Guide += Configuring and using rules for an {ProductShortName} analysis + +[role="abstract"] //Inclusive language statement include::topics/making-open-source-more-inclusive.adoc[] -[id="introduction_{context}"] -== Introduction - -// About the Rules Development Guide -include::topics/rules-guide-intro.adoc[leveloffset=+2] - -// Use of <{ProductShortName}_HOME> in this Guide -include::topics/mta-about-home-var.adoc[leveloffset=+3] - -// MTA Rules -include::topics/about-rules.adoc[leveloffset=+2] - -[id="creating-yaml-rules_{context}"] -== Creating YAML rules - -Each analyzer rule is a set of instructions that are used to analyze source code and detect issues that are problematic for migration. - -The analyzer parses user-provided rules, applies them to applications' source code, and generates issues for matched rules. - -A collection of one or more rules forms a ruleset. Creating rulesets provides a way of organizing multiple rules that achieve a common goal. - -The analyzer CLI takes rulesets as input arguments. - - -include::topics/yaml-rule-structure-syntax.adoc[leveloffset=+2] - -include::topics/ref_yaml-rule-labels.adoc[leveloffset=+2] - -[id="creating-basic-yaml-rules_{context}"] -=== Creating a basic YAML rule - -This section describes how to create a basic {ProductShortName} YAML rule. This assumes that you already have {ProductShortName} installed. See the {ProductShortName} {ProductDocUserGuideURL}[_{UserCLIBookName}_] for installation instructions. - -include::topics/create-basic-yaml-rule-template.adoc[leveloffset=+3] - -include::topics/yaml-rule-categories.adoc[leveloffset=+3] - -include::topics/yaml-rule-actions.adoc[leveloffset=+3] - -include::topics/yaml-rule-conditions.adoc[leveloffset=+3] - -include::topics/yaml-tag-actions.adoc[leveloffset=+3] - -include::topics/yaml-message-actions.adoc[leveloffset=+3] +include::assemblies/rules-development-guide/assembly_rules-introduction.adoc[leveloffset=+1] -include::topics/yaml-rule-hyperlinks.adoc[leveloffset=+3] +include::assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc[leveloffset=+1] -include::topics/yaml-provider-conditions.adoc[leveloffset=+3] +include::assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc[leveloffset=+1] -include::topics/yaml-builin-provider.adoc[leveloffset=+4] +include::assemblies/rules-development-guide/assembly_java-conditions-detailed.adoc[leveloffset=+1] -include::topics/yaml-java-provider.adoc[leveloffset=+4] +include::assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc[leveloffset=+1] -include::topics/yaml-java-locations.adoc[leveloffset=+4] +include::assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc[leveloffset=+1] -include::topics/yaml-annotation-inspection.adoc[leveloffset=+4] +include::assemblies/rules-development-guide/assembly_creating-rule.adoc[leveloffset=+1] -include::topics/yaml-go-provider.adoc[leveloffset=+4] - -include::topics/yaml-dotnet-provider.adoc[leveloffset=+4] - -include::topics/yaml-condition-patterns.adoc[leveloffset=+3] - -include::topics/yaml-custom-variables.adoc[leveloffset=+3] - -include::topics/yaml-logical-conditions.adoc[leveloffset=+3] - -include::topics/yaml-and-condition.adoc[leveloffset=+4] - -include::topics/yaml-or-condition.adoc[leveloffset=+4] - -include::topics/yaml-chaining-condition-variables.adoc[leveloffset=+4] - -include::topics/yaml-chaining-java-provider.adoc[leveloffset=+5] - -include::topics/yaml-rulesets.adoc[leveloffset=+3] - - - -include::topics/create-basic-yaml-ruleset-template.adoc[leveloffset=+3] - -include::topics/create-yaml-rule.adoc[leveloffset=+3] - -include::topics/running-analysis-using-custom-yaml-rule.adoc[leveloffset=+3] - -// Create Your First YAML Rule -include::topics/create-first-yaml-rule.adoc[leveloffset=+2] +include::assemblies/rules-development-guide/assembly_rule-rulesets.adoc[leveloffset=+1] // removing section subject to a later re-write // Testing XML Rules @@ -133,7 +63,8 @@ include::topics/create-first-yaml-rule.adoc[leveloffset=+2] // removing section subject to a later re-write // Using Custom Rule Categories // include::topics/rule-categories.adoc[leveloffset=+1] - +//[appendix] +//== Reference material // Rule Story Points //include::topics/about-story-points.adoc[leveloffset=+2] @@ -141,7 +72,12 @@ include::topics/create-first-yaml-rule.adoc[leveloffset=+2] // removing section subject to a later re-write // For more information on categorizing tasks, see xref:rule-categories_{context}[Using custom rule categories]. -=== Additional resources +== Additional resources + +//include::topics/rules-important-links.adoc[leveloffset=+1] + +* {ProductShortName} Jira issue tracker: {JiraWindupURL} +* {ProductShortName} mailing list: windup-eng@redhat.com // removing section subject to a later re-write // Review the Existing MTA XML Rules @@ -152,11 +88,10 @@ include::topics/create-first-yaml-rule.adoc[leveloffset=+2] // include::topics/fork-ruleset-repo.adoc[leveloffset=+3] // Important Links -include::topics/rules-important-links.adoc[leveloffset=+3] // ********************************** // * Appendix: Revision Information * // ********************************** //include::topics/templates/revision-info.adoc[] -:!rules-development-guide: +:!rules-development-guide: \ No newline at end of file diff --git a/docs/topics/about-rules.adoc b/docs/topics/about-rules.adoc deleted file mode 100644 index 04f7c311..00000000 --- a/docs/topics/about-rules.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/rules-development-guide/master.adoc -// * docs/getting-started-guide/master.adoc - -:_mod-docs-content-type: CONCEPT -[id="about-rules_{context}"] -= The {ProductShortName} rules - -[role="_abstract"] -The {ProductFullName} contains rule-based migration tools (analyzers) that you can use to analyze the application user interfaces (APIs), technologies, and architectures used by the applications you plan to migrate. {ProductShortName} analyzer rules use the following rule pattern: - ----- -when(condition) - message(message) - tag(tags) ----- - - -You can use the {ProductShortName} rules internally to perform the following tasks: - -* Extract files from archives. -* Decompile files. -* Scan and classify file types. -* Analyze XML and other file content. -* Analyze the application code. -* Build the reports. - -{ProductShortName} builds a data model based on the rule execution results and stores component data and relationships in a graph database. This database can then be queried and updated as required by the migration rules and for reporting purposes. - - -[NOTE] -==== -You can create your own custom analyzer rules. You can use custom rules to identify the use of custom libraries or other components that might not be covered by the provided standard migration rules. - -ifndef::rules-development-guide[] -For instructions on how to write custom rules, see [_{RulesDevBookName}_]. -endif::rules-development-guide[] -==== diff --git a/docs/topics/making-open-source-more-inclusive.adoc b/docs/topics/making-open-source-more-inclusive.adoc index af9dce7d..fe859099 100644 --- a/docs/topics/making-open-source-more-inclusive.adoc +++ b/docs/topics/making-open-source-more-inclusive.adoc @@ -10,8 +10,8 @@ // * docs/web-console-guide/master.adoc [preface] -:_mod-docs-content-type: CONCEPT -[id="making-open-source-more-inclusive"] +:_mod-content-type: CONCEPT +[id="making-open-source-more-inclusive_{context}"] = Making open source more inclusive [role="_abstract"] diff --git a/docs/topics/rules-development/about-rules.adoc b/docs/topics/rules-development/about-rules.adoc new file mode 100644 index 00000000..a7627f89 --- /dev/null +++ b/docs/topics/rules-development/about-rules.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc +// * docs/getting-started-guide/master.adoc + +:_mod-docs-content-type: CONCEPT +[id="about-rules_{context}"] += The {ProductShortName} rules + +[role="_abstract"] +The {ProductFullName} contains rule-based migration tools called analyzers that use pluggable providers to analyze static code, dependencies, and other files in your application. + +Analyzers work 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 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. + +[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. +==== + +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. + +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 plug-ins for {ProductShortName} (Visual Studio Code or IntelliJ). + +The rules can be used by {mta-dl-plugin} to generate AI-assisted code resolutions. The issue description and metadata in rules are used by the {mta-dl-plugin} to form well-defined contexts. These contexts generate AI-assisted suggestions to resolve issues in the code that are identified through an analysis. See link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/8.0/html/configuring_and_using_red_hat_developer_lightspeed_for_mta/index[Configuring and Using Red Hat Developer Lightspeed for MTA] for more information. + + +ifndef::rules-development-guide[] +For instructions on how to write custom rules, see [_{RulesDevBookName}_]. +endif::rules-development-guide[] diff --git a/docs/topics/create-basic-yaml-rule-template.adoc b/docs/topics/rules-development/create-basic-yaml-rule-template.adoc similarity index 95% rename from docs/topics/create-basic-yaml-rule-template.adoc rename to docs/topics/rules-development/create-basic-yaml-rule-template.adoc index 45fa397c..81044253 100644 --- a/docs/topics/create-basic-yaml-rule-template.adoc +++ b/docs/topics/rules-development/create-basic-yaml-rule-template.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="create-basic-yaml-rule-template_{context}"] -= Creating a basic YAML rule template += Creating a YAML rule template [role="_abstract"] {ProductShortName} YAML-based rules have the following basic structure: diff --git a/docs/topics/create-basic-yaml-ruleset-template.adoc b/docs/topics/rules-development/create-basic-yaml-ruleset-template.adoc similarity index 98% rename from docs/topics/create-basic-yaml-ruleset-template.adoc rename to docs/topics/rules-development/create-basic-yaml-ruleset-template.adoc index 67808fad..02697ddb 100644 --- a/docs/topics/create-basic-yaml-ruleset-template.adoc +++ b/docs/topics/rules-development/create-basic-yaml-ruleset-template.adoc @@ -23,4 +23,4 @@ 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` :: Ruleset labels are inherited by all rules that belong to the ruleset. \ No newline at end of file diff --git a/docs/topics/create-first-yaml-rule.adoc b/docs/topics/rules-development/create-first-yaml-rule.adoc similarity index 74% rename from docs/topics/create-first-yaml-rule.adoc rename to docs/topics/rules-development/create-first-yaml-rule.adoc index 7c4eb84c..f047741e 100644 --- a/docs/topics/create-first-yaml-rule.adoc +++ b/docs/topics/rules-development/create-first-yaml-rule.adoc @@ -4,16 +4,13 @@ :_mod-docs-content-type: PROCEDURE [id="create-first-yaml-rule_{context}"] -= Creating your first YAML rule += Creating a YAML rule [role="_abstract"] This section guides you through the process of creating and testing your first {ProductShortName} YAML-based rule. 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. 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. -[id="creating-yaml-file-for-the-rule_{context}"] -== Creating a YAML file for the rule - * Create a YAML file for your first rule. [options="nowrap",subs="attributes+"] @@ -21,9 +18,6 @@ In this example, you will create a rule to discover instances where an applicati $ mkdir /home//rule.yaml ---- -[id="mta-creating-data-to-test-the-rule_{context}"] -== Creating data to test the rule - . Create `jboss-web.xml` and `pom.xml` files in a directory: + [options="nowrap",subs="attributes+"] @@ -70,20 +64,7 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xs ---- -[id="mta-creating-the-rule_{context}"] -== Creating the rule - -MTA YAML-based rules use the following rule pattern: - -[options="nowrap",subs="attributes+"] ----- -when(condition) - perform(action) ----- - -.Procedure - -* In the `rule.yaml` file you created, paste the following contents: +. In the `rule.yaml` file you created, paste the following contents: + [options="nowrap",subs="attributes+"] ---- @@ -95,15 +76,15 @@ when(condition) labels: effort: links: - - + - ---- ++ where: `ruleID` :: Unique ID for your rule. For example, `jboss5-web-class-loading`. `description` :: Text description of the rule. `when` :: Complete the `when` block specifying one or more conditions: .. Use the `builtin` provider's XML capability because this rule checks for a match in an XML file. -.. To match on the `class-loading` element that is a child of `jboss-web`, use the XPath expression `jboss-web/web-loading` as an XML query. In this case, you need just one condition: + [options="nowrap",subs="attributes+"] ---- @@ -111,8 +92,7 @@ when: builtin.xml: xpath: jboss-web/class-loading ---- - - `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. The message is generated in the report when the rule matches. For example: [options="nowrap",subs="attributes+"] ---- @@ -121,14 +101,13 @@ when: `labels` :: List of string labels for the rule. `effort` :: Number of expected story points to fix this issue. - `links` :: One or more hyperlinks pointing to documentation around the migration issues that you find. -+ -[options="nowrap",subs="attributes+"] ----- -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 + `links` :: One or more hyperlinks pointing to documentation around the migration issues that you find.+ + [options="nowrap",subs="attributes+"] + ---- + 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 ----- + ---- + The rule is now complete and looks similar to the following: + @@ -146,36 +125,24 @@ The rule is now complete and looks similar to the following: title: Create or Modify Files That Control Class Loading in JBoss EAP 6 ---- -[id="mta-installing-the-rule_{context}"] -== Installing the rule - -.Procedure -* Point the CLI to the rule file you created : +. Point the CLI to the rule file you created : + [options="nowrap",subs="attributes+"] ---- –rules /home//rules.yaml ---- -[id="mta-testing-the-rule_{context}"] -== Testing the rule - -.Procedure -To test the rule, point the input to the test data you created and pass the rule using the rules option in MTA CLI: - +. To test the rule, point the input to the test data you created and pass the rule using the rules option in MTA CLI: ++ [options="nowrap",subs="attributes+"] ---- mta-cli analyze --input /home//data/ --output /home//output/ --rules /home//rules.yaml ---- -[id="mta-reviewing-the-report_{context}"] -== Reviewing the report - -Review the report to be sure that it provides the expected results. - -.Procedure +. 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: +Once the analysis is complete, the command outputs the path to the HTML report: + [options="nowrap",subs="attributes+"] ---- diff --git a/docs/topics/rules-development/create-go-custom-rule.adoc b/docs/topics/rules-development/create-go-custom-rule.adoc new file mode 100644 index 00000000..0c2646a4 --- /dev/null +++ b/docs/topics/rules-development/create-go-custom-rule.adoc @@ -0,0 +1,69 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: PROCEDURE +[id="create-go-custom-rule_{context}"] += Creating a custom Go rule + +[role="_abstract"] +You can create custom rules for Golang (Go) applications based on the following example. + +You can use the following custom rule to check if {ProductShortName} triggers an incident when it detects a `go` file in your project. + +.Procedure +. Create a `go-rule-001.yml` file in a directory. + +. Copy the following rule in the `yaml` file: ++ + +[source, yaml] +---- +- message: golang apiextensions/v1/customresourcedefinitions found + description: "golang apiextensions/v1/customresourcedefinitions found" + ruleID: go-lang-ref-001 + effort: 1 + when: + go.referenced: + pattern: "v1beta1.CustomResourceDefinition" +---- + +. Create a test `go` file named *example.go* in your `Home` directory. + +. Paste the following code in the *example.go* file: ++ + +[source, go] +---- +package main + +import ( + "fmt" + + "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1" +) + +func main() { + fmt.Println(v1beta1.CustomResourceDefinition{}) + +} +---- + +. Run the following command in the {ProductShortName} CLI: ++ + +[source, terminal] +---- +$ ./mta-cli analyze -i __ -o __ \ --run-local=false --rules __ +---- ++ + +[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. +==== + +. Open the static report at `/home//output/static-report/` in your browser. + +. Navigate to the issues to verify the `golang apiextensions/v1/customresourcedefinitions found {{file}}:{{lineNumber}}` issue. + diff --git a/docs/topics/rules-development/create-nodejs-custom-rule.adoc b/docs/topics/rules-development/create-nodejs-custom-rule.adoc new file mode 100644 index 00000000..4e503f93 --- /dev/null +++ b/docs/topics/rules-development/create-nodejs-custom-rule.adoc @@ -0,0 +1,66 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: PROCEDURE +[id="create-nodejs-custom-rule_{context}"] += Creating a custom Node.js rule + +[role="_abstract"] + You must create custom rules to analyze `Node.js` applications by using {ProductShortName}. A `Node.js` rule can contain `nodejs.referenced` capability which supports the `pattern` field. + +The following example uses a custom rule to check if a `.tsx` file in the `Node.js` project imports the `React` framework. + +.Procedure +. Create the `test-nodejs` directory. ++ + +[source, terminal] +---- +$ mkdir -p ~/test-nodejs +---- + +. Save the following rule as `nodejs-rule-001.yml` in the `test-nodejs` directory: ++ +[source, yaml] +---- +- ruleID: test-tsx-support-00000 + description: Found React import in .tsx file + message: Found React import in .tsx file + effort: 1 + when: + nodejs.referenced: + pattern: "React" +---- + +. Create the following test application in the `Component.tsx` file: ++ + +[source, node.js] +---- +import React from 'react'; + export const MyComponent: React.FC = () =>
Hello
; +---- + +. Run the following command in the {ProductShortName} CLI: ++ + +[source, terminal] +---- +$ ./mta-cli analyze -i ~/test-nodejs/ -o \ +~/test-nodejs/report --run-local=false \ +--rules ~/test-nodejs/nodejs-rule-001.yml +---- ++ + +[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. +==== + +. Open the static report at `~/test-nodejs/report/static-report/index.html` in your browser. + +. Click the __ to open the Dashboard. + +. Review the incidents in the *Issues* tab. + diff --git a/docs/topics/rules-development/create-python-custom-rule.adoc b/docs/topics/rules-development/create-python-custom-rule.adoc new file mode 100644 index 00000000..ae1d0b4d --- /dev/null +++ b/docs/topics/rules-development/create-python-custom-rule.adoc @@ -0,0 +1,94 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: PROCEDURE +[id="create-python-custom-rule_{context}"] += Creating custom Python rules + +[role="_abstract"] +You must create custom rules to analyze `Python` applications by using {ProductShortName}. A `Python` rule can contain `python.referenced` capability with the supported fields. + +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. + +.Procedure +. Create the directory `test-python`. ++ +[source, terminal] +---- +$ mkdir -p ~/test-python +---- + +. Create a `python-rule-001.yml` file in the directory and add the following rule: ++ +[source, yaml] +---- +- category: mandatory + ruleID: python-rule-001 + effort: 1 + description: "Bad method" + when: + python.referenced: + pattern: "bad_method" +---- + +. Create a `python-rule-002.yml` file in the directory and add the following rule: ++ +[source, yaml] +---- + - category: mandatory + ruleID: python-rule-002 + effort: 1 + message: "Found a python" + when: + python.referenced: + pattern: "hello_world" +---- + +. Save the following `Python` code as `file_b.py`. ++ + +[source, python] +---- +import deprecated +def hello_world(): + return "Hello, world!" +@deprecated.deprecated("This method is bad!") +def bad_method(): + return "I'm a bad method!" +---- + +. Save the following code as a second file, `file_a.py`. ++ +[source, python] +---- +import file_b +print(file_b.hello_world()) +print(file_b.bad_method()) +---- + +. Run the following command in the {ProductShortName} CLI: ++ +[source, terminal] +---- +$ ./mta-cli analyze -i ~/test-python/ -o \ +~/test-python/report --run-local=false \ +--rules ~/test-python/python-rule-001. \ +--rules ~/test-python/python-rule-002.yml +---- ++ + +[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. +==== + +. Open the static report at `~/test-python/report/static-report/index.html` in your browser. + +. Click the __ to open the Dashboard. + +. Review the incidents in the *Issues* tab. + diff --git a/docs/topics/create-yaml-rule.adoc b/docs/topics/rules-development/create-yaml-rule.adoc similarity index 94% rename from docs/topics/create-yaml-rule.adoc rename to docs/topics/rules-development/create-yaml-rule.adoc index faa6a614..e469aacb 100644 --- a/docs/topics/create-yaml-rule.adoc +++ b/docs/topics/rules-development/create-yaml-rule.adoc @@ -17,9 +17,9 @@ The `when` condition of a YAML rule can be `provider`, `and` or `or`. .. Create a `provider` condition + -The provider condition is used to define a search query for a specific language provider and to invoke a certain capability of the provider. +The provider condition is used to define a search query for a specific language provider. Provider condition also specifies the capability of the provider used to complete the search query. + -The condition's general format is `.`. The condition also has inner fields to specify details of the search. The way you create a `provider` condition and its inner fields depends on which provider you use and which capability you invoke. +The condition's general format is `.`. The condition also has inner fields to specify details of the search. The way you create a `provider` condition and its inner fields depends on the provider you use and its capabilities. + The table below lists the available providers and their capabilities. Select a provider and its capability that suit the purpose of the rule you want to create. This part of the condition does not contain any of the condition's fields yet. + @@ -129,7 +129,7 @@ The table below lists all available providers, their capabilities, and their fie |Yes |Finds files with names matching this pattern |`hasTags` -3+^| This is an inline list of string tags. See *Tag Actions* in xref:yaml-rule-actions_{context}[Rule Actions] for details on tag format. +3+^| This is an inline list of string tags. See *Tag Actions* in xref:yaml-tag-actions_rule-yaml-actions[Tag Actions] for details on tag format. .5+.^|`go` |`referenced` diff --git a/docs/topics/rules-development/developer-preview-admonition.adoc b/docs/topics/rules-development/developer-preview-admonition.adoc new file mode 100644 index 00000000..bb6d5863 --- /dev/null +++ b/docs/topics/rules-development/developer-preview-admonition.adoc @@ -0,0 +1,10 @@ +// When including this file, ensure that {FeatureName} is set immediately before the include. Otherwise it will result in an incorrect replacement. +// use :FeatureName: + +[IMPORTANT] +==== +[subs="attributes+"] +{FeatureName} is a Developer Preview feature only. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to upcoming product features in advance of their possible inclusion in a Red Hat product offering, enabling customers to test functionality and provide feedback during the development process. These features might not have any documentation, are subject to change or removal at any time, and testing is limited. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. +==== +// Undefine {FeatureName} attribute, so that any mistakes are easily spotted +:!FeatureName: diff --git a/docs/topics/rules-development/mta-about-home-var.adoc b/docs/topics/rules-development/mta-about-home-var.adoc new file mode 100644 index 00000000..354c9b96 --- /dev/null +++ b/docs/topics/rules-development/mta-about-home-var.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: CONCEPT +[id="mta-about-home-var_{context}"] += Use of `<{ProductShortName}_HOME>` in this guide + +[role="_abstract"] +This guide uses the `<{ProductShortName}_HOME>` replaceable variable to denote the path to your {ProductShortName} installation. + +The {ProductShortNameLower}-{ProductVersion}-cli.zip* extracts a single binary called `mta-cli`. + +When you encounter `<{ProductShortName}_HOME>` in this guide, replace it with the actual path to your {ProductShortName} installation. diff --git a/docs/topics/rules-guide-intro.adoc b/docs/topics/rules-development/rules-guide-intro.adoc similarity index 94% rename from docs/topics/rules-guide-intro.adoc rename to docs/topics/rules-development/rules-guide-intro.adoc index ef13e498..540b51ee 100644 --- a/docs/topics/rules-guide-intro.adoc +++ b/docs/topics/rules-development/rules-guide-intro.adoc @@ -9,4 +9,4 @@ [role="_abstract"] This guide is intended for software engineers who want to create custom YAML-based rules for {ProductName} ({ProductShortName}) tools. -See the link:{ProductDocIntroToMTAGuideURL}[_{IntroToMTABookName}_] for an overview and the link:{ProductDocUserGuideURL}[_{UserCLIBookName}_] for details. \ No newline at end of file +See the link:{ProductDocIntroToMTAGuideURL}[_{IntroToMTABookName}_] for an overview and the link:{ProductDocUserGuideURL}[_{UserCLIBookName}_] for details. diff --git a/docs/topics/running-analysis-using-custom-yaml-rule.adoc b/docs/topics/rules-development/running-analysis-using-custom-yaml-rule.adoc similarity index 78% rename from docs/topics/running-analysis-using-custom-yaml-rule.adoc rename to docs/topics/rules-development/running-analysis-using-custom-yaml-rule.adoc index 3faacb15..2dd78d57 100644 --- a/docs/topics/running-analysis-using-custom-yaml-rule.adoc +++ b/docs/topics/rules-development/running-analysis-using-custom-yaml-rule.adoc @@ -4,14 +4,15 @@ :_mod-docs-content-type: PROCEDURE [id="running-analysis-using-custom-yaml-rule_{context}"] -= Running an analysis using a custom YAML rule += Running an analysis using a custom YAML rule +//change this procedure to use a ruleset [role="_abstract"] To run an analysis, use the `--rules` option in the CLI. .Procedure -* To use the rules in a single rule file, `/home//rule.yaml`, run the following command: +. To use the rules in a single rule file, `/home//rule.yaml`, run the following command: + [source,terminal] ---- @@ -24,8 +25,9 @@ where: ** `/home//output/` - the directory for reports (HTML and YAML) * To use multiple rule files, you need to place them in a directory and to add a `ruleset.yaml` file. Then the directory is treated as a _ruleset_, and you can pass it as input to the `--rules` option. ++ -Note that if you wish to use the `--target` or `--source` option in the CLI, the engine will only select rules that match the label for that target. Therefore, make sure that you have added target or source labels on your rules. See xref:yaml-rule-labels_rules-development-guide[Reserved labels] for more details. +Note that if you want to use the `--target` or `--source` option in the CLI, the engine will only select rules that match the label for that target. Therefore, make sure that you have added target or source labels on your rules. See xref:yaml-rule-labels_rule-yaml-metadata[Reserved labels] for more details. diff --git a/docs/topics/rules-development/technology-preview.adoc b/docs/topics/rules-development/technology-preview.adoc new file mode 100644 index 00000000..9c1acea0 --- /dev/null +++ b/docs/topics/rules-development/technology-preview.adoc @@ -0,0 +1,12 @@ +// When including this file, ensure that {FeatureName} is set immediately before +// the include. Otherwise it will result in an incorrect replacement. + +[IMPORTANT] +==== +[subs="attributes+"] +{FeatureName} is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. + +For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope]. +==== +// Undefine {FeatureName} attribute, so that any mistakes are easily spotted +:!FeatureName: diff --git a/docs/topics/yaml-and-condition.adoc b/docs/topics/rules-development/yaml-and-condition.adoc similarity index 66% rename from docs/topics/yaml-and-condition.adoc rename to docs/topics/rules-development/yaml-and-condition.adoc index 2a613ea9..d4ea964f 100644 --- a/docs/topics/yaml-and-condition.adoc +++ b/docs/topics/rules-development/yaml-and-condition.adoc @@ -33,20 +33,3 @@ when: location: IMPORT pattern: junit.junit ---- - -[id="yaml-nested-and-condition_{context}"] -== Nested conditions -Conditions can also be nested within other conditions. - -. Example - -[source,yaml] ----- -when: - and: - - and: - - go.referenced: "*CustomResourceDefinition*" - - java.referenced: - pattern: "*CustomResourceDefinition*" - - go.referenced: "*CustomResourceDefinition*" ----- diff --git a/docs/topics/yaml-annotation-inspection.adoc b/docs/topics/rules-development/yaml-annotation-inspection.adoc similarity index 100% rename from docs/topics/yaml-annotation-inspection.adoc rename to docs/topics/rules-development/yaml-annotation-inspection.adoc diff --git a/docs/topics/yaml-builin-provider.adoc b/docs/topics/rules-development/yaml-builtin-provider.adoc similarity index 98% rename from docs/topics/yaml-builin-provider.adoc rename to docs/topics/rules-development/yaml-builtin-provider.adoc index f351cc54..7e0d703b 100644 --- a/docs/topics/yaml-builin-provider.adoc +++ b/docs/topics/rules-development/yaml-builtin-provider.adoc @@ -3,7 +3,7 @@ // * docs/rules-development-guide/master.adoc :_mod-docs-content-type: REFERENCE -[id="yaml-builin-provider_{context}"] +[id="yaml-builtin-provider_{context}"] = Builtin provider [role="_abstract"] diff --git a/docs/topics/yaml-chaining-condition-variables.adoc b/docs/topics/rules-development/yaml-chaining-condition-variables.adoc similarity index 100% rename from docs/topics/yaml-chaining-condition-variables.adoc rename to docs/topics/rules-development/yaml-chaining-condition-variables.adoc diff --git a/docs/topics/yaml-chaining-java-provider.adoc b/docs/topics/rules-development/yaml-chaining-java-provider.adoc similarity index 100% rename from docs/topics/yaml-chaining-java-provider.adoc rename to docs/topics/rules-development/yaml-chaining-java-provider.adoc diff --git a/docs/topics/yaml-condition-patterns.adoc b/docs/topics/rules-development/yaml-condition-patterns.adoc similarity index 100% rename from docs/topics/yaml-condition-patterns.adoc rename to docs/topics/rules-development/yaml-condition-patterns.adoc diff --git a/docs/topics/yaml-custom-variables.adoc b/docs/topics/rules-development/yaml-custom-variables.adoc similarity index 88% rename from docs/topics/yaml-custom-variables.adoc rename to docs/topics/rules-development/yaml-custom-variables.adoc index 1ed5983d..16d89f66 100644 --- a/docs/topics/yaml-custom-variables.adoc +++ b/docs/topics/rules-development/yaml-custom-variables.adoc @@ -7,7 +7,7 @@ = 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-rule-actions_{context}[Message actions]). They can be added to a rule in the `customVariables` field: +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: [source,yaml] ---- diff --git a/docs/topics/yaml-dotnet-provider.adoc b/docs/topics/rules-development/yaml-dotnet-provider.adoc similarity index 85% rename from docs/topics/yaml-dotnet-provider.adoc rename to docs/topics/rules-development/yaml-dotnet-provider.adoc index f8dfc77f..37e09481 100644 --- a/docs/topics/yaml-dotnet-provider.adoc +++ b/docs/topics/rules-development/yaml-dotnet-provider.adoc @@ -22,5 +22,5 @@ when: ---- where: - `pattern` :: A regular expression (regex) pattern to match the desired reference. For example, `HttpNotFound`. + `pattern` :: A regular expression pattern to match the desired reference. For example, `HttpNotFound`. `namespace` :: Specifies the namespace to search within. For example, `System.Web.Mvc`. diff --git a/docs/topics/yaml-go-provider.adoc b/docs/topics/rules-development/yaml-go-provider.adoc similarity index 66% rename from docs/topics/yaml-go-provider.adoc rename to docs/topics/rules-development/yaml-go-provider.adoc index 2964c4c0..9972ddcc 100644 --- a/docs/topics/yaml-go-provider.adoc +++ b/docs/topics/rules-development/yaml-go-provider.adoc @@ -1,4 +1,4 @@ -regular expression// Module included in the following assemblies: +// Module included in the following assemblies: // // * docs/rules-development-guide/master.adoc @@ -7,7 +7,7 @@ regular expression// Module included in the following assemblies: = Go provider [role="_abstract"] -The `go` provider analyzes Go source code. This provider's capabilities are `referenced` and `dependency`. +The `go` provider analyzes `Go` source code. This provider's capabilities are `referenced` and `dependency`. .`referenced` @@ -16,12 +16,12 @@ By using the `referenced` capability, the provider finds references in the sourc [source,yaml] ---- when: - go.referenced: "" + go.referenced: "" ---- .`dependency` -By using the `dependency` capability, the provider finds dependencies for an application. +By using the `dependency` capability, the provider finds dependencies for a `Go` application. [source,yaml] ---- @@ -38,4 +38,4 @@ where: `upperbound` :: Upper bound on the version of the dependency. - `lowerbound` :: Lower bound on the version of the dependency. + `lowerbound` :: Lower bound on the version of the dependency. \ 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 new file mode 100644 index 00000000..ea5de8d9 --- /dev/null +++ b/docs/topics/rules-development/yaml-java-locations.adoc @@ -0,0 +1,226 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: REFERENCE + +[id="yaml-java-locations_{context}"] += Java locations + +[role="_abstract"] +The `java` provider allows scoping 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: + +[source,yaml] +---- +java.referenced: + pattern: org.apache.lucene.search* + location: IMPORT +---- + +would match on each of these imports: + +[source,java] +---- +import org.apache.lucene.search.Query; +import org.apache.lucene.search.Sort; +import org.apache.lucene.search.SortField; +---- + +[TIP] +==== +If you want to match using an asterisk (`++*++`) for a wider +range of results, it is recommended to place it directly after the +package, not after the dot: + +INCORRECT: `org.apache.lucene.search.++*++` +CORRECT: `org.apache.lucene.search++*++` +==== + +* *PACKAGE*: the `PACKAGE` location matches on any usage of a package, be +it in an import or used as part of an FQN in the code: + +[source,yaml] +---- +java.referenced: + pattern: org.apache.lucene.search* + location: PACKAGE +---- + +would match on each of the following import and the FQN usage: + +[source,java] +---- +import org.apache.lucene.search.Query; +import org.apache.lucene.search.Sort; +import org.apache.lucene.search.SortField; +---- + +[source,java] +---- +public class Test { + private org.apache.lucene.search.Query query; +} +---- + +* *CONSTRUCTOR++_++CALL* and *METHOD++_++CALL*: for matching +constructors and methods, respectively. The pattern possibilities are +quite varied, and it is possible to match against specific return types, +arguments, etc. + +For instance, looking for a method named `method` declared on +`org.konveyor.MyClass` that returns a `List` of a type that extends +`java.lang.String` and accepts a single parameter: + +[source,yaml] +---- +java.referenced: + location: METHOD + pattern: 'org.konveyor.Myclass.method(*) java.util.List' +---- + +More information about the possibilities of these patterns can be found in 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(java.lang.String,int,int,int)[the official Java documentaion, which contain all the information for building these patterns] in the `createPattern(String, int, int, int)` section. + +[WARNING] +==== +Presently, fully qualified static method matching is prone +to errors. +==== + +.Supported Java locations +[cols="3,3,6"] +|=== +|Location |Description |Rule condition example + +|TYPE|Matches against all types including classes, interfaces, enum, and annotation types that appear anywhere. +a|The following example looks for a class that implements `java.util.List`. +[source, yaml] +---- + when: + java.referenced: + location: TYPE + pattern: java.util.List +---- +|ANNOTATION|Matches against annotations. +a|The following example matches the `@Bean` annotation in the source code. +[source, yaml] +---- +when: + java.referenced: + location: ANNOTATION + pattern: org.framework.Bean + annotated: + elements: + - name: url + value: "http://www.example.com" +---- +|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] +---- + when: + java.referenced: + location: IMPLEMENTS_TYPE + pattern: java.util.ArrayList +---- +|RETURN_TYPE|Matches against a type being returned by a method. +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] +---- +when: + java.referenced: + location: RETURN_TYPE + pattern: javax.persistence.EntityManager + 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 connection to JMS queues appearing as a variable declaration. Replace the string `QueueConnectionFactory` with `ConnectionFactory`. +[source, yaml] +---- +when: + - java.referenced: + location: VARIABLE_DECLARATION + 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] +a|The following example searches for `QueueConnectionFactory` appearing in a field declaration was used to obtain connection to JMS queues. Replace the string `QueueConnectionFactory` with `ConnectionFactory`. +[source, yaml] +---- +when: + - java.referenced: + location: FIELD_DECLARATION + pattern: javax.jms.QueueConnectionFactory +---- +|METHOD|Matches against a given method declaration. It can be coupled +with an annotation match. See +xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection] +a|The following example locates all methods that return `java.lang.String`. +[source, yaml] +---- +when: + java.referenced: + location: METHOD + pattern: '* java.lang.String' +---- +|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] +---- +when: + java.referenced: + 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]. +a|The following example locates all classes under the `javax.xml` package occurring in all locations of the source code. +[source, yaml] +---- +when: + java.referenced: + pattern: javax.xml* +---- +|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] +---- +when: + java.referenced: + 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. +a|The following example matches with the import of `org.apache.lucene.search` package and sub packages in the source code. +[source, yaml] +---- +when: + java.referenced: + 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. +a|The following example matches all occurrences of `org.jboss` package and its sub packages in the source code. +[source, yaml] +---- +when: + java.referenced: + location: PACKAGE + pattern: org.jboss* +---- +|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] +---- + when: + java.referenced: + pattern: 'org.jboss.system.ServiceMBeanSupport' + location: INHERITANCE +---- +|=== \ No newline at end of file diff --git a/docs/topics/yaml-java-provider.adoc b/docs/topics/rules-development/yaml-java-provider.adoc similarity index 53% rename from docs/topics/yaml-java-provider.adoc rename to docs/topics/rules-development/yaml-java-provider.adoc index 1da2163b..f2f1a34c 100644 --- a/docs/topics/yaml-java-provider.adoc +++ b/docs/topics/rules-development/yaml-java-provider.adoc @@ -23,7 +23,7 @@ By using the `referenced` capability, the provider finds references in the sourc when: java.referenced: pattern: "" - location: "" + location: "" annotated: "" ---- where: @@ -31,7 +31,7 @@ where: `pattern` :: A regular expression pattern to match. `location` :: Specifies the exact location where the pattern needs to be matched, for example, `IMPORT`. `annotated` :: Checks for specific annotations and their elements, such as name and value, in the Java code using a query. For example, the following query matches the `Bean` (url = “http://www.example.com”) annotation in the method. -+ + + [source,yaml] ---- annotated: @@ -40,3 +40,29 @@ where: - name: url value: "http://www.example.com" ---- + +See xref:java-conditions-capabilities[Java condition and capabilities] for a detailed explanation on `java.referenced` capabilities. + +.`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/open source. +For example, to check if a Java application has a certain dependency, you create a `java.dependency` condition: + +[source, yaml] +---- +when: + java.dependency: + name: junit.junit + upperbound: 4.12.2 + lowerbound: 4.4.0 +---- + +You can use the `dependency` capability to check if a Java application has Fabric8 Kubernetes client of version 5.0.100 or lower: + +[source, yaml] +---- +- java.dependency: + name: io.fabric8.kubernetes-client + lowerbound: 5.0.100 +---- \ No newline at end of file diff --git a/docs/topics/yaml-logical-conditions.adoc b/docs/topics/rules-development/yaml-logical-conditions.adoc similarity index 74% rename from docs/topics/yaml-logical-conditions.adoc rename to docs/topics/rules-development/yaml-logical-conditions.adoc index dea9b3e0..71ab44c7 100644 --- a/docs/topics/yaml-logical-conditions.adoc +++ b/docs/topics/rules-development/yaml-logical-conditions.adoc @@ -7,4 +7,4 @@ = Logical conditions [role="_abstract"] -The analyzer provides two basic logical conditions, `and` and `or`, which you can use to aggregate results of other conditions and create more complex queries. +The analyzer provides two basic logical conditions, `and` and `or`, which you can use to aggregate results of other conditions. diff --git a/docs/topics/rules-development/yaml-message-actions.adoc b/docs/topics/rules-development/yaml-message-actions.adoc new file mode 100644 index 00000000..0ef80e86 --- /dev/null +++ b/docs/topics/rules-development/yaml-message-actions.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: REFERENCE +[id="yaml-message-actions_{context}"] += 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: + +[source,yaml] +---- +- 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. + +[source,yaml] +---- +links: + - url: "konveyor.io" + 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] on the rule. +// link link:#custom-variables[Custom Variables]): + +[source,yaml] +---- +- ruleID: lang-ref-004 + customVariables: + - pattern: '([A-z]+)\.get\(\)' + name: VariableName + message: "Found generic call - {{ VariableName }}" + when: + +---- diff --git a/docs/topics/rules-development/yaml-nested-condition.adoc b/docs/topics/rules-development/yaml-nested-condition.adoc new file mode 100644 index 00000000..bebdf0c4 --- /dev/null +++ b/docs/topics/rules-development/yaml-nested-condition.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: REFERENCE +[id="yaml-nested-condition_{context}"] += Nested conditions + +[role="_abstract"] +Conditions can also be nested within other conditions. + +[source,yaml] +---- +when: + and: + - and: + - go.referenced: "*CustomResourceDefinition*" + - java.referenced: + pattern: "*CustomResourceDefinition*" + - go.referenced: "*CustomResourceDefinition*" +---- \ No newline at end of file diff --git a/docs/topics/yaml-or-condition.adoc b/docs/topics/rules-development/yaml-or-condition.adoc similarity index 100% rename from docs/topics/yaml-or-condition.adoc rename to docs/topics/rules-development/yaml-or-condition.adoc diff --git a/docs/topics/rules-development/yaml-provider-conditions.adoc b/docs/topics/rules-development/yaml-provider-conditions.adoc new file mode 100644 index 00000000..55b6e2fd --- /dev/null +++ b/docs/topics/rules-development/yaml-provider-conditions.adoc @@ -0,0 +1,448 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: REFERENCE +[id="yaml-provider-conditions_{context}"] += Provider 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. + +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. + +[source,terminal] +---- +when: + . + +---- + +The analyzer currently supports the following `provider` conditions: + +* `builtin` +* `java` +* `go` +* `node.js` +* `python` +* `dotnet` + +:FeatureName: Dotnet provider +include::developer-preview-admonition.adoc[] + + +[[table-Supported-providers-and-rule-conditions]] +[options="header"][cols="99,99,99,99"][%autowidth] +|=== + +|Provider rule conditions |Provider name + +| Providers that are fully supported and included in the product +| Java + +| Providers that have rules already defined in the product +| .NET + +|Providers that require custom rulesets for analysis +a| +* Go +* Python +* Node.js +|=== + +//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: + +.Summary of providers and their capabilities +[width="100%",cols="15%,25%,60%",options="header",] +|=== +|Provider Name |Capabilities |Description + +.2+|`java` +|referenced +a|Find references of a pattern with an optional code location for detailed searches. +For example, +[source,yaml] +---- +when: + java.referenced: + +---- +|dependency +a|Check whether the application has a given dependency. +For example, + +[source,yaml] +---- +when: + java.dependency: + +---- + +.5+|`builtin` +|xml +|Search XML files using xpath queries. + + +|`json` +a|Search JSON files using `jsonpath` queries. +For example, +[source, yaml] +---- +when: + builtin.json: + +---- + +|filecontent +a|Search content in regular files using regular expression patterns. +For example, +[source, yaml] +---- +when: + builtin.filecontent: + +---- + + +|file +a|Find files with names matching a given pattern. +For example, +[source, yaml] +---- +when: + builtin.file: + +---- + +|hasTags +a|Check whether a tag is created for the application using a tagging rule. +For example, +[source, yaml] +---- +when: + builtin.hasTags: + +---- + +.2+|`go` +|referenced +a|Find references to a pattern. +For example, +[source,yaml] +---- +when: + go.referenced: + +---- + +|dependency +a|Check whether the application has a given dependency. +For example, +[source,yaml] +---- +when: + go.dependency: + +---- +|=== + +Following the example in the previous table, you can create the first part of the condition that does not contain any of the condition fields. + +.Example + +To create a `java` provider condition that uses the `referenced` capability: + +[source,yaml] +---- +when: + java.referenced: + +---- + +[NOTE] +==== +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: + +.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_rule-provider-conditions[java] +.3+|referenced +|pattern +|Yes +a|Regular expression pattern. +For example, +[source, yaml] +---- +when: + java.referenced: + location: PACKAGE + pattern: org.jboss* +---- + +|location +|No +a|Source code location. See xref:yaml-java-locations_java-conditions-capabilities[Java locations]. +For example, +[source, yaml] +---- +when: + java.referenced: + pattern: org.kubernetes* + location: IMPORT +---- + +|annotated +|No +a|Additional query to inspect annotations. See xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection]. +For example, +[source, yaml] +---- +when: + java.referenced: + location: ANNOTATION + pattern: javax.ejb.Singleton +---- + +.4+|dependency +|name +|Yes +a|Name of the dependency. +For example, +[source, yaml] +---- +when: + java.dependency: + name: junit.junit +---- + +|nameregex +|No +|Regular expression pattern to match the name. + +|upperbound +|No +a|Match versions lower than or equal to. +For example, +[source, yaml] +---- +when: + java.dependency: + name: junit.junit + upperbound: 4.12.2 +---- + +|lowerbound +|No +a|Match versions greater than or equal to. +For example, +[source, yaml] +---- +when: + java.dependency: + name: junit.junit + upperbound: 4.12.2 + lowerbound: 4.4.0 +---- + +.9+|xref:yaml-builtin-provider_rule-provider-conditions[builtin] +.3+|xml +|xpath +|Yes +a|Xpath query +[source, yaml] +---- +when: + builtin.xml: + xpath: "//dependencies/dependency" +---- + +|namespaces +|No +a|A map to scope down query to namespaces. +[source, yaml] +---- +when: + builtin.xml: + filepaths: + - beans.xml + namespaces: + b: http://xmlns.jcp.org/xml/ns/javaee + xpath: /b:beans +---- + +|filepaths +|No +a|Optional list of files to scope down search. +[source, yaml] +---- +when: + or: + - builtin.xml: + xpath: "//dependencies/dependency" + filepaths: "{{poms.filepaths}}" + from: poms + - builtin.file: + pattern: pom.xml + as: poms + ignore: true +---- + +.2+|json +|xpath +|Yes +a|Xpath query +For example, +[source, yaml] +---- +when: + and: + - builtin.json: + xpath: //inclusionTestNode +---- + +|filepaths +|No +a|Optional list of files to scope down search. +For example, +[source, yaml] +---- +when: + and: + - builtin.json: + xpath: //inclusionTestNode + filepaths: "{{incTest.filepaths}}" +---- + +.2+|filecontent +|pattern +|Yes +a|Regular expression pattern to match in content. +For example, + +[source, yaml] +---- +when: + builtin.filecontent: + pattern: "import.*React" +---- + +|filePattern +|No +a|Only search in files with names matching this pattern. +For example, + +[source, yaml] +---- +when: + builtin.filecontent: + pattern: "import.*React" + filePattern: "\\.tsx$" +---- + +|file +|pattern +|Yes +a|Find files with names matching this pattern. +For example, +[source, yaml] +---- +when: + builtin.file: + pattern: "*.go" +---- + +|hasTags +| +| +a|This is an inline list of string tags. See xref:yaml-tag-actions_rule-yaml-actions[Tag action] +For example, + +[source, yaml] +---- +when: + or: + - builtin.hasTags: + - Golang + - Kubernetes +---- + +.5+|xref:yaml-go-provider_rule-provider-conditions[go] +|referenced +|pattern +|Yes +a|Regular expression pattern. +For example, +[source, yaml] +---- +when: + go.referenced: + pattern: "v1beta1.CustomResourceDefinition" +---- + +.4+|dependency +|name +|Yes +a|Name of the dependency. +For example, +[source, yaml] +---- +when: + - go.dependency: + name: sigs.k8s.io/structured-merge-diff/v4 +---- + +|nameregex +|No +|Regular expression pattern to match the name. + +|upperbound +|No +a|Match versions lower than or equal to. +For example, +[source, yaml] +---- +when: + - go.dependency: + name: sigs.k8s.io/structured-merge-diff/v4 + upperbound: v4.2.2 +---- + +|lowerbound +|No +a|Match versions greater than or equal to. +For example, +[source, yaml] +---- +when: + - go.dependency: + name: sigs.k8s.io/structured-merge-diff/v4 + lowerbound: v4.2.0 +---- + +.3+|xref:yaml-dotnet-provider_rule-provider-conditions[dotnet] +.2+|referenced +|pattern +|Yes +|Regular expression to match a reference in the source code. For example, `HttpNotFound`. + +|namespace +|Yes +|Specify the namespace within which the search query must be run. For example, `System.Web.Mvc`. +|=== diff --git a/docs/topics/yaml-rule-actions.adoc b/docs/topics/rules-development/yaml-rule-actions.adoc similarity index 95% rename from docs/topics/yaml-rule-actions.adoc rename to docs/topics/rules-development/yaml-rule-actions.adoc index ac25a42f..0b9fe719 100644 --- a/docs/topics/yaml-rule-actions.adoc +++ b/docs/topics/rules-development/yaml-rule-actions.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: REFERENCE [id="yaml-rule-actions_{context}"] -= Rule actions += Types of rule actions [role="_abstract"] Rules can include the following types of actions: @@ -14,6 +14,7 @@ Rules can include the following types of actions: Each rule includes either one of them or both of them. +[id="message-actions"] .Message actions When a message action matches the rule, it creates an issue. The custom data that providers export can be used in the message. diff --git a/docs/topics/yaml-rule-categories.adoc b/docs/topics/rules-development/yaml-rule-categories.adoc similarity index 86% rename from docs/topics/yaml-rule-categories.adoc rename to docs/topics/rules-development/yaml-rule-categories.adoc index 0eca9d55..fb5523c1 100644 --- a/docs/topics/yaml-rule-categories.adoc +++ b/docs/topics/rules-development/yaml-rule-categories.adoc @@ -7,6 +7,8 @@ = 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. + * `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. diff --git a/docs/topics/rules-development/yaml-rule-conditions.adoc b/docs/topics/rules-development/yaml-rule-conditions.adoc new file mode 100644 index 00000000..1226b9dc --- /dev/null +++ b/docs/topics/rules-development/yaml-rule-conditions.adoc @@ -0,0 +1,14 @@ +// 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/yaml-rule-hyperlinks.adoc b/docs/topics/rules-development/yaml-rule-hyperlinks.adoc similarity index 100% rename from docs/topics/yaml-rule-hyperlinks.adoc rename to docs/topics/rules-development/yaml-rule-hyperlinks.adoc diff --git a/docs/topics/ref_yaml-rule-labels.adoc b/docs/topics/rules-development/yaml-rule-labels.adoc similarity index 71% rename from docs/topics/ref_yaml-rule-labels.adoc rename to docs/topics/rules-development/yaml-rule-labels.adoc index 073332c6..87f03b3a 100644 --- a/docs/topics/ref_yaml-rule-labels.adoc +++ b/docs/topics/rules-development/yaml-rule-labels.adoc @@ -6,7 +6,10 @@ = Rule labels [role="_abstract"] -Labels are `key=val` pairs specified for rules or rulesets as well as dependencies. For dependencies, a provider adds the labels to the dependencies when retrieving them. Labels on a ruleset are automatically inherited by all the rules that belong to it. +Labels are `key=val` pairs specified in rules to filter the rule by the label. During an analysis, you can use the `--label-selector` option to apply the filter for rules or rulesets and the +`--dep-label-selector` option to apply the filter for dependencies. + +For dependencies, a provider adds the labels to the dependencies when retrieving them. Labels on a ruleset are automatically inherited by all the rules that belong to it. .Label format @@ -43,6 +46,7 @@ labels: - "konveyor.io/key" ---- +[id="reserved-label_{context}"] .Reserved labels The analyzer defines some labels that have special meaning as follows: @@ -51,9 +55,11 @@ The analyzer defines some labels that have special meaning as follows: * `konveyor.io/target`: Identifies the target technology to which a rule or a ruleset applies. +* `konveyor.io/include`: Overrides filter behavior for a rule irrespective of the label selector used. The value can either be `always` or `never`. If you specify `always`, the analyzer always filters-in this rule, while for `never`, the analyzer excludes this rule. + .Label selector -The analyzer CLI takes the `--label-selector` field as an option. It is a string expression that supports logical AND, OR, and NOT operations. You can use it to filter-in or filter-out rules by their labels. +The analyzer CLI takes the `--label-selector` field as an option. It is a string expression that supports logical `AND`, `OR`, and `NOT` operations. You can use it to filter-in or filter-out rules by their labels. _Examples:_ @@ -102,8 +108,12 @@ 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: -`konveyor-analyzer ... --dep-label-selector !konveyor.io/dep-source=open-source` +`$ 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` \ No newline at end of file +<<<<<<<< HEAD:docs/topics/ref_yaml-rule-labels.adoc +`konveyor-analyzer ... --dep-label-selector !konveyor.io/exclude` +======== +`mta-cli ... --dep-label-selector !konveyor.io/exclude` +>>>>>>>> a09e56b (MTA-5290 Modularized Rule Development Guide):docs/topics/rules-development/yaml-rule-labels.adoc diff --git a/docs/topics/yaml-rule-structure-syntax.adoc b/docs/topics/rules-development/yaml-rule-metadata.adoc similarity index 54% rename from docs/topics/yaml-rule-structure-syntax.adoc rename to docs/topics/rules-development/yaml-rule-metadata.adoc index a3f849ac..ba817fe8 100644 --- a/docs/topics/yaml-rule-structure-syntax.adoc +++ b/docs/topics/rules-development/yaml-rule-metadata.adoc @@ -2,30 +2,18 @@ // // * docs/rules-development-guide/master.adoc -:_mod-docs-content-type: REFERENCE -[id="yaml-rule-structure-syntax_{context}"] -= YAML rule structure and syntax +:_mod-docs-content-type: CONCEPT -[role="_abstract"] -Rules are written in YAML. They consist of: - -* metadata -* conditions -* actions - -Rules instruct the analyzer to take specified actions when given conditions match. +[id="yaml-rule-metadata-structure_{context}"] += Rule metadata structure -A YAML rule file in {ProductShortName} contains one or more YAML rules. - -[id="yaml-rule-metadata_{context}"] -== Rule metadata - -Rule metadata contains general information about the rule. The structure of metadata is as follows: +[role="_abstract"] +Rule metadata contains a unique rule ID, labels, effort, and category. [source,yaml] ---- -ruleID: "unique_id" -labels: +ruleID: "unique_id" +labels: # key=value pair - "label1=val1" # valid label with value omitted @@ -40,6 +28,6 @@ category: mandatory where: *ruleID* :: This is a unique ID for the rule. It must be unique within the ruleset. - *labels* :: A list of string labels associated with the rule. (See link:./labels.md[Labels]) + *labels* :: A list of string labels associated with the rule. (See xref:yaml-rule-labels_rule-yaml-metadata[Labels]). *effort* :: Effort is an integer value that indicates the level of effort needed to resolve this issue. - *category* :: Category describes severity of the issue for migration. Values can be one of `mandatory`, `potential` or `optional`. For more deails, see xref:yaml-rule-categories_{context}[Rule categories]. + *category* :: Category describes severity of the issue for migration. Values can be one of `mandatory`, `potential` or `optional`. For more details, see xref:yaml-rule-categories_rule-yaml-metadata[Rule categories]. diff --git a/docs/topics/rules-development/yaml-rule-structure-syntax.adoc b/docs/topics/rules-development/yaml-rule-structure-syntax.adoc new file mode 100644 index 00000000..3fd9d329 --- /dev/null +++ b/docs/topics/rules-development/yaml-rule-structure-syntax.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: CONCEPT +[id="yaml-rule-structure-syntax_{context}"] += YAML rule structure and syntax + +[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: + +* metadata +* conditions +* actions + +{ProductShortName} analyzer rules have the following pattern: + +[source, yaml] +---- +ruleID: +labels: +category: +effort: +description: +when: + +message: "message" +tag: + - tag_1, tag_2, tag_3 + - key_1="value_1, value_2" +---- diff --git a/docs/topics/rules-development/yaml-rulesets.adoc b/docs/topics/rules-development/yaml-rulesets.adoc new file mode 100644 index 00000000..4a4ae34d --- /dev/null +++ b/docs/topics/rules-development/yaml-rulesets.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: REFERENCE +[id="yaml-rulesets_{context}"] += 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. + +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. + +[source,yaml] +---- +name: "Name of the ruleset" +description: "Description of the ruleset" +labels: + - key=val +---- +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: + +[source,terminal] +---- +$ 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. +* To use multiple rule files, you need to place them in a directory and to add a `ruleset.yaml` file. Then the directory is treated as a _ruleset_, and you can pass it as input to the `--rules` option. ++ + +Note that if you want to use the `--target` or `--source` option in the CLI, the engine will only select rules that match the label for that target. Therefore, make sure that you have added target or source labels on your rules. See xref:reserved-label_rule-yaml-metadata[Reserved labels] for more details. diff --git a/docs/topics/yaml-tag-actions.adoc b/docs/topics/rules-development/yaml-tag-actions.adoc similarity index 100% rename from docs/topics/yaml-tag-actions.adoc rename to docs/topics/rules-development/yaml-tag-actions.adoc diff --git a/docs/topics/templates/document-attributes.adoc b/docs/topics/templates/document-attributes.adoc index 98da00b3..90e58bd3 100644 --- a/docs/topics/templates/document-attributes.adoc +++ b/docs/topics/templates/document-attributes.adoc @@ -114,3 +114,5 @@ endif::[] :kebab: image:kebab.png[title="Options menu"] :edit: image:icon-edit.png[title="*Edit* icon"] +//Developer Preview and Technology Preview snippets +//Add additional software names as needed -- for example DevPreview-software_name_2 diff --git a/docs/topics/yaml-java-locations.adoc b/docs/topics/yaml-java-locations.adoc deleted file mode 100644 index a046501f..00000000 --- a/docs/topics/yaml-java-locations.adoc +++ /dev/null @@ -1,143 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/rules-development-guide/master.adoc - -:_mod-docs-content-type: REFERENCE - -[id="yaml-java-locations_{context}"] -= Java locations - -[role="_abstract"] -The `java` provider allows scoping the search down to certain source code locations. - -* *IMPORT*: IMPORT allows for searches on class imports. It can either -be used with FQNs or an asterisk to allow for wider matches: - -[source,yaml] ----- -java.referenced: - pattern: org.apache.lucene.search* - location: IMPORT ----- - -would match on each of these imports: - -[source,java] ----- -import org.apache.lucene.search.Query; -import org.apache.lucene.search.Sort; -import org.apache.lucene.search.SortField; ----- - -:warning: If you want to match using an asterisk (`++*++`) for a wider -range of results, it is recommended to place it directly after the -package, not after the dot: - -:no++_++entry++_++sign: `org.apache.lucene.search.++*++` -:white++_++check++_++mark: `org.apache.lucene.search++*++` - -* *PACKAGE*: the PACKAGE location matches on any usage of a package, be -it in an import or used as part of a fully qualified name in the code: - -[source,yaml] ----- -java.referenced: - pattern: org.apache.lucene.search* - location: PACKAGE ----- - -would match on both the import and the fully qualified usage: - -[source,java] ----- -import org.apache.lucene.search.*; ----- - -[source,java] ----- -public class Test { - private org.apache.lucene.search.Query query; -} ----- - -:warning: As in the IMPORT condition, try to avoid using asterisk -(`++*++`) right after the package-separation dot (`.`) for better -results. - -* *CONSTRUCTOR++_++CALL* and *METHOD++_++CALL*: for matching -constructors and methods, respectively. The pattern possibilities are -quite varied, and it is possible to match against specific return types, -arguments, etc. - -For instance, looking for a method named "`method`" declared on -`org.konveyor.MyClass` that returns a `List` of a type that extends -`java.lang.String` and accepts a single parameter: - -[source,yaml] ----- -java.referenced: - location: METHOD - pattern: 'org.konveyor.Myclass.method(*) java.util.List' ----- - -More information about the possibilities of these patterns can be found in 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(java.lang.String,int,int,int)[the official Java documentaion, which contain all the information for building these patterns] in the `createPattern(String, int, int, int)` section. - -[WARNING] -==== -Presently, fully qualified static method matching is prone -to errors. -==== - -* *TYPE*: matches against types in general, appearing anywhere. -* *INHERITANCE*: matches against a class inheriting from a given type. -* *ANNOTATION*: matches against annotations. -* *IMPLEMENTS++_++TYPE*: matches against any type implementing the given -type. -* *ENUM++_++CONSTANT*: matches against enum constants. -* *RETURN++_++TYPE*: matches against a type being returned by a method. -* *VARIABLE++_++DECLARATION*: matches against a type being declared as a -variable. -* *FIELD* (declaration): matches against a type appearing in a field -declaration. It can be coupled with an annotation match, this is, an -annotation happening on the field (see -link:#yaml-java-locations_rules-development-guide[Annotation inspection]) -* *METHOD*: matches against a given method declaration. It can be coupled -with an annotation match (see link:#yaml-java-locations_rules-development-guide[Annotation -inspection]). -* *CLASS* (declaration): matches against a given method declaration. Can -be coupled with an annotation match (see -link:#yaml-java-locations_rules-development-guide[Annotation inspection]). - - -The supported locations are the following: - -* `CONSTRUCTOR_CALL` -* `TYPE` -* `INHERITANCE` -* `METHOD_CALL` -* `ANNOTATION` -* `IMPLEMENTS_TYPE` -* `ENUM_CONSTANT` -* `RETURN_TYPE` -* `IMPORT` -* `VARIABLE_DECLARATION` -* `FIELD` -* `METHOD` - -.`dependency` - -By using the `dependency` capability, the provider finds dependencies for a given application. {ProductShortName} generates a list of the application's dependencies, and you can use this capability to query the list and check whether a certain dependency exists for the application within a given range of the dependency's versions. - -[source,yaml] ----- -when: - java.dependency: - name: "" - upperbound: "" - lowerbound: "" ----- -where: - - `name` :: Name of the dependency to search for. - `upperbound` :: Upper bound on the version of the dependency. - `lowerbound` :: Lower bound on the version of the dependency. diff --git a/docs/topics/yaml-message-actions.adoc b/docs/topics/yaml-message-actions.adoc deleted file mode 100644 index 7be71ebe..00000000 --- a/docs/topics/yaml-message-actions.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/rules-development-guide/master.adoc - -:_mod-docs-content-type: REFERENCE -[id="yaml-message-actions_{context}"] -= Message action - -[role="_abstract"] -A message action is employed to generate an issue with the specified message when a rule matches, for example: - -[source,yaml] ----- -# When a match is found, the analyzer generates incidents with the same message. -message: "helpful message about the violation" ----- - -You can also create a template message to include information about the match that has been interpolated through custom variables on the rule. -// link link:#custom-variables[Custom Variables]): - -[source,yaml] ----- -- ruleID: lang-ref-004 - customVariables: - - pattern: '([A-z]+)\.get\(\)' - name: VariableName - message: "Found generic call - {{ VariableName }}" - when: - ----- diff --git a/docs/topics/yaml-provider-conditions.adoc b/docs/topics/yaml-provider-conditions.adoc deleted file mode 100644 index af69329b..00000000 --- a/docs/topics/yaml-provider-conditions.adoc +++ /dev/null @@ -1,254 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/rules-development-guide/master.adoc - -:_mod-docs-content-type: REFERENCE -[id="yaml-provider-conditions_{context}"] -= Provider 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. - -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. - -[source,terminal] ----- -when: - . - ----- - -The analyzer currently supports the following `provider` conditions: - -* `builtin` -* `java` -* `go` -* `dotnet` - -:FeatureName: Dotnet provider -include::developer-preview-feature.adoc[] - -[[table-Supported-providers-and-rule-conditions]] -[options="header"][cols="99,99,99,99"][%autowidth] -|=== - -|Provider rule conditions |Provider name - -| Providers that are fully supported and included in the product -| Java - -| Providers that have rules already defined in the product -| .NET - -|Providers that require custom rulesets for analysis -a| -* Go -* Python -* Node.js -|=== - - -[NOTE] -==== -Depending on the provider, the fields of the condition, for example, the pattern and location in the previous example changes. -==== - -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: - -[source,yaml] ----- -when: - java.dependency: - name: junit.junit - upperbound: 4.12.2 - lowerbound: 4.4.0 ----- - -The *Analyzer* currently supports the following providers: - -* `builtin` -* `java` -* `go` -* `generic` - -The following table summarizes all the providers and their -capabilities: - -.Summary of providers and their capabilities -[width="100%",cols="15%,25%,60%",options="header",] -|=== -|Provider Name |Capabilities |Description - -.2+|`java` -|referenced -|Find references of a pattern with an optional code location for detailed searches. - -|dependency -|Check whether the application has a given dependency. - -.5+|`builtin` -|xml -|Search XML files using xpath queries. - - -|`json` -|Search JSON files using `jsonpath` queries. - -|filecontent -|Search content in regular files using regular expression patterns. - - -|file -|Find files with names matching a given pattern. - -|hasTags -|Check whether a tag is created for the application using a tagging rule. - -.2+|`go` -|referenced -|Find references to a pattern. - -|dependency -|Check whether the application has a given dependency. -|=== - -Following the example in the previous table, you can create the first part of the condition that does not contain any of the condition fields. - -.Example - -To create a `java` provider condition that uses the `referenced` capability: - -[source,yaml] ----- -when: - java.referenced: - ----- - -[NOTE] -==== -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: - -.Summary of providers, their capabilities, and their fields -[width="100%",cols="10%,10%,10%,10%,60%",options="header",] -|=== -|Provider |Capability |Fields |Required |Description - -.7+|java -.3+|referenced -|pattern -|Yes -|Regular expression pattern - -|location -|No -|Source code location (see xref:#yaml-java-locations_rules-development-guide[Java locations]) - -|annotated -|No -|Additional query to inspect annotations (see xref:#yaml-annotation-inspection_rules-development-guide[Annotation inspection]). - -.4+|dependency -|name -|Yes -|Name of the dependency. - -|nameregex -|No -|Regular expression pattern to match the name. - -|upperbound -|No -|Match versions lower than or equal to - -|lowerbound -|No -|Match versions greater than or equal to - -.9+|builtin -.3+|xml -|xpath -|Yes -|Xpath query - -|namespaces -|No -|A map to scope down query to namespaces - -|filepaths -|No -|Optional list of files to scope down search - -.2+|json -|xpath -|Yes -|Xpath query - -|filepaths -|No -|Optional list of files to scope down search - -.2+|filecontent -|pattern -|Yes -|Regular expression pattern to match in content - -|filePattern -|No -|Only search in files with names matching this pattern - -|file hasTags -|pattern -|Yes -|Find files with names matching this pattern - -|hasTags -| -| -|This is an inline list of string tags. See xref:#yaml-tag-actions_rules-development-guide[Tag action] - -.5+|go -|referenced -|pattern -|Yes -|Regular expression pattern. - -.4+|dependency -|name -|Yes -|Name of the dependency. - -|nameregex -|No -|Regular expression pattern to match the name. - -|upperbound -|No -|Match versions lower than or equal to. - -|lowerbound -|No -|Match versions greater than or equal to. -|=== - -.Example - -For example, to complete the previous `java` condition example we created earlier, search for references of a package: - -[source,yaml] ----- -when: - java.referenced: - location: PACKAGE - pattern: org.jboss* ----- diff --git a/docs/topics/yaml-rule-conditions.adoc b/docs/topics/yaml-rule-conditions.adoc deleted file mode 100644 index 807038cb..00000000 --- a/docs/topics/yaml-rule-conditions.adoc +++ /dev/null @@ -1,25 +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"] -Each rule has a `when` block, which specifies a condition that needs to be met for {ProductShortName} to perform a certain action. - -The `when` block contains one condition, but that condition can have multiple conditions nested under it. - -[source,yaml] ----- -when: - - ----- - -{ProductShortName} supports the following types of conditions: - -* `provider` -* `and` -* `or` diff --git a/docs/topics/yaml-rulesets.adoc b/docs/topics/yaml-rulesets.adoc deleted file mode 100644 index af38ae22..00000000 --- a/docs/topics/yaml-rulesets.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/rules-development-guide/master.adoc - -:_mod-docs-content-type: REFERENCE -[id="yaml-rulesets_{context}"] -= Rulesets - -[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. - -You can create a ruleset by placing one or more YAML rules in a directory and creating a `ruleset.yaml` file at the directory root. When 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. - -The `ruleset.yaml` file stores the metadata of the ruleset. - -[source,yaml] ----- -name: "Name of the ruleset" -description: "Description of the ruleset" -labels: # - - key=val ----- -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: - -[source,terminal] ----- -$ 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 rulesets file. - -On initiation, the mta-cli tool determines the type of application and the provider needed for analysis. It then starts the provider in a container that has the required dependencies and tools. Finally, the provider uses the analyzer to execute a series of rulesets to analyze the source code.