開発者ツール · JSON フォーマッタおよびバリデータ
CI が行う前に壊れた package.json を修正します: エラー位置を読み取ります
· なぜそれが重要なのか
json 開発者ワークフロー 検証
手動で編集した package.json、composer.json、または launch.json は、通常は CI で保存してからかなり時間が経っても失敗します。この投稿では、コミット前に検証してエラー位置をすばやく読み取る方法を示します。
1 つのコンマについて学ぶための 12 分間のパイプライン
1 つのコンマ、つまり手動で解決されたマージ競合、緑のエディター、赤のビルドについて学ぶ 12 分間のパイプライン。 Git はマニフェストが解析するかどうかではなくバイトを記録するため、リポジトリのチェックアウトは正常に見えることがあります。その後、CI は依存関係をインストールし、破損したファイルに到達し、テストで有用な信号が得られる前に停止します。
このツールは厳密な JSON 構文のみをチェックし、最大 8,000,000 JavaScript 文字までのドキュメントを受け入れます。 package.jsonとcomposer.jsonは、適切な厳密な例です。 tsconfig.json などのファイルはコメント許容パーサーを使用している可能性があるため、コメントを JSON として拒否しても、所有ツールがコメントを拒否することは証明されません。使用側プログラムが実際に宣言している文法に照らして検証します。
最も頻繁に破損する JSON 構成ファイル
最も頻繁に破損する JSON 構成ファイル (package.json、composer.json、launch.json、およびロック ファイル)、およびコメントを許可する tsconfig.json については別の注意が必要である理由。人間が編集したマニフェストは、依存関係ブロック、スクリプト、ネストされたツール設定に関して失敗する傾向があります。生成されたロック ファイルの失敗方法は異なります。手動で競合を解決すると、区切り文字が損傷したり、構造セクションが重複したりする可能性があります。
JSON のような拡張子を持つすべてのファイルが厳密な JSON を使用すると想定しないでください。 VS Code 設定と TypeScript 構成では通常、特殊なパーサーを介してコメントまたは末尾のカンマを許可しますが、パッケージ マニフェストでは通常許可しません。有効な構文だけでは、ジェネレーターが期待するハッシュ、順序付けルール、または内部一貫性を復元できないため、可能であれば、生成されたロック ファイルをパッケージ マネージャーで検証してください。
ツールが遅れて失敗する理由 — パッケージ マネージャーとコンパイラーはオンデマンドで解析するため、構文エラーは保存時ではなくインストール時またはビルド時に発生します。
ツールが遅く失敗する理由 — パッケージ マネージャーとコンパイラーはオンデマンドで解析するため、構文エラーは保存時ではなくインストール時またはビルド時に発生します。テキスト エディタは、権限のあるパーサーを実行せずに中括弧に色を付ける可能性があり、狭いローカル タスク中に変更されたマニフェストを読み取れない可能性があります。 CI はクリーンな環境から開始され、キャッシュされたワークステーションがスキップするセットアップ パスを実行します。
結果として生じる遅延には、キュー時間、チェックアウト、依存関係のセットアップ、および関連のない予備ジョブが含まれます。さらに悪いことに、最終的なメッセージでは、元の行がコマンド出力の背後に隠れて、無効なパッケージ ファイルのみが指定される可能性があります。編集直後のローカル解析により、そのフィードバック ループが崩壊します。また、文法上の失敗を、後で別の調査が必要となる依存関係の解決やスキーマのエラーから分離します。
圧力下でのエラー位置の読み取り
プレッシャーの下でエラー位置を読み取ります。行と列、前のトークン、および無効な JSON を生成する 3 つのマージ競合パターンです。マークされた文字は継続が不可能になった場所であり、必ずしも間違いが始まった場所ではありません。終了引用符は、以前のエスケープされていない引用符を露出させる可能性があります。中括弧を使用すると、次のプロパティの直前にカンマが欠落していることが明らかになる場合があります。
マージ後、プレーン テキストとして残っている競合マーカー、カンマなしで結合された重複したメンバー ブロック、一方の側を選択するときに削除された区切り文字を探します。報告された場所の前にトークンを検査し、周囲のコンテナ境界をカウントします。パーサーは通常、最初の障害のみを報告し、2 番目の独立した競合がさらに下に残る可能性があるため、1 回修復して検証を再実行し、元の差分を保存します。
うまくいった例: 不適切なマージ後の package.json
うまくいった例: 不適切なマージ後の package.json — 依存関係ブロックの重複、カンマの欠落、検証レポートおよび修正。 `"scripts":{"test":"vitest"}` の直後に `"dependencies":{"vite":"7.3.6"}` が続くことを想像してください。 2 番目のプロパティ名では、スクリプト オブジェクトの後に修正用のカンマが属しているにもかかわらず、オブジェクトに区切り文字がないことがパーサーによって検出されます。
カンマを挿入し、フォーマットする前に再度検証してください。マージによって 2 つの `dependencies` キーも生成された場合でも、構文的に重複した名前が許可されているため、厳密な解析は成功する可能性がありますが、JavaScript 解析では後の値のみが保持されます。ブロックを機械的に削除するのではなく、両方のブランチを比較し、目的のメンバーを結合します。構文修復とセマンティック マージ解決は連続した別個のタスクです。
検証を習慣にする
検証を習慣にする — コミット前に貼り付けるか、IDE の外部で編集した JSON を、アカウントやプラグインを必要とせずに検証します。最良のトリガーは動作です。競合マーカーが解決されたとき、大きなブロックが移動されたとき、または句読点が手動で入力されたときは必ず、ファイルをステージングする前に、所有ツールのチェックまたは厳密なパーサーを実行します。
リポジトリは、コミット前のチェックとマニフェストに範囲を限定した CI ジョブを使用して同じルールを自動化できますが、自動化は最初のパーサーになるのではなく、即時のフィードバックを補完する必要があります。差分に意味のある文字が表示されるように、フォーマットは修復とは別にしてください。生成されたファイルの場合、手動で編集した出力を正規化する代わりにソース マニフェストから再生成し、ジェネレーターに独自の不変条件を証明させます。
これでカバーされない内容
これでカバーされないもの — 間違ったバージョン範囲や不明なフィールドなどの意味上の間違いは、有効な JSON では保護できません。パッケージ マニフェストは、存在しないスクリプトに名前を付けたり、依存関係を間違ったセクションに配置したり、予期せず解決されるバージョン式を使用したりするときに解析される可能性があります。重複キーは、以前の値をサイレントに置き換えながら文法チェックに合格することもできます。
パッケージ マネージャーの検証、スキーマを使用し、テストをインストールし、それらのレイヤーを確認します。このチェックでは、ロック ファイルがそのマニフェストと一致することや、起動構成がインストールされているデバッガに名前を付けていることも証明されません。実際の形式が JSONC または別の方言である場合は、厳密な JSON を満たすためだけにサポートされている構文を削除するのではなく、そのパーサーを使用してください。文法は最初のゲートであり、完全な構成契約ではありません。
要点: 構文チェックには数秒かかりますが、パイプラインの失敗には数分かかります
要点: 構文チェックには数秒のコストがかかり、パイプラインの失敗には数分のコストがかかります。また、バリデーターの正確なレポートによって修正が短縮されます。最後に編集されたバイトに対して実行し、報告された行と列から開始して、前のトークンに区切り文字や区切り文字がないかどうかを検査します。後のエラーは最初は隠されている可能性があるため、修正のたびに再検証してください。
厳密な構文に合格したら、コンシューマーに戻ります。許可されたフィールドと値を理解するパッケージ マネージャー、コンパイラー、またはエディター固有の検証を実行します。特にマージ後は修復差分を狭く保ち、レビュー担当者が句読点と依存関係の決定を区別できるようにします。このシーケンスは、最も安価な障害をローカルで捕捉し、完全な環境のみが評価できる動作のために高価なパイプライン時間を予約します。