casecrash 0.1.0__py3-none-any.whl

casecrash/__init__.py

@@ -0,0 +1,5 @@
+"""casecrash: find filenames in your git index that would collide on
+case-insensitive or Unicode-normalizing filesystems (macOS, Windows)."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

casecrash/cli.py

@@ -0,0 +1,147 @@
+"""Command-line interface for casecrash."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from . import __version__
+from .core import (
+    GitNotFound,
+    NotAGitRepo,
+    escaped_display,
+    normalization_form,
+    safe_display,
+    scan,
+)
+
+EXIT_OK = 0
+EXIT_COLLISIONS = 1
+EXIT_ERROR = 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="casecrash",
+        description=(
+            "Find filenames in your git index that would collide on "
+            "case-insensitive or Unicode-normalizing filesystems "
+            "(macOS, Windows) — before they break someone's checkout."
+        ),
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="directory inside the git repository to scan (default: .)",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="output format (default: text)",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="casecrash " + __version__,
+    )
+    return parser
+
+
+def _platform_note(kind: str) -> str:
+    if kind == "case":
+        return "collide on case-insensitive filesystems (macOS, Windows)"
+    if kind == "normalization":
+        return "collide after Unicode normalization (macOS)"
+    return "identical index entries (index corruption)"
+
+
+def _format_name(raw: bytes) -> str:
+    form = normalization_form(raw)
+    shown = escaped_display(raw)
+    if form:
+        return "'%s'  [%s]" % (shown, form)
+    return "'%s'" % shown
+
+
+def render_text(result) -> str:
+    lines = []
+    if not result.collisions:
+        lines.append(
+            "casecrash: no filename collisions in the git index "
+            "(%d files scanned%s)." % (
+                result.files_scanned,
+                ", %d submodule(s) skipped" % result.gitlinks_skipped
+                if result.gitlinks_skipped else "",
+            )
+        )
+        return "\n".join(lines) + "\n"
+
+    lines.append(
+        "casecrash: found %d filename collision(s) in %s "
+        "(%d files scanned):"
+        % (len(result.collisions), result.repo_root, result.files_scanned)
+    )
+    for collision in result.collisions:
+        lines.append("")
+        lines.append("[%s] %s:" % (collision.kind, _platform_note(collision.kind)))
+        for raw in collision.names:
+            lines.append("  %s" % _format_name(raw))
+        lines.append(
+            "  -> breaks on: %s" % ", ".join(collision.platforms)
+        )
+    if result.gitlinks_skipped:
+        lines.append("")
+        lines.append(
+            "note: %d submodule(s) skipped (not checked)"
+            % result.gitlinks_skipped
+        )
+    lines.append("")
+    lines.append(
+        "Fix: rename one of each colliding pair before a macOS/Windows "
+        "user clones this repo.  "
+        "'git mv' the odd one out and commit."
+    )
+    return "\n".join(lines) + "\n"
+
+
+def render_json(result) -> str:
+    payload = {
+        "tool": "casecrash",
+        "version": __version__,
+        "repo_root": result.repo_root,
+        "files_scanned": result.files_scanned,
+        "gitlinks_skipped": result.gitlinks_skipped,
+        "collisions": [
+            {
+                "kind": collision.kind,
+                "platforms": collision.platforms,
+                "files": [safe_display(n) for n in collision.names],
+            }
+            for collision in result.collisions
+        ],
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=True) + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        result = scan(args.path)
+    except (NotAGitRepo, GitNotFound) as exc:
+        print("casecrash: error: %s" % exc, file=sys.stderr)
+        return EXIT_ERROR
+
+    if args.format == "json":
+        sys.stdout.write(render_json(result))
+    else:
+        sys.stdout.write(render_text(result))
+
+    return EXIT_COLLISIONS if result.has_collisions else EXIT_OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())

casecrash/core.py

