ls には見えるのに、エージェントが開けない — 日本語ファイル名が macOS と Linux で別物になるとき

#!/usr/bin/env python3
"""filename_gate.py — リポジトリ内のパスを3軸で検査する。
 
  python3 filename_gate.py <repo_root>
  終了コード 0=クリーン / 1=要対処
"""
import subprocess
import sys
import unicodedata
from collections import defaultdict
from pathlib import Path
 
# 軸3で弾く文字（正規化では消えないもの）
SUSPICIOUS_CHARS = {
    "　": "全角スペース",
    " ": "ノーブレークスペース",
    "​": "ゼロ幅スペース",
    "‎": "左横書き記号",
    "": "BOM",
}
 
 
def tracked_paths(repo: Path):
    """Git が追跡しているパスを、エスケープさせずに生バイトで受け取る。"""
    out = subprocess.run(
        ["git", "-C", str(repo), "ls-files", "-z"],
        capture_output=True, check=True,
    ).stdout
    for chunk in out.split(b"\x00"):
        if chunk:
            yield chunk.decode("utf-8", errors="surrogateescape")
 
 
def check(repo: Path):
    findings = []
    casefold_groups = defaultdict(list)
 
    for path in tracked_paths(repo):
        name = Path(path).name
 
        # --- 軸1: 正規化 ---
        nfc = unicodedata.normalize("NFC", path)
        if path != nfc:
            findings.append(("NFD", path, f"NFC 形にすると {nfc!r}"))
 
        # --- 軸2: 大文字小文字の衝突候補 ---
        casefold_groups[nfc.casefold()].append(path)
 
        # --- 軸3: 不可視・紛らわしい文字 ---
        for ch, label in SUSPICIOUS_CHARS.items():
            if ch in name:
                findings.append(("CHAR", path, f"{label} (U+{ord(ch):04X}) を含む"))
        if name != name.strip():
            findings.append(("CHAR", path, "先頭または末尾に空白"))
        if any(unicodedata.east_asian_width(c) == "F" for c in name):
            findings.append(("CHAR", path, "全角の英数字または記号を含む"))
 
    for _, group in casefold_groups.items():
        if len(group) > 1:
            findings.append(("CASE", " / ".join(group), "大小のみが異なる複数のパス"))
 
    return findings
 
 
def main():
    repo = Path(sys.argv[1] if len(sys.argv) > 1 else ".")
    findings = check(repo)
    if not findings:
        print("✅ filename_gate: クリーン")
        return 0
    by_kind = defaultdict(list)
    for kind, path, note in findings:
        by_kind[kind].append((path, note))
    for kind in ("NFD", "CASE", "CHAR"):
        for path, note in by_kind.get(kind, []):
            print(f"[{kind}] {path}\n        └ {note}")
    print(f"\n❌ filename_gate: {len(findings)} 件")
    return 1
 
 
if __name__ == "__main__":
    sys.exit(main())

[NFD] content/reference/壁紙_配色ガイド.md
        └ NFC 形にすると 'content/reference/壁紙_配色ガイド.md'
[NFD] content/reference/申請_チェックリスト.md
        └ NFC 形にすると 'content/reference/申請_チェックリスト.md'
[CASE] src/lib/Utils.ts / src/lib/utils.ts
        └ 大小のみが異なる複数のパス
[CHAR] docs/リリース　メモ.md
        └ 全角スペース (U+3000) を含む
 
❌ filename_gate: 14 件

## ファイル名の規約
 
- リポジトリに追加するパスは、ディレクトリ名・ファイル名ともに
  ASCII の小文字・数字・ハイフンのみで構成する。
- 日本語はファイル名に置かない。フロントマターの title など、
  ファイルの「中身」に置く。
- 既存の日本語ファイル名を参照するときは、名前を文脈から
  組み立てず、必ず `git ls-files` の出力から取得する。

#!/usr/bin/env bash
# ci-filename-gate.sh — 追加・変更されたパスだけを検査する
set -euo pipefail
 
BASE="${1:-origin/main}"
 
# 差分のあるパスだけを -z で取得（全件走査は大きなリポジトリで無駄）
CHANGED=$(git diff --name-only -z "${BASE}"...HEAD | tr '\0' '\n' | grep -c . || true)
if [ "${CHANGED}" -eq 0 ]; then
  echo "変更されたパスがありません"
  exit 0
fi
 
python3 scripts/filename_gate.py . || {
  cat <<'MSG'
 
────────────────────────────────────────────
ファイル名ゲートで停止しました。
 
  NFD  → パスを ASCII 名へ改名してください
  CASE → 大小のみ異なる重複を解消してください
  CHAR → 全角・不可視文字を取り除いてください
 
改名は `git mv` を2段階で行ってください:
  git mv 旧名 一時名 && git mv 一時名 新名
（大小のみの変更は1段階だと macOS で無視されます）
────────────────────────────────────────────
MSG
  exit 1
}

import unicodedata
from pathlib import Path
 
 
def resolve_tolerant(root: Path, wanted: str) -> Path | None:
    """要求されたパスを、正規化と大小を吸収して実体へ解決する。
 
    厳密一致を最優先し、緩い一致は候補が1つのときだけ採用する。
    複数候補があるなら、それは幽霊二重ファイルの徴候なので解決しない。
    """
    exact = root / wanted
    if exact.exists():
        return exact
 
    def key(s: str) -> str:
        return unicodedata.normalize("NFC", s).casefold()
 
    target = key(wanted)
    matches = [p for p in root.rglob("*") if key(str(p.relative_to(root))) == target]
 
    if len(matches) == 1:
        return matches[0]
    if len(matches) > 1:
        raise FileExistsError(
            f"同名に解決される実体が {len(matches)} 件あります: {matches}"
        )
    return None