encoding-doctor 0.2.0__py3-none-any.whl

encoding_doctor/__init__.py

@@ -0,0 +1,19 @@
+"""
+encoding-doctor
+---------------
+Scan, fix, and verify file encoding issues.
+
+Usage:
+    from encoding_doctor.scanner import scan_directory
+    from encoding_doctor.fixer import fix_directory
+    from encoding_doctor.verifier import verify_directory
+
+Or via CLI:
+    enc-doctor scan ./my_project
+    enc-doctor fix ./my_project
+    enc-doctor verify ./my_project
+"""
+
+__version__ = "0.1.0"
+__author__ = "Stateflow Labs"
+__license__ = "MIT"

encoding_doctor/cli.py

@@ -0,0 +1,244 @@
+"""
+cli.py
+------
+Command-line interface for encoding-doctor.
+
+Commands:
+    enc-doctor scan       <path>  -- detect encoding issues (FREE)
+    enc-doctor fix        <path>  -- fix detected issues    (LICENSE)
+    enc-doctor verify     <path>  -- verify files are clean (LICENSE)
+    enc-doctor restore    <file>  -- restore a .bak file    (LICENSE)
+    enc-doctor activate   <key>   -- activate license key
+    enc-doctor deactivate         -- deactivate license (free up seat)
+    enc-doctor license            -- show license status
+
+Flags:
+    --dry-run   (fix only) show what would change without writing
+    --all       (scan only) show clean files too
+"""
+
+import sys
+import os
+
+
+def _check_path(path: str):
+    if not os.path.exists(path):
+        print(f"ERROR: path not found: {path}")
+        sys.exit(1)
+
+
+def cmd_scan(path: str, show_all: bool = False):
+    from .scanner import scan_directory, scan_file
+    from .reporter import print_scan_report
+
+    if os.path.isfile(path):
+        report = scan_file(path)
+        reports = [report] if report else []
+    else:
+        reports = scan_directory(path)
+
+    print_scan_report(reports, show_clean=show_all)
+
+    has_issues = any(r.has_issues for r in reports)
+    sys.exit(1 if has_issues else 0)
+
+
+def cmd_fix(path: str, dry_run: bool = False):
+    from .license import require_license
+    require_license("fix")
+
+    from .scanner import scan_directory, scan_file
+    from .fixer import fix_directory
+    from .reporter import print_fix_report
+
+    print("\033[93mWARNING: enc-doctor fix modifies files in-place.\033[0m")
+    print("\033[2mBackups will be created as .bak files.\033[0m")
+    print("\033[2mRun 'enc-doctor scan' first if you have not already.\033[0m\n")
+
+    if os.path.isfile(path):
+        report = scan_file(path)
+        reports = [report] if report else []
+    else:
+        reports = scan_directory(path)
+
+    results = fix_directory(reports, dry_run=dry_run)
+    print_fix_report(results, dry_run=dry_run)
+
+
+def cmd_verify(path: str):
+    from .license import require_license
+    require_license("verify")
+
+    from .verifier import verify_directory, verify_file
+    from .reporter import print_verify_report
+
+    if os.path.isfile(path):
+        results = [verify_file(path)]
+    else:
+        results = verify_directory(path)
+
+    print_verify_report(results)
+
+    all_ok = all(r.ok for r in results)
+    sys.exit(0 if all_ok else 1)
+
+
+def cmd_restore(path: str):
+    from .license import require_license
+    require_license("restore")
+
+    from .verifier import restore_backup
+    bak = path + ".bak"
+    if not os.path.exists(bak):
+        print(f"ERROR: no backup found at {bak}")
+        sys.exit(1)
+    restored = restore_backup(path)
+    if restored:
+        print(f"\033[92mRestored: {path}\033[0m")
+        print(f"\033[2mFrom: {bak}\033[0m")
+    else:
+        print("ERROR: restore failed")
+        sys.exit(1)
+
+
+def cmd_activate(key: str):
+    from .license import activate
+    ok, msg = activate(key)
+    if ok:
+        print(f"\n  \033[92m✓ {msg}\033[0m")
+        print()
+        print("  \033[2mLicense saved to ~/.encoding-doctor/license.json\033[0m")
+        print()
+        print("  Unlocked commands:")
+        print("    scan    \033[92m✓ free\033[0m")
+        print("    fix     \033[92m✓ licensed\033[0m")
+        print("    verify  \033[92m✓ licensed\033[0m")
+        print("    restore \033[92m✓ licensed\033[0m")
+        print()
+    else:
+        print(f"\n  \033[91m✗ {msg}\033[0m\n")
+        sys.exit(1)
+
+
+def cmd_deactivate():
+    from .license import deactivate
+    ok, msg = deactivate()
+    if ok:
+        print(f"\n  \033[92m✓ {msg}\033[0m\n")
+    else:
+        print(f"\n  \033[91m✗ {msg}\033[0m\n")
+        sys.exit(1)
+
+
+def cmd_license_status():
+    from .license import status
+    info = status()
+    print()
+    if info["active"]:
+        print("  \033[92mLicense: ACTIVE\033[0m")
+        if info.get("customer"):
+            print(f"  Customer : {info['customer']}")
+        if info.get("key_preview"):
+            print(f"  Key      : {info['key_preview']}")
+        if info.get("activated_at"):
+            print(f"  Since    : {info['activated_at'][:10]}")
+        print()
+        print("  All commands unlocked.")
+    else:
+        print("  \033[93mLicense: NOT ACTIVATED\033[0m")
+        print()
+        print("  Free:  scan")
+        print("  Paid:  fix, verify, restore")
+        print()
+        print("  Get license → https://stateflow.dev/encoding-doctor")
+        print("  Then run:    enc-doctor activate <YOUR-KEY>")
+    print()
+
+
+def main():
+    args = sys.argv[1:]
+
+    if not args or args[0] in ("-h", "--help"):
+        print("""
+encoding-doctor v0.2.0
+
+Usage:
+  enc-doctor scan       <path> [--all]
+  enc-doctor fix        <path> [--dry-run]
+  enc-doctor verify     <path>
+  enc-doctor restore    <file>
+  enc-doctor activate   <license-key>
+  enc-doctor deactivate
+  enc-doctor license
+
+Commands:
+  scan        Detect encoding issues — free forever
+  fix         Fix detected issues    — requires license
+  verify      Confirm all files are valid UTF-8 — requires license
+  restore     Restore a file from .bak backup   — requires license
+  activate    Activate your license key
+  deactivate  Free up your license seat (e.g. when switching machines)
+  license     Show current license status
+
+Flags:
+  --all      (scan) also show clean files
+  --dry-run  (fix) show what would change without writing files
+
+Get a license → https://stateflow.dev/encoding-doctor
+""")
+        sys.exit(0)
+
+    command = args[0]
+    rest    = args[1:]
+
+    if command == "scan":
+        if not rest:
+            print("ERROR: provide a path. Usage: enc-doctor scan <path>")
+            sys.exit(1)
+        path = rest[0]
+        _check_path(path)
+        show_all = "--all" in rest
+        cmd_scan(path, show_all=show_all)
+
+    elif command == "fix":
+        if not rest:
+            print("ERROR: provide a path. Usage: enc-doctor fix <path>")
+            sys.exit(1)
+        path = rest[0]
+        _check_path(path)
+        dry_run = "--dry-run" in rest
+        cmd_fix(path, dry_run=dry_run)
+
+    elif command == "verify":
+        if not rest:
+            print("ERROR: provide a path. Usage: enc-doctor verify <path>")
+            sys.exit(1)
+        path = rest[0]
+        _check_path(path)
+        cmd_verify(path)
+
+    elif command == "restore":
+        if not rest:
+            print("ERROR: provide a file path. Usage: enc-doctor restore <file>")
+            sys.exit(1)
+        cmd_restore(rest[0])
+
+    elif command == "activate":
+        if not rest:
+            print("ERROR: provide a license key. Usage: enc-doctor activate <key>")
+            sys.exit(1)
+        cmd_activate(rest[0])
+
+    elif command == "deactivate":
+        cmd_deactivate()
+
+    elif command == "license":
+        cmd_license_status()
+
+    else:
+        print(f"ERROR: unknown command '{command}'. Run 'enc-doctor --help'")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

