htmlineage 0.1.0-alpha.0 → 0.1.0-beta.0

package/skills/htmlineage/references/format.md

@@ -0,0 +1,218 @@
+# The lineage graph: field reference
+
+## Files
+
+A report is one HTML file. Its lineage graph is one JSON object kept in
+`.lineage/<report-stem>.json`, beside the report. For `report.html` that is
+`.lineage/report.json`. You write the graph there. `htmlineage check` embeds
+it in the report as a `<script type="application/lineage+json">` block, so you
+never write that block by hand.
+
+The graph is a header and a `nodes` map keyed by id:
+
+```json
+{
+  "lineage": "1.0",
+  "nodes": {
+    "q1": {},
+    "v1": {},
+    "f1": {},
+    "i1": {}
+  }
+}
+```
+
+## Kinds of node
+
+Every value on the page reaches it by one path: source, then view, then
+figure, then insight. A node's `step` says which it is.
+
+```json
+{
+  "step": "source",
+  "kind": "sql",
+  "desc": "Retention by channel and cohort month, January to August 2026",
+  "mart": "marts.retention_by_channel",
+  "period": { "from": "2026-01-01", "to": "2026-08-31" },
+  "sql": "select\n    channel,\n    cohort_month,\n    retention_30d\nfrom marts.retention_by_channel\nwhere cohort_month between '2026-01-01' and '2026-08-31'",
+  "columns": ["channel", "cohort_month", "retention_30d"]
+}
+```
+
+```json
+{
+  "step": "source",
+  "kind": "external",
+  "type": "csv",
+  "ref": "q3-targets.csv",
+  "given": "A CSV with columns channel, target_retention, shared by the builder"
+}
+```
+
+```json
+{
+  "step": "view",
+  "from": ["q1"],
+  "desc": "Average 30-day retention for each channel and cohort month",
+  "sql": "select\n    channel,\n    cohort_month,\n    avg(retention_30d) as retention\nfrom q1\ngroup by channel, cohort_month",
+  "columns": ["channel", "cohort_month", "retention"],
+  "encoding": { "x": "cohort_month", "y": "retention", "series": "channel" }
+}
+```
+
+```json
+{
+  "step": "figure",
+  "from": ["v1"],
+  "desc": "Paid social retention for August 2026",
+  "sql": "select retention\nfrom v1\nwhere channel = 'paid_social'\n  and cohort_month = '2026-08-01'",
+  "value": 0.466,
+  "display": "46.6%",
+  "label": "Paid social retention, August"
+}
+```
+
+```json
+{
+  "step": "figure",
+  "from": ["f1", "f2"],
+  "desc": "Change in paid social retention from July to August, relative to July",
+  "expr": "(f1 - f2) / f2",
+  "value": 0.1175,
+  "display": "11.8%",
+  "label": "Change in paid social retention, August vs July"
+}
+```
+
+```json
+{
+  "step": "insight",
+  "from": ["f3"],
+  "text": "Paid social retention rose by a relative 11.8%."
+}
+```
+
+A claim that rests on nothing you queried is still written down, marked
+`"ungrounded": true` with `"from": []`.
+
+## What may rest on what
+
+- A view's `from` lists sources and views.
+- A figure with `sql` lists sources and views in `from`. A figure with `expr`
+  lists figures.
+- An insight's `from` lists views, figures and insights. Never a source:
+  sources do not appear on the page.
+- A figure never gets its own query. It picks one cell from a view or source
+  that exists, or it derives from other figures.
+
+## Ids
+
+- Lowercase letters, digits and `_`, starting with a letter.
+- Start with the step's letter: `q` for a sql source, `x` for an external
+  source, `v` for a view, `f` for a figure, `i` for an insight. For example
+  `q1`, `x1`, `v1`, `f1`, `i1`.
+- Each id is used once.
+
+## Binding to the page
+
+Put `data-lineage="<id>"` on the element that shows the node:
+
+```html
+<span data-lineage="f3">11.8%</span>
+<p data-lineage="i1">
+  Paid social retention rose by a relative
+  <span data-lineage="f3">11.8%</span>.
+</p>
+<div data-lineage="v1"><svg></svg></div>
+<table data-lineage="v2"></table>
+```
+
+- Views, figures and insights bind. Sources never do.
+- Every view, figure and insight binds at least once. A figure shown in
+  several places binds in each.
+- A number inside a sentence sits in its own `data-lineage` span.
+- A chart binds on the container around the SVG, not the SVG.
+- The attribute adds no style and no behaviour.
+
+## Fields
+
+Each table below lists every field a node of that kind may carry. Required
+means an error if it is missing. Expected means a warning if it is missing.
+
+### sql source
+
+| Field       | Required | Type   | Use                                                                 |
+| ----------- | -------- | ------ | ------------------------------------------------------------------- |
+| `step`      | required | string | `"source"`                                                          |
+| `kind`      | required | string | `"sql"`                                                             |
+| `desc`      | expected | string | One line, 120 characters at most: what the query pulls, in words    |
+| `how`       | optional | string | Leave out                                                           |
+| `mart`      | expected | string | The mart the query reads                                            |
+| `period`    | expected | object | The pinned range, `{ "from": "2026-01-01", "to": "2026-08-31" }`    |
+| `sql`       | expected | string | The query, with the period as literal dates                         |
+| `columns`   | expected | list   | Output column names                                                 |
+| `rows`      | optional | object | Up to 10 rows, columnar: `{ "column": [values] }`; or `null`        |
+| `transform` | optional | string | A judgement the SQL does not show, such as "excluded the test week" |
+
+### external source
+
+| Field       | Required | Type   | Use                                           |
+| ----------- | -------- | ------ | --------------------------------------------- |
+| `step`      | required | string | `"source"`                                    |
+| `kind`      | required | string | `"external"`                                  |
+| `type`      | expected | string | What kind of thing it is, such as `csv`       |
+| `ref`       | expected | string | How a reader can find it, such as a file name |
+| `given`     | expected | string | What you were handed, in words                |
+| `columns`   | optional | list   | Column names, if it has them                  |
+| `rows`      | optional | object | Up to 10 rows, columnar; or `null`            |
+| `transform` | optional | string | A judgement the data does not show            |
+
+### view
+
+| Field        | Required | Type   | Use                                                                              |
+| ------------ | -------- | ------ | -------------------------------------------------------------------------------- |
+| `step`       | required | string | `"view"`                                                                         |
+| `from`       | required | list   | Ids of the sources and views it reads                                            |
+| `desc`       | expected | string | One line, 120 characters at most: what it computes and how, in words             |
+| `sql`        | required | string | A SELECT over the parents, which it names by id as table names                   |
+| `columns`    | expected | list   | Output column names                                                              |
+| `encoding`   | optional | object | For charts: `x`, `y`, `series`, `visual`, each a string                          |
+| `rows`       | optional | object | Up to 10 rows, columnar; or `null`. A view shown as a table needs none           |
+| `transform`  | optional | string | A judgement the SQL does not show                                                |
+| `ungrounded` | optional | bool   | `true` when it has no source: `from` may then be empty and `sql` may be left out |
+
+### figure
+
+| Field        | Required             | Type          | Use                                                                                           |
+| ------------ | -------------------- | ------------- | --------------------------------------------------------------------------------------------- |
+| `step`       | required             | string        | `"figure"`                                                                                    |
+| `from`       | required             | list          | Ids it reads: sources and views with `sql`, figures with `expr`                               |
+| `desc`       | expected             | string        | One line, 120 characters at most: how it was computed, in words                               |
+| `sql`        | one of `sql`, `expr` | string        | A single SELECT returning one cell, ideally a plain pick of one column from one row           |
+| `expr`       | one of `sql`, `expr` | string        | A SQL scalar expression over figure ids, such as `(f1 - f2) / f2`. No comments                |
+| `value`      | expected             | number/string | The number or name the page shows                                                             |
+| `display`    | expected             | string        | The text exactly as shown on the page, such as `"46.6%"`                                      |
+| `label`      | expected             | string        | What the number is, in words                                                                  |
+| `transform`  | optional             | string        | A judgement the SQL does not show                                                             |
+| `ungrounded` | optional             | bool          | `true` when it has no source: `from` may then be empty and neither `sql` nor `expr` is needed |
+
+### insight
+
+| Field        | Required | Type   | Use                                                                   |
+| ------------ | -------- | ------ | --------------------------------------------------------------------- |
+| `step`       | required | string | `"insight"`                                                           |
+| `from`       | required | list   | Ids of the views, figures and insights the claim rests on             |
+| `text`       | required | string | The claim, as it reads on the page                                    |
+| `transform`  | optional | string | A judgement behind the claim that its sources do not show             |
+| `ungrounded` | optional | bool   | `true` when the claim rests on nothing here: `from` may then be empty |
+
+### header
+
+| Field          | Required | Type   | Use                                                    |
+| -------------- | -------- | ------ | ------------------------------------------------------ |
+| `lineage`      | required | string | The format version, `"1.0"`                            |
+| `nodes`        | required | object | Every node, keyed by id                                |
+| `report_id`    | optional | string | A UUID, minted at the first build and kept on rebuilds |
+| `built_at`     | optional | string | When the report was built, an ISO timestamp            |
+| `builder_tool` | optional | string | The tool that built it, such as `report-builder`       |
+| `signature`    | optional | string | Leave out                                              |

package/skills/htmlineage/references/review.md

@@ -0,0 +1,79 @@
+# Reviewing a report
+
+Use this when you are asked to review a report someone else built, or to check
+one before it is shared. Your job is to show the reviewer what each number and
+claim rests on and where that is weak. You do not decide whether the report is
+right, and you do not change it.
+
+## 1. Read the check summary
+
+```
+npx htmlineage check <report>.html --no-embed
+```
+
+`--no-embed` leaves the file untouched. Read the summary. It lists errors
+last, but take them first:
+
+- **Errors.** The lineage is broken. Say so first: nothing below can be traced
+  with confidence until the builder fixes it, and `htmlineage sql` refuses
+  a report with errors.
+- **Ungrounded.** Claims and numbers that rest on nothing queried: a forecast,
+  an opinion, outside knowledge. List each one with its text. They may be
+  fine, but the reader should know they are not backed by data.
+- **External.** Data the builder was handed: a CSV, a number someone said.
+  Name each one and who it came from (its `given`). A reviewer may want to
+  confirm it with that person.
+- **Warnings.** Each is a gap a reader could trip on. The ones that matter
+  most: a number in prose with no lineage (C2), a page that shows a different
+  value from the graph (C3), and a source without literal dates (C7).
+
+## 2. Trace the numbers that carry the report
+
+Pick the headline numbers and the ones the main claims rest on. For each, take
+its id from the element's `data-lineage` attribute and run:
+
+```
+npx htmlineage sql <report>.html --id <id>
+```
+
+Read the script against the claim on the page:
+
+- **Population.** Does the source cover who the claim is about? A claim about
+  all customers over a source filtered to one region is a finding.
+- **Period.** Do the literal dates match the period the page names?
+- **Comparison.** Is a change measured against the base the text says (last
+  month, last year, target)?
+- **Definition.** Does the metric match its name: a 30-day rate computed over
+  30 days, a share over the right total?
+- **Descriptions.** Does each step's `desc` say what its SQL does? A `desc`
+  that promises more than the SQL is a finding.
+
+`npx htmlineage sql <report>.html` with no `--id` composes the whole report into
+one script, if the reviewer wants everything at once.
+
+## 3. Rerun, if you can and are asked to
+
+If you have read access to the warehouse and the reviewer wants the numbers
+reproduced, run the script from step 2 and compare its result with the figure's
+`display` on the page. Run it as it is; do not rewrite it first. Report any
+difference with both values. Because every source has literal dates, the script
+should give the same result as when the report was built, unless the
+underlying data has changed since.
+
+Never run anything that writes to the warehouse.
+
+## 4. Report back
+
+A short list, most serious first:
+
+1. Errors, if any.
+2. Findings from step 2 and step 3: the id, what the page says, what the SQL
+   does, and why it matters.
+3. Ungrounded claims and external data, so the reader knows what to take on
+   trust.
+4. Anything you checked and found sound, briefly. "f1, f3 and f5 trace cleanly
+   to the August retention query" is useful to a reviewer.
+
+Do not edit the report or its graph. If the builder should change something,
+say what and why. For a person to click through the lineage themselves, point
+them to `npx htmlineage view <report>.html`.

