Linting Rules

Clean diagrams aren’t accidental. They’re enforced.

tlDiagram’s linter checks every diagram for architectural anti-patterns. Run it with tld validate.

These are heuristic checks for common issues that lead to messy, unreadable diagrams. They’re advisory and constantly evolving.

Configuring

The level is a global setting:

tld config set validation.level 2

Or override per run:

tld validate --strictness 3
tld validate --strictness 1

Suppressing rules

Disable specific rule codes:

tld config set validation.exclude_rules ARC002,ARC203

Or enable additional rules beyond the selected level:

tld config set validation.include_rules ARC001,ARC004

validation.allow_low_insight is a shortcut that turns ARC005 (Low Insight Ratio) off.

The rules

Level 1 — structural

Code	Rule	What it flags
ARC001	High Density	A view has too many elements to read
ARC002	Isolated Element	An element has no connectors in its view
ARC003	Shared Context	A reused element has no connectors in one of its views
ARC004	Depth Mismatch	The view hierarchy is too flat
ARC005	Low Insight Ratio	A view has mostly elements and few connectors
ARC006	Dead-End Drilldown	An element owns a view with no content
ARC007	Abstraction Leak	Functions or classes placed at the root level
ARC008	Unresolved Connector	A connector endpoint has no element definition

Level 2 — metadata

Code	Rule	What it flags
ARC102	Missing Tech	An element has no technology field
ARC207	Unknown Technology	A technology isn’t in the catalog

Level 3 — polish

Code	Rule	What it flags
ARC201	Missing Desc	An element has no description
ARC202	Generic Naming	A vague, non-domain-specific name
ARC203	Missing Label	A connector has no label
ARC204	Duplicate Name	Multiple elements share a display name
ARC205	Low Grounding	A view has too few source-linked elements
ARC206	Low Link Coverage	Links cover too little of the indexed code directories

Drill into any rule with its code:

tld validate ARC001

How warnings work

Warnings appear in tld validate output and the editor. They are advisory unless you pass --strict, which makes them fail validation. Run tld validate rules for the current catalog.

A warning means “this might be a problem.” It’s your call whether to address it or acknowledge it.