encoding_doctor/fixer.py

@@ -0,0 +1,85 @@
+"""
+fixer.py
+--------
+Fixes encoding issues detected by scanner.py.
+Always creates .bak backup before modifying any file.
+
+Based on real fix operations performed on adaptive_runtime source files.
+"""
+
+import os
+import shutil
+from .scanner import MOJIBAKE_PATTERNS, BOM, FileReport
+
+
+def _backup(path: str) -> str:
+    bak = path + ".bak"
+    shutil.copy2(path, bak)
+    return bak
+
+
+def fix_file(report: FileReport, dry_run: bool = False) -> dict:
+    """
+    Fix all fixable issues in a file.
+    Returns dict with keys: path, fixed, skipped, backup, changes
+    """
+    result = {"path": report.path, "fixed": [], "skipped": [], "backup": None, "changes": 0}
+
+    if not report.fixable:
+        result["skipped"] = [i.label for i in report.issues if not i.fixable]
+        return result
+
+    with open(report.path, "rb") as f:
+        raw = f.read()
+
+    original = raw
+
+    # Fix BOM
+    if raw.startswith(BOM):
+        raw = raw[3:]
+        result["fixed"].append("BOM stripped")
+
+    # Fix mojibake (byte-level replacement)
+    for bad_bytes, good_bytes, label in MOJIBAKE_PATTERNS:
+        n = raw.count(bad_bytes)
+        if n:
+            raw = raw.replace(bad_bytes, good_bytes)
+            result["fixed"].append(f"mojibake fixed: {label} ({n}x)")
+
+    # Fix CRLF -> LF
+    if b"\r\n" in raw:
+        count = raw.count(b"\r\n")
+        raw = raw.replace(b"\r\n", b"\n")
+        result["fixed"].append(f"CRLF -> LF ({count} lines)")
+
+    # Fix null bytes
+    if b"\x00" in raw:
+        count = raw.count(b"\x00")
+        raw = raw.replace(b"\x00", b"")
+        result["fixed"].append(f"null bytes removed ({count})")
+
+    if raw == original:
+        return result
+
+    result["changes"] = len(result["fixed"])
+
+    if not dry_run:
+        result["backup"] = _backup(report.path)
+        with open(report.path, "wb") as f:
+            f.write(raw)
+
+    return result
+
+
+def fix_directory(reports: list, dry_run: bool = False) -> list:
+    """
+    Fix all fixable files from a list of FileReport.
+    Returns list of fix result dicts.
+    """
+    results = []
+    for report in reports:
+        if report.has_issues and report.fixable:
+            result = fix_file(report, dry_run=dry_run)
+            if result["changes"] > 0 or result["skipped"]:
+                results.append(result)
+    return results

