CSV, estadística y gráficos

-- Doc example: CSV parsing, descriptive statistics and native SVG charts (all pure).
intent: "doc example: csv, stats and charts"

let raw be "month,total\njan,10\nfeb,25\nmar,17\napr,25\n"
let rows be csv_parse(raw, {"numbers": true})
let svg be chart_svg("bar", rows, {"x": "month", "y": "total", "title": "Sales"})
print("rows = " + text(length(rows)) + ",  median = " + text(median([10, 25, 17, 25])) + ",  svg = " + text(starts_with(svg, "<svg")))

test "csv_parse: rows are maps (same shape sql() returns), lossless by default"
    let plain be csv_parse("a,b\n00123,x\n")
    assert_eq(plain[0]["a"], "00123")
    assert_eq(type_of(plain[0]["a"]), "text")
    assert_eq(rows[1]["total"], 25)

test "csv round-trip survives embedded commas and quotes"
    let tricky be [{"name": "a,b", "note": "say \"hi\""}]
    assert_eq(csv_parse(csv_encode(tricky)), tricky)

test "median / percentile / histogram (NumPy semantics)"
    assert_eq(median([1, 2, 3, 4]), 2.5)
    assert_eq(percentile([1, 2, 3, 4], 25), 1.75)
    let h be histogram(range(10), 5)
    assert_eq(h["counts"], [2, 2, 2, 2, 2])
    assert_eq(length(h["edges"]), 6)

test "chart_svg is deterministic and escapes data text"
    assert(contains(svg, "<svg"))
    assert_eq(svg, chart_svg("bar", rows, {"x": "month", "y": "total", "title": "Sales"}))
    let hostile be chart_svg("pie", {"<b>x</b>": 4, "y": 2})
    assert(contains(hostile, "&lt;b&gt;"))

test "chart errors are clear and catchable"
    let msg be ""
    try
        chart_svg("bar", [])
    recover e
        set msg to e
    assert(contains(msg, "data is empty"))

test "every chart option, exercised: title/x_label/y_label/legend/colors/width/height/background"
    let multi be [{"m": "a", "sales": 10, "costs": 6}, {"m": "b", "sales": 25, "costs": 12}]
    let full be chart_svg("bar", multi, {
        "x": "m", "y": ["sales", "costs"],
        "title": "Sales vs costs", "x_label": "Month", "y_label": "USD",
        "legend": true, "colors": ["#112233", "#445566"],
        "width": 400, "height": 300, "background": "#fcfcfb"
    })
    assert(contains(full, "Sales vs costs"))
    assert(contains(full, "Month") and contains(full, "USD"))
    assert(contains(full, "sales") and contains(full, "costs"))
    assert(contains(full, "#112233") and contains(full, "#445566"))
    assert(contains(full, "viewBox=\"0 0 400 300\""))
    -- legend: false apaga los nombres de serie; el resto de las formas de datos:
    assert(contains(chart_svg("line", multi, {"x": "m", "y": "sales", "legend": false}), ">sales<") == false)
    assert(contains(chart_svg("pie", {"a": 3, "b": 1}), "<path"))
    assert(contains(chart_svg("line", [1, 2, 3]), "<polyline"))
    assert(contains(chart_svg("scatter", [[1, 2], [3, 4]]), "<circle"))

test "csv options, exercised: headers/delimiter/numbers/eol"
    let semi be csv_parse("a;b\n1;2\n", {"delimiter": ";", "numbers": true})
    assert_eq(semi[0]["b"], 2)
    let positional be csv_parse("1,2\n3,4\n", {"headers": false})
    assert_eq(positional[1][0], "3")
    assert_eq(csv_encode([{"a": "1", "b": "2"}], {"headers": ["b"], "eol": "\n"}), "b\n2\n")

test "histogram bins: integer or explicit edges (last bin closed, out-of-range dropped)"
    assert_eq(histogram([1, 2, 3, 4], [0, 2, 4])["counts"], [1, 3])
    assert_eq(histogram([-5, 1, 99], [0, 2])["counts"], [1])

