maxulysse/nf-core-utils-migration

nf-core-utils マイグレーション

nf-coreパイプラインをベンダー提供のユーティリティコードから nf-core-utils プラグイン（および直接の nf-schema 呼び出し）に移行し、一度に1つのプラグインバージョンずつ、追加設定でパイプラインを起動しても実行が壊れないようにします。

モジュール meta.yml から構築されるツール引用（citationsOnTheFly、publication ブロック）は、以下の「引用」セクションで、マイグレーション後、別のPRとして扱います。nf-test インフラストラクチャ（tests/lib、スナップショットヘルパー、nft-utils）は対象外です。該当する場合はフォローアップとして言及し、マイグレーションPRには含めないでください。

始める前に参照すべきマイグレーション事例: nf-core/rnavar#233（ベンダーサブワークフローの最初の削除）、nf-core/rnavar#252（ゲノムおよびバージョンヘルパー）、nf-core/seqinspector#241 および nf-core/rnaseq#1977（完全な置き換え）。これらは gh pr diff <n> -R nf-core/<repo> で取得できます。

1. すでにマイグレーション済みのものを棚卸しする

マイグレーションは段階的に行われます。各プラグインリリースでより多くのヘルパーが吸収されるため、「すでに nf-core-utils を使用している」パイプラインでも、プラグイン関数をシャドウするローカルコピーが残っていることがよくあります。ユーザーの開始状態の説明が最新であると仮定しないでください。確認:

ls subworkflows/nf-core/ | grep '^utils_'                      # まだ存在するベンダーサブワークフロー
grep -n '"utils_' modules.json                                  # modules.json 内のエントリ
grep -rn "from 'plugin/" main.nf workflows subworkflows/local   # プラグインからすでにインポートされているもの
grep -n "^def " main.nf workflows/*.nf subworkflows/local/utils_*/main.nf   # ローカルヘルパー定義
grep -n "id '" nextflow.config                                  # 現在のプラグインピン

すべてのローカル def を、ターゲットプラグインバージョンがエクスポートする関数（ステップ2）と比較します。プラグインエクスポートと同じ名前のローカル def は削除候補です。パイプライン固有のロジック（カスタムバリデーション、ツールリスト、パイプライン固有のサマリーテキスト）を持つ def は保持します。

2. ピン留めするプラグインバージョンからシグネチャを読み取る

プラグインAPIはバージョン間で変化し、他のパイプラインの差分は異なるバージョンをターゲットにしている場合があります。メモリに頼らず、キャッシュされたプラグインから実際のシグネチャを読み取ってください:

nextflow plugin install nf-core-utils@<ver>      # またはパイプラインを一度実行する。プラグインは ~/.nextflow/plugins/ に配置される
P=~/.nextflow/plugins/nf-core-utils-<ver>
grep Plugin-Requires $P/classes/META-INF/MANIFEST.MF            # 最低限必要なNextflowバージョン
python3 -c "import json;[print(x['spec']['name'],[p['type'] for p in x['spec']['parameters']]) for x in json.load(open('$P/classes/META-INF/spec.json'))['definitions'] if x['type']=='Function']"
javap -cp $P/classes nfcore.plugin.NfUtilsExtension | grep <function>
javap -cp ~/.nextflow/plugins/nf-schema-<ver>/classes nextflow.validation.ValidationExtension | grep <function>

Plugin-Requires が manifest.nextflowVersion より高い場合、manifest.nextflowVersion、.github/workflows/nf-test.yml の最小 NXF_VER、およびREADMEバッジを同じPRで更新します。

古いピン（たとえば、3.x が paramsSummaryLog(Map, WorkflowMetadata) を削除するため nf-schema 2.x を維持する場合）を意図的に保持する場合は、次のメジャーで壊れる呼び出しサイトをPR説明にリストアップし、フォローアップが可視化されるようにしてください。

3. ヘルパーを置き換える