package/src/check/rules.js

@@ -62,7 +62,9 @@ export function parseDisplayNumber(text) {
  * Run the check rules over a graph and its page.
  * @param {unknown} graph  as returned by readGraph; may be malformed
  * @param {{ bindings: {id,text,offset}[], prose: {text,node,offset}[] }} page
- * @returns {{ code, severity, node: string|null, field: string|null, message: string }[]}
+ * @returns {{ code, severity, node: string|null, field: string|null, message: string, fix: string|null }[]}
+ *   `message` says what is wrong; `fix`, when there is one, what to change.
+ *   C7 and C8 list several findings in one message and have no `fix`.
  */
 export function checkRules(graph, page) {
   const nodes = graph?.nodes;
@@ -72,13 +74,14 @@ export function checkRules(graph, page) {
   const node = (id) => (has(id) && isObject(nodes[id]) ? nodes[id] : null);
 
   const issues = [];
-  const report = (code, n, field, message) =>
+  const report = (code, n, field, message, fix) =>
     issues.push({
       code,
       severity: RULES[code].severity,
       node: n,
       field: field ?? null,
       message,
+      fix: fix ?? null,
     });
 
   checkC1(nodes, has, node, page, report);
@@ -99,7 +102,15 @@ function checkC1(nodes, has, node, page, report) {
     if (seen.has(id)) continue;
     if (!has(id)) {
       seen.add(id);
-      report("C1", id, null, `data-lineage="${id}" resolves to no node`);
+      report(
+        "C1",
+        id,
+        null,
+        `data-lineage="${id}" resolves to no node`,
+        id.trim() === ""
+          ? "put a node id in the attribute, or remove the attribute"
+          : "add a node with that id to the graph, or correct the id on the page",
+      );
       continue;
     }
     const n = node(id);
@@ -109,7 +120,8 @@ function checkC1(nodes, has, node, page, report) {
         "C1",
         id,
         null,
-        `\`${id}\` is a source; bind a figure over it instead`,
+        `\`${id}\` is a source`,
+        "bind a figure over it instead",
       );
     }
   }
@@ -125,6 +137,7 @@ function checkC1(nodes, has, node, page, report) {
         id,
         null,
         `${n.step} is not bound to any element on the page`,
+        `add data-lineage="${id}" to the element that shows it`,
       );
     }
   }