encoding_doctor/license.py

@@ -0,0 +1,193 @@
+"""
+license.py
+----------
+License validation for encoding-doctor.
+Uses Lemon Squeezy API for activation/deactivation.
+
+Commands added to CLI:
+    enc-doctor activate <key>   -- activate license key
+    enc-doctor deactivate       -- deactivate (free up seat)
+    enc-doctor license          -- show license status
+
+Free:  scan
+Paid:  fix, verify, restore
+"""
+
+import json
+import os
+import platform
+import urllib.request
+import urllib.error
+from pathlib import Path
+
+# ── Lemon Squeezy config ──────────────────────────────────────────────────────
+# Ganti dengan Store ID & Product ID kamu setelah produk dibuat di Lemon Squeezy
+LS_STORE_ID    = "399875"     # Settings → Store → Store ID
+LS_PRODUCT_ID  = "1123336"   # Products → klik produk → ID di URL
+
+ACTIVATE_URL   = "https://api.lemonsqueezy.com/v1/licenses/activate"
+DEACTIVATE_URL = "https://api.lemonsqueezy.com/v1/licenses/deactivate"
+VALIDATE_URL   = "https://api.lemonsqueezy.com/v1/licenses/validate"
+
+# ── Local storage ─────────────────────────────────────────────────────────────
+LICENSE_DIR  = Path.home() / ".encoding-doctor"
+LICENSE_FILE = LICENSE_DIR / "license.json"
+
+# ── Commands that require a license ──────────────────────────────────────────
+PAID_COMMANDS = ("fix", "verify", "restore")
+FREE_COMMANDS = ("scan",)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Internal helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _save(payload: dict):
+    LICENSE_DIR.mkdir(parents=True, exist_ok=True)
+    LICENSE_FILE.write_text(json.dumps(payload, indent=2))
+
+
+def _load() -> dict | None:
+    try:
+        return json.loads(LICENSE_FILE.read_text())
+    except Exception:
+        return None
+
+
+def _post(url: str, data: dict) -> dict:
+    body = json.dumps(data).encode()
+    req  = urllib.request.Request(
+        url,
+        data=body,
+        headers={"Content-Type": "application/json", "Accept": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=10) as r:
+        return json.loads(r.read())
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Public API  (called from cli.py)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def activate(key: str) -> tuple[bool, str]:
+    """
+    Activate a Lemon Squeezy license key.
+    Saves license.json locally on success.
+    """
+    key = key.strip()
+    if not key:
+        return False, "License key cannot be empty."
+
+    try:
+        resp = _post(ACTIVATE_URL, {
+            "license_key": key,
+            "instance_name": platform.node() or "encoding-doctor",
+        })
+    except urllib.error.HTTPError as e:
+        try:
+            body = json.loads(e.read())
+            return False, f"Activation failed: {body.get('error', e.reason)}"
+        except Exception:
+            return False, f"Activation failed: HTTP {e.code}"
+    except Exception as e:
+        return False, f"Network error: {e}"
+
+    if not resp.get("activated"):
+        return False, resp.get("error", "Activation failed — check your key and try again.")
+
+    payload = {
+        "key":          key,
+        "instance_id":  resp["instance"]["id"],
+        "customer":     resp["meta"].get("customer_email", ""),
+        "store_id":     resp["meta"].get("store_id", ""),
+        "product_id":   resp["meta"].get("product_id", ""),
+        "activated_at": resp["license_key"]["created_at"],
+    }
+    _save(payload)
+
+    customer = payload["customer"] or "user"
+    return True, f"License activated. Welcome, {customer}!"
+
+
+def deactivate() -> tuple[bool, str]:
+    """
+    Deactivate this machine's license seat.
+    Removes license.json so the key can be used on another machine.
+    """
+    data = _load()
+    if not data:
+        return False, "No active license found on this machine."
+
+    try:
+        _post(DEACTIVATE_URL, {
+            "license_key": data["key"],
+            "instance_id": data["instance_id"],
+        })
+    except Exception:
+        pass  # Even if API call fails, remove local file
+
+    try:
+        LICENSE_FILE.unlink()
+    except Exception:
+        pass
+
+    return True, "License deactivated. You can now activate on another machine."
+
+
+def validate() -> tuple[bool, str]:
+    """
+    Offline check: is this machine licensed?
+    Returns (True, customer_email) or (False, reason).
+    Does NOT call the network — fast, always works offline.
+    """
+    data = _load()
+    if not data:
+        return False, "not_activated"
+    if not data.get("key") or not data.get("instance_id"):
+        return False, "corrupted"
+    return True, data.get("customer", "licensed")
+
+
+def status() -> dict:
+    """Return a dict with license info for display."""
+    data = _load()
+    if not data:
+        return {"active": False}
+    return {
+        "active":       True,
+        "customer":     data.get("customer", ""),
+        "activated_at": data.get("activated_at", ""),
+        "key_preview":  data["key"][:4] + "-****-****-" + data["key"][-4:],
+    }
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Gate  (call this before any paid command)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def require_license(command: str):
+    """
+    Call at the top of fix / verify / restore.
+    Prints a clear message and exits if not licensed.
+    """
+    if command not in PAID_COMMANDS:
+        return  # free command, no check needed
+
+    ok, _ = validate()
+    if ok:
+        return  # licensed, proceed
+
+    # Not licensed — print gate message and exit
+    print()
+    print("  \033[93menc-doctor: license required\033[0m")
+    print()
+    print(f"  '\033[1m{command}\033[0m' is a paid feature.")
+    print(f"  '\033[1mscan\033[0m' is free — run that first to see what needs fixing.")
+    print()
+    print("  To unlock fix, verify, and restore:")
+    print("    1. Get your license  →  https://stateflow.dev/encoding-doctor")
+    print("    2. Run:  enc-doctor activate <YOUR-KEY>")
+    print()
+    import sys
+    sys.exit(1)

encoding_doctor/reporter.py

@@ -0,0 +1,107 @@
+"""
+reporter.py
+-----------
+Formats scan, fix, and verify results for terminal output.
+"""
+
+import os
+
+GREEN  = "\033[92m"
+YELLOW = "\033[93m"
+RED    = "\033[91m"
+CYAN   = "\033[96m"
+DIM    = "\033[2m"
+RESET  = "\033[0m"
+BOLD   = "\033[1m"
+
+
+def _rel(path: str) -> str:
+    try:
+        return os.path.relpath(path)
+    except ValueError:
+        return path
+
+
+def print_scan_report(reports: list, show_clean: bool = False):
+    issues = [r for r in reports if r.has_issues]
+    clean  = [r for r in reports if not r.has_issues]
+
+    print(f"\n{BOLD}SCAN REPORT{RESET}")
+    print(f"{DIM}{'='*60}{RESET}")
+    print(f"  Total files scanned : {len(reports)}")
+    print(f"  Files with issues   : {YELLOW}{len(issues)}{RESET}")
+    print(f"  Clean files         : {GREEN}{len(clean)}{RESET}")
+    print()
+
+    if not issues:
+        print(f"  {GREEN}All files are clean.{RESET}")
+        return
+
+    for report in issues:
+        print(f"  {YELLOW}WARN{RESET}  {_rel(report.path)}")
+        for issue in report.issues:
+            count_str = f" ({issue.count}x)" if issue.count else ""
+            fix_str = "" if issue.fixable else f"  {DIM}[manual fix required]{RESET}"
+            print(f"        {DIM}>{RESET} {issue.label}{count_str}{fix_str}")
+
+    if show_clean:
+        for report in clean:
+            print(f"  {GREEN}OK{RESET}    {_rel(report.path)}")
+
+    print()
+    print(f"  {YELLOW}Run 'enc-doctor fix <path>' to repair fixable issues.{RESET}")
+    print(f"  {DIM}Review this report carefully before running fix.{RESET}")
+    print()
+
+
+def print_fix_report(results: list, dry_run: bool = False):
+    label = "DRY RUN" if dry_run else "FIX REPORT"
+    print(f"\n{BOLD}{label}{RESET}")
+    print(f"{DIM}{'='*60}{RESET}")
+
+    total_changes = 0
+    for r in results:
+        if r["changes"]:
+            print(f"  {GREEN}FIXED{RESET}  {_rel(r['path'])}")
+            for change in r["fixed"]:
+                print(f"         {DIM}>{RESET} {change}")
+            if r["backup"] and not dry_run:
+                print(f"         {DIM}backup: {_rel(r['backup'])}{RESET}")
+            total_changes += r["changes"]
+        if r["skipped"]:
+            print(f"  {YELLOW}SKIP{RESET}   {_rel(r['path'])}")
+            for skip in r["skipped"]:
+                print(f"         {DIM}>{RESET} {skip} (manual fix required)")
+
+    print()
+    if total_changes:
+        action = "Would fix" if dry_run else "Fixed"
+        print(f"  {GREEN}{action} {total_changes} issue(s).{RESET}")
+        if not dry_run:
+            print(f"  {DIM}Backups saved as .bak{RESET}")
+            print(f"  {DIM}Run 'enc-doctor verify <path>' to confirm.{RESET}")
+    else:
+        print(f"  {GREEN}No changes made.{RESET}")
+    print()
+
+
+def print_verify_report(results: list):
+    passed = [r for r in results if r.ok]
+    failed = [r for r in results if not r.ok]
+
+    print(f"\n{BOLD}VERIFY REPORT{RESET}")
+    print(f"{DIM}{'='*60}{RESET}")
+
+    for r in failed:
+        print(f"  {RED}FAIL{RESET}  {_rel(r.path)}")
+        print(f"        {DIM}>{RESET} {r.error}")
+
+    print()
+    print(f"  {GREEN}PASS{RESET}  {len(passed)} / {len(results)} files")
+
+    if not failed:
+        print(f"  {GREEN}All files valid UTF-8. Safe to commit.{RESET}")
+    else:
+        print(f"  {RED}{len(failed)} file(s) still have issues.{RESET}")
+        print(f"  {DIM}Run 'enc-doctor fix <path>' or restore from .bak{RESET}")
+    print()

encoding_doctor/scanner.py

@@ -0,0 +1,138 @@
+"""
+scanner.py
+----------
+Scans files and directories for encoding issues.
+
+Detects:
+  - Mojibake (UTF-8 bytes re-encoded as cp1252)
+  - BOM (Byte Order Mark)
+  - CRLF line endings
+  - Null bytes
+  - Non-UTF-8 encoding
+
+Based on real encoding bugs found in production Python projects on Windows.
+"""
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# Mojibake byte patterns identified from real projects.
+# Each: (corrupt_bytes, correct_utf8_bytes, human_label)
+# ---------------------------------------------------------------------------
+MOJIBAKE_PATTERNS = [
+    (b"\xc3\xa2\xe2\x80\xa0\xe2\x80\x99", "\u2192".encode("utf-8"), "arrow ->"),
+    (b"\xc3\xa2\xe2\x82\xac\xe2\x80\x9d", "\u2014".encode("utf-8"), "em dash --"),
+    (b"\xc3\xa2\xe2\x80\xa2\xc2\xac",     "\u2550".encode("utf-8"), "box ="),
+    (b"\xc3\xa2\xe2\x80\x9c\xc2\x80",     "\u2500".encode("utf-8"), "box -"),
+    (b"\xc3\xa2\xe2\x82\xac\xc2\xa2",     "\u2022".encode("utf-8"), "bullet"),
+    (b"\xc3\xa2\xe2\x82\xac\xe2\x84\xa2", "\u2019".encode("utf-8"), "right quote"),
+    (b"\xc3\xa2\xe2\x82\xac\xc5\x93",     "\u201c".encode("utf-8"), "left curly quote"),
+    (b"\xc3\xa2\xe2\x82\xac\xc2\x9d",     "\u201d".encode("utf-8"), "right curly quote"),
+]
+
+BOM = b"\xef\xbb\xbf"
+
+TEXT_EXTENSIONS = {
+    ".py", ".txt", ".md", ".rst", ".json", ".yaml", ".yml",
+    ".toml", ".cfg", ".ini", ".env", ".sh", ".bat", ".ps1",
+    ".js", ".ts", ".jsx", ".tsx", ".css", ".html", ".htm",
+    ".xml", ".csv", ".tsv", ".sql", ".rb", ".php", ".go",
+}
+
+SKIP_DIRS = {
+    "__pycache__", ".git", ".venv", "venv", "env", "node_modules",
+    ".mypy_cache", ".pytest_cache", "dist", "build", ".eggs",
+}
+
+
+@dataclass
+class FileIssue:
+    kind: str
+    label: str
+    count: int = 0
+    fixable: bool = True
+
+
+@dataclass
+class FileReport:
+    path: str
+    encoding: str
+    size: int
+    issues: list = field(default_factory=list)
+
+    @property
+    def has_issues(self):
+        return len(self.issues) > 0
+
+    @property
+    def fixable(self):
+        return any(i.fixable for i in self.issues)
+
+
+def _probe_encoding(raw: bytes) -> str:
+    if raw.startswith(BOM):
+        return "UTF-8 BOM"
+    try:
+        raw.decode("utf-8")
+        return "UTF-8"
+    except UnicodeDecodeError:
+        return "non-UTF-8"
+
+
+def _is_binary(raw: bytes) -> bool:
+    sample = raw[:512]
+    if not sample:
+        return False
+    non_text = sum(1 for b in sample if b < 9 or (14 <= b <= 31 and b != 27))
+    return (non_text / len(sample)) > 0.30
+
+
+def scan_file(path: str) -> Optional[FileReport]:
+    ext = os.path.splitext(path)[1].lower()
+    if ext not in TEXT_EXTENSIONS:
+        return None
+    try:
+        with open(path, "rb") as f:
+            raw = f.read()
+    except (PermissionError, OSError):
+        return None
+    if _is_binary(raw):
+        return None
+
+    enc = _probe_encoding(raw)
+    report = FileReport(path=path, encoding=enc, size=len(raw))
+
+    if raw.startswith(BOM):
+        report.issues.append(FileIssue(kind="bom", label="BOM (\\xef\\xbb\\xbf) detected", count=1))
+
+    for bad_bytes, _, label in MOJIBAKE_PATTERNS:
+        n = raw.count(bad_bytes)
+        if n:
+            report.issues.append(FileIssue(kind="mojibake", label=f"mojibake: {label}", count=n))
+
+    crlf_count = raw.count(b"\r\n")
+    if crlf_count:
+        report.issues.append(FileIssue(kind="crlf", label="CRLF line endings", count=crlf_count))
+
+    null_count = raw.count(b"\x00")
+    if null_count:
+        report.issues.append(FileIssue(kind="null_bytes", label="null bytes", count=null_count))
+
+    if enc == "non-UTF-8":
+        report.issues.append(FileIssue(kind="non_utf8", label="non-UTF-8 encoding", fixable=False))
+
+    return report
+
+
+def scan_directory(path: str) -> list:
+    reports = []
+    for root, dirs, files in os.walk(path):
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
+        for fname in sorted(files):
+            fpath = os.path.join(root, fname)
+            report = scan_file(fpath)
+            if report is not None:
+                reports.append(report)
+    return reports

encoding_doctor/verifier.py

@@ -0,0 +1,67 @@
+"""
+verifier.py
+-----------
+Verifies that files are valid UTF-8 after fixing.
+Restores from .bak if needed.
+"""
+
+import os
+import shutil
+from dataclasses import dataclass
+
+
+@dataclass
+class VerifyResult:
+    path: str
+    ok: bool
+    encoding: str
+    error: str = ""
+
+
+def verify_file(path: str) -> VerifyResult:
+    try:
+        with open(path, "rb") as f:
+            raw = f.read()
+
+        # Check for BOM (should have been removed by fixer)
+        if raw.startswith(b"\xef\xbb\xbf"):
+            return VerifyResult(path=path, ok=False, encoding="UTF-8 BOM", error="BOM still present")
+
+        # Validate UTF-8
+        raw.decode("utf-8")
+
+        # Check for remaining CRLF
+        if b"\r\n" in raw:
+            return VerifyResult(path=path, ok=False, encoding="UTF-8", error="CRLF still present")
+
+        return VerifyResult(path=path, ok=True, encoding="UTF-8")
+
+    except UnicodeDecodeError as e:
+        return VerifyResult(path=path, ok=False, encoding="non-UTF-8", error=str(e))
+    except (PermissionError, OSError) as e:
+        return VerifyResult(path=path, ok=False, encoding="unknown", error=str(e))
+
+
+def verify_directory(path: str, extensions: set = None) -> list:
+    from .scanner import TEXT_EXTENSIONS, SKIP_DIRS
+    ext_filter = extensions or TEXT_EXTENSIONS
+    results = []
+
+    for root, dirs, files in os.walk(path):
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
+        for fname in sorted(files):
+            ext = os.path.splitext(fname)[1].lower()
+            if ext in ext_filter:
+                fpath = os.path.join(root, fname)
+                results.append(verify_file(fpath))
+
+    return results
+
+
+def restore_backup(path: str) -> bool:
+    """Restore file from .bak backup. Returns True if restored."""
+    bak = path + ".bak"
+    if os.path.exists(bak):
+        shutil.copy2(bak, path)
+        return True
+    return False

encoding_doctor-0.2.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: encoding-doctor
+Version: 0.2.0
+Summary: Scan, fix, and verify file encoding issues. Mojibake, BOM, CRLF, null bytes — fixed in one command.
+Author-email: Stateflow Labs <stateflow.labs@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://stateflow-dev.github.io/stateflowlabs/
+Project-URL: Repository, https://github.com/stateflow-dev/encoding-doctor
+Keywords: encoding,utf-8,mojibake,bom,crlf,file encoding,encoding fix,encoding repair,python encoding,encoding tool,developer tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# encoding-doctor
+
+**Scan, fix, and verify file encoding issues across your project in one command.**
+
+Fixes mojibake, BOM, CRLF line endings, null bytes, and non-UTF-8 encoding —
+automatically detected and repaired, with backups created before every change.
+
+Built from real encoding bugs found in production Python projects on Windows.
+
+---
+
+## Install
+
+```bash
+pip install encoding-doctor
+```
+
+---
+
+## Usage
+
+```bash
+# Step 1 — scan first, always
+enc-doctor scan ./my_project
+
+# Step 2 — preview changes without writing
+enc-doctor fix ./my_project --dry-run
+
+# Step 3 — fix (backups created automatically as .bak)
+enc-doctor fix ./my_project
+
+# Step 4 — verify everything is clean
+enc-doctor verify ./my_project
+```
+
+---
+
+## What it fixes
+
+| Problem | Description |
+|---|---|
+| **Mojibake** | UTF-8 bytes mis-read as cp1252 and saved as garbage |
+| **BOM** | `\xef\xbb\xbf` prefix added by Notepad/Excel that breaks parsers |
+| **CRLF** | Windows `\r\n` mixed with Unix `\n` — causes Git diff noise |
+| **Null bytes** | Binary corruption from FTP or terminal copy-paste |
+| **Non-UTF-8** | Detected and flagged for manual conversion |
+
+---
+
+## Warning
+
+> **encoding-doctor modifies files in-place.**
+>
+> - Always run `scan` first and review the report before running `fix`.
+> - Backups are created automatically as `.bak` files.
+> - Run on a Git-tracked project so you can always revert with `git checkout .`
+> - Do not run `fix` on production files without testing first.
+> - `verify` after every fix before committing.
+
+---
+
+## Options
+
+```bash
+enc-doctor scan   <path> [--all]       # --all shows clean files too
+enc-doctor fix    <path> [--dry-run]   # --dry-run previews without writing
+enc-doctor verify <path>
+enc-doctor restore <file>              # restore single file from .bak
+```
+
+---
+
+## Run tests
+
+```bash
+pip install pytest
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT © [Stateflow Labs](https://github.com/stateflow-dev)

encoding_doctor-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+encoding_doctor/__init__.py,sha256=fiW5ZlN8xXzfS3i-nxOeZBkgKmYK47kkh7sxfOmqHOM,443
+encoding_doctor/cli.py,sha256=J2Ae2M5mOcn5X8Bl813WbyK_ZB5eAipKVWjZZggWZTY,7026
+encoding_doctor/fixer.py,sha256=PAGb0oYuPqfoyQT8zKaBBFW26jB-bvSWYVASmaYgaIQ,2314
+encoding_doctor/license.py,sha256=w8_sXfecpQXH_YhyfksqwZDXabQWDSjBkm6sFqLHCnU,7369
+encoding_doctor/reporter.py,sha256=_16iToFSUGSr6oZSd-CRDYxScz6Z-rlfLvinunrSYZE,3409
+encoding_doctor/scanner.py,sha256=D67IY6QgInRw1s2aGBwGzDBBVOM6qgiOuim6-I5NhSo,4170
+encoding_doctor/verifier.py,sha256=e2wsVnNzbUY7oDDS1pSj76frGjpph4hswDfLVmMbNYs,1885
+encoding_doctor-0.2.0.dist-info/METADATA,sha256=-4EOOPa8a7ZlAvODn6lcS745MEfegYg14kbhIcz4mY0,3211
+encoding_doctor-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+encoding_doctor-0.2.0.dist-info/entry_points.txt,sha256=O6xaVIl9Yj2yMlwNwSEYaG5yWK_HXDizwev5z3xzbfA,56
+encoding_doctor-0.2.0.dist-info/top_level.txt,sha256=vz2QN3W3Vl13Zc3BZqLUDGFPlXTdO3IEZ3RlwTPxopQ,16
+encoding_doctor-0.2.0.dist-info/RECORD,,

encoding_doctor-0.2.0.dist-info/WHEEL

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

encoding_doctor-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+enc-doctor = encoding_doctor.cli:main

encoding_doctor-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+encoding_doctor