miku-unicode-guard は、Markdown やソースコードに紛れ込んだ幅ゼロ文字、不可視制御文字、双方向制御文字などの「見えにくく事故を起こしやすい Unicode」を検出する CLI ツールです。生成AI、Web、PDF、各種エディタ由来の混入を早期に発見し、レビューや CI、保守作業の安全性を高めます。必要に応じて、安全に除去できる文字だけを自動修正できます。
miku-unicode-guard v0.1 では、実務上の混入事故やレビュー阻害につながりやすく、かつ検出基準を明確に定義しやすいカテゴリを検出対象とします。具体的には、見た目では気づきにくい幅ゼロ文字、通常の文書やコードでは不要であることが多い不可視制御文字、表示順を変えてレビューを難しくしうる双方向制御文字、文字化けや変換失敗の痕跡である U+FFFD REPLACEMENT CHARACTER などを扱います。
見た目ではほぼ判別できない幅ゼロ文字です。Markdown やソースコードに紛れ込むと、レビューで見落としやすく、比較や検索、編集時の混乱につながります。
代表例:
U+200BZERO WIDTH SPACEU+200CZERO WIDTH NON-JOINERU+200DZERO WIDTH JOINERU+2060WORD JOINERU+FEFFZERO WIDTH NO-BREAK SPACE / BOM
通常の文書やコード中では不要であることが多い不可視制御文字です。表示されないまま動作や解析結果に影響することがあり、混入事故の原因になります。CR LF は除外し、タブも除外します。
文字の表示順を制御する双方向制御文字です。見た目の並びと実際の文字列順をずらせるため、レビューやコード読解を妨げることがあります。Trojan Source のような問題と関係するカテゴリです。
代表例:
U+202ALREU+202BRLEU+202DLROU+202ERLOU+202CPDFU+2066LRIU+2067RLIU+2068FSIU+2069PDI
U+FFFD REPLACEMENT CHARACTER を指します。環境によっては � のように表示されます。これは元の文字を正しく解釈できなかった時に現れる置換文字であり、文字化けや不正な変換、壊れた入出力の痕跡として検出対象にします。
- デフォルト動作は
checkとし、ファイルを変更しません。 - 自動修正は明示した場合のみ有効にします。
--fixは、安全に除去できる文字だけを対象にします。--unsafe-fixは、通常の--fixでは対象外とする文字も含めて修正を試みる強い修正モードです。意図的な Unicode 使用を壊す可能性があるため、内容を理解した上で Git 管理下などで利用することを想定します。--replace-with-spaceを指定した場合、修正対象の文字は除去ではなく半角空白 1 個に置換します。- 改行、タブ、通常スペースは自動除去しません。
- デフォルトでは
node_modules/を走査対象から除外します。 - JSON を正本の出力形式とし、標準出力は人間向けの簡潔な表示にします。
- このツールは Unicode を禁止するものではなく、見えにくく事故を起こしやすい Unicode を監査するものとして設計します。
miku-unicode-guard v0.1 では、対象を絞って小さく始めます。
- 対象ファイルは
.md.java.ts.json.txt - 再帰走査を行う
- デフォルトは
check --fix指定時は、幅ゼロ文字と文中に紛れた不要なU+FEFFのみを除去対象とする--unsafe-fix指定時は、通常の--fixより広い範囲の修正を試みられるようにする--replace-with-space指定時は、修正対象の文字を除去ではなく半角空白 1 個に置換するreplacement-charは検出対象とするが、元の文字を安全に復元できないため、自動修正は慎重に扱う- 検出対象カテゴリは、幅ゼロ文字、不可視制御文字、双方向制御文字、置換文字 (
U+FFFD) とする - JSON 出力をサポートする
- 標準出力で簡潔なサマリを表示する
--fail-on-detectをサポートする