makefile-validator

Makefile 验证器

概述

使用此技能，通过本地优先、确定性的流程验证 Makefile。

默认验证器入口：

bash scripts/validate_makefile.sh <makefile-path>

验证层：

1. 依赖预检（python3、pip3、make）
2. GNU make 语法检查（make 可用时运行 make -n --dry-run）
3. mbake validate
4. mbake format --check
5. 自定义安全性、最佳实践和优化检查
6. 安装了 checkmake 和 unmake 时进行可选检查

触发指南

当请求涉及 Makefile 质量、lint、验证、加固或故障排查时，使用此技能。

触发短语

• “验证此 Makefile”
• “Lint 我的 .mk 文件”
• “找出此构建 Makefile 中的问题”
• “检查 Makefile 的安全问题”
• “在 CI 前审查此 Makefile”

不触发示例

• 从头创建全新的 Makefile（使用 makefile-generator）
• 作为交付的一部分运行构建目标
• 与 Makefile 无关的一般 Shell 脚本工作

确定性执行模型

从此技能目录运行，以使用最短命令：

cd devops-skills-plugin/skills/makefile-validator

步骤 1：预检

1. 确认目标文件存在且可读。
2. 确认是否允许编辑文件（writable），或只能返回建议（read-only）。
3. 优先使用默认验证器路径；仅在环境限制阻碍执行时使用备用方案。

步骤 2：基线验证（默认路径）

# From skill directory
bash scripts/validate_makefile.sh <makefile-path>

# From repository root
bash devops-skills-plugin/skills/makefile-validator/scripts/validate_makefile.sh <makefile-path>

始终记录：

• 执行的命令
• 退出代码
• 摘要计数（Errors、Warnings、Info）
• 工具报告的问题位置

步骤 3：解读输出和退出代码

退出代码	含义	预期摘要行	操作
0	无阻断性发现	Validation PASSED	仅做可选改进
1	仅有警告	Validation PASSED with warnings	建议修复；取决于合并策略
2	存在错误	Validation FAILED - errors must be fixed	必须修复，然后重新运行

步骤 4：按需加载参考资料

仅打开解决当前发现所需的文档。

发现类型	参考文档
.PHONY、.DELETE_ON_ERROR、.ONESHELL、变量用法、性能结构	docs/best-practices.md
制表符与空格、依赖错误、凭据模式、反模式	docs/common-mistakes.md
mbake 行为、格式化器标志、已知的 mbake 注意事项	docs/bake-tool.md

步骤 5：修复并重新运行

应用修复后，重新运行：

bash scripts/validate_makefile.sh <makefile-path>

循环规则：

1. 仅当没有引入新错误时才停止。
2. 如果有意保留警告，请说明接受这些警告的原因。
3. 始终报告最近一次重新运行的退出代码。

如何打开文档

使用明确的文件打开命令，避免路径产生歧义。

从仓库根目录运行：

sed -n '1,220p' devops-skills-plugin/skills/makefile-validator/docs/best-practices.md
sed -n '1,220p' devops-skills-plugin/skills/makefile-validator/docs/common-mistakes.md
sed -n '1,220p' devops-skills-plugin/skills/makefile-validator/docs/bake-tool.md
rg -n "PHONY|DELETE_ON_ERROR|ONESHELL|tab|credential|mbake" devops-skills-plugin/skills/makefile-validator/docs/*.md

从 devops-skills-plugin/skills/makefile-validator 运行：

sed -n '1,220p' docs/best-practices.md
sed -n '1,220p' docs/common-mistakes.md
sed -n '1,220p' docs/bake-tool.md
rg -n "PHONY|DELETE_ON_ERROR|ONESHELL|tab|credential|mbake" docs/*.md

如果无法使用 Shell 命令，请使用环境提供的文件打开/读取操作访问相同路径。

回退行为

仅当默认验证器流程无法完整运行时才使用这些方案。

限制	回退操作	报告要求
python3 或 pip3 不可用	执行有限检查（如果存在 make，则运行 make -f <file> -n --dry-run，并进行针对性的 grep 检查）	说明已跳过 mbake 阶段，检查覆盖范围有所减少
pip3 install mbake 失败（离线／代理／索引问题）	保留仍可运行的语法／自定义检查；推迟格式化程序／代码检查程序阶段	报告安装失败，并要求在可联网的环境中重新运行
make 不可用	继续执行非语法阶段；脚本已自动降低语法阶段的级别	明确说明已跳过语法检查
checkmake 或 unmake 不可用	继续执行；这些是可选阶段	说明未执行可选的代码检查／可移植性检查
目标文件为只读	仅提供补丁建议	标明回复仅供参考
命令执行不可用	根据文件内容和文档进行静态审查	标明结果为未经执行的分析

最简回退命令：

# Syntax only (when make exists)
make -f <makefile-path> -n --dry-run

# Focused quick checks
grep -n "^\\.DELETE_ON_ERROR:" <makefile-path>
grep -n "^\\.PHONY:" <makefile-path>
grep -nE "^(  |    |        )[a-zA-Z@\\$\\(]" <makefile-path>

示例结果与退出代码的对应关系

清洁结果（exit 0）

Errors:   0
Warnings: 0
Info:     2
✓ Validation PASSED

仅有警告的结果（exit 1）

Errors:   0
Warnings: 3
Info:     1
⚠ Validation PASSED with warnings

错误结果（exit 2）

Errors:   2
Warnings: 1
Info:     0
⚠ Validation FAILED - errors must be fixed

故障排查快速入门

1. 检查必需工具：

command -v python3 pip3 make

2. 单独排查 GNU make 语法错误：

make -f <makefile-path> -n --dry-run

3. 检查可能存在的制表符缩进违规：

grep -nE "^(  |    |        )[a-zA-Z@\\$\\(]" <makefile-path>

4. 使用纯文本输出重新运行验证器并保存日志：

NO_COLOR=1 bash scripts/validate_makefile.sh <makefile-path> > /tmp/makefile-validator.log 2>&1
echo "exit=$? log=/tmp/makefile-validator.log"

5. 如果 mbake 安装持续失败，请在可联网的 shell 环境或使用内部 PyPI 镜像进行验证，然后重新运行完整验证器。

Skill 路径

makefile-validator/
├── SKILL.md
├── scripts/
│   └── validate_makefile.sh
├── docs/
│   ├── best-practices.md
│   ├── common-mistakes.md
│   └── bake-tool.md
└── examples/
    ├── good-makefile.mk
    └── bad-makefile.mk

完成标准

满足以下所有条件后，此 skill 更新即告完成：

1. 触发说明明确且易于识别。
2. 执行流程确定无歧义（预检 -> 运行 -> 解读 -> 文档 -> 重新运行）。
3. “如何打开文档”的说明包含准确的命令和路径。
4. 示例结果明确对应退出代码（0、1、2）。
5. 已记录针对缺失工具和受限环境的回退行为。
6. 故障排查快速入门简洁且可执行。
7. Frontmatter 中的 name 和 description 保持不变。