crackerjack 0.18.2__py3-none-any.whl → 0.45.2__py3-none-any.whl

crackerjack/tools/check_yaml.py

@@ -0,0 +1,110 @@
+"""Validate YAML file syntax.
+
+This tool is a native Python implementation replacing pre-commit's
+check-yaml hook. It scans YAML files and validates their syntax.
+
+Usage:
+    python -m crackerjack.tools.check_yaml [files...]
+
+Exit Codes:
+    0: All YAML files are valid
+    1: One or more YAML files have syntax errors
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import yaml
+
+from ._git_utils import get_files_by_extension
+
+
+def validate_yaml_file(file_path: Path) -> tuple[bool, str | None]:
+    """Validate a YAML file's syntax.
+
+    Args:
+        file_path: Path to YAML file to validate
+
+    Returns:
+        Tuple of (is_valid, error_message)
+        - is_valid: True if file has valid YAML syntax
+        - error_message: Error description if is_valid is False, None otherwise
+    """
+    try:
+        with file_path.open(encoding="utf-8") as f:
+            # Load YAML and validate structure
+            yaml.safe_load(f)
+        return True, None
+    except yaml.YAMLError as e:
+        return False, str(e)
+    except Exception as e:
+        return False, f"Error reading file: {e}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point for check-yaml tool.
+
+    Args:
+        argv: Command-line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code: 0 if all YAML valid, 1 if any errors found
+    """
+    parser = argparse.ArgumentParser(description="Validate YAML file syntax")
+    parser.add_argument(
+        "files",
+        nargs="*",
+        type=Path,
+        help="YAML files to check (default: all .yaml/.yml files)",
+    )
+    parser.add_argument(
+        "--unsafe",
+        action="store_true",
+        help="Use unsafe YAML loader (allows Python object instantiation)",
+    )
+
+    args = parser.parse_args(argv)
+
+    # Default to all git-tracked YAML files if none specified
+    if not args.files:
+        # Get all tracked YAML files (respects .gitignore via git ls-files)
+        files = get_files_by_extension([".yaml", ".yml"])
+        if not files:
+            # Fallback to rglob if not in git repo
+            files = list(Path.cwd().rglob("*.yaml"))
+            files.extend(Path.cwd().rglob("*.yml"))
+    else:
+        files = args.files
+
+    # Filter to existing files only
+    files = [f for f in files if f.is_file()]
+
+    if not files:
+        print("No YAML files to check")  # noqa: T201
+        return 0
+
+    # Process files
+    error_count = 0
+    for file_path in files:
+        is_valid, error_msg = validate_yaml_file(file_path)
+
+        if not is_valid:
+            print(f"✗ {file_path}: {error_msg}", file=sys.stderr)  # noqa: T201
+            error_count += 1
+        else:
+            print(f"✓ {file_path}: Valid YAML")  # noqa: T201
+
+    # Return appropriate exit code
+    if error_count > 0:
+        print(f"\n{error_count} YAML file(s) with errors", file=sys.stderr)  # noqa: T201
+        return 1
+
+    print(f"\nAll {len(files)} YAML file(s) are valid")  # noqa: T201
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

crackerjack/tools/codespell_wrapper.py

@@ -0,0 +1,72 @@
+"""Git-aware wrapper for codespell.
+
+This wrapper ensures codespell only checks git-tracked files, automatically
+respecting .gitignore patterns without needing manual skip configuration.
+
+Usage:
+    python -m crackerjack.tools.codespell_wrapper [codespell args...]
+
+Exit Codes:
+    Same as codespell (0 = no issues, 1 = issues found, etc.)
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from ._git_utils import get_git_tracked_files
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run codespell on git-tracked files only.
+
+    This wrapper automatically discovers git-tracked files and passes them
+    to codespell, ensuring .gitignore patterns are respected without manual
+    skip configuration.
+
+    Args:
+        argv: Optional arguments to pass to codespell
+
+    Returns:
+        Exit code from codespell command
+    """
+    # Get all git-tracked files (automatically respects .gitignore)
+    files = get_git_tracked_files()
+
+    if not files:
+        print("No git-tracked files found", file=sys.stderr)  # noqa: T201
+        return 1
+
+    # Build codespell command with git-tracked files
+    cmd = ["codespell"]
+
+    # Add any additional arguments passed to wrapper
+    if argv:
+        cmd.extend(argv)
+
+    # Add file paths at the end
+    cmd.extend([str(f) for f in files])
+
+    # Execute codespell
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=Path.cwd(),
+            check=False,  # Don't raise on non-zero exit (codespell returns 1 for issues found)
+        )
+        return result.returncode
+    except FileNotFoundError:
+        print(
+            "Error: codespell not found. Install with: uv pip install codespell",
+            file=sys.stderr,
+        )  # noqa: T201
+        return 127  # Command not found
+    except Exception as e:
+        print(f"Error running codespell: {e}", file=sys.stderr)  # noqa: T201
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

