What Is the Purpose of self_check.py in the Diagram-Design Repository?

self_check.py is a stand‑alone validation script that inspects generated diagram HTML files to enforce accessibility, security, and motion‑control contracts without requiring any third‑party dependencies.

The self_check.py file in the cathrynlavery/diagram-design repository serves as the primary quality gate for diagram generation. Located at skills/diagram-design/scripts/self_check.py, this Python module enables installed agents and CI pipelines to run a “self‑check” on their own output, ensuring that produced HTML is safe to publish and conforms to the project's strict technical standards.

Core Purpose and Architecture

The primary purpose of self_check.py is to act as a gatekeeper that guarantees any diagram HTML produced by the skill meets three critical requirements: accessibility for screen readers, security against code injection, and consistency with motion‑control templates. The script is referenced in the module docstring (lines 1‑13)【https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py#L1-L13】.

Unlike external linting tools, self_check.py relies exclusively on the Python standard library—using argparse, html.parser, and pathlib—making it safe to run in any environment where the skill is installed. If validation fails, the script prints detailed error messages and exits with a non‑zero status, allowing automated systems to reject non‑conforming output immediately.

Contract Enforcement Mechanisms

The script validates three distinct contracts through specific parser methods and check functions defined in the source file.

Accessible SVG Contract

The check_svgs function (lines 14‑45)【https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py#L14-L45】 ensures that every SVG element in the diagram is accessible to assistive technologies. It verifies that:

• Each SVG is non‑hidden and includes role="img"
• Proper title and desc elements are present
• Correct aria‑labelledby linking is established between elements

Single‑File Safety Contract

To prevent security vulnerabilities, the script enforces a strict single‑file safety contract through the handle_starttag and reference_error methods (lines 57‑70)【https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py#L57-L70】. This validation:

• Disallows unsafe tags such as <iframe> and <embed>
• Blocks executable attributes and inline event handlers
• Prohibits remote assets except for the approved Google Fonts stylesheet

Motion Control Contract

When diagrams include animation, the check_motion function validates the motion contract (around lines 43‑69)【https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py#L69-L43】. It inspects:

• Structure of data‑motion‑* attributes
• Correct number of controls and required actions
• Presence of status elements
• That the embedded script matches the canonical controller defined in skills/diagram-design/assets/template‑motion.html

How to Run the Self‑Check

Command‑Line Validation

Execute the script directly against any generated HTML file:

python3 skills/diagram-design/scripts/self_check.py path/to/generated-diagram.html

The script prints OK <file> if the diagram passes all checks, or FAIL <file> followed by a list of specific violations.

Programmatic Integration

Import the verify function to validate files within Python applications:

from pathlib import Path
from skills.diagram_design.scripts.self_check import verify

# Verify a single file and retrieve the list of errors (empty list → success)

errors = verify(Path("my-diagram.html"))
if errors:
    print("Diagram has problems:", errors)
else:
    print("Diagram is valid")

CI Pipeline Integration

Add the self‑check to GitHub Actions or other CI systems to enforce contracts automatically:

steps:
  - name: Checkout repository
    uses: actions/checkout@v3

  - name: Run self‑check on generated diagrams
    run: |
      python3 skills/diagram-design/scripts/self_check.py diagrams/*.html

Any non‑zero exit code will cause the workflow to fail, preventing invalid diagrams from being deployed.

Relationship to Other Validation Tools

The self_check.py script operates as a distilled subset of the full repository‑wide motion verification logic found in scripts/verify‑motion.py. While verify‑motion.py performs comprehensive repository scans, self_check.py provides a lightweight, zero‑dependency alternative for runtime validation. Similarly, scripts/lint‑skin.py enforces the same SVG and safety rules for repository contributions, and scripts/test‑self‑check.py contains the test suite that exercises self_check.py against known‑good and known‑bad diagrams.

Summary

• self_check.py is a stand‑alone validation script located at skills/diagram-design/scripts/self_check.py that requires no external dependencies.
• It enforces three critical contracts: accessible SVG markup, single‑file safety (no executable code or remote assets), and motion‑control consistency with the canonical template.
• The script provides both command‑line and programmatic interfaces, returning non‑zero exit codes on failure for CI/CD integration.
• It enables agents to self‑validate output before publication, acting as the final quality gate in the diagram generation pipeline.

Frequently Asked Questions

What specific contracts does self_check.py enforce?

According to the cathrynlavery/diagram-design source code, the script enforces three distinct contracts: the accessible‑SVG contract (proper ARIA attributes and titles), the single‑file safety contract (blocking iframes, embeds, and executable code), and the motion contract (validating data‑motion‑* attributes against the canonical controller in template‑motion.html).

Can self_check.py run without installing dependencies?

Yes. The script uses only Python standard library modules such as argparse, html.parser, and pathlib. This design ensures it can execute in any environment where the diagram‑design skill is installed, without requiring pip installs or virtual environments.

How does self_check.py validate motion controls?

The check_motion function parses the HTML for motion markup and verifies that the embedded JavaScript controller matches the reference implementation in skills/diagram-design/assets/template‑motion.html. It checks the structure of data‑motion‑* attributes, ensures the correct number of controls exist, and validates required actions and status elements.

What happens if a diagram fails validation?

If validation fails, the script outputs FAIL <filename> followed by detailed error messages describing which contract was violated (accessibility, safety, or motion). It then exits with a non‑zero status code, allowing CI pipelines, pre‑commit hooks, or runtime agents to automatically reject the non‑conforming HTML file.

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