@inditextech/docouture-antora-extensions 0.1.0-SNAPSHOT.40.1

package/lib/kroki-prewarm.js

@@ -0,0 +1,182 @@
+'use strict'
+
+// GH-44: pre-renders every `[mermaid]`/`[plantuml]`/etc. block the raw
+// content aggregate contains, via a self-hosted Kroki service, asynchronously,
+// before any page is converted. Also starts that Kroki service itself, on
+// demand, if nothing answers at its fixed URL yet — see kroki-docker.js's
+// own header for that half.
+//
+// This is an ANTORA pipeline extension (`antora.extensions` in the
+// playbook) — see index.js's own header for why this package's exports are
+// that kind, and shiki-prewarm.js's own header for the identical shape this
+// follows: `@asciidoctor/core ~2.2` converts every page through a fully
+// synchronous (Opal) loop, but rendering a diagram means an HTTP round trip
+// to Kroki, which is asynchronous. So that work happens ONCE, up front,
+// outside the conversion loop entirely, and its result handed to the
+// synchronous side (kroki.js, in the SIBLING
+// @inditextech/docouture-asciidoc-extensions package) through a plain shared
+// module, kroki-instance.js.
+//
+// Unlike Shiki, there is no single instance to build — every distinct
+// diagram in the corpus needs its own render, and this listener does not yet
+// know which pages actually have `[mermaid]` blocks (that's Asciidoctor's
+// job, which hasn't run yet). So it works off the RAW content instead:
+// `contentAggregated` fires with every source file's contents still a plain
+// Buffer, before Antora classifies anything into pages — the same point
+// nav-modules.js reads a component descriptor's own unknown keys before
+// classification discards them (see that file's header for the citation on
+// event ordering).
+//
+// `kroki-enabled` and `kroki-diagram-types` are read off the PLAYBOOK here
+// (`playbook.asciidoc.attributes`), not off any one document — there is no
+// AsciiDoc document yet at this point in the pipeline. kroki-config.js's
+// `resolveEnabledTypes` is shared with kroki.js specifically so the two
+// never disagree about what "enabled" means from two different attribute
+// shapes (a raw playbook value here, `Document#getAttribute` there).
+const {
+  SUPPORTED_TYPES,
+  ENABLED_ATTR,
+  TYPES_ATTR,
+  KROKI_URL,
+  resolveEnabledTypes,
+  resolveFormat,
+} = require('@inditextech/docouture-asciidoc-extensions/lib/kroki-config')
+const { applyDefaultMermaidTheme } = require('@inditextech/docouture-asciidoc-extensions/lib/kroki-mermaid-theme')
+const kroki = require('@inditextech/docouture-asciidoc-extensions/lib/kroki-instance')
+const { ensureKrokiRunning } = require('./kroki-docker')
+
+// Matches the exact shape kroki.js intercepts: a `[type]` (optionally
+// `,format=<anything>` — deliberately not restricted to `svg|png` here;
+// `resolveFormat` is the one place both this file and kroki.js validate the
+// value, so a typo (`format=jpeg`) is caught and warned about the same way
+// on both sides, rather than this regex silently failing to match the
+// whole block and this file treating it as not a diagram at all while
+// kroki.js's own Asciidoctor-parsed `attrs.format` still sees it) style
+// line immediately followed by a four-dot-delimited LITERAL block. Built
+// from `SUPPORTED_TYPES` rather than a bare `\w+`, so a block styled with
+// some other, unsupported name (or a coincidental four-dot block that
+// isn't a diagram at all) is never sent to Kroki on a guess. Tolerant of
+// `\r\n` line endings and of trailing whitespace on the delimiter lines —
+// real-world authoring and git checkout settings both produce those — but
+// otherwise matches `tools/fumadocs-migrate/lib/emit.mjs`'s own emitted
+// shape verbatim, since that's the one real caller of this today (which
+// never emits `format=`).
+function buildBlockPattern() {
+  const typeAlternation = SUPPORTED_TYPES.map((type) => type.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')
+  return new RegExp(
+    '^\\[(' +
+      typeAlternation +
+      ')(?:,\\s*format\\s*=\\s*([a-zA-Z0-9_-]*)\\s*)?\\]\\r?\\n\\.\\.\\.\\.[ \\t]*\\r?\\n([\\s\\S]*?)\\r?\\n\\.\\.\\.\\.[ \\t]*$',
+    'gm'
+  )
+}
+
+/** Every `(type, source, format)` triple found in one file's raw contents. */
+function extractDiagrams(text, pattern) {
+  const found = []
+  pattern.lastIndex = 0
+  let match
+  while ((match = pattern.exec(text))) {
+    found.push({ type: match[1], format: match[2], source: match[3] })
+  }
+  return found
+}
+
+async function fetchDiagram(type, source, format, logger) {
+  try {
+    const response = await fetch(KROKI_URL + '/' + type + '/' + format, {
+      method: 'POST',
+      headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+      body: source,
+    })
+    if (!response.ok) {
+      logger.warn(
+        'Kroki render failed for a %s diagram (%s): %s %s — falling back to raw source for it',
+        type,
+        format,
+        response.status,
+        response.statusText
+      )
+      return
+    }
+    if (format === 'png') {
+      return Buffer.from(await response.arrayBuffer()).toString('base64')
+    }
+    return await response.text()
+  } catch (err) {
+    logger.warn(
+      'Could not reach the Kroki service at %s to render a %s diagram (%s) — falling back to raw source for it',
+      KROKI_URL,
+      type,
+      err.message
+    )
+  }
+}
+
+module.exports = function registerKrokiPrewarm(context, deps = {}) {
+  const doEnsureKrokiRunning = deps.ensureKrokiRunning || ensureKrokiRunning
+  context.on('contentAggregated', async ({ contentAggregate, playbook }) => {
+    const attributes = (playbook && playbook.asciidoc && playbook.asciidoc.attributes) || {}
+    const logger = context.getLogger('docouture-kroki-prewarm')
+    const enabledTypes = resolveEnabledTypes(attributes[ENABLED_ATTR], attributes[TYPES_ATTR], (unknown) =>
+      logger.warn('Ignoring unknown %s entry "%s"; expected one of %s', TYPES_ATTR, unknown, SUPPORTED_TYPES.join(', '))
+    )
+    if (!enabledTypes.size) return
+
+    // GH-44: no manual `docker compose up` step required — the first build
+    // that actually needs Kroki starts it, on any of this feature's
+    // invocation paths (CLI, justfile/nx, raw `antora`, a consumer's own
+    // CI) equally, because this listener runs on all of them. See
+    // kroki-docker.js's own header for why there's no matching teardown.
+    await doEnsureKrokiRunning(KROKI_URL, playbook && playbook.dir, logger)
+
+    const pattern = buildBlockPattern()
+    // Deduplicated by kroki-instance.js's own key: the same diagram source
+    // (and requested format) repeated across pages (or byte-identical after
+    // a migration re-run) should cost one Kroki call, not one per
+    // occurrence.
+    const jobs = new Map()
+    for (const bucket of contentAggregate) {
+      for (const file of bucket.files || []) {
+        if (!file.path || !file.path.endsWith('.adoc')) continue
+        const text = file.contents.toString('utf8')
+        for (const { type, source, format: requestedFormat } of extractDiagrams(text, pattern)) {
+          if (!enabledTypes.has(type)) continue
+          const format = resolveFormat(type, requestedFormat, (t, requested) =>
+            logger.warn('Ignoring unsupported format "%s" for a %s diagram; falling back to svg', requested, t)
+          )
+          // See kroki-mermaid-theme.js's own header: this has to be the
+          // SAME transform kroki.js applies before computing its own
+          // lookup key, or a prewarmed entry becomes unreachable from the
+          // synchronous side.
+          const effectiveSource = type === 'mermaid' ? applyDefaultMermaidTheme(source) : source
+          const key = kroki.keyFor(type, effectiveSource, format)
+          if (!jobs.has(key)) jobs.set(key, { type, source: effectiveSource, format })
+        }
+      }
+    }
+    if (!jobs.size) return
+
+    logger.info('Rendering %d diagram(s) via Kroki at %s', jobs.size, KROKI_URL)
+    let rendered = 0
+    await Promise.all(
+      Array.from(jobs, async ([key, { type, source, format }]) => {
+        const data = await fetchDiagram(type, source, format, logger)
+        if (data) {
+          kroki.set(key, { format, data })
+          rendered++
+        }
+      })
+    )
+    if (rendered === jobs.size) {
+      logger.info('Kroki rendered all %d diagram(s) successfully', jobs.size)
+    } else {
+      logger.warn(
+        'Kroki rendered %d/%d diagram(s); %d fell back to raw source — see warnings above for why',
+        rendered,
+        jobs.size,
+        jobs.size - rendered
+      )
+    }
+  })
+}

package/lib/kroki-prewarm.spec.js

@@ -0,0 +1,209 @@
+'use strict'
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const registerKrokiPrewarm = require('./kroki-prewarm')
+const kroki = require('@inditextech/docouture-asciidoc-extensions/lib/kroki-instance')
+const { applyDefaultMermaidTheme } = require('@inditextech/docouture-asciidoc-extensions/lib/kroki-mermaid-theme')
+
+function createContext() {
+  const listeners = {}
+  const warnings = []
+  const infos = []
+  return {
+    getLogger: () => ({ warn: (...args) => warnings.push(args), info: (...args) => infos.push(args) }),
+    on(event, fn) {
+      ;(listeners[event] ||= []).push(fn)
+    },
+    async emit(event, payload) {
+      for (const fn of listeners[event] || []) await fn(payload)
+    },
+    warnings,
+    infos,
+  }
+}
+
+function file(path, contents) {
+  return { path, contents: Buffer.from(contents, 'utf8') }
+}
+
+function block(type, source, format) {
+  const style = format ? `${type},format=${format}` : type
+  return `[${style}]\n....\n${source}\n....\n`
+}
+
+async function run({ attributes, files }) {
+  const context = createContext()
+  // GH-44: `ensureKrokiRunning` (auto-start) is exercised on its own, in
+  // kroki-docker.spec.js — stubbed out here via the same dependency-
+  // injection seam publish.ts's own `loadDriver` deps param uses, so these
+  // tests are only about the raw-content scanning and per-diagram fetch/
+  // cache logic. Without this, its own reachability probe would consume the
+  // `fetch` mock these tests set up for the DIAGRAM fetch, throwing off
+  // every call-count assertion below.
+  registerKrokiPrewarm(context, { ensureKrokiRunning: async () => undefined })
+  await context.emit('contentAggregated', {
+    playbook: { asciidoc: { attributes } },
+    contentAggregate: [{ files }],
+  })
+  return context
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('registerKrokiPrewarm', () => {
+  it('does nothing when kroki-enabled is not set', async () => {
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+
+    const source = 'stateDiagram-v2\nA --> B (disabled case)'
+    await run({ attributes: {}, files: [file('modules/main/pages/a.adoc', block('mermaid', source))] })
+
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(kroki.get(kroki.keyFor('mermaid', applyDefaultMermaidTheme(source), 'svg'))).toBeUndefined()
+  })
+
+  it('fetches and caches every requested diagram type found in the raw content', async () => {
+    const svg = '<svg>rendered</svg>'
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, text: async () => svg })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const source = 'stateDiagram-v2\nA --> B (cached case)'
+    await run({
+      attributes: { 'kroki-enabled': true, 'kroki-diagram-types': 'mermaid' },
+      files: [file('modules/main/pages/a.adoc', block('mermaid', source))],
+    })
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(fetchMock.mock.calls[0][0]).toBe('http://localhost:8500/mermaid/svg')
+    // The body actually POSTed is the theme-injected source (kroki-mermaid-
+    // theme.js), not the author's raw one — this is the one place that's
+    // observable from outside kroki-prewarm.js itself.
+    expect(fetchMock.mock.calls[0][1].body).toBe(applyDefaultMermaidTheme(source))
+    expect(kroki.get(kroki.keyFor('mermaid', applyDefaultMermaidTheme(source), 'svg'))).toEqual({
+      format: 'svg',
+      data: svg,
+    })
+  })
+
+  it('logs a success summary when every requested diagram renders', async () => {
+    const svg = '<svg>rendered</svg>'
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, text: async () => svg })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const source = 'stateDiagram-v2\nA --> B (summary case)'
+    const context = await run({
+      attributes: { 'kroki-enabled': true, 'kroki-diagram-types': 'mermaid' },
+      files: [file('modules/main/pages/a.adoc', block('mermaid', source))],
+    })
+
+    expect(context.infos.some(([msg]) => msg.includes('rendered all'))).toBe(true)
+  })
+
+  it('warns with a fallback summary when some diagrams fail to render', async () => {
+    const fetchMock = vi.fn().mockRejectedValue(new Error('connect ECONNREFUSED'))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const source = 'stateDiagram-v2\nA --> B (summary failure case)'
+    const context = await run({
+      attributes: { 'kroki-enabled': true, 'kroki-diagram-types': 'mermaid' },
+      files: [file('modules/main/pages/a.adoc', block('mermaid', source))],
+    })
+
+    expect(context.warnings.some(([msg]) => msg.includes('fell back to raw source'))).toBe(true)
+  })
+
+  it('ignores a block whose type is not in kroki-diagram-types', async () => {
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+
+    const source = 'A -> B (not requested case)'
+    await run({
+      attributes: { 'kroki-enabled': true, 'kroki-diagram-types': 'plantuml' },
+      files: [file('modules/main/pages/a.adoc', block('graphviz', source))],
+    })
+
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(kroki.get(kroki.keyFor('graphviz', source))).toBeUndefined()
+  })
+
+  it('warns and leaves the cache empty when Kroki is unreachable', async () => {
+    const fetchMock = vi.fn().mockRejectedValue(new Error('connect ECONNREFUSED'))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const source = 'stateDiagram-v2\nA --> B (unreachable case)'
+    const context = await run({
+      attributes: { 'kroki-enabled': true },
+      files: [file('modules/main/pages/a.adoc', block('mermaid', source))],
+    })
+
+    expect(kroki.get(kroki.keyFor('mermaid', applyDefaultMermaidTheme(source), 'svg'))).toBeUndefined()
+    expect(context.warnings.some(([msg]) => msg.includes('Could not reach the Kroki service'))).toBe(true)
+  })
+
+  it('warns once per unknown kroki-diagram-types entry and still processes the known ones', async () => {
+    const svg = '<svg>known</svg>'
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, text: async () => svg })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const source = 'stateDiagram-v2\nA --> B (unknown-type case)'
+    const context = await run({
+      attributes: { 'kroki-enabled': true, 'kroki-diagram-types': 'mermaid,not-a-real-type' },
+      files: [file('modules/main/pages/a.adoc', block('mermaid', source))],
+    })
+
+    expect(kroki.get(kroki.keyFor('mermaid', applyDefaultMermaidTheme(source), 'svg'))).toEqual({
+      format: 'svg',
+      data: svg,
+    })
+    expect(context.warnings.some(([msg]) => msg.includes('unknown %s entry'))).toBe(true)
+  })
+
+  it('ignores non-.adoc files', async () => {
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+
+    await run({
+      attributes: { 'kroki-enabled': true },
+      files: [file('modules/main/pages/a.png', block('mermaid', 'A --> B (non-adoc case)'))],
+    })
+
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('requests and base64-caches a png diagram for a type that supports it', async () => {
+    const bytes = new Uint8Array([137, 80, 78, 71]) // a PNG magic-number prefix is enough for this test
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, arrayBuffer: async () => bytes.buffer })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const source = 'stateDiagram-v2\nA --> B (png case)'
+    await run({
+      attributes: { 'kroki-enabled': true, 'kroki-diagram-types': 'mermaid' },
+      files: [file('modules/main/pages/a.adoc', block('mermaid', source, 'png'))],
+    })
+
+    expect(fetchMock.mock.calls[0][0]).toBe('http://localhost:8500/mermaid/png')
+    expect(kroki.get(kroki.keyFor('mermaid', applyDefaultMermaidTheme(source), 'png'))).toEqual({
+      format: 'png',
+      data: Buffer.from(bytes).toString('base64'),
+    })
+  })
+
+  it('falls back to svg and warns when png is requested for a type Kroki does not support', async () => {
+    const svg = '<svg>bpmn fallback</svg>'
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, text: async () => svg })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const source = '<definitions>(bpmn png-unsupported case)</definitions>'
+    const context = await run({
+      attributes: { 'kroki-enabled': true, 'kroki-diagram-types': 'bpmn' },
+      files: [file('modules/main/pages/a.adoc', block('bpmn', source, 'png'))],
+    })
+
+    expect(fetchMock.mock.calls[0][0]).toBe('http://localhost:8500/bpmn/svg')
+    expect(kroki.get(kroki.keyFor('bpmn', source, 'svg'))).toEqual({ format: 'svg', data: svg })
+    expect(context.warnings.some(([msg]) => msg.includes('unsupported format'))).toBe(true)
+  })
+})

