chore: Issue closure 125 cleanup

capabilities/markitect-utils/README.md

@@ -0,0 +1,236 @@
+# MarkiTect Utils Capability
+
+A self-contained capability providing common utility functions for the MarkiTect ecosystem.
+
+## Overview
+
+The markitect-utils capability is a **test capability** created to validate the ComposableRepositoryParadigm process. It provides a collection of commonly used utility functions that can be shared across different MarkiTect capabilities and projects, while serving as a reference implementation for the paradigm.
+
+## Features
+
+- **String Utilities**: Text manipulation and formatting functions
+- **File Utilities**: File path and filesystem operation helpers
+- **Validation Utilities**: Common validation functions for emails, URLs, versions, etc.
+- **Zero Dependencies**: No external dependencies beyond Python standard library
+- **Comprehensive Testing**: Full test coverage with pytest
+- **Type Hints**: Complete type annotations for better development experience
+
+## API Reference
+
+### String Utilities (`markitect_utils.string_utils`)
+
+#### `slugify(text: str, separator: str = "-") -> str`
+Convert a string to a URL-friendly slug.
+
+```python
+from markitect_utils import slugify
+
+slug = slugify("Hello World!")  # Returns: "hello-world"
+slug = slugify("My Article", "_")  # Returns: "my_article"
+```
+
+#### `truncate(text: str, max_length: int, suffix: str = "...") -> str`
+Truncate a string to a maximum length with optional suffix.
+
+```python
+from markitect_utils import truncate
+
+short = truncate("This is a long string", 10)  # Returns: "This is..."
+```
+
+#### `camel_to_snake(text: str) -> str`
+Convert camelCase or PascalCase to snake_case.
+
+```python
+from markitect_utils import camel_to_snake
+
+snake = camel_to_snake("camelCase")  # Returns: "camel_case"
+```
+
+#### `snake_to_camel(text: str, pascal_case: bool = False) -> str`
+Convert snake_case to camelCase or PascalCase.
+
+```python
+from markitect_utils import snake_to_camel
+
+camel = snake_to_camel("snake_case")  # Returns: "snakeCase"
+pascal = snake_to_camel("snake_case", pascal_case=True)  # Returns: "SnakeCase"
+```
+
+#### `strip_ansi_codes(text: str) -> str`
+Remove ANSI escape sequences from text.
+
+```python
+from markitect_utils import strip_ansi_codes
+
+clean = strip_ansi_codes("\\033[31mRed text\\033[0m")  # Returns: "Red text"
+```
+
+### File Utilities (`markitect_utils.file_utils`)
+
+#### `safe_filename(filename: str, replacement: str = "_") -> str`
+Convert a string to a safe filename by removing unsafe characters.
+
+```python
+from markitect_utils import safe_filename
+
+safe = safe_filename("file<name>.txt")  # Returns: "file_name_.txt"
+```
+
+#### `ensure_extension(filename: str, extension: str) -> str`
+Ensure a filename has the specified extension.
+
+```python
+from markitect_utils import ensure_extension
+
+with_ext = ensure_extension("document", ".md")  # Returns: "document.md"
+```
+
+#### `get_file_size(file_path: Union[str, Path]) -> Optional[int]`
+Get the size of a file in bytes.
+
+```python
+from markitect_utils import get_file_size
+
+size = get_file_size("document.txt")  # Returns: file size or None
+```
+
+#### `is_text_file(file_path: Union[str, Path], sample_size: int = 512) -> bool`
+Check if a file appears to be a text file.
+
+```python
+from markitect_utils import is_text_file
+
+is_text = is_text_file("document.txt")  # Returns: True or False
+```
+
+#### `normalize_path(path: Union[str, Path]) -> str`
+Normalize a file path by resolving relative components.
+
+```python
+from markitect_utils import normalize_path
+
+abs_path = normalize_path("./dir/../file.txt")  # Returns: absolute path
+```
+
+### Validation Utilities (`markitect_utils.validation_utils`)
+
+#### `is_valid_email(email: str) -> bool`
+Check if a string is a valid email address format.
+
+```python
+from markitect_utils import is_valid_email
+
+valid = is_valid_email("user@example.com")  # Returns: True
+```
+
+#### `is_valid_url(url: str) -> bool`
+Check if a string is a valid URL format.
+
+```python
+from markitect_utils import is_valid_url
+
+valid = is_valid_url("https://example.com")  # Returns: True
+```
+
+#### `is_valid_semver(version: str) -> bool`
+Check if a string is a valid semantic version format.
+
+```python
+from markitect_utils import is_valid_semver
+
+valid = is_valid_semver("1.0.0")  # Returns: True
+valid = is_valid_semver("1.0.0-alpha.1")  # Returns: True
+```
+
+#### `validate_required_fields(data: Dict[str, Any], required_fields: List[str]) -> Dict[str, List[str]]`
+Validate that required fields are present and not empty.
+
+```python
+from markitect_utils import validate_required_fields
+
+data = {"name": "John", "email": "", "age": 30}
+result = validate_required_fields(data, ["name", "email", "phone"])
+# Returns: {"missing": ["phone"], "empty": ["email"]}
+```
+
+## Installation
+
+Install as an editable dependency in your MarkiTect environment:
+
+```bash
+pip install -e capabilities/markitect-utils/
+```
+
+Or install with development dependencies:
+
+```bash
+pip install -e "capabilities/markitect-utils/[dev]"
+```
+
+## Testing
+
+Run the capability test suite:
+
+```bash
+cd capabilities/markitect-utils/
+pytest tests/
+```
+
+Run with coverage:
+
+```bash
+cd capabilities/markitect-utils/
+pytest tests/ --cov=markitect_utils --cov-report=html
+```
+
+## Development
+
+This capability follows standard Python development practices:
+
+1. **Code Style**: Follow PEP 8 conventions
+2. **Type Hints**: All functions include complete type annotations
+3. **Documentation**: Comprehensive docstrings with examples
+4. **Testing**: Aim for 100% test coverage
+
+## ComposableRepositoryParadigm Compliance
+
+This capability serves as a reference implementation and demonstrates compliance with the ComposableRepositoryParadigm:
+
+### ✅ Structure Requirements
+- **Src Layout**: Uses PEP 660 compliant `src/` directory structure
+- **Consistent Testing**: pytest configuration matches main project
+- **Independent Configuration**: Self-contained `pyproject.toml`
+- **Documentation**: Complete README with API documentation
+
+### ✅ Dependency Management
+- **Unidirectional Dependencies**: No imports from parent MarkiTect project
+- **External Dependencies**: Minimal external dependencies (none in this case)
+- **Self-Contained**: Can be developed and tested independently
+
+### ✅ Quality Standards
+- **Type Safety**: Complete type annotations with mypy configuration
+- **Test Coverage**: Comprehensive test suite with unit and integration tests
+- **Documentation**: Detailed API documentation with examples
+- **Version Management**: Semantic versioning starting at 0.1.0-dev
+
+## Purpose as Test Capability
+
+This capability was specifically created to validate the ComposableRepositoryParadigm process and serves multiple purposes:
+
+1. **Process Validation**: Tests the capability creation workflow
+2. **Structure Template**: Provides a reference for future capabilities
+3. **Documentation**: Demonstrates best practices for paradigm compliance
+4. **Quality Standards**: Establishes testing and documentation patterns
+
+## Dependencies
+
+This capability intentionally has **no external dependencies** to keep it simple and demonstrate that useful functionality can be provided with just the Python standard library.
+
+Development dependencies:
+- `pytest>=7.0.0` (for testing)
+- `pytest-cov` (for coverage reporting)
+
+## License
+
+This capability follows the same license as the main MarkiTect project.