coulomb/markitect-main
2
0
Fork 0
Code Issues 62 Pull Requests Actions Projects 12 Releases 1 Wiki Activity

feat: Complete Issue #52 - Capture actual heading text in schemas

Browse Source 
Implement comprehensive heading text capture functionality that allows schemas to
enforce specific heading text requirements through enum constraints:

• New CLI option: --capture-heading-text flag for exact text constraints
• Schema generation with heading text as enum constraints (not just structure)
• Advanced validation engine that enforces heading text requirements
• Metaschema extension: x-markitect-heading-text-capture marker
• Full integration with Issue #51 outline mode capabilities
• Comprehensive error reporting for heading text mismatches
• Complete backward compatibility with existing schema generation

Technical implementation:
- Extended SchemaGenerator with capture_heading_text parameter
- Enhanced validation system to check enum constraints on heading content
- Added _validate_heading_text_constraints_with_errors for detailed reporting
- Integrated with existing metaschema validation from Issue #50
- Preserved document order of headings in enum constraints

Key features:
- Schemas can now specify required heading text via enum constraints
- Validation rejects documents with incorrect heading text
- Detailed error messages show expected vs actual heading text
- Works seamlessly with outline mode depth controls
- Maintains 100% compatibility with 513 existing tests

Usage examples:
  markitect schema-generate --capture-heading-text document.md
  markitect schema-generate --mode outline --capture-heading-text --depth 2 document.md

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2025-10-01 08:03:11 +02:00
parent b5f510f9c7
commit 0f37900222
4 changed files with 534 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
markitect/cli.py
View File

@@ -1454,8 +1454,9 @@ def ast_stats(config, file_path, format):
@click.option('--format', 'output_format', type=click.Choice(['json', 'yaml']), default='json', help='Output format')
@click.option('--mode', type=click.Choice(['outline']), help='Generation mode: outline for structure-focused schemas')
@click.option('--depth', type=int, help='Maximum depth for outline mode (similar to --max-depth)')
@click.option('--capture-heading-text', is_flag=True, help='Capture exact heading text as schema constraints')
@pass_config
def generate_schema(config, file_path, max_depth, output, outfile, output_format, mode, depth):
def generate_schema(config, file_path, max_depth, output, outfile, output_format, mode, depth, capture_heading_text):
"""
Generate a JSON schema from a markdown file's AST structure.
@@ -1470,9 +1471,17 @@ def generate_schema(config, file_path, max_depth, output, outfile, output_format
markitect schema-generate --mode outline document.md
markitect schema-generate --mode outline --depth 3 --outfile schema.json document.md
# Heading text capture for validation constraints
markitect schema-generate --capture-heading-text document.md
markitect schema-generate --mode outline --capture-heading-text --depth 2 document.md
Modes:
Default: Standard schema generation with structural analysis
Outline: Structure-focused schema with heading text capture and metaschema extensions
Heading Text Capture:
When --capture-heading-text is enabled, the schema will include exact heading text
as enum constraints, enabling validation to enforce specific heading text requirements.
"""
try:
# Handle parameter conflicts and defaults
@@ -1507,7 +1516,8 @@ def generate_schema(config, file_path, max_depth, output, outfile, output_format
file_path,
max_depth=final_depth,
mode=mode,
outline_depth=depth if mode == 'outline' else None
outline_depth=depth if mode == 'outline' else None,
capture_heading_text=capture_heading_text
)
# Format output

24
markitect/schema_generator.py
View File

