nushell-pro

Nushell Pro

安全で、慣用的かつ移植性が高く、テスト可能な Nushell を書きましょう。主要なワークフローはこのファイルに記載し、詳細なリファレンスは必要なタスクに応じて読み込みます。

運用ワークフロー

1. タスクを特定します。新規スクリプト、デバッグ、レビュー、リファクタリング、モジュール設計、移行、パフォーマンス改善、セキュリティ監査、または Bash への変換です。

2. コードを変更する前に、対象の .nu ファイル、近くにあるテスト、AGENTS.md、既存のプロジェクト規約を確認します。

3. プロジェクトがサポートする Nu の範囲（CI、ドキュメント、またはプロジェクト設定から確認）と、ローカルで現在有効なバージョンの両方を把握します。ローカルのバイナリが互換性の対象を決めると想定しないでください。公式の英語ドキュメントを優先してください。翻訳版は更新が遅れている場合があります。ローカルにドキュメントやソースのチェックアウトがある場合は、それらを確認し、インストール済みの Nu バージョンとは別にリビジョンを記録します。どのシェルからでも、次を優先してください。

   nu --version
   

   すでに Nushell 内にいる場合、または構造化されたバージョンデータが必要な場合は、次を使用します。

   version | get version
   

4. 関連する最小限のリファレンス一式を読み込みます。

   タスク	リファレンス
   Nu 0.116 の移行、補完、フラグの展開、クリーンアップ	Nu 0.116 Migration
   Nu 0.115 の移行、YAML、CLI 引数、コマンドの変更	Nu 0.115 Migration
   Nu 0.114 の移行とバージョン互換性	Nu 0.114 Migration
   文字列、正規表現／グロブ、生成される JS／JSON	String Formats
   セキュリティ、パス、認証情報、破壊的操作	Security
   スクリプト／コードのレビュー	Script Review and Anti-Patterns
   Bash／POSIX からの変換	Bash to Nushell
   モジュール、エクスポート、スクリプト、テスト	Modules & Scripts
   デーモン、バックグラウンドジョブ、E2E スモークテスト	Daemon & E2E Smoke Tests
   型、レコード、リスト、変換	Data & Type System
   ストリーミング、クロージャー、パフォーマンス、診断	Advanced Patterns
   大規模な列指向データ	Dataframes
   よくある間違い	Anti-Patterns

   ここに記載されているのは、最も新しい3つの移行ガイドのみです。それ以前のバージョンについては、移行アーカイブを参照してください。

5. スタイルやパフォーマンスの改善に取りかかる前に、以下の横断的なガードレールを適用します。

6. 生成したスクリプトを初めて実行する前に、想定する範囲で nu-check --debug を使用します。扱いにくい文字列やシリアライズされたペイロードについては、出力が完全に一致することを確認してから、関連するテストを実行してください。パースだけでは、意図しないものの有効な補間を検出できません。構造化された診断情報が必要な場合は、--ide-check を使用します。

7. スタイルやパフォーマンスに関する指摘より先に、セキュリティや正確性に関する問題を報告します。

参照先のファイルが利用できない場合は、その旨を伝え、内容を捏造せずにこのファイルに基づいて作業を続けます。

横断的なガードレール

これらのルールは、すべてのタスク種別に適用されます。Nushell のリリース間で構文や動作が変更されている場合は、それらに依存する前に、ルーティングされたリファレンスを読み込んでください。

型とパイプラインの契約

• パイプライン入力は位置パラメーターではなく、I/O シグネチャで宣言してください。ストリームは単一パスでしか処理できない場合があるため、$in を再利用する必要がある場合は一度だけキャプチャしてください。
• エクスポートするコマンドのパラメーターと入出力シグネチャに型を指定してください。
• 外部データや設定レコードは信頼できないものとして扱ってください。$record.field? のようなオプションアクセスを使い、取得した値の型や値を検証してください。
• default はフォールバック引数を先行評価することに注意してください。フォールバックが失敗する可能性がある場合や、コストが高い場合は、null 安全にするか、明示的に分岐してください。
• 戻り値の型に一貫性を持たせてください。関数が真に多相的でない限り、any は避けてください。
• 呼び出し元のトークン表記を Nushell のリテラル変換より優先して保持する必要がある場合に限り、main のパラメーターで external_arg を使ってください。Nu 0.115 では glob／list<glob> の値が生成されるため、構造化されたアプリケーションデータとして扱う前に検証または変換してください。
• 1 つの値に対する複数の分岐には match を使い、単発のブール述語には if を使ってください。
• Nu 0.116 では、レコードのスプレッドによって名前付きフラグが内部コマンド／カスタムコマンドに渡されます。型が nothing を受け入れない限り、null の値はフラグを省略します。switch が false／null の場合もフラグは省略されます。転送するキーを検証し、デフォルト値／null の意図を保持してください。