test "business kinds: area/heatmap/histogram/boxplot/donut/waterfall + stack"
    let multi be [{"m": "a", "sales": 10, "costs": 6}, {"m": "b", "sales": 25, "costs": 12}]
    -- stack is an OPT on bar/area (there is no "stacked_bar" kind)
    assert(contains(chart_svg("bar", multi, {"x": "m", "y": ["sales", "costs"], "stack": true}), "<rect"))
    assert(contains(chart_svg("area", multi, {"x": "m", "y": ["sales", "costs"], "stack": true}), "<polygon"))
    -- heatmap: tidy rows (x/y/value) or a matrix (+ x_labels/y_labels); scale auto/sequential/diverging
    let cells be [{"d": "mon", "h": "9", "v": 1}, {"d": "mon", "h": "10", "v": 5}, {"d": "tue", "h": "9", "v": 9}]
    assert(contains(chart_svg("heatmap", cells, {"x": "h", "y": "d", "value": "v"}), "<rect"))
    let diverging be chart_svg("heatmap", [[-8, 0], [4, 9]], {"x_labels": ["q1", "q2"], "y_labels": ["a", "b"], "scale": "diverging", "center": 0})
    assert(contains(diverging, "<rect"))
    -- histogram plots raw numbers OR the exact map histogram() returns (same binning)
    let data be [1, 2, 2, 3, 3, 3, 9]
    assert_eq(chart_svg("histogram", data, {"bins": 4}), chart_svg("histogram", histogram(data, 4)))
    -- boxplot: >= 2 values per group; quartiles match percentile()
    assert(contains(chart_svg("boxplot", {"web": [1, 2, 3, 4, 100], "tel": [2, 3, 8, 9]}), "<circle"))
    -- donut = pie with a hole (same rules); waterfall takes DELTAS, total is opt-in
    assert(contains(chart_svg("donut", {"a": 4, "b": 2}), "<path"))
    assert(contains(chart_svg("waterfall", {"sales": 100, "costs": -40}, {"total": true}), ">Total<"))

test "theme dark + kind/opt validation errors are clear and catchable"
    let multi be [{"m": "a", "sales": 10, "costs": 6}, {"m": "b", "sales": 25, "costs": 12}]
    let dark be chart_svg("bar", multi, {"x": "m", "y": "sales", "theme": "dark"})
    assert(contains(dark, "<svg"))
    assert(dark != chart_svg("bar", multi, {"x": "m", "y": "sales"}))
    let msg be ""
    try
        chart_svg("treemap", [1])
    recover e
        set msg to e
    assert(contains(msg, "valid kinds are: area, bar, boxplot, donut, heatmap, histogram, line, pie, scatter, waterfall"))
    set msg to ""
    try
        chart_svg("pie", {"a": 1}, {"stack": true})
    recover e
        set msg to e
    assert(contains(msg, "bar, area"))
    set msg to ""
    try
        chart_svg("heatmap", [[1]], {"center": 5})
    recover e
        set msg to e
    assert(contains(msg, "diverging"))

test "svg_to_png / svg_to_pdf: every option, real deterministic bytes"
    let png be svg_to_png(svg, {"scale": 2})
    assert(contains(decode(png, "hex"), "89504e470d0a1a0a"))
    assert_eq(png, svg_to_png(svg, {"scale": 2}))
    let sized be svg_to_png(svg, {"width": 320, "background": "#ffffff", "max_pixels": 1000000})
    assert(contains(decode(sized, "hex"), "89504e470d0a1a0a"))
    let pdf be svg_to_pdf(svg, {"width": 400})
    assert(contains(decode(pdf, "hex"), "255044462d"))
    -- el techo anti-DoS avisa nombrando la opción:
    let msg be ""
    try
        svg_to_png(svg, {"width": 10000000})
    recover e
        set msg to e
    assert(contains(msg, "max_pixels"))