From f19a88f1d5e045d54cfdd0124a9112538f9268ed Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 5 Jan 2026 11:41:33 +0100 Subject: [PATCH] docs: complete Phase 6 - integration testing and documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Completed final phase of Schema-of-Schemas implementation with comprehensive testing and user documentation. **Integration Testing:** - All 97 unit tests passing (50 naming + 35 loader + 12 metaschema) - End-to-end workflow testing: * Schema creation and validation * Schema ingestion into registry * Numbered schema listing * Single schema validation (number, filename, path) * Batch validation (ranges, lists, --all) * Schema deletion and cleanup **Documentation:** - Created comprehensive SCHEMA_MANAGEMENT_GUIDE.md - Quick start guide with templates - Complete command reference for all schema commands - Common workflows and use cases - Best practices and troubleshooting - Advanced usage patterns - Future enhancement notes **Phase Summary:** - Schema-of-Schemas implementation complete (6 phases) - Fully functional schema management system - 97 tests with 100% pass rate - 4 comprehensive documentation files: * SCHEMA_MANAGEMENT_GUIDE.md (usage) * SCHEMA_NAMING_SPEC.md (naming conventions) * SCHEMA_LOADER_GUIDE.md (markdown schemas) * schema-schema-v1.0.md (metaschema reference) This completes the Schema-of-Schemas implementation, providing a robust, well-tested, and well-documented schema management system for MarkiTect. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- CHANGELOG.md | 8 +- TODO.md | 36 ++- docs/SCHEMA_MANAGEMENT_GUIDE.md | 400 ++++++++++++++++++++++++++++++++ 3 files changed, 438 insertions(+), 6 deletions(-) create mode 100644 docs/SCHEMA_MANAGEMENT_GUIDE.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 070266ce..070f802c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,14 +47,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Removed - **BREAKING**: Legacy DocumentControls component from TestDrive JSUI plugin system - all control panel functionality now provided by enhanced control panels (ContentsControl, StatusControl, DebugControl, EditControl) with Reset All button functionality moved to EditControl for better maintainability and elimination of code duplication -### In Progress -- **Schema-of-Schemas Implementation** (Phase 5 of 6 - Completed ✅) +### Completed Features +- **Schema-of-Schemas Implementation** (All 6 Phases Complete ✅) - ✅ Phase 1: Filename validation for schema naming convention (`markitect/schema_naming.py`, 50 tests) - ✅ Phase 2: Markdown schema loader to parse `.md` schema files (`markitect/schema_loader.py`, 35 tests) - ✅ Phase 3: Schema-for-schemas metaschema for schema validation (`schema-schema-v1.0.md`, 12 tests) - ✅ Phase 4: Migration of 5 existing schemas to new format (migrated 2, deleted 3 duplicates) - ✅ Phase 5: CLI enhancements - numbered schema-list, multi-schema validation with selection methods - - ⏳ Phase 6: Integration testing and final documentation + - ✅ Phase 6: Integration testing and comprehensive documentation (SCHEMA_MANAGEMENT_GUIDE.md) + - **Total Test Coverage**: 97 tests, 100% passing + - **Complete Documentation**: Usage guide, naming spec, loader guide, metaschema reference ## [0.9.0] - 2025-11-14 diff --git a/TODO.md b/TODO.md index 7e8beb5b..33b9b50f 100644 --- a/TODO.md +++ b/TODO.md @@ -67,10 +67,17 @@ This section is for tasks currently being discussed with or worked on by the cod - [x] Test all selection methods (1, 1-3, 1,3,5, all, filename, ./path) - [x] Maintain backward compatibility with single-file validation -**Next Phase:** -- Phase 6: Integration testing and final documentation (1 day) +**Phase 6 Tasks (Completed ✅):** +- [x] Run complete test suite - all 97 tests passing (50 naming + 35 loader + 12 metaschema) +- [x] Perform end-to-end integration testing of complete schema workflow +- [x] Test schema creation, validation, ingestion, listing, and batch operations +- [x] Create comprehensive usage documentation (SCHEMA_MANAGEMENT_GUIDE.md) +- [x] Document all commands, workflows, and best practices +- [x] Verify no regressions in existing functionality -**Expected Completion:** 1 day remaining +**Schema-of-Schemas Implementation: COMPLETE ✅** + +All 6 phases completed successfully. The schema management system is fully functional with comprehensive testing and documentation. --- @@ -136,6 +143,29 @@ The **capability-capability** includes: *Recent completed tasks have been documented in _issue-tracking/issue-facade/CHANGELOG.md following Keep a Changelog format.* +### 2026-01-05 - Phase 6: Integration Testing and Final Documentation +- ✅ Ran complete test suite - all 97 tests passing (50 naming + 35 loader + 12 metaschema) +- ✅ Performed end-to-end integration testing: + - Schema creation and validation + - Schema ingestion into registry + - Numbered schema listing + - Single schema validation (by number, filename, path) + - Batch validation (ranges, lists, --all) + - Schema deletion +- ✅ Created comprehensive SCHEMA_MANAGEMENT_GUIDE.md with: + - Quick start guide and templates + - Complete command reference + - Common workflows and examples + - Best practices and troubleshooting + - Advanced usage patterns + +**Schema-of-Schemas Implementation Complete:** +- 6 phases completed over 2 days +- 97 unit tests (100% passing) +- End-to-end integration verified +- Comprehensive documentation delivered +- Fully functional schema management system + ### 2026-01-05 - Phase 5: Enhanced Schema Validation with Multiple Selection - ✅ Enhanced schema-list command with numbered references in all formats - ✅ Implemented schema selection parser supporting: diff --git a/docs/SCHEMA_MANAGEMENT_GUIDE.md b/docs/SCHEMA_MANAGEMENT_GUIDE.md new file mode 100644 index 00000000..3deb724f --- /dev/null +++ b/docs/SCHEMA_MANAGEMENT_GUIDE.md @@ -0,0 +1,400 @@ +# Schema Management Guide + +Complete guide to managing schemas in MarkiTect using the Schema-of-Schemas system. + +## Overview + +MarkiTect provides a comprehensive schema management system with: +- Markdown-first schema format with embedded JSON +- Strict naming conventions for consistency +- Metaschema validation for all schemas +- Multi-schema batch validation +- Schema registry with version tracking + +## Quick Start + +### 1. Create a New Schema + +Create a markdown file following the naming convention: `{domain}-schema-v{major}.{minor}.md` + +```bash +# Example: blog-post-schema-v1.0.md +``` + +**Template:** + +```markdown +--- +schema-id: https://markitect.dev/schemas/blog-post/v1.0 +version: 1.0.0 +status: stable +domain: blog-post +description: Schema for blog post documents +--- + +# Blog Post Schema v1.0.0 + +## Overview +This schema validates blog post documents with frontmatter and content sections. + +## Schema Definition + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://markitect.dev/schemas/blog-post/v1.0", + "title": "Blog Post Schema", + "description": "Schema for blog post documents", + "version": "1.0.0", + "type": "object", + "properties": { + "title": { + "type": "string", + "minLength": 1 + }, + "author": { + "type": "string" + }, + "date": { + "type": "string", + "format": "date" + } + }, + "required": ["title", "author"] +} +``` +\`\`\` + +### 2. Validate Your Schema + +Validate against the metaschema to ensure it follows MarkiTect conventions: + +```bash +# Validate a single schema file +markitect schema-validate ./blog-post-schema-v1.0.md + +# See detailed errors +markitect schema-validate ./blog-post-schema-v1.0.md --detailed-errors +``` + +### 3. Ingest into Registry + +Add your schema to the registry: + +```bash +markitect schema-ingest blog-post-schema-v1.0.md +``` + +### 4. List Registered Schemas + +View all schemas with numbered references: + +```bash +# Simple format (default) +markitect schema-list + +# Table format +markitect schema-list --format table + +# JSON format +markitect schema-list --format json +``` + +**Output:** +``` +Found 4 schema(s): + +[1] 🔧 blog-post-schema-v1.0.md (added: 2026-01-05T10:30:00) +[2] 🔧 schema-schema-v1.0.md (added: 2026-01-05T03:33:42) +[3] 🔧 manpage-schema-v1.0.md (added: 2026-01-05T03:33:42) +[4] 🔧 api-documentation-schema-v1.0.md (added: 2026-01-05T03:33:35) +``` + +## Schema Validation + +### Single Schema Validation + +**By number:** +```bash +markitect schema-validate 1 +``` + +**By filename (from registry):** +```bash +markitect schema-validate blog-post-schema-v1.0.md +``` + +**By filesystem path:** +```bash +markitect schema-validate ./my-schema.md +``` + +### Batch Validation + +**Validate a range:** +```bash +markitect schema-validate 1-3 +``` + +**Validate specific schemas:** +```bash +markitect schema-validate 1,3,5 +``` + +**Validate all schemas:** +```bash +markitect schema-validate --all +``` + +**Output:** +``` +Validating 4 schema(s)... + +Results: + + # Schema Status Details +--- -------------------------------- -------- --------- + 1 blog-post-schema-v1.0.md ✅ Valid v1.0.0 + 2 schema-schema-v1.0.md ✅ Valid v1.0.0 + 3 manpage-schema-v1.0.md ✅ Valid v1.0.0 + 4 api-documentation-schema-v1.0.md ✅ Valid v1.0.0 + +Summary: 4 valid, 0 failed +``` + +## Schema Naming Conventions + +All schema filenames must follow this pattern: + +``` +{domain}-schema-v{major}.{minor}.md +``` + +### Rules + +- **Domain**: Lowercase letters, numbers, and hyphens only +- **Version**: Major.minor format (e.g., `v1.0`, `v2.3`) +- **Extension**: Must be `.md` +- **No spaces**: Use hyphens for separation + +### Valid Examples + +- `blog-post-schema-v1.0.md` +- `api-documentation-schema-v2.1.md` +- `user-profile-schema-v1.0.md` + +### Invalid Examples + +- `BlogPost-schema-v1.0.md` (uppercase) +- `blog_post-schema-v1.0.md` (underscore) +- `blog-post-v1.0.md` (missing "schema") +- `blog-post-schema-v1.md` (missing minor version) + +## Required Schema Fields + +All schemas must include these fields: + +### Frontmatter (YAML) +```yaml +--- +schema-id: https://markitect.dev/schemas/{domain}/v{major}.{minor} +version: {major}.{minor}.{patch} +status: draft|stable|deprecated +domain: {domain} +description: Brief description +--- +``` + +### JSON Schema +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://markitect.dev/schemas/{domain}/v{major}.{minor}", + "title": "Schema Title", + "description": "Schema description", + "version": "{major}.{minor}.{patch}" +} +``` + +## Common Workflows + +### Revalidate All Schemas After Metaschema Changes + +When you update the metaschema, revalidate all registered schemas: + +```bash +markitect schema-validate --all +``` + +### Check Schema Rigidity + +Analyze a schema for overly rigid constraints: + +```bash +markitect schema-analyze my-schema.md +``` + +### Refine a Rigid Schema + +Automatically loosen overly specific constraints: + +```bash +# Dry run (preview changes) +markitect schema-refine my-schema.md --dry-run + +# Apply changes +markitect schema-refine my-schema.md + +# Interactive mode +markitect schema-refine my-schema.md --interactive +``` + +### Get Schema Details + +View schema metadata: + +```bash +markitect schema-get blog-post-schema-v1.0.md +``` + +### Delete a Schema + +Remove a schema from the registry: + +```bash +markitect schema-delete blog-post-schema-v1.0.md --confirm +``` + +## Resolution Precedence + +When validating schemas, MarkiTect uses this resolution order: + +1. **Registry (by filename)**: Exact match in the database +2. **Filesystem (fallback)**: If not found in registry or looks like a path + +### Examples + +```bash +# Looks up in registry first +markitect schema-validate blog-post-schema-v1.0.md + +# Forces filesystem lookup (contains /) +markitect schema-validate ./blog-post-schema-v1.0.md + +# Also forces filesystem +markitect schema-validate ../schemas/blog-post-schema-v1.0.md +``` + +## Best Practices + +### Schema Development + +1. **Start with a template**: Use an existing schema as a starting point +2. **Validate early**: Validate against the metaschema before ingesting +3. **Use semantic versioning**: Major.minor.patch for all versions +4. **Document thoroughly**: Include overview, usage, and examples +5. **Test with real documents**: Validate actual documents against your schema + +### Version Management + +- **Increment major version**: Breaking changes to schema structure +- **Increment minor version**: Backward-compatible additions +- **Increment patch version**: Bug fixes and clarifications + +### Schema Organization + +``` +markitect/schemas/ +├── schema-schema-v1.0.md # Metaschema +├── manpage-schema-v1.0.md # Man page documents +├── api-documentation-schema-v1.0.md +├── terminology-schema-v1.0.md +└── blog-post-schema-v1.0.md # Your schemas +``` + +## Troubleshooting + +### Schema Not Found + +``` +❌ Schema 'my-schema.md' not found in registry or filesystem +``` + +**Solution:** Use `markitect schema-list` to see available schemas, or provide a path: `./my-schema.md` + +### Validation Fails + +``` +❌ Schema validation failed: my-schema.md +Found 2 validation error(s): +``` + +**Solution:** Check error messages and compare with metaschema requirements. Use `--detailed-errors` for more context. + +### Invalid Selector + +``` +❌ Invalid selector: Range 1-10 is out of bounds. Valid range: 1-4 +``` + +**Solution:** Use `markitect schema-list` to see valid numbers, or check your range syntax. + +## Advanced Usage + +### Scripting with Schema Commands + +Validate schemas in CI/CD: + +```bash +#!/bin/bash +# Validate all schemas and exit with error if any fail +if ! markitect schema-validate --all; then + echo "Schema validation failed!" + exit 1 +fi +echo "All schemas valid" +``` + +### Batch Operations + +```bash +# Validate recently added schemas +markitect schema-validate 1-3 + +# Validate specific critical schemas +markitect schema-validate 1,5,8 + +# Check just the metaschema +markitect schema-validate 2 +``` + +## Schema Extensions + +MarkiTect supports custom extensions in schemas: + +- `x-markitect-sections`: Section classification (required, recommended, optional, discouraged, improper) +- `x-markitect-content-control`: Content validation rules and patterns +- `x-markitect-metadata`: Additional metadata for MarkiTect processing + +See existing schemas for examples of these extensions. + +## Future Enhancements + +Planned features: +- Wildcard/globbing support: `markitect schema-validate */manpage*` +- Schema diff tool: Compare schema versions +- Schema migration assistant: Help upgrade documents to new schema versions + +## Related Documentation + +- [Schema Naming Specification](../roadmap/schema-of-schemas/SCHEMA_NAMING_SPEC.md) +- [Schema Loader Guide](../roadmap/schema-of-schemas/SCHEMA_LOADER_GUIDE.md) +- [Metaschema Reference](../markitect/schemas/schema-schema-v1.0.md) + +## Support + +For issues or questions: +- Check existing schemas as examples +- Review metaschema validation errors carefully +- Use `--detailed-errors` for more context +- Consult the metaschema for requirements