crackerjack/tools/end_of_file_fixer.py

@@ -0,0 +1,202 @@
+"""Ensure files end with a newline.
+
+This tool is a native Python implementation replacing pre-commit's
+end-of-file-fixer hook. It scans files and ensures they end with exactly
+one newline character.
+
+Usage:
+    python -m crackerjack.tools.end_of_file_fixer [files...]
+
+Exit Codes:
+    0: All files end with newline (or successfully fixed)
+    1: Files were modified to add/fix ending newline
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ._git_utils import get_files_by_extension
+
+
+def needs_newline_fix(content: bytes) -> tuple[bool, bytes | None]:
+    """Check if file needs newline added or fixed.
+
+    Args:
+        content: File content as bytes
+
+    Returns:
+        Tuple of (needs_fix, fixed_content)
+        - needs_fix: True if file needs modification
+        - fixed_content: Fixed content if needs_fix is True, None otherwise
+    """
+    if not content:
+        # Empty file doesn't need newline
+        return False, None
+
+    # Check if file ends with newline
+    if content.endswith(b"\n"):
+        # Check for multiple trailing newlines
+        stripped = content.rstrip(b"\n")
+        if len(content) - len(stripped) > 1:
+            # Multiple trailing newlines, fix to exactly one
+            return True, stripped + b"\n"
+        # Exactly one newline, no fix needed
+        return False, None
+
+    # No trailing newline, add one
+    return True, content + b"\n"
+
+
+def fix_end_of_file(file_path: Path) -> bool:
+    """Ensure file ends with exactly one newline.
+
+    Args:
+        file_path: Path to file to process
+
+    Returns:
+        True if file was modified, False if no changes needed
+    """
+    try:
+        # Read file content as bytes to preserve encoding
+        content = file_path.read_bytes()
+
+        # Check if fix is needed
+        needs_fix, fixed_content = needs_newline_fix(content)
+
+        if needs_fix and fixed_content is not None:
+            # Write fixed content
+            file_path.write_bytes(fixed_content)
+            print(f"Fixed end-of-file: {file_path}")  # noqa: T201
+            return True
+
+        return False
+
+    except Exception as e:
+        print(f"Error processing {file_path}: {e}", file=sys.stderr)  # noqa: T201
+        return False
+
+
+def _collect_files_to_check(args: argparse.Namespace) -> list[Path]:
+    """Collect files to check for end-of-file issues.
+
+    Args:
+        args: Parsed command-line arguments
+
+    Returns:
+        List of file paths to process
+    """
+    # Default to all git-tracked text files if none specified
+    if not args.files:
+        # Get all tracked text files (respects .gitignore via git ls-files)
+        files = get_files_by_extension(
+            [".py", ".md", ".txt", ".yaml", ".yml", ".toml", ".json"]
+        )
+        if not files:
+            # Fallback to Python files if not in git repo
+            files = list(Path.cwd().rglob("*.py"))
+    else:
+        files = args.files
+
+    # Filter to existing files only
+    return [f for f in files if f.is_file()]
+
+
+def _process_files_in_check_mode(files: list[Path]) -> int:
+    """Process files in check-only mode.
+
+    Args:
+        files: List of file paths to check
+
+    Returns:
+        Count of files with end-of-file issues
+    """
+    modified_count = 0
+    for file_path in files:
+        try:
+            content = file_path.read_bytes()
+            needs_fix, _ = needs_newline_fix(content)
+
+            if needs_fix:
+                print(f"Missing/incorrect end-of-file: {file_path}")  # noqa: T201
+                modified_count += 1
+        except Exception as e:
+            print(f"Error processing {file_path}: {e}", file=sys.stderr)  # noqa: T201
+    return modified_count
+
+
+def _process_files_in_fix_mode(files: list[Path]) -> int:
+    """Process files in fix mode.
+
+    Args:
+        files: List of file paths to fix
+
+    Returns:
+        Count of files modified
+    """
+    modified_count = 0
+    for file_path in files:
+        try:
+            if fix_end_of_file(file_path):
+                modified_count += 1
+        except Exception as e:
+            print(f"Error processing {file_path}: {e}", file=sys.stderr)  # noqa: T201
+    return modified_count
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point for end-of-file-fixer tool.
+
+    Args:
+        argv: Command-line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code: 0 if no files modified, 1 if files were modified
+    """
+    parser = argparse.ArgumentParser(
+        description="Ensure files end with exactly one newline"
+    )
+    parser.add_argument(
+        "files",
+        nargs="*",
+        type=Path,
+        help="Files to check (default: all text files in current directory)",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Check only, don't modify files",
+    )
+
+    args = parser.parse_args(argv)
+
+    files = _collect_files_to_check(args)
+
+    if not files:
+        print("No files to check")  # noqa: T201
+        return 0
+
+    # Process files based on mode
+    if args.check:
+        modified_count = _process_files_in_check_mode(files)
+    else:
+        modified_count = _process_files_in_fix_mode(files)
+
+    # Return appropriate exit code
+    if modified_count > 0:
+        if args.check:
+            print(f"\n{modified_count} file(s) with incorrect end-of-file")  # noqa: T201
+        else:
+            print(f"\nFixed {modified_count} file(s)")  # noqa: T201
+            # Align with pre-commit semantics so HookExecutor treats this as pass
+            print("files were modified by this hook")  # noqa: T201
+        return 1
+
+    print("All files end with correct newline")  # noqa: T201
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