@@ -178,9 +191,23 @@ function checkC3(node, page, report) {
     }
     if (bad.length > 0) {
       const quoted = bad.map((t) => `"${t}"`).join(", ");
-      const against =
-        display !== null ? `display is "${display}"` : `value is ${value}`;
-      report("C3", id, "display", `page shows ${quoted} but ${against}`);
+      if (display !== null) {
+        report(
+          "C3",
+          id,
+          "display",
+          `page shows ${quoted} but display is "${display}"`,
+          "copy `display` onto the page exactly, or update `value` and `display` if the page is right",
+        );
+      } else {
+        report(
+          "C3",
+          id,
+          "display",
+          `page shows ${quoted} but value is ${value}`,
+          "correct the page text or `value`, and set `display` to what the page shows",
+        );
+      }
     }
   }
 }
@@ -209,12 +236,19 @@ function checkC5(nodes, has, node, report) {
       }
     }
 
-    const parts = [];
+    // Each problem is its own issue, so each keeps its own fix.
+    const problem = (message, fix) => report("C5", id, "from", message, fix);
 
     const unknown = n.from.filter((p) => !has(p));
-    if (unknown.length > 0) {
-      parts.push(
-        `\`from\` names ${unknown.join(", ")}, which ${unknown.length > 1 ? "are not nodes" : "is not a node"}`,
+    if (unknown.length > 1) {
+      problem(
+        `\`from\` names ${unknown.join(", ")}, which are not nodes`,
+        "add those nodes, or remove them from `from`",
+      );
+    } else if (unknown.length === 1) {
+      problem(
+        `\`from\` names ${unknown[0]}, which is not a node`,
+        "add that node, or remove it from `from`",
       );
     }
 
@@ -226,38 +260,45 @@ function checkC5(nodes, has, node, report) {
     if (knownParents.length > 0) {
       let ok;
       let message;
+      let fix;
       if (step === "view") {
         ok = knownParents.every(
           (p) => p.step === "source" || p.step === "view",
         );
         message = "a view rests on sources and views only";
+        fix = "point `from` at the sources and views it selects from";
       } else if (step === "figure" && exprIds === null) {
         ok = knownParents.every(
           (p) => p.step === "source" || p.step === "view",
         );
         message = "a figure with `sql` rests on sources and views only";
+        fix = "to compute it from figures, use `expr` instead of `sql`";
       } else if (step === "figure") {
         ok = knownParents.every((p) => p.step === "figure");
         message = "a figure with `expr` rests on figures only";
+        fix = "to pick it from a view, use `sql` instead of `expr`";
       } else {
         ok = knownParents.every((p) => p.step !== "source");
         message = "an insight rests on views, figures and insights only";
+        fix = "put a figure over the source and rest the insight on that";
       }
-      if (!ok) parts.push(message);
+      if (!ok) problem(message, fix);
     }
 
     if (step === "figure" && exprIds !== null) {
       const missing = exprIds.filter((r) => !n.from.includes(r));
-      if (missing.length > 0) {
-        parts.push(
-          `\`expr\` uses ${missing.join(", ")}, which ${missing.length > 1 ? "are not in `from`" : "is not in `from`"}`,
+      if (missing.length > 1) {
+        problem(
+          `\`expr\` uses ${missing.join(", ")}, which are not in \`from\``,
+          "add them to `from`",
+        );
+      } else if (missing.length === 1) {
+        problem(
+          `\`expr\` uses ${missing[0]}, which is not in \`from\``,
+          "add it to `from`",
         );
       }
     }
-
-    if (parts.length > 0) {
-      report("C5", id, "from", parts.join("; "));
-    }
   }
 }
 
@@ -300,6 +341,7 @@ function checkC6(nodes, has, report) {
             rotated[0],
             "from",
             `cycle ${[...rotated, rotated[0]].join(" -> ")}`,
+            `break the loop: take ${rotated[1] ?? rotated[0]} out of ${rotated[0]}'s \`from\`, or remove another link in it`,
           );
         }
       } else if (!state.has(next)) {

package/src/check/summary.js

@@ -137,7 +137,7 @@ export function formatSummary(summary, { color = false } = {}) {
         node: issue.node ?? "graph",
         tag: `${issue.code} ${severity}`,
         paint: severity === "error" ? RED : YELLOW,
-        detail: issue.message,
+        detail: issue.fix ? `${issue.message}; ${issue.fix}` : issue.message,
       });
     }
   }

