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。仅有额外（低）和不支持（信息）发现不会改变判定结果。每份报告都包含以下计数：已声明、已锁定、缺失、违反范围、额外和未检查。输出是确定性的，不包含时间戳。

Monorepo：当根目录的 package.json 声明了 workspaces，或 packages/ 目录中包含 package.json 文件时，也会使用根锁文件检查每个工作区的 package.json。packages/* 等工作区 glob 会展开一层。其他形式的模式会通过 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 服务提供一个工具：

• check_lockfile，带有一个 path 参数：运行与 CLI 相同的检查，并返回完整的 JSON 报告（工具名称、版本、目标、判定结果、计数、发现和摘要）。

支持的范围格式

以下格式之一表示锁定版本符合声明的范围：

• 精确版本：1.2.3
• caret：^1.2.3（同一主版本；适用 0.x 规则，因此 ^0.2.3 表示 >=0.2.3 <0.3.0，而 ^0.0.3 表示恰好为 0.0.3）
• tilde：~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