scripts-validate-c4-diagrams

#!/usr/bin/env python3 """

title: "Validate C4 Diagrams" component_type: script version: "1.0.0" audience: contributor status: stable summary: "CODITECT C4 Diagram Validator =============================" keywords: ['diagrams', 'generation', 'validate', 'validation'] tokens: ~500 created: 2025-12-22 updated: 2025-12-22 script_name: "validate_c4_diagrams.py" language: python executable: true usage: "python3 scripts/validate_c4_diagrams.py [options]" python_version: "3.10+" dependencies: [] modifies_files: false network_access: false requires_auth: false

CODITECT C4 Diagram Validator

STATUS: STUB - Not yet implemented VERSION: 0.1.0 (placeholder) AUTHOR: CODITECT Core Team

DESCRIPTION: Validates C4 model diagrams for structural correctness, consistency, and adherence to C4 methodology standards. Supports Structurizr DSL, PlantUML C4, and Mermaid C4 formats.

PURPOSE: - Validate C4 diagram syntax and structure - Check consistency across diagram levels (Context → Container → Component) - Verify element references and relationships - Ensure naming conventions and descriptions - Generate validation reports with actionable fixes

EXPECTED INPUTS: --paths : Paths to C4 diagram files --format : Input format (structurizr, plantuml, mermaid, auto) --level : C4 levels to validate (context, container, component, code) --output : Validation report output path --strict : Enable strict mode (fail on warnings) --fix : Attempt automatic fixes where possible

EXPECTED OUTPUTS: - c4-validation-report.json with: { "valid": true/false, "summary": { "diagrams": N, "errors": N, "warnings": N, "fixed": N }, "diagrams": [{ "file": "context.puml", "level": "context", "valid": true, "errors": [], "warnings": [], "elements": N, "relationships": N }], "cross_level_issues": [], "recommendations": [] }

DEPENDENCIES: - pyyaml - for Structurizr DSL parsing - plantuml - for PlantUML validation (optional) - jsonschema - for schema validation

IMPLEMENTATION REQUIREMENTS: 1. Parser for each C4 format (Structurizr, PlantUML, Mermaid) 2. C4 model object representation 3. Level-specific validation rules 4. Cross-level consistency checking 5. Element naming convention enforcement 6. Relationship validation (source/target exist) 7. Description completeness checking 8. Technology/tag validation 9. Auto-fix capabilities 10. Report generation

VALIDATION RULES: Context Level: - System must have name and description - External systems properly marked - Person elements defined - All relationships have descriptions

Container Level:
    - Containers linked to parent system
    - Technology specified for each container
    - Internal/external boundary clear

Component Level:
    - Components linked to parent container
    - Responsibilities documented
    - Interface definitions present

Code Level:
    - Classes/functions linked to components
    - Method signatures documented

USAGE EXAMPLES: # Validate all C4 diagrams python scripts/validate_c4_diagrams.py --paths diagrams/

# Validate specific level
python scripts/validate_c4_diagrams.py \\
    --paths diagrams/ \\
    --level container

# Strict mode with auto-fix
python scripts/validate_c4_diagrams.py \\
    --paths diagrams/ \\
    --strict \\
    --fix

RELATED COMMANDS: - /c4-methodology-skill : C4 methodology skill - /strategy : Architecture planning mode

SEE ALSO: - commands/c4-methodology-skill.md - docs/03-architecture/C4-METHODOLOGY-GUIDE.md """

import argparse import json import sys from datetime import datetime from pathlib import Path

def main(): parser = argparse.ArgumentParser( description='C4 Diagram Validator', formatter_class=argparse.RawDescriptionHelpFormatter, epilog=''' Examples: %(prog)s --paths diagrams/ %(prog)s --paths diagrams/ --level container %(prog)s --strict --fix

Status: STUB - Implementation required ''' )

parser.add_argument('--paths', nargs='*', default=['diagrams/'],
                    help='Paths to C4 diagram files')
parser.add_argument('--format', default='auto',
                    choices=['structurizr', 'plantuml', 'mermaid', 'auto'],
                    help='Input format (default: auto-detect)')
parser.add_argument('--level', nargs='*',
                    choices=['context', 'container', 'component', 'code', 'all'],
                    default=['all'],
                    help='C4 levels to validate')
parser.add_argument('--output', default='c4-validation-report.json',
                    help='Validation report output path')
parser.add_argument('--strict', action='store_true',
                    help='Fail on warnings')
parser.add_argument('--fix', action='store_true',
                    help='Attempt automatic fixes')
parser.add_argument('--verbose', '-v', action='store_true',
                    help='Verbose output')

args = parser.parse_args()

print("=" * 70)
print("CODITECT C4-DIAGRAM-VALIDATOR - STUB IMPLEMENTATION")
print("=" * 70)
print(f"\nThis script is a placeholder stub.")
print(f"Full implementation is required.\n")
print(f"Configuration:")
print(f"  Paths: {args.paths}")
print(f"  Format: {args.format}")
print(f"  Levels: {args.level}")
print(f"  Output: {args.output}")
print(f"  Strict: {args.strict}")
print(f"  Auto-fix: {args.fix}")
print()

# Create stub report
stub_report = {
    "status": "stub",
    "message": "C4 diagram validation not yet implemented",
    "timestamp": datetime.now().isoformat(),
    "valid": True,
    "summary": {
        "diagrams": 0,
        "errors": 0,
        "warnings": 0,
        "fixed": 0
    },
    "diagrams": [],
    "cross_level_issues": [],
    "recommendations": [
        "Implement this script to enable C4 diagram validation"
    ]
}

with open(args.output, 'w') as f:
    json.dump(stub_report, f, indent=2)

print(f"Stub report written to: {args.output}")
print("\nTo implement this script, see the docstring requirements above.")

return 0

if name == 'main': sys.exit(main())

#!/usr/bin/env python3 """​

CODITECT C4 Diagram Validator

#!/usr/bin/env python3 """