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

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:]))

crackerjack/tools/trailing_whitespace.py

@@ -0,0 +1,198 @@
+"""Remove trailing whitespace from files.
+
+This tool is a native Python implementation replacing pre-commit's
+trailing-whitespace hook. It scans files for lines with trailing whitespace
+and automatically removes it.
+
+Usage:
+    python -m crackerjack.tools.trailing_whitespace [files...]
+
+Exit Codes:
+    0: No trailing whitespace found (or successfully fixed)
+    1: Trailing whitespace found and fixed (files modified)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ._git_utils import get_files_by_extension
+
+
+def has_trailing_whitespace(line: str) -> bool:
+    """Check if a line has trailing whitespace.
+
+    Args:
+        line: Line to check (should include newline if present)
+
+    Returns:
+        True if line has trailing whitespace before newline
+    """
+    # Remove trailing newline for checking
+    line_stripped = line.rstrip("\n\r")
+    # Check if there's whitespace at the end
+    return line_stripped != line_stripped.rstrip()
+
+
+def fix_trailing_whitespace(file_path: Path) -> bool:
+    """Remove trailing whitespace from a file.
+
+    Args:
+        file_path: Path to file to process
+
+    Returns:
+        True if file was modified, False if no changes needed
+    """
+    try:
+        # Read file content
+        content = file_path.read_text(encoding="utf-8")
+        lines = content.splitlines(keepends=True)
+
+        # Process lines
+        modified = False
+        new_lines = []
+        for line in lines:
+            if has_trailing_whitespace(line):
+                # Remove trailing whitespace but preserve newline
+                stripped = line.rstrip()
+                if line.endswith("\n"):
+                    stripped += "\n"
+                elif line.endswith("\r\n"):
+                    stripped += "\r\n"
+                new_lines.append(stripped)
+                modified = True
+            else:
+                new_lines.append(line)
+
+        # Write back if modified
+        if modified:
+            file_path.write_text("".join(new_lines), encoding="utf-8")
+            print(f"Fixed trailing whitespace: {file_path}")  # noqa: T201
+
+        return modified
+
+    except UnicodeDecodeError:
+        # Skip binary files
+        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 trailing whitespace.
+
+    Args:
+        args: Parsed command-line arguments
+
+    Returns:
+        List of file paths to process
+    """
+    # Default to all git-tracked 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 trailing whitespace
+    """
+    modified_count = 0
+    for file_path in files:
+        content = file_path.read_text(encoding="utf-8")
+        lines = content.splitlines(keepends=True)
+        if any(has_trailing_whitespace(line) for line in lines):
+            print(f"Trailing whitespace found: {file_path}")  # noqa: T201
+            modified_count += 1
+    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:
+        if fix_trailing_whitespace(file_path):
+            modified_count += 1
+    return modified_count
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point for trailing-whitespace 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="Remove trailing whitespace from files"
+    )
+    parser.add_argument(
+        "files",
+        nargs="*",
+        type=Path,
+        help="Files to check (default: all Python 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 trailing whitespace")  # noqa: T201
+        else:
+            print(f"\nFixed {modified_count} file(s)")  # noqa: T201
+            # Align with pre-commit semantics so HookExecutor treats this as pass
+            # when a formatter modifies files but exits with code 1.
+            print("files were modified by this hook")  # noqa: T201
+        return 1
+
+    print("No trailing whitespace found")  # noqa: T201
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

crackerjack/tools/validate_regex_patterns.py

@@ -145,6 +145,10 @@ def validate_file(file_path: Path) -> list[tuple[int, str]]:
 
 
 def main(file_paths: list[str]) -> int:
+    if not file_paths:
+        print("✅ No Python files to validate")
+        return 0
+
     exit_code = 0
 
     for file_path_str in file_paths:
@@ -167,15 +171,15 @@ def main(file_paths: list[str]) -> int:
     if exit_code == 0:
         print("✅ All regex patterns validated successfully!")
     else:
-        print("\n" + "=" * 74)
+        print("\n" + "=" * 70)
         print("REGEX VALIDATION FAILED")
-        print("=" * 74)
+        print("=" * 70)
         print("To fix these issues: ")
         print("1. Use patterns from crackerjack.services.regex_patterns")
         print("2. Add new patterns to SAFE_PATTERNS with comprehensive tests")
         print("3. Use '# REGEX OK: reason' comment for legitimate exceptions")
         print("4. Fix \\g<1> replacement syntax (no spaces)")
-        print("=" * 74)
+        print("=" * 70)
 
     return exit_code
 

crackerjack/ui/README.md

@@ -0,0 +1,11 @@
+> Crackerjack Docs: [Main](<../../README.md>) | [Crackerjack Package](<../README.md>) | [UI](<./README.md>)
+
+# UI
+
+User interface components and templates.
+
+## Related
+
+- [Crackerjack Package](<../README.md>) - Parent package
+- [UI Templates](<./templates/README.md>) - Template files for UI components
+- [MCP](<../mcp/README.md>) - MCP progress monitor UI

crackerjack/ui/dashboard_renderer.py

@@ -0,0 +1,28 @@
+"""Utilities for rendering the monitoring dashboard UI."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+_TEMPLATE_DIR = Path(__file__).with_suffix("").parent / "templates"
+
+
+def _load_asset(filename: str) -> str:
+    path = _TEMPLATE_DIR / filename
+    if not path.exists():
+        msg = f"Dashboard asset not found: {filename}"
+        raise FileNotFoundError(msg)
+    return path.read_text(encoding="utf-8")
+
+
+@lru_cache(maxsize=1)
+def render_monitoring_dashboard() -> str:
+    """Render the monitoring dashboard HTML using cached assets."""
+    html_template = _load_asset("monitoring_dashboard.html")
+    css_styles = _load_asset("monitoring_dashboard.css")
+    javascript_code = _load_asset("monitoring_dashboard.js")
+    return html_template.format(
+        css_styles=css_styles,
+        javascript_code=javascript_code,
+    )

crackerjack/ui/templates/README.md

@@ -0,0 +1,11 @@
+> Crackerjack Docs: [Main](<../../../README.md>) | [Crackerjack Package](<../../README.md>) | [UI](<../README.md>) | [Templates](<./README.md>)
+
+# UI Templates
+
+Templates used by UI components.
+
+## Related
+
+- [UI](<../README.md>) - Parent UI package
+- [Crackerjack Package](<../../README.md>) - Root package
+- [Data](<../../data/README.md>) - Static data and assets

crackerjack/utils/console_utils.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from crackerjack.config import get_console_width
+
+
+def separator(char: str = "-", width: int | None = None) -> str:
+    """Return a horizontal separator string.
+
+    - char: the character to repeat (default '-')
+    - width: explicit width; if None, uses configured console width
+    """
+    w = width if isinstance(width, int) and width > 0 else get_console_width()
+    return char * w

crackerjack/utils/dependency_guard.py

@@ -0,0 +1,230 @@
+"""
+Dependency Guard module to ensure proper dependency injection.
+
+This module provides utilities to ensure that dependencies are properly
+registered in the ACB dependency injection system and to handle cases
+where dependencies might be registered as empty tuples or other invalid
+values.
+"""
+
+import sys
+import typing
+from typing import Any
+
+from acb.depends import depends
+from acb.logger import Logger
+
+
+def _should_log_debug() -> bool:
+    """Check if debug mode is active via CLI flags.
+
+    Uses sys.argv directly for early detection before flag parsing.
+    This is thread-safe as sys.argv is read-only during execution.
+    """
+    return any(
+        arg in ("--debug", "-d", "--ai-debug") or arg.startswith("--debug=")
+        for arg in sys.argv[1:]
+    )
+
+
+def _log_dependency_issue(message: str, level: str = "WARNING") -> None:
+    """Log dependency issues only in debug mode.
+
+    Args:
+        message: The log message to emit
+        level: Log level (INFO, WARNING, ERROR)
+    """
+    if not _should_log_debug():
+        return
+    # Use stderr for diagnostic messages (stdout reserved for user output)
+    print(f"[CRACKERJACK:{level}] {message}", file=sys.stderr)
+
+
+def ensure_logger_dependency() -> None:
+    """
+    Ensure that Logger and LoggerProtocol are properly registered in the DI container.
+    This prevents issues where empty tuples might get registered instead of logger instances.
+    """
+    # Check if Logger is registered and has a valid instance
+    try:
+        logger_instance = depends.get_sync(Logger)
+        # If we get an empty tuple, string, or other invalid value, replace it
+        if isinstance(logger_instance, tuple) and len(logger_instance) == 0:
+            _log_dependency_issue(
+                "Logger dependency was registered as empty tuple, replacing with fresh instance"
+            )
+            # Create a new logger instance to replace the invalid one
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            depends.set(Logger, fresh_logger)
+        elif isinstance(logger_instance, str):
+            _log_dependency_issue(
+                f"Logger dependency was registered as string ({logger_instance!r}), replacing with fresh instance"
+            )
+            # Create a new logger instance to replace the invalid one
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            depends.set(Logger, fresh_logger)
+    except Exception:
+        # If there's no logger registered at all, create one
+        from acb.logger import Logger as ACBLogger
+
+        fresh_logger = ACBLogger()
+        depends.set(Logger, fresh_logger)
+
+    # Do the same check for LoggerProtocol if it exists
+    # Import once to avoid typing issues
+    try:
+        from crackerjack.models.protocols import LoggerProtocol as _LoggerProtocol
+
+        logger_proto_instance = depends.get_sync(_LoggerProtocol)
+        if isinstance(logger_proto_instance, tuple) and len(logger_proto_instance) == 0:
+            _log_dependency_issue(
+                "LoggerProtocol dependency was registered as empty tuple, replacing with fresh instance"
+            )
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            depends.set(_LoggerProtocol, fresh_logger)
+        elif isinstance(logger_proto_instance, str):
+            _log_dependency_issue(
+                f"LoggerProtocol dependency was registered as string ({logger_proto_instance!r}), replacing with fresh instance"
+            )
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            depends.set(_LoggerProtocol, fresh_logger)
+    except ImportError:
+        # LoggerProtocol doesn't exist, that's fine
+        pass
+    except Exception:
+        # If there's no LoggerProtocol registered, create one
+        try:
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            _log_dependency_issue(
+                "Registering LoggerProtocol with fresh logger instance", level="INFO"
+            )
+            # Register the fresh_logger instance with the LoggerProtocol
+            depends.set(_LoggerProtocol, fresh_logger)
+        except NameError:
+            # _LoggerProtocol is not defined if the import failed
+            pass
+        except Exception:
+            pass  # Any other error, just continue
+
+
+def validate_dependency_registration(
+    dep_type: type[Any], fallback_factory: typing.Callable | None = None
+) -> bool:
+    """
+    Validate that a dependency is properly registered and not an empty tuple or string.
+
+    Args:
+        dep_type: The type of dependency to validate
+        fallback_factory: Optional factory function to create a fallback instance if needed
+
+    Returns:
+        True if the dependency is properly registered, False otherwise
+    """
+    try:
+        instance = depends.get_sync(dep_type)
+        # Check if it's an empty tuple (the problematic case)
+        if isinstance(instance, tuple) and len(instance) == 0:
+            _log_dependency_issue(
+                f"Dependency {dep_type} was registered as empty tuple"
+            )
+            # Replace with a fallback if provided
+            if fallback_factory:
+                fallback_instance = fallback_factory()
+                depends.set(dep_type, fallback_instance)
+                _log_dependency_issue(
+                    f"Replaced empty tuple for {dep_type} with new instance",
+                    level="INFO",
+                )
+                return True
+            return False
+        # Check if it's a string (another problematic case)
+        elif isinstance(instance, str):
+            _log_dependency_issue(
+                f"Dependency {dep_type} was registered as string: {instance!r}"
+            )
+            # Replace with a fallback if provided
+            if fallback_factory:
+                fallback_instance = fallback_factory()
+                depends.set(dep_type, fallback_instance)
+                _log_dependency_issue(
+                    f"Replaced string for {dep_type} with new instance", level="INFO"
+                )
+                return True
+            return False
+        return True
+    except Exception:
+        # If dependency doesn't exist at all, return False
+        return False
+
+
+def safe_get_logger() -> Logger:
+    """
+    Safely get a logger instance, ensuring it's not an empty tuple or string.
+
+    Returns:
+        A valid logger instance
+    """
+    try:
+        logger_instance = depends.get_sync(Logger)
+        if isinstance(logger_instance, tuple) and len(logger_instance) == 0:
+            _log_dependency_issue(
+                "Logger dependency was an empty tuple in safe_get_logger, replacing with fresh instance"
+            )
+            # Create and register a fresh logger
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            depends.set(Logger, fresh_logger)
+            return fresh_logger
+        elif isinstance(logger_instance, str):
+            _log_dependency_issue(
+                f"Logger dependency was a string ({logger_instance!r}) in safe_get_logger, replacing with fresh instance"
+            )
+            # Create and register a fresh logger
+            from acb.logger import Logger as ACBLogger
+
+            fresh_logger = ACBLogger()
+            depends.set(Logger, fresh_logger)
+            return fresh_logger
+        return logger_instance
+    except Exception:
+        # If no logger is registered, create one
+        from acb.logger import Logger as ACBLogger
+
+        _log_dependency_issue(
+            "No logger registered, creating and registering a fresh logger instance",
+            level="INFO",
+        )
+        fresh_logger = ACBLogger()
+        depends.set(Logger, fresh_logger)
+        return fresh_logger
+
+
+def check_all_dependencies_for_empty_tuples():
+    """
+    Debug function to check all registered dependencies for empty tuples.
+    This can help identify which dependencies have been incorrectly registered.
+    """
+    # This would require access to the internal state of the ACB DI system
+    # which might not be available, so we'll just print a notice
+    _log_dependency_issue(
+        "Dependency check: To check all dependencies for empty tuples, you would need access to ACB's internal container state.",
+        level="INFO",
+    )
+    _log_dependency_issue(
+        "This is currently not possible without modifying ACB itself.", level="INFO"
+    )
+    _log_dependency_issue(
+        "The best approach is to use the individual validation functions for known problematic dependencies.",
+        level="INFO",
+    )