外部コマンドとエラー

• 外部コマンドの引数は、補間したコマンド文字列ではなく、それぞれ個別の値として渡してください。終了ステータスが重要な場合は complete を使い、exit_code を確認してください。
• 構造化されたプロセス内エラーには、try/catch と $err.details を優先してください。
• Nu 0.115 では、スパン付きの error make ラベルは {text: ..., span: {start: ..., end: ...}} の形です。古いフラットな {text, start, end} 形式は使わないでください。
• Nu 0.115.0 では、ハンドラーが catch である外側の try の中に try/finally を直接ネストすると、内側の finally が黙ってスキップされます。外側のブロックに finally を付けるか、do／コマンド境界の内側にネストしたブロックを置き、所有する状態がなくなったことをアサートしてください。この不具合は 0.116 で修正されています。サポート対象のバージョンで必要な場合に限り、この回避策を残してください。
• ネストされた Nu の診断をレンダリングしたテキストは、安定したプロトコルではなく、表示用テキストとして扱ってください。CLI テストでは、長いドメイン固有のフレーズを照合する前に、ANSI スタイル、ガター、PTY による折り返しを正規化してください。

セキュリティ停止チェックポイント

コマンドを実行する、ファイルを削除する、認証情報を読み取る、またはパス／パターンを受け取るコードを承認する前に、次の境界を確認してください。

• 信頼できない文字列を nu -c、source、run、^sh -c、^bash -c、^cmd.exe /C に渡さないでください。
• 外部コマンドの引数は、補間したシェルコマンド文字列ではなく、それぞれ個別の値として渡してください。
• 既存のパスをベースディレクトリ配下に制限する場合は、両方のパスを展開し、path relative-to を使って包含関係を証明してください。文字列の starts-with チェックは安全ではありません。/safe/base2 は /safe/base で始まるためです。
• Nu の組み込み mktemp／mktemp --directory を優先してください。これらは移植性があり、パスを直接返します。予測可能な一時ファイル名は使わないでください。
• シークレットのスコープには with-env を使ってください。シークレットをログに出力したり、stdin／設定ファイルを使う方法がある場合に argv で渡したりしないでください。
• 破壊的なパスを、ルート、$nu.home-dir、想定外の型、信頼できない glob から保護してください。TOCTOU と部分的な成功の振る舞いも考慮してください。

まだ存在しない出力パスでは、同じ包含ルールを使って既存の親ディレクトリを検証し、その後、検証済みのリーフ名だけを結合してください。

文字列とフォーマット