package/lib/lifecycle-log.js

@@ -0,0 +1,61 @@
+'use strict'
+
+// Traces Antora's OWN generator pipeline — when it starts, and how long
+// each documented phase takes — under a single `docouture-lifecycle` logger, at
+// `info`. @antora/site-generator's generate-site.js notifies every one of
+// the events below (`context.notify(eventName)`, see that file's own
+// source for the exact call sites this list is transcribed from) but never
+// logs any of them at any level itself — they exist purely as extension
+// hook points. Nothing else, in Antora or this package, narrates "starting
+// content aggregation" or "site generation took Ns" without this; asking
+// Antora for a higher `--log-level` gets you MORE of its per-file/per-page
+// diagnostic noise, not a trace of its own pipeline.
+//
+// Unconditional, always registered, unlike kroki-prewarm.js/
+// shiki-prewarm.js — this touches no external state (no Docker, no
+// network) and has no failure mode worth degrading from: it is `Date.now()`
+// and a log line, nothing else, so there is nothing here to disable.
+//
+// Its log lines flow through the exact same observability plumbing already
+// wired for every other `docouture-*` extension — `--log-level=info` (Antora's
+// own real default is `warn`) plus a `"name":"docouture-` filter — in this
+// monorepo's own `just dev`/`just build-site` recipes and in
+// `docouture dev`/`docouture build` (the CLI package's `antora-log.ts`). No extra
+// flag or config specific to this file is needed to see it.
+//
+// EVENT ORDER below is generate-site.js's actual pipeline order (plus
+// GeneratorContext's own always-fired contextStarted/contextClosed), not
+// alphabetical.
+const EVENTS = [
+  'contextStarted', // GeneratorContext.start — before the playbook is even built
+  'playbookBuilt',
+  'beforeProcess',
+  'contentAggregated', // kroki-prewarm.js's/shiki-prewarm.js's own hook point
+  'uiLoaded',
+  'contentClassified', // version-report.js's own hook point
+  'documentsConverted',
+  'navigationBuilt', // nav-modules.js's/footer.js's/search-index.js's/llms-txt.js's/not-found-page.js's own hook point
+  'pagesComposed',
+  'redirectsProduced',
+  'siteMapped', // only fires when playbook.site.url is set
+  'beforePublish',
+  'sitePublished',
+  'contextClosed', // GeneratorContext.close, in generate-site.js's own `finally` — always fires, success or failure
+]
+
+module.exports = function registerLifecycleLog(context, deps = {}) {
+  const now = deps.now || Date.now
+  const logger = context.getLogger('docouture-lifecycle')
+  const startedAt = now()
+  let lastAt = startedAt
+
+  for (const event of EVENTS) {
+    context.on(event, () => {
+      const at = now()
+      logger.info('Antora: %s (+%dms, %dms total)', event, at - lastAt, at - startedAt)
+      lastAt = at
+    })
+  }
+}
+
+module.exports.EVENTS = EVENTS

