makefile-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Makefile Validator

Makefile 验证工具

Overview

概述

Use this skill to validate Makefiles with a local-first, deterministic flow.

Default validator entrypoint:

bash

bash scripts/validate_makefile.sh <makefile-path>

Validation layers:

Dependency preflight (
```
python3
```
,
```
pip3
```
,
```
make
```
)
GNU make syntax check (
```
make -n --dry-run
```
) when
```
make
```
is available
```
mbake validate
```
```
mbake format --check
```
Custom security, best-practice, and optimization checks
Optional
```
checkmake
```
and
```
unmake
```
checks when installed

使用该工具通过本地优先的确定性流程验证Makefile。

默认验证器入口：

bash

bash scripts/validate_makefile.sh <makefile-path>

验证层级：

依赖项预检（
```
python3
```
、
```
pip3
```
、
```
make
```
）
当
```
make
```
可用时执行GNU make语法检查（
```
make -n --dry-run
```
）
```
mbake validate
```
```
mbake format --check
```
自定义安全、最佳实践与优化检查
当
```
checkmake
```
和
```
unmake
```
已安装时，执行可选检查

Trigger Guidance

触发指引

Use this skill when the request includes Makefile quality, linting, validation, hardening, or troubleshooting.

当请求涉及Makefile质量检查、代码规范校验、验证、加固或故障排查时，使用该工具。

Trigger Phrases

触发短语

"Validate this Makefile"
"Lint my
```
.mk
```
file"
"Find issues in this build Makefile"
"Check Makefile security problems"
"Review this Makefile before CI"

"验证这个Makefile"
"检查我的.mk文件"
"查找这个构建Makefile中的问题"
"检查Makefile的安全问题"
"在CI前审核这个Makefile"

Non-Trigger Examples

非触发场景示例

Creating a brand new Makefile from scratch (use
```
makefile-generator
```
)
Running build targets as part of delivery
General shell scripting work unrelated to Makefiles

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

Deterministic Execution Model

确定性执行模型

Run from this skill directory for shortest commands:

bash

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

切换到该工具所在目录以使用最短命令：

bash

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

Step 1: Preflight

步骤1：预检

Confirm target file exists and is readable.
Confirm whether file edits are allowed (
```
writable
```
) or only suggestions can be returned (
```
read-only
```
).
Prefer the default validator path first; use fallbacks only when blocked by environment constraints.

确认目标文件存在且可读。
确认是否允许编辑文件（
```
可写入
```
）或仅能返回建议（
```
只读
```
）。
优先使用默认验证器路径；仅当受环境限制无法使用时，才使用备选方案。

Step 2: Baseline Validation (Default Path)

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

bash

undefined

bash

undefined

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>


Always record:

- command executed
- exit code
- summary counts (`Errors`, `Warnings`, `Info`)
- issue locations reported by tools

bash devops-skills-plugin/skills/makefile-validator/scripts/validate_makefile.sh <makefile-path>


始终记录以下内容：

- 执行的命令
- 退出码
- 统计摘要（`错误数`、`警告数`、`信息数`）
- 工具报告的问题位置

Step 3: Interpret Output and Exit Code

步骤3：解读输出与退出码

Exit code	Meaning	Expected summary line	Action
`0`	no blocking findings	`Validation PASSED`	optional improvements only
`1`	warning-only result	`Validation PASSED with warnings`	fix recommended; merge policy dependent
`2`	error result	`Validation FAILED - errors must be fixed`	fix required, then rerun

退出码	含义	预期摘要行	操作
`0`	无阻塞性问题	`验证通过`	仅需可选优化
`1`	仅存在警告	`验证通过，但存在警告`	建议修复；是否合并取决于策略
`2`	存在错误	`验证失败 - 必须修复错误`	修复后重新运行

Step 4: Progressive Reference Loading

步骤4：渐进式参考文档加载

Open only the docs required by the current findings.

Finding type	Reference doc
`.PHONY` , `.DELETE_ON_ERROR` , `.ONESHELL` , variable usage, performance structure	`docs/best-practices.md`
tabs vs spaces, dependency mistakes, credential patterns, anti-patterns	`docs/common-mistakes.md`
`mbake` behavior, formatter flags, known `mbake` caveats	`docs/bake-tool.md`

仅打开当前问题所需的文档。

问题类型	参考文档
`.PHONY` 、 `.DELETE_ON_ERROR` 、 `.ONESHELL` 、变量使用、性能结构	`docs/best-practices.md`
制表符与空格、依赖错误、凭证模式、反模式	`docs/common-mistakes.md`
`mbake` 行为、格式化器标志、已知 `mbake` 限制	`docs/bake-tool.md`

Step 5: Fix + Rerun Loop

步骤5：修复+重新运行循环

After applying fixes, rerun:

bash

bash scripts/validate_makefile.sh <makefile-path>

Loop rules:

Stop only when no new errors are introduced.
If warnings remain intentionally, document why they are accepted.
Always report the latest rerun exit code.

应用修复后，重新运行：

bash

bash scripts/validate_makefile.sh <makefile-path>

循环规则：

仅当未引入新错误时停止。
如果仍有意保留警告，需记录接受警告的原因。
始终报告最新重新运行的退出码。

