# 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.