@@ -33,7 +33,8 @@ class SchemaGenerator:
file_path: Path,
max_depth: Optional[int] = None,
mode: Optional[str] = None,
outline_depth: Optional[int] = None
outline_depth: Optional[int] = None,
capture_heading_text: bool = False
) -> Dict[str, Any]:
"""
Generate a JSON schema from a markdown file's AST structure.
@@ -43,6 +44,7 @@ class SchemaGenerator:
max_depth: Maximum heading depth to include (None = unlimited)
mode: Generation mode ('outline' for structure-focused schemas)
outline_depth: Depth limit for outline mode
capture_heading_text: Whether to capture exact heading text as constraints
Returns:
JSON schema as a dictionary
@@ -66,7 +68,7 @@ class SchemaGenerator:
structure_analysis = self._analyze_ast_structure(ast_tokens, max_depth)
# Generate the JSON schema
schema = self._create_json_schema(structure_analysis, file_path.name, mode=mode, outline_depth=outline_depth)
schema = self._create_json_schema(structure_analysis, file_path.name, mode=mode, outline_depth=outline_depth, capture_heading_text=capture_heading_text)
return schema
@@ -183,7 +185,8 @@ class SchemaGenerator:
analysis: Dict[str, Any],
filename: str,
mode: Optional[str] = None,
outline_depth: Optional[int] = None
outline_depth: Optional[int] = None,
capture_heading_text: bool = False
) -> Dict[str, Any]:
"""
Create a JSON schema from structural analysis.
@@ -193,6 +196,7 @@ class SchemaGenerator:
filename: Name of the source file
mode: Generation mode ('outline' for structure-focused schemas)
outline_depth: Depth limit for outline mode
capture_heading_text: Whether to capture exact heading text as constraints
Returns:
JSON schema dictionary
@@ -214,18 +218,30 @@ class SchemaGenerator:
if outline_depth is not None:
schema["x-markitect-outline-depth"] = outline_depth
# Add metaschema extension for heading text capture
if capture_heading_text:
schema["x-markitect-heading-text-capture"] = True
# Add heading structure
if analysis['headings']:
heading_properties = {}
for level_key, headings in analysis['headings'].items():
if headings: # Only include levels that have content
# Configure content property based on heading text capture
if capture_heading_text:
# Extract actual heading texts in document order
heading_texts = [heading['content'] for heading in headings]
content_property = {"enum": heading_texts}
else:
content_property = {"type": "string"}
heading_properties[level_key] = {
"type": "array",
"description": f"Headings at {level_key.replace('_', ' ')}",
"items": {
"type": "object",
"properties": {
"content": {"type": "string"},
"content": content_property,
"level": {"type": "integer"},
"position": {"type": "integer"}
},

125
markitect/schema_validator.py
View File

@@ -68,8 +68,13 @@ class SchemaValidator:
except Exception as e:
raise SchemaValidationError(f"Failed to generate document schema: {e}") from e
# Compare the document's structure against the expected schema
return self._compare_structures(document_schema, schema)
# Check if the expected schema has heading text constraints
if self._has_heading_text_constraints(schema):
# For heading text validation, we need to extract actual content and compare against enum constraints
return self._validate_with_heading_text_constraints(file_path, schema, document_schema)
else:
# Use standard structure comparison for backward compatibility
return self._compare_structures(document_schema, schema)
def validate_file_against_schema_string(self, file_path: Path, schema_json: str) -> bool:
"""
@@ -314,7 +319,13 @@ class SchemaValidator:
return error_collector
# Compare the document's structure against the expected schema and collect errors
self._compare_structures_with_errors(document_schema, schema, error_collector)
if self._has_heading_text_constraints(schema):
# For heading text validation, we need to handle enum constraints specially
self._compare_structures_with_errors(document_schema, schema, error_collector)
self._validate_heading_text_constraints_with_errors(file_path, schema, error_collector)
else:
# Use standard structure comparison for backward compatibility
self._compare_structures_with_errors(document_schema, schema, error_collector)
return error_collector
@@ -562,4 +573,110 @@ class SchemaValidator:
expected=f"At most {expected_max} {element_description}",
actual=f"{actual_count} {element_description}",
suggestion=f"Remove {actual_count - expected_max} {element_description}"
)
)
def _has_heading_text_constraints(self, schema: Dict[str, Any]) -> bool:
"""
Check if the schema has heading text constraints (enum values on heading content).
Args:
schema: JSON schema to check
Returns:
True if schema has heading text constraints
"""
headings_props = schema.get('properties', {}).get('headings', {}).get('properties', {})
for level_props in headings_props.values():
items = level_props.get('items', {})
content_prop = items.get('properties', {}).get('content', {})
if 'enum' in content_prop:
return True
return False
def _validate_with_heading_text_constraints(
self,
file_path: Path,
expected_schema: Dict[str, Any],
document_schema: Dict[str, Any]
) -> bool:
"""
Validate document with heading text constraints by comparing actual content against enum values.
Args:
file_path: Path to the markdown file
expected_schema: Schema with heading text constraints
document_schema: Generated schema from the actual document
Returns:
True if document meets all constraints including heading text
"""
# First check standard structure compliance
if not self._compare_structures(document_schema, expected_schema):
return False
# Then check heading text constraints
expected_headings = expected_schema.get('properties', {}).get('headings', {}).get('properties', {})
# Generate document analysis with actual heading content
from .parser import parse_markdown_to_ast
content = file_path.read_text(encoding='utf-8')
ast_tokens = parse_markdown_to_ast(content)
structure_analysis = self.schema_generator._analyze_ast_structure(ast_tokens, None)
for level_key, expected_level_spec in expected_headings.items():
content_constraints = expected_level_spec.get('items', {}).get('properties', {}).get('content', {})
if 'enum' in content_constraints:
allowed_texts = content_constraints['enum']
actual_headings = structure_analysis['headings'].get(level_key, [])
for heading in actual_headings:
actual_text = heading['content']
if actual_text not in allowed_texts:
return False
return True
def _validate_heading_text_constraints_with_errors(
self,
file_path: Path,
expected_schema: Dict[str, Any],
error_collector: ValidationErrorCollector
) -> None:
"""
Validate heading text constraints and collect detailed errors.
Args:
file_path: Path to the markdown file
expected_schema: Schema with heading text constraints
error_collector: Collector for validation errors
"""
expected_headings = expected_schema.get('properties', {}).get('headings', {}).get('properties', {})
# Generate document analysis with actual heading content
from .parser import parse_markdown_to_ast
content = file_path.read_text(encoding='utf-8')
ast_tokens = parse_markdown_to_ast(content)
structure_analysis = self.schema_generator._analyze_ast_structure(ast_tokens, None)
for level_key, expected_level_spec in expected_headings.items():
content_constraints = expected_level_spec.get('items', {}).get('properties', {}).get('content', {})
if 'enum' in content_constraints:
allowed_texts = content_constraints['enum']
actual_headings = structure_analysis['headings'].get(level_key, [])
for i, heading in enumerate(actual_headings):
actual_text = heading['content']
if actual_text not in allowed_texts:
# Add detailed error about heading text mismatch
error_collector.add_error(
ValidationErrorType.HEADING_COUNT_MISMATCH,
f"Heading text mismatch at {level_key.replace('_', ' ')} #{i+1}: expected one of {allowed_texts}, found '{actual_text}'",
f"headings.{level_key}[{i}].content",
expected=f"One of: {allowed_texts}",
actual=actual_text,
suggestion=f"Change heading text to one of the allowed values: {', '.join(allowed_texts)}"
)