casecrash 0.1.0__tar.gz

casecrash-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,112 @@
+# 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/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "casecrash"
+version = "0.1.0"
+description = "Find filenames in your git index that would collide on macOS or Windows checkouts"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "hao li"}]
+keywords = ["git", "macos", "windows", "filename", "case-sensitivity", "unicode", "ci"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Topic :: Utilities",
+]
+
+[project.scripts]
+casecrash = "casecrash.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/hahahahahahahahah6/casecrash"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["casecrash*"]

casecrash-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

casecrash-0.1.0/src/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-0.1.0/src/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())