#!/usr/bin/env python3 """Verify the invariants a sankey can silently break. A sankey's claim is that **ribbon width is volume and volume is conserved**. Every way of breaking that claim renders perfectly. Nothing errors, nothing disappears, and no existing gate would notice: `lint-skin.py` reads colors, fonts and the a11y contract; `verify-geometry.py` reads label masks against later-painted nodes. Neither compares a ribbon against the number printed beside it, and neither adds up what enters a node against what leaves it. Five checks, in the order a defect is likely to reach review: 1. CONSERVATION - what enters a node must leave it. This is the check the type exists for. A ribbon quietly narrowed between two stages is invisible: the eye has no reference width to compare against, so 5,200 minutes arriving and 4,800 departing looks exactly like 5,200 arriving and 5,200 departing. Volume that genuinely leaves the story must be drawn as a named node in the final column, not allowed to evaporate mid-diagram. 2. COLUMN TOTALS - every stage must carry the same total. This is conservation read the other way, and it is what catches a whole node being forgotten rather than a single ribbon being wrong. 3. RIBBON WIDTH CONSTANCY - a ribbon must be the same width at both ends. A ribbon that widens as it travels invents volume out of nothing; one that narrows destroys it. Because the two ends are hundreds of pixels apart, a taper of several pixels reads as perspective rather than as an error. 4. VALUE FIDELITY - a node's drawn height must match the value printed beside it, on one scale shared by every node in the figure. Checked as RELATIVE error, for the reason the treemap checker gives: an absolute threshold passes exactly the small nodes most likely to be wrong. 5. CONTROL-POINT PLACEMENT - both Bezier controls belong on the corridor midline, each at the y of the edge it steers. B'(1) = 3(P3 - P2), so the arrival tangent is set by the last control alone: on the midline it is exactly horizontal and the ribbon plugs into its bar flat. On the target's x the control coincides with the endpoint, the first derivative vanishes, and the eye reads B''(1) instead - steeply off horizontal, so every ribbon visibly skews into its bar. Every endpoint is still correct, so nothing else here would catch it. `--all` adds two more. The light, dark and full-editorial variants must be geometrically identical - they are one figure in three skins, and three hand-maintained copies only stay in agreement if something checks. And any ```svg element pattern in `references/type-sankey.md` must be a literal excerpt of the shipped example: a code sample is the one piece of geometry nothing renders, so it rots in silence the first time the layout moves, and it is exactly what the next contributor copies. The shipped reference carries no such sample today; the gate binds the first one anyone adds. Both checks live here rather than in a build script, because a generator that is not run proves nothing. Guards sit under all of that, because the worst outcome for a checker is not a missed defect but a clean exit having read nothing. A that does not parse as a ribbon is reported rather than skipped, and so is a ribbon end that lands on no node bar, a file whose node bars fall outside the size window, and a figure with bars but no ribbons - each would otherwise quietly remove a shape from the sums, or leave every check to pass vacuously. `--all` additionally refuses to run unless all three shipped variants are present, because a glob that matches nothing reads no files, finds no faults, and exits 0. The widest guards run first. Everything here reads raw coordinates, which is only sound while the markup means what it says - so a file carrying a transform, a clip path, a mask or a hidden element is REFUSED, not checked. Any one of those breaks all five invariants above while every number this checker reads stays correct, and catching them properly would mean reimplementing a browser. Underneath that sits the stance the rest of the file depends on, and it is worth stating plainly because it was learned the expensive way. Every guard here began as a BLOCKLIST, and each was patched three times over: stroke-width but not fill, geometry but not containers, `0` but not `0%`, `4foo` but not `4cap`. A blocklist fails OPEN - whatever it was never told about is certified - and an audit of this file found seventeen constructs it certified as clean, each of which renders a figure that lies while every number read here stays correct. An `` erases every ribbon under it. `` holds geometry that never draws. `systemLanguage` suppresses an element. A nested `.*?)", re.IGNORECASE | re.DOTALL) # Reading attributes with a `name="value"` shape looked fine and was wrong four # ways at once, each of which turns EVERY guard below into a no-op without # touching a coordinate: a single-quoted or unquoted value is simply not seen, # so style='stroke-width:30' sails past the ban on style; a repeated attribute # resolves the opposite way from a browser, which keeps the FIRST; a character # reference is never decoded, so fill="none" reads as a colour named # "none"; and a ">" inside a quoted value ends the element early for any # pattern built on [^>]*. So this is a small tokeniser rather than a shape # match, and it is the ONE place markup becomes attributes. OPEN_TAG_RE = re.compile( r"""<(?P[a-zA-Z][\w:.-]*)(?P(?:"[^"]*"|'[^']*'|[^>"'])*)/?>""" ) ATTRIBUTE_RE = re.compile( r"""(?P[^\s=/>]+)\s*(?:=\s*(?P"[^"]*"|'[^']*'|[^\s>]*))?""" ) COMMENT_RE = re.compile(r"", re.DOTALL) def attributes(raw: str) -> dict: """One element's attributes, resolved the way a browser resolves them.""" found: dict = {} for m in ATTRIBUTE_RE.finditer(raw): name = m.group("name").lower() value = m.group("value") or "" if len(value) >= 2 and value[0] in ('"', "'") and value[-1] == value[0]: value = value[1:-1] if name not in found: # a browser keeps the FIRST of a repeat found[name] = html.unescape(value) return found def elements(source: str): """Every element in document order, with comments blanked first so one can neither hide an element nor contribute one that never renders. Offsets are preserved, so a finding still points at the right line.""" blanked = COMMENT_RE.sub(lambda m: " " * len(m.group(0)), source) for m in OPEN_TAG_RE.finditer(blanked): yield m.group("tag").lower(), attributes(m.group("attrs")), m.start() TAG_RE = re.compile(r"<[^>]+>") # The value line is the only label in a node's block that STARTS with a digit: # the name starts with a letter and the sublabel with an em dash. Anchor on the # leading number ONLY - requiring a unit word right after it silently stops # matching the moment the format changes to something like "9,400 - 78%", and a # value check that attaches to nothing passes everything. VALUE_RE = re.compile(r"^(?P\d[\d,]*(?:\.\d+)?)(?![\d,.])") # A node bar is a thin vertical rect inside the plot band. The legend keys are # 16x8 and the two background rects are the full viewBox, so both fall out on # width and on the band test. BAR_MIN_W, BAR_MAX_W = 5.0, 14.0 BAR_MIN_H = 2.0 # a small flow is still a node; swatches fall out on width and band # The band's floor sits between the lowest plot row (bottom 456 in the shipped # example) and the legend rule at y=492 — a bar is above it, a swatch below. BAND_TOP, BAND_BOTTOM = 30.0, 480.0 COLUMN_EPS = 1.5 # x values this close are the same column EDGE_EPS = 2.0 # a ribbon end this close to a bar edge is attached to it RIBBON_WIDTH_TOL = 0.5 # px, a ribbon's two ends NODE_TOL = 0.75 # px, in vs out at one node COLUMN_TOL = 1.0 # px, stage against stage SCALE_TOL = 4.0 # %, relative, drawn height vs printed value CONTROL_TOL = 0.5 # px, a Bezier control against where it must sit NON_VOLUME_MAX_STROKE = 2.0 # px, the widest a non-ribbon line may be drawn # Constructs that decouple what renders from what the markup literally says. A # checker that reads coordinates cannot reason about any of them, so a file # using one is refused rather than certified. Scoped to sankey files only - other # types use transforms legitimately, and this checker never sees them. OPAQUE_CONSTRUCTS = ( (re.compile(r"\btransform\s*=", re.IGNORECASE), "a transform"), (re.compile(r"\bclip-path\s*[=:]", re.IGNORECASE), "a clip path"), (re.compile(r"\bmask\s*=", re.IGNORECASE), "a mask"), (re.compile(r"\bdisplay\s*[:=]\s*[\"']?\s*none", re.IGNORECASE), "a hidden element"), # `collapse` is the second spelling of hidden, and on everything except a # table row it means exactly `hidden`. Matching one of the two was the same # mistake as matching one spelling of zero. (re.compile(r"\bvisibility\s*[:=]\s*[\"']?\s*(?:hidden|collapse)", re.IGNORECASE), "a hidden element"), ) # Self-test at import: a pattern that cannot match is a check that does not # exist, and it fails open. That has now happened twice - an escaping slip # turns every \b into a literal backspace, and the first version of this # guard only looked at the six patterns named at the time, so the seventh # inherited the bug. So the test is over the SOURCE, not over a list someone # has to remember to extend. if chr(8) in Path(__file__).read_text(encoding="utf-8"): raise SystemExit( "verify-sankey.py contains a literal backspace: a \\b was written " "through a shell that ate an escape level, and every pattern using one " "has silently stopped matching. Rebuild the pattern with chr(92)." ) def line_of(source: str, offset: int) -> int: return source.count("\n", 0, offset) + 1 def plain(body: str) -> str: return html.unescape(TAG_RE.sub("", body)).strip() class Bar: __slots__ = ("x", "y", "w", "h", "offset", "value", "label", "values", "inflow", "outflow") def __init__(self, x: float, y: float, w: float, h: float, offset: int) -> None: self.x, self.y, self.w, self.h, self.offset = x, y, w, h, offset self.value: float | None = None self.label = "" self.values: list[tuple[float, str]] = [] self.inflow = 0.0 self.outflow = 0.0 @property def bottom(self) -> float: return self.y + self.h @property def right(self) -> float: return self.x + self.w class Ribbon: __slots__ = ("x0", "y0t", "y0b", "x1", "y1t", "y1b", "controls", "offset") def __init__(self, nums: list[float], offset: int) -> None: # index: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 # M x0,y0t C xm,y0t xm,y1t x1,y1t L x1,y1b C xm,y1b xm,y0b x0,y0b Z self.x0, self.y0t = nums[0], nums[1] self.x1, self.y1t = nums[6], nums[7] self.y1b = nums[9] self.y0b = nums[15] # (control x, control y, the y it must share) for all four handles. self.controls = ( (nums[2], nums[3], nums[1]), # leaving, top edge (nums[4], nums[5], nums[7]), # arriving, top edge (nums[10], nums[11], nums[9]), # leaving target, bottom edge (nums[12], nums[13], nums[15]), # arriving source, bottom edge ) self.offset = offset @property def source_h(self) -> float: return self.y0b - self.y0t @property def target_h(self) -> float: return self.y1b - self.y1t @property def midline(self) -> float: return (self.x0 + self.x1) / 2 def length_px(raw: str | None) -> tuple[float | None, str | None]: """A length in px, or a reason it cannot be read. The ONE place a length becomes a number, for every attribute that carries one: stroke widths, bar widths, bar heights, bar coordinates. There were briefly three, each having learned a different part of the job - one knew units, one took the numeric part and threw the unit away (so a bar declared `8em` measured 8px and every sum below was computed against a bar that is not that size), and one demanded bare digits in a fixed attribute order. A relative unit is refused rather than guessed. `em` resolves against a font and `%` and `vw` against a viewport, none of which this checker sees, so any number it produced for them would be invented. """ parsed = LENGTH_RE.match((raw or "").strip()) if not parsed: return None, f"{raw!r} is not a length this checker can read" unit = parsed.group("unit").lower() if unit not in PX_PER_UNIT: return None, ( f"{raw!r} carries {unit!r}, which resolves against a font or viewport " f"this checker never sees" ) return float(parsed.group("number")) * PX_PER_UNIT[unit], None def stroke_width_px(attrs: dict) -> tuple[float | None, str | None]: """Stroke width in px, defaulting to SVG's initial value when absent.""" raw = attrs.get("stroke-width") if raw is None: return 1.0, None # SVG's initial value width, why = length_px(raw) return width, (f"stroke-width={why}" if why else None) def fill_alpha(value: str) -> tuple[float | None, str | None]: """Alpha of a CSS colour, or a reason it cannot be read. None means opaque. Written once, for every syntax, because writing it per-syntax is how this file came to reject `rgb(235 108 54 / 0.16)` while accepting `#eb6c3600`. """ colour = value.strip().lower() if not colour: return None, None if colour in {"none", "transparent"}: return 0.0, None hexed = HEX_COLOR_RE.match(colour) if hexed: digits = hexed.group("digits") if len(digits) in {3, 6}: return None, None # no alpha channel: opaque if len(digits) == 4: return int(digits[3] * 2, 16) / 255, None if len(digits) == 8: return int(digits[6:], 16) / 255, None return None, f"{value!r} is not a 3, 4, 6 or 8 digit hex colour" func = FUNC_COLOR_RE.match(colour) if not func: return None, None # a named colour: opaque args = func.group("args") token = None if "/" in args: # modern: fn(a b c / alpha) token = args.split("/", 1)[1].strip() else: parts = [a.strip() for a in args.split(",")] if len(parts) == 4: # legacy: fn(a, b, c, alpha) token = parts[3] elif len(parts) != 1 and len(parts) != 3: return None, f"{value!r} has {len(parts)} components" if token is None: return None, None # no alpha given: opaque alpha, why = alpha_value(token) if why: return None, f"{value!r} has an alpha this checker cannot read" return alpha, None def alpha_value(raw: str) -> tuple[float | None, str | None]: """A CSS as the browser resolves it, or a reason it cannot be. The ONE place an alpha becomes a number, because there were three and each had learned a different half of the grammar. Two rules, and both are what the browser does rather than what the text says: - a percentage is the number over 100, so `50%` and `0.5` are one value; - the result is CLAMPED to [0, 1]. This is the half that bites. `-0.5` renders as 0 - fully transparent - so a ribbon painted that way is a gap in the flow while its authored text still reads as a colour with an alpha. Taking -0.5 to mean "not zero, therefore visible" certifies a figure with a hole in it. Above 1 clamps to 1 and is merely redundant. """ parsed = ALPHA_TOKEN_RE.match(raw.strip()) if not parsed: return None, f"{raw!r} is not a number this checker can read" alpha = float(parsed.group("number")) if parsed.group("pct"): alpha /= 100 return max(0.0, min(1.0, alpha)), None def paints_a_fill(attrs: dict) -> tuple[bool | None, str | None]: """Whether a shape paints its interior, or a reason that cannot be decided. A ribbon carries its volume in its FILL, so a canonical ribbon that paints no fill occupies the arithmetic without occupying the page: conservation still balances, every width is still correct, and the reader sees a gap where the flow should be. Absent fill is SVG's default black, which paints. Returns a reason rather than raising. A malformed value is a defect in the diagram and belongs in the findings list; letting it escape as a ValueError turns a CI diagnosis into a traceback, which tells the contributor nothing about what is wrong with their file. """ alpha, why = fill_alpha(attrs.get("fill", "")) if why: return None, why if alpha == 0: return False, None raw = attrs.get("fill-opacity", "").strip() if raw: opacity, why = alpha_value(raw) if why: return None, f"fill-opacity={raw!r} is not a number" if opacity == 0: return False, None return True, None def is_dashed(value: str) -> bool: """Whether a stroke-dasharray actually produces a dashed line. "Non-empty" is not the test. An invalid pattern makes the browser drop the property and draw a SOLID line, and so does an all-zero one - so `stroke-dasharray="banana"`, `"0"`, `"0 0"`, `"none"` and a negative dash all render exactly like no dash at all. Per SVG: every value must be a non-negative length, and at least one must be positive. """ tokens = [t for t in re.split(r"[,\s]+", value.strip()) if t] if not tokens: return False lengths = [] for token in tokens: parsed = LENGTH_RE.match(token) if not parsed: return False if parsed.group("unit").lower() not in CSS_LENGTH_UNITS: return False # invalid unit: the whole declaration goes length = float(parsed.group("number")) if length < 0: return False lengths.append(length) # The list alternates dash, gap, dash, gap; an odd list is repeated once to # make it even. So it takes a positive DASH and a positive GAP to draw a # dashed line: "4000 0" is a 4000-long dash with nothing between, which is # a solid line with extra steps, and "0 4" is a run of nothing at all. if len(lengths) % 2: lengths = lengths * 2 dashes, gaps = lengths[0::2], lengths[1::2] return any(d > 0 for d in dashes) and any(g > 0 for g in gaps) def is_non_volume_path(attrs: dict) -> bool: """The one non-ribbon path the reference permits: dashed, hairline, unfilled. Every clause is load-bearing. Unfilled alone would let a fill="none" path with a 40px stroke render as a band and skip every check below, because a stroke that wide is exactly what a reader reads as volume. The dash pattern is what marks the line as a different kind of relationship rather than a thin ribbon, and the width cap keeps it from growing into one. """ if attrs.get("fill", "").strip().lower() != "none": return False if not is_dashed(attrs.get("stroke-dasharray", "")): return False width, _ = stroke_width_px(attrs) return width is not None and width <= NON_VOLUME_MAX_STROKE def contained(top: float, bottom: float, bar: Bar) -> bool: """Both edges of a ribbon end inside the bar it attaches to. Testing only the top edge lets a ribbon start just above the bar's foot and run far past it while still counting as attached, which credits the volume to the wrong node. """ return bar.y - EDGE_EPS <= top and bottom <= bar.bottom + EDGE_EPS def parse_bars(source: str) -> list[Bar]: """The node bars, read through the same attribute scan as everything else. This used to be its own regex requiring bare digits in a fixed attribute order, which meant `width="8px"` - a perfectly ordinary SVG length, and one `certify_readable` accepts - silently produced no bar at all, and the figure was then rejected for having too few. Two parsers for one value is the same fault this file has now been fixed for four times, so there is one. A bar that paints no fill is not a bar. `paints_a_fill` was already applied to ribbons for exactly this reason - a shape that occupies the arithmetic without occupying the page - and a node bar lies the same way: conservation balances, the stage totals agree, and the reader sees a column that is not there. """ bars: list[Bar] = [] for tag, attrs, offset in elements(source): if tag != "rect": continue painted, _why = paints_a_fill(attrs) if painted is False: continue # invisible: not a bar, and not measured box = [length_px(attrs.get(k))[0] for k in ("x", "y", "width", "height")] if any(v is None for v in box): continue x, y, w, h = box if not (BAR_MIN_W <= w <= BAR_MAX_W) or h < BAR_MIN_H: continue if y < BAND_TOP or y + h > BAND_BOTTOM: continue bars.append(Bar(x, y, w, h, offset)) return bars def parse_ribbons(source: str, findings: list[str], name: str) -> list[Ribbon]: ribbons: list[Ribbon] = [] for m in PATH_RE.finditer(source): attrs = attributes(m.group("attrs")) d = attrs.get("d", "") commands, nums = path_tokens(d) if commands == RIBBON_COMMANDS and len(nums) == RIBBON_COORDS: paints, why = paints_a_fill(attrs) if why: findings.append( f"{name}:{line_of(source, m.start())}: ribbon {why} — this checker " f"cannot tell whether it renders, and an invisible ribbon still " f"counts in every conservation sum" ) continue if not paints: findings.append( f"{name}:{line_of(source, m.start())}: ribbon paints no fill " f"(fill={attrs.get('fill', '(absent)')!r}) — it would still be " f"counted in every conservation sum while rendering nothing, so the " f"arithmetic balances over a gap the reader can see. A ribbon " f"carries its volume in its fill" ) continue ribbons.append(Ribbon(nums, m.start())) continue # The reference permits exactly one non-ribbon path: a DASHED, HAIRLINE, # unfilled stroke for a relationship that is not a volume. Match that # description and nothing wider. "Unfilled" alone is far too loose — a # fill="none" path with a 40px stroke renders as a band indistinguishable # from a ribbon and would skip every check below. Width is what a reader # reads as volume, so the exemption is capped on stroke width and # requires the dash pattern that marks it as a different kind of line. if is_non_volume_path(attrs): continue findings.append( f"{name}:{line_of(source, m.start())}: is neither a readable ribbon " f"(expected M/C/L/C/Z with {RIBBON_COORDS} coordinates; found " f"{'/'.join(commands) or 'none'} with {len(nums)}) nor an unfilled path — " f"this checker cannot confirm its width is conserved, so it must not ship " f"unexamined. A non-volume relationship takes fill=\"none\"" ) return ribbons def attach_values(source: str, bars: list[Bar], findings: list[str], name: str) -> None: """Bind each bar to the value line printed in its label block. The shipped examples label a node three ways, one per column style: outside the figure anchored `end` (value LEFT of the bar), centred in the gutter anchored `middle` (value ABOVE the bar), and outside anchored `start` (value RIGHT of the bar). Each convention gets its own tight window rather than one loose proximity search: nearest-bar binding looks right until a node is shorter than its own label block, at which point the value belonging to the bar above drifts into the next bar's window and proximity hands it to the wrong node - silently, since both then look internally consistent. Here a value that fits more than one bar's window is a FINDING, not a coin toss. """ for m in TEXT_RE.finditer(source): attrs = attributes(m.group("attrs")) # Through the same length parser as everything else. This was a bare # float() wrapped in `except ValueError: continue`, so a label written # - legal SVG, rendering in exactly the same place - # was silently dropped, and the bar it belonged to lost its printed # value from validation while the file still passed. x, why_x = length_px(attrs.get("x")) y, why_y = length_px(attrs.get("y")) if why_x or why_y or x is None or y is None: continue # unreadable coordinates are refused by certify_readable body = plain(m.group("body")) hit = VALUE_RE.match(body) if not hit: continue anchor = attrs.get("text-anchor", "start") if anchor == "end": # value line LEFT of its bar, outer column candidates = [ bar for bar in bars if bar.x - 60 <= x <= bar.x - 2 and bar.y - 4 <= y <= bar.bottom + 20 ] elif anchor == "middle": # value line ABOVE its bar, in the stage gutter candidates = [ bar for bar in bars if abs(x - (bar.x + bar.w / 2)) <= 8 and bar.y - 40 <= y <= bar.y - 2 ] else: # value line RIGHT of its bar, outer column candidates = [ bar for bar in bars if bar.right + 2 <= x <= bar.right + 60 and bar.y - 4 <= y <= bar.bottom + 20 ] if not candidates: continue # legend copy and annotations may open with a digit if len(candidates) > 1: findings.append( f"{name}:{line_of(source, m.start())}: the value line {body!r} sits " f"where it could label {len(candidates)} different node bars — a " f"reader has the same ambiguity, so the label must move until it " f"belongs to exactly one node" ) continue host = candidates[0] # Record EVERY value-shaped line that binds, not just the first. Taking # the first and moving on lets a second, contradictory number sit in the # same block: the checker validates the one it read, and the reader is # shown the one it ignored. host.values.append((float(hit.group("num").replace(",", "")), body)) if host.value is None: host.value = host.values[0][0] host.label = body # === CERTIFY ONLY WHAT CAN BE READ ========================================== # # Every guard above this line is a BLOCKLIST, and each was patched three times: # stroke-width but not fill, geometry but not containers, `0` but not `0%`, # `4foo` but not `4cap`. A blocklist fails OPEN - whatever it has not been told # about is certified - and SVG has far more ways to render differently than any # list will hold. An audit of this file found seventeen, every one of which the # checks below certified as clean: `` erases every ribbon # under it, `` holds geometry that never draws, `systemLanguage` suppresses # an element, a nested `[^{}]*)\}") CSS_COMMENT_RE = re.compile(r"/\*.*?\*/", re.DOTALL) DEFS_BLOCK_RE = re.compile(r"]*>(?P.*?)", re.IGNORECASE | re.DOTALL) GEOMETRIC_ATTRS = ("x", "y", "width", "height", "x1", "y1", "x2", "y2", "cx", "cy", "r") LEGEND_SWATCH = (16.0, 8.0) def certify_readable(name: str, source: str) -> list[str]: """Refuse anything this checker cannot read, before it reads anything else. An empty result means every construct in the file is one the checks below genuinely understand - which is the only condition under which their silence is evidence that the figure is honest rather than evidence that it is opaque. """ findings: list[str] = [] def refuse(offset: int, why: str) -> None: findings.append(f"{name}:{line_of(source, offset)}: {why}") svg_roots = 0 for tag, attrs, offset in elements(source): if tag not in ALLOWED_TAGS: refuse(offset, f"uses <{tag}>, which this checker does not read. An element " f"it cannot read may paint, hide, clone or move a ribbon while " f"every coordinate here stays correct, so refusing is the " f"honest answer — teach it what <{tag}> does before allowing it") continue for attribute in sorted(attrs): if attribute not in ALLOWED_ATTRS: refuse(offset, f"<{tag}> carries {attribute!r}, which this checker does " f"not read. Conditional processing, filters, clones and " f"paint servers all arrive as an attribute and all change " f"what renders without changing a number here") if tag in SVG_TAGS and ("style" in attrs or "class" in attrs): carried = " and ".join(k for k in ("style", "class") if k in attrs) refuse(offset, f"<{tag}> carries {carried}, which can set a paint property " f"from outside the attributes this checker reads — and on a " f"container it reaches every ribbon below it. A fill decides " f"whether a shape renders at all, and stroke width is apparent " f"volume: under stroke-width:30 a ribbon draws 30px wider than " f"the fill it is measured by. Paint belongs in attributes on " f"the element it paints, so what renders is what is measured") if tag == "svg": svg_roots += 1 if svg_roots > 1: refuse(offset, "nests a second .*?)```", re.DOTALL) ELEMENT_RE = re.compile( r"<(?Prect|text|path)\b(?P[^>]*?)(?:/>|>(?P.*?))", re.DOTALL | re.IGNORECASE, ) WHITESPACE_RE = re.compile(r"\s+") def squashed(text: str) -> str: return WHITESPACE_RE.sub(" ", text).strip() def check_reference_excerpt(findings: list[str]) -> None: """The type reference's element pattern must be a real excerpt. A code sample in a doc is the one piece of geometry nothing renders, so it drifts silently the first time the layout moves - and it is precisely what a contributor copies when building the next diagram of this type. Requiring it to appear verbatim in the shipped example makes the sample as trustworthy as the figure it came from. """ if not REFERENCE_DOC.exists(): findings.append(f"missing type reference: {REFERENCE_DOC.name}") return light = ASSET_DIR / VARIANTS[0] if not light.exists(): return haystack = squashed(light.read_text(encoding="utf-8")) for block in SVG_BLOCK_RE.finditer(REFERENCE_DOC.read_text(encoding="utf-8")): for element in ELEMENT_RE.finditer(block.group("body")): needle = squashed(element.group(0)) if needle not in haystack: findings.append( f"{REFERENCE_DOC.name}: the element pattern shows " f"{needle[:72]!r}, which is not in {VARIANTS[0]} — a sample " f"nothing renders drifts the moment the layout moves, and it " f"is what the next contributor will copy. Paste a real excerpt" ) def check_variants(paths: list[Path]) -> list[str]: if len(paths) < 2: return [] findings: list[str] = [] # Compare against the light minimal, not whatever the glob sorted first, so # the diagnostic names the canonical file a reader would go and look at. base = next((p for p in paths if p.name == VARIANTS[0]), paths[0]) reference = geometry(base) for path in paths: if path == base: continue other = geometry(path) if other == reference: continue extra = [line for line in other if line not in reference] missing = [line for line in reference if line not in other] detail = (extra + missing)[:3] findings.append( f"{path.name}: geometry differs from {base.name} " f"({len(extra)} added, {len(missing)} missing; e.g. {'; '.join(detail)}) — " f"the variants are one figure in three skins, so only tokens may differ. " f"Regenerate them from a single model instead of editing each by hand" ) return findings def targets(args: argparse.Namespace) -> list[Path]: if args.all: return sorted(ASSET_DIR.glob("example-sankey*.html")) return [Path(p) for p in args.paths] def main() -> int: parser = argparse.ArgumentParser( description="Verify sankey flow conservation, ribbon width and value fidelity." ) parser.add_argument("paths", nargs="*", help="HTML files to check") parser.add_argument("--all", action="store_true", help="check every shipped sankey example") args = parser.parse_args() if not args.all and not args.paths: parser.print_help() return 2 paths = targets(args) # A glob that matches nothing is the quietest way for a gate to stop # gating: it reads no files, finds no faults, and exits 0. --all knows # exactly which three files the type ships, so it can tell the difference # between "clean" and "not there". if args.all: missing = [name for name in VARIANTS if not (ASSET_DIR / name).exists()] if missing: print( f"error: --all expects the three shipped variants in " f"{ASSET_DIR.relative_to(ROOT).as_posix()}; missing " f"{', '.join(missing)}", file=sys.stderr, ) return 2 elif not paths: parser.print_help() return 2 findings: list[str] = [] for path in paths: if not path.exists(): print(f"error: {path} does not exist", file=sys.stderr) return 2 findings.extend(check(path)) if args.all: findings.extend(check_variants(paths)) check_reference_excerpt(findings) for finding in findings: print(finding) if findings: print(f"\n{len(findings)} sankey finding(s) across {len(paths)} file(s).") return 1 print( f"OK sankey: {len(paths)} file(s), flow conserved at every node, stages carry " f"equal totals, ribbons hold their width" + (", variants share one geometry" if args.all else "") ) return 0 if __name__ == "__main__": raise SystemExit(main())