Skip to content

Markdown plan: deep-diff nested values and avoid math-renderer errors #163

Description

@bwl21

Problem

The Markdown plan renderer added by #144 / #155 can put complete old and new nested JSON values into a Markdown table cell for a small change inside a dynamic-group ruleset.

This has two consequences:

  1. The actual change is almost impossible to review because it is hidden inside two very large JSON documents.

  2. Escaped JSON arrays such as \[ and \] are interpreted as display-math delimiters by Markdown renderers with KaTeX/MathJax support. The report then shows errors such as:

    Extra open brace or missing close brace
    

The underlying plan and ruleset JSON are valid; only the generated Markdown presentation is broken.

Example

A ruleset update only adds one fallback source:

{
  "var": "groupmemberfieldoption.value"
}

as the first entry of a nested coalesce array. The Markdown report currently renders the complete dynamic value before and after the change in one table row.

Expected behavior

Do not place nested comparisons inside Markdown table cells. The summary table should remain compact and link to a separate, stable per-resource detail section:

| Resource | Action | Summary | Details |
| --- | --- | --- | --- |
| OJBP overview | Update | Dynamic ruleset changed | [View diff](#change-group-ojbp-2026-27) |

The linked section can then use proper multiline Markdown without table-cell escaping:

### Dynamic ruleset: OJBP overview

<a id="change-group-ojbp-2026-27"></a>

```diff
+ dynamic.ruleset.query.params.computedFields[0].value.case[0]
+   .then.concat[2].coalesce[0] = { "var": "groupmemberfieldoption.value" }
```

For nested updates, calculate and render a structural/deep diff containing only changed paths, for example conceptually:

dynamic.ruleset.query.params.computedFields[0].value.case[0]
  .then.concat[2].coalesce[0]
  + { "var": "groupmemberfieldoption.value" }

The precise path notation may differ, but the report should:

  • show only added, removed, or changed nested values;
  • retain enough surrounding context to identify the affected computed field;
  • produce deterministic ordering;
  • distinguish array insertion/removal from replacement;
  • use deterministic, collision-free anchors for links from the summary table;
  • keep the canonical plan computation unchanged; and
  • fall back safely when a semantic or structural diff is unavailable.

Technical JSON fallback content must be emitted as code, a fenced block, or another Markdown-safe representation. It must not generate \[ / \] sequences that math-enabled Markdown renderers interpret as formulas.

Acceptance criteria

  • A one-node change in a dynamic ruleset does not print the complete old and new rulesets.
  • Nested comparisons are outside Markdown table cells; the table links to a separate detail section.
  • Every details link resolves to a deterministic and unique anchor in the same document.
  • Nested object and array changes are represented by stable paths and old/new values.
  • The generated document renders without KaTeX/MathJax parse errors.
  • Tests cover JSON arrays, braces, underscores, backslashes, pipes, backticks, and multiline strings.
  • Tests render or parse the output with both ordinary GFM and a math-enabled Markdown configuration.
  • The full raw values remain available in JSON output for machine consumers.

Relation to #144

#144 already specified that the main report should not dump raw nested JSON when a value can be described meaningfully and required safe escaping. This issue tracks the remaining nested-update and math-delimiter case after #155.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    triageUnsorted intake — decide in the weekly sweep

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions