lockdrift

lockdrift

npm プロジェクト向けのロックファイル差分監査ツールです。lockdrift は、package.json で宣言された依存関係の範囲と、package-lock.json で実際に解決されたバージョンを比較し、両者に差異がある箇所を報告します。

• 宣言された依存関係にロックファイルのエントリーがない（LOCK-MISSING、高）
• ロックされたバージョンが宣言された範囲を満たさない（RANGE-VIOLATED、高。declared ^1.2.0, locked 2.0.0 などの根拠を表示）
• ロックされたトップレベルパッケージが、どこにも宣言されておらず、どこからも依存されていない（EXTRANEOUS、低）
• lockdrift が評価できない形式の宣言範囲（RANGE-UNSUPPORTED、情報）：未チェックとしてカウントされ、違反として扱われることはありません

重大度の高い検出結果がない場合、レポートの判定は IN-SYNC となり、それ以外の場合は DRIFT となります。重大度の低い「余分」な項目や情報レベルの未対応項目だけでは、判定は変わりません。すべてのレポートに、declared、locked、missing、violated、extraneous、unchecked の件数が含まれます。出力は決定的で、タイムスタンプは含まれません。

モノレポ：ルートの package.json で workspaces が宣言されている場合、または packages/ ディレクトリに package.json ファイルがある場合、各ワークスペースの package.json もルートのロックファイルと照合されます。packages/* などのワークスペースグロブは1階層まで展開されます。それ以外の形式のパターンは WORKSPACES-NOTED 情報レベルの検出結果として報告され、チェック済みとして黙って扱われることはありません。

インストール

npx @reneturcios/lockdrift check .

または、依存関係として、あるいはグローバルツールとしてインストールできます。

npm install @reneturcios/lockdrift

CLI

lockdrift check [path] [--json]
lockdrift mcp
lockdrift --version

• check は対象ディレクトリを監査します（デフォルト：カレントディレクトリ）。機械可読なレポートを出力するには --json を追加します。判定が IN-SYNC の場合は終了コード 0、DRIFT の場合は 1、使用方法または入力エラーの場合は 2 です（たとえば package.json または package-lock.json がない場合は、レポートではなく明確なエラーがスローされます）。
• mcp は stdio 経由で MCP サーバーを起動します。
• --version はバージョンを出力します。

MCP

MCP サーバーは、次のツールを1つ公開します。

• check_lockfile。path 引数を受け取ります。CLI と同じチェックを実行し、完全な JSON レポート（ツール名、バージョン、対象、判定、件数、検出結果、概要）を返します。

対応する範囲形式

次のいずれかの形式に該当する場合、ロックされたバージョンは宣言された範囲を満たします。

• 完全一致：1.2.3
• キャレット：^1.2.3（同じメジャーバージョン。0.x にはルールが適用されるため、^0.2.3 は >=0.2.3 <0.3.0、^0.0.3 は 0.0.3 との完全一致を意味します）
• チルダ：~1.2.3（>=1.2.3 <1.3.0 を意味します）
• 単純な比較演算子：>=1.2.3、>1.2.3、<1.2.3、<=1.2.3
• 比較演算子をスペース区切りで並べた AND 条件。例：>=1.0.0 <2.0.0
• *、latest、空の範囲：常に満たされます

プレリリースまたはビルドのサフィックスが付いたバージョン（1.2.3-beta.1 など）は、数値部分だけを比較し、サフィックスは無視します。

これ以外の形式は未対応として、「未チェック」を返します。推測で判定することはありません。URL、Git リファレンス、file: などのプロトコル範囲、workspace: 範囲、npm: エイリアス、|| による結合、ハイフン範囲、^1 や ^1.2 などの部分バージョンが該当します。

余分な項目の判定方法

余分な項目のルールが評価されるのは、node_modules/ のトップレベルにあるエントリーだけです。トップレベルでロックされたパッケージは、チェック対象のいずれの package.json にも宣言されておらず、ローカルのワークスペースパッケージでもなく、さらにどのロックエントリーの dependencies、peerDependencies、optionalDependencies にも記載されていない場合に、余分な項目と判定されます。この参照セットは、推移的依存関係を v0.1 向けに近似したものです。パッケージごとにグラフをたどることはありません。別のパッケージの node_modules/ 内にあるネストされたコピーは評価せず、各名前のトップレベルエントリーのみを評価します。

制限事項

• npm のロックファイルのみが対象です。lockdrift は package-lock.json のロックファイル v3 packages マップを読み取ります。v0.1 では yarn または pnpm のロックファイルには対応していません。
• 未対応の範囲は未チェックとして報告されます。推測による判定は行わず、違反としてフラグ付けされることもありません。
• 静的解析のみです。チェック対象のリポジトリ内で何かをインストールまたは実行することはありません。
• ルートのロックエントリー（packages マップ内の空文字列キー）は package.json の内容を反映するもので、ロックされたパッケージとしては扱いません。

開発

npm install
npm run build
npm test