recurspec

RecurSpec 是一个处于早期阶段、采用 MIT 许可的 Node.js 软件包，用于测试命令行工具的恢复路径。传统的测试可能仅断言是否打印了错误消息，而 RecurSpec 则验证消息中建议的命令是否真的能修复问题，从而确保用户能够真正摆脱困境。 工作原理 测试用例在 recurspec.yml 文件中以声明式描述。每个用例声明要运行的命令、预期的失败结果（例如非零退出码和 stderr 子字符串）、恢复指令的来源以及验证步骤。验证步骤可以重新运行原始命令并要求退出码为零，这样工具就能确认恢复循环已闭合，而不仅仅是确认建议的存在。 快速入门 该项目需要 Node.js 22 或更高版本以及 pnpm。它作为开发依赖项安装，然后通过三个核心命令使用：编写包含可运行 Node.js 示例的启动配置的 init 步骤、validate 步骤和 test 步骤。随附的演示示例特意混合了通过和损坏的恢复路径。 命令行界面 CLI 提供了 test、validate、init、explain 和 discover 命令。test 命令支持选择用例或标签、选择报告格式（human、json、junit 或 markdown）、详细输出、快速失败行为、种子值以及干跑（dry run）等选项。退出码定义为：全部通过为 0，合约失败为 1，配置或使用错误为 2。JSON、JUnit 和 Markdown 报告旨在用于 CI 流水线和拉取请求（pull-request）评论。此外，还可以通过 runRecurSpec 使用编程 API。 检测目标 该工具针对错误消息与其指令之间不匹配的情况：不再存在的建议命令、不完整的恢复步骤、成功运行但未解决原始问题的命令、导致进一步错误的建议、指令循环，以及模糊或不安全的指令。 重试与目标恢复 支持两种恢复模式。在重试式恢复（retry-style recovery）中，移除阻碍因素可使原始命令在第二次尝试时成功。在目标恢复（goal recovery）中，建议的命令完全替代了失败的操作，因此即使重新运行原始命令仍会失败，用户的目标也已达成。README 指出，对 Cargo 用例的研究揭示了这一区别，并促成了基于目标的验证。 现实世界兼容性 兼容性套件包含来自 Git、Cargo 和 npm 的用例，涵盖了诸如 Git 身份缺失、分支删除、发散的 pull 建议、已存在的 Cargo 项目目录以及缺失的 npm 脚本等情况。结果包括模糊的建议（多个互斥或必需的命令）、目标恢复以及被正确忽略的仅信息类消息。运行套件时会跳过缺失的工具。 安全模型 恢复命令在执行前会被解析和检查。默认情况下，Shell 链式调用、重定向、命令替换和已知的破坏性命令将被拦截，且每个用例都在隔离的临时工作区中运行。README 明确指出，本地后端不强制执行 OS 级别的网络沙箱，因此在容器后端出现之前，deny-network 设置仅作为建议。 局限性与状态 文档列出了三个局限性：本地后端没有 OS 级别的网络隔离；测试交互式 TTY 程序时需要脚本化的标准输入（完整的 PTY 支持是未来的工作）；依赖于工具打印可 grep 的建议，模糊或缺失的建议将被报告而非猜测。RecurSpec 被描述为处于早期阶段，在 1.0 版本发布前，配置和公共 API 可能会发生变化。独立的文档涵盖了配置、提取、安全、报告程序和发现功能。