errorcatalog

errorcatalog

コードベース内でスローされるすべてのエラーメッセージをカタログ化します。ドキュメントを指定すると、各メッセージがドキュメントに記載されているかどうかも示します。

errorcatalog はソーステキストを1行ずつスキャンし、throw new <Name>Error(...) 形式の throw 文を検索します。型名は Error（Error、TypeError、RangeError、または FooError のようなカスタム型）のように Error で終わる必要があります。各 throw 箇所について、ファイル、1始まりの行番号、エラー型、および次の情報を記録します。

• literal — 第1引数が、${ を含まない二重引用符、単一引用符、またはバッククォートで囲まれた文字列です。メッセージは、エスケープシーケンスも含め、記述どおりに記録されます。エスケープ解除は行われません。
• dynamic — 第1引数がそれ以外のものです。${ を含むテンプレート、識別子、関数呼び出し、連結、または同じ行で閉じていないリテラルが該当します。メッセージは null です。
• no message — throw new <Name>Error() のように引数がありません。メッセージは null で、エントリーには no message argument という注記が付きます。

new <Name>Error(...) 形式ではない throw（裸の文字列、Error 以外のコンストラクター、変数など）はカタログ化されません。 重複する throw も別々のエントリーとして残ります。カタログは throw 箇所ごとに作成されます。

ドキュメントのテキストが指定されている場合、各リテラルメッセージがドキュメントにそのまま含まれているかどうかを確認します。指定されたドキュメントのいずれかにメッセージが部分文字列として含まれていれば documented は true、含まれていなければ false です。dynamic と no-message のエントリーでは null になります。ドキュメントが指定されていない場合はすべてのエントリーで null となり、結果では docs_provided: false と報告され、documented と undocumented の件数はいずれも 0 になります。

既知の制限事項として、仕様上、throw 文の最初の行だけを調べます。そのため、引数リストが複数行にまたがるリテラルは dynamic としてカタログ化されます。解析はローカルのテキストのみを対象とし、コア処理ではネットワークもファイルシステムも使用しません。

CLI

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

sources.json と docs.json はそれぞれ、{"path": "src/app.ts", "content": "..."} オブジェクトの JSON 配列です。--docs フラグは省略できます。カタログは JSON として出力されます。

終了コード：成功時は 0、実行時エラー時は 1（読み取れない JSON ファイル、無効な JSON ファイル、不正なエントリーを含みます。不正な場合は、該当するパスがエラーに示されます。例：sources[0].content is required）、使用方法のエラー時は 2 です。

MCP server

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}（no-message エントリーには 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 — Copyright (c) 2026 Rene Turcios