Complexity Budgets for Different Diagram Types in diagram-design: 9 Nodes, 12 Edges, and Source Limits

The diagram-design tool enforces a uniform complexity budget of 9 drawable nodes and 12 edges across all supported diagram types, including flowcharts, sequence diagrams, state diagrams, and ER diagrams.

The cathrynlavery/diagram-design repository provides a Mermaid diagram analysis pipeline that flags overly dense visuals before they are rendered. Understanding the complexity budgets for different diagram types helps authors keep their diagrams concise and readable. These budgets are evaluated after parsing in the analyze() function inside skills/diagram-design/scripts/mermaid_extract.py and apply uniformly regardless of diagram kind.

Uniform Node and Edge Budgets

All diagram types share the same two complexity budget thresholds. The tool does not differentiate between flowcharts, sequence diagrams, state diagrams, or ER diagrams when checking for visual density.

Drawable Node Limit (9 Nodes)

In skills/diagram-design/scripts/mermaid_extract.py, the analyze() function calculates how many leaf nodes will actually be drawn. It then sets the budget flag via info["over_node_budget"] = drawable > 9 at lines 1106–1109. If a diagram contains more than nine rendered nodes, it is marked as over-node-budget.

Edge Limit (12 Edges)

The same analyze() function checks the edge count with info["over_edge_budget"] = len(diagram.edges) > 12. Any diagram containing more than twelve edges is flagged as over-edge-budget. The test harness in scripts/verify-motion.py at lines 303–306 verifies that this 12-edge limit is enforced correctly.

Input Safeguards and Hard Parser Limits

The repository distinguishes between user-facing complexity budgets and internal parser guardrails. The latter exist to prevent pathological inputs from crashing the tool.

Source File Size Cap (4 MiB)

Before parsing begins, the tool rejects oversized raw inputs. The constant MAX_SOURCE_BYTES = 4 * 1024 * 1024 is defined at lines 32–33 of mermaid_extract.py. The _read_bounded() helper reads the file and calls _fail() if the source exceeds 4 MiB.

Parser-Level Node and Edge Ceilings (2000 / 5000)

In skills/diagram-design/scripts/mermaid_input.py, the constants MAX_NODES = 2000 and MAX_EDGES = 5000 protect the extraction pipeline. The add_node() and add_edge() methods abort processing with _fail() if these thresholds are reached at lines 33–34. These are hard performance limits, not the final complexity budgets.

How the Budget Logic Is Implemented

The following snippets from the cathrynlavery/diagram-design source show exactly where the limits are applied.

Final Analysis Checks

After parsing completes, the analyze() function evaluates the drawable node count and total edge count:

# In `analyze()` – after the diagram is fully parsed

drawable = len(leaves)                     # leaf nodes that will be drawn

info = {
    ...
    "over_node_budget": drawable > 9,      # > 9 leaves → budget violation

    "over_edge_budget": len(diagram.edges) > 12,  # > 12 edges → violation

    ...
}

Parser Hard Limits

The input parser rejects diagrams that exceed its internal capacity:

# Parsing limits – enforced when adding nodes/edges

def add_node(...):
    if len(self.nodes) >= MAX_NODES:
        _fail(f"node limit exceeded (max {MAX_NODES})")   # 2000 limit

def add_edge(...):
    if len(self.edges) >= MAX_EDGES:
        _fail(f"edge limit exceeded (max {MAX_EDGES})")   # 5000 limit

Source Size Guard

The file reader prevents excessive memory usage from large source files:

# Source-size guard – applied when reading the input file

def _read_bounded(path: Path) -> str:
    data = path.open("rb").read(MAX_SOURCE_BYTES + 1)
    if len(data) > MAX_SOURCE_BYTES:
        _fail(f"source exceeds the {MAX_SOURCE_BYTES // (1024 * 1024)} MiB limit")

Summary

• The complexity budgets for different diagram types are uniform: 9 drawable nodes and 12 edges.
• Violations are detected in analyze() inside skills/diagram-design/scripts/mermaid_extract.py.
• Raw source files are capped at 4 MiB via MAX_SOURCE_BYTES.
• Parser-level limits of 2000 nodes and 5000 edges prevent abuse but do not override the final readability budget.

Frequently Asked Questions

Do complexity budgets vary by diagram type in diagram-design?

No. The tool applies the same 9-node and 12-edge budget to flowcharts, sequenceDiagram, stateDiagram-v2, and erDiagram alike. The analyze() function checks these limits after parsing without branching on diagram kind.

What happens when a diagram exceeds the node or edge budget?

The analysis dictionary sets "over_node_budget": true or "over_edge_budget": true at lines 1106–1109 of mermaid_extract.py. These flags signal that the diagram is visually dense, but processing continues so the caller can decide how to handle the violation.

Why does the parser allow 2000 nodes when the budget is only 9?

The MAX_NODES = 2000 and MAX_EDGES = 5000 constants in skills/diagram-design/scripts/mermaid_input.py are hard safety limits to prevent denial-of-service from pathological inputs. The 9-node and 12-edge values are stylistic complexity budgets used in the final analysis to encourage readable diagrams.

Where is the 4 MiB source-size limit defined?

The limit is defined as MAX_SOURCE_BYTES = 4 * 1024 * 1024 in skills/diagram-design/scripts/mermaid_extract.py at lines 32–33. The _read_bounded() helper enforces this cap when reading raw Mermaid source files from disk.

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