第2章 YAML ルールを作成する
各アナライザールールは、ソースコードを解析し、移行時に問題となる問題を検出するために使用される、一連の命令です。
アナライザーはユーザーが指定したルールを解析し、それをアプリケーションのソースコードに適用し、一致したルールの問題を生成します。ルールセットは、1 つ以上のルールが集合して形成されます。ルールセットを作成することで、共通の目標を達成する複数のルールを編成できます。アナライザー CLI は、ルールセットを入力引数として受け取ります。
2.1. YAML ルールの構造と構文 リンクのコピーリンクがクリップボードにコピーされました!
MTA ルールは YAML で記述されます。各ルールはメタデータ、条件、およびアクションで構成され、アナライザーに対して、指定した条件が一致する場合に指定したアクションを実行するように指示します。
MTA の YAML ルールファイルには、1 つ以上の YAML ルールが含まれています。
2.1.1. ルールのメタデータ リンクのコピーリンクがクリップボードにコピーされました!
ルールのメタデータには、ルールに関する一般情報が含まれています。メタデータの構造は次のとおりです。
2.1.1.1. ルールのラベル リンクのコピーリンクがクリップボードにコピーされました!
ラベルは、ルールまたはルールセット、および依存関係に対して指定された key=val のペアです。依存関係の場合、プロバイダーは依存関係を取得する際にラベルを依存関係に追加します。ルールセットのラベルは、それに属するすべてのルールに自動的に継承されます。
ラベル形式
ラベルは key=val 形式の文字列のリストとして、labels フィールドの下に次のように指定されます。
labels: - "key1=val1" - "key2=val2"
labels:
- "key1=val1"
- "key2=val2"
ラベルのキーにはサブドメインの接頭辞を付けることができます。
labels: - "konveyor.io/key1=val1"
labels:
- "konveyor.io/key1=val1"
ラベルの値は空にすることもできます。
labels: - "konveyor.io/key="
labels:
- "konveyor.io/key="
ラベルの値は省略できます。その場合は空の値として処理されます。
labels: - "konveyor.io/key"
labels:
- "konveyor.io/key"
予約済みラベル
アナライザーは、次のように特別な意味を持ついくつかのラベルを定義します。
-
konveyor.io/source: ルールまたはルールセットが適用されるソーステクノロジーを識別します。 -
konveyor.io/target: ルールまたはルールセットが適用されるターゲットテクノロジーを識別します。
ラベルセレクター
アナライザー CLI は、オプションとして --label-selector フィールドを使用します。これは、論理演算 AND、OR、NOT をサポートする文字列式です。これを使用して、ラベルに基づきルールをフィルターインまたはフィルターアウトできます。
例:
キーが
konveyor.io/source、値がeap6のラベルを持つすべてのルールをフィルターインするには、次のようにします。--label-selector="konveyor.io/source=eap6"konveyor.io/sourceキーと任意の値のラベルを持つすべてのルールをフィルターインするには、次のようにします。--label-selector="konveyor.io/source"複数のルールの一致に対して
&&演算子を使用して論理 AND 演算を実行するには、次のようにします。--label-selector="key1=val1 && key2"複数のルールの一致に対して
||演算子を使用して論理 OR 演算を実行するには、次のようにします。--label-selector="key1=val1 || key2"!演算子を使用して NOT 演算を実行し、key1=val1ラベルが設定されているルールをフィルターアウトするには、次のようにします。--label-selector="!key1=val1"部分式をグループ化し、AND を使用して優先順位を制御するには、次のようにします。
--label-selector="(key1=val1 || key2=val2) && !val3"
依存関係ラベル
アナライザーエンジンは、依存関係にラベルを追加します。このラベルは、プログラミング言語や依存関係がオープンソースか内部依存かなど、依存関係に関する追加情報を提供します。
現在、アナライザーは次のラベルを依存関係に追加します。
labels: - konveyor.io/dep-source=internal - konveyor.io/language=java
labels:
- konveyor.io/dep-source=internal
- konveyor.io/language=java
依存関係ラベルセレクター
アナライザー CLI は --dep-label-selector オプションを受け入れます。これにより、依存関係から生成されたインシデントを、ラベルに基づきフィルターインまたはフィルターアウトできます。
たとえばアナライザーは、依存関係が既知のオープンソース依存関係であるかどうかを示す値を持つ konveyor.io/dep-source ラベルを依存関係に追加します。
このようなオープンソース依存関係のインシデントをすべて除外するには、次のように --dep-label-selector を使用します。
konveyor-analyzer … --dep-label-selector !konveyor.io/dep-source=open-source
アナライザーの Java プロバイダーは、パッケージのリストに除外ラベルを追加することもできます。このようなパッケージをすべて除外するには、次のように --dep-label-selector と ! 演算子を使用します。
konveyor-analyzer … --dep-label-selector !konveyor.io/exclude
2.1.1.2. ルールのカテゴリー リンクのコピーリンクがクリップボードにコピーされました!
mandatory- 移行を成功させるには問題を解決する必要があります。解決しない場合、結果として得られるアプリケーションは正常にビルドまたは実行されません。このような問題の例としては、ターゲットプラットフォームでサポートされていないプロプライエタリー API があります。
optional- 問題を解決しない場合、アプリケーションは正常に動作するはずですが、最適な結果にはならない可能性があります。移行時に変更しない場合は、移行完了後すぐに変更するようスケジュールする必要があります。このような問題の例としては、EJB 2.x コードが EJB 3 にアップグレードされていない場合が挙げられます。
potential- 移行プロセス中に問題を調べる必要がありますが、移行を成功させるために問題の解決が必須かどうかを判断するのに十分な情報がありません。このような問題の例としては、ターゲットプラットフォームに直接互換性のある型がない場合に、サードパーティー独自の型を移行する場合が挙げられます。
2.1.1.3. ルールアクション リンクのコピーリンクがクリップボードにコピーされました!
ルールには、message と tag の 2 種類のアクションを含めることができます。各ルールには、いずれか一方または両方が含まれます。
メッセージアクション
メッセージアクションは、ルールが一致した場合にメッセージに関する問題を作成します。メッセージでは、プロバイダーによってエクスポートされたカスタムデータも使用できます。
message: "helpful message about the issue"
以下に例を示します。
- ruleID: test-rule
when:
<CONDITION>
message: Test rule matched. Please resolve this migration issue.
- ruleID: test-rule
when:
<CONDITION>
message: Test rule matched. Please resolve this migration issue.
オプションで、問題に関する関連情報や簡単な修正を提供する外部 URL へのハイパーリンクをメッセージに含めることができます。
links:
- url: "konveyor.io"
title: "Short title for the link"
links:
- url: "konveyor.io"
title: "Short title for the link"
メッセージは、ルールのカスタム変数を通じて挿入される、一致に関する情報を含めるテンプレートにすることもできます。
タグアクション
タグアクションは、一致が見つかった場合にアプリケーション用に 1 つ以上のタグを生成するようにアナライザーに指示します。tag フィールドの各文字列は、タグのコンマ区切りリストにできます。オプションで、タグにカテゴリーを割り当てることができます。
tag: - "tag1,tag2,tag3" - "Category=tag4,tag5"
tag:
- "tag1,tag2,tag3"
- "Category=tag4,tag5"
例:
タグは、文字列または key=val ペアにすることができ、キーは MTA のタグカテゴリーとして処理されます。このドキュメントでは、タグアクションを持つルールは「タグ付けルール」と呼ばれます。
タグアクションしか持たないルールに対しては問題が作成されない点に注意してください。
2.1.1.4. ルール条件 リンクのコピーリンクがクリップボードにコピーされました!
各ルールには、MTA が特定のアクションを実行するために満たす必要のある条件を指定する when ブロックがあります。
when ブロックには 1 つの条件が含まれますが、その条件の下に複数の条件をネストできます。
when:
<condition>
<nested-condition>
when:
<condition>
<nested-condition>
MTA は、provider、and、or の 3 種類の条件をサポートします。
2.1.1.4.1. プロバイダー条件 リンクのコピーリンクがクリップボードにコピーされました!
アプリケーションアナライザーは、アプリケーションの構築に使用されているプログラミング言語、フレームワーク、およびツールを検出し、それに応じて Language Server Protocol (LSP) を使用して、サポートされている各プロバイダーのデフォルトのルールセットを生成します。サポートされている各プロバイダーは、デフォルトで定義済みのルールセットを持ち、個別のコンテナーで独立して実行されます。
MTA は多言語ソースコード分析をサポートします。ソースコード内の特定の言語の検索は、provider 条件を使用して有効にします。この条件は、特定の言語プロバイダーの検索クエリーを定義します。provider 条件では、コードの分析に使用するプロバイダーの "ケイパビリティー" も指定します。
provider 条件の形式は <provider_name>.<capability> です。
when:
<provider_name>.<capability>
<input_fields>
when:
<provider_name>.<capability>
<input_fields>
アナライザーは現在、次の provider 条件をサポートしています。
-
builtin -
java -
Go -
dotnet
CLI で複数のアプリケーションを分析するときに 1 つのレポートを提供するためのサポートは、テクノロジープレビュー機能です。テクノロジープレビュー機能は、Red Hat 製品のサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではないことがあります。Red Hat は、実稼働環境でこれらを使用することを推奨していません。テクノロジープレビューの機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行いフィードバックを提供していただくことを目的としています。
Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、テクノロジープレビュー機能のサポート範囲 を参照してください。
| プロバイダールールの条件 | プロバイダー名 |
|---|---|
| 完全にサポートされ、製品に含まれているプロバイダー | Java |
| 製品内ですでにルールが定義されているプロバイダー | .NET |
| 分析にカスタムルールセットを必要とするプロバイダー |
|
2.1.1.4.1.1. builtin プロバイダー リンクのコピーリンクがクリップボードにコピーされました!
builtin は、エンジンによって生成されたさまざまなファイルと内部メタデータを分析できる内部プロバイダーです。
このプロバイダーには次のケイパビリティーがあります。
-
file -
filecontent -
xml -
json -
hasTags
file
file ケイパビリティーを使用すると、プロバイダーは指定されたパターンに一致するソースコード内のファイルを検索できます。
when:
builtin.file:
pattern: "<regex_to_match_filenames>"
when:
builtin.file:
pattern: "<regex_to_match_filenames>"
filecontent
filecontent ケイパビリティーを使用すると、プロバイダーは指定されたパターンに一致するコンテンツを検索できます。
when:
builtin.filecontent:
filePattern: "<regex_to_match_filenames_to_scope_search>"
pattern: "<regex_to_match_content_in_the_matching_files>"
when:
builtin.filecontent:
filePattern: "<regex_to_match_filenames_to_scope_search>"
pattern: "<regex_to_match_content_in_the_matching_files>"
xml
xml ケイパビリティーを使用すると、プロバイダーは指定された XML ファイルのリストに対して XPath 式のクエリーを実行できます。このケイパビリティーでは、xpath と filepaths という 2 つの入力パラメーターを使用できます。
json
json ケイパビリティーを使用すると、プロバイダーは指定された JSON ファイルのリストに対して XPath 式のクエリーを実行できます。現在、json は XPath のみを入力として受け取り、コードベース内のすべての JSON ファイルに対して検索を実行します。
when:
builtin.json:
xpath: "<xpath_expressions>"
when:
builtin.json:
xpath: "<xpath_expressions>"
- 1
xpathは、有効な XPath 式である必要があります。
hasTags
hasTags ケイパビリティーを使用すると、プロバイダーはアプリケーションタグをクエリーできます。内部データ構造をクエリーして、アプリケーションに指定されたタグがあるかどうかを確認します。
when:
# when more than one tag is given, a logical AND is implied
hasTags:
- "tag1"
- "tag2"
when:
# when more than one tag is given, a logical AND is implied
hasTags:
- "tag1"
- "tag2"
- 1
- 複数のタグが指定されている場合は、論理積が暗黙的に指定されます。
2.1.1.4.1.2. java プロバイダー リンクのコピーリンクがクリップボードにコピーされました!
java プロバイダーは、Java ソースコードを分析します。
このプロバイダーには次のケイパビリティーがあります。
-
referenced -
dependency
referenced
referenced ケイパビリティーを使用すると、プロバイダーはソースコード内の参照を見つけることができます。この機能には、pattern、location、annotated という 3 つの入力パラメーターを使用できます。
when:
java.referenced:
pattern: "<pattern>"
location: "<location>"
annotated: "<annotated>"
when:
java.referenced:
pattern: "<pattern>"
location: "<location>"
annotated: "<annotated>"
- 1
- 照合する正規表現パターン (例:
org.kubernetes.*)。 - 2
- パターンを照合する必要がある正確な場所を指定します (例:
IMPORT)。 - 3
- クエリーを使用して、Java コード内の名前や値などの特定のアノテーションとその要素をチェックします。たとえば、次のクエリーはメソッド内の Bean (url = “http://www.example.com”) アノテーションと一致します。
annotated: pattern: org.framework.Bean elements: - name: url value: "http://www.example.com"annotated: pattern: org.framework.Bean elements: - name: url value: "http://www.example.com"Copy to Clipboard Copied! Toggle word wrap Toggle overflow
次の場所がサポートされています。
-
CONSTRUCTOR_CALL -
TYPE -
INHERITANCE -
METHOD_CALL -
ANNOTATION -
IMPLEMENTS_TYPE -
ENUM_CONSTANT -
RETURN_TYPE -
IMPORT -
VARIABLE_DECLARATION -
FIELD -
METHOD
dependency
dependency ケイパビリティーを使用すると、プロバイダーは指定されたアプリケーションの依存関係を見つけることができます。MTA は、アプリケーションの依存関係のリストを生成します。このケイパビリティーを使用してリストをクエリーし、依存関係バージョンの指定された範囲内でアプリケーションに特定の依存関係が存在するかどうかを確認できます。
when:
java.dependency:
name: "<dependency_name>"
upperbound: "<version_string>"
lowerbound: "<version_string>"
when:
java.dependency:
name: "<dependency_name>"
upperbound: "<version_string>"
lowerbound: "<version_string>"
2.1.1.4.1.3. go プロバイダー リンクのコピーリンクがクリップボードにコピーされました!
go プロバイダーは、Go ソースコードを分析します。このプロバイダーのケイパビリティーは、referenced と dependency です。
referenced
referenced ケイパビリティーを使用すると、プロバイダーはソースコード内の参照を見つけることができます。
when: go.referenced: "<regex_to_find_reference>"
when:
go.referenced: "<regex_to_find_reference>"
dependency
dependency ケイパビリティーを使用すると、プロバイダーはアプリケーションの依存関係を検索できます。
when:
go.dependency:
name: "<dependency_name>"
upperbound: "<version_string>"
lowerbound: "<version_string>"
when:
go.dependency:
name: "<dependency_name>"
upperbound: "<version_string>"
lowerbound: "<version_string>"
2.1.1.4.1.4. dotnet プロバイダー リンクのコピーリンクがクリップボードにコピーされました!
dotnet は、.NET および C# ソースコードを分析するために使用される外部プロバイダーです。現在、このプロバイダーは referenced 機能をサポートしています。
referenced
referenced ケイパビリティーを使用すると、プロバイダーはソースコード内の参照を見つけることができます。
when:
dotnet.referenced:
pattern: "<pattern>"
namespace: "<namespace>"
when:
dotnet.referenced:
pattern: "<pattern>"
namespace: "<namespace>"
2.1.1.4.2. カスタム変数 リンクのコピーリンクがクリップボードにコピーされました!
プロバイダー条件には、カスタム変数を関連付けることができます。カスタム変数を使用すると、ソースコード内の一致する行から関連情報を取得できます。これらの変数の値には、ソースコード内で一致するデータが挿入されます。これらの値を使用して、ルールのアクションで詳細なテンプレート化されたメッセージを生成できます (メッセージアクション を参照)。これらは、customVariables フィールドのルールに追加できます。
2.1.1.5. 論理条件 リンクのコピーリンクがクリップボードにコピーされました!
アナライザーには、and と or の 2 つの基本的な論理条件があります。これらを使用して、他の条件の結果を集計し、より複雑なクエリーを作成できます。
2.1.1.5.1. and 条件 リンクのコピーリンクがクリップボードにコピーされました!
and 条件は、条件の配列の結果に対して論理 AND 演算を実行します。and 条件は、その子条件が すべて 一致する場合に一致します。
when:
and:
- <condition1>
- <condition2>
when:
and:
- <condition1>
- <condition2>
例:
条件は、他の条件内でネストすることもできます。
例:
2.1.1.5.2. or 条件 リンクのコピーリンクがクリップボードにコピーされました!
or 条件は、条件の配列の結果に対して論理 OR 演算を実行します。or 条件は、その子条件の いずれか が一致する場合に一致します。
when:
or:
- <condition1>
- <condition2>
when:
or:
- <condition1>
- <condition2>
例:
2.1.2. ルールセット リンクのコピーリンクがクリップボードにコピーされました!
ルールセットは、一連のルールで形成されます。MTA では、ルールファイルが必ずルールセットに属する必要はありません。しかし、ルールセットを使用することで、共通の目標を達成する複数のルールをグループ化し、そのルールをルールエンジンに渡すことができます。
ルールセットを作成するには、1 つ以上の YAML ルールをディレクトリーに配置し、そのディレクトリールートに ruleset.yaml ファイルを作成します。このディレクトリーを、--rules オプションを使用して MTA CLI への入力として渡すと、このディレクトリー内のすべてのルールは、ruleset.yaml ファイルで定義されたルールセットの一部として処理されます。
ruleset.yaml ファイルには、ルールセットのメタデータが保存されます。
name: "Name of the ruleset" description: "Description of the ruleset" labels: - key=val
name: "Name of the ruleset"
description: "Description of the ruleset"
labels:
- key=val
アプリケーション分析を実行するには、次のコマンドを実行します。<application_to_analyze> をアプリケーションに、<output_dir> を任意のディレクトリーに、<custom_rule_dir> をカスタムルールセットファイルに置き換えます。
mta-cli analyze --input=<application_to_analyze> --output=<output_dir> --rules=<custom_rule_dir> --enable-default-rulesets=false
$ mta-cli analyze --input=<application_to_analyze> --output=<output_dir> --rules=<custom_rule_dir> --enable-default-rulesets=false
mta-cli ツールは、まず分析に必要なアプリケーションの種類と対応するプロバイダーを決定します。次に、必要な依存関係とツールを持つコンテナー内でプロバイダーを起動します。最後に、プロバイダーがアナライザーを使用して一連のルールセットを実行し、ソースコードを分析します。