validating-pre-commit

用途

该技能用于在提交（commit）或推送（push）代码前运行强制性的质量门禁检查，确保所有代码质量标准得到满足。它按顺序执行质量检查清单，并在失败时报告可操作的修复建议。

何时使用

创建提交或推送到远程之前
做出重大变更之后
CI 失败且需要在本地复现时

主要能力

该技能提供一组质量检查命令，包括：

自动修复：pnpm check:fix，修复 lint/格式问题
构建：pnpm build，编译 TypeScript
测试：pnpm test，运行所有测试
类型检查：npx tsc --noEmit，严格 TS 验证
CI 检查：pnpm check:ci，完整 CI 验证
仅 lint：pnpm lint，检查 linting
仅格式：pnpm format，检查格式化
一次性全部执行：pnpm check:fix && pnpm build && pnpm test && pnpm check:ci

使用方式

强制质量检查清单

按顺序执行以下步骤，全部通过后方可提交。

步骤 1：自动修复 lint 和格式

pnpm check:fix

自动修复 Biome 问题（导入、逗号、引号、缩进）。如果仍有问题，需手动修复复杂度警告、未使用变量或类型错误。

步骤 2：验证 TypeScript 编译

pnpm build

确保项目可编译。检查最近变更中的类型不匹配、缺失导出或导入解析错误。

步骤 3：运行所有测试

pnpm test

如果测试失败：阅读失败信息，检查预期是否与新行为匹配，更新测试或修复实现，使用 pnpm test -- --filter=<test-file> 重新运行。

步骤 4：严格 TypeScript 检查

npx tsc --noEmit

比构建捕获更多问题：隐式 any、未使用的导入/变量、更严格的 null 检查。

步骤 5：最终 CI 验证

pnpm check:ci

运行与 CI 相同的检查（不自动修复的 linting、格式检查、TypeScript 编译）。

E2E CLI 测试协议

何时运行：在推送影响核心 CLI 功能（命令、服务、仓库）的变更之前。

# Credentials from .env.local (see .env.example for template)
# source .env.local

# 1. Clean slate
rm -rf config.yml

# 2. Fresh introspection
pnpm dev introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN

# 3. Deploy changes
pnpm dev deploy --url=$SALEOR_URL --token=$SALEOR_TOKEN

# 4. Test idempotency (deploy again - should have no changes)
pnpm dev deploy --url=$SALEOR_URL --token=$SALEOR_TOKEN

# 5. Clean and re-introspect
rm config.yml
pnpm dev introspect --url=<URL> --token=<TOKEN>

# 6. Verify no drift
pnpm dev diff --url=<URL> --token=<TOKEN>

成功标准：步骤 4 显示无变更（幂等性）。步骤 6 显示无差异（往返一致性）。

常见错误

错误	修复
生产代码中使用 any 类型	使用正确的类型或 unknown + 类型守卫
遗留未使用的导入	移除或使用它（Biome 自动修复可处理）
对象可能为 undefined	使用可选链（?.）或提前返回守卫
类型不可赋值	检查类型定义并确保兼容性
Mock 未返回预期值	`vi.mocked(service.method).mockResolvedValue(expected)`
在 check:fix 后跳过 check:ci	始终运行两者；check:ci 捕获无法自动修复的问题
核心变更忘记 E2E 测试	对任何 CLI 命令变更运行上述完整 E2E 协议

自动化检查

项目具有 Husky pre-push 钩子（.husky/pre-push），会自动生成 schema 文档。这些钩子会自动运行。

参考

scripts/validate-all.sh - 一键验证脚本
docs/TESTING_PROTOCOLS.md - E2E 测试详情
biome.json - Linting 配置

快速参考规则

如需精简快速参考，参见 .claude/rules/deployment-safety.md（始终加载 - 适用于所有文件）。

技能介绍

用途