@@ -0,0 +1,285 @@
+"""Core collision detection for casecrash.
+
+Reads the git index (``git ls-files -s -z``) and groups tracked paths by
+``NFC(casefold(name))``.  Inside each group the cause is classified:
+
+* ``case`` — names share the same NFC form but differ (pure case
+  difference).  Breaks on macOS and Windows.
+* ``normalization`` — NFC forms differ by more than case (e.g. NFC ``café``
+  vs NFD ``café``).  Breaks on macOS, whose filesystems compare names
+  without regard to normalization.
+* ``exact-duplicate`` — the identical (name, mode, sha) entry appears twice,
+  which indicates index corruption.
+
+Filenames are handled as bytes end-to-end and only decoded for display with
+``surrogateescape``, so undecodable names can never crash the tool.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import unicodedata
+from dataclasses import dataclass, field
+
+
+class NotAGitRepo(Exception):
+    """Raised when the target directory is not inside a git repository."""
+
+
+class GitNotFound(Exception):
+    """Raised when the git executable cannot be found."""
+
+
+GITLINK_MODE = b"160000"
+
+
+@dataclass
+class IndexEntry:
+    name: bytes
+    mode: bytes
+    sha: bytes
+    stage: bytes
+
+
+@dataclass
+class Collision:
+    kind: str  # "case" | "normalization" | "exact-duplicate"
+    names: list[bytes] = field(default_factory=list)
+
+    @property
+    def platforms(self) -> list[str]:
+        if self.kind == "case":
+            return ["macOS", "Windows"]
+        if self.kind == "normalization":
+            return ["macOS"]
+        return ["macOS", "Windows", "Linux"]
+
+
+@dataclass
+class ScanResult:
+    repo_root: str
+    files_scanned: int
+    gitlinks_skipped: int
+    collisions: list[Collision] = field(default_factory=list)
+
+    @property
+    def has_collisions(self) -> bool:
+        return bool(self.collisions)
+
+
+# ---------------------------------------------------------------------------
+# display helpers
+# ---------------------------------------------------------------------------
+
+def _safe_char(ch: str) -> str:
+    code = ord(ch)
+    if 0xDC80 <= code <= 0xDCFF:  # surrogateescape byte
+        return "\\x%02x" % (code - 0xDC00)
+    return ch
+
+
+def safe_display(raw: bytes) -> str:
+    """Lossless-ish printable form of a raw filename.
+
+    Undecodable bytes become ``\\xNN`` escapes; everything else passes
+    through unchanged.
+    """
+    return "".join(_safe_char(c) for c in raw.decode("utf-8", "surrogateescape"))
+
+
+def escaped_display(raw: bytes) -> str:
+    """Like :func:`safe_display` but renders every non-ASCII char as \\uXXXX.
+
+    Makes NFC-vs-NFD differences visible in reports.
+    """
+    out = []
+    for ch in raw.decode("utf-8", "surrogateescape"):
+        code = ord(ch)
+        if 0xDC80 <= code <= 0xDCFF:
+            out.append("\\x%02x" % (code - 0xDC00))
+        elif code > 0x7E or code < 0x20:
+            out.append("\\u%04x" % code)
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
+def normalization_form(raw: bytes) -> str:
+    """Best-effort NFC/NFD label for a filename, '' when not applicable."""
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return ""
+    nfc = unicodedata.normalize("NFC", text)
+    nfd = unicodedata.normalize("NFD", text)
+    if text == nfc and text != nfd:
+        return "NFC"
+    if text == nfd and text != nfc:
+        return "NFD"
+    if text != nfc and text != nfd:
+        return "mixed"
+    return ""  # pure ASCII, form is irrelevant
+
+
+# ---------------------------------------------------------------------------
+# index reading
+# ---------------------------------------------------------------------------
+
+def _run_git(args: list[str], cwd: str) -> subprocess.CompletedProcess:
+    try:
+        return subprocess.run(
+            ["git"] + args,
+            cwd=cwd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+    except FileNotFoundError as exc:
+        raise GitNotFound(
+            "the 'git' executable was not found on PATH; "
+            "casecrash needs git to read the index"
+        ) from exc
+
+
+def repo_root(path: str) -> str:
+    """Return the repository root for *path*, or raise NotAGitRepo."""
+    if os.path.isfile(path):
+        path = os.path.dirname(os.path.abspath(path)) or "."
+    proc = _run_git(["rev-parse", "--show-toplevel"], cwd=path)
+    if proc.returncode != 0:
+        raise NotAGitRepo(
+            "%r is not inside a git repository" % os.path.abspath(path)
+        )
+    return proc.stdout.decode("utf-8", "replace").strip()
+
+
+def read_index(path: str) -> tuple[list[IndexEntry], int]:
+    """Read the git index.  Returns (entries, gitlink_count).
+
+    Gitlinks (submodules) are counted and excluded from the entries so they
+    never participate in collision detection.
+    """
+    root = repo_root(path)
+    proc = _run_git(["ls-files", "-s", "-z", "--full-name"], cwd=root)
+    if proc.returncode != 0:
+        raise NotAGitRepo(
+            "could not read the git index of %r: %s"
+            % (root, proc.stderr.decode("utf-8", "replace").strip())
+        )
+    entries: list[IndexEntry] = []
+    gitlinks = 0
+    for record in proc.stdout.split(b"\x00"):
+        if not record:
+            continue
+        head, _, name = record.partition(b"\t")
+        parts = head.split(b" ")
+        if len(parts) < 3 or not name:
+            continue
+        mode, sha, stage = parts[0], parts[1], parts[2]
+        if mode == GITLINK_MODE:
+            gitlinks += 1
+            continue
+        entries.append(IndexEntry(name=name, mode=mode, sha=sha, stage=stage))
+    return entries, gitlinks
+
+
+# ---------------------------------------------------------------------------
+# collision detection
+# ---------------------------------------------------------------------------
+
+def _collision_key(raw: bytes) -> tuple[str, object]:
+    """Grouping key: NFC(casefold(name)).
+
+    Names that are not valid UTF-8 fall back to byte-level lowercasing so
+    ASCII case collisions in weird filenames are still caught.
+    """
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return ("raw", raw.lower())
+    return ("text", unicodedata.normalize("NFC", text.casefold()))
+
+
+def _pair_kind(a: bytes, b: bytes) -> str:
+    """Classify why two colliding names collide.
+
+    * ``case`` — the names are equal under Unicode casefolding, so they
+      differ only by case (``README.md``/``readme.md``, ``É``/``é``).
+      Breaks on macOS and Windows.
+    * ``normalization`` — the casefolded forms still differ, so the names
+      are distinct spellings that only become equal after Unicode
+      normalization (NFC ``café`` vs NFD ``café``).  Breaks on macOS,
+      whose filesystems compare names without regard to normalization.
+    """
+    try:
+        fa = a.decode("utf-8", "surrogateescape").casefold()
+        fb = b.decode("utf-8", "surrogateescape").casefold()
+    except UnicodeDecodeError:  # pragma: no cover - defensive
+        return "case"
+    return "case" if fa == fb else "normalization"
+
+
+def _classify(names: list[bytes]) -> str:
+    """Classify a group of distinct names sharing a collision key.
+
+    A group is labeled ``normalization`` if any pair inside it collides
+    for normalization reasons; otherwise it is a pure ``case`` collision.
+    """
+    for i, first in enumerate(names):
+        for other in names[i + 1:]:
+            if _pair_kind(first, other) == "normalization":
+                return "normalization"
+    return "case"
+
+
+def find_collisions(entries: list[IndexEntry]) -> list[Collision]:
+    """Detect collisions among index entries."""
+    collisions: list[Collision] = []
+
+    # 1. Exact duplicates: identical (name, mode, sha) more than once.
+    #    (Same name at different unmerged stages is normal merge state,
+    #    not corruption, so stage is deliberately ignored here... in fact
+    #    we require the full triple to repeat.)
+    seen: dict[tuple[bytes, bytes, bytes], int] = {}
+    for entry in entries:
+        key = (entry.name, entry.mode, entry.sha)
+        seen[key] = seen.get(key, 0) + 1
+    for (name, _mode, _sha), count in seen.items():
+        if count > 1:
+            collisions.append(
+                Collision(kind="exact-duplicate", names=[name, name])
+            )
+
+    # 2. Case / normalization collisions over distinct names.
+    distinct: dict[bytes, None] = {}
+    for entry in entries:
+        distinct.setdefault(entry.name)
+    groups: dict[tuple[str, object], list[bytes]] = {}
+    for name in distinct:
+        groups.setdefault(_collision_key(name), []).append(name)
+
+    for names in groups.values():
+        if len(names) < 2:
+            continue
+        collisions.append(
+            Collision(kind=_classify(sorted(names)), names=sorted(names))
+        )
+
+    # Deterministic order: exact duplicates first, then by first filename.
+    order = {"exact-duplicate": 0, "normalization": 1, "case": 2}
+    collisions.sort(
+        key=lambda c: (order.get(c.kind, 3), safe_display(c.names[0]))
+    )
+    return collisions
+
+
+def scan(path: str = ".") -> ScanResult:
+    """Scan the git index containing *path* for filename collisions."""
+    root = repo_root(path)
+    entries, gitlinks = read_index(path)
+    return ScanResult(
+        repo_root=root,
+        files_scanned=len({e.name for e in entries}),
+        gitlinks_skipped=gitlinks,
+        collisions=find_collisions(entries),
+    )

casecrash-0.1.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: casecrash
+Version: 0.1.0
+Summary: Find filenames in your git index that would collide on macOS or Windows checkouts
+Author: hao li
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/casecrash
+Keywords: git,macos,windows,filename,case-sensitivity,unicode,ci
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# casecrash
+
+**Git can track two files your Mac cannot check out.**
+
+`README.md` and `readme.md` can sit side by side in a git repo — until
+someone on macOS or Windows clones it and the checkout explodes. The same
+goes for Unicode lookalikes: NFC `café` vs NFD `café` look identical in
+your terminal but are different byte sequences, and macOS treats them as
+the same file.
+
+casecrash reads your git index and flags every pair of tracked files that
+would collide on a case-insensitive or Unicode-normalizing filesystem —
+*before* it breaks a teammate's checkout.
+
+## Quickstart
+
+```bash
+pip install casecrash
+cd your-repo
+casecrash
+```
+
+```
+casecrash: found 2 filename collision(s) in /tmp/demorepo (5 files scanned):
+
+[normalization] collide after Unicode normalization (macOS):
+  'cafe\u0301.md'  [NFD]
+  'caf\u00e9.md'  [NFC]
+  -> breaks on: macOS
+
+[case] collide on case-insensitive filesystems (macOS, Windows):
+  'README.md'
+  'readme.md'
+  -> breaks on: macOS, Windows
+
+Fix: rename one of each colliding pair before a macOS/Windows user clones this repo.  'git mv' the odd one out and commit.
+```
+
+No collisions? Exit 0 and a clean bill of health:
+
+```
+casecrash: no filename collisions in the git index (128 files scanned).
+```
+
+## What it detects
+
+| Kind | Example | Breaks on |
+|---|---|---|
+| `case` | `README.md` vs `readme.md`, `É` vs `é` | macOS, Windows |
+| `normalization` | NFC `café` vs NFD `café` | macOS (APFS compares names without regard to normalization) |
+| `exact-duplicate` | identical index entry twice | everywhere (index corruption) |
+
+Detection is done on the git index (`git ls-files`), not the working
+tree, so it works on any OS — a Linux CI runner can catch a collision
+that would only bite macOS users. Filenames are handled as raw bytes, so
+undecodable names can never crash the tool. Submodules are skipped (and
+counted).
+
+## CI usage
+
+casecrash exits **1** when collisions are found, **0** when clean, **2** on
+errors — so it drops straight into any pipeline:
+
+```yaml
+# .github/workflows/casecrash.yml
+name: casecheck
+on: [push, pull_request]
+jobs:
+  casecrash:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install casecrash
+      - run: casecrash
+```
+
+JSON output for scripting:
+
+```bash
+casecrash --format json
+```
+
+## Why this happens
+
+Git was born on case-sensitive Linux filesystems and its index happily
+stores `File.txt` and `file.txt` as two separate entries. macOS and
+Windows disagree: checking out the second name silently overwrites the
+first (or the clone fails outright). Normalization collisions are
+sneakier — macOS's HFS+/APFS normalizes filenames, so two
+byte-different, canonically-equivalent names are the same file there.
+
+This bites real projects: agents and scripts that generate files with
+slightly different casings, Unicode filenames pasted from different
+platforms, and the occasional CVE (see
+[CVE-2021-21300](https://github.blog/security/vulnerability-research/github-security-lab-cve-2021-21300/),
+where git's own checkout could be tricked on case-insensitive
+filesystems).
+
+## Install
+
+```bash
+pip install casecrash
+```
+
+Requires Python 3.9+ and git. Zero dependencies.
+
+## License
+
+MIT

casecrash-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+casecrash/__init__.py,sha256=R2rcdGlaRrNotjlCC4vWLPDab9lu_bSfzo7DmV29HWo,191
+casecrash/cli.py,sha256=-pWt2vIBf5xGFRx-X_wqQGs0WxhrTGbF6k3lmZgZy_M,4111
+casecrash/core.py,sha256=3wqhjcJJohtmMLg2-72rhvv1PLMEZ366geLycMqLaVE,9428
+casecrash-0.1.0.dist-info/licenses/LICENSE,sha256=OYhQDg7nxWoFtnF6J8NkFUA8NMw5TKv9a1WTXHY-fu4,1063
+casecrash-0.1.0.dist-info/METADATA,sha256=xGorsyE_xQhKF1i1k4fMcvTZy6omLlDRMt67jGv4BTs,4038
+casecrash-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+casecrash-0.1.0.dist-info/entry_points.txt,sha256=HYfGDKu-1RxOjfEpqjq8XKqvQXX3HWQHCCaWVWwsGTw,49
+casecrash-0.1.0.dist-info/top_level.txt,sha256=q1xuSiKusSGVmX-P6XXE9lBP-cFfn3UaUikjNu578zU,10
+casecrash-0.1.0.dist-info/RECORD,,

casecrash-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

casecrash-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+casecrash = casecrash.cli:main

casecrash-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hao li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

casecrash-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+casecrash