crackerjack/tools/format_json.py

@@ -0,0 +1,128 @@
+"""Format JSON files to ensure consistent style.
+
+This tool is a native Python implementation for formatting JSON files
+to ensure consistent indentation and style. It reads JSON files and
+writes them back with standardized formatting.
+
+Usage:
+    python -m crackerjack.tools.format_json [files...]
+
+Exit Codes:
+    0: All JSON files formatted successfully
+    1: One or more JSON files have syntax errors or could not be formatted
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ._git_utils import get_files_by_extension
+
+
+def format_json_file(file_path: Path) -> tuple[bool, str | None]:
+    """Format a JSON file to ensure consistent style.
+
+    Args:
+        file_path: Path to JSON file to format
+
+    Returns:
+        Tuple of (is_success, error_message)
+        - is_success: True if file was formatted successfully
+        - error_message: Error description if is_success is False, None otherwise
+    """
+    try:
+        # Read the file content
+        with file_path.open(encoding="utf-8") as f:
+            content = f.read().strip()
+            if not content:
+                return True, "File is empty, nothing to format"
+
+        # Parse the JSON
+        data = json.loads(content)
+
+        # Format with consistent indentation
+        formatted_content = json.dumps(
+            data, indent=2, ensure_ascii=False, sort_keys=True
+        )
+
+        # Add a newline at the end to match common formatting practices
+        formatted_content += "\n"
+
+        # Write the formatted content back to the file
+        with file_path.open("w", encoding="utf-8") as f:
+            f.write(formatted_content)
+
+        return True, None
+
+    except json.JSONDecodeError as e:
+        return False, f"Invalid JSON syntax: {e}"
+    except Exception as e:
+        return False, f"Error formatting file: {e}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point for format-json tool.
+
+    Args:
+        argv: Command-line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code: 0 if all JSON files formatted successfully, 1 if any errors
+    """
+    parser = argparse.ArgumentParser(
+        description="Format JSON files to ensure consistent style"
+    )
+    parser.add_argument(
+        "files",
+        nargs="*",
+        type=Path,
+        help="JSON files to format (default: all .json files)",
+    )
+
+    args = parser.parse_args(argv)
+
+    # Default to all git-tracked JSON files if none specified
+    if not args.files:
+        # Get all tracked JSON files (respects .gitignore via git ls-files)
+        files = get_files_by_extension([".json"])
+        if not files:
+            # Fallback to rglob if not in git repo
+            files = list(Path.cwd().rglob("*.json"))
+    else:
+        files = args.files
+
+    # Filter to existing files only
+    files = [f for f in files if f.is_file()]
+
+    if not files:
+        print("No JSON files to format")  # noqa: T201
+        return 0
+
+    # Process files
+    error_count = 0
+    for file_path in files:
+        is_success, error_msg = format_json_file(file_path)
+
+        if not is_success:
+            print(f"✗ {file_path}: {error_msg}", file=sys.stderr)  # noqa: T201
+            error_count += 1
+        else:
+            if error_msg:  # File was empty
+                print(f"→ {file_path}: {error_msg}")  # noqa: T201
+            else:
+                print(f"✓ {file_path}: Formatted successfully")  # noqa: T201
+
+    # Return appropriate exit code
+    if error_count > 0:
+        print(f"\n{error_count} JSON file(s) failed to format", file=sys.stderr)  # noqa: T201
+        return 1
+
+    print(f"\nAll {len(files)} JSON file(s) formatted successfully")  # noqa: T201
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