package/lib/lifecycle-log.spec.js

@@ -0,0 +1,59 @@
+'use strict'
+
+import { describe, expect, it } from 'vitest'
+
+const registerLifecycleLog = require('./lifecycle-log')
+
+function createContext() {
+  const listeners = {}
+  const logs = []
+  return {
+    getLogger: () => ({ info: (...args) => logs.push(args) }),
+    on(event, fn) {
+      ;(listeners[event] ||= []).push(fn)
+    },
+    async emit(event) {
+      for (const fn of listeners[event] || []) await fn()
+    },
+    logs,
+  }
+}
+
+describe('registerLifecycleLog', () => {
+  it('registers a listener for every documented generate-site.js event', async () => {
+    const context = createContext()
+    let tick = 0
+    registerLifecycleLog(context, { now: () => tick })
+
+    for (const event of registerLifecycleLog.EVENTS) {
+      tick += 1
+      await context.emit(event)
+    }
+
+    expect(context.logs).toHaveLength(registerLifecycleLog.EVENTS.length)
+    expect(context.logs.map(([, event]) => event)).toEqual(registerLifecycleLog.EVENTS)
+  })
+
+  it('logs elapsed time since the previous event and since the start', async () => {
+    const context = createContext()
+    let tick = 1000
+    registerLifecycleLog(context, { now: () => tick })
+
+    tick = 1050 // +50ms since registration
+    await context.emit('contentAggregated')
+    tick = 1230 // +180ms since the previous event, +230ms total
+    await context.emit('contentClassified')
+
+    expect(context.logs[0]).toEqual(['Antora: %s (+%dms, %dms total)', 'contentAggregated', 50, 50])
+    expect(context.logs[1]).toEqual(['Antora: %s (+%dms, %dms total)', 'contentClassified', 180, 230])
+  })
+
+  it('does not throw when an event Antora never fires for this build (e.g. siteMapped without site.url) is simply never emitted', async () => {
+    const context = createContext()
+    registerLifecycleLog(context, { now: () => 0 })
+
+    await context.emit('contentAggregated')
+
+    expect(context.logs).toHaveLength(1)
+  })
+})