topiclint

topiclint

topiclint は、MQTT トピック文字列がブローカーに届く前、または名前空間設計のレビューにかけられる前に検査します。個々のトピックを Sparkplug B のトピック文法（Sparkplug 3.0）に照らしてリントし、Unified Namespace（UNS）のトピックパス一式を対象に、命名の一貫性をチェックします。大文字・小文字の混在、階層の深さの不揃い、よく似た兄弟ノードなど、名前空間を閲覧、クエリ、引き継ぎしにくくするズレを検出します。1つのバイナリで、コマンドラインインターフェースと stdio MCP サーバーを提供します。

すべてローカルで実行され、オフラインで使用できます。ブローカーへの接続、ネットワークアクセス、API キー、アカウントは不要です。リントで検証するのは文法のみであり、ペイロードのデコードやデバイスの存在確認は行いません。命名チェックで判定するのは一貫性のみであり、プラントの構成を把握したり、名前空間を設計したりすることはありません。

インストール

npx @reneturcios/topiclint lint spBv1.0/Plant1/NBIRTH/Edge1

または、コンテナーイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/topiclint

コンテナーはデフォルトで MCP サーバーを起動します（下記参照）。CLI として使用するには、CLI 引数を渡してください。

CLI

topiclint lint spBv1.0/Plant1/NBIRTH/Edge1 spBv1.0/Plant1/DDATA/Edge1/Dev1
topiclint check enterprise/site1/line1 enterprise/site1/line2

topiclint --version

各トピックまたはパスは1つの引数として指定します。1つの引数に、改行区切りのリストを指定することもできます。どちらのコマンドも JSON レポートを出力します。検出結果が多数含まれていても、実行は成功です。検出結果は出力であり、エラーではありません。終了コード：成功時は 0、実行時エラーは 1、使用方法のエラーは 2 です。

Sparkplug リントのチェック内容

各トピックについて、spBv1.0 名前空間レベル、メッセージタイプ（NBIRTH、NDEATH、DBIRTH、DDEATH、NDATA、DDATA、NCMD、DCMD、および STATE のいずれか）、レベル数（ノードメッセージと STATE は正確に4レベル、デバイスメッセージは正確に5レベル）、レガシーな Sparkplug 2.2 の STATE 形式（名前空間を含まない STATE/<host_id>。独立した失敗として報告）、パブリッシュ側の MQTT ワイルドカード（+ / #）、空のレベル、グループ、ノード、デバイスの各レベルにおける識別子の文字をチェックします。空白文字は失敗となり、[A-Za-z0-9_-] 以外の文字は警告となります。どちらも、トピックを分割、引用、またはマッピングする下流のコンシューマーを妨げるためです。

各結果には、解析されたトピックの各要素（名前空間、グループ ID、メッセージタイプ、エッジノード ID、デバイス ID）と、fail / warn / pass / info のレベルが付いた順序付きの検出結果が含まれます。

UNS チェックの内容

パス一式を対象に、パスの重複、空のレベル、セグメント内の空白文字、不要な MQTT ワイルドカードを検出し、いずれも失敗とします。同じ親の下にある、名前の大文字・小文字だけが異なる兄弟ノードは、大文字・小文字の衝突として失敗になります。1つのノードに見えても、実際には2つあるためです。階層の深さの不一致と、大文字・小文字のスタイル（lower、upper、snake_case、kebab-case、PascalCase、camelCase）の混在は警告となります。レポートの冒頭には1行の要約が表示され、その後に問題ごとの検出結果が続きます。

MCP サーバー

1つのバイナリで両方の機能を提供します。mcp サブコマンドで stdio MCP サーバーを起動します。

npx -y @reneturcios/topiclint mcp

MCP クライアントの設定：

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

ツール

どちらのツールも、単一の topics 引数を受け取ります。引数は、単一の文字列、改行区切りの文字列、またはトピック文字列の配列です。

ツール	入力	返される内容
lint_sparkplug_topic	topics（文字列または文字列の配列）	トピックごとに解析された各要素と順序付きの検出結果。成功数・失敗数と要約も含まれます。
check_uns_namespace	topics（文字列または文字列の配列）	パス一式の要約行と、問題ごとの検出結果。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。