CLI Validation Scripts That Verify Diagram Quality and Geometry in Diagram-Design

The diagram-design repository includes eight Python CLI utilities in scripts/verify-*.py that automatically validate diagram assets for geometric clipping, animation timing, import integrity, and semantic consistency.

This article examines the validation pipeline used in cathrynlavery/diagram-design to enforce quality standards. Each script parses HTML or source files and reports violations against the SKILL.md specification, providing automated quality gates for continuous integration workflows.

The Core Geometry Validator: verify-geometry.py

The primary script for diagram geometry validation is scripts/verify-geometry.py. It enforces label-mask clearance requirements from SKILL §6, ensuring labels remain readable and are not obscured by overlapping nodes.

What It Detects

• Label masks clipped by later-painted nodes (minimum 6 px clearance required)
• Improper paint ordering that breaks visual hierarchy

Implementation Details

The script parses <rect> elements and classifies them by size:

Classification	Dimensions	Purpose
Nodes	≥ 60 × 40 px	Main diagram elements (zones, containers)
Masks	20‑120 × 8‑14 px	Label backgrounds that must stay visible

Core functions in verify-geometry.py:

• parse_rects() — extracts and categorizes rectangle elements
• overlap() — computes geometric intersection between elements
• contained() — checks for fully-contained cases (badge exceptions)
• check() — orchestrates validation and reports violations

For every mask-node pair where the node appears later in the document source, the validator computes overlap. Non-trivial intersections are flagged unless the mask is fully contained (the badge case).

Usage Examples

# Validate all shipped HTML assets

python3 scripts/verify-geometry.py --all

# Validate a single diagram file

python3 scripts/verify-geometry.py path/to/diagram.html

Animation and Motion Validation

verify-motion.py

Validates motion-related elements against SKILL §7 timing constraints. The script scans SVG/HTML for <animate> tags and verifies:

• begin and dur values respect minimum gap requirements
• Motion definitions exist for all arrows flagged with data-motion

python3 scripts/verify-motion.py --all

verify-semantic-motion.py

Performs higher-level semantic checks on animated diagrams. It cross-references motion definitions with node labels to ensure consistent expression of motion semantics (e.g., "request → response") across all assets.

python3 scripts/verify-semantic-motion.py --all

Import Integrity Validators

verify-mermaid-import.py

Ensures Mermaid diagram definitions are syntactically correct and render as expected. The script:

1. Runs the Mermaid CLI to render source files
2. Diff-compares output against stored baselines
3. Reports errors with line numbers from the original .mmd file

python3 scripts/verify-mermaid-import.py --all

verify-drawio-import.py

Validates Draw.io (.drawio) file transformations into HTML assets. It parses generated HTML for unexpected <g> groups and verifies the paint order hierarchy:

background → zones → arrows → labels → nodes

python3 scripts/verify-drawio-import.py --all

Documentation and Package Validators

verify-docs-sync.py

Confirms documentation-diagram synchronization. The script extracts image links from Markdown files (README.md, skill documentation), verifies referenced HTML files exist, and optionally runs geometry checks on linked diagrams.

python3 scripts/verify-docs-sync.py

verify-plugin-package.py

Validates plugin package integrity through:

• JSON schema validation for package.json and plugin.json
• Version consistency checks
• Subset verification on bundled assets

python3 scripts/verify-plugin-package.py

Domain-Specific Sequence Validation

verify-sequence-oauth.py

Specialized validator for OAuth sequence diagrams. It looks for specific node IDs (client, auth-server, resource-server) and validates their ordering and label placement against the prescribed token-exchange flow.

python3 scripts/verify-sequence-oauth.py

Common CLI Interface and CI Integration

All validation scripts share a unified interface built on Python's argparse module:

Flag	Behavior
--all	Scan every asset under skills/diagram-design/assets/
(path)	Validate single file

Output format: human-readable findings followed by a summary line.

CI Pipeline Integration

# Run all validators in sequence, failing on first error

for script in scripts/verify-*.py; do
    $script --all || exit 1
done

The repository's .github/workflows/ci.yml integrates these checks to guarantee every committed diagram honors SKILL.md visual and semantic standards.

Complete Script Reference

File	Validation Focus	GitHub Link
scripts/verify-geometry.py	Label-mask clipping, paint ordering	Source
scripts/verify-motion.py	Animation timing, motion elements	Source
scripts/verify-semantic-motion.py	Semantic motion consistency	Source
scripts/verify-mermaid-import.py	Mermaid syntax and rendering	Source
scripts/verify-drawio-import.py	Draw.io transformation integrity	Source
scripts/verify-docs-sync.py	Documentation-asset synchronization	Source
scripts/verify-plugin-package.py	Package schema and bundling	Source
scripts/verify-sequence-oauth.py	OAuth sequence flow correctness	Source

Summary

• verify-geometry.py is the primary CLI validation script for diagram geometry, enforcing 6 px label-mask clearance through rectangle classification and overlap detection
• Eight specialized validators cover geometry, motion, imports, documentation sync, packaging, and domain-specific sequences
• Unified argparse interface with --all flag enables both single-file and batch validation
• CI-ready exit codes support automated quality gates in GitHub Actions workflows
• All validators reference the SKILL.md specification as the authoritative source of diagram quality rules

Frequently Asked Questions

How do I run all diagram validation checks at once?

Use a shell loop to execute every verify-*.py script with the --all flag. The scripts exit with non-zero status on failure, making them suitable for CI pipelines that fail fast on quality violations.

What is the minimum label-mask clearance enforced by the geometry validator?

The verify-geometry.py script enforces ≥ 6 px clearance between label masks and any nodes painted later in the document, as specified in SKILL §6. This prevents labels from being visually clipped or obscured.

Can I validate a single diagram file instead of all assets?

Yes. Omit the --all flag and provide a file path: python3 scripts/verify-geometry.py path/to/diagram.html. This pattern works for all validation scripts in the repository.

How does the Mermaid import validator detect rendering regressions?

verify-mermaid-import.py runs the Mermaid CLI to render source .mmd files, then performs a diff comparison against stored baseline outputs. Errors are reported with original line numbers to simplify debugging.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}