ベンダーサブワークフローとローカルヘルパーの呼び出しごとの置き換えには references/function-map.md を使用します。nextflow.config にプラグインをピン留めします:

plugins {
    id 'nf-core-utils@<ver>' // nf-core-utils はNextflowパイプライン用のユーティリティコレクションです
    id 'nf-schema@<ver>'     // パイプラインパラメータのバリデーションとサンプルシートからの入力チャネル作成
}

次に、subworkflows/nf-core/utils_nextflow_pipeline、utils_nfcore_pipeline、utils_nfschema_plugin（およびその tests/）とその modules.json エントリを削除します。modules.json の一貫性を保つには nf-core subworkflows remove <name> を使用することを推奨します。modules.json を手動で編集する必要がある場合は、JSONダンプが installed_by 配列を展開してしまうため、その後で npx -y prettier@3 --write modules.json を実行してください。

4. nextflow.config 以外のすべての設定でプラグインをピン留めする

起動時の設定（Seqera Platform の .github/workflows/awsfulltest.yml / awstest.yml の nextflow_config、Tower設定、組織の -c 設定）内の plugins {} ブロックは、パイプライン自身の plugins {} ブロックとマージする代わりに置き換えます。パイプラインが include { ... } from 'plugin/<name>' でインポートしているが、そのブロックにピン留めされていないプラグインは最新リリースに解決され、新しいメジャーが出るとすぐに壊れます。

nextflow.config のバージョンをそのようなブロックごとに正確に繰り返し、さらにそのブロックが独自に追加するプラグインも追加します:

nextflow_config: |
  plugins {
    id 'nf-core-utils@<same as nextflow.config>'
    id 'nf-schema@<same as nextflow.config>'
    id '[email protected]'
  }

ピンが一致していることを確認:

grep -rhoE "id '(nf-core-utils|nf-schema)@[^']+'" nextflow.config .github/workflows/ | sort | uniq -c

すべてのプラグインが単一のバージョンで表示される必要があります。

5. 証拠からプラグイン障害を診断する

Missing process or function X(...) -- Did you mean 'X' instead? は、X という名前の関数は存在するが、引数に一致するオーバーロードがないことを意味します。タイポではなくプラグインバージョンの不一致として解釈し、実際にロードされたバージョンを特定し、そのシグネチャ（ステップ2）を呼び出しサイトと比較してください。

何かを変更する前に、どのバージョンがロードされたかを確認:

• メガテスト / Platform 実行: gh run list -R nf-core/<pipeline> -w "nf-core AWS full size tests" および gh run view <id> --log、または nf-slack が投稿した Slack メッセージ、または Platform 実行ログ。Downloading plugin <name>@<ver> / Starting plugin <name>@<ver> を探します。
• 設定オーバーライドのローカル再現: 外部 plugins {} ブロックのみを含む設定で実行し、ログを確認します。

printf "plugins {\n  id '[email protected]'\n}" > /tmp/override.config
nextflow run . -profile test,docker --outdir /tmp/out -c /tmp/override.config 2>&1 | head -40
grep -E "plugin (nf-schema|nf-core-utils)@" .nextflow.log

これらの情報源が空の場合にのみ、ユーザーにログを依頼してください。

6. 検証

自分が引き起こした障害と、dev にすでに存在する障害を分離します。いずれかを報告する前に、クリーンなワークツリーで失敗したテストまたはlintを再実行します。

git worktree add /tmp/dev-baseline origin/dev
(cd /tmp/dev-baseline && <same test or lint command>)
git worktree remove --force /tmp/dev-baseline

少なくとも以下を実行:

• nextflow lint main.nf workflows subworkflows/local（厳格な構文チェック）
• nf-core pipelines lint
• パイプライン nf-tests。NXF_VER はパイプラインの最小 Nextflow バージョンに設定する
• nextflow run . --help、--help_full、--version。これらのパスは早期に終了し、UTILS_NFSCHEMA_PLUGIN / UTILS_NEXTFLOW_PIPELINE をインライン化するときに壊れやすいため