package/src/commands/check.js

@@ -26,7 +26,10 @@ Options
   --no-embed       Check only; leave the report file untouched
   --json           Print the summary as JSON instead of prose
   --quiet          Print nothing; rely on the exit code
-  -h, --help       Show this help`;
+  -h, --help       Show this help
+
+What each issue code means and how to fix it:
+  https://github.com/htmlineage/htmlineage/blob/main/CHECKS.md`;
 
 export const options = {
   graph: { type: "string" },

package/src/commands/view.js

@@ -11,10 +11,12 @@ export const summary = "Serve the report beside its lineage";
 
 export const usage = `htmlineage view <report.html> [options]
 
-Serves a two-pane page on localhost: the report on the left, the lineage of
-whatever you click on the right. Reads the report and its graph, nothing
-else. No database, no credentials. The viewer itself makes no request off
-this machine; the report loads what it would load in any browser.
+Serves a two-pane page on 127.0.0.1: the report on the left, the lineage of
+whatever you click on the right. It serves the report, its graph and files
+beside the report such as images, never a file whose name starts with a dot
+or any other file outside the report's folder. No database, no credentials.
+The viewer itself makes no request off this machine; the report loads what
+it would load in any browser.
 
 Options
   --port <number>  Port to serve on (default: the first free port from 7171)

package/src/graph/expr.js

@@ -21,7 +21,8 @@ export function exprRefs(source, ids) {
 
 /**
  * Whether the text can be read at all: brackets and quotes close, and there
- * is no comment. Returns null, or { message, position } (0-based).
+ * is no comment. Returns null, or { message, position } (0-based), with a
+ * `fix` when there is something to change beyond the obvious.
  */
 export function exprProblem(source) {
   const open = [];
@@ -36,7 +37,8 @@ export function exprProblem(source) {
     } else if (source.startsWith("--", i) || source.startsWith("/*", i)) {
       const mark = source.slice(i, i + 2);
       return {
-        message: `\`${mark}\` starts a comment; put notes in the node's \`label\``,
+        message: `\`${mark}\` starts a comment`,
+        fix: "put notes in the node's `label`",
         position: i,
       };
     } else if (source[i] === "(") open.push(i);

package/src/graph/schema.js

