fix(confluence): preserve panel/callout macro semantics through sync

Confluence's rendered view HTML wraps Info/Note/Warning/Tip and custom Panel
macros in divs whose class/color convey meaning that the shared
htmlToPlainText tag-stripper discards along with the tags — a red "do not
use" warning panel becomes indistinguishable from a plain paragraph once
flattened, so RAG has no signal that a bullet under it is an exclusion rule
rather than a normal one.

Adds preserveConfluenceCallouts, a Confluence-specific pre-pass that rewrites
each detected panel into a single bracketed label (e.g. "[WARNING] Do NOT use
this form for: GitLab") before the generic plain-text conversion runs, so the
callout semantic survives both the tag strip and htmlToPlainText's trailing
whitespace collapse. Bumps the connector's content-representation marker so
already-synced pages get one automatic re-hydration under the new extraction,
rather than silently keeping their stale flattened content until their next
edit.

Author: waleedlatif1

apps/sim/connectors/confluence/confluence.test.ts

@@ -2,7 +2,12 @@
  * @vitest-environment node
  */
 import { describe, expect, it } from 'vitest'
-import { escapeCql, isCurrentContent } from '@/connectors/confluence/confluence'
+import {
+  escapeCql,
+  isCurrentContent,
+  preserveConfluenceCallouts,
+} from '@/connectors/confluence/confluence'
+import { htmlToPlainText } from '@/connectors/utils'
 
 describe('escapeCql', () => {
   it.concurrent('returns plain strings unchanged', () => {
@@ -48,3 +53,85 @@ describe('isCurrentContent', () => {
     expect(isCurrentContent({ id: '1', status: 'deleted' })).toBe(false)
   })
 })
+
+describe('preserveConfluenceCallouts', () => {
+  it.concurrent('handles empty content', () => {
+    expect(preserveConfluenceCallouts('')).toBe('')
+  })
+
+  it.concurrent('leaves content with no macros unchanged', () => {
+    const html = '<p>Just a normal paragraph.</p>'
+    expect(preserveConfluenceCallouts(html)).toContain('Just a normal paragraph.')
+  })
+
+  it.concurrent('labels a built-in warning macro and keeps its body', () => {
+    const html =
+      '<div class="confluence-information-macro confluence-information-macro-warning">' +
+      '<span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span>' +
+      '<div class="confluence-information-macro-body"><p>Do NOT use this form for GitLab access.</p></div>' +
+      '</div>'
+    const result = preserveConfluenceCallouts(html)
+    expect(result).toContain('[WARNING]')
+    expect(result).toContain('Do NOT use this form for GitLab access.')
+  })
+
+  it.concurrent('labels a built-in info macro', () => {
+    const html =
+      '<div class="confluence-information-macro confluence-information-macro-information">' +
+      '<div class="confluence-information-macro-body"><p>Heads up.</p></div>' +
+      '</div>'
+    expect(preserveConfluenceCallouts(html)).toContain('[INFO] Heads up.')
+  })
+
+  it.concurrent('labels a built-in note macro', () => {
+    const html =
+      '<div class="confluence-information-macro confluence-information-macro-note">' +
+      '<div class="confluence-information-macro-body"><p>See also.</p></div>' +
+      '</div>'
+    expect(preserveConfluenceCallouts(html)).toContain('[NOTE] See also.')
+  })
+
+  it.concurrent('labels a built-in tip macro', () => {
+    const html =
+      '<div class="confluence-information-macro confluence-information-macro-tip">' +
+      '<div class="confluence-information-macro-body"><p>Pro tip.</p></div>' +
+      '</div>'
+    expect(preserveConfluenceCallouts(html)).toContain('[TIP] Pro tip.')
+  })
+
+  it.concurrent('labels a generic custom-colored Panel macro using its header title', () => {
+    const html =
+      '<div class="panel" style="border-width: 1px;">' +
+      '<div class="panelHeader" style="background-color: #ffebe6;"><b>Do NOT use this form for:</b></div>' +
+      '<div class="panelContent"><p>GitLab access requests go to the private channel instead.</p></div>' +
+      '</div>'
+    const result = preserveConfluenceCallouts(html)
+    expect(result).toContain('[CALLOUT: Do NOT use this form for:]')
+    expect(result).toContain('GitLab access requests go to the private channel instead.')
+  })
+
+  it.concurrent('falls back to a bare CALLOUT label when a Panel macro has no header text', () => {
+    const html =
+      '<div class="panel"><div class="panelContent"><p>Untitled panel body.</p></div></div>'
+    const result = preserveConfluenceCallouts(html)
+    expect(result).toContain('[CALLOUT]')
+    expect(result).toContain('Untitled panel body.')
+  })
+
+  it.concurrent(
+    'keeps the exclusion marker attached to its content through htmlToPlainText, even across surrounding whitespace collapse',
+    () => {
+      const html =
+        '<p>Intro paragraph.</p>\n\n' +
+        '<div class="confluence-information-macro confluence-information-macro-warning">' +
+        '<div class="confluence-information-macro-body"><p>Do NOT use this form for:</p>' +
+        '<ul><li>GitLab</li></ul></div>' +
+        '</div>\n\n' +
+        '<p>Trailing paragraph.</p>'
+      const plainText = htmlToPlainText(preserveConfluenceCallouts(html))
+      expect(plainText).toContain('[WARNING] Do NOT use this form for:GitLab')
+      expect(plainText).toContain('Intro paragraph.')
+      expect(plainText).toContain('Trailing paragraph.')
+    }
+  )
+})

apps/sim/connectors/confluence/confluence.ts

@@ -1,5 +1,6 @@
 import { createLogger } from '@sim/logger'
 import { toError } from '@sim/utils/errors'
+import * as cheerio from 'cheerio'
 import { fetchWithRetry, VALIDATE_RETRY_OPTIONS } from '@/lib/knowledge/documents/utils'
 import { confluenceConnectorMeta } from '@/connectors/confluence/meta'
 import type { ConnectorConfig, ExternalDocument, ExternalDocumentList } from '@/connectors/types'
@@ -8,6 +9,53 @@ import { getConfluenceCloudId, normalizeConfluenceDomainHost } from '@/tools/con
 
 const logger = createLogger('ConfluenceConnector')
 
+/** Label prefixes for Confluence's built-in Info/Note/Warning/Tip macros, by their rendered CSS suffix. */
+const CALLOUT_LABELS: Record<string, string> = {
+  information: '[INFO]',
+  note: '[NOTE]',
+  warning: '[WARNING]',
+  tip: '[TIP]',
+  error: '[ERROR]',
+}
+
+/**
+ * Confluence's rendered `view` HTML wraps Info/Note/Warning/Tip macros in
+ * `confluence-information-macro confluence-information-macro-{type}` divs, and
+ * the customizable Panel macro in `.panel` > `.panelHeader` + `.panelContent`
+ * divs. `htmlToPlainText`'s blind tag-stripping discards the divs' classes along
+ * with the tags, so a red "do not use" warning panel becomes indistinguishable
+ * from a plain paragraph once flattened — and its trailing whitespace collapse
+ * would erase any newline-based separation too. Each detected panel is rewritten
+ * into a single bracketed label plus its own text so the callout semantic
+ * survives both the tag strip and the whitespace collapse.
+ */
+export function preserveConfluenceCallouts(html: string): string {
+  if (!html) return html
+
+  const $ = cheerio.load(html)
+
+  $('div.confluence-information-macro').each((_, el) => {
+    const $el = $(el)
+    const type = ($el.attr('class') ?? '')
+      .match(/confluence-information-macro-(\w+)/)?.[1]
+      ?.toLowerCase()
+    const label = (type && CALLOUT_LABELS[type]) || CALLOUT_LABELS.information
+    const body =
+      $el.find('.confluence-information-macro-body').first().text().trim() || $el.text().trim()
+    $el.replaceWith($('<p></p>').text(`${label} ${body}`))
+  })
+
+  $('div.panel').each((_, el) => {
+    const $el = $(el)
+    const headerText = $el.find('.panelHeader').first().text().trim()
+    const bodyText = $el.find('.panelContent').first().text().trim() || $el.text().trim()
+    const label = headerText ? `[CALLOUT: ${headerText}]` : '[CALLOUT]'
+    $el.replaceWith($('<p></p>').text(`${label} ${bodyText}`))
+  })
+
+  return $.html()
+}
+
 /**
  * Escapes a value for use inside CQL double-quoted strings.
  */
@@ -108,10 +156,12 @@ async function fetchLabelsForPages(
  * invalidates every previously-synced Confluence document so a one-time
  * re-hydration picks up content newly reachable by the current extraction
  * (e.g. the switch from `storage` to rendered `view`, which expands Include
- * Page / Excerpt macros). Without it, already-indexed pages whose version is
- * unchanged classify as `unchanged` and keep their stale (empty) content.
+ * Page / Excerpt macros; or `preserveConfluenceCallouts`, which stops
+ * flattening panel/info/note/warning/tip macros into indistinguishable plain
+ * text). Without it, already-indexed pages whose version is unchanged
+ * classify as `unchanged` and keep their stale (pre-fix) content.
  */
-const CONTENT_REPRESENTATION = 'view'
+const CONTENT_REPRESENTATION = 'view-callouts'
 
 /**
  * Produces a canonical metadata stub with a deterministic contentHash that
@@ -288,7 +338,7 @@ export const confluenceConnector: ConnectorConfig = {
     const body = page.body as Record<string, unknown> | undefined
     const view = body?.view as Record<string, unknown> | undefined
     const rawContent = (view?.value as string) || ''
-    const plainText = htmlToPlainText(rawContent)
+    const plainText = htmlToPlainText(preserveConfluenceCallouts(rawContent))
 
     const labelMap = await fetchLabelsForPages(cloudId, accessToken, [String(page.id)])
     const labels = labelMap.get(String(page.id)) ?? []