coulomb/markitect-main
2
0
Fork 0
Code Issues 60 Pull Requests Actions 1 Projects 12 Releases 1 Wiki Activity
Files
14108533fb5fd4e09b7346fc80be56d22897915a
markitect-main/TODO.md
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

142 lines
6.4 KiB
Markdown
Raw Blame History

# Todofile
This is a "to do next" file, particularly useful to keep the human and a coding assistant in sync.
The format is based on [Keep a Todofile V0.0.1](https://coulomb.social/open/KeepaTodofile).
The structure organizes **future tasks** by their impact, just as a changelog organizes past changes by their impact.
***
## [Unreleased] - *Active Vibe-Coding State* 💡
This section is for tasks currently being discussed with or worked on by the coding assistant. These are the ephemeral, flow-of-thought tasks.
### Schema-of-Schemas Implementation (Active - Phase 1)
**Status:** Phase 1 - Filename Convention & Validation (In Progress)
**Workplan:** See `roadmap/schema-of-schemas/WORKPLAN.md`
**Current Goals:**
1. ✅ Establish naming convention: `{domain}-schema-v{major}.{minor}.md`
2. 🔄 Implement filename validation logic
3. 🔄 Update CLI with validation
4. ⏳ Create markdown schema loader
5. ⏳ Build schema-for-schemas metaschema
6. ⏳ Migrate existing schemas to new format
**Phase 1 Tasks (Completed ✅):**
- [x] Write `markitect/schema_naming.py` with validation logic
- [x] Add unit tests for filename validation (50 tests, 100% passing)
- [ ] Update `schema-ingest` command with validation (Next: Phase 2)
- [x] Create SCHEMA_NAMING_SPEC.md documentation
**Next Phases:**
- Phase 2: Markdown Schema Loader (2-3 days)
- Phase 3: Schema-for-Schemas Metaschema (2 days)
- Phase 4: Schema Migration (1-2 days)
- Phase 5: CLI & Documentation Updates (1 day)
- Phase 6: Testing & Validation (1 day)
**Expected Completion:** 8-10 days total
---
### Extract Capability-Capability from Issue-Facade (Paused)
**Context:** Issue-facade currently provides two capabilities:
1. **issue-tracking** (explicit in CAPABILITY-issue-tracking.yaml) - Issue management across platforms
2. **capability-capability** (implicit) - Patterns and tools for creating/managing capabilities
The **capability-capability** includes:
- Feedback pattern (feedback/ directory, .capability/feedback CLI tool, documentation)
- Detachment facility (.capability/detach script for clean capability removal)
- Integration pattern (.capability/integrate.sh for project integration)
- CAPABILITY-*.yaml specification format
- ReusableCapabilitiesArchitecture.md (complete specification)
- Directory conventions (_family/implementation, visible/hidden patterns)
**Goal:** Extract capability-capability to separate `reusable-capability` repository so it can be used by any capability in the markitect ecosystem.
**Approach:** Step-by-step extraction, starting with specification.
#### Phase 1: Specification & Planning (Current)
- [ ] Create CAPABILITY-capability.yaml in issue-facade to explicitly declare the implicit capability
- [ ] Define what belongs to capability-capability family vs issue-tracking family
- [ ] Document the capability-capability API surface (what tools/patterns it provides)
- [ ] Identify all files/directories to extract
- [ ] Plan extraction strategy (copy vs move, how to maintain during transition)
#### Phase 2: Repository Creation
- [ ] Create reusable-capability repository structure
- [ ] Extract ReusableCapabilitiesArchitecture.md to new repo
- [ ] Extract feedback pattern (directory structure, CLI tool, README)
- [ ] Extract detachment facility (.capability/detach)
- [ ] Extract integration scripts (.capability/integrate.sh, integration-checklist.md)
- [ ] Create CAPABILITY-capability.yaml in new repo (canonical version)
- [ ] Add README.md for reusable-capability repo
#### Phase 3: Integration & Testing
- [ ] Update issue-facade to depend on reusable-capability (as integrated capability)
- [ ] Integrate reusable-capability into issue-facade using _capability/reusable-capability pattern
- [ ] Test that issue-facade still works with extracted capability
- [ ] Update issue-facade documentation to reference both capabilities it provides/uses
- [ ] Verify feedback system still works
- [ ] Verify detachment still works
#### Phase 4: Dogfooding & Validation
- [ ] Choose another markitect capability for dogfooding
- [ ] Integrate reusable-capability into that capability
- [ ] Add feedback system to new capability
- [ ] Add detachment facility to new capability
- [ ] Document learnings and refine reusable-capability based on real-world usage
- [ ] Update ReusableCapabilitiesArchitecture.md with insights
**Current Step:** Phase 1, Task 1 - Create CAPABILITY-capability.yaml
***
## Completed Tasks
*Recent completed tasks have been documented in _issue-tracking/issue-facade/CHANGELOG.md following Keep a Changelog format.*
### 2026-01-04 - Phase 2: Schema Refinement Tools & Terminology Example
- ✅ Implemented schema-analyze command to detect rigidity issues
- ✅ Implemented schema-refine command with automatic loosening logic
- ✅ Added interactive mode to schema-refine for fine-grained control
- ✅ Created comprehensive test suite (33 unit tests, 100% passing)
- ✅ Wrote user guide documentation with examples and workflows
- ✅ Successfully tested on example schemas (reduced rigidity from 60/100 to 24/100)
- ✅ Integrated into CLI with proper exit codes and error handling
- ✅ Moved SCHEMA_EVOLUTION_WORKPLAN.md to todo/ directory
- ✅ Created terminology validation example (examples/terminology/)
**Key Features Delivered:**
- Rigidity score calculation (0-100 scale)
- Automatic detection of exact counts, const values, overly specific numbers
- Path navigation for nested schema properties
- Dry-run mode for previewing changes
- Interactive approval workflow
- Comprehensive reporting (normal and verbose modes)
**Terminology Example:**
- Complete terminology document structure (terminology-example.md)
- JSON schema with MarkiTect extensions (terminology-schema.json)
- Demonstrates schema usage for non-manpage documents
- Validates term definitions, synonyms, related terms, examples
- Includes content control and validation rules
- Full documentation and usage examples (README.md)
### 2025-12-17 - Architecture Refactoring
- ✅ Implemented ReusableCapabilitiesArchitecture v0.1
- ✅ Added feedback capability to issue-facade
- ✅ Created detachment facility
- ✅ Refactored to family-based directory structure (_issue-tracking/issue-facade)
- ✅ Made feedback directory visible (feedback/ not .feedback/)
- ✅ Renamed to explicit family declaration (CAPABILITY-issue-tracking.yaml)
- ✅ Created CHANGELOG.md documenting v1.0.0
Reference in New Issue View Git Blame Copy Permalink