rogerchappel/runbooklint

# RunbookLint RunbookLint 是一款针对操作 runbook 的本地优先 Markdown linter。它通过标记缺失的安全章节、危险命令、未定义的占位符以及含糊不清的操作语言，将发布、故障、支持和 agent 交接文档转化为可检查的流程。 它从不执行命令，也从不调用托管 API。 ## 快速开始 ``` npm install npm run build node dist/cli.js check fixtures/clean-release.md ``` 发布后，全局安装 CLI 并在任何仓库中运行相同的检查： ``` npm install -g runbooklint runbooklint check docs --fail-on warning ``` 初始化项目策略： ``` node dist/cli.js init --preset oss-release ``` 检查目录，并在出现警告或错误时让 CI 失败： ``` node dist/cli.js check docs --format json --fail-on warning ``` ## CLI ``` runbooklint check [paths...] [--format markdown|json] [--fail-on info|warning|error] [--output file] [--policy file] runbooklint init [--preset oss-release|incident|agent-handoff] [--print] [--force] ``` ### 报告 Markdown 是默认的报告格式。JSON 格式稳定且具有确定性，适合自动化处理。 ``` node dist/cli.js check fixtures --format markdown --output reports/runbooklint.md node dist/cli.js check fixtures --format json --output reports/runbooklint.json ``` ## 检查内容 - 必需的章节，例如目的、范围、前置条件、流程、验证和回滚。 - 所有者或交接联系人。 - 环境范围。 - 包含危险模式的 Shell 代码块，例如 `rm -rf`、`sudo`、`curl | bash`、强制推送以及影响生产环境的命令。 - TODO/TBD/FIXME 占位符。 - 未定义的 `{{VARIABLE}}` 和 `${VARIABLE}` 占位符。 - 由策略配置的禁用模糊短语。 ## 策略配置 除非提供了 `--policy`，否则 RunbookLint 会从当前目录加载 `.runbooklint.json`。完整的策略参考请参阅 [docs/POLICY.md](docs/POLICY.md)。 ``` { "requiredHeadings": ["purpose", "scope", "prerequisites", "procedure", "validation", "rollback"], "ownerHeadings": ["owner", "contacts"], "environmentHeadings": ["scope", "environment"], "requiredVariableDefinitions": ["OWNER", "TARGET_ENV"], "allowMissingOwner": false } ``` 使用以下命令生成预设策略： ``` node dist/cli.js init --preset oss-release --print node dist/cli.js init --preset incident --print node dist/cli.js init --preset agent-handoff --print ``` ## CI 用法 ``` - run: npm ci - run: npm test - run: npm run check - run: npm run build - run: node dist/cli.js check docs --fail-on warning ``` ## 安全模型 RunbookLint 是保守的。它解析 Markdown 并报告可能的问题；它不执行 runbook 命令、修改基础设施、评估 shell 扩展或联系外部服务。请将检查结果视为审查提示，而不是对人类操作判断的替代。 ## 局限性 - Markdown 解析是刻意保持轻量级的，并针对 runbook 进行了优化，而不是为了处理每一个 CommonMark 边缘情况。 - 风险规则基于模式匹配，可能会产生误报或漏报。 - `.gitignore` 支持涵盖了常见的确定性路径忽略，但不支持所有高级 gitignore 功能。 - 行内抑制和 SARIF 输出已列入计划，但尚未实现。 ## 开发 ``` npm install npm test npm run check npm run build npm run smoke npm run package:smoke npm run release:check bash scripts/validate.sh ``` `release:check` 会执行已编译的 CLI、fixture 测试、冒烟测试脚本和预演包内容，以便在打标签之前对发布候选版本进行审查。 ## 安全 请参阅 [SECURITY.md](SECURITY.md)。请不要在 bug 报告中包含机密信息或私有的故障数据。 ## 许可证 MIT

标签：GNU通用公共许可证, Markdown, MITM代理, Node.js, 代码规范, 文档检查, 文档结构分析, 暗色界面, 自动化攻击, 运维, 静态检查