Your reports belong in code review

A report you can’t diff is a report you can’t review. That’s the argument for making the report a definition — JSON you store, version and read like any other file in the repository.

The usual failure mode is a report nobody can review. When the layout lives in imperative code — a loop here, a doc.text() call there — the pull request shows plumbing rather than intent. The reviewer approves the code and hopes about the output.

A definition turns that around. Now the layout is data: you declare the columns, headers and totals once, and they sit beside the code that feeds them. Changing the report means editing JSON. The diff is the change.

A diff you can read

Adding an amount column to an invoice is one entry in the definition:

{ "columns": [
  { "header": "Item", "value": "{{ @.item }}", "width": 50 },
  { "header": "Qty", "value": "{{ @.qty }}", "width": 15 },
  { "header": "Amount", "value": "{{ round(@.qty * @.unitPrice, 2) }}",
    "style": { "align": "right", "format": "currency" }, "width": 35 }
] }

That’s the whole review. No renderer internals, no coordinate arithmetic. The third column is the new one, and a reader who has never opened quario’s docs can still see what it computes.

The amount interpolates a bare number and declares "format": "currency" beside it. The same line then reads as money on the page, and reaches a workbook as a number the spreadsheet can sum.

round(…, 2) is there because a currency value is a whole number of its currency’s minor units. A number format would hide a stray 242.70000000000002 on the page. The workbook cell behind it would not.

Nothing to escape, nothing to eval

Definitions stay safe to review for the same reason they’re safe to run: the expressions inside {{ … }} parse into closures. There’s no eval, no new Function and no generated code anywhere in the render path. A definition arriving from a teammate, or from a customer, is data you read rather than a program you audit.

A reviewer who has read the definition has read everything the report will do.