はじめに

GitHub Actions のワークフローから node scripts/xxx.mjs --require FOO,BAR -- ... のように自作スクリプトを呼び出していたところ、未使用コード検出ツール knip が「Unresolved imports」を出し続けるようになりました。
原因は knip のバグではなく、自作フラグ名 --require が Node.js ランタイムの予約フラグと同じだったことです。

この記事では、誤検知が起きる仕組みと、フラグ名を変えるだけで解決した流れ、再発防止のために入れたテストの考え方を整理します。
自作CLIを作る方や、CI上で静的解析を回している方が、同じ罠を避けるための参考になれば幸いです。

こんな人におすすめ

  • node script.mjs --独自フラグ の形で自作CLIをワークフローから呼んでいる方
  • knip などの静的解析ツールの誤検知に悩んでいる方
  • CLIのフラグ名をどう決めるか、設計の指針がほしい方
  • 小さな修正でも回帰防止テストをきちんと残したい方

何が起きていたのか

ワークフローには次のようなステップがありました。

- run: node scripts/load-nightly-env.mjs --source SOME_ENV --require KEY1,KEY2 -- bash some-script.sh

このスクリプトは、環境変数のバンドルを読み込み、必須キーが揃っているか確認してから、-- 以降のコマンドを子プロセスで実行する小さなラッパーです。
--require KEY1,KEY2 は「このキーが無ければ失敗させる」という意味で付けた、自作のフラグでした。

ところが knip の GitHub Actions プラグインは、run: に書かれた node <script> ... を解析するとき、Node.js のフラグを理解して引数を読みます。
Node.js には --require(短縮形 -r)という「起動前にモジュールを読み込む」予約フラグがあります。
そのため knip は KEY1,KEY2 を「読み込むモジュールの指定子」と解釈し、解決できない import として報告していたと考えられます。

同じ理由で、--loader / --experimental-loader / --import なども、自作フラグに使うと同種の誤検知を招く可能性があります。

解決策:衝突する側の名前を変える

設定ファイルで knip に除外ルールを足す方法もあります。
ただ、除外を増やすと、本当に壊れた import まで見逃す余地が生まれます。
そこで、衝突している自分側の名前を変えるのが最も安価だと判断しました。

引数パーサーの変更は1行です。

// scripts/load-nightly-env.mjs
- } else if (arg === '--require') {
+ } else if (arg === '--required') {
    opts.required.push(...String(argv[++i] ?? '').split(',').map((item) => item.trim()).filter(Boolean))

ロジックは変えず、意味を保ったまま予約語と衝突しない --required にしただけです。
呼び出し側のワークフローも追随させます。

- run: node scripts/load-nightly-env.mjs --source SOME_ENV --require KEY1,KEY2 -- bash some-script.sh
+ run: node scripts/load-nightly-env.mjs --source SOME_ENV --required KEY1,KEY2 -- bash some-script.sh

呼び出し側は複数のワークフローに散らばっていたため、今回は3本をまとめて修正しました。
リネームでは git grep -- '--require' のように横断検索して、漏れを確認するのが安全です。

再発防止:旧フラグ名が失敗する契約をテストに残す

リネームだけだと、いつか誰かが旧名を書き戻すかもしれません。
そこで「旧フラグ名は未知の引数としてエラーになる」ことをテストで固定しました。

it('rejects the legacy --require flag name (reserved by Node.js module loading)', async () => {
  await expect(
    main(['--source', 'BUNDLE', '--require', 'MISSING', '--', 'bash'], { BUNDLE: 'OTHER=value' }),
  ).rejects.toThrow('unknown argument: --require')
})

単なる動作確認ではなく、「間違った名前は黙って通さず明示的に失敗する」という契約を残している点がポイントです。
あわせて runbook にも、誤検知が起きた理由と「予約フラグ名を使わない」方針を書き残しました。

周辺テストも一緒に拡充する

今回の差分は、追加201行のうち193行がテストでした。
フラグ名の変更は小さくても、パーサー周りのエッジケースを洗い出す良い機会になります。

  • 不正なフラグ
  • -- 以降のコマンドが欠けている場合
  • --source と --file の排他条件
  • 子プロセスがシグナルで終了した場合
  • spawn 自体のエラー

子プロセスのモックは、重複を避けるためヘルパーにまとめました。

// 終了コードを返す子プロセスのスタブを共通化する例
function makeExitingChild(code) {
  return {
    on(event, handler) {
      if (event === 'exit') handler(code, null)
      return this
    },
  }
}

これでテストケースを足すときの記述量が減り、追加のハードルが下がります。
また、環境変数バンドルを「直接指定(--source / --file)」と「別の環境変数でファイルパスを間接指定」の両方でテストしておくと、CIでシークレットを渡す2通りの経路を押さえられます。

つまづきやすいポイント

  • ツール側のバグだと思い込む: 誤検知が続くと設定の調整に時間を使いがちですが、まず自分の引数名がランタイムの予約語と被っていないか確認すると早く切り分けられます
  • リネーム漏れ: 呼び出し元が複数のワークフローに散らばっていると、1か所の修正漏れで本番のジョブが失敗します。横断検索で確認してください
  • 除外設定で済ませてしまう: 除外ルールは将来の見逃しにつながりやすく、命名の変更のほうが保守コストは低い傾向があります
  • 旧名の復活: テストと runbook で残さないと、別のメンバーが同じ名前を選び直す可能性があります

まとめ

自作CLIのフラグ名は、自分のツールの中だけで完結しません。
node <script> <args> の形で呼ばれる以上、Node.js の予約フラグと衝突すると、静的解析ツールが引数をランタイムへの指示と誤解釈することがあります。
今回は --require を --required に変えるだけで解決しました。
あわせて旧名が失敗するテストと runbook を残しておくと、再発を防ぎやすくなります。