encoding-doctor 0.2.0__tar.gz

encoding_doctor-0.2.0/PKG-INFO

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

@@ -0,0 +1,84 @@
+# 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/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-0.2.0/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-0.2.0/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