@baiyibai-antora/extensions 1.7.0 → 1.8.0

package/dist/extensions/autoterm/index.js

@@ -0,0 +1,770 @@
+"use strict";
+/**
+ * @baiyibai-antora/extensions - autoterm
+ *
+ * Scans the Antora content catalog for AsciiDoc index term markup and injects
+ * two generated AsciiDoc partials into each participating component-version:
+ *
+ *   modules/ROOT/partials/generated-terminology.adoc
+ *   modules/ROOT/partials/generated-index.adoc
+ *
+ * A component participates by containing a page that includes the partial:
+ *
+ *   include::partial$generated-terminology.adoc[]
+ *   include::partial$generated-index.adoc[]
+ *
+ * The including page's position in nav.adoc controls where the section
+ * appears. The terminology page carries :!sectnums: to render unnumbered.
+ * The index page carries :assembly-style: index so the Antora Assembler
+ * preserves the [index] section and stock asciidoctor-pdf renders the
+ * page-numbered index; the generated index partial holds the web-linked
+ * index guarded by ifndef::loader-assembler[] so it renders only outside
+ * the PDF build.
+ *
+ * Definitions come from a shared table (the autoterm-data component's
+ * partial) optionally overridden per component by a local partial named
+ * trademark-local-style: modules/ROOT/partials/terminology-local.adoc.
+ * Local rows replace shared rows for the same term.
+ *
+ * Configuration in antora-playbook.yml:
+ *
+ * antora:
+ *   extensions:
+ *     - require: '@baiyibai-antora/extensions/autoterm'
+ *       autoterm:
+ *         enabled: true
+ *         # Antora resource ID or filename of the shared definitions partial.
+ *         terminology_file: 'ROOT:partial$terminology-table.adoc'
+ *         # Filename of a component's local override partial.
+ *         local_file: 'terminology-local.adoc'
+ *         # Filenames of the generated partials.
+ *         terminology_partial: 'generated-terminology.adoc'
+ *         index_partial: 'generated-index.adoc'
+ *         # AsciiDoc cols attribute for each generated table.
+ *         terminology_cols: '15,85'
+ *         index_cols: '30,70'
+ *         # 'combined' welds each letter into its group's first row (default);
+ *         # 'separate' emits the letter as its own row (may orphan at a page
+ *         # bottom in the PDF).
+ *         letter_style: 'combined'
+ *         # Attribution line rendered above the Terminology content outside
+ *         # the PDF build. AsciiDoc inline markup allowed; empty disables.
+ *         attribution: 'Generated by https://gitlab.com/baiyibai-antora/baiyibai-extensions[autoterm].'
+ *
+ * The including page overrides presentation per component through header
+ * attributes: :autoterm-terminology-cols:, :autoterm-index-cols:,
+ * :autoterm-letter-style:.
+ *
+ * The generated partials live in the content catalog and regenerate on every
+ * build. Setting write_to_disk: true additionally writes them into the
+ * component's local worktree; components loaded from a remote source skip
+ * the disk write, mirroring trademark-it.
+ *
+ * Per-component configuration in a component's antora.yml under
+ * ext.autoterm overrides local_file, terminology_cols, index_cols,
+ * letter_style, write_to_disk, and enabled for that component-version.
+ * Unlike trademark-it, the block is optional: participation comes from the
+ * include, not from the block.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTerminologyTable = parseTerminologyTable;
+exports.mergeTerminology = mergeTerminology;
+exports.stripVerbatimBlocks = stripVerbatimBlocks;
+exports.scanIndexterms = scanIndexterms;
+exports.buildTerminologyEntries = buildTerminologyEntries;
+exports.generateTerminologyPartial = generateTerminologyPartial;
+exports.generateIndexPartial = generateIndexPartial;
+exports.pageTitle = pageTitle;
+exports.pageAttribute = pageAttribute;
+exports.register = register;
+const log_time_1 = require("../../lib/log-time");
+const index_1 = require("../trademark-it/index");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+// ---------------------------------------------------------------------------
+// Logging helpers  (mirrors trademark-it style)
+// ---------------------------------------------------------------------------
+let quietMode = true;
+function logEvent(message) {
+    console.log(`[${(0, log_time_1.nowLocal)()}] \x1b[94mEVENT\x1b[0m (autoterm): \x1b[94m${message}\x1b[0m`);
+}
+function makeLogger(hostLogger) {
+    return {
+        debug: (m) => { if (!quietMode) {
+            if (hostLogger?.debug)
+                hostLogger.debug(m);
+            else
+                console.debug(m);
+        } },
+        info: (m) => { if (!quietMode) {
+            if (hostLogger?.info)
+                hostLogger.info(m);
+            else
+                console.log(m);
+        } },
+        warn: (m) => { if (hostLogger?.warn)
+            hostLogger.warn(m);
+        else
+            console.warn(m); },
+        error: (m) => { if (hostLogger?.error)
+            hostLogger.error(m);
+        else
+            console.error(m); },
+    };
+}
+// ---------------------------------------------------------------------------
+// Config helpers  (mirrors trademark-it style)
+// ---------------------------------------------------------------------------
+function toBool(v, def) {
+    if (v === true)
+        return true;
+    if (v === false)
+        return false;
+    if (typeof v === 'string') {
+        const s = v.trim().toLowerCase();
+        if (['true', '1', 'yes', 'on'].includes(s))
+            return true;
+        if (['false', '0', 'no', 'off'].includes(s))
+            return false;
+    }
+    return def;
+}
+function pick(obj, keys, def) {
+    for (const k of keys) {
+        if (obj && obj[k] !== undefined)
+            return obj[k];
+    }
+    return def;
+}
+// ---------------------------------------------------------------------------
+// Definitions table parser
+//
+// Parses the shared/local terminology table: term in the first column,
+// abbreviation in the second, definition in the third. Cell layout follows
+// the trademark table style: header row inline, data cells one per line.
+// ---------------------------------------------------------------------------
+function parseTerminologyTable(asciidocText) {
+    const definitions = new Map();
+    const tableMatch = asciidocText.match(/\|={3,}([\s\S]*?)\|={3,}/);
+    if (!tableMatch)
+        return definitions;
+    const tableBody = tableMatch[1];
+    let colCount = 3;
+    const colsMatch = asciidocText.match(/\[[^\]]*cols\s*=\s*["']([^"']+)["']/);
+    if (colsMatch)
+        colCount = colsMatch[1].split(',').length;
+    const cells = [];
+    for (const raw of tableBody.split('\n')) {
+        const line = raw.trim();
+        if (!line || line === '|===')
+            continue;
+        if (!line.startsWith('|')) {
+            // Continuation of the previous cell (wrapped definition text).
+            if (cells.length > 0)
+                cells[cells.length - 1] += ` ${line}`;
+            continue;
+        }
+        const parts = line.split('|').map((p) => p.trim()).filter((p) => p !== '');
+        if (parts.length > 1) {
+            cells.push(...parts);
+        }
+        else {
+            cells.push(line.slice(1).trim());
+        }
+    }
+    const rows = [];
+    for (let i = 0; i + colCount - 1 < cells.length; i += colCount) {
+        rows.push(cells.slice(i, i + colCount));
+    }
+    // Skip the header row.
+    for (const row of rows.slice(1)) {
+        const fullTerm = (row[0] ?? '').trim();
+        if (!fullTerm)
+            continue;
+        definitions.set(fullTerm, {
+            fullTerm,
+            abbreviation: (row[1] ?? '').trim(),
+            definition: (row[2] ?? '').trim(),
+        });
+    }
+    return definitions;
+}
+/**
+ * Merge a component-local definitions map over the shared map. A local entry
+ * replaces the shared entry whose full term matches exactly, mirroring the
+ * exact-key lookup the definitions serve; remaining local entries are added.
+ */
+function mergeTerminology(shared, local) {
+    const merged = new Map(shared);
+    const overridden = [];
+    for (const [key, entry] of local) {
+        if (merged.has(key))
+            overridden.push(key);
+        merged.set(key, entry);
+    }
+    return { merged, overridden };
+}
+// ---------------------------------------------------------------------------
+// Indexterm scanner
+//
+// Extracts index terms from raw AsciiDoc source: ((visible)), (((concealed))),
+// indexterm:[...], and indexterm2:[...]. Comments and suppressed conditionals
+// are stripped first. An inner parenthetical names an abbreviation:
+// ((Full Term (Abbr) )) — the trailing space before the closing marks keeps
+// the stock PDF index intact, but the scanner accepts both spellings.
+// ---------------------------------------------------------------------------
+/**
+ * Blank the content of listing and literal blocks (---- and .... fences).
+ * Asciidoctor does not process index terms in verbatim context, so the
+ * scanner must not either; documentation showing ((...)) syntax inside a
+ * listing stays inert. Line count is preserved.
+ */
+function stripVerbatimBlocks(text) {
+    const out = [];
+    let fence = null;
+    for (const line of text.split('\n')) {
+        const trimmed = line.trimEnd();
+        if (fence) {
+            if (trimmed === fence)
+                fence = null;
+            out.push('');
+            continue;
+        }
+        if (/^-{4,}$/.test(trimmed) || /^\.{4,}$/.test(trimmed)) {
+            fence = trimmed;
+            out.push('');
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}
+function scanIndexterms(sourceText, ignoreConditionals = []) {
+    // Inline passthroughs display index term syntax without indexing it
+    // (+((Full Term))+), matching Asciidoctor's behavior; remove them and
+    // verbatim block content before scanning.
+    const text = stripVerbatimBlocks((0, index_1.stripNonContent)(sourceText, ignoreConditionals))
+        .replace(/\+\({2,3}[\s\S]+?\){2,3}\+/g, ' ');
+    const found = [];
+    const record = (raw) => {
+        const inner = raw.trim();
+        if (!inner)
+            return;
+        const abbrMatch = inner.match(/^(.*?)\s+\(([^()]+)\)$/);
+        if (abbrMatch) {
+            found.push({ full: abbrMatch[1].trim(), abbr: abbrMatch[2].trim() });
+        }
+        else {
+            found.push({ full: inner, abbr: null });
+        }
+    };
+    // Concealed terms first so the visible-form regex does not half-match them.
+    const concealedRe = /\(\(\(([\s\S]+?)\)\)\)/g;
+    let scrubbed = text.replace(concealedRe, (_, inner) => {
+        record(inner.split(',')[0]);
+        return ' ';
+    });
+    // Visible flow terms. The lazy match stops at the first )); when the
+    // captured text holds an unclosed ( and the next character is ), extend by
+    // one so ((Full Term (Abbr))) yields "Full Term (Abbr)".
+    const visibleRe = /\(\(([\s\S]+?)\)\)/g;
+    let m;
+    while ((m = visibleRe.exec(scrubbed)) !== null) {
+        let inner = m[1];
+        const opens = (inner.match(/\(/g) ?? []).length;
+        const closes = (inner.match(/\)/g) ?? []).length;
+        if (opens > closes && scrubbed[visibleRe.lastIndex] === ')') {
+            inner += ')';
+            visibleRe.lastIndex += 1;
+        }
+        record(inner);
+    }
+    // Macro forms.
+    const macroRe = /indexterm2?:\[([^\]]+)\]/g;
+    while ((m = macroRe.exec(text)) !== null) {
+        record(m[1].split(',')[0]);
+    }
+    return found;
+}
+function escapeCell(s) {
+    return s.replace(/\|/g, '\\|');
+}
+/**
+ * Build the terminology entries from the scanned terms and the merged
+ * definitions, applying the ledger rules: a term with an abbreviation always
+ * appears; a term without one appears only when it has a definition; the
+ * entry label is the abbreviation or the full term; the body is
+ * "Full Term – definition" for abbreviated terms, the definition alone
+ * otherwise; duplicate full terms keep the last-scanned occurrence.
+ */
+function buildTerminologyEntries(terms, definitions) {
+    const byFull = new Map();
+    for (const t of terms)
+        byFull.set(t.full, t);
+    const entries = [];
+    for (const t of byFull.values()) {
+        const definition = definitions.get(t.full)?.definition ?? '';
+        if (!t.abbr && !definition)
+            continue;
+        const label = t.abbr ?? t.full;
+        const body = t.abbr
+            ? (definition ? `${t.full} – ${definition}` : t.full)
+            : definition;
+        const sortKey = label.toLowerCase();
+        entries.push({ label, body, sortKey, letter: (sortKey[0] ?? '').toUpperCase() });
+    }
+    entries.sort((a, b) => a.sortKey.localeCompare(b.sortKey, undefined, { numeric: true, sensitivity: 'base' }));
+    return entries;
+}
+function generateTerminologyPartial(entries, cols = '15,85', letterStyle = 'combined', attribution = '') {
+    if (entries.length === 0) {
+        return '// No index terms detected in this component.\n';
+    }
+    const lines = ['// Auto-generated by autoterm. Do not edit.'];
+    // The attribution renders only outside the PDF build, where a generated
+    // section without explanation reads strangely.
+    if (attribution) {
+        lines.push('ifndef::loader-assembler[]');
+        lines.push('[.autoterm-attribution]');
+        lines.push(attribution);
+        lines.push('endif::[]');
+        lines.push('');
+    }
+    lines.push(`[.autoterm-terminology,cols="${cols}",frame=none,grid=none]`, '|===');
+    let currentLetter = '';
+    for (const entry of entries) {
+        const newLetter = entry.letter !== currentLetter;
+        currentLetter = entry.letter;
+        if (newLetter && letterStyle === 'separate') {
+            lines.push(`|*${entry.letter}*`);
+            lines.push('|');
+            lines.push('');
+        }
+        if (newLetter && letterStyle === 'combined') {
+            lines.push(`|*${entry.letter}* +`);
+            lines.push(escapeCell(entry.label));
+            lines.push(`|{empty} +`);
+            lines.push(escapeCell(entry.body));
+        }
+        else {
+            lines.push(`|${escapeCell(entry.label)}`);
+            lines.push(`|${escapeCell(entry.body)}`);
+        }
+        lines.push('');
+    }
+    lines.push('|===');
+    lines.push('');
+    return lines.join('\n');
+}
+function generateIndexPartial(occurrences, cols = '30,70') {
+    if (occurrences.length === 0) {
+        return '// No index terms detected in this component.\n';
+    }
+    const sorted = [...occurrences].sort((a, b) => a.sortKey.localeCompare(b.sortKey, undefined, { numeric: true, sensitivity: 'base' }));
+    const lines = [
+        '// Auto-generated by autoterm. Do not edit.',
+        'ifndef::loader-assembler[]',
+        `[.autoterm-index,cols="${cols}",frame=none,grid=none]`,
+        '|===',
+    ];
+    let currentLetter = '';
+    for (const occ of sorted) {
+        const xrefs = occ.pages
+            .map((p) => `xref:${p.module === 'ROOT' ? '' : `${p.module}:`}${p.relative}[${p.title}]`)
+            .join(', ');
+        if (occ.letter !== currentLetter) {
+            currentLetter = occ.letter;
+            lines.push(`|*${occ.letter}* +`);
+            lines.push(escapeCell(occ.display));
+            lines.push('a|{empty} +');
+            lines.push(xrefs);
+        }
+        else {
+            lines.push(`|${escapeCell(occ.display)}`);
+            lines.push(`a|${xrefs}`);
+        }
+        lines.push('');
+    }
+    lines.push('|===');
+    lines.push('endif::[]');
+    lines.push('');
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Page helpers
+// ---------------------------------------------------------------------------
+/** Extract the page title from raw AsciiDoc source. */
+function pageTitle(sourceText) {
+    const m = sourceText.match(/^=\s+(.+)$/m);
+    return m ? m[1].trim() : '';
+}
+/** Read a :name: value from a raw page header, or null. */
+function pageAttribute(sourceText, name) {
+    const re = new RegExp(`^:${name}:\\s*(.*)$`, 'm');
+    const m = sourceText.match(re);
+    return m ? m[1].trim() : null;
+}
+function includesPartial(sourceText, partialName) {
+    const re = new RegExp(`^include::[^\\[]*partial\\$${partialName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\[`, 'm');
+    return re.test(sourceText);
+}
+// ---------------------------------------------------------------------------
+// Antora extension entry point
+// ---------------------------------------------------------------------------
+function register(context) {
+    const ctx = context ?? this;
+    const logger = makeLogger(ctx.getLogger ? ctx.getLogger('autoterm') : undefined);
+    let cfg = {
+        enabled: true,
+        quiet: true,
+        terminology_file: 'ROOT:partial$terminology-table.adoc',
+        local_file: 'terminology-local.adoc',
+        terminology_partial: 'generated-terminology.adoc',
+        index_partial: 'generated-index.adoc',
+        terminology_cols: '15,85',
+        index_cols: '30,70',
+        letter_style: 'combined',
+        attribution: 'Generated by https://gitlab.com/baiyibai-antora/baiyibai-extensions[autoterm].',
+        write_to_disk: false,
+        suppress_events: false,
+    };
+    // Per-component overrides from antora.yml ext.autoterm, captured during
+    // contentAggregated where ext is still present, mirroring trademark-it.
+    const extByCompVer = new Map();
+    ctx.once('contentAggregated', ({ contentAggregate }) => {
+        for (const item of (contentAggregate ?? [])) {
+            const atExt = item.ext?.['autoterm'];
+            if (atExt && typeof atExt === 'object') {
+                extByCompVer.set(`${item.name}@${item.version}`, atExt);
+            }
+        }
+    });
+    ctx.once('playbookBuilt', async ({ playbook }) => {
+        const extEntry = (playbook?.antora?.extensions ?? []).find((ext) => String(ext.require ?? '').includes('autoterm')) ?? {};
+        const raw = (extEntry.autoterm ?? extEntry.autoTerm ?? {});
+        cfg = {
+            enabled: toBool(pick(raw, ['enabled'], cfg.enabled), cfg.enabled),
+            quiet: toBool(pick(raw, ['quiet'], cfg.quiet), cfg.quiet),
+            terminology_file: String(pick(raw, ['terminology_file', 'terminologyFile'], cfg.terminology_file)),
+            local_file: String(pick(raw, ['local_file', 'localFile'], cfg.local_file)),
+            terminology_partial: String(pick(raw, ['terminology_partial', 'terminologyPartial'], cfg.terminology_partial)),
+            index_partial: String(pick(raw, ['index_partial', 'indexPartial'], cfg.index_partial)),
+            terminology_cols: String(pick(raw, ['terminology_cols', 'terminologyCols'], cfg.terminology_cols)),
+            index_cols: String(pick(raw, ['index_cols', 'indexCols'], cfg.index_cols)),
+            letter_style: pick(raw, ['letter_style', 'letterStyle'], cfg.letter_style) === 'separate' ? 'separate' : 'combined',
+            attribution: String(pick(raw, ['attribution'], cfg.attribution)),
+            write_to_disk: toBool(pick(raw, ['write_to_disk', 'writeToDisk', 'writetodisk'], cfg.write_to_disk), cfg.write_to_disk),
+            suppress_events: toBool(pick(raw, ['suppress_events', 'suppressEvents'], cfg.suppress_events), cfg.suppress_events),
+        };
+        quietMode = cfg.quiet;
+        logger.debug(`autoterm config: ${JSON.stringify(cfg)}`);
+    });
+    ctx.once('contentClassified', async ({ playbook, contentCatalog }) => {
+        if (!cfg.enabled) {
+            logger.debug('autoterm disabled (skipped)');
+            return;
+        }
+        if (!contentCatalog) {
+            logger.error('contentCatalog is missing');
+            return;
+        }
+        logEvent('Executing autoterm');
+        // -----------------------------------------------------------------------
+        // 1. Locate and parse the shared definitions table.
+        // -----------------------------------------------------------------------
+        const sharedText = resolveDefinitionsFile(cfg.terminology_file, contentCatalog, playbook, logger);
+        const sharedDefinitions = sharedText ? parseTerminologyTable(sharedText) : new Map();
+        if (!sharedText) {
+            logger.warn(`autoterm: shared definitions file "${cfg.terminology_file}" not found; entries render without definitions`);
+        }
+        else {
+            logger.debug(`autoterm: parsed ${sharedDefinitions.size} shared definitions`);
+        }
+        // -----------------------------------------------------------------------
+        // 2. Per component-version: detect participation, scan, generate, inject.
+        // -----------------------------------------------------------------------
+        const componentVersions = new Map();
+        for (const f of contentCatalog.getFiles()) {
+            if (!f.src.component || !f.src.version)
+                continue;
+            const versions = componentVersions.get(f.src.component) ?? new Set();
+            versions.add(f.src.version);
+            componentVersions.set(f.src.component, versions);
+        }
+        for (const [component, versions] of componentVersions) {
+            for (const version of versions) {
+                const files = contentCatalog.getFiles().filter((f) => f.src.component === component && f.src.version === version);
+                const pages = files.filter((f) => f.src.family === 'page');
+                let terminologyHost;
+                let indexHost;
+                for (const p of pages) {
+                    const text = p.contents.toString('utf8');
+                    if (!terminologyHost && includesPartial(text, cfg.terminology_partial))
+                        terminologyHost = p;
+                    if (!indexHost && includesPartial(text, cfg.index_partial))
+                        indexHost = p;
+                }
+                if (!terminologyHost && !indexHost) {
+                    logger.debug(`autoterm: ${component}@${version} — skipped (no page includes a generated partial)`);
+                    continue;
+                }
+                // Per-component overrides. The block is optional: participation comes
+                // from the include, not from the block.
+                const compExt = extByCompVer.get(`${component}@${version}`) ?? {};
+                if (!toBool(compExt['enabled'], true)) {
+                    logger.debug(`autoterm: ${component}@${version} — skipped (enabled: false)`);
+                    continue;
+                }
+                const compLocalFile = typeof compExt['local_file'] === 'string' ? compExt['local_file']
+                    : typeof compExt['localFile'] === 'string' ? compExt['localFile']
+                        : cfg.local_file;
+                const compTermCols = typeof compExt['terminology_cols'] === 'string' ? compExt['terminology_cols'] : cfg.terminology_cols;
+                const compIndexCols = typeof compExt['index_cols'] === 'string' ? compExt['index_cols'] : cfg.index_cols;
+                const compLetterStyle = compExt['letter_style'] === 'separate' ? 'separate'
+                    : compExt['letter_style'] === 'combined' ? 'combined'
+                        : cfg.letter_style;
+                const compWriteToDisk = toBool(compExt['write_to_disk'] ?? compExt['writeToDisk'], cfg.write_to_disk);
+                // A contributor component's own ext.autoterm local_file naming wins
+                // for that component's local table lookup.
+                const findLocalFile = (comp, ver) => {
+                    const theirExt = extByCompVer.get(`${comp}@${ver}`) ?? {};
+                    const name = typeof theirExt['local_file'] === 'string' ? theirExt['local_file']
+                        : comp === component ? compLocalFile
+                            : cfg.local_file;
+                    return contentCatalog.getFiles().find((f) => f.src.component === comp && f.src.version === ver &&
+                        f.src.family === 'partial' &&
+                        (f.src.relative === name || f.src.basename === name));
+                };
+                // Scan pages and partials, excluding the generated and local partials.
+                const excluded = new Set([cfg.terminology_partial, cfg.index_partial, compLocalFile]);
+                const scanFiles = files.filter((f) => (f.src.family === 'page' || f.src.family === 'partial') &&
+                    !excluded.has(f.src.relative ?? '') &&
+                    !excluded.has(f.src.basename ?? ''));
+                // Pre-populate the include-resolution visited set with every file in
+                // this scan plus the excluded data partials, so resolved includes are
+                // neither double-counted nor pulled from the generated partials.
+                const includeVisited = new Set();
+                for (const f of files) {
+                    if (f.src.family !== 'page' && f.src.family !== 'partial')
+                        continue;
+                    const key = `${f.src.component}@${f.src.version}:${f.src.module}:${f.src.family}$${f.src.relative}`;
+                    if (scanFiles.includes(f))
+                        includeVisited.add(key);
+                    if (excluded.has(f.src.relative ?? '') || excluded.has(f.src.basename ?? ''))
+                        includeVisited.add(key);
+                }
+                const allTerms = [];
+                const occurrenceMap = new Map();
+                for (const f of scanFiles) {
+                    let text = f.contents.toString('utf8');
+                    // Resolve include:: directives on pages so terms living in
+                    // transcluded content, such as a reference page carried by another
+                    // component, are collected and attributed to the including page.
+                    if (f.src.family === 'page') {
+                        const extra = (0, index_1.collectIncludeText)(text, contentCatalog, component, version, f.src.module ?? 'ROOT', includeVisited);
+                        if (extra)
+                            text = `${text}\n${extra}`;
+                    }
+                    const terms = scanIndexterms(text);
+                    allTerms.push(...terms);
+                    if (f.src.family !== 'page')
+                        continue;
+                    const title = pageTitle(text) || (f.src.relative ?? '');
+                    for (const t of terms) {
+                        const display = t.abbr ? `${t.full} (${t.abbr})` : t.full;
+                        const sortKey = display.toLowerCase();
+                        const occ = occurrenceMap.get(display) ?? {
+                            display,
+                            sortKey,
+                            letter: (sortKey[0] ?? '').toUpperCase(),
+                            pages: [],
+                        };
+                        const ref = { module: f.src.module ?? 'ROOT', relative: f.src.relative ?? '', title };
+                        if (!occ.pages.some((p) => p.module === ref.module && p.relative === ref.relative)) {
+                            occ.pages.push(ref);
+                        }
+                        occurrenceMap.set(display, occ);
+                    }
+                }
+                if (!cfg.suppress_events) {
+                    logEvent(`${component}@${version} — ${occurrenceMap.size} index term(s) detected`);
+                }
+                // Merge definitions. Order, lowest to highest precedence: the shared
+                // table; contributing components' local files, in component-name
+                // order, where a contributor is any component whose content was
+                // pulled into this scan through include resolution; the participating
+                // component's own local file last.
+                const contributors = new Map();
+                for (const key of includeVisited) {
+                    const at = key.indexOf('@');
+                    const colon = key.indexOf(':', at);
+                    if (at < 0 || colon < 0)
+                        continue;
+                    const comp = key.slice(0, at);
+                    if (comp !== component)
+                        contributors.set(comp, key.slice(at + 1, colon));
+                }
+                let definitions = sharedDefinitions;
+                const mergeLocal = (comp, ver, label) => {
+                    const entry = findLocalFile(comp, ver);
+                    if (!entry)
+                        return;
+                    const local = parseTerminologyTable(entry.contents.toString('utf8'));
+                    const { merged, overridden } = mergeTerminology(definitions, local);
+                    definitions = merged;
+                    const note = overridden.length > 0 ? ` (overriding: ${overridden.join(', ')})` : '';
+                    logger.info(`autoterm: ${component}@${version} — merged ${local.size} definitions from ${label} ${cfg.local_file}${note}`);
+                };
+                for (const comp of [...contributors.keys()].sort()) {
+                    mergeLocal(comp, contributors.get(comp), `contributor ${comp}'s`);
+                }
+                mergeLocal(component, version, 'own');
+                // Generate and inject.
+                if (terminologyHost) {
+                    const hostText = terminologyHost.contents.toString('utf8');
+                    const cols = pageAttribute(hostText, 'autoterm-terminology-cols') ?? compTermCols;
+                    const style = pageAttribute(hostText, 'autoterm-letter-style') === 'separate' ? 'separate'
+                        : pageAttribute(hostText, 'autoterm-letter-style') === 'combined' ? 'combined'
+                            : compLetterStyle;
+                    const entries = buildTerminologyEntries(allTerms, definitions);
+                    const content = generateTerminologyPartial(entries, cols, style, cfg.attribution);
+                    injectPartial(contentCatalog, files, component, version, cfg.terminology_partial, content, compWriteToDisk, logger);
+                }
+                if (indexHost) {
+                    const hostText = indexHost.contents.toString('utf8');
+                    const cols = pageAttribute(hostText, 'autoterm-index-cols') ?? compIndexCols;
+                    const content = generateIndexPartial([...occurrenceMap.values()], cols);
+                    injectPartial(contentCatalog, files, component, version, cfg.index_partial, content, compWriteToDisk, logger);
+                }
+            }
+        }
+        logEvent('autoterm finished');
+    });
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Locate the shared definitions file: catalog partial by resource-ID suffix,
+ * then filesystem path, then basename match — mirroring trademark-it's
+ * resolution strategies.
+ */
+function resolveDefinitionsFile(ref, contentCatalog, playbook, logger) {
+    const catalogFile = contentCatalog.getFiles().find((f) => {
+        if (f.src.family !== 'partial')
+            return false;
+        const rel = f.src.relative ?? '';
+        const resourceId = `${f.src.module ?? 'ROOT'}:partial$${rel}`;
+        return resourceId === ref || resourceId.endsWith(ref) || rel === ref || rel.endsWith(ref);
+    });
+    if (catalogFile) {
+        logger.debug(`autoterm: definitions resolved from catalog (${catalogFile.src.path})`);
+        return catalogFile.contents.toString('utf8');
+    }
+    const fsPath = ref.startsWith('/') ? ref : `${playbook.dir}/${ref}`;
+    if (fs.existsSync(fsPath)) {
+        logger.debug(`autoterm: definitions resolved from filesystem (${fsPath})`);
+        return fs.readFileSync(fsPath, 'utf8');
+    }
+    const basename = ref.split(/[\\/]/).pop() ?? ref;
+    const fallback = contentCatalog.getFiles().find((f) => f.src.family === 'partial' && f.src.basename === basename);
+    if (fallback) {
+        logger.debug(`autoterm: definitions resolved by basename fallback (${fallback.src.path})`);
+        return fallback.contents.toString('utf8');
+    }
+    return null;
+}
+/**
+ * Inject a generated partial into the catalog, replacing an existing entry's
+ * contents when a file with that name was already loaded. When write_to_disk
+ * is enabled and the component has a local worktree, write the file there
+ * too; components loaded from a remote source skip the disk write,
+ * mirroring trademark-it.
+ */
+function injectPartial(contentCatalog, componentFiles, component, version, relative, content, writeToDisk, logger) {
+    const contents = Buffer.from(content, 'utf8');
+    const existing = componentFiles.find((f) => f.src.family === 'partial' &&
+        (f.src.relative === relative || f.src.path === `modules/ROOT/partials/${relative}`));
+    if (existing) {
+        existing.contents = contents;
+        logger.debug(`autoterm: updated partial$${relative} in ${component}@${version}`);
+    }
+    else {
+        const basename = relative.split('/').pop() ?? relative;
+        try {
+            contentCatalog.addFile({
+                contents,
+                src: {
+                    component,
+                    version,
+                    module: 'ROOT',
+                    family: 'partial',
+                    relative,
+                    path: `modules/ROOT/partials/${relative}`,
+                    basename,
+                    stem: basename.replace(/\.[^.]+$/, ''),
+                    extname: basename.includes('.') ? `.${basename.split('.').pop()}` : '',
+                    mediaType: 'text/asciidoc',
+                    origin: undefined,
+                },
+            });
+            logger.debug(`autoterm: injected partial$${relative} into ${component}@${version}`);
+        }
+        catch {
+            logger.warn(`autoterm: could not inject partial$${relative} into ${component}@${version}`);
+        }
+    }
+    if (!writeToDisk)
+        return;
+    const originFile = componentFiles.find((f) => f.src.origin?.worktree);
+    const worktree = originFile?.src.origin?.worktree;
+    const startPath = originFile?.src.origin?.startPath ?? '';
+    if (worktree) {
+        const diskPath = path.join(worktree, startPath, 'modules', 'ROOT', 'partials', relative);
+        try {
+            fs.mkdirSync(path.dirname(diskPath), { recursive: true });
+            fs.writeFileSync(diskPath, content, 'utf8');
+            logger.debug(`autoterm: wrote partial to disk (${diskPath})`);
+        }
+        catch (err) {
+            logger.warn(`autoterm: could not write partial to disk (${diskPath}): ${String(err)}`);
+        }
+    }
+    else {
+        logger.debug(`autoterm: write_to_disk skipped for ${component}@${version} — no local worktree`);
+    }
+}
+//# sourceMappingURL=index.js.map