Skip to content

feat: Substitute variables in markdown tiles - #3246

Merged
kodiakhq[bot] merged 7 commits into
mainfrom
drew/variables-markdown-mcp
Sep 30, 2026
Merged

kodiakhq[bot] merged 7 commits into
mainfrom
drew/variables-markdown-mcp

Conversation

@pulpdrew

@pulpdrew pulpdrew commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This PR extends variable substitution to markdown tiles. By default, variables are substituted using the new markdown format, which escapes values for markdown. Invalid references are flagged, and MCP validation/prompts have been updated.

Security: By default, variable values are markdown-escaped, and markdown tiles already block scripts and raw HTML, so no XSS can occur. Users can opt out of escaping (for example, in markdown code blocks) by using a non-markdown variable from (eg. ${var:csv}).

Screenshots or video

Screenshot 2026-09-29 at 3 30 08 PM

How to test on Vercel preview

  • Create a dashboard
  • Add a variable
  • Reference the variable in a Markdown tile

References

  • Linear Issue: Closes HDX-5508
  • Related PRs:

@changeset-bot

changeset-bot Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 832e069

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages
Name Type
@hyperdx/common-utils Patch
@hyperdx/app Patch
@hyperdx/api Patch
@hyperdx/otel-collector Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@vercel

vercel Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
hyperdx-oss Ready Ready Preview Sep 30, 2026 1:44pm UTC
hyperdx-storybook Ready Ready Preview Sep 30, 2026 1:44pm UTC

Request Review

@github-actions github-actions Bot added the review/tier-3 Standard — full human review required label Sep 29, 2026
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

🟡 Tier 3 — Standard

Introduces new logic, modifies core functionality, or touches areas with non-trivial risk.

Why this tier:

  • Diff size: 263 production lines changed (Tier 2 max: < 250)
  • Cross-layer change: touches frontend (packages/app) + backend (packages/api) + shared utils (packages/common-utils)

Review process: Full human review — logic, architecture, edge cases.
SLA: First-pass feedback within 1 business day.

Stats
  • Production files changed: 7
  • Production lines changed: 263 (+ 292 in test files, excluded from tier calculation)
  • Branch: drew/variables-markdown-mcp
  • Author: pulpdrew

To override this classification, remove the review/tier-3 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

@github-actions

Copy link
Copy Markdown
Contributor

Duplicate code analysis

No new duplicate code introduced by this PR.


jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 128 in total (1.82%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

Comment thread packages/app/src/DBDashboardPage.tsx Outdated
annotations,
isLive,
readOnly,
variables,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Every tile now re-renders when any filter changes

Adding the full variables array to the tile render memo's deps rebuilds every tile's chart element, not just markdown tiles, whenever any filter selection changes. Lines 582-601 go out of their way to avoid this by serializing only the referenced variables into tileVariables. Use tileVariables for substitution (it now includes markdown references via filterReferencedVariables). Pass a stable, serialized list of variable names for the unknown-variable check.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

config.displayType !== DisplayType.Markdown
config.displayType === DisplayType.Markdown
) {
if (config.markdown) validate(config.markdown, 'markdown');

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — MCP warns about $word prose in markdown even when the dashboard has no variables

HDXMarkdownChart deliberately skips validation when !variables?.length, because nothing is substituted and $HOME or $PATH in a runbook note is just prose. getTileVariableWarnings still validates against [], so every markdown tile with a $word gets 'unknown variable … Available variables: (none)'. Skip the markdown validation when variables.length === 0 so it matches the UI.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 critical or 🟠 major in code this PR adds or changes: fix before asking for review.
  • 🔵 minor in code this PR changes: your call. Fix if small, otherwise reply.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    severity. Reply with one sentence; if it is critical, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

4 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 4 minor

1 posted as inline comment(s) on the changed lines. 3 listed below.

Findings outside the changed lines

3 minor
  • 🔵 packages/app/src/components/SQLEditor/variableCompletions.tsx:436 — PromQL ${name:csv} completion lost the sentence explaining when to use it → The refactor cut the PromQL csv help text down to 'Comma-separated and unquoted, with no escaping.' It dropped 'Use it to interpolate something that is not a matcher value, such as a metric or label name.' That sentence is the only guidance on when csv is the right choice over the regex default. Put it back in COMPLETION_FORMATS.promql.csv.
  • 🔵 packages/app/src/components/SQLEditor/variableCompletions.tsx:438 — The lucene and markdown entries in COMPLETION_FORMATS are never read → Only COMPLETION_FORMATS.sql and COMPLETION_FORMATS.promql are used (lines 159 and 194). The empty lucene: {} and markdown: {} entries exist only because the map is typed Record<TemplateLanguage, …>. Type it as Partial<Record<TemplateLanguage, …>>, or use two named constants, and remove the entries nothing uses.
  • 🔵 packages/api/src/mcp/prompts/dashboards/content.ts:70 — MCP prompt doesn't say that the default markdown escaping shows up as literal backslashes inside code spans → escapeMarkdownValue backslash-escapes all ASCII punctuation. Inside `$service` or a fenced block, a value like frontend-proxy therefore renders as frontend\-proxy, because code spans don't process escapes. The prompt only says values are 'escaped', so an agent writing variables inside code gets visible backslashes. Add a line to the MARKDOWN TILES section: use ${name:csv} inside inline code or code blocks.

Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides.

@greptile-apps

greptile-apps Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[Medium risk] Adds variable substitution to markdown tiles on dashboards.

The PR appears safe to merge based on the reviewed changes and outstanding findings.

Summary

This PR substitutes dashboard variables into Markdown tiles, adds Markdown escaping and reference validation, and updates dashboard guidance and tests. Since the previous review, it also changes the app’s viewport initial scale from 0.75 to 1.

Diagram
%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Dashboard variable selections] --> B[Find references in Markdown tile]
  B --> C[Substitute and Markdown-escape values]
  C --> D[Render Markdown]
  B --> E[Validate references]
  E --> F[Show tile warning]
