coulomb/markitect-main
2
0
Fork 0
Code Issues 60 Pull Requests Actions 1 Projects 12 Releases 1 Wiki Activity
Files
965508ec0699482e792dcad7c19ced1071dd1d25
markitect-main/tests/test_schema_naming.py
tegwick 14108533fb feat: implement schema filename validation (Phase 1 complete) 
Implements filename convention enforcement for schema files as part of
the schema-of-schemas implementation. All schemas must now follow the
naming pattern: {domain}-schema-v{major}.{minor}.md

## Phase 1 Deliverables

### Schema Naming Module
**File:** `markitect/schema_naming.py` (380 lines)

**Functions:**
- `validate_schema_filename()` - Validate filename against pattern
- `suggest_schema_filename()` - Generate valid filename from domain/version
- `extract_schema_metadata()` - Extract domain and version from filename
- `get_validation_errors()` - Detailed error messages for invalid filenames
- `is_valid_schema_filename()` - Simple boolean validation
- `format_validation_message()` - User-friendly error formatting

**Features:**
- Regex-based pattern matching
- Automatic normalization (spaces → hyphens, lowercase)
- Detailed error reporting
- Domain validation (must start with letter)
- Version validation (major.minor format)

### Comprehensive Test Suite
**File:** `tests/test_schema_naming.py` (500+ lines, 50 tests)

**Test Coverage:**
- ✅ Valid filename variations (simple, hyphenated, with numbers)
- ✅ Invalid filenames (wrong extension, missing components, wrong case)
- ✅ Filename suggestion with normalization
- ✅ Metadata extraction
- ✅ Error message generation
- ✅ Edge cases (long names, many hyphens, large versions)
- ✅ Pattern regex validation

**Results:** 50/50 tests passing (100%)

### Specification Document
**File:** `roadmap/schema-of-schemas/SCHEMA_NAMING_SPEC.md`

**Contents:**
- Formal specification of naming convention
- Regular expression pattern with explanation
- Valid and invalid examples
- Version numbering guidelines
- Domain naming best practices
- Normalization rules
- Migration strategy from legacy naming
- Implementation guide

## Naming Convention

### Format
```
{domain}-schema-v{major}.{minor}.md
```

### Examples
```
✓ manpage-schema-v1.0.md
✓ api-documentation-schema-v1.0.md
✓ terminology-schema-v1.0.md
✓ arc42-schema-v2.1.md

✗ manpage.json (wrong extension)
✗ ManPage-schema-v1.0.md (uppercase)
✗ manpage-v1.0.md (missing 'schema')
✗ manpage-schema-v1.md (missing minor version)
```

### Components
- **domain**: Lowercase, hyphen-separated, starts with letter
- **schema**: Literal keyword
- **version**: v{major}.{minor} (SemVer simplified)
- **extension**: .md (markdown)

## Implementation Highlights

### Automatic Normalization
```python
suggest_schema_filename("API Documentation", "2.1")
# → "api-documentation-schema-v2.1.md"

suggest_schema_filename("My_Custom Type", "1.0")
# → "my-custom-type-schema-v1.0.md"
```

### Detailed Error Reporting
```python
format_validation_message("invalid.json")
# → Detailed error list + suggested fix
```

### Metadata Extraction
```python
extract_schema_metadata("manpage-schema-v1.0.md")
# → {'domain': 'manpage', 'version': '1.0', 'major': 1, 'minor': 0}
```

## Migration Plan

Current schemas will be renamed:
```
Old                           → New
────────────────────────────────────────────────────────
terminology-schema.json       → terminology-schema-v1.0.md
api-documentation             → api-documentation-schema-v1.0.md
enhanced-manpage              → manpage-schema-v2.0.md
markdown-manpage              → DELETE (duplicate)
markdown-manpage-schema.json  → DELETE (duplicate)
```

## Phase 1 Status: ✅ COMPLETE

### Completed
- [x] Schema naming module implementation
- [x] Comprehensive test suite (50 tests, 100% passing)
- [x] Specification document
- [x] TODO.md updated

### Next: Phase 2
- [ ] Update CLI schema-ingest with validation
- [ ] Implement markdown schema loader
- [ ] Parse frontmatter and JSON code blocks
- [ ] Update SchemaValidator for .md support

## Testing

```bash
# Run tests
pytest tests/test_schema_naming.py -v
# → 50 passed in 0.48s

# Test interactively
python -c "
from markitect.schema_naming import validate_schema_filename
print(validate_schema_filename('manpage-schema-v1.0.md'))
"
# → (True, {'domain': 'manpage', 'version': '1.0', ...})
```

## Files Changed

- markitect/schema_naming.py (NEW, 380 lines)
- tests/test_schema_naming.py (NEW, 500+ lines)
- roadmap/schema-of-schemas/SCHEMA_NAMING_SPEC.md (NEW)
- TODO.md (updated progress tracking)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-04 23:51:29 +01:00

391 lines
15 KiB
Python
Raw Blame History

"""
Unit tests for schema_naming.py - Schema filename validation.
Tests the schema naming convention enforcement including:
- Valid filename validation
- Invalid filename detection
- Metadata extraction
- Filename suggestion
- Error message generation
"""
import pytest
from markitect.schema_naming import (
validate_schema_filename,
suggest_schema_filename,
extract_schema_metadata,
get_validation_errors,
is_valid_schema_filename,
format_validation_message,
SchemaFilenameError,
SCHEMA_FILENAME_PATTERN
)
class TestValidateSchemaFilename:
"""Tests for validate_schema_filename function."""
def test_valid_simple_schema(self):
"""Test validation of simple valid schema filename."""
is_valid, metadata = validate_schema_filename("manpage-schema-v1.0.md")
assert is_valid is True
assert metadata is not None
assert metadata['domain'] == 'manpage'
assert metadata['version'] == '1.0'
assert metadata['major'] == 1
assert metadata['minor'] == 0
assert metadata['filename'] == 'manpage-schema-v1.0.md'
def test_valid_hyphenated_domain(self):
"""Test validation with multi-word hyphenated domain."""
is_valid, metadata = validate_schema_filename("api-documentation-schema-v1.0.md")
assert is_valid is True
assert metadata['domain'] == 'api-documentation'
assert metadata['version'] == '1.0'
def test_valid_with_numbers_in_domain(self):
"""Test validation with numbers in domain name."""
is_valid, metadata = validate_schema_filename("arc42-schema-v1.0.md")
assert is_valid is True
assert metadata['domain'] == 'arc42'
def test_valid_higher_version(self):
"""Test validation with version > 1.0."""
is_valid, metadata = validate_schema_filename("manpage-schema-v2.5.md")
assert is_valid is True
assert metadata['version'] == '2.5'
assert metadata['major'] == 2
assert metadata['minor'] == 5
def test_valid_double_digit_version(self):
"""Test validation with double-digit version numbers."""
is_valid, metadata = validate_schema_filename("manpage-schema-v10.25.md")
assert is_valid is True
assert metadata['major'] == 10
assert metadata['minor'] == 25
def test_invalid_wrong_extension(self):
"""Test that .json extension is invalid."""
is_valid, metadata = validate_schema_filename("manpage-schema-v1.0.json")
assert is_valid is False
assert metadata is None
def test_invalid_no_extension(self):
"""Test that filename without extension is invalid."""
is_valid, metadata = validate_schema_filename("manpage-schema-v1.0")
assert is_valid is False
assert metadata is None
def test_invalid_missing_schema_keyword(self):
"""Test that filename without 'schema' keyword is invalid."""
is_valid, metadata = validate_schema_filename("manpage-v1.0.md")
assert is_valid is False
assert metadata is None
def test_invalid_missing_version(self):
"""Test that filename without version is invalid."""
is_valid, metadata = validate_schema_filename("manpage-schema.md")
assert is_valid is False
assert metadata is None
def test_invalid_wrong_version_format(self):
"""Test that version without 'v' prefix is invalid."""
is_valid, metadata = validate_schema_filename("manpage-schema-1.0.md")
assert is_valid is False
assert metadata is None
def test_invalid_missing_minor_version(self):
"""Test that version without minor number is invalid."""
is_valid, metadata = validate_schema_filename("manpage-schema-v1.md")
assert is_valid is False
assert metadata is None
def test_invalid_uppercase_letters(self):
"""Test that uppercase letters make filename invalid."""
is_valid, metadata = validate_schema_filename("ManPage-Schema-v1.0.md")
assert is_valid is False
assert metadata is None
def test_invalid_starting_with_number(self):
"""Test that domain starting with number is invalid."""
is_valid, metadata = validate_schema_filename("42answers-schema-v1.0.md")
assert is_valid is False
assert metadata is None
def test_invalid_starting_with_hyphen(self):
"""Test that domain starting with hyphen is invalid."""
is_valid, metadata = validate_schema_filename("-manpage-schema-v1.0.md")
assert is_valid is False
assert metadata is None
def test_invalid_special_characters(self):
"""Test that special characters in domain are invalid."""
is_valid, metadata = validate_schema_filename("man_page-schema-v1.0.md")
assert is_valid is False
assert metadata is None
class TestSuggestSchemaFilename:
"""Tests for suggest_schema_filename function."""
def test_suggest_simple_domain(self):
"""Test suggestion for simple domain."""
filename = suggest_schema_filename("manpage", "1.0")
assert filename == "manpage-schema-v1.0.md"
def test_suggest_with_spaces(self):
"""Test suggestion normalizes spaces to hyphens."""
filename = suggest_schema_filename("API Documentation", "1.0")
assert filename == "api-documentation-schema-v1.0.md"
def test_suggest_with_underscores(self):
"""Test suggestion normalizes underscores to hyphens."""
filename = suggest_schema_filename("my_custom_type", "1.0")
assert filename == "my-custom-type-schema-v1.0.md"
def test_suggest_with_uppercase(self):
"""Test suggestion converts to lowercase."""
filename = suggest_schema_filename("MyCustomType", "1.0")
assert filename == "mycustomtype-schema-v1.0.md"
def test_suggest_mixed_normalization(self):
"""Test suggestion with mixed case and separators."""
filename = suggest_schema_filename("My_Custom Type", "1.0")
assert filename == "my-custom-type-schema-v1.0.md"
def test_suggest_higher_version(self):
"""Test suggestion with version > 1.0."""
filename = suggest_schema_filename("manpage", "2.5")
assert filename == "manpage-schema-v2.5.md"
def test_suggest_double_digit_version(self):
"""Test suggestion with double-digit version."""
filename = suggest_schema_filename("manpage", "10.25")
assert filename == "manpage-schema-v10.25.md"
def test_suggest_consecutive_hyphens(self):
"""Test suggestion removes consecutive hyphens."""
filename = suggest_schema_filename("my--custom---type", "1.0")
assert filename == "my-custom-type-schema-v1.0.md"
def test_suggest_leading_trailing_hyphens(self):
"""Test suggestion removes leading/trailing hyphens."""
filename = suggest_schema_filename("-my-type-", "1.0")
assert filename == "my-type-schema-v1.0.md"
def test_suggest_default_version(self):
"""Test suggestion uses default version 1.0."""
filename = suggest_schema_filename("manpage")
assert filename == "manpage-schema-v1.0.md"
def test_suggest_empty_domain_raises_error(self):
"""Test that empty domain raises ValueError."""
with pytest.raises(ValueError, match="Domain cannot be empty"):
suggest_schema_filename("", "1.0")
def test_suggest_invalid_version_format_raises_error(self):
"""Test that invalid version format raises ValueError."""
with pytest.raises(ValueError, match="must be in format 'major.minor'"):
suggest_schema_filename("manpage", "1")
def test_suggest_invalid_version_parts_raises_error(self):
"""Test that non-integer version parts raise ValueError."""
with pytest.raises(ValueError, match="major and minor must be integers"):
suggest_schema_filename("manpage", "1.x")
def test_suggest_negative_version_raises_error(self):
"""Test that negative version numbers raise ValueError."""
with pytest.raises(ValueError, match="must be non-negative"):
suggest_schema_filename("manpage", "-1.0")
def test_suggest_without_normalization(self):
"""Test suggestion without normalization (must already be valid)."""
filename = suggest_schema_filename("manpage", "1.0", normalize=False)
assert filename == "manpage-schema-v1.0.md"
def test_suggest_without_normalization_invalid_raises_error(self):
"""Test that invalid domain without normalization raises ValueError."""
with pytest.raises(ValueError, match="Invalid domain"):
suggest_schema_filename("My Custom Type", "1.0", normalize=False)
class TestExtractSchemaMetadata:
"""Tests for extract_schema_metadata function."""
def test_extract_valid_metadata(self):
"""Test metadata extraction from valid filename."""
metadata = extract_schema_metadata("manpage-schema-v1.0.md")
assert metadata['domain'] == 'manpage'
assert metadata['version'] == '1.0'
assert metadata['major'] == 1
assert metadata['minor'] == 0
def test_extract_invalid_raises_error(self):
"""Test that invalid filename raises SchemaFilenameError."""
with pytest.raises(SchemaFilenameError, match="Invalid schema filename"):
extract_schema_metadata("invalid.json")
class TestGetValidationErrors:
"""Tests for get_validation_errors function."""
def test_valid_filename_no_errors(self):
"""Test that valid filename returns empty error list."""
errors = get_validation_errors("manpage-schema-v1.0.md")
assert errors == []
def test_wrong_extension_error(self):
"""Test error for wrong file extension."""
errors = get_validation_errors("manpage-schema-v1.0.json")
assert len(errors) > 0
assert any("Extension must be '.md'" in e for e in errors)
def test_missing_version_error(self):
"""Test error for missing version."""
errors = get_validation_errors("manpage-schema.md")
assert len(errors) > 0
assert any("Missing version" in e for e in errors)
def test_missing_schema_keyword_error(self):
"""Test error for missing schema keyword."""
errors = get_validation_errors("manpage-v1.0.md")
assert len(errors) > 0
assert any("Missing '-schema-'" in e for e in errors)
def test_uppercase_letters_error(self):
"""Test error for uppercase letters."""
errors = get_validation_errors("ManPage-schema-v1.0.md")
assert len(errors) > 0
assert any("must be lowercase" in e for e in errors)
def test_invalid_domain_error(self):
"""Test error for invalid domain format."""
errors = get_validation_errors("42answer-schema-v1.0.md")
assert len(errors) > 0
# Should detect that domain doesn't start with letter
class TestIsValidSchemaFilename:
"""Tests for is_valid_schema_filename convenience function."""
def test_is_valid_returns_true(self):
"""Test that valid filename returns True."""
assert is_valid_schema_filename("manpage-schema-v1.0.md") is True
def test_is_valid_returns_false(self):
"""Test that invalid filename returns False."""
assert is_valid_schema_filename("invalid.json") is False
class TestFormatValidationMessage:
"""Tests for format_validation_message function."""
def test_format_message_valid_filename(self):
"""Test formatting message for valid filename."""
message = format_validation_message("manpage-schema-v1.0.md")
assert "✅ Valid" in message
assert "manpage-schema-v1.0.md" in message
def test_format_message_invalid_filename(self):
"""Test formatting message for invalid filename."""
message = format_validation_message("invalid.json")
assert "❌ Invalid" in message
assert "Errors:" in message
assert "Expected format:" in message
assert "Example:" in message
def test_format_message_includes_suggestion(self):
"""Test that message includes filename suggestion."""
message = format_validation_message("manpage.json")
assert "Suggested filename:" in message
# Should suggest something like manpage-schema-v1.0.md
class TestSchemaFilenamePattern:
"""Tests for the regex pattern itself."""
def test_pattern_matches_valid_filenames(self):
"""Test that pattern matches all valid filename variations."""
valid_filenames = [
"manpage-schema-v1.0.md",
"api-documentation-schema-v1.0.md",
"arc42-schema-v1.0.md",
"a-schema-v1.0.md", # Single letter domain
"my-long-domain-name-schema-v1.0.md",
"manpage-schema-v10.25.md", # Double digit versions
]
for filename in valid_filenames:
match = SCHEMA_FILENAME_PATTERN.match(filename)
assert match is not None, f"Pattern should match {filename}"
def test_pattern_rejects_invalid_filenames(self):
"""Test that pattern rejects invalid filenames."""
invalid_filenames = [
"manpage-schema-v1.0.json", # Wrong extension
"manpage-v1.0.md", # Missing schema keyword
"manpage-schema.md", # Missing version
"ManPage-schema-v1.0.md", # Uppercase
"42answer-schema-v1.0.md", # Starts with number
"-manpage-schema-v1.0.md", # Starts with hyphen
"man_page-schema-v1.0.md", # Underscore in domain
"manpage-schema-1.0.md", # Missing 'v' prefix
"manpage-schema-v1.md", # Missing minor version
]
for filename in invalid_filenames:
match = SCHEMA_FILENAME_PATTERN.match(filename)
assert match is None, f"Pattern should not match {filename}"
class TestEdgeCases:
"""Tests for edge cases and boundary conditions."""
def test_very_long_domain_name(self):
"""Test with very long domain name."""
long_domain = "a" * 100
filename = suggest_schema_filename(long_domain, "1.0")
assert is_valid_schema_filename(filename)
def test_domain_with_many_hyphens(self):
"""Test domain with multiple hyphens."""
filename = suggest_schema_filename("my-very-long-domain-name", "1.0")
assert filename == "my-very-long-domain-name-schema-v1.0.md"
assert is_valid_schema_filename(filename)
def test_version_zero_zero(self):
"""Test with version 0.0."""
filename = suggest_schema_filename("manpage", "0.0")
assert filename == "manpage-schema-v0.0.md"
assert is_valid_schema_filename(filename)
def test_large_version_numbers(self):
"""Test with large version numbers."""
filename = suggest_schema_filename("manpage", "999.999")
assert filename == "manpage-schema-v999.999.md"
assert is_valid_schema_filename(filename)
Reference in New Issue View Git Blame Copy Permalink