引用（別PR）

ヘルパーがプラグインから提供されるようになったら、MultiQC の methods 説明で、実際に実行されたツールを citationsOnTheFly（nf-core-utils 0.7.0 以降）と各モジュール meta.yml の tools: エントリを使用して引用できます。これはマイグレーションPRからは除外します。多くのモジュールファイルに影響し、パイプライン全体のスナップショットが変更され、ユーザーが行うべき帰属の決定が含まれるためです。

始める前に references/citations.md を読んでください。簡単に:

1. channel.topic("versions").collect(flat: false) を citationsOnTheFly に配線し、collect 後（MultiQC）の実行ツールをエクストラとして渡します。
2. どのツールが No citation metadata found をログに出力し、スナップショットを壊すかを予測します。実際のツールを引用し、汎用ユーティリティは1エントリずつ正確に無視します。
3. 引用メタデータがどこにあるか（upstream nf-core/modules、モジュールパッチ、またはローカルのオーバーレイファイル）をユーザーと合意します。
4. すべての DOI、著者リスト、タイトルは Crossref / PubMed から取得し、記憶からは決して入力しません。モジュールの引用論文を置き換える前に尋ねてください。
5. モジュールパッチは meta.yml に限定し、レンダリングされた Tools used テキストはテスト実行から読み取ります。

注意点

• スナップショット: プラグインからの softwareVersionsToYAML はタプルバージョンを引用符で囲んだ文字列として保持するため、数値バージョン（1.21 の代わりに "1.21"）を保持していたスナップショットは多くのファイルで変更されます。これは予期された動作です。引用符のみが変更されたことを確認してください。
• タプルと空のストリームが生き残るようにバージョンを収集: rnaseq#1977 は .toList() で収集し、レガシーな versions.yml の出力を entry instanceof Path ? entry.text : entry で読み取るため、リモート作業ディレクトリが機能し続けます。
• ベンダー提供の UTILS_NFSCHEMA_PLUGIN 呼び出しが cast_cli_params: false に依存していた場合は、validateParameters(cast_cli_params: false) を維持してください。インライン化する前に古い呼び出しを確認します。
• getWorkflowVersion() はマニフェストを読み取ります。パイプラインが以前に git サフィックスを出力していた場合は、workflow.manifest.version, workflow.commitId を渡します。
• プラグインからの methodsDescriptionText は String パスを受け取るため、Path ではなく file.toString() を渡します。
• nf-core YAML ファイルはキーを引用符で囲むことがあります（- "gatk4":）。正規表現による一括編集は、引用符で囲まれたキーと引用符で囲まれていないキーの両方にマッチさせ、編集したファイル数が期待されるリストと一致することを確認する必要があります。
• モジュールにパッチを適用する必要がある場合、nf-core modules patch は modules/nf-core/<m>/tests/ 以下の gitignore されているファイルも差分に含めるため、まずピン留めされた SHA にリセットし（git -C ~/.config/nfcore/nf-core/modules show <git_sha>:modules/nf-core/<m>/<file>）、各 .diff が意図したファイルのみを名前指定していることを確認します。

PR

• 最初にPRを開き、実際のPR番号でCHANGELOGエントリを記述します。次の番号を推測すると、他のコントリビューターと競合します。
• CHANGELOG: Changed の下のエントリ、PRがプラグインピンを修正する場合は Fixed エントリ、および新旧バージョンを示す Dependencies - Nextflow plugins テーブル。
• PR説明: プラグインバージョンの移行前/移行後、ピン留めしたすべての外部 plugins {} ブロック、どのヘルパーがプラグインに移動し、どれがローカルに残ったか（およびその理由）、フォローアップ（次メジャーの呼び出しサイト、引用、テストインフラストラクチャ）。