How to Open Docs

如何打开文档

Use explicit file-open commands so paths are unambiguous.

From repository root:

bash

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

From

devops-skills-plugin/skills/makefile-validator

bash

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

If shell commands are unavailable, use the environment's file-open/read actions on the same paths.

使用明确的文件打开命令，确保路径无歧义。

从仓库根目录执行：

bash

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

目录执行：

bash

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命令，使用环境中的文件打开/读取操作访问相同路径。

Fallback Behavior

备选行为

Use these only when the default validator path cannot run fully.

Constraint	Fallback action	Reporting requirement
`python3` or `pip3` unavailable	Run limited checks ( `make -f <file> -n --dry-run` if `make` exists, plus focused `grep` checks)	State that `mbake` stages were skipped and coverage is reduced
`pip3 install mbake` fails (offline/proxy/index issue)	Keep syntax/custom checks that still work; defer formatter/linter stages	Report install failure and request rerun in a network-enabled environment
`make` unavailable	Continue with non-syntax stages; script already downgrades syntax stage	Explicitly note syntax coverage was skipped
`checkmake` or `unmake` unavailable	Continue; these are optional stages	Note optional lint/portability coverage not executed
target file is read-only	Provide patch suggestions only	Mark response as advisory only
command execution unavailable	Provide static review from file contents and docs	Mark result as non-executed analysis

Minimal fallback commands:

bash

undefined

仅当默认验证器路径无法完整运行时，使用以下备选方案。

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

最小备选命令：

bash

undefined

Syntax only (when make exists)

仅语法检查（当make可用时）

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>

undefined

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

undefined

Example Outcomes Mapped to Exit Codes

与退出码对应的示例结果

Clean Result (

exit 0

)

无问题结果（

exit 0

）

text

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

text

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

Warning-Only Result (

exit 1

)

仅含警告结果（

exit 1

）

text

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

text

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

Error Result (

exit 2

)

含错误结果（

exit 2

）

text

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

text

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

Troubleshooting Quick Start

故障排查快速入门

Verify required tools:

bash

command -v python3 pip3 make

Isolate GNU make syntax failures:

bash

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

Check likely tab-indentation violations:

bash

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

Rerun validator with plain output and capture log:

bash

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

If mbake install keeps failing, validate in a network-enabled shell or with an internal PyPI mirror, then rerun the full validator.

验证所需工具是否存在：

bash

command -v python3 pip3 make

隔离GNU make语法错误：

bash

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

检查可能的制表符缩进违规：

bash

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

以纯文本输出重新运行验证器并捕获日志：

bash

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

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

Skill Paths

工具目录结构

text

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

text

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

Done Criteria

完成标准

This skill update is complete when all are true:

Trigger guidance is explicit and easy to identify.
Execution flow is deterministic (preflight -> run -> interpret -> docs -> rerun).
"How to open docs" instructions include exact commands and paths.
Example outcomes are explicitly tied to exit codes (
```
0
```
,
```
1
```
,
```
2
```
).
Fallback behavior is documented for missing tools and constrained environments.
Troubleshooting quick-start is concise and runnable.
Frontmatter
```
name
```
and
```
description
```
remain unchanged.

当满足以下所有条件时，该工具更新完成：

触发指引明确且易于识别。
执行流程具有确定性（预检 -> 运行 -> 解读 -> 文档参考 -> 重新运行）。
“如何打开文档”说明包含准确的命令和路径。
示例结果与退出码（
```
0
```
、
```
1
```
、
```
2
```
）明确关联。
已记录针对缺失工具和受限环境的备选行为。
故障排查快速入门简洁且可直接运行。
前端元数据
```
name
```
和
```
description
```
保持不变。",

makefile-validator

Original

Translation

Makefile Validator

Makefile 验证工具

Overview

概述

Trigger Guidance

触发指引

Trigger Phrases

触发短语

Non-Trigger Examples

非触发场景示例

Deterministic Execution Model

确定性执行模型

Step 1: Preflight

步骤1：预检

Step 2: Baseline Validation (Default Path)

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

From skill directory

从工具目录执行

From repository root

从仓库根目录执行

Step 3: Interpret Output and Exit Code

步骤3：解读输出与退出码

Step 4: Progressive Reference Loading

步骤4：渐进式参考文档加载

Step 5: Fix + Rerun Loop

步骤5：修复+重新运行循环

How to Open Docs

如何打开文档

Fallback Behavior

备选行为

Syntax only (when make exists)

仅语法检查（当make可用时）

Focused quick checks

针对性快速检查

Example Outcomes Mapped to Exit Codes

与退出码对应的示例结果

Clean Result (exit 0)

无问题结果（exit 0）

Warning-Only Result (exit 1)

仅含警告结果（exit 1）

Error Result (exit 2)

含错误结果（exit 2）

Troubleshooting Quick Start

故障排查快速入门

Skill Paths

工具目录结构

Done Criteria

完成标准

Clean Result (
`exit 0`
)

无问题结果（
`exit 0`
）

Warning-Only Result (
`exit 1`
)

仅含警告结果（
`exit 1`
）

Error Result (
`exit 2`
)

含错误结果（
`exit 2`
）