errorcatalog

errorcatalog

代码库中抛出的每条错误消息都会被编目；如果你提供文档，还会注明每条消息是否有文档记录。

errorcatalog 会逐行扫描源文本，查找形式为 throw new <Name>Error(...) 的 throw 语句，其中类型名称以 Error 结尾（Error、TypeError、RangeError 或自定义类型，例如 FooError）。对于每个 throw 位置，它都会记录文件、从 1 开始的行号、错误类型，以及：

• 字面量 — 第一个参数是双引号、单引号或反引号括起的字符串，且其中不含 ${。消息会按原样记录，包括转义序列——不会进行反转义。
• 动态 — 第一个参数是其他任何内容：包含 ${ 的模板、标识符、调用、拼接，或未在同一行闭合的字面量。消息为 null。
• 无消息 — throw new <Name>Error() 完全没有参数。消息为 null，且条目带有注记 no message argument。

不是 new <Name>Error(...) 形式的 throw 不会被编目，例如裸字符串、非 Error 构造函数或变量。 重复的 throw 会保留为单独条目：目录按 throw 位置记录。

提供文档文本时，每条字面量消息都会与文档进行逐字检查：如果消息是某份所提供文档的子字符串，则 documented 为 true；如果不是，则为 false。对于动态和无消息条目，documented 为 null；如果没有提供文档，则所有条目的 documented 都为 null，此时结果会报告 docs_provided: false，且 documented / undocumented 计数均为 0。

已知限制（有意为之）：只检查 throw 语句的第一行，因此参数列表跨行的字面量会被归类为动态。分析仅在本地进行纯文本处理：核心功能不会访问网络或文件系统。

CLI

npx @reneturcios/errorcatalog catalog --sources sources.json --docs docs.json
npx @reneturcios/errorcatalog --version

sources.json 和 docs.json 各自包含一个 JSON 数组，数组元素为 {"path": "src/app.ts", "content": "..."} 对象。--docs 标志为可选。目录会以 JSON 格式输出。

退出代码：成功时为 0；发生运行时错误时为 1（包括 JSON 文件无法读取或无效，或条目格式错误——错误会指出出问题的路径，例如 sources[0].content is required）；用法错误时为 2。

MCP 服务

npx -y @reneturcios/errorcatalog mcp

MCP 客户端配置：

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

工具

• catalog_errors — 为给定源文件中抛出的每条错误编目，并注明每条字面量消息是否有文档记录。

  • sources（数组，必需，至少 1 项）— 作为 {path, content} 对象的源文件
  • docs（数组，可选）— 作为 {path, content} 对象的文档文本；会将字面量消息与其进行逐字检查

  返回 {errors, counts, docs_provided}，其中每条错误为 {path, line, error_type, message, dynamic, documented}（无消息条目还会包含 note），而 counts 为 {total, literal, dynamic, no_message, documented, undocumented}。

Docker

docker run -i ghcr.io/cloudcorprecords/errorcatalog
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/errorcatalog catalog --sources /w/sources.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 — 版权所有 (c) 2026 Rene Turcios