Loading

Reviews (5) · Last reviewed commit: "Merge branch 'main' into drew/variables-..."

Comment thread packages/app/src/HDXMarkdownChart.tsx Resolved
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 387 passed • 1 skipped • 1612s

Status Count
✅ Passed 387
❌ Failed 0
⚠️ Flaky 2
⏭️ Skipped 1

Tests ran across 4 shards in parallel.

View full report →

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

Scope: Variable substitution in markdown tiles — packages/common-utils (new markdown template format + escaping), packages/app (HDXMarkdownChart, dashboard wiring, completions), packages/api/src/mcp (validation + prompt docs). Diff taken against merge-base 78ed592.

Intent: Substitute dashboard variables in markdown tiles, markdown-escaping values by default so they render as plain text, flag unknown references, and update MCP validation/prompts.

✅ No critical issues found. The security posture holds: HDXMarkdownChart renders through react-markdown@10 with no rehype-raw, no plugins, and no custom urlTransform, so raw HTML is inert and the default URL sanitizer neutralizes javascript:/data: URLs — even the csv escape hatch inside a link. escapeMarkdownValue covers the full ASCII-punctuation set and collapses newlines, so the default format cannot form active markdown.

🟡 P2 -- recommended

  • packages/app/src/__tests__/HDXMarkdownChart.test.tsx:16 -- The new unit tests assert raw substituted strings because react-markdown is mocked to return its children unchanged, so the escaping's central behavior — that substituted punctuation renders as literal text rather than active markdown — is never exercised, and the e2e test uses only plain-text values.
    • Fix: Add coverage that renders through real markdown-to-HTML with a value containing markdown syntax (e.g. *bold*, [x](javascript:alert(1)), <img onerror>) to assert it renders inert.
    • testing, security, previous-comments
🔵 P3 nitpicks (4)
  • packages/api/src/mcp/tools/dashboards/validation.ts:247 -- variableIssueSubject is a switch typed : string with no default; with noImplicitReturns: false a future TemplateLanguage member would fall through and return undefined. No failure in this diff since all four languages are handled and the exhaustive Record<TemplateLanguage, …> maps would flag a new member at compile time first.
    • Fix: Add a default: language satisfies never; guard to match the exhaustiveness pattern used by the sibling switches in variables.ts.
    • kieran-typescript
  • packages/app/src/HDXMarkdownChart.tsx:79 -- XSS safety of the csv/non-markdown opt-out rests entirely on react-markdown's implicit defaults, which are invisible at the call site; a future rehype-raw, plugin, custom urlTransform, or major version change would silently reintroduce injection since variable values can be telemetry-derived.
    • Fix: Pin intent at the render site with an explicit urlTransform/skipHtml (or a comment plus a regression test) rather than relying on library defaults.
    • security
  • packages/common-utils/src/variables.ts:1360 -- getReferencedVariableNames defaults language to 'sql', so any future caller passing markdown content without the second argument would silently skip references on lines SQL treats as comments (#, --); current callers pass 'markdown' correctly.
    • Fix: Consider making the language argument required, or document the comment-skipping default at the call sites.
  • packages/app/src/HDXMarkdownChart.tsx:36 -- A backslash-escaped reference such as \$service still substitutes because the scanner does not treat the preceding backslash as an escape; the author acknowledged this affects all display types and deferred it as out of scope.
    • Fix: Track as a follow-up for consistent backslash-escape handling across display types.
    • previous-comments

Reviewers (7): correctness, testing, maintainability, security, kieran-typescript, adversarial, previous-comments.

Testing gaps:

  • No test verifies raw HTML (<img onerror=…>) or javascript:/data: link values render inert on the markdown path.
  • No test for escapeMarkdownValue against link/image/autolink/HTML-breakout payloads.
  • No test for the availableVariableNames-vs-substituted-variables split that drives the toolbar unknown-reference indicator.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

Comment thread packages/app/src/DBDashboardPage.tsx Resolved

@brandon-pereira brandon-pereira left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@kodiakhq
kodiakhq Bot merged commit 793fe19 into main Sep 30, 2026
29 checks passed
@kodiakhq
kodiakhq Bot deleted the drew/variables-markdown-mcp branch September 30, 2026 13:51

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — 832e0695 Deployed Sep 30, 2026 by vercel[bot]
Preview – hyperdx-storybook — 832e0695 Deployed Sep 30, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automerge review/tier-3 Standard — full human review required

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants