Waterfall Running Total Verification Mechanism in Diagram-Design

The waterfall running total verification mechanism is a nine-step pipeline implemented in scripts/verify-waterfall.py that ensures SVG waterfall charts maintain mathematical integrity by validating that declared data values match rendered geometry within strict tolerances.

The cathrynlavery/diagram-design repository employs a comprehensive waterfall running total verification mechanism to guarantee that every waterfall chart accurately represents its underlying data. This system parses SVG elements, computes running totals from delta values, and enforces visual consistency rules to prevent discrepancies between data declarations and rendered output.

Pipeline Architecture

The verification logic lives in scripts/verify-waterfall.py and processes each HTML file through a strict sequence of checks. The overall invariant demands that declared data (data-value, data-carry) and rendered geometry (positions, heights, colours) agree exactly, with zero tolerance for numeric discrepancies and only a minimal ±0.75 px tolerance for rounding artefacts.

1. SVG Parsing and Metadata Extraction

The pipeline begins by extracting all visual elements and their semantic attributes. The parse_bars() function uses RECT_RE to identify every <rect> element (bars), while parse_number() uses LINE_RE to locate <line> elements (carries). The parser captures:

• data-role, data-value, data-carry, and data-name attributes
• Geometry attributes (x, y, width, height)
• Style information and CSS transform maps

This step builds an internal representation of the chart structure before any validation occurs.

2. Structural Validation

The check_structure() function enforces the grammatical rules of waterfall charts. It verifies that the chart contains at least a start total, one delta, and an end total. All totals must be positive numbers, while deltas must carry explicit signs (e.g., +64 or -12). The function also validates that the total number of bars and subtotals remains within the defined budget constraints.

3. Transform Detection

Geometric integrity requires that coordinates remain static after calculation. The check_transforms() function scans for SVG <g> or <svg> groups containing transform or style attributes that would shift bar or carry positions after coordinate baking. If detected, the verifier reports a failure because the script would see different geometry than the browser renders.

4. Running Total Computation

The running_levels() function walks the declared bars from left-to-right, adding or subtracting each delta to maintain an accurate running total. It returns a list of (level_before, level_after) tuples for every bar. If any step produces a non-finite or negative total, the verification aborts immediately.

5. Scale Calculation and Geometry Verification

Using the start total’s height as a reference, the script calculates a shared scale factor:

scale = start.h / start.value

The check_geometry() function then recomputes expected top and bottom Y-coordinates for every bar using this scale. It validates that actual y and height values match expectations within GEOMETRY_TOLERANCE (±0.75 px).

6. Carry Line Validation

Between adjacent bars, horizontal <line> elements with data-carry attributes must bridge the gaps accurately. The check_carries() function verifies that:

• Each line spans the complete horizontal gap between bars
• The declared data-carry value matches the computed running level
• The Y-position aligns with baseline - scale * level

7. Printed Value Verification

The printed_values() and check_printed() functions scan <text> elements positioned on bars. They strip markup, parse the displayed number, and confirm that the printed value—including explicit signs for deltas—matches the bar’s declared data-value.

8. Sign Treatment and Visual Consistency

The check_sign_treatment() function enforces the visual grammar of waterfall charts. It confirms that positive and negative deltas use distinct fill colours (tint versus paper) and that at most one bar receives the accent stroke. The function also validates colour mappings across the two supported themes.

9. Error Aggregation and Reporting

The verify_file() and main() functions collect all validation errors into a list. If no errors are found, the script reports OK. Otherwise, it prints detailed diagnostic messages per file before exiting.

Command-Line Usage

Verify a single waterfall HTML file:

python3 scripts/verify-waterfall.py skills/diagram-design/assets/example-waterfall.html

Verify all shipped examples in the repository:

python3 scripts/verify-waterfall.py --all

Successful verification outputs:

OK skills/diagram-design/assets/example-waterfall.html

Programmatic Integration

Import the verification logic directly into Python applications:

from pathlib import Path
from scripts.verify_waterfall import verify_file

# Load an HTML file and get a list of validation errors (empty list = success)

errors = verify_file(Path("skills/diagram-design/assets/example-waterfall.html"))
if errors:
    print("Found problems:")
    for e in errors:
        print("  -", e)
else:
    print("Waterfall passes all checks")

Common Validation Errors

When a delta lacks an explicit sign in its data-value, the parse_signed() function returns signed=False, triggering check_structure() to report:

'Headcount': a delta must declare an explicit sign in data-value; got "64"

If a carry line's Y-coordinate deviates from the calculated level, check_carries() produces:

gap between 'Headcount' and 'Reserved inst.': carry drawn at y=140 but the 304 level sits at y=130.5

Missing carry lines between bars generate:

carry 240: no carry spans it

Summary

• The waterfall running total verification mechanism processes charts through nine sequential checks in scripts/verify-waterfall.py.
• MATLAB: The system validates mathematical integrity by computing running totals via running_levels() and verifying geometry against a shared scale derived from the start total.
• Strict parsing requires explicit signs for all delta values and detects illegal CSS transforms that could alter rendered geometry.
• Sub-pixel precision allows ±0.75 px tolerance for rounding artefacts, but enforces zero tolerance on numeric data mismatches.
• The verifier supports both command-line batch processing (--all) and programmatic integration via verify_file().

Frequently Asked Questions

What triggers a "delta must declare an explicit sign" error?

This error occurs when the data-value attribute of a delta bar contains a number without a leading + or - sign. According to the waterfall grammar defined in docs/adr/0011-waterfall-is-a-running-total-grammar.md, all delta values must explicitly declare their direction to ensure unambiguous running total calculations. The parse_signed() function checks for this prefix, and check_structure() reports the violation if missing.

How does the verifier handle CSS transforms on chart elements?

The check_transforms() function actively scans for transform attributes or inline styles on <g> and <svg> elements that would modify coordinates after the initial geometry calculation. If detected, verification fails immediately because such transforms create a discrepancy between the coordinates seen by the verifier and those rendered by the browser. All geometric positioning must be baked into element attributes before verification.

What is the significance of the 0.75 pixel tolerance in geometry checks?

The GEOMETRY_TOLERANCE constant (±0.75 px) accounts for floating-point rounding differences between JavaScript rendering engines and Python calculation logic. While numeric data values must match exactly with zero tolerance, minor sub-pixel deviations in SVG coordinate calculations are permissible. This tolerance prevents false negatives while maintaining strict visual accuracy standards.

Can the verification script process multiple waterfall charts simultaneously?

Yes. Running python3 scripts/verify-waterfall.py --all processes every shipped example in the repository sequentially. The main() function iterates through all target files, aggregates errors per file, and provides a comprehensive report. For CI/CD pipelines, the script exits with a non-zero status if any validation fails, making it suitable for automated quality gates.

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