Enforce pnpm version consistency to prevent lockfile format churn

[Copilot]

Different pnpm versions serialize pnpm-lock.yaml differently (quote styles, formatting), causing PR noise despite packageManager: "pnpm@10.20.0" being set. Contributors weren't using corepack, and CI didn't enforce the version.

Changes

Validation Scripts

• scripts/check-pnpm-version.mjs - Validates installed pnpm matches packageManager field, exits 1 on mismatch
• scripts/check-lockfile.mjs - Warns when lockfile changes without package.json changes (non-blocking)

CI Enforcement (deploy.yml, content-check.yml, sync-uuid.yml)

• Explicit corepack enable before pnpm setup
• Run version check before install
• Verify lockfile unchanged after pnpm install --frozen-lockfile, fail if modified
• Multi-method version extraction for robust error reporting

Developer Experience

• Pre-commit hook runs checks (warnings only)
• npm scripts: check:pnpm-version, check:lockfile
• Error messages include fix commands

Documentation

• CONTRIBUTING.md: corepack setup, troubleshooting for version mismatches
• README: version requirement warnings
• PNPM_LOCKFILE_GUIDE.md: technical deep-dive, FAQ

Example Error Output

❌ pnpm version mismatch!
   Expected: 10.20.0 (from package.json packageManager field)
   Actual:   9.5.0

Option 1 - Use corepack (recommended):
  corepack enable
  corepack prepare pnpm@10.20.0 --activate

Option 2 - Install the correct pnpm version globally:
  npm install -g pnpm@10.20.0

CI will now catch version mismatches before merge, preventing lockfile format drift in PRs.

Original prompt

当时我们是锁版本了的 "packageManager": "pnpm@10.20.0",

TITLE: pnpm 版本升级导致 pnpm-lock.yaml 单/双引号频繁切换的问题排查

USER INTENT:
理解并解决在已通过 packageManager 字段锁定 pnpm 版本的情况下，pnpm-lock.yaml 仍然在不同环境/更新后频繁出现单双引号风格切换，从而造成开源协作中的无意义 diff 的问题。

TASK DESCRIPTION:

• 分析为何在项目已经设置 "packageManager": "pnpm@10.20.0" 的前提下，pnpm-lock.yaml 仍然在更新或使用 pnpm 时出现单双引号切换。
• 希望找到避免或减轻该问题对开源协作（PR diff 噪音、代码审查）的干扰的方案。
• 关注点集中在：
  • pnpm 版本锁定是否真正生效
  • pnpm 以及其依赖（如 YAML 序列化库）在不同环境下的行为差异
  • 如何在工具链、CI 配置和贡献者指南层面减少无意义的锁文件格式 diff。

EXISTING:

• 项目中已在 package.json 里设置了 packageManager 字段来锁定 pnpm 版本，例如：

  {
    "packageManager": "pnpm@10.20.0"
  }

• 已意识到 pnpm 版本变动会导致 pnpm-lock.yaml 序列化风格产生差异（单双引号），从而导致大量无意义 diff。
• 当前协作方式：开源社区有多位贡献者，锁文件 diff 对 PR 审查造成干扰。

PENDING:

• 进一步确认并保证所有开发者和 CI 实际使用的 pnpm 版本与 packageManager 中指定的版本完全一致（包括：是否启用 corepack、是否有人绕过 packageManager 直接全局安装不同版本的 pnpm）。
• 在 CI 中增加对 pnpm-lock.yaml 的一致性检查（如安装依赖后运行检测，若锁文件有变动则 CI 失败），以强制执行统一的锁文件格式。
• 如果确认版本已统一但问题仍存在，需要进一步排查：
  • pnpm 10.20.0 是否在不同平台/Node 版本上存在非确定性序列化（例如依赖的 YAML 库版本或实现差异）。
  • 是否存在其他工具或脚本在修改 pnpm-lock.yaml。
• 可能需要：
  • 在 CONTRIBUTING.md 中明确要求使用 corepack + 指定 pnpm 版本。
  • 在团队内制定对锁文件 diff 的审查策略，减少单/双引号这类格式 diff 的心理负担。

CODE STATE:
当前对话中没有给出完整文件内容，只有关键配置片段：

1. package.json 节选：

   {
     "packageManager": "pnpm@10.20.0"
   }

2. 之前讨论过的（通常的）锁版本示例（非当前项目真实配置，只是说明用法）：

   {
     "packageManager": "pnpm@9.0.0"
   }

3. 建议过的 corepack 使用方式（同样是示例用法）：

   corepack enable
   corepack prepare pnpm@9.0.0 --activate

RELEVANT CODE/DOCUMENTATION SNIPPETS:

• packageManager 字段的使用：

  {
    "packageManager": "pnpm@10.20.0"
  }

  该字段意图是让 Node（配合 corepack）知晓项目期望的包管理器及版本，从而在项目根目录执行包管理命令时自动选用对应版本。

• 锁文件差异问题背景（概念性说明，非具体代码）：

  • 不同版本的 pnpm 在序列化 pnpm-lock.yaml 时，可能使用了不同的 YAML 库或配置，导致相同逻辑数据在文件中可能以单引号或双引号表现。
  • 当贡献者在本地使用了与项目声明不一致的 pnpm 版本时，重新生成或更新锁文件，就会触发大量引号风格上的差异 diff。

OTHER NOTES:

• 用户明确指出：项目已经做了版本锁定（"packageManager": "pnpm@10.20.0"），但仍然遇到锁文件单双引号切换的问题，这意味着问题并不只是“没有锁版本”这么简单。
• 后续需要重点验证：
  • 开发者是否都启用了 corepack，还是有人直接用 pnpm 全局命令（可能是其他版本）操作项目。
  • CI 环境是否安装和使用的确实是 10.20.0，而不是 Actions 默认的或缓存中的其他版本。
  • 是否存在 pnpm 10.20.0 自身在不同 Node / 平台 / 依赖组合下引号风格不稳定的已知问题（需要查阅 pnpm issue 或 release note）。
• 当前总结集中在问题背景和现有约束，尚未进入具体排障步骤和最终解决方案实施。

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
involutionhell-github-io	Ready	Preview, Comment	Dec 14, 2025 5:57pm
website-preview	Ready	Preview, Comment	Dec 14, 2025 5:57pm