glossarygen

glossarygen

プロジェクトでは、名前の増加に説明が追いつかないことがあります。同じ概念が、データベース層ではuser_id、API 型ではUserID、ドキュメントでは「user id」として現れ、それらが1つの用語なのか3つの用語なのか、誰にも判断できません。glossarygen は、すでに手元にある事実からその疑問を解決します。用語の出現箇所を指定してください。つまり、見つけたとおりの名前、それを見つけた場所、そしてドキュメントに定義がある場合はその定義です。glossarygen は、統合された単一の用語集を返します。用語ごとに1つのエントリがあり、その用語が見つかったすべてのソースと、ドキュメントに記載されていればその定義が含まれます。独自の定義を作成したり、情報を取得したりすることはありません。指定された内容を正規化して統合するだけです。

正規化は、順序が固定された手順で行われます。まず、アンダースコアまたはハイフンの連続をそれぞれ1つのスペースに置き換えます。次に、キャメルケースの区切りを追加します。小文字または数字の後に続く大文字の前、および頭字語の連続の末尾で大文字の単語が始まる位置の大文字の前にスペースを追加します。そのため、HTTPServerはHTTP Serverになります。結果を空白で分割して各単語を小文字にし、単語を単一のスペースで結合したものが用語のキーになります。これにより、parseHTTPResponseはparse http responseをキーとし、user_idとUserIDは同じキーuser idとなって、1つのエントリに統合されます。

各エントリには、表示形式の用語（キーの先頭文字を大文字にしたもの。たとえば、parse http responseはParse http responseと表示されます）、すべての出現箇所に含まれる重複のないソース（昇順でソート）、および統合された出現箇所の数が含まれます。エントリの定義には、統合された出現箇所のうち、指定された順序で最初に定義が指定されたものが使われます。空文字列の定義も指定されたものとして扱われ、入力されたとおりに保持されます。どの出現箇所にも定義が指定されていない場合、定義はnullになります。エントリはキー順に返され、件数には、指定された出現箇所の数、統合された重複のない用語の数、および定義あり・なしの用語数が含まれます。

___のように区切り文字のみで構成された名前は、正規化後に単語がなくなるため、パスを示すバリデーションエラーになります。また、用語リストがない、または空である場合、出現項目がオブジェクトではない場合、nameまたはsourceがない、空、または文字列ではない場合、あるいはdefinitionが指定されていて文字列ではない場合も、バリデーションエラーになります。入力が無効な場合、用語集の一部だけが返されることはありません。未知の追加フィールドは無視されます。

CLI

npx @reneturcios/glossarygen build --input args.json
npx @reneturcios/glossarygen --version

args.jsonには、引数オブジェクト全体が含まれます。

{
  "terms": [
    {
      "name": "user_id",
      "source": "src/user.ts"
    },
    {
      "name": "UserID",
      "source": "docs/api.md",
      "definition": "Stable identifier for a user account."
    },
    {
      "name": "parseHTTPResponse",
      "source": "src/http.ts"
    }
  ]
}

用語集はJSONとして出力されます。

{
  "entries": [
    {
      "term": "Parse http response",
      "sources": ["src/http.ts"],
      "occurrences": 1,
      "definition": null
    },
    {
      "term": "User id",
      "sources": ["docs/api.md", "src/user.ts"],
      "occurrences": 2,
      "definition": "Stable identifier for a user account."
    }
  ],
  "counts": {
    "supplied": 3,
    "distinct_terms": 2,
    "with_definition": 1,
    "without_definition": 1
  }
}

終了コード：成功時は0、実行時エラー（読み取り不能または無効な入力ファイル、無効な入力を含む）では1、使用方法のエラーでは2です。

MCP サーバー

npx -y @reneturcios/glossarygen mcp

MCP クライアントの設定：

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

ツール

• build_glossary — 呼び出し元が指定した用語から、プロジェクトの用語集を作成します。識別子とドキュメント内の名称を正規化して統合し、各エントリにはソースと、指定されていれば定義が含まれます。

  • terms（配列、必須、1項目以上） — 呼び出し元が指定した順序で統合する用語の出現箇所です。各項目：
    • name（文字列、必須、空でない） — 見つかったとおりの用語。識別子またはドキュメント内の語句
    • source（文字列、必須、空でない） — 用語が見つかった場所（パスまたはリンク）。エントリのソースとしてそのまま出力されます
    • definition（文字列、任意） — ドキュメント内で見つかった定義

  {entries, counts}を返します。entriesには、正規化後の用語ごとに{term, sources, occurrences, definition}が1つ含まれ、用語キー順にソートされます。countsは{supplied, distinct_terms, with_definition, without_definition}です。

Docker

docker run -i ghcr.io/cloudcorprecords/glossarygen
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/glossarygen build --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