reviewing-lwc-mobile-offline

LWC モバイルオフラインのレビュー

Lightning Web コンポーネントに対して、オフラインプライミングのコンプライアンスを体系的に確認し、検出した問題と、Salesforce Mobile App Plus および Field Service Mobile App 向けの Komaci の静的解析要件にコンポーネントを準拠させるためのコードレベルの修正を報告します。

使用するタイミング

• 特定の LWC に対して「モバイルオフラインレビュー」「Komaci チェック」「オフラインプライミング監査」を依頼された場合。
• Salesforce Mobile App Plus または Field Service Mobile App のオフラインモードでリリースするコンポーネントを準備する場合。
• オフラインアナライザーが報告したプライミング失敗を調査する場合。

次の場合はこのスキルを使用しないでください。

• ネイティブモバイル機能（バーコードスキャナー、生体認証、位置情報など）を使用する LWC を構築する場合 — using-mobile-native-capabilities を使用してください。
• 一般的な LWC コードレビュー — 適切なドメインスキル（reviewing-lws-security、reviewing-lwc-rtl、accessibility-code-review）を使用してください。

前提条件

• コンポーネントのパス（modules/… 配下の LWC バンドル）。
• コンポーネントの JS/TS と HTML テンプレートへのアクセス。
• ローカルの Node と npm、および @salesforce/eslint-plugin-lwc-graph-analyzer プラグインで npx eslint を実行できること。

ナレッジベース

モバイルオフラインの基礎知識では、3 種類の違反カテゴリと、それぞれがオフラインプライミングを妨げる理由を説明しています。判定する前に読んでください。ルールと修正方法の一次情報は、以下のレビュー担当者向けリファレンスです。

• インライン GraphQL ワイヤー設定：インライン GraphQL レビュー担当者
• lwc:if の条件付きレンダリングの互換性：lwc:if レビュー担当者
• Komaci ESLint 静的解析：Komaci ESLint レビュー担当者

ワークフロー

ステップ 1 — レビュー対象を特定する

コンポーネントバンドルを特定します：.html、.js/.ts。CSS とメタファイルはオフラインプライミングの対象外です。バンドルに複数の HTML テンプレートがある場合は、すべてレビューします。

ステップ 2 — 基礎知識とレビュー担当者向けリファレンスを読む

判定する前に、モバイルオフラインの基礎知識と 3 つのレビュー担当者向けリファレンスを最初から最後まで読んでください。報告の監査可能性を確保するため、各指摘を出す際には、該当するレビュー担当者を明記してください。

ステップ 3 — lwc:if / lwc:elseif / lwc:else（HTML）

バンドル内のすべての .html ファイルを確認し、lwc:if レビュー担当者のルールを適用します。lwc:if={…}、lwc:elseif={…}、または lwc:else の各出現箇所について、lwc:elseif と lwc:else の意味を保持するために必要なネストを含め、正確な if:true / if:false への書き換えを示す指摘を出します。

ステップ 4 — @wire 内のインライン GraphQL（JS）

バンドル内のすべての .js/.ts ファイルを確認し、インライン GraphQL レビュー担当者のルールを適用します。gql テンプレートリテラルを直接（またはトップレベル定数を介して）参照する @wire ごとに、具体的なゲッターを示し、書き換え後の @wire 設定を提示する指摘を出します。

ステップ 5 — Komaci ESLint の実行（JS）

同梱スクリプトを使用して、バンドルの JS ファイルに対して Komaci ESLint アナライザーを実行します。このアナライザーは、bundleAnalyzer プロセッサを有効にした @salesforce/eslint-plugin-lwc-graph-analyzer の推奨ルールセットを適用します。

scripts/run-komaci.sh path/to/component.js

このスクリプトでは、作業ディレクトリから @salesforce/eslint-plugin-lwc-graph-analyzer を解決できる必要があります。また、プラグインの bundleAnalyzer プロセッサはオフラインデータグラフの解決に使用するため、コンポーネントの兄弟 HTML テンプレートが JS ファイルの隣に置かれている必要があります。出力は標準出力への ESLint --format json です。

出力内の各 messages[*] エントリについて、ruleId ごとにまとめ、Komaci ESLint レビュー担当者でルールごとの修正方法を確認します。参照先に記載された正確な修正テキストを使い、ルールと行の各組み合わせにつき指摘を 1 件出してください。新たな助言を作り出さないでください。実行環境でスクリプトを利用できない場合の手動での npx eslint ... の実行方法については、リファレンスを参照してください。

Step 6 — レポートを作成する

次の形式でレポートを出力します。

## Mobile Offline (Komaci priming)
- <reviewer> — <file>:<startLine>:<startColumn>-<endLine>:<endColumn> — <type>
  Description: <verbatim from the reviewer reference>
  Intent analysis: <verbatim from the reviewer reference>
  Suggested action: <verbatim from the reviewer reference>
  Code: |
    <source snippet from startLine through endLine, optional but
     recommended when the violation spans multiple lines>
  Applied: yes/no

## Summary
- <n> issues found; <m> fixed; <k> deferred (with reason)

Komaci ESLint の指摘では、ESLint メッセージの line／column／endLine／endColumn から startLine／startColumn／endLine／endColumn を取得します。 Inline GraphQL と lwc:if の指摘では、ソースで確認した行／列の範囲を指定します。指摘に endLine／endColumn がない場合は、<file>:<startLine> にフォールバックし、末尾の範囲を省略します。

すべての指摘に、レビュー担当者（Inline GraphQL／lwc:if／Komaci ESLint のルール ID）を記載します。

Step 7 — 修正を適用する

ユーザーが修正を依頼した場合は、修正を直接適用します。修正内容がオフライン以外でのコンポーネントの動作と競合する場合（たとえば、開発者が読みやすさのために lwc:elseif を使用していて、ユーザーがまだモバイルオフライン向けにリリースしていない場合）は、黙って書き換えるのではなく、保留リストにその競合を記載します。

検証チェックリスト

• lwc:if／lwc:elseif／lwc:else をすべて確認し、指摘の有無を記載している。
• gql を参照する @wire をすべて確認し、インラインクエリをゲッターに抽出している。
• Komaci ESLint アナライザーを実際に実行し、実在するルール ID を指摘に記載している。架空のルール ID は使用していない。
• 各指摘に、該当するレビュー担当者またはルール ID を記載している。
• 上記の3つのカテゴリ以外の修正を行っていない（ほかの懸念事項は別のスキルで扱う）。

トラブルシューティング

• npx eslint でプラグインが見つからない — ワークスペースに @salesforce/eslint-plugin-lwc-graph-analyzer をインストールするか、固定したローカルインストールパスを使用します。このプラグインは、Komaci ルールの正規の提供元です。
• bundleAnalyzer 関連のエラー — 推奨設定ではバンドルプロセッサーが使用されます。これを削除しないでください。プロセッサーが同階層の HTML ファイルを検出できることを前提としています。簡略化した JS ファイルに対して実行する場合は、一致する HTML ファイルを一時ディレクトリに用意してください。
• 失敗すると予想されるコンポーネントで指摘がない — 推奨ルールセットが適用されていることを確認してください（ルールが空の bundleAnalyzer だけではありません）。HTML を JS と同じ場所に用意する必要があるルールもあります。
• 専用レビュー担当者の lwc:if に関する指摘と重複している — Komaci プラグインはテンプレートをチェックしません。lwc:if のチェックは HTML のみを対象とし、Step 3 で実施します。Step 5 の指摘は JS のみを対象とします。