• シンプルなリテラルと raw 正規表現文字列を優先し、実際にエスケープが必要な場合にのみ二重引用符を使ってください。
• $'...' は補間しますが、エスケープシーケンスは処理しないことに注意してください。
• 補間の中にリテラルの ( を直接含めるには、$"..." が必要です。 $'...' はエスケープ処理をしないため、その中のすべての ( は補間式の開始となり、\( で防ぐことはできません。$"\(abc)($var)" と書き、$'\(abc)($var)' とは書かないでください。この問題はエラーではなく、気づきにくい形で起こることがよくあります。$'(1 + 1) items' は 2 items と評価されます。文字列フォーマットを参照してください。区切り文字が多いコードを生成する場合は、通常のリテラル文字列の断片とシリアライズしたデータを結合してください。
• インタープリター間でコードとデータを分離してください。固定されたプログラムに argv／stdin／JSON を渡します。API がソースしか受け付けない場合は、対象言語のシリアライズを使った固定の信頼できるテンプレートを使用してください。受信側のツールが評価する場合、単一の argv 文字列もコードです。未加工の値をソースに連結しないでください。
• コマンド／フラグには kebab-case、変数／パラメーターには snake_case、環境変数には SCREAMING_SNAKE_CASE を使ってください。

データ形式とグループ化

• from xml は XML の名前空間の識別情報を失います（Nu 0.115.1 で再現）。結果には要素名と属性名のローカル名のみが保存され、名前空間 URI や宣言は含まれません。たとえば、<x xmlns:r="urn:r" id="plain" r:id="rel"/> は id: rel のみを含む attributes レコードになります。属性の順序を逆にすると、id: plain が残ります。ローカル名が重複する場合、後の属性が前の属性を上書きします。名前空間を考慮する必要がある XML の検索、編集、ラウンドトリップには、このレコードを使わないでください。名前空間対応の XML パーサーを使うか、query xml プラグインが利用できる場合は、--namespaces（名前が重要な場合は --output-names も）を指定して XPath を使ってください。プレフィックスの表記ではなく、名前空間 URI とローカル名を照合してください。
• Nu 0.115 では、from yaml のデフォルトが、文字列以外のキーとタグに厳格な YAML 1.2 になります。入力の仕様が別のシステムによって制御されている場合は、デフォルトを意図せず引き継ぐのではなく、--spec、--multiple、タグの処理、キーの解決方法を固定してください。
• to yaml では、ラウンドトリップできない値をデフォルトで拒否させてください。データ損失が文書化された仕様の一部である場合に限り、オプトアウトし、値を引用符で囲んでください。--non-roundtrip 'null' は 0.115／0.116 の両方で動作し、引用符なしの null は 0.116 以降で動作します。--non-roundtrip 'lossy' だけを指定すると 0.116.0 では引き続き拒否されるため、損失のあるエンコードが本当に必要な場合は --serialize を使ってください。0.116 では --compact-list-indent を --list-indent compact|indented に置き換えてください。
• group-by のレコード出力では null キーを表現できず、Nu 0.115 ではそのグループが省略されます。null のグループを保持または空文字列と区別する必要がある場合は、group-by --to-table を使ってください。

データフローとパフォーマンス

• パイプラインと不変の let バインディングを優先してください。
• 手動のパースや可変の蓄積ではなく、where、select、update、insert、items、transpose、reduce、enumerate を使ってください。
• クロージャー内で mut 変数をキャプチャしないでください。
• for は逐次的な副作用には適していますが、変換式ではありません。リストの結果が必要な場合は each を使ってください。
• par-each は並行処理が安全で有益な場合に限って使ってください。順序や逐次的な副作用が重要な場合は each を維持してください。
• 1 行ずつストリームをパースする場合は、parse の前に lines を追加してください。
• Nu 0.116 では、ストリーム内のエラーは length、columns、is-empty、each while に伝播します。テストではストリームを消費し、上流の問題を修正してください。take until などの行条件コマンドでは、述語の前にフラグを置いてください。
• Nu 0.115 で単純な any／all 述語を使う場合は、直接的な行条件を優先してください。述語に準備処理、分解、再利用が必要な場合は、クロージャーを維持してください。
• 小規模な対話型データにはネイティブテーブルを、大規模な列指向の group-by／join／集計処理には Polars を使ってください。

モジュールとスクリプト

• 意図した API のみをエクスポートし、ヘルパーは非公開にしてください。
• コマンド名をモジュール名と一致させる場合は、export def main を使用してください。
• 呼び出し元から参照できる環境変数の変更には、def --env／export def --env を使用してください。
• コマンド、エイリアス、モジュール、エクスポートの名前にパーサーのキーワードを使用しないでください。 Nu 0.115 では $ans も予約語として扱い、以前の ans バインディングは名前を変更してください。
• source、use、run の対象は、信頼できるものであり、解析時に利用できる必要があります。
• 適切な境界でテストしてください。安定した構造化エラーには関数を直接テストし、引数解析やプロセス境界には CLI のサブプロセスを使用してください。必要に応じて両方を行ってください。
• Nu 0.116 の補完関数では、名前付きの token／place／buffer 入力と、シェルの単語には place.command を使用してください。commandline complete でテストし、出力／フォールバックのルールと @interactive の所有権については、0.116 移行ガイドを読み込んでください。

レビューの順序

コードをレビューするときは、次の順序で指摘事項を報告してください。

1. セキュリティ：インジェクション、パストラバーサル、認証情報、破壊的な操作、一時ファイル、環境の汚染。
2. 正確性：型、null の処理、解析時の制約、終了コード、クリーンアップ／ロールバック、データ形式の契約、プラットフォーム／バージョンの挙動、安定したテスト。
3. 保守性：命名、モジュールの境界、重複、ドキュメント。
4. パフォーマンス：ストリーミング、不要なコレクション化、安全な並列処理、Polars。

プロジェクトのフォーマッター／リンターですでに検出される問題は、ツールの出力で現在失敗していると示されていない限り、指摘しないでください。

検証

通常のスクリプト／モジュールの検証には、nu-check --debug を優先してください。対象のトップレベルコマンドを実行せずに解析し、構文エラーだけでなく解析時の型エラーも報告します。一致する解析モードを使用してください。

nu --no-config-file -c 'nu-check --debug path/to/script.nu'
nu --no-config-file -c 'nu-check --debug --as-module path/to/module.nu'
nu --no-config-file path/to/test-script.nu

• --debug を指定しない場合、無効な内容は false を返しますが、周囲の nu プロセスは終了コード 0 のままになることがあります。ブール値を明示的に処理してください。--debug を指定すると、解析エラーがスローされるため、捕捉されないエラーが発生するとゼロ以外で終了します。ファイルが存在しない場合はエラーになります。どちらのモードも、実行時の正しさを証明するものではなく、サンドボックスも提供しません。
• 相対インポートを含む保存済みスクリプトを検査する場合は、ファイルパスを直接渡してください。テキストを nu-check にパイプすると、名前のないソースとして検査されます。パイプライン入力がある場合、任意のパスを指定してもファイルのインポートコンテキストは復元されません。
• スパンと診断レコードを必要とするエディター／CI との統合には、nu --no-config-file --ide-check 100 path/to/script.nu を使用してください。
• --ide-check は標準出力に JSON Lines を出力し、レコードが type: "diagnostic" かつ severity: "Error" の場合でも、終了コードが 0 のままになることがあります。古いバージョンでは、ファイルが存在しない場合も出力なしで 0 を返します。0.116 ではこのケースが修正され、ゼロ以外で終了します。バージョンをまたいで検査する場合は、パスを確認してください。空でない行はすべて from json で解析し、プロセスの終了コードだけを使わないでください。severity: "Error" の診断はブロッカーとして扱い、Warning などの他の重大度はブロックせずに提示し、type: "hint" のレコードは無視してください。ゼロ以外の終了コードや標準エラー出力は、CLI の起動または I/O の失敗として別途処理してください。
• 再現可能な単独検査には、--no-config-file を優先してください。スクリプトがユーザー設定のコマンドや環境に意図的に依存する場合は省略し、その依存関係を文書化してください。
• source はトップレベルのコードを実行するものであり、構文検査ではありません。監査済みの定義やセットアップを意図的に読み込む場合にのみ使用してください。副作用のあるスクリプトは nu-check／--ide-check で検証してから、管理下の一時的なテスト用フィクスチャで実行してください。構造化データを保存する場合は、認識されるデータ拡張子を使用するか、save の前に明示的にシリアライズしてください（to json、to yaml、to nuon など）。
• Nu 0.115 以降では nu --testbin を使用しないでください。必要な動作は Nushell 自体または目的に応じたテスト用フィクスチャで再現してください。
• 診断やテーブルが関係する場合は、たとえば stty cols 24 && nu tests/example.nu のように、狭い PTY を使ってターミナルに依存するテストを再現してください。
• 完了前に、デバッグ用マーカーや意図しない変更がないか差分を確認してください。
• 検証に失敗した場合は、再現可能な最小の問題を修正し、テストスイートを広げる前に、失敗したコマンドをそのまま再実行してください。