@iwonz/ywtc 3.1.0 → 3.2.1

package/dist/content-model.js

@@ -1,4 +1,5 @@
 import transform from '@diplodoc/transform';
+import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { load } from 'cheerio';
 import { LinkifyIt } from 'linkify-it';
@@ -12,9 +13,128 @@ import { unified } from 'unified';
 import { convertYfmToStorage } from './conversion.js';
 import { normalizeWikiSlug, resolveRelativeWikiSlug } from './input.js';
 const linkifier = new LinkifyIt();
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
 function escapeHtml(value) {
     return String(value ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
 }
+function absoluteResourceUrl(page, resource) {
+    if (resource.downloadUrl) {
+        try {
+            return new URL(resource.downloadUrl, page.url).toString();
+        }
+        catch {
+            // Fall through to the page URL so the resource remains discoverable.
+        }
+    }
+    return page.url;
+}
+function normalizedResourceAlias(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    let normalized = trimmed;
+    try {
+        normalized = decodeURIComponent(trimmed);
+    }
+    catch {
+        // Keep provider text when percent encoding is malformed.
+    }
+    return normalized.replace(/\\/g, '/').replace(/^\.\//, '').toLocaleLowerCase();
+}
+function resourceAliasCandidates(reference) {
+    const aliases = new Set();
+    const add = (value) => {
+        if (!value)
+            return;
+        const normalized = normalizedResourceAlias(value);
+        if (!normalized)
+            return;
+        aliases.add(normalized);
+        aliases.add(normalized.replace(/^attachment:/, ''));
+        aliases.add(normalized.replace(/^\/+/, ''));
+        const marker = normalized.match(/(?:^|\/)((?:\.files|_files|attachments)\/.*)$/i)?.[1];
+        if (marker)
+            aliases.add(marker);
+    };
+    const withoutFragment = reference.split('#', 1)[0] ?? reference;
+    add(withoutFragment);
+    try {
+        const url = new URL(withoutFragment);
+        add(url.pathname);
+    }
+    catch {
+        // Relative references are already covered above.
+    }
+    const snapshot = [...aliases];
+    for (const alias of snapshot)
+        add(alias.split('/').at(-1));
+    return [...aliases];
+}
+export function preferredResourceName(resource) {
+    return resource.preferredName ?? resource.name;
+}
+export function sourceResourceAliases(page, resource) {
+    const aliases = new Set();
+    const add = (value) => {
+        for (const alias of value ? resourceAliasCandidates(value) : [])
+            aliases.add(alias);
+    };
+    add(resource.name);
+    add(resource.preferredName);
+    add(resource.downloadUrl);
+    for (const alias of resource.referenceAliases ?? [])
+        add(alias);
+    add(absoluteResourceUrl(page, resource));
+    return [...aliases];
+}
+export function sourceResourceBindings(page, resources) {
+    const bindings = new Map();
+    const aliases = new Map();
+    for (const resource of resources.filter((item) => item.kind !== 'grid')) {
+        for (const alias of sourceResourceAliases(page, resource)) {
+            const matched = aliases.get(alias) ?? [];
+            if (!matched.some((candidate) => candidate.id === resource.id))
+                matched.push(resource);
+            aliases.set(alias, matched);
+        }
+    }
+    for (const [alias, matched] of aliases) {
+        if (matched.length !== 1)
+            continue;
+        const resource = matched[0];
+        bindings.set(alias, { kind: 'source', resource, url: absoluteResourceUrl(page, resource) });
+    }
+    return bindings;
+}
+export function setSourceResourceBinding(bindings, page, resources, resource, binding) {
+    const aliasOwners = new Map();
+    for (const candidate of resources.filter((item) => item.kind !== 'grid')) {
+        for (const alias of sourceResourceAliases(page, candidate)) {
+            const owners = aliasOwners.get(alias) ?? new Set();
+            owners.add(candidate.id);
+            aliasOwners.set(alias, owners);
+        }
+    }
+    for (const alias of sourceResourceAliases(page, resource)) {
+        if (aliasOwners.get(alias)?.size === 1)
+            bindings.set(alias, binding);
+    }
+}
+function bindingTarget(binding) {
+    return binding.kind === 'uploaded' ? binding.resource.url ?? binding.resource.name
+        : binding.kind === 'source' ? binding.url
+            : binding.path;
+}
+function resourceBinding(reference, context) {
+    for (const alias of resourceAliasCandidates(reference)) {
+        const binding = context.resources.get(alias);
+        if (binding)
+            return binding;
+    }
+    return undefined;
+}
 function uniqueReferences(references) {
     const seen = new Set();
     return references.filter((reference) => {
@@ -137,7 +257,69 @@ function storageToSemanticHtml(storage, warnings) {
     });
     return $('main[data-ywtc-root]').html() ?? '';
 }
-function yfmToHtml(content, warnings) {
+export function stripAnsi(value) {
+    let output = '';
+    for (let index = 0; index < value.length;) {
+        const code = value.charCodeAt(index);
+        const controlSequence = code === 0x9b || (code === 0x1b && value[index + 1] === '[');
+        if (controlSequence) {
+            index += code === 0x9b ? 1 : 2;
+            while (index < value.length) {
+                const current = value.charCodeAt(index++);
+                if (current >= 0x40 && current <= 0x7e)
+                    break;
+            }
+            continue;
+        }
+        if (code === 0x1b && value[index + 1] === ']') {
+            index += 2;
+            while (index < value.length) {
+                if (value.charCodeAt(index) === 0x07) {
+                    index += 1;
+                    break;
+                }
+                if (value.charCodeAt(index) === 0x1b && value[index + 1] === '\\') {
+                    index += 2;
+                    break;
+                }
+                index += 1;
+            }
+            continue;
+        }
+        if (code === 0x1b) {
+            index += Math.min(2, value.length - index);
+            continue;
+        }
+        output += value[index];
+        index += 1;
+    }
+    return output;
+}
+function extractTreeDirectives(content) {
+    const directives = [];
+    const next = content.replace(/{%\s*tree\b([^%]*?)%}/gi, (raw, attributes) => {
+        const values = new Map();
+        for (const match of attributes.matchAll(/([\w-]+)\s*=\s*["']([^"']*)["']/g)) {
+            if (match[1] && match[2] !== undefined)
+                values.set(match[1].toLocaleLowerCase(), match[2].toLocaleLowerCase());
+        }
+        const depthValue = Number(values.get('depth'));
+        const sort = values.get('sort');
+        const sortBy = values.get('sort_by');
+        directives.push({
+            raw,
+            ...(Number.isInteger(depthValue) && depthValue > 0 ? { depth: depthValue } : {}),
+            ...(sort === 'asc' || sort === 'desc' ? { sort } : {}),
+            ...(sortBy === 'title' ? { sortBy } : {}),
+        });
+        return '';
+    });
+    return { content: next, directives };
+}
+function containsEmptyYfmHeading(content) {
+    return /^\s{0,3}#{1,6}\s*$/m.test(content);
+}
+function yfmToHtml(content, warnings, normalizations = []) {
     try {
         const result = transform(content || '', {
             allowHTML: true,
@@ -146,11 +328,36 @@ function yfmToHtml(content, warnings) {
             lang: 'ru',
             linkify: true,
         });
-        warnings.push(...(result.logs.warn ?? []), ...(result.logs.error ?? []));
-        return result.result.html || '<p></p>';
+        const $ = load(result.result.html || '<p></p>', null, false);
+        let removedHeadings = 0;
+        $('h1,h2,h3,h4,h5,h6').each((_index, element) => {
+            const heading = $(element);
+            const meaningful = heading.text().replace(/\s+/g, '').length > 0
+                || heading.find('img,table,pre,code').length > 0;
+            if (meaningful)
+                return;
+            heading.find('[id],a[name]').each((_anchorIndex, anchor) => { heading.before($(anchor).clone()); });
+            heading.remove();
+            removedHeadings += 1;
+        });
+        let ignoredHeaderDiagnostics = removedHeadings;
+        for (const diagnostic of [...(result.logs.warn ?? []), ...(result.logs.error ?? [])]) {
+            const clean = stripAnsi(String(diagnostic)).trim();
+            if (/Header without title/i.test(clean)) {
+                if (ignoredHeaderDiagnostics > 0)
+                    ignoredHeaderDiagnostics -= 1;
+                if (removedHeadings > 0 || !containsEmptyYfmHeading(content))
+                    continue;
+            }
+            if (clean)
+                warnings.push(clean);
+        }
+        if (removedHeadings > 0)
+            normalizations.push(`Removed ${removedHeadings} empty heading${removedHeadings === 1 ? '' : 's'} emitted by source conversion`);
+        return $.html() || '<p></p>';
     }
     catch (error) {
-        warnings.push(`YFM transformation failed: ${error instanceof Error ? error.message : String(error)}`);
+        warnings.push(`YFM transformation failed: ${stripAnsi(error instanceof Error ? error.message : String(error))}`);
         return `<pre data-ywtc-fallback><code>${escapeHtml(content)}</code></pre>`;
     }
 }
@@ -160,7 +367,9 @@ function metrics(html) {
 }
 export function normalizePageContent(page) {
     const warnings = [];
-    const html = page.rawFormat === 'yfm' ? yfmToHtml(page.rawContent, warnings) : storageToSemanticHtml(page.rawContent, warnings);
+    const normalizations = [];
+    const tree = page.rawFormat === 'yfm' ? extractTreeDirectives(page.rawContent) : { content: page.rawContent, directives: [] };
+    const html = page.rawFormat === 'yfm' ? yfmToHtml(tree.content, warnings, normalizations) : storageToSemanticHtml(page.rawContent, warnings);
     const references = extractPageReferences(page.rawContent, page.rawFormat).map((reference, index) => ({
         token: `ref-${index}`,
         kind: reference.kind,
@@ -170,6 +379,15 @@ export function normalizePageContent(page) {
         ...(reference.anchor ? { anchor: reference.anchor } : {}),
     }));
     const children = [{ type: 'html', value: html }];
+    children.push(...tree.directives.map((directive) => ({
+        type: 'tree-directive',
+        value: directive.raw,
+        tree: {
+            ...(directive.depth ? { depth: directive.depth } : {}),
+            ...(directive.sort ? { sort: directive.sort } : {}),
+            ...(directive.sortBy ? { sortBy: directive.sortBy } : {}),
+        },
+    })));
     if (warnings.length > 0)
         children.push({ type: 'vendor-extension', vendor: page.provider, value: page.rawContent });
     return {
@@ -178,6 +396,7 @@ export function normalizePageContent(page) {
         rawFormat: page.rawFormat,
         references,
         warnings,
+        normalizations,
         degraded: warnings.length > 0,
         metrics: metrics(html),
     };
@@ -248,6 +467,121 @@ export function renderedPreviewHtml(body, provider) {
     const warnings = [];
     return provider === 'confluence' ? storageToSemanticHtml(body, warnings) : yfmToHtml(body, warnings);
 }
+export function legacyTransferPlaceholder(provider, page) {
+    return provider === 'confluence'
+        ? `<p><em>ywtc transfer in progress from <a href="${escapeHtml(page.url)}">${page.provider}</a>.</em></p>`
+        : `_ywtc transfer in progress from [${page.provider}](${page.url})._`;
+}
+export function isLegacyTransferPlaceholder(body, provider, page) {
+    return body?.trim() === legacyTransferPlaceholder(provider, page).trim();
+}
+function markdownFence(value) {
+    const longest = Math.max(0, ...[...value.matchAll(/`+/g)].map((match) => match[0].length));
+    return '`'.repeat(Math.max(3, longest + 1));
+}
+export function rawContentFallback(page, provider, reason) {
+    const warning = `Preferred rendering failed; complete raw source is shown instead: ${reason}`;
+    if (provider === 'confluence') {
+        const raw = page.rawContent
+            ? `<pre><code>${escapeHtml(page.rawContent)}</code></pre>`
+            : '<p><em>The source page has no body content.</em></p>';
+        return {
+            body: `<p><strong>Source content fallback</strong> · <a href="${escapeHtml(page.url)}">original page</a></p>${raw}`,
+            warnings: [warning],
+            normalizations: [],
+            degraded: true,
+            representedReferences: page.references.length,
+        };
+    }
+    const raw = page.rawContent
+        ? `${markdownFence(page.rawContent)}text\n${page.rawContent}\n${markdownFence(page.rawContent)}`
+        : '_The source page has no body content._';
+    return {
+        body: `**Source content fallback** · [original page](${page.url})\n\n${raw}\n`,
+        warnings: [warning],
+        normalizations: [],
+        degraded: true,
+        representedReferences: page.references.length,
+    };
+}
+function semanticText(value) {
+    return value.replace(/\u00a0/g, ' ').replace(/\s+/g, ' ').trim();
+}
+function semanticContent(body, provider) {
+    const html = renderedPreviewHtml(body, provider);
+    const $ = load(html, null, false);
+    $('script,style').remove();
+    $('h1,h2,h3,h4,h5,h6,p,div,span').each((_index, element) => {
+        const node = $(element);
+        if (!semanticText(node.text()) && node.find('img,table,pre,code,a[href]').length === 0)
+            node.remove();
+    });
+    const textValues = (selector) => $(selector).toArray().map((element) => semanticText($(element).text()));
+    const macroNames = [];
+    if (provider === 'confluence') {
+        const storage = load(`<root>${body}</root>`, { xmlMode: true }, false);
+        storage('ac\\:structured-macro').each((_index, element) => {
+            const macro = storage(element);
+            const name = macro.attr('ac:name') ?? 'unknown';
+            const parameters = macro.children('ac\\:parameter').toArray().map((parameter) => (`${storage(parameter).attr('ac:name') ?? ''}=${semanticText(storage(parameter).text())}`)).sort();
+            macroNames.push(`${name}[${parameters.join(',')}]`);
+        });
+    }
+    return {
+        text: semanticText($.root().text()),
+        headings: $('h1,h2,h3,h4,h5,h6').toArray().map((element) => `${element.tagName}:${semanticText($(element).text())}`),
+        listItems: textValues('li'),
+        tableCells: $('th,td').toArray().map((element) => `${element.tagName}:${semanticText($(element).text())}`),
+        code: textValues('pre,code'),
+        links: $('a[href]').toArray().map((element) => `${$(element).attr('href') ?? ''}|${semanticText($(element).text())}`).sort(),
+        images: $('img').toArray().map((element) => `${$(element).attr('src') ?? ''}|${$(element).attr('alt') ?? ''}`).sort(),
+        anchors: $('[id],a[name]').toArray().map((element) => $(element).attr('id') ?? $(element).attr('name') ?? '').filter(Boolean).sort(),
+        structure: {
+            lists: $('ul,ol').length,
+            rows: $('tr').length,
+            details: $('details').length,
+            asides: $('aside').length,
+            codeBlocks: $('pre').length,
+        },
+        macros: macroNames.sort(),
+    };
+}
+export function semanticContentFingerprint(body, provider) {
+    return sha256(JSON.stringify(semanticContent(body, provider)));
+}
+export function verifyDestinationContent(expectedBody, actualBody, provider, page) {
+    if (actualBody === undefined)
+        return { status: 'failed', differences: [`Verification could not read destination content for ${page.title}`] };
+    if (actualBody.trim().length === 0)
+        return { status: 'failed', differences: [`Verification found empty destination content for ${page.title}`] };
+    if (isLegacyTransferPlaceholder(actualBody, provider, page)) {
+        return { status: 'failed', differences: [`Verification found a transfer placeholder instead of source content for ${page.title}`] };
+    }
+    const expected = semanticContent(expectedBody, provider);
+    const actual = semanticContent(actualBody, provider);
+    const differs = (key) => JSON.stringify(expected[key]) !== JSON.stringify(actual[key]);
+    const missingData = ['text', 'tableCells', 'code', 'links', 'images', 'anchors', 'macros'].filter(differs);
+    if (missingData.length > 0) {
+        return {
+            status: 'failed',
+            differences: [`Verification found destination content that differs from the rendered source for ${page.title}: ${missingData.join(', ')}`],
+        };
+    }
+    const simplifiedFormatting = ['headings', 'listItems', 'structure'].filter(differs);
+    if (simplifiedFormatting.length > 0) {
+        return {
+            status: 'partial',
+            differences: [`Destination formatting was simplified for ${page.title}: ${simplifiedFormatting.join(', ')}`],
+        };
+    }
+    return { status: 'complete', differences: [] };
+}
+export function assertDestinationContent(expectedBody, actualBody, provider, page) {
+    const result = verifyDestinationContent(expectedBody, actualBody, provider, page);
+    if (result.status === 'failed')
+        throw new Error(result.differences.join('; '));
+    return result;
+}
 function relativeTarget(currentPath, targetPath) {
     if (!currentPath)
         return targetPath;
@@ -278,35 +612,78 @@ function rewritePortableHtml(html, context) {
             }
             return;
         }
-        const attachmentName = href.replace(/^attachment:/, '').split('/').at(-1)?.toLocaleLowerCase();
-        const resource = attachmentName ? context.resources.get(attachmentName) : undefined;
-        if (resource)
-            $(element).attr('href', 'path' in resource ? relativeTarget(context.currentPath, resource.path) : resource.url ?? resource.name);
+        const resource = resourceBinding(href, context);
+        const target = resource ? bindingTarget(resource) : undefined;
+        if (resource && target) {
+            $(element).attr('href', resource.kind === 'file' ? relativeTarget(context.currentPath, target) : target);
+        }
     });
     $('img').each((_index, element) => {
         const src = $(element).attr('src') ?? '';
-        const name = src.replace(/^attachment:/, '').split('/').at(-1);
-        if (!name)
-            return;
-        const resource = context.resources.get(name.toLocaleLowerCase());
-        if (resource && 'path' in resource)
-            $(element).attr('src', relativeTarget(context.currentPath, resource.path));
+        const resource = resourceBinding(src, context);
+        const target = resource ? bindingTarget(resource) : undefined;
+        if (resource && target) {
+            $(element).attr('src', resource.kind === 'file' ? relativeTarget(context.currentPath, target) : target);
+        }
     });
     return $.html();
 }
+function treeDirectiveNodes(document) {
+    return document.root.children?.filter((node) => node.type === 'tree-directive') ?? [];
+}
+function treeChildren(context, parentId, directive, depth = 1) {
+    if (directive.depth !== undefined && depth > directive.depth)
+        return [];
+    return [...context.sourcePages.values()]
+        .filter((page) => page.projectedParentId === parentId)
+        .sort((left, right) => {
+        const order = directive.sortBy === 'title' ? left.title.localeCompare(right.title) : left.canonicalId.localeCompare(right.canonicalId);
+        return directive.sort === 'desc' ? -order : order;
+    });
+}
+function renderTreeMarkdown(context, directive) {
+    const render = (parentId, depth) => treeChildren(context, parentId, directive, depth).map((page) => {
+        const destination = context.pages.get(page.canonicalId);
+        if (!destination)
+            return '';
+        const href = 'path' in destination ? relativeTarget(context.currentPath, destination.path) : destination.url;
+        const nested = render(page.canonicalId, depth + 1);
+        return `${'  '.repeat(depth - 1)}- [${page.title}](${href})${nested ? `\n${nested}` : ''}`;
+    }).filter(Boolean).join('\n');
+    return render(context.currentPageId, 1);
+}
+function renderTreeHtml(context, directive) {
+    const render = (parentId, depth) => {
+        const items = treeChildren(context, parentId, directive, depth).map((page) => {
+            const destination = context.pages.get(page.canonicalId);
+            if (!destination)
+                return '';
+            const href = 'path' in destination ? relativeTarget(context.currentPath, destination.path) : destination.url;
+            return `<li><a href="${escapeHtml(href)}">${escapeHtml(page.title)}</a>${render(page.canonicalId, depth + 1)}</li>`;
+        }).filter(Boolean).join('');
+        return items ? `<ul>${items}</ul>` : '';
+    };
+    const tree = render(context.currentPageId, 1);
+    return tree ? `<nav class="ywtc-tree" aria-label="Child pages">${tree}</nav>` : '';
+}
 export async function renderMarkdown(document, context) {
     const html = rewritePortableHtml(htmlFromDocument(document), context);
-    const body = await htmlToMarkdown(html);
-    return { body, warnings: [...document.warnings], degraded: document.degraded, representedReferences: document.references.length };
+    const tree = treeDirectiveNodes(document).map((node) => renderTreeMarkdown(context, node.tree ?? {})).filter(Boolean).join('\n\n');
+    const content = await htmlToMarkdown(html);
+    const body = tree ? `${content.trimEnd()}\n\n${tree}\n` : content;
+    return { body, warnings: [...document.warnings], normalizations: [...(document.normalizations ?? [])], degraded: document.degraded, representedReferences: document.references.length };
 }
 export async function renderStaticHtml(document, context) {
     const rewritten = rewritePortableHtml(htmlFromDocument(document), context);
-    const body = await sanitizeHtml(rewritten);
-    return { body, warnings: [...document.warnings], degraded: document.degraded, representedReferences: document.references.length };
+    const content = await sanitizeHtml(rewritten);
+    const tree = treeDirectiveNodes(document).map((node) => renderTreeHtml(context, node.tree ?? {})).filter(Boolean).join('');
+    const body = `${content}${tree}`;
+    return { body, warnings: [...document.warnings], normalizations: [...(document.normalizations ?? [])], degraded: document.degraded, representedReferences: document.references.length };
 }
 export async function renderYfm(document, context) {
     if (document.rawFormat === 'yfm') {
         let body = document.raw;
+        const resourceWarnings = new Set();
         const replacement = (href) => {
             const current = context.sourcePages.get(context.currentPageId);
             if (!current)
@@ -319,7 +696,13 @@ export async function renderYfm(document, context) {
         };
         body = body.replace(/(!?\[[^\]]*\]\()([^\s)]+)([^)]*\))/g, (match, prefix, href, suffix) => {
             const next = replacement(href);
-            return next ? `${prefix}${next}${suffix}` : match;
+            if (next)
+                return `${prefix}${next}${suffix}`;
+            const binding = resourceBinding(href, context);
+            const target = binding ? bindingTarget(binding) : undefined;
+            if (binding?.kind === 'source')
+                resourceWarnings.add(`Resource uses its source fallback because it was not transferred: ${binding.resource.name}`);
+            return target ? `${prefix}${target}${suffix}` : match;
         });
         body = body.replace(/\[\[([^\]|]+)(\|[^\]]+)?\]\]/g, (match, href, label = '') => {
             const next = replacement(href);
@@ -334,14 +717,78 @@ export async function renderYfm(document, context) {
         const gridHtml = $('.ywtc-grid').toArray().map((element) => $.html(element)).join('');
         if (gridHtml)
             body = `${body.trimEnd()}\n\n${(await htmlToMarkdown(gridHtml)).trimStart()}`;
-        return { body, warnings: [...document.warnings], degraded: document.degraded, representedReferences: document.references.length };
+        return {
+            body,
+            warnings: [...document.warnings, ...resourceWarnings],
+            normalizations: [...(document.normalizations ?? [])],
+            degraded: document.degraded || resourceWarnings.size > 0,
+            representedReferences: document.references.length,
+        };
     }
     const body = await htmlToMarkdown(rewritePortableHtml(htmlFromDocument(document), context));
-    return { body, warnings: [...document.warnings, 'Confluence Storage Format was converted to YFM-compatible Markdown'], degraded: document.degraded, representedReferences: document.references.length };
+    return { body, warnings: [...document.warnings, 'Confluence Storage Format was converted to YFM-compatible Markdown'], normalizations: [...(document.normalizations ?? [])], degraded: document.degraded, representedReferences: document.references.length };
 }
 export async function renderConfluenceStorage(document, page, context, spaceKey) {
     if (document.rawFormat === 'confluence-storage') {
         const $ = load(`<main data-root>${document.raw}</main>`, { xmlMode: true }, false);
+        const warnings = [...document.warnings];
+        $('ac\\:image').each((_index, element) => {
+            const image = $(element);
+            const attachment = image.children('ri\\:attachment');
+            const filename = attachment.attr('ri:filename');
+            if (!filename)
+                return;
+            const binding = resourceBinding(filename, context);
+            if (!binding)
+                return;
+            if (binding.kind === 'uploaded') {
+                attachment.attr('ri:filename', binding.resource.name);
+                return;
+            }
+            const target = bindingTarget(binding);
+            if (!target)
+                return;
+            warnings.push(`Image uses its source fallback because it was not transferred: ${filename}`);
+            attachment.replaceWith(`<ri:url ri:value="${escapeHtml(target)}"/>`);
+        });
+        $('ac\\:link').each((_index, element) => {
+            const link = $(element);
+            const attachment = link.children('ri\\:attachment');
+            const filename = attachment.attr('ri:filename');
+            if (!filename)
+                return;
+            const binding = resourceBinding(filename, context);
+            if (!binding)
+                return;
+            if (binding.kind === 'uploaded') {
+                attachment.attr('ri:filename', binding.resource.name);
+                return;
+            }
+            const target = bindingTarget(binding);
+            if (!target)
+                return;
+            const label = link.children('ac\\:link-body, ac\\:plain-text-link-body').text().trim() || filename;
+            warnings.push(`Attachment uses its source fallback because it was not transferred: ${filename}`);
+            link.replaceWith(`<a href="${escapeHtml(target)}">${escapeHtml(label)}</a>`);
+        });
+        $('ri\\:attachment').each((_index, element) => {
+            const attachment = $(element);
+            const filename = attachment.attr('ri:filename');
+            if (!filename)
+                return;
+            const binding = resourceBinding(filename, context);
+            if (!binding)
+                return;
+            if (binding.kind === 'uploaded') {
+                attachment.attr('ri:filename', binding.resource.name);
+                return;
+            }
+            const target = bindingTarget(binding);
+            if (!target)
+                return;
+            warnings.push(`Attachment uses its source fallback because it was not transferred: ${filename}`);
+            attachment.replaceWith(`<a href="${escapeHtml(target)}">${escapeHtml(filename)}</a>`);
+        });
         $('ri\\:page').each((_index, element) => {
             const title = $(element).attr('ri:content-title');
             const id = $(element).attr('ri:content-id');
@@ -358,8 +805,9 @@ export async function renderConfluenceStorage(document, page, context, spaceKey)
         });
         return {
             body: $('main[data-root]').html() ?? '<p></p>',
-            warnings: [...document.warnings],
-            degraded: document.degraded,
+            warnings,
+            normalizations: [...(document.normalizations ?? [])],
+            degraded: document.degraded || warnings.length > document.warnings.length,
             representedReferences: document.references.length,
         };
     }
@@ -376,21 +824,61 @@ export async function renderConfluenceStorage(document, page, context, spaceKey)
         });
     }
     const attachments = new Map();
-    for (const [name, resource] of context.resources)
-        attachments.set(name, resource.name);
-    const converted = convertYfmToStorage(document.raw, {
+    const resourceFallbacks = new Map();
+    for (const [name, binding] of context.resources) {
+        if (binding.kind === 'uploaded')
+            attachments.set(name, binding.resource.name);
+        else if (binding.kind === 'source' && binding.url)
+            resourceFallbacks.set(name, binding.url);
+    }
+    const tree = extractTreeDirectives(document.raw);
+    const converted = convertYfmToStorage(tree.content, {
         currentSlug: page.locator,
         spaceKey,
         wikiWebUrl: new URL(page.url).origin,
         pagesBySlug,
         attachmentsByReference: attachments,
+        resourceFallbacksByReference: resourceFallbacks,
     });
+    const normalizedStorage = load(`<main data-root>${converted.storage}</main>`, { xmlMode: true }, false);
+    let removedHeadings = 0;
+    normalizedStorage('h1,h2,h3,h4,h5,h6').each((_index, element) => {
+        const heading = normalizedStorage(element);
+        if (semanticText(heading.text()) || heading.find('img,table,pre,code').length > 0)
+            return;
+        heading.find('[id],a[name]').each((_anchorIndex, anchor) => { heading.before(normalizedStorage(anchor).clone()); });
+        heading.remove();
+        removedHeadings += 1;
+    });
+    let ignorableHeaderWarnings = removedHeadings;
+    const conversionWarnings = converted.warnings.map(stripAnsi).filter((warning) => {
+        if (/Header without title/i.test(warning)) {
+            if (ignorableHeaderWarnings > 0)
+                ignorableHeaderWarnings -= 1;
+            if (removedHeadings > 0 || !containsEmptyYfmHeading(tree.content))
+                return false;
+        }
+        return Boolean(warning.trim());
+    });
+    const normalizations = [...(document.normalizations ?? [])];
+    if (removedHeadings > 0 && !normalizations.some((item) => /empty heading/i.test(item))) {
+        normalizations.push(`Removed ${removedHeadings} empty heading${removedHeadings === 1 ? '' : 's'} emitted by source conversion`);
+    }
+    const treeStorage = tree.directives.map((directive) => {
+        const parameters = [
+            directive.depth ? `<ac:parameter ac:name="depth">${directive.depth}</ac:parameter>` : '',
+            directive.sortBy ? `<ac:parameter ac:name="sort">${directive.sortBy}</ac:parameter>` : '',
+            directive.sort ? `<ac:parameter ac:name="reverse">${directive.sort === 'desc' ? 'true' : 'false'}</ac:parameter>` : '',
+        ].join('');
+        return `<ac:structured-macro ac:name="children">${parameters}</ac:structured-macro>`;
+    }).join('');
     const $ = load(htmlFromDocument(document), null, false);
     const gridStorage = $('.ywtc-grid').toArray().map((element) => $(element).html() ?? '').join('');
     return {
-        body: `${converted.storage}${gridStorage}`,
-        warnings: [...document.warnings, ...converted.warnings],
-        degraded: document.degraded || converted.warnings.length > 0,
+        body: `${normalizedStorage('main[data-root]').html() ?? '<p></p>'}${treeStorage}${gridStorage}`,
+        warnings: [...document.warnings, ...conversionWarnings],
+        normalizations,
+        degraded: document.degraded || conversionWarnings.length > 0,
         representedReferences: document.references.length,
     };
 }