@inditextech/docouture-antora-extensions 1.0.0 → 1.1.0

package/lib/changelog-pages.js

@@ -81,7 +81,7 @@ module.exports = function registerChangelogPages(context, changelogPath) {
 
     const indexFiles = contentCatalog
       .getFiles()
-      .filter((file) => file.src && file.src.family === 'page' && file.src.relative === 'changelog/index.adoc')
+      .filter((file) => file.src?.family === 'page' && file.src?.relative === 'changelog/index.adoc')
 
     if (!indexFiles.length) {
       logger.info("No 'changelog/index.adoc' page found on this site — nothing to append to")

package/lib/footer.js

@@ -97,13 +97,13 @@ function resolveFooter(footer, componentVersion, contentCatalog, logger) {
 
   const groups = []
   for (const group of footer.groups) {
-    if (!group || group.constructor !== Object || !Array.isArray(group.links)) {
+    if (group?.constructor !== Object || !Array.isArray(group?.links)) {
       logger.warn('Ignoring footer group in %s: every group needs a links list', where)
       continue
     }
     const links = []
     for (const link of group.links) {
-      if (!link || link.constructor !== Object || !link.text || !link.url) {
+      if (link?.constructor !== Object || !link?.text || !link?.url) {
         logger.warn('Ignoring footer link in %s: every link needs a text and a url', where)
         continue
       }

package/lib/footer.spec.js

@@ -0,0 +1,179 @@
+// SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
+//
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+import { describe, expect, it, vi } from 'vitest'
+
+const registerFooter = require('./footer')
+
+function createContext(logger = { warn: vi.fn(), info: () => {} }) {
+  const listeners = {}
+  return {
+    logger,
+    getLogger: () => logger,
+    on(event, fn) {
+      ;(listeners[event] ||= []).push(fn)
+    },
+    async emit(event, payload) {
+      for (const fn of listeners[event] || []) await fn(payload)
+    },
+  }
+}
+
+function componentVersion(name, version, overrides = {}) {
+  return { name, version, ...overrides }
+}
+
+async function run(buckets, { pages = {}, logger } = {}) {
+  const context = createContext(logger)
+  registerFooter(context)
+
+  const contentCatalog = {
+    resolvePage: (target) => {
+      const url = pages[target]
+      return url ? { pub: { url } } : undefined
+    },
+  }
+
+  const versions = buckets.map((bucket) => componentVersion(bucket.name, bucket.version))
+  const contentCatalog2 = contentCatalog
+
+  await context.emit('contentAggregated', { contentAggregate: buckets })
+  await context.emit('navigationBuilt', {
+    contentCatalog: {
+      ...contentCatalog2,
+      getComponents: () => [{ versions }],
+    },
+  })
+
+  return { versions, logger: context.logger }
+}
+
+function warnedAbout(logger, text) {
+  return logger.warn.mock.calls.some((call) => typeof call[0] === 'string' && call[0].includes(text))
+}
+
+describe('registerFooter', () => {
+  it('attaches resolved footer groups to the matching component version', async () => {
+    const { versions } = await run(
+      [
+        {
+          name: 'weavejs',
+          version: 'latest',
+          footer: {
+            groups: [
+              {
+                title: 'Resources',
+                links: [
+                  { text: 'Home', url: 'ROOT:index.adoc' },
+                  { text: 'Repository', url: 'https://github.com/example/example' },
+                ],
+              },
+            ],
+          },
+        },
+      ],
+      { pages: { 'ROOT:index.adoc': '/weavejs/latest/index.html' } }
+    )
+
+    expect(versions[0].footer).toEqual({
+      groups: [
+        {
+          title: 'Resources',
+          links: [
+            { text: 'Home', url: '/weavejs/latest/index.html' },
+            { text: 'Repository', url: 'https://github.com/example/example' },
+          ],
+        },
+      ],
+    })
+  })
+
+  it('does nothing to a component version whose bucket has no footer', async () => {
+    const { versions } = await run([{ name: 'weavejs', version: 'latest' }])
+    expect(versions[0].footer).toBeUndefined()
+  })
+
+  it('warns and drops a footer that is not a { groups: [...] } shape', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    const { versions } = await run([{ name: 'weavejs', version: 'latest', footer: { groups: 'not-a-list' } }], {
+      logger,
+    })
+    expect(versions[0].footer).toBeUndefined()
+    expect(warnedAbout(logger, 'expected a groups list')).toBe(true)
+  })
+
+  it('warns and skips a group with no links list, but keeps other groups', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    const { versions } = await run(
+      [
+        {
+          name: 'weavejs',
+          version: 'latest',
+          footer: {
+            groups: [{ title: 'Broken' }, { title: 'Fine', links: [{ text: 'Home', url: '/plain.html' }] }],
+          },
+        },
+      ],
+      { logger }
+    )
+    expect(versions[0].footer.groups).toEqual([{ title: 'Fine', links: [{ text: 'Home', url: '/plain.html' }] }])
+    expect(warnedAbout(logger, 'every group needs a links list')).toBe(true)
+  })
+
+  it('warns and skips a link missing text or url', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    const { versions } = await run(
+      [
+        {
+          name: 'weavejs',
+          version: 'latest',
+          footer: { groups: [{ links: [{ text: 'No url' }, { url: '/no-text.html' }] }] },
+        },
+      ],
+      { logger }
+    )
+    expect(versions[0].footer).toBeUndefined()
+    expect(warnedAbout(logger, 'every link needs a text and a url')).toBe(true)
+  })
+
+  it('drops a link whose page ID resolves to nothing, with a warning', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    const { versions } = await run(
+      [
+        {
+          name: 'weavejs',
+          version: 'latest',
+          footer: { groups: [{ links: [{ text: 'Ghost', url: 'ROOT:missing.adoc' }] }] },
+        },
+      ],
+      { logger }
+    )
+    expect(versions[0].footer).toBeUndefined()
+    expect(warnedAbout(logger, 'resolves to no page')).toBe(true)
+  })
+
+  it('drops a group left with no links after filtering, without rendering an empty column', async () => {
+    const { versions } = await run([
+      {
+        name: 'weavejs',
+        version: 'latest',
+        footer: { groups: [{ title: 'Empty', links: [{ text: 'Ghost', url: 'ROOT:missing.adoc' }] }] },
+      },
+    ])
+    expect(versions[0].footer).toBeUndefined()
+  })
+
+  it('renders a group with no title (GH-77)', async () => {
+    const { versions } = await run([
+      {
+        name: 'weavejs',
+        version: 'latest',
+        footer: { groups: [{ links: [{ text: 'Home', url: '/plain.html' }] }] },
+      },
+    ])
+    expect(versions[0].footer.groups[0].title).toBeUndefined()
+  })
+})

package/lib/html-to-markdown.js

@@ -234,12 +234,15 @@ function splitListItem(li, depth) {
 
 function tableToMarkdown(tableNode) {
   const rows = []
-  // Backslash is escaped first: escaping `|` alone would let a source
-  // backslash immediately before one combine with the `\` this line just
-  // inserted, producing `\\|` — an escaped backslash followed by a live,
-  // unescaped column separator, the exact thing this escape exists to
-  // prevent.
-  const escapeCell = (text) => text.replace(/\\/g, '\\\\').replace(/\|/g, '\\|')
+  // Backslash and pipe are escaped in a single pass — not two chained
+  // .replace() calls — so neither escape can interfere with the other:
+  // escaping `|` first would let a source backslash immediately before one
+  // combine with the new backslash to produce `\\|`, an escaped backslash
+  // followed by a live, unescaped column separator. A single regex with a
+  // replacer callback visits each original character exactly once, so this
+  // ordering hazard can't occur no matter which character comes first in
+  // the input.
+  const escapeCell = (text) => text.replace(/[\\|]/g, (ch) => (ch === '\\' ? String.raw`\\` : String.raw`\|`))
   for (const rowNode of tableNode.querySelectorAll('tr')) {
     const cells = rowNode.querySelectorAll('th,td').map((cell) => escapeCell(inlineText(cell)) || ' ')
     if (cells.length) rows.push(cells)

package/lib/html-to-markdown.spec.js

@@ -39,6 +39,15 @@ describe('htmlToMarkdown', () => {
     expect(htmlToMarkdown(html)).toBe('| A | B |\n| --- | --- |\n| 1 | 2 |')
   })
 
+  // Regression test for the escaping order: a cell containing a literal
+  // backslash must come out doubled, and a cell containing a literal pipe
+  // must come out backslash-escaped, without either interfering with the
+  // other — see escapeCell's own comment in html-to-markdown.js.
+  it('escapes backslashes and pipes in table cells', () => {
+    const html = '<table><tr><th>A</th><th>B</th></tr><tr><td>back\\slash</td><td>pipe|char</td></tr></table>'
+    expect(htmlToMarkdown(html)).toBe('| A | B |\n| --- | --- |\n| back\\\\slash | pipe\\|char |')
+  })
+
   it('drops table-of-contents and icon elements', () => {
     const html = '<div class="toc"><a href="#a">A</a></div><p>Body</p><svg><path/></svg>'
     expect(htmlToMarkdown(html)).toBe('Body')

package/lib/kroki-docker.js

@@ -122,7 +122,7 @@ async function ensureKrokiRunning(url, playbookDir, logger, deps = {}) {
   logger.info(
     'docker compose up -d succeeded — waiting for %s to become reachable...%s',
     url,
-    formatProcessOutput(composeResult && composeResult.stdout, composeResult && composeResult.stderr)
+    formatProcessOutput(composeResult?.stdout, composeResult?.stderr)
   )
 
   const deadline = Date.now() + STARTUP_TIMEOUT_MS
@@ -158,8 +158,8 @@ async function ensureKrokiRunning(url, playbookDir, logger, deps = {}) {
  */
 function formatProcessOutput(stdout, stderr) {
   const parts = []
-  if (stdout && stdout.trim()) parts.push('stdout:\n' + stdout.trim())
-  if (stderr && stderr.trim()) parts.push('stderr:\n' + stderr.trim())
+  if (stdout?.trim()) parts.push('stdout:\n' + stdout.trim())
+  if (stderr?.trim()) parts.push('stderr:\n' + stderr.trim())
   return parts.length ? '\n' + parts.join('\n') : ''
 }
 

package/lib/kroki-include-line-filters.js

@@ -76,17 +76,18 @@ function getLines(attrs) {
         filtered = true
         let delim
         let from
-        if (~(delim = linedef.indexOf('..'))) {
+        delim = linedef.indexOf('..')
+        if (~delim) {
           from = linedef.substring(0, delim)
           let to = linedef.substring(delim + 2)
-          if ((to = parseInt(to, 10) || -1) > 0) {
-            if ((from = parseInt(from, 10) || -1) > 0) {
+          if ((to = Number.parseInt(to, 10) || -1) > 0) {
+            if ((from = Number.parseInt(from, 10) || -1) > 0) {
               for (let i = from; i <= to; i++) linenums.push(i)
             }
-          } else if (to === -1 && (from = parseInt(from, 10) || -1) > 0) {
+          } else if (to === -1 && (from = Number.parseInt(from, 10) || -1) > 0) {
             linenums.push(from, Infinity)
           }
-        } else if ((from = parseInt(linedef, 10) || -1) > 0) {
+        } else if ((from = Number.parseInt(linedef, 10) || -1) > 0) {
           linenums.push(from)
         }
       })
@@ -197,7 +198,8 @@ function filterLinesByTags(content, tags, opts = {}) {
     if (star === undefined) {
       selectingDefault = selecting = !mapContainsValue(tags, true)
     } else {
-      if ((wildcard = star) || tags.keys().next().value !== '*') {
+      wildcard = star
+      if (wildcard || tags.keys().next().value !== '*') {
         selectingDefault = selecting = false
       } else {
         selectingDefault = selecting = !wildcard
@@ -240,11 +242,14 @@ function filterLinesByTags(content, tags, opts = {}) {
           }
         }
       } else if (tags.has(thisTag)) {
-        if ((selecting = tags.get(thisTag))) tagsSelected.push(thisTag)
-        tagStack.unshift([(activeTag = thisTag), selecting, lineNum])
+        selecting = tags.get(thisTag)
+        if (selecting) tagsSelected.push(thisTag)
+        activeTag = thisTag
+        tagStack.unshift([activeTag, selecting, lineNum])
       } else if (wildcard !== undefined) {
         selecting = activeTag && !selecting ? false : wildcard
-        tagStack.unshift([(activeTag = thisTag), selecting, lineNum])
+        activeTag = thisTag
+        tagStack.unshift([activeTag, selecting, lineNum])
       }
     } else if (selecting) {
       if (!startLineNum) startLineNum = lineNum

package/lib/kroki-include-line-filters.spec.js

@@ -144,4 +144,23 @@ describe('filterLinesByTags', () => {
     filterLinesByTags(content, getTags({ tags: 'a;b' }), { onWarn: (msg) => warnings.push(msg) })
     expect(warnings.some((msg) => msg.includes('mismatched end tag'))).toBe(true)
   })
+
+  it('defaults to excluding everything when a wildcard (*) is not the sole/first requested tag', () => {
+    // globstar (**) is absent, star (*) is present, and the first key
+    // inserted into the tags map is not '*' itself ('a' was named first) —
+    // both are independently sufficient to force selectingDefault = false.
+    const content = ['tag::a[]', 'kept', 'end::a[]', 'tag::c[]', 'unlisted-tag line', 'end::c[]', 'outro'].join('\n')
+    const [lines] = filterLinesByTags(content, getTags({ tags: 'a,*' }))
+    // 'outro' (outside every tag) is excluded — the false selectingDefault —
+    // while 'c', an unlisted tag, still falls through to the wildcard (true).
+    expect(lines).toEqual(['kept', 'unlisted-tag line'])
+  })
+
+  it('applies the wildcard to a tag directive that names neither a listed tag nor */**', () => {
+    const content = ['tag::unlisted[]', 'wildcard-selected line', 'end::unlisted[]'].join('\n')
+    const [selected] = filterLinesByTags(content, getTags({ tags: 'keep,*' }))
+    expect(selected).toEqual(['wildcard-selected line'])
+    const [excluded] = filterLinesByTags(content, getTags({ tags: 'keep,!*' }))
+    expect(excluded).toEqual([])
+  })
 })

package/lib/kroki-prewarm.js

@@ -137,11 +137,11 @@ const { getLines, getTags, filterLinesByLineNumbers, filterLinesByTags } = requi
 // `format=` value from wherever it appears, quote-aware, the same way
 // `parseIncludeAttrlist` already does for `include::` directives.
 function buildBlockPattern() {
-  const typeAlternation = SUPPORTED_TYPES.map((type) => type.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')
+  const typeAlternation = SUPPORTED_TYPES.map((type) => type.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)).join(
+    '|'
+  )
   return new RegExp(
-    '^\\[(' +
-      typeAlternation +
-      ')(?:,([^\\]]*))?\\]\\r?\\n\\.\\.\\.\\.[ \\t]*\\r?\\n([\\s\\S]*?)\\r?\\n\\.\\.\\.\\.[ \\t]*$',
+    String.raw`^\[(${typeAlternation})(?:,([^\]]*))?\]\r?\n\.\.\.\.[ \t]*\r?\n([\s\S]*?)\r?\n\.\.\.\.[ \t]*$`,
     'gm'
   )
 }
@@ -481,7 +481,7 @@ async function fetchDiagram(type, source, format, options, logger) {
 module.exports = function registerKrokiPrewarm(context, deps = {}) {
   const doEnsureKrokiRunning = deps.ensureKrokiRunning || ensureKrokiRunning
   context.on('contentClassified', async ({ contentCatalog, playbook }) => {
-    const attributes = (playbook && playbook.asciidoc && playbook.asciidoc.attributes) || {}
+    const attributes = 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(', '))
@@ -493,7 +493,7 @@ module.exports = function registerKrokiPrewarm(context, deps = {}) {
     // 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)
+    await doEnsureKrokiRunning(KROKI_URL, playbook?.dir, logger)
 
     const pattern = buildBlockPattern()
     // Deduplicated by kroki-instance.js's own key: the same diagram source
@@ -505,7 +505,7 @@ module.exports = function registerKrokiPrewarm(context, deps = {}) {
     // registered by `registerPageAlias`/`addSplatAlias`) which have no
     // `.path` of their own at all — guard against those rather than just
     // the `.adoc` extension check.
-    for (const file of contentCatalog.getFiles((candidate) => candidate.path && candidate.path.endsWith('.adoc'))) {
+    for (const file of contentCatalog.getFiles((candidate) => candidate.path?.endsWith('.adoc'))) {
       const text = file.contents.toString('utf8')
       for (const { type, source: rawSource, format: requestedFormat, options } of extractDiagrams(text, pattern)) {
         if (!enabledTypes.has(type)) continue

package/lib/nav-modules.js

@@ -140,7 +140,7 @@ function annotate(componentVersion, { nav, navModules }, contentCatalog, logger)
 
   const declared = new Map()
   for (const entry of navModules) {
-    if (!entry || entry.constructor !== Object || !entry.module) {
+    if (entry?.constructor !== Object || !entry?.module) {
       logger.warn('Ignoring nav_modules entry in %s: every entry needs a module key', where)
       continue
     }

package/lib/nav-modules.spec.js

@@ -0,0 +1,223 @@
+// SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
+//
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict'
+
+import { describe, expect, it, vi } from 'vitest'
+
+const registerNavModules = require('./nav-modules')
+
+function createContext(logger = { warn: vi.fn(), info: () => {} }) {
+  const listeners = {}
+  return {
+    logger,
+    getLogger: () => logger,
+    on(event, fn) {
+      ;(listeners[event] ||= []).push(fn)
+    },
+    async emit(event, payload) {
+      for (const fn of listeners[event] || []) await fn(payload)
+    },
+  }
+}
+
+function tree(order, items = []) {
+  return { order, items }
+}
+
+async function run(bucket, trees, { pages = {}, logger } = {}) {
+  const context = createContext(logger)
+  registerNavModules(context)
+
+  const componentVersion = { name: 'weavejs', version: 'latest', navigation: trees }
+  const contentCatalog = {
+    resolvePage: (target) => {
+      const url = pages[target]
+      return url ? { pub: { url } } : undefined
+    },
+    getComponents: () => [{ versions: [componentVersion] }],
+  }
+
+  await context.emit('contentAggregated', { contentAggregate: [bucket] })
+  await context.emit('navigationBuilt', { contentCatalog })
+
+  return { componentVersion, logger: context.logger }
+}
+
+function warnedAbout(logger, text) {
+  return logger.warn.mock.calls.some((call) => typeof call[0] === 'string' && call[0].includes(text))
+}
+
+describe('registerNavModules', () => {
+  it('stamps a matched tree with module/title and finds its first internal page as startUrl', async () => {
+    const item = { urlType: 'internal', url: '/weavejs/latest/main/index.html', items: [] }
+    const { componentVersion } = await run(
+      {
+        name: 'weavejs',
+        version: 'latest',
+        nav: ['modules/main/nav.adoc'],
+        navModules: [{ module: 'main', title: 'Framework', description: 'Desc', icon: 'menu' }],
+      },
+      [tree(0, [item])]
+    )
+
+    const t = componentVersion.navigation[0]
+    expect(t.module).toBe('main')
+    expect(t.title).toBe('Framework')
+    expect(t.description).toBe('Desc')
+    expect(t.icon).toBe('menu')
+    expect(t.startUrl).toBe('/weavejs/latest/main/index.html')
+    expect(item.module).toBe('main')
+  })
+
+  it('stamps items depth-first, all the way down the tree', async () => {
+    const grandchild = { urlType: 'internal', url: '/weavejs/latest/main/deep.html', items: [] }
+    const child = { items: [grandchild] } // an unlinked category heading, no url of its own
+    const { componentVersion } = await run(
+      { name: 'weavejs', version: 'latest', nav: ['modules/main/nav.adoc'], navModules: [{ module: 'main' }] },
+      [tree(0, [child])]
+    )
+    expect(child.module).toBe('main')
+    expect(grandchild.module).toBe('main')
+    expect(componentVersion.navigation[0].startUrl).toBe('/weavejs/latest/main/deep.html')
+  })
+
+  it('falls back to the module slug as the title when none is declared', async () => {
+    const { componentVersion } = await run(
+      { name: 'weavejs', version: 'latest', nav: ['modules/main/nav.adoc'], navModules: [{ module: 'main' }] },
+      [tree(0, [{ urlType: 'internal', url: '/x.html', items: [] }])]
+    )
+    expect(componentVersion.navigation[0].title).toBe('main')
+  })
+
+  it('resolves an authored start_page in preference to the first internal item', async () => {
+    const { componentVersion } = await run(
+      {
+        name: 'weavejs',
+        version: 'latest',
+        nav: ['modules/main/nav.adoc'],
+        navModules: [{ module: 'main', startPage: 'main:quickstart.adoc' }],
+      },
+      [tree(0, [{ urlType: 'internal', url: '/x.html', items: [] }])],
+      { pages: { 'main:quickstart.adoc': '/weavejs/latest/main/quickstart.html' } }
+    )
+    expect(componentVersion.navigation[0].startUrl).toBe('/weavejs/latest/main/quickstart.html')
+  })
+
+  it('warns and falls back to the navigation when start_page resolves to nothing', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    const { componentVersion } = await run(
+      {
+        name: 'weavejs',
+        version: 'latest',
+        nav: ['modules/main/nav.adoc'],
+        navModules: [{ module: 'main', startPage: 'main:missing.adoc' }],
+      },
+      [tree(0, [{ urlType: 'internal', url: '/x.html', items: [] }])],
+      { logger }
+    )
+    expect(componentVersion.navigation[0].startUrl).toBe('/x.html')
+    expect(warnedAbout(logger, 'resolves to no page; falling back')).toBe(true)
+  })
+
+  it('warns when a module has no internal page to link to at all', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    const { componentVersion } = await run(
+      { name: 'weavejs', version: 'latest', nav: ['modules/main/nav.adoc'], navModules: [{ module: 'main' }] },
+      [tree(0, [])],
+      { logger }
+    )
+    expect(componentVersion.navigation[0].startUrl).toBeUndefined()
+    expect(warnedAbout(logger, 'has no internal page to link to')).toBe(true)
+  })
+
+  it('marks switcher:false without warning about a missing start page', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    const { componentVersion } = await run(
+      {
+        name: 'weavejs',
+        version: 'latest',
+        nav: ['modules/ROOT/nav.adoc'],
+        navModules: [{ module: 'ROOT', switcher: false }],
+      },
+      [tree(0, [])],
+      { logger }
+    )
+    expect(componentVersion.navigation[0].switcher).toBe(false)
+    expect(componentVersion.navigation[0].startUrl).toBeUndefined()
+    expect(warnedAbout(logger, 'has no internal page to link to')).toBe(false)
+  })
+
+  it('floors a fractional tree.order to find the owning nav file (one file, multiple lists)', async () => {
+    const { componentVersion } = await run(
+      { name: 'weavejs', version: 'latest', nav: ['modules/main/nav.adoc'], navModules: [{ module: 'main' }] },
+      [tree(0.5, [{ urlType: 'internal', url: '/x.html', items: [] }])]
+    )
+    expect(componentVersion.navigation[0].module).toBe('main')
+  })
+
+  it('leaves a tree untouched when its nav path is outside modules/', async () => {
+    const { componentVersion } = await run(
+      { name: 'weavejs', version: 'latest', nav: ['some-other-file.adoc'], navModules: [{ module: 'main' }] },
+      [tree(0, [])]
+    )
+    expect(componentVersion.navigation[0].module).toBeUndefined()
+  })
+
+  it('warns when navModules is not a list', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    await run({ name: 'weavejs', version: 'latest', nav: [], navModules: 'not-a-list' }, [], { logger })
+    expect(warnedAbout(logger, 'expected a list of entries')).toBe(true)
+  })
+
+  it('warns and skips an entry missing a module key', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    await run({ name: 'weavejs', version: 'latest', nav: [], navModules: [{ title: 'No module key' }] }, [], {
+      logger,
+    })
+    expect(warnedAbout(logger, 'every entry needs a module key')).toBe(true)
+  })
+
+  it('warns and ignores a duplicate nav_modules entry for the same module', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    await run(
+      {
+        name: 'weavejs',
+        version: 'latest',
+        nav: ['modules/main/nav.adoc'],
+        navModules: [
+          { module: 'main', title: 'First' },
+          { module: 'main', title: 'Second' },
+        ],
+      },
+      [tree(0, [{ urlType: 'internal', url: '/x.html', items: [] }])],
+      { logger }
+    )
+    expect(warnedAbout(logger, 'Ignoring duplicate nav_modules entry')).toBe(true)
+  })
+
+  it('warns about a tree matching no nav_modules entry, without failing', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    const { componentVersion } = await run(
+      { name: 'weavejs', version: 'latest', nav: ['modules/other/nav.adoc'], navModules: [{ module: 'main' }] },
+      [tree(0, [{ urlType: 'internal', url: '/x.html', items: [] }])],
+      { logger }
+    )
+    expect(componentVersion.navigation[0].module).toBe('other')
+    expect(warnedAbout(logger, 'No nav_modules entry for module')).toBe(true)
+  })
+
+  it('warns about a declared nav_modules entry that matches no navigation file', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    await run({ name: 'weavejs', version: 'latest', nav: [], navModules: [{ module: 'ghost' }] }, [], { logger })
+    expect(warnedAbout(logger, 'matches no navigation file')).toBe(true)
+  })
+
+  it('does nothing for a bucket with no navModules declared', async () => {
+    const { componentVersion } = await run({ name: 'weavejs', version: 'latest', nav: [] }, [
+      tree(0, [{ urlType: 'internal', url: '/x.html', items: [] }]),
+    ])
+    expect(componentVersion.navigation[0].module).toBeUndefined()
+  })
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inditextech/docouture-antora-extensions",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Antora pipeline extensions shared by docouture documentation sites — per-module navigation metadata (nav_modules)",
   "repository": {
     "type": "git",
@@ -27,7 +27,7 @@
     "@shikijs/themes": "~4.4.0",
     "node-html-parser": "^9.0.1",
     "shiki": "~4.4.0",
-    "@inditextech/docouture-asciidoc-extensions": "1.0.0"
+    "@inditextech/docouture-asciidoc-extensions": "1.1.0"
   },
   "devDependencies": {
     "@antora/content-classifier": "~3.2.0"