guardfile

guardfile

仓库可以声称有各种贡献保障措施——为提交签名、同意许可条款、添加变更集——但只有能指出落实每项措施的文件，这些说法才有意义。guardfile 会帮你指出这些文件：你把仓库的文件交给它，它就会返回一份可核验的报告，列出实际存在的保障措施及各自的证据。

它通过固定规则检测四种保障措施：

• DCO — 文件名（不含路径）恰好为 DCO（不区分大小写），或任意内容提及 Developer Certificate of Origin。
• CLA — 文件名（不含路径）以 CLA 开头（不区分大小写，例如 CLA.md），或任意内容提及 Contributor License Agreement。
• changesets — 路径包含 .changeset/、以 /.changeset 结尾、恰好为 .changeset，或任意内容提及 @changesets/ 作用域。
• sign-off — 任意内容包含 Signed-off-by: 行。冒号是规则的一部分：仅提及 Signed-off-by 不计入。

所有内容匹配均不区分大小写。报告会列出触发每项保障措施的路径，并按顺序排序；即使同一文件通过路径和内容同时触发同一项保障措施，每条路径也最多出现一次。除四项判定结果外，报告还会给出已具备的数量、缺失项名称（固定顺序为 dco、cla、changeset、signoff），以及仅在四项全部具备时才为 true 的 complete 标记。

输入格式错误——文件列表缺失或为空、条目不是对象、路径缺失、为空或重复，或内容缺失或不是字符串——都会导致验证错误，并指出出错路径（例如 files[1].content must be a string），且不会生成部分报告。计算过程纯粹且仅在本地进行：不访问网络、不需要配置，也不会读取你传入内容之外的任何文件。

命令行工具

npx @reneturcios/guardfile extract --input args.json
npx @reneturcios/guardfile --version

args.json 包含完整的参数对象：

{
  "files": [
    { "path": "DCO", "content": "Developer Certificate of Origin\n\nVersion 1.1" },
    { "path": "docs/contributing.md", "content": "Please add a Signed-off-by: line." },
    { "path": ".changeset/bright-foxes-jump.md", "content": "---\n\"pkg\": patch\n---\n" }
  ]
}

报告以 JSON 格式输出：

{
  "guardrails": {
    "dco": { "present": true, "evidence": ["DCO"] },
    "cla": { "present": false, "evidence": [] },
    "changeset": { "present": true, "evidence": [".changeset/bright-foxes-jump.md"] },
    "signoff": { "present": true, "evidence": ["docs/contributing.md"] }
  },
  "present_count": 3,
  "missing": ["cla"],
  "complete": false
}

退出代码：成功时为 0，运行时错误时为 1（包括无法读取或无效的输入文件，或无效输入），用法错误时为 2。

MCP 服务

npx -y @reneturcios/guardfile mcp

MCP 客户端配置：

{
  "mcpServers": {
    "guardfile": {
      "command": "npx",
      "args": ["-y", "@reneturcios/guardfile", "mcp"]
    }
  }
}

工具

• extract_guardrails — 从仓库文件中提取保障措施。
  • files（数组，必填，至少一个）— 仓库文件，采用 {path, content} 对象；path 是仓库相对路径，且在集合中唯一；content 是文件内容，可以为空

返回 {guardrails, present_count, missing, complete}。

Docker

docker run -i ghcr.io/cloudcorprecords/guardfile
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/guardfile extract --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — Copyright (c) 2026 Rene Turcios