crackerjack/tools/mdformat_wrapper.py

@@ -0,0 +1,114 @@
+"""Git-aware wrapper for mdformat.
+
+This wrapper ensures mdformat only checks git-tracked markdown files,
+automatically respecting .gitignore patterns without needing manual skip
+configuration.
+
+Usage:
+    python -m crackerjack.tools.mdformat_wrapper [mdformat args...]
+
+Exit Codes:
+    Same as mdformat (0 = no issues, 1 = issues found, etc.)
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from ._git_utils import get_git_tracked_files
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run mdformat on git-tracked markdown files only.
+
+    This wrapper automatically discovers git-tracked .md and .markdown files
+    and passes them to mdformat, ensuring .gitignore patterns are respected.
+
+    Behavior:
+    - First run: Formats files and returns exit code 1 (fail to signal changes)
+    - Second run: Files already formatted, returns exit code 0 (pass)
+
+    Args:
+        argv: Optional arguments to pass to mdformat
+
+    Returns:
+        Exit code: 0 if no changes needed, 1 if files were formatted
+    """
+    # Get all git-tracked markdown files (automatically respects .gitignore)
+    md_files = get_git_tracked_files("*.md")
+    markdown_files = get_git_tracked_files("*.markdown")
+    files = md_files + markdown_files
+
+    if not files:
+        print("No git-tracked markdown files found", file=sys.stderr)  # noqa: T201
+        return 0  # No files is not an error for formatters
+
+    # Build mdformat command with git-tracked files
+    cmd = ["mdformat"]
+
+    # Add any additional arguments passed to wrapper
+    if argv:
+        cmd.extend(argv)
+
+    # Add file paths at the end
+    cmd.extend([str(f) for f in files])
+
+    # Execute mdformat
+    try:
+        # First, check if files need formatting (dry-run)
+        check_cmd = cmd + ["--check"]
+        check_result = subprocess.run(
+            check_cmd,
+            cwd=Path.cwd(),
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+
+        # If check passed (exit code 0), files are already formatted
+        if check_result.returncode == 0:
+            print(f"All {len(files)} markdown files already formatted correctly")
+            return 0
+
+        # Files need formatting - run mdformat to fix them
+        format_result = subprocess.run(
+            cmd,
+            cwd=Path.cwd(),
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+
+        # Forward output to stdout/stderr
+        if format_result.stdout:
+            print(format_result.stdout, end="")
+        if format_result.stderr:
+            print(format_result.stderr, end="", file=sys.stderr)
+
+        # Return exit code 1 to indicate files were formatted (changes made)
+        # This causes the hook to fail on first run, pass on second run
+        files_formatted = (
+            check_result.returncode
+        )  # Non-zero means files needed formatting
+        if files_formatted:
+            print(
+                f"Formatted {len(files)} markdown files - run crackerjack again to verify"
+            )
+            return 1  # Fail to signal changes were made
+
+        return 0
+    except FileNotFoundError:
+        print(
+            "Error: mdformat not found. Install with: uv pip install mdformat mdformat-ruff",
+            file=sys.stderr,
+        )  # noqa: T201
+        return 127  # Command not found
+    except Exception as e:
+        print(f"Error running mdformat: {e}", file=sys.stderr)  # noqa: T201
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))