@@ -50,7 +50,7 @@ const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
 const ISO_TIMESTAMP =
   /^(\d{4}-\d{2}-\d{2})T(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/;
 
-const HEADER_FIELDS = new Set([
+export const HEADER_FIELDS = new Set([
   "lineage",
   "report_id",
   "built_at",
@@ -63,7 +63,7 @@ const HEADER_FIELDS = new Set([
 const COMMON_FIELDS = ["step", "transform"];
 const DERIVED_FIELDS = [...COMMON_FIELDS, "from", "ungrounded"];
 
-const FIELDS = {
+export const FIELDS = {
   sql: new Set([
     ...COMMON_FIELDS,
     "kind",
@@ -120,18 +120,20 @@ function describe(value) {
 
 /**
  * Validate a parsed graph. Never throws on bad input; returns a flat list of
- * issues, each `{ code, severity, node, field, message }`. `node` is null for
- * header problems. An empty list means the shape is sound.
+ * issues, each `{ code, severity, node, field, message, fix }`. `node` is null
+ * for header problems; `fix` is what to change, or null. A few messages still
+ * carry advice of their own, such as the style findings C8 lists. An empty list means the shape is sound.
  */
 export function validateGraph(graph) {
   const issues = [];
-  const report = (code, node, field, message) =>
+  const report = (code, node, field, message, fix) =>
     issues.push({
       code,
       severity: RULES[code].severity,
       node,
       field: field ?? null,
       message,
+      fix: fix ?? null,
     });
 
   if (!isObject(graph)) {
@@ -201,7 +203,8 @@ function checkNode(id, node, report) {
       "S2",
       id,
       null,
-      `\`${id}\` is not a valid id: use lowercase letters, digits and _, starting with a letter`,
+      `\`${id}\` is not a valid id`,
+      "use lowercase letters, digits and _, starting with a letter",
     );
   }
 
@@ -226,7 +229,13 @@ function checkNode(id, node, report) {
   // they are what makes a node unreadable or uncomposable.
   const need = (field, test, what) => {
     if (node[field] === undefined) {
-      report("S4", id, field, `${node.step} is missing \`${field}\``);
+      report(
+        "S4",
+        id,
+        field,
+        `${node.step} is missing \`${field}\``,
+        `add it: ${what}`,
+      );
       return false;
     }
     if (!test(node[field])) {
@@ -265,13 +274,27 @@ function checkNode(id, node, report) {
     may("desc", isString, "a string");
     if (node.ungrounded !== true) want("desc", DESC_HINT);
     const problem = isString(node.desc) && descProblem(node.desc);
-    if (problem) report("S9", id, "desc", problem);
+    if (problem) {
+      report(
+        "S9",
+        id,
+        "desc",
+        problem,
+        `keep it to one line of ${MAX_DESC} or fewer`,
+      );
+    }
   }
 
   if (allowed) {
     for (const field of Object.keys(node)) {
       if (!allowed.has(field)) {
-        report("S5", id, field, `unknown field \`${field}\` on a ${node.step}`);
+        const article = /^[aeiou]/.test(node.step) ? "an" : "a";
+        report(
+          "S5",
+          id,
+          field,
+          `unknown field \`${field}\` on ${article} ${node.step}`,
+        );
       }
     }
   }
@@ -290,9 +313,8 @@ function checkNode(id, node, report) {
 /** Why a `desc` is not one short line, or null. Length wins over a break. */
 function descProblem(desc) {
   const length = [...desc].length;
-  const rule = `keep it to one line of ${MAX_DESC} or fewer`;
-  if (length > MAX_DESC) return `\`desc\` is ${length} characters; ${rule}`;
-  if (/[\r\n]/.test(desc)) return `\`desc\` has a line break; ${rule}`;
+  if (length > MAX_DESC) return `\`desc\` is ${length} characters`;
+  if (/[\r\n]/.test(desc)) return "`desc` has a line break";
   return null;
 }
 
@@ -352,7 +374,8 @@ function checkDerived(id, node, need, may, report) {
       "C4",
       id,
       "from",
-      "`from` is empty; list the parents, or set `ungrounded: true` if there are none",
+      "`from` is empty",
+      "list the parents, or set `ungrounded: true` if there are none",
     );
   }
 }
@@ -393,14 +416,16 @@ function checkFigure(id, node, may, want, report) {
       "C9",
       id,
       null,
-      "figure has both `sql` and `expr`; keep exactly one",
+      "figure has both `sql` and `expr`",
+      "keep exactly one",
     );
   } else if (!hasSql && !hasExpr && node.ungrounded !== true) {
     report(
       "C9",
       id,
       null,
-      "figure has neither `sql` nor `expr`; add one, or set `ungrounded: true`",
+      "figure has neither `sql` nor `expr`",
+      "add one, or set `ungrounded: true`",
     );
   }
 
@@ -412,6 +437,7 @@ function checkFigure(id, node, may, want, report) {
         id,
         "expr",
         `cannot read \`${node.expr}\` at character ${problem.position + 1}: ${problem.message}`,
+        problem.fix,
       );
     }
   }